commit 842e699a643d8a60647bd824d28255c56ad61a42
Author: Kaiyi <me@kaiyi.cool>
Date:   Fri May 22 15:54:50 2026 +0800

    Kimi For Coding

diff --git a/.agents/skills/gen-changesets/SKILL.md b/.agents/skills/gen-changesets/SKILL.md
new file mode 100644
index 000000000..6a4d91e66
--- /dev/null
+++ b/.agents/skills/gen-changesets/SKILL.md
@@ -0,0 +1,109 @@
+---
+name: gen-changesets
+description: Use when generating changesets in the kimi-code repository, including package bump selection, internal package and CLI bundle handling, bump levels, major confirmation, and English changelog wording.
+---
+
+# Generate Changesets
+
+`kimi-code` uses changesets to manage versions and changelogs. The current user-facing published package is:
+
+- `@moonshot-ai/kimi-code`: the CLI
+
+All other `@moonshot-ai/*` packages are treated as internal packages, including `@moonshot-ai/kimi-code-sdk`, `agent-core`, `kosong`, `kaos`, `kimi-code-oauth`, `kimi-telemetry`, and `migration-legacy`.
+
+## Core Rules
+
+1. **Inspect the actual changes first.** Use `git status` / `git diff --name-only` to identify which packages were actually changed.
+2. **List packages that were actually changed.** Source code, build config, package metadata, and other changes that affect a package's output or behavior need a changeset entry for that package.
+3. **Do not list unchanged internal packages.** For example, if `packages/node-sdk` was not changed, do not list `@moonshot-ai/kimi-code-sdk` just because another internal package changed. The SDK follows the same rule as other internal packages: list it only when it was actually changed.
+4. **Internal package source changes that enter the CLI bundle must manually list the CLI.** `@moonshot-ai/kimi-code` inline-bundles `@moonshot-ai/*` source, but those internal packages are devDependencies from the CLI's perspective, so changesets will not automatically propagate bumps. If a change enters the CLI output, also list `@moonshot-ai/kimi-code`.
+5. **Docs-only and tests-only changes usually do not need a changeset.** README, internal docs, and `test/` changes that do not enter package output do not trigger a CLI bump.
+6. `@moonshot-ai/vis` / `vis-server` / `vis-web` are ignored by changesets and should not be handled.
+
+## Workflow
+
+1. If the change includes `pnpm-lock.yaml`, `pnpm-workspace.yaml`, root or workspace `package.json`, `.npmrc`, `flake.nix`, or `flake.lock`:
+   - First check `command -v nix >/dev/null 2>&1`.
+   - If `nix` exists, run `nix run .#update-pnpm-deps`.
+   - If `nix` is unavailable, skip this step and do not block the changeset; mention in the final response that the command was not run.
+2. List the packages that were actually changed.
+3. Choose a bump level for each package.
+4. If an internal package change enters the CLI bundle, add `@moonshot-ai/kimi-code`.
+5. Create a short kebab-case file under `.changeset/`.
+6. Split unrelated changes into separate changesets; keep one logical change in one file.
+
+Format:
+
+```markdown
+---
+"<package A>": patch
+"<package B>": minor
+---
+
+<English changelog entry>
+```
+
+## Bump Levels
+
+| Level | When to use |
+|---|---|
+| `patch` | Bug fixes; build/package fixes; internal refactors that do not change behavior; wording tweaks; small dependency upgrades |
+| `minor` | New backwards-compatible features or capabilities |
+| `major` | Breaking changes: incompatible config changes, renamed or removed commands/arguments, behavior semantics changes, and similar |
+
+### Major Rule
+
+Never write `major` on your own.
+
+If you believe a change qualifies as major, stop first, explain why, and ask the user for confirmation. Only write `major` after the user explicitly agrees. If the user does not reply, replies ambiguously, or disagrees, fall back to `minor`; if `minor` is also unclear, fall back to `patch`.
+
+## Wording Rules
+
+- Changelog entries **must be written in English**.
+- User-facing CLI wording should only be used when CLI users can perceive the change.
+- Internal changes that do not affect CLI users can still share a changeset with the CLI, but the wording must describe the real change honestly and must not present it as a user-facing feature.
+- Do not mention file names, class names, function names, PR numbers, or commit hashes.
+- Avoid vague words such as `refactor`, `optimize`, and `improve`. Describe the actual change, or use more specific wording.
+
+## Common Examples
+
+An internal package fixes a bug visible to CLI users:
+
+```markdown
+---
+"@moonshot-ai/agent-core": patch
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix occasional loss of tool call results in long conversations.
+```
+
+An internal package has an internal-only change, but it enters the CLI bundle:
+
+```markdown
+---
+"@moonshot-ai/agent-core": patch
+"@moonshot-ai/kimi-code": patch
+---
+
+Unify tool execution metadata handling.
+```
+
+Only SDK source changed, and the CLI does not use it:
+
+```markdown
+---
+"@moonshot-ai/kimi-code-sdk": patch
+---
+
+Clarify session status typing for internal SDK callers.
+```
+
+## Red Flags
+
+- You are about to write `major` without asking the user.
+- Internal package source enters the CLI bundle, but `@moonshot-ai/kimi-code` is missing.
+- `packages/node-sdk` was not changed, but `@moonshot-ai/kimi-code-sdk` was listed for "internal package sync".
+- The changelog entry is in Chinese.
+- The wording claims more than the diff actually did.
+- The CLI wording mentions internal package names, class names, or PR numbers.
diff --git a/.agents/skills/gen-docs/SKILL.md b/.agents/skills/gen-docs/SKILL.md
new file mode 100644
index 000000000..62830a652
--- /dev/null
+++ b/.agents/skills/gen-docs/SKILL.md
@@ -0,0 +1,87 @@
+---
+name: gen-docs
+description: Update Kimi Code CLI user documentation after meaningful code changes that affect product behavior or user experience.
+---
+
+# Gen Docs
+
+## Overview
+
+This repository maintains bilingual user documentation under `docs/`. `docs/en/` and `docs/zh/` are mirrored pairs for most pages; update both in the same change. **Changelog is the exception** — English is the source, and Chinese is translated from English.
+
+Use this skill to update the corresponding documentation whenever the codebase has changes that affect product behavior or user experience.
+
+For a **full pre-release audit** of all pages (detecting hallucinations and coverage gaps), use the `audit-docs` skill instead.
+
+## Prerequisites
+
+This skill depends on the following being in place. If any are missing, stop and report to the user before continuing:
+
+- `docs/` directory with `docs/zh/`, `docs/en/`, and `docs/.vitepress/config.ts` set up (VitePress site).
+- `docs/AGENTS.md` style guide — defines source-of-truth rules, terminology table, typography, and writing style.
+- `docs/scripts/sync-changelog.mjs` — auto-syncs root `CHANGELOG.md` to `docs/en/release-notes/changelog.md`.
+- `translate-docs` skill in `.agents/skills/` — handles bilingual synchronization.
+
+## Workflow
+
+1. **Inspect changes**
+
+   - `git log main..HEAD --oneline` — commits on the current branch
+   - `git diff main..HEAD --stat` — file-level scope
+   - `ls .changeset/*.md` (excluding `README.md`) — pending changeset entries
+   - Read `CHANGELOG.md` and any subpackage `packages/*/CHANGELOG.md` for already-recorded entries.
+
+2. **Understand user-facing impact**
+
+   For each change, read the actual implementation when needed; **do not infer behavior from commit messages or PR titles alone**. Skip:
+
+   - Internal refactors with no externally visible behavior change
+   - Tests, CI, type-only changes
+   - Tooling / build-system changes that do not change how users invoke the CLI
+
+   If after the scan you conclude there is no user-facing impact, say so and stop.
+
+3. **Sync English changelog**
+
+   Run:
+
+   ```bash
+   node docs/scripts/sync-changelog.mjs
+   ```
+
+   This updates `docs/en/release-notes/changelog.md` from the root `CHANGELOG.md`. Never edit the docs changelog by hand.
+
+4. **Update user docs**
+
+   Following the rules in `docs/AGENTS.md`, edit the affected pages in whichever locale you are working in, then sync the mirror. Match terminology with the term table in `docs/AGENTS.md` and the existing wording in surrounding pages.
+
+   Cover all relevant sections:
+
+   - Guides (getting-started, use cases, interaction, sessions, IDE integration)
+   - Customization (skills, agents, MCP, hooks, plugins, etc.)
+   - Configuration (config files, env vars, providers, data locations)
+   - Reference (CLI subcommands, slash commands, keyboard shortcuts)
+   - Release notes (`docs/zh/release-notes/breaking-changes.md` if a breaking change is involved)
+
+5. **Sync bilingual content**
+
+   Invoke the `translate-docs` skill. It will:
+
+   - Sync updated non-changelog pages between `docs/en/` and `docs/zh/`
+   - Translate the English changelog → Chinese under `docs/zh/release-notes/changelog.md`
+
+## Rules and conventions
+
+- **Locale sync**: Non-changelog pages stay mirrored between `docs/en/` and `docs/zh/`. Changelog flows English → Chinese.
+- **Terminology**: Use the term table in `docs/AGENTS.md` exactly. Do not invent new translations or use synonyms.
+- **Scope discipline**: Only update sections affected by the recent changes. Do not opportunistically rewrite unrelated docs.
+- **Breaking changes**: If any change is breaking, also update `docs/en/release-notes/breaking-changes.md` (under `## Unreleased`) with `**Affected**` + `**Migration**` subsections, and mirror it in `docs/zh/release-notes/breaking-changes.md`.
+- **Do not edit auto-synced files**: `docs/en/release-notes/changelog.md` is regenerated by the sync script; any manual edit will be overwritten.
+
+## Common mistakes
+
+- Describing what code changed instead of what the user can now do (or can no longer do).
+- Adding a new section heading per feature instead of weaving the change into existing prose.
+- Updating only one locale and leaving its mirror stale.
+- Editing only the mirror to fix wording that should be corrected in the locale you changed first.
+- Inventing new terminology that drifts from the `docs/AGENTS.md` term table.
diff --git a/.agents/skills/sync-changelog/SKILL.md b/.agents/skills/sync-changelog/SKILL.md
new file mode 100644
index 000000000..13b734771
--- /dev/null
+++ b/.agents/skills/sync-changelog/SKILL.md
@@ -0,0 +1,247 @@
+---
+name: sync-changelog
+description: Use after a release succeeds, when maintainers need to sync apps/kimi-code/CHANGELOG.md into docs/en/release-notes/changelog.md and docs/zh/release-notes/changelog.md.
+---
+
+# Sync Changelog
+
+## Overview
+
+`kimi-code` uses changesets for versioning. Each package gets its own `CHANGELOG.md`. The user-facing CLI package, `@moonshot-ai/kimi-code`, writes its changelog here:
+
+```text
+apps/kimi-code/CHANGELOG.md
+```
+
+This file is the **only upstream source** for the documentation-site changelog. Internal package changelogs such as `packages/*/CHANGELOG.md` do not go into the documentation site.
+
+After the release flow finishes (Release PR merged → `Version Packages` completed → npm publish succeeded), maintainers manually run this skill to copy the new CLI changelog entries into the docs site and translate the English increment into Chinese.
+
+## When To Use
+
+- A new version has been published to npm.
+- The top of `apps/kimi-code/CHANGELOG.md` contains version blocks that are not yet in `docs/en/release-notes/changelog.md`.
+- The `gen-docs` flow does not run this automatically; maintainers must explicitly do it after release.
+
+Do **not** run this before the Release PR is merged. At that point, changesets has not yet written the new version into `apps/kimi-code/CHANGELOG.md`.
+
+## Source And Targets
+
+| File | Role | Edited by |
+|---|---|---|
+| `apps/kimi-code/CHANGELOG.md` | **Only upstream source**, generated by changesets | Never edit manually |
+| `docs/en/release-notes/changelog.md` | English docs changelog; source of truth for docs | This skill |
+| `docs/zh/release-notes/changelog.md` | Chinese docs changelog, translated from English | This skill, following `translate-docs` |
+
+Core rule: the English docs changelog is the source of truth, and Chinese is translated from English. This matches `translate-docs`.
+
+## Preconditions
+
+Before editing, confirm:
+
+- The released version exists on npm (`npm view @moonshot-ai/kimi-code versions --json`) or has a matching GitHub Release tag.
+- The top of `apps/kimi-code/CHANGELOG.md` is that new version.
+- The current branch is clean, or you are on a dedicated docs-sync branch.
+
+If any condition is not true, stop and confirm with the user.
+
+## Workflow
+
+### 1. Find The Version Range
+
+```bash
+# Upstream versions
+rg '^## ' apps/kimi-code/CHANGELOG.md | head -20
+
+# Latest version already synced into the English docs page
+rg '^## ' docs/en/release-notes/changelog.md | head -5
+```
+
+- First sync: copy all upstream version blocks into the English page.
+- Incremental sync: copy every upstream version block above the latest version already present in the English page.
+
+Use upstream order: newest version first.
+
+### 2. Strip Decorations And Extract Entry Text
+
+Upstream entries look like this:
+
+```markdown
+- [#317](https://github.com/...) [`2f51db4`](https://github.com/...) - Clean up lint warnings ...
+```
+
+Keep:
+
+- Version headings such as `## 0.2.0`.
+- Only the body text of each entry, after the PR/hash decoration.
+
+Remove:
+
+- The upstream H1 `# @moonshot-ai/kimi-code` because the docs page already has `# Changelog`.
+- Changesets subheadings such as `### Patch Changes`, `### Minor Changes`, and `### Major Changes`.
+- PR links such as `[#317](...)`.
+- Commit hash links such as ``[`2f51db4`](...)``.
+
+After stripping, each entry should be only:
+
+```markdown
+- <body text>
+```
+
+Upstream language rule: `gen-changesets` requires changelog entries to be English. If the upstream CLI changelog contains a non-English entry, stop and report it to the user. Do not silently rewrite it while syncing docs.
+
+### 3. Classify Entries
+
+The docs changelog uses four section types:
+
+| English section | Chinese section | Meaning |
+|---|---|---|
+| `### Features` | `### 新功能` | New user-facing functionality |
+| `### Bug Fixes` | `### 修复` | Fixes for behavior that was broken |
+| `### Refactors` | `### 重构` | Internal changes with no user-visible behavior change, including build, CI, tests, dependency cleanup, and internal renames |
+| `### Other` | `### 其他` | Anything that does not fit above, such as user-visible adjustments that are not fixes or features, CDN/endpoint swaps, and docs-related artifacts |
+
+Classification process:
+
+1. Classify from the stripped entry text first.
+2. If unclear, inspect the related commit or PR:
+   - Use the stripped commit hash with `git show <hash>`.
+   - Or use the PR number with `gh pr view <NNN>`.
+3. If it is still unclear, put it in `Other`. Do not guess or force entries into `Features`.
+
+Keyword hints:
+
+- **Features**: `Add`, `Introduce`, `Support`, `Allow`, `Enable`, `Implement`, `New ... command/flag/option`
+- **Bug Fixes**: `Fix`, `Resolve`, `Correct`, `Address`, `Prevent ... from`, `Stop ... from`, `... no longer ...`
+- **Refactors**: `Refactor`, `Rename`, `Clean up`, `Simplify`, `Remove unused`, `Migrate to`, `Unify`, `Restructure`, `Internal`, dependency bumps, pure CI/build/test changes
+- **Other**: docs artifacts, CDN/endpoint switches, or small user-visible adjustments that are not fixes or new features
+
+Within each version, section order is:
+
+```text
+Features → Bug Fixes → Refactors → Other
+```
+
+Omit empty sections. Preserve upstream entry order within each section.
+
+### 4. Write The English Page
+
+Never change the English page header:
+
+```markdown
+# Changelog
+
+This page documents the changes in each Kimi Code CLI release.
+```
+
+Insert new version blocks immediately after the header paragraph and before the previous latest version.
+
+Example:
+
+```markdown
+## 0.2.0
+
+### Bug Fixes
+
+- Fix the TUI not restoring the current todo list after resuming a session.
+
+### Refactors
+
+- Clean up lint warnings across the CLI, SDK examples, and bundled runtime code without changing product behavior.
+- Update the native release workflow to use current GitHub artifact actions.
+```
+
+### 5. Translate The Increment Into Chinese
+
+After updating the English page, translate only the newly added English content into `docs/zh/release-notes/changelog.md`.
+
+Follow `translate-docs`, direction `en → zh`. Changelog direction is English-to-Chinese even though many other docs flows use Chinese-to-English.
+
+Chinese page requirements:
+
+- Header:
+
+  ```markdown
+  # 变更记录
+
+  本页记录 Kimi Code CLI 每个版本的变更内容。
+  ```
+
+- Preserve version headings exactly, such as `## 0.2.0`.
+- Translate section headings exactly:
+  - `### Features` → `### 新功能`
+  - `### Bug Fixes` → `### 修复`
+  - `### Refactors` → `### 重构`
+  - `### Other` → `### 其他`
+- The Chinese page must mirror the English page 1:1 for versions, sections, section order, and entry counts.
+- Keep the classification from the English page. Do not reclassify while translating.
+- Translate only entry body text. Do not add entries that are not present in English.
+- Follow `docs/AGENTS.md` for Chinese typography: full-width punctuation, spaces between Chinese and English, and the glossary.
+
+### 6. Verify
+
+Review:
+
+```bash
+git diff docs/en/release-notes/changelog.md docs/zh/release-notes/changelog.md
+```
+
+Check:
+
+- Versions and version counts match between English and Chinese.
+- Each version has the same section set and order on both pages.
+- Each section has the same number of entries on both pages.
+- PR links and commit hashes were stripped.
+- There are no empty sections.
+- Markdown indentation and blank lines are intact.
+
+Then run the docs build:
+
+```bash
+pnpm --filter docs run build
+```
+
+### 7. Commit
+
+Use a neutral docs-sync commit message:
+
+```text
+docs(changelog): sync <version range> from apps/kimi-code/CHANGELOG.md
+```
+
+Do **not** create a changeset for changelog docs sync. Docs sync does not enter the bundle.
+
+## Rules
+
+- The English docs changelog is the source of truth.
+- Never edit upstream `apps/kimi-code/CHANGELOG.md`.
+- Do not backfill unreleased `.changeset/*.md` drafts into the docs site.
+- If upstream wording is wrong, leave upstream alone and fix it in a future changeset.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Adding entries directly to the English docs page without reading upstream | Use `apps/kimi-code/CHANGELOG.md` as the source |
+| Copying PR links or commit hashes into docs | Strip them; keep only body text |
+| Rewording upstream English entries | Upstream is frozen; copy the body text unless the user explicitly asks otherwise |
+| Leaving English text untranslated in the Chinese page | The Chinese page must be fully Chinese except preserved technical terms |
+| Editing upstream changelog text | Do not edit upstream |
+| Losing two-space indentation in multi-line list items | Restore indentation so Markdown lists stay valid |
+| Copying `### Patch Changes` into docs | Remove changesets headings and classify under Features / Bug Fixes / Refactors / Other |
+| Guessing unclear entries as Features | Inspect commit/PR; if still unclear, use Other |
+| Reclassifying entries while translating | Chinese classification must mirror English |
+| Leaving empty sections | Delete sections with no entries |
+| Putting everything under Other for convenience | Classify what can be classified first |
+| Translating tool names, command names, or config keys | Keep them as written |
+| Creating a changeset for docs sync | Do not create one |
+| Using curly quotes or half-width Chinese punctuation | Follow `docs/AGENTS.md` |
+
+## Stop Signals
+
+- The top version in `apps/kimi-code/CHANGELOG.md` is not published on npm or GitHub Releases.
+- You are about to edit `apps/kimi-code/CHANGELOG.md`.
+- You are about to add docs sync to a changeset.
+- English and Chinese versions, entry counts, or section sets do not match.
+- A section is empty.
+- A Chinese term is uncertain and `docs/AGENTS.md` does not answer it.
diff --git a/.agents/skills/translate-docs/SKILL.md b/.agents/skills/translate-docs/SKILL.md
new file mode 100644
index 000000000..d34370225
--- /dev/null
+++ b/.agents/skills/translate-docs/SKILL.md
@@ -0,0 +1,65 @@
+---
+name: translate-docs
+description: Translate and sync bilingual user documentation between docs/zh/ and docs/en/ following the source-of-truth rules in docs/AGENTS.md.
+---
+
+# Translate Docs
+
+## Overview
+
+This repository keeps bilingual user documentation under `docs/zh/` and `docs/en/`. This skill synchronizes the two locales, page by page, after either side has been updated.
+
+This skill is invoked by both `gen-docs` (incremental updates) and `audit-docs` (full pre-release audit) to keep locale mirrors in sync.
+
+## Prerequisites
+
+If any of the following are missing, stop and report to the user before continuing:
+
+- `docs/zh/` and `docs/en/` mirrored directory structure.
+- `docs/AGENTS.md` — terminology table, typography rules, and source-of-truth rules.
+
+## Locale sync rules
+
+- **Changelog** (`release-notes/changelog.md`): English is the source. Translate to Chinese.
+- **Breaking changes** (`release-notes/breaking-changes.md`): English is the source. Translate to Chinese.
+- **All other pages**: `docs/en/` and `docs/zh/` are mirrored pairs. After either side changes, update the other locale in the same change.
+
+When non-changelog pages change in either locale, sync the mirror before release. When the English changelog changes, sync the Chinese changelog.
+
+## Workflow
+
+1. **Detect what needs syncing**
+
+   - `git diff main..HEAD --stat docs/` — see which files changed
+   - For each changed file under `docs/en/` or `docs/zh/`, locate its mirror in the other locale (same relative path).
+
+2. **Translate page by page, section by section**
+
+   - Keep heading hierarchy, list structure, code blocks, callout blocks, and link targets identical between the two versions.
+   - When in doubt about a technical term, **read the actual code** to confirm behavior rather than guessing.
+
+3. **Apply terminology and typography rules from `docs/AGENTS.md`**
+
+   - Use the term table exactly. Do not invent translations or use synonyms.
+   - English H2+ uses sentence case (proper nouns excepted, per the term table).
+   - Chinese typography: full-width punctuation (`，。；：？！（）`), space between Chinese and ASCII (letters / numbers / inline code / links).
+   - Callout titles (`::: tip` / `::: warning` / `::: info` / `::: danger`) use the short Chinese labels from `docs/AGENTS.md`.
+
+4. **Verify**
+
+   - `git diff docs/` — scan for terminology drift or punctuation regressions.
+   - Run the docs build if available (`pnpm --filter docs run build` or equivalent) to catch broken links and Markdown errors.
+
+## Rules and conventions
+
+- **Do not one-sided fixes**: if the changed locale has an unclear or incorrect statement, fix it there first; do not patch only the mirror.
+- **Match style, not just words**: Chinese docs use a narrative tone (see `docs/AGENTS.md` writing-style examples); preserve that tone in Chinese; preserve sentence-case headings and concise English style in English.
+- **Code blocks and identifiers stay as-is**: do not translate code, command names, flag names, or file paths.
+
+## Common mistakes
+
+- Rewriting only the mirror because a phrase feels awkward in the target language — fix the changed locale first, then sync.
+- Letting English headings slip into Title Case (only sentence case is allowed for H2+).
+- Forgetting to add spaces between Chinese characters and inline code or English words.
+- Translating proper nouns listed in the term table (`Wire`, `MCP`, `ACP`, `JSON`, `OAuth`, `macOS`, `uv`, etc.).
+- Updating only one direction and leaving the other locale stale — always finish all pages flagged by the diff.
diff --git a/.changeset/README.md b/.changeset/README.md
new file mode 100644
index 000000000..aed0865b2
--- /dev/null
+++ b/.changeset/README.md
@@ -0,0 +1,152 @@
+# Changesets
+
+This repository uses [changesets](https://github.com/changesets/changesets) to manage npm package versions and releases.
+
+## Package Publishing Strategy
+
+This repository uses an **independent, manually-selected publishing** strategy. When generating a changeset, only select the publishable packages that this change actually affects. The repository's `.changeset/config.json` already filters out internal workspace packages via `ignore`, so only the publishable packages listed below should appear in the `pnpm changeset` prompt.
+
+Current publishable packages:
+
+| Package | Directory | Description |
+| --- | --- | --- |
+| `@moonshot-ai/kimi-code` | `apps/kimi-code` | CLI / TUI application — provides the `kimi` command after install |
+| `@moonshot-ai/kimi-code-sdk` | `packages/node-sdk` | Public TypeScript SDK |
+
+All other workspace packages are private internal packages, are not published to npm, and are excluded via `ignore` in `.changeset/config.json`:
+
+- `@moonshot-ai/agent-core`
+- `@moonshot-ai/kimi-code-oauth`
+- `@moonshot-ai/kimi-telemetry`
+- `@moonshot-ai/kaos`
+- `@moonshot-ai/kosong`
+- `@moonshot-ai/vis`
+- `@moonshot-ai/vis-server`
+- `@moonshot-ai/vis-web`
+
+Version impact from internal dependencies must be judged manually. The published artifacts for CLI and SDK bundle internal workspace packages into the artifact itself; runtime `dependencies` of published packages must not include any `@moonshot-ai/*` internal workspace packages.
+
+The repository's `.changeset/config.json` sets `updateInternalDependencies: "patch"`. Because internal packages are not published, you still need to manually select all affected publishable packages in the changeset — do not rely solely on automatic dependency bumps to express user-visible changes.
+
+Example scenarios:
+
+| Change | Changeset selection |
+| --- | --- |
+| Only modifies TUI behavior in `@moonshot-ai/kimi-code` | Add `patch` / `minor` / `major` to `@moonshot-ai/kimi-code` |
+| Only modifies internal packages, no user-visible change in SDK / CLI | Usually no changeset needed |
+| Internal package fix changes the CLI user experience | Add a changeset to `@moonshot-ai/kimi-code` describing the user-visible fix |
+| Internal package adds a new capability exposed by the SDK | Add a changeset to `@moonshot-ai/kimi-code-sdk` |
+| SDK behavior change affects CLI user experience | Add changesets to both `@moonshot-ai/kimi-code-sdk` and `@moonshot-ai/kimi-code` |
+| Provider abstraction change affects SDK / CLI | Add changesets to the affected `@moonshot-ai/kimi-code-sdk` and/or `@moonshot-ai/kimi-code` |
+| Test-only, internal refactor, docs, or private debug tooling changes | Usually no changeset needed |
+
+## Prerequisite: NPM Trusted Publishing (OIDC)
+
+This repository uses npm's **Trusted Publishing** (OIDC-based) for publishing — no `NPM_TOKEN` is required.
+
+### Configuration steps
+
+1. Open each publishable package's page on the npm website, e.g. `https://www.npmjs.com/package/@moonshot-ai/kimi-code`.
+2. Go to **Settings** -> **Publishing access**.
+3. Find **Automate publishing with GitHub Actions** or **Add trusted publisher**.
+4. Click **Add a new trusted publisher**.
+
+Fill in the following:
+
+| Field | Value |
+| --- | --- |
+| GitHub Organization | `MoonshotAI` |
+| GitHub Repository | `kimi-code` |
+| GitHub Workflow | `release.yml` |
+| Environment | leave empty |
+
+Each publishable package needs its Trusted Publisher configured once. The current GitHub Actions workflow lives at `.github/workflows/release.yml` and already has `id-token: write` configured.
+
+## Development Workflow
+
+### 1. Implement the feature or fix
+
+Complete code, tests, and documentation changes as usual. A changeset is required when the change affects user-visible behavior, public API, dependency ranges, or release artifacts of a publishable package.
+
+### 2. Generate a changeset
+
+From the repository root:
+
+```sh
+pnpm changeset
+```
+
+Follow the prompts to choose:
+
+- Which publishable packages this change affects;
+- The version bump level:
+  - `patch`: bug fixes, small changes, follow-up dependency updates;
+  - `minor`: backward-compatible new features;
+  - `major`: breaking changes;
+- A user-facing description of the change.
+
+The command creates a `.changeset/*.md` file that must be committed alongside the code.
+
+### 3. Commit the changeset
+
+```sh
+git add .changeset/
+git commit -m "chore: add changeset for package release"
+git push
+```
+
+Commit messages must follow Conventional Commit style. Do not include any author/agent identity in the commit message.
+
+### 4. CI generates the release PR
+
+Once the changeset file is merged into `main`, `.github/workflows/release.yml` uses `changesets/action@v1` to create or update a release PR.
+
+The release PR runs:
+
+- `pnpm changeset version`: bumps publishable package versions and updates changelogs;
+- Deletes the consumed `.changeset/*.md` files;
+- Uses the title `[CI]: Release packages`.
+
+### 5. Merge the release PR
+
+Once the release PR is merged into `main`, the same workflow runs:
+
+- `pnpm install --frozen-lockfile`
+- `pnpm build`
+- `pnpm changeset publish`
+
+The packages are then published via npm Trusted Publishing, and a GitHub Release is created.
+
+## Manual Publishing (Not Recommended)
+
+Only publish manually when CI is unavailable. Before publishing manually, make sure you are logged into npm locally and using the Node.js and pnpm versions required by the repository.
+
+```sh
+pnpm run version
+pnpm run publish
+```
+
+The underlying changesets commands are:
+
+```sh
+pnpm changeset version
+pnpm changeset publish
+```
+
+The root-level `pnpm run publish` first runs typecheck, lint, sherif, test, build, and package lint, then runs `changeset publish`.
+
+## Notes
+
+- Every PR that affects publishable-package behavior or public API should include a corresponding changeset.
+- Changeset files must be committed to the repository — release PRs are only triggered after they're merged.
+- Release PRs require human review and merge; they will not publish automatically.
+- Do not add release changesets for private internal packages; only select `@moonshot-ai/kimi-code` and `@moonshot-ai/kimi-code-sdk`.
+- If a change in an underlying internal package alters user-visible behavior or public API of a publishable package, add a changeset to the affected publishable package. For example, when a bug fixed in `@moonshot-ai/agent-core` resolves an issue CLI users encounter, add a changeset to `@moonshot-ai/kimi-code` describing the user-visible fix.
+- `@moonshot-ai/kimi-code` is the official CLI package name; after a global install it provides the `kimi` command.
+- Make sure each publishable package on npm has a Trusted Publisher configured.
+
+## References
+
+- [Changesets documentation](https://github.com/changesets/changesets)
+- [Changesets GitHub Action](https://github.com/changesets/action)
+- [npm Trusted Publishing documentation](https://docs.npmjs.com/trusted-publishers)
diff --git a/.changeset/config.json b/.changeset/config.json
new file mode 100644
index 000000000..af6143de9
--- /dev/null
+++ b/.changeset/config.json
@@ -0,0 +1,18 @@
+{
+  "changelog": ["@changesets/changelog-github", { "repo": "MoonshotAI/kimi-code", "disableThanks": true }],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": [
+    "@moonshot-ai/vis",
+    "@moonshot-ai/vis-server",
+    "@moonshot-ai/vis-web"
+  ],
+  "snapshot": {
+    "useCalculatedVersion": true,
+    "prereleaseTemplate": "{tag}-{commit}"
+  }
+}
diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 000000000..4039ff111
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
diff --git a/.github/ISSUE_TEMPLATE/1-bug-report.yml b/.github/ISSUE_TEMPLATE/1-bug-report.yml
new file mode 100644
index 000000000..d38aab205
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/1-bug-report.yml
@@ -0,0 +1,65 @@
+name: Bug Report
+description: Report an issue that should be fixed
+labels:
+  - bug
+  - needs triage
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for submitting a bug report! It helps make Kimi Code better for everyone.
+
+        Make sure you are running the latest version of Kimi Code CLI. The bug you are experiencing may already have been fixed.
+
+        Please try to include as much information as possible.
+
+  - type: input
+    id: version
+    attributes:
+      label: What version of Kimi Code is running?
+      description: Copy the output of `kimi --version` or `/version`
+    validations:
+      required: true
+  - type: input
+    id: plan
+    attributes:
+      label: Which open platform/subscription were you using?
+      description: The one you selected when running `/login`
+    validations:
+      required: true
+  - type: input
+    id: model
+    attributes:
+      label: Which model were you using?
+      description: The one you can see on the bottom status line, like `kimi-k2.6`, `kimi-for-coding`, etc.
+  - type: input
+    id: platform
+    attributes:
+      label: What platform is your computer?
+      description: |
+        For MacOS and Linux: copy the output of `uname -mprs`
+        For Windows: copy the output of `"$([Environment]::OSVersion | ForEach-Object VersionString) $(if ([Environment]::Is64BitOperatingSystem) { "x64" } else { "x86" })"` in the PowerShell console
+  - type: textarea
+    id: actual
+    attributes:
+      label: What issue are you seeing?
+      description: Please include the full error messages and prompts with any private information redacted. If possible, please provide text instead of a screenshot.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: What steps can reproduce the bug?
+      description: Explain the bug and provide a code snippet that can reproduce it. Please include session id and context usage if applicable.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What is the expected behavior?
+      description: If possible, please provide text instead of a screenshot.
+  - type: textarea
+    id: notes
+    attributes:
+      label: Additional information
+      description: Is there anything else you think we should know?
diff --git a/.github/ISSUE_TEMPLATE/2-feature-request.yml b/.github/ISSUE_TEMPLATE/2-feature-request.yml
new file mode 100644
index 000000000..cbc055334
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/2-feature-request.yml
@@ -0,0 +1,25 @@
+name: Feature Request
+description: Propose a new feature for Kimi Code
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Is Kimi Code missing a feature that you'd like to see? Feel free to propose it here.
+
+        Before you submit a feature:
+        1. Search existing issues for similar features. If you find one, 👍 it rather than opening a new one.
+        2. The Kimi Code team will try to balance the varying needs of the community when prioritizing or rejecting new features. Please understand that not all features will be accepted.
+
+  - type: textarea
+    id: feature
+    attributes:
+      label: What feature would you like to see?
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Additional information
+      description: Is there anything else you think we should know?
diff --git a/.github/actions/macos-keychain-cleanup/action.yml b/.github/actions/macos-keychain-cleanup/action.yml
new file mode 100644
index 000000000..1cc377a1c
--- /dev/null
+++ b/.github/actions/macos-keychain-cleanup/action.yml
@@ -0,0 +1,12 @@
+name: macOS keychain cleanup
+description: Delete the temporary keychain created by macos-keychain-setup.
+
+runs:
+  using: composite
+  steps:
+    - name: Cleanup keychain
+      shell: bash
+      run: |
+        if [[ -n "${APPLE_KEYCHAIN_PATH:-}" && -f "${APPLE_KEYCHAIN_PATH}" ]]; then
+          security delete-keychain "$APPLE_KEYCHAIN_PATH" || true
+        fi
diff --git a/.github/actions/macos-keychain-setup/action.yml b/.github/actions/macos-keychain-setup/action.yml
new file mode 100644
index 000000000..199f8ed7f
--- /dev/null
+++ b/.github/actions/macos-keychain-setup/action.yml
@@ -0,0 +1,82 @@
+name: macOS keychain setup
+description: |
+  Create a temporary keychain, import a Developer ID Application certificate,
+  discover the signing identity, and export APPLE_SIGNING_IDENTITY +
+  APPLE_KEYCHAIN_PATH to GITHUB_ENV for subsequent steps. Must be paired
+  with macos-keychain-cleanup in an if: always() step at job end.
+
+inputs:
+  certificate-p12:
+    description: Base64-encoded P12 certificate
+    required: true
+  certificate-password:
+    description: P12 password
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Import signing certificate
+      shell: bash
+      env:
+        APPLE_CERTIFICATE_P12: ${{ inputs.certificate-p12 }}
+        APPLE_CERTIFICATE_PASSWORD: ${{ inputs.certificate-password }}
+        KEYCHAIN_PASSWORD: actions
+      run: |
+        set -euo pipefail
+
+        # 0. Validate inputs early — base64 decoding "" gives 0-byte .p12 → security import reports
+        # "SecKeychainItemImport: One or more parameters passed to a function were not valid"
+        # which is cryptic. Fail loudly here instead.
+        if [ -z "$APPLE_CERTIFICATE_P12" ]; then
+          echo "::error::APPLE_CERTIFICATE_P12 secret is empty. Configure it in repo settings, or pass sign-macos=false."
+          exit 1
+        fi
+        if [ -z "$APPLE_CERTIFICATE_PASSWORD" ]; then
+          echo "::error::APPLE_CERTIFICATE_PASSWORD secret is empty."
+          exit 1
+        fi
+
+        # 1. Decode certificate
+        cert_path="${RUNNER_TEMP}/certificate.p12"
+        printf '%s' "$APPLE_CERTIFICATE_P12" | base64 -d > "$cert_path"
+        if [ ! -s "$cert_path" ]; then
+          echo "::error::Decoded certificate is empty. APPLE_CERTIFICATE_P12 secret value may not be valid base64."
+          exit 1
+        fi
+
+        # 2. Create temporary keychain (don't pollute runner default keychain)
+        keychain_path="${RUNNER_TEMP}/signing.keychain-db"
+        security create-keychain -p "$KEYCHAIN_PASSWORD" "$keychain_path"
+        security set-keychain-settings -lut 21600 "$keychain_path"
+        security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$keychain_path"
+
+        # 3. Add to user keychain search list and set default
+        security list-keychains -d user -s "$keychain_path" $(security list-keychains -d user | tr -d '"')
+        security default-keychain -s "$keychain_path"
+
+        # 4. Import cert, authorize codesign + security tools
+        security import "$cert_path" -k "$keychain_path" \
+          -P "$APPLE_CERTIFICATE_PASSWORD" \
+          -T /usr/bin/codesign -T /usr/bin/security
+
+        # 5. Non-interactive private key access
+        security set-key-partition-list -S apple-tool:,apple: \
+          -s -k "$KEYCHAIN_PASSWORD" "$keychain_path" > /dev/null
+
+        # 6. Discover identity (don't hardcode team ID)
+        IDENTITY=$(security find-identity -v -p codesigning "$keychain_path" \
+          | grep "Developer ID Application" | head -1 \
+          | sed -n 's/.*"\(Developer ID Application[^"]*\)".*/\1/p')
+
+        if [[ -z "$IDENTITY" ]]; then
+          echo "::error::No Developer ID Application identity found in keychain"
+          security find-identity -v -p codesigning "$keychain_path"
+          exit 1
+        fi
+
+        echo "Found signing identity: $IDENTITY"
+        echo "APPLE_SIGNING_IDENTITY=$IDENTITY" >> "$GITHUB_ENV"
+        echo "APPLE_KEYCHAIN_PATH=$keychain_path" >> "$GITHUB_ENV"
+
+        rm -f "$cert_path"
diff --git a/.github/actions/macos-notarize/action.yml b/.github/actions/macos-notarize/action.yml
new file mode 100644
index 000000000..9a919d810
--- /dev/null
+++ b/.github/actions/macos-notarize/action.yml
@@ -0,0 +1,95 @@
+name: macOS notarize
+description: |
+  Submit a signed binary to Apple notary service via notarytool, wait for
+  result, and run Gatekeeper online check (spctl). Fails the job with the
+  notarytool log on rejection.
+
+inputs:
+  binary-path:
+    description: Absolute path to the signed binary
+    required: true
+  notarization-key-p8:
+    description: Base64-encoded App Store Connect API Key (.p8)
+    required: true
+  notarization-key-id:
+    description: API Key ID
+    required: true
+  notarization-issuer-id:
+    description: Issuer ID
+    required: true
+  timeout:
+    description: notarytool wait timeout (e.g. 15m)
+    required: false
+    default: '15m'
+
+runs:
+  using: composite
+  steps:
+    - name: Submit to notary service
+      shell: bash
+      env:
+        BINARY_PATH: ${{ inputs.binary-path }}
+        APPLE_NOTARIZATION_KEY_P8: ${{ inputs.notarization-key-p8 }}
+        APPLE_NOTARIZATION_KEY_ID: ${{ inputs.notarization-key-id }}
+        APPLE_NOTARIZATION_ISSUER_ID: ${{ inputs.notarization-issuer-id }}
+        NOTARY_TIMEOUT: ${{ inputs.timeout }}
+      run: |
+        set -euo pipefail
+
+        if [[ ! -f "$BINARY_PATH" ]]; then
+          echo "::error::Binary not found at $BINARY_PATH"
+          exit 1
+        fi
+
+        # 1. Decode API key
+        key_path="${RUNNER_TEMP}/AuthKey.p8"
+        printf '%s' "$APPLE_NOTARIZATION_KEY_P8" | base64 -d > "$key_path"
+
+        # 2. Pack with ditto (--norsrc avoids ._AppleDouble files)
+        binary_name=$(basename "$BINARY_PATH")
+        zip_path="${RUNNER_TEMP}/${binary_name}.notarize.zip"
+        ditto -c -k --norsrc --keepParent "$BINARY_PATH" "$zip_path"
+
+        echo "==> Submitting $binary_name for notarization..."
+
+        # 3. Submit and capture log
+        log_path="${RUNNER_TEMP}/notarize-${binary_name}.log"
+        set +e
+        xcrun notarytool submit "$zip_path" \
+          --key "$key_path" \
+          --key-id "$APPLE_NOTARIZATION_KEY_ID" \
+          --issuer "$APPLE_NOTARIZATION_ISSUER_ID" \
+          --wait --timeout "$NOTARY_TIMEOUT" 2>&1 | tee "$log_path"
+        notarize_rc=${PIPESTATUS[0]}
+        set -e
+
+        # 4. Inspect status
+        if ! grep -q "status: Accepted" "$log_path"; then
+          echo "::error::Notarization failed (exit=$notarize_rc)"
+          submission_id=$(grep -m1 "id:" "$log_path" | awk '{print $2}' || true)
+          if [[ -n "$submission_id" ]]; then
+            echo "Fetching detailed log for submission $submission_id..."
+            xcrun notarytool log "$submission_id" \
+              --key "$key_path" \
+              --key-id "$APPLE_NOTARIZATION_KEY_ID" \
+              --issuer "$APPLE_NOTARIZATION_ISSUER_ID" || true
+          fi
+          rm -f "$key_path" "$zip_path"
+          exit 1
+        fi
+
+        echo "==> Notarization accepted"
+
+        # 5. Cleanup
+        rm -f "$key_path" "$zip_path"
+
+    - name: Verify with Gatekeeper online check
+      shell: bash
+      env:
+        BINARY_PATH: ${{ inputs.binary-path }}
+      run: |
+        set -euo pipefail
+        echo "==> codesign -dv $BINARY_PATH"
+        codesign -dv --verbose=2 "$BINARY_PATH"
+        echo "==> spctl -a -vvv -t install $BINARY_PATH"
+        spctl -a -vvv -t install "$BINARY_PATH"
diff --git a/.github/pr-title-checker-config.json b/.github/pr-title-checker-config.json
new file mode 100644
index 000000000..c1000ebb4
--- /dev/null
+++ b/.github/pr-title-checker-config.json
@@ -0,0 +1,12 @@
+{
+    "LABEL": {
+        "name": "Invalid PR Title",
+        "color": "B60205"
+    },
+    "CHECKS": {
+        "regexp": "^(feat|fix|test|refactor|chore|style|docs|perf|build|ci|revert)(\\(.*\\))?:.*"
+    },
+    "MESSAGES": {
+        "failure": "The PR title is invalid. Please refer to https://www.conventionalcommits.org/en/v1.0.0/ for the convention."
+    }
+}
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 000000000..020e01f04
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,25 @@
+<!--
+Thank you for your contribution to Kimi Code!
+Please make sure you already discussed the feature or bugfix you are proposing in an issue with the maintainers.
+Please understand that if you have not gotten confirmation from the maintainers, your pull request may be closed or ignored without further review due to limited bandwidth.
+
+See https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md for more.
+-->
+
+## Related Issue
+
+<!-- Please link to the issue here. -->
+
+Resolve #(issue_number)
+
+## Description
+
+<!-- Please describe your changes in detail. -->
+
+## Checklist
+
+- [ ] I have read the [CONTRIBUTING](https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md) document.
+- [ ] I have linked the related issue, if any.
+- [ ] I have added tests that prove my fix is effective or that my feature works.
+- [ ] Ran `gen-changesets` skill, or this PR needs no changeset.
+- [ ] Ran `gen-docs` skill, or this PR needs no doc update.
diff --git a/.github/workflows/_native-build.yml b/.github/workflows/_native-build.yml
new file mode 100644
index 000000000..439d23544
--- /dev/null
+++ b/.github/workflows/_native-build.yml
@@ -0,0 +1,115 @@
+name: _native-build
+
+on:
+  workflow_call:
+    inputs:
+      upload-artifact-prefix:
+        description: 'Prefix for uploaded artifact name'
+        required: false
+        type: string
+        default: 'kimi-code-native'
+      retention-days:
+        description: 'Artifact retention in days'
+        required: false
+        type: number
+        default: 3
+      sign-macos:
+        description: 'Whether to sign + notarize macOS builds (requires Apple secrets)'
+        required: false
+        type: boolean
+        default: false
+    secrets:
+      APPLE_CERTIFICATE_P12:
+        required: false
+      APPLE_CERTIFICATE_PASSWORD:
+        required: false
+      APPLE_NOTARIZATION_KEY_P8:
+        required: false
+      APPLE_NOTARIZATION_KEY_ID:
+        required: false
+      APPLE_NOTARIZATION_ISSUER_ID:
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  native-bundle:
+    name: Native bundle (${{ matrix.target }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-24.04
+            target: linux-x64
+          - os: ubuntu-24.04-arm
+            target: linux-arm64
+          - os: macos-15-intel
+            target: darwin-x64
+          - os: macos-15
+            target: darwin-arm64
+          - os: windows-2025-vs2026
+            target: win32-x64
+          - os: windows-11-arm
+            target: win32-arm64
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Setup macOS keychain (release only)
+        if: runner.os == 'macOS' && inputs.sign-macos
+        uses: ./.github/actions/macos-keychain-setup
+        with:
+          certificate-p12: ${{ secrets.APPLE_CERTIFICATE_P12 }}
+          certificate-password: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+
+      - name: Build native executable (release profile, macOS signed)
+        if: runner.os == 'macOS' && inputs.sign-macos
+        run: pnpm --filter @moonshot-ai/kimi-code run build:native:release
+
+      - name: Build native executable (local profile)
+        if: '!(runner.os == ''macOS'' && inputs.sign-macos)'
+        run: pnpm --filter @moonshot-ai/kimi-code run build:native:sea
+
+      - name: Notarize macOS binary
+        if: runner.os == 'macOS' && inputs.sign-macos
+        uses: ./.github/actions/macos-notarize
+        with:
+          binary-path: ${{ github.workspace }}/apps/kimi-code/dist-native/bin/${{ matrix.target }}/kimi
+          notarization-key-p8: ${{ secrets.APPLE_NOTARIZATION_KEY_P8 }}
+          notarization-key-id: ${{ secrets.APPLE_NOTARIZATION_KEY_ID }}
+          notarization-issuer-id: ${{ secrets.APPLE_NOTARIZATION_ISSUER_ID }}
+
+      - name: Cleanup macOS keychain
+        if: always() && runner.os == 'macOS' && inputs.sign-macos
+        uses: ./.github/actions/macos-keychain-cleanup
+
+      - name: Smoke test native executable
+        run: pnpm --filter @moonshot-ai/kimi-code run test:native:smoke
+
+      - name: Package native artifact
+        run: pnpm --filter @moonshot-ai/kimi-code run package:native
+
+      - name: Upload native artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: ${{ inputs.upload-artifact-prefix }}-${{ matrix.target }}
+          retention-days: ${{ inputs.retention-days }}
+          path: |
+            apps/kimi-code/dist-native/artifacts/kimi-code-${{ matrix.target }}.zip
+            apps/kimi-code/dist-native/artifacts/kimi-code-${{ matrix.target }}.zip.sha256
+          if-no-files-found: ignore
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 000000000..c7ceac2ad
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - name: Smoke test CLI bundle
+        run: pnpm -C apps/kimi-code run smoke
+
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run test
+
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run lint
+      - run: pnpm run sherif
+
+  typecheck:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+      - name: Typecheck
+        run: |
+          pnpm dlx --package @typescript/native-preview@beta tsgo --version
+          for config in packages/*/tsconfig.json apps/kimi-code/tsconfig.json; do
+            echo "Typechecking ${config}"
+            pnpm dlx --package @typescript/native-preview@beta tsgo -p "${config}" --noEmit
+          done
diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml
new file mode 100644
index 000000000..1d54f305b
--- /dev/null
+++ b/.github/workflows/docs-deploy.yml
@@ -0,0 +1,60 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs-deploy.yml'
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Install docs dependencies
+        run: pnpm --ignore-workspace -C docs install
+
+      - name: Build docs
+        run: pnpm -C docs run build
+        env:
+          VITEPRESS_BASE: /${{ github.event.repository.name }}/
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
diff --git a/.github/workflows/native-bundle.yml b/.github/workflows/native-bundle.yml
new file mode 100644
index 000000000..c9aa010c5
--- /dev/null
+++ b/.github/workflows/native-bundle.yml
@@ -0,0 +1,21 @@
+name: Native Bundle
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    uses: ./.github/workflows/_native-build.yml
+    with:
+      upload-artifact-prefix: kimi-code-native
+      retention-days: 3
+      sign-macos: true
+    secrets:
+      APPLE_CERTIFICATE_P12: ${{ secrets.APPLE_CERTIFICATE_P12 }}
+      APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+      APPLE_NOTARIZATION_KEY_P8: ${{ secrets.APPLE_NOTARIZATION_KEY_P8 }}
+      APPLE_NOTARIZATION_KEY_ID: ${{ secrets.APPLE_NOTARIZATION_KEY_ID }}
+      APPLE_NOTARIZATION_ISSUER_ID: ${{ secrets.APPLE_NOTARIZATION_ISSUER_ID }}
diff --git a/.github/workflows/pr-title-checker.yml b/.github/workflows/pr-title-checker.yml
new file mode 100644
index 000000000..00bfdf20f
--- /dev/null
+++ b/.github/workflows/pr-title-checker.yml
@@ -0,0 +1,15 @@
+name: PR Title Checker
+
+on:
+  pull_request:
+    types: [opened, edited, labeled]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    name: pr-title-checker
+    steps:
+      - uses: thehanimo/pr-title-checker@v1.4.3
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          configuration_path: ".github/pr-title-checker-config.json"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 000000000..fc0b9a8bb
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,112 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    if: github.repository_owner == 'MoonshotAI'
+    outputs:
+      kimi_native_release: ${{ steps.kimi-release.outputs.should_publish }}
+      kimi_release_tag: ${{ steps.kimi-release.outputs.tag }}
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write  # Required for NPM Trusted Publishing (OIDC)
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Upgrade npm for Trusted Publishing
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build packages
+        run: pnpm build
+
+      - name: Create Release Pull Request or Publish to npm
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          publish: pnpm changeset publish
+          version: pnpm changeset version
+          commit: 'ci: release packages'
+          title: 'ci: release packages'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # NPM_TOKEN is not needed with Trusted Publishing (OIDC)
+
+      - name: Resolve Kimi Code native release
+        if: steps.changesets.outputs.published == 'true'
+        id: kimi-release
+        run: node apps/kimi-code/scripts/native/resolve-release.mjs
+        env:
+          CHANGESETS_PUBLISHED_PACKAGES: ${{ steps.changesets.outputs.publishedPackages }}
+
+  native-artifacts:
+    name: Native release artifact
+    needs: release
+    if: needs.release.outputs.kimi_native_release == 'true'
+    uses: ./.github/workflows/_native-build.yml
+    with:
+      upload-artifact-prefix: kimi-code-native
+      retention-days: 7
+      sign-macos: true
+    secrets:
+      APPLE_CERTIFICATE_P12: ${{ secrets.APPLE_CERTIFICATE_P12 }}
+      APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+      APPLE_NOTARIZATION_KEY_P8: ${{ secrets.APPLE_NOTARIZATION_KEY_P8 }}
+      APPLE_NOTARIZATION_KEY_ID: ${{ secrets.APPLE_NOTARIZATION_KEY_ID }}
+      APPLE_NOTARIZATION_ISSUER_ID: ${{ secrets.APPLE_NOTARIZATION_ISSUER_ID }}
+
+  publish-native-assets:
+    name: Publish native release assets
+    needs:
+      - release
+      - native-artifacts
+    if: needs.release.outputs.kimi_native_release == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Download native artifacts
+        uses: actions/download-artifact@v8
+        with:
+          pattern: kimi-code-native-*
+          path: dist-native-release
+          merge-multiple: true
+
+      - name: Produce manifest.json
+        env:
+          RELEASE_TAG: ${{ needs.release.outputs.kimi_release_tag }}
+        run: node apps/kimi-code/scripts/native/produce-manifest.mjs dist-native-release "$RELEASE_TAG"
+
+      - name: Upload assets to GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ needs.release.outputs.kimi_release_tag }}
+        run: gh release upload "$RELEASE_TAG" dist-native-release/* --clobber
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 000000000..13b316428
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,13 @@
+node_modules/
+dist/
+dist-native/
+.tmp-api-extractor/
+coverage/
+*.tsbuildinfo
+.vitest-results/
+.DS_Store
+.playwright-mcp/
+.claude
+.conductor
+.kimi-stash-dir
+superpowers/
diff --git a/.npmrc b/.npmrc
new file mode 100644
index 000000000..fd6158e56
--- /dev/null
+++ b/.npmrc
@@ -0,0 +1,3 @@
+auto-install-peers=true
+engine-strict=true
+strict-peer-dependencies=false
diff --git a/.nvmrc b/.nvmrc
new file mode 100644
index 000000000..5bf4400f2
--- /dev/null
+++ b/.nvmrc
@@ -0,0 +1 @@
+24.15.0
diff --git a/.oxfmtrc.json b/.oxfmtrc.json
new file mode 100644
index 000000000..493d050e2
--- /dev/null
+++ b/.oxfmtrc.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "sortImports": {
+    "groups": ["builtin", "external", "internal", ["parent", "sibling", "index"], "unknown"],
+    "newlinesBetween": true,
+    "order": "asc"
+  },
+  "sortPackageJson": true,
+  "ignorePatterns": ["dist/", "coverage/", "pnpm-lock.yaml", "*.generated.ts"]
+}
diff --git a/.oxlintrc.json b/.oxlintrc.json
new file mode 100644
index 000000000..877553f49
--- /dev/null
+++ b/.oxlintrc.json
@@ -0,0 +1,155 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn",
+    "pedantic": "warn",
+    "perf": "warn"
+  },
+  "plugins": ["typescript", "import", "unicorn", "promise", "node"],
+  "rules": {
+    "eslint/no-useless-return": "off",
+    "eslint/no-shadow": "off",
+    "eslint/eqeqeq": "error",
+    "eslint/no-throw-literal": "off",
+    "eslint/no-control-regex": "off",
+    "typescript/no-misused-promises": "error",
+    "typescript/return-await": "error",
+    "typescript/only-throw-error": "error",
+    "import/no-cycle": "error",
+    "import/no-self-import": "error",
+    "import/no-unassigned-import": "off",
+    "unicorn/prefer-node-protocol": "error",
+    "unicorn/no-useless-undefined": "off",
+    "unicorn/no-lonely-if": "off",
+    "unicorn/no-array-callback-reference": "off",
+    "typescript/prefer-promise-reject-errors": "off",
+    "typescript/no-unsafe-function-type": "off",
+    "typescript/no-unsafe-argument": "off",
+    "typescript/no-unsafe-assignment": "off",
+    "typescript/no-unsafe-call": "off",
+    "typescript/no-unsafe-member-access": "off",
+    "typescript/no-unsafe-return": "off",
+
+    "eslint/no-console": "warn",
+    "typescript/no-explicit-any": "off",
+    "typescript/no-non-null-assertion": "off",
+    "typescript/use-unknown-in-catch-callback-variable": "off",
+    "typescript/consistent-type-imports": "off",
+    "typescript/ban-types": "off",
+    "import/first": "warn",
+    "import/extensions": [
+      "error",
+      "ignorePackages",
+      {
+        "js": "never",
+        "ts": "never",
+        "tsx": "never"
+      }
+    ],
+    "import/no-duplicates": "warn",
+    "import/no-mutable-exports": "warn",
+    "unicorn/error-message": "warn",
+    "unicorn/throw-new-error": "warn",
+    "unicorn/catch-error-name": "warn",
+    "unicorn/prefer-add-event-listener": "off",
+    "node/no-new-require": "warn",
+    "node/no-path-concat": "warn",
+
+    "promise/no-callback-in-promise": "warn",
+    "promise/valid-params": "warn",
+    "promise/no-return-in-finally": "warn",
+    "promise/always-return": "off",
+
+    "eslint/max-classes-per-file": "off",
+    "eslint/max-depth": "off",
+    "eslint/max-lines": "off",
+    "eslint/max-lines-per-function": "off",
+    "eslint/max-nested-callbacks": "off",
+    "eslint/no-warning-comments": "off",
+    "eslint/no-inline-comments": "off",
+    "eslint/no-negated-condition": "off",
+    "eslint/no-await-in-loop": "off",
+    "eslint/require-await": "off",
+    "typescript/require-await": "off",
+    "eslint/sort-vars": "off",
+    "eslint/radix": "off",
+    "eslint/symbol-description": "off",
+    "typescript/consistent-return": "off",
+    "unicorn/consistent-function-scoping": "off",
+    "typescript/no-deprecated": "off",
+    "typescript/no-unsafe-type-assertion": "off",
+    "typescript/strict-boolean-expressions": "off",
+    "typescript/no-duplicate-type-constituents": "off",
+    "import/max-dependencies": "off"
+  },
+  "overrides": [
+    {
+      "files": ["**/examples/**/*.ts", "**/examples/**/*.tsx"],
+      "rules": {
+        "eslint/no-console": "off"
+      }
+    },
+    {
+      "files": ["packages/kosong/src/providers/**/*.ts"],
+      "rules": {
+        "typescript/no-unsafe-argument": "off",
+        "typescript/no-unsafe-assignment": "off",
+        "typescript/no-unsafe-call": "off",
+        "typescript/no-unsafe-member-access": "off",
+        "typescript/no-unsafe-return": "off"
+      }
+    },
+    {
+      "files": [
+        "**/*.test.ts",
+        "**/*.test.tsx",
+        "**/*.spec.ts",
+        "**/*.spec.tsx",
+        "**/test/**/*.ts",
+        "**/test/**/*.tsx"
+      ],
+      "plugins": ["vitest"],
+      "rules": {
+        "typescript/no-explicit-any": "off",
+        "typescript/no-unsafe-assignment": "off",
+        "typescript/no-unsafe-argument": "off",
+        "typescript/no-non-null-assertion": "off",
+        "typescript/unbound-method": "off",
+        "typescript/no-redundant-type-constituents": "off",
+        "eslint/no-console": "off",
+        "eslint/no-promise-executor-return": "off",
+        "typescript/no-unsafe-member-access": "off",
+        "vitest/require-mock-type-parameters": "off",
+        "eslint/no-shadow": "off",
+        "unicorn/prefer-event-target": "off",
+        "jest/no-disabled-tests": "off",
+        "vitest/no-disabled-tests": "off",
+        "eslint/no-control-regex": "off",
+        "eslint/no-unused-vars": "off",
+        "eslint/no-unsafe-optional-chaining": "off",
+        "jest/valid-expect": "off",
+        "unicorn/no-useless-spread": "off",
+        "import/no-cycle": "off",
+        "typescript/no-meaningless-void-operator": "off",
+        "typescript/require-array-sort-compare": "off",
+        "vitest/expect-expect": "error",
+        "vitest/no-conditional-tests": "error",
+        "vitest/no-focused-tests": "error",
+        "vitest/no-identical-title": "error",
+        "vitest/valid-expect": "off",
+        "vitest/valid-describe-callback": "error",
+        "vitest/no-standalone-expect": "error",
+        "vitest/warn-todo": "off"
+      }
+    }
+  ],
+  "ignorePatterns": [
+    "dist/",
+    "coverage/",
+    "node_modules/",
+    "apps/*/scripts/",
+    "docs/smoke-archive/",
+    "*.generated.ts"
+  ]
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..ddb2cea34
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,60 @@
+# Repository-level Agent Guide
+
+Reply in the same language as the user.
+
+This is a TypeScript monorepo built for agent-assisted development. Keep the root `AGENTS.md` limited to hot-path rules: the project map, hard constraints, and workflow requirements — things every task needs to know.
+
+## Working Principles
+
+- Think from first principles. Start from real requirements, code facts, and verification results; if the goal is unclear, discuss it with the user first.
+- Treat code, not documentation, as the source of truth. Unless the user explicitly says otherwise, do not read ordinary Markdown just to understand the implementation.
+- Before making code changes, read the relevant code and the most recent constraints, and follow the nearest `AGENTS.md` in the directory tree.
+- Keep changes focused. Do not slip in unrelated refactors along the way.
+- When committing, do not add any co-author attribution, and do not reveal the identity of the agent in commit messages, PR descriptions, or any explanatory text.
+
+## Project Map
+
+- `apps/kimi-code`: the CLI / TUI application. It consumes core capabilities through `@moonshot-ai/kimi-code-sdk` and must not depend directly on `@moonshot-ai/agent-core`.
+- `apps/vis`, `apps/vis/server`, `apps/vis/web`: visual debugging tools for sessions and replays.
+- `packages/agent-core`: the unified agent engine, including Agent, Session, profile, skills, tools, plan, permission, background, records, and other core capabilities.
+- `packages/node-sdk`: the public TypeScript SDK and harness.
+- `packages/kosong`: the LLM / provider abstraction layer.
+- `packages/kaos`: the execution environment and file/process abstractions.
+- `packages/oauth`: Kimi OAuth and managed auth utilities.
+- `packages/telemetry`: shared client-side telemetry infrastructure.
+
+## Environment Requirements
+
+- **Node.js**: `>=24.15.0` (from the root `package.json` `engines`; `.nvmrc` is `24.15.0`, used by nvm / fnm / mise to pick the minimum recommended version).
+- **pnpm**: `10.33.0` (from the root `package.json` `packageManager`).
+- `pnpm install` will fail when the Node version is not satisfied, because `.npmrc` sets `engine-strict=true`.
+
+## General Coding Rules
+
+- For optional object properties, pass `undefined` directly instead of using conditional spread.
+  - YES: `{ user }`
+  - NO: `{ ...(user ? { user } : undefined) }`
+- Optional object properties do not need to additionally allow `undefined` in the type.
+  - YES: `interface Options { user?: User }`
+  - NO: `interface Options { user?: User | undefined }`
+- Internal methods with only a single parameter should not be turned into options objects just for stylistic uniformity.
+- Except for a package's `index.ts`, other `index.ts` files should prefer `export * from './module';`.
+- The `Agent` class in `packages/agent-core/src/agent` must be usable on its own. The constructor must not force the caller to create a `Session` instance, nor require an `agentId` or `session`. It may accept an optional `sessionId` as a request-config hint — for example mapped to the provider's `prompt_cache_key` — but the instance must not hold `sessionId`, and must not depend on the Session lifecycle, metadata, or parent/child relationship logic.
+- Do not add too many new test files. Prefer adding tests to the existing test file of the corresponding component or module.
+- When a test fails because of a user modification, default to fixing the test first; do not change the implementation to satisfy an old test unless the implementation truly has a bug.
+- Do not sacrifice code quality for external compatibility unless the user explicitly asks for it. Breaking changes go through changesets and a `major` bump, gated by the rule below.
+
+## Where to Update Instructions
+
+- Hard rules that affect almost every task: update the root `AGENTS.md`.
+- Rules that only affect a specific directory: update the nearest sub-directory `AGENTS.md`.
+- Keep instruction updates focused and supported by code facts.
+
+## Workflow Requirements
+
+- Prefer `rg` / `rg --files` when reading code.
+- When designing changes, follow existing boundaries and local patterns first.
+- When creating a PR, the PR title must follow Conventional Commit style, e.g. `chore: remove legacy format commands`.
+- After finishing a task and before submitting a PR, you must run the `gen-changesets` skill (see `.agents/skills/gen-changesets/SKILL.md`) and generate a changeset under `.changeset/` according to its rules.
+- When generating a changeset, **never** decide on a `major` bump on your own. When you judge a change to meet the major criteria (breaking changes, incompatible user configuration, renamed or removed commands/arguments, changed behavior semantics, etc.), you must stop and explain it to the user and ask for confirmation. **Only write `major` after the user has explicitly agreed.** Otherwise default to `minor` (and fall back to `patch` if `minor` is unclear). See the "Hard rule: confirm with the user before writing `major`" section in `.agents/skills/gen-changesets/SKILL.md` for details.
+- Prefer importing via `import ... from '#/...'`, which serves the same purpose as `import ... from '@/...'`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..ac49526de
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,96 @@
+# Contributing to kimi-code
+
+Thanks for taking the time to contribute! This project moves quickly, and thoughtful contributions from the community are what keep it sharp. The guide below walks you through how we work so your PR has the best chance of landing smoothly.
+
+## Before You Start
+
+- Open an issue or discussion before making changes larger than ~100 lines so we can align on direction early.
+- We only merge PRs that are aligned with the roadmap — drive-by refactors without context are unlikely to land.
+- Code quality bar: as good as code written by a strong human engineer or a competent coding agent. We hold AI-assisted contributions to the same standard as hand-written ones.
+
+## Project Layout
+
+This is a pnpm monorepo. The most relevant entry points are:
+
+- `apps/kimi-code` — CLI / TUI
+- `apps/vis` — session replay & debugging visualizer
+- `packages/node-sdk` — public TypeScript SDK (`@moonshot-ai/kimi-code-sdk`)
+- `packages/agent-core`, `kosong`, `kaos`, `oauth`, `telemetry` — internal engine packages
+- `docs/` — VitePress bilingual docs site
+
+For the full project map, see [AGENTS.md](AGENTS.md).
+
+## Development Setup
+
+Prerequisites: Node.js >= 24.15.0, pnpm 10.33.0, Git.
+
+```sh
+git clone https://github.com/MoonshotAI/kimi-code.git
+cd kimi-code
+pnpm install
+```
+
+Useful scripts:
+
+- `pnpm dev:cli` — run the CLI in dev mode
+- `pnpm test` — run tests (vitest)
+- `pnpm typecheck` — TypeScript check (note: builds packages first)
+- `pnpm lint` — oxlint
+- `pnpm lint:fix` — oxlint with auto-fix
+- `pnpm build` — build all packages
+
+## Commit Convention
+
+All commits and PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/).
+
+| Type     | Use for                                     | Example                                   |
+|----------|---------------------------------------------|-------------------------------------------|
+| feat     | A new feature                               | feat(agent-core): add tool dedup          |
+| fix      | A bug fix                                   | fix(tui): correct status bar alignment    |
+| docs     | Documentation only                          | docs: clarify install instructions        |
+| chore    | Tooling / housekeeping                      | chore: bump dependencies                  |
+| refactor | Internal refactor without behavior change   | refactor(kosong): extract retry helper    |
+| test     | Adding or improving tests                   | test(agent-core): cover skill resolver    |
+| ci       | CI / build pipeline changes                 | ci: cache pnpm store                      |
+| build    | Build system / artifact changes             | build(native): add win32-arm64 target     |
+| perf     | Performance improvement                     | perf(session): batch event flushes        |
+| style    | Formatting only (no logic)                  | style: apply oxlint --fix                 |
+
+PR titles are enforced by the `pr-title-checker` workflow — a non-conforming title will block merge.
+
+## Changesets
+
+This repo uses [changesets](https://github.com/changesets/changesets) to manage versioning and releases.
+
+- Every PR that affects release artifacts (code, behavior, public API) **must** include a changeset.
+- Docs-only, test-only, or CI-only PRs may skip changesets.
+- Generate one with `pnpm changeset` and follow the prompts (which packages are touched, which bump level).
+- For repo-specific conventions, see `.changeset/README.md`.
+
+## Pull Request Checklist
+
+Before requesting review, make sure your PR ticks the following:
+
+- [ ] Linked an issue (for non-trivial changes)
+- [ ] PR title follows Conventional Commits
+- [ ] Added or updated tests
+- [ ] Added a changeset if the PR affects release artifacts
+- [ ] Ran `pnpm lint && pnpm typecheck && pnpm test` locally
+- [ ] Updated user-facing docs in `docs/` if behavior changed
+
+The `.github/pull_request_template.md` checklist is a shorter subset of this — both must pass.
+
+## Code Style
+
+- TypeScript across the codebase.
+- Linting via `oxlint` (config in `.oxlintrc.json`).
+- Auto-formatting via `pnpm lint:fix`.
+- Follow existing local patterns when the lint rules do not cover a style choice.
+
+## Reporting Security Issues
+
+Found a security issue? Please see [SECURITY.md](SECURITY.md) instead of opening a public issue.
+
+## License
+
+By contributing to this repository, you agree that your contributions will be licensed under the [MIT License](LICENSE).
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 000000000..6102a1bc7
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moonshot AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/Makefile b/Makefile
new file mode 100644
index 000000000..d5889efa2
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,67 @@
+.PHONY: prepare build typecheck lint lint-fix lint-pkg sherif test test-watch test-coverage clean changeset version publish release dev vis
+
+## Setup
+
+prepare:
+	pnpm install
+
+## Build
+
+build:
+	pnpm run build
+
+## Quality
+
+typecheck:
+	pnpm run typecheck
+
+lint:
+	pnpm run lint
+
+lint-fix:
+	pnpm run lint:fix
+
+sherif:
+	pnpm run sherif
+
+lint-pkg:
+	pnpm run lint:pkg
+
+## Test
+
+test:
+	pnpm run test
+
+test-watch:
+	pnpm run test:watch
+
+test-coverage:
+	pnpm run test:coverage
+
+## Clean
+
+clean:
+	pnpm run clean
+
+## Release
+
+changeset:
+	pnpm run changeset
+
+version:
+	pnpm run version
+
+publish:
+	pnpm run publish
+
+release: version publish
+
+## Development
+
+dev:
+	pnpm run dev:cli
+
+## vis
+
+vis:
+	pnpm run vis
diff --git a/README.md b/README.md
new file mode 100644
index 000000000..501bf8199
--- /dev/null
+++ b/README.md
@@ -0,0 +1,100 @@
+# Kimi Code CLI
+
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![Docs](https://img.shields.io/badge/docs-online-blue)](https://moonshotai.github.io/kimi-code/en/) <br>
+[Documentation](https://moonshotai.github.io/kimi-code/en/) · [Issues](https://github.com/MoonshotAI/kimi-code/issues) · [中文](README.zh-CN.md)
+
+![Demo of using Kimi Code](./docs/media/intro.gif)
+
+## What is Kimi Code CLI
+
+Kimi Code CLI is an AI coding agent that runs in your terminal — it can read and edit code, run shell commands, search files, fetch web pages, and choose the next step based on the feedback it receives. It works out of the box with Moonshot AI’s Kimi models and can also be configured to use other compatible providers.
+
+## Install
+
+Install with the official script. No Node.js required.
+
+- **macOS or Linux**:
+
+```sh
+curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
+```
+
+- **Windows (PowerShell)**:
+
+```powershell
+irm https://code.kimi.com/kimi-code/install.ps1 | iex
+```
+
+Then, run it with a new shell session:
+
+```sh
+kimi --version
+```
+
+For npm install, upgrade, uninstall, see [Getting Started](https://moonshotai.github.io/kimi-code/en/guides/getting-started).
+
+## Quick Start
+
+Open a project and start the interactive UI:
+
+```sh
+cd your-project
+kimi
+```
+
+On first launch, run `/login` inside Kimi Code CLI and choose either Kimi Code OAuth or a Moonshot AI Open Platform API key. After login, try your first task:
+
+```
+Take a look at this project and explain its main directories.
+```
+
+## Key Features
+
+- **Single-binary distribution.** Install with one command: no Node.js setup, PATH gymnastics, or global module conflicts.
+- **Blazing-fast startup.** The TUI is ready in milliseconds, so starting a session never feels heavy.
+- **Purpose-built TUI.** A carefully tuned interface for long, focused agent sessions.
+- **Video input.** Drop a screen recording or demo clip into the chat, and let the agent watch what is hard to describe in words.
+- **AI-native MCP configuration.** Add, edit, and authenticate Model Context Protocol servers conversationally with `/mcp-config`, without hand-editing JSON.
+- **Subagents for focused, parallel work.** Dispatch built-in `coder`, `explore`, and `plan` subagents in isolated contexts while keeping the main conversation clean.
+- **Lifecycle hooks.** Run local commands at key points to gate risky tool calls, audit decisions, trigger desktop notifications, or connect to your own automation.
+
+## Docs
+
+- [Getting Started](https://moonshotai.github.io/kimi-code/en/guides/getting-started)
+- [Interaction and approvals](https://moonshotai.github.io/kimi-code/en/guides/interaction)
+- [Sessions](https://moonshotai.github.io/kimi-code/en/guides/sessions)
+- [Configuration](https://moonshotai.github.io/kimi-code/en/configuration/config-files)
+- [Command reference](https://moonshotai.github.io/kimi-code/en/reference/kimi-command)
+
+## Develop
+
+Requirements: Node.js ≥ 24.15.0, pnpm 10.33.0.
+
+```sh
+git clone https://github.com/MoonshotAI/kimi-code.git
+cd kimi-code
+pnpm install
+```
+
+```sh
+pnpm dev:cli    # run the CLI in dev mode
+pnpm test       # run tests
+pnpm typecheck  # TypeScript check
+pnpm lint       # oxlint
+pnpm build      # build all packages
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution guide.
+
+## Community
+
+- [Issues](https://github.com/MoonshotAI/kimi-code/issues)
+- For security vulnerabilities, see [SECURITY.md](SECURITY.md).
+
+## Acknowledgements
+
+Our TUI is built on top of [`pi-tui`](https://github.com/earendil-works/pi-mono/tree/main/packages/tui). We thank the authors of `pi-tui` for their valuable work.
+
+## License
+
+Released under the [MIT License](LICENSE).
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 000000000..ace6cb425
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,104 @@
+# Kimi Code CLI
+
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![Docs](https://img.shields.io/badge/docs-online-blue)](https://moonshotai.github.io/kimi-code/zh/)
+
+[Documentation](https://moonshotai.github.io/kimi-code/zh/) · [Issues](https://github.com/MoonshotAI/kimi-code/issues) · [English](README.md)
+
+
+![Kimi Code 的使用演示](./docs/media/intro.gif)
+
+
+## 什么是 Kimi Code CLI
+
+Kimi Code CLI 是一个运行在终端里的 AI 编程 agent，可以帮你读写代码、执行 shell 命令、检索文件、抓取网页，并根据反馈自主决定下一步动作。开箱即用对接 Moonshot AI 的 Kimi 模型，也可指向其他兼容厂商。
+
+## 安装
+
+推荐使用官方安装脚本，不需要提前安装 Node.js。
+
+- **macOS / Linux**：
+
+```sh
+curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
+```
+
+- **Windows（PowerShell）**：
+
+```powershell
+irm https://code.kimi.com/kimi-code/install.ps1 | iex
+```
+
+随后在新的终端会话中运行：
+
+```sh
+kimi --version
+```
+
+npm 安装、升级、卸载方式，见[快速上手](https://moonshotai.github.io/kimi-code/zh/guides/getting-started)。
+
+## 快速开始
+
+进入项目目录并启动交互界面：
+
+```sh
+cd your-project
+kimi
+```
+
+首次启动时，在 Kimi Code CLI 里输入 `/login`，选择 Kimi Code OAuth 或 Moonshot AI Open Platform API 密钥登录。登录完成后，可以先让它熟悉项目：
+
+```
+帮我看一下这个项目的目录结构，简单介绍一下每个目录是做什么的
+```
+
+## 核心特性
+
+- **二进制发行，零环境依赖** 一行命令安装，不需要预装 Node.js，不用折腾 PATH，也不会和全局模块冲突。
+- **极速启动** TUI 在毫秒级就绪，开一个新会话没有任何心智负担。
+- **精致的 TUI 体验** 为长时间、专注的 Agent 会话精心打磨的交互界面。
+- **视频也能输入** 屏幕录像、演示视频也能拖进对话。
+- **AI-native 的 MCP 配置** 通过 `/mcp-config` 对话式添加、编辑、认证 MCP 服务器，无需手写 JSON。
+- **子 Agent 聚焦并行工作** 内置 `coder`、`explore`、`plan` 子 Agent 在隔离上下文中处理子任务，主对话保持清爽。
+- **生命周期 hooks** 在关键节点执行本地命令：拦截高风险工具调用、审计决策、发送桌面通知，或对接你自己的自动化脚本。
+
+
+## 文档
+
+- [快速上手](https://moonshotai.github.io/kimi-code/zh/guides/getting-started)
+- [交互与审批](https://moonshotai.github.io/kimi-code/zh/guides/interaction)
+- [会话](https://moonshotai.github.io/kimi-code/zh/guides/sessions)
+- [配置](https://moonshotai.github.io/kimi-code/zh/configuration/config-files)
+- [命令参考](https://moonshotai.github.io/kimi-code/zh/reference/kimi-command)
+
+## 本地开发
+
+环境要求：Node.js ≥ 24.15.0，pnpm 10.33.0。
+
+```sh
+git clone https://github.com/MoonshotAI/kimi-code.git
+cd kimi-code
+pnpm install
+```
+
+```sh
+pnpm dev:cli    # 以开发模式运行 CLI
+pnpm test       # 运行测试
+pnpm typecheck  # TypeScript 检查
+pnpm lint       # 运行 oxlint
+pnpm build      # 构建所有包
+```
+
+完整贡献流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 社区
+
+- [Issues](https://github.com/MoonshotAI/kimi-code/issues)
+- 安全漏洞反馈，请见 [SECURITY.md](SECURITY.md)。
+
+## 致谢
+
+我们的 TUI 构建在 [`pi-tui`](https://github.com/earendil-works/pi-mono/tree/main/packages/tui) 之上。我们忠心感谢 `pi-tui` 作者的工作。
+
+## 许可证
+
+基于 [MIT](LICENSE) 协议发布。
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 000000000..982c6df63
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,33 @@
+# Security Policy
+
+## Supported Versions
+
+Currently, Kimi Code only provides security support for the latest released version.
+
+## Reporting a Vulnerability
+
+We take security seriously. **Please do not open a public issue for security vulnerabilities.**
+
+Preferred channel:
+
+- GitHub Security Advisories — https://github.com/MoonshotAI/kimi-code/security/advisories/new
+  (private disclosure, tracked with the codebase)
+
+Alternative channel:
+
+- Email: code@moonshot.ai (please include "[security]" in the subject)
+
+## What to Include
+
+- Affected version (output of `kimi --version`)
+- Reproduction steps
+- Impact assessment
+- Any suggested mitigation
+
+## Our Response
+
+We will acknowledge your report and provide an initial assessment as soon as we can.
+
+## Public Disclosure
+
+We will coordinate with you on disclosure timing once a fix is ready.
diff --git a/apps/kimi-code/.gitignore b/apps/kimi-code/.gitignore
new file mode 100644
index 000000000..66d6a21a6
--- /dev/null
+++ b/apps/kimi-code/.gitignore
@@ -0,0 +1,2 @@
+# Copied from packages/kimi-core at build time
+agents/
diff --git a/apps/kimi-code/AGENTS.md b/apps/kimi-code/AGENTS.md
new file mode 100644
index 000000000..9c8f422cf
--- /dev/null
+++ b/apps/kimi-code/AGENTS.md
@@ -0,0 +1,128 @@
+# apps/kimi-code Development Guide
+
+This file only contains rules local to `apps/kimi-code`. For cross-repo rules, see the root `AGENTS.md`.
+
+## TUI File Layout
+
+`apps/kimi-code` is the terminal UI / CLI app. The entry chain is:
+
+`src/main.ts` -> `src/cli/commands.ts` -> `src/cli/run-shell.ts` -> SDK `KimiHarness` -> `src/tui/kimi-tui.ts`
+
+Main directories:
+
+- `src/constant/`: non-copy constants shared by CLI/TUI — product, protocol, paths, terminal control, updates, and so on.
+- `src/cli/`: command-line arguments, subcommands, and CLI startup.
+- `src/tui/`: the interactive terminal UI.
+- `src/tui/kimi-tui.ts`: the TUI master assembler, responsible for wiring state, layout, editor, session, SDK events, and dialogs together.
+- `src/tui/actions/`: reusable TUI state/replay/projection logic. Pure logic that can be split out of `KimiTUI` should land here first.
+- `src/tui/commands/`: slash command definitions, parsing, ordering, and dynamic skill command generation.
+- `src/tui/components/`: pi-tui components, organized by UI type.
+- `src/tui/constant/`: non-copy constants reused across TUI modules — symbols, terminal sequences, render sizing, streaming-arg match rules, and so on.
+- `src/tui/components/chrome/`: persistent UI chrome — footer, todo panel, welcome, loader, device code.
+- `src/tui/components/dialogs/`: selectors, approval panels, question popups, and settings popups that temporarily replace the editor.
+- `src/tui/components/editor/`: the custom input box and the file mention provider.
+- `src/tui/components/media/`: image, diff, code highlight, and other media displays.
+- `src/tui/components/messages/`: message blocks in the transcript — assistant, user, tool call, thinking, usage, subagent, and so on.
+- `src/tui/components/panes/`: right-side / activity-area panes such as the activity pane and queue pane.
+- `src/tui/reverse-rpc/`: the adapter layer that bridges SDK approval/question callbacks to the UI.
+- `src/tui/theme/`: themes, color tokens, style helpers, and the pi-tui markdown theme.
+- `src/tui/utils/`: TUI-only utility functions.
+- `src/utils/`: app-wide utilities — clipboard, git, history, image, process, usage, and so on.
+
+## Module Responsibilities
+
+- `cli` only interprets command-line input, assembles startup arguments, and invokes the TUI. Do not put TUI interaction logic into the CLI.
+- `KimiTUI` coordinates; it does not accumulate complex business rules. New logic that can be tested independently should be split into `actions`, `commands`, `components`, `reverse-rpc`, or `utils` first.
+- `commands` only owns slash-command declaration, parsing, and the parsed-result types. The actual execution can be dispatched from `KimiTUI`, but complex logic should continue to sink downward.
+- `components` only handle presentation and local interaction; they must not call the SDK directly, and must not read or write session state directly.
+- `reverse-rpc` converts SDK approval/question requests into the data shape a UI panel/dialog needs, and converts the user's choice back into an SDK response.
+- `theme` is the single source of truth for colors and styles. Components must not bypass the theme system and use chalk named colors directly.
+- `utils` holds utility functions with no UI-state dependency. Logic that needs `TUIState` or a component instance must not live under app-level `src/utils`.
+- `apps/kimi-code` may only use core capabilities through `@moonshot-ai/kimi-code-sdk`. Do not import `@moonshot-ai/agent-core` directly in app code.
+
+## KimiTUI Internal Sections
+
+`src/tui/kimi-tui.ts` is large. When you modify it, place code into the existing responsibility section — do not just drop it where it happens to be convenient.
+
+- Types and state creation: `KimiTUIStartupInput`, `TUIState`, `createInitialAppState`, `createTUIState`. Before adding new global UI state, decide whether it really belongs in `TUIState`.
+- Startup helpers: slash commands, autocomplete, skill commands, input history.
+- Lifecycle: `start`, `init`, `stop`. They only handle startup/shutdown order — do not stuff feature implementations into them.
+- Layout and editor: `buildLayout`, `setupEditorHandlers`, external editor, clipboard image, exit shortcuts.
+- User input: `handleUserInput`, `executeSlashCommand`, `handleBuiltInSlashCommand`, `sendNormalUserInput`.
+- Sending and queueing: `enqueueMessage`, `sendMessageInternal`, `sendMessage`, `steerMessage`, `finalizeTurn`.
+- Session management: create, restore, switch, close, sync runtime state, subscribe to session events.
+- Event routing: `handleEvent` only dispatches; concrete events go into the corresponding `handleXxx`.
+- Streaming rendering: assistant delta, thinking, tool call, tool result, compaction, subagent, background agent.
+- Transcript: `createTranscriptComponent`, `appendTranscriptEntry`, read/tool/agent group aggregation.
+- Activity / queue / footer: `updateActivityPane`, `resolveActivityPaneMode`, `updateQueueDisplay`, terminal progress.
+- Dialogs / selectors: help, session picker, editor/model/thinking/theme/permission/settings selectors, approval / question panels.
+- Slash command handlers: `handleThemeCommand`, `handleModelCommand`, `handlePlanCommand`, `handleCompactCommand`, `handleLoginCommand`, and so on.
+
+If a section keeps growing, split pure functions, state projections, presentation components, and handler logic into the corresponding directories rather than continuing to expand `KimiTUI`.
+
+## Where New Features Go
+
+The feature type decides where it lands:
+
+- New CLI arguments: change `src/cli/commands.ts` / `src/cli/options.ts`, then pass them into the TUI via `src/cli/run-shell.ts`. Do not let the CLI operate on the session directly.
+- New CLI subcommands: put them under `src/cli/sub/`, with non-interactive command logic only; when SDK access is needed, go through `@moonshot-ai/kimi-code-sdk`.
+- New slash commands: first change definition, parsing, and types under `src/tui/commands/`; put the execution entry into the slash-command handler section of `KimiTUI`; split complex execution logic into `actions` or `utils`.
+- New skill-derived commands: hook into `buildSkillSlashCommands` / the skill command map — do not hard-code a single skill.
+- New transcript message types: define the data shape in `src/tui/types.ts`, add or extend a component under `components/messages/`, and register the renderer in `createTranscriptComponent`.
+- New tool-result display: prefer extending `components/messages/tool-renderers/registry.ts` and the corresponding renderer; do not stack branches inside `ToolCallComponent`.
+- New popup / selector: put it under `components/dialogs/` and mount it via `mountEditorReplacement`; if the trigger comes from an SDK callback, also check whether `reverse-rpc/` needs an adapter/controller/handler.
+- New SDK event handling: add the dispatch in `handleEvent`, then add the corresponding `handleXxx`. If the event simply maps to a transcript entry.
+- New session start / resume behavior: put it in the session management section, keeping `init` focused only on startup orchestration.
+- New status bar, activity area, or queue display: change `chrome/footer`, `panes/activity`, `panes/queue`, and the corresponding `updateXxx` method.
+- New configuration option: first change the read/write and schema in `src/tui/config.ts`, then wire the settings UI; when persistence is needed, go through `saveTuiConfig`.
+- New constants: constants shared by CLI/TUI and not copy belong in `src/constant/`; non-copy constants reused only within the TUI belong in `src/tui/constant/`. Component-local copy, option labels, help descriptions, dialog title/footer text — keep these next to the corresponding component or command, do not centralize them into a global copy constants module.
+- New general-purpose capability: if it does not depend on TUI state, put it under `src/utils/`; if it depends on TUI state or a component, put it under `src/tui/utils/`.
+
+Test placement rules:
+
+- Component behavior tests live next to the corresponding component's tests.
+- Command parsing tests go under `test/tui/commands/`.
+- reverse-rpc tests go under `test/tui/reverse-rpc/`.
+- Pure utility tests go next to the corresponding utils tests.
+- Do not create a generic `some-feature.test.ts` just to land a small feature.
+
+## TUI Coding Conventions
+
+- Do not over-encapsulate, especially for one- or two-line functions — do not introduce a two-layer wrapper, just inline.
+- Functions with no state / UI side effects do not belong as private methods on the `KimiTUI` class; put them in external utils.
+- Constants must live in the corresponding `constant` directory; they must not be scattered through component or logic code.
+- Inside `handleInput(data)`, when comparing a printable character (letter, digit, space, punctuation), it is **forbidden** to write literal comparisons such as `data === 'q'`. With the Kitty keyboard protocol enabled in terminals like VSCode, these keys are sent as CSI-u sequences (e.g. `\x1b[113u`), and a bare comparison will never match. Decode with `printableChar(data)` from `src/tui/utils/printable-key.ts` first, then compare; function keys continue to use `matchesKey(data, Key.*)`; control characters (codepoint < 32) may still be compared against the raw `data`. `test/tui/printable-key-guard.test.ts` enforces this in CI.
+
+## How to Set Themes
+
+Themes are managed centrally under `src/tui/theme/`:
+
+- `colors.ts` defines semantic tokens: `ColorPalette`, `darkColors`, `lightColors`.
+- `styles.ts` builds common chalk helpers on top of `ColorPalette`.
+- `pi-tui-theme.ts` produces the theme configuration markdown / pi-tui requires.
+- `bundle.ts` packs `colors`, `styles`, and `markdownTheme` into a `KimiTUIThemeBundle`.
+- `index.ts` / `detect.ts` handle the theme type and auto/dark/light resolution.
+
+When setting or switching themes:
+
+- The UI entry goes through `ThemeSelectorComponent`, `handleThemeCommand`, and `applyThemeChoice`.
+- The real apply step goes through `KimiTUI.applyTheme`, which should update `state.theme`, `state.appState.theme`, and notify the relevant components to refresh their palette.
+- Persisting the user's choice goes through `saveTuiConfig`. Do not let a component write the config file itself.
+
+When writing color:
+
+- Do not use chalk named colors such as `chalk.red`, `chalk.cyan`, `chalk.white`, `chalk.gray`, `chalk.dim`, or `chalk.yellow` directly.
+- If a component already has `colors`, use `chalk.hex(colors.<token>)(text)`.
+- If a component already has `state.theme.styles` or styles passed in, prefer helpers such as `styles.error(text)`, `styles.dim(text)`.
+- When new visual semantics have no token, first add a semantic field to `ColorPalette`, and fill in both `darkColors` and `lightColors`.
+- In light themes, text tokens against a white background must be at least 4.5:1; borders and large chrome must be at least 3:1.
+- Do not cache styled chalk functions at module top level. Theme switching must take effect within a single render, so styles must be generated on the render path from the current palette.
+
+After a theme change, non-comment code must not contain chalk named colors such as `chalk.white`, `chalk.cyan`, `chalk.red`, `chalk.green`, `chalk.gray`, `chalk.yellow`, `chalk.blue`, `chalk.magenta`, `chalk.whiteBright`, or `chalk.blackBright`.
+
+## General Coding Requirements
+
+- For optional object properties, pass `undefined` directly — do not use conditional spread.
+- Optional object properties do not need to additionally allow `undefined` in the type.
+- Internal methods with only a single parameter should not be turned into options objects just for stylistic uniformity.
+- Except for a package's own `index.ts`, other `index.ts` files should prefer `export * from './module'`.
diff --git a/apps/kimi-code/README.md b/apps/kimi-code/README.md
new file mode 100644
index 000000000..9c0bd4e27
--- /dev/null
+++ b/apps/kimi-code/README.md
@@ -0,0 +1,88 @@
+# @moonshot-ai/kimi-code
+
+> The Starting Point for Next-Gen Agents
+
+[![npm](https://img.shields.io/npm/v/@moonshot-ai/kimi-code)](https://www.npmjs.com/package/@moonshot-ai/kimi-code) [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)  [![Docs](https://img.shields.io/badge/docs-online-blue)](https://moonshotai.github.io/kimi-code/en/)
+
+## What is Kimi Code CLI
+
+Kimi Code CLI is an AI coding agent that runs in your terminal. It can read and edit code, run shell commands, search files, fetch web pages, and choose the next step based on the feedback it receives. It works out of the box with Moonshot AI's Kimi models and can also be configured to use other compatible providers.
+
+## Install
+
+The recommended install path is the official script. It does not require Node.js to be installed first.
+
+- **macOS / Linux**:
+
+```sh
+curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
+```
+
+- **Windows (PowerShell)**:
+
+```powershell
+irm https://code.kimi.com/kimi-code/install.ps1 | iex
+```
+
+Then run it with a new Terminal session:
+
+```sh
+kimi --version
+```
+
+### Alternative: npm
+
+If you prefer npm, use Node.js 22.19.0 or later:
+
+```sh
+npm install -g @moonshot-ai/kimi-code
+```
+
+Or with pnpm:
+
+```sh
+pnpm add -g @moonshot-ai/kimi-code
+```
+
+For upgrade and uninstall instructions, see the [Getting Started guide](https://moonshotai.github.io/kimi-code/en/guides/getting-started).
+
+## Quick Start
+
+Open a project and start the interactive UI:
+
+```sh
+cd your-project
+kimi
+```
+
+On first launch, run `/login` inside Kimi Code CLI and choose either Kimi Code OAuth or a Moonshot AI Open Platform API key. After login, try a first task:
+
+```
+Take a look at this project and explain the main directories.
+```
+
+## Key Features
+
+- **Single-binary distribution.** Install with one command — no Node.js setup, no PATH gymnastics, no global module conflicts.
+- **Blazing-fast startup.** The TUI is ready in milliseconds, so opening a session never feels heavy.
+- **Polished TUI.** A carefully tuned interface designed for long, focused agent sessions.
+- **Video input.** Drop a screen recording or demo clip into the chat — let the agent watch instead of typing out what's hard to describe in words.
+- **AI-native MCP configuration.** Add, edit, and authenticate Model Context Protocol servers conversationally via `/mcp-config` — no hand-editing JSON.
+- **Subagents for focused, parallel work.** Dispatch built-in `coder`, `explore`, and `plan` subagents in isolated context windows; the main conversation stays clean.
+- **Lifecycle hooks.** Run local commands at key points — gate risky tool calls, audit decisions, fire desktop notifications, wire into your own automation.
+
+## Documentation
+
+- Full docs: https://moonshotai.github.io/kimi-code/en/
+- 中文文档: https://moonshotai.github.io/kimi-code/zh/
+- Getting Started: https://moonshotai.github.io/kimi-code/en/guides/getting-started
+
+## Repository & Issues
+
+- Source: https://github.com/MoonshotAI/kimi-code
+- Issues: https://github.com/MoonshotAI/kimi-code/issues
+- Security: see SECURITY.md in the main repository
+
+## License
+
+MIT
diff --git a/apps/kimi-code/package.json b/apps/kimi-code/package.json
new file mode 100644
index 000000000..01f448325
--- /dev/null
+++ b/apps/kimi-code/package.json
@@ -0,0 +1,88 @@
+{
+  "name": "@moonshot-ai/kimi-code",
+  "version": "0.1.1",
+  "description": "The Starting Point for Next-Gen Agents",
+  "license": "MIT",
+  "author": "Moonshot AI",
+  "homepage": "https://github.com/MoonshotAI/kimi-code/tree/main/apps/kimi-code#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MoonshotAI/kimi-code.git",
+    "directory": "apps/kimi-code"
+  },
+  "bugs": {
+    "url": "https://github.com/MoonshotAI/kimi-code/issues"
+  },
+  "keywords": [
+    "kimi",
+    "kimi-code",
+    "cli",
+    "agent",
+    "coding-agent",
+    "ai",
+    "tui"
+  ],
+  "bin": {
+    "kimi": "dist/main.mjs"
+  },
+  "files": [
+    "dist",
+    "scripts/postinstall.mjs",
+    "scripts/postinstall",
+    "README.md"
+  ],
+  "type": "module",
+  "imports": {
+    "#/*": [
+      "./src/*.ts",
+      "./src/*/index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "smoke": "node scripts/smoke.mjs",
+    "build:native:js": "node scripts/native/01-bundle.mjs",
+    "build:native:sea": "node scripts/native/build.mjs --profile=local",
+    "build:native:release": "node scripts/native/build.mjs --profile=release",
+    "package:native": "node scripts/native/package.mjs",
+    "produce:native:manifest": "node scripts/native/produce-manifest.mjs",
+    "release:native:resolve": "node scripts/native/resolve-release.mjs",
+    "test:native:smoke": "node scripts/native/smoke.mjs",
+    "dev": "tsx --import ../../build/register-raw-text-loader.mjs ./src/main.ts",
+    "dev:prod": "node dist/main.mjs",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm -w run build:packages && vitest run",
+    "e2e": "pnpm -w run build:packages && KIMI_E2E=1 vitest run test/e2e",
+    "e2e:real": "pnpm -w run build:packages && KIMI_E2E_REAL=1 vitest run test/e2e/real-llm-smoke.e2e.test.ts",
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "dependencies": {
+    "@earendil-works/pi-tui": "^0.74.0",
+    "@mariozechner/clipboard": "^0.3.2",
+    "chalk": "^5.4.1",
+    "cli-highlight": "^2.1.11",
+    "commander": "^13.1.0",
+    "semver": "^7.7.4",
+    "smol-toml": "^1.6.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@moonshot-ai/kimi-code-oauth": "workspace:^",
+    "@moonshot-ai/kimi-code-sdk": "workspace:^",
+    "@moonshot-ai/kimi-telemetry": "workspace:^",
+    "@moonshot-ai/migration-legacy": "workspace:^",
+    "@types/semver": "^7.7.0",
+    "@types/yazl": "^2.4.6",
+    "postject": "1.0.0-alpha.6",
+    "tsx": "^4.21.0",
+    "yazl": "^3.3.1"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}
diff --git a/apps/kimi-code/scripts/native/01-bundle.mjs b/apps/kimi-code/scripts/native/01-bundle.mjs
new file mode 100644
index 000000000..46193d3e7
--- /dev/null
+++ b/apps/kimi-code/scripts/native/01-bundle.mjs
@@ -0,0 +1,17 @@
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+
+import { run } from './exec.mjs';
+
+const requireFromScript = createRequire(import.meta.url);
+const tsdownCliPath = requireFromScript.resolve('tsdown/run');
+const checkBundlePath = resolve(import.meta.dirname, 'check-bundle.mjs');
+
+export async function runBundleStep() {
+  await run(process.execPath, [tsdownCliPath, '--config', 'tsdown.native.config.ts']);
+  await run(process.execPath, [checkBundlePath]);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runBundleStep();
+}
diff --git a/apps/kimi-code/scripts/native/02-sea-blob.mjs b/apps/kimi-code/scripts/native/02-sea-blob.mjs
new file mode 100644
index 000000000..8bac05a84
--- /dev/null
+++ b/apps/kimi-code/scripts/native/02-sea-blob.mjs
@@ -0,0 +1,69 @@
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+import {
+  collectNativeAssets,
+  nativeAssetManifestKey,
+  nativeAssetSummary,
+} from './assets.mjs';
+import { fail, run } from './exec.mjs';
+import {
+  appRoot,
+  nativeBlobPath,
+  nativeIntermediatesDir,
+  nativeJsBundlePath,
+  nativeManifestDir,
+  nativeSeaConfigPath,
+  targetTriple,
+} from './paths.mjs';
+
+async function ensureBundleExists() {
+  try {
+    await stat(nativeJsBundlePath());
+  } catch {
+    fail(`Native JS bundle not found at ${nativeJsBundlePath()}. Run 01-bundle.mjs first.`);
+  }
+}
+
+async function writeSeaConfig(target) {
+  await mkdir(nativeIntermediatesDir(), { recursive: true });
+  const { manifest, manifestJson, assets } = await collectNativeAssets({
+    appRoot,
+    target,
+  });
+  const manifestPath = resolve(nativeManifestDir(target), 'manifest.json');
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(manifestPath, manifestJson);
+
+  const seaAssets = {
+    [nativeAssetManifestKey(target)]: manifestPath,
+    ...assets,
+  };
+  const config = {
+    main: nativeJsBundlePath(),
+    output: nativeBlobPath(),
+    assets: Object.fromEntries(
+      Object.entries(seaAssets).sort(([a], [b]) => a.localeCompare(b)),
+    ),
+    disableExperimentalSEAWarning: true,
+    useCodeCache: false,
+    useSnapshot: false,
+  };
+  await writeFile(nativeSeaConfigPath(), `${JSON.stringify(config, null, 2)}\n`);
+
+  console.log(`Collected native assets for ${manifest.target}:`);
+  for (const line of nativeAssetSummary(manifest)) {
+    console.log(`- ${line}`);
+  }
+}
+
+export async function runSeaBlobStep() {
+  await ensureBundleExists();
+  const target = targetTriple();
+  await writeSeaConfig(target);
+  await run(process.execPath, ['--experimental-sea-config', nativeSeaConfigPath()]);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runSeaBlobStep();
+}
diff --git a/apps/kimi-code/scripts/native/03-inject.mjs b/apps/kimi-code/scripts/native/03-inject.mjs
new file mode 100644
index 000000000..24cd0ad32
--- /dev/null
+++ b/apps/kimi-code/scripts/native/03-inject.mjs
@@ -0,0 +1,65 @@
+import { copyFile, mkdir, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { fail, run, tryRun } from './exec.mjs';
+import {
+  appRoot,
+  nativeBinDir,
+  nativeBinPath,
+  nativeBlobPath,
+  SEA_SENTINEL_FUSE,
+  targetTriple,
+} from './paths.mjs';
+
+function postjectPath() {
+  const command = process.platform === 'win32' ? 'postject.cmd' : 'postject';
+  return resolve(appRoot, 'node_modules/.bin', command);
+}
+
+async function ensureBlobExists() {
+  try {
+    await stat(nativeBlobPath());
+  } catch {
+    fail(`SEA blob not found at ${nativeBlobPath()}. Run 02-sea-blob.mjs first.`);
+  }
+}
+
+async function copyNodeExecutable(target) {
+  await mkdir(nativeBinDir(target), { recursive: true });
+  const out = nativeBinPath(target);
+  await copyFile(process.execPath, out);
+  if (process.platform !== 'win32') {
+    await run('chmod', ['755', out]);
+  }
+}
+
+async function removeSignatureIfNeeded(target) {
+  const out = nativeBinPath(target);
+  if (process.platform === 'darwin') {
+    await tryRun('codesign', ['--remove-signature', out]);
+  }
+  if (process.platform === 'win32') {
+    await tryRun('signtool', ['remove', '/s', out]);
+  }
+}
+
+async function injectSeaBlob(target) {
+  const out = nativeBinPath(target);
+  const args = [out, 'NODE_SEA_BLOB', nativeBlobPath(), '--sentinel-fuse', SEA_SENTINEL_FUSE];
+  if (process.platform === 'darwin') {
+    args.push('--macho-segment-name', 'NODE_SEA');
+  }
+  await run(postjectPath(), args);
+}
+
+export async function runInjectStep() {
+  const target = targetTriple();
+  await ensureBlobExists();
+  await copyNodeExecutable(target);
+  await removeSignatureIfNeeded(target);
+  await injectSeaBlob(target);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runInjectStep();
+}
diff --git a/apps/kimi-code/scripts/native/04-sign.mjs b/apps/kimi-code/scripts/native/04-sign.mjs
new file mode 100644
index 000000000..2930b5e63
--- /dev/null
+++ b/apps/kimi-code/scripts/native/04-sign.mjs
@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+
+import { run } from './exec.mjs';
+import { nativeBinPath, targetTriple } from './paths.mjs';
+
+const ENTITLEMENTS_PATH = resolve(import.meta.dirname, 'entitlements.plist');
+
+export function buildCodesignArgs({ identity, executable, entitlementsPath, keychainPath }) {
+  if (identity === '-') {
+    return ['--sign', '-', executable];
+  }
+  const args = [
+    '--sign',
+    identity,
+    '--options',
+    'runtime',
+    '--entitlements',
+    entitlementsPath,
+    '--timestamp',
+  ];
+  if (keychainPath) {
+    args.push('--keychain', keychainPath);
+  }
+  args.push('--force', executable);
+  return args;
+}
+
+async function sha256(path) {
+  return await new Promise((resolveHash, reject) => {
+    const hash = createHash('sha256');
+    const stream = createReadStream(path);
+    stream.on('error', reject);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => resolveHash(hash.digest('hex')));
+  });
+}
+
+async function writeChecksum(executable) {
+  const digest = await sha256(executable);
+  await writeFile(`${executable}.sha256`, `${digest}  ${basename(executable)}\n`);
+}
+
+export async function runSignStep({ identity = '-', keychainPath = null } = {}) {
+  const target = targetTriple();
+  const executable = nativeBinPath(target);
+
+  if (process.platform === 'darwin') {
+    const args = buildCodesignArgs({
+      identity,
+      executable,
+      entitlementsPath: ENTITLEMENTS_PATH,
+      keychainPath,
+    });
+    await run('codesign', args);
+  }
+
+  await writeChecksum(executable);
+  console.log(`Signed and hashed: ${executable}`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const identity = process.env.APPLE_SIGNING_IDENTITY ?? '-';
+  const keychainPath = process.env.APPLE_KEYCHAIN_PATH ?? null;
+  await runSignStep({ identity, keychainPath });
+}
diff --git a/apps/kimi-code/scripts/native/05-verify.mjs b/apps/kimi-code/scripts/native/05-verify.mjs
new file mode 100644
index 000000000..5c47da6bc
--- /dev/null
+++ b/apps/kimi-code/scripts/native/05-verify.mjs
@@ -0,0 +1,30 @@
+import { run } from './exec.mjs';
+import { nativeBinPath, targetTriple } from './paths.mjs';
+
+export async function runVerifyStep({ requireGatekeeper = false } = {}) {
+  if (process.platform !== 'darwin') {
+    console.log('Verify step skipped (not macOS)');
+    return;
+  }
+
+  const target = targetTriple();
+  const executable = nativeBinPath(target);
+
+  console.log(`==> codesign -dv ${executable}`);
+  await run('codesign', ['-dv', '--verbose=2', executable]);
+
+  if (requireGatekeeper) {
+    // spctl in 'install' mode simulates the Gatekeeper online check — only a
+    // fully notarized binary passes. Ad-hoc signed binaries fail, so this is
+    // only run under the release profile.
+    console.log(`==> spctl -a -vvv -t install ${executable}`);
+    await run('spctl', ['-a', '-vvv', '-t', 'install', executable]);
+  } else {
+    console.log('Skipping spctl check (requireGatekeeper=false)');
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const requireGatekeeper = process.env.KIMI_VERIFY_GATEKEEPER === '1';
+  await runVerifyStep({ requireGatekeeper });
+}
diff --git a/apps/kimi-code/scripts/native/assets.mjs b/apps/kimi-code/scripts/native/assets.mjs
new file mode 100644
index 000000000..7b0560b69
--- /dev/null
+++ b/apps/kimi-code/scripts/native/assets.mjs
@@ -0,0 +1,276 @@
+import { createHash } from 'node:crypto';
+import { existsSync, realpathSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { NATIVE_ASSET_MANIFEST_VERSION, buildManifestKey } from './manifest.mjs';
+import { resolveTargetDeps, SUPPORTED_TARGETS } from './native-deps.mjs';
+
+export { NATIVE_ASSET_MANIFEST_VERSION };
+
+// Re-export for any external consumer that still needs it. Internally we
+// use resolveTargetDeps() exclusively — no more if/else against package names.
+export const NATIVE_TARGETS = Object.freeze(
+  Object.fromEntries(
+    SUPPORTED_TARGETS.map((t) => {
+      const deps = resolveTargetDeps(t);
+      const clipboardTarget = deps.find((d) => d.id === 'clipboard-target')?.resolvedName;
+      const koffiNativeFile = deps.find((d) => d.id === 'koffi')?.nativeFileRelatives?.[0];
+      const koffiTriplet = koffiNativeFile?.match(/koffi\/([^/]+)\/koffi\.node$/)?.[1] ?? null;
+      return [t, { clipboardPackage: clipboardTarget, koffiTriplet }];
+    }),
+  ),
+);
+
+const jsExtensions = ['.js', '.cjs', '.mjs', '.json', '.node'];
+const runtimeEntryNames = ['index.js', 'index.cjs', 'index.mjs'];
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function toPosixPath(path) {
+  return path.split('\\').join('/');
+}
+
+function sha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, 'utf-8'));
+}
+
+async function listFiles(root) {
+  const files = [];
+
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(path);
+        continue;
+      }
+      if (entry.isFile()) {
+        files.push(path);
+      }
+    }
+  }
+
+  await walk(root);
+  return files;
+}
+
+function resolvePackageRootGeneric(requireFromApp, packageName, parentPackageName, appRoot, target) {
+  try {
+    return dirname(requireFromApp.resolve(`${packageName}/package.json`));
+  } catch (rootError) {
+    if (parentPackageName !== null) {
+      try {
+        const parentPackageJsonPath = realpathSync(
+          requireFromApp.resolve(`${parentPackageName}/package.json`),
+        );
+        const requireFromParent = createRequire(pathToFileURL(parentPackageJsonPath));
+        return dirname(requireFromParent.resolve(`${packageName}/package.json`));
+      } catch {}
+    }
+    fail(
+      [
+        `Native asset package is not installed for target ${target}: ${packageName}`,
+        parentPackageName ? `Searched via parent: ${parentPackageName}` : '',
+        `Resolve root: ${appRoot}`,
+        'Run pnpm install --frozen-lockfile before building native assets.',
+        rootError instanceof Error ? rootError.message : String(rootError),
+      ]
+        .filter(Boolean)
+        .join('\n'),
+    );
+  }
+}
+
+function resolveFileCandidate(path) {
+  if (existsSync(path)) return path;
+  for (const extension of jsExtensions) {
+    const candidate = `${path}${extension}`;
+    if (existsSync(candidate)) return candidate;
+  }
+  for (const entryName of runtimeEntryNames) {
+    const candidate = join(path, entryName);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function resolvePackageEntry(packageRoot, packageJson) {
+  const rawMain =
+    typeof packageJson.main === 'string'
+      ? packageJson.main
+      : typeof packageJson.module === 'string'
+        ? packageJson.module
+        : 'index.js';
+  return resolveFileCandidate(resolve(packageRoot, rawMain));
+}
+
+function relativeRuntimeSpecifiers(text) {
+  const specifiers = new Set();
+  for (const match of text.matchAll(/\brequire\(\s*["'](\.[^"']+)["']\s*\)/g)) {
+    specifiers.add(match[1]);
+  }
+  for (const match of text.matchAll(/(?<![.\w])import\(\s*["'](\.[^"']+)["']\s*\)/g)) {
+    specifiers.add(match[1]);
+  }
+  for (const match of text.matchAll(/\bfrom\s+["'](\.[^"']+)["']/g)) {
+    specifiers.add(match[1]);
+  }
+  return [...specifiers];
+}
+
+async function addRuntimeDependencyFiles(packageRoot, filePath, selected) {
+  const extension = extname(filePath);
+  if (!['.js', '.cjs', '.mjs'].includes(extension)) return;
+
+  let text;
+  try {
+    text = await readFile(filePath, 'utf-8');
+  } catch {
+    return;
+  }
+
+  for (const specifier of relativeRuntimeSpecifiers(text)) {
+    const candidate = resolveFileCandidate(resolve(dirname(filePath), specifier));
+    if (candidate === null) continue;
+    if (candidate.endsWith('.node')) continue;
+    const packageRelativePath = relative(packageRoot, candidate);
+    if (
+      packageRelativePath.startsWith('..') ||
+      isAbsolute(packageRelativePath) ||
+      packageRelativePath.length === 0
+    ) {
+      continue;
+    }
+    if (selected.has(candidate)) continue;
+    selected.add(candidate);
+    await addRuntimeDependencyFiles(packageRoot, candidate, selected);
+  }
+}
+
+async function collectPackageFiles({
+  packageName,
+  packageRoot,
+  includeNativeFiles,
+  nativeFileRelatives = [],
+}) {
+  const packageJsonPath = join(packageRoot, 'package.json');
+  const packageJson = await readJson(packageJsonPath);
+  const selected = new Set([packageJsonPath]);
+
+  const entry = resolvePackageEntry(packageRoot, packageJson);
+  if (entry !== null) {
+    selected.add(entry);
+    await addRuntimeDependencyFiles(packageRoot, entry, selected);
+  }
+
+  for (const nativeFileRelative of nativeFileRelatives) {
+    const nativeFile = resolve(packageRoot, nativeFileRelative);
+    if (!existsSync(nativeFile)) {
+      fail(`Native package ${packageName} does not contain ${nativeFileRelative} at ${packageRoot}`);
+    }
+    selected.add(nativeFile);
+  }
+
+  if (includeNativeFiles) {
+    const files = await listFiles(packageRoot);
+    for (const file of files) {
+      if (file.endsWith('.node')) {
+        selected.add(file);
+      }
+    }
+  }
+
+  const sorted = [...selected].sort((a, b) => a.localeCompare(b));
+  if (includeNativeFiles && !sorted.some((file) => file.endsWith('.node'))) {
+    fail(`Native package ${packageName} does not contain a .node file at ${packageRoot}`);
+  }
+  return sorted;
+}
+
+async function packageManifestEntries({ packageName, packageRoot, files, target }) {
+  const root = `node_modules/${packageName}`;
+  const entries = [];
+  const assets = {};
+
+  for (const file of files) {
+    const sourceBytes = await readFile(file);
+    const packageRelativePath = toPosixPath(relative(packageRoot, file));
+    const relativePath = `${root}/${packageRelativePath}`;
+    const assetKey = `native/${target}/${relativePath}`;
+    entries.push({
+      assetKey,
+      relativePath,
+      sha256: sha256(sourceBytes),
+    });
+    assets[assetKey] = file;
+  }
+
+  return {
+    packageManifest: {
+      name: packageName,
+      root,
+      files: entries,
+    },
+    assets,
+  };
+}
+
+export const nativeAssetManifestKey = buildManifestKey;
+
+export function nativeAssetSummary(manifest) {
+  return manifest.packages.map((pkg) => `${pkg.name}: ${pkg.files.length} files`);
+}
+
+export async function collectNativeAssets({ appRoot, target }) {
+  const requireFromApp = createRequire(pathToFileURL(resolve(appRoot, 'package.json')));
+  const targetDeps = resolveTargetDeps(target); // throws on unsupported target
+
+  const manifestPackages = [];
+  const assets = {};
+
+  for (const dep of targetDeps) {
+    const packageRoot = resolvePackageRootGeneric(
+      requireFromApp,
+      dep.resolvedName,
+      dep.parentName,
+      appRoot,
+      target,
+    );
+    const files = await collectPackageFiles({
+      packageName: dep.resolvedName,
+      packageRoot,
+      includeNativeFiles: dep.collect === 'native-files',
+      nativeFileRelatives: dep.nativeFileRelatives,
+    });
+    const result = await packageManifestEntries({
+      packageName: dep.resolvedName,
+      packageRoot,
+      files,
+      target,
+    });
+    manifestPackages.push(result.packageManifest);
+    Object.assign(assets, result.assets);
+  }
+
+  const manifest = {
+    version: NATIVE_ASSET_MANIFEST_VERSION,
+    target,
+    packages: manifestPackages,
+  };
+
+  return {
+    manifest,
+    manifestJson: `${JSON.stringify(manifest, null, 2)}\n`,
+    assets,
+  };
+}
diff --git a/apps/kimi-code/scripts/native/build.mjs b/apps/kimi-code/scripts/native/build.mjs
new file mode 100644
index 000000000..ec51d2368
--- /dev/null
+++ b/apps/kimi-code/scripts/native/build.mjs
@@ -0,0 +1,47 @@
+import { parseArgs } from 'node:util';
+
+import { runBundleStep } from './01-bundle.mjs';
+import { runInjectStep } from './03-inject.mjs';
+import { runSeaBlobStep } from './02-sea-blob.mjs';
+import { runSignStep } from './04-sign.mjs';
+import { runVerifyStep } from './05-verify.mjs';
+
+const { values } = parseArgs({
+  options: {
+    profile: { type: 'string', default: 'local' },
+  },
+});
+
+const profile = values.profile;
+if (!['local', 'release'].includes(profile)) {
+  console.error(`Unknown profile: ${profile}. Expected 'local' or 'release'.`);
+  process.exit(1);
+}
+
+function ensureNodeVersion() {
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  if (major < 24 || (major === 24 && minor < 15)) {
+    console.error(
+      `Kimi Code native SEA build requires Node.js >=24.15.0, current ${process.versions.node}.`,
+    );
+    process.exit(1);
+  }
+}
+
+ensureNodeVersion();
+console.log(`==> Native build (profile=${profile})`);
+
+await runBundleStep();
+await runSeaBlobStep();
+await runInjectStep();
+
+const identity =
+  profile === 'release' ? (process.env.APPLE_SIGNING_IDENTITY ?? '-') : '-';
+const keychainPath = profile === 'release' ? (process.env.APPLE_KEYCHAIN_PATH ?? null) : null;
+await runSignStep({ identity, keychainPath });
+
+// Verify always runs (codesign -dv); spctl gatekeeper gate only after notarization
+// (CI macos-notarize composite action) — orchestrator just self-checks signing here.
+await runVerifyStep({ requireGatekeeper: false });
+
+console.log('==> Native build complete');
diff --git a/apps/kimi-code/scripts/native/check-bundle.mjs b/apps/kimi-code/scripts/native/check-bundle.mjs
new file mode 100644
index 000000000..a0479f209
--- /dev/null
+++ b/apps/kimi-code/scripts/native/check-bundle.mjs
@@ -0,0 +1,90 @@
+import { builtinModules } from 'node:module';
+import { readFileSync } from 'node:fs';
+
+import { nativeJsBundlePath } from './paths.mjs';
+
+const bundlePath = nativeJsBundlePath();
+const text = readFileSync(bundlePath, 'utf-8');
+
+const builtins = new Set([
+  ...builtinModules,
+  ...builtinModules.map((name) => `node:${name}`),
+]);
+
+const optionalRuntimeRequires = new Set([
+  'ajv-formats/dist/formats',
+  'ajv/dist/runtime/validation_error',
+  'bufferutil',
+  'canvas',
+  'chokidar',
+  'cpu-features',
+  'utf-8-validate',
+]);
+const optionalRelativeRuntimeRequires = new Set(['./crypto/build/Release/sshcrypto.node']);
+const handledNativeRuntimeRequires = new Set(['koffi']);
+
+function isAllowedSpecifier(specifier) {
+  if (builtins.has(specifier) || specifier.startsWith('node:')) return true;
+  if (optionalRuntimeRequires.has(specifier)) return true;
+  if (handledNativeRuntimeRequires.has(specifier)) return true;
+  return false;
+}
+
+const errors = [];
+
+function executableLines() {
+  return text
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => {
+      if (line.length === 0) return false;
+      if (line.startsWith('*') || line.startsWith('//') || line.startsWith('/*')) return false;
+      return true;
+    });
+}
+
+for (const line of executableLines()) {
+  for (const match of line.matchAll(/\brequire\(\s*["']([^"']+)["']\s*\)/g)) {
+    const specifier = match[1];
+    if (specifier.startsWith('.') || specifier.startsWith('/')) {
+      if (optionalRelativeRuntimeRequires.has(specifier)) continue;
+      errors.push(`relative require remains: ${specifier}`);
+      continue;
+    }
+    if (!isAllowedSpecifier(specifier)) {
+      errors.push(`external require remains: ${specifier}`);
+    }
+  }
+
+  for (const match of line.matchAll(/(?<![.\w])import\(\s*["']([^"']+)["']\s*\)/g)) {
+    const specifier = match[1];
+    if (specifier.startsWith('.') || specifier.startsWith('/')) {
+      errors.push(`relative dynamic import remains: ${specifier}`);
+      continue;
+    }
+    if (!isAllowedSpecifier(specifier)) {
+      errors.push(`external dynamic import remains: ${specifier}`);
+    }
+  }
+
+  if (line.startsWith('import ')) {
+    for (const match of line.matchAll(/\bfrom\s+["']([^"']+)["']/g)) {
+      const specifier = match[1];
+      if (specifier.startsWith('.') || specifier.startsWith('/')) {
+        errors.push(`relative import remains: ${specifier}`);
+        continue;
+      }
+      if (!isAllowedSpecifier(specifier)) {
+        errors.push(`external import remains: ${specifier}`);
+      }
+    }
+  }
+}
+
+if (errors.length > 0) {
+  console.error(`Native JS bundle check failed for ${bundlePath}:`);
+  for (const error of errors) {
+    console.error(`- ${error}`);
+  }
+  process.exit(1);
+}
diff --git a/apps/kimi-code/scripts/native/entitlements.plist b/apps/kimi-code/scripts/native/entitlements.plist
new file mode 100644
index 000000000..d7e0e9d6b
--- /dev/null
+++ b/apps/kimi-code/scripts/native/entitlements.plist
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <!-- Node V8 needs JIT pages -->
+  <key>com.apple.security.cs.allow-jit</key>
+  <true/>
+
+  <!-- V8 writes to executable memory during codegen -->
+  <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+  <true/>
+
+  <!-- We dlopen koffi.node / clipboard.node at runtime; they're built by
+       third parties and aren't signed by our Team. Without this they'd be
+       rejected by hardened runtime. -->
+  <key>com.apple.security.cs.disable-library-validation</key>
+  <true/>
+
+  <!-- Some users set NODE_OPTIONS / DYLD_* envs; allow them. -->
+  <key>com.apple.security.cs.allow-dyld-environment-variables</key>
+  <true/>
+</dict>
+</plist>
diff --git a/apps/kimi-code/scripts/native/exec.mjs b/apps/kimi-code/scripts/native/exec.mjs
new file mode 100644
index 000000000..03ebe5b0c
--- /dev/null
+++ b/apps/kimi-code/scripts/native/exec.mjs
@@ -0,0 +1,61 @@
+import { execFile } from 'node:child_process';
+import { basename } from 'node:path';
+import { promisify } from 'node:util';
+
+import { appRoot } from './paths.mjs';
+
+const execFileAsync = promisify(execFile);
+
+export function commandForExecFile(command, args, platform = process.platform, env = process.env) {
+  if (platform !== 'win32' || !/\.(?:bat|cmd)$/i.test(command)) {
+    return { command, args };
+  }
+  const shellCommand = [command, ...args]
+    .map((arg) => `"${String(arg).replaceAll('"', '""')}"`)
+    .join(' ');
+  return {
+    command: env.ComSpec ?? 'cmd.exe',
+    args: ['/d', '/s', '/c', `"${shellCommand}"`],
+    options: { windowsVerbatimArguments: true },
+  };
+}
+
+export function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+export async function run(command, args, options = {}) {
+  const exec = commandForExecFile(command, args);
+  try {
+    const { stdout, stderr } = await execFileAsync(exec.command, exec.args, {
+      cwd: appRoot,
+      maxBuffer: 1024 * 1024 * 16,
+      ...exec.options,
+      ...options,
+    });
+    if (stdout.trim()) console.log(stdout.trim());
+    if (stderr.trim()) console.error(stderr.trim());
+  } catch (error) {
+    const details = [error.stdout?.trim(), error.stderr?.trim(), error.message]
+      .filter(Boolean)
+      .join('\n');
+    fail(`Command failed: ${basename(command)} ${args.join(' ')}\n${details}`);
+  }
+}
+
+export async function tryRun(command, args, options = {}) {
+  const exec = commandForExecFile(command, args);
+  try {
+    await execFileAsync(exec.command, exec.args, {
+      cwd: appRoot,
+      maxBuffer: 1024 * 1024 * 16,
+      ...exec.options,
+    });
+  } catch (error) {
+    const details = [error.stdout?.trim(), error.stderr?.trim(), error.message]
+      .filter(Boolean)
+      .join('\n');
+    console.warn(`Warning: ${basename(command)} ${args.join(' ')} failed.\n${details}`);
+  }
+}
diff --git a/apps/kimi-code/scripts/native/manifest.mjs b/apps/kimi-code/scripts/native/manifest.mjs
new file mode 100644
index 000000000..910738943
--- /dev/null
+++ b/apps/kimi-code/scripts/native/manifest.mjs
@@ -0,0 +1,13 @@
+export const NATIVE_ASSET_MANIFEST_VERSION = 1;
+
+export function buildManifestKey(target) {
+  return `native/${target}/manifest.json`;
+}
+
+export function isManifestVersionSupported(version) {
+  return version === NATIVE_ASSET_MANIFEST_VERSION;
+}
+
+export function buildAssetKey(target, packageRoot, relativePath) {
+  return `native/${target}/${packageRoot}/${relativePath}`;
+}
diff --git a/apps/kimi-code/scripts/native/native-deps.mjs b/apps/kimi-code/scripts/native/native-deps.mjs
new file mode 100644
index 000000000..f195a3cb1
--- /dev/null
+++ b/apps/kimi-code/scripts/native/native-deps.mjs
@@ -0,0 +1,103 @@
+/**
+ * Native dependency registry.
+ *
+ * Each entry describes one native-bearing npm package: how to resolve its
+ * install root, what to collect (JS only / native binary only / both), and
+ * which other registered dep it nests under (for `pnpm`-style nested resolves).
+ *
+ * Adding a new native package = appending one object here. No edits to
+ * NATIVE_TARGETS table or resolvePackageRoot if/else chain.
+ */
+
+export const SUPPORTED_TARGETS = Object.freeze([
+  'darwin-arm64',
+  'darwin-x64',
+  'linux-arm64',
+  'linux-x64',
+  'win32-arm64',
+  'win32-x64',
+]);
+
+const clipboardSubpackageByTarget = Object.freeze({
+  'darwin-arm64': '@mariozechner/clipboard-darwin-arm64',
+  'darwin-x64': '@mariozechner/clipboard-darwin-x64',
+  'linux-arm64': '@mariozechner/clipboard-linux-arm64-gnu',
+  'linux-x64': '@mariozechner/clipboard-linux-x64-gnu',
+  'win32-arm64': '@mariozechner/clipboard-win32-arm64-msvc',
+  'win32-x64': '@mariozechner/clipboard-win32-x64-msvc',
+});
+
+const koffiTripletByTarget = Object.freeze({
+  'darwin-arm64': 'darwin_arm64',
+  'darwin-x64': 'darwin_x64',
+  'linux-arm64': 'linux_arm64',
+  'linux-x64': 'linux_x64',
+  'win32-arm64': 'win32_arm64',
+  'win32-x64': 'win32_x64',
+});
+
+export function isSupportedTarget(target) {
+  return SUPPORTED_TARGETS.includes(target);
+}
+
+/**
+ * @typedef {Object} NativeDepDescriptor
+ * @property {string} id                — stable internal id used for parent refs
+ * @property {(target: string) => string} name
+ *           — npm package name (may depend on target)
+ * @property {'js-only'|'native-files'|'js-and-native-file'|'virtual'} collect
+ * @property {string|null} parent
+ *           — id of another registered dep this nests under (for pnpm),
+ *           or null for top-level (resolvable from app root)
+ * @property {(target: string) => string[]} [nativeFileRelatives]
+ *           — explicit list of .node files relative to package root
+ *           (used by 'js-and-native-file'; native-files mode auto-scans *.node)
+ */
+
+/** @type {readonly NativeDepDescriptor[]} */
+export const nativeDeps = Object.freeze([
+  {
+    id: 'clipboard-host',
+    name: () => '@mariozechner/clipboard',
+    collect: 'js-only',
+    parent: null,
+  },
+  {
+    id: 'clipboard-target',
+    name: (target) => clipboardSubpackageByTarget[target],
+    collect: 'native-files',
+    parent: 'clipboard-host',
+  },
+  {
+    id: 'pi-tui',
+    name: () => '@earendil-works/pi-tui',
+    // pi-tui is bundled into main.cjs at build time — we don't collect it as
+    // a native dep, only register it so koffi can declare it as parent.
+    collect: 'virtual',
+    parent: null,
+  },
+  {
+    id: 'koffi',
+    name: () => 'koffi',
+    collect: 'js-and-native-file',
+    parent: 'pi-tui',
+    nativeFileRelatives: (target) => [`build/koffi/${koffiTripletByTarget[target]}/koffi.node`],
+  },
+]);
+
+/**
+ * Resolve which deps need collecting for a given build target, with concrete names.
+ */
+export function resolveTargetDeps(target) {
+  if (!isSupportedTarget(target)) {
+    throw new Error(`Unsupported native asset target: ${target}`);
+  }
+  return nativeDeps
+    .filter((d) => d.collect !== 'virtual')
+    .map((d) => ({
+      ...d,
+      resolvedName: d.name(target),
+      nativeFileRelatives: d.nativeFileRelatives?.(target) ?? [],
+      parentName: d.parent ? nativeDeps.find((p) => p.id === d.parent)?.name(target) ?? null : null,
+    }));
+}
diff --git a/apps/kimi-code/scripts/native/package.mjs b/apps/kimi-code/scripts/native/package.mjs
new file mode 100644
index 000000000..e146af0ab
--- /dev/null
+++ b/apps/kimi-code/scripts/native/package.mjs
@@ -0,0 +1,53 @@
+import { createHash } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+
+import { ZipFile } from 'yazl';
+
+import { executableName, nativeArtifactsDir, nativeBinPath, targetTriple } from './paths.mjs';
+
+const target = targetTriple();
+const execName = executableName();
+const sourceBinary = nativeBinPath(target);
+const artifactsDir = nativeArtifactsDir();
+
+// Flat-name archive for GH Release (GitHub Release assets do not support subdirectories).
+const artifactName = `kimi-code-${target}.zip`;
+const artifactPath = resolve(artifactsDir, artifactName);
+const checksumPath = `${artifactPath}.sha256`;
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+async function sha256(path) {
+  return await new Promise((resolveHash, reject) => {
+    const hash = createHash('sha256');
+    const stream = createReadStream(path);
+    stream.on('error', reject);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => resolveHash(hash.digest('hex')));
+  });
+}
+
+try {
+  await stat(sourceBinary);
+} catch {
+  fail(`Native executable not found at ${sourceBinary}. Run build:native:sea first.`);
+}
+
+await mkdir(artifactsDir, { recursive: true });
+
+const zip = new ZipFile();
+zip.addFile(sourceBinary, execName, { mode: 0o100755 });
+zip.end();
+await pipeline(zip.outputStream, createWriteStream(artifactPath));
+
+const digest = await sha256(artifactPath);
+await writeFile(checksumPath, `${digest}  ${basename(artifactPath)}\n`);
+
+console.log(`Wrote native artifact: ${artifactPath}`);
+console.log(`Wrote artifact checksum: ${checksumPath}`);
diff --git a/apps/kimi-code/scripts/native/paths.mjs b/apps/kimi-code/scripts/native/paths.mjs
new file mode 100644
index 000000000..ca0462072
--- /dev/null
+++ b/apps/kimi-code/scripts/native/paths.mjs
@@ -0,0 +1,57 @@
+import { resolve } from 'node:path';
+
+export const appRoot = resolve(import.meta.dirname, '..', '..');
+
+export function targetTriple({ platform = process.platform, arch = process.arch, env = process.env } = {}) {
+  return env.KIMI_CODE_BUILD_TARGET ?? `${platform}-${arch}`;
+}
+
+export function executableName(platform = process.platform) {
+  return platform === 'win32' ? 'kimi.exe' : 'kimi';
+}
+
+export function nativeDistRoot() {
+  return resolve(appRoot, 'dist-native');
+}
+
+export function nativeIntermediatesDir() {
+  return resolve(nativeDistRoot(), 'intermediates');
+}
+
+export function nativeBinDir(target = targetTriple()) {
+  return resolve(nativeDistRoot(), 'bin', target);
+}
+
+export function nativeBinPath(target = targetTriple(), platform = process.platform) {
+  return resolve(nativeBinDir(target), executableName(platform));
+}
+
+export function nativeJsBundlePath() {
+  return resolve(nativeIntermediatesDir(), 'main.cjs');
+}
+
+export function nativeBlobPath() {
+  return resolve(nativeIntermediatesDir(), 'kimi.blob');
+}
+
+export function nativeSeaConfigPath() {
+  return resolve(nativeIntermediatesDir(), 'sea-config.json');
+}
+
+export function nativeManifestDir(target = targetTriple()) {
+  return resolve(nativeIntermediatesDir(), 'native-assets', target);
+}
+
+export function nativeArtifactsDir() {
+  return resolve(nativeDistRoot(), 'artifacts');
+}
+
+export function nativeSmokeHome() {
+  return resolve(nativeDistRoot(), 'smoke-home');
+}
+
+export function nativeManifestKey(target = targetTriple()) {
+  return `native/${target}/manifest.json`;
+}
+
+export const SEA_SENTINEL_FUSE = 'NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2';
diff --git a/apps/kimi-code/scripts/native/produce-manifest.mjs b/apps/kimi-code/scripts/native/produce-manifest.mjs
new file mode 100644
index 000000000..7718f64b1
--- /dev/null
+++ b/apps/kimi-code/scripts/native/produce-manifest.mjs
@@ -0,0 +1,55 @@
+/**
+ * Aggregate per-platform zip archive `.sha256` files into a single
+ * `manifest.json` written into the same input directory.
+ *
+ * Usage:
+ *   node produce-manifest.mjs <input-dir> <release-tag>
+ *
+ * Input dir must contain files matching: kimi-code-<target>.zip.sha256
+ * (produced by package.mjs across the 6 native-build matrix runners).
+ *
+ * Output:
+ *   <input-dir>/manifest.json   ← consumed by install.sh / install.ps1
+ *
+ */
+
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+
+const [, , inputDir, tag] = process.argv;
+if (!inputDir || !tag) {
+  console.error('Usage: produce-manifest.mjs <input-dir> <release-tag>');
+  process.exit(1);
+}
+
+// Tag 格式 `@moonshot-ai/kimi-code@x.y.z` 或 `vx.y.z` 或 `x.y.z`，都归一化到 x.y.z
+const version = tag.replace(/^@moonshot-ai\/kimi-code@/, '').replace(/^v/, '');
+
+const entries = await readdir(inputDir);
+const sumFiles = entries.filter((f) => /^kimi-code-[a-z0-9-]+\.zip\.sha256$/.test(f));
+
+if (sumFiles.length === 0) {
+  console.error(`No kimi-code-<target>.zip.sha256 files found in ${inputDir}`);
+  process.exit(1);
+}
+
+const platforms = {};
+for (const sumFile of sumFiles.sort()) {
+  const text = await readFile(resolve(inputDir, sumFile), 'utf-8');
+  const [checksum] = text.trim().split(/\s+/, 1);
+  if (!checksum || !/^[a-f0-9]{64}$/.test(checksum)) {
+    console.error(`Invalid checksum in ${sumFile}: ${checksum}`);
+    process.exit(1);
+  }
+  const filename = basename(sumFile, '.sha256');
+  // kimi-code-darwin-arm64.zip → darwin-arm64
+  const target = filename.replace(/^kimi-code-/, '').replace(/\.zip$/, '');
+  platforms[target] = { filename, checksum };
+}
+
+const manifest = { version, tag, platforms };
+const manifestPath = resolve(inputDir, 'manifest.json');
+
+await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+console.log(`Wrote ${manifestPath} (${Object.keys(platforms).length} platforms)`);
diff --git a/apps/kimi-code/scripts/native/resolve-release.mjs b/apps/kimi-code/scripts/native/resolve-release.mjs
new file mode 100644
index 000000000..10b4f9724
--- /dev/null
+++ b/apps/kimi-code/scripts/native/resolve-release.mjs
@@ -0,0 +1,55 @@
+import { appendFile, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { appRoot } from './paths.mjs';
+
+const packageName = '@moonshot-ai/kimi-code';
+const packageJson = JSON.parse(
+  await readFile(resolve(appRoot, 'package.json'), 'utf-8'),
+);
+
+function parsePublishedPackages() {
+  const raw = process.env['CHANGESETS_PUBLISHED_PACKAGES'];
+  if (raw === undefined || raw.trim().length === 0) {
+    return [];
+  }
+
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function outputLine(name, value) {
+  return `${name}=${value}\n`;
+}
+
+const publishedPackage = parsePublishedPackages().find(
+  (entry) =>
+    typeof entry === 'object' &&
+    entry !== null &&
+    entry.name === packageName &&
+    typeof entry.version === 'string',
+);
+
+const version = publishedPackage?.version ?? packageJson.version;
+const shouldPublish = publishedPackage !== undefined;
+const tag = `${packageName}@${version}`;
+const githubOutput = process.env['GITHUB_OUTPUT'];
+
+if (githubOutput !== undefined) {
+  await appendFile(
+    githubOutput,
+    [
+      outputLine('should_publish', String(shouldPublish)),
+      outputLine('version', version),
+      outputLine('tag', tag),
+    ].join(''),
+  );
+}
+
+console.log(`should_publish=${String(shouldPublish)}`);
+console.log(`version=${version}`);
+console.log(`tag=${tag}`);
diff --git a/apps/kimi-code/scripts/native/smoke.mjs b/apps/kimi-code/scripts/native/smoke.mjs
new file mode 100644
index 000000000..ed3a8624f
--- /dev/null
+++ b/apps/kimi-code/scripts/native/smoke.mjs
@@ -0,0 +1,82 @@
+import { execFile } from 'node:child_process';
+import { readFile, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+import { appRoot, nativeBinPath, nativeSmokeHome, targetTriple } from './paths.mjs';
+
+const execFileAsync = promisify(execFile);
+const target = targetTriple();
+const executablePath = nativeBinPath(target);
+const smokeHome = nativeSmokeHome();
+const packageJson = JSON.parse(await readFile(resolve(appRoot, 'package.json'), 'utf-8'));
+const expectedVersion = packageJson.version;
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+async function ensureExecutableExists() {
+  try {
+    await stat(executablePath);
+  } catch {
+    fail(`Native executable not found at ${executablePath}. Run build:native:sea first.`);
+  }
+}
+
+async function runKimi(args) {
+  try {
+    const { stdout, stderr } = await execFileAsync(executablePath, args, {
+      cwd: appRoot,
+      maxBuffer: 1024 * 1024 * 16,
+    });
+    return `${stdout}${stderr}`;
+  } catch (error) {
+    const detail = [error.stdout?.trim(), error.stderr?.trim(), error.message]
+      .filter(Boolean)
+      .join('\n');
+    fail(`Native smoke failed: ${executablePath} ${args.join(' ')}\n${detail}`);
+  }
+}
+
+async function runKimiWithEnv(args, env) {
+  try {
+    const { stdout, stderr } = await execFileAsync(executablePath, args, {
+      cwd: appRoot,
+      env: { ...process.env, ...env },
+      maxBuffer: 1024 * 1024 * 16,
+    });
+    return `${stdout}${stderr}`;
+  } catch (error) {
+    const detail = [error.stdout?.trim(), error.stderr?.trim(), error.message]
+      .filter(Boolean)
+      .join('\n');
+    fail(`Native smoke failed: ${executablePath} ${args.join(' ')}\n${detail}`);
+  }
+}
+
+function assertIncludes(output, expected, command) {
+  if (!output.includes(expected)) {
+    fail(`Native smoke output for "${command}" did not include "${expected}".\n${output}`);
+  }
+}
+
+await ensureExecutableExists();
+
+const versionOutput = await runKimi(['--version']);
+assertIncludes(versionOutput, expectedVersion, '--version');
+
+const helpOutput = await runKimi(['--help']);
+assertIncludes(helpOutput, 'Usage: kimi', '--help');
+
+const exportHelpOutput = await runKimi(['export', '--help']);
+assertIncludes(exportHelpOutput, 'Usage: kimi export', 'export --help');
+
+const nativeAssetOutput = await runKimiWithEnv(['--version'], {
+  KIMI_CODE_HOME: smokeHome,
+  KIMI_CODE_NATIVE_ASSET_SMOKE: '1',
+});
+assertIncludes(nativeAssetOutput, `Native asset smoke passed: ${target}`, 'native asset smoke');
+
+console.log(`Native smoke passed: ${executablePath}`);
diff --git a/apps/kimi-code/scripts/postinstall.mjs b/apps/kimi-code/scripts/postinstall.mjs
new file mode 100644
index 000000000..4662c43cf
--- /dev/null
+++ b/apps/kimi-code/scripts/postinstall.mjs
@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+/**
+ * Postinstall hook for @moonshot-ai/kimi-code.
+ *
+ * Goal: when this package is installed globally, ensure typing `kimi`
+ * invokes the new TypeScript CLI. The npm `package.json` bin field
+ * installs a fresh `kimi` shim into the global bin dir; this script
+ * removes any pre-existing `kimi` shim left behind by the previous
+ * Python CLI (installed via `uv tool install`, `pipx install`,
+ * `pip install`, etc.) that would otherwise shadow ours via PATH
+ * ordering. The renamed shim is kept as `kimi-legacy` so users can
+ * still invoke the old CLI if they want to fall back.
+ *
+ * ## Hard rules
+ *
+ *   - Only runs for global installs across npm, yarn (classic), and
+ *     pnpm. Non-global installs (npx, local project deps, workspace
+ *     bootstraps, `pnpm dlx`) are silent no-ops.
+ *   - Never fails the install. Any error here is caught and reported,
+ *     but the script always exits 0.
+ *   - Does not touch a `kimi` we don't recognize as the previous
+ *     Python CLI (matched by realpath-resolved shim head containing
+ *     `kimi_cli`).
+ *   - Cross-platform: POSIX and Windows. Windows-specific bits live
+ *     in the helpers (PATHEXT-aware PATH walking, whole-file marker
+ *     sniff for uv's Rust launcher .exe, extension-preserving
+ *     rename target like `kimi.exe` → `kimi-legacy.exe`).
+ *
+ * ## Code layout
+ *
+ * This file is the orchestrator; the actual logic lives in
+ * sibling modules to keep each file under a manageable size:
+ *
+ *   - `./postinstall/reach.mjs` — package-manager detection,
+ *     global-install gate, own-package-root resolution, user-shell
+ *     PATH lookup, reachability check.
+ *   - `./postinstall/migrate.mjs` — legacy detection,
+ *     `kimi`-vs-`kimi-legacy` classification, the rename / unlink
+ *     primitives.
+ *   - `./postinstall/ui.mjs` — `notify()` (with `/dev/tty` fallback),
+ *     ANSI styling, the fixed-width box, and the five outcome
+ *     renderers.
+ *
+ * ## Workflow
+ *
+ * What runs when a user types `npm install -g @moonshot-ai/kimi-code`
+ * (or the yarn / pnpm equivalent):
+ *
+ *   1. The manager extracts the package and runs lifecycle scripts.
+ *      The `bin.kimi` mapping in `package.json` tells the manager to
+ *      install a `kimi` shim under its global bin directory.
+ *   2. The manager invokes this script via the `scripts.postinstall`
+ *      entry — orchestrated by `main` below.
+ *   3. Install-context gate: only proceed when this is a global
+ *      install (`isGlobalInstall` checks `npm_config_global` /
+ *      `pnpm_config_global` / `npm_config_location`).
+ *   4. Probe PATH once via `postinstallPaths()`: detection uses the
+ *      union of shell PATH + process PATH; reachability uses the
+ *      shell PATH alone (with a fallback to process PATH if the
+ *      shell can't be probed). Sharing one probe keeps detection
+ *      and reachability symmetric and avoids running `$SHELL -l`
+ *      twice.
+ *   5. Detect EVERY previous Python `kimi-cli` shim on the detection
+ *      PATH (`detectLegacyShims`). Returns `[]` for fresh-install /
+ *      no-op. Multiple results happen when the user has installed
+ *      `kimi-cli` through more than one Python tool (uv + pipx, or
+ *      sudo-pip + pip-user). PATH order is preserved.
+ *   6. Pre-flight classify each shim (`classifyShim`) — pure
+ *      filesystem inspection, no writes. Each shim ends up
+ *      `renameable`, `consolidate`, `delete-only`, or `blocked`.
+ *   7. Decide abort vs proceed against the WHOLE set:
+ *      `findFirstResolvableKimi` walks PATH treating the actionable
+ *      shims as gone and reports what wins:
+ *        - `own` → proceed to execute.
+ *        - `blocked-legacy` → a legacy we can't remove still wins.
+ *          Surface `logMigrationBlocked` with sudo / admin
+ *          instructions; touch nothing.
+ *        - `foreign` → some `kimi` we don't recognize (a user's own
+ *          file) wins. Surface `logForeignKimiInTheWay` asking the
+ *          user to delete or rename their own file; touch nothing.
+ *        - `none` → no `kimi` on PATH at all (our shim's bin dir
+ *          isn't in the shell's PATH). Surface
+ *          `logNewCliNotOnPath`; touch nothing.
+ *   8. Execute. The FIRST classification in PATH order that we can
+ *      touch becomes `kimi-legacy` (preserves what `kimi` referred
+ *      to before this install). Each subsequent shim is `unlink`ed —
+ *      keeping it as a dormant duplicate adds no value. If the
+ *      first shim's `kimi-legacy` target is already user-managed,
+ *      we delete `kimi` anyway (still achieves takeover) and tell
+ *      the user we couldn't preserve a fallback. Extension is
+ *      preserved on Windows (`kimi.exe` → `kimi-legacy.exe`).
+ *   9. One end-of-orchestration notice (`logMigrationDone`)
+ *      summarizes every action — renames, consolidates,
+ *      delete-only, deletes, and harmless blocked leftovers. The
+ *      takeover-success line only fires on this path because Step 7
+ *      already certified it.
+ *  10. The manager completes the install with its usual summary.
+ *      This script always exits 0; any uncaught error is swallowed
+ *      by the top-level `catch` so the install never fails because
+ *      of the migration.
+ */
+
+import {
+  detectPackageManager,
+  findFirstResolvableKimi,
+  isGlobalInstall,
+  ownPackageRoot,
+  postinstallPaths,
+} from './postinstall/reach.mjs';
+import {
+  classifyShim,
+  deleteShim,
+  detectLegacyShims,
+  renameInPlace,
+} from './postinstall/migrate.mjs';
+import {
+  logForeignKimiInTheWay,
+  logMigrationBlocked,
+  logMigrationDone,
+  logNewCliNotOnPath,
+  notify,
+} from './postinstall/ui.mjs';
+
+async function main() {
+  // Step 1: skip non-global installs (npx, local project deps,
+  // workspace bootstraps). Windows is supported natively; the
+  // platform-specific bits (PATHEXT-aware PATH walk, whole-file
+  // marker sniff for uv's launcher .exe, extension-preserving
+  // rename) live in the helpers.
+  if (!isGlobalInstall()) return;
+
+  // Step 2: locate our own installed package root once and share it
+  // with both detection (skip files inside our package) and
+  // reachability (only count our shim as "found").
+  const ownRoot = await ownPackageRoot(import.meta.dirname);
+  const pm = detectPackageManager();
+
+  // Step 3: probe the user's shell PATH once so detection and
+  // reachability share a single consistent view. Detection uses the
+  // union of shell PATH + process PATH (so we catch a legacy shim
+  // visible to either); reachability uses the shell PATH alone (so
+  // we don't claim "kimi works now" when the shim only sits in the
+  // installer's env).
+  const paths = await postinstallPaths();
+
+  // Step 4: detect EVERY previous Python `kimi-cli` shim on the
+  // detection PATH. A user with both `uv tool install` and `pipx
+  // install` would have two; we must address all of them or the
+  // survivor still shadows the new CLI.
+  const detections = await detectLegacyShims(ownRoot, paths.detection);
+  if (detections.length === 0) return;
+
+  // Step 5: pre-flight classify every shim WITHOUT touching the
+  // filesystem yet. The orchestrator decides abort-or-proceed against
+  // the whole set rather than discovering mid-loop that we got partway
+  // and have to backtrack.
+  const classifications = await Promise.all(
+    detections.map(async (detection) => {
+      const c = await classifyShim(detection.shimPath);
+      return { ...c, detection };
+    }),
+  );
+
+  // Step 6: figure out what wins PATH resolution once every shim we
+  // CAN touch is treated as gone. Three possible blockers:
+  //   - a legacy shim we couldn't classify as actionable (sudo/admin
+  //     needed)
+  //   - an unrelated `kimi` we don't recognize (a user's own wrapper
+  //     script — they own the decision)
+  //   - nothing resolves (our shim isn't on PATH at all)
+  // For each we render a different notice and touch NOTHING. The
+  // common-case fourth result is "our shim wins" — we proceed.
+  const actionable = classifications.filter((c) => c.kind !== 'blocked');
+  const blocked = classifications.filter((c) => c.kind === 'blocked');
+  const actionableShimPaths = actionable.map((c) => c.shimPath);
+  const allDetectedShimPaths = classifications.map((c) => c.shimPath);
+
+  const blocker = await findFirstResolvableKimi(
+    ownRoot,
+    paths.reachability,
+    actionableShimPaths,
+    allDetectedShimPaths,
+  );
+  if (blocker.kind !== 'own') {
+    if (blocker.kind === 'blocked-legacy') {
+      logMigrationBlocked(blocked, actionable, pm);
+    } else if (blocker.kind === 'foreign') {
+      logForeignKimiInTheWay(blocker.path, pm);
+    } else {
+      // 'none' — our shim isn't on PATH at all.
+      logNewCliNotOnPath(detections[0], pm);
+    }
+    return;
+  }
+
+  // Step 7: execute. The FIRST classification in PATH order that
+  // we can touch becomes `kimi-legacy` (preserves what the user's
+  // `kimi` used to refer to). Every subsequent shim is just
+  // deleted — keeping it as a dormant duplicate adds no value.
+  const renames = [];
+  const consolidates = [];
+  const skippedForeignTarget = [];
+  const deletes = [];
+  const errors = [];
+  let preservedFirst = false;
+
+  for (const c of classifications) {
+    if (c.kind === 'blocked') continue; // already established harmless
+
+    if (!preservedFirst) {
+      preservedFirst = true;
+      if (c.kind === 'renameable') {
+        const r = await renameInPlace(c.shimPath, c.target);
+        if (r.success) {
+          renames.push(c);
+        } else {
+          errors.push({ ...c, ...r });
+        }
+        continue;
+      }
+      if (c.kind === 'consolidate') {
+        const r = await deleteShim(c.shimPath);
+        if (r.success) {
+          consolidates.push(c);
+        } else {
+          errors.push({ ...c, ...r });
+        }
+        continue;
+      }
+      if (c.kind === 'delete-only') {
+        const r = await deleteShim(c.shimPath);
+        if (r.success) {
+          skippedForeignTarget.push(c);
+        } else {
+          errors.push({ ...c, ...r });
+        }
+        continue;
+      }
+    } else {
+      // Not the first actionable shim. Just delete it.
+      const r = await deleteShim(c.shimPath);
+      if (r.success) {
+        deletes.push(c);
+      } else {
+        errors.push({ ...c, ...r });
+      }
+    }
+  }
+
+  // Step 8: one notice summarizing everything that happened. The
+  // takeover-success language is only emitted when we know it's true
+  // (we already passed the reachability gate above).
+  logMigrationDone(
+    {
+      renames,
+      consolidates,
+      skippedForeignTarget,
+      deletes,
+      blockedHarmless: blocked,
+      errors,
+    },
+    pm,
+  );
+}
+
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  notify(`[kimi-code] postinstall warning: ${message}`);
+});
diff --git a/apps/kimi-code/scripts/postinstall/migrate.mjs b/apps/kimi-code/scripts/postinstall/migrate.mjs
new file mode 100644
index 000000000..b1ae695a3
--- /dev/null
+++ b/apps/kimi-code/scripts/postinstall/migrate.mjs
@@ -0,0 +1,351 @@
+/**
+ * Detection of the previous Python `kimi-cli` shim and the actual
+ * filesystem operations that perform (or refuse) the rename.
+ *
+ * Detection:
+ *   - {@link detectLegacyShims}: walks the caller-supplied
+ *     `pathString` and returns every legacy `kimi` shim along the
+ *     way (in PATH order). A shim qualifies when it realpath-resolves
+ *     outside our own installed package root and its head 4 KiB
+ *     contains the `kimi_cli` module marker — the setuptools
+ *     entry-point format produced by `uv tool install`,
+ *     `pipx install`, `pip install`, etc. Returning all hits (not
+ *     just the first) matters because a user with both uv- and
+ *     pipx-installed `kimi-cli` has two legacy shims in different
+ *     dirs, and renaming only the earlier one leaves the later one
+ *     shadowing our new CLI. Callers should pass the `detection`
+ *     field from `postinstallPaths()` so detection sees the union of
+ *     the shell PATH and the installer's PATH.
+ *   - {@link isLegacyShim}: same criterion in standalone form, used to
+ *     decide whether an existing `kimi-legacy` is itself a legacy CLI
+ *     (safe to consolidate over) or a user-managed file (preserve).
+ *
+ * Classify + execute (two-phase):
+ *   - {@link classifyShim}: pre-flight inspection that says what we
+ *     COULD do to a given shim. Returns one of `renameable`,
+ *     `consolidate`, `delete-only`, `blocked`. No filesystem writes.
+ *   - {@link renameInPlace} / {@link deleteShim}: the primitive
+ *     operations that actually mutate the filesystem. Run after the
+ *     orchestrator has looked at the full set of classifications and
+ *     decided to proceed.
+ *
+ * Splitting classification from execution lets the orchestrator make
+ * the abort-or-proceed decision once, against the whole detected set,
+ * rather than discovering mid-loop that something failed and ending up
+ * with a misleading "kimi now launches the new CLI" notice in front of
+ * a "permission denied" notice. Uses `fs.lstat` (not `fs.access`) to
+ * detect dangling symlinks at the target so we don't clobber them.
+ */
+
+import { constants as fsConstants, promises as fs } from 'node:fs';
+import { delimiter, dirname, extname, join, sep } from 'node:path';
+
+const LEGACY_BIN = 'kimi';
+const LEGACY_RENAME = 'kimi-legacy';
+const PYTHON_MARKER = 'kimi_cli';
+const IS_WINDOWS = process.platform === 'win32';
+
+// Read window for the marker sniff.
+//   POSIX: setuptools entry-point scripts are a few hundred bytes —
+//          4 KiB is generous.
+//   Windows: `uv tool install` produces a Rust-built launcher .exe
+//            (~45 KiB) and the `kimi_cli` module name sits embedded
+//            near the END of the file (verified offset ≈ 44103 on
+//            uv 0.11). Cap reads at 256 KiB so a hostile or
+//            unexpectedly large file can't make us hold a lot of
+//            memory.
+const SHIM_SNIFF_BYTES_POSIX = 4096;
+const SHIM_SNIFF_BYTES_WINDOWS_MAX = 256 * 1024;
+
+function pathEntries(pathString) {
+  if (!pathString) return [];
+  const seen = new Set();
+  const out = [];
+  for (const entry of pathString.split(delimiter)) {
+    if (!entry || seen.has(entry)) continue;
+    seen.add(entry);
+    out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * Expand `kimi` into the set of filenames that resolve as executables
+ * on this platform. POSIX → just `['kimi']`. Windows → adds every
+ * `PATHEXT` extension (so we find `kimi.exe`, `kimi.cmd`, etc).
+ */
+function executableCandidates(basename) {
+  if (!IS_WINDOWS) return [basename];
+  const pathext = (process.env['PATHEXT'] ?? '.EXE;.CMD;.BAT;.COM')
+    .toLowerCase()
+    .split(';')
+    .map((e) => e.trim())
+    .filter(Boolean);
+  return [basename, ...pathext.map((ext) => basename + ext)];
+}
+
+async function isExecutableFile(filePath) {
+  try {
+    const info = await fs.stat(filePath);
+    if (!info.isFile()) return false;
+    // Windows: stat().mode doesn't reflect ACLs in any useful way.
+    // Callers already restrict to PATHEXT candidates, so existence
+    // suffices.
+    if (IS_WINDOWS) return true;
+    return (info.mode & 0o111) !== 0;
+  } catch {
+    return false;
+  }
+}
+
+async function readShimHead(filePath) {
+  let handle;
+  try {
+    handle = await fs.open(filePath, 'r');
+    const stat = await handle.stat();
+    const limit = IS_WINDOWS ? SHIM_SNIFF_BYTES_WINDOWS_MAX : SHIM_SNIFF_BYTES_POSIX;
+    const target = Math.min(stat.size, limit);
+    const buffer = Buffer.alloc(target);
+    const { bytesRead } = await handle.read(buffer, 0, target, 0);
+    // `latin1` is a 1-to-1 byte→char mapping; we're searching for an
+    // ASCII substring, so we don't want UTF-8 decoding to mangle the
+    // bytes around the marker.
+    return buffer.subarray(0, bytesRead).toString('latin1');
+  } catch {
+    return null;
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+  }
+}
+
+/**
+ * Walk `pathString` and return every legacy `kimi` shim along the
+ * way, in PATH order. The orchestrator renames each in turn — a
+ * single rename is insufficient when the user has multiple legacy
+ * installs (e.g. one from `uv tool install` and another from `pipx
+ * install`) in different directories, because the survivor still
+ * shadows the new CLI.
+ *
+ * Each entry has the same shape as the previous single-return
+ * value: `{ shimPath, realPath }`. The empty array means
+ * "fresh-install / no-op".
+ */
+export async function detectLegacyShims(ownRoot, pathString) {
+  const ownRootPrefix = ownRoot ? ownRoot + sep : null;
+  const candidates = executableCandidates(LEGACY_BIN);
+  const results = [];
+  const seenShims = new Set();
+
+  for (const dir of pathEntries(pathString)) {
+    for (const name of candidates) {
+      const shimPath = join(dir, name);
+      if (seenShims.has(shimPath)) continue;
+      if (!(await isExecutableFile(shimPath))) continue;
+
+      let realPath;
+      try {
+        realPath = await fs.realpath(shimPath);
+      } catch {
+        continue;
+      }
+
+      // Defence-in-depth: never touch a `kimi` that resolves into our
+      // own installed package. The `kimi_cli` marker check below
+      // already excludes the manager's generated wrapper today, but
+      // this layer keeps us safe if anything in our bundle ever
+      // happens to contain the marker substring.
+      if (
+        ownRootPrefix !== null &&
+        (realPath === ownRoot || realPath.startsWith(ownRootPrefix))
+      ) {
+        continue;
+      }
+
+      const head = await readShimHead(realPath);
+      if (!head || !head.includes(PYTHON_MARKER)) continue;
+
+      seenShims.add(shimPath);
+      results.push({ shimPath, realPath });
+    }
+  }
+  return results;
+}
+
+/**
+ * Does the file at `p` look like the legacy Python `kimi-cli`?
+ *
+ * Same criterion as {@link detectLegacyShim} uses to recognize the
+ * original shim: realpath-resolvable and the first 4 KiB of the
+ * resolved file contains the `kimi_cli` module name. Used to decide
+ * whether an existing `kimi-legacy` is itself a legacy shim (safe to
+ * drop the duplicate `kimi`) or a user-managed file we must not
+ * clobber.
+ */
+export async function isLegacyShim(p) {
+  let real;
+  try {
+    real = await fs.realpath(p);
+  } catch {
+    return false;
+  }
+  const head = await readShimHead(real);
+  return Boolean(head && head.includes(PYTHON_MARKER));
+}
+
+async function pathExists(p) {
+  try {
+    // lstat (not access/stat) so a dangling symlink at `p` still
+    // reports as existing — `fs.access` follows symlinks and would
+    // return ENOENT for a broken link, after which `fs.rename` would
+    // silently replace it.
+    await fs.lstat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Compute where `shimPath` should be renamed to. Preserves the file
+ * extension so a Windows `C:\…\kimi.exe` ends up at `kimi-legacy.exe`
+ * rather than an extension-less `kimi-legacy` that `kimi.exe -- legacy`
+ * shells won't run.
+ */
+function renameTargetFor(shimPath) {
+  const ext = extname(shimPath);  // "" on POSIX, ".exe" on Windows
+  return join(dirname(shimPath), LEGACY_RENAME + ext);
+}
+
+/**
+ * Is the directory containing `shimPath` a system-managed location
+ * the current user can't write to?
+ *
+ * POSIX: dir owned by uid 0 (root) — captures
+ *   `sudo pip install kimi-cli` → `/usr/local/bin/`.
+ *
+ * Windows: dir under one of the well-known system roots
+ *   (`C:\Program Files`, `C:\ProgramData`, `C:\Windows`). uv tool
+ *   installs land in user space (`%USERPROFILE%\.local\bin`) so this
+ *   path almost never fires on Windows in practice, but the heuristic
+ *   correctly classifies the rare admin-prefix install case.
+ *
+ * The dedicated permission-denied notice (`logPermissionDenied`)
+ * uses this to switch from a bare "rename it manually" message to a
+ * sudo-aware / admin-aware explanation.
+ */
+async function isSystemOwnedDir(shimPath) {
+  if (IS_WINDOWS) {
+    const dir = dirname(shimPath).toLowerCase();
+    const systemRoots = [
+      'c:\\program files',
+      'c:\\program files (x86)',
+      'c:\\programdata',
+      'c:\\windows',
+    ];
+    return systemRoots.some(
+      (root) => dir === root || dir.startsWith(root + '\\'),
+    );
+  }
+  try {
+    const info = await fs.stat(dirname(shimPath));
+    return info.uid === 0;
+  } catch {
+    return false;
+  }
+}
+
+async function canWriteDir(dir) {
+  try {
+    // For `fs.rename` and `fs.unlink` the parent dir needs to be both
+    // writable and executable (POSIX `wx`). `fs.access` follows the
+    // same semantics. On Windows ACL details are coarse but
+    // `fs.access(W_OK)` is a reasonable best-effort.
+    await fs.access(dir, fsConstants.W_OK | fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Pre-flight inspection of a single legacy shim. Returns what action
+ * we could take WITHOUT executing it. The orchestrator uses these
+ * classifications to decide the whole-set strategy (abort vs proceed,
+ * which shim becomes kimi-legacy) before any filesystem writes
+ * happen.
+ *
+ * Result shapes (all carry `shimPath` and `target` so the renderer
+ * has the paths):
+ *   - `renameable`     : can `fs.rename(shim → target)` cleanly;
+ *                        target slot is free.
+ *   - `consolidate`    : target already exists and is itself a legacy
+ *                        shim; we'd `fs.unlink(shim)` and leave the
+ *                        existing `kimi-legacy` as the canonical
+ *                        fallback (functionally equivalent — same
+ *                        upstream package).
+ *   - `delete-only`    : target exists but is a user-managed file we
+ *                        won't clobber. We can still `fs.unlink(shim)`
+ *                        to stop the shadowing; the
+ *                        "preserve original kimi" invariant fails for
+ *                        THIS dir (we tell the user).
+ *   - `blocked`        : we can't write to the parent dir. Carries
+ *                        `isSystemPath` so the renderer can suggest
+ *                        sudo (POSIX) or admin PowerShell (Windows).
+ */
+export async function classifyShim(shimPath) {
+  const target = renameTargetFor(shimPath);
+  const dir = dirname(shimPath);
+
+  if (!(await canWriteDir(dir))) {
+    return {
+      kind: 'blocked',
+      shimPath,
+      target,
+      isSystemPath: await isSystemOwnedDir(shimPath),
+    };
+  }
+
+  if (await pathExists(target)) {
+    if (await isLegacyShim(target)) {
+      return { kind: 'consolidate', shimPath, target };
+    }
+    return { kind: 'delete-only', shimPath, target };
+  }
+
+  return { kind: 'renameable', shimPath, target };
+}
+
+/**
+ * Execute an `fs.rename`. Pre-flight classification establishes
+ * whether this is expected to succeed; this primitive just runs the
+ * call and wraps the error.
+ */
+export async function renameInPlace(shimPath, target) {
+  try {
+    await fs.rename(shimPath, target);
+    return { success: true };
+  } catch (err) {
+    const code = err && typeof err === 'object' ? err.code : undefined;
+    const message = err instanceof Error ? err.message : String(err);
+    return { success: false, code, message };
+  }
+}
+
+/**
+ * Execute an `fs.unlink`. Used when:
+ *   - we're consolidating onto an existing legacy `kimi-legacy`, or
+ *   - we couldn't rename (foreign target) but can still remove the
+ *     shadow, or
+ *   - this is a non-first shim and we just want to clear it out so
+ *     PATH order resolves to our new CLI.
+ */
+export async function deleteShim(shimPath) {
+  try {
+    await fs.unlink(shimPath);
+    return { success: true };
+  } catch (err) {
+    const code = err && typeof err === 'object' ? err.code : undefined;
+    const message = err instanceof Error ? err.message : String(err);
+    return { success: false, code, message };
+  }
+}
diff --git a/apps/kimi-code/scripts/postinstall/reach.mjs b/apps/kimi-code/scripts/postinstall/reach.mjs
new file mode 100644
index 000000000..e6a4c9385
--- /dev/null
+++ b/apps/kimi-code/scripts/postinstall/reach.mjs
@@ -0,0 +1,457 @@
+/**
+ * Where the user actually types things, and what `kimi` resolves to
+ * from there.
+ *
+ * Covers:
+ *
+ *   - Package-manager detection ({@link detectPackageManager}) and
+ *     manager-specific command hints ({@link pmGlobalBinCommand},
+ *     {@link pmGlobalInstallCommand}) used in user-facing notices.
+ *   - Global-install gating ({@link isGlobalInstall}) — what counts as
+ *     a global install across npm / yarn classic / pnpm.
+ *   - Own-package-root location ({@link ownPackageRoot}) — walks up
+ *     from `import.meta.dirname` looking for `package.json`.
+ *   - User-shell PATH ({@link userShellPath}) — spawns `$SHELL -l` so
+ *     we can check reachability from the shell the user will type
+ *     `kimi` into, not just the installer's environment.
+ *   - The combined PATH dispatcher ({@link postinstallPaths}) —
+ *     called once by the orchestrator so detection and reachability
+ *     stay symmetric and the shell probe doesn't run twice.
+ *   - The reachability check ({@link findFirstResolvableKimi}) —
+ *     walks PATH treating the to-be-renamed legacy shims as gone
+ *     and reports what wins resolution. Distinguishes our own shim
+ *     from a blocked legacy that's still in the way vs. an
+ *     unknown/foreign `kimi` (e.g. a user-written wrapper).
+ *
+ * All functions are pure w.r.t. the filesystem (no mutations).
+ */
+
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import { delimiter, dirname, join, sep } from 'node:path';
+
+const LEGACY_BIN = 'kimi';
+const IS_WINDOWS = process.platform === 'win32';
+
+/**
+ * Expand a basename like `kimi` into the set of filenames the OS
+ * would actually match on PATH.
+ *
+ * On POSIX: just `['kimi']`.
+ *
+ * On Windows: `['kimi', 'kimi.exe', 'kimi.cmd', …]` — every
+ * extension in `PATHEXT`. Without this, our PATH walk would miss
+ * the typical `kimi.exe` shim produced by `uv tool install` on
+ * Windows.
+ */
+export function executableCandidates(basename) {
+  if (!IS_WINDOWS) return [basename];
+  const pathext = (process.env['PATHEXT'] ?? '.EXE;.CMD;.BAT;.COM')
+    .toLowerCase()
+    .split(';')
+    .map((e) => e.trim())
+    .filter(Boolean);
+  return [basename, ...pathext.map((ext) => basename + ext)];
+}
+
+/**
+ * Identify which package manager ran us. `npm_config_user_agent` is
+ * set by npm, yarn (classic + berry), and pnpm, and starts with the
+ * manager's name plus version. Defaults to `'npm'` for unknown /
+ * missing values.
+ */
+export function detectPackageManager() {
+  const ua = process.env['npm_config_user_agent'] ?? '';
+  if (ua.startsWith('pnpm/')) return 'pnpm';
+  if (ua.startsWith('yarn/')) return 'yarn';
+  return 'npm';
+}
+
+/**
+ * Manager-specific shell command that prints (or expands to) the
+ * global bin directory. Used in the PATH-fix hint so the suggestion
+ * is valid regardless of which manager the user ran.
+ */
+export function pmGlobalBinCommand(pm) {
+  switch (pm) {
+    case 'pnpm':
+      return 'pnpm bin -g';
+    case 'yarn':
+      return 'yarn global bin';
+    case 'npm':
+    default:
+      return 'npm prefix -g';
+  }
+}
+
+/** Manager-specific reinstall command, used in the success-notice hint. */
+export function pmGlobalInstallCommand(pm, pkg) {
+  switch (pm) {
+    case 'pnpm':
+      return `pnpm add -g ${pkg}`;
+    case 'yarn':
+      return `yarn global add ${pkg}`;
+    case 'npm':
+    default:
+      return `npm install -g ${pkg}`;
+  }
+}
+
+/**
+ * Did the user run a global install via some Node package manager?
+ *
+ * We accept four signals, any of which means "this install is
+ * landing in the manager's global bin directory":
+ *
+ *   - `npm_config_global === 'true'`  — set by `npm install -g`, and
+ *     by pnpm on its global paths for back-compat.
+ *   - `pnpm_config_global === 'true'` — set by pnpm in addition to
+ *     the npm-compat flag above.
+ *   - `npm_config_location === 'global'` — set by npm 7+ when the
+ *     user passes `--location=global` (or runs `npm config set
+ *     location global` persistently). npm intentionally does NOT
+ *     also set `npm_config_global` in this case, so without this
+ *     branch the migration silently no-ops for `npm install
+ *     --location=global @moonshot-ai/kimi-code` — verified on npm
+ *     11.13.0.
+ *   - {@link isYarnClassicGlobalAdd} — yarn classic does NOT set
+ *     `npm_config_global` for `yarn global add`. The only reliable
+ *     signal is parsing `npm_config_argv` and seeing the `global`
+ *     subcommand. Verified on yarn 1.22.22.
+ *
+ * Local installs, `npx`, `pnpm dlx`, and workspace bootstraps leave
+ * all four signals false.
+ *
+ * Yarn berry (v2+) intentionally has no global-install concept, so
+ * it doesn't matter here. Postinstall on yarn berry runs in local
+ * context.
+ */
+export function isGlobalInstall() {
+  return (
+    process.env['npm_config_global'] === 'true' ||
+    process.env['pnpm_config_global'] === 'true' ||
+    process.env['npm_config_location'] === 'global' ||
+    isYarnClassicGlobalAdd()
+  );
+}
+
+/**
+ * `yarn global add` (yarn classic, v1.x) runs lifecycle scripts but
+ * leaves both `npm_config_global` and `npm_config_location` unset.
+ * The only reliable in-band signal is `npm_config_argv`, which yarn
+ * populates with the original command line as JSON:
+ *   { original: ["global", "add", "<pkg>", "--prefix=..."] }
+ * Parse it and require both:
+ *   - `npm_config_user_agent` starts with `yarn/1.` (yarn classic;
+ *     yarn berry has no global concept anyway).
+ *   - Some token in argv is literally `"global"` AND the very next
+ *     token is a known yarn-global subcommand (`add`, `remove`,
+ *     etc). This handles the simple case (`yarn global add foo` →
+ *     argv `["global","add",...]`) and the value-taking-flag case
+ *     (`yarn --cwd /tmp global add foo` → argv `["--cwd","/tmp",
+ *     "global","add",...]`) without having to maintain yarn's full
+ *     flag table. It rejects `yarn add global` (the next token is
+ *     undefined) and `yarn add @scope/global` (the literal string
+ *     `"global"` doesn't appear). The remaining false positives
+ *     (e.g., `yarn add global add` — installing two packages, one
+ *     literally named `global`) are caught downstream by the
+ *     reachability gate: a local install's bin dir isn't on PATH,
+ *     so `isOwnCliResolvableFirst` will refuse to migrate.
+ */
+function isYarnClassicGlobalAdd() {
+  const ua = process.env['npm_config_user_agent'] ?? '';
+  if (!ua.startsWith('yarn/1.')) return false;
+  const raw = process.env['npm_config_argv'];
+  if (!raw) return false;
+  let argv;
+  try {
+    argv = JSON.parse(raw);
+  } catch {
+    return false;
+  }
+  if (!Array.isArray(argv?.original)) return false;
+  const globalIdx = argv.original.indexOf('global');
+  if (globalIdx === -1) return false;
+  const next = argv.original[globalIdx + 1];
+  return typeof next === 'string' && YARN_GLOBAL_SUBCOMMANDS.has(next);
+}
+
+// Yarn 1.x global subcommands. The install-class ones (`add`,
+// `upgrade`, `upgrade-interactive`) are the ones that actually run
+// our postinstall, but the read-only ones are included so the
+// detection is consistent across all `yarn global ...` invocations.
+const YARN_GLOBAL_SUBCOMMANDS = new Set([
+  'add',
+  'remove',
+  'upgrade',
+  'upgrade-interactive',
+  'list',
+  'bin',
+  'dir',
+]);
+
+/**
+ * Locate the realpath of our own installed package root.
+ *
+ * Callers pass the starting directory (typically `import.meta.dirname`
+ * of the entry script, which lives at `<package-root>/scripts/`). We
+ * walk up looking for the nearest `package.json`, then `realpath` the
+ * directory so symlinked install layouts (e.g. `<prefix>/bin/kimi`
+ * symlinked into `lib/node_modules/.../dist/main.mjs`) compare equal
+ * in the caller's prefix check.
+ *
+ * Returns null if no `package.json` is found within a few levels —
+ * callers should treat that as "can't locate ourselves" and bail.
+ */
+export async function ownPackageRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 6; i++) {
+    try {
+      await fs.access(join(dir, 'package.json'));
+      try {
+        return await fs.realpath(dir);
+      } catch {
+        return dir;
+      }
+    } catch {
+      // No `package.json` here; walk up.
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+async function isExecutableFile(filePath) {
+  try {
+    const info = await fs.stat(filePath);
+    if (!info.isFile()) return false;
+    // Windows: ACLs aren't visible through stat().mode meaningfully —
+    // existence + a recognized extension is what PATHEXT-style lookup
+    // checks. Callers only pass us candidates that already match an
+    // extension in `executableCandidates()`, so "is a file" suffices.
+    if (IS_WINDOWS) return true;
+    return (info.mode & 0o111) !== 0;
+  } catch {
+    return false;
+  }
+}
+
+// Package-manager shim generators embed the package's resolved path
+// into the wrapper file. So any shim whose first KB contains our
+// package name is one we own. Used as a fallback when realpath alone
+// can't catch the shim — that happens for:
+//   - Windows cmd-shims (literal `.cmd` / `.ps1` files, not symlinks)
+//   - pnpm POSIX shims (literal `/bin/sh` scripts, not symlinks; pnpm
+//     does not symlink into the package root the way npm/yarn classic
+//     do on POSIX)
+const PACKAGE_NAME_MARKERS = ['@moonshot-ai/kimi-code', '@moonshot-ai\\kimi-code'];
+
+async function shimReferencesOwnPackage(shimPath) {
+  try {
+    const handle = await fs.open(shimPath, 'r');
+    try {
+      const buf = Buffer.alloc(4096);
+      const { bytesRead } = await handle.read(buf, 0, 4096, 0);
+      const text = buf.subarray(0, bytesRead).toString('latin1');
+      return PACKAGE_NAME_MARKERS.some((m) => text.includes(m));
+    } finally {
+      await handle.close().catch(() => {});
+    }
+  } catch {
+    return false;
+  }
+}
+
+async function classifyShim(shim, ownRoot, ownPrefix) {
+  let real;
+  try {
+    real = await fs.realpath(shim);
+  } catch {
+    return 'unreadable';
+  }
+  if (real === ownRoot || real.startsWith(ownPrefix)) return 'own';
+  if (await shimReferencesOwnPackage(shim)) return 'own';
+  return 'other';
+}
+
+/**
+ * Walk `pathString` and report what the user's shell would resolve
+ * `kimi` to, AFTER the to-be-removed shims in `actionableShimPaths`
+ * are pretended gone. Returns the first match by PATH order:
+ *
+ *   - { kind: 'own' }                     — our shim wins.
+ *   - { kind: 'blocked-legacy', shim }    — a legacy `kimi` we
+ *     detected but couldn't touch (a "blocked" shim) wins.
+ *   - { kind: 'foreign', path }           — something else wins: a
+ *     `kimi` we didn't recognize as a legacy CLI and didn't generate
+ *     ourselves (e.g. a user-managed wrapper script in `~/bin`).
+ *   - { kind: 'none' }                    — no `kimi` resolves at all.
+ *
+ * Used by the orchestrator to give an accurate "why the takeover
+ * can't proceed" notice: a blocked-legacy blocker needs different
+ * remediation (sudo / admin delete) than a foreign blocker (the
+ * user's own file, which only they can decide what to do with).
+ *
+ * `allDetectedShimPaths` is every legacy shim our detector found
+ * (both blocked and actionable). It lets us distinguish a blocked
+ * legacy that survived our hypothetical removal pass from a totally
+ * unknown `kimi`.
+ */
+export async function findFirstResolvableKimi(
+  ownRoot,
+  pathString,
+  actionableShimPaths,
+  allDetectedShimPaths,
+) {
+  if (!ownRoot || !pathString) return { kind: 'none' };
+  const ownPrefix = ownRoot + sep;
+  const candidates = executableCandidates(LEGACY_BIN);
+  const skipSet = new Set(actionableShimPaths ?? []);
+  const knownLegacySet = new Set(allDetectedShimPaths ?? []);
+  const seenDirs = new Set();
+  for (const dir of pathString.split(delimiter)) {
+    if (!dir || seenDirs.has(dir)) continue;
+    seenDirs.add(dir);
+    for (const name of candidates) {
+      const shim = join(dir, name);
+      if (skipSet.has(shim)) continue;
+      if (!(await isExecutableFile(shim))) continue;
+      const kind = await classifyShim(shim, ownRoot, ownPrefix);
+      if (kind === 'unreadable') continue;
+      if (kind === 'own') return { kind: 'own' };
+      if (knownLegacySet.has(shim)) {
+        return { kind: 'blocked-legacy', shim };
+      }
+      return { kind: 'foreign', path: shim };
+    }
+  }
+  return { kind: 'none' };
+}
+
+/**
+ * Read the user's default shell's view of `PATH`.
+ *
+ * Why: `process.env.PATH` reflects the environment of whichever
+ * shell the user happened to invoke the package manager from, which
+ * may or may not match the daily-driver shell they'll later type
+ * `kimi` into. A `~/.zshrc`-only PATH entry, a `~/.bash_profile`
+ * that doesn't source `~/.bashrc`, or a sudo'd install that scrubs
+ * HOME all break the installer's-PATH heuristic.
+ *
+ * We spawn `$SHELL -l -c 'printf %s "$PATH"'` so the shell reads
+ * its login-profile files (`.profile`, `.bash_profile`, `.zprofile`).
+ * `-i` would also pull in interactive rc files (`.bashrc`, `.zshrc`)
+ * but it requires a tty for some shells and is much more likely to
+ * have side effects (prompts, agent startup) — we accept the
+ * narrower view and let `'unknown'` fall through to a gentler
+ * check.
+ *
+ * Outcomes:
+ *   { kind: 'ok',      path: string }   — shell printed its PATH.
+ *   { kind: 'unknown', reason: string } — `$SHELL` missing, spawn
+ *                                         failed, timed out, or
+ *                                         shell printed no `PATH`.
+ */
+export async function userShellPath() {
+  // Windows has no `$SHELL`/login-shell concept worth probing — cmd.exe
+  // and PowerShell don't have profile files in the rc-chain sense, and
+  // their PATH already comes from the user's persistent registry env
+  // (which is what `process.env.PATH` reflects). Skip the spawn and
+  // let the caller fall back to `process.env.PATH`.
+  if (IS_WINDOWS) return { kind: 'unknown', reason: 'windows skip' };
+
+  const shell = process.env['SHELL'];
+  if (!shell) return { kind: 'unknown', reason: 'no SHELL env var' };
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+
+    let stdout = '';
+    // Wrap PATH in delimiters we can parse out, defensively, in case
+    // the shell prints anything else (motd, prompt redraw, …).
+    const probe =
+      'printf "<<<KIMI_PATH_BEGIN>>>%s<<<KIMI_PATH_END>>>\\n" "$PATH"';
+    const child = spawn(shell, ['-l', '-c', probe], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString('utf-8');
+    });
+
+    // Bound the wait. Login rc files are usually quick, but a hostile
+    // `.profile` could hang indefinitely.
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      settle({ kind: 'unknown', reason: 'shell spawn timed out' });
+    }, 5000);
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      const match = stdout.match(
+        /<<<KIMI_PATH_BEGIN>>>([\s\S]*?)<<<KIMI_PATH_END>>>/,
+      );
+      if (match && match[1].length > 0) {
+        settle({ kind: 'ok', path: match[1] });
+        return;
+      }
+      settle({ kind: 'unknown', reason: `no PATH printed (exit ${code})` });
+    });
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      settle({ kind: 'unknown', reason: `spawn error: ${err.message}` });
+    });
+  });
+}
+
+/**
+ * Compute the two PATH strings the postinstall consults.
+ *
+ *   - `detection`: a `delimiter`-joined union of the user's shell
+ *     PATH and `process.env.PATH`, deduplicated. Used by
+ *     {@link detectLegacyShim} to walk for legacy shims. We union
+ *     because either source may contain a legacy `kimi` we want to
+ *     rename — including one that lives in a directory the
+ *     installer's environment can't see but the user's shell can
+ *     (e.g. a sanitized lifecycle env from a packaged manager), and
+ *     vice versa.
+ *
+ *   - `reachability`: the user's shell PATH if we can probe it, else
+ *     `process.env.PATH`. Used to verify our own shim is on the PATH
+ *     the user will actually type `kimi` into. We do NOT union here:
+ *     a shim that's only in the installer's PATH wouldn't help the
+ *     user after the install, so unioning would mis-classify the
+ *     install as reachable.
+ *
+ * Returns a single object so the (potentially slow) shell-probe runs
+ * just once per postinstall.
+ */
+export async function postinstallPaths() {
+  const shellResult = await userShellPath();
+  const processPath = process.env['PATH'] ?? '';
+  const shellPathStr = shellResult.kind === 'ok' ? shellResult.path : null;
+  const reachability = shellPathStr ?? processPath;
+  const detection = unionPaths(shellPathStr, processPath);
+  return { detection, reachability };
+}
+
+function unionPaths(...paths) {
+  const seen = new Set();
+  const out = [];
+  for (const p of paths) {
+    if (!p) continue;
+    for (const entry of p.split(delimiter)) {
+      if (!entry || seen.has(entry)) continue;
+      seen.add(entry);
+      out.push(entry);
+    }
+  }
+  return out.join(delimiter);
+}
+
diff --git a/apps/kimi-code/scripts/postinstall/ui.mjs b/apps/kimi-code/scripts/postinstall/ui.mjs
new file mode 100644
index 000000000..84be992f5
--- /dev/null
+++ b/apps/kimi-code/scripts/postinstall/ui.mjs
@@ -0,0 +1,458 @@
+/**
+ * User-facing output for the postinstall: where lines go, ANSI styling,
+ * the fixed-width box layout, and the four outcome renderers:
+ *
+ *   - `logMigrationDone` — the takeover succeeded (one or more legacy
+ *     shims were processed). Lists every action taken: renames,
+ *     consolidates, delete-only, plain deletes, and harmless blocked
+ *     leftovers. Footer branches three ways: preserved-somewhere
+ *     (standard "type kimi-legacy"), only skippedForeignTarget (we
+ *     couldn't save the old CLI because a user file took the name),
+ *     and only blockedHarmless (just notes the leftovers, no
+ *     phantom-file talk).
+ *   - `logMigrationBlocked` — a legacy `kimi` we can't remove sits
+ *     on PATH ahead of our shim. Nothing was touched; user is told
+ *     which paths need their manual attention with sudo / admin.
+ *   - `logForeignKimiInTheWay` — a `kimi` we don't recognize (not
+ *     ours, not a legacy CLI) sits ahead of our shim on PATH. User
+ *     needs to delete or rename their own file. Different remediation
+ *     from `logMigrationBlocked`.
+ *   - `logNewCliNotOnPath` — we found a legacy but our own shim
+ *     isn't on the user's shell PATH at all. Same "touch nothing"
+ *     behavior, different prose.
+ *
+ * This module is intentionally self-contained: no PATH walking, no fs
+ * mutations, no shell spawning — just rendering. The orchestrator
+ * (`postinstall.mjs`) makes the abort-or-proceed decision once and
+ * calls exactly one renderer at the end.
+ */
+
+import { writeFileSync } from 'node:fs';
+
+import { pmGlobalInstallCommand, pmGlobalBinCommand } from './reach.mjs';
+
+// Fixed-width box rendering. 80 cols is the de facto terminal default.
+// We can't reliably read TTY width from a piped postinstall context, so
+// we pin the width and truncate long content with an ellipsis if needed.
+const BOX_WIDTH = 80;
+const BOX_INNER = BOX_WIDTH - 2; // chars between the two vertical borders
+const BOX_PAD_LEFT = 2; // leading spaces inside the box for breathing room
+
+// ANSI styling. Disabled when NO_COLOR is set (https://no-color.org/).
+// We can't reliably tell whether `/dev/tty`'s far end supports color,
+// but modern terminals all do; users who want plain output can set
+// NO_COLOR.
+const USE_COLOR = !process.env['NO_COLOR'];
+const ANSI_ESCAPE = /\x1b\[[0-9;]*[a-zA-Z]/g;
+const C_RESET = USE_COLOR ? '\x1b[0m' : '';
+const C_DIM = USE_COLOR ? '\x1b[2m' : '';
+const C_BOLD_GREEN = USE_COLOR ? '\x1b[1;32m' : '';
+const C_BOLD_YELLOW = USE_COLOR ? '\x1b[1;33m' : '';
+const C_CYAN = USE_COLOR ? '\x1b[36m' : '';
+
+function color(c, text) {
+  return USE_COLOR ? c + text + C_RESET : text;
+}
+
+function visibleLength(s) {
+  return s.replace(ANSI_ESCAPE, '').length;
+}
+
+function stripAnsi(s) {
+  return s.replace(ANSI_ESCAPE, '');
+}
+
+// Platform-specific path to the controlling terminal device. Writing
+// here bypasses the package manager's lifecycle stdout capture (npm 7+
+// hides script stdout/stderr by default). On POSIX it's `/dev/tty`;
+// on Windows it's the special filename `CON`, which Node resolves to
+// the console device. (The fully-qualified `\\.\CON` form looks
+// equivalent but Node appends a trailing backslash that breaks the
+// open call — confirmed empirically on Windows 11 / Node 22.)
+const TERMINAL_DEVICE = process.platform === 'win32' ? 'CON' : '/dev/tty';
+
+/**
+ * Print a user-facing line. npm 7+ captures lifecycle stdout/stderr by
+ * default, so messages here would be invisible to a user running
+ * `npm install -g`. Writing directly to the platform's terminal
+ * device bypasses the manager's capture when one is available
+ * (interactive terminals). In CI / non-TTY contexts the device isn't
+ * writable; fall back to stdout so the message is still preserved in
+ * npm's lifecycle log under `~/.npm/_logs/`, with ANSI stripped so
+ * the log file stays readable.
+ */
+export function notify(line) {
+  const text = line + '\n';
+  try {
+    writeFileSync(TERMINAL_DEVICE, text);
+    return;
+  } catch {
+    // Terminal device not writable (CI, sandboxed environments).
+  }
+  process.stdout.write(stripAnsi(text));
+}
+
+// Single-quote `path` for safe interpolation in a POSIX `sh` command.
+// Wraps in single quotes and escapes any embedded `'` as `'\''`.
+function quotePosixPath(path) {
+  return "'" + path.replace(/'/g, "'\\''") + "'";
+}
+
+// Single-quote `path` for safe interpolation in a PowerShell command.
+// PowerShell single-quoted strings disable expansion; embedded `'` is
+// escaped by doubling.
+function quotePowerShellPath(path) {
+  return "'" + path.replace(/'/g, "''") + "'";
+}
+
+function boxBorder(left, right, fill = '─') {
+  return color(C_DIM, left + fill.repeat(BOX_INNER) + right);
+}
+
+function boxLine(content = '') {
+  const visible = visibleLength(content);
+  const padding =
+    visible < BOX_INNER ? ' '.repeat(BOX_INNER - visible) : '';
+  return color(C_DIM, '│') + content + padding + color(C_DIM, '│');
+}
+
+function pad(content) {
+  return ' '.repeat(BOX_PAD_LEFT) + content;
+}
+
+function renderBox(lines) {
+  const out = [boxBorder('╭', '╮'), boxLine('')];
+  for (const line of lines) out.push(boxLine(line));
+  out.push(boxLine(''), boxBorder('╰', '╯'));
+  return out;
+}
+
+function emit(lines) {
+  notify('');
+  for (const line of lines) notify(line);
+  notify('');
+}
+
+function pathInBox(path) {
+  // 7-space lead = box pad (2) + prose indent (3) + nesting under
+  // label (2). We intentionally do NOT truncate overflowing content:
+  // for command lines (`sudo rm <path>`, `mv <a> <b>`), left-truncation
+  // would swallow the command verb and leave the user with
+  // un-copy-pasteable instructions. Long lines just overflow the box
+  // border, which is visually less pretty but keeps the content
+  // intact.
+  const lead = ' '.repeat(BOX_PAD_LEFT + 5);
+  return lead + color(C_CYAN, path);
+}
+
+function successHeading(text) {
+  return pad(color(C_BOLD_GREEN, '✓  ' + text));
+}
+
+function warningHeading(text) {
+  return pad(color(C_BOLD_YELLOW, '!  ' + text));
+}
+
+/**
+ * The takeover completed. Renders one box that lists every action
+ * taken, so the user sees a single coherent picture even when several
+ * shims were involved.
+ *
+ * Sections (each only shown when non-empty):
+ *   - "Renamed" — the first PATH-order shim, preserved as
+ *     `kimi-legacy`. The "`kimi` now launches the new CLI" claim is
+ *     safe to make here because the orchestrator already verified
+ *     reachability after this set of removals.
+ *   - "Consolidated" — first shim's `kimi-legacy` already pointed at
+ *     a legacy file (re-migration case); we deleted the duplicate
+ *     source and kept the existing target. Same end state, different
+ *     mechanism.
+ *   - "Couldn't preserve as kimi-legacy" — first shim's `kimi-legacy`
+ *     slot was a user-managed file; we deleted the source `kimi` to
+ *     remove the shadow but left their file alone, so no fallback
+ *     exists in that dir.
+ *   - "Also removed" — non-first PATH-order shims that would have
+ *     shadowed our new shim. Just `unlink`ed.
+ *   - "Note: legacy left behind" — blocked shims that couldn't be
+ *     removed but PATH order means they don't shadow us; the user
+ *     can clean them up at leisure.
+ *   - "Errors" — anything that failed during execution despite
+ *     pre-flight saying it should work (race conditions, transient
+ *     fs errors). Listed last so the user can see what to retry.
+ */
+export function logMigrationDone(outcomes, pm) {
+  const reinstallCmd = pmGlobalInstallCommand(pm, '@moonshot-ai/kimi-code');
+  const {
+    renames,
+    consolidates,
+    skippedForeignTarget,
+    deletes,
+    blockedHarmless,
+    errors,
+  } = outcomes;
+
+  const lines = [successHeading('kimi now runs the new version'), ''];
+
+  if (renames.length > 0) {
+    lines.push(pad('   Renamed your old kimi so you can still run it as'));
+    lines.push(pad('   kimi-legacy:'));
+    for (const c of renames) {
+      lines.push(pathInBox(c.shimPath + '  ->  ' + c.target));
+    }
+    lines.push('');
+  }
+
+  if (consolidates.length > 0) {
+    lines.push(pad('   Removed an extra copy of your old kimi (kimi-legacy'));
+    lines.push(pad('   was already set up here from before):'));
+    for (const c of consolidates) {
+      lines.push(pathInBox(c.shimPath));
+      lines.push(pathInBox('  (kimi-legacy is at ' + c.target + ')'));
+    }
+    lines.push('');
+  }
+
+  if (skippedForeignTarget.length > 0) {
+    lines.push(pad('   Removed your old kimi (a file you created was already'));
+    lines.push(pad('   using the name kimi-legacy, so we left it alone):'));
+    for (const c of skippedForeignTarget) {
+      lines.push(pathInBox(c.shimPath));
+      lines.push(pathInBox('  (your file at ' + c.target + ' is untouched)'));
+    }
+    lines.push('');
+  }
+
+  if (deletes.length > 0) {
+    lines.push(pad('   Also removed (these would have run instead of the'));
+    lines.push(pad('   new kimi if we left them):'));
+    for (const c of deletes) {
+      lines.push(pathInBox(c.shimPath));
+    }
+    lines.push('');
+  }
+
+  if (blockedHarmless.length > 0) {
+    lines.push(pad('   Note: we can\'t change these files, but it\'s OK —'));
+    lines.push(pad('   they won\'t run instead of the new kimi:'));
+    for (const c of blockedHarmless) {
+      lines.push(pathInBox(c.shimPath));
+    }
+    lines.push('');
+  }
+
+  if (errors.length > 0) {
+    lines.push(pad('   Some changes didn\'t go through:'));
+    for (const e of errors) {
+      lines.push(
+        pathInBox(e.shimPath + '  (' + (e.message ?? e.code ?? 'error') + ')'),
+      );
+    }
+    lines.push('');
+  }
+
+  // Footer has three branches based on what actually happened:
+  //
+  //   1. Preserved somewhere (rename or consolidate): the old CLI is
+  //      available as `kimi-legacy`. Standard takeover footer.
+  //   2. Only skippedForeignTarget (no rename, no consolidate, no
+  //      blockedHarmless): user has a file they made called
+  //      `kimi-legacy`, so we couldn't save the old CLI under that
+  //      name. Explain the situation honestly.
+  //   3. Only blockedHarmless (no rename, no consolidate, no
+  //      skippedForeignTarget): we have nothing to celebrate or
+  //      apologize for — the "Note: we can't change these files but
+  //      it's OK" section above already covers it. Plain footer.
+  //
+  // If both skippedForeignTarget AND blockedHarmless are present
+  // (but no preservation), branch 2 wins — the foreign-target story
+  // is the more useful one for the user to know about.
+  const preservedSomewhere = renames.length > 0 || consolidates.length > 0;
+  if (preservedSomewhere) {
+    lines.push(
+      pad('   Now typing `kimi` runs the new version. To run the old'),
+      pad('   version, type `kimi-legacy` instead. Your settings from'),
+      pad('   the old version will be moved over the first time you'),
+      pad('   run `kimi`.'),
+      '',
+      pad('   Note: if you reinstall the old kimi later (e.g. with'),
+      pad('   `uv tool`, `pip`, or `pipx`), it will put `kimi` back.'),
+      pad('   Run this command again to switch to the new one:'),
+      pathInBox(reinstallCmd),
+      '',
+      pad('   If typing `kimi` still runs the old version, open a new'),
+      pad('   terminal window — your current one may have remembered'),
+      pad('   the old path.'),
+    );
+  } else if (skippedForeignTarget.length > 0) {
+    lines.push(
+      pad('   Now typing `kimi` runs the new version. Your settings'),
+      pad('   from the old version will be moved over the first time'),
+      pad('   you run `kimi`.'),
+      '',
+      pad('   We couldn\'t save the old kimi as `kimi-legacy` because'),
+      pad('   that name was already taken by a file you\'d created.'),
+      pad('   If you need the old kimi back, install it again with'),
+      pad('   `uv tool install kimi-cli` (or pipx / pip).'),
+      '',
+      pad('   If typing `kimi` still runs the old version, open a new'),
+      pad('   terminal window — your current one may have remembered'),
+      pad('   the old path.'),
+    );
+  } else {
+    lines.push(
+      pad('   Now typing `kimi` runs the new version. Your settings'),
+      pad('   from the old version will be moved over the first time'),
+      pad('   you run `kimi`.'),
+      '',
+      pad('   If typing `kimi` still runs the old version, open a new'),
+      pad('   terminal window — your current one may have remembered'),
+      pad('   the old path.'),
+    );
+  }
+
+  emit(renderBox(lines));
+}
+
+/**
+ * At least one blocked legacy shim still sits on PATH ahead of where
+ * our new shim would land. We refused to touch anything (pre-flight
+ * abort), so neither the user's existing setup nor the new install
+ * gets a half-migrated state. List each blocking path with the
+ * platform-appropriate manual fix.
+ */
+export function logMigrationBlocked(blocked, actionable, pm) {
+  const isWindows = process.platform === 'win32';
+  const reinstallCmd = pmGlobalInstallCommand(pm, '@moonshot-ai/kimi-code');
+
+  const lines = [
+    warningHeading('Can\'t switch to the new kimi yet'),
+    '',
+    pad('   There\'s an old kimi on your computer that we can\'t change.'),
+    pad('   As long as it\'s there, typing `kimi` will still run the old'),
+    pad('   version. Files we can\'t change:'),
+  ];
+
+  for (const c of blocked) {
+    lines.push(pathInBox(c.shimPath));
+  }
+
+  lines.push('', pad('   Please delete them yourself, then install again:'));
+
+  for (const c of blocked) {
+    if (isWindows && c.isSystemPath) {
+      // Admin PowerShell needed.
+      lines.push(pathInBox('# in an elevated PowerShell:'));
+      lines.push(pathInBox('Remove-Item ' + quotePowerShellPath(c.shimPath)));
+    } else if (c.isSystemPath) {
+      lines.push(pathInBox('sudo rm ' + quotePosixPath(c.shimPath)));
+    } else if (isWindows) {
+      lines.push(pathInBox('Remove-Item ' + quotePowerShellPath(c.shimPath)));
+    } else {
+      lines.push(pathInBox('rm ' + quotePosixPath(c.shimPath)));
+    }
+  }
+
+  if (actionable.length > 0) {
+    lines.push(
+      '',
+      pad('   We also found these old kimi files. We could remove them'),
+      pad('   ourselves, once the ones above are gone:'),
+    );
+    for (const c of actionable) {
+      lines.push(pathInBox(c.shimPath));
+    }
+  }
+
+  lines.push(
+    '',
+    pad('   After deleting them, install again to finish:'),
+    pathInBox(reinstallCmd),
+    '',
+    pad('   Nothing on your computer was changed.'),
+  );
+
+  emit(renderBox(lines));
+}
+
+/**
+ * The reachability check found a `kimi` ahead of our shim on PATH
+ * that's neither ours nor a legacy Python CLI — almost certainly a
+ * wrapper the user wrote themselves (or installed from somewhere we
+ * don't recognize). Deleting blocked legacy shims wouldn't help
+ * here: the foreign file would still win resolution. So the
+ * remediation is "delete or rename your own file", which only the
+ * user can decide.
+ */
+export function logForeignKimiInTheWay(foreignPath, pm) {
+  const reinstallCmd = pmGlobalInstallCommand(pm, '@moonshot-ai/kimi-code');
+  emit(
+    renderBox([
+      warningHeading('Can\'t switch to the new kimi yet'),
+      '',
+      pad('   There\'s another file called `kimi` on your computer that\'s'),
+      pad('   not the new CLI and not the old one — it looks like'),
+      pad('   something you set up yourself. As long as it\'s there,'),
+      pad('   typing `kimi` will run it instead of the new version.'),
+      '',
+      pad('   We found it at:'),
+      pathInBox(foreignPath),
+      '',
+      pad('   To use the new kimi, delete or rename that file, then'),
+      pad('   install again:'),
+      pathInBox(reinstallCmd),
+      '',
+      pad('   Nothing on your computer was changed.'),
+    ]),
+  );
+}
+
+/**
+ * The legacy `kimi` was found, but the directory where the package
+ * manager placed the new `kimi` shim is not on the user's PATH.
+ * Renaming the legacy shim now would leave the user with NO reachable
+ * `kimi` command — the new one would still not be discoverable by
+ * their shell. Show them the PATH fix and leave the legacy CLI alone.
+ *
+ * The PATH-fix hint uses the manager-specific subshell command (one
+ * of `npm prefix -g`, `yarn global bin`, `pnpm bin -g`) so it works
+ * regardless of which manager the user ran, and renders in the
+ * syntax of the user's likely shell:
+ *   - POSIX  : `export PATH=...`.
+ *   - Windows: `$env:Path = ...` (PowerShell).
+ * On Windows, npm places global shims directly under `<prefix>` (no
+ * `bin` subdir), and pnpm/yarn already report the bin dir, so we
+ * skip the `/bin` suffix the POSIX branch needs for npm.
+ */
+export function logNewCliNotOnPath(detection, pm) {
+  const isWindows = process.platform === 'win32';
+  const binCmd = pmGlobalBinCommand(pm);
+  const reinstallCmd = pmGlobalInstallCommand(pm, '@moonshot-ai/kimi-code');
+
+  const newPathHint = isWindows
+    ? `$env:Path = "$(${binCmd});$env:Path"`
+    : pm === 'npm'
+      ? `export PATH="$(${binCmd})/bin:$PATH"`
+      : `export PATH="$(${binCmd}):$PATH"`;
+  const rcLabel = isWindows ? 'PowerShell profile' : 'shell rc';
+
+  emit(
+    renderBox([
+      warningHeading('New kimi is installed, but your terminal can\'t find it'),
+      '',
+      pad('   The old kimi is still here:'),
+      pathInBox(detection.shimPath),
+      '',
+      pad('   The new kimi was installed by ' + pm + ', but it landed in a'),
+      pad('   folder your terminal doesn\'t search. (Your terminal looks'),
+      pad('   for commands in folders listed in your PATH.) If we removed'),
+      pad('   the old kimi now, typing `kimi` wouldn\'t find anything.'),
+      '',
+      pad('   Add the new kimi\'s folder to your PATH (and save the change'),
+      pad('   in your ' + rcLabel + ' so it sticks), then install again:'),
+      pathInBox(newPathHint),
+      pathInBox(reinstallCmd),
+      '',
+      pad('   The old kimi is still where it was.'),
+    ]),
+  );
+}
diff --git a/apps/kimi-code/scripts/smoke.mjs b/apps/kimi-code/scripts/smoke.mjs
new file mode 100644
index 000000000..9c64dd80d
--- /dev/null
+++ b/apps/kimi-code/scripts/smoke.mjs
@@ -0,0 +1,58 @@
+import { execFile } from 'node:child_process';
+import { readFile, stat } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const appRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const bundlePath = resolve(appRoot, 'dist', 'main.mjs');
+const packageJson = JSON.parse(await readFile(resolve(appRoot, 'package.json'), 'utf-8'));
+const expectedVersion = packageJson.version;
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+async function ensureBundleExists() {
+  try {
+    await stat(bundlePath);
+  } catch {
+    fail(`Bundle not found at ${bundlePath}. Run \`pnpm build\` first.`);
+  }
+}
+
+async function runBundle(args) {
+  try {
+    const { stdout, stderr } = await execFileAsync(process.execPath, [bundlePath, ...args], {
+      cwd: appRoot,
+      maxBuffer: 1024 * 1024 * 16,
+    });
+    return `${stdout}${stderr}`;
+  } catch (error) {
+    const detail = [error.stdout?.trim(), error.stderr?.trim(), error.message]
+      .filter(Boolean)
+      .join('\n');
+    fail(`Bundle smoke failed: node ${bundlePath} ${args.join(' ')}\n${detail}`);
+  }
+}
+
+function assertIncludes(output, expected, command) {
+  if (!output.includes(expected)) {
+    fail(`Bundle smoke output for "${command}" did not include "${expected}".\n${output}`);
+  }
+}
+
+await ensureBundleExists();
+
+const versionOutput = await runBundle(['--version']);
+assertIncludes(versionOutput, expectedVersion, '--version');
+
+const helpOutput = await runBundle(['--help']);
+assertIncludes(helpOutput, 'Usage: kimi', '--help');
+
+const exportHelpOutput = await runBundle(['export', '--help']);
+assertIncludes(exportHelpOutput, 'Usage: kimi export', 'export --help');
+
+console.log(`Bundle smoke passed: ${bundlePath}`);
diff --git a/apps/kimi-code/src/cli/build-info.ts b/apps/kimi-code/src/cli/build-info.ts
new file mode 100644
index 000000000..56c89a5b8
--- /dev/null
+++ b/apps/kimi-code/src/cli/build-info.ts
@@ -0,0 +1,34 @@
+declare const __KIMI_CODE_VERSION__: string | undefined;
+declare const __KIMI_CODE_CHANNEL__: string | undefined;
+declare const __KIMI_CODE_COMMIT__: string | undefined;
+declare const __KIMI_CODE_BUILD_TARGET__: string | undefined;
+
+export interface KimiBuildInfo {
+  readonly version?: string;
+  readonly channel?: string;
+  readonly commit?: string;
+  readonly buildTarget?: string;
+}
+
+function optionalBuildString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+export const KIMI_BUILD_INFO: KimiBuildInfo = {
+  version:
+    typeof __KIMI_CODE_VERSION__ === 'string'
+      ? optionalBuildString(__KIMI_CODE_VERSION__)
+      : undefined,
+  channel:
+    typeof __KIMI_CODE_CHANNEL__ === 'string'
+      ? optionalBuildString(__KIMI_CODE_CHANNEL__)
+      : undefined,
+  commit:
+    typeof __KIMI_CODE_COMMIT__ === 'string'
+      ? optionalBuildString(__KIMI_CODE_COMMIT__)
+      : undefined,
+  buildTarget:
+    typeof __KIMI_CODE_BUILD_TARGET__ === 'string'
+      ? optionalBuildString(__KIMI_CODE_BUILD_TARGET__)
+      : undefined,
+};
diff --git a/apps/kimi-code/src/cli/commands.ts b/apps/kimi-code/src/cli/commands.ts
new file mode 100644
index 000000000..b0a65f257
--- /dev/null
+++ b/apps/kimi-code/src/cli/commands.ts
@@ -0,0 +1,98 @@
+import { Command, Option } from 'commander';
+
+import { CLI_COMMAND_NAME } from '#/constant/app';
+
+import { registerMigrateCommand } from '#/migration/index';
+
+import type { CLIOptions } from './options';
+import { registerExportCommand } from './sub/export';
+
+export type MainCommandHandler = (opts: CLIOptions) => void;
+export type MigrateCommandHandler = () => void;
+
+export function createProgram(
+  version: string,
+  onMain: MainCommandHandler,
+  onMigrate: MigrateCommandHandler,
+): Command {
+  const program = new Command(CLI_COMMAND_NAME)
+    .description('The Starting Point for Next-Gen Agents')
+    .version(version, '-V, --version')
+    .allowUnknownOption(false)
+    .configureHelp({ helpWidth: 100 })
+    .helpOption('-h, --help', 'Show help.')
+    .addHelpText(
+      'after',
+      '\nDocumentation:        https://moonshotai.github.io/kimi-code/\n'
+    );
+
+  program
+    .addOption(
+      new Option(
+        '-S, --session [id]',
+        'Resume a session. With ID: resume that session. Without ID: interactively pick.',
+      ).argParser((val: string | boolean) => (val === true ? '' : (val as string))),
+    )
+    .addOption(
+      new Option('-r, --resume [id]')
+        .hideHelp()
+        .argParser((val: string | boolean) => (val === true ? '' : (val as string))),
+    )
+    .option('-C, --continue', 'Continue the previous session for the working directory.', false)
+    .option('-y, --yolo', 'Automatically approve all actions.', false)
+    .addOption(
+      new Option(
+        '-m, --model <model>',
+        'LLM model alias to use for this invocation. Defaults to default_model in config.toml.',
+      ),
+    )
+    .addOption(
+      new Option(
+        '-p, --prompt <prompt>',
+        'Run one prompt non-interactively and print the response.',
+      ),
+    )
+    .addOption(
+      new Option(
+        '--output-format <format>',
+        'Output format for prompt mode. Defaults to text.',
+      ).choices(['text', 'stream-json']),
+    )
+    .addOption(
+      new Option(
+        '--skills-dir <dir>',
+        'Load skills from this directory instead of auto-discovered user and project directories. Can be repeated.',
+      )
+        .argParser((value: string, previous: string[] | undefined) => [...(previous ?? []), value])
+        .default([]),
+    )
+    .addOption(new Option('--yes').hideHelp().default(false))
+    .addOption(new Option('--auto-approve').hideHelp().default(false))
+    .option('--plan', 'Start in plan mode.', false);
+
+  registerExportCommand(program);
+  registerMigrateCommand(program, onMigrate);
+
+  program.action(() => {
+    const raw = program.opts<Record<string, unknown>>();
+
+    const rawSession = raw['session'] ?? raw['resume'];
+    const sessionValue = rawSession === true ? '' : (rawSession as string | undefined);
+    const yoloValue = raw['yolo'] === true || raw['yes'] === true || raw['autoApprove'] === true;
+
+    const opts: CLIOptions = {
+      session: sessionValue,
+      continue: raw['continue'] as boolean,
+      yolo: yoloValue,
+      plan: raw['plan'] as boolean,
+      model: raw['model'] as string | undefined,
+      outputFormat: raw['outputFormat'] as CLIOptions['outputFormat'],
+      prompt: raw['prompt'] as string | undefined,
+      skillsDirs: raw['skillsDir'] as string[],
+    };
+
+    onMain(opts);
+  });
+
+  return program;
+}
diff --git a/apps/kimi-code/src/cli/options.ts b/apps/kimi-code/src/cli/options.ts
new file mode 100644
index 000000000..67bc86d4f
--- /dev/null
+++ b/apps/kimi-code/src/cli/options.ts
@@ -0,0 +1,58 @@
+export type UIMode = 'shell' | 'print';
+export type PromptOutputFormat = 'text' | 'stream-json';
+
+export interface CLIOptions {
+  session: string | undefined;
+  continue: boolean;
+  yolo: boolean;
+  plan: boolean;
+  model: string | undefined;
+  outputFormat: PromptOutputFormat | undefined;
+  prompt: string | undefined;
+  skillsDirs: string[];
+}
+
+export interface ValidatedOptions {
+  options: CLIOptions;
+  uiMode: UIMode;
+}
+
+export class OptionConflictError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'OptionConflictError';
+  }
+}
+
+export function validateOptions(opts: CLIOptions): ValidatedOptions {
+  const prompt = opts.prompt;
+  const promptMode = prompt !== undefined;
+  if (promptMode && prompt.trim().length === 0) {
+    throw new OptionConflictError('Prompt cannot be empty.');
+  }
+  if (opts.model !== undefined && opts.model.trim().length === 0) {
+    throw new OptionConflictError('Model cannot be empty.');
+  }
+  if (!promptMode && opts.outputFormat !== undefined) {
+    throw new OptionConflictError('Output format is only supported in prompt mode.');
+  }
+  if (promptMode && opts.yolo) {
+    throw new OptionConflictError('Cannot combine --prompt with --yolo.');
+  }
+  if (promptMode && opts.plan) {
+    throw new OptionConflictError('Cannot combine --prompt with --plan.');
+  }
+  if (promptMode && opts.session === '') {
+    throw new OptionConflictError('Cannot use --session without an id in prompt mode.');
+  }
+  if (opts.continue && opts.session !== undefined) {
+    throw new OptionConflictError('Cannot combine --continue, --session.');
+  }
+  if (!promptMode && (opts.continue || opts.session !== undefined) && opts.yolo) {
+    throw new OptionConflictError('Cannot combine --yolo with --continue or --session.');
+  }
+  if (!promptMode && (opts.continue || opts.session !== undefined) && opts.plan) {
+    throw new OptionConflictError('Cannot combine --plan with --continue or --session.');
+  }
+  return { options: opts, uiMode: promptMode ? 'print' : 'shell' };
+}
diff --git a/apps/kimi-code/src/cli/run-prompt.ts b/apps/kimi-code/src/cli/run-prompt.ts
new file mode 100644
index 000000000..806d60a6d
--- /dev/null
+++ b/apps/kimi-code/src/cli/run-prompt.ts
@@ -0,0 +1,673 @@
+import { createKimiDeviceId, KIMI_CODE_PROVIDER_NAME } from '@moonshot-ai/kimi-code-oauth';
+import {
+  initializeTelemetry,
+  setCrashPhase,
+  setTelemetryContext,
+  shutdownTelemetry,
+  track,
+  withTelemetryContext,
+} from '@moonshot-ai/kimi-telemetry';
+import {
+  KimiHarness,
+  log,
+  type Event,
+  type HookResultEvent,
+  type Session,
+  type SessionStatus,
+  type TelemetryClient,
+} from '@moonshot-ai/kimi-code-sdk';
+
+import { CLI_SHUTDOWN_TIMEOUT_MS, CLI_USER_AGENT_PRODUCT } from '#/constant/app';
+
+import type { CLIOptions, PromptOutputFormat } from './options';
+import { createKimiCodeHostIdentity } from './version';
+
+interface PromptOutput {
+  readonly columns?: number | undefined;
+  write(chunk: string): boolean;
+}
+
+interface PromptRunIO {
+  readonly stdout?: PromptOutput;
+  readonly stderr?: PromptOutput;
+  readonly process?: PromptProcess;
+}
+
+interface PromptProcess {
+  once(signal: NodeJS.Signals, listener: () => Promise<void>): unknown;
+  off(signal: NodeJS.Signals, listener: () => Promise<void>): unknown;
+  exit(code?: number): never | void;
+}
+
+const PROMPT_UI_MODE = 'print';
+const PROMPT_MAIN_AGENT_ID = 'main';
+const PROMPT_BLOCK_BULLET = '• ';
+const PROMPT_BLOCK_INDENT = '  ';
+
+export async function runPrompt(
+  opts: CLIOptions,
+  version: string,
+  io: PromptRunIO = {},
+): Promise<void> {
+  const startedAt = Date.now();
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  const promptProcess = io.process ?? process;
+  const workDir = process.cwd();
+  const telemetryClient: TelemetryClient = {
+    track,
+    withContext: withTelemetryContext,
+    setContext: setTelemetryContext,
+  };
+  const harness = new KimiHarness({
+    identity: createKimiCodeHostIdentity(version),
+    uiMode: PROMPT_UI_MODE,
+    skillDirs: opts.skillsDirs,
+    telemetry: telemetryClient,
+    onOAuthRefresh: (outcome) => {
+      if (outcome.success) {
+        track('oauth_refresh', { success: true });
+        return;
+      }
+      track('oauth_refresh', { success: false, reason: outcome.reason });
+    },
+  });
+  log.info('kimi-code starting', {
+    version,
+    uiMode: PROMPT_UI_MODE,
+    nodeVersion: process.version,
+    platform: `${process.platform}/${process.arch}`,
+    workDir,
+  });
+  let restorePromptSessionPermission = async (): Promise<void> => {};
+  let removeTerminationCleanup: (() => void) | undefined;
+  let cleanupPromise: Promise<void> | undefined;
+  const cleanupPromptRun = async (): Promise<void> => {
+    cleanupPromise ??= (async () => {
+      removeTerminationCleanup?.();
+      setCrashPhase('shutdown');
+      try {
+        await restorePromptSessionPermission();
+      } finally {
+        await shutdownTelemetry({ timeoutMs: CLI_SHUTDOWN_TIMEOUT_MS });
+        await harness.close();
+      }
+    })();
+    await cleanupPromise;
+  };
+  removeTerminationCleanup = installPromptTerminationCleanup(promptProcess, cleanupPromptRun);
+
+  try {
+    await harness.ensureConfigFile();
+    const config = await harness.getConfig();
+    const { session, resumed, restorePermission, telemetryModel } = await resolvePromptSession(
+      harness,
+      opts,
+      workDir,
+      config.defaultModel,
+      stderr,
+      (restorePermission) => {
+        restorePromptSessionPermission = restorePermission;
+      },
+    );
+    restorePromptSessionPermission = restorePermission;
+
+    const deviceId = createKimiDeviceId(harness.homeDir);
+    initializeTelemetry({
+      homeDir: harness.homeDir,
+      deviceId,
+      enabled: config.telemetry !== false,
+      appName: CLI_USER_AGENT_PRODUCT,
+      version,
+      uiMode: PROMPT_UI_MODE,
+      model: telemetryModel,
+      getAccessToken: async () =>
+        (await harness.auth.getCachedAccessToken(KIMI_CODE_PROVIDER_NAME)) ?? null,
+    });
+    setCrashPhase('runtime');
+
+    withTelemetryContext({ sessionId: session.id }).track('started', {
+      resumed,
+      yolo: false,
+      plan: false,
+      afk: true,
+    });
+
+    await runPromptTurn(session, opts.prompt!, opts.outputFormat ?? 'text', stdout, stderr);
+    stderr.write(`To resume this session: kimi -r ${session.id}\n`);
+
+    withTelemetryContext({ sessionId: session.id }).track('exit', {
+      duration_s: (Date.now() - startedAt) / 1000,
+    });
+  } finally {
+    await cleanupPromptRun();
+  }
+}
+
+interface ResolvedPromptSession {
+  readonly session: Session;
+  readonly resumed: boolean;
+  readonly restorePermission: () => Promise<void>;
+  readonly telemetryModel?: string;
+}
+
+async function resolvePromptSession(
+  harness: KimiHarness,
+  opts: CLIOptions,
+  workDir: string,
+  defaultModel: string | undefined,
+  stderr: PromptOutput,
+  setRestorePermission: (restorePermission: () => Promise<void>) => void,
+): Promise<ResolvedPromptSession> {
+  if (opts.session !== undefined) {
+    const session = await harness.resumeSession({ id: opts.session });
+    const status = await session.getStatus();
+    const restorePermission = await forcePromptPermission(
+      session,
+      status.permission,
+      setRestorePermission,
+    );
+    if (opts.model !== undefined) {
+      await session.setModel(opts.model);
+    }
+    installHeadlessHandlers(session);
+    return {
+      session,
+      resumed: true,
+      restorePermission,
+      telemetryModel: configuredModel(opts.model, status.model, defaultModel),
+    };
+  }
+
+  if (opts.continue) {
+    const sessions = await harness.listSessions({ workDir });
+    const previous = sessions[0];
+    if (previous !== undefined) {
+      const session = await harness.resumeSession({ id: previous.id });
+      const status = await session.getStatus();
+      const restorePermission = await forcePromptPermission(
+        session,
+        status.permission,
+        setRestorePermission,
+      );
+      if (opts.model !== undefined) {
+        await session.setModel(opts.model);
+      }
+      installHeadlessHandlers(session);
+      return {
+        session,
+        resumed: true,
+        restorePermission,
+        telemetryModel: configuredModel(opts.model, status.model, defaultModel),
+      };
+    }
+    stderr.write(`No sessions to continue under "${workDir}"; starting a fresh session.\n`);
+  }
+
+  const model = requireConfiguredModel(opts.model, defaultModel);
+  const session = await harness.createSession({ workDir, model, permission: 'auto' });
+  installHeadlessHandlers(session);
+  return { session, resumed: false, restorePermission: async () => {}, telemetryModel: model };
+}
+
+async function forcePromptPermission(
+  session: Session,
+  previousPermission: SessionStatus['permission'],
+  setRestorePermission: (restorePermission: () => Promise<void>) => void,
+): Promise<() => Promise<void>> {
+  let overridePermission: Promise<void> | undefined;
+  const restorePermission = async () => {
+    await overridePermission?.catch(() => {});
+    if (previousPermission !== 'auto') {
+      await session.setPermission(previousPermission);
+    }
+  };
+  setRestorePermission(restorePermission);
+  if (previousPermission !== 'auto') {
+    overridePermission = session.setPermission('auto');
+    await overridePermission;
+  }
+  return restorePermission;
+}
+
+function requireConfiguredModel(...models: readonly (string | undefined)[]): string {
+  const model = configuredModel(...models);
+  if (model === undefined) {
+    throw new Error('No model configured. Set default_model in config.toml.');
+  }
+  return model;
+}
+
+function configuredModel(...models: readonly (string | undefined)[]): string | undefined {
+  return models.find((model) => model !== undefined && model.trim().length > 0);
+}
+
+function installHeadlessHandlers(session: Session): void {
+  session.setApprovalHandler(() => ({ decision: 'approved' }));
+  session.setQuestionHandler(() => null);
+}
+
+function installPromptTerminationCleanup(
+  promptProcess: PromptProcess,
+  cleanup: () => Promise<void>,
+): () => void {
+  let terminating = false;
+  const exitAfterCleanup = async (signal: NodeJS.Signals): Promise<void> => {
+    if (terminating) return;
+    terminating = true;
+    try {
+      await cleanup();
+    } finally {
+      promptProcess.exit(signalExitCode(signal));
+    }
+  };
+  const onSigint = () => exitAfterCleanup('SIGINT');
+  const onSigterm = () => exitAfterCleanup('SIGTERM');
+  promptProcess.once('SIGINT', onSigint);
+  promptProcess.once('SIGTERM', onSigterm);
+  return () => {
+    promptProcess.off('SIGINT', onSigint);
+    promptProcess.off('SIGTERM', onSigterm);
+  };
+}
+
+function signalExitCode(signal: NodeJS.Signals): number {
+  return signal === 'SIGINT' ? 130 : 143;
+}
+
+function runPromptTurn(
+  session: Session,
+  prompt: string,
+  outputFormat: PromptOutputFormat,
+  stdout: PromptOutput,
+  stderr: PromptOutput,
+): Promise<void> {
+  let activeTurnId: number | undefined;
+  let activeAgentId: string | undefined;
+  const outputWriter =
+    outputFormat === 'stream-json'
+      ? new PromptJsonWriter(stdout)
+      : new PromptTranscriptWriter(stdout, stderr);
+  let settled = false;
+  let unsubscribe: (() => void) | undefined;
+
+  return new Promise<void>((resolve, reject) => {
+    const finish = (error?: Error): void => {
+      if (settled) return;
+      settled = true;
+      unsubscribe?.();
+      outputWriter.finish();
+      if (error !== undefined) {
+        reject(error);
+        return;
+      }
+      resolve();
+    };
+
+    unsubscribe = session.onEvent((event) => {
+      if (event.type === 'error') {
+        if (event.agentId !== PROMPT_MAIN_AGENT_ID) {
+          return;
+        }
+        finish(new Error(`${event.code}: ${event.message}`));
+        return;
+      }
+      if (event.type === 'turn.started' && activeTurnId === undefined) {
+        if (event.agentId !== PROMPT_MAIN_AGENT_ID) {
+          return;
+        }
+        activeTurnId = event.turnId;
+        activeAgentId = event.agentId;
+        return;
+      }
+      if (
+        activeTurnId === undefined ||
+        activeAgentId === undefined ||
+        !hasTurnId(event) ||
+        event.turnId !== activeTurnId ||
+        event.agentId !== activeAgentId
+      ) {
+        return;
+      }
+      switch (event.type) {
+        case 'turn.step.started':
+        case 'turn.step.interrupted':
+          outputWriter.flushAssistant();
+          return;
+        case 'turn.step.retrying':
+          outputWriter.discardAssistant();
+          return;
+        case 'assistant.delta':
+          outputWriter.writeAssistantDelta(event.delta);
+          return;
+        case 'hook.result':
+          outputWriter.writeHookResult(event);
+          return;
+        case 'thinking.delta':
+          outputWriter.writeThinkingDelta(event.delta);
+          return;
+        case 'tool.call.started':
+          outputWriter.writeToolCall(event.toolCallId, event.name, event.args);
+          return;
+        case 'tool.call.delta':
+          outputWriter.writeToolCallDelta(event.toolCallId, event.name, event.argumentsPart);
+          return;
+        case 'tool.result':
+          outputWriter.writeToolResult(event.toolCallId, event.output);
+          return;
+        case 'tool.progress':
+          if (event.update.text !== undefined && event.update.text.length > 0) {
+            stderr.write(
+              event.update.text.endsWith('\n') ? event.update.text : `${event.update.text}\n`,
+            );
+          }
+          return;
+        case 'turn.ended':
+          if (event.reason === 'completed') {
+            finish();
+            return;
+          }
+          finish(new Error(formatTurnEndedFailure(event)));
+          return;
+        case 'agent.status.updated':
+        case 'background.task.started':
+        case 'background.task.terminated':
+        case 'background.task.updated':
+        case 'compaction.blocked':
+        case 'compaction.cancelled':
+        case 'compaction.completed':
+        case 'compaction.started':
+        case 'mcp.server.status':
+        case 'session.meta.updated':
+        case 'skill.activated':
+        case 'subagent.completed':
+        case 'subagent.failed':
+        case 'subagent.spawned':
+        case 'tool.list.updated':
+        case 'turn.started':
+        case 'turn.step.completed':
+          return;
+      }
+    });
+
+    session.prompt(prompt).catch((error: unknown) => {
+      finish(error instanceof Error ? error : new Error(String(error)));
+    });
+  });
+}
+
+interface PromptTurnWriter {
+  writeAssistantDelta(delta: string): void;
+  writeHookResult(event: HookResultEvent): void;
+  writeThinkingDelta(delta: string): void;
+  writeToolCall(toolCallId: string, name: string, args: unknown): void;
+  writeToolCallDelta(
+    toolCallId: string,
+    name: string | undefined,
+    argumentsPart: string | undefined,
+  ): void;
+  writeToolResult(toolCallId: string, output: unknown): void;
+  flushAssistant(): void;
+  discardAssistant(): void;
+  finish(): void;
+}
+
+class PromptTranscriptWriter implements PromptTurnWriter {
+  private readonly assistantWriter: PromptBlockWriter;
+  private readonly thinkingWriter: PromptBlockWriter;
+
+  constructor(stdout: PromptOutput, stderr: PromptOutput) {
+    this.assistantWriter = new PromptBlockWriter(stdout);
+    this.thinkingWriter = new PromptBlockWriter(stderr);
+  }
+
+  writeAssistantDelta(delta: string): void {
+    this.thinkingWriter.finish();
+    this.assistantWriter.write(delta);
+  }
+
+  writeHookResult(event: HookResultEvent): void {
+    this.thinkingWriter.finish();
+    this.assistantWriter.finish();
+    this.assistantWriter.write(formatHookResultPlain(event));
+    this.assistantWriter.finish();
+  }
+
+  writeThinkingDelta(delta: string): void {
+    this.thinkingWriter.write(delta);
+  }
+
+  writeToolCall(): void {}
+
+  writeToolCallDelta(): void {}
+
+  writeToolResult(): void {}
+
+  flushAssistant(): void {}
+
+  discardAssistant(): void {}
+
+  finish(): void {
+    this.thinkingWriter.finish();
+    this.assistantWriter.finish();
+  }
+}
+
+interface PromptJsonToolCall {
+  type: 'function';
+  id: string;
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+
+interface PromptJsonAssistantMessage {
+  role: 'assistant';
+  content?: string;
+  tool_calls?: PromptJsonToolCall[];
+}
+
+interface PromptJsonToolMessage {
+  role: 'tool';
+  tool_call_id: string;
+  content: string;
+}
+
+class PromptJsonWriter implements PromptTurnWriter {
+  private assistantText = '';
+  private readonly toolCalls: PromptJsonToolCall[] = [];
+
+  constructor(private readonly stdout: PromptOutput) {}
+
+  writeAssistantDelta(delta: string): void {
+    this.assistantText += delta;
+  }
+
+  writeHookResult(event: HookResultEvent): void {
+    this.flushAssistant();
+    this.writeJsonLine({
+      role: 'assistant',
+      content: formatHookResultPlain(event),
+    });
+  }
+
+  writeThinkingDelta(): void {}
+
+  writeToolCall(toolCallId: string, name: string, args: unknown): void {
+    const existing = this.toolCalls.find((toolCall) => toolCall.id === toolCallId);
+    if (existing !== undefined) {
+      existing.function.name = name;
+      existing.function.arguments = stringifyJsonValue(args);
+      return;
+    }
+    this.toolCalls.push({
+      type: 'function',
+      id: toolCallId,
+      function: {
+        name,
+        arguments: stringifyJsonValue(args),
+      },
+    });
+  }
+
+  writeToolCallDelta(
+    toolCallId: string,
+    name: string | undefined,
+    argumentsPart: string | undefined,
+  ): void {
+    const toolCall = this.findOrCreateToolCall(toolCallId, name ?? '');
+    if (name !== undefined) {
+      toolCall.function.name = name;
+    }
+    if (argumentsPart !== undefined) {
+      toolCall.function.arguments += argumentsPart;
+    }
+  }
+
+  writeToolResult(toolCallId: string, output: unknown): void {
+    this.flushAssistant();
+    this.writeJsonLine({
+      role: 'tool',
+      tool_call_id: toolCallId,
+      content: stringifyToolOutput(output),
+    });
+  }
+
+  flushAssistant(): void {
+    if (this.assistantText.length === 0 && this.toolCalls.length === 0) return;
+    const message: PromptJsonAssistantMessage = {
+      role: 'assistant',
+      content: this.assistantText.length > 0 ? this.assistantText : undefined,
+      tool_calls: this.toolCalls.length > 0 ? [...this.toolCalls] : undefined,
+    };
+    this.writeJsonLine(message);
+    this.discardAssistant();
+  }
+
+  discardAssistant(): void {
+    this.assistantText = '';
+    this.toolCalls.length = 0;
+  }
+
+  finish(): void {
+    this.flushAssistant();
+  }
+
+  private findOrCreateToolCall(toolCallId: string, name: string): PromptJsonToolCall {
+    const existing = this.toolCalls.find((toolCall) => toolCall.id === toolCallId);
+    if (existing !== undefined) return existing;
+    const toolCall: PromptJsonToolCall = {
+      type: 'function',
+      id: toolCallId,
+      function: {
+        name,
+        arguments: '',
+      },
+    };
+    this.toolCalls.push(toolCall);
+    return toolCall;
+  }
+
+  private writeJsonLine(message: PromptJsonAssistantMessage | PromptJsonToolMessage): void {
+    this.stdout.write(`${JSON.stringify(message)}\n`);
+  }
+}
+
+class PromptBlockWriter {
+  private started = false;
+  private atLineStart = false;
+  private lineWidth = 0;
+  private readonly wrapWidth: number | undefined;
+
+  constructor(private readonly output: PromptOutput) {
+    this.wrapWidth =
+      typeof output.columns === 'number' && output.columns > PROMPT_BLOCK_INDENT.length + 1
+        ? output.columns
+        : undefined;
+  }
+
+  write(chunk: string): void {
+    if (chunk.length === 0) return;
+    let rendered = this.start();
+    for (const char of chunk) {
+      if (this.atLineStart && char !== '\n') {
+        rendered += PROMPT_BLOCK_INDENT;
+        this.atLineStart = false;
+        this.lineWidth = PROMPT_BLOCK_INDENT.length;
+      }
+      const charWidth = visibleCharWidth(char);
+      if (
+        this.wrapWidth !== undefined &&
+        !this.atLineStart &&
+        char !== '\n' &&
+        this.lineWidth + charWidth > this.wrapWidth
+      ) {
+        rendered += `\n${PROMPT_BLOCK_INDENT}`;
+        this.lineWidth = PROMPT_BLOCK_INDENT.length;
+      }
+      rendered += char;
+      if (char === '\n') {
+        this.atLineStart = true;
+        this.lineWidth = 0;
+      } else {
+        this.lineWidth += charWidth;
+      }
+    }
+    this.output.write(rendered);
+  }
+
+  finish(): void {
+    if (!this.started) return;
+    this.output.write(this.atLineStart ? '\n' : '\n\n');
+    this.started = false;
+    this.atLineStart = false;
+    this.lineWidth = 0;
+  }
+
+  private start(): string {
+    if (this.started) return '';
+    this.started = true;
+    this.atLineStart = false;
+    this.lineWidth = PROMPT_BLOCK_BULLET.length;
+    return PROMPT_BLOCK_BULLET;
+  }
+}
+
+function visibleCharWidth(char: string): number {
+  return char === '\t' ? 4 : 1;
+}
+
+function formatHookResultPlain(event: HookResultEvent): string {
+  return `${formatHookResultTitle(event)}\n\n${formatHookResultBody(event)}`;
+}
+
+function formatHookResultTitle(event: HookResultEvent): string {
+  return `${event.hookEvent} hook${event.blocked === true ? ' blocked' : ''}`;
+}
+
+function formatHookResultBody(event: HookResultEvent): string {
+  const content = event.content.trim();
+  return content.length === 0 ? '(empty)' : content;
+}
+
+function stringifyJsonValue(value: unknown): string {
+  if (typeof value === 'string') return value;
+  const json = JSON.stringify(value);
+  return json ?? '';
+}
+
+function stringifyToolOutput(output: unknown): string {
+  if (typeof output === 'string') return output;
+  const json = JSON.stringify(output);
+  return json ?? String(output);
+}
+
+function hasTurnId(event: Event): event is Event & { readonly turnId: number } {
+  return 'turnId' in event;
+}
+
+function formatTurnEndedFailure(event: Extract<Event, { type: 'turn.ended' }>): string {
+  if (event.error !== undefined) return `${event.error.code}: ${event.error.message}`;
+  return `Prompt turn ended with reason: ${event.reason}`;
+}
diff --git a/apps/kimi-code/src/cli/run-shell.ts b/apps/kimi-code/src/cli/run-shell.ts
new file mode 100644
index 000000000..6e3e3204b
--- /dev/null
+++ b/apps/kimi-code/src/cli/run-shell.ts
@@ -0,0 +1,180 @@
+import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { createKimiDeviceId, KIMI_CODE_PROVIDER_NAME } from '@moonshot-ai/kimi-code-oauth';
+import {
+  initializeTelemetry,
+  setCrashPhase,
+  setTelemetryContext,
+  shutdownTelemetry,
+  track,
+  withTelemetryContext,
+} from '@moonshot-ai/kimi-telemetry';
+import { KimiHarness, log, type TelemetryClient } from '@moonshot-ai/kimi-code-sdk';
+
+import { CLI_SHUTDOWN_TIMEOUT_MS, CLI_UI_MODE, CLI_USER_AGENT_PRODUCT } from '#/constant/app';
+import { detectPendingMigration } from '#/migration/index';
+import type { TuiConfig } from '#/tui/config';
+import { loadTuiConfig, TuiConfigParseError } from '#/tui/config';
+import { CHROME_GUTTER } from '#/tui/constant/rendering';
+import { KimiTUI } from '#/tui/index';
+import { detectTerminalTheme } from '#/tui/theme/detect';
+
+import type { CLIOptions } from './options';
+import { createKimiCodeHostIdentity } from './version';
+
+export async function runShell(
+  opts: CLIOptions,
+  version: string,
+  runOptions: { readonly migrateOnly?: boolean } = {},
+): Promise<void> {
+  const startedAt = Date.now();
+  const configStartedAt = startedAt;
+  let tuiConfig: TuiConfig;
+  let configWarning: string | undefined;
+  try {
+    tuiConfig = await loadTuiConfig();
+  } catch (error) {
+    if (!(error instanceof TuiConfigParseError)) throw error;
+    tuiConfig = error.fallback;
+    configWarning = error.message;
+  }
+
+  // Resolve `theme = "auto"` against the live terminal once, before pi-tui
+  // grabs stdin. Explicit `dark` / `light` skip detection.
+  const resolvedTheme = tuiConfig.theme === 'auto' ? await detectTerminalTheme() : tuiConfig.theme;
+
+  const workDir = process.cwd();
+  const telemetryClient: TelemetryClient = {
+    track,
+    withContext: withTelemetryContext,
+    setContext: setTelemetryContext,
+  };
+  const harness = new KimiHarness({
+    identity: createKimiCodeHostIdentity(version),
+    telemetry: telemetryClient,
+    onOAuthRefresh: (outcome) => {
+      if (outcome.success) {
+        track('oauth_refresh', { success: true });
+        return;
+      }
+      track('oauth_refresh', {
+        success: false,
+        reason: outcome.reason,
+      });
+    },
+  });
+  log.info('kimi-code starting', {
+    version,
+    uiMode: CLI_UI_MODE,
+    nodeVersion: process.version,
+    platform: `${process.platform}/${process.arch}`,
+    workDir,
+  });
+  await harness.ensureConfigFile();
+  const migrationPlan = await detectPendingMigration({
+    sourceHome: join(homedir(), '.kimi'),
+    targetHome: harness.homeDir,
+    ignoreMarker: runOptions.migrateOnly,
+  });
+  if (runOptions.migrateOnly === true && migrationPlan === null) {
+    process.stdout.write('  Nothing to migrate from ~/.kimi/.\n');
+    await harness.close();
+    return;
+  }
+  const config = await harness.getConfig();
+  const configMs = Date.now() - configStartedAt;
+  const tui = new KimiTUI(harness, {
+    cliOptions: opts,
+    tuiConfig,
+    version,
+    workDir,
+    startupNotice: configWarning,
+    resolvedTheme,
+    migrationPlan,
+    migrateOnly: runOptions.migrateOnly,
+  });
+
+  let firstLaunch = false;
+  const deviceId = createKimiDeviceId(harness.homeDir, {
+    onFirstLaunch: () => {
+      firstLaunch = true;
+    },
+  });
+  initializeTelemetry({
+    homeDir: harness.homeDir,
+    deviceId,
+    enabled: config.telemetry !== false,
+    appName: CLI_USER_AGENT_PRODUCT,
+    version,
+    uiMode: CLI_UI_MODE,
+    model: config.defaultModel,
+    getAccessToken: async () =>
+      (await harness.auth.getCachedAccessToken(KIMI_CODE_PROVIDER_NAME)) ?? null,
+  });
+  setCrashPhase('runtime');
+
+  if (firstLaunch) {
+    harness.track('first_launch');
+  }
+  const resumed = opts.continue || opts.session !== undefined;
+  const trackLifecycleForSession = (
+    sessionId: string,
+    event: string,
+    properties?: Parameters<KimiHarness['track']>[1],
+  ) => {
+    if (sessionId.length === 0) {
+      harness.track(event, properties);
+      return;
+    }
+    withTelemetryContext({ sessionId }).track(event, properties);
+  };
+  const trackLifecycle = (event: string, properties?: Parameters<KimiHarness['track']>[1]) => {
+    trackLifecycleForSession(tui.getCurrentSessionId(), event, properties);
+  };
+
+  tui.onExit = async (exitCode = 0) => {
+    const sessionId = tui.getCurrentSessionId();
+    const hasContent = tui.hasSessionContent();
+    setCrashPhase('shutdown');
+    trackLifecycle('exit', { duration_s: (Date.now() - startedAt) / 1000 });
+    await shutdownTelemetry({ timeoutMs: CLI_SHUTDOWN_TIMEOUT_MS });
+    const gutter = ' '.repeat(CHROME_GUTTER);
+    process.stdout.write(`${gutter}Bye!\n`);
+    if (sessionId !== '' && hasContent) {
+      process.stderr.write(`\n${gutter}To resume this session: kimi -r ${sessionId}\n`);
+    }
+    process.exit(exitCode);
+  };
+  try {
+    execSync('stty -ixon', { stdio: 'ignore' });
+  } catch {
+    /* ignore */
+  }
+  try {
+    const initStartedAt = Date.now();
+    await tui.start();
+    const initMs = Date.now() - initStartedAt;
+    trackLifecycle('started', {
+      resumed,
+      yolo: opts.yolo,
+      plan: opts.plan,
+      afk: false,
+    });
+    const startupSessionId = tui.getCurrentSessionId();
+    const mcpMs = await tui.getStartupMcpMs();
+    trackLifecycleForSession(startupSessionId, 'startup_perf', {
+      duration_ms: Date.now() - startedAt,
+      config_ms: configMs,
+      init_ms: initMs,
+      mcp_ms: mcpMs,
+    });
+  } catch (error) {
+    setCrashPhase('shutdown');
+    trackLifecycle('exit', { duration_s: (Date.now() - startedAt) / 1000 });
+    await shutdownTelemetry({ timeoutMs: CLI_SHUTDOWN_TIMEOUT_MS });
+    await harness.close();
+    throw error;
+  }
+}
diff --git a/apps/kimi-code/src/cli/startup-error.ts b/apps/kimi-code/src/cli/startup-error.ts
new file mode 100644
index 000000000..b40b714f2
--- /dev/null
+++ b/apps/kimi-code/src/cli/startup-error.ts
@@ -0,0 +1,35 @@
+import { KIMI_ERROR_INFO, isKimiError } from '@moonshot-ai/kimi-code-sdk';
+import { chalkStderr } from 'chalk';
+
+import { STARTUP_ERROR_COLOR } from '#/constant/startup-error';
+
+export interface StartupErrorFormatOptions {
+  readonly errorStyle?: (text: string) => string;
+  readonly operation?: string;
+}
+
+function formatUnknownErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function formatStartupError(
+  error: unknown,
+  options: StartupErrorFormatOptions = {},
+): string {
+  const errorStyle = options.errorStyle ?? chalkStderr.hex(STARTUP_ERROR_COLOR);
+
+  if (!isKimiError(error)) {
+    const operation = options.operation ?? 'start shell';
+    return `${errorStyle(`error: failed to ${operation}: ${formatUnknownErrorMessage(error)}`)}\n`;
+  }
+
+  const info = KIMI_ERROR_INFO[error.code];
+  const lines = [
+    errorStyle(`error: ${info.title}`),
+    '',
+    errorStyle('message:'),
+    errorStyle(error.message),
+  ];
+
+  return `${lines.join('\n')}\n`;
+}
diff --git a/apps/kimi-code/src/cli/sub/export.ts b/apps/kimi-code/src/cli/sub/export.ts
new file mode 100644
index 000000000..93608cc3d
--- /dev/null
+++ b/apps/kimi-code/src/cli/sub/export.ts
@@ -0,0 +1,224 @@
+/**
+ * `kimi export` sub-command.
+ *
+ * CLI glue only: session lookup, previous-session confirmation, and output.
+ * The actual ZIP/manifest export is owned by the SDK.
+ */
+
+import { createInterface } from 'node:readline/promises';
+
+import { createKimiDeviceId, KIMI_CODE_PROVIDER_NAME } from '@moonshot-ai/kimi-code-oauth';
+import {
+  initializeTelemetry,
+  setTelemetryContext,
+  shutdownTelemetry,
+  track,
+  withTelemetryContext,
+} from '@moonshot-ai/kimi-telemetry';
+import {
+  KimiHarness,
+  type ExportSessionInput,
+  type ExportSessionResult,
+  type SessionSummary,
+  type TelemetryClient,
+} from '@moonshot-ai/kimi-code-sdk';
+import type { Command } from 'commander';
+
+import { CLI_SHUTDOWN_TIMEOUT_MS, CLI_UI_MODE, CLI_USER_AGENT_PRODUCT } from '#/constant/app';
+import { createKimiCodeHostIdentity } from '#/cli/version';
+
+interface WritableLike {
+  write(chunk: string): boolean;
+}
+
+export interface PreviousSessionSummary {
+  readonly workDir: string;
+  readonly sessionId: string;
+  readonly sessionDir: string;
+  readonly title?: string | undefined;
+}
+
+export interface ExportDeps {
+  readonly listSessions: (workDir: string) => Promise<readonly SessionSummary[]>;
+  readonly exportSession: (input: ExportSessionInput) => Promise<ExportSessionResult>;
+  readonly confirmPreviousSession: (summary: PreviousSessionSummary) => Promise<boolean>;
+  readonly version: string;
+  readonly cwd: () => string;
+  readonly stdout: WritableLike;
+  readonly stderr: WritableLike;
+  readonly exit: (code: number) => never;
+}
+
+export interface ExportOptions {
+  readonly yes: boolean;
+  readonly includeGlobalLog: boolean;
+}
+
+export async function handleExport(
+  deps: ExportDeps,
+  sessionId: string | undefined,
+  output: string | undefined,
+  opts: ExportOptions,
+): Promise<void> {
+  const requestedId = normalizeOptionalSessionId(sessionId);
+  const previousSummary = requestedId === undefined ? await findPreviousSession(deps) : undefined;
+
+  let resolvedId: string;
+  if (requestedId !== undefined) {
+    resolvedId = requestedId;
+  } else {
+    if (previousSummary === undefined) {
+      deps.stderr.write('No previous session found to export.\n');
+      deps.exit(1);
+    }
+    resolvedId = previousSummary.id;
+    if (!opts.yes) {
+      const confirmed = await deps.confirmPreviousSession(toPreviousSessionSummary(previousSummary));
+      if (!confirmed) {
+        deps.stdout.write('Export cancelled.\n');
+        return;
+      }
+    }
+  }
+
+  try {
+    const result = await deps.exportSession({
+      id: resolvedId,
+      version: deps.version,
+      ...(output === undefined ? {} : { outputPath: output }),
+      ...(opts.includeGlobalLog ? { includeGlobalLog: true } : {}),
+    });
+    deps.stdout.write(`${result.zipPath}\n`);
+  } catch (error) {
+    deps.stderr.write(`${errorMessage(error)}\n`);
+    deps.exit(1);
+  }
+}
+
+export function registerExportCommand(parent: Command, deps?: Partial<ExportDeps>): void {
+  parent
+    .command('export')
+    .description('Export a session as a ZIP archive.')
+    .option('-o, --output <path>', 'Output ZIP path.')
+    .option('-y, --yes', 'Skip previous-session confirmation.')
+    .option(
+      '--no-include-global-log',
+      'Skip bundling the active global diagnostic log (~/.kimi-code/logs/kimi-code.log, not rotated .1 files). By default the global log is included.',
+    )
+    .argument('[sessionId]', 'Session id to export. Defaults to the most recent session.')
+    .action(
+      async (
+        sessionId: string | undefined,
+        options: { output?: string; yes?: boolean; includeGlobalLog?: boolean },
+      ) => {
+        await handleExport(createDefaultExportDeps(deps), sessionId, options.output, {
+          yes: options.yes === true,
+          includeGlobalLog: options.includeGlobalLog !== false,
+        });
+      },
+    );
+}
+
+function createDefaultExportDeps(overrides: Partial<ExportDeps> = {}): ExportDeps {
+  let harness: KimiHarness | undefined;
+  let telemetryInitialized = false;
+  let telemetryShutdown = false;
+  const identity = createKimiCodeHostIdentity();
+  const telemetryClient: TelemetryClient = {
+    track,
+    withContext: withTelemetryContext,
+    setContext: setTelemetryContext,
+  };
+  const getHarness = (): KimiHarness => {
+    harness ??= new KimiHarness({
+      identity,
+      telemetry: telemetryClient,
+    });
+    return harness;
+  };
+  const initializeDefaultTelemetry = async (): Promise<void> => {
+    if (telemetryInitialized) return;
+    const currentHarness = getHarness();
+    await currentHarness.ensureConfigFile();
+    const config = await currentHarness.getConfig();
+    const deviceId = createKimiDeviceId(currentHarness.homeDir);
+    initializeTelemetry({
+      homeDir: currentHarness.homeDir,
+      deviceId,
+      enabled: config.telemetry !== false,
+      appName: CLI_USER_AGENT_PRODUCT,
+      version: identity.version,
+      uiMode: CLI_UI_MODE,
+      model: config.defaultModel,
+      getAccessToken: async () =>
+        (await currentHarness.auth.getCachedAccessToken(KIMI_CODE_PROVIDER_NAME)) ?? null,
+    });
+    telemetryInitialized = true;
+  };
+  const shutdownDefaultTelemetry = async (): Promise<void> => {
+    if (!telemetryInitialized || telemetryShutdown) return;
+    telemetryShutdown = true;
+    await shutdownTelemetry({ timeoutMs: CLI_SHUTDOWN_TIMEOUT_MS });
+  };
+  return {
+    listSessions:
+      overrides.listSessions ??
+      ((workDir: string) =>
+        getHarness().listSessions({
+          workDir,
+        })),
+    exportSession:
+      overrides.exportSession ??
+      (async (input: ExportSessionInput) => {
+        await initializeDefaultTelemetry();
+        try {
+          return await getHarness().exportSession(input);
+        } finally {
+          await shutdownDefaultTelemetry();
+        }
+      }),
+    version: overrides.version ?? identity.version,
+    confirmPreviousSession: overrides.confirmPreviousSession ?? confirmPreviousSession,
+    cwd: overrides.cwd ?? (() => process.cwd()),
+    stdout: overrides.stdout ?? process.stdout,
+    stderr: overrides.stderr ?? process.stderr,
+    exit: overrides.exit ?? ((code: number) => process.exit(code)),
+  };
+}
+
+async function findPreviousSession(deps: Pick<ExportDeps, 'cwd' | 'listSessions'>): Promise<
+  SessionSummary | undefined
+> {
+  const sessions = await deps.listSessions(deps.cwd());
+  return sessions[0];
+}
+
+function toPreviousSessionSummary(summary: SessionSummary): PreviousSessionSummary {
+  return {
+    workDir: summary.workDir,
+    sessionId: summary.id,
+    sessionDir: summary.sessionDir,
+    ...(summary.title === undefined ? {} : { title: summary.title }),
+  };
+}
+
+function normalizeOptionalSessionId(sessionId: string | undefined): string | undefined {
+  const trimmed = sessionId?.trim();
+  return trimmed === undefined || trimmed === '' ? undefined : trimmed;
+}
+
+async function confirmPreviousSession(summary: PreviousSessionSummary): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const title = summary.title === undefined ? summary.sessionId : `${summary.title} (${summary.sessionId})`;
+    const answer = await rl.question(`Export previous session "${title}"? [Y/n] `);
+    const trimmed = answer.trim().toLowerCase();
+    return trimmed === '' || trimmed === 'y' || trimmed === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
diff --git a/apps/kimi-code/src/cli/update/cache.ts b/apps/kimi-code/src/cli/update/cache.ts
new file mode 100644
index 000000000..83132bf36
--- /dev/null
+++ b/apps/kimi-code/src/cli/update/cache.ts
@@ -0,0 +1,31 @@
+import { z } from 'zod';
+
+import { getUpdateStateFile } from '#/utils/paths';
+import { readJsonFile, writeJsonFile } from '#/utils/persistence';
+
+import { emptyUpdateCache, type UpdateCache } from './types';
+
+const UpdateCacheSchema: z.ZodType<UpdateCache> = z
+  .object({
+    source: z.literal('cdn'),
+    checkedAt: z.string().min(1).nullable(),
+    latest: z.string().min(1).nullable(),
+  })
+  .strict();
+
+export async function readUpdateCache(
+  filePath: string = getUpdateStateFile(),
+): Promise<UpdateCache> {
+  try {
+    return await readJsonFile(filePath, UpdateCacheSchema, emptyUpdateCache());
+  } catch {
+    return emptyUpdateCache();
+  }
+}
+
+export async function writeUpdateCache(
+  value: UpdateCache,
+  filePath: string = getUpdateStateFile(),
+): Promise<void> {
+  await writeJsonFile(filePath, UpdateCacheSchema, value);
+}
diff --git a/apps/kimi-code/src/cli/update/cdn.ts b/apps/kimi-code/src/cli/update/cdn.ts
new file mode 100644
index 000000000..5664f021f
--- /dev/null
+++ b/apps/kimi-code/src/cli/update/cdn.ts
@@ -0,0 +1,27 @@
+import { valid } from 'semver';
+
+import { KIMI_CODE_CDN_LATEST_URL } from '#/constant/app';
+
+/**
+ * Fetch the latest published Kimi Code version from the CDN.
+ *
+ * **Throws** on any failure (network error, non-2xx, empty body, non-semver
+ * text). Callers must catch — `refreshUpdateCache` deliberately lets the
+ * error propagate so the existing cache stays intact instead of being
+ * overwritten with a null `latest` on a transient blip.
+ *
+ * `fetchImpl` is injectable for tests; defaults to the global `fetch`.
+ */
+export async function fetchLatestVersionFromCdn(
+  fetchImpl: typeof fetch = fetch,
+): Promise<string> {
+  const response = await fetchImpl(KIMI_CODE_CDN_LATEST_URL);
+  if (!response.ok) {
+    throw new Error(`CDN /latest returned HTTP ${response.status}`);
+  }
+  const raw = (await response.text()).trim();
+  if (valid(raw) === null) {
+    throw new Error(`CDN /latest returned invalid semver: ${JSON.stringify(raw)}`);
+  }
+  return raw;
+}
diff --git a/apps/kimi-code/src/cli/update/preflight.ts b/apps/kimi-code/src/cli/update/preflight.ts
new file mode 100644
index 000000000..385f1807e
--- /dev/null
+++ b/apps/kimi-code/src/cli/update/preflight.ts
@@ -0,0 +1,246 @@
+import { spawn } from 'node:child_process';
+
+import type { TelemetryProperties } from '@moonshot-ai/kimi-telemetry';
+
+import {
+  NATIVE_INSTALL_COMMAND_UNIX,
+  NATIVE_INSTALL_COMMAND_WIN,
+} from '#/constant/app';
+
+import { readUpdateCache } from './cache';
+import { promptForInstallConfirmation, type InstallPromptOptions } from './prompt';
+import { refreshUpdateCache } from './refresh';
+import { selectUpdateTarget } from './select';
+import { detectInstallSource } from './source';
+import {
+  NPM_PACKAGE_NAME,
+  type InstallSource,
+  type UpdateDecision,
+  type UpdatePreflightResult,
+  type UpdateTarget,
+} from './types';
+
+export type { UpdatePreflightResult } from './types';
+
+export interface RunUpdatePreflightOptions {
+  readonly stdout?: { write(chunk: string): boolean };
+  readonly stderr?: { write(chunk: string): boolean };
+  readonly isTTY?: boolean;
+  readonly track?: (event: string, properties?: TelemetryProperties) => void;
+}
+
+function withCmdSuffix(base: string, platform: NodeJS.Platform): string {
+  return platform === 'win32' ? `${base}.cmd` : base;
+}
+
+function bunCommand(platform: NodeJS.Platform): string {
+  return platform === 'win32' ? 'bun.exe' : 'bun';
+}
+
+function installCommandFor(
+  source: InstallSource,
+  version: string,
+  platform: NodeJS.Platform,
+): string {
+  switch (source) {
+    case 'npm-global':
+      return `npm install -g ${NPM_PACKAGE_NAME}@${version}`;
+    case 'pnpm-global':
+      return `pnpm add -g ${NPM_PACKAGE_NAME}@${version}`;
+    case 'yarn-global':
+      return `yarn global add ${NPM_PACKAGE_NAME}@${version}`;
+    case 'bun-global':
+      return `bun add -g ${NPM_PACKAGE_NAME}@${version}`;
+    case 'native':
+      return platform === 'win32' ? NATIVE_INSTALL_COMMAND_WIN : NATIVE_INSTALL_COMMAND_UNIX;
+    case 'unsupported':
+      return `npm install -g ${NPM_PACKAGE_NAME}@${version}`;
+  }
+}
+
+function canAutoInstall(source: InstallSource, platform: NodeJS.Platform): boolean {
+  switch (source) {
+    case 'npm-global':
+    case 'pnpm-global':
+    case 'yarn-global':
+    case 'bun-global':
+      return true;
+    case 'native':
+      return platform !== 'win32';
+    case 'unsupported':
+      return false;
+  }
+}
+
+interface SpawnCommand {
+  readonly cmd: string;
+  readonly args: readonly string[];
+}
+
+function spawnForSource(
+  source: InstallSource,
+  version: string,
+  platform: NodeJS.Platform,
+): SpawnCommand {
+  switch (source) {
+    case 'npm-global':
+      return { cmd: withCmdSuffix('npm', platform), args: ['install', '-g', `${NPM_PACKAGE_NAME}@${version}`] };
+    case 'pnpm-global':
+      return { cmd: withCmdSuffix('pnpm', platform), args: ['add', '-g', `${NPM_PACKAGE_NAME}@${version}`] };
+    case 'yarn-global':
+      return { cmd: withCmdSuffix('yarn', platform), args: ['global', 'add', `${NPM_PACKAGE_NAME}@${version}`] };
+    case 'bun-global':
+      return { cmd: bunCommand(platform), args: ['add', '-g', `${NPM_PACKAGE_NAME}@${version}`] };
+    case 'native':
+      return { cmd: 'bash', args: ['-c', NATIVE_INSTALL_COMMAND_UNIX] };
+    case 'unsupported':
+      throw new Error('unsupported install source cannot be auto-installed');
+  }
+}
+
+function formatErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function renderManualUpdateMessage(
+  currentVersion: string,
+  target: UpdateTarget,
+  source: InstallSource,
+  installCommand: string,
+): string {
+  const sourceDesc =
+    source === 'native'
+      ? 'native (windows). Auto-update is not supported on this platform.'
+      : 'unsupported package manager or layout.';
+  return (
+    `A newer version of ${NPM_PACKAGE_NAME} is available ` +
+    `(${currentVersion} -> ${target.version}).\n` +
+    `Detected install source: ${sourceDesc}\n` +
+    `To update manually, run: ${installCommand}\n`
+  );
+}
+
+function renderInstallSuccessMessage(target: UpdateTarget): string {
+  return `Updated ${NPM_PACKAGE_NAME} to ${target.version}. Restart the CLI to use the new version.\n`;
+}
+
+function refreshInBackground(): void {
+  void refreshUpdateCache().catch(() => {});
+}
+
+function trackUpdatePrompted(
+  track: RunUpdatePreflightOptions['track'],
+  currentVersion: string,
+  target: UpdateTarget,
+  source: InstallSource,
+  decision: UpdateDecision,
+): void {
+  try {
+    track?.('update_prompted', {
+      current: currentVersion,
+      latest: target.version,
+      current_version: currentVersion,
+      target_version: target.version,
+      source,
+      decision,
+    });
+  } catch {
+    // Telemetry must never affect update prompting.
+  }
+}
+
+async function promptInstall(
+  currentVersion: string,
+  target: UpdateTarget,
+  source: InstallSource,
+  installCommand: string,
+): Promise<boolean> {
+  const options: InstallPromptOptions = {
+    currentVersion,
+    target,
+    installSource: source,
+    installCommand,
+  };
+  return promptForInstallConfirmation(options);
+}
+
+async function installUpdate(
+  source: InstallSource,
+  version: string,
+  platform: NodeJS.Platform,
+): Promise<void> {
+  const { cmd, args } = spawnForSource(source, version, platform);
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(cmd, [...args], { stdio: 'inherit' });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      const detail = signal !== null ? `signal ${signal}` : `code ${String(code)}`;
+      reject(new Error(`${cmd} exited with ${detail}`));
+    });
+  });
+}
+
+export function decideUpdateAction(
+  target: UpdateTarget | null,
+  isInteractive: boolean,
+  source: InstallSource,
+  platform: NodeJS.Platform,
+): UpdateDecision {
+  if (target === null || !isInteractive) return 'none';
+  return canAutoInstall(source, platform) ? 'prompt-install' : 'manual-command';
+}
+
+export async function runUpdatePreflight(
+  currentVersion: string,
+  options: RunUpdatePreflightOptions = {},
+): Promise<UpdatePreflightResult> {
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const platform = process.platform;
+
+  try {
+    const cache = await readUpdateCache().catch(() => null);
+    const latest = cache?.latest ?? null;
+    const target = selectUpdateTarget(currentVersion, latest);
+    refreshInBackground();
+
+    const isInteractive =
+      options.isTTY ?? (process.stdin.isTTY && process.stdout.isTTY);
+    const source: InstallSource =
+      target === null || !isInteractive
+        ? 'unsupported'
+        : await detectInstallSource().catch(() => 'unsupported' as const);
+
+    const decision = decideUpdateAction(target, isInteractive, source, platform);
+    if (decision === 'none' || target === null) return 'continue';
+
+    const installCommand = installCommandFor(source, target.version, platform);
+    trackUpdatePrompted(options.track, currentVersion, target, source, decision);
+
+    if (decision === 'manual-command') {
+      stdout.write(renderManualUpdateMessage(currentVersion, target, source, installCommand));
+      return 'continue';
+    }
+
+    const confirmed = await promptInstall(currentVersion, target, source, installCommand);
+    if (!confirmed) return 'continue';
+
+    try {
+      await installUpdate(source, target.version, platform);
+      stdout.write(renderInstallSuccessMessage(target));
+      return 'exit';
+    } catch (error) {
+      stderr.write(
+        `warning: failed to install ${NPM_PACKAGE_NAME}@${target.version}: ` +
+          `${formatErrorMessage(error)}\n`,
+      );
+      return 'continue';
+    }
+  } catch {
+    return 'continue';
+  }
+}
diff --git a/apps/kimi-code/src/cli/update/prompt.ts b/apps/kimi-code/src/cli/update/prompt.ts
new file mode 100644
index 000000000..4bcd0e3e9
--- /dev/null
+++ b/apps/kimi-code/src/cli/update/prompt.ts
@@ -0,0 +1,184 @@
+import { clearLine, cursorTo, emitKeypressEvents, moveCursor } from 'node:readline';
+
+import chalk from 'chalk';
+
+import { PRODUCT_NAME } from '#/constant/app';
+import { HIDE_CURSOR, SHOW_CURSOR } from '#/constant/terminal';
+import {
+  UPDATE_PROMPT_MUTED,
+  UPDATE_PROMPT_PRIMARY,
+  UPDATE_PROMPT_SUCCESS,
+  UPDATE_PROMPT_TEXT_DIM,
+  UPDATE_PROMPT_WARNING,
+} from '#/constant/update';
+
+import { type InstallSource, type UpdateTarget } from './types';
+
+export type InstallPromptChoiceValue = 'install' | 'skip';
+
+export interface InstallPromptChoice {
+  readonly value: InstallPromptChoiceValue;
+  readonly label: string;
+}
+
+export interface InstallPromptOptions {
+  readonly currentVersion: string;
+  readonly target: UpdateTarget;
+  readonly installCommand: string;
+  readonly installSource: InstallSource;
+  readonly input?: NodeJS.ReadStream;
+  readonly output?: NodeJS.WriteStream;
+}
+
+const INSTALL_HINT = 'Install update now';
+const SKIP_HINT = 'Continue with current version';
+
+export function createInstallPromptChoices(target: UpdateTarget): readonly InstallPromptChoice[] {
+  return [
+    { value: 'install', label: `${INSTALL_HINT} (${target.version})` },
+    { value: 'skip', label: SKIP_HINT },
+  ];
+}
+
+export function getDefaultInstallPromptSelection(choices: readonly InstallPromptChoice[]): number {
+  const installIndex = choices.findIndex((choice) => choice.value === 'install');
+  return Math.max(installIndex, 0);
+}
+
+export function moveInstallPromptSelection(
+  currentIndex: number,
+  direction: 'up' | 'down',
+  choiceCount: number,
+): number {
+  if (direction === 'up') {
+    return Math.max(0, currentIndex - 1);
+  }
+  return Math.min(choiceCount - 1, currentIndex + 1);
+}
+
+function renderInstallPrompt(
+  options: InstallPromptOptions,
+  choices: readonly InstallPromptChoice[],
+  selectedIndex: number,
+): readonly string[] {
+  const label = chalk.hex(UPDATE_PROMPT_TEXT_DIM).bold;
+  const currentVersion = chalk.hex(UPDATE_PROMPT_WARNING).bold(options.currentVersion);
+  const targetVersion = chalk.hex(UPDATE_PROMPT_SUCCESS).bold(options.target.version);
+  const sourceLabel = chalk.hex(UPDATE_PROMPT_PRIMARY).bold(options.installSource);
+  const command = chalk.hex(UPDATE_PROMPT_PRIMARY)(options.installCommand);
+  const lines = [
+    chalk.hex(UPDATE_PROMPT_PRIMARY).bold('Kimi Code Update Available'),
+    chalk.hex(UPDATE_PROMPT_MUTED)(`${PRODUCT_NAME} has a newer release ready.`),
+    '',
+    `${label('Current')}  ${currentVersion}`,
+    `${label('Target ')}  ${targetVersion}`,
+    `${label('Source ')}  ${sourceLabel}`,
+    `${label('Command')}  ${command}`,
+    '',
+    chalk.hex(UPDATE_PROMPT_MUTED)('↑↓ choose · Enter confirm · Esc continue'),
+    '',
+  ];
+
+  for (let i = 0; i < choices.length; i++) {
+    const choice = choices[i];
+    if (choice === undefined) continue;
+    const isSelected = i === selectedIndex;
+    const pointer = isSelected ? '❯' : ' ';
+    const content = ` ${pointer} ${choice.label}`;
+    if (isSelected) {
+      lines.push(chalk.hex(UPDATE_PROMPT_PRIMARY).bold(content));
+      continue;
+    }
+    lines.push(chalk.hex(UPDATE_PROMPT_TEXT_DIM)(content));
+  }
+
+  return lines;
+}
+
+function writePromptFrame(
+  output: NodeJS.WriteStream,
+  lines: readonly string[],
+  previousLineCount: number,
+): number {
+  if (previousLineCount > 0) {
+    moveCursor(output, 0, -(previousLineCount - 1));
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    clearLine(output, 0);
+    cursorTo(output, 0);
+    output.write(lines[i] ?? '');
+    if (i < lines.length - 1) {
+      output.write('\n');
+    }
+  }
+
+  return lines.length;
+}
+
+export async function promptForInstallConfirmation(
+  options: InstallPromptOptions,
+): Promise<boolean> {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const choices = createInstallPromptChoices(options.target);
+  let selectedIndex = getDefaultInstallPromptSelection(choices);
+
+  return new Promise<boolean>((resolve) => {
+    let lineCount = 0;
+    const hadRawMode = 'isRaw' in input ? input.isRaw : false;
+    const canSetRawMode = typeof input.setRawMode === 'function';
+
+    const cleanup = (): void => {
+      input.off('keypress', onKeypress);
+      if (canSetRawMode) {
+        input.setRawMode(hadRawMode);
+      }
+      output.write(SHOW_CURSOR);
+      output.write('\n');
+    };
+
+    const finish = (choice: InstallPromptChoiceValue): void => {
+      cleanup();
+      resolve(choice === 'install');
+    };
+
+    const render = (): void => {
+      lineCount = writePromptFrame(
+        output,
+        renderInstallPrompt(options, choices, selectedIndex),
+        lineCount,
+      );
+    };
+
+    const onKeypress = (_input: string, key: { name?: string; ctrl?: boolean }): void => {
+      if (key.name === 'up') {
+        selectedIndex = moveInstallPromptSelection(selectedIndex, 'up', choices.length);
+        render();
+        return;
+      }
+      if (key.name === 'down') {
+        selectedIndex = moveInstallPromptSelection(selectedIndex, 'down', choices.length);
+        render();
+        return;
+      }
+      if (key.name === 'return' || key.name === 'enter') {
+        const chosen = choices[selectedIndex]?.value ?? 'skip';
+        finish(chosen);
+        return;
+      }
+      if (key.name === 'escape' || (key.ctrl === true && key.name === 'c')) {
+        finish('skip');
+      }
+    };
+
+    emitKeypressEvents(input);
+    if (canSetRawMode) {
+      input.setRawMode(true);
+    }
+    input.resume();
+    input.on('keypress', onKeypress);
+    output.write(HIDE_CURSOR);
+    render();
+  });
+}
diff --git a/apps/kimi-code/src/cli/update/refresh.ts b/apps/kimi-code/src/cli/update/refresh.ts
new file mode 100644
index 000000000..20bcdf0de
--- /dev/null
+++ b/apps/kimi-code/src/cli/update/refresh.ts
@@ -0,0 +1,32 @@
+import { writeUpdateCache } from './cache';
+import { fetchLatestVersionFromCdn } from './cdn';
+import { type UpdateCache } from './types';
+
+export interface RefreshUpdateCacheDeps {
+  /** Resolves with the latest semver. **Throws** on any failure — callers
+   * (including the default background invocation in preflight) must catch.
+   * Errors intentionally skip `writeCache` so a transient CDN blip does not
+   * overwrite a previously known `latest` with `null`. */
+  readonly fetchLatest: () => Promise<string>;
+  readonly writeCache: (cache: UpdateCache) => Promise<void>;
+  readonly now: () => Date;
+}
+
+export async function refreshUpdateCache(
+  overrides: Partial<RefreshUpdateCacheDeps> = {},
+): Promise<UpdateCache> {
+  const resolved: RefreshUpdateCacheDeps = {
+    fetchLatest: overrides.fetchLatest ?? (() => fetchLatestVersionFromCdn()),
+    writeCache: overrides.writeCache ?? writeUpdateCache,
+    now: overrides.now ?? (() => new Date()),
+  };
+
+  const latest = await resolved.fetchLatest();
+  const cache: UpdateCache = {
+    source: 'cdn',
+    checkedAt: resolved.now().toISOString(),
+    latest,
+  };
+  await resolved.writeCache(cache);
+  return cache;
+}
diff --git a/apps/kimi-code/src/cli/update/select.ts b/apps/kimi-code/src/cli/update/select.ts
new file mode 100644
index 000000000..bf241ed80
--- /dev/null
+++ b/apps/kimi-code/src/cli/update/select.ts
@@ -0,0 +1,13 @@
+import { gt, valid } from 'semver';
+
+import { type UpdateTarget } from './types';
+
+export function selectUpdateTarget(
+  currentVersion: string,
+  latest: string | null,
+): UpdateTarget | null {
+  if (latest === null) return null;
+  if (valid(currentVersion) === null || valid(latest) === null) return null;
+  if (!gt(latest, currentVersion)) return null;
+  return { version: latest };
+}
diff --git a/apps/kimi-code/src/cli/update/source.ts b/apps/kimi-code/src/cli/update/source.ts
new file mode 100644
index 000000000..4b544d140
--- /dev/null
+++ b/apps/kimi-code/src/cli/update/source.ts
@@ -0,0 +1,155 @@
+import { execFile } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+
+import { getHostPackageRoot } from '#/cli/version';
+
+import { NPM_PACKAGE_NAME, type InstallSource } from './types';
+
+const nodeRequire = createRequire(import.meta.url);
+
+interface NodeSeaModule {
+  isSea(): boolean;
+}
+
+let cachedSea: NodeSeaModule | null | undefined;
+
+function loadSeaModule(): NodeSeaModule | null {
+  if (cachedSea !== undefined) return cachedSea;
+  try {
+    cachedSea = nodeRequire('node:sea') as NodeSeaModule;
+  } catch {
+    cachedSea = null;
+  }
+  return cachedSea;
+}
+
+/** Runtime SEA detection — true when running as a packaged native binary. */
+export function detectNativeInstall(): boolean {
+  const sea = loadSeaModule();
+  if (sea === null) return false;
+  try {
+    return sea.isSea();
+  } catch {
+    return false;
+  }
+}
+
+// Path heuristic markers (compared in lowercase; both forward and backward slashes accepted).
+const PNPM_PATH_SEGMENT = 'pnpm/global/';
+const YARN_PATH_SEGMENTS = ['.config/yarn/global/', '/.yarn/global/'];
+const BUN_PATH_SEGMENT = '.bun/install/global/';
+
+function normalizeForHeuristic(filePath: string): string {
+  return filePath.replaceAll('\\', '/').toLowerCase();
+}
+
+/**
+ * Heuristic classification by package root path segments. Returns the
+ * matching `InstallSource` or `null` if no heuristic matches (caller should
+ * fall through to npm-prefix comparison).
+ */
+export function classifyByPathHeuristic(packageRoot: string): InstallSource | null {
+  const normalized = normalizeForHeuristic(packageRoot);
+  if (normalized.includes(PNPM_PATH_SEGMENT)) return 'pnpm-global';
+  for (const seg of YARN_PATH_SEGMENTS) {
+    if (normalized.includes(seg)) return 'yarn-global';
+  }
+  if (normalized.includes(BUN_PATH_SEGMENT)) return 'bun-global';
+  return null;
+}
+
+export interface DetectInstallSourceDeps {
+  readonly getPackageRoot: () => string;
+  readonly getGlobalPrefix: () => Promise<string>;
+  readonly detectNative: () => boolean;
+  readonly platform: NodeJS.Platform;
+}
+
+function npmCommand(platform: NodeJS.Platform): string {
+  return platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function execFileText(command: string, args: readonly string[]): Promise<string> {
+  return new Promise((resolveOutput, reject) => {
+    execFile(command, [...args], { encoding: 'utf-8' }, (error, stdout) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolveOutput(stdout);
+    });
+  });
+}
+
+function normalizePathForComparison(filePath: string, platform: NodeJS.Platform): string | null {
+  const trimmed = filePath.trim();
+  if (trimmed.length === 0) return null;
+  try {
+    return normalizeResolvedPath(realpathSync(trimmed), platform);
+  } catch {
+    return normalizeResolvedPath(resolve(trimmed), platform);
+  }
+}
+
+function normalizeResolvedPath(filePath: string, platform: NodeJS.Platform): string {
+  const resolvedPath = resolve(filePath);
+  return platform === 'win32' ? resolvedPath.toLowerCase() : resolvedPath;
+}
+
+function candidateGlobalPackageDirs(
+  globalPrefix: string,
+  platform: NodeJS.Platform,
+): readonly string[] {
+  if (platform === 'win32') {
+    return [join(globalPrefix, 'node_modules', NPM_PACKAGE_NAME)];
+  }
+  return [
+    join(globalPrefix, 'lib', 'node_modules', NPM_PACKAGE_NAME),
+    join(globalPrefix, 'node_modules', NPM_PACKAGE_NAME),
+  ];
+}
+
+export function classifyInstallSource(
+  packageRoot: string,
+  globalPrefix: string,
+  platform: NodeJS.Platform = process.platform,
+): InstallSource {
+  const normalizedPackageRoot = normalizePathForComparison(packageRoot, platform);
+  if (normalizedPackageRoot === null) return 'unsupported';
+
+  for (const candidate of candidateGlobalPackageDirs(globalPrefix, platform)) {
+    if (normalizePathForComparison(candidate, platform) === normalizedPackageRoot) {
+      return 'npm-global';
+    }
+  }
+  return 'unsupported';
+}
+
+export async function detectInstallSource(
+  deps: Partial<DetectInstallSourceDeps> = {},
+): Promise<InstallSource> {
+  const platform = deps.platform ?? process.platform;
+  const resolved: DetectInstallSourceDeps = {
+    getPackageRoot: deps.getPackageRoot ?? getHostPackageRoot,
+    getGlobalPrefix:
+      deps.getGlobalPrefix ??
+      (() => execFileText(npmCommand(platform), ['prefix', '-g']).then((text) => text.trim())),
+    detectNative: deps.detectNative ?? detectNativeInstall,
+    platform,
+  };
+
+  if (resolved.detectNative()) return 'native';
+
+  const packageRoot = resolved.getPackageRoot();
+  const heuristic = classifyByPathHeuristic(packageRoot);
+  if (heuristic !== null) return heuristic;
+
+  try {
+    const globalPrefix = await resolved.getGlobalPrefix();
+    return classifyInstallSource(packageRoot, globalPrefix, resolved.platform);
+  } catch {
+    return 'unsupported';
+  }
+}
diff --git a/apps/kimi-code/src/cli/update/types.ts b/apps/kimi-code/src/cli/update/types.ts
new file mode 100644
index 000000000..652fc97d5
--- /dev/null
+++ b/apps/kimi-code/src/cli/update/types.ts
@@ -0,0 +1,33 @@
+import { NPM_PACKAGE_NAME } from '#/constant/app';
+
+export { NPM_PACKAGE_NAME };
+
+/** Where the running CLI was installed from. Drives update command + spawn. */
+export type InstallSource =
+  | 'npm-global'
+  | 'pnpm-global'
+  | 'yarn-global'
+  | 'bun-global'
+  | 'native'
+  | 'unsupported';
+
+export interface UpdateTarget {
+  readonly version: string;
+}
+
+export interface UpdateCache {
+  readonly source: 'cdn';
+  readonly checkedAt: string | null;
+  readonly latest: string | null;
+}
+
+export type UpdateDecision = 'none' | 'prompt-install' | 'manual-command';
+export type UpdatePreflightResult = 'continue' | 'exit';
+
+export function emptyUpdateCache(): UpdateCache {
+  return {
+    source: 'cdn',
+    checkedAt: null,
+    latest: null,
+  };
+}
diff --git a/apps/kimi-code/src/cli/version.ts b/apps/kimi-code/src/cli/version.ts
new file mode 100644
index 000000000..f0a9f695d
--- /dev/null
+++ b/apps/kimi-code/src/cli/version.ts
@@ -0,0 +1,63 @@
+/**
+ * Kimi Code version helpers.
+ *
+ * `getVersion` reads the host CLI's `package.json#version`.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+import { createKimiDefaultHeaders, type KimiHostIdentity } from '@moonshot-ai/kimi-code-oauth';
+
+import { CLI_USER_AGENT_PRODUCT } from '#/constant/app';
+
+import { getDataDir } from '../utils/paths';
+import { KIMI_BUILD_INFO } from './build-info';
+
+const MODULE_DIR = import.meta.dirname;
+
+export function getHostPackageJsonPath(): string {
+  // Walk upwards from this file's directory until a `package.json` shows up,
+  // so both dev (`tsx src/main.ts` — this file in `src/cli/`, pkg 2 levels
+  // up) and prod (`node dist/main.mjs` — this code bundled into `dist/`,
+  // pkg 1 level up) resolve correctly.
+  let dir = MODULE_DIR;
+  for (let i = 0; i < 6; i++) {
+    const candidate = resolve(dir, 'package.json');
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(`Could not locate package.json near ${MODULE_DIR}`);
+}
+
+export function getHostPackageRoot(): string {
+  return dirname(getHostPackageJsonPath());
+}
+
+export function getVersion(): string {
+  if (KIMI_BUILD_INFO.version !== undefined) {
+    return KIMI_BUILD_INFO.version;
+  }
+  const pkg = JSON.parse(readFileSync(getHostPackageJsonPath(), 'utf-8')) as {
+    version: string;
+  };
+  return pkg.version;
+}
+
+export function createKimiCodeHostIdentity(version = getVersion()): KimiHostIdentity {
+  return {
+    userAgentProduct: CLI_USER_AGENT_PRODUCT,
+    version,
+  };
+}
+
+export function buildKimiDefaultHeaders(version: string): Record<string, string> {
+  return createKimiDefaultHeaders({
+    homeDir: getDataDir(),
+    ...createKimiCodeHostIdentity(version),
+  });
+}
diff --git a/apps/kimi-code/src/constant/app.ts b/apps/kimi-code/src/constant/app.ts
new file mode 100644
index 000000000..d6d37c3a2
--- /dev/null
+++ b/apps/kimi-code/src/constant/app.ts
@@ -0,0 +1,49 @@
+import { ErrorCodes } from '@moonshot-ai/kimi-code-sdk';
+
+export const PRODUCT_NAME = 'Kimi Code';
+export const CLI_COMMAND_NAME = 'kimi';
+
+// Used in telemetry app names and HTTP User-Agent headers.
+export const CLI_USER_AGENT_PRODUCT = 'kimi-code-cli';
+export const CLI_UI_MODE = 'shell';
+
+// Give telemetry a short flush window without making CLI exit feel stuck.
+export const CLI_SHUTDOWN_TIMEOUT_MS = 3000;
+
+// Published npm package name; this can differ from the executable command.
+export const NPM_PACKAGE_NAME = '@moonshot-ai/kimi-code';
+
+// App-owned data paths. SDK/core runtime config is intentionally not routed here.
+export const KIMI_CODE_HOME_ENV = 'KIMI_CODE_HOME';
+export const KIMI_CODE_DATA_DIR_NAME = '.kimi-code';
+export const KIMI_CODE_LOG_DIR_NAME = 'logs';
+export const KIMI_CODE_UPDATE_DIR_NAME = 'updates';
+export const KIMI_CODE_UPDATE_STATE_FILE_NAME = 'latest.json';
+export const KIMI_CODE_INPUT_HISTORY_DIR_NAME = 'user-history';
+
+// Managed Kimi auth provider key shared with OAuth/SDK config.
+export const DEFAULT_OAUTH_PROVIDER_NAME = 'managed:kimi-code';
+
+// SDK/core error code that tells the TUI to show a login-required startup
+// notice. Derived from sdk's ErrorCodes so a future rename in core
+// auto-propagates instead of silently breaking the startup recovery path.
+export const OAUTH_LOGIN_REQUIRED_CODE = ErrorCodes.AUTH_LOGIN_REQUIRED;
+
+export const FEEDBACK_ISSUE_URL = 'https://github.com/MoonshotAI/kimi-code/issues';
+
+// Sent in the feedback `version` field so the backend can distinguish this
+// TypeScript client from clients that send a bare version.
+export const FEEDBACK_VERSION_PREFIX = 'kimi-code-';
+
+// Telemetry event name; keep stable for dashboard queries.
+export const FEEDBACK_TELEMETRY_EVENT = 'feedback_submitted';
+
+// CDN source of truth: all version checks and native install scripts pull from here.
+export const KIMI_CODE_CDN_BASE = 'https://code.kimi.com/kimi-code';
+export const KIMI_CODE_CDN_LATEST_URL = `${KIMI_CODE_CDN_BASE}/latest`;
+export const KIMI_CODE_INSTALL_SH_URL = `${KIMI_CODE_CDN_BASE}/install.sh`;
+export const KIMI_CODE_INSTALL_PS1_URL = `${KIMI_CODE_CDN_BASE}/install.ps1`;
+
+// Native install commands, split by platform. Use these for prompt copy and spawn calls only; do not assemble the strings elsewhere.
+export const NATIVE_INSTALL_COMMAND_UNIX = `curl -fsSL ${KIMI_CODE_INSTALL_SH_URL} | bash`;
+export const NATIVE_INSTALL_COMMAND_WIN = `irm ${KIMI_CODE_INSTALL_PS1_URL} | iex`;
diff --git a/apps/kimi-code/src/constant/index.ts b/apps/kimi-code/src/constant/index.ts
new file mode 100644
index 000000000..afa11b2a1
--- /dev/null
+++ b/apps/kimi-code/src/constant/index.ts
@@ -0,0 +1,4 @@
+export * from './app';
+export * from './startup-error';
+export * from './terminal';
+export * from './update';
diff --git a/apps/kimi-code/src/constant/startup-error.ts b/apps/kimi-code/src/constant/startup-error.ts
new file mode 100644
index 000000000..a59cb9093
--- /dev/null
+++ b/apps/kimi-code/src/constant/startup-error.ts
@@ -0,0 +1,2 @@
+// Pre-TUI startup errors render directly to stderr, before theme detection.
+export const STARTUP_ERROR_COLOR = '#E85454';
diff --git a/apps/kimi-code/src/constant/terminal.ts b/apps/kimi-code/src/constant/terminal.ts
new file mode 100644
index 000000000..22a4dfdfd
--- /dev/null
+++ b/apps/kimi-code/src/constant/terminal.ts
@@ -0,0 +1,8 @@
+// C0/control-sequence bytes used to build terminal protocol messages.
+export const ESC = '\u001B';
+export const BEL = '\u0007';
+export const ST = '\\';
+
+// ANSI cursor visibility toggles used by CLI prompts.
+export const HIDE_CURSOR = `${ESC}[?25l`;
+export const SHOW_CURSOR = `${ESC}[?25h`;
diff --git a/apps/kimi-code/src/constant/update.ts b/apps/kimi-code/src/constant/update.ts
new file mode 100644
index 000000000..9881219cf
--- /dev/null
+++ b/apps/kimi-code/src/constant/update.ts
@@ -0,0 +1,7 @@
+// Local palette for the pre-TUI update prompt. TUI colors still come
+// from `src/tui/theme`; do not use these in interactive TUI components.
+export const UPDATE_PROMPT_PRIMARY = '#1783ff';
+export const UPDATE_PROMPT_SUCCESS = '#16A34A';
+export const UPDATE_PROMPT_WARNING = '#CA8A04';
+export const UPDATE_PROMPT_MUTED = '#999999';
+export const UPDATE_PROMPT_TEXT_DIM = '#6B7280';
diff --git a/apps/kimi-code/src/main.ts b/apps/kimi-code/src/main.ts
new file mode 100644
index 000000000..d2804a939
--- /dev/null
+++ b/apps/kimi-code/src/main.ts
@@ -0,0 +1,128 @@
+/**
+ * Kimi Code entry point.
+ *
+ * Parses CLI arguments via Commander.js, validates options, runs the
+ * outer update preflight, then delegates to the requested UI runner.
+ */
+
+import {
+  flushDiagnosticLogs,
+  log,
+  resolveGlobalLogPath,
+  resolveKimiHome,
+} from '@moonshot-ai/kimi-code-sdk';
+import { installCrashHandlers, track } from '@moonshot-ai/kimi-telemetry';
+
+import { createProgram } from './cli/commands';
+import type { CLIOptions } from './cli/options';
+import { OptionConflictError, validateOptions } from './cli/options';
+import { runPrompt } from './cli/run-prompt';
+import { runShell } from './cli/run-shell';
+import { formatStartupError } from './cli/startup-error';
+import { runUpdatePreflight } from './cli/update/preflight';
+import { getVersion } from './cli/version';
+import { cleanupStaleNativeCacheForCurrent } from './native/native-assets';
+import { installNativeModuleHook } from './native/module-hook';
+import { runNativeAssetSmokeIfRequested } from './native/smoke';
+import { initProcessName } from './utils/process/proctitle';
+
+export async function handleMainCommand(opts: CLIOptions, version: string): Promise<void> {
+  let validated: ReturnType<typeof validateOptions>;
+  try {
+    validated = validateOptions(opts);
+  } catch (error) {
+    if (error instanceof OptionConflictError) {
+      process.stderr.write(`error: ${error.message}\n`);
+      process.exit(1);
+    }
+    throw error;
+  }
+
+  const preflightResult = await runUpdatePreflight(
+    version,
+    validated.uiMode === 'print' ? { track, isTTY: false } : { track },
+  );
+  if (preflightResult === 'exit') {
+    process.exit(0);
+  }
+
+  if (validated.uiMode === 'print') {
+    await runPrompt(validated.options, version);
+    return;
+  }
+
+  await runShell(validated.options, version);
+}
+
+/** `kimi migrate`: launch the migration screen only, then exit. */
+async function handleMigrateCommand(version: string): Promise<void> {
+  await runShell(MIGRATE_CLI_OPTIONS, version, { migrateOnly: true });
+}
+
+/** A neutral CLIOptions value — `kimi migrate` never opens a chat session. */
+const MIGRATE_CLI_OPTIONS: CLIOptions = {
+  session: undefined,
+  continue: false,
+  yolo: false,
+  plan: false,
+  model: undefined,
+  outputFormat: undefined,
+  prompt: undefined,
+  skillsDirs: [],
+};
+
+export function main(): void {
+  initProcessName();
+  installCrashHandlers();
+  installNativeModuleHook();
+  if (runNativeAssetSmokeIfRequested()) return;
+
+  // Start the background cleanup of stale native cache. Fire-and-forget; must not block startup or throw.
+  queueMicrotask(() => {
+    try {
+      cleanupStaleNativeCacheForCurrent();
+    } catch {
+      // ignore: cache GC must never affect process startup
+    }
+  });
+
+  const version = getVersion();
+
+  const program = createProgram(
+    version,
+    (opts) => {
+      void handleMainCommand(opts, version).catch(async (error: unknown) => {
+        const operation = opts.prompt !== undefined ? 'run prompt' : 'start shell';
+        await logStartupFailure(operation, error);
+        process.stderr.write(
+          formatStartupError(error, {
+            operation,
+          }),
+        );
+        process.stderr.write(`See log: ${resolveGlobalLogPath(resolveKimiHome())}\n`);
+        process.exit(1);
+      });
+    },
+    () => {
+      void handleMigrateCommand(version).catch(async (error: unknown) => {
+        await logStartupFailure('run migration', error);
+        process.stderr.write(formatStartupError(error, { operation: 'run migration' }));
+        process.stderr.write(`See log: ${resolveGlobalLogPath(resolveKimiHome())}\n`);
+        process.exit(1);
+      });
+    },
+  );
+
+  program.parse(process.argv);
+}
+
+main();
+
+async function logStartupFailure(operation: string, error: unknown): Promise<void> {
+  log.error('startup failed', { operation, error });
+  try {
+    await flushDiagnosticLogs();
+  } catch {
+    // Best-effort diagnostic flush only.
+  }
+}
diff --git a/apps/kimi-code/src/migration/badge.ts b/apps/kimi-code/src/migration/badge.ts
new file mode 100644
index 000000000..47b3fabb6
--- /dev/null
+++ b/apps/kimi-code/src/migration/badge.ts
@@ -0,0 +1,27 @@
+/**
+ * Pure helpers for composing session labels in the session picker.
+ *
+ * Detection rule for the `[imported]` badge: `metadata.imported_from_kimi_cli`
+ * is strictly the boolean `true`. This mirrors the value written by
+ * `migration-legacy` into the session's `state.json` `custom` block.
+ */
+
+const IMPORTED_BADGE = '[imported]';
+const IMPORTED_FLAG_KEY = 'imported_from_kimi_cli';
+
+export interface SessionLabelInput {
+  readonly title: string;
+  readonly metadata?: Readonly<Record<string, unknown>> | undefined;
+}
+
+export function isImportedSession(
+  metadata: Readonly<Record<string, unknown>> | undefined,
+): boolean {
+  if (metadata === undefined) return false;
+  return metadata[IMPORTED_FLAG_KEY] === true;
+}
+
+export function formatSessionLabel(input: SessionLabelInput): string {
+  const prefix = isImportedSession(input.metadata) ? `${IMPORTED_BADGE} ` : '';
+  return `${prefix}${input.title}`;
+}
diff --git a/apps/kimi-code/src/migration/command.ts b/apps/kimi-code/src/migration/command.ts
new file mode 100644
index 000000000..13d02f885
--- /dev/null
+++ b/apps/kimi-code/src/migration/command.ts
@@ -0,0 +1,19 @@
+/**
+ * `kimi migrate` sub-command.
+ *
+ * A bare, flagless subcommand: it launches the native pi-tui migration screen
+ * (the same one shown on first launch), then exits. The screen collects the
+ * migration scope interactively, so there are no CLI options. The actual
+ * launch is delegated to a host-provided handler.
+ */
+
+import type { Command } from 'commander';
+
+export function registerMigrateCommand(parent: Command, onMigrate: () => void): void {
+  parent
+    .command('migrate')
+    .description('Migrate data from a legacy kimi-cli installation into kimi-code.')
+    .action(() => {
+      onMigrate();
+    });
+}
diff --git a/apps/kimi-code/src/migration/detect-pending.ts b/apps/kimi-code/src/migration/detect-pending.ts
new file mode 100644
index 000000000..60e2219dd
--- /dev/null
+++ b/apps/kimi-code/src/migration/detect-pending.ts
@@ -0,0 +1,69 @@
+/**
+ * Pre-TUI detection: decide whether a first-launch migration screen should be
+ * shown. Cheap, synchronous-ish, no TTY required. Returns the MigrationPlan to
+ * drive the screen, or null when there is nothing to offer.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { detectMigration, type MigrationPlan } from '@moonshot-ai/migration-legacy';
+
+export interface DetectPendingInput {
+  readonly sourceHome: string;
+  readonly targetHome: string;
+  /**
+   * When true, skip the marker-based suppression (`.migrated-to-kimi-code` /
+   * `.skip-migration-from-kimi-cli`). The explicit `kimi migrate` command sets
+   * this so a deliberate invocation always runs regardless of prior runs.
+   */
+  readonly ignoreMarker?: boolean;
+}
+
+export async function detectPendingMigration(
+  input: DetectPendingInput,
+): Promise<MigrationPlan | null> {
+  const { sourceHome, targetHome } = input;
+  if (!existsSync(sourceHome)) return null;
+  if (input.ignoreMarker !== true) {
+    if (migrationAlreadyTargeted(join(sourceHome, '.migrated-to-kimi-code'), targetHome)) {
+      return null;
+    }
+    if (existsSync(join(targetHome, '.skip-migration-from-kimi-cli'))) return null;
+  }
+
+  let plan: MigrationPlan;
+  try {
+    plan = await detectMigration({ sourcePath: sourceHome });
+  } catch {
+    // Detection failure must never block startup; skip the screen.
+    return null;
+  }
+
+  const nothingToMigrate =
+    plan.totalSessions === 0 &&
+    !plan.hasConfig &&
+    !plan.hasMcp &&
+    !plan.hasUserHistory &&
+    plan.oauthCredentials.length === 0;
+  if (nothingToMigrate) return null;
+
+  return plan;
+}
+
+/**
+ * True when the legacy `.migrated-to-kimi-code` marker records a migration
+ * into *this* target home. A marker written for a different `KIMI_CODE_HOME`
+ * must not suppress the prompt — that target has never received migrated data.
+ * An unreadable/old marker without `target_path` is treated as "matches"
+ * (conservative: do not re-prompt when the marker exists but is ambiguous).
+ */
+function migrationAlreadyTargeted(markerPath: string, targetHome: string): boolean {
+  if (!existsSync(markerPath)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(markerPath, 'utf-8')) as { target_path?: unknown };
+    if (typeof parsed.target_path !== 'string') return true;
+    return resolve(parsed.target_path) === resolve(targetHome);
+  } catch {
+    return true;
+  }
+}
diff --git a/apps/kimi-code/src/migration/index.ts b/apps/kimi-code/src/migration/index.ts
new file mode 100644
index 000000000..fa4a385d2
--- /dev/null
+++ b/apps/kimi-code/src/migration/index.ts
@@ -0,0 +1,12 @@
+/**
+ * kimi-cli → kimi-code migration: host integration surface.
+ *
+ * Removable glue: the `kimi migrate` sub-command, the first-launch detection,
+ * the native pi-tui migration screen, and the session-picker `[imported]`
+ * badge helper. Migration logic itself lives in
+ * `@moonshot-ai/migration-legacy`.
+ */
+export { registerMigrateCommand } from './command';
+export { formatSessionLabel, isImportedSession, type SessionLabelInput } from './badge';
+export { detectPendingMigration } from './detect-pending';
+export { MigrationScreenComponent, type MigrationScreenResult } from './migration-screen';
diff --git a/apps/kimi-code/src/migration/migration-screen.ts b/apps/kimi-code/src/migration/migration-screen.ts
new file mode 100644
index 000000000..3f9814924
--- /dev/null
+++ b/apps/kimi-code/src/migration/migration-screen.ts
@@ -0,0 +1,532 @@
+/**
+ * MigrationScreenComponent — native pi-tui first-launch migration experience.
+ *
+ * A single mounted Container & Focusable that runs a 3-phase state machine:
+ *   ask (2-step choice wizard) -> progress -> result
+ *
+ * Pure decision mapping (choices -> MigrationScope) is delegated to the
+ * package's `resolveMigrationScope`. Rendering follows the `ChoicePicker`
+ * conventions in `apps/kimi-code/src/tui/components/dialogs/choice-picker.ts`.
+ *
+ * This file implements the ask, progress, and result phases. `beginMigration`
+ * drives the real runMigration flow (injectable for tests).
+ */
+import { Container, matchesKey, Key, truncateToWidth, type Focusable } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+import {
+  resolveMigrationScope,
+  runMigration as realRunMigration,
+  type AnyChoice,
+  type MigrationPlan,
+  type MigrationPromptResult,
+  type MigrationReport,
+  type MigrationScope,
+  type Prompt1Choice,
+  type Prompt2Choice,
+  type RunMigrationInput,
+} from '@moonshot-ai/migration-legacy';
+
+type Phase = 'ask1' | 'ask2' | 'progress' | 'result';
+
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'] as const;
+
+/** Spinner frame cadence — one full braille cycle every ~800ms. */
+const SPINNER_INTERVAL_MS = 80;
+
+const STEP_LABELS: ReadonlyArray<readonly [string, string]> = [
+  ['config', 'Config'],
+  ['mcp', 'MCP'],
+  ['user-history', 'REPL history'],
+  ['sessions', 'Sessions'],
+];
+
+export interface MigrationScreenOptions {
+  readonly plan: MigrationPlan;
+  readonly sourceHome: string;
+  readonly targetHome: string;
+  readonly colors: ColorPalette;
+  /** Called once the screen is finished; the host then restores the editor. */
+  readonly onComplete: (result: MigrationScreenResult) => void;
+  /** Triggers a re-render; the host wires this to `ui.requestRender()`. */
+  readonly requestRender?: () => void;
+  /** Injectable for tests; defaults to the package's runMigration. */
+  readonly runMigration?: (input: RunMigrationInput) => Promise<MigrationReport>;
+  /**
+   * When true, the screen starts at the scope question and skips the
+   * now/later/never gate — used by the explicit `kimi migrate` command, where
+   * invoking the command is itself the decision to migrate.
+   */
+  readonly skipDecisionStep?: boolean;
+}
+
+/** What the screen reports back to the host when finished. */
+export interface MigrationScreenResult {
+  readonly decision: 'now' | 'later' | 'never';
+  /** Resolved migration scope; present only when decision === 'now'. */
+  readonly scope?: MigrationScope;
+  // present only when decision === 'now' and migration ran
+  readonly migrated?: boolean;
+}
+
+interface StepDef {
+  readonly title: string;
+  readonly options: ReadonlyArray<{ readonly label: string; readonly value: AnyChoice }>;
+}
+
+export class MigrationScreenComponent extends Container implements Focusable {
+  focused = false;
+  private readonly opts: MigrationScreenOptions;
+  private phase: Phase = 'ask1';
+  private selectedIndex = 0;
+  private readonly choices: AnyChoice[] = [];
+  private progressDone = 0;
+  private progressTotal = 0;
+  private readonly stepStatus = new Map<string, 'pending' | 'done'>([
+    ['config', 'pending'],
+    ['mcp', 'pending'],
+    ['user-history', 'pending'],
+    ['sessions', 'pending'],
+  ]);
+  private spinnerFrame = 0;
+  private spinnerTimer: ReturnType<typeof setInterval> | undefined;
+  private report: MigrationReport | undefined;
+  private migrationFailed = false;
+
+  constructor(opts: MigrationScreenOptions) {
+    super();
+    this.opts = opts;
+    if (opts.skipDecisionStep === true) {
+      // Explicit `kimi migrate`: the now/later/never gate is meaningless, so
+      // start at the scope question with the decision already fixed to 'now'.
+      this.phase = 'ask2';
+      this.choices.push('now');
+    }
+  }
+
+  /** Host calls this once runMigration resolves. */
+  showResult(report: MigrationReport): void {
+    this.report = report;
+    this.phase = 'result';
+    this.stopSpinner();
+  }
+
+  /** Host calls this if runMigration threw. */
+  showFailure(): void {
+    this.migrationFailed = true;
+    this.phase = 'result';
+    this.stopSpinner();
+  }
+
+  /** Host calls this when migration starts. */
+  enterProgress(): void {
+    this.phase = 'progress';
+  }
+
+  /** Host wires this to runMigration's onProgress (step-level messages). */
+  reportStep(msg: string): void {
+    // msg is like 'config done', 'mcp done', 'sessions done'
+    const key = msg.replace(/ done$/, '');
+    if (this.stepStatus.has(key)) this.stepStatus.set(key, 'done');
+  }
+
+  /** Host wires this to runMigration's onSessionProgress. */
+  reportSessionProgress(done: number, total: number): void {
+    this.progressDone = done;
+    this.progressTotal = total;
+  }
+
+  // The braille spinner advances on its own timer so the progress screen stays
+  // visibly alive even while a single step (e.g. session translation) runs for
+  // a while without emitting progress events. Runs only for the progress
+  // phase: started on entering it, stopped the moment it ends.
+  private startSpinner(): void {
+    this.stopSpinner();
+    this.spinnerTimer = setInterval(() => {
+      this.spinnerFrame = (this.spinnerFrame + 1) % SPINNER_FRAMES.length;
+      this.opts.requestRender?.();
+    }, SPINNER_INTERVAL_MS);
+    // A decorative timer must never keep the process alive on its own.
+    this.spinnerTimer.unref();
+  }
+
+  private stopSpinner(): void {
+    if (this.spinnerTimer !== undefined) {
+      clearInterval(this.spinnerTimer);
+      this.spinnerTimer = undefined;
+    }
+  }
+
+  // test hooks (thin aliases so tests don't depend on host wiring)
+  _testEnterProgress(): void {
+    this.enterProgress();
+  }
+  _testUpdateStep(msg: string): void {
+    this.reportStep(msg);
+  }
+  _testUpdateSessionProgress(done: number, total: number): void {
+    this.reportSessionProgress(done, total);
+  }
+  _testShowResult(report: MigrationReport): void {
+    this.showResult(report);
+  }
+
+  handleInput(data: string): void {
+    if (this.phase === 'ask1' || this.phase === 'ask2') {
+      this.handleAskInput(data);
+      return;
+    }
+    if (this.phase === 'result') {
+      if (matchesKey(data, Key.enter)) {
+        this.opts.onComplete({ decision: 'now', migrated: !this.migrationFailed });
+      }
+      return;
+    }
+    // progress phase: ignore input
+  }
+
+  private currentStep(): StepDef {
+    return stepFor(this.phase, this.opts.plan);
+  }
+
+  private handleAskInput(data: string): void {
+    const step = this.currentStep();
+    if (matchesKey(data, Key.up)) {
+      this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.selectedIndex = Math.min(step.options.length - 1, this.selectedIndex + 1);
+      return;
+    }
+    if (matchesKey(data, Key.escape)) {
+      // Esc anywhere in ask == "later"
+      this.opts.onComplete({ decision: 'later' });
+      return;
+    }
+    if (matchesKey(data, Key.enter)) {
+      const chosen = step.options[this.selectedIndex];
+      if (chosen === undefined) return;
+      this.advance(chosen.value);
+      return;
+    }
+  }
+
+  /** Apply a chosen value and move the state machine forward. */
+  private advance(value: AnyChoice): void {
+    this.choices.push(value);
+    this.selectedIndex = 0;
+
+    const result: MigrationPromptResult = resolveMigrationScope(this.choices);
+    if (this.phase === 'ask1') {
+      if (value === 'now') {
+        this.phase = 'ask2';
+        return;
+      }
+      // 'later' | 'never'
+      this.opts.onComplete({ decision: value as 'later' | 'never' });
+      return;
+    }
+    // ask2 — either choice resolves the full scope; run migration immediately.
+    this.beginMigration(result);
+  }
+
+  /** Enter the progress phase and run the migration to completion. */
+  private beginMigration(result: MigrationPromptResult): void {
+    if (result.decision !== 'now' || result.scope === undefined) {
+      this.opts.onComplete({ decision: 'later' });
+      return;
+    }
+    this.enterProgress();
+    this.startSpinner();
+    this.opts.requestRender?.();
+    const run = this.opts.runMigration ?? realRunMigration;
+    void run({
+      plan: this.opts.plan,
+      scope: result.scope,
+      source: this.opts.sourceHome,
+      target: this.opts.targetHome,
+      onProgress: (msg) => {
+        this.reportStep(msg);
+        this.opts.requestRender?.();
+      },
+      onSessionProgress: (done, total) => {
+        this.reportSessionProgress(done, total);
+        this.opts.requestRender?.();
+      },
+    }).then(
+      (report) => {
+        this.showResult(report);
+        this.opts.requestRender?.();
+      },
+      () => {
+        this.showFailure();
+        this.opts.requestRender?.();
+      },
+    );
+  }
+
+  override render(width: number): string[] {
+    if (this.phase === 'ask1' || this.phase === 'ask2') {
+      return this.renderAsk(width);
+    }
+    if (this.phase === 'progress') return this.renderProgress(width);
+    return this.renderResult(width);
+  }
+
+  private renderResult(width: number): string[] {
+    const { colors } = this.opts;
+    const lines: string[] = [chalk.hex(colors.primary)('─'.repeat(width))];
+    if (this.migrationFailed) {
+      lines.push(chalk.hex(colors.error).bold(' Migration failed'));
+      lines.push('');
+      lines.push(chalk.hex(colors.text)(' You can retry later by running "kimi migrate".'));
+      lines.push('');
+      lines.push(chalk.hex(colors.textMuted)(' ⏎ continue to kimi-code'));
+      lines.push(chalk.hex(colors.primary)('─'.repeat(width)));
+      return lines.map((l) => truncateToWidth(l, width));
+    }
+    const r = this.report;
+    lines.push(chalk.hex(colors.primary).bold(' Migration complete'));
+    lines.push('');
+    if (r !== undefined) {
+      const sum = r.summary;
+      if (sum.sessions.sessionsMigrated > 0) {
+        lines.push(
+          chalk.hex(colors.success)(`  ✓ ${sum.sessions.sessionsMigrated} sessions migrated`),
+        );
+      }
+      // Only claim a data class was migrated when the summary says it was —
+      // a skipped/failed step (e.g. malformed config.toml) must not show ✓.
+      const migratedKinds: string[] = [];
+      if (sum.config.migrated) migratedKinds.push('config');
+      if (sum.config.migratedHooks > 0) migratedKinds.push('hooks');
+      if (sum.mcp.mergedServers.length > 0) migratedKinds.push('MCP');
+      if (sum.userHistory.copied > 0) migratedKinds.push('REPL history');
+      if (migratedKinds.length > 0) {
+        lines.push(chalk.hex(colors.success)(`  ✓ ${migratedKinds.join(' · ')}`));
+      }
+      if (sum.sessions.sessionsMigrated === 0 && migratedKinds.length === 0) {
+        lines.push(chalk.hex(colors.textMuted)('  Nothing needed migrating.'));
+      }
+      if (r.notices.detectedPlugins.length > 0) {
+        lines.push(
+          chalk.hex(colors.warning)(
+            `  ⚠ ${r.notices.detectedPlugins.length} kimi-cli plugins — not yet supported for migration`,
+          ),
+        );
+      }
+      if (r.notices.oauthLoginsRequiringRelogin.length > 0) {
+        lines.push(
+          chalk.hex(colors.warning)(
+            '  ⚠ kimi-cli login not migrated — run /login in kimi-code to sign in',
+          ),
+        );
+      }
+      if (sum.config.droppedHooks > 0) {
+        lines.push(
+          chalk.hex(colors.warning)(
+            `  ⚠ ${sum.config.droppedHooks} hooks dropped (incompatible)`,
+          ),
+        );
+      }
+      // Conflicts and partial failures: the report records them, so surface
+      // them here too — otherwise "✓ config / MCP" hides that the data only
+      // landed in a *.migrated-from-kimi-cli.* sibling or that sessions failed.
+      if (sum.config.configConflicts.length > 0) {
+        lines.push(
+          chalk.hex(colors.warning)(
+            `  ⚠ ${sum.config.configConflicts.length} config conflicts kept yours: ${sum.config.configConflicts.join(' · ')}`,
+          ),
+        );
+      }
+      if (sum.config.wroteSiblingDueToConflict) {
+        // Sibling mode: the live config.toml could not be parsed, so the
+        // migrated content went to `config.migrated-from-kimi-cli.toml` and
+        // the user must merge it by hand. Show the enumeration of contents
+        // on a SEPARATE line below — a single-line message with the contents
+        // appended would overflow 80 columns and be truncated, silently
+        // hiding the very info we want users to see.
+        lines.push(
+          chalk.hex(colors.warning)(
+            '  ⚠ config.toml could not be parsed — review config.migrated-from-kimi-cli.toml',
+          ),
+        );
+        const sc = sum.config.siblingContents;
+        const items: string[] = [];
+        if (sc.providers.length > 0) {
+          items.push(`${sc.providers.length} provider${sc.providers.length === 1 ? '' : 's'}`);
+        }
+        if (sc.models.length > 0) {
+          items.push(`${sc.models.length} model${sc.models.length === 1 ? '' : 's'}`);
+        }
+        if (sc.hooks > 0) {
+          items.push(`${sc.hooks} hook${sc.hooks === 1 ? '' : 's'}`);
+        }
+        if (items.length > 0) {
+          lines.push(chalk.hex(colors.warning)(`     contains: ${items.join(', ')}`));
+        }
+      }
+      if (sum.config.wroteTuiSibling) {
+        lines.push(
+          chalk.hex(colors.warning)(
+            '  ⚠ tui.toml conflicted — review tui.migrated-from-kimi-cli.toml',
+          ),
+        );
+      }
+      if (sum.mcp.wroteSiblingDueToConflict) {
+        lines.push(
+          chalk.hex(colors.warning)(
+            '  ⚠ mcp.json unreadable — review mcp.migrated-from-kimi-cli.json',
+          ),
+        );
+      }
+      if (r.notices.mcpOauthServersRequiringReauth.length > 0) {
+        lines.push(
+          chalk.hex(colors.warning)(
+            `  ⚠ ${r.notices.mcpOauthServersRequiringReauth.length} MCP servers need re-authentication`,
+          ),
+        );
+      }
+      if (sum.sessions.sessionsFailed.length > 0) {
+        lines.push(
+          chalk.hex(colors.warning)(
+            `  ⚠ ${sum.sessions.sessionsFailed.length} sessions failed to migrate`,
+          ),
+        );
+      }
+      if (sum.sessions.sessionsConflicts.length > 0) {
+        lines.push(
+          chalk.hex(colors.warning)(
+            `  ⚠ ${sum.sessions.sessionsConflicts.length} sessions skipped (target already occupied)`,
+          ),
+        );
+      }
+      // Empty / user-cleared sessions carry no conversation — neutral info,
+      // not a failure, so it is shown muted rather than as a ⚠ warning.
+      if (sum.sessions.sessionsSkippedEmpty > 0) {
+        lines.push(
+          chalk.hex(colors.textMuted)(
+            `  ${sum.sessions.sessionsSkippedEmpty} empty sessions skipped`,
+          ),
+        );
+      }
+      lines.push('');
+      lines.push(
+        chalk.hex(colors.textMuted)(' Old data kept at ~/.kimi/ — kimi-cli still works.'),
+      );
+    }
+    lines.push('');
+    lines.push(chalk.hex(colors.textMuted)(' ⏎ continue to kimi-code'));
+    lines.push(chalk.hex(colors.primary)('─'.repeat(width)));
+    return lines.map((l) => truncateToWidth(l, width));
+  }
+
+  private renderProgress(width: number): string[] {
+    const { colors } = this.opts;
+    const spinner = SPINNER_FRAMES[this.spinnerFrame] ?? SPINNER_FRAMES[0];
+    const lines: string[] = [
+      chalk.hex(colors.primary)('─'.repeat(width)),
+      chalk.hex(colors.primary).bold(' Migrating from kimi-cli'),
+      '',
+    ];
+    if (this.progressTotal > 0) {
+      lines.push(
+        chalk.hex(colors.accent)(`  ${spinner}  `) +
+          chalk.hex(colors.text)(
+            `Translating sessions…  ${this.progressDone} / ${this.progressTotal}`,
+          ),
+      );
+      lines.push('');
+    }
+    for (const [key, label] of STEP_LABELS) {
+      const status = this.stepStatus.get(key) ?? 'pending';
+      const mark =
+        status === 'done'
+          ? chalk.hex(colors.success)('✓')
+          : chalk.hex(colors.textDim)('◐');
+      lines.push(`  ${mark} ${chalk.hex(colors.text)(label)}`);
+    }
+    lines.push('');
+    lines.push(chalk.hex(colors.primary)('─'.repeat(width)));
+    return lines.map((l) => truncateToWidth(l, width));
+  }
+
+  private renderAsk(width: number): string[] {
+    const { colors } = this.opts;
+    const step = this.currentStep();
+    const lines: string[] = [
+      chalk.hex(colors.primary)('─'.repeat(width)),
+      chalk.hex(colors.primary).bold(' Migrate from kimi-cli'),
+      '',
+    ];
+    if (this.phase === 'ask1') {
+      lines.push(chalk.hex(colors.text)(' Found an existing kimi-cli installation:'));
+      lines.push(chalk.hex(colors.textMuted)(`   ${summarizePlan(this.opts.plan)}`));
+      lines.push('');
+    }
+    lines.push(chalk.hex(colors.text)(` ${step.title}`));
+    lines.push('');
+    for (let i = 0; i < step.options.length; i++) {
+      const opt = step.options[i]!;
+      const isSel = i === this.selectedIndex;
+      const pointer = isSel ? '❯' : ' ';
+      const labelStyle = isSel ? chalk.hex(colors.primary).bold : chalk.hex(colors.text);
+      lines.push(
+        chalk.hex(isSel ? colors.primary : colors.textDim)(`  ${pointer} `) +
+          labelStyle(opt.label),
+      );
+    }
+    lines.push('');
+    lines.push(
+      chalk.hex(colors.textMuted)(
+        ` ↑/↓ move · ⏎ select · esc ${this.opts.skipDecisionStep === true ? 'cancel' : 'later'}`,
+      ),
+    );
+    lines.push(chalk.hex(colors.primary)('─'.repeat(width)));
+    return lines.map((l) => truncateToWidth(l, width));
+  }
+}
+
+function summarizePlan(plan: MigrationPlan): string {
+  const parts: string[] = [];
+  if (plan.totalSessions > 0) parts.push(`${plan.totalSessions} sessions`);
+  if (plan.hasConfig) parts.push('config.toml');
+  if (plan.hasMcp) parts.push('mcp.json');
+  if (plan.hasUserHistory) parts.push('REPL history');
+  // OAuth credentials are detected but not migrated (refresh tokens rotate;
+  // re-login in kimi-code is the right answer). Surface the detection up
+  // front so an install whose only data is `credentials/*.json` does not
+  // render this line blank, and so the pre-migration screen stays consistent
+  // with the result screen's "kimi-cli login not migrated — run /login" line.
+  if (plan.oauthCredentials.length > 0) parts.push('kimi-cli login (needs /login)');
+  return parts.join(' · ');
+}
+
+function stepFor(phase: Phase, plan: MigrationPlan): StepDef {
+  if (phase === 'ask1') {
+    return {
+      title: 'Migrate this data to kimi-code?',
+      options: [
+        { label: 'Migrate now', value: 'now' satisfies Prompt1Choice },
+        { label: 'Ask me later', value: 'later' satisfies Prompt1Choice },
+        { label: 'Never ask again', value: 'never' satisfies Prompt1Choice },
+      ],
+    };
+  }
+  // ask2 — the second option carries the actual session count so users can see
+  // the cost they are signing up for. Falls back to the singular "sessions"
+  // word only (no count) when no sessions were detected.
+  const sessionsLabel =
+    plan.totalSessions > 0
+      ? `Config + ${plan.totalSessions} sessions`
+      : 'Config + all sessions';
+  return {
+    title: 'Migrate chat sessions too? (they are bulky and slower)',
+    options: [
+      { label: 'Config only', value: 'config-only' satisfies Prompt2Choice },
+      { label: sessionsLabel, value: 'all-sessions' satisfies Prompt2Choice },
+    ],
+  };
+}
diff --git a/apps/kimi-code/src/native/module-hook.ts b/apps/kimi-code/src/native/module-hook.ts
new file mode 100644
index 000000000..bbef5d4cb
--- /dev/null
+++ b/apps/kimi-code/src/native/module-hook.ts
@@ -0,0 +1,40 @@
+import { createRequire } from 'node:module';
+
+import { loadNativePackage } from './native-require';
+
+type ModuleLoad = (request: string, parent: unknown, isMain: boolean) => unknown;
+
+interface ModuleWithLoad {
+  _load?: ModuleLoad;
+}
+
+const nodeRequire = createRequire(import.meta.url);
+let installed = false;
+let loadingNativePackage = false;
+
+export function installNativeModuleHook(): void {
+  if (installed) return;
+  installed = true;
+
+  const moduleBuiltin = nodeRequire('node:module') as ModuleWithLoad;
+  const originalLoad = moduleBuiltin._load;
+  if (originalLoad === undefined) return;
+
+  moduleBuiltin._load = function loadWithNativeAssets(
+    this: unknown,
+    request: string,
+    parent: unknown,
+    isMain: boolean,
+  ): unknown {
+    if (request === 'koffi' && !loadingNativePackage) {
+      loadingNativePackage = true;
+      try {
+        const pkg = loadNativePackage<unknown>('koffi');
+        if (pkg !== null) return pkg;
+      } finally {
+        loadingNativePackage = false;
+      }
+    }
+    return originalLoad.call(this, request, parent, isMain);
+  };
+}
diff --git a/apps/kimi-code/src/native/native-assets.ts b/apps/kimi-code/src/native/native-assets.ts
new file mode 100644
index 000000000..576c8079e
--- /dev/null
+++ b/apps/kimi-code/src/native/native-assets.ts
@@ -0,0 +1,371 @@
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, join, win32 as pathWin32 } from 'node:path';
+
+import { KIMI_BUILD_INFO } from '#/cli/build-info';
+import { NATIVE_ASSET_MANIFEST_VERSION as MANIFEST_VERSION, buildManifestKey } from '../../scripts/native/manifest.mjs';
+
+export const NATIVE_ASSET_MANIFEST_VERSION = MANIFEST_VERSION;
+
+export interface NativeAssetFile {
+  readonly assetKey: string;
+  readonly relativePath: string;
+  readonly sha256: string;
+  readonly mode?: number;
+}
+
+export interface NativeAssetPackage {
+  readonly name: string;
+  readonly root: string;
+  readonly files: readonly NativeAssetFile[];
+}
+
+export interface NativeAssetManifest {
+  readonly version: typeof NATIVE_ASSET_MANIFEST_VERSION;
+  readonly target: string;
+  readonly packages: readonly NativeAssetPackage[];
+}
+
+export interface NativeAssetSource {
+  getAssetKeys(): readonly string[];
+  getRawAsset(assetKey: string): ArrayBuffer | ArrayBufferView | Buffer | string;
+}
+
+export interface NativeAssetOptions {
+  readonly source?: NativeAssetSource | null;
+  readonly manifest?: NativeAssetManifest | null;
+  readonly cacheBase?: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly platform?: NodeJS.Platform;
+  readonly homeDir?: string;
+  readonly version?: string;
+}
+
+type RawNativeAssetManifest = Omit<NativeAssetManifest, 'version'> & {
+  readonly version: number;
+};
+
+interface NodeSeaModule {
+  isSea(): boolean;
+  getAssetKeys(): string[];
+  getRawAsset(assetKey: string): ArrayBuffer;
+}
+
+const nodeRequire = createRequire(import.meta.url);
+let seaModule: NodeSeaModule | null | undefined;
+
+function loadSeaModule(): NodeSeaModule | null {
+  if (seaModule !== undefined) return seaModule;
+  try {
+    seaModule = nodeRequire('node:sea') as NodeSeaModule;
+  } catch {
+    seaModule = null;
+  }
+  return seaModule;
+}
+
+function currentTarget(): string {
+  return KIMI_BUILD_INFO.buildTarget ?? `${process.platform}-${process.arch}`;
+}
+
+export function nativeAssetManifestKey(target: string = currentTarget()): string {
+  return buildManifestKey(target);
+}
+
+function toBuffer(value: ArrayBuffer | ArrayBufferView | Buffer | string): Buffer {
+  if (Buffer.isBuffer(value)) return value;
+  if (typeof value === 'string') return Buffer.from(value);
+  if (ArrayBuffer.isView(value)) {
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  }
+  return Buffer.from(value);
+}
+
+function sha256(bytes: Buffer | Uint8Array | string): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function optionalEnvValue(env: NodeJS.ProcessEnv, key: string): string | null {
+  const value = env[key];
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function sanitizeSegment(value: string): string {
+  const sanitized = value.replaceAll(/[^a-zA-Z0-9._-]/g, '_');
+  return sanitized.length > 0 ? sanitized : 'unknown';
+}
+
+export function getSeaAssetSource(): NativeAssetSource | null {
+  const sea = loadSeaModule();
+  if (sea === null || !sea.isSea()) return null;
+  return {
+    getAssetKeys: () => sea.getAssetKeys(),
+    getRawAsset: (assetKey) => sea.getRawAsset(assetKey),
+  };
+}
+
+export function getEmbeddedNativeAssetManifest(
+  source = getSeaAssetSource(),
+  target = currentTarget(),
+): NativeAssetManifest | null {
+  if (source === null) return null;
+  const key = nativeAssetManifestKey(target);
+  if (!source.getAssetKeys().includes(key)) return null;
+  const raw = source.getRawAsset(key);
+  const manifest = JSON.parse(toBuffer(raw).toString('utf-8')) as RawNativeAssetManifest;
+  if (manifest.version !== NATIVE_ASSET_MANIFEST_VERSION) {
+    throw new Error(`Unsupported native asset manifest version: ${manifest.version}`);
+  }
+  if (manifest.target !== target) {
+    throw new Error(`Native asset manifest target mismatch: ${manifest.target} !== ${target}`);
+  }
+  return manifest as NativeAssetManifest;
+}
+
+export function getNativeCacheBase(options: NativeAssetOptions = {}): string {
+  if (options.cacheBase !== undefined) return options.cacheBase;
+
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+  const home = options.homeDir ?? homedir();
+
+  const cacheDirEnv = optionalEnvValue(env, 'KIMI_CODE_CACHE_DIR');
+  if (cacheDirEnv !== null) return cacheDirEnv;
+
+  if (platform === 'darwin') return join(home, 'Library', 'Caches', 'kimi-code');
+  if (platform === 'win32') {
+    const localAppData = optionalEnvValue(env, 'LOCALAPPDATA');
+    return localAppData !== null
+      ? pathWin32.join(localAppData, 'kimi-code')
+      : pathWin32.join(home, 'AppData', 'Local', 'kimi-code', 'Cache');
+  }
+
+  return join(optionalEnvValue(env, 'XDG_CACHE_HOME') ?? join(home, '.cache'), 'kimi-code');
+}
+
+export function getNativeAssetCacheRoot(
+  manifest: NativeAssetManifest,
+  options: NativeAssetOptions = {},
+): string {
+  const version = sanitizeSegment(options.version ?? KIMI_BUILD_INFO.version ?? 'dev');
+  const manifestHash = sha256(JSON.stringify(manifest));
+  return join(
+    getNativeCacheBase(options),
+    'native',
+    version,
+    sanitizeSegment(manifest.target),
+    manifestHash,
+  );
+}
+
+function readFileSha256(path: string): string | null {
+  try {
+    return sha256(readFileSync(path));
+  } catch {
+    return null;
+  }
+}
+
+function ensureFile(path: string, bytes: Buffer, expectedSha256: string, mode?: number): void {
+  if (readFileSha256(path) === expectedSha256) return;
+
+  mkdirSync(dirname(path), { recursive: true });
+  const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tempPath, bytes, { mode: mode ?? 0o644 });
+
+  try {
+    renameSync(tempPath, path);
+    return;
+  } catch {
+    if (readFileSha256(path) === expectedSha256) {
+      rmSync(tempPath, { force: true });
+      return;
+    }
+  }
+
+  try {
+    rmSync(path, { force: true });
+    renameSync(tempPath, path);
+  } catch (error) {
+    rmSync(tempPath, { force: true });
+    if (readFileSha256(path) === expectedSha256) return;
+    throw error;
+  }
+}
+
+function ensureEntryFile(cacheRoot: string): void {
+  const entryPath = join(cacheRoot, 'node_modules', '.kimi-native-entry.cjs');
+  ensureFile(
+    entryPath,
+    Buffer.from('module.exports = require;\n'),
+    sha256('module.exports = require;\n'),
+    0o644,
+  );
+}
+
+export function ensureNativeAssetTree(options: NativeAssetOptions = {}): string | null {
+  const source = options.source ?? getSeaAssetSource();
+  if (source === null) return null;
+
+  const manifest =
+    options.manifest ?? getEmbeddedNativeAssetManifest(source, currentTarget());
+  if (manifest === null) return null;
+
+  const cacheRoot = getNativeAssetCacheRoot(manifest, options);
+  for (const pkg of manifest.packages) {
+    for (const file of pkg.files) {
+      const bytes = toBuffer(source.getRawAsset(file.assetKey));
+      const actualSha256 = sha256(bytes);
+      if (actualSha256 !== file.sha256) {
+        throw new Error(
+          `Native asset checksum mismatch for ${file.assetKey}: ${actualSha256} !== ${file.sha256}`,
+        );
+      }
+      ensureFile(join(cacheRoot, file.relativePath), bytes, file.sha256, file.mode);
+    }
+  }
+  ensureEntryFile(cacheRoot);
+  return cacheRoot;
+}
+
+export function getNativePackageRoot(
+  packageName: string,
+  options: NativeAssetOptions = {},
+): string | null {
+  const source = options.source ?? getSeaAssetSource();
+  if (source === null) return null;
+
+  const manifest =
+    options.manifest ?? getEmbeddedNativeAssetManifest(source, currentTarget());
+  if (manifest === null) return null;
+
+  const pkg = manifest.packages.find((entry) => entry.name === packageName);
+  if (pkg === undefined) return null;
+
+  const cacheRoot = ensureNativeAssetTree({ ...options, source, manifest });
+  return cacheRoot === null ? null : join(cacheRoot, pkg.root);
+}
+
+export function hasNativePackage(packageName: string, manifest: NativeAssetManifest): boolean {
+  return manifest.packages.some((pkg) => pkg.name === packageName);
+}
+
+export function nativeAssetCacheExists(
+  packageName: string,
+  options: NativeAssetOptions = {},
+): boolean {
+  const root = getNativePackageRoot(packageName, options);
+  return root !== null && existsSync(root);
+}
+
+export interface CleanupOptions {
+  readonly cacheBase: string;
+  readonly version: string;
+  readonly target: string;
+  readonly currentRoot: string;
+}
+
+export interface CleanupResult {
+  readonly kept: string[];
+  readonly removed: string[];
+  readonly errors: Array<{ path: string; error: unknown }>;
+}
+
+/**
+ * Remove stale native asset cache directories for the current (version, target).
+ *
+ * Keeps:
+ *   - the currentRoot (passed in by caller)
+ *   - the most recently modified sibling (defensive: in case currentRoot calc changed)
+ *
+ * Deletes all other sibling <manifest-hash> directories. Other versions and
+ * other targets are never touched. Errors per-entry are collected and returned
+ * (never throw — this is fire-and-forget background work).
+ */
+export function cleanupStaleNativeCache(options: CleanupOptions): CleanupResult {
+  const { cacheBase, version, target, currentRoot } = options;
+  const targetDir = join(cacheBase, 'native', version, target);
+  const result: CleanupResult = { kept: [], removed: [], errors: [] };
+
+  let entries: string[];
+  try {
+    entries = readdirSync(targetDir);
+  } catch {
+    return result;
+  }
+
+  const siblings: Array<{ path: string; mtimeMs: number }> = [];
+  for (const name of entries) {
+    const path = join(targetDir, name);
+    try {
+      const st = statSync(path);
+      if (!st.isDirectory()) continue;
+      siblings.push({ path, mtimeMs: st.mtimeMs });
+    } catch (error) {
+      (result.errors as Array<{ path: string; error: unknown }>).push({ path, error });
+    }
+  }
+
+  if (siblings.length === 0) return result;
+
+  // sort newest first
+  siblings.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  // Defensive: keep the most recently modified sibling that is not currentRoot
+  // so a previously-written cache survives in case currentRoot calc changed.
+  const mostRecentOther = siblings.find((entry) => entry.path !== currentRoot)?.path;
+  const keepSet = new Set<string>(
+    mostRecentOther === undefined ? [currentRoot] : [currentRoot, mostRecentOther],
+  );
+
+  for (const { path } of siblings) {
+    if (keepSet.has(path)) {
+      result.kept.push(path);
+      continue;
+    }
+    try {
+      rmSync(path, { recursive: true, force: true });
+      result.removed.push(path);
+    } catch (error) {
+      (result.errors as Array<{ path: string; error: unknown }>).push({ path, error });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Convenience: discover currentRoot from embedded manifest + run cleanup.
+ * Safe to call without args from main.ts startup. Returns null if not in SEA mode.
+ */
+export function cleanupStaleNativeCacheForCurrent(
+  options: NativeAssetOptions = {},
+): CleanupResult | null {
+  const source = options.source ?? getSeaAssetSource();
+  if (source === null) return null;
+
+  const manifest =
+    options.manifest ?? getEmbeddedNativeAssetManifest(source, currentTarget());
+  if (manifest === null) return null;
+
+  const cacheBase = getNativeCacheBase(options);
+  const version = KIMI_BUILD_INFO.version ?? 'dev';
+  const currentRoot = getNativeAssetCacheRoot(manifest, options);
+
+  return cleanupStaleNativeCache({
+    cacheBase,
+    version,
+    target: manifest.target,
+    currentRoot,
+  });
+}
diff --git a/apps/kimi-code/src/native/native-require.ts b/apps/kimi-code/src/native/native-require.ts
new file mode 100644
index 000000000..6840d610b
--- /dev/null
+++ b/apps/kimi-code/src/native/native-require.ts
@@ -0,0 +1,30 @@
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+
+import {
+  ensureNativeAssetTree,
+  getNativePackageRoot,
+  type NativeAssetOptions,
+} from './native-assets';
+
+export function createNativePackageRequire(
+  packageName: string,
+  options: NativeAssetOptions = {},
+): ReturnType<typeof createRequire> | null {
+  const packageRoot = getNativePackageRoot(packageName, options);
+  if (packageRoot === null) return null;
+
+  const cacheRoot = ensureNativeAssetTree(options);
+  if (cacheRoot === null) return null;
+
+  return createRequire(join(cacheRoot, 'node_modules', '.kimi-native-entry.cjs'));
+}
+
+export function loadNativePackage<T>(
+  packageName: string,
+  options: NativeAssetOptions = {},
+): T | null {
+  const nativeRequire = createNativePackageRequire(packageName, options);
+  if (nativeRequire === null) return null;
+  return nativeRequire(packageName) as T;
+}
diff --git a/apps/kimi-code/src/native/smoke.ts b/apps/kimi-code/src/native/smoke.ts
new file mode 100644
index 000000000..56d39253f
--- /dev/null
+++ b/apps/kimi-code/src/native/smoke.ts
@@ -0,0 +1,26 @@
+import { getEmbeddedNativeAssetManifest, getNativePackageRoot } from './native-assets';
+
+const smokePackages = ['@mariozechner/clipboard', 'koffi'];
+
+export function runNativeAssetSmokeIfRequested(): boolean {
+  if (process.env['KIMI_CODE_NATIVE_ASSET_SMOKE'] !== '1') return false;
+
+  try {
+    const manifest = getEmbeddedNativeAssetManifest();
+    if (manifest === null) {
+      throw new Error('Native asset manifest is not available.');
+    }
+    for (const packageName of smokePackages) {
+      const packageRoot = getNativePackageRoot(packageName, { manifest });
+      if (packageRoot === null) {
+        throw new Error(`Native package is not available: ${packageName}`);
+      }
+    }
+    process.stdout.write(`Native asset smoke passed: ${manifest.target}\n`);
+    process.exit(0);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Native asset smoke failed: ${message}\n`);
+    process.exit(1);
+  }
+}
diff --git a/apps/kimi-code/src/tui/actions/replay-ops.ts b/apps/kimi-code/src/tui/actions/replay-ops.ts
new file mode 100644
index 000000000..8b11a2c7a
--- /dev/null
+++ b/apps/kimi-code/src/tui/actions/replay-ops.ts
@@ -0,0 +1,699 @@
+/**
+ * Session replay hydration.
+ *
+ * Core owns durable history as raw session records. The TUI projects those
+ * records into the same transcript entries/components used by live events,
+ * without mutating core session state or responding to replayed data.
+ */
+
+import type {
+  AgentReplayRecord,
+  BackgroundTaskInfo,
+  ContentPart,
+  ContextMessage,
+  PromptOrigin,
+  PermissionMode,
+  ResumedAgentState,
+  Session,
+  ToolCall,
+} from '@moonshot-ai/kimi-code-sdk';
+
+import { AgentGroupComponent } from '#/tui/components/messages/agent-group';
+import type { TodoItem } from '#/tui/components/chrome/todo-panel';
+import { ToolCallComponent } from '#/tui/components/messages/tool-call';
+import type { TUIState } from '#/tui/kimi-tui';
+import type {
+  AppState,
+  BackgroundAgentMetadata,
+  BackgroundAgentStatusData,
+  ToolCallBlockData,
+  TranscriptEntry,
+} from '#/tui/types';
+import { formatErrorMessage, isTodoItemShape } from '#/tui/utils/event-payload';
+import { formatBackgroundAgentTranscript } from '#/tui/utils/background-agent-status';
+import { mediaUrlPartToText } from '#/tui/utils/media-url';
+import { nextTranscriptId } from '#/tui/utils/transcript-id';
+
+export interface ReplayHydrationHooks {
+  readonly setAppState: (patch: Partial<AppState>) => void;
+  readonly appendEntry: (entry: TranscriptEntry) => void;
+  readonly setTodoList: (todos: readonly TodoItem[]) => void;
+  readonly emitError: (message: string) => void;
+}
+
+interface ReplayProjection {
+  readonly entries: readonly TranscriptEntry[];
+  /**
+   * Background subagents still not completed or failed when replay ends,
+   * keyed by agent_id. `hydrateTranscriptFromReplay` seeds
+   * `state.backgroundAgents` from this so the footer badge starts accurate.
+   */
+  readonly backgroundAgents: ReadonlySet<string>;
+  /**
+   * Background agent metadata that remains needed after replay so live
+   * terminal events can keep rendering transcript copy after resume.
+   */
+  readonly backgroundAgentMetadata: ReadonlyMap<string, BackgroundAgentMetadata>;
+}
+
+interface OpenAssistant {
+  thinking: string[];
+  text: string[];
+}
+
+interface ProjectionState {
+  entries: TranscriptEntry[];
+  toolCalls: Map<string, ToolCallBlockData>;
+  assistant: OpenAssistant;
+  skillActivationIds: Set<string>;
+  permissionMode?: PermissionMode;
+  backgroundAgents: Set<string>;
+  backgroundAgentMetadata: Map<string, BackgroundAgentMetadata>;
+  backgroundTasks: ReadonlyMap<string, BackgroundTaskInfo>;
+}
+
+type BackgroundTaskOrigin = Extract<PromptOrigin, { kind: 'background_task' }>;
+
+const REPLAY_TURN_LIMIT = 10;
+
+export async function hydrateTranscriptFromReplay(
+  state: TUIState,
+  hooks: ReplayHydrationHooks,
+  session: Session,
+): Promise<boolean> {
+  hooks.setAppState({ isReplaying: true });
+  try {
+    const main = session.getResumeState()?.agents['main'];
+    if (main === undefined) {
+      hooks.emitError('Session history is unavailable for this session.');
+      return false;
+    }
+
+    const projection = projectReplayRecords(main.replay, main.background);
+    hydrateProjectedEntries(state, projection.entries, hooks.appendEntry);
+    hydrateTodoPanelFromResume(main, hooks);
+    state.backgroundAgents = new Set(projection.backgroundAgents);
+    state.backgroundAgentMetadata = new Map(projection.backgroundAgentMetadata);
+
+    // Seed the BPM-derived store from the resume snapshot. This is the
+    // authoritative source for footer count + transcript dedupe; the
+    // subagent-derived `backgroundAgents` set above is kept for legacy
+    // metadata lookups (agent name / description) until removed.
+    state.backgroundTasks = new Map<string, BackgroundTaskInfo>(
+      main.background.map((info) => [info.taskId, info]),
+    );
+    state.backgroundTaskTranscriptedTerminal.clear();
+    // Resumed terminal tasks should not re-emit transcript cards.
+    for (const info of main.background) {
+      if (
+        info.status === 'completed' ||
+        info.status === 'failed' ||
+        info.status === 'killed' ||
+        info.status === 'lost'
+      ) {
+        state.backgroundTaskTranscriptedTerminal.add(info.taskId);
+      }
+    }
+    const counts = countActiveBackgroundTasks(state.backgroundTasks);
+    state.footer.setBackgroundCounts(counts);
+    hooks.setAppState(appStateFromResumeAgent(main));
+    return true;
+  } catch (error) {
+    const message = formatErrorMessage(error);
+    hooks.emitError(`Failed to replay session history: ${message}`);
+    return false;
+  } finally {
+    hooks.setAppState({ isReplaying: false });
+  }
+}
+
+function hydrateTodoPanelFromResume(
+  agent: ResumedAgentState,
+  hooks: ReplayHydrationHooks,
+): void {
+  const rawTodos = agent.toolStore?.['todo'];
+  if (!Array.isArray(rawTodos)) {
+    hooks.setTodoList([]);
+    return;
+  }
+  const todos = rawTodos
+    .filter((todo): todo is TodoItem => isTodoItemShape(todo))
+    .map((todo) => ({ title: todo.title, status: todo.status }));
+  hooks.setTodoList(todos);
+}
+
+function countActiveBackgroundTasks(tasks: ReadonlyMap<string, BackgroundTaskInfo>): {
+  bashTasks: number;
+  agentTasks: number;
+} {
+  let bashTasks = 0;
+  let agentTasks = 0;
+  for (const info of tasks.values()) {
+    if (
+      info.status === 'completed' ||
+      info.status === 'failed' ||
+      info.status === 'killed' ||
+      info.status === 'lost'
+    ) {
+      continue;
+    }
+    if (info.taskId.startsWith('agent-')) {
+      agentTasks += 1;
+    } else {
+      bashTasks += 1;
+    }
+  }
+  return { bashTasks, agentTasks };
+}
+
+function appStateFromResumeAgent(agent: ResumedAgentState): Partial<AppState> {
+  const maxContextTokens = agent.config.modelCapabilities?.max_context_tokens ?? 0;
+  const contextTokens = agent.context.tokenCount;
+  const contextUsage = maxContextTokens > 0 ? contextTokens / maxContextTokens : 0;
+  return {
+    // `?? ''` so a resumed session with no resolvable model yields a string,
+    // not `undefined` — the editor's `appState.model.trim()` would otherwise
+    // throw. An empty model surfaces the normal "LLM not set" state.
+    model: agent.config.modelAlias ?? agent.config.provider?.model ?? '',
+    contextTokens,
+    maxContextTokens,
+    contextUsage,
+    planMode: agent.plan !== null,
+    yolo: agent.permission.mode === 'yolo',
+    permissionMode: agent.permission.mode,
+  };
+}
+
+export function projectReplayRecords(
+  records: readonly AgentReplayRecord[],
+  backgroundTasks: readonly BackgroundTaskInfo[] = [],
+): ReplayProjection {
+  const state: ProjectionState = {
+    entries: [],
+    toolCalls: new Map(),
+    assistant: { thinking: [], text: [] },
+    skillActivationIds: new Set<string>(),
+    backgroundAgents: new Set<string>(),
+    backgroundAgentMetadata: new Map<string, BackgroundAgentMetadata>(),
+    backgroundTasks: new Map(backgroundTasks.map((info) => [info.taskId, info])),
+  };
+
+  for (const record of limitReplayRecordsByTurn(records, REPLAY_TURN_LIMIT)) {
+    projectReplayRecord(state, record);
+  }
+  flushAssistant(state);
+
+  return {
+    entries: state.entries,
+    backgroundAgents: state.backgroundAgents,
+    backgroundAgentMetadata: state.backgroundAgentMetadata,
+  };
+}
+
+function limitReplayRecordsByTurn(
+  records: readonly AgentReplayRecord[],
+  maxTurns: number,
+): readonly AgentReplayRecord[] {
+  if (maxTurns <= 0) return [];
+
+  const turnStarts = records.flatMap((record, index) =>
+    isReplayUserTurnRecord(record) ? [index] : [],
+  );
+  if (turnStarts.length <= maxTurns) return records;
+
+  return records.slice(turnStarts[turnStarts.length - maxTurns]);
+}
+
+function isReplayUserTurnRecord(record: AgentReplayRecord): boolean {
+  if (record.type !== 'message') return false;
+  const { message } = record;
+  if (message.role !== 'user') return false;
+  switch (message.origin?.kind) {
+    case undefined:
+    case 'user':
+      return true;
+    case 'skill_activation':
+      return message.origin.trigger === 'user-slash';
+    case 'background_task':
+    case 'compaction_summary':
+    case 'hook_result':
+    case 'injection':
+    case 'system_trigger':
+      return false;
+  }
+}
+
+function projectReplayRecord(state: ProjectionState, record: AgentReplayRecord): void {
+  switch (record.type) {
+    case 'message':
+      projectContextMessage(state, record.message);
+      return;
+    case 'plan_updated':
+      flushAssistant(state);
+      state.entries.push(entry('status', `Plan mode: ${record.enabled ? 'ON' : 'OFF'}`, 'notice'));
+      return;
+    case 'permission_updated':
+      flushAssistant(state);
+      projectPermissionUpdate(state, record.mode);
+      return;
+    case 'approval_result': {
+      flushAssistant(state);
+      const { record: approvalRecord } = record;
+      const { result } = approvalRecord;
+      const parts: string[] = [];
+      switch (result.decision) {
+        case 'approved':
+          parts.push(result.scope === 'session' ? 'Approved for session' : 'Approved');
+          break;
+        case 'rejected':
+          parts.push('Rejected');
+          break;
+        case 'cancelled':
+          parts.push('Cancelled');
+          break;
+      }
+      parts.push(`: ${approvalRecord.action}`);
+      if (result.feedback !== undefined && result.feedback.length > 0) {
+        parts.push(` — "${result.feedback}"`);
+      }
+      state.entries.push(entry('status', parts.join(''), 'notice'));
+      return;
+    }
+    case 'config_updated':
+      return;
+  }
+}
+
+function projectPermissionUpdate(state: ProjectionState, mode: PermissionMode): void {
+  if (mode === 'yolo') {
+    state.entries.push(
+      entry('status', 'YOLO mode: ON', 'notice', {
+        detail: 'All actions will be approved automatically. Use with caution.',
+      }),
+    );
+    state.permissionMode = mode;
+    return;
+  }
+  if (state.permissionMode === 'yolo' && mode === 'manual') {
+    state.entries.push(entry('status', 'YOLO mode: OFF', 'notice'));
+    state.permissionMode = mode;
+    return;
+  }
+  state.entries.push(entry('status', `Permission mode: ${mode}`, 'notice'));
+  state.permissionMode = mode;
+}
+
+interface SkillActivationProjection {
+  readonly activationId: string;
+  readonly skillName: string;
+  readonly skillArgs?: string;
+}
+
+function projectSkillActivation(
+  state: ProjectionState,
+  skill: SkillActivationProjection | undefined,
+): void {
+  if (skill === undefined) return;
+  if (state.skillActivationIds.has(skill.activationId)) return;
+  state.skillActivationIds.add(skill.activationId);
+  state.entries.push(
+    entry('skill_activation', `Activated skill: ${skill.skillName}`, 'plain', {
+      skillActivationId: skill.activationId,
+      skillName: skill.skillName,
+      skillArgs: skill.skillArgs,
+    }),
+  );
+}
+
+function projectContextMessage(state: ProjectionState, message: ContextMessage): void {
+  switch (message.role) {
+    case 'user': {
+      const origin = backgroundOrigin(message);
+      if (origin !== undefined) {
+        flushAssistant(state);
+        projectBackgroundTaskNotification(state, origin);
+        return;
+      }
+      if (message.origin?.kind === 'hook_result') {
+        projectHookResultMessage(state, message);
+        return;
+      }
+      if (message.origin?.kind === 'injection') {
+        return;
+      }
+      flushAssistant(state);
+      const skill = skillActivationFromOrigin(message.origin);
+      if (skill !== undefined) {
+        projectSkillActivation(state, skill);
+        return;
+      }
+      state.entries.push(entry('user', contentPartsToText(message.content), 'plain'));
+      return;
+    }
+    case 'assistant':
+      if (message.origin?.kind === 'hook_result') {
+        projectHookResultMessage(state, message);
+        projectMessageToolCalls(state, message.toolCalls);
+        return;
+      }
+      collectMessageContent(state.assistant, message.content);
+      flushAssistant(state);
+      projectMessageToolCalls(state, message.toolCalls);
+      return;
+    case 'tool':
+      flushAssistant(state);
+      projectMessageToolResult(state, message);
+      return;
+    case 'system':
+      return;
+    default:
+      return;
+  }
+}
+
+function projectMessageToolCalls(state: ProjectionState, toolCalls: readonly ToolCall[]): void {
+  for (const rawToolCall of toolCalls) {
+    const toolCall = toolCallFromMessage(rawToolCall);
+    if (toolCall === undefined) continue;
+    state.toolCalls.set(toolCall.id, toolCall);
+    state.entries.push(
+      entry('tool_call', '', 'plain', {
+        toolCallData: toolCall,
+      }),
+    );
+  }
+}
+
+function projectMessageToolResult(state: ProjectionState, message: ContextMessage): void {
+  const toolCallId = message.toolCallId;
+  if (toolCallId === undefined) return;
+  const call = state.toolCalls.get(toolCallId);
+  if (call === undefined) return;
+  call.result = {
+    tool_call_id: toolCallId,
+    output: toolResultOutput(message.content),
+    is_error: message.isError,
+  };
+}
+
+function projectBackgroundTaskNotification(
+  state: ProjectionState,
+  origin: BackgroundTaskOrigin,
+): void {
+  const task = state.backgroundTasks.get(origin.taskId);
+  const meta: BackgroundAgentMetadata = {
+    agentId: origin.taskId,
+    parentToolCallId: origin.taskId,
+    description: task?.description,
+  };
+  let status = formatBackgroundAgentTranscript(
+    origin.status === 'completed' ? 'completed' : 'failed',
+    meta,
+  );
+  if (origin.status === 'lost') {
+    status = {
+      ...status,
+      headline: status.headline.replace(' failed in background', ' lost in background'),
+    };
+  } else if (origin.status === 'killed') {
+    status = {
+      ...status,
+      headline: status.headline.replace(' failed in background', ' stopped'),
+    };
+  }
+  state.entries.push(
+    entry('status', status.headline, 'plain', {
+      detail: status.detail,
+      backgroundAgentStatus: status,
+    }),
+  );
+  state.backgroundAgents.delete(meta.agentId);
+  state.backgroundAgentMetadata.delete(meta.agentId);
+}
+
+function toolResultOutput(content: readonly ContentPart[]): string {
+  if (content.some((part) => part.type !== 'text')) {
+    return JSON.stringify(content);
+  }
+  return contentPartsToText(content);
+}
+
+function flushAssistant(state: ProjectionState): void {
+  const thinking = state.assistant.thinking.join('');
+  const text = state.assistant.text.join('');
+  state.assistant = { thinking: [], text: [] };
+  if (thinking.length > 0) {
+    state.entries.push(entry('thinking', thinking, 'plain'));
+  }
+  if (text.length > 0) {
+    state.entries.push(entry('assistant', text, 'markdown'));
+  }
+}
+
+function projectHookResultMessage(state: ProjectionState, message: ContextMessage): void {
+  if (message.origin?.kind !== 'hook_result') return;
+  flushAssistant(state);
+  state.entries.push(
+    entry(
+      'assistant',
+      formatHookResultMessageForTranscript(
+        contentPartsToText(message.content),
+        message.origin.event,
+        message.origin.blocked === true,
+      ),
+      'markdown',
+    ),
+  );
+}
+
+const HOOK_RESULT_RE =
+  /<hook_result\s+hook_event="([^"]+)">\n?([\s\S]*?)\n?<\/hook_result>/g;
+
+function formatHookResultMessageForTranscript(
+  text: string,
+  fallbackEvent: string,
+  blocked: boolean,
+): string {
+  const results: Array<{ event: string; body: string }> = [];
+  let lastIndex = 0;
+
+  for (const match of text.matchAll(HOOK_RESULT_RE)) {
+    if (text.slice(lastIndex, match.index).trim().length > 0) {
+      return formatHookResultBlock(fallbackEvent, text, blocked);
+    }
+    const event = match[1];
+    const body = match[2];
+    if (event === undefined || body === undefined) {
+      return formatHookResultBlock(fallbackEvent, text, blocked);
+    }
+    results.push({ event, body });
+    lastIndex = match.index + match[0].length;
+  }
+
+  if (results.length === 0 || text.slice(lastIndex).trim().length > 0) {
+    return formatHookResultBlock(fallbackEvent, text, blocked);
+  }
+
+  return results.map(({ event, body }) => formatHookResultBlock(event, body, blocked)).join('\n\n');
+}
+
+function formatHookResultBlock(event: string, body: string, blocked: boolean): string {
+  return `*${event} hook${blocked ? ' blocked' : ''}*\n\n${body.trim() || '(empty)'}`;
+}
+
+function collectMessageContent(target: OpenAssistant, content: readonly ContentPart[]): void {
+  for (const part of content) {
+    switch (part.type) {
+      case 'think':
+        target.thinking.push(part.think);
+        break;
+      case 'text':
+        target.text.push(part.text);
+        break;
+      case 'audio_url':
+      case 'image_url':
+      case 'video_url':
+        break;
+    }
+  }
+}
+
+function toolCallFromMessage(rawToolCall: ToolCall): ToolCallBlockData | undefined {
+  const id = rawToolCall.id;
+  const name = rawToolCall.function.name;
+  if (id.length === 0 || name.length === 0) return undefined;
+  return {
+    id,
+    name,
+    args: parseToolArguments(rawToolCall.function.arguments),
+  };
+}
+
+function parseToolArguments(value: string | null): Record<string, unknown> {
+  if (value === null || value.length === 0) return {};
+  try {
+    const parsed = JSON.parse(value);
+    return isObject(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function entry(
+  kind: TranscriptEntry['kind'],
+  content: string,
+  renderMode: TranscriptEntry['renderMode'],
+  extras?: {
+    turnId?: string;
+    toolCallData?: ToolCallBlockData;
+    detail?: string;
+    color?: string;
+    backgroundAgentStatus?: BackgroundAgentStatusData;
+    skillActivationId?: string;
+    skillName?: string;
+    skillArgs?: string;
+  },
+): TranscriptEntry {
+  return {
+    id: nextTranscriptId(),
+    kind,
+    renderMode,
+    content,
+    turnId: extras?.turnId,
+    detail: extras?.detail,
+    color: extras?.color,
+    toolCallData: extras?.toolCallData,
+    backgroundAgentStatus: extras?.backgroundAgentStatus,
+    skillActivationId: extras?.skillActivationId,
+    skillName: extras?.skillName,
+    skillArgs: extras?.skillArgs,
+  };
+}
+
+function contentPartsToText(content: readonly ContentPart[]): string {
+  return content.map(userPartToText).join('');
+}
+
+function backgroundOrigin(message: ContextMessage): BackgroundTaskOrigin | undefined {
+  return message.origin?.kind === 'background_task' ? message.origin : undefined;
+}
+
+function userPartToText(part: ContentPart): string {
+  switch (part.type) {
+    case 'text':
+      return part.text;
+    case 'think':
+      return part.think;
+    case 'image_url':
+      return mediaUrlPartToText('image', part.imageUrl.url);
+    case 'video_url':
+      return mediaUrlPartToText('video', part.videoUrl.url);
+    case 'audio_url':
+      return mediaUrlPartToText('audio', part.audioUrl.url);
+  }
+}
+
+function skillActivationFromOrigin(
+  origin: PromptOrigin | undefined,
+): SkillActivationProjection | undefined {
+  if (origin?.kind !== 'skill_activation') return undefined;
+  return {
+    activationId: origin.activationId,
+    skillName: origin.skillName,
+    skillArgs: origin.skillArgs,
+  };
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Inject projected flat entries into live state. Adjacent Agent tool_call
+ * entries sharing `(turnId, step)` are grouped into an AgentGroupComponent so
+ * replay matches live behavior. Other entries use the original append path.
+ *
+ * Unlike `tryAttachAgentToolCall`, this does not write
+ * `state.pendingAgentGroup`; after replay, live events must take over from a
+ * clean pending group state.
+ */
+export function hydrateProjectedEntries(
+  state: TUIState,
+  entries: readonly TranscriptEntry[],
+  appendEntry: (entry: TranscriptEntry) => void,
+): void {
+  let i = 0;
+  while (i < entries.length) {
+    const cur = entries[i];
+    if (cur === undefined) {
+      i += 1;
+      continue;
+    }
+    if (cur.kind === 'skill_activation' && cur.skillActivationId !== undefined) {
+      if (state.renderedSkillActivationIds.has(cur.skillActivationId)) {
+        i += 1;
+        continue;
+      }
+      state.renderedSkillActivationIds.add(cur.skillActivationId);
+    }
+    const tc = cur.toolCallData;
+    if (
+      cur.kind === 'tool_call' &&
+      tc !== undefined &&
+      tc.name === 'Agent' &&
+      tc.step !== undefined
+    ) {
+      // Collect all adjacent Agent calls with the same step and turn id.
+      const batch: TranscriptEntry[] = [cur];
+      let j = i + 1;
+      while (j < entries.length) {
+        const next = entries[j];
+        if (next === undefined) break;
+        const nextTc = next.toolCallData;
+        if (
+          next.kind === 'tool_call' &&
+          nextTc !== undefined &&
+          nextTc.name === 'Agent' &&
+          nextTc.step === tc.step &&
+          nextTc.turnId === tc.turnId
+        ) {
+          batch.push(next);
+          j++;
+          continue;
+        }
+        break;
+      }
+      if (batch.length >= 2) {
+        attachAgentBatchAsGroup(state, batch);
+        i = j;
+        continue;
+      }
+      // A single Agent stays on the standalone card path.
+    }
+    appendEntry(cur);
+    i++;
+  }
+}
+
+function attachAgentBatchAsGroup(state: TUIState, batch: readonly TranscriptEntry[]): void {
+  const group = new AgentGroupComponent(state.theme.colors, state.ui);
+  state.transcriptContainer.addChild(group);
+  for (const item of batch) {
+    const tc = item.toolCallData;
+    if (tc === undefined) continue;
+    state.transcriptEntries.push(item);
+    const component = new ToolCallComponent(
+      tc,
+      tc.result,
+      state.theme.colors,
+      state.ui,
+      state.theme.markdownTheme,
+      state.appState.workDir,
+    );
+    if (state.toolOutputExpanded) component.setExpanded(true);
+    if (state.planExpanded) component.setPlanExpanded(true);
+    state.pendingToolComponents.set(tc.id, component);
+    group.attach(tc.id, component);
+  }
+  state.ui.requestRender();
+}
diff --git a/apps/kimi-code/src/tui/commands/index.ts b/apps/kimi-code/src/tui/commands/index.ts
new file mode 100644
index 000000000..fab43f75c
--- /dev/null
+++ b/apps/kimi-code/src/tui/commands/index.ts
@@ -0,0 +1,5 @@
+export * from './parse';
+export * from './registry';
+export * from './resolve';
+export * from './skills';
+export * from './types';
diff --git a/apps/kimi-code/src/tui/commands/parse.ts b/apps/kimi-code/src/tui/commands/parse.ts
new file mode 100644
index 000000000..ee19d3585
--- /dev/null
+++ b/apps/kimi-code/src/tui/commands/parse.ts
@@ -0,0 +1,12 @@
+import type { ParsedSlashInput } from './types';
+
+export function parseSlashInput(input: string): ParsedSlashInput | null {
+  if (!input.startsWith('/')) return null;
+  const trimmed = input.slice(1).trim();
+  if (trimmed.length === 0) return null;
+  const spaceIdx = trimmed.indexOf(' ');
+  const name = spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx);
+  const args = spaceIdx === -1 ? '' : trimmed.slice(spaceIdx + 1).trim();
+  if (name.includes('/')) return null;
+  return { name, args };
+}
diff --git a/apps/kimi-code/src/tui/commands/registry.ts b/apps/kimi-code/src/tui/commands/registry.ts
new file mode 100644
index 000000000..5195bf5e7
--- /dev/null
+++ b/apps/kimi-code/src/tui/commands/registry.ts
@@ -0,0 +1,181 @@
+import type { KimiSlashCommand, SlashCommandAvailability } from './types';
+
+export const BUILTIN_SLASH_COMMANDS = [
+  {
+    name: 'yolo',
+    aliases: ['yes'],
+    description: 'Toggle auto-approve mode',
+    priority: 100,
+    availability: 'always',
+  },
+  {
+    name: 'permission',
+    aliases: [],
+    description: 'Select permission mode',
+    priority: 100,
+    availability: 'always',
+  },
+  {
+    name: 'settings',
+    aliases: ['config'],
+    description: 'Open TUI settings',
+    priority: 100,
+    availability: 'always',
+  },
+  {
+    name: 'plan',
+    aliases: [],
+    description: 'Toggle plan mode',
+    priority: 100,
+    availability: (args) => (args.trim().toLowerCase() === 'clear' ? 'idle-only' : 'always'),
+  },
+  {
+    name: 'model',
+    aliases: [],
+    description: 'Switch LLM model',
+    priority: 100,
+    availability: 'always',
+  },
+  {
+    name: 'help',
+    aliases: ['h', '?'],
+    description: 'Show available commands and shortcuts',
+    priority: 80,
+    availability: 'always',
+  },
+  {
+    name: 'new',
+    aliases: ['clear'],
+    description: 'Start a fresh session in the current workspace',
+    priority: 80,
+  },
+  {
+    name: 'sessions',
+    aliases: ['resume'],
+    description: 'Browse and resume sessions',
+    priority: 80,
+    availability: 'always',
+  },
+  {
+    name: 'tasks',
+    aliases: ['task'],
+    description: 'Browse background tasks',
+    priority: 80,
+    availability: 'always',
+  },
+  {
+    name: 'mcp',
+    aliases: [],
+    description: 'Show MCP server status',
+    priority: 60,
+    availability: 'always',
+  },
+  {
+    name: 'compact',
+    aliases: [],
+    description: 'Compact the conversation context',
+    priority: 80,
+  },
+  {
+    name: 'init',
+    aliases: [],
+    description: 'Analyze the codebase and generate AGENTS.md',
+  },
+  {
+    name: 'fork',
+    aliases: [],
+    description: 'Fork the current session',
+    priority: 80,
+  },
+  {
+    name: 'title',
+    aliases: ['rename'],
+    description: 'Set or show session title',
+    priority: 60,
+    availability: 'always',
+  },
+  {
+    name: 'usage',
+    aliases: [],
+    description: 'Show session tokens + context window + plan quotas',
+    priority: 60,
+    availability: 'always',
+  },
+  {
+    name: 'status',
+    aliases: [],
+    description: 'Show current session and runtime status',
+    priority: 60,
+    availability: 'always',
+  },
+  {
+    name: 'feedback',
+    aliases: [],
+    description: 'Send feedback to make Kimi Code better',
+    priority: 60,
+    availability: 'always',
+  },
+  {
+    name: 'editor',
+    aliases: [],
+    description: 'Set the external editor for Ctrl-G',
+    priority: 60,
+    availability: 'always',
+  },
+  {
+    name: 'theme',
+    aliases: [],
+    description: 'Set the terminal UI theme',
+    priority: 60,
+    availability: 'always',
+  },
+  {
+    name: 'logout',
+    aliases: [],
+    description: 'Clear credentials for the current platform',
+    priority: 40,
+  },
+  {
+    name: 'login',
+    aliases: [],
+    description: 'Select a platform and authenticate',
+    priority: 40,
+  },
+  {
+    name: 'exit',
+    aliases: ['quit', 'q'],
+    description: 'Exit the application',
+    priority: 20,
+  },
+  {
+    name: 'version',
+    aliases: [],
+    description: 'Show version information',
+    priority: 20,
+    availability: 'always',
+  },
+] as const satisfies readonly KimiSlashCommand[];
+
+export type BuiltinSlashCommand = (typeof BUILTIN_SLASH_COMMANDS)[number];
+export type BuiltinSlashCommandName = BuiltinSlashCommand['name'];
+
+export function findBuiltInSlashCommand(commandName: string): BuiltinSlashCommand | undefined {
+  const commands = BUILTIN_SLASH_COMMANDS as readonly KimiSlashCommand<BuiltinSlashCommandName>[];
+  return commands.find(
+    (command) => command.name === commandName || command.aliases.includes(commandName),
+  ) as BuiltinSlashCommand | undefined;
+}
+
+export function resolveSlashCommandAvailability(
+  command: KimiSlashCommand,
+  args: string,
+): SlashCommandAvailability {
+  const availability = command.availability ?? 'idle-only';
+  return typeof availability === 'function' ? availability(args) : availability;
+}
+
+export function sortSlashCommands(commands: readonly KimiSlashCommand[]): KimiSlashCommand[] {
+  return [...commands].toSorted(
+    (a, b) => (b.priority ?? 0) - (a.priority ?? 0) || a.name.localeCompare(b.name),
+  );
+}
diff --git a/apps/kimi-code/src/tui/commands/resolve.ts b/apps/kimi-code/src/tui/commands/resolve.ts
new file mode 100644
index 000000000..2d0807bf4
--- /dev/null
+++ b/apps/kimi-code/src/tui/commands/resolve.ts
@@ -0,0 +1,115 @@
+import {
+  findBuiltInSlashCommand,
+  resolveSlashCommandAvailability,
+  type BuiltinSlashCommand,
+  type BuiltinSlashCommandName,
+} from './registry';
+import { parseSlashInput } from './parse';
+import type { SlashCommandBusyReason, SlashCommandInvalidReason } from './types';
+
+export type SlashCommandIntent =
+  | { readonly kind: 'not-command' }
+  | {
+      readonly kind: 'builtin';
+      readonly command: BuiltinSlashCommand;
+      readonly name: BuiltinSlashCommandName;
+      readonly args: string;
+    }
+  | {
+      readonly kind: 'skill';
+      readonly commandName: string;
+      readonly skillName: string;
+      readonly args: string;
+    }
+  | { readonly kind: 'message'; readonly input: string }
+  | {
+      readonly kind: 'blocked';
+      readonly commandName: string;
+      readonly reason: SlashCommandBusyReason;
+    }
+  | {
+      readonly kind: 'invalid';
+      readonly commandName: string;
+      readonly reason: SlashCommandInvalidReason;
+    };
+
+export interface ResolveSlashCommandInput {
+  readonly input: string;
+  readonly skillCommandMap: ReadonlyMap<string, string>;
+  readonly isStreaming: boolean;
+  readonly isCompacting: boolean;
+}
+
+export function resolveSlashCommandInput(options: ResolveSlashCommandInput): SlashCommandIntent {
+  const parsed = parseSlashInput(options.input);
+  if (parsed === null) return { kind: 'not-command' };
+
+  const command = findBuiltInSlashCommand(parsed.name);
+  if (command !== undefined) {
+    const busyReason = slashCommandBusyReason(options);
+    if (
+      busyReason !== undefined &&
+      resolveSlashCommandAvailability(command, parsed.args) === 'idle-only'
+    ) {
+      return {
+        kind: 'blocked',
+        commandName: parsed.name,
+        reason: busyReason,
+      };
+    }
+    return {
+      kind: 'builtin',
+      command,
+      name: command.name,
+      args: parsed.args,
+    };
+  }
+
+  const skillName = resolveSkillCommand(options.skillCommandMap, parsed.name);
+  if (skillName !== undefined) {
+    const busyReason = slashCommandBusyReason(options);
+    if (busyReason !== undefined) {
+      return {
+        kind: 'blocked',
+        commandName: parsed.name,
+        reason: busyReason,
+      };
+    }
+    return {
+      kind: 'skill',
+      commandName: parsed.name,
+      skillName,
+      args: parsed.args.trim(),
+    };
+  }
+
+  return {
+    kind: 'message',
+    input: options.input,
+  };
+}
+
+export function resolveSkillCommand(
+  skillCommandMap: ReadonlyMap<string, string>,
+  commandName: string,
+): string | undefined {
+  return skillCommandMap.get(commandName) ?? skillCommandMap.get(`skill:${commandName}`);
+}
+
+export function slashCommandBusyReason(
+  options: Pick<ResolveSlashCommandInput, 'isStreaming' | 'isCompacting'>,
+): SlashCommandBusyReason | undefined {
+  if (options.isStreaming) return 'streaming';
+  if (options.isCompacting) return 'compacting';
+  return undefined;
+}
+
+export function slashBusyMessage(
+  commandName: string,
+  reason: SlashCommandBusyReason,
+): string {
+  if (reason === 'streaming') {
+    return `Cannot /${commandName} while streaming — press Esc or Ctrl-C first.`;
+  }
+  return `Cannot /${commandName} while compacting — wait for compaction to finish first.`;
+}
diff --git a/apps/kimi-code/src/tui/commands/skills.ts b/apps/kimi-code/src/tui/commands/skills.ts
new file mode 100644
index 000000000..08dfafc7e
--- /dev/null
+++ b/apps/kimi-code/src/tui/commands/skills.ts
@@ -0,0 +1,33 @@
+import type { Session, SkillSummary } from '@moonshot-ai/kimi-code-sdk';
+
+import type { KimiSlashCommand } from './types';
+
+export type SkillListSession = Pick<Session, 'listSkills'>;
+
+export interface SkillSlashCommands {
+  readonly commands: readonly KimiSlashCommand[];
+  readonly commandMap: ReadonlyMap<string, string>;
+}
+
+export function isUserActivatableSkill(skill: SkillSummary): boolean {
+  return (
+    skill.type === undefined ||
+    skill.type === 'prompt' ||
+    skill.type === 'inline' ||
+    skill.type === 'flow'
+  );
+}
+
+export function buildSkillSlashCommands(skills: readonly SkillSummary[]): SkillSlashCommands {
+  const commandMap = new Map<string, string>();
+  const commands = skills.filter(isUserActivatableSkill).map((skill) => {
+    const commandName = `skill:${skill.name}`;
+    commandMap.set(commandName, skill.name);
+    return {
+      name: commandName,
+      aliases: [],
+      description: skill.description ?? '',
+    };
+  });
+  return { commands, commandMap };
+}
diff --git a/apps/kimi-code/src/tui/commands/types.ts b/apps/kimi-code/src/tui/commands/types.ts
new file mode 100644
index 000000000..cb784f84d
--- /dev/null
+++ b/apps/kimi-code/src/tui/commands/types.ts
@@ -0,0 +1,20 @@
+import type { SlashCommand } from '@earendil-works/pi-tui';
+
+export type SlashCommandAvailability = 'always' | 'idle-only';
+
+export interface KimiSlashCommand<Name extends string = string> extends SlashCommand {
+  readonly name: Name;
+  readonly aliases: readonly string[];
+  readonly description: string;
+  readonly priority?: number;
+  readonly availability?: SlashCommandAvailability | ((args: string) => SlashCommandAvailability);
+}
+
+export interface ParsedSlashInput {
+  readonly name: string;
+  readonly args: string;
+}
+
+export type SlashCommandBusyReason = 'streaming' | 'compacting';
+
+export type SlashCommandInvalidReason = 'unknown';
diff --git a/apps/kimi-code/src/tui/components/chrome/device-code-box.ts b/apps/kimi-code/src/tui/components/chrome/device-code-box.ts
new file mode 100644
index 000000000..de2704228
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/chrome/device-code-box.ts
@@ -0,0 +1,76 @@
+/**
+ * OAuth device-code panel rendered inside the transcript.
+ *
+ * Borrows the rounded-border layout from `WelcomeComponent` so the login
+ * prompt matches the rest of the chrome. All colors flow through the
+ * active palette so theme switches take effect on the next render.
+ */
+
+import type { Component } from '@earendil-works/pi-tui';
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+
+export interface DeviceCodeBoxParams {
+  readonly title: string;
+  readonly url: string;
+  readonly code: string;
+  readonly hint?: string;
+  readonly colors: ColorPalette;
+}
+
+export class DeviceCodeBoxComponent implements Component {
+  private readonly params: DeviceCodeBoxParams;
+
+  constructor(params: DeviceCodeBoxParams) {
+    this.params = params;
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const { title, url, code, hint, colors } = this.params;
+    const border = (s: string): string => chalk.hex(colors.primary)(s);
+    const safeWidth = Math.max(28, width);
+    const innerWidth = Math.max(10, safeWidth - 4);
+    const pad = '  ';
+
+    const titleLine = truncateToWidth(chalk.bold.hex(colors.textStrong)(title), innerWidth, '…');
+    const promptLine = truncateToWidth(
+      chalk.hex(colors.textDim)('Visit the URL below in your browser to authorize:'),
+      innerWidth,
+      '…',
+    );
+    const urlLine = truncateToWidth(chalk.hex(colors.primary)(url), innerWidth, '…');
+
+    const codeLabel = chalk.bold.hex(colors.textDim)('Verification code:  ');
+    const codeValue = chalk.bold.hex(colors.accent)(code);
+    const codeLine = truncateToWidth(`${codeLabel}${codeValue}`, innerWidth, '…');
+
+    const contentLines: string[] = [titleLine, '', promptLine, urlLine, '', codeLine];
+    if (hint !== undefined && hint.length > 0) {
+      contentLines.push('');
+      contentLines.push(truncateToWidth(chalk.hex(colors.textDim)(hint), innerWidth, '…'));
+    }
+
+    const lines: string[] = [
+      '',
+      border('╭' + '─'.repeat(safeWidth - 2) + '╮'),
+      border('│') + ' '.repeat(safeWidth - 2) + border('│'),
+    ];
+
+    for (const content of contentLines) {
+      const truncated = content;
+      const vis = visibleWidth(truncated);
+      const rightPad = Math.max(0, innerWidth - vis);
+      lines.push(border('│') + pad + truncated + ' '.repeat(rightPad) + border('│'));
+    }
+
+    lines.push(border('│') + ' '.repeat(safeWidth - 2) + border('│'));
+    lines.push(border('╰' + '─'.repeat(safeWidth - 2) + '╯'));
+    lines.push('');
+
+    return lines;
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/chrome/footer.ts b/apps/kimi-code/src/tui/components/chrome/footer.ts
new file mode 100644
index 000000000..9079da44e
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/chrome/footer.ts
@@ -0,0 +1,266 @@
+/**
+ * Footer/status bar — multi-line status display at the bottom of the TUI.
+ *
+ * Layout:
+ *   Line 1: [yolo] [plan] <model> <cwd>  <git-badge>  <shortcut hints>
+ *   Line 2: context: XX.X% (tokens/max)
+ */
+
+import type { Component } from '@earendil-works/pi-tui';
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+import type { AppState } from '#/tui/types';
+import {
+  createGitStatusCache,
+  formatGitBadgeBase,
+  formatPullRequestBadge,
+  type GitStatus,
+  type GitStatusCache,
+} from '#/utils/git/git-status';
+import { safeUsageRatio } from '#/utils/usage/usage-format';
+
+const MAX_CWD_SEGMENTS = 3;
+
+// Toolbar tips — rotates every 30s, shows 2 tips joined by " | " when
+// space allows, falls back to 1.
+const TIP_ROTATE_INTERVAL_MS = 30_000;
+const TIP_SEPARATOR = ' | ';
+const TOOLBAR_TIPS: readonly string[] = [
+  'shift+tab: plan mode',
+  '/yolo: toggle yolo',
+  'ctrl+c: cancel',
+  '/help: show commands',
+  '/model: switch model',
+  '@: mention files',
+];
+
+function currentTipIndex(): number {
+  return Math.floor(Date.now() / TIP_ROTATE_INTERVAL_MS);
+}
+
+function twoRotatingTips(index: number): string {
+  const n = TOOLBAR_TIPS.length;
+  if (n === 0) return '';
+  if (n === 1) return TOOLBAR_TIPS[0]!;
+  const offset = ((index % n) + n) % n;
+  return TOOLBAR_TIPS[offset]! + TIP_SEPARATOR + TOOLBAR_TIPS[(offset + 1) % n]!;
+}
+
+function oneRotatingTip(index: number): string {
+  const n = TOOLBAR_TIPS.length;
+  if (n === 0) return '';
+  const offset = ((index % n) + n) % n;
+  return TOOLBAR_TIPS[offset]!;
+}
+
+function shortenModel(model: string): string {
+  if (!model) return model;
+  const slash = model.lastIndexOf('/');
+  return slash >= 0 ? model.slice(slash + 1) : model;
+}
+
+function modelDisplayName(state: AppState): string {
+  const model = state.availableModels[state.model];
+  return model?.displayName ?? model?.model ?? state.model;
+}
+
+function shortenCwd(path: string): string {
+  if (!path) return path;
+  const home = process.env['HOME'] ?? '';
+  let work = path;
+  if (home && path === home) {
+    return '~';
+  }
+  if (home && path.startsWith(home + '/')) {
+    work = '~' + path.slice(home.length);
+  }
+
+  const segments = work.split('/').filter((s) => s.length > 0);
+  if (segments.length <= MAX_CWD_SEGMENTS) return work;
+  const tail = segments.slice(-MAX_CWD_SEGMENTS).join('/');
+  return `…/${tail}`;
+}
+
+function formatTokenCount(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(n);
+}
+
+function safeUsage(usage: number): number {
+  return safeUsageRatio(usage);
+}
+
+function formatContextStatus(usage: number, tokens?: number, maxTokens?: number): string {
+  const pct = `${(safeUsage(usage) * 100).toFixed(1)}%`;
+  if (maxTokens && maxTokens > 0 && tokens !== undefined) {
+    return `context: ${pct} (${formatTokenCount(tokens)}/${formatTokenCount(maxTokens)})`;
+  }
+  return `context: ${pct}`;
+}
+
+export function formatFooterGitBadge(status: GitStatus, colors: ColorPalette): string {
+  const base = chalk.hex(colors.status)(formatGitBadgeBase(status));
+  if (status.pullRequest === null) return base;
+
+  const pullRequest = chalk.hex(colors.primary)(
+    formatPullRequestBadge(status.pullRequest, { linkPullRequest: true }),
+  );
+  return `${base} ${pullRequest}`;
+}
+
+export class FooterComponent implements Component {
+  private state: AppState;
+  private colors: ColorPalette;
+  private readonly onGitStatusChange: () => void;
+  private gitCache: GitStatusCache;
+  private gitCacheWorkDir: string;
+  private transientHint: string | null = null;
+  /**
+   * Non-terminal background-task counts split by kind so the footer can
+   * render two distinct badges. `bashTasks` covers `bash-*` BPM tasks
+   * spawned via `Shell run_in_background=true`; `agentTasks` covers
+   * `agent-*` BPM tasks (background subagents). Either zero hides its
+   * respective badge.
+   */
+  private backgroundBashTaskCount = 0;
+  private backgroundAgentCount = 0;
+
+  constructor(state: AppState, colors: ColorPalette, onGitStatusChange: () => void = () => {}) {
+    this.state = state;
+    this.colors = colors;
+    this.onGitStatusChange = onGitStatusChange;
+    this.gitCacheWorkDir = state.workDir;
+    this.gitCache = createGitStatusCache(state.workDir, { onChange: this.onGitStatusChange });
+  }
+
+  setState(state: AppState): void {
+    if (state.workDir !== this.gitCacheWorkDir) {
+      this.gitCacheWorkDir = state.workDir;
+      this.gitCache = createGitStatusCache(state.workDir, { onChange: this.onGitStatusChange });
+    }
+    this.state = state;
+  }
+
+  setColors(colors: ColorPalette): void {
+    this.colors = colors;
+  }
+
+  /**
+   * Short-lived hint that replaces the rotating toolbar tips on line 1.
+   * Used by the exit-confirmation double-tap flow to show "Press Ctrl+C
+   * again to exit" without requiring a toast/overlay subsystem.
+   * Pass `null` to clear.
+   */
+  setTransientHint(hint: string | null): void {
+    this.transientHint = hint;
+  }
+
+  /**
+   * Sync both background-task badges with live counts. Each non-zero
+   * count produces its own bracketed badge on line 1; zeros hide them
+   * independently.
+   */
+  setBackgroundCounts(counts: { bashTasks: number; agentTasks: number }): void {
+    this.backgroundBashTaskCount = Math.max(0, counts.bashTasks);
+    this.backgroundAgentCount = Math.max(0, counts.agentTasks);
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const colors = this.colors;
+    const state = this.state;
+
+    // ── Line 1: mode badges + model + [N task(s) running] + [N agent(s) running] + cwd + git + hints ──
+    const left: string[] = [];
+    if (state.permissionMode === 'auto') left.push(chalk.hex(colors.warning).bold('auto'));
+    if (state.permissionMode === 'yolo') left.push(chalk.hex(colors.warning).bold('yolo'));
+    if (state.planMode) left.push(chalk.hex(colors.primary).bold('plan'));
+
+    const model = shortenModel(modelDisplayName(state));
+    if (model) {
+      const thinkingLabel = state.thinking ? ' thinking' : '';
+      left.push(chalk.hex(colors.text)(`${model}${thinkingLabel}`));
+    }
+
+    // Background-task badges sit immediately before cwd. `bash-*` tasks
+    // (shell processes) and `agent-*` tasks (background subagents) get
+    // separate badges so the user can distinguish them at a glance.
+    if (this.backgroundBashTaskCount > 0) {
+      const noun = this.backgroundBashTaskCount === 1 ? 'task' : 'tasks';
+      left.push(
+        chalk.hex(colors.primary)(`[${String(this.backgroundBashTaskCount)} ${noun} running]`),
+      );
+    }
+    if (this.backgroundAgentCount > 0) {
+      const noun = this.backgroundAgentCount === 1 ? 'agent' : 'agents';
+      left.push(
+        chalk.hex(colors.primary)(`[${String(this.backgroundAgentCount)} ${noun} running]`),
+      );
+    }
+
+    const cwd = shortenCwd(state.workDir);
+    if (cwd) left.push(chalk.hex(colors.status)(cwd));
+
+    const git = this.gitCache.getStatus();
+    if (git !== null) {
+      left.push(formatFooterGitBadge(git, colors));
+    }
+
+    const leftLine = left.join('  ');
+    const leftWidth = visibleWidth(leftLine);
+
+    // Rotating hint tips, fill remaining space on line 1.
+    const tipIndex = currentTipIndex();
+    const tipTwo = twoRotatingTips(tipIndex);
+    const tipOne = oneRotatingTip(tipIndex);
+    const gap = 2;
+    const remaining = Math.max(0, width - leftWidth - gap);
+    let tipText = '';
+    if (tipTwo && visibleWidth(tipTwo) <= remaining) {
+      tipText = tipTwo;
+    } else if (tipOne && visibleWidth(tipOne) <= remaining) {
+      tipText = tipOne;
+    }
+
+    let line1: string;
+    if (tipText) {
+      const pad = width - leftWidth - visibleWidth(tipText);
+      line1 = leftLine + ' '.repeat(Math.max(0, pad)) + chalk.hex(colors.textMuted)(tipText);
+    } else if (leftWidth <= width) {
+      line1 = leftLine;
+    } else {
+      line1 = truncateToWidth(leftLine, width, '…');
+    }
+
+    // ── Line 2: transient hint (bottom-left) + context (right) ──
+    const contextText = formatContextStatus(
+      state.contextUsage,
+      state.contextTokens,
+      state.maxContextTokens,
+    );
+    const contextWidth = visibleWidth(contextText);
+    let line2: string;
+    if (this.transientHint) {
+      const maxHintWidth = Math.max(0, width - contextWidth - 1);
+      const shownHint =
+        visibleWidth(this.transientHint) <= maxHintWidth
+          ? this.transientHint
+          : truncateToWidth(this.transientHint, maxHintWidth, '…');
+      const hintWidth = visibleWidth(shownHint);
+      const pad = Math.max(0, width - hintWidth - contextWidth);
+      line2 =
+        chalk.hex(colors.warning).bold(shownHint) +
+        ' '.repeat(pad) +
+        chalk.hex(colors.text)(contextText);
+    } else {
+      const leftPad = Math.max(0, width - contextWidth);
+      line2 = ' '.repeat(leftPad) + chalk.hex(colors.text)(contextText);
+    }
+
+    return [truncateToWidth(line1, width), truncateToWidth(line2, width)];
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/chrome/gutter-container.ts b/apps/kimi-code/src/tui/components/chrome/gutter-container.ts
new file mode 100644
index 000000000..39ed97c49
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/chrome/gutter-container.ts
@@ -0,0 +1,33 @@
+/**
+ * Container that reserves left/right gutter columns around its children,
+ * so the chrome (statusline, transcript, panels) lines up with the input
+ * box's inner content area instead of butting up against the terminal edge.
+ *
+ * Children are rendered at `width - left - right` and each emitted line is
+ * prefixed with `left` plain spaces. Right padding is logical only — we
+ * never emit trailing spaces, since terminals already paint background to
+ * the edge and adding them would just churn the diff renderer.
+ */
+
+import { Container } from '@earendil-works/pi-tui';
+
+export class GutterContainer extends Container {
+  constructor(
+    private readonly leftPad: number,
+    private readonly rightPad: number,
+  ) {
+    super();
+  }
+
+  override render(width: number): string[] {
+    const inner = Math.max(1, width - this.leftPad - this.rightPad);
+    const lead = ' '.repeat(this.leftPad);
+    const out: string[] = [];
+    for (const child of this.children) {
+      for (const line of child.render(inner)) {
+        out.push(lead + line);
+      }
+    }
+    return out;
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/chrome/moon-loader.ts b/apps/kimi-code/src/tui/components/chrome/moon-loader.ts
new file mode 100644
index 000000000..0e88e6af4
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/chrome/moon-loader.ts
@@ -0,0 +1,68 @@
+import { Text } from '@earendil-works/pi-tui';
+import type { TUI } from '@earendil-works/pi-tui';
+
+import {
+  BRAILLE_SPINNER_FRAMES,
+  BRAILLE_SPINNER_INTERVAL_MS,
+  MOON_SPINNER_FRAMES,
+  MOON_SPINNER_INTERVAL_MS,
+} from '#/tui/constant/rendering';
+
+export type SpinnerStyle = 'moon' | 'braille';
+
+export class MoonLoader extends Text {
+  private currentFrame = 0;
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+  private ui: TUI;
+  private frames: string[];
+  private interval: number;
+  private colorFn?: (s: string) => string;
+  private label: string;
+
+  constructor(
+    ui: TUI,
+    style: SpinnerStyle = 'moon',
+    colorFn?: (s: string) => string,
+    label: string = '',
+  ) {
+    super('', 1, 0);
+    this.ui = ui;
+    this.frames = style === 'moon' ? [...MOON_SPINNER_FRAMES] : [...BRAILLE_SPINNER_FRAMES];
+    this.interval = style === 'moon' ? MOON_SPINNER_INTERVAL_MS : BRAILLE_SPINNER_INTERVAL_MS;
+    this.colorFn = colorFn;
+    this.label = label;
+    this.start();
+  }
+
+  start(): void {
+    this.updateDisplay();
+    this.intervalId = setInterval(() => {
+      this.currentFrame = (this.currentFrame + 1) % this.frames.length;
+      this.updateDisplay();
+    }, this.interval);
+  }
+
+  stop(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+
+  setLabel(label: string): void {
+    this.label = label;
+    this.updateDisplay();
+  }
+
+  setColorFn(colorFn: (s: string) => string): void {
+    this.colorFn = colorFn;
+    this.updateDisplay();
+  }
+
+  private updateDisplay(): void {
+    const frame = this.frames[this.currentFrame]!;
+    const coloredFrame = this.colorFn ? this.colorFn(frame) : frame;
+    this.setText(this.label ? `${coloredFrame} ${this.label}` : coloredFrame);
+    this.ui.requestRender();
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/chrome/todo-panel.ts b/apps/kimi-code/src/tui/components/chrome/todo-panel.ts
new file mode 100644
index 000000000..ede986e60
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/chrome/todo-panel.ts
@@ -0,0 +1,96 @@
+/**
+ * TodoPanel — live-updating TODO list shown before the input area.
+ *
+ * Mounted as a dedicated `Container` slot between the activity pane
+ * (spinners / thinking stream) and the queue / editor block. The host
+ * calls {@link setTodos} whenever the LLM invokes the `TodoList`
+ * tool; state survives across turns so the list stays visible until
+ * explicitly cleared (`todos: []`), a new session starts, or `/clear`
+ * is issued.
+ */
+
+import type { Component } from '@earendil-works/pi-tui';
+import { truncateToWidth } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+
+export type TodoStatus = 'pending' | 'in_progress' | 'done';
+
+export interface TodoItem {
+  readonly title: string;
+  readonly status: TodoStatus;
+}
+
+export class TodoPanelComponent implements Component {
+  private todos: readonly TodoItem[] = [];
+  private colors: ColorPalette;
+
+  constructor(colors: ColorPalette) {
+    this.colors = colors;
+  }
+
+  setTodos(todos: readonly TodoItem[]): void {
+    this.todos = todos.map((t) => ({ title: t.title, status: t.status }));
+  }
+
+  getTodos(): readonly TodoItem[] {
+    return this.todos;
+  }
+
+  clear(): void {
+    this.todos = [];
+  }
+
+  isEmpty(): boolean {
+    return this.todos.length === 0;
+  }
+
+  setColors(colors: ColorPalette): void {
+    this.colors = colors;
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    if (this.todos.length === 0) return [];
+    const c = this.colors;
+    const lines: string[] = [
+      chalk.hex(c.border)('─'.repeat(width)),
+      chalk.hex(c.primary).bold(' Todo'),
+    ];
+    for (const todo of this.todos) {
+      lines.push(renderRow(todo, c));
+    }
+
+    return lines.map((line) => truncateToWidth(line, width));
+  }
+}
+
+function renderRow(todo: TodoItem, colors: ColorPalette): string {
+  const marker = statusMarker(todo.status, colors);
+  const titleStyled = styleTitle(todo.title, todo.status, colors);
+  return `  ${marker} ${titleStyled}`;
+}
+
+function statusMarker(status: TodoStatus, colors: ColorPalette): string {
+  switch (status) {
+    case 'in_progress':
+      return chalk.hex(colors.primary).bold('●');
+    case 'done':
+      return chalk.hex(colors.success)('✓');
+    case 'pending':
+      return chalk.hex(colors.textDim)('○');
+  }
+}
+
+function styleTitle(title: string, status: TodoStatus, colors: ColorPalette): string {
+  switch (status) {
+    case 'in_progress':
+      return chalk.hex(colors.text).bold(title);
+    case 'done':
+      return chalk.hex(colors.textDim).strikethrough(title);
+    case 'pending':
+      return chalk.hex(colors.text)(title);
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/chrome/welcome.ts b/apps/kimi-code/src/tui/components/chrome/welcome.ts
new file mode 100644
index 000000000..e75d46df9
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/chrome/welcome.ts
@@ -0,0 +1,86 @@
+/**
+ * Welcome panel shown at the top of the TUI.
+ * Renders a round-bordered box with the logo, session, model, and version.
+ */
+
+import type { Component } from '@earendil-works/pi-tui';
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+import type { AppState } from '#/tui/types';
+
+export class WelcomeComponent implements Component {
+  private state: AppState;
+  private colors: ColorPalette;
+
+  constructor(state: AppState, colors: ColorPalette) {
+    this.state = state;
+    this.colors = colors;
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const primary = (s: string): string => chalk.hex(this.colors.primary)(s);
+    const innerWidth = Math.max(10, width - 4);
+    const pad = '  ';
+
+    // Logo + side-by-side text.
+    const logo = ['▐█▛█▛█▌', '▐█████▌'];
+    const logoWidth = Math.max(...logo.map((row) => visibleWidth(row)));
+    const gap = '  ';
+    const textWidth = Math.max(4, innerWidth - logoWidth - gap.length);
+
+    const rightRow0 = truncateToWidth(
+      chalk.bold.hex(this.colors.primary)('Welcome to Kimi Code!'),
+      textWidth,
+      '…',
+    );
+    const isLoggedOut = !this.state.model;
+    const dim = chalk.hex(this.colors.textDim);
+    const labelStyle = chalk.bold.hex(this.colors.textDim);
+    const rightRow1 = truncateToWidth(
+      dim(isLoggedOut ? 'Run /login to sign in.' : 'Send /help for help information.'),
+      textWidth,
+      '…',
+    );
+
+    const headerLines = [
+      primary(logo[0]!.padEnd(logoWidth)) + gap + rightRow0,
+      primary(logo[1]!.padEnd(logoWidth)) + gap + rightRow1,
+    ];
+
+    const modelValue = isLoggedOut
+      ? chalk.hex(this.colors.warning)('not set, send /login to login')
+      : this.state.model;
+
+    const infoLines = [
+      labelStyle('Directory: ') + this.state.workDir,
+      labelStyle('Session:   ') + this.state.sessionId,
+      labelStyle('Model:     ') + modelValue,
+      labelStyle('Version:   ') + this.state.version,
+    ];
+
+    const contentLines: string[] = [...headerLines, '', ...infoLines];
+
+    const lines: string[] = [
+      '',
+      primary('╭' + '─'.repeat(width - 2) + '╮'),
+      primary('│') + ' '.repeat(width - 2) + primary('│'),
+    ];
+
+    for (const content of contentLines) {
+      const truncated = truncateToWidth(content, innerWidth, '…');
+      const vis = visibleWidth(truncated);
+      const rightPad = Math.max(0, innerWidth - vis);
+      lines.push(primary('│') + pad + truncated + ' '.repeat(rightPad) + primary('│'));
+    }
+
+    lines.push(primary('│') + ' '.repeat(width - 2) + primary('│'));
+    lines.push(primary('╰' + '─'.repeat(width - 2) + '╯'));
+    lines.push('');
+
+    return lines;
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/api-key-input-dialog.ts b/apps/kimi-code/src/tui/components/dialogs/api-key-input-dialog.ts
new file mode 100644
index 000000000..abf1b3e99
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/api-key-input-dialog.ts
@@ -0,0 +1,148 @@
+import {
+  Container,
+  Input,
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  type Focusable,
+} from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+
+export type ApiKeyInputResult =
+  | { readonly kind: 'ok'; readonly value: string }
+  | { readonly kind: 'cancel' };
+
+const FOOTER = 'Enter to submit  ·  Esc to cancel';
+
+function maskInputLine(raw: string): string {
+  const prefix = '> ';
+  if (!raw.startsWith(prefix)) return raw;
+
+  // Strip trailing padding spaces so they stay as spaces.
+  let end = raw.length;
+  while (end > prefix.length && raw[end - 1] === ' ') {
+    end--;
+  }
+  const padding = raw.slice(end);
+  const content = raw.slice(prefix.length, end);
+
+  // Protect ANSI escape sequences (reverse-video cursor, IME marker, etc.)
+  // while masking every other visible character.
+  const parts = content.split(/(\u001B(?:\[[0-9;]*m|_pi:c\u0007))/);
+  const maskedContent = parts
+    .map((part, index) => {
+      if (index % 2 === 1) return part; // ANSI sequence
+      return part.replaceAll(/./g, '•');
+    })
+    .join('');
+
+  return prefix + maskedContent + padding;
+}
+
+export class ApiKeyInputDialogComponent extends Container implements Focusable {
+  focused = false;
+
+  private readonly input = new Input();
+  private readonly onDone: (result: ApiKeyInputResult) => void;
+  private readonly colors: ColorPalette;
+  private readonly title: string;
+  private readonly subtitle: string;
+  private done = false;
+  private emptyHinted = false;
+
+  constructor(
+    platformName: string,
+    onDone: (result: ApiKeyInputResult) => void,
+    colors: ColorPalette,
+  ) {
+    super();
+    this.onDone = onDone;
+    this.colors = colors;
+    this.title = `Enter API key for ${platformName}`;
+    this.subtitle = 'Your key will be saved to ~/.kimi-code/config.toml';
+    this.input.onSubmit = (value) => {
+      this.submit(value);
+    };
+  }
+
+  handleInput(data: string): void {
+    if (this.done) return;
+    if (
+      matchesKey(data, Key.escape) ||
+      matchesKey(data, Key.ctrl('c')) ||
+      matchesKey(data, Key.ctrl('d'))
+    ) {
+      this.cancel();
+      return;
+    }
+    if (this.emptyHinted) {
+      this.emptyHinted = false;
+    }
+    this.input.handleInput(data);
+  }
+
+  override invalidate(): void {
+    super.invalidate();
+    this.input.invalidate();
+  }
+
+  override render(width: number): string[] {
+    this.input.focused = this.focused && !this.done;
+
+    const safeWidth = Math.max(28, width);
+    const innerWidth = Math.max(10, safeWidth - 4);
+    const pad = '  ';
+
+    const border = (s: string): string => chalk.hex(this.colors.primary)(s);
+    const titleStyled = chalk.bold.hex(this.colors.textStrong)(this.title);
+    const subtitleText = this.emptyHinted ? 'API key cannot be empty.' : this.subtitle;
+    const subtitleStyled = chalk.hex(this.colors.textDim)(subtitleText);
+    const footerStyled = chalk.hex(this.colors.textDim)(FOOTER);
+
+    const titleLine = truncateToWidth(titleStyled, innerWidth, '…');
+    const subtitleLine = truncateToWidth(subtitleStyled, innerWidth, '…');
+    const footerLine = truncateToWidth(footerStyled, innerWidth, '…');
+    const rawInputLine = this.input.render(innerWidth)[0] ?? '> ';
+    const inputLine = maskInputLine(rawInputLine);
+
+    const contentLines: string[] = [titleLine, '', subtitleLine, '', inputLine, '', footerLine];
+
+    const lines: string[] = [
+      '',
+      border('╭' + '─'.repeat(safeWidth - 2) + '╮'),
+      border('│') + ' '.repeat(safeWidth - 2) + border('│'),
+    ];
+
+    for (const content of contentLines) {
+      const vis = visibleWidth(content);
+      const rightPad = Math.max(0, innerWidth - vis);
+      lines.push(border('│') + pad + content + ' '.repeat(rightPad) + border('│'));
+    }
+
+    lines.push(border('│') + ' '.repeat(safeWidth - 2) + border('│'));
+    lines.push(border('╰' + '─'.repeat(safeWidth - 2) + '╯'));
+    lines.push('');
+
+    return lines;
+  }
+
+  private submit(value: string): void {
+    if (this.done) return;
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+      this.emptyHinted = true;
+      return;
+    }
+    this.done = true;
+    this.onDone({ kind: 'ok', value: trimmed });
+  }
+
+  private cancel(): void {
+    if (this.done) return;
+    this.done = true;
+    this.onDone({ kind: 'cancel' });
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/approval-panel.ts b/apps/kimi-code/src/tui/components/dialogs/approval-panel.ts
new file mode 100644
index 000000000..ed93602f6
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/approval-panel.ts
@@ -0,0 +1,406 @@
+/**
+ * ApprovalPanel — pi-tui version of the approval request UI.
+ *
+ * Container-based component with keyboard navigation.
+ */
+
+import {
+  Container,
+  Input,
+  matchesKey,
+  Key,
+  decodeKittyPrintable,
+  type Focusable,
+  truncateToWidth,
+  visibleWidth,
+} from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import { highlightLines, langFromPath } from '#/tui/components/media/code-highlight';
+import { renderDiffLinesClustered } from '#/tui/components/media/diff-preview';
+import type { ApprovalPanelChoice, DisplayBlock, PendingApproval } from '#/tui/reverse-rpc/types';
+import type { ColorPalette } from '#/tui/theme/colors';
+
+export interface ApprovalPanelResponse {
+  readonly response: 'approved' | 'approved_for_session' | 'rejected' | 'cancelled';
+  readonly feedback?: string | undefined;
+  readonly selected_label?: string | undefined;
+}
+
+function truncateOneLine(text: string, max: number): string {
+  const firstLine = text.split('\n')[0] ?? '';
+  return firstLine.length > max ? firstLine.slice(0, max - 1) + '…' : firstLine;
+}
+
+const DIFF_SUMMARY_MAX_LINES = 10;
+const CONTENT_SUMMARY_MAX_LINES = 10;
+
+interface BlockStyles {
+  strong: (s: string) => string;
+  dim: (s: string) => string;
+  accent: (s: string) => string;
+  gutter: (s: string) => string;
+  errorBold: (s: string) => string;
+}
+
+function makeBlockStyles(colors: ColorPalette): BlockStyles {
+  return {
+    strong: (s) => chalk.hex(colors.textStrong)(s),
+    dim: (s) => chalk.hex(colors.textDim)(s),
+    accent: (s) => chalk.hex(colors.accent)(s),
+    gutter: (s) => chalk.hex(colors.diffGutter)(s),
+    errorBold: (s) => chalk.bold.hex(colors.error)(s),
+  };
+}
+
+function renderDisplayBlock(
+  block: DisplayBlock,
+  expanded: boolean,
+  s: BlockStyles,
+  colors: ColorPalette,
+): string[] {
+  switch (block.type) {
+    case 'diff':
+      return renderDiffLinesClustered(block.old_text, block.new_text, block.path, colors, {
+        contextLines: 3,
+        expandKeyHint: 'ctrl+e',
+        ...(expanded ? {} : { maxLines: DIFF_SUMMARY_MAX_LINES }),
+      });
+    case 'file_content': {
+      const lang = block.language ?? langFromPath(block.path);
+      const allLines = highlightLines(block.content, lang);
+      const cap = expanded ? allLines.length : CONTENT_SUMMARY_MAX_LINES;
+      const shown = allLines.slice(0, cap);
+      const lines = [s.strong(block.path)];
+      for (const [i, line] of shown.entries()) {
+        lines.push(s.gutter(String(i + 1).padStart(4) + '  ') + line);
+      }
+      const remaining = allLines.length - shown.length;
+      if (remaining > 0) {
+        lines.push(
+          s.dim(
+            `     … ${String(remaining)} more line${remaining > 1 ? 's' : ''} hidden (ctrl+e to expand)`,
+          ),
+        );
+      }
+      return lines;
+    }
+    case 'shell': {
+      const lines: string[] = [];
+      if (block.cwd !== undefined && block.cwd.length > 0) {
+        lines.push(s.dim(`cwd: ${block.cwd}`));
+      }
+      if (block.danger !== undefined) {
+        lines.push(s.errorBold(`Dangerous: ${block.danger}`));
+      }
+      const cmdLines = block.command.length > 0 ? block.command.split('\n') : [''];
+      cmdLines.forEach((cmdLine, idx) => {
+        const prefix = idx === 0 ? s.accent('$') : s.dim('·');
+        lines.push(`${prefix} ${s.strong(cmdLine)}`);
+      });
+      if (block.description !== undefined && block.description.length > 0) {
+        lines.push(`  ${s.dim(block.description)}`);
+      }
+      return lines;
+    }
+    case 'file_op': {
+      const op = s.accent(block.operation.padEnd(5));
+      const lines = [`${op} ${s.strong(block.path)}`];
+      if (block.detail !== undefined && block.detail.length > 0) {
+        lines.push(s.dim(block.detail));
+      }
+      return lines;
+    }
+    case 'url_fetch': {
+      const method = s.accent((block.method ?? 'GET').toUpperCase().padEnd(5));
+      return [`${method} ${s.strong(block.url)}`];
+    }
+    case 'search': {
+      const lines = [`${s.accent('search')} ${s.strong(block.query)}`];
+      if (block.scope !== undefined && block.scope.length > 0) {
+        lines.push(s.dim(`scope: ${block.scope}`));
+      }
+      return lines;
+    }
+    case 'invocation': {
+      const lines = [`${s.accent(block.kind.padEnd(5))} ${s.strong(block.name)}`];
+      if (block.description !== undefined && block.description.length > 0) {
+        lines.push(s.dim(truncateOneLine(block.description, 200)));
+      }
+      return lines;
+    }
+    case 'brief':
+      return block.text
+        ? block.text.split('\n').map((line) => (line.length > 0 ? s.strong(line) : ''))
+        : [];
+    case 'background_task':
+      return [
+        s.strong(`${block.status} ${block.kind} task ${block.task_id}: ${block.description}`),
+      ];
+    case 'todo':
+      return block.items.map((item) => s.strong(`- [${item.status}] ${item.title}`));
+    default:
+      return [];
+  }
+}
+
+function normalizeApprovalText(text: string): string {
+  return text.replaceAll('\r\n', '\n').trim();
+}
+
+function isDuplicateBriefBlock(block: DisplayBlock, description: string): boolean {
+  if (block.type !== 'brief' || block.text.trim().length === 0) return false;
+  const normalizedDescription = normalizeApprovalText(description);
+  if (normalizedDescription.length === 0) return false;
+  const normalizedBlockText = normalizeApprovalText(block.text);
+  if (normalizedBlockText === normalizedDescription) return true;
+  const blockLines = normalizedBlockText.split('\n');
+  if (blockLines.length <= 1) return false;
+  return normalizeApprovalText(blockLines.slice(1).join('\n')) === normalizedDescription;
+}
+
+function headerFor(toolName: string): string {
+  switch (toolName) {
+    case 'Bash':
+      return 'Run this command?';
+    case 'Write':
+      return 'Write this file?';
+    case 'Edit':
+      return 'Apply these edits?';
+    case 'TaskStop':
+      return 'Stop this task?';
+    case 'ExitPlanMode':
+      return 'Ready to build with this plan?';
+    default:
+      return `Approve ${toolName}?`;
+  }
+}
+
+export class ApprovalPanelComponent extends Container implements Focusable {
+  focused = false;
+  private selectedIndex = 0;
+  private feedbackMode = false;
+  private readonly feedbackInput = new Input();
+  private expanded = false;
+  private onResponse: (response: ApprovalPanelResponse) => void;
+  private request: PendingApproval;
+  private readonly colors: ColorPalette;
+  private readonly onToggleToolOutput: (() => void) | undefined;
+  private readonly onTogglePlanExpand: (() => void) | undefined;
+
+  constructor(
+    request: PendingApproval,
+    onResponse: (response: ApprovalPanelResponse) => void,
+    colors: ColorPalette,
+    onToggleToolOutput?: () => void,
+    onTogglePlanExpand?: () => void,
+  ) {
+    super();
+    this.request = request;
+    this.onResponse = onResponse;
+    this.colors = colors;
+    this.onToggleToolOutput = onToggleToolOutput;
+    this.onTogglePlanExpand = onTogglePlanExpand;
+    this.feedbackInput.onSubmit = (value) => {
+      this.submit(this.selectedIndex, value);
+    };
+    this.feedbackInput.onEscape = () => {
+      this.feedbackMode = false;
+      this.feedbackInput.setValue('');
+    };
+  }
+
+  private submit(index: number, feedback: string = ''): void {
+    const option = this.choiceAt(index);
+    if (!option) return;
+    this.onResponse({
+      response: option.response,
+      feedback: feedback || undefined,
+      selected_label: option.selected_label,
+    });
+  }
+
+  private selectAndSubmit(index: number): void {
+    const option = this.choiceAt(index);
+    if (!option) return;
+    if (option.requires_feedback === true) {
+      this.selectedIndex = index;
+      this.feedbackMode = true;
+    } else {
+      this.submit(index);
+    }
+  }
+
+  handleInput(data: string): void {
+    if (
+      matchesKey(data, Key.escape) ||
+      matchesKey(data, Key.ctrl('c')) ||
+      matchesKey(data, Key.ctrl('d'))
+    ) {
+      this.onResponse({ response: 'rejected' });
+      return;
+    }
+
+    if (matchesKey(data, Key.ctrl('e'))) {
+      this.expanded = !this.expanded;
+      this.onTogglePlanExpand?.();
+      return;
+    }
+
+    if (matchesKey(data, Key.ctrl('o'))) {
+      this.onToggleToolOutput?.();
+      return;
+    }
+
+    if (this.feedbackMode) {
+      if (matchesKey(data, Key.up)) {
+        this.feedbackMode = false;
+        this.selectedIndex = (this.selectedIndex - 1 + this.choiceCount()) % this.choiceCount();
+        return;
+      }
+      if (matchesKey(data, Key.down)) {
+        this.feedbackMode = false;
+        this.selectedIndex = (this.selectedIndex + 1) % this.choiceCount();
+        return;
+      }
+      this.feedbackInput.handleInput(data);
+      return;
+    }
+
+    if (this.choiceCount() === 0) return;
+    if (matchesKey(data, Key.up)) {
+      this.selectedIndex = (this.selectedIndex - 1 + this.choiceCount()) % this.choiceCount();
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.selectedIndex = (this.selectedIndex + 1) % this.choiceCount();
+      return;
+    }
+    if (matchesKey(data, Key.enter)) {
+      this.selectAndSubmit(this.selectedIndex);
+      return;
+    }
+
+    const printable = decodeKittyPrintable(data) ?? data;
+    const numericIndex = Number(printable) - 1;
+    if (Number.isInteger(numericIndex) && numericIndex >= 0 && numericIndex < this.choiceCount()) {
+      this.selectAndSubmit(numericIndex);
+    }
+  }
+
+  override render(width: number): string[] {
+    this.clear();
+    this.ensureValidSelection();
+    this.feedbackInput.focused = this.focused && this.feedbackMode;
+    const { data } = this.request;
+    const blockStyles = makeBlockStyles(this.colors);
+    const borderColor = chalk.hex(this.colors.borderFocus);
+    const borderColorBold = chalk.bold.hex(this.colors.borderFocus);
+    const selectColorBold = chalk.bold.hex(this.colors.accent);
+    const dim = chalk.hex(this.colors.textDim);
+    const strong = chalk.hex(this.colors.textStrong);
+    const horizontalBar = borderColor('─'.repeat(width));
+    const indent = (s: string): string => `  ${s}`;
+
+    const title = headerFor(data.tool_name);
+    const lines: string[] = [
+      horizontalBar,
+      indent(`${borderColorBold('▶')} ${borderColorBold(title)}`),
+    ];
+
+    const dedupedBlocks = data.display.filter(
+      (block) => !isDuplicateBriefBlock(block, data.description),
+    );
+    const visibleBlocks = dedupedBlocks.slice(0, 5);
+    const hasExpandable = visibleBlocks.some(
+      (block) => block.type === 'diff' || block.type === 'file_content',
+    );
+
+    if (visibleBlocks.length > 0) {
+      lines.push('');
+      for (const block of visibleBlocks) {
+        const blockLines = renderDisplayBlock(block, this.expanded, blockStyles, this.colors);
+        for (const line of blockLines) {
+          lines.push(indent(line));
+        }
+      }
+    } else if (data.description) {
+      lines.push('');
+      for (const descLine of data.description.split('\n')) {
+        lines.push(indent(dim(descLine)));
+      }
+    }
+
+    lines.push('');
+    for (let idx = 0; idx < data.choices.length; idx++) {
+      const option = data.choices[idx];
+      if (option === undefined) continue;
+      const isSelected = idx === this.selectedIndex;
+      const num = idx + 1;
+
+      const labelWithNum = `${String(num)}. ${option.label}`;
+      if (this.feedbackMode && option.requires_feedback === true && isSelected) {
+        lines.push(indent(this.renderInlineFeedbackLine(width - 2, labelWithNum)));
+      } else if (isSelected) {
+        lines.push(indent(`${selectColorBold('▶')} ${selectColorBold(labelWithNum)}`));
+      } else {
+        lines.push(indent(strong(`  ${labelWithNum}`)));
+      }
+    }
+
+    lines.push('');
+    if (this.feedbackMode) {
+      lines.push(indent(dim('Type feedback · ↵ submit.')));
+    } else {
+      const expandHint = hasExpandable ? ` · ctrl+e ${this.expanded ? 'collapse' : 'expand'}` : '';
+      lines.push(
+        indent(
+          dim(
+            `↑/↓ select · ${buildNumericHint(data.choices.length)} choose · ↵ confirm${expandHint}`,
+          ),
+        ),
+      );
+    }
+    lines.push(horizontalBar);
+
+    return lines.map((line) => truncateToWidth(line, width));
+  }
+
+  private choiceAt(index: number): ApprovalPanelChoice | undefined {
+    return this.request.data.choices[index];
+  }
+
+  private choiceCount(): number {
+    return this.request.data.choices.length;
+  }
+
+  private ensureValidSelection(): void {
+    const count = this.choiceCount();
+    if (count === 0) {
+      this.selectedIndex = 0;
+      return;
+    }
+    if (this.selectedIndex < 0 || this.selectedIndex >= count) {
+      this.selectedIndex = Math.max(0, Math.min(this.selectedIndex, count - 1));
+    }
+  }
+
+  private renderInlineFeedbackLine(width: number, labelWithNum: string): string {
+    const selectColorBold = chalk.bold.hex(this.colors.accent);
+    const prefix = `${selectColorBold('▶')} ${selectColorBold(labelWithNum)}  `;
+    const inputWidth = Math.max(4, width - visibleWidth(prefix) + 2);
+    const inputLine = this.feedbackInput.render(inputWidth)[0] ?? '> ';
+    const inlineInput = inputLine.startsWith('> ') ? inputLine.slice(2) : inputLine;
+    return prefix + inlineInput;
+  }
+
+  override invalidate(): void {
+    super.invalidate();
+    this.feedbackInput.invalidate();
+  }
+}
+
+function buildNumericHint(count: number): string {
+  if (count <= 0) return '↵';
+  return Array.from({ length: Math.min(count, 9) }, (_, idx) => String(idx + 1)).join('/');
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/choice-picker.ts b/apps/kimi-code/src/tui/components/dialogs/choice-picker.ts
new file mode 100644
index 000000000..66bca1a65
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/choice-picker.ts
@@ -0,0 +1,133 @@
+/**
+ * ChoicePicker — modal single-select list for slash commands that ask
+ * the user to pick from a small set of preset values.
+ *
+ * Mirrors SessionPickerComponent's container-replacement pattern: host
+ * calls `showChoicePicker(...)` which clears the editor container,
+ * addChild(picker), setFocus(picker); the picker invokes `onSelect` or
+ * `onCancel`, and the host tears it down.
+ */
+
+import {
+  Container,
+  matchesKey,
+  Key,
+  truncateToWidth,
+  visibleWidth,
+  type Focusable,
+} from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+
+export interface ChoiceOption {
+  /** Value passed to onSelect (e.g. the actual editor command string). */
+  readonly value: string;
+  /** Display text shown in the list. */
+  readonly label: string;
+  /** Optional explanatory text shown below the label. */
+  readonly description?: string | undefined;
+}
+
+export interface ChoicePickerOptions {
+  readonly title: string;
+  readonly hint?: string;
+  readonly options: readonly ChoiceOption[];
+  readonly currentValue?: string;
+  readonly colors: ColorPalette;
+  readonly onSelect: (value: string) => void;
+  readonly onCancel: () => void;
+}
+
+const CURRENT_MARK = '← current';
+
+function wrapDescription(text: string, width: number): string[] {
+  const maxWidth = Math.max(1, width);
+  const words = text
+    .trim()
+    .split(/\s+/)
+    .filter((word) => word.length > 0);
+  const lines: string[] = [];
+  let current = '';
+
+  for (const word of words) {
+    const candidate = current.length === 0 ? word : `${current} ${word}`;
+    if (visibleWidth(candidate) <= maxWidth) {
+      current = candidate;
+      continue;
+    }
+    if (current.length > 0) lines.push(current);
+    current = visibleWidth(word) <= maxWidth ? word : truncateToWidth(word, maxWidth, '…');
+  }
+
+  if (current.length > 0) lines.push(current);
+  return lines;
+}
+
+export class ChoicePickerComponent extends Container implements Focusable {
+  focused = false;
+  private readonly opts: ChoicePickerOptions;
+  private selectedIndex: number;
+
+  constructor(opts: ChoicePickerOptions) {
+    super();
+    this.opts = opts;
+    const currentIdx = opts.options.findIndex((o) => o.value === opts.currentValue);
+    this.selectedIndex = Math.max(currentIdx, 0);
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.escape)) {
+      this.opts.onCancel();
+      return;
+    }
+    if (matchesKey(data, Key.up)) {
+      this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.selectedIndex = Math.min(this.opts.options.length - 1, this.selectedIndex + 1);
+      return;
+    }
+    if (matchesKey(data, Key.enter)) {
+      const chosen = this.opts.options[this.selectedIndex];
+      if (chosen !== undefined) this.opts.onSelect(chosen.value);
+      return;
+    }
+  }
+
+  override render(width: number): string[] {
+    const { colors } = this.opts;
+    const hint = this.opts.hint ?? '↑↓ navigate · Enter select · Esc cancel';
+    const lines: string[] = [
+      chalk.hex(colors.primary)('─'.repeat(width)),
+      chalk.hex(colors.primary).bold(` ${this.opts.title}`),
+      chalk.hex(colors.textMuted)(` ${hint}`),
+      '',
+    ];
+
+    for (let i = 0; i < this.opts.options.length; i++) {
+      const opt = this.opts.options[i]!;
+      const isSelected = i === this.selectedIndex;
+      const isCurrent = opt.value === this.opts.currentValue;
+      const pointer = isSelected ? '❯' : ' ';
+      const labelStyle = isSelected ? chalk.hex(colors.primary).bold : chalk.hex(colors.text);
+      let line = chalk.hex(isSelected ? colors.primary : colors.textDim)(`  ${pointer} `);
+      line += labelStyle(opt.label);
+      if (isCurrent) {
+        line += ' ' + chalk.hex(colors.success)(CURRENT_MARK);
+      }
+      lines.push(line);
+      if (opt.description !== undefined && opt.description.length > 0) {
+        const descriptionWidth = Math.max(1, width - 4);
+        for (const descLine of wrapDescription(opt.description, descriptionWidth)) {
+          lines.push(chalk.hex(colors.textMuted)(`    ${descLine}`));
+        }
+      }
+    }
+
+    lines.push('');
+    lines.push(chalk.hex(colors.primary)('─'.repeat(width)));
+    return lines.map((line) => truncateToWidth(line, width));
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/compaction.ts b/apps/kimi-code/src/tui/components/dialogs/compaction.ts
new file mode 100644
index 000000000..6a55ede98
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/compaction.ts
@@ -0,0 +1,109 @@
+/**
+ * Renders a compaction block in the transcript.
+ *
+ * Lifecycle:
+ *   - constructed on `compaction.started` → blinking white bullet +
+ *     "Compacting context..." and optional custom instruction
+ *   - `markDone()` on `compaction.completed` → solid green bullet +
+ *     "Compaction complete (X → Y tokens)"
+ *   - `markCanceled()` on `compaction.cancelled` → solid warning bullet +
+ *     "Compaction cancelled"
+ *
+ * Bullet animation mirrors `ToolCallComponent` (500ms blink) so the user
+ * reads the same "work in progress" signal across the UI.
+ */
+
+import { Container, Text, Spacer } from '@earendil-works/pi-tui';
+import type { TUI } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import { STATUS_BULLET } from '#/tui/constant/symbols';
+import type { ColorPalette } from '#/tui/theme/colors';
+
+const BLINK_INTERVAL = 500;
+
+export class CompactionComponent extends Container {
+  private readonly colors: ColorPalette;
+  private readonly ui: TUI | undefined;
+  private readonly headerText: Text;
+  private blinkOn = true;
+  private blinkTimer: ReturnType<typeof setInterval> | null = null;
+  private done = false;
+  private canceled = false;
+  private tokensBefore: number | undefined;
+  private tokensAfter: number | undefined;
+
+  constructor(colors: ColorPalette, ui?: TUI, instruction?: string | undefined) {
+    super();
+    this.colors = colors;
+    this.ui = ui;
+
+    // Top margin so the block isn't glued to the previous transcript
+    // entry (status line, tool result, etc.).
+    this.addChild(new Spacer(1));
+    this.headerText = new Text(this.buildHeader(), 0, 0);
+    this.addChild(this.headerText);
+    if (instruction !== undefined) {
+      this.addChild(new Text(chalk.dim(`  ${instruction}`), 0, 0));
+    }
+
+    this.startBlink();
+  }
+
+  markDone(tokensBefore?: number, tokensAfter?: number): void {
+    if (this.done || this.canceled) return;
+    this.done = true;
+    this.tokensBefore = tokensBefore;
+    this.tokensAfter = tokensAfter;
+    this.stopBlink();
+    this.headerText.setText(this.buildHeader());
+    this.ui?.requestRender();
+  }
+
+  markCanceled(): void {
+    if (this.done || this.canceled) return;
+    this.canceled = true;
+    this.stopBlink();
+    this.headerText.setText(this.buildHeader());
+    this.ui?.requestRender();
+  }
+
+  dispose(): void {
+    this.stopBlink();
+  }
+
+  private buildHeader(): string {
+    if (this.done) {
+      const bullet = chalk.hex(this.colors.success)(STATUS_BULLET);
+      const label = chalk.hex(this.colors.success).bold('Compaction complete');
+      const detail =
+        this.tokensBefore !== undefined && this.tokensAfter !== undefined
+          ? chalk.dim(` (${String(this.tokensBefore)} → ${String(this.tokensAfter)} tokens)`)
+          : '';
+      return `${bullet}${label}${detail}`;
+    }
+    if (this.canceled) {
+      const bullet = chalk.hex(this.colors.warning)(STATUS_BULLET);
+      const label = chalk.hex(this.colors.warning).bold('Compaction cancelled');
+      return `${bullet}${label}`;
+    }
+    const bullet = this.blinkOn ? chalk.hex(this.colors.roleAssistant)(STATUS_BULLET) : '  ';
+    const label = chalk.hex(this.colors.primary).bold('Compacting context...');
+    return `${bullet}${label}`;
+  }
+
+  private startBlink(): void {
+    this.blinkTimer = setInterval(() => {
+      this.blinkOn = !this.blinkOn;
+      this.headerText.setText(this.buildHeader());
+      this.ui?.requestRender();
+    }, BLINK_INTERVAL);
+  }
+
+  private stopBlink(): void {
+    if (this.blinkTimer !== null) {
+      clearInterval(this.blinkTimer);
+      this.blinkTimer = null;
+    }
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/editor-selector.ts b/apps/kimi-code/src/tui/components/dialogs/editor-selector.ts
new file mode 100644
index 000000000..24467dd05
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/editor-selector.ts
@@ -0,0 +1,31 @@
+import { ChoicePickerComponent, type ChoiceOption } from './choice-picker';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+
+const EDITOR_OPTIONS: readonly ChoiceOption[] = [
+  { value: 'code --wait', label: 'VS Code (code --wait)' },
+  { value: 'vim', label: 'Vim' },
+  { value: 'nvim', label: 'Neovim' },
+  { value: 'nano', label: 'Nano' },
+  { value: '', label: 'Auto-detect ($VISUAL / $EDITOR)' },
+];
+
+export interface EditorSelectorOptions {
+  readonly currentValue: string;
+  readonly colors: ColorPalette;
+  readonly onSelect: (value: string) => void;
+  readonly onCancel: () => void;
+}
+
+export class EditorSelectorComponent extends ChoicePickerComponent {
+  constructor(opts: EditorSelectorOptions) {
+    super({
+      title: 'Select external editor',
+      options: [...EDITOR_OPTIONS],
+      currentValue: opts.currentValue,
+      colors: opts.colors,
+      onSelect: opts.onSelect,
+      onCancel: opts.onCancel,
+    });
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/feedback-input-dialog.ts b/apps/kimi-code/src/tui/components/dialogs/feedback-input-dialog.ts
new file mode 100644
index 000000000..1fb963625
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/feedback-input-dialog.ts
@@ -0,0 +1,126 @@
+/**
+ * FeedbackInputDialog — blue rounded box that collects a single line of
+ * user feedback before submitting it to the managed Kimi Code platform.
+ *
+ * Geometry mirrors `DeviceCodeBox` so the chrome stays consistent with
+ * the OAuth login flow. The box embeds a `pi-tui` Input for the actual
+ * text entry; cursor visibility tracks the dialog's `focused` flag.
+ */
+
+import {
+  Container,
+  Input,
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  type Focusable,
+} from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+
+export type FeedbackInputDialogResult =
+  | { readonly kind: 'ok'; readonly value: string }
+  | { readonly kind: 'cancel' };
+
+const TITLE = 'Send feedback to Kimi Code';
+const SUBTITLE_DEFAULT = "Tell us what's working or what's not.";
+const SUBTITLE_EMPTY = 'Feedback cannot be empty.';
+const FOOTER = 'Enter to submit  ·  Esc to cancel';
+
+export class FeedbackInputDialogComponent extends Container implements Focusable {
+  focused = false;
+
+  private readonly input = new Input();
+  private readonly onDone: (result: FeedbackInputDialogResult) => void;
+  private readonly colors: ColorPalette;
+  private done = false;
+  private emptyHinted = false;
+
+  constructor(onDone: (result: FeedbackInputDialogResult) => void, colors: ColorPalette) {
+    super();
+    this.onDone = onDone;
+    this.colors = colors;
+    this.input.onSubmit = (value) => {
+      this.submit(value);
+    };
+  }
+
+  handleInput(data: string): void {
+    if (this.done) return;
+    if (
+      matchesKey(data, Key.escape) ||
+      matchesKey(data, Key.ctrl('c')) ||
+      matchesKey(data, Key.ctrl('d'))
+    ) {
+      this.cancel();
+      return;
+    }
+    if (this.emptyHinted) {
+      this.emptyHinted = false;
+    }
+    this.input.handleInput(data);
+  }
+
+  override invalidate(): void {
+    super.invalidate();
+    this.input.invalidate();
+  }
+
+  override render(width: number): string[] {
+    this.input.focused = this.focused && !this.done;
+
+    const safeWidth = Math.max(28, width);
+    const innerWidth = Math.max(10, safeWidth - 4);
+    const pad = '  ';
+
+    const border = (s: string): string => chalk.hex(this.colors.primary)(s);
+    const titleStyled = chalk.bold.hex(this.colors.textStrong)(TITLE);
+    const subtitleText = this.emptyHinted ? SUBTITLE_EMPTY : SUBTITLE_DEFAULT;
+    const subtitleStyled = chalk.hex(this.colors.textDim)(subtitleText);
+    const footerStyled = chalk.hex(this.colors.textDim)(FOOTER);
+
+    const titleLine = truncateToWidth(titleStyled, innerWidth, '…');
+    const subtitleLine = truncateToWidth(subtitleStyled, innerWidth, '…');
+    const footerLine = truncateToWidth(footerStyled, innerWidth, '…');
+    const inputLine = this.input.render(innerWidth)[0] ?? '> ';
+
+    const contentLines: string[] = [titleLine, '', subtitleLine, '', inputLine, '', footerLine];
+
+    const lines: string[] = [
+      '',
+      border('╭' + '─'.repeat(safeWidth - 2) + '╮'),
+      border('│') + ' '.repeat(safeWidth - 2) + border('│'),
+    ];
+
+    for (const content of contentLines) {
+      const vis = visibleWidth(content);
+      const rightPad = Math.max(0, innerWidth - vis);
+      lines.push(border('│') + pad + content + ' '.repeat(rightPad) + border('│'));
+    }
+
+    lines.push(border('│') + ' '.repeat(safeWidth - 2) + border('│'));
+    lines.push(border('╰' + '─'.repeat(safeWidth - 2) + '╯'));
+    lines.push('');
+
+    return lines;
+  }
+
+  private submit(value: string): void {
+    if (this.done) return;
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+      this.emptyHinted = true;
+      return;
+    }
+    this.done = true;
+    this.onDone({ kind: 'ok', value: trimmed });
+  }
+
+  private cancel(): void {
+    if (this.done) return;
+    this.done = true;
+    this.onDone({ kind: 'cancel' });
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/help-panel.ts b/apps/kimi-code/src/tui/components/dialogs/help-panel.ts
new file mode 100644
index 000000000..36713a204
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/help-panel.ts
@@ -0,0 +1,148 @@
+/**
+ * HelpPanel — modal `/help` display. Lists keyboard shortcuts, slash
+ * commands (with aliases + descriptions) in colour-coded sections.
+ *
+ * Mirrors the container-replacement pattern used by SessionPicker /
+ * ApprovalPanel: host mounts the panel into `editorContainer`, picks
+ * it as the focused component, and tears it down on the `onClose`
+ * callback (fired on Esc / Enter / q).
+ */
+
+import {
+  Container,
+  matchesKey,
+  Key,
+  decodeKittyPrintable,
+  type Focusable,
+  truncateToWidth,
+} from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+
+export interface KeyboardShortcut {
+  readonly keys: string;
+  readonly description: string;
+}
+
+export interface HelpPanelCommand {
+  readonly name: string;
+  readonly aliases: readonly string[];
+  readonly description: string;
+}
+
+/** Static list — keep in sync with the global editor bindings. */
+export const DEFAULT_KEYBOARD_SHORTCUTS: readonly KeyboardShortcut[] = [
+  { keys: 'Shift-Tab', description: 'Toggle plan mode' },
+  // { keys: 'Ctrl-G', description: 'Edit in external editor ($VISUAL / $EDITOR)' },
+  { keys: 'Ctrl-O', description: 'Toggle tool output expansion' },
+  { keys: 'Ctrl-S', description: 'Steer — inject a follow-up during streaming' },
+  { keys: 'Shift-Enter', description: 'Insert newline' },
+  { keys: 'Ctrl-C', description: 'Interrupt stream / clear input' },
+  { keys: 'Ctrl-D', description: 'Exit (on empty input)' },
+  { keys: 'Esc', description: 'Close dialogs / interrupt streaming' },
+  { keys: '↑ / ↓', description: 'Browse input history' },
+  { keys: 'Enter', description: 'Submit' },
+];
+
+export interface HelpPanelOptions {
+  readonly commands: readonly HelpPanelCommand[];
+  readonly shortcuts?: readonly KeyboardShortcut[];
+  readonly colors: ColorPalette;
+  readonly onClose: () => void;
+  /** Terminal height — used to decide whether to show the hint tail. */
+  readonly maxVisible?: number;
+}
+
+export class HelpPanelComponent extends Container implements Focusable {
+  focused = false;
+  private readonly opts: HelpPanelOptions;
+  private scrollTop = 0;
+
+  constructor(opts: HelpPanelOptions) {
+    super();
+    this.opts = opts;
+  }
+
+  handleInput(data: string): void {
+    const printable = decodeKittyPrintable(data) ?? data;
+    if (
+      matchesKey(data, Key.escape) ||
+      matchesKey(data, Key.enter) ||
+      printable === 'q' ||
+      printable === 'Q'
+    ) {
+      this.opts.onClose();
+      return;
+    }
+    if (matchesKey(data, Key.up)) {
+      this.scrollTop = Math.max(0, this.scrollTop - 1);
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.scrollTop += 1; // render clamps
+      return;
+    }
+    if (matchesKey(data, Key.pageUp)) {
+      this.scrollTop = Math.max(0, this.scrollTop - 10);
+      return;
+    }
+    if (matchesKey(data, Key.pageDown)) {
+      this.scrollTop += 10;
+    }
+  }
+
+  override render(width: number): string[] {
+    const colors = this.opts.colors;
+    const accent = chalk.hex(colors.primary);
+    const dim = chalk.hex(colors.textDim);
+    const muted = chalk.hex(colors.textMuted);
+    const kbdColor = chalk.hex(colors.warning);
+    const slashColor = chalk.hex(colors.primary);
+
+    const shortcuts = this.opts.shortcuts ?? DEFAULT_KEYBOARD_SHORTCUTS;
+    const kbdWidth = Math.max(8, ...shortcuts.map((s) => s.keys.length));
+    const sortedCmds = [...this.opts.commands].toSorted((a, b) => a.name.localeCompare(b.name));
+    const cmdLabels = sortedCmds.map((c) => {
+      const aliases = c.aliases.length > 0 ? ` (${c.aliases.map((a) => '/' + a).join(', ')})` : '';
+      return `/${c.name}${aliases}`;
+    });
+    const cmdWidth = Math.max(12, ...cmdLabels.map((l) => l.length));
+    const lines: string[] = [
+      accent('─'.repeat(width)),
+      accent.bold(' help ') + muted('· Esc / Enter / q to close · ↑↓ scroll'),
+      '',
+      // Greeting
+      `  ${dim('Sure, Kimi is ready to help! Just send a message to get started.')}`,
+      '',
+      // Section: keyboard shortcuts
+      `  ${chalk.bold('Keyboard shortcuts')}`,
+      ...shortcuts.map((s) => `    ${kbdColor(s.keys.padEnd(kbdWidth))}  ${dim(s.description)}`),
+      '',
+      // Section: slash commands
+      `  ${chalk.bold('Slash commands')}`,
+      ...sortedCmds.map((cmd, i) => {
+        const label = cmdLabels[i] ?? `/${cmd.name}`;
+        return `    ${slashColor(label.padEnd(cmdWidth))}  ${dim(cmd.description)}`;
+      }),
+      '',
+      accent('─'.repeat(width)),
+    ];
+
+    // Apply scroll windowing — keep the borders visible.
+    const content = lines.slice(1, lines.length - 1);
+    const maxVisible = Math.max(5, this.opts.maxVisible ?? 24);
+    if (content.length > maxVisible) {
+      this.scrollTop = Math.max(0, Math.min(this.scrollTop, content.length - maxVisible));
+      const slice = content.slice(this.scrollTop, this.scrollTop + maxVisible);
+      const scrollInfo = muted(
+        ` showing ${String(this.scrollTop + 1)}-${String(this.scrollTop + slice.length)} of ${String(content.length)}`,
+      );
+      return [lines[0] ?? '', ...slice, scrollInfo, lines.at(-1) ?? ''].map((line) =>
+        truncateToWidth(line, width),
+      );
+    }
+    this.scrollTop = 0;
+    return lines.map((line) => truncateToWidth(line, width));
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/model-selector.ts b/apps/kimi-code/src/tui/components/dialogs/model-selector.ts
new file mode 100644
index 000000000..600d0ca5a
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/model-selector.ts
@@ -0,0 +1,184 @@
+import type { ModelAlias } from '@moonshot-ai/kimi-code-sdk';
+import {
+  Container,
+  Key,
+  matchesKey,
+  truncateToWidth,
+  type Focusable,
+} from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import { DEFAULT_OAUTH_PROVIDER_NAME, PRODUCT_NAME } from '#/constant/app';
+import type { ColorPalette } from '#/tui/theme/colors';
+
+import type { ChoiceOption } from './choice-picker';
+
+type ThinkingAvailability = 'toggle' | 'always-on' | 'unsupported';
+
+interface ModelChoice {
+  readonly alias: string;
+  readonly model: ModelAlias;
+  readonly label: string;
+}
+
+export interface ModelSelection {
+  readonly alias: string;
+  readonly thinking: boolean;
+}
+
+export function modelDisplayName(alias: string, model: ModelAlias | undefined): string {
+  return model?.displayName ?? model?.model ?? alias;
+}
+
+export function providerDisplayName(provider: string): string {
+  if (provider === DEFAULT_OAUTH_PROVIDER_NAME) return PRODUCT_NAME;
+  if (provider.startsWith('managed:')) return provider.slice('managed:'.length);
+  return provider;
+}
+
+export function createModelChoiceOptions(
+  models: Record<string, ModelAlias>,
+): readonly ChoiceOption[] {
+  return Object.entries(models).map(([alias, cfg]) => ({
+    value: alias,
+    label: `${modelDisplayName(alias, cfg)} (${providerDisplayName(cfg.provider)})`,
+  }));
+}
+
+export interface ModelSelectorOptions {
+  readonly models: Record<string, ModelAlias>;
+  readonly currentValue: string;
+  readonly selectedValue?: string;
+  readonly currentThinking: boolean;
+  readonly colors: ColorPalette;
+  readonly onSelect: (selection: ModelSelection) => void;
+  readonly onCancel: () => void;
+}
+
+function createModelChoices(models: Record<string, ModelAlias>): readonly ModelChoice[] {
+  return Object.entries(models).map(([alias, cfg]) => ({
+    alias,
+    model: cfg,
+    label: `${modelDisplayName(alias, cfg)} (${providerDisplayName(cfg.provider)})`,
+  }));
+}
+
+function thinkingAvailability(model: ModelAlias): ThinkingAvailability {
+  const caps = model.capabilities ?? [];
+  if (caps.includes('always_thinking')) return 'always-on';
+  if (caps.includes('thinking')) return 'toggle';
+  return 'unsupported';
+}
+
+function effectiveThinking(model: ModelAlias, thinkingDraft: boolean): boolean {
+  const availability = thinkingAvailability(model);
+  if (availability === 'always-on') return true;
+  if (availability === 'unsupported') return false;
+  return thinkingDraft;
+}
+
+export class ModelSelectorComponent extends Container implements Focusable {
+  focused = false;
+  private readonly opts: ModelSelectorOptions;
+  private readonly choices: readonly ModelChoice[];
+  private selectedIndex: number;
+  private thinkingDraft: boolean;
+
+  constructor(opts: ModelSelectorOptions) {
+    super();
+    this.opts = opts;
+    this.choices = createModelChoices(opts.models);
+    const selectedValue = opts.selectedValue ?? opts.currentValue;
+    const selectedIdx = this.choices.findIndex((choice) => choice.alias === selectedValue);
+    this.selectedIndex = Math.max(selectedIdx, 0);
+    this.thinkingDraft = opts.currentThinking;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.escape)) {
+      this.opts.onCancel();
+      return;
+    }
+    if (matchesKey(data, Key.up)) {
+      this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.selectedIndex = Math.max(0, Math.min(this.choices.length - 1, this.selectedIndex + 1));
+      return;
+    }
+    const selected = this.selectedChoice();
+    if (selected !== undefined && thinkingAvailability(selected.model) === 'toggle') {
+      if (matchesKey(data, Key.left)) {
+        this.thinkingDraft = true;
+        return;
+      }
+      if (matchesKey(data, Key.right)) {
+        this.thinkingDraft = false;
+        return;
+      }
+    }
+    if (matchesKey(data, Key.enter)) {
+      if (selected === undefined) return;
+      this.opts.onSelect({
+        alias: selected.alias,
+        thinking: effectiveThinking(selected.model, this.thinkingDraft),
+      });
+    }
+  }
+
+  override render(width: number): string[] {
+    const { colors } = this.opts;
+    const lines: string[] = [
+      chalk.hex(colors.primary)('─'.repeat(width)),
+      chalk.hex(colors.primary).bold(' Select a model'),
+      chalk.hex(colors.textMuted)(' ↑↓ model · ←→ thinking · Enter apply · Esc cancel'),
+      '',
+    ];
+
+    for (let i = 0; i < this.choices.length; i++) {
+      const choice = this.choices[i]!;
+      const isSelected = i === this.selectedIndex;
+      const isCurrent = choice.alias === this.opts.currentValue;
+      const pointer = isSelected ? '❯' : ' ';
+      const labelStyle = isSelected ? chalk.hex(colors.primary).bold : chalk.hex(colors.text);
+      let line = chalk.hex(isSelected ? colors.primary : colors.textDim)(`  ${pointer} `);
+      line += labelStyle(choice.label);
+      if (isCurrent) {
+        line += ' ' + chalk.hex(colors.success)('← current');
+      }
+      lines.push(line);
+    }
+
+    lines.push('');
+    lines.push(chalk.hex(colors.textMuted)(' Thinking'));
+    const selected = this.selectedChoice();
+    if (selected !== undefined) {
+      lines.push(this.renderThinkingControl(selected.model));
+    }
+    lines.push('');
+    lines.push(chalk.hex(colors.primary)('─'.repeat(width)));
+    return lines.map((line) => truncateToWidth(line, width));
+  }
+
+  private selectedChoice(): ModelChoice | undefined {
+    return this.choices[this.selectedIndex];
+  }
+
+  private renderThinkingControl(model: ModelAlias): string {
+    const { colors } = this.opts;
+    const segment = (label: string, active: boolean): string =>
+      active
+        ? chalk.hex(colors.primary).bold(`[ ${label} ]`)
+        : chalk.hex(colors.text)(`  ${label}  `);
+
+    const availability = thinkingAvailability(model);
+    if (availability === 'always-on') {
+      return `  ${segment('Always on', true)}`;
+    }
+    if (availability === 'unsupported') {
+      return `  ${segment('Off', true)} ${chalk.hex(colors.textMuted)('unsupported')}`;
+    }
+    return `  ${segment('On', this.thinkingDraft)}  ${segment('Off', !this.thinkingDraft)}`;
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/permission-selector.ts b/apps/kimi-code/src/tui/components/dialogs/permission-selector.ts
new file mode 100644
index 000000000..6445206d3
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/permission-selector.ts
@@ -0,0 +1,52 @@
+import type { PermissionMode } from '@moonshot-ai/kimi-code-sdk';
+
+import { ChoicePickerComponent, type ChoiceOption } from './choice-picker';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+
+const PERMISSION_OPTIONS: readonly ChoiceOption[] = [
+  {
+    value: 'manual',
+    label: 'Manual',
+    description:
+      'Ask before commands, edits, and other risky actions. Read/search tools run directly; session approval rules are respected.',
+  },
+  {
+    value: 'auto',
+    label: 'Auto',
+    description:
+      'Run fully non-interactively. Tool actions are approved automatically, and agent questions are skipped so it can decide on its own.',
+  },
+  {
+    value: 'yolo',
+    label: 'YOLO',
+    description:
+      'Automatically approve tool actions and plan transitions. The agent can still ask you explicit questions when your input is needed.',
+  },
+];
+
+function isPermissionModeChoice(value: string): value is PermissionMode {
+  return value === 'manual' || value === 'auto' || value === 'yolo';
+}
+
+export interface PermissionSelectorOptions {
+  readonly currentValue: PermissionMode;
+  readonly colors: ColorPalette;
+  readonly onSelect: (mode: PermissionMode) => void;
+  readonly onCancel: () => void;
+}
+
+export class PermissionSelectorComponent extends ChoicePickerComponent {
+  constructor(opts: PermissionSelectorOptions) {
+    super({
+      title: 'Select permission mode',
+      options: [...PERMISSION_OPTIONS],
+      currentValue: opts.currentValue,
+      colors: opts.colors,
+      onSelect: (value) => {
+        if (isPermissionModeChoice(value)) opts.onSelect(value);
+      },
+      onCancel: opts.onCancel,
+    });
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/platform-selector.ts b/apps/kimi-code/src/tui/components/dialogs/platform-selector.ts
new file mode 100644
index 000000000..d01b26e50
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/platform-selector.ts
@@ -0,0 +1,27 @@
+import { ChoicePickerComponent, type ChoiceOption } from './choice-picker';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+
+const PLATFORM_OPTIONS: readonly ChoiceOption[] = [
+  { value: 'kimi-code', label: 'Kimi Code' },
+  { value: 'moonshot-cn', label: 'Moonshot AI Open Platform (moonshot.cn)' },
+  { value: 'moonshot-ai', label: 'Moonshot AI Open Platform (moonshot.ai)' },
+];
+
+export interface PlatformSelectorOptions {
+  readonly colors: ColorPalette;
+  readonly onSelect: (platformId: string) => void;
+  readonly onCancel: () => void;
+}
+
+export class PlatformSelectorComponent extends ChoicePickerComponent {
+  constructor(opts: PlatformSelectorOptions) {
+    super({
+      title: 'Select a platform',
+      options: [...PLATFORM_OPTIONS],
+      colors: opts.colors,
+      onSelect: opts.onSelect,
+      onCancel: opts.onCancel,
+    });
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/question-dialog.ts b/apps/kimi-code/src/tui/components/dialogs/question-dialog.ts
new file mode 100644
index 000000000..534e2c2f2
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/question-dialog.ts
@@ -0,0 +1,755 @@
+/**
+ * QuestionDialog — pi-tui version of the structured question prompt.
+ *
+ * Each question collects an answer locally, and a final Submit tab
+ * reviews everything before the answers are emitted upstream.
+ */
+
+import {
+  Container,
+  Input,
+  matchesKey,
+  Key,
+  decodeKittyPrintable,
+  type Focusable,
+  truncateToWidth,
+  visibleWidth,
+} from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type {
+  PendingQuestion,
+  QuestionPanelResponse,
+  QuestionSubmissionMethod,
+} from '#/tui/reverse-rpc/types';
+import type { ColorPalette } from '#/tui/theme/colors';
+
+const NUMBER_KEYS = ['1', '2', '3', '4', '5', '6', '7', '8', '9'];
+const MAX_BODY_LINES = 12;
+const DEFAULT_OTHER_LABEL = 'Other';
+const NOT_ANSWERED_LABEL = 'Not answered';
+const REVIEW_TITLE = 'Review your answer before submit';
+const SUBMIT_PROMPT = 'Ready to submit your answers?';
+const UNANSWERED_WARNING = 'Some questions are still unanswered.';
+const SUBMIT_ACTIONS = ['Submit', 'Cancel'] as const;
+
+interface DisplayOption {
+  readonly label: string;
+  readonly description?: string | undefined;
+  readonly kind: 'preset' | 'other';
+}
+
+export class QuestionDialogComponent extends Container implements Focusable {
+  focused = false;
+
+  private readonly request: PendingQuestion;
+  private readonly colors: ColorPalette;
+  private readonly onAnswer: (response: QuestionPanelResponse) => void;
+  private readonly maxVisibleOptions: number;
+  private readonly otherInput = new Input();
+
+  private currentTab = 0;
+  private submitActionIdx = 0;
+  private editingOther = false;
+  private reviewMessage: string | undefined;
+  private lastAnswerMethod: QuestionSubmissionMethod | undefined;
+
+  /** Per-question cursor position. */
+  private readonly cursors: number[];
+  /** Per-question single-select choice. */
+  private readonly singleSelections: (number | undefined)[];
+  /** Per-question multi-select choices. */
+  private readonly multiSelections: Set<number>[];
+  /** Per-question free-text drafts for the synthetic Other option. */
+  private readonly otherDrafts: string[];
+  /** Per-question committed Other values. */
+  private readonly committedOtherValues: (string | undefined)[];
+  /** Per-question derived answers used by tabs + review. */
+  private readonly answers: (string | undefined)[];
+
+  private readonly onToggleToolOutput: (() => void) | undefined;
+  private readonly onTogglePlanExpand: (() => void) | undefined;
+
+  constructor(
+    request: PendingQuestion,
+    onAnswer: (response: QuestionPanelResponse) => void,
+    colors: ColorPalette,
+    maxVisibleOptions = 6,
+    onToggleToolOutput?: () => void,
+    onTogglePlanExpand?: () => void,
+  ) {
+    super();
+    this.request = request;
+    this.onAnswer = onAnswer;
+    this.colors = colors;
+    this.maxVisibleOptions = maxVisibleOptions;
+    this.onToggleToolOutput = onToggleToolOutput;
+    this.onTogglePlanExpand = onTogglePlanExpand;
+    this.otherInput.onSubmit = (value) => {
+      this.commitOtherInput(value, 'enter');
+    };
+
+    const total = request.data.questions.length;
+    this.cursors = Array.from({ length: total }, (): number => 0);
+    this.singleSelections = Array.from({ length: total }, (): number | undefined => undefined);
+    this.multiSelections = Array.from({ length: total }, () => new Set<number>());
+    this.otherDrafts = Array.from({ length: total }, (): string => '');
+    this.committedOtherValues = Array.from({ length: total }, (): string | undefined => undefined);
+    this.answers = Array.from({ length: total }, (): string | undefined => undefined);
+  }
+
+  // ── Input ─────────────────────────────────────────────────────────
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.escape)) {
+      this.onAnswer({ answers: [] });
+      return;
+    }
+
+    if (matchesKey(data, Key.ctrl('c')) || matchesKey(data, Key.ctrl('d'))) {
+      this.onAnswer({ answers: [] });
+      return;
+    }
+
+    if (matchesKey(data, Key.ctrl('o'))) {
+      this.onToggleToolOutput?.();
+      return;
+    }
+
+    if (matchesKey(data, Key.ctrl('e'))) {
+      this.onTogglePlanExpand?.();
+      return;
+    }
+
+    if (this.isEditingOther()) {
+      this.handleOtherInput(data);
+      return;
+    }
+
+    if (this.isSubmitTab()) {
+      this.handleSubmitInput(data);
+      return;
+    }
+
+    const questionIdx = this.currentQuestionIndex();
+    if (questionIdx === undefined) return;
+    const question = this.request.data.questions[questionIdx];
+    if (question === undefined) return;
+
+    const optionCount = this.displayOptions(questionIdx).length;
+    if (optionCount === 0) return;
+
+    if (matchesKey(data, Key.up)) {
+      this.moveQuestionCursor(-1);
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.moveQuestionCursor(1);
+      return;
+    }
+
+    if (matchesKey(data, Key.left)) {
+      this.gotoTab(this.currentTab - 1);
+      return;
+    }
+    if (matchesKey(data, Key.right) || matchesKey(data, Key.tab)) {
+      this.gotoTab(this.currentTab + 1);
+      return;
+    }
+
+    if (matchesKey(data, Key.enter)) {
+      this.activateQuestionOption(this.currentCursor(), 'enter');
+      return;
+    }
+
+    const printable = decodeKittyPrintable(data) ?? data;
+    const numIdx = NUMBER_KEYS.indexOf(printable);
+    if (numIdx >= 0 && numIdx < optionCount) {
+      this.cursors[questionIdx] = numIdx;
+      this.activateQuestionOption(numIdx, 'number_key');
+      return;
+    }
+
+    if ((printable === ' ' || matchesKey(data, Key.space)) && question.multi_select) {
+      this.activateQuestionOption(this.currentCursor(), 'space');
+    }
+  }
+
+  private handleOtherInput(data: string): void {
+    const questionIdx = this.currentQuestionIndex();
+    if (questionIdx === undefined) return;
+
+    if (matchesKey(data, Key.tab)) {
+      this.syncOtherDraft(questionIdx);
+      this.editingOther = false;
+      this.gotoTab(this.currentTab + 1);
+      return;
+    }
+    if (matchesKey(data, Key.up)) {
+      this.syncOtherDraft(questionIdx);
+      this.editingOther = false;
+      this.moveQuestionCursor(-1);
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.syncOtherDraft(questionIdx);
+      this.editingOther = false;
+      this.moveQuestionCursor(1);
+      return;
+    }
+
+    this.otherInput.handleInput(data);
+    this.syncOtherDraft(questionIdx);
+    this.reviewMessage = undefined;
+  }
+
+  private handleSubmitInput(data: string): void {
+    if (matchesKey(data, Key.up)) {
+      this.submitActionIdx =
+        (this.submitActionIdx - 1 + SUBMIT_ACTIONS.length) % SUBMIT_ACTIONS.length;
+      this.reviewMessage = undefined;
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.submitActionIdx = (this.submitActionIdx + 1) % SUBMIT_ACTIONS.length;
+      this.reviewMessage = undefined;
+      return;
+    }
+
+    if (matchesKey(data, Key.left)) {
+      this.gotoTab(this.currentTab - 1);
+      return;
+    }
+    if (matchesKey(data, Key.right) || matchesKey(data, Key.tab)) {
+      this.gotoTab(this.currentTab + 1);
+      return;
+    }
+
+    if (matchesKey(data, Key.enter)) {
+      this.executeSubmitAction(this.submitActionIdx, 'enter');
+      return;
+    }
+
+    const printable = decodeKittyPrintable(data) ?? data;
+    if (printable === '1') {
+      this.submitActionIdx = 0;
+      this.executeSubmitAction(0, 'number_key');
+      return;
+    }
+    if (printable === '2') {
+      this.submitActionIdx = 1;
+      this.executeSubmitAction(1, 'number_key');
+    }
+  }
+
+  // ── State mutation ────────────────────────────────────────────────
+
+  private gotoTab(target: number): void {
+    const total = this.totalTabs();
+    if (total <= 0) return;
+
+    const wrapped = ((target % total) + total) % total;
+    if (wrapped === this.currentTab) return;
+
+    this.currentTab = wrapped;
+    this.editingOther = false;
+    this.reviewMessage = undefined;
+    if (this.isSubmitTab()) this.submitActionIdx = 0;
+  }
+
+  private moveQuestionCursor(delta: number): void {
+    const questionIdx = this.currentQuestionIndex();
+    if (questionIdx === undefined) return;
+
+    const total = this.displayOptions(questionIdx).length;
+    if (total <= 0) return;
+
+    this.cursors[questionIdx] = (this.currentCursor() + delta + total) % total;
+    this.reviewMessage = undefined;
+  }
+
+  private activateQuestionOption(optionIdx: number, method: QuestionSubmissionMethod): void {
+    const questionIdx = this.currentQuestionIndex();
+    if (questionIdx === undefined) return;
+
+    const question = this.request.data.questions[questionIdx];
+    if (question === undefined) return;
+
+    this.cursors[questionIdx] = optionIdx;
+    this.editingOther = false;
+    this.reviewMessage = undefined;
+
+    if (this.isOtherOption(questionIdx, optionIdx)) {
+      this.enterOtherInput(questionIdx);
+      return;
+    }
+
+    if (question.multi_select) {
+      const set = this.multiSelections[questionIdx];
+      if (set === undefined) return;
+      if (set.has(optionIdx)) set.delete(optionIdx);
+      else set.add(optionIdx);
+      this.lastAnswerMethod = method;
+      this.updateAnswer(questionIdx);
+      return;
+    }
+
+    this.singleSelections[questionIdx] = optionIdx;
+    this.committedOtherValues[questionIdx] = undefined;
+    this.lastAnswerMethod = method;
+    this.updateAnswer(questionIdx);
+    this.advanceAfterSingleSelect(questionIdx);
+  }
+
+  private enterOtherInput(questionIdx: number): void {
+    this.cursors[questionIdx] = this.otherOptionIndex(questionIdx);
+    this.editingOther = true;
+    this.otherInput.setValue(this.otherDraftValue(questionIdx));
+    this.reviewMessage = undefined;
+  }
+
+  private commitOtherInput(rawValue: string | undefined, method: QuestionSubmissionMethod): void {
+    const questionIdx = this.currentQuestionIndex();
+    if (questionIdx === undefined) return;
+
+    const question = this.request.data.questions[questionIdx];
+    if (question === undefined) return;
+
+    const value = (rawValue ?? this.otherInput.getValue()).trim();
+    if (value.length === 0) return;
+
+    this.otherInput.setValue(value);
+    this.otherDrafts[questionIdx] = value;
+    this.committedOtherValues[questionIdx] = value;
+
+    if (question.multi_select) {
+      this.multiSelections[questionIdx]?.add(this.otherOptionIndex(questionIdx));
+    } else {
+      this.singleSelections[questionIdx] = this.otherOptionIndex(questionIdx);
+    }
+
+    this.lastAnswerMethod = method;
+    this.updateAnswer(questionIdx);
+    this.editingOther = false;
+    this.reviewMessage = undefined;
+
+    if (!question.multi_select) this.advanceAfterSingleSelect(questionIdx);
+  }
+
+  private advanceAfterSingleSelect(questionIdx: number): void {
+    const next = this.findNextUnansweredAfter(questionIdx);
+    this.currentTab = next ?? this.submitTabIndex();
+    this.reviewMessage = undefined;
+    if (this.isSubmitTab()) this.submitActionIdx = 0;
+  }
+
+  private findNextUnansweredAfter(fromIdx: number): number | null {
+    const total = this.request.data.questions.length;
+    for (let idx = fromIdx + 1; idx < total; idx++) {
+      if (!this.isAnswered(idx)) return idx;
+    }
+    return null;
+  }
+
+  private updateAnswer(questionIdx: number): void {
+    const question = this.request.data.questions[questionIdx];
+    if (question === undefined) return;
+
+    if (question.multi_select) {
+      const labels: string[] = [];
+      const set = this.multiSelections[questionIdx] ?? new Set<number>();
+      const otherIdx = this.otherOptionIndex(questionIdx);
+      for (let i = 0; i < question.options.length; i++) {
+        if (!set.has(i)) continue;
+        const label = question.options[i]?.label;
+        if (label !== undefined && label.length > 0) labels.push(label);
+      }
+      const otherText = this.committedOtherValues[questionIdx];
+      if (set.has(otherIdx) && otherText !== undefined && otherText.length > 0) {
+        labels.push(otherText);
+      }
+      this.answers[questionIdx] = labels.length > 0 ? labels.join(', ') : undefined;
+      return;
+    }
+
+    const selection = this.singleSelections[questionIdx];
+    if (selection === undefined) {
+      this.answers[questionIdx] = undefined;
+      return;
+    }
+
+    if (this.isOtherOption(questionIdx, selection)) {
+      const otherText = this.committedOtherValues[questionIdx];
+      this.answers[questionIdx] =
+        otherText !== undefined && otherText.length > 0 ? otherText : undefined;
+      return;
+    }
+
+    const label = question.options[selection]?.label;
+    this.answers[questionIdx] = label !== undefined && label.length > 0 ? label : undefined;
+  }
+
+  private executeSubmitAction(actionIdx: number, method: QuestionSubmissionMethod): void {
+    if (actionIdx === 1) {
+      this.onAnswer({ answers: [] });
+      return;
+    }
+
+    this.reviewMessage = undefined;
+    this.emitAnswers(method);
+  }
+
+  private emitAnswers(method: QuestionSubmissionMethod): void {
+    const out: string[] = [];
+    for (let i = 0; i < this.answers.length; i++) {
+      const answer = this.answers[i];
+      if (answer !== undefined && answer.length > 0) out[i] = answer;
+    }
+    this.onAnswer({ answers: out, method: this.lastAnswerMethod ?? method });
+  }
+
+  // ── Render ────────────────────────────────────────────────────────
+
+  override render(width: number): string[] {
+    this.otherInput.focused = this.focused && this.isEditingOther();
+    return this.isSubmitTab() ? this.renderSubmitTab(width) : this.renderQuestionTab(width);
+  }
+
+  private renderQuestionTab(width: number): string[] {
+    const questionIdx = this.currentQuestionIndex();
+    if (questionIdx === undefined) return this.renderSubmitTab(width);
+
+    const question = this.request.data.questions[questionIdx];
+    if (question === undefined) return [];
+
+    const colors = this.colors;
+    const accent = chalk.hex(colors.primary);
+    const dim = chalk.hex(colors.textDim);
+    const success = chalk.hex(colors.success);
+
+    const renderWidth = Math.max(1, width);
+    const lines: string[] = [accent('─'.repeat(renderWidth)), accent.bold(' question'), ''];
+    this.pushTabs(lines);
+    lines.push('');
+
+    lines.push(accent(` ? ${question.question}`));
+    if (this.isEditingOther()) {
+      lines.push(dim('   Type your answer, then press Enter to save.'));
+    }
+
+    if (question.body !== undefined && question.body.trim().length > 0) {
+      lines.push('');
+      const bodyLines = question.body.trim().split('\n');
+      const visibleBodyLines = bodyLines.slice(0, MAX_BODY_LINES);
+      for (const bodyLine of visibleBodyLines) {
+        lines.push(dim(`   ${bodyLine}`));
+      }
+      if (bodyLines.length > visibleBodyLines.length) {
+        lines.push(dim(`   ... ${String(bodyLines.length - visibleBodyLines.length)} more lines`));
+      }
+    }
+
+    lines.push('');
+
+    const options = this.displayOptions(questionIdx);
+    const cursor = this.currentCursor();
+    const visibleStart = this.computeVisibleStart(cursor, options.length);
+    const visibleEnd = Math.min(options.length, visibleStart + this.maxVisibleOptions);
+    const multiSet = this.multiSelections[questionIdx] ?? new Set<number>();
+    const singleSelection = this.singleSelections[questionIdx];
+
+    for (let i = visibleStart; i < visibleEnd; i++) {
+      const option = options[i];
+      if (option === undefined) continue;
+      const num = i + 1;
+      const isCursor = i === cursor;
+      const isOther = option.kind === 'other';
+      const isSelected = question.multi_select ? multiSet.has(i) : singleSelection === i;
+
+      if (this.isEditingOther() && isCursor && isOther) {
+        lines.push(this.renderEditingOtherLine(renderWidth, questionIdx, option, num, isSelected));
+        continue;
+      }
+
+      const label = this.renderOptionLabel(questionIdx, option, isCursor);
+
+      let line: string;
+      if (question.multi_select) {
+        const checked = isSelected ? '✓' : ' ';
+        const body = `[${checked}] ${label}`;
+        if (isSelected && isCursor) line = success.bold(`  ${body}`);
+        else if (isSelected) line = success(`  ${body}`);
+        else if (isCursor) line = accent(`  ${body}`);
+        else line = dim(`  ${body}`);
+      } else if (isSelected && this.isAnswered(questionIdx)) {
+        line = isCursor
+          ? success.bold(`  → [${String(num)}] ${label}`)
+          : success(`    [${String(num)}] ${label}`);
+      } else if (isCursor) {
+        line = accent(`  → [${String(num)}] ${label}`);
+      } else {
+        line = dim(`    [${String(num)}] ${label}`);
+      }
+      lines.push(line);
+
+      if (
+        option.description !== undefined &&
+        option.description.length > 0 &&
+        !(this.isEditingOther() && isCursor && isOther)
+      ) {
+        lines.push(dim(`        ${option.description}`));
+      }
+    }
+
+    if (visibleEnd < options.length || visibleStart > 0) {
+      lines.push(
+        dim(
+          `   showing ${String(visibleStart + 1)}-${String(visibleEnd)} of ${String(options.length)}`,
+        ),
+      );
+    }
+
+    lines.push('');
+    lines.push(this.buildQuestionHint(dim, questionIdx));
+    lines.push(accent('─'.repeat(renderWidth)));
+
+    return lines.map((line) => truncateToWidth(line, width));
+  }
+
+  private renderSubmitTab(width: number): string[] {
+    const colors = this.colors;
+    const accent = chalk.hex(colors.primary);
+    const dim = chalk.hex(colors.textDim);
+    const text = chalk.hex(colors.text);
+    const warning = chalk.hex(colors.warning);
+
+    const renderWidth = Math.max(1, width);
+    const lines: string[] = [accent('─'.repeat(renderWidth)), accent.bold(' question'), ''];
+    this.pushTabs(lines);
+    lines.push('');
+    lines.push(text.bold(` ${REVIEW_TITLE}`));
+    const reviewWarning =
+      this.reviewMessage ?? (this.hasUnansweredQuestions() ? UNANSWERED_WARNING : undefined);
+    if (reviewWarning !== undefined) {
+      lines.push(warning(`  ${reviewWarning}`));
+    }
+    lines.push('');
+
+    for (let i = 0; i < this.request.data.questions.length; i++) {
+      const question = this.request.data.questions[i];
+      if (question === undefined) continue;
+      const answer = this.answers[i];
+      lines.push(`  ${dim('Q')}  ${question.question}`);
+      if (answer !== undefined && answer.length > 0) {
+        lines.push(`  ${accent('→')}  ${text(answer)}`);
+      } else {
+        lines.push(`  ${dim('→')}  ${dim(NOT_ANSWERED_LABEL)}`);
+      }
+    }
+
+    lines.push('');
+    lines.push(text(` ${SUBMIT_PROMPT}`));
+    lines.push('');
+
+    for (let i = 0; i < SUBMIT_ACTIONS.length; i++) {
+      const label = SUBMIT_ACTIONS[i];
+      if (label === undefined) continue;
+      const num = i + 1;
+      if (i === this.submitActionIdx) {
+        lines.push(accent(`  → [${String(num)}] ${label}`));
+      } else {
+        lines.push(dim(`    [${String(num)}] ${label}`));
+      }
+    }
+
+    lines.push('');
+    lines.push(this.buildSubmitHint(dim));
+    lines.push(accent('─'.repeat(renderWidth)));
+
+    return lines.map((line) => truncateToWidth(line, width));
+  }
+
+  private pushTabs(lines: string[]): void {
+    const dim = chalk.hex(this.colors.textDim);
+    const active = chalk.bgHex(this.colors.primary).hex(this.colors.text).bold;
+
+    const tabs: string[] = [];
+    for (let i = 0; i < this.request.data.questions.length; i++) {
+      const question = this.request.data.questions[i];
+      if (question === undefined) continue;
+      const label =
+        question.header !== undefined && question.header.length > 0
+          ? question.header
+          : `Q${String(i + 1)}`;
+      if (i === this.currentTab) tabs.push(active(` ${label} `));
+      else if (this.isAnswered(i)) tabs.push(chalk.hex(this.colors.success)(`(✓) ${label}`));
+      else tabs.push(dim(`(○) ${label}`));
+    }
+
+    const submitLabel = 'Submit';
+    if (this.isSubmitTab()) tabs.push(active(` ${submitLabel} `));
+    else tabs.push(dim(` ${submitLabel} `));
+
+    lines.push(` ${tabs.join('  ')}`);
+  }
+
+  private buildQuestionHint(dim: (s: string) => string, questionIdx: number): string {
+    if (this.isEditingOther()) {
+      const parts: string[] = [
+        'type answer',
+        '↵ save',
+        ...(this.totalTabs() > 1 ? ['tab switch'] : []),
+        'esc dismiss',
+      ];
+      return dim(`  ${parts.join('  ')}`);
+    }
+
+    const optionCount = Math.min(this.displayOptions(questionIdx).length, NUMBER_KEYS.length);
+    const numberHint = optionCount <= 1 ? '1' : `1-${String(optionCount)}`;
+    const question = this.request.data.questions[questionIdx];
+    if (question === undefined) return dim('  esc dismiss');
+
+    const parts: string[] = [
+      '▲/▼ select',
+      `${numberHint} / ↵ ${question.multi_select ? 'toggle' : 'choose'}`,
+    ];
+    if (this.totalTabs() > 1) parts.push('←/→/tab switch');
+    parts.push('esc dismiss');
+    return dim(`  ${parts.join('  ')}`);
+  }
+
+  private buildSubmitHint(dim: (s: string) => string): string {
+    const parts: string[] = ['▲/▼ select', '1/2 choose', '↵ confirm'];
+    if (this.totalTabs() > 1) parts.push('←/→/tab switch');
+    parts.push('esc dismiss');
+    return dim(`  ${parts.join('  ')}`);
+  }
+
+  private computeVisibleStart(cursor: number, total: number): number {
+    if (total <= this.maxVisibleOptions) return 0;
+    const half = Math.floor(this.maxVisibleOptions / 2);
+    const max = Math.max(0, total - this.maxVisibleOptions);
+    return Math.max(0, Math.min(cursor - half, max));
+  }
+
+  // ── Helpers ───────────────────────────────────────────────────────
+
+  private totalTabs(): number {
+    return this.request.data.questions.length + 1;
+  }
+
+  private submitTabIndex(): number {
+    return this.request.data.questions.length;
+  }
+
+  private isSubmitTab(): boolean {
+    return this.currentTab === this.submitTabIndex();
+  }
+
+  private isEditingOther(): boolean {
+    return this.editingOther && !this.isSubmitTab();
+  }
+
+  private currentQuestionIndex(): number | undefined {
+    return this.isSubmitTab() ? undefined : this.currentTab;
+  }
+
+  private currentCursor(): number {
+    const questionIdx = this.currentQuestionIndex();
+    if (questionIdx === undefined) return 0;
+    return this.cursors[questionIdx] ?? 0;
+  }
+
+  private displayOptions(questionIdx: number): DisplayOption[] {
+    const question = this.request.data.questions[questionIdx];
+    if (question === undefined) return [];
+
+    return [
+      ...question.options.map((option) => ({
+        label: option.label,
+        description: option.description,
+        kind: 'preset' as const,
+      })),
+      {
+        label: question.other_label?.length ? question.other_label : DEFAULT_OTHER_LABEL,
+        description: question.other_description?.length ? question.other_description : undefined,
+        kind: 'other' as const,
+      },
+    ];
+  }
+
+  private otherOptionIndex(questionIdx: number): number {
+    return this.request.data.questions[questionIdx]?.options.length ?? 0;
+  }
+
+  private isOtherOption(questionIdx: number, optionIdx: number): boolean {
+    return optionIdx === this.otherOptionIndex(questionIdx);
+  }
+
+  private renderOptionLabel(questionIdx: number, option: DisplayOption, isCursor: boolean): string {
+    if (option.kind !== 'other') return option.label;
+
+    const value = this.otherDraftValue(questionIdx);
+    if (this.isEditingOther() && isCursor) {
+      return `${option.label}: ${value ?? ''}█`;
+    }
+    if (value !== undefined && value.length > 0) return `${option.label}: ${value}`;
+    return option.label;
+  }
+
+  private renderEditingOtherLine(
+    width: number,
+    questionIdx: number,
+    option: DisplayOption,
+    num: number,
+    isSelected: boolean,
+  ): string {
+    const question = this.request.data.questions[questionIdx];
+    if (question === undefined) return option.label;
+
+    let prefix: string;
+    if (question.multi_select) {
+      const checked = isSelected ? '✓' : ' ';
+      const body = `  [${checked}] ${option.label}: `;
+      prefix = isSelected
+        ? chalk.hex(this.colors.success).bold(body)
+        : chalk.hex(this.colors.primary)(body);
+    } else {
+      const body = `  → [${String(num)}] ${option.label}: `;
+      prefix =
+        isSelected && this.isAnswered(questionIdx)
+          ? chalk.hex(this.colors.success).bold(body)
+          : chalk.hex(this.colors.primary)(body);
+    }
+
+    const inputWidth = Math.max(4, width - visibleWidth(prefix) + 2);
+    const inputLine = this.otherInput.render(inputWidth)[0] ?? '> ';
+    const inlineInput = inputLine.startsWith('> ') ? inputLine.slice(2) : inputLine;
+    return prefix + inlineInput;
+  }
+
+  private otherDraftValue(questionIdx: number): string {
+    return (this.otherDrafts[questionIdx] ?? this.committedOtherValues[questionIdx]) ?? '';
+  }
+
+  private syncOtherDraft(questionIdx: number): void {
+    this.otherDrafts[questionIdx] = this.otherInput.getValue();
+  }
+
+  private isAnswered(questionIdx: number): boolean {
+    const answer = this.answers[questionIdx];
+    return answer !== undefined && answer.length > 0;
+  }
+
+  private hasUnansweredQuestions(): boolean {
+    for (let i = 0; i < this.request.data.questions.length; i++) {
+      if (!this.isAnswered(i)) return true;
+    }
+    return false;
+  }
+
+  override invalidate(): void {
+    super.invalidate();
+    this.otherInput.invalidate();
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/session-picker.ts b/apps/kimi-code/src/tui/components/dialogs/session-picker.ts
new file mode 100644
index 000000000..da1a139e6
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/session-picker.ts
@@ -0,0 +1,268 @@
+/**
+ * SessionPicker — pi-tui version of the session selection dialog.
+ */
+
+import {
+  Container,
+  matchesKey,
+  Key,
+  truncateToWidth,
+  visibleWidth,
+  type Focusable,
+} from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import { formatSessionLabel } from '#/migration/index';
+import type { ColorPalette } from '#/tui/theme/colors';
+
+export interface SessionRow {
+  readonly id: string;
+  readonly title: string | null;
+  readonly last_prompt?: string | null;
+  readonly work_dir: string;
+  readonly updated_at: number;
+  readonly metadata?: Readonly<Record<string, unknown>> | undefined;
+}
+
+const ELLIPSIS = '…';
+const CURRENT_BADGE = '(current)';
+
+function formatRelativeTime(ts: number): string {
+  // SessionSummary timestamps come from filesystem stat `*timeMs`,
+  // so they use the same millisecond unit as `Date.now()`.
+  if (!Number.isFinite(ts) || ts <= 0) return '';
+  const diffSec = Math.floor(Math.max(0, Date.now() - ts) / 1000);
+  if (diffSec < 60) return 'just now';
+  const minutes = Math.floor(diffSec / 60);
+  if (minutes < 60) return `${String(minutes)}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${String(hours)}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${String(days)}d ago`;
+}
+
+function homeAlias(path: string): string {
+  const home = process.env['HOME'] ?? '';
+  if (home && path.startsWith(home)) return '~' + path.slice(home.length);
+  return path;
+}
+
+// Truncates from the LEFT (keeps the tail), prefixing an ellipsis when clipped.
+// Paths typically carry the relevant info near the end, so we drop the prefix.
+function truncatePathLeft(path: string, maxWidth: number): string {
+  if (maxWidth <= 0) return '';
+  if (visibleWidth(path) <= maxWidth) return path;
+  if (maxWidth === 1) return ELLIPSIS;
+  // Walk graphemes from the end accumulating width, keep the longest tail
+  // whose width + ellipsis fits.
+  const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+  const segments = [...segmenter.segment(path)].map((s) => s.segment);
+  let used = 0;
+  const budget = maxWidth - 1; // reserve 1 column for ellipsis
+  let i = segments.length - 1;
+  while (i >= 0) {
+    const seg = segments[i];
+    if (seg === undefined) break;
+    const w = visibleWidth(seg);
+    if (used + w > budget) break;
+    used += w;
+    i--;
+  }
+  return ELLIPSIS + segments.slice(i + 1).join('');
+}
+
+function singleLine(text: string): string {
+  return text.replaceAll(/\s+/g, ' ').trim();
+}
+
+export class SessionPickerComponent extends Container implements Focusable {
+  private sessions: SessionRow[];
+  private currentSessionId: string;
+  private colors: ColorPalette;
+  private onSelect: (sessionId: string) => void;
+  private onCancel: () => void;
+  private maxVisibleSessions: number;
+  private loading: boolean;
+
+  focused = false;
+  private selectedIndex = 0;
+
+  constructor(opts: {
+    sessions: SessionRow[];
+    loading: boolean;
+    currentSessionId: string;
+    colors: ColorPalette;
+    onSelect: (sessionId: string) => void;
+    onCancel: () => void;
+    maxVisibleSessions?: number;
+  }) {
+    super();
+    this.sessions = opts.sessions;
+    this.loading = opts.loading;
+    this.currentSessionId = opts.currentSessionId;
+    this.colors = opts.colors;
+    this.onSelect = opts.onSelect;
+    this.onCancel = opts.onCancel;
+    this.maxVisibleSessions = opts.maxVisibleSessions ?? 4;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.escape)) {
+      this.onCancel();
+      return;
+    }
+    if (matchesKey(data, Key.enter) && this.sessions.length > 0) {
+      const session = this.sessions[this.selectedIndex];
+      if (session) this.onSelect(session.id);
+      return;
+    }
+    if (matchesKey(data, Key.up)) {
+      this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.selectedIndex = Math.min(this.sessions.length - 1, this.selectedIndex + 1);
+    }
+  }
+
+  override render(width: number): string[] {
+    const colors = this.colors;
+    const lines: string[] = [chalk.hex(colors.primary)('─'.repeat(width))];
+
+    if (this.loading) {
+      lines.push(chalk.hex(colors.primary).bold(truncateToWidth('Sessions', width, ELLIPSIS)));
+      lines.push(
+        chalk.hex(colors.textMuted)(truncateToWidth('Loading sessions...', width, ELLIPSIS)),
+      );
+      lines.push(chalk.hex(colors.primary)('─'.repeat(width)));
+      return lines;
+    }
+
+    if (this.sessions.length === 0) {
+      lines.push(chalk.hex(colors.primary).bold(truncateToWidth('Sessions', width, ELLIPSIS)));
+      lines.push(
+        chalk.hex(colors.textMuted)(
+          truncateToWidth('No sessions found. Press Escape to close.', width, ELLIPSIS),
+        ),
+      );
+      lines.push(chalk.hex(colors.primary)('─'.repeat(width)));
+      return lines;
+    }
+
+    const headerLabel = 'Sessions ';
+    const headerHint = '(↑↓ navigate, Enter select, Esc cancel)';
+    const labelWidth = visibleWidth(headerLabel);
+    const hintBudget = Math.max(0, width - labelWidth);
+    const shownHint = truncateToWidth(headerHint, hintBudget, ELLIPSIS);
+    lines.push(
+      chalk.hex(colors.primary).bold(headerLabel) + chalk.hex(colors.textMuted)(shownHint),
+    );
+    lines.push('');
+
+    const visibleStart = Math.max(
+      0,
+      Math.min(
+        this.selectedIndex - Math.floor(this.maxVisibleSessions / 2),
+        Math.max(0, this.sessions.length - this.maxVisibleSessions),
+      ),
+    );
+    const visibleSessions = this.sessions.slice(
+      visibleStart,
+      visibleStart + this.maxVisibleSessions,
+    );
+
+    for (const [vi, session] of visibleSessions.entries()) {
+      const index = visibleStart + vi;
+      const isSelected = index === this.selectedIndex;
+      const isCurrent = session.id === this.currentSessionId;
+      const card = this.renderSessionCard(width, session, isSelected, isCurrent);
+      lines.push(...card);
+      if (vi < visibleSessions.length - 1) lines.push('');
+    }
+
+    if (this.sessions.length > visibleSessions.length) {
+      lines.push('');
+      const footer = `Showing ${String(visibleStart + 1)}-${String(visibleStart + visibleSessions.length)} of ${String(this.sessions.length)} sessions`;
+      lines.push(chalk.hex(colors.textMuted)(truncateToWidth(footer, width, ELLIPSIS)));
+    }
+
+    lines.push(chalk.hex(colors.primary)('─'.repeat(width)));
+    return lines;
+  }
+
+  private renderSessionCard(
+    width: number,
+    session: SessionRow,
+    isSelected: boolean,
+    isCurrent: boolean,
+  ): string[] {
+    const colors = this.colors;
+    const pointer = isSelected ? '❯' : ' ';
+    const indent = '  ';
+    const indentWidth = visibleWidth(indent);
+    const titleColor = isSelected ? colors.primary : colors.text;
+    const titleStyle = isSelected ? chalk.hex(titleColor).bold : chalk.hex(titleColor);
+
+    const time = formatRelativeTime(session.updated_at);
+    const badge = isCurrent ? CURRENT_BADGE : '';
+    const rawTitle = (session.title ?? session.id).trim() || session.id;
+    const titleSource = formatSessionLabel({ title: rawTitle, metadata: session.metadata });
+
+    // Inline trailing parts after the title: "<title>  <time>  (current)".
+    const trailingParts = [time, badge].filter((p) => p.length > 0);
+    const trailingText = trailingParts.length > 0 ? '  ' + trailingParts.join('  ') : '';
+    const trailingWidth = visibleWidth(trailingText);
+    const headerPrefixWidth = visibleWidth(pointer) + 1; // pointer + space
+    const titleBudget = Math.max(8, width - headerPrefixWidth - trailingWidth);
+    const shownTitle = truncateToWidth(singleLine(titleSource), titleBudget, ELLIPSIS);
+
+    let header = chalk.hex(isSelected ? colors.primary : colors.textDim)(pointer + ' ');
+    header += titleStyle(shownTitle);
+    if (time.length > 0) header += '  ' + chalk.hex(colors.textDim)(time);
+    if (badge.length > 0) header += '  ' + chalk.hex(colors.success)(badge);
+    const card: string[] = [header];
+
+    // Session id is rendered in full (no truncation). The directory wraps to
+    // its own line if it would push past the terminal edge.
+    const fullId = session.id;
+    const idWidth = visibleWidth(fullId);
+    const metaGap = '   ';
+    const metaGapWidth = visibleWidth(metaGap);
+    const idLineWidth = indentWidth + idWidth;
+    const aliasedDir = homeAlias(session.work_dir);
+    const dirWidth = visibleWidth(aliasedDir);
+
+    if (idLineWidth + metaGapWidth + dirWidth <= width) {
+      card.push(
+        indent +
+          chalk.hex(colors.textMuted)(fullId) +
+          chalk.hex(colors.textDim)(metaGap) +
+          chalk.hex(colors.textMuted)(aliasedDir),
+      );
+    } else {
+      // Not enough room for both on one line — keep the id intact and put the
+      // directory on the next line (left-truncated only if it still doesn't fit).
+      card.push(
+        indent +
+          chalk.hex(colors.textMuted)(
+            truncateToWidth(fullId, Math.max(idWidth, width - indentWidth), ELLIPSIS),
+          ),
+      );
+      const dirBudget = Math.max(8, width - indentWidth);
+      const dir = truncatePathLeft(aliasedDir, dirBudget);
+      card.push(indent + chalk.hex(colors.textMuted)(dir));
+    }
+
+    const rawPrompt = session.last_prompt?.trim();
+    if (rawPrompt && rawPrompt.length > 0) {
+      const promptMarker = '› ';
+      const promptMarkerWidth = visibleWidth(promptMarker);
+      const promptBudget = Math.max(8, width - indentWidth - promptMarkerWidth);
+      const promptText = truncateToWidth(singleLine(rawPrompt), promptBudget, ELLIPSIS);
+      const promptLine = indent + chalk.hex(colors.textDim)(promptMarker + promptText);
+      card.push(promptLine);
+    }
+
+    return card;
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/settings-selector.ts b/apps/kimi-code/src/tui/components/dialogs/settings-selector.ts
new file mode 100644
index 000000000..fb224345b
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/settings-selector.ts
@@ -0,0 +1,63 @@
+import { ChoicePickerComponent, type ChoiceOption } from './choice-picker';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+
+export type SettingsSelection = 'model' | 'theme' | 'editor' | 'permission' | 'usage';
+
+const SETTINGS_OPTIONS: readonly ChoiceOption[] = [
+  {
+    value: 'model',
+    label: 'Model',
+    description: 'Switch the active model and thinking mode.',
+  },
+  {
+    value: 'permission',
+    label: 'Permission',
+    description: 'Choose how tool actions are approved.',
+  },
+  {
+    value: 'theme',
+    label: 'Theme',
+    description: 'Change the terminal UI theme.',
+  },
+  {
+    value: 'editor',
+    label: 'Editor',
+    description: 'Set the external editor command.',
+  },
+  {
+    value: 'usage',
+    label: 'Usage',
+    description: 'Show session tokens, context window, and plan quotas.',
+  },
+];
+
+function isSettingsSelection(value: string): value is SettingsSelection {
+  return (
+    value === 'model' ||
+    value === 'theme' ||
+    value === 'editor' ||
+    value === 'permission' ||
+    value === 'usage'
+  );
+}
+
+export interface SettingsSelectorOptions {
+  readonly colors: ColorPalette;
+  readonly onSelect: (value: SettingsSelection) => void;
+  readonly onCancel: () => void;
+}
+
+export class SettingsSelectorComponent extends ChoicePickerComponent {
+  constructor(opts: SettingsSelectorOptions) {
+    super({
+      title: 'Settings',
+      options: [...SETTINGS_OPTIONS],
+      colors: opts.colors,
+      onSelect: (value) => {
+        if (isSettingsSelection(value)) opts.onSelect(value);
+      },
+      onCancel: opts.onCancel,
+    });
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/task-output-viewer.ts b/apps/kimi-code/src/tui/components/dialogs/task-output-viewer.ts
new file mode 100644
index 000000000..0f1fa04b7
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/task-output-viewer.ts
@@ -0,0 +1,261 @@
+/**
+ * TaskOutputViewer — full-screen pi-tui rendered output viewer for
+ * a single background task. Replaces the previous "shell out to less"
+ * approach so the experience stays inside the TUI: same colors, same
+ * fonts, same redraw cycle, no alt-screen flip-flop.
+ *
+ * Mounted by `kimi-tui.ts` via nested container swap on top of the
+ * TasksBrowserApp. Snapshot view (no live tail) — content is fetched
+ * once when the viewer opens.
+ */
+
+import {
+  Container,
+  Key,
+  matchesKey,
+  type Terminal,
+  truncateToWidth,
+  visibleWidth,
+  type Focusable,
+} from '@earendil-works/pi-tui';
+import type { BackgroundTaskInfo, BackgroundTaskStatus } from '@moonshot-ai/kimi-code-sdk';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '@/tui/theme/colors';
+import { printableChar } from '@/tui/utils/printable-key';
+
+const ELLIPSIS = '…';
+
+export interface TaskOutputViewerProps {
+  readonly taskId: string;
+  readonly info: BackgroundTaskInfo | undefined;
+  readonly output: string;
+  readonly colors: ColorPalette;
+  readonly onClose: () => void;
+}
+
+const STATUS_LABEL: Record<BackgroundTaskStatus, string> = {
+  running: 'running',
+  awaiting_approval: 'awaiting',
+  completed: 'completed',
+  failed: 'failed',
+  killed: 'killed',
+  lost: 'lost',
+};
+
+function statusColor(colors: ColorPalette, status: BackgroundTaskStatus): string {
+  switch (status) {
+    case 'running':
+      return colors.success;
+    case 'awaiting_approval':
+      return colors.warning;
+    case 'completed':
+      return colors.textMuted;
+    case 'failed':
+    case 'killed':
+    case 'lost':
+      return colors.error;
+  }
+}
+
+function padToWidth(line: string, width: number): string {
+  const w = visibleWidth(line);
+  if (w === width) return line;
+  if (w > width) return truncateToWidth(line, width, ELLIPSIS);
+  return line + ' '.repeat(width - w);
+}
+
+function fitExactly(line: string, width: number): string {
+  let s = line;
+  if (visibleWidth(s) > width) s = truncateToWidth(s, width, ELLIPSIS);
+  return padToWidth(s, width);
+}
+
+export class TaskOutputViewer extends Container implements Focusable {
+  focused = false;
+
+  private props: TaskOutputViewerProps;
+  private readonly terminal: Terminal;
+  /** Output split on '\n'. Replaced on `setProps` when `output` changes. */
+  private lines: string[];
+  /** Index of the topmost visible line. */
+  private scrollTop = 0;
+
+  constructor(props: TaskOutputViewerProps, terminal: Terminal) {
+    super();
+    this.props = props;
+    this.terminal = terminal;
+    this.lines = this.splitOutput(props.output);
+  }
+
+  /**
+   * Update viewer props. When `output` grows (the watched task wrote
+   * new content), follow the tail like `less +F` if the user is parked
+   * at the bottom; otherwise keep the user's current scroll position
+   * so they can read history without being yanked around.
+   */
+  setProps(next: TaskOutputViewerProps): void {
+    const previousOutput = this.props.output;
+    const wasAtBottom = this.scrollTop >= this.maxScroll();
+    this.props = next;
+    if (next.output !== previousOutput) {
+      this.lines = this.splitOutput(next.output);
+      if (wasAtBottom) this.scrollTop = this.maxScroll();
+      else this.scrollTop = Math.min(this.scrollTop, this.maxScroll());
+    }
+    this.invalidate();
+  }
+
+  private splitOutput(output: string): string[] {
+    return (output.length > 0 ? output : '[no output captured]').split('\n');
+  }
+
+  // ── input ──────────────────────────────────────────────────────────
+
+  handleInput(data: string): void {
+    const visible = this.viewableRows();
+    const k = printableChar(data);
+
+    if (matchesKey(data, Key.escape) || k === 'q' || k === 'Q') {
+      this.props.onClose();
+      return;
+    }
+    if (matchesKey(data, Key.up) || k === 'k') {
+      this.scrollBy(-1);
+      return;
+    }
+    if (matchesKey(data, Key.down) || k === 'j') {
+      this.scrollBy(1);
+      return;
+    }
+    if (matchesKey(data, Key.pageUp) || k === ' ' || data === '\u0002' /* C-b */) {
+      this.scrollBy(-Math.max(1, visible - 1));
+      return;
+    }
+    if (matchesKey(data, Key.pageDown) || data === '\u0006' /* C-f */) {
+      this.scrollBy(Math.max(1, visible - 1));
+      return;
+    }
+    if (matchesKey(data, Key.home) || k === 'g') {
+      this.scrollTo(0);
+      return;
+    }
+    if (matchesKey(data, Key.end) || k === 'G') {
+      this.scrollTo(this.maxScroll());
+      return;
+    }
+  }
+
+  private scrollBy(delta: number): void {
+    this.scrollTo(this.scrollTop + delta);
+  }
+
+  private scrollTo(target: number): void {
+    this.scrollTop = Math.max(0, Math.min(target, this.maxScroll()));
+    this.invalidate();
+  }
+
+  private maxScroll(): number {
+    return Math.max(0, this.lines.length - this.viewableRows());
+  }
+
+  /**
+   * Number of content rows visible inside the body frame: total terminal
+   * rows minus header(1) + footer(1) + top border(1) + bottom border(1).
+   */
+  private viewableRows(): number {
+    return Math.max(1, this.terminal.rows - 4);
+  }
+
+  // ── render ─────────────────────────────────────────────────────────
+
+  override render(width: number): string[] {
+    const rows = Math.max(3, this.terminal.rows);
+    const bodyHeight = rows - 2;
+
+    const header = this.renderHeader(width);
+    const body = this.renderBody(width, bodyHeight);
+    const footer = this.renderFooter(width, bodyHeight);
+
+    const out: string[] = [header];
+    for (const line of body) out.push(line);
+    out.push(footer);
+    return out;
+  }
+
+  private renderHeader(width: number): string {
+    const colors = this.props.colors;
+    const title = chalk.hex(colors.primary).bold(' Task output ');
+    const id = chalk.hex(colors.text).bold(this.props.taskId);
+    const info = this.props.info;
+    const segments: string[] = [];
+    if (info !== undefined) {
+      segments.push(chalk.hex(statusColor(colors, info.status))(STATUS_LABEL[info.status]));
+      if (info.exitCode !== null && info.exitCode !== undefined) {
+        segments.push(chalk.hex(colors.textMuted)(`exit ${String(info.exitCode)}`));
+      }
+      if (info.description && info.description.length > 0) {
+        segments.push(chalk.hex(colors.textMuted)(info.description));
+      }
+    }
+    const composed = title + id + (segments.length > 0 ? '  ' + segments.join('  ') : '');
+    return fitExactly(composed, width);
+  }
+
+  private renderBody(width: number, bodyHeight: number): string[] {
+    const colors = this.props.colors;
+    const stroke = colors.primary;
+
+    // Reserve 1 col for left/right border each, 1 col for left padding.
+    const innerWidth = Math.max(1, width - 4);
+
+    // Re-clamp scroll in case the terminal got resized smaller.
+    const max = this.maxScroll();
+    if (this.scrollTop > max) this.scrollTop = max;
+    if (this.scrollTop < 0) this.scrollTop = 0;
+
+    const viewRows = bodyHeight - 2; // inside top + bottom border
+    const top = chalk.hex(stroke)('┌' + '─'.repeat(Math.max(0, width - 2)) + '┐');
+    const bottom = chalk.hex(stroke)('└' + '─'.repeat(Math.max(0, width - 2)) + '┘');
+
+    const out: string[] = [top];
+    for (let i = 0; i < viewRows; i++) {
+      const lineIndex = this.scrollTop + i;
+      const raw = this.lines[lineIndex] ?? '';
+      const inner = fitExactly(chalk.hex(colors.text)(raw), innerWidth);
+      out.push(chalk.hex(stroke)('│ ') + inner + chalk.hex(stroke)(' │'));
+    }
+    out.push(bottom);
+    return out;
+  }
+
+  private renderFooter(width: number, bodyHeight: number): string {
+    const colors = this.props.colors;
+    const key = (text: string): string => chalk.hex(colors.primary).bold(text);
+    const dim = (text: string): string => chalk.hex(colors.textMuted)(text);
+
+    const total = this.lines.length;
+    const viewRows = Math.max(1, bodyHeight - 2);
+    const maxScroll = Math.max(0, total - viewRows);
+    const percent =
+      maxScroll === 0 ? 100 : Math.round((this.scrollTop / maxScroll) * 100);
+    const lineFrom = this.scrollTop + 1;
+    const lineTo = Math.min(total, this.scrollTop + viewRows);
+
+    const position = chalk.hex(colors.textMuted)(
+      ` ${String(lineFrom)}-${String(lineTo)} / ${String(total)} (${String(percent)}%) `,
+    );
+    const keys =
+      `${key('↑↓')} ${dim('line')}  ` +
+      `${key('PgUp/PgDn')} ${dim('page')}  ` +
+      `${key('g/G')} ${dim('top/bot')}  ` +
+      `${key('Q/Esc')} ${dim('back')}`;
+    const left = ` ${keys}`;
+    const leftW = visibleWidth(left);
+    const rightW = visibleWidth(position);
+    if (leftW + 2 + rightW <= width) {
+      return left + ' '.repeat(width - leftW - rightW) + position;
+    }
+    return fitExactly(left, width);
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/tasks-browser.ts b/apps/kimi-code/src/tui/components/dialogs/tasks-browser.ts
new file mode 100644
index 000000000..8634e045d
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/tasks-browser.ts
@@ -0,0 +1,603 @@
+/**
+ * TasksBrowserApp — full-screen alt-screen takeover for browsing
+ * background tasks. Three-pane layout (left task list, right top
+ * detail, right bottom preview output) framed by a header row and
+ * footer key hint.
+ *
+ * Mounted by `kimi-tui.ts` via container swap rather than `showOverlay`
+ * — the main TUI's children are saved, cleared, and this component is
+ * added as the sole child so it covers the entire screen. The
+ * controller restores the children when the user exits.
+ *
+ * Data (tasks list, tail output) flows in via `setProps`; user actions
+ * fire the `on*` callbacks back to the controller.
+ */
+
+import {
+  Container,
+  Key,
+  matchesKey,
+  type Terminal,
+  truncateToWidth,
+  visibleWidth,
+  type Focusable,
+} from '@earendil-works/pi-tui';
+import type { BackgroundTaskInfo, BackgroundTaskStatus } from '@moonshot-ai/kimi-code-sdk';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '@/tui/theme/colors';
+import { printableChar } from '@/tui/utils/printable-key';
+
+const ELLIPSIS = '…';
+
+export type TasksFilter = 'all' | 'active';
+
+export interface TasksBrowserProps {
+  readonly tasks: readonly BackgroundTaskInfo[];
+  readonly filter: TasksFilter;
+  readonly selectedTaskId: string | undefined;
+  readonly tailOutput: string | undefined;
+  readonly tailLoading: boolean;
+  readonly flashMessage: string | undefined;
+  readonly colors: ColorPalette;
+  readonly onSelect: (taskId: string) => void;
+  readonly onToggleFilter: () => void;
+  readonly onRefresh: () => void;
+  readonly onCancel: () => void;
+  /** Fired when the user confirms a stop request via the inline `y` prompt. */
+  readonly onStopConfirmed: (taskId: string) => void;
+  /** Fired when the user presses Enter or O on a selected task. */
+  readonly onOpenOutput: (taskId: string) => void;
+  /** Fired when stop is requested on a task that cannot be stopped. */
+  readonly onStopIgnored?: (taskId: string, reason: 'terminal') => void;
+}
+
+const STATUS_LABEL: Record<BackgroundTaskStatus, string> = {
+  running: 'running',
+  awaiting_approval: 'awaiting',
+  completed: 'completed',
+  failed: 'failed',
+  killed: 'killed',
+  lost: 'lost',
+};
+
+/** Auto-cancel the inline stop confirmation after this many ms. */
+const STOP_CONFIRM_TIMEOUT_MS = 5_000;
+
+/** Minimum dimensions before we just print a "too small" message. */
+const MIN_WIDTH = 48;
+const MIN_HEIGHT = 10;
+
+/** Hard caps so a tiny / huge terminal still gets a sensible left-column width. */
+const LIST_COL_MIN = 28;
+const LIST_COL_MAX = 44;
+const LIST_COL_RATIO = 0.32;
+
+function statusColor(colors: ColorPalette, status: BackgroundTaskStatus): string {
+  switch (status) {
+    case 'running':
+      return colors.success;
+    case 'awaiting_approval':
+      return colors.warning;
+    case 'completed':
+      return colors.textMuted;
+    case 'failed':
+    case 'killed':
+    case 'lost':
+      return colors.error;
+  }
+}
+
+function isTerminal(status: BackgroundTaskStatus): boolean {
+  return (
+    status === 'completed' || status === 'failed' || status === 'killed' || status === 'lost'
+  );
+}
+
+function formatRelativeTime(ts: number | null | undefined): string {
+  if (ts === null || ts === undefined || !Number.isFinite(ts) || ts <= 0) return '';
+  const diffSec = Math.floor(Math.max(0, Date.now() - ts) / 1000);
+  if (diffSec < 60) return 'just now';
+  const minutes = Math.floor(diffSec / 60);
+  if (minutes < 60) return `${String(minutes)}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${String(hours)}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${String(days)}d ago`;
+}
+
+function singleLine(text: string): string {
+  return text.replaceAll(/\s+/g, ' ').trim();
+}
+
+function padToWidth(line: string, width: number): string {
+  const w = visibleWidth(line);
+  if (w === width) return line;
+  if (w > width) return truncateToWidth(line, width, ELLIPSIS);
+  return line + ' '.repeat(width - w);
+}
+
+/** Fit `line` into exactly `width` columns, even after CJK-edge truncation. */
+function fitExactly(line: string, width: number): string {
+  let s = line;
+  if (visibleWidth(s) > width) s = truncateToWidth(s, width, ELLIPSIS);
+  return padToWidth(s, width);
+}
+
+function visibleTasks(
+  tasks: readonly BackgroundTaskInfo[],
+  filter: TasksFilter,
+): BackgroundTaskInfo[] {
+  if (filter === 'all') return [...tasks];
+  return tasks.filter((t) => !isTerminal(t.status));
+}
+
+function compareTasks(a: BackgroundTaskInfo, b: BackgroundTaskInfo): number {
+  const aTerminal = isTerminal(a.status);
+  const bTerminal = isTerminal(b.status);
+  if (aTerminal !== bTerminal) return aTerminal ? 1 : -1;
+  if (!aTerminal) return a.startedAt - b.startedAt;
+  return (b.endedAt ?? b.startedAt) - (a.endedAt ?? a.startedAt);
+}
+
+interface StatusCounts {
+  running: number;
+  awaiting: number;
+  completed: number;
+  terminalFailed: number;
+}
+
+function countByStatus(tasks: readonly BackgroundTaskInfo[]): StatusCounts {
+  const counts: StatusCounts = { running: 0, awaiting: 0, completed: 0, terminalFailed: 0 };
+  for (const t of tasks) {
+    switch (t.status) {
+      case 'running':
+        counts.running += 1;
+        break;
+      case 'awaiting_approval':
+        counts.awaiting += 1;
+        break;
+      case 'completed':
+        counts.completed += 1;
+        break;
+      case 'failed':
+      case 'killed':
+      case 'lost':
+        counts.terminalFailed += 1;
+        break;
+    }
+  }
+  return counts;
+}
+
+export class TasksBrowserApp extends Container implements Focusable {
+  focused = false;
+
+  private props: TasksBrowserProps;
+  private readonly terminal: Terminal;
+  private sortedVisible: BackgroundTaskInfo[];
+  private selectedIndex = 0;
+  private listScroll = 0;
+  private pendingStopTaskId: string | undefined = undefined;
+  private pendingStopTimer: NodeJS.Timeout | undefined = undefined;
+
+  constructor(props: TasksBrowserProps, terminal: Terminal) {
+    super();
+    this.props = props;
+    this.terminal = terminal;
+    this.sortedVisible = visibleTasks(props.tasks, props.filter).toSorted(compareTasks);
+    this.syncSelectionFromProps();
+  }
+
+  setProps(next: TasksBrowserProps): void {
+    this.props = next;
+    this.sortedVisible = visibleTasks(next.tasks, next.filter).toSorted(compareTasks);
+    this.syncSelectionFromProps();
+    if (this.pendingStopTaskId !== undefined) {
+      const task = next.tasks.find((t) => t.taskId === this.pendingStopTaskId);
+      if (task === undefined || isTerminal(task.status)) this.clearPendingStop();
+    }
+    this.invalidate();
+  }
+
+  private syncSelectionFromProps(): void {
+    if (this.sortedVisible.length === 0) {
+      this.selectedIndex = 0;
+      this.listScroll = 0;
+      return;
+    }
+    if (this.props.selectedTaskId !== undefined) {
+      const idx = this.sortedVisible.findIndex((t) => t.taskId === this.props.selectedTaskId);
+      if (idx !== -1) {
+        this.selectedIndex = idx;
+        return;
+      }
+    }
+    if (this.selectedIndex >= this.sortedVisible.length) {
+      this.selectedIndex = this.sortedVisible.length - 1;
+    }
+  }
+
+  private clearPendingStop(): void {
+    this.pendingStopTaskId = undefined;
+    if (this.pendingStopTimer !== undefined) {
+      clearTimeout(this.pendingStopTimer);
+      this.pendingStopTimer = undefined;
+    }
+  }
+
+  private emitSelect(): void {
+    const task = this.sortedVisible[this.selectedIndex];
+    if (task) this.props.onSelect(task.taskId);
+  }
+
+  handleInput(data: string): void {
+    const k = printableChar(data);
+
+    if (this.pendingStopTaskId !== undefined) {
+      if (k === 'y' || k === 'Y') {
+        const taskId = this.pendingStopTaskId;
+        this.clearPendingStop();
+        this.props.onStopConfirmed(taskId);
+        this.invalidate();
+        return;
+      }
+      this.clearPendingStop();
+      this.invalidate();
+      return;
+    }
+
+    if (matchesKey(data, Key.escape) || k === 'q' || k === 'Q') {
+      this.props.onCancel();
+      return;
+    }
+    if (matchesKey(data, Key.up) || k === 'k') {
+      if (this.sortedVisible.length === 0) return;
+      this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+      this.emitSelect();
+      this.invalidate();
+      return;
+    }
+    if (matchesKey(data, Key.down) || k === 'j') {
+      if (this.sortedVisible.length === 0) return;
+      this.selectedIndex = Math.min(this.sortedVisible.length - 1, this.selectedIndex + 1);
+      this.emitSelect();
+      this.invalidate();
+      return;
+    }
+    if (matchesKey(data, Key.tab) || k === '\t') {
+      this.props.onToggleFilter();
+      return;
+    }
+    if (k === 'r' || k === 'R') {
+      this.props.onRefresh();
+      return;
+    }
+    if (k === 's' || k === 'S') {
+      const task = this.sortedVisible[this.selectedIndex];
+      if (task === undefined) return;
+      if (isTerminal(task.status)) {
+        this.props.onStopIgnored?.(task.taskId, 'terminal');
+        return;
+      }
+      this.pendingStopTaskId = task.taskId;
+      this.pendingStopTimer = setTimeout(() => {
+        this.clearPendingStop();
+        this.invalidate();
+      }, STOP_CONFIRM_TIMEOUT_MS);
+      this.invalidate();
+      return;
+    }
+    if (k === 'o' || k === 'O' || matchesKey(data, Key.enter)) {
+      const task = this.sortedVisible[this.selectedIndex];
+      if (task) this.props.onOpenOutput(task.taskId);
+      return;
+    }
+  }
+
+  /**
+   * Render the entire screen as `terminal.rows` lines of `width` cols.
+   * Layout: header(1) + body(rows-2) + footer(1).
+   */
+  override render(width: number): string[] {
+    const rows = Math.max(1, this.terminal.rows);
+    if (width < MIN_WIDTH || rows < MIN_HEIGHT) {
+      return this.renderTooSmall(width, rows);
+    }
+
+    const header = this.renderHeader(width);
+    const footer = this.renderFooter(width);
+    const bodyHeight = rows - 2;
+
+    const listWidth = Math.max(
+      LIST_COL_MIN,
+      Math.min(LIST_COL_MAX, Math.floor(width * LIST_COL_RATIO)),
+    );
+    const rightWidth = width - listWidth;
+
+    const listFrame = this.renderListFrame(listWidth, bodyHeight);
+    const rightFrames = this.renderRightStack(rightWidth, bodyHeight);
+
+    const lines: string[] = [header];
+    for (let i = 0; i < bodyHeight; i++) {
+      lines.push((listFrame[i] ?? ' '.repeat(listWidth)) + (rightFrames[i] ?? ' '.repeat(rightWidth)));
+    }
+    lines.push(footer);
+    return lines;
+  }
+
+  // ── header / footer ──────────────────────────────────────────────────
+
+  private renderHeader(width: number): string {
+    const colors = this.props.colors;
+    const title = chalk.hex(colors.primary).bold(' TASK BROWSER ');
+    const filterText = chalk.hex(colors.textMuted)(
+      ` filter=${this.props.filter === 'all' ? 'ALL' : 'ACTIVE'} `,
+    );
+    const counts = countByStatus(this.props.tasks);
+    const countSegments: string[] = [];
+    if (counts.running > 0)
+      countSegments.push(chalk.hex(colors.success)(` ${String(counts.running)} running `));
+    if (counts.awaiting > 0)
+      countSegments.push(chalk.hex(colors.warning)(` ${String(counts.awaiting)} awaiting `));
+    if (counts.completed > 0)
+      countSegments.push(chalk.hex(colors.textDim)(` ${String(counts.completed)} completed `));
+    if (counts.terminalFailed > 0)
+      countSegments.push(
+        chalk.hex(colors.error)(` ${String(counts.terminalFailed)} interrupted `),
+      );
+    const totals = chalk.hex(colors.textMuted)(` ${String(this.props.tasks.length)} total `);
+
+    const composed = title + filterText + countSegments.join('') + totals;
+    return fitExactly(composed, width);
+  }
+
+  private renderFooter(width: number): string {
+    const colors = this.props.colors;
+    const key = (text: string): string => chalk.hex(colors.primary).bold(text);
+    const dim = (text: string): string => chalk.hex(colors.textMuted)(text);
+
+    if (this.pendingStopTaskId !== undefined) {
+      const warn = (text: string): string => chalk.hex(colors.warning).bold(text);
+      const line =
+        ` ${warn('Stop')} ${chalk.hex(colors.text)(this.pendingStopTaskId)}? ` +
+        `${key('Y')} ${dim('confirm')}  ${key('N')} ${dim('cancel')} `;
+      return fitExactly(line, width);
+    }
+
+    const parts = [
+      ` ${key('↑↓')} ${dim('select')}`,
+      `${key('Enter/O')} ${dim('output')}`,
+      `${key('S')} ${dim('stop')}`,
+      `${key('R')} ${dim('refresh')}`,
+      `${key('Tab')} ${dim('filter')}`,
+      `${key('Q/Esc')} ${dim('exit')} `,
+    ];
+    const left = parts.join('  ');
+    const flash = this.props.flashMessage;
+    if (flash !== undefined && flash.length > 0) {
+      const flashStyled = chalk.hex(colors.warning)(` ${flash} `);
+      const total = visibleWidth(left) + visibleWidth(flashStyled);
+      if (total <= width) {
+        return left + ' '.repeat(width - total) + flashStyled;
+      }
+    }
+    return fitExactly(left, width);
+  }
+
+  // ── frame primitive ──────────────────────────────────────────────────
+
+  /**
+   * Render a framed box: `┌─ Title ─┐` top, `│ <content> │` sides, `└─┘`
+   * bottom. Result is exactly `width × height` cells. `content` is a
+   * pre-rendered array of inner-width-sized lines; extra rows are padded.
+   */
+  private renderFrame(
+    title: string,
+    content: readonly string[],
+    width: number,
+    height: number,
+  ): string[] {
+    if (height < 2 || width < 4) {
+      const out: string[] = [];
+      for (let i = 0; i < height; i++) out.push(' '.repeat(width));
+      return out;
+    }
+    const stroke = this.props.colors.primary;
+    const innerWidth = width - 2;
+    const innerHeight = height - 2;
+
+    const titleStyled = chalk.hex(this.props.colors.textStrong).bold(title);
+    const titleWidth = visibleWidth(titleStyled);
+    const titleSegment = `─ ${titleStyled} `;
+    const titleSegmentWidth = visibleWidth(titleSegment);
+    const remainingDashes = Math.max(0, innerWidth - titleSegmentWidth);
+    const topMid =
+      titleWidth > 0 && titleSegmentWidth <= innerWidth
+        ? chalk.hex(stroke)('─ ') +
+          titleStyled +
+          ' ' +
+          chalk.hex(stroke)('─'.repeat(remainingDashes))
+        : chalk.hex(stroke)('─'.repeat(innerWidth));
+    const top = chalk.hex(stroke)('┌') + topMid + chalk.hex(stroke)('┐');
+    const bottom = chalk.hex(stroke)('└' + '─'.repeat(innerWidth) + '┘');
+
+    const lines: string[] = [top];
+    for (let i = 0; i < innerHeight; i++) {
+      const inner = content[i] ?? '';
+      lines.push(chalk.hex(stroke)('│') + fitExactly(inner, innerWidth) + chalk.hex(stroke)('│'));
+    }
+    lines.push(bottom);
+    return lines;
+  }
+
+  // ── left: task list frame ────────────────────────────────────────────
+
+  private renderListFrame(width: number, height: number): string[] {
+    const title = `Tasks [${this.props.filter}]`;
+    const innerHeight = Math.max(0, height - 2);
+
+    if (this.sortedVisible.length === 0) {
+      const empty =
+        this.props.filter === 'active'
+          ? 'No active tasks. Tab = show all.'
+          : 'No background tasks in this session.';
+      const lines: string[] = [chalk.hex(this.props.colors.textMuted)(empty)];
+      while (lines.length < innerHeight) lines.push('');
+      return this.renderFrame(title, lines, width, height);
+    }
+
+    this.adjustScroll(innerHeight);
+    const start = this.listScroll;
+    const window = this.sortedVisible.slice(start, start + innerHeight);
+
+    const innerWidth = width - 2;
+    const lines: string[] = [];
+    for (const [vi, task] of window.entries()) {
+      const index = start + vi;
+      lines.push(this.renderListRow(task, index === this.selectedIndex, innerWidth));
+    }
+    while (lines.length < innerHeight) lines.push('');
+
+    return this.renderFrame(title, lines, width, height);
+  }
+
+  private renderListRow(task: BackgroundTaskInfo, selected: boolean, innerWidth: number): string {
+    const colors = this.props.colors;
+    const pointer = selected ? '> ' : '  ';
+    const pointerStyled = chalk.hex(selected ? colors.primary : colors.textDim)(pointer);
+
+    const idColor = selected ? colors.primary : task.taskId.startsWith('agent-')
+      ? colors.success
+      : colors.accent;
+    const idText = selected
+      ? chalk.hex(idColor).bold(task.taskId)
+      : chalk.hex(idColor)(task.taskId);
+    const idPad = ' '.repeat(Math.max(0, 17 - task.taskId.length));
+
+    const status = STATUS_LABEL[task.status];
+    const statusBadge = chalk.hex(statusColor(colors, task.status))(status);
+
+    const prefix = `${pointerStyled}${idText}${idPad} ${statusBadge}`;
+    const prefixWidth = visibleWidth(prefix);
+    const descBudget = Math.max(0, innerWidth - prefixWidth - 1);
+    if (descBudget < 4) return fitExactly(prefix, innerWidth);
+
+    const description =
+      singleLine(task.description) || singleLine(task.command) || '(no description)';
+    const desc = truncateToWidth(description, descBudget, ELLIPSIS);
+    return fitExactly(`${prefix} ${chalk.hex(colors.text)(desc)}`, innerWidth);
+  }
+
+  private adjustScroll(visibleRows: number): void {
+    if (visibleRows <= 0) {
+      this.listScroll = 0;
+      return;
+    }
+    if (this.selectedIndex < this.listScroll) {
+      this.listScroll = this.selectedIndex;
+    } else if (this.selectedIndex >= this.listScroll + visibleRows) {
+      this.listScroll = this.selectedIndex - visibleRows + 1;
+    }
+    const maxScroll = Math.max(0, this.sortedVisible.length - visibleRows);
+    if (this.listScroll < 0) this.listScroll = 0;
+    if (this.listScroll > maxScroll) this.listScroll = maxScroll;
+  }
+
+  // ── right: detail + preview stack ────────────────────────────────────
+
+  private renderRightStack(width: number, height: number): string[] {
+    // Detail gets ~8 rows (or 40% of body, whichever is larger). Preview
+    // takes the rest. Both rendered as separate frames stacked vertically.
+    const detailHeight = Math.max(8, Math.min(Math.floor(height * 0.4), height - 5));
+    const previewHeight = height - detailHeight;
+    return [
+      ...this.renderDetailFrame(width, detailHeight),
+      ...this.renderPreviewFrame(width, previewHeight),
+    ];
+  }
+
+  private renderDetailFrame(width: number, height: number): string[] {
+    const colors = this.props.colors;
+    const innerHeight = Math.max(0, height - 2);
+    const task = this.sortedVisible[this.selectedIndex];
+    if (task === undefined) {
+      const empty = chalk.hex(colors.textMuted)('Select a task from the list.');
+      const lines: string[] = [empty];
+      while (lines.length < innerHeight) lines.push('');
+      return this.renderFrame('Detail', lines, width, height);
+    }
+
+    const label = (text: string): string => chalk.hex(colors.textMuted)(text.padEnd(14));
+    const value = (text: string): string => chalk.hex(colors.text)(text);
+
+    const lines: string[] = [
+      `${label('Task ID:')}${value(task.taskId)}`,
+      `${label('Status:')}${chalk.hex(statusColor(colors, task.status))(STATUS_LABEL[task.status])}`,
+      `${label('Description:')}${value(singleLine(task.description) || '—')}`,
+    ];
+    if (task.command && task.command !== task.description) {
+      lines.push(`${label('Command:')}${value(singleLine(task.command))}`);
+    }
+    const timing =
+      task.status === 'running' || task.status === 'awaiting_approval'
+        ? `running ${formatRelativeTime(task.startedAt)}`
+        : task.endedAt !== null && task.endedAt !== undefined
+          ? `finished ${formatRelativeTime(task.endedAt)}`
+          : '';
+    if (timing.length > 0) lines.push(`${label('Time:')}${chalk.hex(colors.textMuted)(timing)}`);
+    if (task.pid > 0) lines.push(`${label('Pid:')}${chalk.hex(colors.textMuted)(String(task.pid))}`);
+    if (task.exitCode !== null && task.exitCode !== undefined) {
+      lines.push(`${label('Exit code:')}${chalk.hex(colors.textMuted)(String(task.exitCode))}`);
+    }
+    if (task.stopReason !== undefined && task.stopReason.length > 0) {
+      lines.push(`${label('Stop reason:')}${chalk.hex(colors.textMuted)(task.stopReason)}`);
+    }
+    if (task.timedOut === true) {
+      lines.push(`${label('Timed out:')}${chalk.hex(colors.warning)('yes')}`);
+    }
+    if (task.approvalReason !== undefined && task.approvalReason.length > 0) {
+      lines.push(
+        `${label('Awaiting:')}${chalk.hex(colors.warning)(singleLine(task.approvalReason))}`,
+      );
+    }
+
+    while (lines.length < innerHeight) lines.push('');
+    return this.renderFrame('Detail', lines, width, height);
+  }
+
+  private renderPreviewFrame(width: number, height: number): string[] {
+    const colors = this.props.colors;
+    const innerHeight = Math.max(0, height - 2);
+    const task = this.sortedVisible[this.selectedIndex];
+    if (task === undefined) {
+      const lines: string[] = [chalk.hex(colors.textMuted)('No task selected.')];
+      while (lines.length < innerHeight) lines.push('');
+      return this.renderFrame('Preview Output', lines, width, height);
+    }
+
+    let body: string;
+    if (this.props.tailLoading) body = '[loading…]';
+    else if (this.props.tailOutput === undefined || this.props.tailOutput.length === 0)
+      body = '[no output captured]';
+    else body = this.props.tailOutput;
+
+    const rawLines = body.split('\n');
+    const tailLines = rawLines.slice(-innerHeight);
+    const styled = tailLines.map((line) => chalk.hex(colors.textDim)(line));
+    while (styled.length < innerHeight) styled.push('');
+    return this.renderFrame('Preview Output', styled, width, height);
+  }
+
+  // ── too-small fallback ──────────────────────────────────────────────
+
+  private renderTooSmall(width: number, rows: number): string[] {
+    const lines: string[] = [];
+    const msg = chalk.hex(this.props.colors.error)(
+      `Terminal too small (need ≥ ${String(MIN_WIDTH)} × ${String(MIN_HEIGHT)})`,
+    );
+    lines.push(fitExactly(msg, width));
+    for (let i = 1; i < rows; i++) lines.push(' '.repeat(width));
+    return lines;
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/dialogs/theme-selector.ts b/apps/kimi-code/src/tui/components/dialogs/theme-selector.ts
new file mode 100644
index 000000000..8d6381c61
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/dialogs/theme-selector.ts
@@ -0,0 +1,36 @@
+import { ChoicePickerComponent, type ChoiceOption } from './choice-picker';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+import type { Theme } from '#/tui/theme/index';
+
+const THEME_OPTIONS: readonly ChoiceOption[] = [
+  { value: 'auto', label: 'Auto (match terminal)' },
+  { value: 'dark', label: 'Dark' },
+  { value: 'light', label: 'Light' },
+];
+
+function isThemeChoice(value: string): value is Theme {
+  return value === 'auto' || value === 'dark' || value === 'light';
+}
+
+export interface ThemeSelectorOptions {
+  readonly currentValue: Theme;
+  readonly colors: ColorPalette;
+  readonly onSelect: (theme: Theme) => void;
+  readonly onCancel: () => void;
+}
+
+export class ThemeSelectorComponent extends ChoicePickerComponent {
+  constructor(opts: ThemeSelectorOptions) {
+    super({
+      title: 'Select theme',
+      options: [...THEME_OPTIONS],
+      currentValue: opts.currentValue,
+      colors: opts.colors,
+      onSelect: (value) => {
+        if (isThemeChoice(value)) opts.onSelect(value);
+      },
+      onCancel: opts.onCancel,
+    });
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/editor/custom-editor.ts b/apps/kimi-code/src/tui/components/editor/custom-editor.ts
new file mode 100644
index 000000000..8450d37e4
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/editor/custom-editor.ts
@@ -0,0 +1,362 @@
+/**
+ * Custom editor extending pi-tui Editor with app-level keybindings.
+ */
+
+import { Editor, isKeyRelease, matchesKey, Key, type TUI } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+import { createEditorTheme } from '#/tui/theme/pi-tui-theme';
+
+// oxlint-disable-next-line no-control-regex -- ESC (\x1b) is required to match ANSI SGR escape sequences
+const ANSI_SGR = /\u001B\[[0-9;]*m/g;
+
+// Kitty keyboard protocol CSI-u sequence: ESC [ keycode ; modifier[:eventType] u.
+// We intentionally match only the simple two-field form — enough to rewrite
+// `ctrl+<LETTER>` with caps_lock into `ctrl+<letter>` without caps_lock.
+// oxlint-disable-next-line no-control-regex -- ESC (\x1b) is required to match CSI
+const KITTY_CSI_U = /^\u001B\[(\d+);(\d+)((?::\d+)*)u$/;
+// Kitty modifier bit layout: shift=1, alt=2, ctrl=4, super=8, hyper=16,
+// meta=32, caps_lock=64, num_lock=128. Reported value is `mask + 1`.
+const CAPS_LOCK_BIT = 64;
+const CTRL_BIT = 4;
+const SHIFT_BIT = 1;
+
+interface AutocompleteInternals {
+  cancelAutocomplete(): void;
+  readonly autocompleteAbort?: AbortController;
+  readonly autocompleteDebounceTimer?: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Workaround for a pi-tui bug that surfaces when Kitty keyboard protocol
+ * is active AND caps_lock is on. In that state terminals emit, e.g.,
+ * `ESC[68;69u` for ctrl+d (codepoint=68=`D`, modifier=ctrl|caps_lock).
+ * pi-tui's `matchesKittySequence` masks `caps_lock` out of the *modifier*
+ * but leaves the *codepoint* capitalised, so `matchesKey(data, "ctrl+d")`
+ * (which expects codepoint=100=`d`) fails and every ctrl-shortcut is
+ * silently dropped.
+ *
+ * We rewrite the sequence back to its unlocked form before dispatching,
+ * but only when ctrl is held and shift is not — i.e. exactly the
+ * `ctrl+<letter>` case. Plain uppercase (caps_lock only, no ctrl) and
+ * explicit ctrl+shift+<letter> are left alone.
+ */
+export function normalizeCapsLockedCtrl(data: string): string {
+  const m = data.match(KITTY_CSI_U);
+  if (m === null) return data;
+  const codepoint = Number(m[1]);
+  const modifierPlus1 = Number(m[2]);
+  const tail = m[3] ?? '';
+  if (!Number.isFinite(codepoint) || !Number.isFinite(modifierPlus1)) return data;
+  const modifier = modifierPlus1 - 1;
+  if ((modifier & CAPS_LOCK_BIT) === 0) return data;
+  if ((modifier & CTRL_BIT) === 0) return data;
+  if ((modifier & SHIFT_BIT) !== 0) return data;
+  if (codepoint < 65 || codepoint > 90) return data;
+  const loweredCodepoint = codepoint + 32;
+  const strippedModifier = (modifier & ~CAPS_LOCK_BIT) + 1;
+  return `\u001B[${String(loweredCodepoint)};${String(strippedModifier)}${tail}u`;
+}
+
+/** Convert a visible-char index (ANSI-stripped) back to an index into the raw ANSI-bearing string. */
+function mapVisibleIdxToRaw(line: string, visibleIdx: number): number {
+  let visibleCount = 0;
+  let i = 0;
+  const re = new RegExp(ANSI_SGR.source, 'y');
+  while (i < line.length && visibleCount < visibleIdx) {
+    re.lastIndex = i;
+    const m = re.exec(line);
+    if (m !== null && m.index === i) {
+      i += m[0].length;
+    } else {
+      visibleCount++;
+      i++;
+    }
+  }
+  return i;
+}
+
+function stripSgr(s: string): string {
+  return s.replace(ANSI_SGR, '');
+}
+
+function isNewlineShortcut(data: string): boolean {
+  return data === '\n' || data === '\u001B\r' || data === '\u001B[13;2~';
+}
+
+export class CustomEditor extends Editor {
+  public onEscape?: () => void;
+  public onCtrlD?: () => void;
+  public onCtrlC?: () => void;
+  public onToggleToolExpand?: () => void;
+  // Returns true when a plan card actually handled the toggle. When it
+  // returns false (no plan in the transcript) the keystroke falls through
+  // to pi-tui's default ctrl+e binding (move cursor to end of line).
+  public onTogglePlanExpand?: () => boolean;
+  public onOpenExternalEditor?: () => void;
+  public onCtrlS?: () => void;
+  public onUndo?: () => void;
+  public onInsertNewline?: () => void;
+  public onTextPaste?: () => void;
+  /**
+   * Called when ↑ is pressed in an empty editor. Return `true` to consume
+   * the key (e.g. recalled a queued message); return `false` to fall
+   * through so pi-tui's built-in history navigation runs.
+   */
+  public onUpArrowEmpty?: () => boolean;
+  public onShiftTab?: () => void;
+  /**
+   * Called when the user triggers "paste image" (Ctrl-V on Unix,
+   * Alt-V on Windows — Ctrl-V is terminal-reserved there). Return
+   * `true` to consume the key (image was read and handled); return
+   * `false` to let the key fall through to the normal paste path.
+   * The callback may be async; pi-tui awaits it before dispatching
+   * the next keystroke.
+   */
+  public onPasteImage?: () => Promise<boolean>;
+
+  /**
+   * `colors` is the live `ColorPalette` reference — the host mutates it
+   * in place on theme switch (`Object.assign(state.theme.colors, ...)`), so
+   * reading `this.colors.<token>` at render time always sees the
+   * current theme without any setter plumbing. The `EditorTheme` that
+   * pi-tui's `Editor` requires is derived from the same palette, and
+   * `paddingX: 2` reserves the two leading columns where `render()`
+   * paints the terminal-style `> ` prompt — both are implementation
+   * details, not caller knobs.
+   */
+  constructor(
+    tui: TUI,
+    private readonly colors: ColorPalette,
+  ) {
+    // paddingX: 4 reserves column 0 for the left vertical border (│),
+    // column 1 as a single space between border and prompt, column 2 for
+    // the `>` prompt token, and column 3 as the space between prompt and
+    // content. The right side mirrors with 3 padding columns and the right
+    // border at the last column.
+    super(tui, createEditorTheme(colors), { paddingX: 4 });
+  }
+
+  private hasAutocompleteActivity(): boolean {
+    const autocomplete = this as unknown as AutocompleteInternals;
+    return (
+      this.isShowingAutocomplete() ||
+      autocomplete.autocompleteAbort !== undefined ||
+      autocomplete.autocompleteDebounceTimer !== undefined
+    );
+  }
+
+  private cancelAutocompleteActivity(): void {
+    // pi-tui exposes `isShowingAutocomplete()` but keeps cancellation private.
+    // Kimi needs Esc to win over app-level cancel while the slash menu request is active.
+    (this as unknown as AutocompleteInternals).cancelAutocomplete();
+  }
+
+  override render(width: number): string[] {
+    const lines = super.render(width);
+    if (lines.length < 3) return lines;
+    const firstContentIdx = 1;
+    const text = this.getText().trimStart();
+    if (text.startsWith('/')) {
+      // Paint only the FIRST editor content line; multi-line slash commands
+      // are not a thing in practice.
+      const original = lines[firstContentIdx];
+      if (original !== undefined) {
+        const highlighted = highlightFirstSlashToken(original, this.colors.primary);
+        if (highlighted !== undefined) {
+          lines[firstContentIdx] = highlighted;
+        }
+      }
+    }
+    const firstContent = lines[firstContentIdx];
+    if (firstContent !== undefined) {
+      const withPrompt = injectPromptSymbol(firstContent);
+      if (withPrompt !== undefined) {
+        lines[firstContentIdx] = withPrompt;
+      }
+    }
+    // `this.borderColor` is pi-tui's per-render paint function. The host may
+    // overwrite it (e.g. plan-mode / slash-context highlight via
+    // `editor.borderColor = chalk.hex(primary)`), so we route corners and
+    // side bars through the same hook to stay in sync.
+    return wrapWithSideBorders(lines, (s) => this.borderColor(s));
+  }
+
+  override handleInput(data: string): void {
+    const normalized = normalizeCapsLockedCtrl(data);
+    if (isKeyRelease(normalized)) {
+      return;
+    }
+    // Paste image binding — platform-aware:
+    //   Windows terminals reserve Ctrl-V for their own paste handling
+    //   (e.g. Windows Terminal's Ctrl+V shortcut), so we listen for
+    //   Alt-V there. Everywhere else Ctrl-V pastes. When the host
+    //   reports no image available, we fall through to pi-tui's
+    //   normal paste path so text from the clipboard still works.
+    const pasteKey = process.platform === 'win32' ? 'alt+v' : Key.ctrl('v');
+    if (matchesKey(normalized, pasteKey) && this.onPasteImage !== undefined) {
+      const handler = this.onPasteImage;
+      void handler().then((handled) => {
+        if (!handled) {
+          this.onTextPaste?.();
+          // No image on the clipboard — forward the original keystroke
+          // through the base handler so a textual clipboard still works.
+          super.handleInput.call(this, normalized);
+        }
+      });
+      return;
+    }
+
+    if (matchesKey(normalized, Key.ctrl('d'))) {
+      if (this.getText().length === 0) {
+        this.onCtrlD?.();
+        return;
+      }
+    }
+
+    if (matchesKey(normalized, Key.ctrl('c'))) {
+      this.onCtrlC?.();
+      return;
+    }
+
+    if (matchesKey(normalized, Key.ctrl('g'))) {
+      this.onOpenExternalEditor?.();
+      return;
+    }
+
+    if (matchesKey(normalized, Key.ctrl('o'))) {
+      this.onToggleToolExpand?.();
+      return;
+    }
+
+    if (matchesKey(normalized, Key.ctrl('e'))) {
+      if (this.onTogglePlanExpand?.() === true) return;
+      // No plan to toggle — fall through to pi-tui's end-of-line.
+    }
+
+    if (matchesKey(normalized, Key.ctrl('s'))) {
+      this.onCtrlS?.();
+      return;
+    }
+
+    if (matchesKey(normalized, 'shift+tab')) {
+      this.onShiftTab?.();
+      return;
+    }
+
+    if (matchesKey(normalized, Key.ctrl('-'))) {
+      this.onUndo?.();
+    }
+
+    if (isNewlineShortcut(normalized)) {
+      this.onInsertNewline?.();
+    }
+
+    if (matchesKey(normalized, Key.up)) {
+      if (this.getText().length === 0 && this.onUpArrowEmpty) {
+        if (this.onUpArrowEmpty()) return;
+        // fall through to super so Editor's built-in history navigation runs
+      }
+    }
+
+    if (matchesKey(normalized, Key.escape)) {
+      if (this.hasAutocompleteActivity()) {
+        this.cancelAutocompleteActivity();
+        return;
+      }
+      this.onEscape?.();
+      return;
+    }
+
+    super.handleInput(normalized);
+  }
+}
+
+/**
+ * Return a copy of `line` with the first `/token` coloured using `hex`.
+ * `line` may already contain SGR escapes (cursor inverse, etc.); we
+ * locate `/` via visible-index math so ANSI pass-through survives.
+ * Returns `undefined` if no token is found.
+ */
+export function highlightFirstSlashToken(line: string, hex: string): string | undefined {
+  const visible = stripSgr(line);
+  const slashIdx = visible.indexOf('/');
+  if (slashIdx < 0) return undefined;
+  // Guard: only paint when `/` is the first non-whitespace character
+  // on the line (avoids colouring a mid-sentence slash).
+  for (let i = 0; i < slashIdx; i++) {
+    if (visible[i] !== ' ' && visible[i] !== '\t') return undefined;
+  }
+  // Token ends at the next whitespace (or the visible end).
+  let endVisible = slashIdx + 1;
+  while (endVisible < visible.length) {
+    const ch = visible[endVisible];
+    if (ch === ' ' || ch === '\t') break;
+    endVisible++;
+  }
+  const visibleToken = visible.slice(slashIdx, endVisible);
+  if (visibleToken.slice(1).includes('/')) return undefined;
+  const rawStart = mapVisibleIdxToRaw(line, slashIdx);
+  const rawEnd = mapVisibleIdxToRaw(line, endVisible);
+  const before = line.slice(0, rawStart);
+  const token = line.slice(rawStart, rawEnd);
+  const after = line.slice(rawEnd);
+  return before + chalk.hex(hex).bold(token) + after;
+}
+
+/**
+ * Overlay a terminal-style `> ` prompt symbol on the first content line.
+ * Column 0 is reserved for the left vertical border (overlaid later by
+ * wrapWithSideBorders); column 1 is a single-space gap, so the `>` token
+ * lives at column 2 with column 3 separating it from content.
+ * Relies on the editor being configured with `paddingX >= 4` so the line
+ * starts with at least four literal spaces. Emits no SGR so the terminal's
+ * default foreground colour renders the symbol. Returns `undefined` if the
+ * line is too short or doesn't begin with the expected padding.
+ */
+export function injectPromptSymbol(line: string): string | undefined {
+  if (line.length < 4) return undefined;
+  for (let i = 0; i < 4; i++) {
+    if (line[i] !== ' ') return undefined;
+  }
+  return '  > ' + line.slice(4);
+}
+
+/**
+ * Post-process pi-tui's editor output to draw a full box around it.
+ *
+ * pi-tui only renders horizontal top/bottom borders; we wrap them with
+ * `╭╮╰╯` corners and add vertical `│` bars on each row's outer columns.
+ * Horizontal-border rows (those whose first visible char is `─`, including
+ * scroll indicators like `── ↑ N more ──`) are stripped of their existing
+ * SGR and repainted as a single box-drawn span. Content rows keep their
+ * inner SGR intact; only column 0 and the last column are overlaid, and
+ * only if they're literal spaces — that protects the cursor-overflow
+ * case where the rightmost column is an SGR-tagged inverse cursor.
+ */
+export function wrapWithSideBorders(
+  lines: string[],
+  paint: (s: string) => string,
+): string[] {
+  let seenTop = false;
+  return lines.map((line) => {
+    const plain = stripSgr(line);
+    if (plain.length > 0 && plain[0] === '─') {
+      const leftCorner = seenTop ? '╰' : '╭';
+      const rightCorner = seenTop ? '╯' : '╮';
+      seenTop = true;
+      if (plain.length === 1) return paint(leftCorner);
+      const middle = plain.slice(1, -1);
+      return paint(leftCorner + middle + rightCorner);
+    }
+    if (line.length === 0) return line;
+    const firstCh = line[0];
+    const lastCh = line.at(-1);
+    const head = firstCh === ' ' ? paint('│') : (firstCh ?? '');
+    const tail =
+      line.length > 1 && lastCh === ' ' ? paint('│') : (lastCh ?? '');
+    if (line.length === 1) return head;
+    return head + line.slice(1, -1) + tail;
+  });
+}
diff --git a/apps/kimi-code/src/tui/components/editor/file-mention-provider.ts b/apps/kimi-code/src/tui/components/editor/file-mention-provider.ts
new file mode 100644
index 000000000..d2a7d39c1
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/editor/file-mention-provider.ts
@@ -0,0 +1,272 @@
+/**
+ * `@file` autocomplete provider for the input box.
+ *
+ * pi-tui's `CombinedAutocompleteProvider` handles the mechanical parts
+ * (extract `@…` prefix, insert completion with the right quoting). This
+ * wrapper adds kimi-specific ranking + filtering so the default "empty
+ * `@`" list surfaces files the user actually wants, not alphabetical
+ * noise from `.agents/skills/*` et al.
+ *
+ * Sort order — empty query:
+ *   1. recently edited (from `git log --name-only`)
+ *   2. recent fs mtime
+ *   3. basename alphabetical
+ *   (first 15, not 50 — pi-tui's menu height is ~6-10 lines anyway)
+ *
+ * Sort order — non-empty query (strict to fuzzy):
+ *   cat 0: basename starts-with query
+ *   cat 1: basename contains query
+ *   cat 2: fuzzyMatch succeeds on full path
+ *   tie-break within each cat: recency rank → mtime → basename length
+ *   (first 50)
+ *
+ * Filter — dot directories are hidden by default. User can opt in by starting the query
+ * with `.` (e.g. `@.github/`), since those paths rarely need
+ * completion.
+ *
+ * When `fd` is available the inner pi-tui provider owns the `@` branch
+ * verbatim — its fd invocation respects `.gitignore` and is strictly
+ * better than anything we can cheaply reproduce in TS. We only kick in
+ * when `fd` is missing AND we're in a git repo.
+ */
+
+import { basename } from 'node:path';
+
+import {
+  CombinedAutocompleteProvider,
+  fuzzyFilter,
+  fuzzyMatch,
+  type AutocompleteItem,
+  type AutocompleteProvider,
+  type AutocompleteSuggestions,
+  type SlashCommand,
+} from '@earendil-works/pi-tui';
+
+import type { GitLsFilesCache, GitSnapshot } from '#/utils/git/git-ls-files';
+
+const MAX_SUGGESTIONS_WHEN_QUERY = 50;
+const MAX_SUGGESTIONS_WHEN_EMPTY = 15;
+
+// Mirrors pi-tui's PATH_DELIMITERS. Keeping a local copy so @-detection
+// stays aligned even if pi-tui extends its set.
+const PATH_DELIMITERS = new Set([' ', '\t', '"', "'", '=']);
+
+export class FileMentionProvider implements AutocompleteProvider {
+  private readonly inner: CombinedAutocompleteProvider;
+
+  constructor(
+    slashCommands: SlashCommand[],
+    workDir: string,
+    private readonly fdPath: string | null,
+    private readonly gitCache: GitLsFilesCache,
+  ) {
+    this.inner = new CombinedAutocompleteProvider(slashCommands, workDir, fdPath);
+  }
+
+  async getSuggestions(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+    options: { signal: AbortSignal; force?: boolean },
+  ): Promise<AutocompleteSuggestions | null> {
+    const textBeforeCursor = (lines[cursorLine] ?? '').slice(0, cursorCol);
+    const atPrefix = extractAtPrefix(textBeforeCursor);
+
+    // Non-`@` branch (slash commands, `/path`, quoted paths) — pi-tui
+    // already owns the edge cases. No intercept.
+    if (atPrefix === null) {
+      return this.inner.getSuggestions(lines, cursorLine, cursorCol, options);
+    }
+
+    // `fd` available → inner's fuzzy search is strictly better than our
+    // git fallback (fd respects .gitignore AND covers unstaged paths
+    // without a second spawn). Accept its output as-is.
+    if (this.fdPath !== null) {
+      return this.inner.getSuggestions(lines, cursorLine, cursorCol, options);
+    }
+
+    const snapshot = this.gitCache.getSnapshot();
+    if (snapshot === null || snapshot.files.length === 0) {
+      return this.inner.getSuggestions(lines, cursorLine, cursorCol, options);
+    }
+
+    const query = atPrefix.slice(1); // strip leading '@'
+    const includeDotDirs = query.startsWith('.');
+    const candidates = includeDotDirs
+      ? snapshot.files
+      : snapshot.files.filter((p) => !containsDotSegment(p));
+
+    const items =
+      query.length === 0
+        ? rankForEmptyQuery(candidates, snapshot)
+        : rankForQuery(candidates, query, snapshot);
+
+    if (items.length === 0) {
+      // Git cache had nothing useful — fall through to readdir (user
+      // may be typing a path that exists but isn't tracked, e.g. a
+      // freshly created file not yet in the 2s cache).
+      return this.inner.getSuggestions(lines, cursorLine, cursorCol, options);
+    }
+    return { items, prefix: atPrefix };
+  }
+
+  applyCompletion(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+    item: AutocompleteItem,
+    prefix: string,
+  ): { lines: string[]; cursorLine: number; cursorCol: number } {
+    // Reuse pi-tui's insertion logic — it handles `@` prefix, quoted
+    // paths, directory trailing slash. Our item shape matches what
+    // pi-tui produces.
+    return this.inner.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+  }
+}
+
+/**
+ * Return the `@…` token ending at the cursor, or `null` if we're not in
+ * an `@` mention. Mirrors pi-tui's `extractAtPrefix` — the token
+ * boundary is the last PATH_DELIMITER before the cursor, and the token
+ * must start with `@`.
+ */
+function extractAtPrefix(text: string): string | null {
+  let tokenStart = 0;
+  for (let i = text.length - 1; i >= 0; i -= 1) {
+    if (PATH_DELIMITERS.has(text[i] ?? '')) {
+      tokenStart = i + 1;
+      break;
+    }
+  }
+  if (text[tokenStart] !== '@') return null;
+  return text.slice(tokenStart);
+}
+
+/** True when any path segment starts with a dot (e.g. `.github/x.yml`). */
+function containsDotSegment(path: string): boolean {
+  for (const segment of path.split('/')) {
+    if (segment.startsWith('.')) return true;
+  }
+  return false;
+}
+
+/**
+ * Empty-query ranking: stratified by signal strength.
+ *
+ * Layer 1: files touched in the last RECENT_COMMIT_DEPTH commits,
+ *          ordered by how recently. Strongest signal — if the user
+ *          just worked on it, they probably want to mention it.
+ * Layer 2: files with the newest fs mtime (covers uncommitted edits
+ *          and files edited but not yet added to git).
+ * Layer 3: everything else, alphabetical by basename so
+ *          README/package.json-style top-level files bubble up
+ *          relative to deeply-nested alphabetical paths.
+ *
+ * Cap at MAX_SUGGESTIONS_WHEN_EMPTY. Layers fill in order; dedup by
+ * path so a recently-edited file isn't also listed in layer 2.
+ */
+function rankForEmptyQuery(files: readonly string[], snapshot: GitSnapshot): AutocompleteItem[] {
+  const picked = new Set<string>();
+  const result: string[] = [];
+  const cap = MAX_SUGGESTIONS_WHEN_EMPTY;
+  const inFiles = new Set(files);
+
+  // Layer 1 — git log recency.
+  const byRecency = [...snapshot.recencyOrder.entries()]
+    .filter(([path]) => inFiles.has(path))
+    .toSorted((a, b) => a[1] - b[1]);
+  for (const [path] of byRecency) {
+    if (result.length >= cap) break;
+    if (picked.has(path)) continue;
+    picked.add(path);
+    result.push(path);
+  }
+
+  // Layer 2 — fs mtime.
+  if (result.length < cap) {
+    const byMtime = files
+      .filter((p) => !picked.has(p) && snapshot.mtimeByPath.has(p))
+      .toSorted((a, b) => (snapshot.mtimeByPath.get(b) ?? 0) - (snapshot.mtimeByPath.get(a) ?? 0));
+    for (const path of byMtime) {
+      if (result.length >= cap) break;
+      picked.add(path);
+      result.push(path);
+    }
+  }
+
+  // Layer 3 — alphabetical by basename.
+  if (result.length < cap) {
+    const rest = files
+      .filter((p) => !picked.has(p))
+      .toSorted((a, b) => basename(a).localeCompare(basename(b)) || a.localeCompare(b));
+    for (const path of rest) {
+      if (result.length >= cap) break;
+      result.push(path);
+    }
+  }
+
+  return result.map(toItem);
+}
+
+/**
+ * Non-empty-query ranking: three strictness tiers, with recency /
+ * mtime as tie-breakers inside each tier so "the readme you just
+ * edited" beats "a readme deep in a vendor dir".
+ */
+function rankForQuery(
+  files: readonly string[],
+  query: string,
+  snapshot: GitSnapshot,
+): AutocompleteItem[] {
+  const lowerQuery = query.toLowerCase();
+  const scored: Array<{ path: string; cat: number; fuzzyScore: number }> = [];
+  for (const path of files) {
+    const base = basename(path).toLowerCase();
+    if (base.startsWith(lowerQuery)) {
+      scored.push({ path, cat: 0, fuzzyScore: 0 });
+      continue;
+    }
+    if (base.includes(lowerQuery)) {
+      scored.push({ path, cat: 1, fuzzyScore: 0 });
+      continue;
+    }
+    const fuzzy = fuzzyMatch(query, path);
+    if (fuzzy.matches) {
+      scored.push({ path, cat: 2, fuzzyScore: fuzzy.score });
+    }
+  }
+
+  if (scored.length === 0) {
+    // pi-tui's fuzzyFilter is slightly different (token-splitting);
+    // try it as a last-resort safety net.
+    return fuzzyFilter([...files], query, (p) => p)
+      .slice(0, MAX_SUGGESTIONS_WHEN_QUERY)
+      .map(toItem);
+  }
+
+  scored.sort((a, b) => {
+    if (a.cat !== b.cat) return a.cat - b.cat;
+    if (a.cat === 2 && a.fuzzyScore !== b.fuzzyScore) return a.fuzzyScore - b.fuzzyScore;
+    const ra = snapshot.recencyOrder.get(a.path);
+    const rb = snapshot.recencyOrder.get(b.path);
+    if (ra !== undefined && rb !== undefined && ra !== rb) return ra - rb;
+    if (ra !== undefined && rb === undefined) return -1;
+    if (ra === undefined && rb !== undefined) return 1;
+    const ma = snapshot.mtimeByPath.get(a.path) ?? 0;
+    const mb = snapshot.mtimeByPath.get(b.path) ?? 0;
+    if (ma !== mb) return mb - ma;
+    const baseLenDiff = basename(a.path).length - basename(b.path).length;
+    if (baseLenDiff !== 0) return baseLenDiff;
+    return a.path.localeCompare(b.path);
+  });
+
+  return scored.slice(0, MAX_SUGGESTIONS_WHEN_QUERY).map((entry) => toItem(entry.path));
+}
+
+function toItem(path: string): AutocompleteItem {
+  return {
+    value: `@${path}`,
+    label: basename(path),
+    description: path,
+  };
+}
diff --git a/apps/kimi-code/src/tui/components/index.ts b/apps/kimi-code/src/tui/components/index.ts
new file mode 100644
index 000000000..bcff5b2ac
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/index.ts
@@ -0,0 +1,35 @@
+export * from './chrome/device-code-box';
+export * from './chrome/footer';
+export * from './chrome/moon-loader';
+export * from './chrome/todo-panel';
+export * from './chrome/welcome';
+export * from './dialogs/approval-panel';
+export * from './dialogs/choice-picker';
+export * from './dialogs/compaction';
+export * from './dialogs/editor-selector';
+export * from './dialogs/help-panel';
+export * from './dialogs/model-selector';
+export * from './dialogs/permission-selector';
+export * from './dialogs/question-dialog';
+export * from './dialogs/session-picker';
+export * from './dialogs/settings-selector';
+export * from './dialogs/theme-selector';
+export * from './editor/custom-editor';
+export * from './editor/file-mention-provider';
+export * from './media/code-highlight';
+export * from './media/diff-preview';
+export * from './media/image-thumbnail';
+export * from './messages/agent-group';
+export * from './messages/assistant-message';
+export * from './messages/background-agent-status';
+export * from './messages/plan-box';
+export * from './messages/read-group';
+export * from './messages/shell-execution';
+export * from './messages/skill-activation';
+export * from './messages/status-message';
+export * from './messages/thinking';
+export * from './messages/tool-call';
+export * from './messages/usage-panel';
+export * from './messages/user-message';
+export * from './panes/activity-pane';
+export * from './panes/queue-pane';
diff --git a/apps/kimi-code/src/tui/components/media/code-highlight.ts b/apps/kimi-code/src/tui/components/media/code-highlight.ts
new file mode 100644
index 000000000..bfef3d91b
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/media/code-highlight.ts
@@ -0,0 +1,52 @@
+/**
+ * Shared syntax-highlighting helpers for code previews
+ * (tool-call Write/Edit, approval-panel Write content, etc.).
+ */
+
+import { extname } from 'node:path';
+
+import { highlight, supportsLanguage } from 'cli-highlight';
+
+const EXT_LANG_MAP: Record<string, string> = {
+  ts: 'typescript',
+  tsx: 'typescript',
+  js: 'javascript',
+  jsx: 'javascript',
+  py: 'python',
+  rb: 'ruby',
+  rs: 'rust',
+  go: 'go',
+  java: 'java',
+  sh: 'bash',
+  bash: 'bash',
+  zsh: 'bash',
+  json: 'json',
+  yaml: 'yaml',
+  yml: 'yaml',
+  toml: 'toml',
+  md: 'markdown',
+  css: 'css',
+  html: 'html',
+  sql: 'sql',
+  c: 'c',
+  cpp: 'cpp',
+  h: 'c',
+  hpp: 'cpp',
+};
+
+export function langFromPath(filePath: string): string | undefined {
+  const ext = extname(filePath).slice(1).toLowerCase();
+  if (ext.length === 0) return undefined;
+  const lang = EXT_LANG_MAP[ext] ?? ext;
+  return supportsLanguage(lang) ? lang : undefined;
+}
+
+export function highlightLines(code: string, lang: string | undefined): string[] {
+  const normalizedLang = lang?.trim().toLowerCase();
+  if (!normalizedLang || !supportsLanguage(normalizedLang)) return code.split('\n');
+  try {
+    return highlight(code, { language: normalizedLang, ignoreIllegals: true }).split('\n');
+  } catch {
+    return code.split('\n');
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/media/diff-preview.ts b/apps/kimi-code/src/tui/components/media/diff-preview.ts
new file mode 100644
index 000000000..5a978723d
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/media/diff-preview.ts
@@ -0,0 +1,310 @@
+/**
+ * Diff preview rendering as plain ANSI strings.
+ *
+ * Reuses the diff algorithm from approval/DiffPreview.tsx, but outputs
+ * formatted text lines instead of React elements.
+ */
+
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+
+export type DiffLineKind = 'context' | 'add' | 'delete';
+
+interface DiffStyles {
+  add: (s: string) => string;
+  del: (s: string) => string;
+  addBold: (s: string) => string;
+  delBold: (s: string) => string;
+  gutter: (s: string) => string;
+  meta: (s: string) => string;
+}
+
+function makeDiffStyles(colors: ColorPalette): DiffStyles {
+  return {
+    add: (s) => chalk.hex(colors.diffAdded)(s),
+    del: (s) => chalk.hex(colors.diffRemoved)(s),
+    addBold: (s) => chalk.bold.hex(colors.diffAddedStrong)(s),
+    delBold: (s) => chalk.bold.hex(colors.diffRemovedStrong)(s),
+    gutter: (s) => chalk.hex(colors.diffGutter)(s),
+    meta: (s) => chalk.hex(colors.diffMeta)(s),
+  };
+}
+
+export interface DiffLine {
+  kind: DiffLineKind;
+  lineNum: number;
+  code: string;
+}
+
+export function computeDiffLines(
+  oldText: string,
+  newText: string,
+  oldStart: number = 1,
+  newStart: number = 1,
+  isIncomplete: boolean = false,
+): DiffLine[] {
+  const oldLines = oldText ? oldText.split('\n') : [];
+  const newLines = newText ? newText.split('\n') : [];
+  const m = oldLines.length;
+  const n = newLines.length;
+
+  const dp: number[][] = Array.from({ length: m + 1 }, () =>
+    Array.from({ length: n + 1 }, () => 0),
+  );
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      if (oldLines[i - 1] === newLines[j - 1]) {
+        dp[i]![j] = dp[i - 1]![j - 1]! + 1;
+      } else {
+        dp[i]![j] = Math.max(dp[i - 1]![j]!, dp[i]![j - 1]!);
+      }
+    }
+  }
+
+  const reversed: DiffLine[] = [];
+  let i = m;
+  let j = n;
+  while (i > 0 || j > 0) {
+    if (i > 0 && j > 0 && oldLines[i - 1] === newLines[j - 1]) {
+      reversed.push({ kind: 'context', lineNum: newStart + j - 1, code: newLines[j - 1]! });
+      i--;
+      j--;
+    } else if (j > 0 && (i === 0 || dp[i]![j - 1]! >= dp[i - 1]![j]!)) {
+      reversed.push({ kind: 'add', lineNum: newStart + j - 1, code: newLines[j - 1]! });
+      j--;
+    } else {
+      reversed.push({ kind: 'delete', lineNum: oldStart + i - 1, code: oldLines[i - 1]! });
+      i--;
+    }
+  }
+
+  const result: DiffLine[] = [];
+  for (let k = reversed.length - 1; k >= 0; k--) {
+    result.push(reversed[k]!);
+  }
+
+  // While the text is still streaming, suppress trailing delete lines.
+  // They are likely artefacts of newText not having arrived yet rather
+  // than genuine deletions.
+  if (isIncomplete && result.length > 0) {
+    let lastNonDelete = result.length - 1;
+    while (lastNonDelete >= 0 && result[lastNonDelete]!.kind === 'delete') {
+      lastNonDelete--;
+    }
+    if (lastNonDelete >= 0) {
+      result.length = lastNonDelete + 1;
+    } else {
+      // Every line would be shown as deleted; suppress them all so the
+      // UI doesn't flash a wall of red before newText starts arriving.
+      result.length = 0;
+    }
+  }
+
+  return result;
+}
+
+export function renderDiffLines(
+  oldText: string,
+  newText: string,
+  path: string,
+  colors: ColorPalette,
+  isIncomplete: boolean = false,
+  oldStart?: number,
+  newStart?: number,
+  maxLines?: number,
+): string[] {
+  const s = makeDiffStyles(colors);
+  const diffLines = computeDiffLines(oldText, newText, oldStart ?? 1, newStart ?? 1, isIncomplete);
+  const changedLines = diffLines.filter((l) => l.kind !== 'context');
+  const added = changedLines.filter((l) => l.kind === 'add').length;
+  const removed = changedLines.filter((l) => l.kind === 'delete').length;
+
+  const output: string[] = [];
+
+  let header = '';
+  if (added > 0) header += s.addBold(`+${String(added)} `);
+  if (removed > 0) header += s.delBold(`-${String(removed)} `);
+  header += path;
+  output.push(header);
+
+  const shown =
+    maxLines !== undefined && maxLines >= 0 && changedLines.length > maxLines
+      ? changedLines.slice(0, maxLines)
+      : changedLines;
+
+  for (const line of shown) {
+    const marker = line.kind === 'add' ? '+' : '-';
+    const color = line.kind === 'add' ? s.add : s.del;
+    output.push(s.gutter(String(line.lineNum).padStart(4) + ' ') + color(marker + ' ' + line.code));
+  }
+
+  const hidden = changedLines.length - shown.length;
+  if (hidden > 0) {
+    output.push(
+      s.meta(
+        `     … ${String(hidden)} more change${hidden > 1 ? 's' : ''} hidden (ctrl+o to expand)`,
+      ),
+    );
+  }
+
+  return output;
+}
+
+export interface ClusteredDiffOptions {
+  readonly contextLines?: number;
+  readonly maxLines?: number;
+  readonly isIncomplete?: boolean;
+  readonly expandKeyHint?: string;
+}
+
+interface Cluster {
+  readonly start: number;
+  readonly end: number;
+}
+
+function buildClusters(
+  diffLines: DiffLine[],
+  contextLines: number,
+): { clusters: Cluster[]; changedCount: number; addedCount: number; removedCount: number } {
+  const changeIndices: number[] = [];
+  let added = 0;
+  let removed = 0;
+  for (const [i, line] of diffLines.entries()) {
+    if (line.kind === 'add') {
+      added++;
+      changeIndices.push(i);
+    } else if (line.kind === 'delete') {
+      removed++;
+      changeIndices.push(i);
+    }
+  }
+
+  const clusters: Cluster[] = [];
+  if (changeIndices.length === 0) {
+    return { clusters, changedCount: 0, addedCount: added, removedCount: removed };
+  }
+
+  const mergeGap = 2 * contextLines;
+  let groupStart = changeIndices[0]!;
+  let groupEnd = changeIndices[0]!;
+  for (let i = 1; i < changeIndices.length; i++) {
+    const idx = changeIndices[i]!;
+    if (idx - groupEnd <= mergeGap) {
+      groupEnd = idx;
+    } else {
+      clusters.push({
+        start: Math.max(0, groupStart - contextLines),
+        end: Math.min(diffLines.length - 1, groupEnd + contextLines),
+      });
+      groupStart = idx;
+      groupEnd = idx;
+    }
+  }
+  clusters.push({
+    start: Math.max(0, groupStart - contextLines),
+    end: Math.min(diffLines.length - 1, groupEnd + contextLines),
+  });
+
+  return {
+    clusters,
+    changedCount: changeIndices.length,
+    addedCount: added,
+    removedCount: removed,
+  };
+}
+
+function formatDiffRow(line: DiffLine, s: DiffStyles): string {
+  const gutter = s.gutter(String(line.lineNum).padStart(4) + ' ');
+  if (line.kind === 'add') return gutter + s.add('+ ' + line.code);
+  if (line.kind === 'delete') return gutter + s.del('- ' + line.code);
+  return gutter + '  ' + line.code;
+}
+
+/**
+ * Render a diff with surrounding context, eliding unchanged middle
+ * regions between change clusters with a `… N unchanged lines …`
+ * separator. When `maxLines` is set, the body is capped at a cluster
+ * boundary and a `ctrl+o to expand` footer is appended.
+ *
+ * Used by Edit's call preview where we want to show *what changed*
+ * with enough context to read the change, but not the whole file.
+ */
+export function renderDiffLinesClustered(
+  oldText: string,
+  newText: string,
+  path: string,
+  colors: ColorPalette,
+  opts: ClusteredDiffOptions = {},
+): string[] {
+  const s = makeDiffStyles(colors);
+  const contextLines = opts.contextLines ?? 3;
+  const maxLines = opts.maxLines;
+  const diffLines = computeDiffLines(oldText, newText, 1, 1, opts.isIncomplete ?? false);
+  const { clusters, changedCount, addedCount, removedCount } = buildClusters(
+    diffLines,
+    contextLines,
+  );
+
+  const output: string[] = [];
+  let header = '';
+  if (addedCount > 0) header += s.addBold(`+${String(addedCount)} `);
+  if (removedCount > 0) header += s.delBold(`-${String(removedCount)} `);
+  header += path;
+  output.push(header);
+
+  if (clusters.length === 0) return output;
+
+  const cap = maxLines !== undefined && maxLines >= 0 ? maxLines : Number.POSITIVE_INFINITY;
+  let body = 0;
+  let prevEnd = -1;
+  let truncated = false;
+  let shownChanges = 0;
+
+  outer: for (const cluster of clusters) {
+    if (body >= cap) {
+      truncated = true;
+      break;
+    }
+    if (prevEnd >= 0) {
+      const gap = cluster.start - prevEnd - 1;
+      if (gap > 0) {
+        if (body + 1 > cap) {
+          truncated = true;
+          break;
+        }
+        output.push(s.meta(`     … ${String(gap)} unchanged line${gap > 1 ? 's' : ''} …`));
+        body++;
+      }
+    }
+    // Emit cluster rows one at a time; allow mid-cluster truncation so
+    // a single huge cluster (e.g. the whole file replaced inline) still
+    // shows the leading lines instead of degenerating to "N changes
+    // hidden" with no body at all.
+    for (let i = cluster.start; i <= cluster.end; i++) {
+      if (body >= cap) {
+        truncated = true;
+        break outer;
+      }
+      const line = diffLines[i]!;
+      output.push(formatDiffRow(line, s));
+      body++;
+      if (line.kind !== 'context') shownChanges++;
+      prevEnd = i;
+    }
+  }
+
+  if (truncated) {
+    const hidden = changedCount - shownChanges;
+    if (hidden > 0) {
+      const hint = opts.expandKeyHint ?? 'ctrl+o';
+      output.push(
+        s.meta(
+          `     … ${String(hidden)} more change${hidden > 1 ? 's' : ''} hidden (${hint} to expand)`,
+        ),
+      );
+    }
+  }
+
+  return output;
+}
diff --git a/apps/kimi-code/src/tui/components/media/image-thumbnail.ts b/apps/kimi-code/src/tui/components/media/image-thumbnail.ts
new file mode 100644
index 000000000..86253582f
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/media/image-thumbnail.ts
@@ -0,0 +1,55 @@
+/**
+ * Transcript-side rendering of a pasted image.
+ *
+ * On terminals that speak the Kitty graphics protocol or iTerm2 inline
+ * image protocol (detected by pi-tui's `getCapabilities()`), we show
+ * the actual image. Everywhere else we fall back to a one-line text
+ * marker matching the placeholder the user sees in the input box —
+ * this keeps the transcript readable on Terminal.app / Linux default
+ * terminals / `script` recordings without extra chrome.
+ *
+ * Height is capped at ~12 rows so a single screenshot can't monopolize
+ * the viewport; pi-tui handles proportional scaling internally.
+ */
+
+import { Container, Image, Text, type ImageTheme, getCapabilities } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+import type { ImageAttachment } from '#/tui/utils/image-attachment-store';
+
+const MAX_IMAGE_ROWS = 12;
+const MAX_IMAGE_WIDTH = 40;
+
+export class ImageThumbnail extends Container {
+  constructor(attachment: ImageAttachment, colors: ColorPalette) {
+    super();
+
+    const caps = getCapabilities();
+    const supportsInline = caps.images === 'kitty' || caps.images === 'iterm2';
+
+    if (!supportsInline) {
+      // Non-graphic terminal — show the placeholder text in dim cyan so
+      // it's clearly an attachment reference but doesn't shout.
+      this.addChild(new Text(chalk.hex(colors.accent)(attachment.placeholder), 0, 0));
+      return;
+    }
+
+    const theme: ImageTheme = {
+      fallbackColor: (s: string) => chalk.hex(colors.textDim)(s),
+    };
+    const base64 = Buffer.from(attachment.bytes).toString('base64');
+    const image = new Image(
+      base64,
+      attachment.mime,
+      theme,
+      {
+        maxHeightCells: MAX_IMAGE_ROWS,
+        maxWidthCells: MAX_IMAGE_WIDTH,
+        filename: attachment.placeholder,
+      },
+      { widthPx: attachment.width, heightPx: attachment.height },
+    );
+    this.addChild(image);
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/messages/agent-group.ts b/apps/kimi-code/src/tui/components/messages/agent-group.ts
new file mode 100644
index 000000000..593ae9746
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/agent-group.ts
@@ -0,0 +1,240 @@
+/**
+ * AgentGroupComponent renders 2+ Agent tool calls from the same step as one group.
+ *
+ * Design:
+ * - State container: each child Agent keeps its real state in its
+ *   `ToolCallComponent` (subagent meta, phase, sub-tool calls, tokens, text).
+ *   AgentGroup only stores references and does not copy state. Event handlers
+ *   still route through `state.pendingToolComponents.get(parent_tool_call_id)`.
+ * - Subscription: `attach` registers a snapshot listener on each child so the
+ *   group can refresh when child state changes.
+ * - Throttling: normal changes are coalesced into one render every 200ms.
+ *   Phase transitions (spawning -> running -> done/failed) flush immediately.
+ * - Mounting: `KimiTUI` attaches the group to the transcript at the
+ *   right time; the group handles `invalidate` plus `ui.requestRender`.
+ * - Ungrouping is not implemented. Once formed, a group stays grouped.
+ */
+
+import type { TUI } from '@earendil-works/pi-tui';
+import { Container, Spacer, Text } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import { STATUS_BULLET } from '#/tui/constant/symbols';
+import type { ColorPalette } from '#/tui/theme/colors';
+
+import type { ToolCallComponent, ToolCallSubagentSnapshot } from './tool-call';
+
+const THROTTLE_MS = 200;
+
+interface AgentEntry {
+  readonly toolCallId: string;
+  readonly tc: ToolCallComponent;
+}
+
+export class AgentGroupComponent extends Container {
+  private readonly entries: AgentEntry[] = [];
+  private readonly headerText: Text;
+  private readonly bodyContainer: Container;
+  private throttleTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastFlushPhases = new Map<string, ToolCallSubagentSnapshot['phase']>();
+
+  constructor(
+    private readonly colors: ColorPalette,
+    private readonly ui: TUI | undefined,
+  ) {
+    super();
+    this.addChild(new Spacer(1));
+    this.headerText = new Text('', 0, 0);
+    this.addChild(this.headerText);
+    this.bodyContainer = new Container();
+    this.addChild(this.bodyContainer);
+  }
+
+  size(): number {
+    return this.entries.length;
+  }
+
+  /**
+   * Borrows a standalone `ToolCallComponent` into the group as a hidden state
+   * container. Snapshot changes trigger throttled refreshes. Re-attaching the
+   * same toolCallId is a no-op.
+   */
+  attach(toolCallId: string, tc: ToolCallComponent): void {
+    if (this.entries.some((e) => e.toolCallId === toolCallId)) return;
+    this.entries.push({ toolCallId, tc });
+    tc.setSnapshotListener(() => {
+      this.scheduleRender();
+    });
+    this.flushRender();
+  }
+
+  /**
+   * Schedules a repaint. Real phase transitions force an immediate refresh;
+   * other changes such as latestActivity, tokens, or toolCount are throttled.
+   */
+  private scheduleRender(): void {
+    if (this.detectPhaseTransition()) {
+      this.flushRender();
+      return;
+    }
+    if (this.throttleTimer !== null) return;
+    this.throttleTimer = setTimeout(() => {
+      this.throttleTimer = null;
+      this.flushRender();
+    }, THROTTLE_MS);
+  }
+
+  /**
+   * Compares each child's current phase with the phase captured at the last
+   * flush. Any change is treated as a phase transition.
+   */
+  private detectPhaseTransition(): boolean {
+    let changed = false;
+    for (const e of this.entries) {
+      const phase = e.tc.getSubagentSnapshot().phase;
+      if (this.lastFlushPhases.get(e.toolCallId) !== phase) {
+        changed = true;
+        break;
+      }
+    }
+    return changed;
+  }
+
+  private flushRender(): void {
+    if (this.throttleTimer !== null) {
+      clearTimeout(this.throttleTimer);
+      this.throttleTimer = null;
+    }
+
+    const snapshots = this.entries.map((e) => e.tc.getSubagentSnapshot());
+    this.headerText.setText(this.buildHeader(snapshots));
+    this.bodyContainer.clear();
+    snapshots.forEach((snap, idx) => {
+      const isLast = idx === snapshots.length - 1;
+      this.appendLines(snap, isLast);
+    });
+
+    this.lastFlushPhases.clear();
+    this.entries.forEach((entry, i) => {
+      const snap = snapshots[i];
+      if (snap !== undefined) this.lastFlushPhases.set(entry.toolCallId, snap.phase);
+    });
+
+    this.invalidate();
+    this.ui?.requestRender();
+  }
+
+  private buildHeader(snapshots: readonly ToolCallSubagentSnapshot[]): string {
+    const colors = this.colors;
+    const total = snapshots.length;
+    const done = snapshots.filter((s) => s.phase === 'done').length;
+    const failed = snapshots.filter((s) => s.phase === 'failed').length;
+    const finished = done + failed;
+    const allDone = finished === total;
+    const bullet = allDone
+      ? chalk.hex(colors.success)(STATUS_BULLET)
+      : chalk.hex(colors.roleAssistant)(STATUS_BULLET);
+
+    if (allDone) {
+      const types = new Set(snapshots.map((s) => s.agentName).filter((n) => n !== undefined));
+      const headerLabel =
+        types.size === 1
+          ? `${String(total)} ${[...types][0]} agents finished`
+          : `${String(total)} agents finished`;
+      const totalTools = snapshots.reduce((acc, s) => acc + s.toolCount, 0);
+      const totalTokens = snapshots.reduce((acc, s) => acc + s.tokens, 0);
+      const tail = formatHeaderTail(totalTools, totalTokens);
+      return `${bullet}${chalk.hex(colors.primary).bold(headerLabel)}${tail}`;
+    }
+
+    let headerText = `Running ${String(total)} agents`;
+    // Mixed status gets a breakdown so the current state is clear.
+    if (finished > 0) {
+      const running = total - finished;
+      const parts: string[] = [];
+      if (done > 0) parts.push(`${String(done)} done`);
+      if (failed > 0) parts.push(`${String(failed)} failed`);
+      if (running > 0) parts.push(`${String(running)} running`);
+      headerText = `Running ${String(total)} agents (${parts.join(', ')})`;
+    }
+    return `${bullet}${chalk.hex(colors.primary).bold(headerText)}`;
+  }
+
+  private appendLines(snap: ToolCallSubagentSnapshot, isLast: boolean): void {
+    const colors = this.colors;
+    const dim = chalk.dim;
+
+    // First-level branch line.
+    const branch1 = isLast ? '└─' : '├─';
+    const agentType = snap.agentName ?? 'agent';
+    const desc = snap.toolCallDescription || '(no description)';
+    const tail = formatLineTail(snap, colors);
+    const namePart = chalk.hex(colors.primary)(agentType);
+    const descPart = dim(`· ${desc}`);
+    const stats = formatStats(snap);
+    const line1 = `  ${branch1} ${namePart} ${descPart}${stats}${tail}`;
+    this.bodyContainer.addChild(new Text(line1, 0, 0));
+
+    // Second-level line: latest activity, or Error for failures.
+    const branch2 = isLast ? '   ' : '│  ';
+    if (snap.phase === 'failed') {
+      // Show one error line; error messages can be long.
+      const errLine = (snap.errorText ?? 'Failed').split('\n').at(0) ?? 'Failed';
+      const errStr = chalk.hex(colors.error)(`Error: ${errLine}`);
+      this.bodyContainer.addChild(new Text(`  ${branch2}    ${errStr}`, 0, 0));
+      return;
+    }
+    if (snap.phase === 'done' || snap.phase === 'backgrounded') {
+      // Terminal states omit the second line.
+      return;
+    }
+    // Running or not-yet-started agents show latest activity, with a fallback.
+    const activity = snap.latestActivity ?? 'Initializing…';
+    this.bodyContainer.addChild(new Text(`  ${branch2}    ${dim(activity)}`, 0, 0));
+  }
+
+  /** Releases throttle timers so destroyed components cannot refresh later. */
+  dispose(): void {
+    if (this.throttleTimer !== null) {
+      clearTimeout(this.throttleTimer);
+      this.throttleTimer = null;
+    }
+    for (const e of this.entries) {
+      e.tc.setSnapshotListener(undefined);
+    }
+  }
+}
+
+function formatStats(snap: ToolCallSubagentSnapshot): string {
+  const dim = chalk.dim;
+  const tools = ` · ${String(snap.toolCount)} tool${snap.toolCount === 1 ? '' : 's'}`;
+  const tokens = snap.tokens > 0 ? ` · ${formatTokens(snap.tokens)}` : '';
+  return dim(`${tools}${tokens}`);
+}
+
+function formatLineTail(snap: ToolCallSubagentSnapshot, colors: ColorPalette): string {
+  if (snap.phase === 'done') {
+    return chalk.dim(' · ') + chalk.hex(colors.success)('✓ Completed');
+  }
+  if (snap.phase === 'failed') {
+    return chalk.dim(' · ') + chalk.hex(colors.error)('✗ Failed');
+  }
+  if (snap.phase === 'backgrounded') {
+    return chalk.dim(' · ◐ backgrounded');
+  }
+  return '';
+}
+
+function formatHeaderTail(toolCount: number, tokens: number): string {
+  const dim = chalk.dim;
+  const parts: string[] = [];
+  if (toolCount > 0) parts.push(`${String(toolCount)} tool${toolCount === 1 ? '' : 's'}`);
+  if (tokens > 0) parts.push(formatTokens(tokens));
+  return parts.length > 0 ? dim(` · ${parts.join(' · ')}`) : '';
+}
+
+function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M tok`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k tok`;
+  return `${String(n)} tok`;
+}
diff --git a/apps/kimi-code/src/tui/components/messages/assistant-message.ts b/apps/kimi-code/src/tui/components/messages/assistant-message.ts
new file mode 100644
index 000000000..1be89b2ca
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/assistant-message.ts
@@ -0,0 +1,63 @@
+/**
+ * Renders an assistant message using pi-tui Markdown.
+ *
+ * Displays a white bullet prefix with markdown content indented
+ * to align after the bullet.
+ */
+
+import type { Component, MarkdownTheme } from '@earendil-works/pi-tui';
+import { Container, Markdown, visibleWidth } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import { MESSAGE_INDENT } from '#/tui/constant/rendering';
+import { STATUS_BULLET } from '#/tui/constant/symbols';
+import type { ColorPalette } from '#/tui/theme/colors';
+
+export class AssistantMessageComponent implements Component {
+  private contentContainer: Container;
+  private markdownTheme: MarkdownTheme;
+  private bulletColor: string;
+  private lastText = '';
+  private showBullet: boolean;
+
+  constructor(markdownTheme: MarkdownTheme, colors: ColorPalette, showBullet: boolean = true) {
+    this.markdownTheme = markdownTheme;
+    this.bulletColor = colors.roleAssistant;
+    this.showBullet = showBullet;
+    this.contentContainer = new Container();
+  }
+
+  setShowBullet(show: boolean): void {
+    this.showBullet = show;
+  }
+
+  updateContent(text: string): void {
+    const displayText = text;
+    if (displayText === this.lastText) return;
+    this.lastText = displayText;
+    this.contentContainer.clear();
+    if (displayText.trim().length > 0) {
+      this.contentContainer.addChild(new Markdown(displayText.trim(), 0, 0, this.markdownTheme));
+    }
+  }
+
+  invalidate(): void {
+    this.contentContainer.invalidate?.();
+  }
+
+  render(width: number): string[] {
+    if (this.lastText.trim().length === 0) return [];
+
+    const prefix = this.showBullet ? STATUS_BULLET : MESSAGE_INDENT;
+    const contentWidth = Math.max(1, width - visibleWidth(prefix));
+    const contentLines = this.contentContainer.render(contentWidth);
+
+    const lines: string[] = [''];
+    for (let i = 0; i < contentLines.length; i++) {
+      const p =
+        i === 0 && this.showBullet ? chalk.hex(this.bulletColor)(STATUS_BULLET) : MESSAGE_INDENT;
+      lines.push(p + contentLines[i]);
+    }
+    return lines;
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/messages/background-agent-status.ts b/apps/kimi-code/src/tui/components/messages/background-agent-status.ts
new file mode 100644
index 000000000..c1086f805
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/background-agent-status.ts
@@ -0,0 +1,42 @@
+import type { Component } from '@earendil-works/pi-tui';
+import { Text } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import { MESSAGE_INDENT } from '#/tui/constant/rendering';
+import { FAILURE_MARK, STATUS_BULLET } from '#/tui/constant/symbols';
+import type { ColorPalette } from '#/tui/theme/colors';
+import type { BackgroundAgentStatusData } from '#/tui/types';
+
+export class BackgroundAgentStatusComponent implements Component {
+  constructor(
+    private readonly data: BackgroundAgentStatusData,
+    private readonly colors: ColorPalette,
+  ) {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const tone =
+      this.data.phase === 'started'
+        ? this.colors.primary
+        : this.data.phase === 'completed'
+          ? this.colors.success
+          : this.colors.error;
+
+    const bullet =
+      this.data.phase === 'failed' ? chalk.hex(tone)(FAILURE_MARK) : chalk.hex(tone)(STATUS_BULLET);
+    const text =
+      chalk.hex(tone)(this.data.headline) +
+      (this.data.detail !== undefined && this.data.detail.length > 0
+        ? chalk.hex(this.colors.textDim)(` (${this.data.detail})`)
+        : '');
+
+    const textComponent = new Text(text, 0, 0);
+    const contentWidth = Math.max(1, width - MESSAGE_INDENT.length);
+    const contentLines = textComponent.render(contentWidth);
+    return [
+      '',
+      ...contentLines.map((line, index) => (index === 0 ? bullet : MESSAGE_INDENT) + line),
+    ];
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/messages/mcp-status-panel.ts b/apps/kimi-code/src/tui/components/messages/mcp-status-panel.ts
new file mode 100644
index 000000000..9b7905eb0
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/mcp-status-panel.ts
@@ -0,0 +1,143 @@
+import type { McpServerInfo } from '@moonshot-ai/kimi-code-sdk';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+
+export interface McpStatusReportOptions {
+  readonly colors: ColorPalette;
+  readonly servers: readonly McpServerInfo[];
+}
+
+const STATUS_PRIORITY: Record<McpServerInfo['status'], number> = {
+  failed: 0,
+  'needs-auth': 1,
+  pending: 2,
+  connected: 3,
+  disabled: 4,
+};
+
+const STATUS_LABEL: Record<McpServerInfo['status'], string> = {
+  connected: 'connected',
+  pending: 'pending',
+  'needs-auth': 'needs auth',
+  failed: 'failed',
+  disabled: 'disabled',
+};
+
+const SUMMARY_ORDER: readonly McpServerInfo['status'][] = [
+  'connected',
+  'pending',
+  'needs-auth',
+  'failed',
+  'disabled',
+];
+
+function statusPainter(
+  status: McpServerInfo['status'],
+  colors: ColorPalette,
+): (text: string) => string {
+  switch (status) {
+    case 'connected':
+      return chalk.hex(colors.success);
+    case 'failed':
+      return chalk.hex(colors.error);
+    case 'needs-auth':
+    case 'pending':
+      return chalk.hex(colors.warning);
+    case 'disabled':
+      return chalk.hex(colors.textDim);
+  }
+}
+
+function formatToolCount(server: McpServerInfo): string {
+  if (server.status === 'disabled') return '—';
+  return `${server.toolCount} tool${server.toolCount === 1 ? '' : 's'}`;
+}
+
+function formatToolsAvailable(count: number): string {
+  return `${count} tool${count === 1 ? '' : 's'} available`;
+}
+
+function sortedServers(servers: readonly McpServerInfo[]): McpServerInfo[] {
+  return servers.toSorted(
+    (a, b) =>
+      STATUS_PRIORITY[a.status] - STATUS_PRIORITY[b.status] || a.name.localeCompare(b.name),
+  );
+}
+
+function buildSummary(servers: readonly McpServerInfo[]): string {
+  const counts: Partial<Record<McpServerInfo['status'], number>> = {};
+  let toolsAvailable = 0;
+  for (const server of servers) {
+    counts[server.status] = (counts[server.status] ?? 0) + 1;
+    if (server.status === 'connected') toolsAvailable += server.toolCount;
+  }
+  const parts: string[] = [];
+  for (const status of SUMMARY_ORDER) {
+    const n = counts[status];
+    if (n === undefined || n === 0) continue;
+    parts.push(`${n} ${STATUS_LABEL[status]}`);
+  }
+  parts.push(formatToolsAvailable(toolsAvailable));
+  return parts.join(' · ');
+}
+
+export function buildMcpStatusReportLines(options: McpStatusReportOptions): string[] {
+  const servers = sortedServers(options.servers);
+  const colors = options.colors;
+  const accent = chalk.hex(colors.primary).bold;
+  const muted = chalk.hex(colors.textDim);
+  const value = chalk.hex(colors.text);
+  const error = chalk.hex(colors.error);
+
+  const lines: string[] = [accent('Servers')];
+
+  if (servers.length === 0) {
+    lines.push(muted('  No MCP servers configured. Run /mcp-config to add one.'));
+    return lines;
+  }
+
+  const nameWidth = Math.max('Name'.length, ...servers.map((server) => server.name.length));
+  const statusWidth = Math.max(
+    'Status'.length,
+    ...servers.map((server) => STATUS_LABEL[server.status].length),
+  );
+  const transportWidth = Math.max(
+    'Transport'.length,
+    ...servers.map((server) => server.transport.length),
+  );
+
+  lines.push(
+    `  ${muted('Name'.padEnd(nameWidth))}  ${muted('Status'.padEnd(statusWidth))}  ${muted(
+      'Transport'.padEnd(transportWidth),
+    )}  ${muted('Tools')}`,
+  );
+
+  for (const server of servers) {
+    const status = statusPainter(
+      server.status,
+      colors,
+    )(STATUS_LABEL[server.status].padEnd(statusWidth));
+    lines.push(
+      `  ${value(server.name.padEnd(nameWidth))}  ${status}  ${muted(
+        server.transport.padEnd(transportWidth),
+      )}  ${value(formatToolCount(server))}`,
+    );
+
+    if (
+      server.status === 'failed' &&
+      server.error !== undefined &&
+      server.error.trim().length > 0
+    ) {
+      lines.push(`    ${muted('error:')} ${error(server.error.trim())}`);
+    }
+    if (server.status === 'needs-auth') {
+      lines.push(`    ${muted('action:')} ${value(`run /mcp-config login ${server.name}`)}`);
+    }
+  }
+
+  lines.push('');
+  lines.push(`  ${value(buildSummary(servers))}`);
+
+  return lines;
+}
diff --git a/apps/kimi-code/src/tui/components/messages/plan-box.ts b/apps/kimi-code/src/tui/components/messages/plan-box.ts
new file mode 100644
index 000000000..8f16e0580
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/plan-box.ts
@@ -0,0 +1,124 @@
+/**
+ * PlanBoxComponent — renders an ExitPlanMode plan inside a full box
+ * border, width-aware. The plan text is parsed as Markdown so headings,
+ * lists, bold, inline code etc. render the same way assistant messages do.
+ */
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type { Component, MarkdownTheme } from '@earendil-works/pi-tui';
+import { Markdown, visibleWidth } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+const LEFT_MARGIN = 2; // two-space indent matching other tool call children
+const SIDE_PADDING = 1; // space between the │ and the content on each side
+const TITLE_PREFIX = ' plan: ';
+const TITLE_SUFFIX = ' ';
+
+export interface PlanBoxOptions {
+  maxContentLines?: number;
+  expanded?: boolean;
+}
+
+export class PlanBoxComponent implements Component {
+  private readonly markdown: Markdown;
+  private readonly maxContentLines: number | undefined;
+  private readonly expanded: boolean;
+  private cachedWidth: number | undefined;
+  private cachedLines: string[] | undefined;
+
+  constructor(
+    plan: string,
+    markdownTheme: MarkdownTheme,
+    private readonly borderHex: string,
+    private readonly planPath?: string,
+    opts?: PlanBoxOptions,
+  ) {
+    // Build the Markdown instance once — pi-tui's Markdown caches its own
+    // parse + wrap output keyed on (text, width), so reusing the same
+    // instance means repeated render() calls from the parent Container
+    // hit the cache instead of re-parsing on every frame.
+    this.markdown = new Markdown(plan.trim(), 0, 0, markdownTheme);
+    this.maxContentLines = opts?.maxContentLines;
+    this.expanded = opts?.expanded ?? false;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+    this.markdown.invalidate?.();
+  }
+
+  render(width: number): string[] {
+    if (this.cachedLines !== undefined && this.cachedWidth === width) {
+      return this.cachedLines;
+    }
+
+    // Box layout: "  ┌──...──┐"
+    //             "  │ <content> │"
+    //             "  └──...──┘"
+    // width = LEFT_MARGIN + 1 + horzLen + 1 ⇒ horzLen = width - 4
+    // content width = horzLen - 2 * SIDE_PADDING = width - 6
+    const horzLen = Math.max(2, width - LEFT_MARGIN - 2);
+    const contentWidth = Math.max(1, horzLen - 2 * SIDE_PADDING);
+
+    const paint = (s: string): string => chalk.hex(this.borderHex)(s);
+    const indent = ' '.repeat(LEFT_MARGIN);
+
+    const title = this.buildTitle(horzLen);
+    const trailingDashLen = Math.max(0, horzLen - visibleWidth(title));
+    const top =
+      indent + paint('┌') + paint(title) + paint('─'.repeat(trailingDashLen)) + paint('┐');
+    const bottom = indent + paint('└' + '─'.repeat(horzLen) + '┘');
+
+    const rawLines = this.markdown.render(contentWidth);
+    const { shown, hiddenCount } = this.capContentLines(rawLines);
+
+    const lines: string[] = [top];
+    for (const raw of shown) {
+      const pad = Math.max(0, contentWidth - visibleWidth(raw));
+      lines.push(indent + paint('│') + ' ' + raw + ' '.repeat(pad) + ' ' + paint('│'));
+    }
+    if (hiddenCount > 0) {
+      const footer = chalk.dim(
+        `... (${String(hiddenCount)} more line${hiddenCount === 1 ? '' : 's'}, ctrl+e to expand)`,
+      );
+      const pad = Math.max(0, contentWidth - visibleWidth(footer));
+      lines.push(indent + paint('│') + ' ' + footer + ' '.repeat(pad) + ' ' + paint('│'));
+    }
+    lines.push(bottom);
+
+    this.cachedWidth = width;
+    this.cachedLines = lines;
+    return lines;
+  }
+
+  private capContentLines(rawLines: string[]): { shown: string[]; hiddenCount: number } {
+    const cap = this.maxContentLines;
+    if (this.expanded || cap === undefined || rawLines.length <= cap) {
+      return { shown: rawLines, hiddenCount: 0 };
+    }
+    const shownCount = Math.max(0, cap - 1);
+    return { shown: rawLines.slice(0, shownCount), hiddenCount: rawLines.length - shownCount };
+  }
+
+  private buildTitle(horzLen: number): string {
+    const fallback = ' plan ';
+    const planPath = this.planPath;
+    if (planPath === undefined || planPath.length === 0) return fallback;
+    const basename = path.basename(planPath);
+    if (basename.length === 0) return fallback;
+    const wrapperLen = TITLE_PREFIX.length + TITLE_SUFFIX.length;
+    const budget = horzLen - 1;
+    if (wrapperLen + basename.length > budget) return fallback;
+    const linked = path.isAbsolute(planPath)
+      ? toTerminalHyperlink(basename, pathToFileURL(planPath).href)
+      : basename;
+    return TITLE_PREFIX + linked + TITLE_SUFFIX;
+  }
+}
+
+function toTerminalHyperlink(text: string, url: string): string {
+  return `\u001B]8;;${url}\u0007${text}\u001B]8;;\u0007`;
+}
diff --git a/apps/kimi-code/src/tui/components/messages/read-group.ts b/apps/kimi-code/src/tui/components/messages/read-group.ts
new file mode 100644
index 000000000..1d48f3c37
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/read-group.ts
@@ -0,0 +1,188 @@
+/**
+ * ReadGroupComponent renders 2+ Read tool calls from the same step as one group.
+ *
+ * It follows the same structure as `AgentGroupComponent`, with a smaller
+ * surface:
+ * - one summary header and a tree body listing each file path and status;
+ * - permanently grouped, while the body remains visible;
+ * - 200ms throttling, matching AgentGroup;
+ * - state stays in each `ToolCallComponent`; the group only reads snapshots.
+ *
+ * Header forms:
+ *   pending > 0: Reading {N} files
+ *   all done:    Read {N} files · {L} lines
+ *   some failed: append · {F} failed
+ *   all failed:  Read {N} files · failed
+ *
+ * Body lines follow AgentGroup's branch style:
+ *   src/main.ts · 51 lines
+ *   src/cli.ts · reading
+ *   src/missing.ts · failed
+ */
+
+import type { TUI } from '@earendil-works/pi-tui';
+import { Container, Spacer, Text } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import { STATUS_BULLET } from '#/tui/constant/symbols';
+import type { ColorPalette } from '#/tui/theme/colors';
+
+import type { ToolCallComponent, ToolCallReadSnapshot } from './tool-call';
+
+const THROTTLE_MS = 200;
+
+interface ReadEntry {
+  readonly toolCallId: string;
+  readonly tc: ToolCallComponent;
+}
+
+export class ReadGroupComponent extends Container {
+  private readonly entries: ReadEntry[] = [];
+  private readonly headerText: Text;
+  private readonly bodyContainer: Container;
+  private throttleTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastFlushPhases = new Map<string, ToolCallReadSnapshot['phase']>();
+
+  constructor(
+    private readonly colors: ColorPalette,
+    private readonly ui: TUI | undefined,
+  ) {
+    super();
+    this.addChild(new Spacer(1));
+    this.headerText = new Text('', 0, 0);
+    this.addChild(this.headerText);
+    this.bodyContainer = new Container();
+    this.addChild(this.bodyContainer);
+  }
+
+  size(): number {
+    return this.entries.length;
+  }
+
+  /**
+   * Borrows a standalone `ToolCallComponent` into the group as a hidden state
+   * container. Snapshot changes trigger throttled refreshes. Re-attaching the
+   * same toolCallId is a no-op.
+   */
+  attach(toolCallId: string, tc: ToolCallComponent): void {
+    if (this.entries.some((e) => e.toolCallId === toolCallId)) return;
+    this.entries.push({ toolCallId, tc });
+    tc.setSnapshotListener(() => {
+      this.scheduleRender();
+    });
+    this.flushRender();
+  }
+
+  /**
+   * The pending -> done/failed transition is the important visible change, so
+   * it refreshes immediately. Other changes are throttled.
+   */
+  private scheduleRender(): void {
+    if (this.detectPhaseTransition()) {
+      this.flushRender();
+      return;
+    }
+    if (this.throttleTimer !== null) return;
+    this.throttleTimer = setTimeout(() => {
+      this.throttleTimer = null;
+      this.flushRender();
+    }, THROTTLE_MS);
+  }
+
+  private detectPhaseTransition(): boolean {
+    for (const e of this.entries) {
+      const phase = e.tc.getReadSnapshot().phase;
+      if (this.lastFlushPhases.get(e.toolCallId) !== phase) return true;
+    }
+    return false;
+  }
+
+  private flushRender(): void {
+    if (this.throttleTimer !== null) {
+      clearTimeout(this.throttleTimer);
+      this.throttleTimer = null;
+    }
+
+    const snapshots = this.entries.map((e) => e.tc.getReadSnapshot());
+    let pending = 0;
+    let failed = 0;
+    let totalLines = 0;
+    for (const snap of snapshots) {
+      if (snap.phase === 'pending') pending += 1;
+      else if (snap.phase === 'failed') failed += 1;
+      else totalLines += snap.lines;
+    }
+    this.headerText.setText(this.buildHeader(snapshots.length, pending, failed, totalLines));
+
+    this.bodyContainer.clear();
+    const visibleSnapshots = snapshots.filter(
+      (snap) => snap.filePath !== undefined && snap.filePath.length > 0,
+    );
+    visibleSnapshots.forEach((snap, idx) => {
+      const isLast = idx === visibleSnapshots.length - 1;
+      this.bodyContainer.addChild(new Text(this.buildBodyLine(snap, isLast), 0, 0));
+    });
+
+    this.lastFlushPhases.clear();
+    this.entries.forEach((entry, i) => {
+      const snap = snapshots[i];
+      if (snap !== undefined) this.lastFlushPhases.set(entry.toolCallId, snap.phase);
+    });
+
+    this.invalidate();
+    this.ui?.requestRender();
+  }
+
+  private buildHeader(total: number, pending: number, failed: number, totalLines: number): string {
+    const colors = this.colors;
+    const dim = chalk.dim;
+
+    if (pending > 0) {
+      const bullet = chalk.hex(colors.roleAssistant)(STATUS_BULLET);
+      const label = chalk.hex(colors.primary).bold(`Reading ${String(total)} files…`);
+      return `${bullet}${label}`;
+    }
+
+    // All reads have finished, either successfully or with failures.
+    if (failed === total) {
+      const bullet = chalk.hex(colors.error)('✗ ');
+      const label = chalk.hex(colors.error).bold(`Read ${String(total)} files`);
+      return `${bullet}${label}${chalk.hex(colors.error)(' · failed')}`;
+    }
+
+    const bullet = chalk.hex(colors.success)(STATUS_BULLET);
+    const label = chalk.hex(colors.primary).bold(`Read ${String(total)} files`);
+    const linesPart = dim(` · ${String(totalLines)} ${totalLines === 1 ? 'line' : 'lines'}`);
+    const failPart = failed > 0 ? chalk.hex(colors.error)(` · ${String(failed)} failed`) : '';
+    return `${bullet}${label}${linesPart}${failPart}`;
+  }
+
+  private buildBodyLine(snap: ToolCallReadSnapshot, isLast: boolean): string {
+    const colors = this.colors;
+    const dim = chalk.dim;
+    const branch = isLast ? '└─' : '├─';
+    const path = snap.filePath ?? '';
+    const pathPart = chalk.hex(colors.text)(path);
+
+    let tail: string;
+    if (snap.phase === 'pending') {
+      tail = dim(' · reading…');
+    } else if (snap.phase === 'failed') {
+      tail = chalk.hex(colors.error)(' · failed');
+    } else {
+      tail = dim(` · ${String(snap.lines)} ${snap.lines === 1 ? 'line' : 'lines'}`);
+    }
+    return `  ${branch} ${pathPart}${tail}`;
+  }
+
+  /** Releases throttle timers so destroyed components cannot refresh later. */
+  dispose(): void {
+    if (this.throttleTimer !== null) {
+      clearTimeout(this.throttleTimer);
+      this.throttleTimer = null;
+    }
+    for (const e of this.entries) {
+      e.tc.setSnapshotListener(undefined);
+    }
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/messages/shell-execution.ts b/apps/kimi-code/src/tui/components/messages/shell-execution.ts
new file mode 100644
index 000000000..45279fd94
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/shell-execution.ts
@@ -0,0 +1,88 @@
+import type { Component } from '@earendil-works/pi-tui';
+import { Container, Text } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import { COMMAND_PREVIEW_LINES } from '#/tui/constant/rendering';
+import type { ColorPalette } from '#/tui/theme/colors';
+import type { ToolCallBlockData, ToolResultBlockData } from '#/tui/types';
+
+import type { ResultRenderer } from './tool-renderers/types';
+import { PREVIEW_LINES } from './tool-renderers/types';
+
+export interface ShellExecutionOptions {
+  readonly command?: string;
+  readonly result?: ToolResultBlockData;
+  readonly colors: ColorPalette;
+  readonly expanded?: boolean;
+  readonly showCommand?: boolean;
+  readonly commandPreviewLines?: number;
+  readonly resultPreviewLines?: number;
+}
+
+export class ShellExecutionComponent extends Container {
+  constructor(options: ShellExecutionOptions) {
+    super();
+
+    if (options.showCommand === true) {
+      this.addCommandPreview(
+        options.command ?? '',
+        options.commandPreviewLines ?? COMMAND_PREVIEW_LINES,
+      );
+    }
+
+    if (options.result !== undefined) {
+      this.addResultPreview(
+        options.result,
+        options.colors,
+        options.expanded ?? false,
+        options.resultPreviewLines ?? PREVIEW_LINES,
+      );
+    }
+  }
+
+  private addCommandPreview(command: string, previewLines: number): void {
+    if (command.length === 0) return;
+    const lines = command.split('\n').slice(0, previewLines);
+    for (const [i, line] of lines.entries()) {
+      const prefix = i === 0 ? '$ ' : '  ';
+      this.addChild(new Text(chalk.dim(prefix + line), 2, 0));
+    }
+  }
+
+  private addResultPreview(
+    result: ToolResultBlockData,
+    colors: ColorPalette,
+    expanded: boolean,
+    previewLines: number,
+  ): void {
+    if (!result.output) return;
+    const tint = result.is_error ? chalk.hex(colors.error) : chalk.dim;
+    if (expanded) {
+      this.addChild(new Text(tint(result.output), 2, 0));
+      return;
+    }
+
+    const lines = result.output.split('\n');
+    const shown = lines.slice(0, previewLines);
+    const remaining = lines.length - shown.length;
+    this.addChild(new Text(tint(shown.join('\n')), 2, 0));
+    if (remaining > 0) {
+      this.addChild(
+        new Text(chalk.dim(`... (${String(remaining)} more lines, ctrl+o to expand)`), 2, 0),
+      );
+    }
+  }
+}
+
+export const shellExecutionResultRenderer: ResultRenderer = (
+  toolCall: ToolCallBlockData,
+  result: ToolResultBlockData,
+  ctx,
+): Component[] => [
+  new ShellExecutionComponent({
+    command: typeof toolCall.args['command'] === 'string' ? toolCall.args['command'] : '',
+    result,
+    colors: ctx.colors,
+    expanded: ctx.expanded,
+  }),
+];
diff --git a/apps/kimi-code/src/tui/components/messages/skill-activation.ts b/apps/kimi-code/src/tui/components/messages/skill-activation.ts
new file mode 100644
index 000000000..7f9e05c9f
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/skill-activation.ts
@@ -0,0 +1,36 @@
+/**
+ * Skill activation card.
+ *
+ * When the user runs `/skill:foo bar`, the TUI renders a compact card instead
+ * of expanding the SKILL.md body into the user bubble:
+ *
+ *   ▶ Activated skill: foo
+ *     bar
+ *
+ * The args line is optional. Core expands the skill body into the LLM context;
+ * the TUI only consumes the `skill.activated` event and user_message origin
+ * metadata.
+ */
+
+import { Container, Text, Spacer } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '#/tui/theme/colors';
+
+const ARGS_PREVIEW_MAX = 200;
+
+export class SkillActivationComponent extends Container {
+  constructor(name: string, args: string | undefined, colors: ColorPalette) {
+    super();
+    this.addChild(new Spacer(1));
+    const head =
+      chalk.hex(colors.primary).bold('▶ Activated skill: ') + chalk.hex(colors.roleUser).bold(name);
+    this.addChild(new Text(head, 0, 0));
+    const trimmed = args?.trim() ?? '';
+    if (trimmed.length > 0) {
+      const preview =
+        trimmed.length > ARGS_PREVIEW_MAX ? trimmed.slice(0, ARGS_PREVIEW_MAX) + '…' : trimmed;
+      this.addChild(new Text('  ' + chalk.hex(colors.textDim)(preview), 0, 0));
+    }
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/messages/status-message.ts b/apps/kimi-code/src/tui/components/messages/status-message.ts
new file mode 100644
index 000000000..be2292358
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/status-message.ts
@@ -0,0 +1,23 @@
+import { Container, Spacer, Text } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ColorPalette } from '../../theme/colors';
+
+export class StatusMessageComponent extends Container {
+  constructor(content: string, colors: ColorPalette, color?: string) {
+    super();
+    const text = color === undefined ? chalk.hex(colors.textDim)(content) : chalk.hex(color)(content);
+    this.addChild(new Text(`  ${text}`, 0, 0));
+  }
+}
+
+export class NoticeMessageComponent extends Container {
+  constructor(title: string, detail: string | undefined, colors: ColorPalette) {
+    super();
+    this.addChild(new Spacer(1));
+    this.addChild(new Text(`  ${chalk.hex(colors.textStrong)(title)}`, 0, 0));
+    if (detail !== undefined && detail.length > 0) {
+      this.addChild(new Text(`  ${chalk.hex(colors.textDim)(detail)}`, 0, 0));
+    }
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/messages/status-panel.ts b/apps/kimi-code/src/tui/components/messages/status-panel.ts
new file mode 100644
index 000000000..c60e2f546
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/status-panel.ts
@@ -0,0 +1,148 @@
+/**
+ * Status report line builder for `/status`.
+ *
+ * It mirrors `/usage` visual language but keeps runtime status formatting
+ * separate from the TUI orchestration layer.
+ */
+
+import type { ModelAlias, PermissionMode, SessionStatus } from '@moonshot-ai/kimi-code-sdk';
+import chalk from 'chalk';
+
+import { PRODUCT_NAME } from '#/constant/app';
+import type { ColorPalette } from '#/tui/theme/colors';
+import {
+  formatTokenCount,
+  ratioSeverity,
+  renderProgressBar,
+  safeUsageRatio,
+} from '#/utils/usage/usage-format';
+
+import { buildManagedUsageReportLines, type ManagedUsageReport } from './usage-panel';
+
+interface FieldRow {
+  readonly label: string;
+  readonly value: string;
+  readonly severity?: 'error';
+}
+
+export interface StatusReportOptions {
+  readonly colors: ColorPalette;
+  readonly version: string;
+  readonly model: string;
+  readonly workDir: string;
+  readonly sessionId: string;
+  readonly sessionTitle: string | null;
+  readonly thinking: boolean;
+  readonly permissionMode: PermissionMode;
+  readonly planMode: boolean;
+  readonly contextUsage: number;
+  readonly contextTokens: number;
+  readonly maxContextTokens: number;
+  readonly availableModels: Record<string, ModelAlias>;
+  readonly status?: SessionStatus;
+  readonly statusError?: string;
+  readonly managedUsage?: ManagedUsageReport;
+  readonly managedUsageError?: string;
+}
+
+type Colorize = (text: string) => string;
+
+function displayModelName(alias: string, models: Record<string, ModelAlias>): string {
+  const model = models[alias];
+  return model?.displayName ?? model?.model ?? alias;
+}
+
+function formatModelStatus(options: StatusReportOptions): string {
+  const model = options.status?.model ?? options.model;
+  if (model.trim().length === 0) return 'not set';
+
+  const thinking = (options.status?.thinkingLevel ?? (options.thinking ? 'on' : 'off')) === 'off'
+    ? 'off'
+    : 'on';
+  return `${displayModelName(model, options.availableModels)} (thinking ${thinking})`;
+}
+
+function addFieldRows(
+  lines: string[],
+  rows: readonly FieldRow[],
+  muted: Colorize,
+  value: Colorize,
+  errorStyle: Colorize,
+): void {
+  const labelWidth = Math.max(10, ...rows.map((row) => row.label.length));
+  for (const row of rows) {
+    const colorize = row.severity === 'error' ? errorStyle : value;
+    lines.push(`  ${muted(row.label.padEnd(labelWidth, ' '))}  ${colorize(row.value)}`);
+  }
+}
+
+function contextValues(options: StatusReportOptions): {
+  ratio: number;
+  tokens: number;
+  maxTokens: number;
+} {
+  return {
+    ratio: options.status?.contextUsage ?? options.contextUsage,
+    tokens: options.status?.contextTokens ?? options.contextTokens,
+    maxTokens: options.status?.maxContextTokens ?? options.maxContextTokens,
+  };
+}
+
+export function buildStatusReportLines(options: StatusReportOptions): string[] {
+  const colors = options.colors;
+  const accent = chalk.hex(colors.primary).bold;
+  const value = chalk.hex(colors.text);
+  const muted = chalk.hex(colors.textDim);
+  const errorStyle = chalk.hex(colors.error);
+  const severityHex = (sev: 'ok' | 'warn' | 'danger'): string =>
+    sev === 'danger' ? colors.error : sev === 'warn' ? colors.warning : colors.success;
+
+  const permission = options.status?.permission ?? options.permissionMode;
+  const planMode = options.status?.planMode ?? options.planMode;
+  const sessionId = options.sessionId.trim().length > 0 ? options.sessionId : 'none';
+  const rows: FieldRow[] = [
+    { label: 'Model', value: formatModelStatus(options) },
+    { label: 'Directory', value: options.workDir },
+    { label: 'Permissions', value: permission },
+    { label: 'Plan mode', value: planMode ? 'on' : 'off' },
+    { label: 'Session', value: sessionId },
+  ];
+  const title = options.sessionTitle?.trim();
+  if (title !== undefined && title.length > 0) rows.push({ label: 'Title', value: title });
+  if (options.statusError !== undefined) {
+    rows.push({ label: 'Warning', value: options.statusError, severity: 'error' });
+  }
+
+  const lines: string[] = [
+    `${accent(`>_ ${PRODUCT_NAME}`)} ${muted(`(v${options.version})`)}`,
+    '',
+  ];
+  addFieldRows(lines, rows, muted, value, errorStyle);
+
+  const { ratio, tokens, maxTokens } = contextValues(options);
+  lines.push('');
+  lines.push(accent('Context window'));
+  if (maxTokens > 0) {
+    const safeRatio = safeUsageRatio(ratio);
+    const bar = renderProgressBar(safeRatio, 20);
+    const barColoured = chalk.hex(severityHex(ratioSeverity(safeRatio)))(bar);
+    lines.push(
+      `  ${barColoured}  ${value(`${(safeRatio * 100).toFixed(1)}%`.padStart(6, ' '))}  ` +
+        muted(`(${formatTokenCount(tokens)} / ${formatTokenCount(maxTokens)})`),
+    );
+  } else {
+    lines.push(`  ${muted('No context window data available.')}`);
+  }
+
+  const managedSection = buildManagedUsageReportLines({
+    colors,
+    managedUsage: options.managedUsage,
+    managedUsageError: options.managedUsageError,
+  });
+  if (managedSection.length > 0) {
+    lines.push('');
+    lines.push(...managedSection);
+  }
+
+  return lines;
+}
diff --git a/apps/kimi-code/src/tui/components/messages/thinking.ts b/apps/kimi-code/src/tui/components/messages/thinking.ts
new file mode 100644
index 000000000..632cef307
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/thinking.ts
@@ -0,0 +1,122 @@
+/**
+ * Renders thinking content in the transcript.
+ * Supports live in-place updates while thinking streams, then finalizes
+ * without replacing the component.
+ * Supports expand/collapse via Ctrl+O (shared with tool output).
+ */
+
+import type { Component, TUI } from '@earendil-works/pi-tui';
+import { Text } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import {
+  BRAILLE_SPINNER_FRAMES,
+  BRAILLE_SPINNER_INTERVAL_MS,
+  MESSAGE_INDENT,
+  RESULT_PREVIEW_LINES,
+} from '#/tui/constant/rendering';
+import { STATUS_BULLET } from '#/tui/constant/symbols';
+import type { ColorPalette } from '#/tui/theme/colors';
+
+export type ThinkingRenderMode = 'live' | 'finalized';
+
+export class ThinkingComponent implements Component {
+  private text: string;
+  private color: string;
+  private showMarker: boolean;
+  private mode: ThinkingRenderMode;
+  private expanded = false;
+  private readonly ui: TUI | undefined;
+  private spinnerFrame = 0;
+  private spinnerInterval: ReturnType<typeof setInterval> | undefined;
+
+  constructor(
+    text: string,
+    colors: ColorPalette,
+    showMarker: boolean = true,
+    mode: ThinkingRenderMode = 'finalized',
+    ui?: TUI,
+  ) {
+    this.text = text;
+    this.color = colors.roleThinking;
+    this.showMarker = showMarker;
+    this.mode = mode;
+    this.ui = ui;
+    if (mode === 'live') {
+      this.startSpinner();
+    }
+  }
+
+  invalidate(): void {}
+
+  setText(text: string): void {
+    this.text = text;
+  }
+
+  finalize(): void {
+    this.mode = 'finalized';
+    this.stopSpinner();
+  }
+
+  dispose(): void {
+    this.stopSpinner();
+  }
+
+  setExpanded(expanded: boolean): void {
+    if (this.expanded === expanded) return;
+    this.expanded = expanded;
+  }
+
+  render(width: number): string[] {
+    const contentWidth = Math.max(1, width - MESSAGE_INDENT.length);
+    const textComponent = new Text(chalk.hex(this.color).italic(this.text), 0, 0);
+    const contentLines = this.text.length > 0 ? textComponent.render(contentWidth) : [''];
+
+    if (this.mode === 'live') {
+      const visibleLines =
+        contentLines.length > RESULT_PREVIEW_LINES
+          ? contentLines.slice(contentLines.length - RESULT_PREVIEW_LINES)
+          : contentLines;
+      const spinner = chalk.hex(this.color)(
+        `${BRAILLE_SPINNER_FRAMES[this.spinnerFrame] ?? BRAILLE_SPINNER_FRAMES[0]} `,
+      );
+      return [
+        '',
+        spinner + chalk.hex(this.color)('thinking...'),
+        ...visibleLines.map((line) => MESSAGE_INDENT + line),
+      ];
+    }
+
+    const rendered: string[] = [''];
+    for (let i = 0; i < contentLines.length; i++) {
+      const p = i === 0 && this.showMarker ? chalk.hex(this.color)(STATUS_BULLET) : MESSAGE_INDENT;
+      rendered.push(p + contentLines[i]);
+    }
+
+    if (this.expanded || contentLines.length <= RESULT_PREVIEW_LINES) {
+      return rendered;
+    }
+
+    // Leading blank + first PREVIEW_LINES content lines + hint line.
+    const truncated = rendered.slice(0, 1 + RESULT_PREVIEW_LINES);
+    const remaining = contentLines.length - RESULT_PREVIEW_LINES;
+    truncated.push(
+      MESSAGE_INDENT + chalk.dim(`... (${String(remaining)} more lines, ctrl+o to expand)`),
+    );
+    return truncated;
+  }
+
+  private startSpinner(): void {
+    if (this.ui === undefined || this.spinnerInterval !== undefined) return;
+    this.spinnerInterval = setInterval(() => {
+      this.spinnerFrame = (this.spinnerFrame + 1) % BRAILLE_SPINNER_FRAMES.length;
+      this.ui?.requestRender();
+    }, BRAILLE_SPINNER_INTERVAL_MS);
+  }
+
+  private stopSpinner(): void {
+    if (this.spinnerInterval === undefined) return;
+    clearInterval(this.spinnerInterval);
+    this.spinnerInterval = undefined;
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/messages/tool-call.ts b/apps/kimi-code/src/tui/components/messages/tool-call.ts
new file mode 100644
index 000000000..dc831e8be
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/tool-call.ts
@@ -0,0 +1,1675 @@
+/**
+ * Renders a tool call entry in the transcript.
+ * Supports expand/collapse via Ctrl+O.
+ */
+
+import { isAbsolute, relative, sep } from 'node:path';
+
+import { Container, Text, Spacer, visibleWidth } from '@earendil-works/pi-tui';
+import type { Component, MarkdownTheme, TUI } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import { highlightLines, langFromPath } from '#/tui/components/media/code-highlight';
+import { renderDiffLinesClustered } from '#/tui/components/media/diff-preview';
+import { COMMAND_PREVIEW_LINES } from '#/tui/constant/rendering';
+import { STREAMING_ARGS_FIELD_RE } from '#/tui/constant/streaming';
+import { STATUS_BULLET } from '#/tui/constant/symbols';
+import type { ColorPalette } from '#/tui/theme/colors';
+import type { ToolCallBlockData, ToolResultBlockData } from '#/tui/types';
+import { decodeMcpToolName } from '#/tui/utils/mcp-tool-name';
+
+import { PlanBoxComponent } from './plan-box';
+import { ShellExecutionComponent } from './shell-execution';
+import { countNonEmptyLines, pickChip } from './tool-renderers/chip';
+import { pickResultRenderer } from './tool-renderers/registry';
+
+const MAX_ARG_LENGTH = 60;
+const MAX_SUB_TOOL_CALLS_SHOWN = 4;
+const MAX_SINGLE_SUBAGENT_TOOL_ROWS = 4;
+const APPROVED_PLAN_MARKER = '## Approved Plan:';
+const STREAMING_PROGRESS_INTERVAL_MS = 1000;
+const SUBAGENT_ELAPSED_INTERVAL_MS = 1000;
+const PROGRESS_URL_RE = /https?:\/\/\S+/g;
+
+type SubagentTextKind = 'thinking' | 'text';
+
+interface SubagentTokenUsage {
+  readonly input?: number | undefined;
+  readonly inputOther?: number | undefined;
+  readonly inputCacheRead?: number | undefined;
+  readonly inputCacheCreation?: number | undefined;
+  readonly output: number;
+}
+
+interface FinishedSubCall {
+  readonly name: string;
+  readonly args: Record<string, unknown>;
+  readonly output: string;
+  readonly isError: boolean;
+}
+
+interface OngoingSubCall {
+  readonly name: string;
+  readonly args: Record<string, unknown>;
+  readonly streamingArguments?: string | undefined;
+}
+
+interface SubToolActivity {
+  readonly id: string;
+  name: string;
+  args: Record<string, unknown>;
+  phase: 'ongoing' | 'done' | 'failed';
+  readonly orderSeq: number;
+}
+
+/**
+ * Immutable subagent state snapshot. `AgentGroupComponent` reads one-time
+ * views via `ToolCallComponent.getSubagentSnapshot()` and renders its own
+ * branch lines; `onSnapshotChange` notifies it when state changes.
+ *
+ * `latestActivity` priority, used only while running:
+ *   1. latest ongoing sub-tool (`Using {name} ({keyArg})`)
+ *   2. latest finished sub-tool (`Used {name} ({keyArg})`)
+ *   3. last non-empty line from accumulated subagent text
+ */
+export interface ToolCallSubagentSnapshot {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly toolCallDescription: string;
+  readonly agentName: string | undefined;
+  readonly phase: 'spawning' | 'running' | 'done' | 'failed' | 'backgrounded' | undefined;
+  readonly toolCount: number;
+  readonly tokens: number;
+  readonly isError: boolean;
+  readonly errorText: string | undefined;
+  readonly latestActivity: string | undefined;
+}
+
+/**
+ * Immutable Read tool state snapshot. `ReadGroupComponent` reads one-time
+ * views via `ToolCallComponent.getReadSnapshot()` and sums lines for the group
+ * header. `lines` is 0 while pending or failed, and the non-empty result line
+ * count when done, matching the single-card chip.
+ */
+export interface ToolCallReadSnapshot {
+  readonly toolCallId: string;
+  readonly filePath: string | undefined;
+  readonly phase: 'pending' | 'done' | 'failed';
+  readonly lines: number;
+}
+
+function str(v: unknown): string {
+  return typeof v === 'string' ? v : '';
+}
+
+function usageInputTotal(usage: SubagentTokenUsage): number {
+  return (
+    usage.input ??
+    (usage.inputOther ?? 0) + (usage.inputCacheRead ?? 0) + (usage.inputCacheCreation ?? 0)
+  );
+}
+
+function formatSubagentTokens(usage: SubagentTokenUsage | undefined): string | undefined {
+  if (usage === undefined) return undefined;
+  const total = usageInputTotal(usage) + usage.output;
+  if (total <= 0) return undefined;
+  const formatted = total >= 1000 ? `${(total / 1000).toFixed(1)}k` : String(total);
+  return `${formatted} tok`;
+}
+
+function formatByteSize(bytes: number): string {
+  if (bytes < 1024) return `${String(bytes)} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+function formatElapsed(seconds: number): string {
+  if (seconds < 60) return `${String(seconds)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return `${String(minutes)}m ${String(remainder)}s`;
+}
+
+function extractApprovedPlan(output: string): string {
+  const markerIndex = output.indexOf(APPROVED_PLAN_MARKER);
+  if (markerIndex < 0) return '';
+  return output.slice(markerIndex + APPROVED_PLAN_MARKER.length).trim();
+}
+
+interface ExitPlanModeOutcome {
+  readonly kind: 'approved' | 'rejected';
+  readonly chosen?: string;
+  readonly feedback?: string;
+  readonly path?: string;
+}
+
+const REJECT_PREFIX = 'User rejected the plan.';
+const REJECT_FEEDBACK_PREFIX = 'User rejected the plan. Feedback:';
+const APPROVED_OPTION_RE = /^User approved option "([^"]+)"\./;
+const PLAN_REJECT_PREFIX = 'Plan rejected by user.';
+const SELECTED_APPROACH_RE = /^Exited plan mode\. Selected approach: ([^\n]+)\n/;
+const PLAN_SAVED_TO_RE = /\nPlan saved to: ([^\n]+)\n/;
+
+/**
+ * Parses the ExitPlanMode result content string to recover the approval outcome
+ * and optional plan path. Core-side templates live in
+ * `packages/agent-core/src/tools/builtin/planning/exit-plan-mode.ts`:
+ *   - Approved output starts with 'Exited plan mode.' and selected options
+ *     are reported as 'Selected approach: <label>'. Older outputs may start
+ *     with 'User approved option "<label>".' Plan-file mode may include
+ *     'Plan saved to: <path>'.
+ *   - Rejected output starts with 'Plan rejected by user.' or older
+ *     'User rejected the plan.'; feedback uses 'User rejected the plan.
+ *     Feedback:\n\n<text>'.
+ * This is a string protocol rather than a structured payload. Prefer a
+ * structured event payload if core starts emitting one.
+ */
+function interpretExitPlanModeOutcome(output: string): ExitPlanModeOutcome {
+  if (output.startsWith(REJECT_PREFIX)) {
+    if (output.startsWith(REJECT_FEEDBACK_PREFIX)) {
+      const feedback = output.slice(REJECT_FEEDBACK_PREFIX.length).trimStart();
+      return { kind: 'rejected', feedback };
+    }
+    return { kind: 'rejected' };
+  }
+  if (output.startsWith(PLAN_REJECT_PREFIX)) {
+    return { kind: 'rejected' };
+  }
+  const pathMatch = PLAN_SAVED_TO_RE.exec(output);
+  const path = pathMatch?.[1]?.trim();
+  const optionMatch = SELECTED_APPROACH_RE.exec(output) ?? APPROVED_OPTION_RE.exec(output);
+  if (optionMatch !== null) {
+    return path !== undefined && path.length > 0
+      ? { kind: 'approved', chosen: optionMatch[1], path }
+      : { kind: 'approved', chosen: optionMatch[1] };
+  }
+  return path !== undefined && path.length > 0 ? { kind: 'approved', path } : { kind: 'approved' };
+}
+
+function unescapeJsonString(s: string): string {
+  return s.replaceAll(/\\(["\\/bfnrt])/g, (_, ch: string) => {
+    switch (ch) {
+      case 'n':
+        return '\n';
+      case 't':
+        return '\t';
+      case 'r':
+        return '\r';
+      case 'b':
+        return '\b';
+      case 'f':
+        return '\f';
+      case '"':
+        return '"';
+      case '\\':
+        return '\\';
+      case '/':
+        return '/';
+      default:
+        return ch;
+    }
+  });
+}
+
+/**
+ * Pull the live value of a JSON string field out of partially-streamed
+ * arguments, even if the closing quote hasn't arrived yet. Handles the
+ * common JSON string escapes so `\n` in a streamed `content` becomes a
+ * real newline we can highlight. Returns `undefined` if the field hasn't
+ * started streaming yet.
+ */
+function extractPartialStringField(text: string, key: string): string | undefined {
+  const opener = new RegExp(`"${key}"\\s*:\\s*"`);
+  const match = opener.exec(text);
+  if (match === null) return undefined;
+  const start = match.index + match[0].length;
+  let out = '';
+  let i = start;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '\\') {
+      const next = text[i + 1];
+      if (next === undefined) return out;
+      switch (next) {
+        case 'n':
+          out += '\n';
+          break;
+        case 't':
+          out += '\t';
+          break;
+        case 'r':
+          out += '\r';
+          break;
+        case 'b':
+          out += '\b';
+          break;
+        case 'f':
+          out += '\f';
+          break;
+        case '"':
+          out += '"';
+          break;
+        case '\\':
+          out += '\\';
+          break;
+        case '/':
+          out += '/';
+          break;
+        case 'u': {
+          if (i + 5 >= text.length) return out;
+          const hex = text.slice(i + 2, i + 6);
+          const code = Number.parseInt(hex, 16);
+          if (Number.isNaN(code)) return out;
+          out += String.fromCodePoint(code);
+          i += 6;
+          continue;
+        }
+        default:
+          out += next;
+      }
+      i += 2;
+      continue;
+    }
+    if (ch === '"') return out;
+    out += ch;
+    i++;
+  }
+  return out;
+}
+
+function parseArgsPreview(value: string): Record<string, unknown> {
+  if (value.trim().length === 0) return {};
+  if (value.trimEnd().endsWith('}')) {
+    try {
+      const parsed = JSON.parse(value) as unknown;
+      if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+        return parsed as Record<string, unknown>;
+      }
+    } catch {
+      // fall through to partial scan
+    }
+  }
+  const result: Record<string, unknown> = {};
+  for (const match of value.matchAll(STREAMING_ARGS_FIELD_RE)) {
+    const key = match[1];
+    const rawValue = match[2];
+    if (key === undefined || rawValue === undefined) continue;
+    if (!(key in result)) result[key] = unescapeJsonString(rawValue);
+  }
+  return result;
+}
+
+const PATH_KEYS = new Set(['path', 'file_path']);
+
+function truncateArgValue(key: string, value: string): string {
+  if (value.length <= MAX_ARG_LENGTH) return value;
+  if (PATH_KEYS.has(key)) {
+    // Preserve the tail (filename) — drop the prefix so the user can
+    // still tell which file is being touched.
+    return '…' + value.slice(value.length - (MAX_ARG_LENGTH - 1));
+  }
+  return value.slice(0, MAX_ARG_LENGTH - 3) + '...';
+}
+
+function makeWorkspaceRelativePath(filePath: string, workspaceDir: string | undefined): string {
+  if (workspaceDir === undefined || workspaceDir.length === 0 || !isAbsolute(filePath)) {
+    return filePath;
+  }
+  const relativePath = relative(workspaceDir, filePath);
+  if (
+    relativePath.length === 0 ||
+    relativePath === '..' ||
+    relativePath.startsWith(`..${sep}`) ||
+    isAbsolute(relativePath)
+  ) {
+    return filePath;
+  }
+  return relativePath;
+}
+
+function formatKeyArgument(
+  toolName: string,
+  key: string,
+  value: string,
+  workspaceDir: string | undefined,
+): string {
+  const displayValue =
+    toolName === 'Read' && PATH_KEYS.has(key)
+      ? makeWorkspaceRelativePath(value, workspaceDir)
+      : value;
+  return truncateArgValue(key, displayValue);
+}
+
+function extractKeyArgument(
+  toolName: string,
+  args: Record<string, unknown>,
+  workspaceDir?: string,
+): string | null {
+  const keyMap: Record<string, string[]> = {
+    Bash: ['command'],
+    Read: ['path', 'file_path'],
+    Write: ['path', 'file_path'],
+    Edit: ['path', 'file_path'],
+    Grep: ['pattern'],
+    Glob: ['pattern'],
+    FetchURL: ['url'],
+    WebSearch: ['query'],
+    // Prefer the short `description` so the header preview never spills a
+    // multi-line `prompt` into the TUI chrome.
+    Agent: ['description', 'prompt'],
+  };
+
+  const candidates = keyMap[toolName] ?? Object.keys(args);
+  for (const key of candidates) {
+    const val = args[key];
+    if (typeof val === 'string' && val.length > 0) {
+      const firstLine = val.split('\n')[0] ?? val;
+      return formatKeyArgument(toolName, key, firstLine, workspaceDir);
+    }
+  }
+  return null;
+}
+
+function formatSubagentLabel(agentName: string | undefined): string {
+  const raw = agentName?.trim();
+  if (raw === undefined || raw.length === 0) return 'SubAgent';
+  const label = raw
+    .split(/[-_\s]+/)
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+  if (/\bagent$/i.test(label)) return label;
+  return `${label} Agent`;
+}
+
+function tailNonEmptyLines(text: string, maxLines: number): string[] {
+  if (text.length === 0) return [];
+  return text
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim().length > 0)
+    .slice(-maxLines);
+}
+
+class PrefixedWrappedLine implements Component {
+  constructor(
+    private readonly firstPrefix: string,
+    private readonly continuationPrefix: string,
+    private readonly text: string,
+  ) { }
+
+  invalidate(): void { }
+
+  render(width: number): string[] {
+    const prefixWidth = Math.max(
+      visibleWidth(this.firstPrefix),
+      visibleWidth(this.continuationPrefix),
+    );
+    const contentWidth = Math.max(1, width - prefixWidth);
+    const lines = new Text(this.text, 0, 0).render(contentWidth);
+    return lines.map((line, index) =>
+      index === 0 ? `${this.firstPrefix}${line}` : `${this.continuationPrefix}${line}`,
+    );
+  }
+}
+
+export class ToolCallComponent extends Container {
+  private expanded = false;
+  private planExpanded = false;
+  private toolCall: ToolCallBlockData;
+  private result: ToolResultBlockData | undefined;
+  private colors: ColorPalette;
+  private ui: TUI | undefined;
+  private markdownTheme: MarkdownTheme | undefined;
+  private planPath: string | undefined;
+  /**
+   * Fallback plan body used when the LLM uses plan-file mode and
+   * `args.plan` is empty. `KimiTUI` calls `setPlanInfo` with
+   * `session.getPlan()` content so the plan box can render while
+   * approval is pending, and so rejected or revised results still show
+   * the plan body even without a `## Approved Plan:` marker.
+   */
+  private currentPlan: string | undefined;
+  private headerText: Text;
+  private callPreviewEndIndex = 0;
+
+  // ── Subagent state ───────────────────────────────────────────────
+  //
+  // Populated by `setSubagentMeta` / `appendSubToolCall` / `finishSubToolCall`
+  // when KimiTUI routes a `subagent.event` with this tool call
+  // id as its `parent_tool_call_id`. Rendered at the tail of
+  // buildContent so it shows up both during streaming and after the
+  // parent tool call resolves.
+  private subagentAgentId: string | undefined;
+  private subagentAgentName: string | undefined;
+  private readonly ongoingSubCalls = new Map<string, OngoingSubCall>();
+  private readonly finishedSubCalls: FinishedSubCall[] = [];
+  private readonly subToolActivities = new Map<string, SubToolActivity>();
+  private subToolOrderSeq = 0;
+  private hiddenSubCallCount = 0;
+  /**
+   * Recent normal-output lines from the child agent. Historical replay can also
+   * store mixed text here.
+   */
+  private subagentText = '';
+  private subagentThinkingText = '';
+  // ── Subagent lifecycle state from subagent.spawned/completed/failed ──
+  private subagentPhase: 'spawning' | 'running' | 'done' | 'failed' | 'backgrounded' | undefined;
+  private subagentUsage: SubagentTokenUsage | undefined;
+  private subagentResultSummary: string | undefined;
+  private subagentError: string | undefined;
+  private streamingProgressTimer: ReturnType<typeof setInterval> | undefined;
+  private subagentElapsedTimer: ReturnType<typeof setInterval> | undefined;
+  private subagentStartedAtMs: number | undefined;
+  private subagentEndedAtMs: number | undefined;
+
+  // ── Live progress lines ──────────────────────────────────────────
+  //
+  // Populated by `appendProgress` whenever the tool emits an
+  // `onUpdate({kind:'status', text})` while still running. Used by
+  // long-blocking tools (e.g. the MCP `authenticate` synthetic tool
+  // whose 15-minute browser wait would otherwise display only a
+  // spinner). Cleared when the result lands — the result is the
+  // authoritative final state.
+  private progressLines: string[] = [];
+  private static readonly MAX_PROGRESS_LINES = 24;
+
+  /**
+   * Registered by a group container (`AgentGroupComponent` or
+   * `ReadGroupComponent`) when this component is borrowed as a hidden state
+   * container. Any state change (subagent meta, phase, sub-tool, result, etc.)
+   * triggers a throttled group re-render. `undefined` means no group is
+   * subscribed and standalone rendering is unaffected. A ToolCallComponent can
+   * only belong to one group at a time, so one listener slot is enough.
+   */
+  private onSnapshotChange: (() => void) | undefined;
+
+  constructor(
+    toolCall: ToolCallBlockData,
+    result: ToolResultBlockData | undefined,
+    colors: ColorPalette,
+    ui?: TUI,
+    markdownTheme?: MarkdownTheme,
+    private readonly workspaceDir?: string,
+  ) {
+    super();
+    this.toolCall = toolCall;
+    this.result = result;
+    this.colors = colors;
+    this.ui = ui;
+    this.markdownTheme = markdownTheme;
+    this.applySubagentReplay(toolCall.subagent);
+
+    this.addChild(new Spacer(1));
+    this.headerText = new Text(this.buildHeader(), 0, 0);
+    this.addChild(this.headerText);
+    this.buildCallPreview();
+    this.callPreviewEndIndex = this.children.length;
+    this.buildProgressBlock();
+    this.buildContent();
+    this.buildSubagentBlock();
+    this.syncStreamingProgressTimer();
+    this.syncSubagentElapsedTimer();
+  }
+
+  setExpanded(expanded: boolean): void {
+    if (this.expanded === expanded) return;
+    this.expanded = expanded;
+    // rebuildBody (not rebuildContent) so the args-driven call preview
+    // — which is what carries Write content / Edit diff — re-renders
+    // with the new line cap. rebuildContent only touches result-driven
+    // children and would leave the call preview stuck at its initial
+    // collapsed size.
+    this.rebuildBody();
+  }
+
+  // Toggle the plan box's expanded state independently from tool-output
+  // expansion. Returns true iff this card actually owns a plan preview
+  // (ExitPlanMode), so the caller can decide whether to consume the keystroke.
+  setPlanExpanded(expanded: boolean): boolean {
+    if (this.toolCall.name !== 'ExitPlanMode') return false;
+    if (this.planExpanded === expanded) return true;
+    this.planExpanded = expanded;
+    this.rebuildBody();
+    return true;
+  }
+
+  setResult(result: ToolResultBlockData): void {
+    this.result = result;
+    // Result supersedes any live progress chatter; the result body is the
+    // authoritative final state. Without this clear, a finished tool would
+    // show both the streamed status lines and the final output stacked.
+    this.progressLines = [];
+    this.finalizeSubagentElapsedIfNeeded();
+    this.syncStreamingProgressTimer();
+    this.syncSubagentElapsedTimer();
+    this.headerText.setText(this.buildHeader());
+    // rebuildBody (not rebuildContent) so the call preview re-renders
+    // with the collapsed cap applied — Write streaming previews and
+    // Edit's progress placeholder needs to snap to the final preview on
+    // result.
+    this.rebuildBody();
+    // Final results affect group summaries, especially failed/done counts.
+    this.notifySnapshotChange();
+  }
+
+  updateToolCall(toolCall: ToolCallBlockData): void {
+    this.toolCall = toolCall;
+    this.syncStreamingProgressTimer();
+    this.headerText.setText(this.buildHeader());
+    this.rebuildBody();
+    this.notifySnapshotChange();
+    this.ui?.requestRender();
+  }
+
+  /**
+   * Append a live progress line emitted by the tool via
+   * `onUpdate({kind:'status', text})`. Splits on newlines so multi-line
+   * status payloads render row-by-row. Old lines are dropped once the
+   * buffer fills past {@link ToolCallComponent.MAX_PROGRESS_LINES} so a
+   * misbehaving tool can't grow the box unboundedly.
+   */
+  appendProgress(text: string): void {
+    if (this.result !== undefined) return;
+    for (const line of text.split('\n')) {
+      this.progressLines.push(line);
+    }
+    while (this.progressLines.length > ToolCallComponent.MAX_PROGRESS_LINES) {
+      this.progressLines.shift();
+    }
+    this.rebuildBody();
+    this.notifySnapshotChange();
+    this.ui?.requestRender();
+  }
+
+  dispose(): void {
+    this.stopStreamingProgressTimer();
+    this.stopSubagentElapsedTimer();
+  }
+
+  /**
+   * Injects plan body/path asynchronously. Only ExitPlanMode cards use
+   * this: plan-file mode leaves `args.plan` empty, so `KimiTUI` fetches
+   * the plan via `session.getPlan()` and calls this method to render the
+   * plan box.
+   */
+  setPlanInfo(info: { plan?: string; path?: string }): void {
+    if (this.toolCall.name !== 'ExitPlanMode') return;
+    let changed = false;
+    if (info.plan !== undefined && info.plan.length > 0 && this.currentPlan !== info.plan) {
+      this.currentPlan = info.plan;
+      changed = true;
+    }
+    if (info.path !== undefined && info.path.length > 0 && this.planPath !== info.path) {
+      this.planPath = info.path;
+      changed = true;
+    }
+    if (!changed) return;
+    this.rebuildBody();
+    this.ui?.requestRender();
+  }
+
+  private applySubagentReplay(subagent: ToolCallBlockData['subagent']): void {
+    if (subagent === undefined) return;
+    this.subagentAgentId = subagent.id;
+    this.subagentAgentName = subagent.name;
+    this.subagentText = subagent.text ?? '';
+    for (const call of subagent.toolCalls ?? []) {
+      if (call.result === undefined) {
+        this.ongoingSubCalls.set(call.id, { name: call.name, args: call.args });
+        this.upsertSubToolActivity(call.id, call.name, call.args, 'ongoing');
+        continue;
+      }
+      this.finishedSubCalls.push({
+        name: call.name,
+        args: call.args,
+        output: call.result.output,
+        isError: call.result.is_error ?? false,
+      });
+      this.upsertSubToolActivity(
+        call.id,
+        call.name,
+        call.args,
+        call.result.is_error === true ? 'failed' : 'done',
+      );
+    }
+    while (this.finishedSubCalls.length > MAX_SUB_TOOL_CALLS_SHOWN) {
+      this.finishedSubCalls.shift();
+      this.hiddenSubCallCount += 1;
+    }
+  }
+
+  // ── Subagent API (called by KimiTUI event routing) ───────────────
+
+  setSubagentMeta(agentId: string, agentName?: string): void {
+    if (this.subagentAgentId === agentId && this.subagentAgentName === agentName) return;
+    this.subagentAgentId = agentId;
+    this.subagentAgentName = agentName;
+    this.headerText.setText(this.buildHeader());
+    this.rebuildContent();
+    this.notifySnapshotChange();
+    this.ui?.requestRender();
+  }
+
+  /**
+   * Lets group containers (AgentGroup or ReadGroup) subscribe to this card's
+   * state changes. Registration immediately calls back so the group receives
+   * the current snapshot without separately calling getSubagentSnapshot or
+   * getReadSnapshot. Pass `undefined` to unsubscribe.
+   */
+  setSnapshotListener(cb: (() => void) | undefined): void {
+    this.onSnapshotChange = cb;
+    if (cb !== undefined) cb();
+  }
+
+  getSubagentSnapshot(): ToolCallSubagentSnapshot {
+    const finished = this.finishedSubCalls.length + this.hiddenSubCallCount;
+    const tokens =
+      this.subagentUsage === undefined
+        ? 0
+        : usageInputTotal(this.subagentUsage) + this.subagentUsage.output;
+    const latestActivity = computeLatestActivity(
+      this.ongoingSubCalls,
+      this.finishedSubCalls,
+      this.getCombinedSubagentText(),
+      this.workspaceDir,
+    );
+    // Terminal-state priority: SDK `tool.result` is authoritative for Agent
+    // tool calls. Once it arrives, force done/failed over intermediate
+    // spawning/running states for two reasons:
+    //   1. Replay does not replay spawned/completed/failed events, so
+    //      `subagentPhase` stays undefined and result must be used.
+    //   2. Live type-validation failures may skip `subagent.failed`, or
+    //      `tool.result` may arrive first; otherwise the UI can stay stuck at
+    //      'spawning' and keep showing `Initializing...`.
+    // Intermediate states without a result still use `subagentPhase`.
+    // `backgrounded` has no result because background agents do not enter the
+    // transcript.
+    const derivedPhase: ToolCallSubagentSnapshot['phase'] =
+      this.result !== undefined ? (this.result.is_error ? 'failed' : 'done') : this.subagentPhase;
+    return {
+      toolCallId: this.toolCall.id,
+      toolName: this.toolCall.name,
+      toolCallDescription: str(this.toolCall.args['description']) || str(this.toolCall.description),
+      agentName: this.subagentAgentName,
+      phase: derivedPhase,
+      toolCount: finished,
+      tokens,
+      isError: derivedPhase === 'failed',
+      errorText:
+        this.subagentError ?? (derivedPhase === 'failed' ? this.result?.output : undefined),
+      latestActivity,
+    };
+  }
+
+  /**
+   * Used by `ReadGroupComponent` to sum line counts across same-step Read
+   * cards. `lines` matches the single-card chip
+   * (`pluralize(countNonEmptyLines(...), 'line')`) so group and card counts do
+   * not drift.
+   */
+  getReadSnapshot(): ToolCallReadSnapshot {
+    const args = this.toolCall.args;
+    const filePathRaw = args['file_path'] ?? args['path'];
+    const filePath =
+      typeof filePathRaw === 'string'
+        ? makeWorkspaceRelativePath(filePathRaw, this.workspaceDir)
+        : undefined;
+    if (this.result === undefined) {
+      return { toolCallId: this.toolCall.id, filePath, phase: 'pending', lines: 0 };
+    }
+    if (this.result.is_error === true) {
+      return { toolCallId: this.toolCall.id, filePath, phase: 'failed', lines: 0 };
+    }
+    return {
+      toolCallId: this.toolCall.id,
+      filePath,
+      phase: 'done',
+      lines: countNonEmptyLines(this.result.output),
+    };
+  }
+
+  // Readonly view for group access to toolCall metadata (id, name, description).
+  get toolCallView(): Readonly<ToolCallBlockData> {
+    return this.toolCall;
+  }
+
+  /** Notifies the listener when internal state changes, if a group is attached. */
+  private notifySnapshotChange(): void {
+    this.onSnapshotChange?.();
+  }
+
+  private upsertSubToolActivity(
+    id: string,
+    name: string,
+    args: Record<string, unknown>,
+    phase: SubToolActivity['phase'],
+  ): void {
+    const existing = this.subToolActivities.get(id);
+    if (existing !== undefined) {
+      existing.name = name;
+      existing.args = args;
+      existing.phase = phase;
+      return;
+    }
+    this.subToolActivities.set(id, {
+      id,
+      name,
+      args,
+      phase,
+      orderSeq: ++this.subToolOrderSeq,
+    });
+  }
+
+  private getCombinedSubagentText(): string {
+    return [this.subagentThinkingText, this.subagentText].filter((s) => s.length > 0).join('\n');
+  }
+
+  private isStreamingEditPreview(): boolean {
+    return (
+      this.toolCall.name === 'Edit' &&
+      this.result === undefined &&
+      this.toolCall.streamingArguments !== undefined
+    );
+  }
+
+  private syncStreamingProgressTimer(): void {
+    if (!this.isStreamingEditPreview()) {
+      this.stopStreamingProgressTimer();
+      return;
+    }
+    if (this.ui === undefined || this.streamingProgressTimer !== undefined) return;
+    this.streamingProgressTimer = setInterval(() => {
+      if (!this.isStreamingEditPreview()) {
+        this.stopStreamingProgressTimer();
+        return;
+      }
+      this.rebuildBody();
+      this.ui?.requestRender();
+    }, STREAMING_PROGRESS_INTERVAL_MS);
+  }
+
+  private stopStreamingProgressTimer(): void {
+    if (this.streamingProgressTimer === undefined) return;
+    clearInterval(this.streamingProgressTimer);
+    this.streamingProgressTimer = undefined;
+  }
+
+  private syncSubagentElapsedTimer(): void {
+    const phase = this.getDerivedSubagentPhase();
+    const shouldTick =
+      this.isSingleSubagentView() &&
+      this.subagentStartedAtMs !== undefined &&
+      (phase === 'spawning' || phase === 'running');
+    if (!shouldTick) {
+      this.stopSubagentElapsedTimer();
+      return;
+    }
+    if (this.ui === undefined || this.subagentElapsedTimer !== undefined) return;
+    this.subagentElapsedTimer = setInterval(() => {
+      const latestPhase = this.getDerivedSubagentPhase();
+      if (latestPhase !== 'spawning' && latestPhase !== 'running') {
+        this.stopSubagentElapsedTimer();
+        return;
+      }
+      this.headerText.setText(this.buildHeader());
+      this.invalidate();
+      this.ui?.requestRender();
+    }, SUBAGENT_ELAPSED_INTERVAL_MS);
+  }
+
+  private stopSubagentElapsedTimer(): void {
+    if (this.subagentElapsedTimer === undefined) return;
+    clearInterval(this.subagentElapsedTimer);
+    this.subagentElapsedTimer = undefined;
+  }
+
+  private finalizeSubagentElapsedIfNeeded(): void {
+    if (
+      this.toolCall.name === 'Agent' &&
+      this.subagentStartedAtMs !== undefined &&
+      this.subagentEndedAtMs === undefined
+    ) {
+      this.subagentEndedAtMs = Date.now();
+    }
+  }
+
+  /**
+   * Handles SDK `subagent.spawned`. The child agent is registered, but internal
+   * activity events (`assistant.delta` or `tool.call.started`) may not have
+   * arrived yet, so the UI moves to the 'spawning' placeholder state unless the
+   * agent is running in the background.
+   */
+  onSubagentSpawned(meta: {
+    agentId: string;
+    agentName?: string | undefined;
+    runInBackground: boolean;
+  }): void {
+    this.subagentAgentId = meta.agentId;
+    this.subagentAgentName = meta.agentName;
+    this.subagentPhase = meta.runInBackground ? 'backgrounded' : 'spawning';
+    this.subagentStartedAtMs = Date.now();
+    this.subagentEndedAtMs = undefined;
+    this.syncSubagentElapsedTimer();
+    this.headerText.setText(this.buildHeader());
+    this.rebuildContent();
+    this.notifySnapshotChange();
+    this.ui?.requestRender();
+  }
+
+  /**
+   * Handles SDK `subagent.completed`. Moves the phase to 'done' and records
+   * token usage plus the result summary for the header chip and tail summary.
+   */
+  onSubagentCompleted(payload: {
+    usage?: SubagentTokenUsage | undefined;
+    resultSummary: string;
+  }): void {
+    this.subagentPhase = 'done';
+    this.subagentEndedAtMs ??= Date.now();
+    this.subagentUsage = payload.usage;
+    this.subagentResultSummary =
+      payload.resultSummary.length > 0 ? payload.resultSummary : undefined;
+    if (this.subagentText.trim().length === 0 && this.subagentResultSummary !== undefined) {
+      this.subagentText = this.subagentResultSummary;
+    }
+    this.syncSubagentElapsedTimer();
+    this.headerText.setText(this.buildHeader());
+    this.rebuildContent();
+    this.notifySnapshotChange();
+    this.ui?.requestRender();
+  }
+
+  /** Handles SDK `subagent.failed`. */
+  onSubagentFailed(payload: { error: string }): void {
+    this.subagentPhase = 'failed';
+    this.subagentEndedAtMs ??= Date.now();
+    this.subagentError = payload.error;
+    this.syncSubagentElapsedTimer();
+    this.headerText.setText(this.buildHeader());
+    this.rebuildContent();
+    this.notifySnapshotChange();
+    this.ui?.requestRender();
+  }
+
+  appendSubagentText(text: string, kind: SubagentTextKind = 'text'): void {
+    if (kind === 'thinking') {
+      this.subagentThinkingText += text;
+    } else {
+      this.subagentText += text;
+    }
+    // Child-agent activity means it is running unless already terminal/backgrounded.
+    if (this.subagentPhase === undefined || this.subagentPhase === 'spawning') {
+      this.subagentPhase = 'running';
+    }
+    this.headerText.setText(this.buildHeader());
+    this.rebuildContent();
+    this.notifySnapshotChange();
+    this.ui?.requestRender();
+  }
+
+  appendSubToolCall(call: { id: string; name: string; args: Record<string, unknown> }): void {
+    const existing = this.ongoingSubCalls.get(call.id);
+    this.ongoingSubCalls.set(call.id, {
+      name: call.name,
+      args: call.args,
+      ...(existing?.streamingArguments !== undefined
+        ? { streamingArguments: existing.streamingArguments }
+        : {}),
+    });
+    this.upsertSubToolActivity(call.id, call.name, call.args, 'ongoing');
+    if (this.subagentPhase === undefined || this.subagentPhase === 'spawning') {
+      this.subagentPhase = 'running';
+    }
+    this.headerText.setText(this.buildHeader());
+    this.rebuildContent();
+    this.notifySnapshotChange();
+    this.ui?.requestRender();
+  }
+
+  appendSubToolCallDelta(delta: {
+    id: string;
+    name?: string | undefined;
+    argumentsPart: string | null;
+  }): void {
+    const existing = this.ongoingSubCalls.get(delta.id);
+    const nextArgsText = `${existing?.streamingArguments ?? ''}${delta.argumentsPart ?? ''}`;
+    const parsed = parseArgsPreview(nextArgsText);
+    this.ongoingSubCalls.set(delta.id, {
+      name: delta.name ?? existing?.name ?? 'Tool',
+      args: parsed,
+      streamingArguments: nextArgsText,
+    });
+    this.upsertSubToolActivity(delta.id, delta.name ?? existing?.name ?? 'Tool', parsed, 'ongoing');
+    this.headerText.setText(this.buildHeader());
+    this.rebuildContent();
+    this.notifySnapshotChange();
+    this.ui?.requestRender();
+  }
+
+  finishSubToolCall(result: {
+    tool_call_id: string;
+    output: string;
+    is_error?: boolean | undefined;
+  }): void {
+    const ongoing = this.ongoingSubCalls.get(result.tool_call_id);
+    if (ongoing === undefined) return;
+    this.ongoingSubCalls.delete(result.tool_call_id);
+    this.finishedSubCalls.push({
+      name: ongoing.name,
+      args: ongoing.args,
+      output: result.output,
+      isError: result.is_error ?? false,
+    });
+    this.upsertSubToolActivity(
+      result.tool_call_id,
+      ongoing.name,
+      ongoing.args,
+      result.is_error === true ? 'failed' : 'done',
+    );
+    while (this.finishedSubCalls.length > MAX_SUB_TOOL_CALLS_SHOWN) {
+      this.finishedSubCalls.shift();
+      this.hiddenSubCallCount += 1;
+    }
+    this.headerText.setText(this.buildHeader());
+    this.rebuildContent();
+    this.notifySnapshotChange();
+    this.ui?.requestRender();
+  }
+
+  private buildHeader(): string {
+    const { toolCall, result, colors } = this;
+    const isFinished = result !== undefined;
+    const isError = result?.is_error ?? false;
+    const isTruncated = toolCall.truncated === true && !isFinished;
+
+    let bullet: string;
+    if (isFinished) {
+      bullet = isError ? chalk.hex(colors.error)('✗ ') : chalk.hex(colors.success)(STATUS_BULLET);
+    } else if (isTruncated) {
+      bullet = chalk.hex(colors.error)('✗ ');
+    } else {
+      // Solid bullet for in-flight tools — the previous marker ↔ blank
+      // toggle caused visible flicker on every re-render.
+      bullet = chalk.hex(colors.roleAssistant)(STATUS_BULLET);
+    }
+
+    if (toolCall.name === 'ExitPlanMode') {
+      const label = chalk.hex(colors.primary).bold('Current plan');
+      if (!isFinished || result === undefined || result.is_error === true) {
+        return label;
+      }
+      const outcome = interpretExitPlanModeOutcome(result.output);
+      if (outcome.kind === 'approved') {
+        const chipText =
+          outcome.chosen !== undefined && outcome.chosen.length > 0
+            ? `Approved: ${outcome.chosen}`
+            : 'Approved';
+        return `${label}${chalk.hex(colors.success)(` · ${chipText}`)}`;
+      }
+      return `${label}${chalk.hex(colors.error)(' · Rejected')}`;
+    }
+
+    if (toolCall.name === 'AskUserQuestion') {
+      const label = isFinished
+        ? isError
+          ? 'Could not collect your input'
+          : 'Collected your answers'
+        : 'Waiting for your input';
+      const tone = isError ? chalk.hex(colors.error) : chalk.hex(colors.primary);
+      return `${bullet}${tone.bold(label)}`;
+    }
+
+    if (this.isSingleSubagentView()) {
+      return this.buildSingleSubagentHeader();
+    }
+
+    const verb = isFinished ? 'Used' : isTruncated ? 'Truncated' : 'Using';
+    const keyArg = extractKeyArgument(toolCall.name, toolCall.args, this.workspaceDir);
+    const decoded = decodeMcpToolName(toolCall.name);
+    const verbStyled = isTruncated
+      ? chalk.hex(colors.error)(verb)
+      : verb;
+    const toolLabel =
+      decoded !== null
+        ? `${chalk.hex(colors.primary).bold(decoded.toolName)}${chalk.dim(` · MCP/${decoded.serverName}`)}`
+        : chalk.hex(colors.primary).bold(toolCall.name);
+    const argStr = keyArg ? chalk.dim(` (${keyArg})`) : '';
+    let chipStr = '';
+    if (isFinished && result) chipStr = this.buildHeaderChip(result);
+    return `${bullet}${verbStyled} ${toolLabel}${argStr}${chipStr}`;
+  }
+
+  private buildHeaderChip(result: ToolResultBlockData): string {
+    const provider = pickChip(this.toolCall.name);
+    if (provider === undefined) return '';
+    const text = provider(this.toolCall, result);
+    if (text.length === 0) return '';
+    const tone = result.is_error ? chalk.hex(this.colors.error) : chalk.dim;
+    return tone(` · ${text}`);
+  }
+
+  private rebuildContent(): void {
+    while (this.children.length > this.callPreviewEndIndex) {
+      this.children.pop();
+    }
+    this.buildProgressBlock();
+    this.buildContent();
+    this.buildSubagentBlock();
+  }
+
+  private rebuildBody(): void {
+    while (this.children.length > 2) {
+      this.children.pop();
+    }
+    this.buildCallPreview();
+    this.callPreviewEndIndex = this.children.length;
+    this.buildProgressBlock();
+    this.buildContent();
+    this.buildSubagentBlock();
+  }
+
+  /**
+   * Render the accumulated `progressLines` between the call preview and
+   * the result body. URLs inside a line are wrapped in an OSC 8 hyperlink
+   * sequence so terminals that support it (iTerm2, Ghostty, kitty, modern
+   * Terminal.app, VS Code) make the URL Cmd-clickable and expose
+   * "Copy Link" via the context menu — even when pi-tui soft-wraps the
+   * URL across multiple rows (pi-tui's wrapTextWithAnsi re-opens the
+   * active OSC 8 link on each continuation line). Each embedded URL is
+   * styled individually so surrounding prose keeps its default dim tone.
+   */
+  private buildProgressBlock(): void {
+    if (this.progressLines.length === 0) return;
+    if (this.result !== undefined) return;
+    for (const raw of this.progressLines) {
+      if (raw.length === 0) {
+        this.addChild(new Text('', 2, 0));
+        continue;
+      }
+      PROGRESS_URL_RE.lastIndex = 0;
+      const styled = PROGRESS_URL_RE.test(raw)
+        ? raw.replace(PROGRESS_URL_RE, (url) => {
+          const visible = chalk.hex(this.colors.warning).underline(url);
+          return `\u001B]8;;${url}\u001B\\${visible}\u001B]8;;\u001B\\`;
+        })
+        : chalk.dim(raw);
+      PROGRESS_URL_RE.lastIndex = 0;
+      this.addChild(new Text(styled, 2, 0));
+    }
+  }
+
+  private buildSubagentBlock(): void {
+    if (
+      this.subagentAgentId === undefined &&
+      this.ongoingSubCalls.size === 0 &&
+      this.finishedSubCalls.length === 0 &&
+      this.subagentText.length === 0 &&
+      this.subagentPhase === undefined
+    ) {
+      return;
+    }
+
+    if (this.isSingleSubagentView()) {
+      this.buildSingleSubagentBlock();
+      return;
+    }
+
+    const dim = chalk.dim;
+    const phaseChip = this.formatPhaseChip();
+    const headerLabel =
+      this.subagentAgentName !== undefined
+        ? `subagent ${this.subagentAgentName} (${this.formatAgentId()})`
+        : `subagent (${this.formatAgentId()})`;
+    this.addChild(new Text(`  ${dim(`↳ ${headerLabel}`)}${phaseChip}`, 0, 0));
+
+    if (this.hiddenSubCallCount > 0) {
+      const suffix = this.hiddenSubCallCount > 1 ? 's' : '';
+      this.addChild(
+        new Text(
+          dim.italic(`    ${String(this.hiddenSubCallCount)} more tool call${suffix} ...`),
+          0,
+          0,
+        ),
+      );
+    }
+
+    for (const sub of this.finishedSubCalls) {
+      const mark = sub.isError
+        ? chalk.hex(this.colors.error)('✗')
+        : chalk.hex(this.colors.success)('•');
+      const keyArg = extractKeyArgument(sub.name, sub.args, this.workspaceDir);
+      const nameCol = chalk.hex(this.colors.primary)(sub.name);
+      const argCol = keyArg ? dim(` (${keyArg})`) : '';
+      this.addChild(new Text(`    ${mark} Used ${nameCol}${argCol}`, 0, 0));
+    }
+
+    for (const [id, call] of this.ongoingSubCalls) {
+      const keyArg = extractKeyArgument(call.name, call.args, this.workspaceDir);
+      const nameCol = chalk.hex(this.colors.primary)(call.name);
+      const argCol = keyArg ? dim(` (${keyArg})`) : '';
+      void id;
+      this.addChild(new Text(`    ${dim('…')} Using ${nameCol}${argCol}`, 0, 0));
+    }
+
+    if (this.subagentText.length > 0) {
+      const tailLines = this.subagentText.split('\n').slice(-3);
+      for (const line of tailLines) {
+        this.addChild(new Text(`    ${dim(line)}`, 0, 0));
+      }
+    }
+
+    // Result summary from subagent.completed.
+    if (this.subagentPhase === 'done' && this.subagentResultSummary !== undefined) {
+      const summaryLines = this.subagentResultSummary.split('\n').slice(0, 2);
+      for (const line of summaryLines) {
+        this.addChild(new Text(`    ${dim('└')} ${line}`, 0, 0));
+      }
+    }
+
+    // Full error text from subagent.failed; do not collapse it.
+    if (this.subagentPhase === 'failed' && this.subagentError !== undefined) {
+      const errLines = this.subagentError.split('\n');
+      for (const line of errLines) {
+        this.addChild(new Text(`    ${chalk.hex(this.colors.error)('└')} ${line}`, 0, 0));
+      }
+    }
+  }
+
+  /**
+   * Header phase/token chip. No chip is shown when phase is undefined.
+   *   spawning      -> starting
+   *   running       -> running
+   *   done          -> N tools, 8.4k tok
+   *   failed        -> failed
+   *   backgrounded  -> backgrounded
+   */
+  private formatPhaseChip(): string {
+    if (this.subagentPhase === undefined) return '';
+    const dim = chalk.dim;
+    const parts: string[] = [];
+    switch (this.subagentPhase) {
+      case 'spawning':
+        parts.push('↻ starting…');
+        break;
+      case 'running':
+        parts.push('↻ running');
+        break;
+      case 'done': {
+        parts.push(chalk.hex(this.colors.success)('✓ done'));
+        const toolCount = this.finishedSubCalls.length + this.hiddenSubCallCount;
+        if (toolCount > 0) parts.push(`${String(toolCount)} tool${toolCount > 1 ? 's' : ''}`);
+        const tokens = formatSubagentTokens(this.subagentUsage);
+        if (tokens !== undefined) parts.push(tokens);
+        break;
+      }
+      case 'failed':
+        parts.push(chalk.hex(this.colors.error)('✗ failed'));
+        break;
+      case 'backgrounded':
+        parts.push('◐ backgrounded');
+        break;
+    }
+    return parts.length > 0 ? dim(` · ${parts.join(' · ')}`) : '';
+  }
+
+  private formatAgentId(): string {
+    const id = this.subagentAgentId ?? '';
+    return id.length > 10 ? id.slice(0, 10) + '…' : id;
+  }
+
+  private hasSubagentState(): boolean {
+    return (
+      this.subagentAgentId !== undefined ||
+      this.ongoingSubCalls.size > 0 ||
+      this.finishedSubCalls.length > 0 ||
+      this.subToolActivities.size > 0 ||
+      this.subagentText.length > 0 ||
+      this.subagentThinkingText.length > 0 ||
+      this.subagentPhase !== undefined
+    );
+  }
+
+  private isSingleSubagentView(): boolean {
+    return this.toolCall.name === 'Agent' && this.hasSubagentState();
+  }
+
+  private getDerivedSubagentPhase():
+    | 'spawning'
+    | 'running'
+    | 'done'
+    | 'failed'
+    | 'backgrounded'
+    | undefined {
+    if (this.result !== undefined) return this.result.is_error ? 'failed' : 'done';
+    return this.subagentPhase;
+  }
+
+  private buildSingleSubagentHeader(): string {
+    const phase = this.getDerivedSubagentPhase();
+    const isFailed = phase === 'failed';
+    const isDone = phase === 'done';
+    const bullet = isFailed
+      ? chalk.hex(this.colors.error)('✗ ')
+      : isDone
+        ? chalk.hex(this.colors.success)(STATUS_BULLET)
+        : chalk.hex(this.colors.roleAssistant)(STATUS_BULLET);
+    const labelText = formatSubagentLabel(this.subagentAgentName);
+    const label = chalk.hex(this.colors.primary).bold(labelText);
+    const status = this.formatSingleSubagentStatus(phase);
+    const description = str(this.toolCall.args['description']);
+    const descriptionPlain = description.length > 0 ? ` (${description})` : '';
+    const descriptionText = descriptionPlain.length > 0 ? chalk.dim(descriptionPlain) : '';
+    const statsText = this.formatSingleSubagentStatsText();
+    if (isDone) {
+      const success = chalk.hex(this.colors.success);
+      return `${bullet}${success.bold(labelText)} ${success(`Completed${descriptionPlain}${statsText}`)}`;
+    }
+    const stats = chalk.dim(statsText);
+    return `${bullet}${label} ${status}${descriptionText}${stats}`;
+  }
+
+  private formatSingleSubagentStatus(
+    phase: 'spawning' | 'running' | 'done' | 'failed' | 'backgrounded' | undefined,
+  ): string {
+    switch (phase) {
+      case 'done':
+        return chalk.hex(this.colors.success)('Completed');
+      case 'failed':
+        return chalk.hex(this.colors.error)('Failed');
+      case 'running':
+        return chalk.hex(this.colors.primary)('Running');
+      case 'backgrounded':
+        return 'Backgrounded';
+      case 'spawning':
+      case undefined:
+        return chalk.hex(this.colors.primary)('Starting');
+    }
+  }
+
+  private formatSingleSubagentStatsText(): string {
+    const parts = [
+      `${String(this.subToolActivities.size)} tool${this.subToolActivities.size === 1 ? '' : 's'}`,
+    ];
+    const elapsed = this.getSubagentElapsedSeconds();
+    if (elapsed !== undefined) parts.push(formatElapsed(elapsed));
+    return ` · ${parts.join(' · ')}`;
+  }
+
+  private getSubagentElapsedSeconds(): number | undefined {
+    if (this.subagentStartedAtMs === undefined) return undefined;
+    const end = this.subagentEndedAtMs ?? Date.now();
+    return Math.max(0, Math.floor((end - this.subagentStartedAtMs) / 1000));
+  }
+
+  private buildSingleSubagentBlock(): void {
+    for (const activity of this.getRecentSubToolActivities()) {
+      const mark =
+        activity.phase === 'failed'
+          ? chalk.hex(this.colors.error)('✗')
+          : activity.phase === 'done'
+            ? chalk.hex(this.colors.success)('•')
+            : chalk.hex(this.colors.text)('•');
+      const verb = activity.phase === 'ongoing' ? 'Using' : 'Used';
+      this.addChild(new Text(`  ${mark} ${this.formatSubToolActivity(verb, activity)}`, 0, 0));
+    }
+
+    if (this.getDerivedSubagentPhase() === 'failed' && this.subagentError !== undefined) {
+      const errorLine = tailNonEmptyLines(this.subagentError, 1).at(-1);
+      if (errorLine !== undefined) {
+        this.addChild(
+          new PrefixedWrappedLine(
+            `  ${chalk.hex(this.colors.error)('└')} `,
+            '    ',
+            chalk.hex(this.colors.error)(errorLine),
+          ),
+        );
+      }
+      return;
+    }
+
+    const outputLine = tailNonEmptyLines(this.subagentText, 1).at(-1);
+    const thinkingLine = tailNonEmptyLines(this.subagentThinkingText, 1).at(-1);
+    if (this.getDerivedSubagentPhase() !== 'done' && thinkingLine !== undefined) {
+      this.addChild(
+        new PrefixedWrappedLine(`  ${chalk.dim('◌')} `, '    ', chalk.dim(thinkingLine)),
+      );
+    }
+    if (outputLine !== undefined) {
+      this.addChild(
+        new PrefixedWrappedLine(
+          `  ${chalk.hex(this.colors.text)('└')} `,
+          '    ',
+          chalk.hex(this.colors.text)(outputLine),
+        ),
+      );
+    }
+  }
+
+  private getRecentSubToolActivities(): SubToolActivity[] {
+    return [...this.subToolActivities.values()]
+      .toSorted((a, b) => a.orderSeq - b.orderSeq)
+      .slice(-MAX_SINGLE_SUBAGENT_TOOL_ROWS);
+  }
+
+  private formatSubToolActivity(verb: string, activity: SubToolActivity): string {
+    const keyArg = extractKeyArgument(activity.name, activity.args, this.workspaceDir);
+    const nameCol = chalk.hex(this.colors.primary)(activity.name);
+    const argCol = keyArg ? chalk.dim(` (${keyArg})`) : '';
+    return `${verb} ${nameCol}${argCol}`;
+  }
+
+  private buildCallPreview(): void {
+    const name = this.toolCall.name;
+    if (name === 'ExitPlanMode') {
+      this.buildPlanPreview();
+      return;
+    }
+    if (this.result === undefined && this.toolCall.truncated === true) {
+      this.addChild(
+        new Text(
+          chalk.dim('Tool call arguments truncated by max_tokens — call never executed.'),
+          2,
+          0,
+        ),
+      );
+      return;
+    }
+    if (this.result === undefined && this.toolCall.streamingArguments !== undefined) {
+      this.buildStreamingPreview(this.toolCall.streamingArguments);
+      return;
+    }
+    // Collapse only kicks in once the result lands (bullet turns
+    // green). Between args-finalize and result we may sit in approval
+    // for a while — keep the preview fully visible during that gap so
+    // the user reviews the full change in context.
+    const shouldCap = this.result !== undefined && !this.expanded;
+    if (name === 'Write') {
+      const content = str(this.toolCall.args['content']);
+      if (content.length === 0) return;
+      const filePath = str(this.toolCall.args['file_path'] ?? this.toolCall.args['path']);
+      const lang = langFromPath(filePath);
+      const allLines = highlightLines(content, lang);
+      const shown = shouldCap ? allLines.slice(0, COMMAND_PREVIEW_LINES) : allLines;
+      const remaining = allLines.length - shown.length;
+      for (const [i, line] of shown.entries()) {
+        const lineNum = chalk.dim(String(i + 1).padStart(4) + '  ');
+        this.addChild(new Text(lineNum + line, 2, 0));
+      }
+      if (shouldCap && remaining > 0) {
+        this.addChild(
+          new Text(
+            chalk.dim(
+              `... (${String(remaining)} more lines, ${String(allLines.length)} total, ctrl+o to expand)`,
+            ),
+            2,
+            0,
+          ),
+        );
+      }
+    } else if (name === 'Edit') {
+      const oldStr = str(this.toolCall.args['old_string']);
+      const newStr = str(this.toolCall.args['new_string']);
+      if (oldStr.length === 0 && newStr.length === 0) return;
+      const filePath = str(this.toolCall.args['file_path'] ?? this.toolCall.args['path']);
+      const lines = renderDiffLinesClustered(oldStr, newStr, filePath, this.colors, {
+        contextLines: 3,
+        ...(shouldCap ? { maxLines: COMMAND_PREVIEW_LINES } : {}),
+      });
+      for (const line of lines) {
+        this.addChild(new Text(line, 2, 0));
+      }
+    }
+  }
+
+  /**
+   * Live-rendering during the `tool.call.delta` streaming window.
+   *
+   * For tools we recognise, we reach into the partial JSON (via
+   * `extractPartialStringField`) and render a stable high-signal
+   * preview: Write's `content` as highlighted code, Edit's argument
+   * receive progress, Bash's `$ command`, etc. While args are still
+   * streaming we render the body in full (no 10-line cap) — once the
+   * result lands, the preview snaps to the collapsed cap unless the user
+   * has expanded.
+   */
+  private buildStreamingPreview(streamText: string): void {
+    const name = this.toolCall.name;
+    if (name === 'Write') {
+      const content = extractPartialStringField(streamText, 'content');
+      if (content === undefined || content.length === 0) return;
+      const filePath =
+        extractPartialStringField(streamText, 'file_path') ??
+        extractPartialStringField(streamText, 'path') ??
+        '';
+      const lang = langFromPath(filePath);
+      const allLines = highlightLines(content, lang);
+      for (const [i, line] of allLines.entries()) {
+        const lineNum = chalk.dim(String(i + 1).padStart(4) + '  ');
+        this.addChild(new Text(lineNum + line, 2, 0));
+      }
+      return;
+    }
+    if (name === 'Edit') {
+      const filePath =
+        extractPartialStringField(streamText, 'file_path') ??
+        extractPartialStringField(streamText, 'path') ??
+        '';
+      const bytes = Buffer.byteLength(streamText, 'utf8');
+      const startedAtMs = this.toolCall.streamingStartedAtMs;
+      const elapsedSeconds =
+        startedAtMs === undefined ? 0 : Math.max(0, Math.floor((Date.now() - startedAtMs) / 1000));
+      const target = filePath.length > 0 ? ` for ${filePath}` : '';
+      const progress = `Preparing changes${target}... ${formatByteSize(bytes)} · ${formatElapsed(
+        elapsedSeconds,
+      )} elapsed`;
+      this.addChild(new Text(chalk.dim(progress), 2, 0));
+      return;
+    }
+    if (name === 'Bash') {
+      const cmd = extractPartialStringField(streamText, 'command');
+      if (cmd === undefined || cmd.length === 0) return;
+      this.addChild(
+        new ShellExecutionComponent({
+          command: cmd,
+          colors: this.colors,
+          showCommand: true,
+          commandPreviewLines: COMMAND_PREVIEW_LINES,
+        }),
+      );
+    }
+    // Unknown tools: nothing sensible to stream without a schema, so
+    // leave the body blank and let the header do the talking.
+  }
+
+  private buildPlanPreview(): void {
+    // Priority: inline `args.plan`, approved plan parsed from result, then
+    // asynchronously injected currentPlan used while approval is in flight.
+    // Once a plan is found, PlanBoxComponent renders it. Without markdownTheme
+    // (unit tests), fall back to indented dim text so it remains visible.
+    const plan = this.resolvePlanForPreview();
+    if (plan.length === 0) return;
+    const path = this.resolvePlanPath();
+    if (this.markdownTheme !== undefined) {
+      this.addChild(
+        new PlanBoxComponent(plan, this.markdownTheme, this.colors.success, path, {
+          maxContentLines: this.computePlanBoxMaxContentLines(),
+          expanded: this.planExpanded,
+        }),
+      );
+    } else {
+      this.addChild(new Text(chalk.dim(plan), 2, 0));
+    }
+  }
+
+  private computePlanBoxMaxContentLines(): number | undefined {
+    const rows = this.ui?.terminal.rows;
+    if (rows === undefined || !Number.isFinite(rows) || rows <= 0) return undefined;
+    return Math.max(8, Math.floor(rows * 0.6) - 4);
+  }
+
+  private resolvePlanForPreview(): string {
+    const inlinePlan = str(this.toolCall.args['plan']);
+    if (inlinePlan.length > 0) return inlinePlan;
+    if (this.result !== undefined && !this.result.is_error) {
+      const approved = extractApprovedPlan(this.result.output);
+      if (approved.length > 0) return approved;
+    }
+    return this.currentPlan ?? '';
+  }
+
+  // Priority: approved result.output with 'Plan saved to: <path>', then the
+  // planPath asynchronously injected by setPlanInfo while approval is in flight.
+  private resolvePlanPath(): string | undefined {
+    if (this.result !== undefined && !this.result.is_error) {
+      const fromResult = interpretExitPlanModeOutcome(this.result.output).path;
+      if (fromResult !== undefined && fromResult.length > 0) return fromResult;
+    }
+    return this.planPath;
+  }
+
+  private buildContent(): void {
+    const { result } = this;
+    if (result === undefined || !result.output) return;
+
+    if (this.isSingleSubagentView()) {
+      return;
+    }
+
+    // Outputs that start with a `<system…>` tag are harness-injected
+    // reminders piggy-backing on a tool result. They are noise for the
+    // user, so suppress the body while keeping the header chip intact.
+    if (result.output.trimStart().startsWith('<system')) {
+      return;
+    }
+
+    if (this.toolCall.name === 'ExitPlanMode' && !result.is_error) {
+      // Approved plans are already rendered by buildCallPreview via
+      // resolvePlanForPreview. Rejected or revise feedback uses a warning label
+      // plus normal body text so it remains visible in the transcript.
+      const outcome = interpretExitPlanModeOutcome(result.output);
+      if (outcome.kind === 'rejected' && outcome.feedback !== undefined) {
+        const trimmed = outcome.feedback.trim();
+        if (trimmed.length > 0) {
+          const labelTone = chalk.hex(this.colors.warning).bold;
+          this.addChild(new Text(labelTone('↪ Suggestion'), 2, 0));
+          for (const line of trimmed.split('\n')) {
+            this.addChild(new Text(line, 4, 0));
+          }
+        }
+      }
+      return;
+    }
+
+    // TodoList: the authoritative list is shown in the dedicated
+    // TodoPanel before the input area, so repeating the text dump here is
+    // pure clutter. Keep the headline, drop the body.
+    if (this.toolCall.name === 'TodoList' && !result.is_error) {
+      return;
+    }
+
+    if (this.toolCall.name === 'EnterPlanMode' && !result.is_error) {
+      return;
+    }
+
+    if (
+      this.toolCall.name === 'AskUserQuestion' &&
+      !result.is_error &&
+      this.renderAskUserQuestionResult(result.output)
+    ) {
+      return;
+    }
+
+    const renderer = pickResultRenderer(this.toolCall.name);
+    const components = renderer(this.toolCall, result, {
+      expanded: this.expanded,
+      colors: this.colors,
+    });
+    for (const component of components) {
+      this.addChild(component);
+    }
+  }
+
+  /**
+   * Render AskUserQuestion's JSON payload as a friendly Q/A list.
+   * Returns true on success (caller skips the default JSON dump);
+   * false on parse failure (caller falls back to raw display).
+   */
+  private renderAskUserQuestionResult(output: string): boolean {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(output);
+    } catch {
+      return false;
+    }
+    if (typeof parsed !== 'object' || parsed === null) return false;
+
+    const colors = this.colors;
+    const dim = chalk.dim;
+    const accent = chalk.hex(colors.primary);
+
+    const answers = (parsed as { answers?: unknown }).answers;
+    const note = (parsed as { note?: unknown }).note;
+
+    const hasAnswers =
+      typeof answers === 'object' && answers !== null && Object.keys(answers).length > 0;
+
+    if (!hasAnswers) {
+      const noteText =
+        typeof note === 'string' && note.length > 0 ? note : 'User dismissed the question.';
+      this.addChild(new Text(dim(`  ${noteText}`), 0, 0));
+      return true;
+    }
+
+    for (const [question, answer] of Object.entries(answers as Record<string, unknown>)) {
+      const answerText = typeof answer === 'string' ? answer : JSON.stringify(answer);
+      this.addChild(new Text(`  ${dim('Q')}  ${question}`, 0, 0));
+      this.addChild(new Text(`  ${accent('→')}  ${answerText}`, 0, 0));
+    }
+    return true;
+  }
+}
+
+/**
+ * Computes the second-level "latest activity" line for group rows:
+ *   1. latest ongoing sub-tool (`Using {name} ({keyArg})`)
+ *   2. latest finished sub-tool (`Used {name} ({keyArg})`)
+ *   3. last non-empty line from accumulated subagent text
+ */
+function computeLatestActivity(
+  ongoing: ReadonlyMap<string, OngoingSubCall>,
+  finished: readonly FinishedSubCall[],
+  text: string,
+  workspaceDir?: string,
+): string | undefined {
+  if (ongoing.size > 0) {
+    const lastOngoing = [...ongoing.values()].at(-1);
+    if (lastOngoing !== undefined) {
+      return formatActivityLine('Using', lastOngoing.name, lastOngoing.args, workspaceDir);
+    }
+  }
+  if (finished.length > 0) {
+    const last = finished.at(-1);
+    if (last !== undefined) {
+      return formatActivityLine('Used', last.name, last.args, workspaceDir);
+    }
+  }
+  if (text.length > 0) {
+    const tail = text
+      .split('\n')
+      .toReversed()
+      .find((l) => l.trim().length > 0);
+    if (tail !== undefined) return tail.trim();
+  }
+  return undefined;
+}
+
+function formatActivityLine(
+  verb: string,
+  toolName: string,
+  args: Record<string, unknown>,
+  workspaceDir?: string,
+): string {
+  const keyArg = extractKeyArgument(toolName, args, workspaceDir);
+  return keyArg ? `${verb} ${toolName} (${keyArg})` : `${verb} ${toolName}`;
+}
diff --git a/apps/kimi-code/src/tui/components/messages/tool-renderers/chip.ts b/apps/kimi-code/src/tui/components/messages/tool-renderers/chip.ts
new file mode 100644
index 000000000..a0200a761
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/tool-renderers/chip.ts
@@ -0,0 +1,126 @@
+/**
+ * Header chip providers — produce a short "stat" suffix appended to the
+ * tool call header once a result has arrived. Chips own the *numeric*
+ * summary (line counts, exit codes, byte sizes), so summary renderers
+ * below don't repeat them.
+ *
+ * A chip returning `''` is suppressed; tools without an entry in the
+ * registry get no chip at all.
+ */
+
+import { computeDiffLines } from '#/tui/components/media/diff-preview';
+import type { ToolCallBlockData, ToolResultBlockData } from '#/tui/types';
+
+import { readMediaChip } from './media';
+import { strArg } from './types';
+
+export type ChipProvider = (toolCall: ToolCallBlockData, result: ToolResultBlockData) => string;
+
+export function countNonEmptyLines(text: string): number {
+  if (text.length === 0) return 0;
+  let n = 0;
+  for (const line of text.split('\n')) if (line.length > 0) n++;
+  return n;
+}
+
+function pluralize(n: number, singular: string, plural?: string): string {
+  return `${String(n)} ${n === 1 ? singular : (plural ?? `${singular}s`)}`;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${String(bytes)} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+export interface EditStats {
+  readonly added: number;
+  readonly removed: number;
+}
+
+export interface WriteStats {
+  readonly lines: number;
+}
+
+export function computeEditStats(args: Record<string, unknown>): EditStats {
+  const oldStr = strArg(args, 'old_string');
+  const newStr = strArg(args, 'new_string');
+  if (oldStr.length === 0 && newStr.length === 0) return { added: 0, removed: 0 };
+  const diff = computeDiffLines(oldStr, newStr);
+  let added = 0;
+  let removed = 0;
+  for (const line of diff) {
+    if (line.kind === 'add') added++;
+    else if (line.kind === 'delete') removed++;
+  }
+  return { added, removed };
+}
+
+export function computeWriteStats(args: Record<string, unknown>): WriteStats {
+  const content = strArg(args, 'content');
+  const normalized = content.endsWith('\n') ? content.slice(0, -1) : content;
+  const lines = normalized.length > 0 ? normalized.split('\n').length : 0;
+  return { lines };
+}
+
+export function formatEditChip(stats: EditStats): string {
+  const parts: string[] = [];
+  if (stats.added > 0) parts.push(`+${String(stats.added)}`);
+  if (stats.removed > 0) parts.push(`-${String(stats.removed)}`);
+  return parts.join(' ');
+}
+
+export function formatWriteChip(stats: WriteStats): string {
+  return pluralize(stats.lines, 'line');
+}
+
+const editChip: ChipProvider = (toolCall) => {
+  const stats = computeEditStats(toolCall.args);
+  if (stats.added === 0 && stats.removed === 0) return '';
+  return formatEditChip(stats);
+};
+
+const writeChip: ChipProvider = (toolCall) => formatWriteChip(computeWriteStats(toolCall.args));
+
+const readChip: ChipProvider = (_toolCall, result) =>
+  pluralize(countNonEmptyLines(result.output), 'line');
+
+const grepChip: ChipProvider = (_toolCall, result) => {
+  const matches = countNonEmptyLines(result.output);
+  if (matches === 0) return 'no matches';
+  return pluralize(matches, 'match', 'matches');
+};
+
+const globChip: ChipProvider = (_toolCall, result) => {
+  const files = countNonEmptyLines(result.output);
+  if (files === 0) return 'no files';
+  return pluralize(files, 'file');
+};
+
+const fetchChip: ChipProvider = (_toolCall, result) =>
+  formatBytes(Buffer.byteLength(result.output, 'utf8'));
+
+const webSearchChip: ChipProvider = (_toolCall, result) => {
+  const lines = result.output.split('\n').filter((l) => l.trim().length > 0);
+  let count = 0;
+  for (const line of lines) {
+    if (/^\s*(\d+\.|[-*])\s+/.test(line)) count++;
+  }
+  if (count === 0) return lines.length === 0 ? 'no results' : 'web result';
+  return pluralize(count, 'result');
+};
+
+const REGISTRY: Record<string, ChipProvider> = {
+  Edit: editChip,
+  Write: writeChip,
+  Read: readChip,
+  ReadMediaFile: readMediaChip,
+  Grep: grepChip,
+  Glob: globChip,
+  FetchURL: fetchChip,
+  WebSearch: webSearchChip,
+};
+
+export function pickChip(toolName: string): ChipProvider | undefined {
+  return REGISTRY[toolName];
+}
diff --git a/apps/kimi-code/src/tui/components/messages/tool-renderers/media.ts b/apps/kimi-code/src/tui/components/messages/tool-renderers/media.ts
new file mode 100644
index 000000000..fd753cd27
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/tool-renderers/media.ts
@@ -0,0 +1,152 @@
+/**
+ * ReadMediaFile renderer.
+ *
+ * The ReadMediaFile tool `output` is the JSON-serialized array of
+ * content parts the tool returned — which includes the full base64 of
+ * the image/video. Dumping that string into the transcript blasts a
+ * multi-screen blob of base64. This renderer parses the envelope and
+ * surfaces just the human-readable bits (kind, path, mime, size) via
+ * a header chip + a tiny expanded body. It never emits the base64.
+ *
+ * On error, or when the output isn't the expected media envelope, we
+ * fall back to the truncated renderer so the user still sees the raw
+ * message.
+ */
+
+import type { Component } from '@earendil-works/pi-tui';
+import { Text } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ChipProvider } from './chip';
+import { renderTruncated } from './truncated';
+import type { ResultRenderer } from './types';
+
+export interface ReadMediaSummary {
+  kind: 'image' | 'video';
+  path?: string;
+  mimeType?: string;
+  bytes?: number;
+  url?: string;
+  originalSize?: string;
+}
+
+const PATH_TAG_RE = /^<(image|video)\s+path="([^"]+)">$/;
+const ORIGINAL_SIZE_RE = /original size\s+(\d+x\d+px)/;
+const DATA_URL_RE = /^data:([^;]+);base64,(.*)$/s;
+
+function bytesFromBase64(b64: string): number {
+  const len = b64.length;
+  if (len === 0) return 0;
+  const padding = b64.endsWith('==') ? 2 : b64.endsWith('=') ? 1 : 0;
+  return Math.floor((len * 3) / 4) - padding;
+}
+
+export function parseReadMediaOutput(output: string): ReadMediaSummary | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(output);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(parsed)) return null;
+
+  let kind: 'image' | 'video' | undefined;
+  let path: string | undefined;
+  let mimeType: string | undefined;
+  let bytes: number | undefined;
+  let url: string | undefined;
+  let originalSize: string | undefined;
+  let foundMedia = false;
+
+  for (const raw of parsed) {
+    if (typeof raw !== 'object' || raw === null) continue;
+    const part = raw as Record<string, unknown>;
+    const type = part['type'];
+
+    if (type === 'text' && typeof part['text'] === 'string') {
+      const text = part['text'];
+      const tag = PATH_TAG_RE.exec(text);
+      if (tag) {
+        kind = tag[1] as 'image' | 'video';
+        path = tag[2];
+        continue;
+      }
+      const size = ORIGINAL_SIZE_RE.exec(text);
+      if (size) originalSize = size[1];
+      continue;
+    }
+
+    if (type === 'image_url' || type === 'video_url') {
+      foundMedia = true;
+      kind = type === 'image_url' ? 'image' : 'video';
+      const holder = part[type === 'image_url' ? 'imageUrl' : 'videoUrl'];
+      if (typeof holder === 'object' && holder !== null) {
+        const h = holder as Record<string, unknown>;
+        const u = h['url'];
+        if (typeof u === 'string') {
+          const data = DATA_URL_RE.exec(u);
+          if (data && data[1] !== undefined && data[2] !== undefined) {
+            mimeType = data[1];
+            bytes = bytesFromBase64(data[2]);
+          } else {
+            url = u;
+          }
+        }
+      }
+    }
+  }
+
+  if (!foundMedia || kind === undefined) return null;
+
+  const summary: ReadMediaSummary = { kind };
+  if (path !== undefined) summary.path = path;
+  if (mimeType !== undefined) summary.mimeType = mimeType;
+  if (bytes !== undefined) summary.bytes = bytes;
+  if (url !== undefined) summary.url = url;
+  if (originalSize !== undefined) summary.originalSize = originalSize;
+  return summary;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${String(bytes)} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+function metaSegments(summary: ReadMediaSummary): string[] {
+  const segs: string[] = [];
+  if (summary.mimeType !== undefined) segs.push(summary.mimeType);
+  if (summary.bytes !== undefined) segs.push(formatBytes(summary.bytes));
+  if (summary.originalSize !== undefined) segs.push(summary.originalSize);
+  return segs;
+}
+
+export const readMediaChip: ChipProvider = (_toolCall, result) => {
+  if (result.is_error) return '';
+  const summary = parseReadMediaOutput(result.output);
+  if (summary === null) return '';
+  const meta = metaSegments(summary);
+  if (meta.length === 0) {
+    return summary.url !== undefined ? `${summary.kind} · uploaded` : summary.kind;
+  }
+  return `${summary.kind} (${meta.join(', ')})`;
+};
+
+export const readMediaSummary: ResultRenderer = (toolCall, result, ctx) => {
+  if (result.is_error) return renderTruncated(toolCall, result, ctx);
+  const summary = parseReadMediaOutput(result.output);
+  if (summary === null) return renderTruncated(toolCall, result, ctx);
+  if (!ctx.expanded) return [];
+
+  const dim = chalk.dim;
+  const out: Component[] = [];
+  if (summary.path !== undefined) {
+    out.push(new Text(`  ${dim(summary.path)}`, 0, 0));
+  }
+  const meta = metaSegments(summary);
+  const tail: string[] = [summary.kind];
+  if (meta.length > 0) tail.push(meta.join(', '));
+  if (summary.url !== undefined) tail.push(summary.url);
+  out.push(new Text(`  ${dim(tail.join(' · '))}`, 0, 0));
+  return out;
+};
diff --git a/apps/kimi-code/src/tui/components/messages/tool-renderers/registry.ts b/apps/kimi-code/src/tui/components/messages/tool-renderers/registry.ts
new file mode 100644
index 000000000..2d59b805b
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/tool-renderers/registry.ts
@@ -0,0 +1,55 @@
+/**
+ * Tool result renderer registry.
+ *
+ * Each tool name maps to a `ResultRenderer` that turns the tool's
+ * `ToolResultBlockData` into renderable Components. Tools without an
+ * explicit entry fall through to `renderTruncated` (the original
+ * 3-line + ctrl+o behavior).
+ *
+ * Keep this dispatch flat — tool names live next to the renderer they
+ * choose, so adding a new tool means appending one case.
+ */
+
+import { readMediaSummary } from './media';
+import { shellExecutionResultRenderer } from '../shell-execution';
+import {
+  editSummary,
+  fetchSummary,
+  globSummary,
+  grepSummary,
+  readSummary,
+  thinkSummary,
+  webSearchSummary,
+  writeSummary,
+} from './summary';
+import { renderTruncated } from './truncated';
+import type { ResultRenderer } from './types';
+
+export function pickResultRenderer(toolName: string): ResultRenderer {
+  switch (toolName) {
+    case 'Read':
+      return readSummary;
+    case 'ReadMediaFile':
+      return readMediaSummary;
+    case 'Grep':
+      return grepSummary;
+    case 'Glob':
+      return globSummary;
+    case 'FetchURL':
+      return fetchSummary;
+    case 'WebSearch':
+      return webSearchSummary;
+    case 'Bash':
+      return shellExecutionResultRenderer;
+    case 'Think':
+      return thinkSummary;
+    case 'Edit':
+      return editSummary;
+    case 'Write':
+      return writeSummary;
+    default:
+      return renderTruncated;
+  }
+}
+
+export type { ResultRenderer } from './types';
diff --git a/apps/kimi-code/src/tui/components/messages/tool-renderers/summary.ts b/apps/kimi-code/src/tui/components/messages/tool-renderers/summary.ts
new file mode 100644
index 000000000..a3f929dcc
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/tool-renderers/summary.ts
@@ -0,0 +1,91 @@
+/**
+ * Summary-style renderers — produce optional inline-glance content for
+ * tools whose raw output is high-volume but low-information (Grep,
+ * Glob). The numeric summary (line counts, exit codes, sizes) lives in
+ * the header chip (see chip.ts), so most tools intentionally render an
+ * empty body and only expose details when the global expand toggle is
+ * on.
+ *
+ * Errors always fall through to the truncated renderer so the user
+ * sees the actual error message, not a synthetic summary.
+ */
+
+import type { Component } from '@earendil-works/pi-tui';
+import { Text } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import { renderTruncated } from './truncated';
+import type { ResultRenderer } from './types';
+
+const GLANCE_SAMPLES = 3;
+
+type GlanceFn = (
+  toolCall: Parameters<ResultRenderer>[0],
+  result: Parameters<ResultRenderer>[1],
+) => string;
+
+function withGlance(glance: GlanceFn | null): ResultRenderer {
+  return (toolCall, result, ctx) => {
+    if (result.is_error) return renderTruncated(toolCall, result, ctx);
+
+    const out: Component[] = [];
+    if (glance !== null) {
+      const line = glance(toolCall, result);
+      if (line.length > 0) {
+        out.push(new Text(`  ${chalk.dim(line)}`, 0, 0));
+      }
+    }
+    if (ctx.expanded && result.output.length > 0) {
+      out.push(new Text(chalk.dim(result.output), 4, 0));
+    }
+    return out;
+  };
+}
+
+function nonEmptyLines(text: string): string[] {
+  if (text.length === 0) return [];
+  return text.split('\n').filter((line) => line.length > 0);
+}
+
+// Strip a trailing `:line:col:text` so the glance shows the file path
+// only, even when grep is in `content` mode (`src/foo.ts:42:    foo()`).
+function pathFromGrepLine(line: string): string {
+  const idx = line.indexOf(':');
+  if (idx <= 0) return line;
+  const second = line.indexOf(':', idx + 1);
+  if (second <= 0) return line;
+  return line.slice(0, second);
+}
+
+const grepGlance: GlanceFn = (_toolCall, result) => {
+  const lines = nonEmptyLines(result.output);
+  if (lines.length === 0) return '';
+  const samples = lines.slice(0, GLANCE_SAMPLES).map(pathFromGrepLine);
+  const remaining = lines.length - samples.length;
+  const tail = remaining > 0 ? `, +${String(remaining)} more` : '';
+  return `${samples.join(', ')}${tail}`;
+};
+
+const globGlance: GlanceFn = (_toolCall, result) => {
+  const lines = nonEmptyLines(result.output);
+  if (lines.length === 0) return '';
+  const samples = lines.slice(0, GLANCE_SAMPLES);
+  const remaining = lines.length - samples.length;
+  const tail = remaining > 0 ? `, +${String(remaining)} more` : '';
+  return `${samples.join(', ')}${tail}`;
+};
+
+// ── Exports ──────────────────────────────────────────────────────────
+
+// Tools whose chip already conveys everything — the body is empty in
+// the collapsed state and only the raw output appears when expanded.
+export const readSummary: ResultRenderer = withGlance(null);
+export const fetchSummary: ResultRenderer = withGlance(null);
+export const webSearchSummary: ResultRenderer = withGlance(null);
+export const thinkSummary: ResultRenderer = withGlance(null);
+export const editSummary: ResultRenderer = withGlance(null);
+export const writeSummary: ResultRenderer = withGlance(null);
+
+// Tools that benefit from inline path samples below the chip.
+export const grepSummary: ResultRenderer = withGlance(grepGlance);
+export const globSummary: ResultRenderer = withGlance(globGlance);
diff --git a/apps/kimi-code/src/tui/components/messages/tool-renderers/truncated.ts b/apps/kimi-code/src/tui/components/messages/tool-renderers/truncated.ts
new file mode 100644
index 000000000..2bd9cf01b
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/tool-renderers/truncated.ts
@@ -0,0 +1,22 @@
+import type { Component } from '@earendil-works/pi-tui';
+import { Text } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { ResultRenderer } from './types';
+import { PREVIEW_LINES } from './types';
+
+export const renderTruncated: ResultRenderer = (_toolCall, result, ctx) => {
+  if (!result.output) return [];
+  const tint = result.is_error ? chalk.hex(ctx.colors.error) : chalk.dim;
+  const lines = result.output.split('\n');
+  if (ctx.expanded) {
+    return [new Text(tint(result.output), 2, 0)];
+  }
+  const shown = lines.slice(0, PREVIEW_LINES);
+  const remaining = lines.length - shown.length;
+  const out: Component[] = [new Text(tint(shown.join('\n')), 2, 0)];
+  if (remaining > 0) {
+    out.push(new Text(chalk.dim(`... (${String(remaining)} more lines, ctrl+o to expand)`), 2, 0));
+  }
+  return out;
+};
diff --git a/apps/kimi-code/src/tui/components/messages/tool-renderers/types.ts b/apps/kimi-code/src/tui/components/messages/tool-renderers/types.ts
new file mode 100644
index 000000000..462b53a44
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/tool-renderers/types.ts
@@ -0,0 +1,26 @@
+import type { Component } from '@earendil-works/pi-tui';
+
+import { RESULT_PREVIEW_LINES } from '#/tui/constant/rendering';
+import type { ColorPalette } from '#/tui/theme/colors';
+import type { ToolCallBlockData, ToolResultBlockData } from '#/tui/types';
+
+export interface RendererContext {
+  readonly expanded: boolean;
+  readonly colors: ColorPalette;
+}
+
+export type ResultRenderer = (
+  toolCall: ToolCallBlockData,
+  result: ToolResultBlockData,
+  ctx: RendererContext,
+) => Component[];
+
+export const PREVIEW_LINES = RESULT_PREVIEW_LINES;
+
+export function strArg(args: Record<string, unknown>, ...keys: string[]): string {
+  for (const key of keys) {
+    const v = args[key];
+    if (typeof v === 'string' && v.length > 0) return v;
+  }
+  return '';
+}
diff --git a/apps/kimi-code/src/tui/components/messages/usage-panel.ts b/apps/kimi-code/src/tui/components/messages/usage-panel.ts
new file mode 100644
index 000000000..4db3d8c88
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/usage-panel.ts
@@ -0,0 +1,246 @@
+/**
+ * UsagePanelComponent — wraps pre-coloured `/usage` lines in a blue box
+ * border with a left indent, mirroring the PlanBoxComponent layout so
+ * the pattern stays consistent across command-triggered panels.
+ */
+
+import type { Component } from '@earendil-works/pi-tui';
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import type { SessionUsage, TokenUsage } from '@moonshot-ai/kimi-code-sdk';
+import chalk from 'chalk';
+
+import {
+  formatTokenCount,
+  ratioSeverity,
+  renderProgressBar,
+  safeUsageRatio,
+} from '#/utils/usage/usage-format';
+import type { ColorPalette } from '#/tui/theme/colors';
+
+const LEFT_MARGIN = 2;
+const SIDE_PADDING = 1;
+const MIN_INTERIOR_WIDTH = 20;
+
+type Colorize = (text: string) => string;
+
+export interface ManagedUsageRow {
+  readonly label: string;
+  readonly used: number;
+  readonly limit: number;
+  readonly resetHint?: string;
+}
+
+export interface ManagedUsageReport {
+  readonly summary: ManagedUsageRow | null;
+  readonly limits: readonly ManagedUsageRow[];
+}
+
+export interface UsageReportOptions {
+  readonly colors: ColorPalette;
+  readonly sessionUsage?: SessionUsage;
+  readonly sessionUsageError?: string;
+  readonly contextUsage: number;
+  readonly contextTokens: number;
+  readonly maxContextTokens: number;
+  readonly managedUsage?: ManagedUsageReport;
+  readonly managedUsageError?: string;
+}
+
+export interface ManagedUsageReportLineOptions {
+  readonly colors: ColorPalette;
+  readonly managedUsage?: ManagedUsageReport;
+  readonly managedUsageError?: string;
+}
+
+function usageNumber(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function usageInputTotal(usage: TokenUsage): number {
+  return (
+    usageNumber(usage.inputOther) +
+    usageNumber(usage.inputCacheRead) +
+    usageNumber(usage.inputCacheCreation)
+  );
+}
+
+function buildSessionUsageSection(
+  usage: SessionUsage | undefined,
+  error: string | undefined,
+  value: Colorize,
+  muted: Colorize,
+  errorStyle: Colorize,
+): string[] {
+  if (error !== undefined) return [errorStyle(`  ${error}`)];
+  const byModel = (usage as { readonly byModel?: Record<string, TokenUsage> } | undefined)
+    ?.byModel;
+  const entries = Object.entries(byModel ?? {});
+  if (entries.length === 0) return [muted('  No token usage recorded yet.')];
+
+  const lines: string[] = [];
+  let totalInput = 0;
+  let totalOutput = 0;
+  for (const [model, row] of entries) {
+    const input = usageInputTotal(row);
+    const output = usageNumber(row.output);
+    totalInput += input;
+    totalOutput += output;
+    lines.push(
+      `  ${muted(model)}  input ${value(formatTokenCount(input))}  output ${value(
+        formatTokenCount(output),
+      )}  total ${value(formatTokenCount(input + output))}`,
+    );
+  }
+  if (entries.length > 1) {
+    lines.push(
+      `  ${muted('total')}  input ${value(formatTokenCount(totalInput))}  output ${value(
+        formatTokenCount(totalOutput),
+      )}  total ${value(formatTokenCount(totalInput + totalOutput))}`,
+    );
+  }
+  return lines;
+}
+
+function buildManagedUsageSection(
+  usage: ManagedUsageReport | undefined,
+  error: string | undefined,
+  accent: Colorize,
+  value: Colorize,
+  muted: Colorize,
+  errorStyle: Colorize,
+  severityHex: (sev: 'ok' | 'warn' | 'danger') => string,
+): string[] {
+  if (error !== undefined) return [accent('Plan usage'), errorStyle(`  ${error}`)];
+  if (usage === undefined) return [];
+  const { summary, limits } = usage;
+  if (summary === null && limits.length === 0) {
+    return [accent('Plan usage'), muted('  No usage data available.')];
+  }
+
+  const rows: ManagedUsageRow[] = [];
+  if (summary !== null) rows.push(summary);
+  rows.push(...limits);
+  const labelWidth = Math.max(10, ...rows.map((r) => r.label.length));
+  const out: string[] = [accent('Plan usage')];
+  for (const row of rows) {
+    const ratioUsed = row.limit > 0 ? row.used / row.limit : 0;
+    const leftRatio = 1 - Math.max(0, Math.min(ratioUsed, 1));
+    const bar = renderProgressBar(Math.max(0, Math.min(ratioUsed, 1)), 20);
+    const pct = `${Math.round(leftRatio * 100)}% left`;
+    const barColoured = chalk.hex(severityHex(ratioSeverity(ratioUsed)))(bar);
+    const label = row.label.padEnd(labelWidth, ' ');
+    const resetStr = row.resetHint ? muted(` (${row.resetHint})`) : '';
+    out.push(`  ${muted(label)}  ${barColoured}  ${value(pct)}${resetStr}`);
+  }
+  return out;
+}
+
+export function buildManagedUsageReportLines(options: ManagedUsageReportLineOptions): string[] {
+  const colors = options.colors;
+  const accent = chalk.hex(colors.primary).bold;
+  const value = chalk.hex(colors.text);
+  const muted = chalk.hex(colors.textDim);
+  const errorStyle = chalk.hex(colors.error);
+  const severityHex = (sev: 'ok' | 'warn' | 'danger'): string =>
+    sev === 'danger' ? colors.error : sev === 'warn' ? colors.warning : colors.success;
+
+  return buildManagedUsageSection(
+    options.managedUsage,
+    options.managedUsageError,
+    accent,
+    value,
+    muted,
+    errorStyle,
+    severityHex,
+  );
+}
+
+export function buildUsageReportLines(options: UsageReportOptions): string[] {
+  const colors = options.colors;
+  const accent = chalk.hex(colors.primary).bold;
+  const value = chalk.hex(colors.text);
+  const muted = chalk.hex(colors.textDim);
+  const errorStyle = chalk.hex(colors.error);
+  const severityHex = (sev: 'ok' | 'warn' | 'danger'): string =>
+    sev === 'danger' ? colors.error : sev === 'warn' ? colors.warning : colors.success;
+
+  const lines: string[] = [
+    accent('Session usage'),
+    ...buildSessionUsageSection(
+      options.sessionUsage,
+      options.sessionUsageError,
+      value,
+      muted,
+      errorStyle,
+    ),
+  ];
+
+  if (options.maxContextTokens > 0) {
+    const ratio = safeUsageRatio(options.contextUsage);
+    const bar = renderProgressBar(ratio, 20);
+    const pct = `${(ratio * 100).toFixed(1)}%`;
+    const barColoured = chalk.hex(severityHex(ratioSeverity(ratio)))(bar);
+    lines.push('');
+    lines.push(accent('Context window'));
+    lines.push(
+      `  ${barColoured}  ${value(pct.padStart(6, ' '))}  ` +
+        muted(
+          `(${formatTokenCount(options.contextTokens)} / ${formatTokenCount(
+            options.maxContextTokens,
+          )})`,
+        ),
+    );
+  }
+
+  const managedSection = buildManagedUsageReportLines({
+    colors,
+    managedUsage: options.managedUsage,
+    managedUsageError: options.managedUsageError,
+  });
+  if (managedSection.length > 0) {
+    lines.push('');
+    lines.push(...managedSection);
+  }
+
+  return lines;
+}
+
+export class UsagePanelComponent implements Component {
+  constructor(
+    private readonly lines: readonly string[],
+    private readonly borderHex: string,
+    private readonly title: string = ' Usage ',
+  ) {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const paint = (s: string): string => chalk.hex(this.borderHex)(s);
+    const indent = ' '.repeat(LEFT_MARGIN);
+
+    const availableInterior = Math.max(
+      MIN_INTERIOR_WIDTH,
+      width - LEFT_MARGIN - 2 - 2 * SIDE_PADDING,
+    );
+    const longestLine = this.lines.reduce((max, line) => Math.max(max, visibleWidth(line)), 0);
+    const contentWidth = Math.max(
+      MIN_INTERIOR_WIDTH,
+      Math.min(availableInterior, longestLine, Math.max(longestLine, this.title.length)),
+    );
+    const horzLen = contentWidth + 2 * SIDE_PADDING;
+
+    const trailingDashLen = Math.max(0, horzLen - this.title.length);
+    const top =
+      indent + paint('╭') + paint(this.title) + paint('─'.repeat(trailingDashLen)) + paint('╮');
+    const bottom = indent + paint('╰' + '─'.repeat(horzLen) + '╯');
+
+    const out: string[] = [top];
+    for (const line of this.lines) {
+      const clipped = visibleWidth(line) > contentWidth ? truncateToWidth(line, contentWidth) : line;
+      const pad = Math.max(0, contentWidth - visibleWidth(clipped));
+      out.push(indent + paint('│') + ' ' + clipped + ' '.repeat(pad) + ' ' + paint('│'));
+    }
+    out.push(bottom);
+    return out;
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/messages/user-message.ts b/apps/kimi-code/src/tui/components/messages/user-message.ts
new file mode 100644
index 000000000..8617598a0
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/messages/user-message.ts
@@ -0,0 +1,63 @@
+/**
+ * Renders a user message in the transcript.
+ */
+
+import type { Component } from '@earendil-works/pi-tui';
+import { Spacer, Text, visibleWidth } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import { ImageThumbnail } from '#/tui/components/media/image-thumbnail';
+import { USER_MESSAGE_BULLET } from '#/tui/constant/symbols';
+import type { ColorPalette } from '#/tui/theme/colors';
+import type { ImageAttachment } from '#/tui/utils/image-attachment-store';
+
+export class UserMessageComponent implements Component {
+  private color: string;
+  private textComponent: Text;
+  private spacerComponent: Spacer;
+  private imageThumbnails: ImageThumbnail[];
+
+  constructor(text: string, colors: ColorPalette, images?: ImageAttachment[]) {
+    this.color = colors.roleUser;
+    this.textComponent = new Text(chalk.hex(colors.roleUser).bold(text), 0, 0);
+    this.spacerComponent = new Spacer(1);
+    this.imageThumbnails = images?.map((img) => new ImageThumbnail(img, colors)) ?? [];
+  }
+
+  invalidate(): void {
+    this.textComponent.invalidate();
+    for (const img of this.imageThumbnails) {
+      img.invalidate?.();
+    }
+  }
+
+  render(width: number): string[] {
+    const bullet = chalk.hex(this.color).bold(USER_MESSAGE_BULLET);
+    const bulletWidth = visibleWidth(bullet);
+    const contentWidth = Math.max(1, width - bulletWidth);
+
+    const lines: string[] = [];
+
+    // Spacer
+    for (const line of this.spacerComponent.render(width)) {
+      lines.push(line);
+    }
+
+    // Text
+    const textLines = this.textComponent.render(contentWidth);
+    for (let i = 0; i < textLines.length; i++) {
+      const prefix = i === 0 ? bullet : ' '.repeat(bulletWidth);
+      lines.push(prefix + textLines[i]);
+    }
+
+    // Images — indented to align with text after the bullet
+    for (const thumbnail of this.imageThumbnails) {
+      const imageLines = thumbnail.render(contentWidth);
+      for (const line of imageLines) {
+        lines.push(' '.repeat(bulletWidth) + line);
+      }
+    }
+
+    return lines;
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/panes/activity-pane.ts b/apps/kimi-code/src/tui/components/panes/activity-pane.ts
new file mode 100644
index 000000000..2a1d8ea1d
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/panes/activity-pane.ts
@@ -0,0 +1,29 @@
+import { Container, Spacer } from '@earendil-works/pi-tui';
+
+import type { MoonLoader } from '../chrome/moon-loader';
+
+export type ActivityPaneMode = 'hidden' | 'waiting' | 'thinking' | 'composing' | 'tool';
+
+export interface ActivityPaneOptions {
+  readonly mode: ActivityPaneMode;
+  readonly spinner?: MoonLoader;
+}
+
+export class ActivityPaneComponent extends Container {
+  constructor(options: ActivityPaneOptions) {
+    super();
+
+    if (options.mode === 'waiting' || options.mode === 'tool') {
+      if (options.spinner !== undefined) {
+        this.addChild(new Spacer(1));
+        this.addChild(options.spinner);
+      }
+      return;
+    }
+
+    if (options.mode === 'composing' && options.spinner !== undefined) {
+      this.addChild(new Spacer(1));
+      this.addChild(options.spinner);
+    }
+  }
+}
diff --git a/apps/kimi-code/src/tui/components/panes/queue-pane.ts b/apps/kimi-code/src/tui/components/panes/queue-pane.ts
new file mode 100644
index 000000000..87b0d924f
--- /dev/null
+++ b/apps/kimi-code/src/tui/components/panes/queue-pane.ts
@@ -0,0 +1,36 @@
+import { Container, Text } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+
+import type { QueuedMessage } from '../../types';
+import type { ColorPalette } from '../../theme/colors';
+
+export interface QueuePaneOptions {
+  readonly messages: readonly QueuedMessage[];
+  readonly colors: ColorPalette;
+  readonly isCompacting: boolean;
+  readonly isStreaming: boolean;
+  readonly canSteerImmediately: boolean;
+}
+
+export class QueuePaneComponent extends Container {
+  constructor(options: QueuePaneOptions) {
+    super();
+
+    const accent = chalk.hex(options.colors.accent);
+    const dim = chalk.hex(options.colors.textDim);
+
+    for (const item of options.messages) {
+      this.addChild(new Text(accent(`  ❯ ${item.text}`), 0, 0));
+    }
+
+    if (options.messages.length > 0) {
+      const hint =
+        options.isCompacting && !options.isStreaming
+          ? '  ↑ to edit · will send after compaction'
+          : !options.canSteerImmediately
+            ? '  ↑ to edit · will send after current task'
+          : '  ↑ to edit · ctrl-s to steer immediately';
+      this.addChild(new Text(dim(hint), 0, 0));
+    }
+  }
+}
diff --git a/apps/kimi-code/src/tui/config.ts b/apps/kimi-code/src/tui/config.ts
new file mode 100644
index 000000000..e09774a40
--- /dev/null
+++ b/apps/kimi-code/src/tui/config.ts
@@ -0,0 +1,153 @@
+/**
+ * TUI-owned configuration.
+ *
+ * Agent/runtime settings live in core's `config.toml`; this file owns only
+ * terminal UI preferences for the kimi-code client.
+ */
+
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { parse as parseToml } from 'smol-toml';
+import { z } from 'zod';
+
+import { getDataDir } from '#/utils/paths';
+
+export const INVALID_TUI_CONFIG_MESSAGE =
+  'Invalid TUI config in ~/.kimi-code/tui.toml; using defaults.';
+
+export const TuiThemeSchema = z.enum(['dark', 'light', 'auto']);
+
+export const NotificationConditionSchema = z.enum(['unfocused', 'always']);
+
+export const NotificationsConfigSchema = z.object({
+  enabled: z.boolean(),
+  condition: NotificationConditionSchema,
+});
+
+export const TuiConfigFileSchema = z.object({
+  theme: TuiThemeSchema.optional(),
+  editor: z
+    .object({
+      command: z.string().optional(),
+    })
+    .optional(),
+  notifications: z
+    .object({
+      enabled: z.boolean().optional(),
+      notification_condition: NotificationConditionSchema.optional(),
+    })
+    .optional(),
+});
+
+export const TuiConfigSchema = z.object({
+  theme: TuiThemeSchema,
+  editorCommand: z.string().nullable(),
+  notifications: NotificationsConfigSchema,
+});
+
+export type TuiConfigFileShape = z.infer<typeof TuiConfigFileSchema>;
+export type TuiConfig = z.infer<typeof TuiConfigSchema>;
+export type NotificationsConfig = z.infer<typeof NotificationsConfigSchema>;
+
+export const DEFAULT_NOTIFICATIONS_CONFIG: NotificationsConfig = {
+  enabled: true,
+  condition: 'unfocused',
+};
+
+export const DEFAULT_TUI_CONFIG: TuiConfig = TuiConfigSchema.parse({
+  theme: 'auto',
+  editorCommand: null,
+  notifications: DEFAULT_NOTIFICATIONS_CONFIG,
+});
+
+/**
+ * Thrown by `loadTuiConfig` when the on-disk TOML cannot be parsed.
+ * Carries `fallback` so the caller can recover without re-running the
+ * I/O, and use `message` (== `INVALID_TUI_CONFIG_MESSAGE`) as a
+ * user-facing notice.
+ */
+export class TuiConfigParseError extends Error {
+  override readonly name = 'TuiConfigParseError';
+  readonly fallback: TuiConfig;
+  constructor(fallback: TuiConfig) {
+    super(INVALID_TUI_CONFIG_MESSAGE);
+    this.fallback = fallback;
+  }
+}
+
+export function getTuiConfigPath(): string {
+  return join(getDataDir(), 'tui.toml');
+}
+
+export async function loadTuiConfig(filePath: string = getTuiConfigPath()): Promise<TuiConfig> {
+  if (!existsSync(filePath)) {
+    await saveTuiConfig(DEFAULT_TUI_CONFIG, filePath);
+    return DEFAULT_TUI_CONFIG;
+  }
+
+  try {
+    const text = await readFile(filePath, 'utf-8');
+    return parseTuiConfig(text);
+  } catch {
+    throw new TuiConfigParseError(DEFAULT_TUI_CONFIG);
+  }
+}
+
+export function parseTuiConfig(tomlText: string): TuiConfig {
+  if (tomlText.trim().length === 0) {
+    return DEFAULT_TUI_CONFIG;
+  }
+  const raw = parseToml(tomlText) as Record<string, unknown>;
+  const parsed = TuiConfigFileSchema.parse(raw);
+  return normalizeTuiConfig(parsed);
+}
+
+export async function saveTuiConfig(
+  config: TuiConfig,
+  filePath: string = getTuiConfigPath(),
+): Promise<void> {
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, renderTuiConfig(config), 'utf-8');
+}
+
+export function normalizeTuiConfig(config: TuiConfigFileShape): TuiConfig {
+  const command = config.editor?.command?.trim();
+  return TuiConfigSchema.parse({
+    theme: config.theme ?? DEFAULT_TUI_CONFIG.theme,
+    editorCommand: command === undefined || command.length === 0 ? null : command,
+    notifications: {
+      enabled: config.notifications?.enabled ?? DEFAULT_NOTIFICATIONS_CONFIG.enabled,
+      condition:
+        config.notifications?.notification_condition ?? DEFAULT_NOTIFICATIONS_CONFIG.condition,
+    },
+  });
+}
+
+export function renderTuiConfig(config: TuiConfig): string {
+  return `# ~/.kimi-code/tui.toml
+# Terminal UI preferences for kimi-code.
+# Agent/runtime settings stay in ~/.kimi-code/config.toml.
+
+theme = "${config.theme}" # "auto" | "dark" | "light"
+
+[editor]
+command = "${escapeTomlBasicString(config.editorCommand ?? '')}" # Empty uses $VISUAL / $EDITOR
+
+[notifications]
+enabled = ${String(config.notifications.enabled)} # true | false
+notification_condition = "${config.notifications.condition}" # "unfocused" | "always"
+`;
+}
+
+function escapeTomlBasicString(value: string): string {
+  return value
+    .replaceAll('\\', '\\\\')
+    .replaceAll('"', '\\"')
+    .replaceAll('\b', '\\b')
+    .replaceAll('\t', '\\t')
+    .replaceAll('\n', '\\n')
+    .replaceAll('\f', '\\f')
+    .replaceAll('\r', '\\r');
+}
diff --git a/apps/kimi-code/src/tui/constant/feedback.ts b/apps/kimi-code/src/tui/constant/feedback.ts
new file mode 100644
index 000000000..37a50a43a
--- /dev/null
+++ b/apps/kimi-code/src/tui/constant/feedback.ts
@@ -0,0 +1,42 @@
+/**
+ * Constants for the /feedback command — endpoints, telemetry keys, and
+ * the status messages shown around the feedback submission flow.
+ *
+ * Dialog-internal copy (the box title, subtitle, footer) lives next to
+ * the dialog component itself, since it is part of that component's
+ * visual contract.
+ */
+
+import { FEEDBACK_VERSION_PREFIX } from '#/constant/app';
+
+export {
+  FEEDBACK_ISSUE_URL,
+  FEEDBACK_TELEMETRY_EVENT,
+  FEEDBACK_VERSION_PREFIX,
+} from '#/constant/app';
+
+export const FEEDBACK_STATUS_SUBMITTING = 'Submitting feedback…';
+export const FEEDBACK_STATUS_SUCCESS = 'Feedback submitted, thank you!';
+export const FEEDBACK_STATUS_CANCELLED = 'Feedback cancelled.';
+export const FEEDBACK_STATUS_NETWORK_ERROR = 'Network error, failed to submit feedback.';
+export const FEEDBACK_STATUS_FALLBACK = 'Opening GitHub Issues as fallback…';
+export const FEEDBACK_STATUS_NOT_SIGNED_IN =
+  "You're not signed in. Opening GitHub Issues for feedback…";
+
+export function feedbackHttpErrorMessage(status: number): string {
+  return `Failed to submit feedback (HTTP ${String(status)}).`;
+}
+
+export function feedbackSessionLine(sessionId: string): string {
+  return `Session: ${sessionId}`;
+}
+
+// Hint shown beneath session-level error messages in the TUI to point users
+// at the `kimi export` workflow so they can share diagnostics with us.
+export function errorReportHintLine(sessionId: string): string {
+  return `If this persists, run \`kimi export ${sessionId}\` and share the file with us for diagnosis. Please don't share it publicly.`;
+}
+
+export function withFeedbackVersionPrefix(version: string): string {
+  return `${FEEDBACK_VERSION_PREFIX}${version}`;
+}
diff --git a/apps/kimi-code/src/tui/constant/kimi-tui.ts b/apps/kimi-code/src/tui/constant/kimi-tui.ts
new file mode 100644
index 000000000..03ef814c0
--- /dev/null
+++ b/apps/kimi-code/src/tui/constant/kimi-tui.ts
@@ -0,0 +1,17 @@
+import { DEFAULT_OAUTH_PROVIDER_NAME } from '#/constant/app';
+
+export { DEFAULT_OAUTH_PROVIDER_NAME, OAUTH_LOGIN_REQUIRED_CODE } from '#/constant/app';
+
+export const LLM_NOT_SET_MESSAGE = 'LLM not set, send "/login" to login';
+export const NO_ACTIVE_SESSION_MESSAGE = 'No active session. Send /login to login.';
+export const CTRL_D_HINT = 'Press Ctrl+D again to exit';
+export const CTRL_C_HINT = 'Press Ctrl+C again to exit';
+export const MAIN_AGENT_ID = 'main';
+export const OAUTH_LOGIN_REQUIRED_STARTUP_NOTICE = 'OAuth login expired. Send /login to login.';
+export const EXIT_CONFIRM_WINDOW_MS = 1500;
+
+export function isManagedUsageProvider(
+  providerKey: string | undefined,
+): providerKey is typeof DEFAULT_OAUTH_PROVIDER_NAME {
+  return providerKey === DEFAULT_OAUTH_PROVIDER_NAME;
+}
diff --git a/apps/kimi-code/src/tui/constant/rendering.ts b/apps/kimi-code/src/tui/constant/rendering.ts
new file mode 100644
index 000000000..c96abf466
--- /dev/null
+++ b/apps/kimi-code/src/tui/constant/rendering.ts
@@ -0,0 +1,19 @@
+// Continuation indent for transcript rows that use a two-cell leading marker.
+export const MESSAGE_INDENT = '  ';
+
+// Outer left/right padding applied to the transcript, panels, and the
+// statusline so the chrome's left edge lines up with the input box's
+// interior (the `>` prompt). The editor itself stays at column 0 — its
+// vertical borders are the visual anchor everything else aligns against.
+export const CHROME_GUTTER = 1;
+
+// Shared preview caps used by thinking, tool results, and shell snippets.
+export const RESULT_PREVIEW_LINES = 3;
+export const COMMAND_PREVIEW_LINES = 10;
+
+// Animation frames are shared by the login/update loaders and live thinking.
+export const BRAILLE_SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export const BRAILLE_SPINNER_INTERVAL_MS = 80;
+
+export const MOON_SPINNER_FRAMES = ['🌑', '🌒', '🌓', '🌔', '🌕', '🌖', '🌗', '🌘'];
+export const MOON_SPINNER_INTERVAL_MS = 120;
diff --git a/apps/kimi-code/src/tui/constant/streaming.ts b/apps/kimi-code/src/tui/constant/streaming.ts
new file mode 100644
index 000000000..e52117249
--- /dev/null
+++ b/apps/kimi-code/src/tui/constant/streaming.ts
@@ -0,0 +1,4 @@
+// Extracts useful string fields from partially streamed JSON tool args.
+// This is intentionally a preview parser, not a full JSON parser.
+export const STREAMING_ARGS_FIELD_RE =
+  /"(path|file_path|command|pattern|query|url|description|title|name)"\s*:\s*"((?:\\.|[^"\\])*)"/g;
diff --git a/apps/kimi-code/src/tui/constant/symbols.ts b/apps/kimi-code/src/tui/constant/symbols.ts
new file mode 100644
index 000000000..670b94eb0
--- /dev/null
+++ b/apps/kimi-code/src/tui/constant/symbols.ts
@@ -0,0 +1,7 @@
+// Use U+25CF instead of U+23FA to avoid emoji/fallback rendering in terminals.
+export const STATUS_BULLET = '● ';
+
+// Shared transcript markers. Keep widths stable because message wrapping
+// assumes the marker occupies the leading cells.
+export const USER_MESSAGE_BULLET = '✨ ';
+export const FAILURE_MARK = '✗ ';
diff --git a/apps/kimi-code/src/tui/constant/terminal.ts b/apps/kimi-code/src/tui/constant/terminal.ts
new file mode 100644
index 000000000..9d68af25f
--- /dev/null
+++ b/apps/kimi-code/src/tui/constant/terminal.ts
@@ -0,0 +1,40 @@
+import { BEL, ESC, ST } from "#/constant/terminal";
+
+export { BEL, ESC, ST } from "#/constant/terminal";
+
+// Terminal theme reporting uses private CSI sequences: enable reporting,
+// query once, then parse dark/light reports from the input stream.
+export const QUERY_TERMINAL_THEME = `${ESC}[?996n`;
+export const TERMINAL_THEME_DARK = `${ESC}[?997;1n`;
+export const TERMINAL_THEME_LIGHT = `${ESC}[?997;2n`;
+export const ENABLE_TERMINAL_THEME_REPORTING = `${ESC}[?2031h`;
+export const DISABLE_TERMINAL_THEME_REPORTING = `${ESC}[?2031l`;
+
+// Xterm-style focus reporting. Input listeners consume these bytes so
+// they do not leak into the editor.
+export const TERMINAL_FOCUS_IN = `${ESC}[I`;
+export const TERMINAL_FOCUS_OUT = `${ESC}[O`;
+export const ENABLE_TERMINAL_FOCUS_REPORTING = `${ESC}[?1004h`;
+export const DISABLE_TERMINAL_FOCUS_REPORTING = `${ESC}[?1004l`;
+
+// Standard OSC 11 background-color query. The response regex intentionally
+// allows a missing leading ESC because terminals can echo replies alongside
+// other raw input, but it requires an OSC terminator so fragmented color
+// channels are not parsed as complete replies.
+export const OSC11_QUERY = `${ESC}]11;?${BEL}`;
+const OSC11_RESPONSE_TERMINATOR_PATTERN = `(?:${BEL}|${ESC}\\\\)`;
+export const OSC11_RESPONSE = new RegExp(
+  String.raw`${ESC}?\]11;rgb:([0-9a-f]{1,4})\/([0-9a-f]{1,4})\/([0-9a-f]{1,4})${OSC11_RESPONSE_TERMINATOR_PATTERN}`,
+  "i",
+);
+export const OSC11_RESPONSE_PREFIX = `${ESC}]11;rgb:`;
+export const OSC11_RESPONSE_PREFIX_NO_ESC = "]11;rgb:";
+
+// Keep notification/title payloads bounded so terminal tabs and desktop
+// notifications stay readable.
+export const MAX_TERMINAL_NOTIFICATION_MESSAGE_LENGTH = 240;
+export const MAX_PROCESS_TITLE_LENGTH = 80;
+
+// OSC 11 probing must be short because unsupported terminals do not reply.
+export const TERMINAL_THEME_DETECT_TIMEOUT_MS = 250;
+export const TERMINAL_THEME_INPUT_BUFFER_MAX_LENGTH = 512;
diff --git a/apps/kimi-code/src/tui/index.ts b/apps/kimi-code/src/tui/index.ts
new file mode 100644
index 000000000..e4581aa39
--- /dev/null
+++ b/apps/kimi-code/src/tui/index.ts
@@ -0,0 +1,3 @@
+export { KimiTUI } from './kimi-tui';
+export type { KimiTUIStartupInput } from './kimi-tui';
+export type { KimiTUIOptions } from './kimi-tui';
diff --git a/apps/kimi-code/src/tui/kimi-tui.ts b/apps/kimi-code/src/tui/kimi-tui.ts
new file mode 100644
index 000000000..9dc684f3c
--- /dev/null
+++ b/apps/kimi-code/src/tui/kimi-tui.ts
@@ -0,0 +1,5221 @@
+/**
+ * KimiTUI owns the terminal UI shell for a Kimi Code session.
+ *
+ * It builds the pi-tui layout, tracks view state, wires editor shortcuts and
+ * slash commands, drives session startup/switching, renders SDK events into the
+ * transcript and live panes, and bridges approval, question, auth, and config
+ * flows back to the harness.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { release as osRelease, type as osType } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  Container,
+  deleteAllKittyImages,
+  type Component,
+  type Focusable,
+  getCapabilities,
+  ProcessTerminal,
+  type SlashCommand,
+  Spacer,
+  TUI,
+} from '@earendil-works/pi-tui';
+import type { MigrationPlan } from '@moonshot-ai/migration-legacy';
+import {
+  applyOpenPlatformConfig,
+  capabilitiesForModel,
+  fetchOpenPlatformModels,
+  filterModelsByPrefix,
+  getOpenPlatformById,
+  isOpenPlatformId,
+  OpenPlatformApiError,
+  type DeviceAuthorization,
+  type ManagedKimiCodeModelInfo,
+  type ManagedKimiConfigShape,
+  type OpenPlatformDefinition,
+} from '@moonshot-ai/kimi-code-oauth';
+import { log } from '@moonshot-ai/kimi-code-sdk';
+import type {
+  AgentStatusUpdatedEvent,
+  ApprovalRequest,
+  ApprovalResponse,
+  AssistantDeltaEvent,
+  BackgroundTaskInfo,
+  BackgroundTaskStartedEvent,
+  BackgroundTaskTerminatedEvent,
+  BackgroundTaskUpdatedEvent,
+  CompactionCancelledEvent,
+  CompactionCompletedEvent,
+  CompactionStartedEvent,
+  CreateSessionOptions,
+  ErrorEvent,
+  Event,
+  HookResultEvent,
+  KimiHarness,
+  ModelAlias,
+  McpServerInfo,
+  PermissionMode,
+  PromptPart,
+  Session,
+  SessionMetaUpdatedEvent,
+  SessionStatus,
+  SessionUsage,
+  SkillActivatedEvent,
+  SubagentCompletedEvent,
+  SubagentFailedEvent,
+  SubagentSpawnedEvent,
+  ThinkingDeltaEvent,
+  ToolCallDeltaEvent,
+  ToolCallStartedEvent,
+  ToolProgressEvent,
+  ToolResultEvent,
+  TurnEndedEvent,
+  TurnStartedEvent,
+  TurnStepCompletedEvent,
+  TurnStepInterruptedEvent,
+  TurnStepStartedEvent,
+} from '@moonshot-ai/kimi-code-sdk';
+import chalk from 'chalk';
+
+import type { CLIOptions } from '#/cli/options';
+import { MigrationScreenComponent, type MigrationScreenResult } from '#/migration/index';
+import { ClipboardMediaError, readClipboardMedia } from '#/utils/clipboard/clipboard-image';
+import type { GitLsFilesCache } from '#/utils/git/git-ls-files';
+import { createGitLsFilesCache } from '#/utils/git/git-ls-files';
+import { appendInputHistory, loadInputHistory } from '#/utils/history/input-history';
+import { parseImageMeta } from '#/utils/image/image-mime';
+import { getInputHistoryFile } from '#/utils/paths';
+import { editInExternalEditor, resolveEditorCommand } from '#/utils/process/external-editor';
+import { detectFdPath } from '#/utils/process/fd-detect';
+
+import { hydrateTranscriptFromReplay, type ReplayHydrationHooks } from './actions/replay-ops';
+import {
+  BUILTIN_SLASH_COMMANDS,
+  buildSkillSlashCommands,
+  parseSlashInput,
+  resolveSlashCommandInput,
+  slashBusyMessage,
+  sortSlashCommands,
+  type BuiltinSlashCommandName,
+  type KimiSlashCommand,
+  type SkillListSession,
+} from './commands';
+import { DeviceCodeBoxComponent } from './components/chrome/device-code-box';
+import { FooterComponent } from './components/chrome/footer';
+import { GutterContainer } from './components/chrome/gutter-container';
+import { CHROME_GUTTER } from './constant/rendering';
+import { MoonLoader, type SpinnerStyle } from './components/chrome/moon-loader';
+import { TodoPanelComponent, type TodoItem } from './components/chrome/todo-panel';
+import { WelcomeComponent } from './components/chrome/welcome';
+import {
+  ApprovalPanelComponent,
+  type ApprovalPanelResponse,
+} from './components/dialogs/approval-panel';
+import {
+  ApiKeyInputDialogComponent,
+  type ApiKeyInputResult,
+} from './components/dialogs/api-key-input-dialog';
+import { CompactionComponent } from './components/dialogs/compaction';
+import { EditorSelectorComponent } from './components/dialogs/editor-selector';
+import {
+  FeedbackInputDialogComponent,
+  type FeedbackInputDialogResult,
+} from './components/dialogs/feedback-input-dialog';
+import { HelpPanelComponent } from './components/dialogs/help-panel';
+import { ModelSelectorComponent } from './components/dialogs/model-selector';
+import { PlatformSelectorComponent } from './components/dialogs/platform-selector';
+import { PermissionSelectorComponent } from './components/dialogs/permission-selector';
+import { QuestionDialogComponent } from './components/dialogs/question-dialog';
+import { SessionPickerComponent, type SessionRow } from './components/dialogs/session-picker';
+import { TaskOutputViewer } from './components/dialogs/task-output-viewer';
+import { TasksBrowserApp, type TasksFilter } from './components/dialogs/tasks-browser';
+import {
+  SettingsSelectorComponent,
+  type SettingsSelection,
+} from './components/dialogs/settings-selector';
+import { ThemeSelectorComponent } from './components/dialogs/theme-selector';
+import { CustomEditor } from './components/editor/custom-editor';
+import { FileMentionProvider } from './components/editor/file-mention-provider';
+import { AgentGroupComponent } from './components/messages/agent-group';
+import { AssistantMessageComponent } from './components/messages/assistant-message';
+import { BackgroundAgentStatusComponent } from './components/messages/background-agent-status';
+import { buildMcpStatusReportLines } from './components/messages/mcp-status-panel';
+import { ReadGroupComponent } from './components/messages/read-group';
+import { SkillActivationComponent } from './components/messages/skill-activation';
+import {
+  NoticeMessageComponent,
+  StatusMessageComponent,
+} from './components/messages/status-message';
+import { buildStatusReportLines } from './components/messages/status-panel';
+import { ThinkingComponent } from './components/messages/thinking';
+import { ToolCallComponent } from './components/messages/tool-call';
+import {
+  buildUsageReportLines,
+  UsagePanelComponent,
+  type ManagedUsageReport,
+} from './components/messages/usage-panel';
+import { UserMessageComponent } from './components/messages/user-message';
+import { ActivityPaneComponent, type ActivityPaneMode } from './components/panes/activity-pane';
+import { QueuePaneComponent } from './components/panes/queue-pane';
+import { saveTuiConfig, type TuiConfig } from './config';
+import {
+  FEEDBACK_ISSUE_URL,
+  FEEDBACK_STATUS_CANCELLED,
+  FEEDBACK_STATUS_FALLBACK,
+  FEEDBACK_STATUS_NETWORK_ERROR,
+  FEEDBACK_STATUS_NOT_SIGNED_IN,
+  FEEDBACK_STATUS_SUBMITTING,
+  FEEDBACK_STATUS_SUCCESS,
+  FEEDBACK_TELEMETRY_EVENT,
+  errorReportHintLine,
+  feedbackHttpErrorMessage,
+  feedbackSessionLine,
+  withFeedbackVersionPrefix,
+} from './constant/feedback';
+import {
+  CTRL_C_HINT,
+  CTRL_D_HINT,
+  DEFAULT_OAUTH_PROVIDER_NAME,
+  EXIT_CONFIRM_WINDOW_MS,
+  isManagedUsageProvider,
+  LLM_NOT_SET_MESSAGE,
+  MAIN_AGENT_ID,
+  NO_ACTIVE_SESSION_MESSAGE,
+  OAUTH_LOGIN_REQUIRED_CODE,
+  OAUTH_LOGIN_REQUIRED_STARTUP_NOTICE,
+} from './constant/kimi-tui';
+import { adaptPanelResponse } from './reverse-rpc/approval/adapter';
+import { ApprovalController } from './reverse-rpc/approval/controller';
+import { createApprovalRequestHandler } from './reverse-rpc/approval/handler';
+import { registerReverseRPCHandlers } from './reverse-rpc/index';
+import { QuestionController } from './reverse-rpc/question/controller';
+import { createQuestionAskHandler } from './reverse-rpc/question/handler';
+import type { ApprovalPanelData, QuestionPanelData } from './reverse-rpc/types';
+import { createKimiTUIThemeBundle, type KimiTUIThemeBundle } from './theme/bundle';
+import type { ResolvedTheme } from './theme/colors';
+import { isTheme, type Theme } from './theme/index';
+import {
+  INITIAL_LIVE_PANE,
+  type AppState,
+  type BackgroundAgentMetadata,
+  type LivePaneState,
+  type QueuedMessage,
+  type ToolCallBlockData,
+  type ToolResultBlockData,
+  type TranscriptEntry,
+} from './types';
+import { formatBackgroundAgentTranscript } from './utils/background-agent-status';
+import { formatBackgroundTaskTranscript } from './utils/background-task-status';
+import { hasDispose, isExpandable, isPlanExpandable } from './utils/component-capabilities';
+import {
+  argsRecord,
+  formatErrorMessage,
+  isTodoItemShape,
+  parseStreamingArgs,
+  serializeToolResultOutput,
+  stringValue,
+} from './utils/event-payload';
+import { isAbortError } from './utils/errors';
+import { ImageAttachmentStore, type ImageAttachment } from './utils/image-attachment-store';
+import { extractMediaAttachments } from './utils/image-placeholder';
+import { McpOAuthAuthorizationUrlOpener } from './utils/mcp-oauth';
+import {
+  formatMcpStartupStatusSummary,
+  mcpServerStatusKey,
+  type McpServerStatusSnapshot,
+  selectMcpStartupStatusRows,
+} from './utils/mcp-server-status';
+import { openUrl } from './utils/open-url';
+import { setProcessTitle } from './utils/proctitle';
+import { installTerminalFocusTracking } from './utils/terminal-focus';
+import { notifyTerminalOnce } from './utils/terminal-notification';
+import { createTerminalState, type TerminalState } from './utils/terminal-state';
+import { installTerminalThemeTracking } from './utils/terminal-theme';
+import { nextTranscriptId } from './utils/transcript-id';
+
+export interface KimiTUIStartupInput {
+  readonly cliOptions: CLIOptions;
+  readonly tuiConfig: TuiConfig;
+  readonly version: string;
+  readonly workDir: string;
+  readonly startupNotice?: string;
+  readonly resolvedTheme?: ResolvedTheme;
+  readonly migrationPlan?: MigrationPlan | null;
+  /** When true, run only the migration screen, then exit (the `kimi migrate` command). */
+  readonly migrateOnly?: boolean;
+}
+
+export interface PendingExit {
+  readonly kind: 'ctrl-c' | 'ctrl-d';
+  readonly timer: ReturnType<typeof setTimeout>;
+}
+
+type EffectiveActivityPaneMode = ActivityPaneMode | 'idle' | 'session';
+
+export interface TUIStartupOptions {
+  readonly sessionFlag?: string;
+  readonly continueLast: boolean;
+  readonly yolo: boolean;
+  readonly plan: boolean;
+  readonly model?: string;
+  readonly startupNotice?: string;
+}
+
+export type TUIStartupState = 'pending' | 'ready' | 'picker';
+
+export interface KimiTUIOptions {
+  initialAppState: AppState;
+  startup: TUIStartupOptions;
+  resolvedTheme?: ResolvedTheme;
+}
+
+export interface TUIState {
+  ui: TUI;
+  terminal: ProcessTerminal;
+  transcriptContainer: Container;
+  activityContainer: Container;
+  todoPanelContainer: Container;
+  todoPanel: TodoPanelComponent;
+  queueContainer: Container;
+  editorContainer: Container;
+  footer: FooterComponent;
+  editor: CustomEditor;
+  theme: KimiTUIThemeBundle;
+  appState: AppState;
+  startupState: TUIStartupState;
+  startupNotice: string | undefined;
+  livePane: LivePaneState;
+  transcriptEntries: TranscriptEntry[];
+  terminalState: TerminalState;
+  activitySpinner: MoonLoader | undefined;
+  activitySpinnerStyle: SpinnerStyle | undefined;
+  activeThinkingComponent: ThinkingComponent | undefined;
+  streamingComponent: AssistantMessageComponent | undefined;
+  streamingTranscriptEntry: TranscriptEntry | undefined;
+  activeCompactionBlock: CompactionComponent | undefined;
+  toolOutputExpanded: boolean;
+  planExpanded: boolean;
+  lastActivityMode: string | undefined;
+  lastHistoryContent: string | undefined;
+  pendingToolComponents: Map<string, ToolCallComponent>;
+  pendingAgentGroup: {
+    readonly turnId: string | undefined;
+    readonly step: number;
+    solo?: ToolCallComponent;
+    group?: AgentGroupComponent;
+  } | null;
+  pendingReadGroup: {
+    readonly turnId: string | undefined;
+    readonly step: number;
+    solo?: ToolCallComponent;
+    group?: ReadGroupComponent;
+  } | null;
+  backgroundAgents: Set<string>;
+  backgroundAgentMetadata: Map<string, BackgroundAgentMetadata>;
+  /**
+   * Authoritative live mirror of the BPM. Keyed by `taskId`. Includes
+   * both bash and agent tasks, and retains terminal entries until they
+   * are explicitly forgotten (kept so transcript replay and footer
+   * lookups stay consistent).
+   */
+  backgroundTasks: Map<string, BackgroundTaskInfo>;
+  /**
+   * Task IDs whose terminal transcript card has already been pushed.
+   * Used to dedupe between the BPM `background.task.terminated` event
+   * and the older `subagent.completed/failed` flow, both of which
+   * arrive for `agent-*` tasks.
+   */
+  backgroundTaskTranscriptedTerminal: Set<string>;
+  renderedSkillActivationIds: Set<string>;
+  renderedMcpServerStatusKeys: Map<string, string>;
+  mcpServerStatusSpinners: Map<string, MoonLoader>;
+  subagentParentToolCallIds: Map<string, string>;
+  subagentNames: Map<string, string>;
+  sessions: SessionRow[];
+  loadingSessions: boolean;
+  showingSessionPicker: boolean;
+  showingHelpPanel: boolean;
+  /**
+   * Active `/tasks` full-screen takeover. When non-undefined, the main
+   * TUI's children have been replaced by `component`; `savedChildren`
+   * holds the original list so we can restore on exit.
+   */
+  tasksBrowser:
+    | {
+        component: TasksBrowserApp;
+        savedChildren: readonly Component[];
+        filter: TasksFilter;
+        selectedTaskId: string | undefined;
+        tailOutput: string | undefined;
+        tailLoading: boolean;
+        tailRequestId: number;
+        flashMessage: string | undefined;
+        flashTimer: NodeJS.Timeout | undefined;
+        pollTimer: NodeJS.Timeout | undefined;
+        /**
+         * Active nested output viewer (TaskOutputViewer). Undefined when
+         * the browser is showing its normal 3-pane layout.
+         */
+        viewer:
+          | {
+              component: TaskOutputViewer;
+              savedChildren: readonly Component[];
+              /** Task whose output the viewer is currently following. */
+              taskId: string;
+              /** Latest output snapshot pushed into the viewer. */
+              output: string;
+              /** Last in-flight refresh — used to ignore late responses. */
+              refreshId: number;
+              /** 1s background poll so live tail still works if events drop. */
+              pollTimer: NodeJS.Timeout;
+            }
+          | undefined;
+      }
+    | undefined;
+  externalEditorRunning: boolean;
+  currentTurnId: string | undefined;
+  currentStep: number;
+  assistantDraft: string;
+  assistantStreamActive: boolean;
+  thinkingDraft: string;
+  activeToolCalls: Map<string, ToolCallBlockData>;
+  streamingToolCallArguments: Map<
+    string,
+    { name?: string; argumentsText: string; startedAtMs: number }
+  >;
+  queuedMessages: QueuedMessage[];
+}
+
+// Builds the app-state snapshot used before a session is attached.
+function createInitialAppState(input: KimiTUIStartupInput): AppState {
+  const startupPermission: PermissionMode = input.cliOptions.yolo ? 'yolo' : 'manual';
+  return {
+    model: '',
+    workDir: input.workDir,
+    sessionId: '',
+    yolo: input.cliOptions.yolo,
+    permissionMode: startupPermission,
+    planMode: input.cliOptions.plan,
+    thinking: false,
+    contextUsage: 0,
+    contextTokens: 0,
+    maxContextTokens: 0,
+    isStreaming: false,
+    isCompacting: false,
+    isReplaying: false,
+    streamingPhase: 'idle',
+    streamingStartTime: 0,
+    theme: input.tuiConfig.theme,
+    version: input.version,
+    editorCommand: input.tuiConfig.editorCommand,
+    notifications: input.tuiConfig.notifications,
+    availableModels: {},
+    availableProviders: {},
+    sessionTitle: null,
+  };
+}
+
+// Creates all pi-tui components and mutable runtime state owned by KimiTUI.
+export function createTUIState(options: KimiTUIOptions): TUIState {
+  const initialAppState = options.initialAppState;
+  const theme = createKimiTUIThemeBundle(initialAppState.theme, options.resolvedTheme);
+
+  const terminal = new ProcessTerminal();
+  const ui = new TUI(terminal);
+
+  // Every chrome container runs with a 2-column outer gutter on each
+  // side. That gives the transcript, panels, the editor and the
+  // statusline a shared left edge — the input box's `│` lines up with
+  // panel borders like Welcome's `│`, and bullets / `>` share a column.
+  const transcriptContainer = new GutterContainer(CHROME_GUTTER, CHROME_GUTTER);
+  const activityContainer = new GutterContainer(CHROME_GUTTER, CHROME_GUTTER);
+  const todoPanelContainer = new GutterContainer(CHROME_GUTTER, CHROME_GUTTER);
+  const todoPanel = new TodoPanelComponent(theme.colors);
+  const queueContainer = new GutterContainer(CHROME_GUTTER, CHROME_GUTTER);
+  const editorContainer = new GutterContainer(CHROME_GUTTER, CHROME_GUTTER);
+  const editor = new CustomEditor(ui, theme.colors);
+  const footer = new FooterComponent({ ...initialAppState }, theme.colors, () => {
+    ui.requestRender();
+  });
+
+  return {
+    ui,
+    terminal,
+    transcriptContainer,
+    activityContainer,
+    todoPanelContainer,
+    todoPanel,
+    queueContainer,
+    editorContainer,
+    footer,
+    editor,
+    theme,
+    appState: { ...initialAppState },
+    startupState: 'pending',
+    startupNotice: options.startup.startupNotice,
+    livePane: { ...INITIAL_LIVE_PANE },
+    transcriptEntries: [],
+    terminalState: createTerminalState(),
+    activitySpinner: undefined,
+    activitySpinnerStyle: undefined,
+    activeThinkingComponent: undefined,
+    streamingComponent: undefined,
+    streamingTranscriptEntry: undefined,
+    activeCompactionBlock: undefined,
+    toolOutputExpanded: false,
+    planExpanded: false,
+    lastActivityMode: undefined,
+    lastHistoryContent: undefined,
+    pendingToolComponents: new Map<string, ToolCallComponent>(),
+    pendingAgentGroup: null,
+    pendingReadGroup: null,
+    backgroundAgents: new Set<string>(),
+    backgroundAgentMetadata: new Map<string, BackgroundAgentMetadata>(),
+    backgroundTasks: new Map<string, BackgroundTaskInfo>(),
+    backgroundTaskTranscriptedTerminal: new Set<string>(),
+    renderedSkillActivationIds: new Set<string>(),
+    renderedMcpServerStatusKeys: new Map<string, string>(),
+    mcpServerStatusSpinners: new Map<string, MoonLoader>(),
+    subagentParentToolCallIds: new Map<string, string>(),
+    subagentNames: new Map<string, string>(),
+    sessions: [],
+    loadingSessions: false,
+    showingSessionPicker: false,
+    showingHelpPanel: false,
+    tasksBrowser: undefined,
+    externalEditorRunning: false,
+    currentTurnId: undefined,
+    currentStep: 0,
+    assistantDraft: '',
+    assistantStreamActive: false,
+    thinkingDraft: '',
+    activeToolCalls: new Map<string, ToolCallBlockData>(),
+    streamingToolCallArguments: new Map(),
+    queuedMessages: [],
+  };
+}
+
+// Merges startup notices while preserving their display order.
+function combineStartupNotice(
+  existing: string | undefined,
+  next: string | undefined,
+): string | undefined {
+  if (existing !== undefined && next !== undefined) {
+    return `${existing}\n${next}`;
+  }
+  return existing ?? next;
+}
+
+function isOAuthLoginRequiredError(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+  return (error as { readonly code?: unknown }).code === OAUTH_LOGIN_REQUIRED_CODE;
+}
+
+interface SessionUsageResult {
+  readonly usage?: SessionUsage;
+  readonly error?: string;
+}
+
+interface ManagedUsageResult {
+  readonly usage?: ManagedUsageReport;
+  readonly error?: string;
+}
+
+interface RuntimeStatusResult {
+  readonly status?: SessionStatus;
+  readonly error?: string;
+}
+
+interface SendMessageOptions {
+  readonly parts?: readonly PromptPart[];
+  readonly imageAttachmentIds?: readonly number[];
+  readonly hasMedia?: boolean;
+}
+
+interface LoginProgressSpinnerHandle {
+  /** Stops the login progress row and replaces it with a final status. */
+  stop(opts: { ok: boolean; label: string }): void;
+}
+
+export class KimiTUI {
+  private readonly harness: KimiHarness;
+  private readonly options: KimiTUIOptions;
+  private session: Session | undefined;
+  private state: TUIState;
+  private readonly approvalController = new ApprovalController();
+  private readonly questionController = new QuestionController();
+  private readonly reverseRpcDisposers: Array<() => void> = [];
+  private skillCommands: readonly KimiSlashCommand[] = [];
+  private readonly skillCommandMap = new Map<string, string>();
+  private readonly imageStore = new ImageAttachmentStore();
+  private readonly fdPath: string | null = detectFdPath();
+  private readonly gitLsFilesCache: GitLsFilesCache;
+  private sessionEventUnsubscribe: (() => void) | undefined;
+  private pendingExit: PendingExit | null = null;
+  private cancelInFlight: (() => void) | undefined;
+  // Queues editor messages instead of sending or steering them. Used by /init.
+  private deferUserMessages = false;
+  private aborted = false;
+  private terminalFocusTrackingDispose: (() => void) | undefined;
+  private terminalThemeTrackingDispose: (() => void) | undefined;
+  // First-launch migration plan detected pre-TUI; null when nothing to migrate.
+  private readonly migrationPlan: MigrationPlan | null;
+  // When true, the migration screen is the whole session: run it, then exit.
+  private readonly migrateOnly: boolean;
+
+  public onExit?: (exitCode?: number) => Promise<void>;
+
+  private track(
+    event: string,
+    properties?: Parameters<KimiHarness['track']>[1],
+  ): void {
+    this.harness.track(event, properties);
+  }
+
+  // Initializes state, reverse-RPC handlers, editor callbacks, and layout.
+  constructor(harness: KimiHarness, startupInput: KimiTUIStartupInput) {
+    this.harness = harness;
+    const tuiOptions: KimiTUIOptions = {
+      initialAppState: createInitialAppState(startupInput),
+      startup: {
+        sessionFlag: startupInput.cliOptions.session,
+        continueLast: startupInput.cliOptions.continue,
+        yolo: startupInput.cliOptions.yolo,
+        plan: startupInput.cliOptions.plan,
+        model: startupInput.cliOptions.model,
+        startupNotice: startupInput.startupNotice,
+      },
+      resolvedTheme: startupInput.resolvedTheme,
+    };
+    this.options = tuiOptions;
+    this.migrationPlan = startupInput.migrationPlan ?? null;
+    this.migrateOnly = startupInput.migrateOnly ?? false;
+    this.state = createTUIState(tuiOptions);
+    this.gitLsFilesCache = createGitLsFilesCache(tuiOptions.initialAppState.workDir);
+
+    // Register approval / question UI controllers before SDK handlers.
+    this.reverseRpcDisposers.push(
+      ...registerReverseRPCHandlers(this.approvalController, this.questionController, {
+        showApprovalPanel: (payload) => {
+          this.showApprovalPanel(payload);
+        },
+        hideApprovalPanel: () => {
+          this.hideApprovalPanel();
+        },
+        showQuestionDialog: (payload) => {
+          this.showQuestionDialog(payload);
+        },
+        hideQuestionDialog: () => {
+          this.hideQuestionDialog();
+        },
+      }),
+    );
+    this.setupEditorHandlers();
+    this.buildLayout();
+  }
+
+  // =========================================================================
+  // Startup Helpers
+  // =========================================================================
+
+  // Returns built-in and dynamically loaded slash commands in display order.
+  private getSlashCommands(): readonly KimiSlashCommand[] {
+    return [...sortSlashCommands(BUILTIN_SLASH_COMMANDS), ...this.skillCommands];
+  }
+
+  // Rebuilds editor autocomplete from slash commands and file mentions.
+  private setupAutocomplete(): void {
+    const slashCommands: SlashCommand[] = this.getSlashCommands().map((cmd) => ({
+      name: cmd.name,
+      description: cmd.description,
+    }));
+    const provider = new FileMentionProvider(
+      slashCommands,
+      this.state.appState.workDir,
+      this.fdPath,
+      this.gitLsFilesCache,
+    );
+    this.state.editor.setAutocompleteProvider(provider);
+  }
+
+  // Loads skill-backed slash commands from the active session.
+  private async refreshSkillCommands(session?: SkillListSession): Promise<void> {
+    if (session === undefined) {
+      this.skillCommands = [];
+      this.skillCommandMap.clear();
+      this.setupAutocomplete();
+      return;
+    }
+
+    let skills;
+    try {
+      skills = await session.listSkills();
+    } catch {
+      return;
+    }
+    const skillCommands = buildSkillSlashCommands(skills);
+    this.skillCommands = skillCommands.commands;
+    this.skillCommandMap.clear();
+    for (const [commandName, skillName] of skillCommands.commandMap) {
+      this.skillCommandMap.set(commandName, skillName);
+    }
+    this.setupAutocomplete();
+  }
+
+  // Restores persisted input history for the current working directory.
+  private async loadPersistedInputHistory(): Promise<void> {
+    try {
+      const file = getInputHistoryFile(this.state.appState.workDir);
+      const entries = await loadInputHistory(file);
+      for (const entry of entries) {
+        this.state.editor.addToHistory(entry.content);
+      }
+      this.state.lastHistoryContent = entries.at(-1)?.content;
+    } catch {
+      /* history is best-effort */
+    }
+  }
+
+  // =========================================================================
+  // Lifecycle
+  // =========================================================================
+
+  // Starts the TUI, performs startup routing, and begins session event handling.
+  async start(): Promise<void> {
+    // Migration path: the migration screen is a pi-tui component, so the event
+    // loop must run first. It then renders as the very first thing on screen,
+    // before the session is created and the Welcome banner is drawn.
+    if (this.migrationPlan !== null) {
+      this.startEventLoop();
+      try {
+        const migrationResult = await this.runMigrationScreen(this.migrationPlan);
+        if (this.migrateOnly) {
+          // Explicit `kimi migrate`: the screen is the whole command — exit
+          // instead of continuing into the chat TUI. A migration that ran but
+          // failed exits non-zero so scripted callers can detect it.
+          const failed =
+            migrationResult.decision === 'now' && migrationResult.migrated === false;
+          // Restore the terminal before `onExit` calls `process.exit`: dispose
+          // the focus/theme tracking `startEventLoop()` installed, then stop
+          // the pi-tui loop. Skipping either leaves the terminal in raw mode
+          // or still emitting focus/OSC sequences after the command finishes.
+          this.disposeTerminalTracking();
+          this.state.ui.stop();
+          await this.onExit?.(failed ? 1 : 0);
+          return;
+        }
+        const shouldReplayHistory = await this.initMainTui();
+        await this.finishStartup(shouldReplayHistory);
+      } catch (error) {
+        // The pi-tui loop is running and startEventLoop() installed focus/
+        // theme tracking; a startup failure must tear all of it down before
+        // the exception propagates, otherwise the terminal is left in raw
+        // mode or still emitting focus/OSC sequences.
+        this.disposeTerminalTracking();
+        this.state.ui.stop();
+        throw error;
+      }
+      return;
+    }
+
+    // No-migration path: ordering is identical to the original `start()`.
+    const shouldReplayHistory = await this.initMainTui();
+    this.startEventLoop();
+    try {
+      await this.finishStartup(shouldReplayHistory);
+    } catch (error) {
+      // The pi-tui loop is running and startEventLoop() installed focus/theme
+      // tracking; tear all of it down so a finishStartup failure does not
+      // leave the terminal in raw mode or emitting focus/OSC sequences.
+      this.disposeTerminalTracking();
+      this.state.ui.stop();
+      throw error;
+    }
+  }
+
+  // Creates/resumes the session, renders the Welcome banner, configures
+  // autocomplete and input history, and mounts the editor. Returns whether
+  // transcript history should be replayed.
+  private async initMainTui(): Promise<boolean> {
+    const shouldReplayHistory = await this.init();
+
+    this.renderWelcome();
+    this.setupAutocomplete();
+    void this.loadPersistedInputHistory();
+    this.state.editorContainer.clear();
+    this.state.editorContainer.addChild(this.state.editor);
+    this.state.ui.setFocus(this.state.editor);
+    return shouldReplayHistory;
+  }
+
+  // Starts the pi-tui event loop and installs terminal focus/theme tracking.
+  private startEventLoop(): void {
+    this.state.ui.start();
+    this.terminalFocusTrackingDispose = installTerminalFocusTracking(this.state);
+    this.refreshTerminalThemeTracking();
+  }
+
+  // Runs post-init startup tasks: startup notice, picker bootstrap, transcript
+  // replay, and session event subscriptions.
+  private async finishStartup(shouldReplayHistory: boolean): Promise<void> {
+    if (this.state.startupNotice !== undefined) {
+      this.showStatus(this.state.startupNotice);
+      this.state.startupNotice = undefined;
+    }
+    if (this.state.startupState === 'picker') {
+      void this.bootstrapFromPicker();
+      // resumeSession (fired on picker select) owns post-pick init; nothing
+      // else to do here until the user makes a choice.
+      return;
+    }
+    if (shouldReplayHistory) {
+      await hydrateTranscriptFromReplay(
+        this.state,
+        this.replayHydrationHooks(),
+        this.requireSession(),
+      );
+    }
+    if (this.session !== undefined) {
+      this.startSessionEventSubscription();
+    }
+    void this.fetchSessions();
+    if (this.session !== undefined) {
+      this.refreshSessionTitle();
+    }
+    void this.refreshSkillCommands(this.session);
+  }
+
+  // Creates or resumes the startup session and reports whether history should replay.
+  private async init(): Promise<boolean> {
+    await this.refreshAvailableModels();
+
+    const { startup } = this.options;
+    const { workDir } = this.state.appState;
+    let session: Session | undefined;
+    let shouldReplayHistory = false;
+    const isResumeStartup = startup.sessionFlag !== undefined || startup.continueLast;
+    const createSessionOptions: CreateSessionOptions = {
+      workDir,
+      model: startup.model,
+      permission: startup.yolo ? 'yolo' : undefined,
+      planMode: startup.plan ? true : undefined,
+    };
+
+    try {
+      if (isResumeStartup) {
+        if (startup.sessionFlag === '') {
+          this.state.startupState = 'picker';
+          return false;
+        }
+
+        if (startup.sessionFlag !== undefined) {
+          const sessions = await this.harness.listSessions({ workDir });
+          const target = sessions.find((candidate) => candidate.id === startup.sessionFlag);
+          if (target === undefined) {
+            throw new Error(`Session "${startup.sessionFlag}" not found.`);
+          }
+          session = await this.harness.resumeSession({ id: startup.sessionFlag });
+          shouldReplayHistory = true;
+        } else {
+          const sessions = await this.harness.listSessions({ workDir });
+          const target = sessions[0];
+          if (target !== undefined) {
+            session = await this.harness.resumeSession({ id: target.id });
+            shouldReplayHistory = true;
+          } else {
+            session = await this.harness.createSession(createSessionOptions);
+            this.state.startupNotice = combineStartupNotice(
+              this.state.startupNotice,
+              `No sessions to continue under "${workDir}"; starting a fresh session.`,
+            );
+          }
+        }
+      } else {
+        session = await this.harness.createSession(createSessionOptions);
+      }
+      if (session !== undefined && startup.model !== undefined && isResumeStartup) {
+        await session.setModel(startup.model);
+      }
+    } catch (error) {
+      if (!isOAuthLoginRequiredError(error)) throw error;
+      this.enterLoginRequiredStartupState();
+      return false;
+    }
+
+    if (session === undefined) {
+      throw new Error('Startup session was not initialized.');
+    }
+    await this.setSession(session);
+    await this.syncRuntimeState(session);
+    this.state.startupState = 'ready';
+    return shouldReplayHistory;
+  }
+
+  // Stops UI resources, active sessions, reverse-RPC handlers, and the harness.
+  async stop(): Promise<void> {
+    this.aborted = true;
+    if (this.pendingExit) {
+      clearTimeout(this.pendingExit.timer);
+      this.pendingExit = null;
+    }
+    for (const dispose of this.reverseRpcDisposers) {
+      dispose();
+    }
+    this.reverseRpcDisposers.length = 0;
+    this.disposeTerminalTracking();
+    await this.closeSession('shutting down');
+    await this.harness.close();
+    this.stopAllMcpServerStatusSpinners();
+    this.state.ui.stop();
+    if (this.onExit) {
+      await this.onExit();
+    }
+  }
+
+  // Tears down the terminal focus + theme tracking installed by
+  // `startEventLoop()`. Every exit path must run this, or the terminal is
+  // left with focus-reporting / theme-query modes on and emits stray
+  // focus/OSC sequences after the process exits.
+  private disposeTerminalTracking(): void {
+    this.stopTerminalThemeTracking();
+    this.terminalFocusTrackingDispose?.();
+    this.terminalFocusTrackingDispose = undefined;
+  }
+
+  // Returns the currently selected session id shown by the UI.
+  getCurrentSessionId(): string {
+    return this.state.appState.sessionId;
+  }
+
+  // Reports whether the transcript contains user-visible session content.
+  hasSessionContent(): boolean {
+    return this.state.transcriptEntries.length > 0;
+  }
+
+  async getStartupMcpMs(): Promise<number> {
+    const session = this.session;
+    if (session === undefined) return 0;
+    try {
+      const metrics = await session.getMcpStartupMetrics();
+      return metrics.durationMs;
+    } catch {
+      return 0;
+    }
+  }
+
+  // =========================================================================
+  // Auth / Model Bootstrap
+  // =========================================================================
+
+  // Refreshes model metadata from the harness config.
+  private async refreshAvailableModels(): Promise<void> {
+    const config = await this.harness.getConfig({ reload: true });
+    this.setAppState({
+      availableModels: config.models ?? {},
+      availableProviders: config.providers ?? {},
+    });
+  }
+
+  // Allows the shell to start even when the managed OAuth token needs login.
+  private enterLoginRequiredStartupState(): void {
+    this.resetSessionRuntime();
+    this.setAppState({
+      sessionId: '',
+      model: '',
+      thinking: false,
+      contextTokens: 0,
+      maxContextTokens: 0,
+      contextUsage: 0,
+      sessionTitle: null,
+    });
+    this.state.startupNotice = combineStartupNotice(
+      this.state.startupNotice,
+      OAUTH_LOGIN_REQUIRED_STARTUP_NOTICE,
+    );
+    this.state.startupState = 'ready';
+  }
+
+  // Ensures a usable session exists for the default model after login.
+  private async activateModelAfterLogin(model: string, thinking?: boolean): Promise<void> {
+    const level = thinking === undefined ? undefined : thinking ? 'on' : 'off';
+    if (this.session !== undefined) {
+      await this.session.setModel(model);
+      if (level !== undefined) {
+        await this.session.setThinking(level);
+      }
+      return;
+    }
+
+    const session = await this.harness.createSession({
+      workDir: this.state.appState.workDir,
+      model,
+      thinking: level,
+      permission: this.options.startup.yolo ? 'yolo' : undefined,
+      planMode: this.state.appState.planMode ? true : undefined,
+    });
+    await this.setSession(session);
+    this.setAppState({
+      sessionId: session.id,
+      sessionTitle: session.summary?.title ?? null,
+    });
+    await this.syncRuntimeState(session);
+    this.startSessionEventSubscription();
+    void this.fetchSessions();
+    this.refreshSessionTitle();
+    void this.refreshSkillCommands(this.session);
+  }
+
+  // Clears the active session and runtime UI after logout.
+  private async clearActiveSessionAfterLogout(): Promise<void> {
+    await this.closeSession('logged out');
+    this.resetSessionRuntime();
+    this.setAppState({
+      sessionId: '',
+      model: '',
+      sessionTitle: null,
+    });
+    await this.refreshSkillCommands();
+  }
+
+  // Reloads config after login and selects the configured default model.
+  private async refreshConfigAfterLogin(): Promise<void> {
+    const config = await this.harness.getConfig({ reload: true });
+    const availableModels = config.models ?? {};
+    const availableProviders = config.providers ?? {};
+    const defaultModel = this.options.startup.model ?? config.defaultModel;
+    const selected = defaultModel !== undefined ? availableModels[defaultModel] : undefined;
+
+    if (defaultModel === undefined || selected === undefined) {
+      this.setAppState({ availableModels, availableProviders });
+      return;
+    }
+
+    await this.activateModelAfterLogin(defaultModel, config.defaultThinking);
+    const appStatePatch: Partial<AppState> = {
+      availableModels,
+      availableProviders,
+      model: defaultModel,
+      maxContextTokens: selected.maxContextSize,
+    };
+    if (config.defaultThinking !== undefined) {
+      appStatePatch.thinking = config.defaultThinking;
+    }
+    this.setAppState(appStatePatch);
+  }
+
+  // Reloads config after logout and clears model-dependent state.
+  private async refreshConfigAfterLogout(): Promise<void> {
+    const config = await this.harness.getConfig({ reload: true });
+    const availableModels = config.models ?? {};
+    const availableProviders = config.providers ?? {};
+    this.setAppState({
+      availableModels,
+      availableProviders,
+      model: '',
+      thinking: false,
+      maxContextTokens: 0,
+      contextUsage: 0,
+      contextTokens: 0,
+    });
+  }
+
+  // =========================================================================
+  // Layout / Editor Setup
+  // =========================================================================
+
+  // Mounts the root TUI containers in their rendering order.
+  private buildLayout(): void {
+    const { ui } = this.state;
+    ui.clear();
+    ui.addChild(this.state.transcriptContainer);
+    ui.addChild(this.state.activityContainer);
+    ui.addChild(this.state.todoPanelContainer);
+    ui.addChild(this.state.queueContainer);
+    ui.addChild(this.state.editorContainer);
+    // FooterComponent isn't a Container; wrap it so it picks up the same
+    // outer gutter as the transcript/panels above.
+    const footerWrap = new GutterContainer(CHROME_GUTTER, CHROME_GUTTER);
+    footerWrap.addChild(this.state.footer);
+    ui.addChild(footerWrap);
+  }
+
+  // Wires editor shortcuts, submission, paste, and navigation callbacks.
+  private setupEditorHandlers(): void {
+    const editor = this.state.editor;
+
+    editor.onSubmit = (text: string) => {
+      this.handleUserInput(text);
+    };
+
+    editor.onChange = (text: string) => {
+      if (this.pendingExit) this.clearPendingExit();
+      this.updateEditorBorderHighlight(text);
+    };
+
+    editor.onCtrlC = () => {
+      if (this.cancelInFlight !== undefined) {
+        const cancel = this.cancelInFlight;
+        this.cancelInFlight = undefined;
+        this.clearPendingExit();
+        cancel();
+        return;
+      }
+
+      if (this.state.appState.isStreaming) {
+        this.clearPendingExit();
+        this.cancelCurrentStream();
+        return;
+      }
+
+      if (this.state.appState.isCompacting) {
+        this.clearPendingExit();
+        this.cancelCurrentCompaction();
+        return;
+      }
+
+      if (this.pendingExit?.kind === 'ctrl-c') {
+        this.clearPendingExit();
+        void this.stop();
+        return;
+      }
+
+      if (editor.getText().length > 0) {
+        editor.setText('');
+      }
+      this.armPendingExit('ctrl-c', CTRL_C_HINT);
+    };
+
+    editor.onCtrlD = () => {
+      if (this.pendingExit?.kind === 'ctrl-d') {
+        this.clearPendingExit();
+        void this.stop();
+        return;
+      }
+      this.armPendingExit('ctrl-d', CTRL_D_HINT);
+    };
+
+    editor.onEscape = () => {
+      if (this.pendingExit) this.clearPendingExit();
+      if (this.state.showingSessionPicker) {
+        this.hideSessionPicker();
+        return;
+      }
+      if (this.state.appState.isStreaming) {
+        this.cancelCurrentStream();
+        return;
+      }
+      if (this.state.appState.isCompacting) {
+        this.cancelCurrentCompaction();
+      }
+    };
+
+    editor.onShiftTab = () => {
+      const session = this.session;
+      if (session === undefined) {
+        this.showError(NO_ACTIVE_SESSION_MESSAGE);
+        return;
+      }
+      const next = !this.state.appState.planMode;
+      this.track('shortcut_plan_toggle', { enabled: next });
+      this.track('shortcut_mode_switch', { to_mode: next ? 'plan' : 'agent' });
+      void this.applyPlanMode(session, next);
+    };
+
+    editor.onOpenExternalEditor = () => {
+      this.track('shortcut_editor');
+      void this.openExternalEditor();
+    };
+
+    editor.onToggleToolExpand = () => {
+      this.track('shortcut_expand');
+      this.toggleToolOutputExpansion();
+    };
+
+    editor.onTogglePlanExpand = () => this.togglePlanExpansion();
+
+    editor.onCtrlS = () => {
+      if (!this.state.appState.isStreaming || this.state.appState.isCompacting) return;
+      const text = editor.getText().trim();
+      const queuedTexts = this.state.queuedMessages.map((m) => m.text);
+      this.state.queuedMessages = [];
+
+      const parts: string[] = [];
+      for (const q of queuedTexts) {
+        const trimmed = q.trim();
+        if (trimmed.length > 0) parts.push(trimmed);
+      }
+      if (text.length > 0) parts.push(text);
+
+      if (parts.length > 0) {
+        editor.setText('');
+        const session = this.session;
+        if (this.state.appState.model.trim().length === 0 || session === undefined) {
+          this.showError(LLM_NOT_SET_MESSAGE);
+        } else {
+          this.steerMessage(session, parts);
+        }
+      }
+      this.updateQueueDisplay();
+      this.state.ui.requestRender();
+    };
+
+    editor.onUndo = () => {
+      this.track('undo');
+    };
+
+    editor.onInsertNewline = () => {
+      this.track('shortcut_newline');
+    };
+
+    editor.onTextPaste = () => {
+      this.track('shortcut_paste', { kind: 'text' });
+    };
+
+    editor.onUpArrowEmpty = () => {
+      if (!this.state.appState.isStreaming && !this.state.appState.isCompacting) return false;
+      const recalled = this.recallLastQueued();
+      if (recalled !== undefined) {
+        editor.setText(recalled);
+        this.updateQueueDisplay();
+        this.state.ui.requestRender();
+        return true;
+      }
+      return false;
+    };
+
+    editor.onPasteImage = async () => this.handleClipboardImagePaste();
+  }
+
+  // Cancels the pending double-key exit prompt.
+  private clearPendingExit(): void {
+    if (!this.pendingExit) return;
+    clearTimeout(this.pendingExit.timer);
+    this.state.footer.setTransientHint(null);
+    this.pendingExit = null;
+  }
+
+  // Starts a timed confirmation window for Ctrl-C or Ctrl-D exit.
+  private armPendingExit(kind: 'ctrl-c' | 'ctrl-d', hint: string): void {
+    this.clearPendingExit();
+    this.state.footer.setTransientHint(hint);
+
+    const timer = setTimeout(() => {
+      if (this.pendingExit?.timer === timer) {
+        this.clearPendingExit();
+        this.state.ui.requestRender();
+      }
+    }, EXIT_CONFIRM_WINDOW_MS);
+
+    this.pendingExit = { kind, timer };
+    this.state.ui.requestRender();
+  }
+
+  // Reads image or video data from the clipboard and inserts an attachment placeholder.
+  private async handleClipboardImagePaste(): Promise<boolean> {
+    let media;
+    try {
+      media = await readClipboardMedia();
+    } catch (error) {
+      if (error instanceof ClipboardMediaError) {
+        this.showError(error.message);
+        return true;
+      }
+      return false;
+    }
+    if (media === null) return false;
+
+    if (media.kind === 'video') {
+      const attachment = this.imageStore.addVideo(media.mimeType, media.sourcePath, media.filename);
+      this.state.editor.insertTextAtCursor?.(`${attachment.placeholder} `);
+      this.state.ui.requestRender();
+      this.track('shortcut_paste', { kind: 'video' });
+      return true;
+    }
+
+    const meta = parseImageMeta(media.bytes);
+    if (meta === null) return false;
+    const attachment = this.imageStore.addImage(media.bytes, meta.mime, meta.width, meta.height);
+    this.state.editor.insertTextAtCursor?.(`${attachment.placeholder} `);
+    this.state.ui.requestRender();
+    this.track('shortcut_paste', { kind: 'image' });
+    return true;
+  }
+
+  // Opens the configured external editor and writes the edited text back.
+  private async openExternalEditor(): Promise<void> {
+    if (this.state.externalEditorRunning) return;
+    const cmd = resolveEditorCommand(this.state.appState.editorCommand);
+    if (cmd === undefined) {
+      this.showError('No editor configured. Set $VISUAL / $EDITOR, or run /editor <command>.');
+      return;
+    }
+    this.state.externalEditorRunning = true;
+    const seed = this.state.editor.getExpandedText?.() ?? this.state.editor.getText();
+    this.state.ui.stop();
+    await new Promise<void>((resolve) => {
+      setImmediate(resolve);
+    });
+    try {
+      const result = await editInExternalEditor(seed, cmd);
+      if (result !== undefined) {
+        this.state.editor.setText(result.replaceAll('\r\n', '\n').replace(/\n$/, ''));
+      }
+    } catch (error) {
+      const msg = formatErrorMessage(error);
+      this.showError(`External editor failed: ${msg}`);
+    } finally {
+      if (typeof process.stdin.pause === 'function') {
+        process.stdin.pause();
+      }
+      this.state.ui.start();
+      this.state.ui.setFocus(this.state.editor);
+      this.state.ui.requestRender(true);
+      this.state.externalEditorRunning = false;
+    }
+  }
+
+  // =========================================================================
+  // Input Dispatch
+  // =========================================================================
+
+  // Routes submitted editor text to slash command handling or normal prompting.
+  private handleUserInput(text: string): void {
+    if (text.trim().length === 0) return;
+    if (this.state.appState.isReplaying) {
+      this.showError('Cannot send input while session history is replaying.');
+      return;
+    }
+    void this.persistInputHistory(text);
+    if (parseSlashInput(text) !== null) {
+      void this.executeSlashCommand(text);
+      return;
+    }
+
+    this.sendNormalUserInput(text);
+  }
+
+  // Parses and executes a slash command intent.
+  private async executeSlashCommand(input: string): Promise<void> {
+    const parsedCommand = parseSlashInput(input);
+    const intent = resolveSlashCommandInput({
+      input,
+      skillCommandMap: this.skillCommandMap,
+      isStreaming: this.state.appState.isStreaming,
+      isCompacting: this.state.appState.isCompacting,
+    });
+
+    switch (intent.kind) {
+      case 'not-command':
+        return;
+      case 'blocked':
+        this.track('input_command_invalid', { reason: 'blocked', command: intent.commandName });
+        this.showError(slashBusyMessage(intent.commandName, intent.reason));
+        return;
+      case 'skill': {
+        const session = this.session;
+        if (this.state.appState.model.trim().length === 0 || session === undefined) {
+          this.showError(LLM_NOT_SET_MESSAGE);
+          return;
+        }
+        this.track('input_command', {
+          command: intent.commandName,
+          skill_name: intent.skillName,
+        });
+        this.sendSkillActivation(session, intent.skillName, intent.args);
+        return;
+      }
+      case 'message': {
+        this.sendNormalUserInput(intent.input);
+        return;
+      }
+      case 'builtin':
+        this.track('input_command', { command: intent.name });
+        if (intent.name === 'new' && parsedCommand?.name === 'clear') {
+          this.track('clear');
+        }
+        try {
+          await this.handleBuiltInSlashCommand(intent.name, intent.args);
+        } catch (error) {
+          this.showError(formatErrorMessage(error));
+        }
+        return;
+    }
+  }
+
+  // Dispatches a built-in slash command to its concrete handler.
+  private async handleBuiltInSlashCommand(
+    name: BuiltinSlashCommandName,
+    args: string,
+  ): Promise<void> {
+    switch (name) {
+      case 'exit':
+        void this.stop();
+        return;
+      case 'help':
+        this.showHelpPanel();
+        return;
+      case 'version':
+        this.showStatus(`Kimi Code v${this.state.appState.version}`);
+        return;
+      case 'new':
+        await this.createNewSession();
+        this.state.ui.requestRender();
+        return;
+      case 'sessions':
+        void this.showSessionPicker();
+        return;
+      case 'tasks':
+        void this.showTasksBrowser();
+        return;
+      case 'mcp':
+        void this.showMcpServers();
+        return;
+      case 'editor':
+        await this.handleEditorCommand(args, {});
+        return;
+      case 'theme':
+        await this.handleThemeCommand(args);
+        return;
+      case 'model':
+        this.handleModelCommand(args);
+        return;
+      case 'permission':
+        this.showPermissionPicker();
+        return;
+      case 'settings':
+        this.showSettingsSelector();
+        return;
+      case 'usage':
+        void this.showUsage();
+        return;
+      case 'status':
+        void this.showStatusReport();
+        return;
+      case 'feedback':
+        await this.handleFeedbackCommand();
+        return;
+      case 'title':
+        await this.handleTitleCommand(args);
+        return;
+      case 'yolo':
+        await this.handleYoloCommand(args);
+        return;
+      case 'plan':
+        await this.handlePlanCommand(args);
+        return;
+      case 'compact':
+        await this.handleCompactCommand(args);
+        return;
+      case 'init':
+        await this.handleInitCommand();
+        return;
+      case 'fork':
+        await this.handleForkCommand(args);
+        return;
+      case 'login':
+        await this.handleLoginCommand();
+        return;
+      case 'logout':
+        await this.handleLogoutCommand();
+        return;
+      default:
+        this.showError(`Unknown slash command: /${String(name)}`);
+        return;
+    }
+  }
+
+  // Sends regular user input after validating model and media support.
+  private sendNormalUserInput(text: string): void {
+    if (this.state.appState.model.trim().length === 0) {
+      this.showError(LLM_NOT_SET_MESSAGE);
+      return;
+    }
+    const extraction = extractMediaAttachments(text, this.imageStore);
+    if (!this.validateMediaCapabilities(extraction)) return;
+    const session = this.session;
+    if (session === undefined) {
+      this.showError(LLM_NOT_SET_MESSAGE);
+      return;
+    }
+    if (extraction.hasMedia) {
+      this.sendMessage(session, text, {
+        hasMedia: true,
+        parts: extraction.parts,
+        imageAttachmentIds: extraction.imageAttachmentIds,
+      });
+    } else {
+      this.sendMessage(session, text);
+    }
+    this.updateQueueDisplay();
+    this.state.ui.requestRender();
+  }
+
+  // Checks whether the current model can accept attached media.
+  private validateMediaCapabilities(
+    extraction: ReturnType<typeof extractMediaAttachments>,
+  ): boolean {
+    if (!extraction.hasMedia) return true;
+    if (
+      extraction.imageAttachmentIds.length > 0 &&
+      !this.supportsCurrentModelCapability('image_in')
+    ) {
+      this.showError('Current model does not support image input.');
+      return false;
+    }
+    if (
+      extraction.videoAttachmentIds.length > 0 &&
+      !this.supportsCurrentModelCapability('video_in')
+    ) {
+      this.showError('Current model does not support video input.');
+      return false;
+    }
+    return true;
+  }
+
+  // Tests the active model's advertised capability list.
+  private supportsCurrentModelCapability(capability: string): boolean {
+    const capabilities =
+      this.state.appState.availableModels[this.state.appState.model]?.capabilities;
+    if (capabilities === undefined) return true;
+    return capabilities.includes(capability);
+  }
+
+  // Persists a submitted input line and mirrors it into editor history.
+  private async persistInputHistory(text: string): Promise<void> {
+    const trimmed = text.trim();
+    if (trimmed.length === 0) return;
+    if (trimmed === this.state.lastHistoryContent) return;
+    this.state.editor.addToHistory(trimmed);
+    try {
+      const file = getInputHistoryFile(this.state.appState.workDir);
+      const written = await appendInputHistory(file, trimmed, this.state.lastHistoryContent);
+      if (written) this.state.lastHistoryContent = trimmed;
+    } catch {
+      this.state.lastHistoryContent = trimmed;
+    }
+  }
+
+  // Pops the most recent queued message back into the editor.
+  private recallLastQueued(): string | undefined {
+    if (this.state.queuedMessages.length === 0) return undefined;
+    const last = this.state.queuedMessages.at(-1)!;
+    this.state.queuedMessages = this.state.queuedMessages.slice(0, -1);
+    return last.text;
+  }
+
+  // =========================================================================
+  // Session Requests / Queues
+  // =========================================================================
+
+  // Adds a message to the queue for delivery after current work finishes.
+  private enqueueMessage(text: string, options?: SendMessageOptions): void {
+    this.state.queuedMessages.push({
+      text,
+      agentId: this.harness.interactiveAgentId,
+      parts: options?.parts,
+      imageAttachmentIds:
+        options?.imageAttachmentIds !== undefined && options.imageAttachmentIds.length > 0
+          ? options.imageAttachmentIds
+          : undefined,
+    });
+    this.track('input_queue');
+  }
+
+  // Resets request-scoped state before submitting work to the active session.
+  private beginSessionRequest(): void {
+    this.state.currentTurnId = undefined;
+    this.resetLiveTextRuntime();
+    this.resetLiveToolUiState();
+    this.resetToolCallState();
+
+    this.patchLivePane({
+      mode: 'waiting',
+      pendingApproval: null,
+      pendingQuestion: null,
+    });
+    this.setAppState({
+      isStreaming: true,
+      streamingPhase: 'waiting',
+      streamingStartTime: Date.now(),
+    });
+  }
+
+  // Ends a failed session request and renders the failure to the transcript.
+  private failSessionRequest(message: string): void {
+    this.setAppState({ isStreaming: false, streamingPhase: 'idle' });
+    this.resetLivePane();
+    this.showError(message);
+  }
+
+  // Sends a queued message after restoring the agent target captured at enqueue time.
+  private sendQueuedMessage(session: Session, item: QueuedMessage): void {
+    this.harness.interactiveAgentId = item.agentId ?? MAIN_AGENT_ID;
+    this.sendMessageInternal(session, item.text, {
+      parts: item.parts,
+      imageAttachmentIds: item.imageAttachmentIds,
+    });
+  }
+
+  // Appends the user message and sends the prompt to the session immediately.
+  private sendMessageInternal(session: Session, input: string, options?: SendMessageOptions): void {
+    const imageAttachmentIds =
+      options?.imageAttachmentIds !== undefined && options.imageAttachmentIds.length > 0
+        ? options.imageAttachmentIds
+        : undefined;
+    this.appendTranscriptEntry({
+      id: nextTranscriptId(),
+      kind: 'user',
+      turnId: undefined,
+      renderMode: 'plain',
+      content: input,
+      imageAttachmentIds,
+    });
+
+    this.beginSessionRequest();
+
+    const sdkInput = options?.parts ?? input;
+    void session.prompt(sdkInput).catch((error: unknown) => {
+      const message = formatErrorMessage(error);
+      this.failSessionRequest(`Failed to send: ${message}`);
+    });
+  }
+
+  // Starts a skill activation turn on the session.
+  private sendSkillActivation(session: Session, skillName: string, skillArgs: string): void {
+    this.beginSessionRequest();
+    void session.activateSkill(skillName, skillArgs).catch((error: unknown) => {
+      const message = formatErrorMessage(error);
+      this.failSessionRequest(`Skill "${skillName}" failed: ${message}`);
+    });
+  }
+
+  // Sends a message now or queues it when the session is busy.
+  private sendMessage(session: Session, input: string, options?: SendMessageOptions): void {
+    if (
+      this.deferUserMessages ||
+      this.state.appState.isStreaming ||
+      this.state.appState.isCompacting
+    ) {
+      this.enqueueMessage(input, options);
+      return;
+    }
+    this.sendMessageInternal(session, input, options);
+  }
+
+  // Sends steering input into an active stream or falls back to normal prompts.
+  private steerMessage(session: Session, input: string[]): void {
+    if (this.deferUserMessages || this.state.appState.isCompacting) {
+      for (const part of input) {
+        this.enqueueMessage(part);
+      }
+      return;
+    }
+    if (!this.state.appState.isStreaming) {
+      for (const part of input) {
+        this.sendMessageInternal(session, part);
+      }
+      return;
+    }
+
+    for (const part of input) {
+      this.appendTranscriptEntry({
+        id: nextTranscriptId(),
+        kind: 'user',
+        turnId: this.state.currentTurnId,
+        renderMode: 'plain',
+        content: part,
+      });
+    }
+
+    void session.steer(input.join('\n\n')).catch((error: unknown) => {
+      const message = formatErrorMessage(error);
+      this.showError(`Failed to steer: ${message}`);
+    });
+  }
+
+  // Requests cancellation of the active session stream.
+  private cancelCurrentStream(): void {
+    const session = this.session;
+    if (session === undefined) return;
+    void session.cancel();
+  }
+
+  private cancelCurrentCompaction(): void {
+    const session = this.session;
+    if (session === undefined) return;
+    void session.cancelCompaction().catch((error: unknown) => {
+      const message = formatErrorMessage(error);
+      this.showError(`Failed to cancel compaction: ${message}`);
+    });
+  }
+
+  // Finalizes live thinking output and moves the live pane to the next mode.
+  private flushThinkingToTranscript(nextMode: LivePaneState['mode'] = 'idle'): void {
+    if (this.state.thinkingDraft.length === 0) {
+      this.patchLivePane({ mode: nextMode });
+      return;
+    }
+    this.state.thinkingDraft = '';
+    this.onThinkingEnd();
+    this.patchLivePane({ mode: nextMode });
+  }
+
+  // Finalizes live assistant text and clears streaming component state.
+  private finalizeAssistantStream(): void {
+    if (this.state.assistantStreamActive) {
+      this.onStreamingTextEnd();
+      this.state.assistantStreamActive = false;
+    }
+    this.state.assistantDraft = '';
+    this.updateActivityPane();
+    this.state.ui.requestRender();
+  }
+
+  // Discards live thinking and assistant text state without finalizing transcript output.
+  private resetLiveTextRuntime(): void {
+    this.state.assistantDraft = '';
+    this.state.assistantStreamActive = false;
+    this.state.streamingComponent = undefined;
+    this.state.streamingTranscriptEntry = undefined;
+    this.state.thinkingDraft = '';
+    this.disposeActiveThinkingComponent();
+  }
+
+  // Clears live tool UI state while preserving active tool-call tracking.
+  private resetLiveToolUiState(): void {
+    this.state.streamingToolCallArguments.clear();
+    this.disposeAndClearPendingToolComponents();
+    this.state.pendingAgentGroup = null;
+    this.state.pendingReadGroup = null;
+  }
+
+  // Clears SDK tool-call tracking.
+  private resetToolCallState(): void {
+    this.state.activeToolCalls.clear();
+  }
+
+  // Finalizes any live thinking and assistant text for a phase transition.
+  private finalizeLiveTextBuffers(nextMode: LivePaneState['mode'] = 'idle'): void {
+    this.flushThinkingToTranscript(nextMode);
+    this.finalizeAssistantStream();
+  }
+
+  // Completes a turn, dispatches queued work, and sends completion notification.
+  private finalizeTurn(sendQueued: (item: QueuedMessage) => void): void {
+    if (!this.state.appState.isStreaming) return;
+    this.deferUserMessages = false;
+    const completedTurnKey =
+      this.state.currentTurnId ?? `local:${String(this.state.appState.streamingStartTime)}`;
+    this.finalizeLiveTextBuffers('idle');
+    this.resetToolCallState();
+    this.state.currentTurnId = undefined;
+
+    if (this.state.queuedMessages.length > 0) {
+      const [next, ...rest] = this.state.queuedMessages;
+      this.state.queuedMessages = rest;
+      this.setAppState({ isStreaming: false, streamingPhase: 'idle' });
+      this.resetLivePane();
+      if (next !== undefined) {
+        setTimeout(() => {
+          sendQueued(next);
+        }, 0);
+      }
+      return;
+    }
+
+    this.setAppState({ isStreaming: false, streamingPhase: 'idle' });
+    this.resetLivePane();
+    notifyTerminalOnce(this.state, `turn-complete:${completedTurnKey}`, {
+      title: 'Kimi Code task complete',
+      body: this.state.appState.sessionTitle ?? undefined,
+    });
+  }
+
+  // =========================================================================
+  // State Helpers
+  // =========================================================================
+
+  // Applies app-state changes and refreshes dependent UI surfaces.
+  private setAppState(patch: Partial<AppState>): void {
+    const busyChanged = 'isStreaming' in patch || 'isCompacting' in patch;
+    Object.assign(this.state.appState, patch);
+    if ('planMode' in patch) this.updateEditorBorderHighlight();
+    this.state.footer.setState(this.state.appState);
+    this.updateActivityPane();
+    if (busyChanged) this.updateQueueDisplay();
+    this.state.ui.requestRender();
+  }
+
+  // Applies live-pane changes and refreshes activity presentation.
+  private patchLivePane(patch: Partial<LivePaneState>): void {
+    Object.assign(this.state.livePane, patch);
+    this.updateActivityPane();
+    this.state.ui.requestRender();
+  }
+
+  // Restores the live pane to its initial idle state.
+  private resetLivePane(): void {
+    this.state.livePane = { ...INITIAL_LIVE_PANE };
+    this.updateActivityPane();
+    this.state.ui.requestRender();
+  }
+
+  // =========================================================================
+  // Session Runtime
+  // =========================================================================
+
+  // Returns the active session or raises the standard no-session error.
+  private requireSession(): Session {
+    if (this.session === undefined) {
+      throw new Error(NO_ACTIVE_SESSION_MESSAGE);
+    }
+    return this.session;
+  }
+
+  // Creates a session using the current model, known session runtime, permission, and plan state.
+  private async createSessionFromCurrentState(): Promise<Session> {
+    const model = this.state.appState.model.trim();
+    if (model.length === 0) {
+      throw new Error(LLM_NOT_SET_MESSAGE);
+    }
+    return this.harness.createSession({
+      workDir: this.state.appState.workDir,
+      model,
+      thinking:
+        this.session === undefined ? undefined : this.state.appState.thinking ? 'on' : 'off',
+      permission: this.state.appState.permissionMode,
+      planMode: this.state.appState.planMode ? true : undefined,
+    });
+  }
+
+  // Replaces the active session and installs approval/question handlers.
+  private async setSession(session: Session): Promise<void> {
+    const previous = this.unloadCurrentSession('switching session');
+    await previous?.close();
+    this.session = session;
+    this.harness.setTelemetryContext({ sessionId: session.id });
+    this.registerSessionHandlers(session);
+  }
+
+  // Pulls runtime session status into the app state.
+  private async syncRuntimeState(session: Session = this.requireSession()): Promise<void> {
+    const status = await session.getStatus();
+    this.setAppState({
+      sessionId: session.id,
+      model: status.model ?? '',
+      thinking: status.thinkingLevel !== 'off',
+      permissionMode: status.permission,
+      yolo: status.permission === 'yolo',
+      planMode: status.planMode,
+      contextTokens: status.contextTokens,
+      maxContextTokens: status.maxContextTokens,
+      contextUsage: status.contextUsage,
+      sessionTitle: session.summary?.title ?? null,
+    });
+  }
+
+  // Applies current permission and plan settings to the active session.
+  private async activateRuntime(): Promise<void> {
+    const session = this.requireSession();
+    await session.setPermission(this.state.appState.permissionMode);
+    if (this.state.appState.planMode) {
+      await session.setPlanMode(true);
+    }
+    await this.syncRuntimeState(session);
+  }
+
+  // Detaches and closes the current session.
+  private async closeSession(reason: string): Promise<void> {
+    const previous = this.unloadCurrentSession(reason);
+    await previous?.close();
+  }
+
+  // Detaches session subscriptions and cancels pending interactive requests.
+  private unloadCurrentSession(reason: string): Session | undefined {
+    const previous = this.session;
+    this.sessionEventUnsubscribe?.();
+    this.sessionEventUnsubscribe = undefined;
+    this.clearReverseRpcPanels();
+    previous?.setApprovalHandler(undefined);
+    previous?.setQuestionHandler(undefined);
+    this.approvalController.cancelAll(reason);
+    this.questionController.cancelAll(reason);
+    this.session = undefined;
+    this.harness.setTelemetryContext({ sessionId: null });
+    return previous;
+  }
+
+  private clearReverseRpcPanels(): void {
+    for (const dispose of this.reverseRpcDisposers) {
+      dispose();
+    }
+  }
+
+  // Connects session approval and question requests to local controllers.
+  private registerSessionHandlers(session: Session): void {
+    session.setApprovalHandler(
+      createApprovalRequestHandler(this.approvalController, (request, response) => {
+        this.appendApprovalTranscriptEntry(request, response);
+      }),
+    );
+    session.setQuestionHandler(createQuestionAskHandler(this.questionController));
+  }
+
+  // Loads session picker rows for the current working directory.
+  private async fetchSessions(): Promise<void> {
+    this.state.loadingSessions = true;
+    try {
+      const sessions = await this.harness.listSessions({ workDir: this.state.appState.workDir });
+      this.state.sessions = sessions.map((session) => ({
+        id: session.id,
+        title: session.title ?? null,
+        last_prompt: session.lastPrompt ?? null,
+        work_dir: session.workDir,
+        updated_at: session.updatedAt ?? session.createdAt ?? 0,
+        metadata: session.metadata,
+      }));
+    } catch {
+      /* silently ignore */
+    } finally {
+      this.state.loadingSessions = false;
+    }
+  }
+
+  // Syncs the process title with the current session title and id.
+  private refreshSessionTitle(): void {
+    setProcessTitle(this.state.appState.sessionTitle, this.state.appState.sessionId);
+  }
+
+  // Resets turn, tool, queue, and background-agent state for a session switch.
+  private resetSessionRuntime(): void {
+    this.aborted = false;
+    this.state.queuedMessages = [];
+    this.harness.interactiveAgentId = MAIN_AGENT_ID;
+    this.resetToolCallState();
+    this.resetLiveToolUiState();
+    this.state.backgroundAgents.clear();
+    this.state.backgroundAgentMetadata.clear();
+    this.state.backgroundTasks.clear();
+    this.state.backgroundTaskTranscriptedTerminal.clear();
+    this.closeTasksBrowser();
+    this.state.subagentParentToolCallIds.clear();
+    this.state.subagentNames.clear();
+    this.state.renderedSkillActivationIds.clear();
+    this.state.renderedMcpServerStatusKeys.clear();
+    this.stopAllMcpServerStatusSpinners();
+    this.state.footer.setBackgroundCounts({ bashTasks: 0, agentTasks: 0 });
+    this.setTodoList([]);
+    this.state.currentTurnId = undefined;
+    this.state.currentStep = 0;
+    this.resetLiveTextRuntime();
+    this.updateQueueDisplay();
+  }
+
+  // Switches to an existing session and replays its transcript.
+  private async resumeSession(targetSessionId: string): Promise<boolean> {
+    if (targetSessionId === this.state.appState.sessionId) {
+      this.showStatus('Already on this session.');
+      return true;
+    }
+    if (this.state.appState.isStreaming) {
+      this.showError('Cannot switch sessions while streaming — press Esc or Ctrl-C first.');
+      return false;
+    }
+    if (this.state.appState.isReplaying) {
+      this.showError('Cannot switch sessions while history is replaying.');
+      return false;
+    }
+
+    let session: Session;
+    try {
+      session = await this.harness.resumeSession({ id: targetSessionId });
+    } catch (error) {
+      const msg = formatErrorMessage(error);
+      this.showError(`Failed to resume session ${targetSessionId}: ${msg}`);
+      return false;
+    }
+
+    await this.switchToSession(session, `Resumed session (${session.id}).`);
+    return true;
+  }
+
+  // Switches to a provided session and replays its transcript.
+  private async switchToSession(session: Session, statusMessage: string): Promise<void> {
+    this.resetSessionRuntime();
+    await this.setSession(session);
+    await this.syncRuntimeState(session);
+    this.refreshSessionTitle();
+    try {
+      await this.refreshSkillCommands(this.session);
+    } catch {
+      /* keep the switched session usable even if dynamic skills fail */
+    }
+    this.clearTranscriptAndRedraw();
+    try {
+      await hydrateTranscriptFromReplay(this.state, this.replayHydrationHooks(), session);
+    } catch (error) {
+      const msg = formatErrorMessage(error);
+      this.showError(`Failed to replay session history: ${msg}`);
+    } finally {
+      this.startSessionEventSubscription();
+    }
+    this.showStatus(statusMessage);
+  }
+
+  // Creates a fresh session from current UI settings and resets the transcript.
+  private async createNewSession(): Promise<void> {
+    if (this.state.appState.isReplaying) {
+      this.showError('Cannot start a new session while history is replaying.');
+      return;
+    }
+
+    let session: Session;
+    try {
+      session = await this.createSessionFromCurrentState();
+    } catch (error) {
+      const msg = formatErrorMessage(error);
+      this.showError(`Failed to start a new session: ${msg}`);
+      return;
+    }
+
+    this.resetSessionRuntime();
+    await this.setSession(session);
+    this.setAppState({ sessionId: session.id });
+    try {
+      await this.activateRuntime();
+      await this.syncRuntimeState(session);
+    } catch (error) {
+      const msg = formatErrorMessage(error);
+      this.showError(`Post-create setup failed: ${msg}`);
+      return;
+    }
+    try {
+      await this.refreshSkillCommands(this.session);
+    } catch {
+      /* keep the new session usable even if dynamic skills fail */
+    }
+    this.startSessionEventSubscription();
+    this.clearTranscriptAndRedraw();
+    this.showStatus(`Started a new session (${session.id}).`);
+  }
+
+  // =========================================================================
+  // Session Events
+  // =========================================================================
+
+  private startSessionEventSubscription(): void {
+    const session = this.requireSession();
+    const sendQueued = (item: QueuedMessage): void => {
+      this.sendQueuedMessage(session, item);
+    };
+    this.sessionEventUnsubscribe?.();
+    const mcpOAuthOpener = new McpOAuthAuthorizationUrlOpener(openUrl);
+    const { sessionId } = this.state.appState;
+    this.sessionEventUnsubscribe = session.onEvent((event) => {
+      if (this.aborted) return;
+      if (event.sessionId !== sessionId) return;
+      if (event.type === 'tool.progress') {
+        mcpOAuthOpener.handleToolProgress(event);
+      }
+      this.handleEvent(event, sendQueued);
+    });
+    void this.syncMcpServerStatusSnapshot(session);
+  }
+
+  private async syncMcpServerStatusSnapshot(session: Session): Promise<void> {
+    let servers: readonly McpServerStatusSnapshot[];
+    try {
+      servers = await session.listMcpServers();
+    } catch (error) {
+      if (this.session !== session || this.aborted) return;
+      const message = error instanceof Error ? error.message : String(error);
+      this.showError(`Failed to sync MCP server status: ${message}`);
+      return;
+    }
+    if (this.session !== session || this.state.appState.sessionId !== session.id) return;
+
+    const visible = selectMcpStartupStatusRows(servers);
+    const visibleNames = new Set(visible.map((server) => server.name));
+    for (const server of visible) {
+      if (this.state.renderedMcpServerStatusKeys.has(server.name)) continue;
+      this.renderMcpServerStatus(server);
+    }
+
+    const hidden: McpServerStatusSnapshot[] = [];
+    for (const server of servers) {
+      if (visibleNames.has(server.name)) continue;
+      if (this.state.renderedMcpServerStatusKeys.has(server.name)) continue;
+      this.state.renderedMcpServerStatusKeys.set(server.name, mcpServerStatusKey(server));
+      hidden.push(server);
+    }
+    if (hidden.length > 0) {
+      this.showStatus(
+        formatMcpStartupStatusSummary(hidden, visible.length),
+        this.state.theme.colors.textMuted,
+      );
+    }
+  }
+
+  // Routes an SDK event to the matching TUI state transition.
+  private handleEvent(event: Event, sendQueued: (item: QueuedMessage) => void): void {
+    if (this.routeSubagentEvent(event)) {
+      return;
+    }
+
+    if ('turnId' in event && event.turnId !== undefined) {
+      this.state.currentTurnId = String(event.turnId);
+    }
+
+    switch (event.type) {
+      case 'turn.started':
+        this.handleTurnBegin(event);
+        break;
+      case 'turn.ended':
+        this.handleTurnEnd(event, sendQueued);
+        break;
+      case 'turn.step.started':
+        this.handleStepBegin(event);
+        break;
+      case 'turn.step.interrupted':
+        this.handleStepInterrupted(event);
+        break;
+      case 'turn.step.completed':
+        this.handleStepCompleted(event);
+        break;
+      case 'turn.step.retrying':
+        break;
+      case 'tool.progress':
+        this.handleToolProgress(event);
+        break;
+      case 'assistant.delta':
+        this.handleAssistantDelta(event);
+        break;
+      case 'hook.result':
+        this.handleHookResult(event);
+        break;
+      case 'thinking.delta':
+        this.handleThinkingDelta(event);
+        break;
+      case 'tool.call.started':
+        this.handleToolCall(event);
+        break;
+      case 'tool.call.delta':
+        this.handleToolCallDelta(event);
+        break;
+      case 'tool.result':
+        this.handleToolResult(event);
+        break;
+      case 'agent.status.updated':
+        this.handleStatusUpdate(event);
+        break;
+      case 'session.meta.updated':
+        this.handleSessionMetaChanged(event);
+        break;
+      case 'skill.activated':
+        this.handleSkillActivated(event);
+        break;
+      case 'error':
+        this.handleSessionError(event);
+        break;
+      case 'compaction.started':
+        this.handleCompactionBegin(event);
+        break;
+      case 'compaction.completed':
+        this.handleCompactionEnd(event, sendQueued);
+        break;
+      case 'compaction.blocked':
+        break;
+      case 'compaction.cancelled':
+        this.handleCompactionCancel(event, sendQueued);
+        break;
+      case 'subagent.spawned':
+        this.handleSubagentSpawned(event);
+        break;
+      case 'subagent.completed':
+        this.handleSubagentCompleted(event);
+        break;
+      case 'subagent.failed':
+        this.handleSubagentFailed(event);
+        break;
+      case 'background.task.started':
+      case 'background.task.updated':
+      case 'background.task.terminated':
+        this.handleBackgroundTaskEvent(event);
+        break;
+      case 'mcp.server.status':
+        this.renderMcpServerStatus(event.server);
+        break;
+      case 'tool.list.updated':
+        break;
+      default:
+        break;
+    }
+  }
+
+  // Routes child-agent events into their parent tool-call component.
+  private routeSubagentEvent(event: Event): boolean {
+    const subagentId = event.agentId;
+    if (subagentId === MAIN_AGENT_ID) return false;
+
+    const parentToolCallId = this.state.subagentParentToolCallIds.get(subagentId);
+    if (parentToolCallId === undefined || parentToolCallId.length === 0) return true;
+    const sourceName = this.state.subagentNames.get(subagentId);
+    const toolCall = this.state.pendingToolComponents.get(parentToolCallId);
+    if (toolCall === undefined) return true;
+    toolCall.setSubagentMeta(subagentId, sourceName);
+
+    switch (event.type) {
+      case 'hook.result':
+        toolCall.appendSubagentText(formatHookResultPlain(event), 'text');
+        return true;
+      case 'assistant.delta':
+        toolCall.appendSubagentText(event.delta, 'text');
+        return true;
+      case 'thinking.delta':
+        toolCall.appendSubagentText(event.delta, 'thinking');
+        return true;
+      case 'tool.call.started':
+        toolCall.appendSubToolCall({
+          id: `${subagentId}:${event.toolCallId}`,
+          name: event.name,
+          args: argsRecord(event.args),
+        });
+        return true;
+      case 'tool.call.delta':
+        toolCall.appendSubToolCallDelta({
+          id: `${subagentId}:${event.toolCallId}`,
+          name: event.name,
+          argumentsPart: event.argumentsPart ?? null,
+        });
+        return true;
+      case 'tool.result':
+        toolCall.finishSubToolCall({
+          tool_call_id: `${subagentId}:${event.toolCallId}`,
+          output: serializeToolResultOutput(event.output),
+          is_error: event.isError,
+        });
+        return true;
+      case 'agent.status.updated':
+      case 'background.task.started':
+      case 'background.task.updated':
+      case 'background.task.terminated':
+      case 'compaction.blocked':
+      case 'compaction.cancelled':
+      case 'compaction.completed':
+      case 'compaction.started':
+      case 'error':
+      case 'session.meta.updated':
+      case 'skill.activated':
+      case 'subagent.completed':
+      case 'subagent.failed':
+      case 'subagent.spawned':
+      case 'tool.progress':
+      case 'tool.list.updated':
+      case 'mcp.server.status':
+      case 'turn.ended':
+      case 'turn.started':
+      case 'turn.step.completed':
+      case 'turn.step.interrupted':
+      case 'turn.step.retrying':
+      case 'turn.step.started':
+        return true;
+      default:
+        return true;
+    }
+  }
+
+  // Initializes turn-scoped buffers when the SDK starts a turn.
+  private handleTurnBegin(_event: TurnStartedEvent): void {
+    void _event;
+    this.resetLiveToolUiState();
+    this.state.currentStep = 0;
+    this.patchLivePane({
+      mode: 'waiting',
+      pendingApproval: null,
+      pendingQuestion: null,
+    });
+    this.setAppState({
+      isStreaming: true,
+      streamingPhase: 'waiting',
+      streamingStartTime: Date.now(),
+    });
+  }
+
+  // Finalizes turn-scoped state when the SDK completes a turn.
+  private handleTurnEnd(_event: TurnEndedEvent, sendQueued: (item: QueuedMessage) => void): void {
+    void _event;
+    const todos = this.state.todoPanel.getTodos();
+    if (todos.length > 0 && todos.every((t) => t.status === 'done')) {
+      this.setTodoList([]);
+    }
+    this.resetLiveToolUiState();
+    this.finalizeTurn(sendQueued);
+  }
+
+  // Resets live render state for a new turn step.
+  private handleStepBegin(event: TurnStepStartedEvent): void {
+    this.state.currentStep = event.step;
+    this.resetLiveToolUiState();
+    this.finalizeLiveTextBuffers('waiting');
+    this.patchLivePane({
+      mode: 'waiting',
+      pendingApproval: null,
+      pendingQuestion: null,
+    });
+    this.setAppState({
+      streamingPhase: 'waiting',
+      streamingStartTime: Date.now(),
+    });
+  }
+
+  // Surfaces step-level outcomes the user needs to act on. The common
+  // case (finishReason === 'tool_use' or 'end_turn') is silent — those
+  // already render via tool.call.started/tool.result and assistant.delta.
+  // The interesting case is max_tokens: the model started a tool_use but
+  // ran out of budget before finalizing it, so the partial tool call is
+  // still pinned in 'Preparing' state with no signal that anything went
+  // wrong. Flip those into a visible 'Truncated' state and append a
+  // notice pointing at the config knob.
+  private handleStepCompleted(event: TurnStepCompletedEvent): void {
+    if (event.finishReason !== 'max_tokens') return;
+
+    // Scope the truncation marking to tool calls that belong to the
+    // step that just completed. Without this guard, stale entries from
+    // earlier retry attempts (or unrelated still-tracked calls) would
+    // get relabeled and counted, producing misleading "tool call was
+    // truncated" notices for the wrong step.
+    const eventTurnId = String(event.turnId);
+    let truncatedCount = 0;
+    for (const toolCall of this.state.activeToolCalls.values()) {
+      if (toolCall.result !== undefined) continue;
+      if (toolCall.streamingArguments === undefined) continue;
+      if (toolCall.turnId !== eventTurnId) continue;
+      if (toolCall.step !== event.step) continue;
+      toolCall.truncated = true;
+      const component = this.state.pendingToolComponents.get(toolCall.id);
+      if (component !== undefined) {
+        component.updateToolCall(toolCall);
+      }
+      truncatedCount += 1;
+    }
+    this.state.streamingToolCallArguments.clear();
+
+    const title =
+      truncatedCount > 0
+        ? 'Model hit max_tokens — tool call was truncated before it could run.'
+        : 'Model hit max_tokens — no tool call was emitted.';
+    // The `max_output_size` knob is only wired through to provider
+    // requests for the Anthropic provider (see toKosongProviderConfig).
+    // For OpenAI / Kimi / Google sessions the advice would be a
+    // dead end, so skip the second line on those providers.
+    const detail = this.isAnthropicSessionActive()
+      ? 'If this limit is wrong for your model, set `max_output_size` on the model alias in your kimi-code config.'
+      : undefined;
+    this.showNotice(title, detail);
+  }
+
+  private isAnthropicSessionActive(): boolean {
+    const providerKey = this.state.appState.availableModels[this.state.appState.model]?.provider;
+    if (providerKey === undefined) return false;
+    return this.state.appState.availableProviders[providerKey]?.type === 'anthropic';
+  }
+
+  // Renders user-facing status for an interrupted turn step.
+  private handleStepInterrupted(event: TurnStepInterruptedEvent): void {
+    this.resetLiveToolUiState();
+    this.finalizeLiveTextBuffers('idle');
+    const reason = event.reason;
+    if (reason === 'error') return;
+    if (reason === 'aborted' || reason === undefined || reason === '') {
+      this.showStatus('Interrupted by user', this.state.theme.colors.error);
+      return;
+    }
+    this.showError(
+      reason === 'max_steps'
+        ? 'reached per-turn step limit (max_steps)'
+        : `step interrupted (${reason})`,
+    );
+  }
+
+  // Appends a thinking delta to the live thinking block.
+  private handleThinkingDelta(event: ThinkingDeltaEvent): void {
+    this.state.thinkingDraft += event.delta;
+    this.onThinkingUpdate(this.state.thinkingDraft);
+    this.patchLivePane({ mode: 'idle' });
+    this.setAppState({ streamingPhase: 'thinking' });
+  }
+
+  // Appends an assistant text delta to the live assistant block.
+  private handleAssistantDelta(event: AssistantDeltaEvent): void {
+    if (this.state.thinkingDraft.length > 0) {
+      this.flushThinkingToTranscript('idle');
+    }
+
+    if (!this.state.assistantStreamActive) {
+      this.state.assistantStreamActive = true;
+      this.onStreamingTextStart();
+    }
+
+    this.state.assistantDraft += event.delta;
+    this.onStreamingTextUpdate(this.state.assistantDraft);
+
+    this.patchLivePane({
+      mode: 'idle',
+      pendingApproval: null,
+      pendingQuestion: null,
+    });
+    this.setAppState({
+      streamingPhase: 'composing',
+      streamingStartTime: Date.now(),
+    });
+  }
+
+  private handleHookResult(event: HookResultEvent): void {
+    if (this.state.thinkingDraft.length > 0) {
+      this.flushThinkingToTranscript('idle');
+    }
+    this.finalizeAssistantStream();
+    this.appendTranscriptEntry({
+      id: nextTranscriptId(),
+      kind: 'assistant',
+      turnId: String(event.turnId),
+      renderMode: 'markdown',
+      content: formatHookResultMarkdown(event),
+    });
+    this.patchLivePane({
+      mode: 'idle',
+      pendingApproval: null,
+      pendingQuestion: null,
+    });
+  }
+
+  // Starts or updates a rendered tool call from a tool-call start event.
+  private handleToolCall(event: ToolCallStartedEvent): void {
+    const toolCall: ToolCallBlockData = {
+      id: event.toolCallId,
+      name: event.name,
+      args: argsRecord(event.args),
+      description: event.description,
+      display: event.display,
+      step: this.state.currentStep,
+      turnId: this.state.currentTurnId,
+    };
+    const existing = this.state.activeToolCalls.get(event.toolCallId);
+    this.state.activeToolCalls.set(event.toolCallId, toolCall);
+    this.state.streamingToolCallArguments.delete(event.toolCallId);
+    const existingComponent = this.state.pendingToolComponents.get(event.toolCallId);
+    if (existingComponent !== undefined) {
+      existingComponent.updateToolCall(toolCall);
+    } else if (existing === undefined) {
+      this.finalizeLiveTextBuffers('tool');
+      if (event.name !== 'Agent') {
+        this.onToolCallStart(toolCall);
+      }
+    }
+    this.patchLivePane({
+      mode: 'tool',
+      pendingApproval: null,
+      pendingQuestion: null,
+    });
+  }
+
+  // Accumulates streaming tool-call arguments and updates the rendered call.
+  private handleToolCallDelta(event: ToolCallDeltaEvent): void {
+    if (event.toolCallId.length === 0) return;
+    const id = event.toolCallId;
+    const existing = this.state.streamingToolCallArguments.get(id);
+    const argumentsText = `${existing?.argumentsText ?? ''}${event.argumentsPart ?? ''}`;
+    const name = event.name ?? existing?.name ?? this.state.activeToolCalls.get(id)?.name ?? 'Tool';
+    const startedAtMs = existing?.startedAtMs ?? Date.now();
+    this.state.streamingToolCallArguments.set(id, { name, argumentsText, startedAtMs });
+
+    const toolCall: ToolCallBlockData = {
+      id,
+      name,
+      args: parseStreamingArgs(argumentsText),
+      streamingArguments: argumentsText,
+      streamingStartedAtMs: startedAtMs,
+      step: this.state.currentStep,
+      turnId: this.state.currentTurnId,
+    };
+    this.state.activeToolCalls.set(id, toolCall);
+
+    if (this.state.thinkingDraft.length > 0 || this.state.assistantStreamActive) {
+      this.finalizeLiveTextBuffers('tool');
+    }
+
+    const existingComponent = this.state.pendingToolComponents.get(id);
+    if (existingComponent !== undefined) {
+      existingComponent.updateToolCall(toolCall);
+    } else if (name !== 'Agent') {
+      this.onToolCallStart(toolCall);
+    }
+
+    this.patchLivePane({
+      mode: 'tool',
+      pendingApproval: null,
+      pendingQuestion: null,
+    });
+    this.setAppState({
+      streamingPhase: 'composing',
+      streamingStartTime: Date.now(),
+    });
+  }
+
+  // Streams a `{kind:'status'}` progress text into the live tool box so
+  // long-blocking tools (e.g. the MCP synthetic `authenticate` tool whose
+  // 15-minute browser wait would otherwise show only a spinner) can surface
+  // their authorization URL. Non-status update kinds stay out of the terminal
+  // transcript because only status text needs persistent display.
+  private handleToolProgress(event: ToolProgressEvent): void {
+    if (event.update.kind !== 'status') return;
+    const text = event.update.text;
+    if (text === undefined || text.length === 0) return;
+    const tc = this.state.pendingToolComponents.get(event.toolCallId);
+    if (tc === undefined) return;
+    tc.appendProgress(text);
+  }
+
+  // Completes a tool call and applies any tool-specific UI side effects.
+  private handleToolResult(event: ToolResultEvent): void {
+    const matchedCall = this.state.activeToolCalls.get(event.toolCallId);
+    const resultData: ToolResultBlockData = {
+      tool_call_id: event.toolCallId,
+      output: serializeToolResultOutput(event.output),
+      is_error: event.isError,
+      synthetic: event.synthetic,
+    };
+    if (matchedCall !== undefined) {
+      this.onToolCallEnd(event.toolCallId, resultData);
+      if (matchedCall.name === 'TodoList' && !event.isError) {
+        const rawTodos = (matchedCall.args as { todos?: unknown }).todos;
+        if (Array.isArray(rawTodos)) {
+          const sanitized = rawTodos
+            .filter((todo): todo is { title: string; status: 'pending' | 'in_progress' | 'done' } =>
+              isTodoItemShape(todo),
+            )
+            .map((t) => ({ title: t.title, status: t.status }));
+          this.setTodoList(sanitized);
+        }
+      }
+    }
+    this.state.activeToolCalls.delete(event.toolCallId);
+    this.state.streamingToolCallArguments.delete(event.toolCallId);
+    this.patchLivePane({ mode: 'waiting' });
+  }
+
+  // Applies agent status updates to app state.
+  private handleStatusUpdate(event: AgentStatusUpdatedEvent): void {
+    const patch: Partial<AppState> = {};
+    if (event.contextUsage !== undefined) patch.contextUsage = event.contextUsage;
+    if (event.contextTokens !== undefined) patch.contextTokens = event.contextTokens;
+    if (event.maxContextTokens !== undefined) patch.maxContextTokens = event.maxContextTokens;
+    if (event.planMode !== undefined) patch.planMode = event.planMode;
+    if (event.permission !== undefined) {
+      patch.permissionMode = event.permission;
+      patch.yolo = event.permission === 'yolo';
+    }
+    if (event.model !== undefined) patch.model = event.model;
+    if (Object.keys(patch).length > 0) this.setAppState(patch);
+  }
+
+  // Applies session metadata changes to the UI and process title.
+  private handleSessionMetaChanged(event: SessionMetaUpdatedEvent): void {
+    const title = event.title ?? stringValue(event.patch?.['title']);
+    if (title !== undefined) {
+      this.setAppState({ sessionTitle: title });
+      setProcessTitle(title, this.state.appState.sessionId);
+    }
+  }
+
+  // Finalizes live buffers and renders a session error.
+  private handleSessionError(event: ErrorEvent): void {
+    this.resetLiveToolUiState();
+    this.finalizeLiveTextBuffers('idle');
+    if (event.code === OAUTH_LOGIN_REQUIRED_CODE) {
+      this.showError(OAUTH_LOGIN_REQUIRED_STARTUP_NOTICE);
+      return;
+    }
+    this.showError(`[${event.code}] ${event.message}`);
+    const sessionId = this.state.appState.sessionId;
+    if (sessionId.length > 0) {
+      this.showStatus(errorReportHintLine(sessionId));
+    }
+  }
+
+  private renderMcpServerStatus(server: McpServerStatusSnapshot): void {
+    const key = mcpServerStatusKey(server);
+    if (this.state.renderedMcpServerStatusKeys.get(server.name) === key) return;
+    this.state.renderedMcpServerStatusKeys.set(server.name, key);
+
+    const colors = this.state.theme.colors;
+    switch (server.status) {
+      case 'connected': {
+        const toolStr = `${server.toolCount} tool${server.toolCount === 1 ? '' : 's'}`;
+        const message = `MCP server "${server.name}" connected · ${toolStr} (${server.transport})`;
+        this.finalizeMcpServerStatusRow(server.name, message, colors.success);
+        return;
+      }
+      case 'failed': {
+        const message = `MCP server "${server.name}" failed${server.error !== undefined ? `: ${server.error}` : ''}`;
+        this.finalizeMcpServerStatusRow(server.name, message, colors.error);
+        return;
+      }
+      case 'needs-auth': {
+        const message = `MCP server "${server.name}" needs OAuth — run /mcp-config login ${server.name}`;
+        this.finalizeMcpServerStatusRow(server.name, message, colors.warning);
+        return;
+      }
+      case 'disabled':
+        this.finalizeMcpServerStatusRow(
+          server.name,
+          `MCP server "${server.name}" disabled`,
+          colors.textMuted,
+        );
+        return;
+      case 'pending':
+        this.showMcpServerStatusSpinner(server.name);
+        return;
+    }
+  }
+
+  private showMcpServerStatusSpinner(name: string): void {
+    const label = `MCP server "${name}" connecting…`;
+    const existing = this.state.mcpServerStatusSpinners.get(name);
+    if (existing !== undefined) {
+      existing.setLabel(label);
+      return;
+    }
+    const tint = (s: string): string => chalk.hex(this.state.theme.colors.textMuted)(s);
+    const spinner = new MoonLoader(this.state.ui, 'braille', tint, label);
+    this.state.transcriptContainer.addChild(spinner);
+    this.state.mcpServerStatusSpinners.set(name, spinner);
+    this.state.ui.requestRender();
+  }
+
+  private finalizeMcpServerStatusRow(name: string, message: string, color: string): void {
+    const spinner = this.state.mcpServerStatusSpinners.get(name);
+    if (spinner === undefined) {
+      this.showStatus(message, color);
+      return;
+    }
+    spinner.stop();
+    const status = new StatusMessageComponent(message, this.state.theme.colors, color);
+    const children = this.state.transcriptContainer.children;
+    const idx = children.indexOf(spinner);
+    if (idx >= 0) {
+      children[idx] = status;
+      this.state.transcriptContainer.invalidate();
+    } else {
+      this.state.transcriptContainer.addChild(status);
+    }
+    this.state.mcpServerStatusSpinners.delete(name);
+    this.state.ui.requestRender();
+  }
+
+  private stopAllMcpServerStatusSpinners(): void {
+    for (const spinner of this.state.mcpServerStatusSpinners.values()) {
+      spinner.stop();
+    }
+    this.state.mcpServerStatusSpinners.clear();
+  }
+
+  // Adds a skill activation entry to the transcript once.
+  private handleSkillActivated(event: SkillActivatedEvent): void {
+    if (this.state.renderedSkillActivationIds.has(event.activationId)) return;
+    this.state.renderedSkillActivationIds.add(event.activationId);
+    this.appendTranscriptEntry({
+      id: nextTranscriptId(),
+      kind: 'skill_activation',
+      turnId: undefined,
+      renderMode: 'plain',
+      content: `Activated skill: ${event.skillName}`,
+      skillActivationId: event.activationId,
+      skillName: event.skillName,
+      skillArgs: event.skillArgs,
+    });
+  }
+
+  // Starts the compaction UI block and marks the app as compacting.
+  private handleCompactionBegin(event: CompactionStartedEvent): void {
+    this.finalizeLiveTextBuffers('waiting');
+    this.setAppState({
+      isCompacting: true,
+      streamingPhase: 'waiting',
+      streamingStartTime: Date.now(),
+    });
+    this.beginCompaction(event.instruction);
+  }
+
+  // Finishes compaction and resumes queued work when possible.
+  private handleCompactionEnd(
+    event: CompactionCompletedEvent,
+    sendQueued: (item: QueuedMessage) => void,
+  ): void {
+    this.endCompaction(event.result.tokensBefore, event.result.tokensAfter);
+    this.finishCompaction(sendQueued);
+  }
+
+  private handleCompactionCancel(
+    _event: CompactionCancelledEvent,
+    sendQueued: (item: QueuedMessage) => void,
+  ): void {
+    this.cancelCompactionBlock();
+    this.finishCompaction(sendQueued);
+  }
+
+  private finishCompaction(sendQueued: (item: QueuedMessage) => void): void {
+    if (!this.state.appState.isStreaming) {
+      this.setAppState({
+        isCompacting: false,
+        streamingPhase: 'idle',
+      });
+      this.resetLivePane();
+      if (this.state.queuedMessages.length > 0) {
+        const [next, ...rest] = this.state.queuedMessages;
+        this.state.queuedMessages = rest;
+        if (next !== undefined) {
+          setTimeout(() => {
+            sendQueued(next);
+          }, 0);
+        }
+      }
+    } else {
+      this.setAppState({ isCompacting: false });
+    }
+  }
+
+  // Registers a spawned subagent and renders foreground or background status.
+  private handleSubagentSpawned(event: SubagentSpawnedEvent): void {
+    this.state.subagentParentToolCallIds.set(event.subagentId, event.parentToolCallId);
+    this.state.subagentNames.set(event.subagentId, event.subagentName);
+
+    if (event.runInBackground) {
+      const meta = this.buildBackgroundAgentMetadata(event);
+      this.state.backgroundAgentMetadata.set(event.subagentId, meta);
+      this.state.backgroundAgents.add(event.subagentId);
+      this.appendBackgroundAgentEntry('started', meta);
+      this.syncBackgroundAgentBadge();
+      return;
+    }
+
+    let tc = this.state.pendingToolComponents.get(event.parentToolCallId);
+    if (tc === undefined) {
+      const toolCall = this.state.activeToolCalls.get(event.parentToolCallId);
+      if (toolCall !== undefined) {
+        this.onToolCallStart(toolCall);
+        tc = this.state.pendingToolComponents.get(event.parentToolCallId);
+      }
+    }
+    tc ??= this.createStandaloneSubagentToolCall(event);
+    if (tc === undefined) return;
+    tc.onSubagentSpawned({
+      agentId: event.subagentId,
+      agentName: event.subagentName,
+      runInBackground: event.runInBackground,
+    });
+  }
+
+  // Completes a subagent in its parent tool call or background transcript entry.
+  private handleSubagentCompleted(event: SubagentCompletedEvent): void {
+    const backgroundMeta = this.state.backgroundAgentMetadata.get(event.subagentId);
+    if (this.state.backgroundAgents.delete(event.subagentId)) {
+      this.syncBackgroundAgentBadge();
+    }
+    if (backgroundMeta !== undefined) {
+      this.state.backgroundAgentMetadata.delete(event.subagentId);
+      // Dedupe: if the BPM `background.task.terminated` for the
+      // matching agent task already pushed a terminal card, skip.
+      // Otherwise mark the subagent id so a later BPM event skips.
+      const taskId = this.findAgentTaskId(event.subagentId);
+      if (taskId !== undefined && this.state.backgroundTaskTranscriptedTerminal.has(taskId)) {
+        return;
+      }
+      if (taskId !== undefined) {
+        this.state.backgroundTaskTranscriptedTerminal.add(taskId);
+      }
+      const extras =
+        event.resultSummary === undefined ? undefined : { resultSummary: event.resultSummary };
+      this.appendBackgroundAgentEntry('completed', backgroundMeta, extras);
+      return;
+    }
+    const tc = this.state.pendingToolComponents.get(event.parentToolCallId);
+    if (tc === undefined) return;
+    tc.onSubagentCompleted({
+      usage: event.usage,
+      resultSummary: event.resultSummary,
+    });
+    if (!this.state.activeToolCalls.has(event.parentToolCallId)) {
+      this.state.pendingToolComponents.delete(event.parentToolCallId);
+    }
+  }
+
+  // Marks a subagent failure in its parent tool call or background transcript entry.
+  private handleSubagentFailed(event: SubagentFailedEvent): void {
+    const backgroundMeta = this.state.backgroundAgentMetadata.get(event.subagentId);
+    if (this.state.backgroundAgents.delete(event.subagentId)) {
+      this.syncBackgroundAgentBadge();
+    }
+    if (backgroundMeta !== undefined) {
+      this.state.backgroundAgentMetadata.delete(event.subagentId);
+      const taskId = this.findAgentTaskId(event.subagentId);
+      if (taskId !== undefined && this.state.backgroundTaskTranscriptedTerminal.has(taskId)) {
+        return;
+      }
+      if (taskId !== undefined) {
+        this.state.backgroundTaskTranscriptedTerminal.add(taskId);
+      }
+      this.appendBackgroundAgentEntry('failed', backgroundMeta, { error: event.error });
+      return;
+    }
+    const tc = this.state.pendingToolComponents.get(event.parentToolCallId);
+    if (tc === undefined) return;
+    tc.onSubagentFailed({ error: event.error });
+    if (!this.state.activeToolCalls.has(event.parentToolCallId)) {
+      this.state.pendingToolComponents.delete(event.parentToolCallId);
+    }
+  }
+
+  // Mounts subagents launched by session-level commands that do not originate
+  // from a model-issued Agent tool call.
+  private createStandaloneSubagentToolCall(event: SubagentSpawnedEvent): ToolCallComponent | undefined {
+    const description = event.description ?? `Run ${event.subagentName} agent`;
+    const toolCall: ToolCallBlockData = {
+      id: event.parentToolCallId,
+      name: 'Agent',
+      args: {
+        description,
+        subagent_type: event.subagentName,
+      },
+      description,
+      step: this.state.currentStep,
+      turnId: this.state.currentTurnId,
+    };
+    this.onToolCallStart(toolCall);
+    return this.state.pendingToolComponents.get(event.parentToolCallId);
+  }
+
+  /**
+   * Locate the BPM `agent-*` task id whose `description` matches the
+   * spawned subagent's recorded description. Used only for dedupe
+   * between the BPM and subagent flows — best-effort: if there is no
+   * unique match (e.g. multiple agent tasks with the same description)
+   * the caller treats the dedupe as a miss, which is safe.
+   */
+  private findAgentTaskId(subagentId: string): string | undefined {
+    const meta = this.state.backgroundAgentMetadata.get(subagentId);
+    const description = meta?.description ?? meta?.agentName;
+    if (description === undefined) return undefined;
+    let match: string | undefined;
+    for (const info of this.state.backgroundTasks.values()) {
+      if (!info.taskId.startsWith('agent-')) continue;
+      if (info.description !== description) continue;
+      if (match !== undefined) return undefined; // ambiguous
+      match = info.taskId;
+    }
+    return match;
+  }
+
+  // Builds transcript metadata for a background subagent.
+  private buildBackgroundAgentMetadata(event: SubagentSpawnedEvent): BackgroundAgentMetadata {
+    const parent = this.state.activeToolCalls.get(event.parentToolCallId);
+    const description = parent?.args['description'] ?? event.description;
+    return {
+      agentId: event.subagentId,
+      parentToolCallId: event.parentToolCallId,
+      agentName: event.subagentName,
+      description: typeof description === 'string' ? description : undefined,
+    };
+  }
+
+  // Appends a background-agent status row to the transcript.
+  private appendBackgroundAgentEntry(
+    phase: 'started' | 'completed' | 'failed',
+    meta: BackgroundAgentMetadata,
+    extras: { resultSummary?: string; error?: string } | undefined = undefined,
+  ): void {
+    const status = formatBackgroundAgentTranscript(phase, meta, extras);
+    const entry: TranscriptEntry = {
+      id: nextTranscriptId(),
+      kind: 'status',
+      turnId: this.state.currentTurnId,
+      renderMode: 'plain',
+      content: status.headline,
+      detail: status.detail,
+      backgroundAgentStatus: status,
+    };
+    this.appendTranscriptEntry(entry);
+  }
+
+  // Updates the footer badge for active background agents.
+  private syncBackgroundAgentBadge(): void {
+    this.syncBackgroundTaskBadge();
+  }
+
+  // =========================================================================
+  // Background task lifecycle (BPM-derived, covers both bash + agent tasks)
+  // =========================================================================
+
+  private handleBackgroundTaskEvent(
+    event: BackgroundTaskStartedEvent | BackgroundTaskUpdatedEvent | BackgroundTaskTerminatedEvent,
+  ): void {
+    const { info } = event;
+    const previous = this.state.backgroundTasks.get(info.taskId);
+    this.state.backgroundTasks.set(info.taskId, info);
+
+    // If the user is currently viewing this task's output, nudge a
+    // refresh immediately so they see new content without waiting for
+    // the 1s poll. Same dedupe-by-output-equality applies inside.
+    const viewer = this.state.tasksBrowser?.viewer;
+    if (viewer !== undefined && viewer.taskId === info.taskId) {
+      void this.refreshTaskOutputViewer({ silent: true });
+    }
+
+    const isTerminal =
+      info.status === 'completed' ||
+      info.status === 'failed' ||
+      info.status === 'killed' ||
+      info.status === 'lost';
+
+    if (event.type === 'background.task.started') {
+      // For agent-* tasks, the legacy subagent.spawned flow already
+      // pushed a 'started' transcript card; skip to avoid duplicates.
+      if (info.taskId.startsWith('agent-')) {
+        this.syncBackgroundTaskBadge();
+        this.repaintTasksBrowser();
+        return;
+      }
+      this.appendBackgroundTaskEntry(info);
+      this.syncBackgroundTaskBadge();
+      this.repaintTasksBrowser();
+      return;
+    }
+
+    if (event.type === 'background.task.terminated' && isTerminal) {
+      if (!this.state.backgroundTaskTranscriptedTerminal.has(info.taskId)) {
+        // For agent-* tasks, the older subagent.completed/failed flow
+        // may also produce a terminal card; whoever wins records the
+        // dedupe marker first. See handleSubagentCompleted/Failed.
+        if (info.taskId.startsWith('bash-')) {
+          this.appendBackgroundTaskEntry(info);
+        }
+        this.state.backgroundTaskTranscriptedTerminal.add(info.taskId);
+      }
+      this.syncBackgroundTaskBadge();
+      this.repaintTasksBrowser();
+      return;
+    }
+
+    // updated: status flipped between running and awaiting_approval.
+    // No transcript card — just sync the badge if the active count
+    // changed (awaiting_approval still counts as active).
+    if (previous?.status !== info.status) {
+      this.syncBackgroundTaskBadge();
+    }
+    this.repaintTasksBrowser();
+  }
+
+  private appendBackgroundTaskEntry(info: BackgroundTaskInfo): void {
+    const status = formatBackgroundTaskTranscript(info);
+    const entry: TranscriptEntry = {
+      id: nextTranscriptId(),
+      kind: 'status',
+      turnId: this.state.currentTurnId,
+      renderMode: 'plain',
+      content: status.headline,
+      detail: status.detail,
+      backgroundAgentStatus: status,
+    };
+    this.appendTranscriptEntry(entry);
+  }
+
+  // Footer counts are BPM-derived: every task that is not terminal,
+  // split by id prefix so bash and agent badges render independently.
+  // awaiting_approval still counts as active; lost/killed/completed/
+  // failed do not.
+  private syncBackgroundTaskBadge(): void {
+    let bashTasks = 0;
+    let agentTasks = 0;
+    for (const info of this.state.backgroundTasks.values()) {
+      if (
+        info.status === 'completed' ||
+        info.status === 'failed' ||
+        info.status === 'killed' ||
+        info.status === 'lost'
+      ) {
+        continue;
+      }
+      if (info.taskId.startsWith('agent-')) {
+        agentTasks += 1;
+      } else {
+        bashTasks += 1;
+      }
+    }
+    this.state.footer.setBackgroundCounts({ bashTasks, agentTasks });
+    this.state.ui.requestRender();
+  }
+
+  // =========================================================================
+  // Live Render Hooks
+  // =========================================================================
+
+  // Creates the live assistant transcript component.
+  private onStreamingTextStart(): void {
+    this.state.pendingAgentGroup = null;
+    this.state.pendingReadGroup = null;
+    const entry = {
+      id: nextTranscriptId(),
+      kind: 'assistant' as const,
+      turnId: this.state.currentTurnId,
+      renderMode: 'markdown' as const,
+      content: '',
+    };
+    this.state.streamingComponent = new AssistantMessageComponent(
+      this.state.theme.markdownTheme,
+      this.state.theme.colors,
+    );
+    this.state.streamingTranscriptEntry = entry;
+    this.state.transcriptEntries.push(entry);
+    this.state.transcriptContainer.addChild(this.state.streamingComponent);
+    this.state.ui.requestRender();
+  }
+
+  // Updates the live assistant transcript component.
+  private onStreamingTextUpdate(fullText: string): void {
+    if (this.state.streamingTranscriptEntry !== undefined) {
+      this.state.streamingTranscriptEntry.content = fullText;
+    }
+    if (this.state.streamingComponent) {
+      this.state.streamingComponent.updateContent(fullText);
+      this.state.ui.requestRender();
+    }
+  }
+
+  // Clears live assistant component references after streaming ends.
+  private onStreamingTextEnd(): void {
+    this.state.streamingComponent = undefined;
+    this.state.streamingTranscriptEntry = undefined;
+  }
+
+  // Creates or updates the live thinking transcript component.
+  private onThinkingUpdate(fullText: string): void {
+    if (this.state.activeThinkingComponent === undefined) {
+      this.state.pendingAgentGroup = null;
+      this.state.pendingReadGroup = null;
+      this.state.activeThinkingComponent = new ThinkingComponent(
+        fullText,
+        this.state.theme.colors,
+        true,
+        'live',
+        this.state.ui,
+      );
+      if (this.state.toolOutputExpanded) this.state.activeThinkingComponent.setExpanded(true);
+      this.state.transcriptContainer.addChild(this.state.activeThinkingComponent);
+    } else {
+      this.state.activeThinkingComponent.setText(fullText);
+    }
+    this.state.ui.requestRender();
+  }
+
+  // Finalizes the live thinking transcript component.
+  private onThinkingEnd(): void {
+    if (this.state.activeThinkingComponent === undefined) return;
+    this.state.activeThinkingComponent.finalize();
+    this.state.activeThinkingComponent = undefined;
+    this.state.ui.requestRender();
+  }
+
+  // Creates and mounts a live tool-call component.
+  private onToolCallStart(toolCall: ToolCallBlockData): void {
+    if (toolCall.name === 'AskUserQuestion') return;
+
+    const tc = new ToolCallComponent(
+      toolCall,
+      undefined,
+      this.state.theme.colors,
+      this.state.ui,
+      this.state.theme.markdownTheme,
+      this.state.appState.workDir,
+    );
+    if (this.state.toolOutputExpanded) tc.setExpanded(true);
+    if (this.state.planExpanded) tc.setPlanExpanded(true);
+    this.state.pendingToolComponents.set(toolCall.id, tc);
+
+    if (toolCall.name !== 'Agent') this.state.pendingAgentGroup = null;
+    if (toolCall.name !== 'Read') this.state.pendingReadGroup = null;
+
+    let handled = this.tryAttachAgentToolCall(toolCall, tc);
+    if (!handled) handled = this.tryAttachReadToolCall(toolCall, tc);
+    if (!handled) {
+      this.state.transcriptContainer.addChild(tc);
+      this.state.ui.requestRender();
+    }
+
+    if (toolCall.name === 'ExitPlanMode' && typeof toolCall.args['plan'] !== 'string') {
+      const session = this.requireSession();
+      void (async () => {
+        try {
+          const plan = await session.getPlan();
+          tc.setPlanInfo(plan === null ? {} : { plan: plan.content, path: plan.path });
+        } catch {
+          tc.setPlanInfo({});
+        }
+      })();
+    }
+  }
+
+  // Applies a tool result to a live or completed tool-call component.
+  private onToolCallEnd(toolCallId: string, result: ToolResultBlockData): void {
+    const matchedCall = this.state.activeToolCalls.get(toolCallId);
+    const tc = this.state.pendingToolComponents.get(toolCallId);
+    if (tc) {
+      tc.setResult(result);
+      this.state.pendingToolComponents.delete(toolCallId);
+      this.state.ui.requestRender();
+      return;
+    }
+
+    if (matchedCall?.name === 'AskUserQuestion') {
+      const completed = new ToolCallComponent(
+        matchedCall,
+        result,
+        this.state.theme.colors,
+        this.state.ui,
+        this.state.theme.markdownTheme,
+        this.state.appState.workDir,
+      );
+      if (this.state.toolOutputExpanded) completed.setExpanded(true);
+      if (this.state.planExpanded) completed.setPlanExpanded(true);
+      this.state.transcriptContainer.addChild(completed);
+      this.state.ui.requestRender();
+    }
+  }
+
+  // Replaces the visible todo list panel.
+  private setTodoList(todos: readonly TodoItem[]): void {
+    this.state.todoPanel.setTodos(todos);
+    this.state.todoPanelContainer.clear();
+    if (!this.state.todoPanel.isEmpty()) {
+      this.state.todoPanelContainer.addChild(this.state.todoPanel);
+    }
+    this.state.ui.requestRender();
+  }
+
+  // Renders a compaction block in the transcript.
+  private beginCompaction(instruction?: string): void {
+    if (this.state.activeCompactionBlock !== undefined) {
+      this.state.activeCompactionBlock.markDone();
+      this.state.activeCompactionBlock = undefined;
+    }
+    const block = new CompactionComponent(this.state.theme.colors, this.state.ui, instruction);
+    this.state.activeCompactionBlock = block;
+    this.state.transcriptContainer.addChild(block);
+    this.state.ui.requestRender();
+  }
+
+  // Marks the active compaction block complete.
+  private endCompaction(tokensBefore?: number, tokensAfter?: number): void {
+    const block = this.state.activeCompactionBlock;
+    if (block === undefined) return;
+    block.markDone(tokensBefore, tokensAfter);
+    this.state.activeCompactionBlock = undefined;
+    this.state.ui.requestRender();
+  }
+
+  private cancelCompactionBlock(): void {
+    const block = this.state.activeCompactionBlock;
+    if (block === undefined) return;
+    block.markCanceled();
+    this.state.activeCompactionBlock = undefined;
+    this.state.ui.requestRender();
+  }
+
+  // Groups Agent tool calls that belong to the same turn step.
+  private tryAttachAgentToolCall(toolCall: ToolCallBlockData, tc: ToolCallComponent): boolean {
+    if (toolCall.name !== 'Agent') {
+      this.state.pendingAgentGroup = null;
+      return false;
+    }
+
+    const step = toolCall.step ?? this.state.currentStep;
+    const turnId = toolCall.turnId ?? this.state.currentTurnId;
+    const pending = this.state.pendingAgentGroup;
+
+    if (pending !== null && (pending.step !== step || pending.turnId !== turnId)) {
+      this.state.pendingAgentGroup = null;
+    }
+
+    const cur = this.state.pendingAgentGroup;
+    if (cur === null) {
+      this.state.pendingAgentGroup = { step, turnId, solo: tc };
+      this.state.transcriptContainer.addChild(tc);
+      this.state.ui.requestRender();
+      return true;
+    }
+
+    if (cur.group !== undefined) {
+      cur.group.attach(toolCall.id, tc);
+      return true;
+    }
+
+    const solo = cur.solo;
+    if (solo === undefined) {
+      this.state.pendingAgentGroup = { step, turnId, solo: tc };
+      this.state.transcriptContainer.addChild(tc);
+      this.state.ui.requestRender();
+      return true;
+    }
+    const group = this.upgradeSoloAgentToGroup(solo);
+    group.attach(toolCall.id, tc);
+    this.state.pendingAgentGroup = { step, turnId, group };
+    this.state.ui.requestRender();
+    return true;
+  }
+
+  // Replaces a single Agent tool call with an Agent group component.
+  private upgradeSoloAgentToGroup(solo: ToolCallComponent): AgentGroupComponent {
+    const group = new AgentGroupComponent(this.state.theme.colors, this.state.ui);
+    const children = this.state.transcriptContainer.children;
+    const idx = children.indexOf(solo);
+    if (idx >= 0) {
+      children[idx] = group;
+      this.state.transcriptContainer.invalidate();
+    } else {
+      this.state.transcriptContainer.addChild(group);
+    }
+    group.attach(solo.toolCallView.id, solo);
+    return group;
+  }
+
+  // Groups Read tool calls that belong to the same turn step.
+  private tryAttachReadToolCall(toolCall: ToolCallBlockData, tc: ToolCallComponent): boolean {
+    if (toolCall.name !== 'Read') {
+      this.state.pendingReadGroup = null;
+      return false;
+    }
+
+    const step = toolCall.step ?? this.state.currentStep;
+    const turnId = toolCall.turnId ?? this.state.currentTurnId;
+    const pending = this.state.pendingReadGroup;
+
+    if (pending !== null && (pending.step !== step || pending.turnId !== turnId)) {
+      this.state.pendingReadGroup = null;
+    }
+
+    const cur = this.state.pendingReadGroup;
+    if (cur === null) {
+      this.state.pendingReadGroup = { step, turnId, solo: tc };
+      this.state.transcriptContainer.addChild(tc);
+      this.state.ui.requestRender();
+      return true;
+    }
+
+    if (cur.group !== undefined) {
+      cur.group.attach(toolCall.id, tc);
+      return true;
+    }
+
+    const solo = cur.solo;
+    if (solo === undefined) {
+      this.state.pendingReadGroup = { step, turnId, solo: tc };
+      this.state.transcriptContainer.addChild(tc);
+      this.state.ui.requestRender();
+      return true;
+    }
+    const group = this.upgradeSoloReadToGroup(solo);
+    group.attach(toolCall.id, tc);
+    this.state.pendingReadGroup = { step, turnId, group };
+    this.state.ui.requestRender();
+    return true;
+  }
+
+  // Replaces a single Read tool call with a Read group component.
+  private upgradeSoloReadToGroup(solo: ToolCallComponent): ReadGroupComponent {
+    const group = new ReadGroupComponent(this.state.theme.colors, this.state.ui);
+    const children = this.state.transcriptContainer.children;
+    const idx = children.indexOf(solo);
+    if (idx >= 0) {
+      children[idx] = group;
+      this.state.transcriptContainer.invalidate();
+    } else {
+      this.state.transcriptContainer.addChild(group);
+    }
+    group.attach(solo.toolCallView.id, solo);
+    return group;
+  }
+
+  // =========================================================================
+  // Transcript Rendering
+  // =========================================================================
+
+  // Creates the pi-tui component that renders a transcript entry.
+  private createTranscriptComponent(entry: TranscriptEntry): Component | null {
+    if (entry.compactionData !== undefined) {
+      const data = entry.compactionData;
+      const block = new CompactionComponent(
+        this.state.theme.colors,
+        this.state.ui,
+        data.instruction,
+      );
+      block.markDone(data.tokensBefore, data.tokensAfter);
+      return block;
+    }
+
+    switch (entry.kind) {
+      case 'user': {
+        const images = entry.imageAttachmentIds
+          ?.map((id) => this.imageStore.get(id))
+          .filter((a): a is ImageAttachment => a?.kind === 'image');
+        return new UserMessageComponent(entry.content, this.state.theme.colors, images);
+      }
+      case 'skill_activation':
+        return new SkillActivationComponent(
+          entry.skillName ?? entry.content,
+          entry.skillArgs,
+          this.state.theme.colors,
+        );
+      case 'assistant': {
+        const component = new AssistantMessageComponent(
+          this.state.theme.markdownTheme,
+          this.state.theme.colors,
+        );
+        component.updateContent(entry.content);
+        return component;
+      }
+      case 'thinking': {
+        const thinking = new ThinkingComponent(entry.content, this.state.theme.colors, true);
+        if (this.state.toolOutputExpanded) thinking.setExpanded(true);
+        return thinking;
+      }
+      case 'tool_call':
+        if (entry.toolCallData) {
+          const tc = new ToolCallComponent(
+            entry.toolCallData,
+            entry.toolCallData.result,
+            this.state.theme.colors,
+            this.state.ui,
+            this.state.theme.markdownTheme,
+            this.state.appState.workDir,
+          );
+          if (this.state.toolOutputExpanded) tc.setExpanded(true);
+          if (this.state.planExpanded) tc.setPlanExpanded(true);
+          return tc;
+        }
+        if (entry.backgroundAgentStatus !== undefined) {
+          return new BackgroundAgentStatusComponent(
+            entry.backgroundAgentStatus,
+            this.state.theme.colors,
+          );
+        }
+        return entry.renderMode === 'notice'
+          ? new NoticeMessageComponent(entry.content, entry.detail, this.state.theme.colors)
+          : new StatusMessageComponent(entry.content, this.state.theme.colors, entry.color);
+      case 'status':
+        if (entry.backgroundAgentStatus !== undefined) {
+          return new BackgroundAgentStatusComponent(
+            entry.backgroundAgentStatus,
+            this.state.theme.colors,
+          );
+        }
+        return entry.renderMode === 'notice'
+          ? new NoticeMessageComponent(entry.content, entry.detail, this.state.theme.colors)
+          : new StatusMessageComponent(entry.content, this.state.theme.colors, entry.color);
+      case 'welcome':
+        return null;
+      default:
+        return null;
+    }
+  }
+
+  // Stores a transcript entry and mounts its component if renderable.
+  private appendTranscriptEntry(entry: TranscriptEntry): void {
+    this.state.transcriptEntries.push(entry);
+    const component = this.createTranscriptComponent(entry);
+    if (component) {
+      this.state.transcriptContainer.addChild(component);
+      this.state.ui.requestRender();
+    }
+  }
+
+  // Appends an approval-result entry to the transcript.
+  private appendApprovalTranscriptEntry(request: ApprovalRequest, response: ApprovalResponse): void {
+    const parts: string[] = [];
+    switch (response.decision) {
+      case 'approved':
+        parts.push(response.scope === 'session' ? 'Approved for session' : 'Approved');
+        break;
+      case 'rejected':
+        parts.push('Rejected');
+        break;
+      case 'cancelled':
+        parts.push('Cancelled');
+        break;
+    }
+    parts.push(`: ${request.action}`);
+    if (response.feedback !== undefined && response.feedback.length > 0) {
+      parts.push(` — "${response.feedback}"`);
+    }
+    this.appendTranscriptEntry({
+      id: nextTranscriptId(),
+      kind: 'status',
+      renderMode: 'notice',
+      content: parts.join(''),
+    });
+  }
+
+  // Adds the welcome component to the transcript.
+  private renderWelcome(): void {
+    const welcome = new WelcomeComponent(this.state.appState, this.state.theme.colors);
+    this.state.transcriptContainer.addChild(welcome);
+  }
+
+  // Disposes the active compaction component if one is mounted.
+  private disposeActiveCompactionBlock(): void {
+    if (this.state.activeCompactionBlock !== undefined) {
+      this.state.activeCompactionBlock.dispose();
+      this.state.activeCompactionBlock = undefined;
+    }
+  }
+
+  // Disposes the active thinking component if one is mounted.
+  private disposeActiveThinkingComponent(): void {
+    if (this.state.activeThinkingComponent !== undefined) {
+      this.state.activeThinkingComponent.dispose();
+      this.state.activeThinkingComponent = undefined;
+    }
+  }
+
+  // Disposes and forgets all pending live tool-call components.
+  private disposeAndClearPendingToolComponents(): void {
+    for (const component of this.state.pendingToolComponents.values()) {
+      if (hasDispose(component)) component.dispose();
+    }
+    this.state.pendingToolComponents.clear();
+  }
+
+  private clearTerminalInlineImages(): void {
+    if (getCapabilities().images !== 'kitty') return;
+    this.state.terminal.write(deleteAllKittyImages());
+  }
+
+  // Clears transcript-related state and redraws the welcome view.
+  private clearTranscriptAndRedraw(): void {
+    this.state.transcriptEntries = [];
+    this.disposeActiveCompactionBlock();
+    this.resetLiveTextRuntime();
+    this.resetLiveToolUiState();
+    this.stopAllMcpServerStatusSpinners();
+    this.state.transcriptContainer.clear();
+    this.clearTerminalInlineImages();
+    this.state.todoPanel.clear();
+    this.state.todoPanelContainer.clear();
+    this.imageStore.clear();
+    this.renderWelcome();
+  }
+
+  // Appends a status message to the transcript.
+  private showStatus(message: string, color?: string): void {
+    this.state.transcriptContainer.addChild(
+      new StatusMessageComponent(message, this.state.theme.colors, color),
+    );
+    this.state.ui.requestRender();
+  }
+
+  // Appends a notice message to the transcript.
+  private showNotice(title: string, detail?: string): void {
+    this.state.transcriptContainer.addChild(
+      new NoticeMessageComponent(title, detail, this.state.theme.colors),
+    );
+    this.state.ui.requestRender();
+  }
+
+  // Appends an error status message to the transcript.
+  private showError(message: string): void {
+    this.showStatus(`Error: ${message}`, this.state.theme.colors.error);
+  }
+
+  // Adds an animated login progress row to the transcript.
+  private showLoginProgressSpinner(label: string): LoginProgressSpinnerHandle {
+    const tint = (s: string): string => chalk.hex(this.state.theme.colors.primary)(s);
+    const spinner = new MoonLoader(this.state.ui, 'braille', tint, label);
+    this.state.transcriptContainer.addChild(new Spacer(1));
+    this.state.transcriptContainer.addChild(spinner);
+    this.state.ui.requestRender();
+    return {
+      stop: ({ ok, label: finalLabel }) => {
+        spinner.stop();
+        const tone = ok ? this.state.theme.colors.success : this.state.theme.colors.error;
+        const symbol = ok ? '✓' : '✗';
+        spinner.setText(chalk.hex(tone)(`${symbol} ${finalLabel}`));
+        this.state.ui.requestRender();
+      },
+    };
+  }
+
+  // Opens the device-code URL and renders the login authorization prompt.
+  private showLoginAuthorizationPrompt(auth: DeviceAuthorization): LoginProgressSpinnerHandle {
+    openUrl(auth.verificationUriComplete);
+    this.state.transcriptContainer.addChild(
+      new DeviceCodeBoxComponent({
+        title: 'Sign in to Kimi Code',
+        url: auth.verificationUriComplete,
+        code: auth.userCode,
+        hint: 'Press Ctrl-C to cancel',
+        colors: this.state.theme.colors,
+      }),
+    );
+    this.state.ui.requestRender();
+    return this.showLoginProgressSpinner('Waiting for authorization…');
+  }
+
+  // Provides UI callbacks used while hydrating transcript history.
+  private replayHydrationHooks(): ReplayHydrationHooks {
+    return {
+      setAppState: (patch) => {
+        this.setAppState(patch);
+      },
+      appendEntry: (entry) => {
+        this.appendTranscriptEntry(entry);
+      },
+      setTodoList: (todos) => {
+        this.setTodoList(todos);
+      },
+      emitError: (message) => {
+        this.showError(message);
+      },
+    };
+  }
+
+  // =========================================================================
+  // Panes / Presentation State
+  // =========================================================================
+
+  // Rebuilds the activity pane for the current live and streaming state.
+  private updateActivityPane(): void {
+    const effectiveMode = this.resolveActivityPaneMode();
+    this.syncTerminalProgress(this.shouldShowTerminalProgress(effectiveMode));
+
+    if (
+      effectiveMode === this.state.lastActivityMode &&
+      (effectiveMode === 'waiting' || effectiveMode === 'thinking' || effectiveMode === 'tool')
+    ) {
+      return;
+    }
+
+    this.state.lastActivityMode = effectiveMode;
+    this.state.activityContainer.clear();
+
+    switch (effectiveMode) {
+      case 'hidden':
+        this.stopActivitySpinner();
+        this.state.ui.requestRender();
+        return;
+      case 'waiting': {
+        const spinner = this.ensureActivitySpinner('moon');
+        this.state.activityContainer.addChild(
+          new ActivityPaneComponent({
+            mode: 'waiting',
+            spinner,
+          }),
+        );
+        break;
+      }
+      case 'thinking': {
+        this.stopActivitySpinner();
+        break;
+      }
+      case 'composing': {
+        const spinner = this.ensureActivitySpinner('braille', 'working...', (s) =>
+          chalk.hex(this.state.theme.colors.primary)(s),
+        );
+        this.state.activityContainer.addChild(
+          new ActivityPaneComponent({
+            mode: 'composing',
+            spinner,
+          }),
+        );
+        break;
+      }
+      case 'tool': {
+        const spinner = this.ensureActivitySpinner('moon');
+        this.state.activityContainer.addChild(
+          new ActivityPaneComponent({
+            mode: 'tool',
+            spinner,
+          }),
+        );
+        break;
+      }
+      case 'idle':
+      case 'session': {
+        this.stopActivitySpinner();
+        break;
+      }
+    }
+    this.state.ui.requestRender();
+  }
+
+  // Computes the effective activity-pane mode from modal and streaming state.
+  private resolveActivityPaneMode(): EffectiveActivityPaneMode {
+    if (this.state.showingSessionPicker) return 'hidden';
+    if (this.state.livePane.pendingApproval !== null) return 'hidden';
+    if (this.state.appState.isCompacting) return 'hidden';
+    if (this.state.livePane.pendingQuestion !== null) return 'hidden';
+
+    const streamingPhase = this.state.appState.streamingPhase;
+    if (this.state.livePane.mode === 'idle') {
+      if (streamingPhase === 'thinking' || streamingPhase === 'composing') {
+        return streamingPhase;
+      }
+    }
+
+    return this.state.livePane.mode;
+  }
+
+  // Re-renders the queued-message pane.
+  private updateQueueDisplay(): void {
+    this.state.queueContainer.clear();
+    const queued = this.state.queuedMessages;
+    if (queued.length === 0) return;
+
+    this.state.queueContainer.addChild(
+      new QueuePaneComponent({
+        messages: queued,
+        colors: this.state.theme.colors,
+        isCompacting: this.state.appState.isCompacting,
+        isStreaming: this.state.appState.isStreaming,
+        canSteerImmediately: !this.deferUserMessages,
+      }),
+    );
+  }
+
+  // Toggles expansion for all expandable tool-output components.
+  private toggleToolOutputExpansion(): void {
+    this.state.toolOutputExpanded = !this.state.toolOutputExpanded;
+    for (const child of this.state.transcriptContainer.children) {
+      if (isExpandable(child)) {
+        child.setExpanded(this.state.toolOutputExpanded);
+      }
+    }
+    this.state.ui.requestRender();
+  }
+
+  // Toggles expansion for plan-preview cards (ExitPlanMode). Returns true
+  // iff at least one plan card was actually toggled so the caller can decide
+  // whether to consume the keystroke vs. let pi-tui's default end-of-line run.
+  private togglePlanExpansion(): boolean {
+    const next = !this.state.planExpanded;
+    let toggled = false;
+    for (const child of this.state.transcriptContainer.children) {
+      if (isPlanExpandable(child) && child.setPlanExpanded(next)) {
+        toggled = true;
+      }
+    }
+    if (!toggled) return false;
+    this.state.planExpanded = next;
+    this.state.ui.requestRender();
+    return true;
+  }
+
+  // Updates the editor border color for slash command and plan-mode context.
+  private updateEditorBorderHighlight(text?: string): void {
+    const trimmed = (text ?? this.state.editor.getText()).trimStart();
+    const colorToken =
+      this.state.appState.planMode || trimmed.startsWith('/')
+        ? this.state.theme.colors.primary
+        : this.state.theme.colors.border;
+    this.state.editor.borderColor = (s: string) => chalk.hex(colorToken)(s);
+    this.state.ui.requestRender();
+  }
+
+  // Applies a theme bundle to all stateful UI theme references.
+  private applyTheme(theme: Theme, resolved?: ResolvedTheme): void {
+    const nextTheme = createKimiTUIThemeBundle(theme, resolved);
+    Object.assign(this.state.theme.colors, nextTheme.colors);
+    this.state.theme.resolvedTheme = nextTheme.resolvedTheme;
+    this.state.theme.styles = nextTheme.styles;
+    this.state.theme.markdownTheme = nextTheme.markdownTheme;
+    this.setAppState({ theme });
+    this.updateEditorBorderHighlight();
+    this.state.ui.requestRender(true);
+  }
+
+  // Starts or stops terminal theme notifications according to the user preference.
+  private refreshTerminalThemeTracking(): void {
+    this.stopTerminalThemeTracking();
+    if (this.state.appState.theme !== 'auto') return;
+
+    this.terminalThemeTrackingDispose = installTerminalThemeTracking(this.state, (resolved) => {
+      this.applyResolvedAutoTheme(resolved);
+    });
+  }
+
+  // Stops terminal theme notifications if they were enabled for auto mode.
+  private stopTerminalThemeTracking(): void {
+    this.terminalThemeTrackingDispose?.();
+    this.terminalThemeTrackingDispose = undefined;
+  }
+
+  // Applies a concrete terminal-reported theme while keeping the preference as auto.
+  private applyResolvedAutoTheme(resolved: ResolvedTheme): void {
+    if (this.state.appState.theme !== 'auto') return;
+    if (this.state.theme.resolvedTheme === resolved) return;
+    this.applyTheme('auto', resolved);
+  }
+
+  // Determines whether the terminal should expose progress state.
+  private shouldShowTerminalProgress(effectiveMode: EffectiveActivityPaneMode): boolean {
+    if (this.state.appState.isCompacting) return true;
+    return (
+      effectiveMode === 'waiting' ||
+      effectiveMode === 'thinking' ||
+      effectiveMode === 'composing' ||
+      effectiveMode === 'tool'
+    );
+  }
+
+  // Syncs terminal progress only when the active flag changes.
+  private syncTerminalProgress(active: boolean): void {
+    if (this.state.terminalState.progressActive === active) return;
+    this.state.terminal.setProgress(active);
+    this.state.terminalState.progressActive = active;
+  }
+
+  // Returns an activity spinner with the requested style and presentation.
+  private ensureActivitySpinner(
+    style: SpinnerStyle,
+    label = '',
+    colorFn?: (s: string) => string,
+  ): MoonLoader {
+    if (this.state.activitySpinnerStyle !== style) {
+      this.stopActivitySpinner();
+    }
+
+    if (this.state.activitySpinner === undefined) {
+      this.state.activitySpinner = new MoonLoader(this.state.ui, style, colorFn, label);
+      this.state.activitySpinnerStyle = style;
+      return this.state.activitySpinner;
+    }
+
+    this.state.activitySpinner.setLabel(label);
+    if (colorFn !== undefined) {
+      this.state.activitySpinner.setColorFn(colorFn);
+    }
+    return this.state.activitySpinner;
+  }
+
+  // Stops and clears the activity spinner.
+  private stopActivitySpinner(): void {
+    if (this.state.activitySpinner) {
+      this.state.activitySpinner.stop();
+      this.state.activitySpinner = undefined;
+    }
+    this.state.activitySpinnerStyle = undefined;
+  }
+
+  // =========================================================================
+  // Dialogs / Selectors
+  // =========================================================================
+
+  // Replaces the editor with a focusable dialog or selector panel.
+  private mountEditorReplacement(panel: Component & Focusable): void {
+    this.state.editorContainer.clear();
+    this.state.editorContainer.addChild(panel);
+    this.state.ui.setFocus(panel);
+    this.state.ui.requestRender();
+  }
+
+  // Restores the main editor after a dialog or selector closes.
+  private restoreEditor(): void {
+    this.state.editorContainer.clear();
+    this.state.editorContainer.addChild(this.state.editor);
+    this.state.ui.setFocus(this.state.editor);
+    this.state.ui.requestRender();
+  }
+
+  // Runs the first-launch migration screen, if a plan was detected pre-TUI.
+  // Resolves with the screen's result when the user dismisses it; the editor
+  // is then restored.
+  private async runMigrationScreen(plan: MigrationPlan): Promise<MigrationScreenResult> {
+    const result = await new Promise<MigrationScreenResult>((resolve) => {
+      const screen = new MigrationScreenComponent({
+        plan,
+        // Reuse the source path detection already resolved — the single source
+        // of truth — rather than re-deriving it here.
+        sourceHome: plan.sourceHome,
+        targetHome: this.harness.homeDir,
+        colors: this.state.theme.colors,
+        skipDecisionStep: this.migrateOnly,
+        requestRender: () => {
+          this.state.ui.requestRender();
+        },
+        onComplete: (r) => {
+          resolve(r);
+        },
+      });
+      this.mountEditorReplacement(screen);
+    });
+    this.restoreEditor();
+    if (result.decision === 'never') {
+      // Persist the skip marker `detectPendingMigration` checks, so "Never ask
+      // again" actually stops the prompt from reappearing every launch.
+      try {
+        writeFileSync(
+          join(this.harness.homeDir, '.skip-migration-from-kimi-cli'),
+          '',
+          'utf-8',
+        );
+      } catch {
+        // Non-blocking: a failed marker write must never crash startup.
+      }
+    }
+    return result;
+  }
+
+  // Shows the help panel with the current slash command list.
+  private showHelpPanel(): void {
+    this.state.showingHelpPanel = true;
+    this.mountEditorReplacement(
+      new HelpPanelComponent({
+        commands: this.getSlashCommands(),
+        colors: this.state.theme.colors,
+        onClose: () => {
+          this.hideHelpPanel();
+        },
+      }),
+    );
+  }
+
+  // Hides the help panel and returns focus to the editor.
+  private hideHelpPanel(): void {
+    this.state.showingHelpPanel = false;
+    this.restoreEditor();
+  }
+
+  // Loads sessions and shows the session picker.
+  private async showSessionPicker(): Promise<void> {
+    await this.fetchSessions();
+    this.mountSessionPicker(() => {
+      this.hideSessionPicker();
+    });
+  }
+
+  // Shows the startup session picker and exits when it is cancelled.
+  private async bootstrapFromPicker(): Promise<void> {
+    await this.fetchSessions();
+    this.mountSessionPicker(() => {
+      this.hideSessionPicker();
+      void this.stop();
+    });
+  }
+
+  // Hides the session picker and restores the editor.
+  private hideSessionPicker(): void {
+    this.state.showingSessionPicker = false;
+    this.restoreEditor();
+  }
+
+  // Mounts a session picker with shared selection behavior.
+  private mountSessionPicker(onCancel: () => void): void {
+    this.state.showingSessionPicker = true;
+    this.mountEditorReplacement(
+      new SessionPickerComponent({
+        sessions: this.state.sessions,
+        loading: this.state.loadingSessions,
+        currentSessionId: this.state.appState.sessionId,
+        colors: this.state.theme.colors,
+        onSelect: (sessionId: string) => {
+          void this.resumeSession(sessionId).then((switched) => {
+            if (switched) {
+              this.hideSessionPicker();
+            }
+          });
+        },
+        onCancel,
+      }),
+    );
+  }
+
+  // =========================================================================
+  // Background tasks browser (`/tasks`)
+  // =========================================================================
+
+  /**
+   * Open the `/tasks` overlay. Idempotent: a second `/tasks` while the
+   * panel is already open is a no-op (the focus stays on the existing
+   * overlay) — prevents accidental stacking.
+   */
+  private async showTasksBrowser(): Promise<void> {
+    if (this.state.tasksBrowser !== undefined) return;
+    const session = this.session;
+    if (session === undefined) {
+      this.showError('No active session.');
+      return;
+    }
+
+    let tasks: readonly BackgroundTaskInfo[] = [];
+    try {
+      tasks = await session.listBackgroundTasks({ activeOnly: false });
+    } catch (error) {
+      this.showError(
+        `Failed to load tasks: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return;
+    }
+    // Race: panel might have been opened then immediately closed by
+    // another path while the await above was in flight. Bail out then.
+    if (this.state.tasksBrowser !== undefined) return;
+
+    const filter: TasksFilter = 'all';
+    const selectedTaskId = this.pickInitialSelection(tasks, filter);
+    const component = new TasksBrowserApp(
+      {
+        tasks,
+        filter,
+        selectedTaskId,
+        tailOutput: undefined,
+        tailLoading: false,
+        flashMessage: undefined,
+        colors: this.state.theme.colors,
+        ...this.buildTasksBrowserCallbacks(),
+      },
+      this.state.terminal,
+    );
+
+    // Alt-screen takeover: save the main TUI's children, then replace
+    // them with this single full-screen component. `closeTasksBrowser`
+    // restores the original layout. Mirrors the Python `Application(
+    // full_screen=True, erase_when_done=True)` pattern.
+    const savedChildren = [...this.state.ui.children];
+    this.state.ui.clear();
+    this.state.ui.addChild(component);
+    this.state.ui.setFocus(component);
+    this.state.ui.requestRender(true);
+
+    const pollTimer = setInterval(() => {
+      void this.refreshTasksBrowser({ silent: true });
+    }, 1000);
+
+    this.state.tasksBrowser = {
+      component,
+      savedChildren,
+      filter,
+      selectedTaskId,
+      tailOutput: undefined,
+      tailLoading: false,
+      tailRequestId: 0,
+      flashMessage: undefined,
+      flashTimer: undefined,
+      pollTimer,
+      viewer: undefined,
+    };
+
+    if (selectedTaskId !== undefined) {
+      this.loadTasksBrowserTail(selectedTaskId);
+    }
+  }
+
+  private pickInitialSelection(
+    tasks: readonly BackgroundTaskInfo[],
+    filter: TasksFilter,
+  ): string | undefined {
+    const candidates =
+      filter === 'all'
+        ? tasks
+        : tasks.filter(
+            (t) =>
+              t.status !== 'completed' &&
+              t.status !== 'failed' &&
+              t.status !== 'killed' &&
+              t.status !== 'lost',
+          );
+    if (candidates.length === 0) return undefined;
+    // Prefer the first non-terminal task; fall back to the first one.
+    return (
+      candidates.find(
+        (t) => t.status === 'running' || t.status === 'awaiting_approval',
+      )?.taskId ?? candidates[0]!.taskId
+    );
+  }
+
+  private async refreshTasksBrowser(opts: { silent?: boolean } = {}): Promise<void> {
+    const browser = this.state.tasksBrowser;
+    if (browser === undefined) return;
+    const session = this.session;
+    if (session === undefined) return;
+
+    let tasks: readonly BackgroundTaskInfo[];
+    try {
+      tasks = await session.listBackgroundTasks({ activeOnly: false });
+    } catch (error) {
+      if (!opts.silent) {
+        this.flashTasksBrowser(
+          `Refresh failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+      return;
+    }
+    if (this.state.tasksBrowser !== browser) return;
+    this.pushTasksBrowserProps(tasks);
+  }
+
+  private pushTasksBrowserProps(tasks: readonly BackgroundTaskInfo[]): void {
+    const browser = this.state.tasksBrowser;
+    if (browser === undefined) return;
+    browser.component.setProps({
+      tasks,
+      filter: browser.filter,
+      selectedTaskId: browser.selectedTaskId,
+      tailOutput: browser.tailOutput,
+      tailLoading: browser.tailLoading,
+      flashMessage: browser.flashMessage,
+      colors: this.state.theme.colors,
+      ...this.buildTasksBrowserCallbacks(),
+    });
+    this.state.ui.requestRender();
+  }
+
+  /** Callback bundle for `TasksBrowserComponent`. Single source of truth. */
+  private buildTasksBrowserCallbacks(): {
+    onSelect: (taskId: string) => void;
+    onToggleFilter: () => void;
+    onRefresh: () => void;
+    onCancel: () => void;
+    onStopConfirmed: (taskId: string) => void;
+    onOpenOutput: (taskId: string) => void;
+    onStopIgnored: (taskId: string, reason: 'terminal') => void;
+  } {
+    return {
+      onSelect: (taskId) => {
+        this.handleTasksBrowserSelect(taskId);
+      },
+      onToggleFilter: () => {
+        this.handleTasksBrowserToggleFilter();
+      },
+      onRefresh: () => {
+        this.handleTasksBrowserRefresh();
+      },
+      onCancel: () => {
+        this.closeTasksBrowser();
+      },
+      onStopConfirmed: (taskId) => {
+        void this.handleTasksBrowserStop(taskId);
+      },
+      onOpenOutput: (taskId) => {
+        void this.handleTasksBrowserOpenOutput(taskId);
+      },
+      onStopIgnored: (taskId, reason) => {
+        if (reason === 'terminal') {
+          this.flashTasksBrowser(`${taskId} is already terminal — nothing to stop.`);
+        }
+      },
+    };
+  }
+
+  private handleTasksBrowserSelect(taskId: string): void {
+    const browser = this.state.tasksBrowser;
+    if (browser === undefined) return;
+    if (browser.selectedTaskId === taskId) return;
+    browser.selectedTaskId = taskId;
+    browser.tailOutput = undefined;
+    browser.tailLoading = true;
+    this.repaintTasksBrowser();
+    this.loadTasksBrowserTail(taskId);
+  }
+
+  private handleTasksBrowserToggleFilter(): void {
+    const browser = this.state.tasksBrowser;
+    if (browser === undefined) return;
+    browser.filter = browser.filter === 'all' ? 'active' : 'all';
+    this.repaintTasksBrowser();
+  }
+
+  private handleTasksBrowserRefresh(): void {
+    this.flashTasksBrowser('Refreshing…', 600);
+    void this.refreshTasksBrowser();
+  }
+
+  /**
+   * Re-render the `/tasks` panel from the in-memory BPM store (no RPC
+   * fetch). Safe to call when the panel is closed (no-op). Use this
+   * after any local state change — selection, filter, flash message,
+   * or an incoming `background.task.*` event — so the UI stays in sync.
+   * Use `refreshTasksBrowser` instead when you also want fresh data
+   * from the agent (e.g. a manual `R refresh`).
+   */
+  private repaintTasksBrowser(): void {
+    const browser = this.state.tasksBrowser;
+    if (browser === undefined) return;
+    const tasks = [...this.state.backgroundTasks.values()];
+    this.pushTasksBrowserProps(tasks);
+  }
+
+  private loadTasksBrowserTail(taskId: string): void {
+    const browser = this.state.tasksBrowser;
+    if (browser === undefined) return;
+    const session = this.session;
+    if (session === undefined) {
+      browser.tailLoading = false;
+      this.repaintTasksBrowser();
+      return;
+    }
+    const requestId = ++browser.tailRequestId;
+    void session
+      .getBackgroundTaskOutput(taskId, { tail: 4000 })
+      .then((output) => {
+        const current = this.state.tasksBrowser;
+        if (current === undefined) return;
+        if (current !== browser || current.tailRequestId !== requestId) return;
+        if (current.selectedTaskId !== taskId) return;
+        current.tailOutput = output;
+        current.tailLoading = false;
+        this.repaintTasksBrowser();
+      })
+      .catch(() => {
+        const current = this.state.tasksBrowser;
+        if (current === undefined) return;
+        if (current !== browser || current.tailRequestId !== requestId) return;
+        if (current.selectedTaskId !== taskId) return;
+        current.tailOutput = '';
+        current.tailLoading = false;
+        this.repaintTasksBrowser();
+      });
+  }
+
+  private flashTasksBrowser(message: string, durationMs = 2500): void {
+    const browser = this.state.tasksBrowser;
+    if (browser === undefined) return;
+    if (browser.flashTimer !== undefined) clearTimeout(browser.flashTimer);
+    browser.flashMessage = message;
+    browser.flashTimer = setTimeout(() => {
+      const current = this.state.tasksBrowser;
+      if (current !== browser) return;
+      current.flashMessage = undefined;
+      current.flashTimer = undefined;
+      this.repaintTasksBrowser();
+    }, durationMs);
+    this.repaintTasksBrowser();
+  }
+
+  private async handleTasksBrowserStop(taskId: string): Promise<void> {
+    const browser = this.state.tasksBrowser;
+    if (browser === undefined) return;
+    const session = this.session;
+    if (session === undefined) {
+      this.flashTasksBrowser('No active session.');
+      return;
+    }
+    this.flashTasksBrowser(`Stopping ${taskId}…`, 1500);
+    try {
+      await session.stopBackgroundTask(taskId, { reason: 'stopped from /tasks' });
+      // Force a refresh so the row flips to `killed` immediately. The
+      // `background.task.terminated` event will repaint again shortly.
+      await this.refreshTasksBrowser({ silent: true });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.flashTasksBrowser(`Stop failed: ${message}`);
+    }
+  }
+
+  private async handleTasksBrowserOpenOutput(taskId: string): Promise<void> {
+    const browser = this.state.tasksBrowser;
+    if (browser === undefined) return;
+    if (browser.viewer !== undefined) return; // already viewing
+    const session = this.session;
+    if (session === undefined) {
+      this.flashTasksBrowser('No active session.');
+      return;
+    }
+
+    let output: string;
+    try {
+      output = await session.getBackgroundTaskOutput(taskId);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.flashTasksBrowser(`Cannot open output: ${message}`);
+      return;
+    }
+    // Race: panel might have been closed while the await was in flight.
+    const current = this.state.tasksBrowser;
+    if (current === undefined || current !== browser) return;
+
+    const info = this.state.backgroundTasks.get(taskId);
+    const viewer = new TaskOutputViewer(
+      {
+        taskId,
+        info,
+        output,
+        colors: this.state.theme.colors,
+        onClose: () => {
+          this.closeTaskOutputViewer();
+        },
+      },
+      this.state.terminal,
+    );
+
+    // Nested takeover: save the TasksBrowser layer (which itself is a
+    // single-child swap of the main TUI), then put the viewer in its
+    // place. `closeTaskOutputViewer` reverses this without touching the
+    // outer "main TUI ↔ TasksBrowser" swap state.
+    const savedBrowserChildren = [...this.state.ui.children];
+    this.state.ui.clear();
+    this.state.ui.addChild(viewer);
+    this.state.ui.setFocus(viewer);
+    this.state.ui.requestRender(true);
+
+    // Live-tail: keep re-fetching the output every second so the viewer
+    // shows new content as the task writes it. The viewer itself decides
+    // whether to follow the tail or preserve scroll position.
+    const pollTimer = setInterval(() => {
+      void this.refreshTaskOutputViewer({ silent: true });
+    }, 1000);
+
+    browser.viewer = {
+      component: viewer,
+      savedChildren: savedBrowserChildren,
+      taskId,
+      output,
+      refreshId: 0,
+      pollTimer,
+    };
+  }
+
+  /**
+   * Re-fetch the current viewer task's output and push it into the
+   * component. Safe to call when the viewer is closed (no-op). Stale
+   * responses (issued before a more recent call) are discarded via the
+   * monotonically-increasing `refreshId`.
+   */
+  private async refreshTaskOutputViewer(opts: { silent?: boolean } = {}): Promise<void> {
+    const browser = this.state.tasksBrowser;
+    const viewer = browser?.viewer;
+    if (browser === undefined || viewer === undefined) return;
+    const session = this.session;
+    if (session === undefined) return;
+
+    const myRefreshId = ++viewer.refreshId;
+    let output: string;
+    try {
+      output = await session.getBackgroundTaskOutput(viewer.taskId);
+    } catch (error) {
+      if (!opts.silent) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.flashTasksBrowser(`Output refresh failed: ${message}`);
+      }
+      return;
+    }
+    // If the viewer was closed or another refresh raced ahead, drop this result.
+    const current = this.state.tasksBrowser?.viewer;
+    if (current === undefined || current !== viewer || current.refreshId !== myRefreshId) {
+      return;
+    }
+    // Skip the setProps round-trip when nothing changed — keeps the
+    // differential renderer from re-emitting the same frame.
+    if (output === viewer.output) return;
+    viewer.output = output;
+    const info = this.state.backgroundTasks.get(viewer.taskId);
+    viewer.component.setProps({
+      taskId: viewer.taskId,
+      info,
+      output,
+      colors: this.state.theme.colors,
+      onClose: () => {
+        this.closeTaskOutputViewer();
+      },
+    });
+    this.state.ui.requestRender();
+  }
+
+  private closeTaskOutputViewer(): void {
+    const browser = this.state.tasksBrowser;
+    if (browser === undefined || browser.viewer === undefined) return;
+    const viewer = browser.viewer;
+    clearInterval(viewer.pollTimer);
+    browser.viewer = undefined;
+    this.state.ui.clear();
+    for (const child of viewer.savedChildren) {
+      this.state.ui.addChild(child);
+    }
+    this.state.ui.setFocus(browser.component);
+    this.state.ui.requestRender(true);
+  }
+
+  private closeTasksBrowser(): void {
+    const browser = this.state.tasksBrowser;
+    if (browser === undefined) return;
+    // If the output viewer is open, fold it back before tearing down
+    // the browser so the saved-children stack stays consistent.
+    if (browser.viewer !== undefined) this.closeTaskOutputViewer();
+    if (browser.pollTimer !== undefined) clearInterval(browser.pollTimer);
+    if (browser.flashTimer !== undefined) clearTimeout(browser.flashTimer);
+
+    // Restore the main TUI's children we saved when opening. After
+    // clearing, re-add in original order, then return focus to the
+    // editor so the user is back at the prompt.
+    this.state.ui.clear();
+    for (const child of browser.savedChildren) {
+      this.state.ui.addChild(child);
+    }
+    this.state.tasksBrowser = undefined;
+    this.state.ui.setFocus(this.state.editor);
+    this.state.ui.requestRender(true);
+  }
+
+  // Shows the editor command selector.
+  private showEditorPicker(): void {
+    const currentValue = this.state.appState.editorCommand ?? '';
+    this.mountEditorReplacement(
+      new EditorSelectorComponent({
+        currentValue,
+        colors: this.state.theme.colors,
+        onSelect: (value) => {
+          this.restoreEditor();
+          void this.applyEditorChoice(value);
+        },
+        onCancel: () => {
+          this.restoreEditor();
+        },
+      }),
+    );
+  }
+
+  // Persists and applies the selected external editor command.
+  private async applyEditorChoice(value: string): Promise<void> {
+    const previous = this.state.appState.editorCommand ?? '';
+    if (value === previous && value.length > 0) {
+      this.showStatus(`Editor unchanged: ${value.length > 0 ? value : 'auto-detect'}`);
+      return;
+    }
+
+    const editorCommand = value.length > 0 ? value : null;
+    try {
+      await saveTuiConfig({
+        theme: this.state.appState.theme,
+        editorCommand,
+        notifications: this.state.appState.notifications,
+      });
+    } catch (error) {
+      this.showStatus(
+        `Failed to save editor: ${formatErrorMessage(error)}`,
+        this.state.theme.colors.error,
+      );
+      return;
+    }
+
+    this.setAppState({ editorCommand });
+    this.showStatus(
+      value.length > 0
+        ? `Editor set to "${value}".`
+        : 'Editor set to auto-detect ($VISUAL / $EDITOR).',
+    );
+  }
+
+  // Shows the model selector when models are available.
+  private showModelPicker(selectedValue: string = this.state.appState.model): void {
+    const entries = Object.entries(this.state.appState.availableModels);
+    if (entries.length === 0) {
+      this.showError('No models configured.');
+      return;
+    }
+    this.mountEditorReplacement(
+      new ModelSelectorComponent({
+        models: this.state.appState.availableModels,
+        currentValue: this.state.appState.model,
+        selectedValue,
+        currentThinking: this.state.appState.thinking,
+        colors: this.state.theme.colors,
+        onSelect: ({ alias, thinking }) => {
+          this.restoreEditor();
+          void this.performModelSwitch(alias, thinking);
+        },
+        onCancel: () => {
+          this.restoreEditor();
+        },
+      }),
+    );
+  }
+
+  // Applies model and thinking changes to the active or newly created session.
+  private async performModelSwitch(alias: string, thinking: boolean): Promise<void> {
+    if (this.state.appState.isStreaming) {
+      this.showError('Cannot switch models while streaming — press Esc or Ctrl-C first.');
+      return;
+    }
+
+    if (alias === this.state.appState.model && thinking === this.state.appState.thinking) {
+      this.showStatus(`Already using ${alias} with thinking ${thinking ? 'on' : 'off'}.`);
+      return;
+    }
+
+    const level = thinking ? 'on' : 'off';
+    const prevModel = this.state.appState.model;
+    const prevThinking = this.state.appState.thinking;
+
+    try {
+      const session = this.session;
+      if (session === undefined) {
+        await this.activateModelAfterLogin(alias, thinking);
+      } else {
+        if (alias !== prevModel) {
+          await session.setModel(alias);
+        }
+        if (thinking !== prevThinking) {
+          await session.setThinking(level);
+        }
+      }
+      this.setAppState({ model: alias, thinking });
+      if (session === undefined) {
+        if (alias !== prevModel) {
+          this.track('model_switch', { model: alias });
+        }
+        if (thinking !== prevThinking) {
+          this.track('thinking_toggle', { enabled: thinking });
+        }
+      }
+      this.showStatus(
+        `Switched to ${alias} with thinking ${level}.`,
+        this.state.theme.colors.success,
+      );
+    } catch (error) {
+      const msg = formatErrorMessage(error);
+      this.showError(`Failed to switch model: ${msg}`);
+    }
+  }
+
+  // Shows the theme selector.
+  private showThemePicker(): void {
+    this.mountEditorReplacement(
+      new ThemeSelectorComponent({
+        currentValue: this.state.appState.theme,
+        colors: this.state.theme.colors,
+        onSelect: (value) => {
+          this.restoreEditor();
+          void this.applyThemeChoice(value);
+        },
+        onCancel: () => {
+          this.restoreEditor();
+        },
+      }),
+    );
+  }
+
+  // Shows the permission mode selector.
+  private showPermissionPicker(): void {
+    this.mountEditorReplacement(
+      new PermissionSelectorComponent({
+        currentValue: this.state.appState.permissionMode,
+        colors: this.state.theme.colors,
+        onSelect: (value) => {
+          this.restoreEditor();
+          void this.applyPermissionChoice(value);
+        },
+        onCancel: () => {
+          this.restoreEditor();
+        },
+      }),
+    );
+  }
+
+  // Shows the settings selector entry point.
+  private showSettingsSelector(): void {
+    this.mountEditorReplacement(
+      new SettingsSelectorComponent({
+        colors: this.state.theme.colors,
+        onSelect: (value) => {
+          this.handleSettingsSelection(value);
+        },
+        onCancel: () => {
+          this.restoreEditor();
+        },
+      }),
+    );
+  }
+
+  // Routes a settings selection to the matching selector or panel.
+  private handleSettingsSelection(value: SettingsSelection): void {
+    this.restoreEditor();
+    switch (value) {
+      case 'model':
+        this.showModelPicker();
+        return;
+      case 'permission':
+        this.showPermissionPicker();
+        return;
+      case 'theme':
+        this.showThemePicker();
+        return;
+      case 'editor':
+        this.showEditorPicker();
+        return;
+      case 'usage':
+        void this.showUsage();
+        return;
+    }
+  }
+
+  // Applies a permission mode choice to the active session and app state.
+  private async applyPermissionChoice(mode: PermissionMode): Promise<void> {
+    if (mode === this.state.appState.permissionMode) {
+      this.showStatus(`Permission mode unchanged: ${mode}.`);
+      return;
+    }
+
+    try {
+      await this.requireSession().setPermission(mode);
+    } catch (error) {
+      const msg = formatErrorMessage(error);
+      this.showError(`Failed to set permission mode: ${msg}`);
+      return;
+    }
+
+    this.setAppState({ permissionMode: mode, yolo: mode === 'yolo' });
+    this.showNotice(`Permission mode: ${mode}`);
+  }
+
+  // Persists and applies a theme choice.
+  private async applyThemeChoice(theme: Theme): Promise<void> {
+    if (theme === this.state.appState.theme) {
+      if (theme === 'auto') this.refreshTerminalThemeTracking();
+      this.showStatus(`Theme unchanged: "${theme}".`);
+      return;
+    }
+
+    try {
+      await saveTuiConfig({
+        theme,
+        editorCommand: this.state.appState.editorCommand,
+        notifications: this.state.appState.notifications,
+      });
+    } catch (error) {
+      this.showStatus(
+        `Failed to save theme: ${formatErrorMessage(error)}`,
+        this.state.theme.colors.error,
+      );
+      return;
+    }
+
+    const resolved = theme === 'auto' ? this.state.theme.resolvedTheme : theme;
+    this.applyTheme(theme, resolved);
+    this.refreshTerminalThemeTracking();
+    this.track('theme_switch', { theme });
+    const detail = theme === 'auto' ? ` (tracking terminal; current: ${resolved})` : '';
+    this.showStatus(`Theme set to "${theme}"${detail}.`);
+  }
+
+  // Loads and renders current usage information.
+  private async showUsage(): Promise<void> {
+    const sessionUsage = await this.loadSessionUsageReport();
+    const managedUsage = await this.loadManagedUsageReport();
+    const lines = buildUsageReportLines({
+      colors: this.state.theme.colors,
+      sessionUsage: sessionUsage.usage,
+      sessionUsageError: sessionUsage.error,
+      contextUsage: this.state.appState.contextUsage,
+      contextTokens: this.state.appState.contextTokens,
+      maxContextTokens: this.state.appState.maxContextTokens,
+      managedUsage: managedUsage?.usage,
+      managedUsageError: managedUsage?.error,
+    });
+    const panel = new UsagePanelComponent(lines, this.state.theme.colors.primary);
+    this.state.transcriptContainer.addChild(panel);
+    this.state.ui.requestRender();
+  }
+
+  // Loads and renders current runtime status.
+  private async showStatusReport(): Promise<void> {
+    const [runtimeStatus, managedUsage] = await Promise.all([
+      this.loadRuntimeStatusReport(),
+      this.loadManagedUsageReport(),
+    ]);
+    const appState = this.state.appState;
+    const lines = buildStatusReportLines({
+      colors: this.state.theme.colors,
+      version: appState.version,
+      model: appState.model,
+      workDir: appState.workDir,
+      sessionId: appState.sessionId,
+      sessionTitle: appState.sessionTitle,
+      thinking: appState.thinking,
+      permissionMode: appState.permissionMode,
+      planMode: appState.planMode,
+      contextUsage: appState.contextUsage,
+      contextTokens: appState.contextTokens,
+      maxContextTokens: appState.maxContextTokens,
+      availableModels: appState.availableModels,
+      status: runtimeStatus.status,
+      statusError: runtimeStatus.error,
+      managedUsage: managedUsage?.usage,
+      managedUsageError: managedUsage?.error,
+    });
+    const panel = new UsagePanelComponent(lines, this.state.theme.colors.primary, ' Status ');
+    this.state.transcriptContainer.addChild(panel);
+    this.state.ui.requestRender();
+  }
+
+  // Loads and renders current MCP server status.
+  private async showMcpServers(): Promise<void> {
+    let servers: readonly McpServerInfo[];
+    try {
+      servers = await this.requireSession().listMcpServers();
+    } catch (error) {
+      this.showError(`Failed to load MCP servers: ${formatErrorMessage(error)}`);
+      return;
+    }
+
+    const lines = buildMcpStatusReportLines({
+      colors: this.state.theme.colors,
+      servers,
+    });
+    const title = servers.length > 0 ? ` MCP (${servers.length}) ` : ' MCP ';
+    const panel = new UsagePanelComponent(lines, this.state.theme.colors.primary, title);
+    this.state.transcriptContainer.addChild(panel);
+    this.state.ui.requestRender();
+  }
+
+  // Loads per-session usage and captures displayable errors.
+  private async loadSessionUsageReport(): Promise<SessionUsageResult> {
+    try {
+      return { usage: await this.requireSession().getUsage() };
+    } catch (error) {
+      return { error: formatErrorMessage(error) };
+    }
+  }
+
+  // Loads per-session runtime status and captures displayable errors.
+  private async loadRuntimeStatusReport(): Promise<RuntimeStatusResult> {
+    try {
+      return { status: await this.requireSession().getStatus() };
+    } catch (error) {
+      return { error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
+  // Loads managed-provider usage when the active model supports it.
+  private async loadManagedUsageReport(): Promise<ManagedUsageResult | undefined> {
+    const alias = this.state.appState.model;
+    const providerKey = this.state.appState.availableModels[alias]?.provider;
+    if (!isManagedUsageProvider(providerKey)) return undefined;
+
+    let res;
+    try {
+      res = await this.harness.auth.getManagedUsage(providerKey);
+    } catch (error) {
+      return { error: formatErrorMessage(error) };
+    }
+    if (res.kind === 'error') {
+      return { error: res.message };
+    }
+    return { usage: { summary: res.summary, limits: res.limits } };
+  }
+
+  // Shows an approval panel and connects its response callback.
+  private showApprovalPanel(payload: ApprovalPanelData): void {
+    this.patchLivePane({ pendingApproval: { data: payload } });
+    notifyTerminalOnce(this.state, `approval:${payload.id}`, {
+      title: 'Kimi Code approval required',
+      body: payload.tool_name,
+    });
+    const panel = new ApprovalPanelComponent(
+      { data: payload },
+      (response: ApprovalPanelResponse) => {
+        this.approvalController.respond(adaptPanelResponse(response));
+      },
+      this.state.theme.colors,
+      () => {
+        this.toggleToolOutputExpansion();
+      },
+      () => {
+        this.togglePlanExpansion();
+      },
+    );
+    this.mountEditorReplacement(panel);
+  }
+
+  // Hides the active approval panel.
+  private hideApprovalPanel(): void {
+    this.patchLivePane({ pendingApproval: null });
+    this.restoreEditor();
+  }
+
+  // Shows a question dialog and connects its response callback.
+  private showQuestionDialog(payload: QuestionPanelData): void {
+    this.patchLivePane({ pendingQuestion: { data: payload } });
+    notifyTerminalOnce(this.state, `question:${payload.id}`, {
+      title: 'Kimi Code needs your answer',
+      body: payload.questions[0]?.question,
+    });
+    const dialog = new QuestionDialogComponent(
+      { data: payload },
+      (response) => {
+        this.questionController.respond(response);
+      },
+      this.state.theme.colors,
+      undefined,
+      () => {
+        this.toggleToolOutputExpansion();
+      },
+      () => {
+        this.togglePlanExpansion();
+      },
+    );
+    this.mountEditorReplacement(dialog);
+  }
+
+  // Hides the active question dialog.
+  private hideQuestionDialog(): void {
+    this.patchLivePane({ pendingQuestion: null });
+    this.restoreEditor();
+  }
+
+  // =========================================================================
+  // Slash Command Handlers
+  // =========================================================================
+
+  // Applies plan mode through the session and mirrors it into UI state.
+  private async applyPlanMode(session: Session, enabled: boolean): Promise<void> {
+    try {
+      await session.setPlanMode(enabled);
+      this.setAppState({ planMode: enabled });
+      if (enabled) {
+        const plan = await session.getPlan().catch(() => null);
+        this.showNotice(
+          'Plan mode: ON',
+          plan?.path !== undefined ? `Plan will be created here: ${plan.path}` : undefined,
+        );
+        return;
+      }
+      this.showNotice('Plan mode: OFF');
+    } catch (error) {
+      const msg = formatErrorMessage(error);
+      this.showError(`Failed to set plan mode: ${msg}`);
+    }
+  }
+
+  // Handles the /editor command.
+  private async handleEditorCommand(args: string, _eCtx: {}): Promise<void> {
+    const command = args.trim();
+    if (command.length === 0) {
+      this.showEditorPicker();
+      return;
+    }
+    await this.applyEditorChoice(command);
+  }
+
+  // Handles the /theme command.
+  private async handleThemeCommand(args: string): Promise<void> {
+    const theme = args.trim();
+    if (theme.length === 0) {
+      this.showThemePicker();
+      return;
+    }
+    if (!isTheme(theme)) {
+      this.showError(`Unknown theme: ${theme}`);
+      return;
+    }
+    await this.applyThemeChoice(theme);
+  }
+
+  // Handles the /model command.
+  private handleModelCommand(args: string): void {
+    const alias = args.trim();
+    if (alias.length === 0) {
+      this.showModelPicker();
+      return;
+    }
+    if (this.state.appState.availableModels[alias] === undefined) {
+      this.showError(`Unknown model alias: ${alias}`);
+      return;
+    }
+    this.showModelPicker(alias);
+  }
+
+  // Handles the /title command.
+  private async handleTitleCommand(args: string): Promise<void> {
+    const title = args.trim();
+    if (title.length === 0) {
+      const current = this.state.appState.sessionTitle;
+      this.showStatus(
+        current !== null && current.length > 0
+          ? `Session title: ${current}`
+          : `Session title: (not set) — id: ${this.state.appState.sessionId}`,
+      );
+      return;
+    }
+
+    const session = this.session;
+    if (session === undefined) {
+      this.showError(NO_ACTIVE_SESSION_MESSAGE);
+      return;
+    }
+
+    const newTitle = title.slice(0, 200);
+    try {
+      await this.harness.renameSession({ id: session.id, title: newTitle });
+    } catch (error) {
+      const msg = formatErrorMessage(error);
+      this.showError(`Failed to set title: ${msg}`);
+      return;
+    }
+    this.showStatus(`Session title set to: ${newTitle}`);
+  }
+
+  // Handles the /fork command.
+  private async handleForkCommand(args: string): Promise<void> {
+    void args;
+
+    const session = this.session;
+    if (session === undefined) {
+      this.showError(NO_ACTIVE_SESSION_MESSAGE);
+      return;
+    }
+
+    const sourceTitle = this.forkSourceTitle(session);
+    let forked: Session;
+    try {
+      forked = await this.harness.forkSession({
+        id: session.id,
+        title: `Fork: ${sourceTitle}`,
+      });
+    } catch (error) {
+      const msg = formatErrorMessage(error);
+      this.showError(`Failed to fork session: ${msg}`);
+      return;
+    }
+
+    try {
+      await this.switchToSession(forked, `Session forked (${forked.id}).`);
+    } catch (error) {
+      const msg = formatErrorMessage(error);
+      this.showError(`Failed to switch to forked session: ${msg}`);
+    }
+  }
+
+  private forkSourceTitle(session: Session): string {
+    const currentTitle = this.state.appState.sessionTitle?.trim();
+    if (currentTitle !== undefined && currentTitle.length > 0) return currentTitle;
+
+    const summaryTitle =
+      typeof session.summary?.title === 'string' ? session.summary.title.trim() : '';
+    return summaryTitle.length > 0 ? summaryTitle : session.id;
+  }
+
+  // Handles the /yolo command.
+  private async handleYoloCommand(args: string): Promise<void> {
+    const session = this.session;
+    if (session === undefined) {
+      this.showError(NO_ACTIVE_SESSION_MESSAGE);
+      return;
+    }
+
+    let enabled: boolean;
+    if (args === 'on') enabled = true;
+    else if (args === 'off') enabled = false;
+    else enabled = !this.state.appState.yolo;
+
+    await session.setPermission(enabled ? 'yolo' : 'manual');
+    this.setAppState({ yolo: enabled, permissionMode: enabled ? 'yolo' : 'manual' });
+    if (enabled) {
+      this.showNotice(
+        'YOLO mode: ON',
+        'All actions will be approved automatically. Use with caution.',
+      );
+      return;
+    }
+    this.showNotice('YOLO mode: OFF');
+  }
+
+  // Handles the /plan command.
+  private async handlePlanCommand(args: string): Promise<void> {
+    const session = this.session;
+    if (session === undefined) {
+      this.showError(NO_ACTIVE_SESSION_MESSAGE);
+      return;
+    }
+
+    const subcmd = args.trim().toLowerCase();
+    if (subcmd === 'clear') {
+      await session.clearPlan();
+      this.showNotice('Plan cleared');
+      return;
+    }
+
+    let enabled: boolean;
+    if (subcmd.length === 0) enabled = !this.state.appState.planMode;
+    else if (subcmd === 'on') enabled = true;
+    else if (subcmd === 'off') enabled = false;
+    else {
+      this.showError(`Unknown plan subcommand: ${subcmd}`);
+      return;
+    }
+
+    await this.applyPlanMode(session, enabled);
+  }
+
+  // Handles the /compact command.
+  private async handleCompactCommand(args: string): Promise<void> {
+    const session = this.session;
+    if (session === undefined) {
+      this.showError(NO_ACTIVE_SESSION_MESSAGE);
+      return;
+    }
+
+    const customInstruction = args.trim() || undefined;
+    await session.compact({ instruction: customInstruction });
+  }
+
+  // Handles the /init command.
+  private async handleInitCommand(): Promise<void> {
+    const session = this.session;
+    if (this.state.appState.model.trim().length === 0 || session === undefined) {
+      this.showError(LLM_NOT_SET_MESSAGE);
+      return;
+    }
+
+    this.deferUserMessages = true;
+    this.beginSessionRequest();
+    try {
+      await session.init();
+      this.track('init_complete');
+      this.finalizeTurn((item) => {
+        this.sendQueuedMessage(session, item);
+      });
+    } catch (error) {
+      if (isAbortError(error)) {
+        this.setAppState({ isStreaming: false, streamingPhase: 'idle' });
+        this.resetLivePane();
+        return;
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      this.failSessionRequest(`Init failed: ${msg}`);
+    } finally {
+      this.deferUserMessages = false;
+    }
+  }
+
+  // Handles the /login command.
+  private async handleLoginCommand(): Promise<void> {
+    const platformId = await this.promptPlatformSelection();
+    if (platformId === undefined) return;
+
+    if (platformId === 'kimi-code') {
+      await this.handleKimiCodeOAuthLogin();
+      return;
+    }
+
+    const platform = getOpenPlatformById(platformId);
+    if (platform === undefined) return;
+    await this.handleOpenPlatformLogin(platform);
+  }
+
+  // Kimi Code OAuth login flow.
+  private async handleKimiCodeOAuthLogin(): Promise<void> {
+    const status = await this.harness.auth.status(DEFAULT_OAUTH_PROVIDER_NAME);
+    const alreadyLoggedIn = status.providers.some(
+      (provider) => provider.providerName === DEFAULT_OAUTH_PROVIDER_NAME && provider.hasToken,
+    );
+
+    let spinner: LoginProgressSpinnerHandle | undefined;
+    const controller = new AbortController();
+    const cancelLogin = (): void => {
+      controller.abort();
+    };
+    this.cancelInFlight = cancelLogin;
+    try {
+      await this.harness.auth.login(DEFAULT_OAUTH_PROVIDER_NAME, {
+        signal: controller.signal,
+        onDeviceCode: (data) => {
+          spinner = this.showLoginAuthorizationPrompt(data);
+        },
+      });
+      spinner?.stop({ ok: true, label: 'Logged in.' });
+      spinner = undefined;
+      try {
+        await this.refreshConfigAfterLogin();
+      } catch (refreshError) {
+        const message = formatErrorMessage(refreshError);
+        this.showError(`Authentication successful, but failed to refresh config: ${message}`);
+        return;
+      }
+      this.track('login', {
+        provider: DEFAULT_OAUTH_PROVIDER_NAME,
+        already_logged_in: alreadyLoggedIn,
+      });
+      if (alreadyLoggedIn) {
+        this.showStatus('Already logged in. Model configuration refreshed.');
+      }
+    } catch (error) {
+      const cancelled = controller.signal.aborted;
+      spinner?.stop({
+        ok: false,
+        label: cancelled ? 'Login cancelled.' : 'Login failed.',
+      });
+      spinner = undefined;
+      if (cancelled) return;
+      log.warn('login failed', {
+        providerName: DEFAULT_OAUTH_PROVIDER_NAME,
+        alreadyLoggedIn,
+        sessionId: this.session?.id,
+        error,
+      });
+      const message = formatErrorMessage(error);
+      this.showError(`Login failed: ${message}`);
+    } finally {
+      if (this.cancelInFlight === cancelLogin) {
+        this.cancelInFlight = undefined;
+      }
+    }
+  }
+
+  // Open platform API key login flow.
+  private async handleOpenPlatformLogin(
+    platform: OpenPlatformDefinition,
+  ): Promise<void> {
+    const apiKey = await this.promptApiKey(platform.name);
+    if (apiKey === undefined) return;
+
+    const controller = new AbortController();
+    const cancelLogin = (): void => {
+      controller.abort();
+    };
+    this.cancelInFlight = cancelLogin;
+
+    let models: ManagedKimiCodeModelInfo[];
+    try {
+      models = await fetchOpenPlatformModels(platform, apiKey, fetch, controller.signal);
+      models = filterModelsByPrefix(models, platform);
+    } catch (error) {
+      if (controller.signal.aborted) return;
+      const msg = formatErrorMessage(error);
+      this.showError(`Failed to verify API key: ${msg}`);
+      if (
+        error instanceof OpenPlatformApiError &&
+        error.status === 401
+      ) {
+        this.showStatus(
+          'Hint: If your API key was obtained from Kimi Code, please select "Kimi Code" instead.',
+        );
+      }
+      return;
+    } finally {
+      if (this.cancelInFlight === cancelLogin) {
+        this.cancelInFlight = undefined;
+      }
+    }
+
+    if (models.length === 0) {
+      this.showError('No models available for this platform.');
+      return;
+    }
+
+    const selection = await this.promptModelSelectionForOpenPlatform(models, platform);
+    if (selection === undefined) return;
+
+    // Remove stale provider config first so old model aliases are fully
+    // cleared (setConfig patch merge cannot delete nested keys).
+    const existingConfig = await this.harness.getConfig();
+    if (existingConfig.providers[platform.id] !== undefined) {
+      await this.harness.removeProvider(platform.id);
+    }
+
+    const config = await this.harness.getConfig();
+    applyOpenPlatformConfig(config as ManagedKimiConfigShape, {
+      platform,
+      models,
+      selectedModel: selection.model,
+      thinking: selection.thinking,
+      apiKey,
+    });
+
+    await this.harness.setConfig({
+      providers: config.providers,
+      models: config.models,
+      defaultModel: config.defaultModel,
+      defaultThinking: config.defaultThinking,
+    });
+
+    await this.refreshConfigAfterLogin();
+    this.track('login', { provider: platform.id, method: 'api_key' });
+    this.showStatus(`Setup complete: ${platform.name} · ${selection.model.id}`);
+  }
+
+  // Handles the /feedback command — opens an inline input dialog and POSTs
+  // the result to the managed Kimi Code platform. Falls back to the GitHub
+  // Issues page when the user is not signed in or the request fails.
+  private async handleFeedbackCommand(): Promise<void> {
+    const fallback = (reason: string): void => {
+      this.showStatus(reason);
+      this.showStatus(FEEDBACK_ISSUE_URL);
+      openUrl(FEEDBACK_ISSUE_URL);
+    };
+
+    const providerKey = this.state.appState.availableModels[this.state.appState.model]?.provider;
+    if (!isManagedUsageProvider(providerKey)) {
+      fallback(FEEDBACK_STATUS_NOT_SIGNED_IN);
+      return;
+    }
+
+    const content = await this.promptFeedbackInput();
+    if (content === undefined) {
+      this.showStatus(FEEDBACK_STATUS_CANCELLED);
+      return;
+    }
+
+    const spinner = this.showLoginProgressSpinner(FEEDBACK_STATUS_SUBMITTING);
+    const res = await this.harness.auth.submitFeedback({
+      content,
+      sessionId: this.state.appState.sessionId,
+      version: withFeedbackVersionPrefix(this.state.appState.version),
+      os: `${osType()} ${osRelease()}`,
+      model: this.state.appState.model.length > 0 ? this.state.appState.model : null,
+    });
+
+    if (res.kind === 'ok') {
+      spinner.stop({ ok: true, label: FEEDBACK_STATUS_SUCCESS });
+      this.showStatus(feedbackSessionLine(this.state.appState.sessionId));
+      this.track(FEEDBACK_TELEMETRY_EVENT);
+      return;
+    }
+
+    const failLabel =
+      res.status !== undefined
+        ? feedbackHttpErrorMessage(res.status)
+        : FEEDBACK_STATUS_NETWORK_ERROR;
+    spinner.stop({ ok: false, label: failLabel });
+    fallback(FEEDBACK_STATUS_FALLBACK);
+  }
+
+  // Mounts the feedback input dialog and resolves with the trimmed value
+  // when submitted, or undefined when the user cancels.
+  private promptFeedbackInput(): Promise<string | undefined> {
+    return new Promise((resolve) => {
+      const dialog = new FeedbackInputDialogComponent((result: FeedbackInputDialogResult) => {
+        this.restoreEditor();
+        resolve(result.kind === 'ok' ? result.value : undefined);
+      }, this.state.theme.colors);
+      this.mountEditorReplacement(dialog);
+    });
+  }
+
+  // Handles the /logout command.
+  private async handleLogoutCommand(): Promise<void> {
+    const currentModel = this.state.appState.model.trim();
+    const currentProvider = this.state.appState.availableModels[currentModel]?.provider;
+
+    if (currentProvider === undefined || currentProvider === DEFAULT_OAUTH_PROVIDER_NAME) {
+      await this.harness.auth.logout(DEFAULT_OAUTH_PROVIDER_NAME);
+      await this.refreshConfigAfterLogout();
+      await this.clearActiveSessionAfterLogout();
+      this.track('logout', { provider: DEFAULT_OAUTH_PROVIDER_NAME });
+      this.showStatus('Logged out.');
+      return;
+    }
+
+    if (isOpenPlatformId(currentProvider)) {
+      await this.harness.removeProvider(currentProvider);
+      await this.refreshConfigAfterLogout();
+      await this.clearActiveSessionAfterLogout();
+      this.track('logout', { provider: currentProvider });
+      this.showStatus(`Logged out from ${currentProvider}.`);
+      return;
+    }
+
+    this.showStatus('Nothing to logout.');
+  }
+
+  // ---------------------------------------------------------------------------
+  // Login / setup prompts
+  // ---------------------------------------------------------------------------
+
+  private promptPlatformSelection(): Promise<string | undefined> {
+    return new Promise((resolve) => {
+      const selector = new PlatformSelectorComponent({
+        colors: this.state.theme.colors,
+        onSelect: (platformId) => {
+          this.restoreEditor();
+          resolve(platformId);
+        },
+        onCancel: () => {
+          this.restoreEditor();
+          resolve(undefined);
+        },
+      });
+      this.mountEditorReplacement(selector);
+    });
+  }
+
+  private promptApiKey(platformName: string): Promise<string | undefined> {
+    return new Promise((resolve) => {
+      const dialog = new ApiKeyInputDialogComponent(
+        platformName,
+        (result: ApiKeyInputResult) => {
+          this.restoreEditor();
+          resolve(result.kind === 'ok' ? result.value : undefined);
+        },
+        this.state.theme.colors,
+      );
+      this.mountEditorReplacement(dialog);
+    });
+  }
+
+  private promptModelSelectionForOpenPlatform(
+    models: ManagedKimiCodeModelInfo[],
+    platform: OpenPlatformDefinition,
+  ): Promise<{ model: ManagedKimiCodeModelInfo; thinking: boolean } | undefined> {
+    return new Promise((resolve) => {
+      const modelDict: Record<string, ModelAlias> = {};
+      for (const m of models) {
+        const alias = `${platform.id}/${m.id}`;
+        modelDict[alias] = {
+          provider: platform.id,
+          model: m.id,
+          maxContextSize: m.contextLength,
+          capabilities: capabilitiesForModel(m),
+          displayName: m.displayName,
+        };
+      }
+
+      const firstAlias = Object.keys(modelDict)[0] ?? '';
+      const firstModel = modelDict[firstAlias];
+      const initialThinking = (() => {
+        const caps = firstModel?.capabilities ?? [];
+        return caps.includes('always_thinking') || caps.includes('thinking');
+      })();
+
+      const selector = new ModelSelectorComponent({
+        models: modelDict,
+        currentValue: firstAlias,
+        currentThinking: initialThinking,
+        colors: this.state.theme.colors,
+        onSelect: ({ alias, thinking }) => {
+          this.restoreEditor();
+          const model = models.find((m) => `${platform.id}/${m.id}` === alias);
+          resolve(model ? { model, thinking } : undefined);
+        },
+        onCancel: () => {
+          this.restoreEditor();
+          resolve(undefined);
+        },
+      });
+      this.mountEditorReplacement(selector);
+    });
+  }
+}
+
+function formatHookResultMarkdown(event: HookResultEvent): string {
+  return `*${formatHookResultTitle(event)}*\n\n${formatHookResultBody(event)}`;
+}
+
+function formatHookResultPlain(event: HookResultEvent): string {
+  return `${formatHookResultTitle(event)}\n\n${formatHookResultBody(event)}`;
+}
+
+function formatHookResultTitle(event: HookResultEvent): string {
+  return `${event.hookEvent} hook${event.blocked === true ? ' blocked' : ''}`;
+}
+
+function formatHookResultBody(event: HookResultEvent): string {
+  const content = event.content.trim();
+  return content.length === 0 ? '(empty)' : content;
+}
diff --git a/apps/kimi-code/src/tui/reverse-rpc/approval/adapter.ts b/apps/kimi-code/src/tui/reverse-rpc/approval/adapter.ts
new file mode 100644
index 000000000..c53cce753
--- /dev/null
+++ b/apps/kimi-code/src/tui/reverse-rpc/approval/adapter.ts
@@ -0,0 +1,339 @@
+import type { ApprovalRequest, ApprovalResponse, ToolInputDisplay } from '@moonshot-ai/kimi-code-sdk';
+
+import type { ApprovalPanelResponse } from '#/tui/components/dialogs/approval-panel';
+import type { ApprovalPanelChoice, ApprovalPanelData, DisplayBlock } from '#/tui/reverse-rpc/types';
+
+const DEFAULT_APPROVAL_CHOICES: ApprovalPanelChoice[] = [
+  { label: 'Approve once', response: 'approved' },
+  { label: 'Approve for this session', response: 'approved_for_session' },
+  { label: 'Reject', response: 'rejected' },
+  { label: 'Reject with feedback', response: 'rejected', requires_feedback: true },
+];
+
+const PLAN_REJECT_CHOICES: ApprovalPanelChoice[] = [
+  { label: 'Reject', response: 'rejected', selected_label: 'Reject' },
+  { label: 'Revise', response: 'rejected', selected_label: 'Revise', requires_feedback: true },
+];
+
+export function adaptApprovalRequest(event: ApprovalRequest): ApprovalPanelData {
+  const resolved = resolveDisplay(event.toolName, event.display, event.action);
+  return {
+    id: event.toolCallId,
+    tool_call_id: event.toolCallId,
+    tool_name: event.toolName,
+    action: event.action,
+    description: resolved.description,
+    display: resolved.blocks,
+    choices: adaptChoices(event.toolName, event.display),
+  };
+}
+
+interface ResolvedDisplay {
+  blocks: DisplayBlock[];
+  description: string;
+}
+
+function resolveDisplay(
+  toolName: string,
+  display: ToolInputDisplay,
+  action: string,
+): ResolvedDisplay {
+  if (display.kind === 'generic' && isRecord(display.detail)) {
+    const extracted = extractFromArgs(toolName, display.detail);
+    if (extracted !== null) return extracted;
+  }
+  return {
+    blocks: adaptDisplay(display),
+    description: describeApproval(display, action),
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function stringField(detail: Record<string, unknown>, key: string): string | undefined {
+  const value = detail[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+function extractFromArgs(
+  toolName: string,
+  detail: Record<string, unknown>,
+): ResolvedDisplay | null {
+  const command = stringField(detail, 'command');
+  if (command !== undefined) {
+    const cwd = stringField(detail, 'cwd');
+    const toolDescription = stringField(detail, 'description');
+    const danger = detectDanger(command);
+    const language = stringField(detail, 'language') ?? 'bash';
+    return {
+      blocks: [
+        {
+          type: 'shell',
+          language,
+          command,
+          cwd,
+          description: toolDescription,
+          danger,
+        },
+      ],
+      description: toolDescription ?? '',
+    };
+  }
+
+  const oldString = stringField(detail, 'old_string');
+  const newString = stringField(detail, 'new_string');
+  if (oldString !== undefined && newString !== undefined) {
+    const path = stringField(detail, 'file_path') ?? stringField(detail, 'path') ?? '';
+    // Diff block carries its own `+N -M path` header — no separate
+    // file_op title row needed.
+    return {
+      blocks: [{ type: 'diff', path, old_text: oldString, new_text: newString }],
+      description: '',
+    };
+  }
+
+  const filePath = stringField(detail, 'file_path') ?? stringField(detail, 'path');
+  const content = stringField(detail, 'content');
+  if (filePath !== undefined && content !== undefined) {
+    // Write is a brand-new file: render the content as a syntax-
+    // highlighted code block, not a diff full of `+` markers.
+    return {
+      blocks: [{ type: 'file_content', path: filePath, content }],
+      description: '',
+    };
+  }
+
+  const url = stringField(detail, 'url');
+  if (url !== undefined) {
+    const method = stringField(detail, 'method');
+    return {
+      blocks: [{ type: 'url_fetch', url, method }],
+      description: '',
+    };
+  }
+
+  const query = stringField(detail, 'query');
+  if (query !== undefined) {
+    return {
+      blocks: [{ type: 'search', query }],
+      description: '',
+    };
+  }
+
+  const pattern = stringField(detail, 'pattern');
+  if (pattern !== undefined) {
+    const scope = stringField(detail, 'path');
+    return {
+      blocks: [{ type: 'search', query: pattern, scope }],
+      description: '',
+    };
+  }
+
+  if (filePath !== undefined) {
+    const operation = inferFileOp(toolName);
+    return {
+      blocks: [{ type: 'file_op', operation, path: filePath }],
+      description: '',
+    };
+  }
+
+  return null;
+}
+
+function inferFileOp(toolName: string): 'read' | 'write' | 'edit' | 'glob' | 'grep' {
+  const lower = toolName.toLowerCase();
+  if (lower.includes('glob')) return 'glob';
+  if (lower.includes('grep')) return 'grep';
+  if (lower.includes('edit')) return 'edit';
+  if (lower.includes('write')) return 'write';
+  return 'read';
+}
+
+export function adaptPanelResponse(response: ApprovalPanelResponse): ApprovalResponse {
+  if (response.response === 'approved_for_session') {
+    return {
+      decision: 'approved',
+      scope: 'session',
+      feedback: response.feedback,
+      selectedLabel: response.selected_label,
+    };
+  }
+  return {
+    decision:
+      response.response === 'approved'
+        ? 'approved'
+        : response.response === 'rejected'
+          ? 'rejected'
+          : 'cancelled',
+    feedback: response.feedback,
+    selectedLabel: response.selected_label,
+  };
+}
+
+function describeApproval(display: ToolInputDisplay, action: string): string {
+  switch (display.kind) {
+    case 'plan_review':
+      return '';
+    case 'generic':
+      if (typeof display.detail === 'string' && display.detail.length > 0) {
+        return display.detail;
+      }
+      return display.summary ?? action;
+    case 'command':
+      return display.description ?? display.command ?? action;
+    case 'diff':
+      return `edit ${display.path ?? ''}`.trim();
+    case 'file_io':
+      return `${display.operation ?? 'file'} ${display.path ?? ''}`.trim();
+    case 'task_stop':
+      return `stop task: ${display.task_description ?? display.task_id ?? ''}`.trim();
+    case 'agent_call':
+      return `spawn ${display.agent_name ?? 'agent'}`;
+    case 'skill_call':
+      return `invoke skill ${display.skill_name ?? ''}`.trim();
+    case 'url_fetch':
+      return `fetch ${display.url ?? ''}`.trim();
+    case 'search':
+      return `search: ${display.query ?? ''}`.trim();
+    case 'todo_list':
+      return `update todo list (${String(display.items?.length ?? 0)} items)`;
+    case 'background_task':
+      return `${display.status ?? 'background'} task ${display.task_id ?? ''}: ${
+        display.description ?? ''
+      }`.trim();
+    default:
+      return action;
+  }
+}
+
+const DANGER_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /\brm\s+(-[a-zA-Z]*[rRfF][a-zA-Z]*|--recursive|--force)/i, label: 'recursive delete' },
+  { pattern: /\bsudo\b/i, label: 'sudo' },
+  { pattern: /\b(curl|wget)\b[^|]*\|\s*(sh|bash|zsh)\b/i, label: 'pipe to shell' },
+  { pattern: /\bdd\b[^|]*\bof=/i, label: 'dd write' },
+  { pattern: /\bmkfs\b/i, label: 'mkfs' },
+  { pattern: />\s*\/dev\/(sd|nvme|disk|hd)/i, label: 'write to raw device' },
+  { pattern: /\bchmod\s+-R?\s*777\b/i, label: 'chmod 777' },
+  { pattern: /:\(\)\s*\{\s*:\|:&\s*\}/i, label: 'fork bomb' },
+];
+
+function detectDanger(command: string): string | undefined {
+  for (const { pattern, label } of DANGER_PATTERNS) {
+    if (pattern.test(command)) return label;
+  }
+  return undefined;
+}
+
+function adaptDisplay(display: ToolInputDisplay): DisplayBlock[] {
+  switch (display.kind) {
+    case 'command': {
+      const command = display.command ?? '';
+      const danger = detectDanger(command);
+      return [
+        {
+          type: 'shell',
+          language: display.language ?? 'bash',
+          command,
+          cwd: display.cwd,
+          description: display.description,
+          danger,
+        },
+      ];
+    }
+    case 'diff':
+      return [
+        {
+          type: 'diff',
+          path: display.path ?? '',
+          old_text: display.before ?? '',
+          new_text: display.after ?? '',
+        },
+      ];
+    case 'file_io':
+      return [
+        {
+          type: 'file_op',
+          operation: display.operation,
+          path: display.path ?? '',
+          detail: display.detail,
+        },
+      ];
+    case 'url_fetch':
+      return [
+        {
+          type: 'url_fetch',
+          url: display.url ?? '',
+          method: display.method,
+        },
+      ];
+    case 'search':
+      return [
+        {
+          type: 'search',
+          query: display.query ?? '',
+          scope: display.scope,
+        },
+      ];
+    case 'agent_call':
+      return [
+        {
+          type: 'invocation',
+          kind: 'agent',
+          name: display.agent_name ?? '',
+          description: display.prompt,
+        },
+      ];
+    case 'skill_call':
+      return [
+        {
+          type: 'invocation',
+          kind: 'skill',
+          name: display.skill_name ?? '',
+          description: display.args,
+        },
+      ];
+    case 'task_stop':
+      return [
+        {
+          type: 'brief',
+          text: `Stop task ${display.task_id ?? ''}: ${display.task_description ?? ''}`,
+        },
+      ];
+    case 'plan_review':
+      return [];
+    case 'generic':
+      return [];
+    case 'todo_list':
+      return [];
+    case 'background_task':
+      return [];
+    default:
+      return [];
+  }
+}
+
+function adaptChoices(toolName: string, display: ToolInputDisplay): ApprovalPanelChoice[] {
+  if (toolName === 'ExitPlanMode' || display.kind === 'plan_review') {
+    return adaptPlanReviewChoices(display);
+  }
+
+  return DEFAULT_APPROVAL_CHOICES.map((choice) => cloneChoice(choice));
+}
+
+function adaptPlanReviewChoices(display: ToolInputDisplay): ApprovalPanelChoice[] {
+  const optionChoices =
+    display.kind === 'plan_review' && display.options !== undefined && display.options.length >= 2
+      ? display.options.map((option) => ({
+          label: option.label,
+          response: 'approved' as const,
+          selected_label: option.label,
+        }))
+      : [{ label: 'Approve', response: 'approved' as const, selected_label: 'Approve' }];
+  return [...optionChoices, ...PLAN_REJECT_CHOICES].map((choice) => cloneChoice(choice));
+}
+
+function cloneChoice(choice: ApprovalPanelChoice): ApprovalPanelChoice {
+  return { ...choice };
+}
diff --git a/apps/kimi-code/src/tui/reverse-rpc/approval/controller.ts b/apps/kimi-code/src/tui/reverse-rpc/approval/controller.ts
new file mode 100644
index 000000000..5578a5189
--- /dev/null
+++ b/apps/kimi-code/src/tui/reverse-rpc/approval/controller.ts
@@ -0,0 +1,27 @@
+import type { ApprovalResponse } from '@moonshot-ai/kimi-code-sdk';
+
+import { ReverseRpcController } from '#/tui/reverse-rpc/base-controller';
+import type { ApprovalPanelData } from '#/tui/reverse-rpc/types';
+
+export class ApprovalController extends ReverseRpcController<
+  ApprovalPanelData,
+  ApprovalResponse
+> {
+  protected createCancelResponse(reason: string): ApprovalResponse {
+    return { decision: 'cancelled', feedback: reason };
+  }
+
+  protected override autoResolveFor(
+    resolvedPayload: ApprovalPanelData,
+    response: ApprovalResponse,
+    queuedPayload: ApprovalPanelData,
+  ): ApprovalResponse | undefined {
+    if (response.decision !== 'approved') return undefined;
+    if (response.scope !== 'session') return undefined;
+    if (resolvedPayload.action !== queuedPayload.action) return undefined;
+    // Inherit the session-scoped approval. Drop `feedback` and
+    // `selectedLabel` — those described the user's interaction with the
+    // first request only and would be misleading on auto-resolved ones.
+    return { decision: 'approved', scope: 'session' };
+  }
+}
diff --git a/apps/kimi-code/src/tui/reverse-rpc/approval/handler.ts b/apps/kimi-code/src/tui/reverse-rpc/approval/handler.ts
new file mode 100644
index 000000000..8640dd5d9
--- /dev/null
+++ b/apps/kimi-code/src/tui/reverse-rpc/approval/handler.ts
@@ -0,0 +1,24 @@
+import type { ApprovalHandler, ApprovalRequest, ApprovalResponse } from '@moonshot-ai/kimi-code-sdk';
+
+import { adaptApprovalRequest } from './adapter';
+import type { ApprovalController } from './controller';
+
+export function createApprovalRequestHandler(
+  controller: ApprovalController,
+  onResponse?: (request: ApprovalRequest, response: ApprovalResponse) => void,
+): ApprovalHandler {
+  return async (event): Promise<ApprovalResponse> => {
+    try {
+      const response = await controller.show(adaptApprovalRequest(event));
+      onResponse?.(event, response);
+      return response;
+    } catch {
+      const response: ApprovalResponse = {
+        decision: 'cancelled',
+        feedback: 'approval handler failed',
+      };
+      onResponse?.(event, response);
+      return response;
+    }
+  };
+}
diff --git a/apps/kimi-code/src/tui/reverse-rpc/base-controller.ts b/apps/kimi-code/src/tui/reverse-rpc/base-controller.ts
new file mode 100644
index 000000000..a32dcb047
--- /dev/null
+++ b/apps/kimi-code/src/tui/reverse-rpc/base-controller.ts
@@ -0,0 +1,111 @@
+/**
+ * Base class for promise-based reverse RPC dialog controllers.
+ *
+ * Approval and question flows wait for a UI action before returning a response.
+ * Subclasses only need to define the default cancellation response.
+ *
+ * When concurrent requests arrive (e.g. multiple parallel subagents each
+ * needing approval), only one panel is shown at a time; additional requests
+ * are queued in arrival order and advance after the current one resolves.
+ */
+
+export interface ReverseRpcUIHooks<TPayload> {
+  showPanel(payload: TPayload): void;
+  hidePanel(): void;
+}
+
+interface Pending<TPayload, TResponse> {
+  readonly payload: TPayload;
+  readonly resolve: (data: TResponse) => void;
+}
+
+export abstract class ReverseRpcController<TPayload, TResponse> {
+  private uiHooks: ReverseRpcUIHooks<TPayload> | null = null;
+  private current: Pending<TPayload, TResponse> | null = null;
+  private queue: Array<Pending<TPayload, TResponse>> = [];
+
+  setUIHooks(hooks: ReverseRpcUIHooks<TPayload>): void {
+    this.uiHooks = hooks;
+  }
+
+  /**
+   * Called when a reverse RPC request arrives from core. The returned promise
+   * resolves after the user responds or `cancelAll` forces cancellation.
+   */
+  show(payload: TPayload): Promise<TResponse> {
+    return new Promise<TResponse>((resolve) => {
+      const entry: Pending<TPayload, TResponse> = { payload, resolve };
+      if (this.current === null) {
+        this.current = entry;
+        this.uiHooks?.showPanel(payload);
+      } else {
+        this.queue.push(entry);
+      }
+    });
+  }
+
+  /** Called by the UI after the user makes a panel choice. */
+  respond(data: TResponse): void {
+    const pending = this.current;
+    this.current = null;
+    pending?.resolve(data);
+    if (pending !== null) {
+      this.drainAutoResolved(pending.payload, data);
+    }
+    this.advanceOrHide();
+  }
+
+  /** Cancels all pending requests during shutdown or session switches. */
+  cancelAll(reason: string): void {
+    const all = [...(this.current === null ? [] : [this.current]), ...this.queue];
+    this.current = null;
+    this.queue = [];
+    this.uiHooks?.hidePanel();
+    for (const entry of all) {
+      entry.resolve(this.createCancelResponse(reason));
+    }
+  }
+
+  hasPending(): boolean {
+    return this.current !== null || this.queue.length > 0;
+  }
+
+  private advanceOrHide(): void {
+    const next = this.queue.shift();
+    if (next === undefined) {
+      this.uiHooks?.hidePanel();
+      return;
+    }
+    this.current = next;
+    this.uiHooks?.showPanel(next.payload);
+  }
+
+  private drainAutoResolved(resolvedPayload: TPayload, response: TResponse): void {
+    const remaining: Array<Pending<TPayload, TResponse>> = [];
+    for (const entry of this.queue) {
+      const auto = this.autoResolveFor(resolvedPayload, response, entry.payload);
+      if (auto === undefined) {
+        remaining.push(entry);
+      } else {
+        entry.resolve(auto);
+      }
+    }
+    this.queue = remaining;
+  }
+
+  /**
+   * Subclasses override to short-circuit queued requests when an answer to the
+   * just-resolved one (e.g. an approve-for-session) implies the same answer
+   * for matching queued requests. Return `undefined` to leave the queued
+   * request waiting for its own panel turn.
+   */
+  protected autoResolveFor(
+    _resolvedPayload: TPayload,
+    _response: TResponse,
+    _queuedPayload: TPayload,
+  ): TResponse | undefined {
+    return undefined;
+  }
+
+  protected abstract createCancelResponse(reason: string): TResponse;
+}
diff --git a/apps/kimi-code/src/tui/reverse-rpc/index.ts b/apps/kimi-code/src/tui/reverse-rpc/index.ts
new file mode 100644
index 000000000..3a00ae889
--- /dev/null
+++ b/apps/kimi-code/src/tui/reverse-rpc/index.ts
@@ -0,0 +1,44 @@
+import type { ApprovalController } from './approval/controller';
+import type { QuestionController } from './question/controller';
+import { ReverseRpcModalCoordinator } from './modal-coordinator';
+import type { ApprovalPanelData, QuestionPanelData } from './types';
+
+export interface ReverseRPCUIHooks {
+  readonly showApprovalPanel: (payload: ApprovalPanelData) => void;
+  readonly hideApprovalPanel: () => void;
+  readonly showQuestionDialog: (payload: QuestionPanelData) => void;
+  readonly hideQuestionDialog: () => void;
+}
+
+export function registerReverseRPCHandlers(
+  approvalController: ApprovalController,
+  questionController: QuestionController,
+  uiHooks: ReverseRPCUIHooks,
+): Array<() => void> {
+  const modalCoordinator = new ReverseRpcModalCoordinator(uiHooks);
+
+  // Setup UI hooks for controllers
+  approvalController.setUIHooks({
+    showPanel: (payload) => {
+      modalCoordinator.showApproval(payload);
+    },
+    hidePanel: () => {
+      modalCoordinator.hide('approval');
+    },
+  });
+
+  questionController.setUIHooks({
+    showPanel: (payload) => {
+      modalCoordinator.showQuestion(payload);
+    },
+    hidePanel: () => {
+      modalCoordinator.hide('question');
+    },
+  });
+
+  return [
+    () => {
+      modalCoordinator.clear();
+    },
+  ];
+}
diff --git a/apps/kimi-code/src/tui/reverse-rpc/modal-coordinator.ts b/apps/kimi-code/src/tui/reverse-rpc/modal-coordinator.ts
new file mode 100644
index 000000000..623ec761a
--- /dev/null
+++ b/apps/kimi-code/src/tui/reverse-rpc/modal-coordinator.ts
@@ -0,0 +1,97 @@
+import type { ApprovalPanelData, QuestionPanelData } from './types';
+
+export type ReverseRpcModalOwner = 'approval' | 'question';
+
+export interface ReverseRpcModalUIHooks {
+  readonly showApprovalPanel: (payload: ApprovalPanelData) => void;
+  readonly hideApprovalPanel: () => void;
+  readonly showQuestionDialog: (payload: QuestionPanelData) => void;
+  readonly hideQuestionDialog: () => void;
+}
+
+interface ReverseRpcModalEntry {
+  readonly owner: ReverseRpcModalOwner;
+  readonly show: () => void;
+  readonly hide: () => void;
+}
+
+export class ReverseRpcModalCoordinator {
+  private active: ReverseRpcModalEntry | null = null;
+  private readonly queued: ReverseRpcModalEntry[] = [];
+
+  constructor(private readonly hooks: ReverseRpcModalUIHooks) {}
+
+  showApproval(payload: ApprovalPanelData): void {
+    this.show({
+      owner: 'approval',
+      show: () => {
+        this.hooks.showApprovalPanel(payload);
+      },
+      hide: () => {
+        this.hooks.hideApprovalPanel();
+      },
+    });
+  }
+
+  showQuestion(payload: QuestionPanelData): void {
+    this.show({
+      owner: 'question',
+      show: () => {
+        this.hooks.showQuestionDialog(payload);
+      },
+      hide: () => {
+        this.hooks.hideQuestionDialog();
+      },
+    });
+  }
+
+  hide(owner: ReverseRpcModalOwner): void {
+    if (this.active?.owner === owner) {
+      const active = this.active;
+      this.active = null;
+      active.hide();
+      this.showNext();
+      return;
+    }
+
+    const queuedIndex = this.queued.findIndex((entry) => entry.owner === owner);
+    if (queuedIndex >= 0) this.queued.splice(queuedIndex, 1);
+  }
+
+  clear(): void {
+    const active = this.active;
+    this.active = null;
+    this.queued.length = 0;
+    active?.hide();
+  }
+
+  private show(entry: ReverseRpcModalEntry): void {
+    const active = this.active;
+    if (active === null) {
+      this.active = entry;
+      entry.show();
+      return;
+    }
+
+    if (active.owner === entry.owner) {
+      this.active = entry;
+      entry.show();
+      return;
+    }
+
+    const queuedIndex = this.queued.findIndex((queued) => queued.owner === entry.owner);
+    if (queuedIndex >= 0) {
+      this.queued[queuedIndex] = entry;
+      return;
+    }
+
+    this.queued.push(entry);
+  }
+
+  private showNext(): void {
+    const next = this.queued.shift();
+    if (next === undefined) return;
+    this.active = next;
+    next.show();
+  }
+}
diff --git a/apps/kimi-code/src/tui/reverse-rpc/question/controller.ts b/apps/kimi-code/src/tui/reverse-rpc/question/controller.ts
new file mode 100644
index 000000000..a87c24daf
--- /dev/null
+++ b/apps/kimi-code/src/tui/reverse-rpc/question/controller.ts
@@ -0,0 +1,11 @@
+import { ReverseRpcController } from '#/tui/reverse-rpc/base-controller';
+import type { QuestionPanelData, QuestionPanelResponse } from '#/tui/reverse-rpc/types';
+
+export class QuestionController extends ReverseRpcController<
+  QuestionPanelData,
+  QuestionPanelResponse
+> {
+  protected createCancelResponse(_reason: string): QuestionPanelResponse {
+    return { answers: [] };
+  }
+}
diff --git a/apps/kimi-code/src/tui/reverse-rpc/question/handler.ts b/apps/kimi-code/src/tui/reverse-rpc/question/handler.ts
new file mode 100644
index 000000000..3bf564b02
--- /dev/null
+++ b/apps/kimi-code/src/tui/reverse-rpc/question/handler.ts
@@ -0,0 +1,57 @@
+import type { QuestionHandler, QuestionRequest, QuestionResult } from '@moonshot-ai/kimi-code-sdk';
+
+import type {
+  QuestionPanelData,
+  QuestionPanelResponse,
+} from '#/tui/reverse-rpc/types';
+
+import type { QuestionController } from './controller';
+
+export function createQuestionAskHandler(controller: QuestionController): QuestionHandler {
+  return async (event): Promise<QuestionResult> => {
+    try {
+      const answers = await controller.show(adaptQuestionRequest(event));
+      return adaptQuestionAnswers(event, answers);
+    } catch {
+      return null;
+    }
+  };
+}
+
+export function adaptQuestionRequest(event: QuestionRequest): QuestionPanelData {
+  const id =
+    event.toolCallId ??
+    (event.turnId === undefined ? 'question' : `question-${String(event.turnId)}`);
+  return {
+    id,
+    tool_call_id: id,
+    questions: event.questions.map((question) => ({
+      question: question.question,
+      header: question.header,
+      body: question.body,
+      multi_select: question.multiSelect ?? false,
+      other_label: question.otherLabel,
+      other_description: question.otherDescription,
+      options: question.options.map((option) => ({
+        label: option.label,
+        description: option.description,
+      })),
+    })),
+  };
+}
+
+export function adaptQuestionAnswers(
+  event: QuestionRequest,
+  response: QuestionPanelResponse,
+): QuestionResult {
+  const result: Record<string, string | true> = {};
+  for (let i = 0; i < event.questions.length; i++) {
+    const question = event.questions[i];
+    const answer = response.answers[i];
+    if (question === undefined || typeof answer !== 'string' || answer.length === 0) continue;
+    result[question.question] = answer;
+  }
+  return Object.keys(result).length > 0
+    ? { answers: result, method: response.method }
+    : null;
+}
diff --git a/apps/kimi-code/src/tui/reverse-rpc/types.ts b/apps/kimi-code/src/tui/reverse-rpc/types.ts
new file mode 100644
index 000000000..c23c938f0
--- /dev/null
+++ b/apps/kimi-code/src/tui/reverse-rpc/types.ts
@@ -0,0 +1,151 @@
+/**
+ * Reverse RPC view-layer types.
+ *
+ * These types are the contract between the UI layer and reverse RPC
+ * controllers, not SDK event payloads. Approval and question adapters convert
+ * core payloads into these shapes for panel components.
+ */
+
+import type { QuestionAnswerMethod } from '@moonshot-ai/kimi-code-sdk';
+
+// ── Display blocks (approval panel) ──────────────────────────────────
+
+export interface BriefDisplayBlock {
+  type: 'brief';
+  text: string;
+}
+
+export interface DiffDisplayBlock {
+  type: 'diff';
+  path: string;
+  old_text: string;
+  new_text: string;
+  old_start?: number | undefined;
+  new_start?: number | undefined;
+  is_summary?: boolean | undefined;
+}
+
+export interface ShellDisplayBlock {
+  type: 'shell';
+  language: string;
+  command: string;
+  cwd?: string | undefined;
+  description?: string | undefined;
+  danger?: string | undefined;
+}
+
+export interface FileOpDisplayBlock {
+  type: 'file_op';
+  operation: 'read' | 'write' | 'edit' | 'glob' | 'grep';
+  path: string;
+  detail?: string | undefined;
+}
+
+/** Full file content preview for Write — a code block, not a diff. */
+export interface FileContentDisplayBlock {
+  type: 'file_content';
+  path: string;
+  content: string;
+  language?: string | undefined;
+}
+
+export interface UrlFetchDisplayBlock {
+  type: 'url_fetch';
+  url: string;
+  method?: string | undefined;
+}
+
+export interface SearchDisplayBlock {
+  type: 'search';
+  query: string;
+  scope?: string | undefined;
+}
+
+export interface InvocationDisplayBlock {
+  type: 'invocation';
+  kind: 'agent' | 'skill';
+  name: string;
+  description?: string | undefined;
+}
+
+export interface TodoDisplayItem {
+  title: string;
+  status: 'pending' | 'in_progress' | 'done';
+}
+
+export interface TodoDisplayBlock {
+  type: 'todo';
+  items: TodoDisplayItem[];
+}
+
+export interface BackgroundTaskDisplayBlock {
+  type: 'background_task';
+  task_id: string;
+  kind: string;
+  status: string;
+  description: string;
+}
+
+export type DisplayBlock =
+  | BriefDisplayBlock
+  | DiffDisplayBlock
+  | ShellDisplayBlock
+  | FileOpDisplayBlock
+  | FileContentDisplayBlock
+  | UrlFetchDisplayBlock
+  | SearchDisplayBlock
+  | InvocationDisplayBlock
+  | TodoDisplayBlock
+  | BackgroundTaskDisplayBlock;
+
+export interface ApprovalPanelChoice {
+  label: string;
+  response: 'approved' | 'approved_for_session' | 'rejected' | 'cancelled';
+  selected_label?: string | undefined;
+  requires_feedback?: boolean | undefined;
+}
+
+// ── Approval / Question view payloads ────────────────────────────────
+
+export interface ApprovalPanelData {
+  id: string;
+  tool_call_id: string;
+  tool_name: string;
+  action: string;
+  description: string;
+  display: DisplayBlock[];
+  choices: ApprovalPanelChoice[];
+}
+
+export interface QuestionPanelItem {
+  question: string;
+  header?: string;
+  body?: string;
+  multi_select: boolean;
+  other_label?: string;
+  other_description?: string;
+  options: Array<{ label: string; description?: string }>;
+}
+
+export interface QuestionPanelData {
+  id: string;
+  tool_call_id: string;
+  questions: QuestionPanelItem[];
+}
+
+export type QuestionSubmissionMethod = QuestionAnswerMethod;
+
+export interface QuestionPanelResponse {
+  readonly answers: string[];
+  readonly method?: QuestionSubmissionMethod | undefined;
+}
+
+// ── Pending state wrappers ───────────────────────────────────────────
+
+export interface PendingApproval {
+  data: ApprovalPanelData;
+}
+
+export interface PendingQuestion {
+  data: QuestionPanelData;
+}
diff --git a/apps/kimi-code/src/tui/theme/bundle.ts b/apps/kimi-code/src/tui/theme/bundle.ts
new file mode 100644
index 000000000..8cfd0e921
--- /dev/null
+++ b/apps/kimi-code/src/tui/theme/bundle.ts
@@ -0,0 +1,27 @@
+import type { MarkdownTheme } from '@earendil-works/pi-tui';
+
+import { getColorPalette, type ColorPalette, type ResolvedTheme } from './colors';
+import { createMarkdownTheme } from './pi-tui-theme';
+import { createThemeStyles, type ThemeStyles } from './styles';
+import { resolveThemeSync, type Theme } from './index';
+
+export interface KimiTUIThemeBundle {
+  resolvedTheme: ResolvedTheme;
+  colors: ColorPalette;
+  styles: ThemeStyles;
+  markdownTheme: MarkdownTheme;
+}
+
+export function createKimiTUIThemeBundle(
+  theme: Theme,
+  resolvedTheme?: ResolvedTheme,
+): KimiTUIThemeBundle {
+  const actualTheme = resolvedTheme ?? resolveThemeSync(theme);
+  const colors = { ...getColorPalette(actualTheme) };
+  return {
+    resolvedTheme: actualTheme,
+    colors,
+    styles: createThemeStyles(colors),
+    markdownTheme: createMarkdownTheme(colors),
+  };
+}
diff --git a/apps/kimi-code/src/tui/theme/colors.ts b/apps/kimi-code/src/tui/theme/colors.ts
new file mode 100644
index 000000000..4a9b37bad
--- /dev/null
+++ b/apps/kimi-code/src/tui/theme/colors.ts
@@ -0,0 +1,148 @@
+/**
+ * Color palette definitions for dark and light themes.
+ *
+ * Two layers:
+ *  - private `dark` / `light` raw palettes — unsemantic constants reused
+ *    across multiple semantic tokens to avoid hex literal duplication.
+ *  - exported `darkColors` / `lightColors` — the semantic `ColorPalette`
+ *    consumed by every UI component via chalk.hex(...).
+ *
+ * Light palette values are tuned for ≥ 4.5:1 contrast against #FFFFFF
+ * for text tokens and ≥ 3:1 for chrome (border / large text), matching
+ * WCAG AA.
+ */
+
+const dark = {
+  blue400: '#4FA8FF',
+  cyan400: '#5BC0BE',
+  gray50: '#F5F5F5',
+  gray100: '#E0E0E0',
+  gray500: '#888888',
+  gray600: '#6B6B6B',
+  gray700: '#5A5A5A',
+  green400: '#4EC87E',
+  green300: '#7AD99B',
+  red400: '#E85454',
+  red300: '#F08585',
+  amber400: '#E8A838',
+  orange300: '#FFCB6B',
+} as const;
+
+const light = {
+  blue600: '#1565C0',
+  cyan700: '#00838F',
+  gray900: '#1A1A1A',
+  gray700: '#454545',
+  gray600: '#5F5F5F',
+  gray500: '#737373',
+  green700: '#0E7A38',
+  red700: '#B91C1C',
+  amber800: '#92660A',
+  orange700: '#9A4A00',
+} as const;
+
+export interface ColorPalette {
+  // Brand
+  primary: string;
+  accent: string;
+
+  // Text
+  text: string;
+  textStrong: string;
+  textDim: string;
+  textMuted: string;
+
+  // Surface
+  border: string;
+  borderFocus: string;
+
+  // State
+  success: string;
+  warning: string;
+  error: string;
+
+  // Diff
+  diffAdded: string;
+  diffRemoved: string;
+  diffAddedStrong: string;
+  diffRemovedStrong: string;
+  diffGutter: string;
+  diffMeta: string;
+
+  // Roles
+  roleUser: string;
+  roleAssistant: string;
+  roleThinking: string;
+  roleTool: string;
+
+  // Status
+  status: string;
+}
+
+export const darkColors: ColorPalette = {
+  primary: dark.blue400,
+  accent: dark.cyan400,
+
+  text: dark.gray100,
+  textStrong: dark.gray50,
+  textDim: dark.gray500,
+  textMuted: dark.gray600,
+
+  border: dark.gray700,
+  borderFocus: dark.amber400,
+
+  success: dark.green400,
+  warning: dark.amber400,
+  error: dark.red400,
+
+  diffAdded: dark.green400,
+  diffRemoved: dark.red400,
+  diffAddedStrong: dark.green300,
+  diffRemovedStrong: dark.red300,
+  diffGutter: dark.gray600,
+  diffMeta: dark.gray500,
+
+  roleUser: dark.orange300,
+  roleAssistant: dark.gray100,
+  roleThinking: dark.gray500,
+  roleTool: dark.amber400,
+
+  status: dark.gray500,
+};
+
+export const lightColors: ColorPalette = {
+  primary: light.blue600,
+  accent: light.cyan700,
+
+  text: light.gray900,
+  textStrong: light.gray900,
+  textDim: light.gray700,
+  textMuted: light.gray600,
+
+  border: light.gray500,
+  borderFocus: light.amber800,
+
+  success: light.green700,
+  warning: light.amber800,
+  error: light.red700,
+
+  diffAdded: light.green700,
+  diffRemoved: light.red700,
+  diffAddedStrong: light.green700,
+  diffRemovedStrong: light.red700,
+  diffGutter: light.gray500,
+  diffMeta: light.gray600,
+
+  roleUser: light.orange700,
+  roleAssistant: light.gray900,
+  roleThinking: light.gray700,
+  roleTool: light.amber800,
+
+  status: light.gray700,
+};
+
+export type ResolvedTheme = 'dark' | 'light';
+
+export function getColorPalette(theme: ResolvedTheme): ColorPalette {
+  return theme === 'dark' ? darkColors : lightColors;
+}
diff --git a/apps/kimi-code/src/tui/theme/detect.ts b/apps/kimi-code/src/tui/theme/detect.ts
new file mode 100644
index 000000000..0f4d40953
--- /dev/null
+++ b/apps/kimi-code/src/tui/theme/detect.ts
@@ -0,0 +1,121 @@
+/**
+ * Terminal background detection.
+ *
+ * Strategy, in priority order:
+ *   1. Reject — non-TTY, NO_COLOR, FORCE_COLOR=0, CI → safe `'dark'`.
+ *   2. OSC 11 — write `ESC ] 11 ; ? BEL`, parse `ESC ] 11 ; rgb:RR/GG/BB BEL`,
+ *      compute relative luminance. Capped at `timeoutMs` so unsupported
+ *      terminals don't hang.
+ *   3. COLORFGBG — VT100 / xterm fallback exposing `"fg;bg"`.
+ *   4. Default — `'dark'`.
+ *
+ * Must run before pi-tui enters raw mode; once the framework owns stdin
+ * the OSC reply gets eaten by the input loop.
+ */
+
+import { OSC11_QUERY, TERMINAL_THEME_DETECT_TIMEOUT_MS } from "#/tui/constant/terminal";
+
+import type { ResolvedTheme } from "./colors";
+import { parseOsc11BackgroundTheme } from "./terminal-background";
+
+export interface DetectOptions {
+  readonly timeoutMs?: number;
+}
+
+export async function detectTerminalTheme(opts: DetectOptions = {}): Promise<ResolvedTheme> {
+  if (!isInteractiveTerminal()) return "dark";
+  if (isColorOptOut()) return "dark";
+
+  const fromOsc = await queryOsc11({
+    timeoutMs: opts.timeoutMs ?? TERMINAL_THEME_DETECT_TIMEOUT_MS,
+  });
+  if (fromOsc !== null) return fromOsc;
+
+  const fromColorFgBg = parseColorFgBg(process.env["COLORFGBG"]);
+  if (fromColorFgBg !== null) return fromColorFgBg;
+
+  return "dark";
+}
+
+function isInteractiveTerminal(): boolean {
+  return (process.stdin.isTTY ?? false) && (process.stdout.isTTY ?? false);
+}
+
+function isColorOptOut(): boolean {
+  const env = process.env;
+  if (env["NO_COLOR"] !== undefined && env["NO_COLOR"] !== "") return true;
+  if (env["FORCE_COLOR"] === "0") return true;
+  if (env["CI"] !== undefined && env["CI"] !== "" && env["CI"] !== "0") return true;
+  return false;
+}
+
+interface RawModeStdin {
+  isRaw?: boolean;
+  setRawMode(mode: boolean): NodeJS.ReadStream;
+  on(event: "data", listener: (data: Buffer) => void): NodeJS.ReadStream;
+  off(event: "data", listener: (data: Buffer) => void): NodeJS.ReadStream;
+}
+
+async function queryOsc11(opts: { timeoutMs: number }): Promise<ResolvedTheme | null> {
+  const stdin = process.stdin as unknown as RawModeStdin;
+  if (typeof stdin.setRawMode !== "function") return null;
+  // If something else is already listening on stdin (e.g. another raw-mode
+  // consumer), don't fight for it — punt to COLORFGBG instead.
+  if (process.stdin.listenerCount("data") > 0) return null;
+
+  const wasRaw = stdin.isRaw === true;
+  let buffer = "";
+  let listener: ((data: Buffer) => void) | null = null;
+  let timer: NodeJS.Timeout | null = null;
+
+  try {
+    if (!wasRaw) stdin.setRawMode(true);
+
+    const result = await new Promise<ResolvedTheme | null>((resolve) => {
+      listener = (chunk: Buffer): void => {
+        buffer += chunk.toString("utf8");
+        const theme = parseOsc11BackgroundTheme(buffer);
+        if (theme !== null) resolve(theme);
+      };
+      stdin.on("data", listener);
+      timer = setTimeout(() => {
+        resolve(null);
+      }, opts.timeoutMs);
+      try {
+        process.stdout.write(OSC11_QUERY);
+      } catch {
+        resolve(null);
+      }
+    });
+
+    return result;
+  } catch {
+    return null;
+  } finally {
+    if (timer !== null) clearTimeout(timer);
+    if (listener !== null) stdin.off("data", listener);
+    if (!wasRaw) {
+      try {
+        stdin.setRawMode(false);
+      } catch {
+        /* ignore — raw mode restoration best-effort */
+      }
+    }
+  }
+}
+
+/**
+ * COLORFGBG is `"fg;bg"` (sometimes `"fg;default;bg"`). The last token is
+ * the background ANSI 16-color index; 0–6 and 8 are dark, the rest light.
+ */
+export function parseColorFgBg(value: string | undefined): ResolvedTheme | null {
+  if (value === undefined || value === "") return null;
+  const parts = value.split(";");
+  const bgRaw = parts.at(-1);
+  if (bgRaw === undefined) return null;
+  const bg = parseInt(bgRaw, 10);
+  if (!Number.isInteger(bg)) return null;
+  // ANSI 0=black, 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 8=bright black.
+  const darkBgs = new Set([0, 1, 2, 3, 4, 5, 6, 8]);
+  return darkBgs.has(bg) ? "dark" : "light";
+}
diff --git a/apps/kimi-code/src/tui/theme/index.ts b/apps/kimi-code/src/tui/theme/index.ts
new file mode 100644
index 000000000..a9a143633
--- /dev/null
+++ b/apps/kimi-code/src/tui/theme/index.ts
@@ -0,0 +1,46 @@
+/**
+ * Theme system public API.
+ */
+
+import type { ResolvedTheme } from './colors';
+import { detectTerminalTheme } from './detect';
+
+export { darkColors, lightColors, getColorPalette } from './colors';
+export type { ColorPalette, ResolvedTheme } from './colors';
+export { createThemeStyles } from './styles';
+export type { ThemeStyles } from './styles';
+export { createMarkdownTheme, createEditorTheme } from './pi-tui-theme';
+export { detectTerminalTheme } from './detect';
+
+/**
+ * User-facing theme preference. `'auto'` defers to terminal background
+ * detection at startup; `'dark'` / `'light'` are explicit overrides that
+ * never trigger detection. The persisted value in `tui.toml` is always
+ * one of these three; the detected `ResolvedTheme` is computed at
+ * startup and held only in memory.
+ */
+export type Theme = 'dark' | 'light' | 'auto';
+
+export function isTheme(value: string): value is Theme {
+  return value === 'dark' || value === 'light' || value === 'auto';
+}
+
+/**
+ * Resolve a user preference to a concrete palette key. `'auto'` triggers
+ * terminal background detection (OSC 11 with COLORFGBG / dark fallback);
+ * explicit choices pass through.
+ */
+export async function resolveTheme(theme: Theme): Promise<ResolvedTheme> {
+  if (theme === 'auto') return detectTerminalTheme();
+  return theme;
+}
+
+/**
+ * Synchronous fallback used by paths that cannot wait on terminal probes
+ * (initial state construction, in-TUI theme switches). `'auto'` collapses
+ * to `'dark'`; explicit choices pass through.
+ */
+export function resolveThemeSync(theme: Theme): ResolvedTheme {
+  if (theme === 'auto') return 'dark';
+  return theme;
+}
diff --git a/apps/kimi-code/src/tui/theme/pi-tui-theme.ts b/apps/kimi-code/src/tui/theme/pi-tui-theme.ts
new file mode 100644
index 000000000..dc3b1b9ad
--- /dev/null
+++ b/apps/kimi-code/src/tui/theme/pi-tui-theme.ts
@@ -0,0 +1,71 @@
+/**
+ * Pi-tui theme adapters — MarkdownTheme and EditorTheme from our ColorPalette.
+ *
+ * All chalk calls route through `ColorPalette` tokens so themes flip
+ * cleanly. No raw `chalk.gray` / `chalk.dim` / `chalk.white` here.
+ */
+
+import type { MarkdownTheme, EditorTheme } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+import { highlight, supportsLanguage } from 'cli-highlight';
+
+import type { ColorPalette } from './colors';
+
+// pi-tui's renderer emits literal "### " / "#### " / ... markers for h3-h6
+// headings (h1/h2 are rendered without the `#` prefix). The prefix arrives
+// here already wrapped in bold SGR codes, so we strip it — after any leading
+// ANSI sequences — before re-styling. Without this, h3+ renders as raw
+// "### Title" and reads like unparsed markdown.
+// eslint-disable-next-line no-control-regex -- intentionally matches the ESC byte that opens ANSI SGR sequences.
+const HEADING_HASH_PREFIX = /^((?:\u001B\[[0-9;]*m)*)#{1,6}[ \t]+/;
+
+export function createMarkdownTheme(colors: ColorPalette): MarkdownTheme {
+  const stripHash = (text: string): string => text.replace(HEADING_HASH_PREFIX, '$1');
+  const muted = chalk.hex(colors.textMuted);
+  const dim = chalk.hex(colors.textDim);
+  const border = chalk.hex(colors.border);
+  return {
+    heading: (text) => chalk.bold.hex(colors.text)(stripHash(text)),
+    link: (text) => chalk.hex(colors.primary)(text),
+    linkUrl: (text) => muted(text),
+    code: (text) => chalk.hex(colors.primary)(text),
+    codeBlock: (text) => text,
+    codeBlockBorder: (text) => muted(text),
+    quote: (text) => dim(text),
+    quoteBorder: (text) => dim(text),
+    hr: (text) => border(text),
+    // Match the assistant-message bullet so list markers read like a reply
+    // prefix. Ordered lists arrive as `"1. "` / `"2. "` and are left
+    // untouched by the leading-dash anchor.
+    listBullet: (text) => chalk.hex(colors.roleAssistant)(text.replace(/^-/, '•')),
+    bold: (text) => chalk.bold(text),
+    italic: (text) => chalk.italic(text),
+    strikethrough: (text) => chalk.strikethrough(text),
+    underline: (text) => chalk.underline(text),
+    highlightCode: (code: string, lang?: string) => {
+      const normalizedLang = lang?.trim().toLowerCase();
+      const language =
+        normalizedLang !== undefined && supportsLanguage(normalizedLang) ? normalizedLang : 'text';
+      try {
+        const highlighted = highlight(code, { language, ignoreIllegals: true });
+        return highlighted.split('\n');
+      } catch {
+        return code.split('\n');
+      }
+    },
+  };
+}
+
+export function createEditorTheme(colors: ColorPalette): EditorTheme {
+  const muted = chalk.hex(colors.textMuted);
+  return {
+    borderColor: (s) => chalk.hex(colors.border)(s),
+    selectList: {
+      selectedPrefix: (s) => chalk.hex(colors.primary)(s),
+      selectedText: (s) => chalk.hex(colors.primary)(s),
+      description: (s) => muted(s),
+      scrollInfo: (s) => muted(s),
+      noMatch: (s) => muted(s),
+    },
+  };
+}
diff --git a/apps/kimi-code/src/tui/theme/styles.ts b/apps/kimi-code/src/tui/theme/styles.ts
new file mode 100644
index 000000000..625302e45
--- /dev/null
+++ b/apps/kimi-code/src/tui/theme/styles.ts
@@ -0,0 +1,66 @@
+/**
+ * Theme-aware style helpers built on chalk. Components hold a reference
+ * to a `ThemeStyles` instance via `state.theme.styles` and never reach into
+ * raw chalk color names — that keeps theme switches consistent and lets
+ * every visual token route through `ColorPalette`.
+ */
+
+import chalk from 'chalk';
+
+import type { ColorPalette } from './colors';
+
+export interface ThemeStyles {
+  colors: ColorPalette;
+
+  /** Brand primary (links, focus, slash highlight). */
+  primary(text: string): string;
+  /** Secondary brand accent (command operators, approval labels). */
+  accent(text: string): string;
+  /** Dimmed text — secondary but still readable. */
+  dim(text: string): string;
+  /** Muted text — most faded; for unchanged-line counters, scroll info. */
+  muted(text: string): string;
+  /** Body text — same color as default but explicit for theming. */
+  text(text: string): string;
+  /** Strong / emphasized text — paths, URLs, command bodies. */
+  strong(text: string): string;
+
+  error(text: string): string;
+  warning(text: string): string;
+  success(text: string): string;
+
+  /** Bold + dim, for label cells. */
+  label(text: string): string;
+  /** Body color, for value cells. */
+  value(text: string): string;
+
+  diffAdd(text: string): string;
+  diffDel(text: string): string;
+  diffAddBold(text: string): string;
+  diffDelBold(text: string): string;
+  diffGutter(text: string): string;
+  diffMeta(text: string): string;
+}
+
+export function createThemeStyles(colors: ColorPalette): ThemeStyles {
+  return {
+    colors,
+    primary: (s) => chalk.hex(colors.primary)(s),
+    accent: (s) => chalk.hex(colors.accent)(s),
+    dim: (s) => chalk.hex(colors.textDim)(s),
+    muted: (s) => chalk.hex(colors.textMuted)(s),
+    text: (s) => chalk.hex(colors.text)(s),
+    strong: (s) => chalk.hex(colors.textStrong)(s),
+    error: (s) => chalk.hex(colors.error)(s),
+    warning: (s) => chalk.hex(colors.warning)(s),
+    success: (s) => chalk.hex(colors.success)(s),
+    label: (s) => chalk.bold.hex(colors.textDim)(s),
+    value: (s) => chalk.hex(colors.text)(s),
+    diffAdd: (s) => chalk.hex(colors.diffAdded)(s),
+    diffDel: (s) => chalk.hex(colors.diffRemoved)(s),
+    diffAddBold: (s) => chalk.bold.hex(colors.diffAddedStrong)(s),
+    diffDelBold: (s) => chalk.bold.hex(colors.diffRemovedStrong)(s),
+    diffGutter: (s) => chalk.hex(colors.diffGutter)(s),
+    diffMeta: (s) => chalk.hex(colors.diffMeta)(s),
+  };
+}
diff --git a/apps/kimi-code/src/tui/theme/terminal-background.ts b/apps/kimi-code/src/tui/theme/terminal-background.ts
new file mode 100644
index 000000000..ba9803fdb
--- /dev/null
+++ b/apps/kimi-code/src/tui/theme/terminal-background.ts
@@ -0,0 +1,28 @@
+import { OSC11_RESPONSE } from "#/tui/constant/terminal";
+
+import type { ResolvedTheme } from "./colors";
+
+export function parseOsc11BackgroundTheme(data: string): ResolvedTheme | null {
+  const match = OSC11_RESPONSE.exec(data);
+  if (match === null) return null;
+  const [, r, g, b] = match;
+  if (r === undefined || g === undefined || b === undefined) return null;
+  return themeFromHexChannels(r, g, b);
+}
+
+export function themeFromHexChannels(rHex: string, gHex: string, bHex: string): ResolvedTheme {
+  const r = normalizeChannel(rHex);
+  const g = normalizeChannel(gHex);
+  const b = normalizeChannel(bHex);
+  // Relative luminance, sRGB-linearised. Threshold 0.5 splits dark/light
+  // backgrounds reliably for both pure-black (#000) and pure-white (#fff).
+  const luma = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  return luma > 0.5 ? "light" : "dark";
+}
+
+function normalizeChannel(hex: string): number {
+  // OSC 11 channels can be 1-4 hex digits. Scale into [0,1] regardless.
+  const max = (1 << (hex.length * 4)) - 1;
+  const value = parseInt(hex, 16);
+  return Number.isFinite(value) ? value / max : 0;
+}
diff --git a/apps/kimi-code/src/tui/types.ts b/apps/kimi-code/src/tui/types.ts
new file mode 100644
index 000000000..16be35503
--- /dev/null
+++ b/apps/kimi-code/src/tui/types.ts
@@ -0,0 +1,149 @@
+import type {
+  ModelAlias,
+  PermissionMode,
+  ProviderConfig,
+  PromptPart,
+  ToolInputDisplay,
+} from '@moonshot-ai/kimi-code-sdk';
+
+import type { NotificationsConfig } from './config';
+import type { PendingApproval, PendingQuestion } from './reverse-rpc/types';
+import type { Theme } from './theme';
+
+export interface AppState {
+  model: string;
+  workDir: string;
+  sessionId: string;
+  yolo: boolean;
+  permissionMode: PermissionMode;
+  planMode: boolean;
+  thinking: boolean;
+  contextUsage: number;
+  contextTokens: number;
+  maxContextTokens: number;
+  isStreaming: boolean;
+  isCompacting: boolean;
+  isReplaying: boolean;
+  streamingPhase: 'idle' | 'waiting' | 'thinking' | 'composing';
+  streamingStartTime: number;
+  theme: Theme;
+  version: string;
+  editorCommand: string | null;
+  notifications: NotificationsConfig;
+  availableModels: Record<string, ModelAlias>;
+  availableProviders: Record<string, ProviderConfig>;
+  sessionTitle: string | null;
+}
+
+export interface ToolCallBlockData {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+  description?: string;
+  display?: ToolInputDisplay;
+  streamingArguments?: string;
+  streamingStartedAtMs?: number;
+  result?: ToolResultBlockData;
+  subagent?: SubagentReplayBlockData;
+  step?: number;
+  turnId?: string;
+  /** Set when the step ended (e.g. max_tokens) before the tool call's
+   *  arguments finished streaming. Renderer flips the header verb to
+   *  "Truncated" and stops showing the in-progress argument preview. */
+  truncated?: boolean;
+}
+
+export interface ToolResultBlockData {
+  tool_call_id: string;
+  output: string;
+  is_error?: boolean;
+  synthetic?: boolean;
+}
+
+export interface SubagentReplayToolCallData {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+  description?: string;
+  result?: ToolResultBlockData;
+}
+
+export interface SubagentReplayBlockData {
+  id: string;
+  name?: string;
+  text?: string;
+  toolCalls?: readonly SubagentReplayToolCallData[];
+}
+
+export interface BackgroundAgentMetadata {
+  readonly agentId: string;
+  readonly parentToolCallId: string;
+  readonly agentName?: string;
+  readonly description?: string;
+}
+
+export type BackgroundAgentStatusPhase = 'started' | 'completed' | 'failed';
+
+export interface BackgroundAgentStatusData {
+  readonly phase: BackgroundAgentStatusPhase;
+  readonly headline: string;
+  readonly detail?: string;
+}
+
+export interface CompactionTranscriptData {
+  readonly tokensBefore?: number;
+  readonly tokensAfter?: number;
+  readonly instruction?: string;
+}
+
+export type TranscriptEntryKind =
+  | 'welcome'
+  | 'user'
+  | 'assistant'
+  | 'tool_call'
+  | 'thinking'
+  | 'status'
+  | 'skill_activation';
+
+export interface TranscriptEntry {
+  id: string;
+  kind: TranscriptEntryKind;
+  turnId?: string;
+  renderMode: 'markdown' | 'plain' | 'notice';
+  content: string;
+  color?: string;
+  detail?: string;
+  toolCallData?: ToolCallBlockData;
+  backgroundAgentStatus?: BackgroundAgentStatusData;
+  compactionData?: CompactionTranscriptData;
+  imageAttachmentIds?: readonly number[];
+  skillActivationId?: string;
+  skillName?: string;
+  skillArgs?: string;
+}
+
+export type LivePaneMode =
+  | 'idle'
+  | 'waiting'
+  | 'thinking'
+  | 'tool'
+  | 'session';
+
+export interface LivePaneState {
+  mode: LivePaneMode;
+  pendingApproval: PendingApproval | null;
+  pendingQuestion: PendingQuestion | null;
+}
+
+export interface QueuedMessage {
+  readonly text: string;
+  readonly agentId?: string;
+  readonly parts?: readonly PromptPart[];
+  readonly imageAttachmentIds?: readonly number[];
+}
+
+export const INITIAL_LIVE_PANE: LivePaneState = {
+  mode: 'idle',
+  pendingApproval: null,
+  pendingQuestion: null,
+};
diff --git a/apps/kimi-code/src/tui/utils/background-agent-status.ts b/apps/kimi-code/src/tui/utils/background-agent-status.ts
new file mode 100644
index 000000000..a54257a97
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/background-agent-status.ts
@@ -0,0 +1,40 @@
+import type {
+  BackgroundAgentMetadata,
+  BackgroundAgentStatusData,
+  BackgroundAgentStatusPhase,
+} from '#/tui/types';
+
+const MAX_BACKGROUND_FIELD_LENGTH = 240;
+
+function normalizeBackgroundField(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const collapsed = value.trim().replaceAll(/\s+/g, ' ');
+  if (collapsed.length === 0) return undefined;
+  if (collapsed.length <= MAX_BACKGROUND_FIELD_LENGTH) return collapsed;
+  return `${collapsed.slice(0, MAX_BACKGROUND_FIELD_LENGTH - 3)}...`;
+}
+
+export function formatBackgroundAgentTranscript(
+  phase: BackgroundAgentStatusPhase,
+  meta: BackgroundAgentMetadata,
+  extras: { resultSummary?: string; error?: string } | undefined = undefined,
+): BackgroundAgentStatusData {
+  const normalizedAgentName = normalizeBackgroundField(meta.agentName);
+  const subject = normalizedAgentName !== undefined ? `${normalizedAgentName} agent` : 'agent';
+  const headline =
+    phase === 'started'
+      ? `${subject} started in background`
+      : phase === 'completed'
+        ? `${subject} completed in background`
+        : `${subject} failed in background`;
+  const tail = phase === 'failed' ? normalizeBackgroundField(extras?.error) : undefined;
+  const detailParts = [normalizeBackgroundField(meta.description), tail].filter(
+    (part): part is string => part !== undefined,
+  );
+
+  return {
+    phase,
+    headline,
+    detail: detailParts.length > 0 ? detailParts.join(' · ') : undefined,
+  };
+}
diff --git a/apps/kimi-code/src/tui/utils/background-task-status.ts b/apps/kimi-code/src/tui/utils/background-task-status.ts
new file mode 100644
index 000000000..def7a39c5
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/background-task-status.ts
@@ -0,0 +1,104 @@
+/**
+ * Format a `BackgroundTaskInfo` snapshot into the transcript card data
+ * consumed by `BackgroundAgentStatusComponent`.
+ *
+ * Background tasks have six statuses (running / awaiting_approval /
+ * completed / failed / killed / lost) but the transcript card only
+ * renders three visual phases (started / completed / failed). The
+ * mapping packs the extra nuance — exit code, kill reason, lost-reason
+ * — into the dim detail line so the user still sees it.
+ */
+
+import type { BackgroundTaskInfo, BackgroundTaskStatus } from '@moonshot-ai/kimi-code-sdk';
+
+import type { BackgroundAgentStatusData, BackgroundAgentStatusPhase } from '@/tui/types';
+
+const MAX_DETAIL_LENGTH = 240;
+
+function truncate(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const collapsed = value.trim().replaceAll(/\s+/g, ' ');
+  if (collapsed.length === 0) return undefined;
+  if (collapsed.length <= MAX_DETAIL_LENGTH) return collapsed;
+  return `${collapsed.slice(0, MAX_DETAIL_LENGTH - 3)}...`;
+}
+
+export type BackgroundTaskTranscriptPhase = 'started' | 'updated' | 'terminal';
+
+function phaseFromStatus(status: BackgroundTaskStatus): BackgroundAgentStatusPhase {
+  switch (status) {
+    case 'running':
+    case 'awaiting_approval':
+      return 'started';
+    case 'completed':
+      return 'completed';
+    case 'failed':
+    case 'killed':
+    case 'lost':
+      return 'failed';
+  }
+}
+
+function subjectFor(taskId: string): string {
+  return taskId.startsWith('agent-') ? 'agent task' : 'bash task';
+}
+
+function headlineFor(info: BackgroundTaskInfo): string {
+  const subject = subjectFor(info.taskId);
+  switch (info.status) {
+    case 'running':
+      return `${subject} started in background`;
+    case 'awaiting_approval':
+      return `${subject} awaiting approval`;
+    case 'completed':
+      return `${subject} completed in background`;
+    case 'failed':
+      return `${subject} failed in background`;
+    case 'killed':
+      return `${subject} stopped`;
+    case 'lost':
+      return `${subject} lost`;
+  }
+}
+
+function detailFor(info: BackgroundTaskInfo): string | undefined {
+  const parts: string[] = [];
+  const description = truncate(info.description);
+  if (description !== undefined) parts.push(description);
+
+  if (info.status === 'completed' || info.status === 'failed') {
+    if (info.exitCode !== null && info.exitCode !== undefined) {
+      parts.push(`exit ${info.exitCode}`);
+    }
+  }
+  if (info.status === 'killed') {
+    const reason = truncate(info.stopReason);
+    parts.push(reason !== undefined ? `stopped — ${reason}` : 'stopped');
+  }
+  if (info.status === 'awaiting_approval') {
+    const reason = truncate(info.approvalReason);
+    if (reason !== undefined) parts.push(`awaiting: ${reason}`);
+  }
+  if (info.status === 'lost') {
+    parts.push('session restarted before completion');
+  }
+  if (info.timedOut === true) parts.push('timed out');
+
+  return parts.length > 0 ? parts.join(' · ') : undefined;
+}
+
+/**
+ * Build a transcript card payload for a background task lifecycle
+ * snapshot. The returned phase drives bullet color in the renderer
+ * (`BackgroundAgentStatusComponent`); the detail line carries the extra
+ * status nuance (exit code, kill reason, etc.).
+ */
+export function formatBackgroundTaskTranscript(
+  info: BackgroundTaskInfo,
+): BackgroundAgentStatusData {
+  return {
+    phase: phaseFromStatus(info.status),
+    headline: headlineFor(info),
+    detail: detailFor(info),
+  };
+}
diff --git a/apps/kimi-code/src/tui/utils/component-capabilities.ts b/apps/kimi-code/src/tui/utils/component-capabilities.ts
new file mode 100644
index 000000000..5f1f0ba97
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/component-capabilities.ts
@@ -0,0 +1,40 @@
+export interface Expandable {
+  setExpanded(expanded: boolean): void;
+}
+
+export interface PlanExpandable {
+  // Returns true iff the component actually owns a plan preview and
+  // applied the new state.
+  setPlanExpanded(expanded: boolean): boolean;
+}
+
+export interface Disposable {
+  dispose(): void;
+}
+
+export function isExpandable(obj: unknown): obj is Expandable {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'setExpanded' in obj &&
+    typeof (obj as Expandable).setExpanded === 'function'
+  );
+}
+
+export function isPlanExpandable(obj: unknown): obj is PlanExpandable {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'setPlanExpanded' in obj &&
+    typeof (obj as PlanExpandable).setPlanExpanded === 'function'
+  );
+}
+
+export function hasDispose(value: unknown): value is Disposable {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'dispose' in value &&
+    typeof (value as Disposable).dispose === 'function'
+  );
+}
diff --git a/apps/kimi-code/src/tui/utils/errors.ts b/apps/kimi-code/src/tui/utils/errors.ts
new file mode 100644
index 000000000..f0fd60a2b
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/errors.ts
@@ -0,0 +1,14 @@
+function isAbortMessage(message: string): boolean {
+  return message === 'Aborted' || message.endsWith(': Aborted');
+}
+
+export function isAbortError(error: unknown): boolean {
+  if (error instanceof Error) {
+    return error.name === 'AbortError' || isAbortMessage(error.message);
+  }
+  if (typeof error === 'object' && error !== null) {
+    const message = (error as { readonly message?: unknown }).message;
+    return typeof message === 'string' && isAbortMessage(message);
+  }
+  return isAbortMessage(String(error));
+}
diff --git a/apps/kimi-code/src/tui/utils/event-payload.ts b/apps/kimi-code/src/tui/utils/event-payload.ts
new file mode 100644
index 000000000..195f7d392
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/event-payload.ts
@@ -0,0 +1,81 @@
+import { isKimiError } from '@moonshot-ai/kimi-code-sdk';
+
+import { STREAMING_ARGS_FIELD_RE } from '#/tui/constant/streaming';
+
+function unescapeJsonString(s: string): string {
+  return s.replaceAll(/\\(["\\/bfnrt])/g, (_, ch: string) => {
+    switch (ch) {
+      case 'n':
+        return '\n';
+      case 't':
+        return '\t';
+      case 'r':
+        return '\r';
+      case 'b':
+        return '\b';
+      case 'f':
+        return '\f';
+      case '"':
+        return '"';
+      case '\\':
+        return '\\';
+      case '/':
+        return '/';
+      default:
+        return ch;
+    }
+  });
+}
+
+export function parseStreamingArgs(argumentsText: string): Record<string, unknown> {
+  if (argumentsText.trim().length === 0) return {};
+  if (argumentsText.trimEnd().endsWith('}')) {
+    try {
+      const parsed = JSON.parse(argumentsText) as unknown;
+      if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+        return parsed as Record<string, unknown>;
+      }
+    } catch {
+      // fall through to partial scan
+    }
+  }
+  const result: Record<string, unknown> = {};
+  for (const match of argumentsText.matchAll(STREAMING_ARGS_FIELD_RE)) {
+    const key = match[1];
+    const rawValue = match[2];
+    if (key === undefined || rawValue === undefined) continue;
+    if (!(key in result)) {
+      result[key] = unescapeJsonString(rawValue);
+    }
+  }
+  return result;
+}
+
+export function argsRecord(args: unknown): Record<string, unknown> {
+  return typeof args === 'object' && args !== null && !Array.isArray(args)
+    ? (args as Record<string, unknown>)
+    : {};
+}
+
+export function serializeToolResultOutput(output: unknown): string {
+  if (typeof output === 'string') return output;
+  return JSON.stringify(output, null, 2);
+}
+
+export function isTodoItemShape(
+  value: unknown,
+): value is { title: string; status: 'pending' | 'in_progress' | 'done' } {
+  if (typeof value !== 'object' || value === null) return false;
+  const rec = value as { title?: unknown; status?: unknown };
+  if (typeof rec.title !== 'string' || rec.title.length === 0) return false;
+  return rec.status === 'pending' || rec.status === 'in_progress' || rec.status === 'done';
+}
+
+export function formatErrorMessage(error: unknown): string {
+  if (isKimiError(error)) return `[${error.code}] ${error.message}`;
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
diff --git a/apps/kimi-code/src/tui/utils/image-attachment-store.ts b/apps/kimi-code/src/tui/utils/image-attachment-store.ts
new file mode 100644
index 000000000..bac4ab8fb
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/image-attachment-store.ts
@@ -0,0 +1,120 @@
+/**
+ * Registry for media pasted into the input box.
+ *
+ * Each paste produces an `ImageAttachment` with an auto-incrementing id
+ * or `VideoAttachment` with a human-readable placeholder (`[image #1
+ * (640×480)]` / `[video #2 sample.mov]`). The placeholder is what the
+ * user sees in the input field; on submit, `extractMediaAttachments`
+ * walks the text and expands image placeholders to image content parts
+ * and video placeholders to file-path tags for `ReadMediaFile`.
+ *
+ * Scope is per-`KimiTUI` instance. Reloads (`/new`, `/clear`,
+ * session switch) call `clear()` so ids restart from 1 and stale
+ * prompt attachments are dropped. We intentionally do NOT persist
+ * attachments across sessions — coding-agent doesn't either, and
+ * `--resume` wouldn't know how to materialize the files anyway.
+ */
+
+export interface ImageAttachment {
+  readonly id: number;
+  readonly kind: 'image';
+  readonly bytes: Uint8Array;
+  readonly mime: string;
+  readonly width: number;
+  readonly height: number;
+  /** Rendered placeholder string, e.g. `[image #1 (640×480)]`. */
+  readonly placeholder: string;
+}
+
+export interface VideoAttachment {
+  readonly id: number;
+  readonly kind: 'video';
+  readonly mime: string;
+  readonly filename: string;
+  readonly sourcePath: string;
+  readonly label: string;
+  /** Rendered placeholder string, e.g. `[video #1 sample.mov]`. */
+  readonly placeholder: string;
+}
+
+export type MediaAttachment = ImageAttachment | VideoAttachment;
+
+export class ImageAttachmentStore {
+  private nextId = 1;
+  private readonly byId = new Map<number, MediaAttachment>();
+
+  addImage(bytes: Uint8Array, mime: string, width: number, height: number): ImageAttachment {
+    const id = this.nextId;
+    this.nextId += 1;
+    const attachment: ImageAttachment = {
+      id,
+      kind: 'image',
+      bytes,
+      mime,
+      width,
+      height,
+      placeholder: formatPlaceholder(id, width, height),
+    };
+    this.byId.set(id, attachment);
+    return attachment;
+  }
+
+  addVideo(mime: string, sourcePath: string, filename?: string | undefined): VideoAttachment {
+    const id = this.nextId;
+    this.nextId += 1;
+    const normalizedFilename = basenameLike(
+      filename !== undefined && filename !== '' ? filename : sourcePath,
+    );
+    const label = sanitizeVideoLabel(normalizedFilename.length > 0 ? normalizedFilename : mime);
+    const attachment: VideoAttachment = {
+      id,
+      kind: 'video',
+      mime,
+      filename: normalizedFilename,
+      sourcePath,
+      label,
+      placeholder: formatVideoPlaceholder(id, label),
+    };
+    this.byId.set(id, attachment);
+    return attachment;
+  }
+
+  get(id: number): MediaAttachment | undefined {
+    return this.byId.get(id);
+  }
+
+  clear(): void {
+    this.byId.clear();
+    this.nextId = 1;
+  }
+
+  size(): number {
+    return this.byId.size;
+  }
+}
+
+export function formatPlaceholder(id: number, width: number, height: number): string {
+  return `[image #${String(id)} (${String(width)}×${String(height)})]`;
+}
+
+export function formatVideoPlaceholder(id: number, label: string): string {
+  return `[video #${String(id)} ${sanitizeVideoLabel(label)}]`;
+}
+
+function sanitizeVideoLabel(raw: string): string {
+  let label = '';
+  for (const char of raw) {
+    const code = char.codePointAt(0);
+    label +=
+      code === undefined || code < 0x20 || code === 0x7f || char === '[' || char === ']'
+        ? '_'
+        : char;
+  }
+  label = label.trim();
+  return label.length > 0 ? label : 'video';
+}
+
+function basenameLike(raw: string): string {
+  const parts = raw.split(/[\\/]/).filter((part) => part.length > 0);
+  return parts.at(-1) ?? raw;
+}
diff --git a/apps/kimi-code/src/tui/utils/image-placeholder.ts b/apps/kimi-code/src/tui/utils/image-placeholder.ts
new file mode 100644
index 000000000..11c401f2f
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/image-placeholder.ts
@@ -0,0 +1,126 @@
+/**
+ * Scan submitted text for media placeholders and produce
+ * the `PromptPart[]` we'll send to the SDK prompt endpoint.
+ *
+ * Rules:
+ *   - Only placeholders that resolve against `store` get extracted.
+ *     A literal `[image #999 ...]` the user typed themselves stays in
+ *     the text (we can't hallucinate files for it).
+ *   - Order is preserved for text/image/video segments. Image placeholders
+ *     expand to image content parts so the prompt reaches the provider
+ *     without relying on a model tool call. Video placeholders still expand
+ *     to file-path tags so `ReadMediaFile` can own video upload behavior.
+ *   - Adjacent text segments are flattened — empty / whitespace-only
+ *     segments drop out so we never emit `{type:'text', text:' '}`
+ *     noise between two media parts.
+ */
+
+import type { PromptPart } from '@moonshot-ai/kimi-code-sdk';
+
+import type {
+  ImageAttachment,
+  ImageAttachmentStore,
+  VideoAttachment,
+} from './image-attachment-store';
+
+const PLACEHOLDER_REGEX = /\[(image|video) #(\d+) (?:(\(\d+×\d+\))|([^\]]+))\]/g;
+
+export interface ExtractionResult {
+  /** Flat list of parts in input order; empty array when no media matched. */
+  parts: PromptPart[];
+  /**
+   * Did we find at least one matching attachment? When false, callers
+   * should keep the prompt on the plain text path.
+   */
+  hasMedia: boolean;
+  /** Image attachment ids matched, in the order they appeared. */
+  imageAttachmentIds: number[];
+  /** Video attachment ids matched, in the order they appeared. */
+  videoAttachmentIds: number[];
+}
+
+export function extractMediaAttachments(
+  text: string,
+  store: ImageAttachmentStore,
+): ExtractionResult {
+  const parts: PromptPart[] = [];
+  const imageAttachmentIds: number[] = [];
+  const videoAttachmentIds: number[] = [];
+  let cursor = 0;
+  let hasMedia = false;
+
+  PLACEHOLDER_REGEX.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = PLACEHOLDER_REGEX.exec(text)) !== null) {
+    const [literal, kind, idStr] = match;
+    if (kind !== 'image' && kind !== 'video') continue;
+    if (idStr === undefined) continue;
+    const id = Number.parseInt(idStr, 10);
+    const attachment = store.get(id);
+    if (attachment === undefined) continue; // stale / user-typed — leave as text
+    if (attachment.kind !== kind) continue;
+    const before = text.slice(cursor, match.index);
+    pushText(parts, before);
+    if (attachment.kind === 'video') {
+      const mediaText = tagTextForVideo(attachment);
+      pushText(parts, mediaText);
+      videoAttachmentIds.push(id);
+    } else {
+      parts.push(imagePartForAttachment(attachment));
+      imageAttachmentIds.push(id);
+    }
+    hasMedia = true;
+    cursor = match.index + literal.length;
+  }
+  const tail = text.slice(cursor);
+  pushText(parts, tail);
+
+  return {
+    // Text-only submissions drop the synthesised parts array — the
+    // caller's contract is "parts is meaningful iff hasMedia", and
+    // emitting a stray TextPart confuses consumers that branch on
+    // `parts.length > 0`.
+    parts: hasMedia ? parts : [],
+    hasMedia,
+    imageAttachmentIds,
+    videoAttachmentIds,
+  };
+}
+
+function pushText(parts: PromptPart[], segment: string): void {
+  if (segment.length === 0) return;
+  // Keep whitespace-only segments only when they sit between non-empty
+  // text elsewhere — the simpler rule "drop everything whitespace-only"
+  // is fine here because the LLM doesn't care about inter-image spaces.
+  if (segment.trim().length === 0) return;
+  const last = parts.at(-1);
+  if (last?.type === 'text') {
+    parts[parts.length - 1] = { type: 'text', text: last.text + segment };
+    return;
+  }
+  parts.push({ type: 'text', text: segment });
+}
+
+function imagePartForAttachment(att: ImageAttachment): PromptPart {
+  const base64 = Buffer.from(att.bytes).toString('base64');
+  return {
+    type: 'image_url',
+    imageUrl: { url: `data:${att.mime};base64,${base64}` },
+  };
+}
+
+function tagTextForVideo(att: VideoAttachment): string {
+  return formatMediaTag('video', att.sourcePath);
+}
+
+function formatMediaTag(tag: 'image' | 'video', path: string): string {
+  return `<${tag} path="${escapeAttribute(path)}"></${tag}>`;
+}
+
+function escapeAttribute(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
diff --git a/apps/kimi-code/src/tui/utils/mcp-oauth.ts b/apps/kimi-code/src/tui/utils/mcp-oauth.ts
new file mode 100644
index 000000000..e0c17b043
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/mcp-oauth.ts
@@ -0,0 +1,51 @@
+import {
+  MCP_OAUTH_AUTHORIZATION_URL_TOOL_UPDATE,
+  type McpOAuthAuthorizationUrlUpdateData,
+  type ToolProgressEvent,
+  type ToolUpdate,
+} from '@moonshot-ai/kimi-code-sdk';
+
+export type OpenUrl = (url: string) => void;
+
+export class McpOAuthAuthorizationUrlOpener {
+  private readonly openedAuthorizationUrls = new Set<string>();
+
+  constructor(private readonly openUrl: OpenUrl) {}
+
+  handleToolProgress(event: Pick<ToolProgressEvent, 'toolCallId' | 'update'>): void {
+    const update = parseMcpOAuthAuthorizationUrlUpdate(event.update);
+    if (update === undefined) return;
+    const key = `${event.toolCallId}\0${update.authorizationUrl}`;
+    if (this.openedAuthorizationUrls.has(key)) return;
+    this.openedAuthorizationUrls.add(key);
+    this.openUrl(update.authorizationUrl);
+  }
+}
+
+export function parseMcpOAuthAuthorizationUrlUpdate(
+  update: ToolUpdate,
+): McpOAuthAuthorizationUrlUpdateData | undefined {
+  if (update.kind !== 'custom') return undefined;
+  if (update.customKind !== MCP_OAUTH_AUTHORIZATION_URL_TOOL_UPDATE) return undefined;
+  const data = update.customData;
+  if (!isRecord(data)) return undefined;
+  const serverName = data['serverName'];
+  const authorizationUrl = data['authorizationUrl'];
+  if (typeof serverName !== 'string' || serverName.length === 0) return undefined;
+  if (typeof authorizationUrl !== 'string' || authorizationUrl.length === 0) return undefined;
+  if (!isHttpUrl(authorizationUrl)) return undefined;
+  return { serverName, authorizationUrl };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
diff --git a/apps/kimi-code/src/tui/utils/mcp-server-status.ts b/apps/kimi-code/src/tui/utils/mcp-server-status.ts
new file mode 100644
index 000000000..09fda3989
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/mcp-server-status.ts
@@ -0,0 +1,73 @@
+import type { McpServerInfo, McpServerStatusEvent } from '@moonshot-ai/kimi-code-sdk';
+
+export type McpServerStatusSnapshot = McpServerInfo | McpServerStatusEvent['server'];
+
+export const MCP_STARTUP_STATUS_ROW_LIMIT = 4;
+
+function mcpStartupStatusPriority(status: McpServerStatusSnapshot['status']): number {
+  switch (status) {
+    case 'failed':
+      return 0;
+    case 'needs-auth':
+      return 1;
+    case 'pending':
+      return 2;
+    case 'connected':
+      return 3;
+    case 'disabled':
+      return 4;
+  }
+}
+
+export function selectMcpStartupStatusRows(
+  servers: readonly McpServerStatusSnapshot[],
+): McpServerStatusSnapshot[] {
+  return [...servers]
+    .filter((server) => server.status !== 'disabled')
+    .toSorted((a, b) => mcpStartupStatusPriority(a.status) - mcpStartupStatusPriority(b.status))
+    .slice(0, MCP_STARTUP_STATUS_ROW_LIMIT);
+}
+
+export function formatMcpStartupStatusSummary(
+  hidden: readonly McpServerStatusSnapshot[],
+  visibleCount: number,
+): string {
+  let failed = 0;
+  let needsAuth = 0;
+  let connecting = 0;
+  let connected = 0;
+  let disabled = 0;
+  for (const server of hidden) {
+    switch (server.status) {
+      case 'failed':
+        failed++;
+        break;
+      case 'needs-auth':
+        needsAuth++;
+        break;
+      case 'pending':
+        connecting++;
+        break;
+      case 'connected':
+        connected++;
+        break;
+      case 'disabled':
+        disabled++;
+        break;
+    }
+  }
+
+  const parts: string[] = [];
+  if (failed > 0) parts.push(`${failed} failed`);
+  if (needsAuth > 0) parts.push(`${needsAuth} need auth`);
+  if (connecting > 0) parts.push(`${connecting} connecting`);
+  if (connected > 0) parts.push(`${connected} connected`);
+  if (disabled > 0) parts.push(`${disabled} disabled`);
+  const detail = parts.join(', ');
+  if (visibleCount === 0) return `MCP servers: ${detail}`;
+  return `MCP servers: ${hidden.length} more (${detail})`;
+}
+
+export function mcpServerStatusKey(server: McpServerStatusSnapshot): string {
+  return JSON.stringify([server.status, server.transport, server.toolCount, server.error]);
+}
diff --git a/apps/kimi-code/src/tui/utils/mcp-tool-name.ts b/apps/kimi-code/src/tui/utils/mcp-tool-name.ts
new file mode 100644
index 000000000..dd5998a82
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/mcp-tool-name.ts
@@ -0,0 +1,16 @@
+// Decodes the `mcp__<server>__<tool>` qualified names produced by kimi-core's
+// `qualifyMcpToolName`. Returns null for non-MCP tools and for hash-truncated
+// qualified names (where the trailing `__<tool>` segment has been collapsed).
+export function decodeMcpToolName(
+  name: string,
+): { readonly serverName: string; readonly toolName: string } | null {
+  const PREFIX = 'mcp__';
+  if (!name.startsWith(PREFIX)) return null;
+  const rest = name.slice(PREFIX.length);
+  const sep = rest.indexOf('__');
+  if (sep <= 0 || sep === rest.length - 2) return null;
+  return {
+    serverName: rest.slice(0, sep),
+    toolName: rest.slice(sep + 2),
+  };
+}
diff --git a/apps/kimi-code/src/tui/utils/media-url.ts b/apps/kimi-code/src/tui/utils/media-url.ts
new file mode 100644
index 000000000..f04edeb29
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/media-url.ts
@@ -0,0 +1,51 @@
+export type MediaUrlKind = 'audio' | 'image' | 'video';
+
+export function mediaUrlPartToText(kind: MediaUrlKind, url: string): string {
+  const summary = summarizeDataUrl(url);
+  if (summary !== undefined) {
+    const size = summary.bytes !== undefined ? `, ${formatByteSize(summary.bytes)}` : '';
+    return `[${kind} ${summary.mime}${size}]`;
+  }
+  return `<${kind} url="${escapeAttribute(url)}">`;
+}
+
+export function summarizeDataUrl(url: string): { mime: string; bytes?: number } | undefined {
+  if (!url.startsWith('data:')) return undefined;
+  const commaIndex = url.indexOf(',');
+  const header =
+    commaIndex >= 0 ? url.slice('data:'.length, commaIndex) : url.slice('data:'.length);
+  const data = commaIndex >= 0 ? url.slice(commaIndex + 1) : '';
+  const [rawMime, ...params] = header.split(';');
+  const mime = rawMime !== undefined && rawMime.length > 0 ? rawMime : 'application/octet-stream';
+  const isBase64 = params.some((param) => param.toLowerCase() === 'base64');
+  return {
+    mime,
+    bytes: isBase64 ? estimateBase64Bytes(data) : undefined,
+  };
+}
+
+function estimateBase64Bytes(data: string): number {
+  const compact = data.replaceAll(/\s/g, '');
+  if (compact.length === 0) return 0;
+  const padding = compact.endsWith('==') ? 2 : compact.endsWith('=') ? 1 : 0;
+  return Math.max(0, Math.floor((compact.length * 3) / 4) - padding);
+}
+
+function formatByteSize(bytes: number): string {
+  if (bytes < 1024) return `${String(bytes)} B`;
+  const kib = bytes / 1024;
+  if (kib < 1024) return `${formatOneDecimal(kib)} KB`;
+  return `${formatOneDecimal(kib / 1024)} MB`;
+}
+
+function formatOneDecimal(value: number): string {
+  return value >= 10 ? value.toFixed(0) : value.toFixed(1);
+}
+
+function escapeAttribute(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
diff --git a/apps/kimi-code/src/tui/utils/open-url.ts b/apps/kimi-code/src/tui/utils/open-url.ts
new file mode 100644
index 000000000..4112d9c6f
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/open-url.ts
@@ -0,0 +1,11 @@
+import { execFile } from 'node:child_process';
+
+export function openUrl(url: string): void {
+  const command: [string, string[]] =
+    process.platform === 'darwin'
+      ? ['open', [url]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', url]]
+        : ['xdg-open', [url]];
+  execFile(command[0], command[1], () => {});
+}
diff --git a/apps/kimi-code/src/tui/utils/printable-key.ts b/apps/kimi-code/src/tui/utils/printable-key.ts
new file mode 100644
index 000000000..1b0977369
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/printable-key.ts
@@ -0,0 +1,27 @@
+/**
+ * Decode raw stdin bytes into a comparable printable character.
+ *
+ * When a terminal (e.g. the VSCode integrated terminal) enables the Kitty
+ * keyboard protocol disambiguate flag, ordinary printable keys are sent as
+ * CSI-u sequences: pressing `r` arrives as "\x1b[114u", pressing `q` as
+ * "\x1b[113u". A bare `data === 'q'` comparison inside a Container's
+ * `handleInput` therefore never matches under Kitty-mode terminals.
+ *
+ * Rules:
+ * - Every bare-literal printable-character comparison (letters, digits,
+ *   space, punctuation) must go through this function first.
+ * - Functional keys (arrows, Enter, Tab, Esc, ...) continue to use
+ *   `matchesKey(data, Key.*)`; pi-tui's `matchesKey` already handles Kitty.
+ * - Control characters (codepoint < 32, e.g. ctrl-b, ctrl-f) may still
+ *   compare against the raw `data` — `decodeKittyPrintable` rejects them.
+ *
+ * The module's existence is itself the "don't forget to decode" constraint:
+ * `test/tui/printable-key-guard.test.ts` scans every `handleInput` under
+ * `tui/components/**` and rejects bare-literal comparisons.
+ */
+
+import { decodeKittyPrintable } from '@earendil-works/pi-tui';
+
+export function printableChar(data: string): string {
+  return decodeKittyPrintable(data) ?? data;
+}
diff --git a/apps/kimi-code/src/tui/utils/proctitle.ts b/apps/kimi-code/src/tui/utils/proctitle.ts
new file mode 100644
index 000000000..c9c30d823
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/proctitle.ts
@@ -0,0 +1,29 @@
+/**
+ * Terminal window title synchronization.
+ *
+ * Uses the session title when present, capped at 80 characters to keep tabs
+ * readable. New or unnamed sessions fall back to `Kimi Code`.
+ *
+ * Writes both `process.title`, for process listings, and OSC 0/2 escape
+ * sequences, which most terminals use for window/tab titles. Non-TTY stdout
+ * skips the OSC write.
+ */
+import { PRODUCT_NAME } from '#/constant/app';
+import { MAX_PROCESS_TITLE_LENGTH } from '#/tui/constant/terminal';
+
+export function setProcessTitle(title: string | null, _sessionId: string): void {
+  const trimmed = title?.trim() ?? '';
+  const label = trimmed.length > 0 ? trimmed.slice(0, MAX_PROCESS_TITLE_LENGTH) : PRODUCT_NAME;
+  try {
+    process.title = label;
+  } catch {
+    /* noop */
+  }
+  try {
+    if (process.stdout.isTTY) {
+      process.stdout.write(`\u001B]0;${label}\u0007`);
+    }
+  } catch {
+    /* noop */
+  }
+}
diff --git a/apps/kimi-code/src/tui/utils/terminal-focus.ts b/apps/kimi-code/src/tui/utils/terminal-focus.ts
new file mode 100644
index 000000000..3a3559e60
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/terminal-focus.ts
@@ -0,0 +1,44 @@
+import {
+  DISABLE_TERMINAL_FOCUS_REPORTING,
+  ENABLE_TERMINAL_FOCUS_REPORTING,
+  TERMINAL_FOCUS_IN,
+  TERMINAL_FOCUS_OUT,
+} from '#/tui/constant/terminal';
+import type { TUIState } from '#/tui/kimi-tui';
+import type { TerminalState } from '#/tui/utils/terminal-state';
+
+export {
+  DISABLE_TERMINAL_FOCUS_REPORTING,
+  ENABLE_TERMINAL_FOCUS_REPORTING,
+  TERMINAL_FOCUS_IN,
+  TERMINAL_FOCUS_OUT,
+} from '#/tui/constant/terminal';
+
+export function installTerminalFocusTracking(state: TUIState): () => void {
+  state.terminalState.focused = true;
+  const disposeInputListener = state.ui.addInputListener((data) =>
+    handleTerminalFocusInput(state.terminalState, data),
+  );
+  state.terminal.write(ENABLE_TERMINAL_FOCUS_REPORTING);
+
+  return () => {
+    disposeInputListener();
+    state.terminal.write(DISABLE_TERMINAL_FOCUS_REPORTING);
+    state.terminalState.focused = true;
+  };
+}
+
+export function handleTerminalFocusInput(
+  state: Pick<TerminalState, 'focused'>,
+  data: string,
+): { consume: true } | undefined {
+  if (data === TERMINAL_FOCUS_IN) {
+    state.focused = true;
+    return { consume: true };
+  }
+  if (data === TERMINAL_FOCUS_OUT) {
+    state.focused = false;
+    return { consume: true };
+  }
+  return undefined;
+}
diff --git a/apps/kimi-code/src/tui/utils/terminal-notification.ts b/apps/kimi-code/src/tui/utils/terminal-notification.ts
new file mode 100644
index 000000000..a71da9347
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/terminal-notification.ts
@@ -0,0 +1,129 @@
+import type { Terminal } from '@earendil-works/pi-tui';
+
+import { BEL, ESC, MAX_TERMINAL_NOTIFICATION_MESSAGE_LENGTH, ST } from '#/tui/constant/terminal';
+import type { TUIState } from '#/tui/kimi-tui';
+
+export interface TerminalNotification {
+  readonly title: string;
+  readonly body?: string | undefined;
+}
+
+export interface EmitOptions {
+  readonly supportsOsc9?: boolean;
+  readonly insideTmux?: boolean;
+}
+
+export interface BuildOptions {
+  readonly supportsOsc9: boolean;
+  readonly insideTmux: boolean;
+}
+
+export function notifyTerminalOnce(
+  state: TUIState,
+  key: string,
+  notification: TerminalNotification,
+): void {
+  const { enabled, condition } = state.appState.notifications;
+  if (!enabled) return;
+  if (state.terminalState.notificationKeys.has(key)) return;
+  state.terminalState.notificationKeys.add(key);
+  if (condition === 'unfocused' && state.terminalState.focused) return;
+  emitTerminalNotification(state.terminal, notification, {
+    supportsOsc9: state.terminalState.supportsOsc9,
+    insideTmux: state.terminalState.insideTmux,
+  });
+}
+
+export function emitTerminalNotification(
+  terminal: Pick<Terminal, 'write'>,
+  notification: TerminalNotification,
+  options: EmitOptions = {},
+): void {
+  const sequences = buildTerminalNotificationSequences(notification, {
+    supportsOsc9: options.supportsOsc9 ?? supportsOsc9Notification(),
+    insideTmux: options.insideTmux ?? isInsideTmux(),
+  });
+  for (const sequence of sequences) {
+    terminal.write(sequence);
+  }
+}
+
+export function formatNotification(notification: TerminalNotification): string {
+  const title = sanitizeNotificationText(notification.title);
+  const body = sanitizeNotificationText(notification.body ?? '');
+  const message =
+    title.length > 0 && body.length > 0 ? `${title}: ${body}` : title.length > 0 ? title : body;
+  return message.slice(0, MAX_TERMINAL_NOTIFICATION_MESSAGE_LENGTH);
+}
+
+/**
+ * Build the OSC/BEL bytes for a terminal notification.
+ *
+ * - `supportsOsc9 === true`: emit a single OSC 9 sequence — the modern
+ *   desktop-notification path used by iTerm2, WezTerm, Kitty, Ghostty
+ *   and Warp.
+ * - `supportsOsc9 === false`: fall back to a bare BEL so the user still
+ *   gets the system bell on terminals that don't recognize OSC 9.
+ *
+ * When `insideTmux === true` and we're emitting OSC 9, wrap the sequence
+ * in a tmux DCS passthrough (`ESC P tmux ; <payload> ESC \`) and double
+ * any `ESC` bytes inside the payload — otherwise tmux swallows the OSC.
+ * BEL is single-byte and passes through tmux unchanged, so no wrap is
+ * needed in the fallback path.
+ */
+export function buildTerminalNotificationSequences(
+  notification: TerminalNotification,
+  options: BuildOptions,
+): string[] {
+  const message = formatNotification(notification);
+  if (message.length === 0) return [];
+  if (!options.supportsOsc9) {
+    return [BEL];
+  }
+  const osc9 = `${ESC}]9;${message}${BEL}`;
+  if (options.insideTmux) {
+    const escaped = osc9.replaceAll(ESC, `${ESC}${ESC}`);
+    return [`${ESC}Ptmux;${escaped}${ESC}${ST}`];
+  }
+  return [osc9];
+}
+
+/**
+ * Best-effort detection of OSC 9 desktop-notification support, driven
+ * entirely off well-known environment variables. The allow-list is
+ * intentionally short and conservative because BEL is safe everywhere,
+ * while shipping OSC 9 to a terminal that doesn't grok it would print
+ * escape garbage on screen.
+ */
+export function supportsOsc9Notification(env: NodeJS.ProcessEnv = process.env): boolean {
+  const termProgram = env['TERM_PROGRAM'] ?? '';
+  if (
+    termProgram === 'iTerm.app' ||
+    termProgram === 'WezTerm' ||
+    termProgram === 'ghostty' ||
+    termProgram === 'WarpTerminal'
+  ) {
+    return true;
+  }
+  const term = env['TERM'] ?? '';
+  if (term === 'xterm-kitty' || term === 'xterm-ghostty') return true;
+  return false;
+}
+
+export function isInsideTmux(env: NodeJS.ProcessEnv = process.env): boolean {
+  const tmux = env['TMUX'] ?? '';
+  return tmux.length > 0;
+}
+
+function sanitizeNotificationText(value: string): string {
+  return Array.from(value)
+    .map((ch) => (isControlCharacter(ch) ? ' ' : ch))
+    .join('')
+    .replaceAll(/\s+/g, ' ')
+    .trim();
+}
+
+function isControlCharacter(ch: string): boolean {
+  const code = ch.codePointAt(0) ?? 0;
+  return (code >= 0x00 && code <= 0x1f) || (code >= 0x7f && code <= 0x9f);
+}
diff --git a/apps/kimi-code/src/tui/utils/terminal-state.ts b/apps/kimi-code/src/tui/utils/terminal-state.ts
new file mode 100644
index 000000000..86d2bab9f
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/terminal-state.ts
@@ -0,0 +1,19 @@
+import { isInsideTmux, supportsOsc9Notification } from './terminal-notification';
+
+export interface TerminalState {
+  notificationKeys: Set<string>;
+  focused: boolean;
+  supportsOsc9: boolean;
+  insideTmux: boolean;
+  progressActive: boolean;
+}
+
+export function createTerminalState(): TerminalState {
+  return {
+    notificationKeys: new Set<string>(),
+    focused: true,
+    supportsOsc9: supportsOsc9Notification(),
+    insideTmux: isInsideTmux(),
+    progressActive: false,
+  };
+}
diff --git a/apps/kimi-code/src/tui/utils/terminal-theme.ts b/apps/kimi-code/src/tui/utils/terminal-theme.ts
new file mode 100644
index 000000000..71c6b9bbf
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/terminal-theme.ts
@@ -0,0 +1,153 @@
+import {
+  DISABLE_TERMINAL_THEME_REPORTING,
+  ENABLE_TERMINAL_THEME_REPORTING,
+  OSC11_QUERY,
+  OSC11_RESPONSE,
+  OSC11_RESPONSE_PREFIX,
+  OSC11_RESPONSE_PREFIX_NO_ESC,
+  QUERY_TERMINAL_THEME,
+  TERMINAL_THEME_INPUT_BUFFER_MAX_LENGTH,
+  TERMINAL_THEME_DARK,
+  TERMINAL_THEME_LIGHT,
+} from "#/tui/constant/terminal";
+import type { TUIState } from "#/tui/kimi-tui";
+import type { ResolvedTheme } from "#/tui/theme/colors";
+import { parseOsc11BackgroundTheme } from "#/tui/theme/terminal-background";
+
+export {
+  DISABLE_TERMINAL_THEME_REPORTING,
+  ENABLE_TERMINAL_THEME_REPORTING,
+  OSC11_QUERY,
+  QUERY_TERMINAL_THEME,
+  TERMINAL_THEME_DARK,
+  TERMINAL_THEME_LIGHT,
+} from "#/tui/constant/terminal";
+
+export function hasTerminalThemeReport(data: string): boolean {
+  return data.includes(TERMINAL_THEME_DARK) || data.includes(TERMINAL_THEME_LIGHT);
+}
+
+export interface TerminalThemeInputState {
+  osc11Buffer: string;
+}
+
+export type TerminalThemeInputResult =
+  | {
+      consume?: boolean;
+      data?: string;
+    }
+  | undefined;
+
+export function createTerminalThemeInputState(): TerminalThemeInputState {
+  return { osc11Buffer: "" };
+}
+
+export function handleTerminalThemeInput(
+  data: string,
+  terminal: Pick<TUIState["terminal"], "write">,
+  onTheme: (theme: ResolvedTheme) => void,
+  inputState: TerminalThemeInputState = createTerminalThemeInputState(),
+): TerminalThemeInputResult {
+  let remaining = data;
+
+  if (inputState.osc11Buffer !== "") {
+    const candidate = `${inputState.osc11Buffer}${data}`;
+    const stripped = stripOsc11Reports(candidate, onTheme);
+    if (stripped !== candidate) {
+      inputState.osc11Buffer = "";
+      return resultFromRemaining(stripped);
+    }
+
+    inputState.osc11Buffer =
+      candidate.length > TERMINAL_THEME_INPUT_BUFFER_MAX_LENGTH ? "" : candidate;
+    return { consume: true };
+  }
+
+  remaining = stripOsc11Reports(remaining, onTheme);
+  remaining = stripTerminalThemeReports(remaining, terminal);
+
+  const partialOsc11Start = findPartialOsc11Start(remaining);
+  if (partialOsc11Start !== -1) {
+    inputState.osc11Buffer = remaining.slice(partialOsc11Start);
+    return resultFromRemaining(remaining.slice(0, partialOsc11Start));
+  }
+
+  if (remaining !== data) return resultFromRemaining(remaining);
+
+  return undefined;
+}
+
+function stripOsc11Reports(data: string, onTheme: (theme: ResolvedTheme) => void): string {
+  let remaining = data;
+
+  for (;;) {
+    const match = OSC11_RESPONSE.exec(remaining);
+    if (match === null) return remaining;
+
+    const theme = parseOsc11BackgroundTheme(match[0]);
+    if (theme !== null) onTheme(theme);
+
+    remaining = `${remaining.slice(0, match.index)}${remaining.slice(match.index + match[0].length)}`;
+  }
+}
+
+function stripTerminalThemeReports(
+  data: string,
+  terminal: Pick<TUIState["terminal"], "write">,
+): string {
+  let remaining = data;
+  let strippedReport = false;
+
+  for (const report of [TERMINAL_THEME_DARK, TERMINAL_THEME_LIGHT]) {
+    if (!remaining.includes(report)) continue;
+    remaining = remaining.split(report).join("");
+    strippedReport = true;
+  }
+
+  if (strippedReport) {
+    terminal.write(OSC11_QUERY);
+  }
+
+  return remaining;
+}
+
+function findPartialOsc11Start(data: string): number {
+  const fullPrefixIndex = data.indexOf(OSC11_RESPONSE_PREFIX);
+  if (fullPrefixIndex !== -1) return fullPrefixIndex;
+
+  const noEscPrefixIndex = data.indexOf(OSC11_RESPONSE_PREFIX_NO_ESC);
+  if (noEscPrefixIndex !== -1) return noEscPrefixIndex;
+
+  for (let i = 0; i < data.length; i++) {
+    const suffix = data.slice(i);
+    if (OSC11_RESPONSE_PREFIX.startsWith(suffix) && suffix.length > 1) return i;
+    if (OSC11_RESPONSE_PREFIX_NO_ESC.startsWith(suffix) && suffix.startsWith("]11;")) {
+      return i;
+    }
+  }
+
+  return -1;
+}
+
+function resultFromRemaining(data: string): TerminalThemeInputResult {
+  if (data.length === 0) return { consume: true };
+  return { data };
+}
+
+export function installTerminalThemeTracking(
+  state: Pick<TUIState, "terminal" | "ui">,
+  onTheme: (theme: ResolvedTheme) => void,
+): () => void {
+  const inputState = createTerminalThemeInputState();
+  const disposeInputListener = state.ui.addInputListener((data) =>
+    handleTerminalThemeInput(data, state.terminal, onTheme, inputState),
+  );
+  state.terminal.write(ENABLE_TERMINAL_THEME_REPORTING);
+  state.terminal.write(OSC11_QUERY);
+  state.terminal.write(QUERY_TERMINAL_THEME);
+
+  return () => {
+    disposeInputListener();
+    state.terminal.write(DISABLE_TERMINAL_THEME_REPORTING);
+  };
+}
diff --git a/apps/kimi-code/src/tui/utils/transcript-id.ts b/apps/kimi-code/src/tui/utils/transcript-id.ts
new file mode 100644
index 000000000..149378a9b
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/transcript-id.ts
@@ -0,0 +1,6 @@
+let transcriptIdCounter = 0;
+
+export function nextTranscriptId(): string {
+  transcriptIdCounter += 1;
+  return `entry-${String(transcriptIdCounter)}`;
+}
diff --git a/apps/kimi-code/src/utils/clipboard/clipboard-image.ts b/apps/kimi-code/src/utils/clipboard/clipboard-image.ts
new file mode 100644
index 000000000..0bb8d3c76
--- /dev/null
+++ b/apps/kimi-code/src/utils/clipboard/clipboard-image.ts
@@ -0,0 +1,516 @@
+/**
+ * Read media from the system clipboard with graceful platform fallbacks.
+ *
+ * kimi-core's LLM pipeline only accepts PNG/JPEG/GIF/WebP, and the
+ * clipboard sources we query already emit those formats on supported
+ * platforms — so we deliberately do not include a BMP→PNG converter.
+ *
+ * Lookup order:
+ *   macOS file clipboard       -> osascript/AppKit file URLs
+ *   macOS / Windows            -> native `@mariozechner/clipboard`
+ *   Linux Wayland              -> wl-paste
+ *   Linux X11                  -> xclip
+ *   WSL (image not on Linux cb) -> PowerShell fallback via wslpath
+ *
+ * Returns `null` when no supported media is available, the format isn't
+ * supported, or every fallback fails.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readFileSync, statSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parseImageMeta } from '#/utils/image/image-mime';
+
+import { clipboard, type ClipboardModule } from './clipboard-native';
+
+export interface ClipboardImage {
+  kind: 'image';
+  bytes: Uint8Array;
+  mimeType: string;
+}
+
+export interface ClipboardVideo {
+  kind: 'video';
+  mimeType: string;
+  filename: string;
+  sourcePath: string;
+}
+
+export type ClipboardMedia = ClipboardImage | ClipboardVideo;
+
+export class ClipboardMediaError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ClipboardMediaError';
+  }
+}
+
+type RunCommandOptions = { timeoutMs?: number; env?: NodeJS.ProcessEnv };
+type RunCommand = (
+  command: string,
+  args: string[],
+  options?: RunCommandOptions,
+) => { stdout: Buffer; ok: boolean };
+
+const SUPPORTED_IMAGE_MIME_TYPES = ['image/png', 'image/jpeg', 'image/webp', 'image/gif'] as const;
+const MAX_VIDEO_BYTES = 100 * 1024 * 1024;
+
+const VIDEO_MIME_BY_SUFFIX: Readonly<Record<string, string>> = Object.freeze({
+  '.mp4': 'video/mp4',
+  '.mpg': 'video/mpeg',
+  '.mpeg': 'video/mpeg',
+  '.mkv': 'video/x-matroska',
+  '.avi': 'video/x-msvideo',
+  '.mov': 'video/quicktime',
+  '.ogv': 'video/ogg',
+  '.wmv': 'video/x-ms-wmv',
+  '.webm': 'video/webm',
+  '.m4v': 'video/x-m4v',
+  '.flv': 'video/x-flv',
+  '.3gp': 'video/3gpp',
+  '.3g2': 'video/3gpp2',
+});
+
+const DEFAULT_LIST_TIMEOUT_MS = 1000;
+const DEFAULT_READ_TIMEOUT_MS = 3000;
+const DEFAULT_POWERSHELL_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_BUFFER_BYTES = 50 * 1024 * 1024;
+
+const MACOS_FILE_PATH_SCRIPT = String.raw`
+ObjC.import('AppKit');
+ObjC.import('Foundation');
+
+const out = [];
+const pb = $.NSPasteboard.generalPasteboard;
+if (String(pb) !== '[id nil]') {
+  try {
+    const options = $.NSMutableDictionary.dictionary;
+    options.setObjectForKey($.NSNumber.numberWithBool(true), $.NSPasteboardURLReadingFileURLsOnlyKey);
+    const urls = pb.readObjectsForClassesOptions([$.NSURL], options);
+    const count = urls ? urls.count : 0;
+    for (let i = 0; i < count; i++) {
+      const value = urls.objectAtIndex(i).path;
+      const path = value ? ObjC.unwrap(value) : '';
+      if (path) out.push(path);
+    }
+  } catch (error) {}
+
+  if (out.length === 0) {
+    try {
+      const files = ObjC.deepUnwrap(pb.propertyListForType('NSFilenamesPboardType'));
+      if (Array.isArray(files)) {
+        for (const path of files) {
+          if (path) out.push(String(path));
+        }
+      } else if (files) {
+        out.push(String(files));
+      }
+    } catch (error) {}
+  }
+}
+out.join('\n');
+`.trim();
+
+function isWaylandSession(env: NodeJS.ProcessEnv): boolean {
+  return Boolean(env['WAYLAND_DISPLAY']) || env['XDG_SESSION_TYPE'] === 'wayland';
+}
+
+function isWSL(env: NodeJS.ProcessEnv): boolean {
+  if (env['WSL_DISTRO_NAME'] !== undefined || env['WSLENV'] !== undefined) return true;
+  try {
+    return /microsoft|wsl/i.test(readFileSync('/proc/version', 'utf-8'));
+  } catch {
+    return false;
+  }
+}
+
+function baseMimeType(raw: string): string {
+  return raw.split(';')[0]?.trim().toLowerCase() ?? raw.toLowerCase();
+}
+
+function isSupportedImageMimeType(mime: string): boolean {
+  const base = baseMimeType(mime);
+  return (SUPPORTED_IMAGE_MIME_TYPES as readonly string[]).includes(base);
+}
+
+function selectPreferredImageMimeType(candidates: string[]): string | null {
+  const normalized = candidates
+    .map((t) => t.trim())
+    .filter((t) => t.length > 0)
+    .map((raw) => ({ raw, base: baseMimeType(raw) }));
+
+  for (const preferred of SUPPORTED_IMAGE_MIME_TYPES) {
+    const match = normalized.find((t) => t.base === preferred);
+    if (match !== undefined) return match.raw;
+  }
+  const anyImage = normalized.find((t) => t.base.startsWith('image/'));
+  return anyImage?.raw ?? null;
+}
+
+function videoMimeFromPath(path: string): string | null {
+  const dot = path.lastIndexOf('.');
+  if (dot < 0) return null;
+  const suffix = path.slice(dot).toLowerCase();
+  return VIDEO_MIME_BY_SUFFIX[suffix] ?? null;
+}
+
+function parseClipboardPaths(text: string): string[] {
+  return splitClipboardPathLines(text)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith('#'))
+    .map((line) => {
+      if (line.startsWith('file://')) {
+        try {
+          return fileURLToPath(line);
+        } catch {
+          return '';
+        }
+      }
+      return line;
+    })
+    .filter((line) => line.length > 0 && isAbsolute(line));
+}
+
+function splitClipboardPathLines(text: string): string[] {
+  const lines: string[] = [];
+  let start = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === '\r' || char === '\n' || text.codePointAt(i) === 0) {
+      lines.push(text.slice(start, i));
+      start = i + 1;
+    }
+  }
+  lines.push(text.slice(start));
+  return lines;
+}
+
+function readImagePath(path: string): ClipboardImage | null {
+  let stat: ReturnType<typeof statSync>;
+  try {
+    stat = statSync(path);
+  } catch {
+    return null;
+  }
+  if (!stat.isFile()) return null;
+
+  let bytes: Buffer;
+  try {
+    bytes = readFileSync(path);
+  } catch {
+    return null;
+  }
+  if (bytes.length === 0) return null;
+
+  const meta = parseImageMeta(bytes);
+  if (meta === null) return null;
+  return { kind: 'image', bytes: new Uint8Array(bytes), mimeType: meta.mime };
+}
+
+function readVideoPath(path: string): ClipboardVideo | null {
+  const mimeType = videoMimeFromPath(path);
+  if (mimeType === null) return null;
+  let stat: ReturnType<typeof statSync>;
+  try {
+    stat = statSync(path);
+  } catch {
+    return null;
+  }
+  if (!stat.isFile()) return null;
+  if (stat.size > MAX_VIDEO_BYTES) {
+    throw new ClipboardMediaError(
+      `Video is ${(stat.size / 1024 / 1024).toFixed(1)} MB; maximum supported size is 100 MB.`,
+    );
+  }
+  return {
+    kind: 'video',
+    mimeType,
+    filename: basename(path),
+    sourcePath: path,
+  };
+}
+
+function readMediaPath(path: string): ClipboardMedia | null {
+  // Video files are never opened as images.
+  const video = readVideoPath(path);
+  if (video !== null) return video;
+  return readImagePath(path);
+}
+
+function readMediaFromPaths(paths: readonly string[]): ClipboardMedia | null {
+  for (const path of paths) {
+    const media = readMediaPath(path);
+    if (media !== null) return media;
+  }
+  return null;
+}
+
+function readMediaFromText(text: string): ClipboardMedia | null {
+  return readMediaFromPaths(parseClipboardPaths(text));
+}
+
+function runCommand(
+  command: string,
+  args: string[],
+  options?: RunCommandOptions,
+): { stdout: Buffer; ok: boolean } {
+  const result = spawnSync(command, args, {
+    timeout: options?.timeoutMs ?? DEFAULT_READ_TIMEOUT_MS,
+    maxBuffer: DEFAULT_MAX_BUFFER_BYTES,
+    env: options?.env,
+  });
+  if (result.error !== undefined || result.status !== 0) {
+    return { ok: false, stdout: Buffer.alloc(0) };
+  }
+  const stdout = Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(result.stdout ?? '');
+  return { ok: true, stdout };
+}
+
+function parseTargetList(output: Buffer): string[] {
+  return output
+    .toString('utf-8')
+    .split(/\r?\n/)
+    .map((t) => t.trim())
+    .filter((t) => t.length > 0);
+}
+
+function readClipboardFileMediaViaWlPaste(): ClipboardMedia | null {
+  const list = runCommand('wl-paste', ['--list-types'], {
+    timeoutMs: DEFAULT_LIST_TIMEOUT_MS,
+  });
+  if (!list.ok) return null;
+
+  const types = parseTargetList(list.stdout);
+  const uriType = types.find((t) => baseMimeType(t) === 'text/uri-list');
+  if (uriType === undefined) return null;
+
+  const uris = runCommand('wl-paste', ['--type', uriType, '--no-newline']);
+  return uris.ok ? readMediaFromText(uris.stdout.toString('utf-8')) : null;
+}
+
+function readClipboardImageViaWlPaste(): ClipboardImage | null {
+  const list = runCommand('wl-paste', ['--list-types'], {
+    timeoutMs: DEFAULT_LIST_TIMEOUT_MS,
+  });
+  if (!list.ok) return null;
+
+  const selected = selectPreferredImageMimeType(parseTargetList(list.stdout));
+  if (selected === null) return null;
+
+  const data = runCommand('wl-paste', ['--type', selected, '--no-newline']);
+  if (!data.ok || data.stdout.length === 0) return null;
+  return { kind: 'image', bytes: data.stdout, mimeType: baseMimeType(selected) };
+}
+
+function readClipboardFileMediaViaXclip(): ClipboardMedia | null {
+  const targets = runCommand('xclip', ['-selection', 'clipboard', '-t', 'TARGETS', '-o'], {
+    timeoutMs: DEFAULT_LIST_TIMEOUT_MS,
+  });
+  if (!targets.ok) return null;
+
+  const candidates = parseTargetList(targets.stdout);
+  const uriType = candidates.find((t) => baseMimeType(t) === 'text/uri-list');
+  if (uriType === undefined) return null;
+
+  const uris = runCommand('xclip', ['-selection', 'clipboard', '-t', uriType, '-o']);
+  return uris.ok ? readMediaFromText(uris.stdout.toString('utf-8')) : null;
+}
+
+function readClipboardImageViaXclip(): ClipboardImage | null {
+  const targets = runCommand('xclip', ['-selection', 'clipboard', '-t', 'TARGETS', '-o'], {
+    timeoutMs: DEFAULT_LIST_TIMEOUT_MS,
+  });
+
+  const candidates = targets.ok ? parseTargetList(targets.stdout) : [];
+  const preferred = candidates.length > 0 ? selectPreferredImageMimeType(candidates) : null;
+  const tryTypes =
+    preferred !== null
+      ? [preferred, ...SUPPORTED_IMAGE_MIME_TYPES]
+      : [...SUPPORTED_IMAGE_MIME_TYPES];
+
+  for (const mime of tryTypes) {
+    const data = runCommand('xclip', ['-selection', 'clipboard', '-t', mime, '-o']);
+    if (data.ok && data.stdout.length > 0) {
+      return { kind: 'image', bytes: data.stdout, mimeType: baseMimeType(mime) };
+    }
+  }
+  return null;
+}
+
+/**
+ * Windows clipboard images (Win+Shift+S) don't bridge into the WSL
+ * Linux clipboard. PowerShell reaches the Windows clipboard directly;
+ * we round-trip via a temp PNG because binary stdout is unreliable
+ * across the WSL interop boundary.
+ */
+function readClipboardImageViaPowerShell(): ClipboardImage | null {
+  const tmpFile = join(tmpdir(), `kimi-wsl-clip-${randomUUID()}.png`);
+  try {
+    const winPathResult = runCommand('wslpath', ['-w', tmpFile], {
+      timeoutMs: DEFAULT_LIST_TIMEOUT_MS,
+    });
+    if (!winPathResult.ok) return null;
+    const winPath = winPathResult.stdout.toString('utf-8').trim();
+    if (winPath.length === 0) return null;
+
+    const psScript = [
+      'Add-Type -AssemblyName System.Windows.Forms',
+      'Add-Type -AssemblyName System.Drawing',
+      '$path = $env:KIMI_WSL_CLIPBOARD_IMAGE_PATH',
+      '$img = [System.Windows.Forms.Clipboard]::GetImage()',
+      "if ($img) { $img.Save($path, [System.Drawing.Imaging.ImageFormat]::Png); Write-Output 'ok' } else { Write-Output 'empty' }",
+    ].join('; ');
+
+    const result = runCommand('powershell.exe', ['-NoProfile', '-Command', psScript], {
+      timeoutMs: DEFAULT_POWERSHELL_TIMEOUT_MS,
+      env: { ...process.env, KIMI_WSL_CLIPBOARD_IMAGE_PATH: winPath },
+    });
+    if (!result.ok) return null;
+    if (result.stdout.toString('utf-8').trim() !== 'ok') return null;
+
+    const bytes = readFileSync(tmpFile);
+    if (bytes.length === 0) return null;
+    return { kind: 'image', bytes: new Uint8Array(bytes), mimeType: 'image/png' };
+  } catch {
+    return null;
+  } finally {
+    try {
+      unlinkSync(tmpFile);
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+}
+
+function readClipboardFilePathsViaMacOs(run: RunCommand): string[] {
+  const result = run('osascript', ['-l', 'JavaScript', '-e', MACOS_FILE_PATH_SCRIPT], {
+    timeoutMs: DEFAULT_LIST_TIMEOUT_MS,
+  });
+  if (!result.ok || result.stdout.length === 0) return [];
+  return parseClipboardPaths(result.stdout.toString('utf-8'));
+}
+
+function isFileLikeNativeFormat(format: string): boolean {
+  const f = format.toLowerCase();
+  const base = baseMimeType(format);
+  return (
+    f.includes('file-url') ||
+    f.includes('file url') ||
+    f.includes('nsfilenames') ||
+    f.includes('com.apple.finder') ||
+    base === 'text/uri-list' ||
+    base === 'public.url'
+  );
+}
+
+function safeAvailableFormats(clip: ClipboardModule | null): string[] {
+  if (clip?.availableFormats === undefined) return [];
+  try {
+    return clip.availableFormats();
+  } catch {
+    return [];
+  }
+}
+
+async function readClipboardFileMediaViaNativeText(
+  clip: ClipboardModule | null,
+): Promise<{ media: ClipboardMedia | null; lookedFileLike: boolean }> {
+  if (clip === null) return { media: null, lookedFileLike: false };
+
+  const formats = safeAvailableFormats(clip);
+  const lookedFileLike = formats.some(isFileLikeNativeFormat);
+  if (!lookedFileLike || clip.getText === undefined) {
+    return { media: null, lookedFileLike };
+  }
+
+  try {
+    return { media: readMediaFromText(await clip.getText()), lookedFileLike };
+  } catch (error) {
+    if (error instanceof ClipboardMediaError) throw error;
+    return { media: null, lookedFileLike };
+  }
+}
+
+async function readClipboardImageViaNative(
+  clip: ClipboardModule | null = clipboard,
+): Promise<ClipboardImage | null> {
+  if (clip === null) return null;
+
+  let hasImage = false;
+  try {
+    hasImage = clip.hasImage();
+  } catch {
+    return null;
+  }
+  if (!hasImage) return null;
+
+  try {
+    const data = await clip.getImageBinary();
+    if (data.length === 0) return null;
+    return { kind: 'image', bytes: Uint8Array.from(data), mimeType: 'image/png' };
+  } catch {
+    return null;
+  }
+}
+
+export async function readClipboardMedia(options?: {
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  clipboard?: ClipboardModule | null;
+  runCommand?: RunCommand;
+}): Promise<ClipboardMedia | null> {
+  const env = options?.env ?? process.env;
+  const platform = options?.platform ?? process.platform;
+  const clip = options?.clipboard ?? clipboard;
+  const run = options?.runCommand ?? runCommand;
+
+  // Termux on Android has no desktop clipboard; skip early rather than
+  // churn through every fallback.
+  if (env['TERMUX_VERSION'] !== undefined) return null;
+
+  let image: ClipboardImage | null = null;
+  if (platform === 'linux') {
+    const wayland = isWaylandSession(env);
+    const wsl = isWSL(env);
+
+    if (wayland || wsl) {
+      const fileMedia = readClipboardFileMediaViaWlPaste() ?? readClipboardFileMediaViaXclip();
+      if (fileMedia !== null) return fileMedia;
+      image = readClipboardImageViaWlPaste() ?? readClipboardImageViaXclip();
+    }
+    if (image === null && wsl) {
+      image = readClipboardImageViaPowerShell();
+    }
+    if (image === null && !wayland) {
+      const nativeFileMedia = await readClipboardFileMediaViaNativeText(clip);
+      if (nativeFileMedia.media !== null) return nativeFileMedia.media;
+      if (nativeFileMedia.lookedFileLike) return null;
+      image = await readClipboardImageViaNative(clip);
+    }
+  } else {
+    if (platform === 'darwin') {
+      const fileMedia = readMediaFromPaths(readClipboardFilePathsViaMacOs(run));
+      if (fileMedia !== null) return fileMedia;
+    }
+
+    const nativeFileMedia = await readClipboardFileMediaViaNativeText(clip);
+    if (nativeFileMedia.media !== null) return nativeFileMedia.media;
+
+    // Finder exposes file icons/thumbnails as image data. If the clipboard
+    // looks file-like but we could not read a real file path, do not consume
+    // that icon as an image attachment.
+    if (platform === 'darwin' && nativeFileMedia.lookedFileLike) {
+      return null;
+    }
+
+    image = await readClipboardImageViaNative(clip);
+  }
+
+  if (image === null) return null;
+  if (!isSupportedImageMimeType(image.mimeType)) return null;
+  return image;
+}
diff --git a/apps/kimi-code/src/utils/clipboard/clipboard-native.ts b/apps/kimi-code/src/utils/clipboard/clipboard-native.ts
new file mode 100644
index 000000000..051e9af46
--- /dev/null
+++ b/apps/kimi-code/src/utils/clipboard/clipboard-native.ts
@@ -0,0 +1,51 @@
+/**
+ * Optional native clipboard binding.
+ *
+ * `@mariozechner/clipboard` is a native Node binding that can read image
+ * binaries from the system clipboard on macOS and Windows. It's an
+ * optional dependency — if the native module fails to load (e.g. on a
+ * platform where no prebuilt is available) we degrade to shell-based
+ * fallbacks (wl-paste / xclip / PowerShell) in `clipboard-image.ts`.
+ */
+
+import { createRequire } from 'node:module';
+
+import { loadNativePackage } from '#/native/native-require';
+
+declare const __KIMI_CODE_NATIVE_BUNDLE__: boolean | undefined;
+
+export interface ClipboardModule {
+  availableFormats?(): string[];
+  hasText?(): boolean;
+  getText?(): Promise<string>;
+  hasImage(): boolean;
+  getImageBinary(): Promise<Array<number>>;
+}
+
+const nodeRequire = createRequire(import.meta.url);
+const isNativeBundle =
+  typeof __KIMI_CODE_NATIVE_BUNDLE__ === 'boolean' && __KIMI_CODE_NATIVE_BUNDLE__;
+
+// The native module uses X11/Wayland on Linux; if no display is
+// available, skip the load attempt so headless environments don't pay
+// the binding cost just to fail later.
+const hasDisplay =
+  process.platform !== 'linux' || Boolean(process.env['DISPLAY'] ?? process.env['WAYLAND_DISPLAY']);
+
+const clipboard: ClipboardModule | null = (() => {
+  if (process.env['TERMUX_VERSION'] !== undefined || !hasDisplay) return null;
+  try {
+    const bundledClipboard = loadNativePackage<ClipboardModule>('@mariozechner/clipboard');
+    if (bundledClipboard !== null) return bundledClipboard;
+  } catch {
+    return null;
+  }
+  if (isNativeBundle) return null;
+  try {
+    return nodeRequire('@mariozechner/clipboard') as ClipboardModule;
+  } catch {
+    return null;
+  }
+})();
+
+export { clipboard };
diff --git a/apps/kimi-code/src/utils/git/git-ls-files.ts b/apps/kimi-code/src/utils/git/git-ls-files.ts
new file mode 100644
index 000000000..a68613284
--- /dev/null
+++ b/apps/kimi-code/src/utils/git/git-ls-files.ts
@@ -0,0 +1,189 @@
+/**
+ * Git-aware file listing + relevance signals with a short-TTL cache.
+ * Used as the cross-directory `@file` completion source when `fd` is
+ * not installed.
+ *
+ * Tracks three things per snapshot, all refreshed atomically:
+ *   - `files`            deduped (tracked + untracked-not-ignored), capped at 1000
+ *   - `mtimeByPath`      absolute-path → fs mtime (ms), for recency ranking
+ *   - `recencyOrder`     file path → position in recent git history (0-indexed; smaller = more recent)
+ *
+ * Rebuild strategy: 2s TTL plus `.git/index` mtime invalidation so
+ * rapid edits surface without paying the full spawn+stat cost on every
+ * keystroke. When outside a git worktree,
+ * `getSnapshot()` returns `null` and callers fall back further.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const TTL_MS = 2000;
+const MAX_ENTRIES = 1000;
+// Number of most-recent commits to scan for "recently edited" hotness.
+// 200 is enough to cover a week of active work in a typical repo while
+// staying fast (<100ms even on large repos).
+const RECENT_COMMIT_DEPTH = 200;
+
+export interface GitSnapshot {
+  readonly files: readonly string[];
+  /** Absolute path → mtime (ms). Missing entries = stat failed. */
+  readonly mtimeByPath: ReadonlyMap<string, number>;
+  /** Path → 0-indexed recency rank (earlier = more recent). */
+  readonly recencyOrder: ReadonlyMap<string, number>;
+}
+
+export interface GitLsFilesCache {
+  /** Full snapshot, or `null` when the work dir is not a git repo. */
+  getSnapshot(): GitSnapshot | null;
+  /** Convenience shortcut; identical to `getSnapshot()?.files ?? null`. */
+  list(): string[] | null;
+  isGitRepo(): boolean;
+}
+
+interface SnapshotState {
+  snapshot: GitSnapshot;
+  fetchedAt: number;
+  indexMtime: number;
+}
+
+export function createGitLsFilesCache(workDir: string): GitLsFilesCache {
+  const gitRoot = resolveGitRoot(workDir);
+  const indexPath = gitRoot === null ? null : join(gitRoot, '.git', 'index');
+  let state: SnapshotState | undefined;
+
+  return {
+    isGitRepo: () => gitRoot !== null,
+    getSnapshot: () => {
+      if (gitRoot === null) return null;
+
+      const now = Date.now();
+      const currentIndexMtime = indexMtime(indexPath);
+      const fresh =
+        state !== undefined &&
+        now - state.fetchedAt < TTL_MS &&
+        state.indexMtime === currentIndexMtime;
+      if (fresh) return state!.snapshot;
+
+      const snapshot = fetchSnapshot(gitRoot);
+      if (snapshot === null) return null; // transient git failure — retry next call
+
+      state = { snapshot, fetchedAt: now, indexMtime: currentIndexMtime };
+      return snapshot;
+    },
+    list: function listCompat() {
+      return this.getSnapshot()?.files.slice() ?? null;
+    },
+  };
+}
+
+function resolveGitRoot(workDir: string): string | null {
+  try {
+    const result = spawnSync('git', ['-C', workDir, 'rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+    });
+    if (result.status !== 0) return null;
+    const stdout = result.stdout.trim();
+    return stdout.length > 0 ? stdout : null;
+  } catch {
+    return null;
+  }
+}
+
+function indexMtime(indexPath: string | null): number {
+  if (indexPath === null || !existsSync(indexPath)) return 0;
+  try {
+    return statSync(indexPath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+function fetchSnapshot(gitRoot: string): GitSnapshot | null {
+  const tracked = runLsFiles(gitRoot, ['-z']);
+  if (tracked === null) return null;
+  const untracked = runLsFiles(gitRoot, ['-z', '--others', '--exclude-standard']);
+  if (untracked === null) return null;
+
+  const seen = new Set<string>();
+  for (const path of tracked) seen.add(path);
+  for (const path of untracked) seen.add(path);
+  const merged = [...seen].toSorted();
+  const files = merged.length > MAX_ENTRIES ? merged.slice(0, MAX_ENTRIES) : merged;
+
+  const mtimeByPath = collectMtimes(gitRoot, files);
+  const recencyOrder = collectRecencyOrder(gitRoot, new Set(files));
+
+  return { files, mtimeByPath, recencyOrder };
+}
+
+function runLsFiles(gitRoot: string, args: readonly string[]): string[] | null {
+  try {
+    const result = spawnSync('git', ['-C', gitRoot, 'ls-files', ...args], {
+      encoding: 'utf8',
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    if (result.status !== 0) return null;
+    return result.stdout.split('\0').filter((entry) => entry.length > 0);
+  } catch {
+    return null;
+  }
+}
+
+function collectMtimes(gitRoot: string, files: readonly string[]): Map<string, number> {
+  const result = new Map<string, number>();
+  for (const path of files) {
+    try {
+      const stat = statSync(join(gitRoot, path));
+      result.set(path, stat.mtimeMs);
+    } catch {
+      // File was deleted between ls-files and stat, or permission error.
+      // Missing entry → ranker treats it as "no mtime signal".
+    }
+  }
+  return result;
+}
+
+/**
+ * Walk the last RECENT_COMMIT_DEPTH commits and record the first time
+ * each path is seen (a file touched in HEAD wins over a file touched
+ * 50 commits ago). Runs on the whole repo, not the work dir, so rename
+ * tracking stays consistent even when the user cd's into a subdir.
+ *
+ * `trackedSet` filters out paths that were renamed away / deleted — we
+ * only care about files that still appear in `ls-files`, since those
+ * are the ones we could actually complete.
+ */
+function collectRecencyOrder(gitRoot: string, trackedSet: Set<string>): Map<string, number> {
+  const result = new Map<string, number>();
+  try {
+    const proc = spawnSync(
+      'git',
+      [
+        '-C',
+        gitRoot,
+        'log',
+        `-n`,
+        String(RECENT_COMMIT_DEPTH),
+        '--name-only',
+        '--pretty=format:',
+        '--no-renames',
+      ],
+      { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 },
+    );
+    if (proc.status !== 0) return result;
+    let rank = 0;
+    for (const raw of proc.stdout.split('\n')) {
+      const line = raw.trim();
+      if (line.length === 0) continue;
+      if (result.has(line)) continue; // keep the earliest (most recent) occurrence
+      if (!trackedSet.has(line)) continue; // drop deleted / renamed-away paths
+      result.set(line, rank);
+      rank += 1;
+    }
+  } catch {
+    // Fall through with whatever we've collected — an incomplete
+    // recency map just means fewer entries get a hotness boost.
+  }
+  return result;
+}
diff --git a/apps/kimi-code/src/utils/git/git-status.ts b/apps/kimi-code/src/utils/git/git-status.ts
new file mode 100644
index 000000000..d78358b11
--- /dev/null
+++ b/apps/kimi-code/src/utils/git/git-status.ts
@@ -0,0 +1,351 @@
+/**
+ * Cached git branch + working-tree status for the footer/statusline.
+ *
+ * Branch name refreshes every 5s, porcelain status every 15s. Branch
+ * and status reads stay synchronous with short timeouts. Pull request
+ * lookup uses an async cache so a slow `gh pr view` never blocks
+ * footer rendering.
+ */
+
+import { execFile, spawnSync } from 'node:child_process';
+
+const BRANCH_TTL_MS = 5_000;
+const STATUS_TTL_MS = 15_000;
+const PULL_REQUEST_TTL_MS = 60_000;
+const SPAWN_TIMEOUT_MS = 500;
+const PR_SPAWN_TIMEOUT_MS = 5_000;
+
+export interface GitStatus {
+  readonly branch: string;
+  readonly dirty: boolean;
+  readonly ahead: number;
+  readonly behind: number;
+  readonly diffAdded: number;
+  readonly diffDeleted: number;
+  readonly pullRequest: PullRequestInfo | null;
+}
+
+export interface PullRequestInfo {
+  readonly number: number;
+  readonly url: string;
+}
+
+export interface GitStatusCache {
+  /** Returns current status, or `null` when workDir is not a git repo. */
+  getStatus(): GitStatus | null;
+}
+
+export interface GitStatusCacheOptions {
+  readonly onChange?: () => void;
+}
+
+interface BranchState {
+  value: string | null;
+  fetchedAt: number;
+}
+
+interface StatusState {
+  dirty: boolean;
+  ahead: number;
+  behind: number;
+  diffAdded: number;
+  diffDeleted: number;
+  fetchedAt: number;
+}
+
+interface PullRequestState {
+  value: PullRequestInfo | null;
+  branch: string | null;
+  fetchedAt: number;
+  pendingBranch: string | null;
+  requestId: number;
+}
+
+const AHEAD_BEHIND_RE = /\[(?:ahead (\d+))?(?:, )?(?:behind (\d+))?\]/;
+
+export function createGitStatusCache(
+  workDir: string,
+  options: GitStatusCacheOptions = {},
+): GitStatusCache {
+  const isRepo = detectGitRepo(workDir);
+  let branch: BranchState = { value: null, fetchedAt: 0 };
+  let status: StatusState = {
+    dirty: false,
+    ahead: 0,
+    behind: 0,
+    diffAdded: 0,
+    diffDeleted: 0,
+    fetchedAt: 0,
+  };
+  let pullRequest: PullRequestState = {
+    value: null,
+    branch: null,
+    fetchedAt: 0,
+    pendingBranch: null,
+    requestId: 0,
+  };
+
+  return {
+    getStatus: () => {
+      if (!isRepo) return null;
+
+      const now = Date.now();
+      if (now - branch.fetchedAt >= BRANCH_TTL_MS) {
+        branch = { value: readBranch(workDir), fetchedAt: now };
+      }
+      if (branch.value === null) return null;
+
+      if (now - status.fetchedAt >= STATUS_TTL_MS) {
+        status = { ...readStatus(workDir), fetchedAt: now };
+      }
+      refreshPullRequestIfNeeded(branch.value, now);
+
+      return {
+        branch: branch.value,
+        dirty: status.dirty,
+        ahead: status.ahead,
+        behind: status.behind,
+        diffAdded: status.diffAdded,
+        diffDeleted: status.diffDeleted,
+        pullRequest: pullRequest.branch === branch.value ? pullRequest.value : null,
+      };
+    },
+  };
+
+  function refreshPullRequestIfNeeded(branchName: string, now: number): void {
+    if (pullRequest.pendingBranch === branchName) return;
+    const fetchedAt = pullRequest.branch === branchName ? pullRequest.fetchedAt : 0;
+    if (now - fetchedAt < PULL_REQUEST_TTL_MS) return;
+
+    const requestId = pullRequest.requestId + 1;
+    pullRequest = {
+      value: pullRequest.branch === branchName ? pullRequest.value : null,
+      branch: branchName,
+      fetchedAt,
+      pendingBranch: branchName,
+      requestId,
+    };
+
+    void readPullRequest(workDir).then((value) => {
+      if (pullRequest.requestId !== requestId) return;
+
+      const previous = pullRequest.branch === branchName ? pullRequest.value : null;
+      const changed = !samePullRequest(previous, value);
+      pullRequest = {
+        value,
+        branch: branchName,
+        fetchedAt: Date.now(),
+        pendingBranch: null,
+        requestId,
+      };
+      if (changed) options.onChange?.();
+    });
+  }
+}
+
+function detectGitRepo(workDir: string): boolean {
+  try {
+    const result = spawnSync('git', ['-C', workDir, 'rev-parse', '--is-inside-work-tree'], {
+      encoding: 'utf8',
+      timeout: SPAWN_TIMEOUT_MS,
+    });
+    return result.status === 0 && result.stdout.trim() === 'true';
+  } catch {
+    return false;
+  }
+}
+
+function readBranch(workDir: string): string | null {
+  try {
+    const result = spawnSync('git', ['-C', workDir, 'branch', '--show-current'], {
+      encoding: 'utf8',
+      timeout: SPAWN_TIMEOUT_MS,
+    });
+    if (result.status !== 0) return null;
+    const name = result.stdout.trim();
+    return name.length > 0 ? name : null;
+  } catch {
+    return null;
+  }
+}
+
+function readStatus(workDir: string): {
+  dirty: boolean;
+  ahead: number;
+  behind: number;
+  diffAdded: number;
+  diffDeleted: number;
+} {
+  try {
+    const result = spawnSync('git', ['-C', workDir, 'status', '--porcelain', '-b'], {
+      encoding: 'utf8',
+      timeout: SPAWN_TIMEOUT_MS,
+      maxBuffer: 4 * 1024 * 1024,
+    });
+    if (result.status !== 0) {
+      return { dirty: false, ahead: 0, behind: 0, diffAdded: 0, diffDeleted: 0 };
+    }
+
+    let dirty = false;
+    let ahead = 0;
+    let behind = 0;
+    for (const line of result.stdout.split('\n')) {
+      if (line.startsWith('## ')) {
+        const m = AHEAD_BEHIND_RE.exec(line);
+        if (m) {
+          ahead = Number.parseInt(m[1] ?? '0', 10) || 0;
+          behind = Number.parseInt(m[2] ?? '0', 10) || 0;
+        }
+      } else if (line.trim().length > 0) {
+        dirty = true;
+      }
+    }
+    const diff = dirty ? readDiffStats(workDir) : { added: 0, deleted: 0 };
+    return {
+      dirty,
+      ahead,
+      behind,
+      diffAdded: diff.added,
+      diffDeleted: diff.deleted,
+    };
+  } catch {
+    return { dirty: false, ahead: 0, behind: 0, diffAdded: 0, diffDeleted: 0 };
+  }
+}
+
+function readDiffStats(workDir: string): { added: number; deleted: number } {
+  try {
+    const result = spawnSync('git', ['-C', workDir, 'diff', '--numstat', 'HEAD', '--'], {
+      encoding: 'utf8',
+      timeout: SPAWN_TIMEOUT_MS,
+      maxBuffer: 4 * 1024 * 1024,
+    });
+    if (result.status !== 0) return { added: 0, deleted: 0 };
+
+    let added = 0;
+    let deleted = 0;
+    for (const line of result.stdout.split('\n')) {
+      if (!line) continue;
+      const [addedText, deletedText] = line.split('\t');
+      added += parseDiffNumstatCount(addedText);
+      deleted += parseDiffNumstatCount(deletedText);
+    }
+    return { added, deleted };
+  } catch {
+    return { added: 0, deleted: 0 };
+  }
+}
+
+function parseDiffNumstatCount(value: string | undefined): number {
+  if (value === undefined || value === '-') return 0;
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+function readPullRequest(workDir: string): Promise<PullRequestInfo | null> {
+  return new Promise((resolve) => {
+    execFile(
+      'gh',
+      ['pr', 'view', '--json', 'number,url'],
+      {
+        cwd: workDir,
+        encoding: 'utf8',
+        env: {
+          ...process.env,
+          GH_NO_UPDATE_NOTIFIER: '1',
+          GH_PROMPT_DISABLED: '1',
+        },
+        timeout: PR_SPAWN_TIMEOUT_MS,
+        maxBuffer: 256 * 1024,
+      },
+      (error, stdout) => {
+        if (error !== null) {
+          resolve(null);
+          return;
+        }
+        resolve(parsePullRequest(stdout));
+      },
+    );
+  });
+}
+
+function samePullRequest(a: PullRequestInfo | null, b: PullRequestInfo | null): boolean {
+  if (a === null || b === null) return a === b;
+  return a.number === b.number && a.url === b.url;
+}
+
+function parsePullRequest(stdout: string): PullRequestInfo | null {
+  try {
+    const raw = JSON.parse(stdout) as unknown;
+    if (typeof raw !== 'object' || raw === null) return null;
+    const record = raw as Record<string, unknown>;
+    const number = record['number'];
+    const url = record['url'];
+    if (typeof number !== 'number' || !Number.isInteger(number) || number <= 0) return null;
+    if (typeof url !== 'string' || !isSafeHttpUrl(url)) return null;
+    return { number, url };
+  } catch {
+    return null;
+  }
+}
+
+function isSafeHttpUrl(value: string): boolean {
+  if (hasControlChars(value)) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' || url.protocol === 'http:';
+  } catch {
+    return false;
+  }
+}
+
+function hasControlChars(value: string): boolean {
+  for (const char of value) {
+    const code = char.codePointAt(0) ?? 0;
+    if (code <= 0x1f || code === 0x7f) return true;
+  }
+  return false;
+}
+
+export interface FormatGitBadgeOptions {
+  readonly linkPullRequest?: boolean;
+}
+
+export function formatGitBadgeBase(status: GitStatus): string {
+  const parts: string[] = [];
+  const diff = formatDiffStats(status);
+  if (diff) parts.push(diff);
+  let sync = '';
+  if (status.ahead > 0) sync += `↑${status.ahead}`;
+  if (status.behind > 0) sync += `↓${status.behind}`;
+  if (sync) parts.push(sync);
+  return parts.length === 0 ? status.branch : `${status.branch} [${parts.join(' ')}]`;
+}
+
+export function formatPullRequestBadge(
+  pullRequest: PullRequestInfo,
+  options: FormatGitBadgeOptions = {},
+): string {
+  const prText = `[PR#${String(pullRequest.number)}]`;
+  return options.linkPullRequest ? toTerminalHyperlink(prText, pullRequest.url) : prText;
+}
+
+export function formatGitBadge(status: GitStatus, options: FormatGitBadgeOptions = {}): string {
+  const base = formatGitBadgeBase(status);
+  if (status.pullRequest === null) return base;
+
+  return `${base} ${formatPullRequestBadge(status.pullRequest, options)}`;
+}
+
+function formatDiffStats(status: GitStatus): string | null {
+  const parts: string[] = [];
+  if (status.diffAdded > 0) parts.push(`+${String(status.diffAdded)}`);
+  if (status.diffDeleted > 0) parts.push(`-${String(status.diffDeleted)}`);
+  if (parts.length > 0) return parts.join(' ');
+  return status.dirty ? '±' : null;
+}
+
+function toTerminalHyperlink(text: string, url: string): string {
+  if (!isSafeHttpUrl(url)) return text;
+  return `\u001B]8;;${url}\u0007${text}\u001B]8;;\u0007`;
+}
diff --git a/apps/kimi-code/src/utils/history/input-history.ts b/apps/kimi-code/src/utils/history/input-history.ts
new file mode 100644
index 000000000..950542563
--- /dev/null
+++ b/apps/kimi-code/src/utils/history/input-history.ts
@@ -0,0 +1,42 @@
+/**
+ * User input history persistence — JSONL file with `{"content": "..."}` per line.
+ *
+ * Semantics:
+ * - One JSON object per line (`InputHistoryEntry { content }`)
+ * - Append-only writes
+ * - Skip empty entries
+ * - Skip when same as last entry (consecutive deduplication)
+ * - Tolerate corrupt lines: log + skip, do not abort load
+ */
+
+import { z } from 'zod';
+
+import { appendJsonlLine, readJsonlFile } from '#/utils/persistence';
+
+export interface InputHistoryEntry {
+  content: string;
+}
+
+const InputHistoryEntrySchema: z.ZodType<InputHistoryEntry> = z.object({
+  content: z.string(),
+});
+
+export async function loadInputHistory(file: string): Promise<InputHistoryEntry[]> {
+  return readJsonlFile(file, InputHistoryEntrySchema);
+}
+
+/**
+ * Append an entry to the history file. Returns true if written, false if
+ * skipped (empty or equal to `lastContent`).
+ */
+export async function appendInputHistory(
+  file: string,
+  text: string,
+  lastContent?: string,
+): Promise<boolean> {
+  const content = text.trim();
+  if (content.length === 0) return false;
+  if (content === lastContent) return false;
+  await appendJsonlLine(file, InputHistoryEntrySchema, { content });
+  return true;
+}
diff --git a/apps/kimi-code/src/utils/image/image-mime.ts b/apps/kimi-code/src/utils/image/image-mime.ts
new file mode 100644
index 000000000..e7ceb97de
--- /dev/null
+++ b/apps/kimi-code/src/utils/image/image-mime.ts
@@ -0,0 +1,189 @@
+/**
+ * Detect image MIME type + dimensions from raw bytes.
+ *
+ * Uses magic-byte sniffing for MIME and minimal format-specific parsing
+ * for dimensions. Only formats that the kimi-core multimodal pipeline
+ * accepts are supported: PNG / JPEG / GIF / WebP.
+ *
+ * Unsupported or truncated inputs return `null` so the caller can
+ * decline the paste cleanly.
+ */
+
+export type SupportedImageMime = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+
+export interface ImageMeta {
+  mime: SupportedImageMime;
+  width: number;
+  height: number;
+}
+
+export function parseImageMeta(bytes: Uint8Array): ImageMeta | null {
+  if (isPng(bytes)) return parsePng(bytes);
+  if (isJpeg(bytes)) return parseJpeg(bytes);
+  if (isGif(bytes)) return parseGif(bytes);
+  if (isWebp(bytes)) return parseWebp(bytes);
+  return null;
+}
+
+// ── PNG ─────────────────────────────────────────────────────────────
+
+function isPng(b: Uint8Array): boolean {
+  return (
+    b.length >= 8 &&
+    b[0] === 0x89 &&
+    b[1] === 0x50 &&
+    b[2] === 0x4e &&
+    b[3] === 0x47 &&
+    b[4] === 0x0d &&
+    b[5] === 0x0a &&
+    b[6] === 0x1a &&
+    b[7] === 0x0a
+  );
+}
+
+function parsePng(b: Uint8Array): ImageMeta | null {
+  // IHDR chunk immediately follows the 8-byte signature: length (4) +
+  // "IHDR" (4) + width (4 BE) + height (4 BE) + ...
+  if (b.length < 24) return null;
+  const width = readUInt32BE(b, 16);
+  const height = readUInt32BE(b, 20);
+  if (width <= 0 || height <= 0) return null;
+  return { mime: 'image/png', width, height };
+}
+
+// ── JPEG ────────────────────────────────────────────────────────────
+
+function isJpeg(b: Uint8Array): boolean {
+  return b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff;
+}
+
+function parseJpeg(b: Uint8Array): ImageMeta | null {
+  // Scan for a Start-Of-Frame marker (SOF0..SOF3, SOF5..SOF7, SOF9..SOF11,
+  // SOF13..SOF15). After the marker + 2-byte segment length come:
+  //   precision (1), height (2 BE), width (2 BE), components (1).
+  let i = 2;
+  while (i < b.length) {
+    if (b[i] !== 0xff) {
+      i += 1;
+      continue;
+    }
+    // Skip fill bytes (0xFF padding before a marker).
+    while (i < b.length && b[i] === 0xff) i += 1;
+    if (i >= b.length) return null;
+    const marker = b[i]!;
+    i += 1;
+    if (marker === 0xd8 || marker === 0xd9) continue; // SOI / EOI — no length
+    if (i + 1 >= b.length) return null;
+    const segLen = readUInt16BE(b, i);
+    if (isSofMarker(marker)) {
+      if (i + 7 >= b.length) return null;
+      const height = readUInt16BE(b, i + 3);
+      const width = readUInt16BE(b, i + 5);
+      if (width <= 0 || height <= 0) return null;
+      return { mime: 'image/jpeg', width, height };
+    }
+    i += segLen;
+  }
+  return null;
+}
+
+function isSofMarker(marker: number): boolean {
+  if (marker < 0xc0 || marker > 0xcf) return false;
+  // Exclude DHT (0xC4), JPG (0xC8), DAC (0xCC) — these reuse the SOF
+  // number range but are not frame headers.
+  return marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+}
+
+// ── GIF ─────────────────────────────────────────────────────────────
+
+function isGif(b: Uint8Array): boolean {
+  return (
+    b.length >= 6 &&
+    b[0] === 0x47 && // G
+    b[1] === 0x49 && // I
+    b[2] === 0x46 && // F
+    b[3] === 0x38 && // 8
+    (b[4] === 0x37 || b[4] === 0x39) && // 7 or 9
+    b[5] === 0x61 // a
+  );
+}
+
+function parseGif(b: Uint8Array): ImageMeta | null {
+  // Logical screen width/height are at offsets 6-9, little-endian.
+  if (b.length < 10) return null;
+  const width = readUInt16LE(b, 6);
+  const height = readUInt16LE(b, 8);
+  if (width <= 0 || height <= 0) return null;
+  return { mime: 'image/gif', width, height };
+}
+
+// ── WebP ────────────────────────────────────────────────────────────
+
+function isWebp(b: Uint8Array): boolean {
+  return (
+    b.length >= 12 &&
+    b[0] === 0x52 && // R
+    b[1] === 0x49 && // I
+    b[2] === 0x46 && // F
+    b[3] === 0x46 && // F
+    b[8] === 0x57 && // W
+    b[9] === 0x45 && // E
+    b[10] === 0x42 && // B
+    b[11] === 0x50 // P
+  );
+}
+
+function parseWebp(b: Uint8Array): ImageMeta | null {
+  // WebP has three sub-formats: VP8 (simple), VP8L (lossless), VP8X
+  // (extended). Offset 12 is the 4-byte chunk identifier.
+  if (b.length < 30) return null;
+  const chunk = String.fromCodePoint(b[12]!, b[13]!, b[14]!, b[15]!);
+  if (chunk === 'VP8 ') {
+    // Frame data starts at offset 20 + 3-byte start code; dimensions at
+    // offsets 26-29 (little-endian, 14-bit values with 2 top bits masked).
+    const widthRaw = readUInt16LE(b, 26);
+    const heightRaw = readUInt16LE(b, 28);
+    const width = widthRaw & 0x3fff;
+    const height = heightRaw & 0x3fff;
+    if (width <= 0 || height <= 0) return null;
+    return { mime: 'image/webp', width, height };
+  }
+  if (chunk === 'VP8L') {
+    // VP8L packs width-1 (14 bits) and height-1 (14 bits) across bytes 21-24
+    // starting from the signature byte at offset 20 (0x2F).
+    if (b[20] !== 0x2f) return null;
+    const b1 = b[21]!;
+    const b2 = b[22]!;
+    const b3 = b[23]!;
+    const b4 = b[24]!;
+    const width = 1 + (((b2 & 0x3f) << 8) | b1);
+    const height = 1 + (((b4 & 0x0f) << 10) | (b3 << 2) | ((b2 & 0xc0) >> 6));
+    if (width <= 0 || height <= 0) return null;
+    return { mime: 'image/webp', width, height };
+  }
+  if (chunk === 'VP8X') {
+    // Canvas width-1 at offsets 24-26, height-1 at 27-29 (24-bit LE).
+    const width = 1 + readUInt24LE(b, 24);
+    const height = 1 + readUInt24LE(b, 27);
+    if (width <= 0 || height <= 0) return null;
+    return { mime: 'image/webp', width, height };
+  }
+  return null;
+}
+
+// ── byte helpers ────────────────────────────────────────────────────
+
+function readUInt16BE(b: Uint8Array, off: number): number {
+  return (b[off]! << 8) | b[off + 1]!;
+}
+function readUInt16LE(b: Uint8Array, off: number): number {
+  return b[off]! | (b[off + 1]! << 8);
+}
+function readUInt24LE(b: Uint8Array, off: number): number {
+  return b[off]! | (b[off + 1]! << 8) | (b[off + 2]! << 16);
+}
+function readUInt32BE(b: Uint8Array, off: number): number {
+  return Math.trunc(
+    b[off]! * 0x100_0000 + (b[off + 1]! << 16) + (b[off + 2]! << 8) + b[off + 3]!,
+  );
+}
diff --git a/apps/kimi-code/src/utils/paths.ts b/apps/kimi-code/src/utils/paths.ts
new file mode 100644
index 000000000..b0375d376
--- /dev/null
+++ b/apps/kimi-code/src/utils/paths.ts
@@ -0,0 +1,55 @@
+/**
+ * CLI-owned data path helpers.
+ *
+ * These paths are for local app data such as logs and input history. Config
+ * files are owned by Core/SDK and intentionally do not live behind this module.
+ */
+
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  KIMI_CODE_DATA_DIR_NAME,
+  KIMI_CODE_HOME_ENV,
+  KIMI_CODE_INPUT_HISTORY_DIR_NAME,
+  KIMI_CODE_LOG_DIR_NAME,
+  KIMI_CODE_UPDATE_DIR_NAME,
+  KIMI_CODE_UPDATE_STATE_FILE_NAME,
+} from '#/constant/app';
+
+/**
+ * Return the root data directory for Kimi Code.
+ *
+ * Priority: `KIMI_CODE_HOME` env var > `~/.kimi-code`.
+ */
+export function getDataDir(): string {
+  const envDir = process.env[KIMI_CODE_HOME_ENV];
+  if (envDir) {
+    return envDir;
+  }
+  return join(homedir(), KIMI_CODE_DATA_DIR_NAME);
+}
+
+/**
+ * Return the diagnostic log directory: `<dataDir>/logs/`.
+ */
+export function getLogDir(): string {
+  return join(getDataDir(), KIMI_CODE_LOG_DIR_NAME);
+}
+
+/**
+ * Return the update cache file: `<dataDir>/updates/latest.json`.
+ */
+export function getUpdateStateFile(): string {
+  return join(getDataDir(), KIMI_CODE_UPDATE_DIR_NAME, KIMI_CODE_UPDATE_STATE_FILE_NAME);
+}
+
+/**
+ * Return the user input history file for a given working directory.
+ * Layout: `<share_dir>/user-history/<md5(cwd)>.jsonl`.
+ */
+export function getInputHistoryFile(workDir: string): string {
+  const hash = createHash('md5').update(workDir, 'utf-8').digest('hex');
+  return join(getDataDir(), KIMI_CODE_INPUT_HISTORY_DIR_NAME, `${hash}.jsonl`);
+}
diff --git a/apps/kimi-code/src/utils/persistence.ts b/apps/kimi-code/src/utils/persistence.ts
new file mode 100644
index 000000000..a458ae02a
--- /dev/null
+++ b/apps/kimi-code/src/utils/persistence.ts
@@ -0,0 +1,105 @@
+/**
+ * Small persistence helpers for CLI-owned data files.
+ *
+ * This module is intentionally for non-config files only. User-facing
+ * configuration is owned by core/SDK; do not route `config.toml` through
+ * these helpers.
+ */
+
+import { appendFile, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+
+import type { z } from 'zod';
+
+function isNotFound(error: unknown): boolean {
+  return (
+    typeof error === 'object' && error !== null && (error as { code?: string }).code === 'ENOENT'
+  );
+}
+
+function assertNonConfigWrite(filePath: string): void {
+  if (basename(filePath) === 'config.toml') {
+    throw new Error(
+      'CLI persistence helpers must not write config.toml; use core/SDK config APIs.',
+    );
+  }
+}
+
+function tempPathFor(filePath: string): string {
+  const dir = dirname(filePath);
+  const base = basename(filePath);
+  const nonce = `${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}`;
+  return join(dir, `.${base}.${nonce}.tmp`);
+}
+
+export async function readJsonFile<T>(
+  filePath: string,
+  schema: z.ZodType<T>,
+  fallback: T,
+): Promise<T> {
+  let raw: string;
+  try {
+    raw = await readFile(filePath, 'utf-8');
+  } catch (error) {
+    if (isNotFound(error)) return fallback;
+    throw error;
+  }
+  const parsed = JSON.parse(raw) as unknown;
+  return schema.parse(parsed);
+}
+
+export async function writeJsonFile<T>(
+  filePath: string,
+  schema: z.ZodType<T>,
+  value: T,
+): Promise<void> {
+  assertNonConfigWrite(filePath);
+  const parsed = schema.parse(value);
+  await mkdir(dirname(filePath), { recursive: true });
+  const tmpPath = tempPathFor(filePath);
+  try {
+    await writeFile(tmpPath, `${JSON.stringify(parsed, null, 2)}\n`, 'utf-8');
+    await rename(tmpPath, filePath);
+  } catch (error) {
+    await unlink(tmpPath).catch(() => {});
+    throw error;
+  }
+}
+
+export async function readJsonlFile<T>(
+  filePath: string,
+  lineSchema: z.ZodType<T>,
+): Promise<T[]> {
+  let raw: string;
+  try {
+    raw = await readFile(filePath, 'utf-8');
+  } catch (error) {
+    if (isNotFound(error)) return [];
+    throw error;
+  }
+
+  const entries: T[] = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      const parsed = JSON.parse(trimmed) as unknown;
+      const result = lineSchema.safeParse(parsed);
+      if (result.success) entries.push(result.data);
+    } catch {
+      // JSONL is append-only user data; tolerate bad rows and keep the rest.
+    }
+  }
+  return entries;
+}
+
+export async function appendJsonlLine<T>(
+  filePath: string,
+  lineSchema: z.ZodType<T>,
+  value: T,
+): Promise<void> {
+  assertNonConfigWrite(filePath);
+  const parsed = lineSchema.parse(value);
+  await mkdir(dirname(filePath), { recursive: true });
+  await appendFile(filePath, `${JSON.stringify(parsed)}\n`, 'utf-8');
+}
diff --git a/apps/kimi-code/src/utils/process/external-editor.ts b/apps/kimi-code/src/utils/process/external-editor.ts
new file mode 100644
index 000000000..7aa895d3c
--- /dev/null
+++ b/apps/kimi-code/src/utils/process/external-editor.ts
@@ -0,0 +1,60 @@
+/**
+ * External-editor helper — spawn $VISUAL / $EDITOR (or a configured
+ * command) on a temp file seeded with the current editor buffer, then
+ * read the edited contents back.
+ *
+ * Resolution priority:
+ *   configured (from Core/SDK defaults or `/editor`) >
+ *   $VISUAL > $EDITOR > undefined (caller handles "no editor" toast).
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export function resolveEditorCommand(configured?: string | null): string | undefined {
+  const candidates = [configured, process.env['VISUAL'], process.env['EDITOR']];
+  for (const c of candidates) {
+    if (typeof c === 'string' && c.trim().length > 0) {
+      return c.trim();
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Launch `command` (tokenised via a shell) against a temp file seeded
+ * with `initialText`. Returns the edited contents on success, or
+ * `undefined` if the editor exited non-zero / the file disappeared.
+ *
+ * The command is passed to `/bin/sh -c "<cmd> <tmpfile>"` so users can
+ * supply argv-style strings like `"code --wait"` or `"nvim +set ft=markdown"`.
+ */
+export async function editInExternalEditor(
+  initialText: string,
+  command: string,
+): Promise<string | undefined> {
+  const dir = await mkdtemp(join(tmpdir(), 'kimi-edit-'));
+  const file = join(dir, 'prompt.md');
+  await writeFile(file, initialText, 'utf-8');
+  try {
+    const code = await new Promise<number>((resolve, reject) => {
+      const shellCmd = `${command} ${shellQuote(file)}`;
+      const child = spawn('/bin/sh', ['-c', shellCmd], { stdio: 'inherit' });
+      child.on('exit', (c) =>{  resolve(c ?? 0); });
+      child.on('error', reject);
+    });
+    if (code !== 0) return undefined;
+    return await readFile(file, 'utf-8');
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch(() => {
+      // best-effort cleanup
+    });
+  }
+}
+
+function shellQuote(path: string): string {
+  // Single-quote and escape any embedded single quotes.
+  return `'${path.replaceAll('\'', "'\\''")}'`;
+}
diff --git a/apps/kimi-code/src/utils/process/fd-detect.ts b/apps/kimi-code/src/utils/process/fd-detect.ts
new file mode 100644
index 000000000..d8fc662b5
--- /dev/null
+++ b/apps/kimi-code/src/utils/process/fd-detect.ts
@@ -0,0 +1,28 @@
+/**
+ * Probe for the `fd` binary so the pi-tui `CombinedAutocompleteProvider`
+ * can enable its cross-directory fuzzy file search.
+ *
+ * Naming differs across distros:
+ *   - Homebrew / Arch / most Linuxes: `fd`
+ *   - Debian / Ubuntu:                `fdfind`
+ *
+ * We use `spawnSync(..., { stdio: 'ignore' })` rather than shelling out
+ * to `which` so the check doesn't depend on the parent shell's PATH
+ * resolution semantics and stays cheap (~ms) on startup.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+const CANDIDATES = ['fd', 'fdfind'];
+
+export function detectFdPath(): string | null {
+  for (const name of CANDIDATES) {
+    try {
+      const result = spawnSync(name, ['--version'], { stdio: 'ignore' });
+      if (result.status === 0) return name;
+    } catch {
+      // ENOENT, EACCES, etc. — try next candidate
+    }
+  }
+  return null;
+}
diff --git a/apps/kimi-code/src/utils/process/proctitle.ts b/apps/kimi-code/src/utils/process/proctitle.ts
new file mode 100644
index 000000000..b731233af
--- /dev/null
+++ b/apps/kimi-code/src/utils/process/proctitle.ts
@@ -0,0 +1,31 @@
+/**
+ * Early-startup process name initialization.
+ *
+ * Sets the process title so `ps`/`top` and the terminal tab show
+ * `Kimi Code` from the moment the binary launches — before Commander
+ * parses argv, before any preflight, even on `--help`/`--version`.
+ *
+ * OSC is written to stderr (not stdout) so it still reaches the terminal
+ * when stdout is piped, e.g. `kimi --print | grep ...`.
+ */
+import { PRODUCT_NAME } from '#/constant/app';
+import { BEL, ESC } from '#/constant/terminal';
+
+export function setProcessTitle(label: string): void {
+  try {
+    process.title = label;
+  } catch {
+    /* noop */
+  }
+  try {
+    if (process.stderr.isTTY) {
+      process.stderr.write(`${ESC}]0;${label}${BEL}`);
+    }
+  } catch {
+    /* noop */
+  }
+}
+
+export function initProcessName(name: string = PRODUCT_NAME): void {
+  setProcessTitle(name);
+}
diff --git a/apps/kimi-code/src/utils/process/stdin.ts b/apps/kimi-code/src/utils/process/stdin.ts
new file mode 100644
index 000000000..c59792f2a
--- /dev/null
+++ b/apps/kimi-code/src/utils/process/stdin.ts
@@ -0,0 +1,18 @@
+import { createInterface } from 'node:readline';
+
+export function readStdinText(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    process.stdin.on('data', (chunk: Buffer) => chunks.push(chunk));
+    process.stdin.on('end', () =>{  resolve(Buffer.concat(chunks).toString('utf-8').trim()); });
+    process.stdin.on('error', reject);
+    process.stdin.resume();
+  });
+}
+
+export async function* createStdinLineReader(): AsyncIterable<string> {
+  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  for await (const line of rl) {
+    yield line;
+  }
+}
diff --git a/apps/kimi-code/src/utils/usage/usage-format.ts b/apps/kimi-code/src/utils/usage/usage-format.ts
new file mode 100644
index 000000000..34db897a2
--- /dev/null
+++ b/apps/kimi-code/src/utils/usage/usage-format.ts
@@ -0,0 +1,37 @@
+/**
+ * Formatting helpers for the `/usage` slash command.
+ *
+ * Kept pure + ANSI-free so they're trivial to unit-test; the slash
+ * command itself chalks the colour afterwards.
+ */
+
+export function formatTokenCount(n: number): string {
+  if (!Number.isFinite(n) || n < 0) return '0';
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(Math.round(n));
+}
+
+/**
+ * Build a `[███░░░░░░░]` style bar. Returns a plain-ASCII string with
+ * `filled`/`empty` glyphs — colouring is the caller's responsibility.
+ */
+export function renderProgressBar(ratio: number, width = 20, filled = '█', empty = '░'): string {
+  const clamped = safeUsageRatio(ratio);
+  const filledCount = Math.round(clamped * width);
+  return filled.repeat(filledCount) + empty.repeat(Math.max(0, width - filledCount));
+}
+
+export function safeUsageRatio(ratio: number): number {
+  return Number.isFinite(ratio) ? Math.max(0, Math.min(ratio, 1)) : 0;
+}
+
+/**
+ * Map a usage ratio to a semantic colour token — the `/usage` renderer
+ * translates these into palette hex values.
+ */
+export function ratioSeverity(ratio: number): 'ok' | 'warn' | 'danger' {
+  if (ratio >= 0.85) return 'danger';
+  if (ratio >= 0.5) return 'warn';
+  return 'ok';
+}
diff --git a/apps/kimi-code/test/cli/export.test.ts b/apps/kimi-code/test/cli/export.test.ts
new file mode 100644
index 000000000..4a124cc80
--- /dev/null
+++ b/apps/kimi-code/test/cli/export.test.ts
@@ -0,0 +1,446 @@
+/**
+ * `kimi export`
+ *
+ * Verifies the CLI layer: argument handling, previous-session confirmation,
+ * error reporting, and delegation to the session export implementation.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type { createKimiDeviceId as createKimiDeviceIdFn } from '@moonshot-ai/kimi-code-oauth';
+import { Command } from 'commander';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { handleExport, registerExportCommand } from '#/cli/sub/export';
+import type { ExportDeps } from '#/cli/sub/export';
+import type {
+  ExportSessionInput,
+  ExportSessionManifest,
+  ExportSessionResult,
+  SessionSummary,
+} from '@moonshot-ai/kimi-code-sdk';
+
+let tmp: string;
+
+type CreateKimiDeviceId = typeof createKimiDeviceIdFn;
+
+const mocks = vi.hoisted(() => ({
+  kimiHarnessConstructor: vi.fn(),
+  harnessEnsureConfigFile: vi.fn(),
+  harnessGetConfig: vi.fn(async () => ({
+    providers: {},
+    defaultModel: 'k2',
+    telemetry: true,
+  })),
+  harnessGetCachedAccessToken: vi.fn(),
+  harnessExportSession: vi.fn(),
+  createKimiDeviceId: vi.fn<CreateKimiDeviceId>(() => 'device-1'),
+  initializeTelemetry: vi.fn(),
+  shutdownTelemetry: vi.fn(),
+  telemetryTrack: vi.fn(),
+  setTelemetryContext: vi.fn(),
+  withTelemetryContext: vi.fn(),
+}));
+
+vi.mock('@moonshot-ai/kimi-code-sdk', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@moonshot-ai/kimi-code-sdk')>();
+  return {
+    ...actual,
+    KimiHarness: class {
+      homeDir = '/tmp/kimi-export-home';
+      auth = {
+        getCachedAccessToken: mocks.harnessGetCachedAccessToken,
+      };
+      ensureConfigFile = mocks.harnessEnsureConfigFile;
+      getConfig = mocks.harnessGetConfig;
+      constructor(...args: unknown[]) {
+        mocks.kimiHarnessConstructor(...args);
+      }
+
+      exportSession = mocks.harnessExportSession;
+    },
+  };
+});
+
+vi.mock('@moonshot-ai/kimi-code-oauth', async () => {
+  const actual = await vi.importActual<typeof import('@moonshot-ai/kimi-code-oauth')>(
+    '@moonshot-ai/kimi-code-oauth',
+  );
+  return {
+    ...actual,
+    createKimiDeviceId: mocks.createKimiDeviceId,
+    KIMI_CODE_PROVIDER_NAME: 'kimi-code',
+  };
+});
+
+vi.mock('@moonshot-ai/kimi-telemetry', () => ({
+  initializeTelemetry: mocks.initializeTelemetry,
+  shutdownTelemetry: mocks.shutdownTelemetry,
+  track: mocks.telemetryTrack,
+  setTelemetryContext: mocks.setTelemetryContext,
+  withTelemetryContext: mocks.withTelemetryContext,
+}));
+
+beforeEach(() => {
+  tmp = mkdtempSync(join(tmpdir(), 'kimi-export-'));
+});
+
+afterEach(() => {
+  rmSync(tmp, { recursive: true, force: true });
+  vi.clearAllMocks();
+  mocks.harnessGetConfig.mockResolvedValue({
+    providers: {},
+    defaultModel: 'k2',
+    telemetry: true,
+  });
+});
+
+function makeSummary(id: string, overrides: Partial<SessionSummary> = {}): SessionSummary {
+  return {
+    id,
+    workDir: tmp,
+    sessionDir: join(tmp, 'sessions', id),
+    createdAt: 1,
+    updatedAt: 2,
+    ...overrides,
+  };
+}
+
+function makeResult(id: string, zipPath: string): ExportSessionResult {
+  const manifest: ExportSessionManifest = {
+    sessionId: id,
+    exportedAt: '2026-04-18T12:00:00.000Z',
+    kimiCodeVersion: '1.27.0',
+    wireProtocolVersion: '1.0',
+    os: 'test',
+    nodejsVersion: '22.0.0',
+    workspaceDir: tmp,
+  };
+  return {
+    zipPath,
+    entries: ['manifest.json', 'wire.jsonl'],
+    sessionDir: join(tmp, 'sessions', id),
+    manifest,
+  };
+}
+
+function makeDeps(overrides: Partial<ExportDeps> = {}): {
+  deps: ExportDeps;
+  stdout: string[];
+  stderr: string[];
+  exitCodes: number[];
+  exportInputs: ExportSessionInput[];
+  listedWorkDirs: string[];
+} {
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  const exitCodes: number[] = [];
+  const exportInputs: ExportSessionInput[] = [];
+  const listedWorkDirs: string[] = [];
+  const deps: ExportDeps = {
+    listSessions: async (workDir) => {
+      listedWorkDirs.push(workDir);
+      return [];
+    },
+    exportSession: async (input) => {
+      exportInputs.push(input);
+      return makeResult(input.id, input.outputPath ?? join(tmp, `${input.id}.zip`));
+    },
+    confirmPreviousSession: async () => true,
+    version: '1.0.0-test',
+    cwd: () => tmp,
+    stdout: {
+      write: (chunk: string) => {
+        stdout.push(chunk);
+        return true;
+      },
+    },
+    stderr: {
+      write: (chunk: string) => {
+        stderr.push(chunk);
+        return true;
+      },
+    },
+    exit: ((code: number) => {
+      exitCodes.push(code);
+      throw new ExitCalled(code);
+    }) as ExportDeps['exit'],
+    ...overrides,
+  };
+  return { deps, stdout, stderr, exitCodes, exportInputs, listedWorkDirs };
+}
+
+class ExitCalled extends Error {
+  constructor(public readonly code: number) {
+    super(`exit(${code})`);
+  }
+}
+
+async function runExport(
+  deps: ExportDeps,
+  args: {
+    sessionId?: string;
+    output?: string;
+    yes?: boolean;
+    includeGlobalLog?: boolean;
+  } = {},
+): Promise<void> {
+  try {
+    await handleExport(deps, args.sessionId, args.output, {
+      yes: args.yes ?? false,
+      includeGlobalLog: args.includeGlobalLog ?? true,
+    });
+  } catch (error) {
+    if (error instanceof ExitCalled) return;
+    throw error;
+  }
+}
+
+describe('kimi export', () => {
+  it('delegates a named session export and prints the resulting zip path', async () => {
+    const output = join(tmp, 'out.zip');
+    const { deps, stdout, stderr, exitCodes, exportInputs, listedWorkDirs } = makeDeps();
+
+    await runExport(deps, { sessionId: 'ses_test123456', output });
+
+    expect(exitCodes).toEqual([]);
+    expect(stderr).toEqual([]);
+    expect(listedWorkDirs).toEqual([]);
+    expect(exportInputs).toEqual([{ id: 'ses_test123456', outputPath: output, includeGlobalLog: true, version: '1.0.0-test' }]);
+    expect(stdout.join('').trim()).toBe(output);
+  });
+
+  it('omits outputPath when the caller does not provide --output', async () => {
+    const { deps, stdout, exportInputs } = makeDeps();
+
+    await runExport(deps, { sessionId: 'session_default_output' });
+
+    expect(exportInputs).toEqual([{ id: 'session_default_output', includeGlobalLog: true, version: '1.0.0-test' }]);
+    expect(stdout.join('').trim()).toBe(join(tmp, 'session_default_output.zip'));
+  });
+
+  it('exits 1 when no session-id is provided and no previous session exists', async () => {
+    const { deps, stderr, exitCodes, exportInputs, listedWorkDirs } = makeDeps();
+
+    await runExport(deps);
+
+    expect(listedWorkDirs).toEqual([tmp]);
+    expect(exportInputs).toEqual([]);
+    expect(exitCodes).toContain(1);
+    expect(stderr.join('').toLowerCase()).toContain('no previous session');
+  });
+
+  it('surfaces export errors for a named session', async () => {
+    const { deps, stderr, exitCodes } = makeDeps({
+      exportSession: async () => {
+        throw new Error('Session "ses_does_not_exist" was not found');
+      },
+    });
+
+    await runExport(deps, { sessionId: 'ses_does_not_exist' });
+
+    expect(exitCodes).toContain(1);
+    expect(stderr.join('').toLowerCase()).toContain('not found');
+  });
+
+  it('falls back to the most-recent session when no id is supplied', async () => {
+    const previous = makeSummary('ses_fallback');
+    const output = join(tmp, 'fallback.zip');
+    const { deps, stdout, exitCodes, exportInputs } = makeDeps({
+      listSessions: async () => [previous],
+    });
+
+    await runExport(deps, { output });
+
+    expect(exitCodes).toEqual([]);
+    expect(exportInputs).toEqual([{ id: 'ses_fallback', outputPath: output, includeGlobalLog: true, version: '1.0.0-test' }]);
+    expect(stdout.join('').trim()).toBe(output);
+  });
+
+  it('confirms before exporting the previous session when no id is supplied', async () => {
+    const previous = makeSummary('ses_confirm', { title: 'Prod debug' });
+    const summaries: unknown[] = [];
+    const { deps, stdout, exitCodes, exportInputs } = makeDeps({
+      listSessions: async () => [previous],
+      confirmPreviousSession: async (summary) => {
+        summaries.push(summary);
+        return false;
+      },
+    });
+
+    await runExport(deps, { output: join(tmp, 'cancelled.zip') });
+
+    expect(exitCodes).toEqual([]);
+    expect(exportInputs).toEqual([]);
+    expect(stdout.join('')).toContain('Export cancelled.');
+    expect(summaries).toEqual([
+      {
+        workDir: tmp,
+        sessionId: 'ses_confirm',
+        sessionDir: join(tmp, 'sessions', 'ses_confirm'),
+        title: 'Prod debug',
+      },
+    ]);
+  });
+
+  it('skips previous-session confirmation with --yes', async () => {
+    const previous = makeSummary('ses_yes');
+    const { deps, exitCodes, exportInputs } = makeDeps({
+      listSessions: async () => [previous],
+      confirmPreviousSession: async () => {
+        throw new Error('confirm should not be called');
+      },
+    });
+
+    await runExport(deps, { output: join(tmp, 'yes.zip'), yes: true });
+
+    expect(exitCodes).toEqual([]);
+    expect(exportInputs).toEqual([{ id: 'ses_yes', outputPath: join(tmp, 'yes.zip'), includeGlobalLog: true, version: '1.0.0-test' }]);
+  });
+
+  it('describes the user-facing command without implementation details', () => {
+    const program = new Command('kimi');
+    const { deps } = makeDeps();
+
+    registerExportCommand(program, deps);
+
+    const command = program.commands.find((item) => item.name() === 'export');
+    expect(command?.description()).toBe('Export a session as a ZIP archive.');
+    expect(command?.description()).not.toMatch(/sdk/i);
+  });
+
+  it('parses --no-include-global-log as an option when no session id is given', async () => {
+    const previous = makeSummary('ses_global_log');
+    const { deps, stdout, exitCodes, exportInputs } = makeDeps({
+      listSessions: async () => [previous],
+      confirmPreviousSession: async () => true,
+    });
+    const program = new Command('kimi');
+    registerExportCommand(program, deps);
+
+    await program.parseAsync(['node', 'kimi', 'export', '--no-include-global-log', '-y']);
+
+    expect(exitCodes).toEqual([]);
+    expect(exportInputs).toEqual([{ id: 'ses_global_log', version: '1.0.0-test' }]);
+    expect(stdout.join('').trim()).toBe(join(tmp, 'ses_global_log.zip'));
+  });
+
+  it('parses options after an explicit session id', async () => {
+    const output = join(tmp, 'after-id.zip');
+    const { deps, exitCodes, exportInputs } = makeDeps();
+    const program = new Command('kimi');
+    registerExportCommand(program, deps);
+
+    await program.parseAsync([
+      'node',
+      'kimi',
+      'export',
+      'ses_after_id',
+      '-o',
+      output,
+      '-y',
+      '--no-include-global-log',
+    ]);
+
+    expect(exitCodes).toEqual([]);
+    expect(exportInputs).toEqual([
+      { id: 'ses_after_id', outputPath: output, version: '1.0.0-test' },
+    ]);
+  });
+
+  it('initializes and flushes telemetry around default export tracking', async () => {
+    const program = new Command('kimi');
+    const output = join(tmp, 'telemetry.zip');
+    mocks.harnessExportSession.mockResolvedValue(makeResult('ses_telemetry', output));
+
+    registerExportCommand(program, {
+      cwd: () => tmp,
+      stdout: {
+        write: () => true,
+      },
+      stderr: {
+        write: () => true,
+      },
+      exit: ((code: number) => {
+        throw new ExitCalled(code);
+      }) as ExportDeps['exit'],
+    });
+
+    await program.parseAsync(['node', 'kimi', 'export', 'ses_telemetry', '--output', output], {
+      from: 'node',
+    });
+
+    expect(mocks.kimiHarnessConstructor).toHaveBeenCalledWith(
+      expect.objectContaining({
+        telemetry: {
+          track: mocks.telemetryTrack,
+          setContext: mocks.setTelemetryContext,
+          withContext: mocks.withTelemetryContext,
+        },
+      }),
+    );
+    expect(mocks.harnessEnsureConfigFile).toHaveBeenCalledOnce();
+    expect(mocks.harnessGetConfig).toHaveBeenCalledOnce();
+    expect(mocks.createKimiDeviceId).toHaveBeenCalledWith('/tmp/kimi-export-home');
+    expect(mocks.initializeTelemetry).toHaveBeenCalledWith({
+      homeDir: '/tmp/kimi-export-home',
+      deviceId: 'device-1',
+      enabled: true,
+      appName: 'kimi-code-cli',
+      version: expect.any(String),
+      uiMode: 'shell',
+      model: 'k2',
+      getAccessToken: expect.any(Function),
+    });
+    expect(mocks.initializeTelemetry.mock.invocationCallOrder[0]).toBeLessThan(
+      mocks.harnessExportSession.mock.invocationCallOrder[0]!,
+    );
+    expect(mocks.harnessExportSession).toHaveBeenCalledWith({
+      id: 'ses_telemetry',
+      outputPath: output,
+      version: expect.any(String),
+      includeGlobalLog: true,
+    });
+    expect(mocks.shutdownTelemetry).toHaveBeenCalledWith({ timeoutMs: 3000 });
+    expect(mocks.harnessExportSession.mock.invocationCallOrder[0]).toBeLessThan(
+      mocks.shutdownTelemetry.mock.invocationCallOrder[0]!,
+    );
+  });
+
+  it('passes enabled false when default export config disables telemetry', async () => {
+    const program = new Command('kimi');
+    const output = join(tmp, 'telemetry-disabled.zip');
+    mocks.harnessGetConfig.mockResolvedValue({
+      providers: {},
+      defaultModel: 'k2',
+      telemetry: false,
+    });
+    mocks.harnessExportSession.mockResolvedValue(makeResult('ses_disabled', output));
+
+    registerExportCommand(program, {
+      cwd: () => tmp,
+      stdout: {
+        write: () => true,
+      },
+      stderr: {
+        write: () => true,
+      },
+      exit: ((code: number) => {
+        throw new ExitCalled(code);
+      }) as ExportDeps['exit'],
+    });
+
+    await program.parseAsync(['node', 'kimi', 'export', 'ses_disabled', '--output', output], {
+      from: 'node',
+    });
+
+    expect(mocks.initializeTelemetry).toHaveBeenCalledWith(
+      expect.objectContaining({
+        enabled: false,
+      }),
+    );
+    expect(mocks.shutdownTelemetry).toHaveBeenCalledWith({ timeoutMs: 3000 });
+  });
+});
diff --git a/apps/kimi-code/test/cli/main.test.ts b/apps/kimi-code/test/cli/main.test.ts
new file mode 100644
index 000000000..8ab1ea976
--- /dev/null
+++ b/apps/kimi-code/test/cli/main.test.ts
@@ -0,0 +1,211 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ErrorCodes, KimiError } from '@moonshot-ai/kimi-code-sdk';
+
+import { validateOptions } from '#/cli/options';
+import type { CLIOptions } from '#/cli/options';
+import type * as OptionsModule from '#/cli/options';
+import { runPrompt } from '#/cli/run-prompt';
+import { runShell } from '#/cli/run-shell';
+import { formatStartupError } from '#/cli/startup-error';
+import { runUpdatePreflight } from '#/cli/update/preflight';
+import { handleMainCommand, main } from '#/main';
+
+const mocks = vi.hoisted(() => {
+  const parse = vi.fn();
+  return {
+    parse,
+    createProgram: vi.fn(() => ({ parse })),
+    getVersion: vi.fn(() => '0.0.1-alpha.2'),
+    validateOptions: vi.fn(),
+    runUpdatePreflight: vi.fn(),
+    runShell: vi.fn(),
+    runPrompt: vi.fn(),
+    installCrashHandlers: vi.fn(),
+  };
+});
+
+vi.mock('@moonshot-ai/kimi-telemetry', () => ({
+  installCrashHandlers: mocks.installCrashHandlers,
+  track: vi.fn(),
+}));
+
+vi.mock('../../src/cli/commands', () => ({
+  createProgram: mocks.createProgram,
+}));
+
+vi.mock('../../src/cli/version', () => ({
+  getVersion: mocks.getVersion,
+}));
+
+vi.mock('../../src/cli/options', async () => {
+  const actual = await vi.importActual<typeof OptionsModule>('../../src/cli/options.js');
+  return {
+    ...actual,
+    validateOptions: mocks.validateOptions,
+  };
+});
+
+vi.mock('../../src/cli/update/preflight', () => ({
+  runUpdatePreflight: mocks.runUpdatePreflight,
+}));
+
+vi.mock('../../src/cli/run-shell', () => ({
+  runShell: mocks.runShell,
+}));
+
+vi.mock('../../src/cli/run-prompt', () => ({
+  runPrompt: mocks.runPrompt,
+}));
+
+class ExitCalled extends Error {
+  constructor(readonly code: number) {
+    super(`exit(${code})`);
+  }
+}
+
+function defaultOpts(): CLIOptions {
+  return {
+    session: undefined,
+    continue: false,
+    yolo: false,
+    plan: false,
+    model: undefined,
+    outputFormat: undefined,
+    prompt: undefined,
+    skillsDirs: [],
+  };
+}
+
+async function runHandleMainCommand(opts: CLIOptions): Promise<number | null> {
+  const exitSpy = vi.spyOn(process, 'exit').mockImplementation((code?: string | number | null) => {
+    throw new ExitCalled(Number(code ?? 0));
+  });
+  try {
+    await handleMainCommand(opts, '0.0.1-alpha.2');
+    return null;
+  } catch (error) {
+    if (error instanceof ExitCalled) {
+      return error.code;
+    }
+    throw error;
+  } finally {
+    exitSpy.mockRestore();
+  }
+}
+
+describe('main entry command handling', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('runs update preflight before starting the shell', async () => {
+    const opts = defaultOpts();
+    mocks.validateOptions.mockReturnValue({ options: opts, uiMode: 'shell' });
+    mocks.runUpdatePreflight.mockResolvedValue('continue');
+    mocks.runShell.mockResolvedValue(void 0);
+
+    const exitCode = await runHandleMainCommand(opts);
+
+    expect(exitCode).toBeNull();
+    expect(validateOptions).toHaveBeenCalledWith(opts);
+    expect(runUpdatePreflight).toHaveBeenCalledWith('0.0.1-alpha.2', { track: expect.any(Function) });
+    expect(mocks.runUpdatePreflight.mock.invocationCallOrder[0]).toBeLessThan(
+      mocks.runShell.mock.invocationCallOrder[0]!,
+    );
+    expect(runShell).toHaveBeenCalledWith(opts, '0.0.1-alpha.2');
+  });
+
+  it('runs prompt mode without interactive update preflight', async () => {
+    const opts: CLIOptions = {
+      ...defaultOpts(),
+      prompt: 'explain the repo',
+    };
+    mocks.validateOptions.mockReturnValue({ options: opts, uiMode: 'print' });
+    mocks.runUpdatePreflight.mockResolvedValue('continue');
+    mocks.runPrompt.mockResolvedValue(void 0);
+
+    const exitCode = await runHandleMainCommand(opts);
+
+    expect(exitCode).toBeNull();
+    expect(runUpdatePreflight).toHaveBeenCalledWith('0.0.1-alpha.2', {
+      track: expect.any(Function),
+      isTTY: false,
+    });
+    expect(runPrompt).toHaveBeenCalledWith(opts, '0.0.1-alpha.2');
+    expect(runShell).not.toHaveBeenCalled();
+  });
+
+  it('keeps shell mode update preflight interactive by default', async () => {
+    const opts = defaultOpts();
+    mocks.validateOptions.mockReturnValue({ options: opts, uiMode: 'shell' });
+    mocks.runUpdatePreflight.mockResolvedValue('continue');
+    mocks.runShell.mockResolvedValue(void 0);
+
+    const exitCode = await runHandleMainCommand(opts);
+
+    expect(exitCode).toBeNull();
+    expect(runUpdatePreflight).toHaveBeenCalledWith('0.0.1-alpha.2', {
+      track: expect.any(Function),
+    });
+    expect(runShell).toHaveBeenCalledWith(opts, '0.0.1-alpha.2');
+  });
+
+  it('installs crash handlers before parsing CLI arguments', () => {
+    main();
+
+    expect(mocks.installCrashHandlers).toHaveBeenCalledTimes(1);
+    expect(mocks.installCrashHandlers.mock.invocationCallOrder[0]).toBeLessThan(
+      mocks.createProgram.mock.invocationCallOrder[0]!,
+    );
+    expect(mocks.parse).toHaveBeenCalledWith(process.argv);
+  });
+
+  it('exits early when update preflight requests process exit', async () => {
+    const opts = defaultOpts();
+    mocks.validateOptions.mockReturnValue({ options: opts, uiMode: 'shell' });
+    mocks.runUpdatePreflight.mockResolvedValue('exit');
+    mocks.runShell.mockResolvedValue(void 0);
+
+    const exitCode = await runHandleMainCommand(opts);
+
+    expect(exitCode).toBe(0);
+    expect(runShell).not.toHaveBeenCalled();
+  });
+
+  it('formats Kimi startup errors with structured fields', () => {
+    const error = new KimiError(
+      ErrorCodes.SHELL_GIT_BASH_NOT_FOUND,
+      'Git Bash was not found on this Windows host. Checked: C:\\Program Files\\Git\\bin\\bash.exe.',
+    );
+    const red = (text: string): string => `\u001B[31m${text}\u001B[39m`;
+
+    expect(formatStartupError(error, { errorStyle: red })).toBe(
+      [
+        '\u001B[31merror: Git Bash not found\u001B[39m',
+        '',
+        '\u001B[31mmessage:\u001B[39m',
+        '\u001B[31mGit Bash was not found on this Windows host. Checked: C:\\Program Files\\Git\\bin\\bash.exe.\u001B[39m',
+        '',
+      ].join('\n'),
+    );
+  });
+
+  it('keeps generic startup errors on the legacy fallback path', () => {
+    expect(formatStartupError(new Error('Provider not set'), { errorStyle: (text) => text })).toBe(
+      'error: failed to start shell: Provider not set\n',
+    );
+  });
+
+  it('formats generic prompt mode errors without saying shell', () => {
+    expect(
+      formatStartupError(new Error('Provider not set'), {
+        errorStyle: (text) => text,
+        operation: 'run prompt',
+      }),
+    ).toBe('error: failed to run prompt: Provider not set\n');
+  });
+});
diff --git a/apps/kimi-code/test/cli/options.test.ts b/apps/kimi-code/test/cli/options.test.ts
new file mode 100644
index 000000000..a98268ced
--- /dev/null
+++ b/apps/kimi-code/test/cli/options.test.ts
@@ -0,0 +1,256 @@
+import { describe, expect, it } from 'vitest';
+
+import { createProgram } from '#/cli/commands';
+import type { CLIOptions } from '#/cli/options';
+import { OptionConflictError, validateOptions } from '#/cli/options';
+
+function parse(argv: string[]): CLIOptions {
+  let captured: CLIOptions | undefined;
+
+  const program = createProgram(
+    '0.1.0-test',
+    (opts) => {
+      captured = opts;
+    },
+    () => {},
+  );
+
+  program.exitOverride();
+  program.configureOutput({
+    writeOut: () => {},
+    writeErr: () => {},
+  });
+
+  program.parse(['node', 'kimi', ...argv]);
+
+  if (captured === undefined) {
+    throw new Error('Main action handler was not called');
+  }
+  return captured;
+}
+
+describe('CLI options parsing', () => {
+  describe('defaults', () => {
+    it('returns defaults when no arguments are given', () => {
+      const opts = parse([]);
+      expect(opts.yolo).toBe(false);
+      expect(opts.plan).toBe(false);
+      expect(opts.continue).toBe(false);
+      expect(opts.session).toBeUndefined();
+      expect(opts.model).toBeUndefined();
+      expect(opts.outputFormat).toBeUndefined();
+      expect(opts.prompt).toBeUndefined();
+      expect(opts.skillsDirs).toEqual([]);
+    });
+  });
+
+  describe('--version', () => {
+    it('prints the version string and exits', () => {
+      let output = '';
+      const program = createProgram('1.2.3', () => {}, () => {});
+      program.exitOverride();
+      program.configureOutput({
+        writeOut: (s) => {
+          output += s;
+        },
+      });
+
+      expect(() => program.parse(['node', 'kimi', '--version'])).toThrow();
+      expect(output).toContain('1.2.3');
+    });
+
+    it('supports -V as a short alias', () => {
+      let output = '';
+      const program = createProgram('4.5.6', () => {}, () => {});
+      program.exitOverride();
+      program.configureOutput({
+        writeOut: (s) => {
+          output += s;
+        },
+      });
+
+      expect(() => program.parse(['node', 'kimi', '-V'])).toThrow();
+      expect(output).toContain('4.5.6');
+    });
+  });
+
+  describe('--yolo family', () => {
+    it('--yolo sets yolo to true', () => {
+      expect(parse(['--yolo']).yolo).toBe(true);
+    });
+
+    it('-y sets yolo to true', () => {
+      expect(parse(['-y']).yolo).toBe(true);
+    });
+
+    it('--yes sets yolo to true (hidden alias)', () => {
+      expect(parse(['--yes']).yolo).toBe(true);
+    });
+
+    it('--auto-approve sets yolo to true (hidden alias)', () => {
+      expect(parse(['--auto-approve']).yolo).toBe(true);
+    });
+  });
+
+  describe('--session / --resume / --continue', () => {
+    it('-S sets session', () => {
+      expect(parse(['-S', 'sess-123']).session).toBe('sess-123');
+    });
+
+    it('-r is an alias for --session', () => {
+      expect(parse(['-r', 'sess-456']).session).toBe('sess-456');
+    });
+
+    it('--resume is an alias for --session', () => {
+      expect(parse(['--resume', 'sess-789']).session).toBe('sess-789');
+    });
+
+    it('bare -S (no id) yields empty string — triggers the picker', () => {
+      expect(parse(['-S']).session).toBe('');
+    });
+
+    it('-C sets continue', () => {
+      expect(parse(['-C']).continue).toBe(true);
+    });
+
+    it('--continue and --session combined raises a conflict', () => {
+      const opts = parse(['--continue', '--session', 'abc123']);
+      expect(() => validateOptions(opts)).toThrow(OptionConflictError);
+      expect(() => validateOptions(opts)).toThrow('Cannot combine --continue, --session.');
+    });
+  });
+
+  describe('--plan', () => {
+    it('sets plan mode flag', () => {
+      expect(parse(['--plan']).plan).toBe(true);
+    });
+  });
+
+  describe('--model / -m', () => {
+    it('parses -m as a model override', () => {
+      expect(parse(['-m', 'kimi-code/k2']).model).toBe('kimi-code/k2');
+    });
+
+    it('parses --model=value as a model override', () => {
+      expect(parse(['--model=kimi-code/k2.5']).model).toBe('kimi-code/k2.5');
+    });
+
+    it('rejects empty model values', () => {
+      const opts = parse(['--model', '   ']);
+      expect(() => validateOptions(opts)).toThrow(OptionConflictError);
+      expect(() => validateOptions(opts)).toThrow('Model cannot be empty.');
+    });
+  });
+
+  describe('--prompt / -p', () => {
+    it('parses -p as prompt mode', () => {
+      const opts = parse(['-p', 'explain this repo']);
+      expect(opts.prompt).toBe('explain this repo');
+      expect(validateOptions(opts).uiMode).toBe('print');
+    });
+
+    it('parses --prompt=value as prompt mode', () => {
+      const opts = parse(['--prompt=explain this repo']);
+      expect(opts.prompt).toBe('explain this repo');
+      expect(validateOptions(opts).uiMode).toBe('print');
+    });
+
+    it('rejects empty prompt values before reaching the SDK', () => {
+      const opts = parse(['-p', '   ']);
+      expect(() => validateOptions(opts)).toThrow(OptionConflictError);
+      expect(() => validateOptions(opts)).toThrow('Prompt cannot be empty.');
+    });
+
+    it('allows prompt mode with --continue', () => {
+      const opts = parse(['-p', 'continue here', '--continue']);
+      expect(opts.continue).toBe(true);
+      expect(validateOptions(opts).uiMode).toBe('print');
+    });
+
+    it('allows prompt mode with a concrete session id', () => {
+      const opts = parse(['-p', 'resume here', '--session', 'ses_123']);
+      expect(opts.session).toBe('ses_123');
+      expect(validateOptions(opts).uiMode).toBe('print');
+    });
+
+    it('rejects prompt mode with bare --session picker', () => {
+      const opts = parse(['-p', 'resume here', '--session']);
+      expect(() => validateOptions(opts)).toThrow(OptionConflictError);
+      expect(() => validateOptions(opts)).toThrow('Cannot use --session without an id in prompt mode.');
+    });
+
+    it('rejects prompt mode with --yolo because prompt mode always uses auto permission', () => {
+      const opts = parse(['-p', 'run this', '--yolo']);
+      expect(() => validateOptions(opts)).toThrow(OptionConflictError);
+      expect(() => validateOptions(opts)).toThrow('Cannot combine --prompt with --yolo.');
+    });
+
+    it('rejects prompt mode with --plan', () => {
+      const opts = parse(['-p', 'run this', '--plan']);
+      expect(() => validateOptions(opts)).toThrow(OptionConflictError);
+      expect(() => validateOptions(opts)).toThrow('Cannot combine --prompt with --plan.');
+    });
+
+    it('parses --output-format=stream-json in prompt mode', () => {
+      const opts = parse(['-p', 'run this', '--output-format=stream-json']);
+      expect(opts.outputFormat).toBe('stream-json');
+      expect(validateOptions(opts).uiMode).toBe('print');
+    });
+
+    it('parses --output-format text in prompt mode', () => {
+      const opts = parse(['-p', 'run this', '--output-format', 'text']);
+      expect(opts.outputFormat).toBe('text');
+    });
+
+    it('rejects --output-format outside prompt mode', () => {
+      const opts = parse(['--output-format=stream-json']);
+      expect(() => validateOptions(opts)).toThrow(OptionConflictError);
+      expect(() => validateOptions(opts)).toThrow(
+        'Output format is only supported in prompt mode.',
+      );
+    });
+  });
+
+  describe('--skills-dir', () => {
+    it('collects repeated skill directories', () => {
+      expect(parse(['--skills-dir', '/one', '--skills-dir=/two']).skillsDirs).toEqual([
+        '/one',
+        '/two',
+      ]);
+    });
+  });
+
+  describe('sub-commands', () => {
+    it('registers the diagnostic sub-commands during alpha', () => {
+      const program = createProgram('0.0.0', () => {}, () => {});
+      const commandNames: string[] = program.commands.map((command) => command.name());
+      expect(commandNames).toEqual(['export', 'migrate']);
+    });
+  });
+
+  describe('rejected flags', () => {
+    it('any removed flag is unknown to Commander', () => {
+      for (const arg of [
+        '--verbose',
+        '--debug',
+        '--work-dir=/',
+        '--config=x',
+        '--thinking',
+        '--print',
+        '--wire',
+        '--agent=default',
+        '--add-dir=/',
+        '--raw-model',
+        '--config-file=x',
+        '--quiet',
+        '--final-message-only',
+        '--input-format=text',
+        '--agent-file=x',
+        '--mcp-config={}',
+        '--mcp-config-file=/',
+      ]) {
+        expect(() => parse([arg])).toThrow();
+      }
+    });
+  });
+});
diff --git a/apps/kimi-code/test/cli/run-prompt.test.ts b/apps/kimi-code/test/cli/run-prompt.test.ts
new file mode 100644
index 000000000..0169acba3
--- /dev/null
+++ b/apps/kimi-code/test/cli/run-prompt.test.ts
@@ -0,0 +1,689 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { runPrompt } from '#/cli/run-prompt';
+
+const mocks = vi.hoisted(() => {
+  const eventHandlers = new Set<(event: any) => void>();
+  const agentEvent = (agentId: string, event: Record<string, unknown>) => ({
+    sessionId: 'ses_prompt',
+    agentId,
+    ...event,
+  });
+  const mainEvent = (event: Record<string, unknown>) => agentEvent('main', event);
+  const session = {
+    id: 'ses_prompt',
+    setModel: vi.fn(),
+    setPermission: vi.fn(),
+    setApprovalHandler: vi.fn(),
+    setQuestionHandler: vi.fn(),
+    getStatus: vi.fn(
+      async (): Promise<{ readonly permission: string; readonly model?: string }> => ({
+        permission: 'manual',
+      }),
+    ),
+    onEvent: vi.fn((handler: (event: any) => void) => {
+      eventHandlers.add(handler);
+      return () => eventHandlers.delete(handler);
+    }),
+    prompt: vi.fn(async () => {
+      for (const handler of eventHandlers) {
+        handler(
+          mainEvent({ type: 'turn.started', turnId: 1, origin: { kind: 'user' } }),
+        );
+        handler(mainEvent({ type: 'assistant.delta', turnId: 1, delta: 'hello' }));
+        handler(mainEvent({ type: 'assistant.delta', turnId: 1, delta: ' world' }));
+        handler(mainEvent({ type: 'turn.ended', turnId: 1, reason: 'completed' }));
+      }
+    }),
+  };
+
+  return {
+    session,
+    eventHandlers,
+    agentEvent,
+    mainEvent,
+    kimiHarnessConstructor: vi.fn(),
+    harnessEnsureConfigFile: vi.fn(),
+    harnessGetConfig: vi.fn(
+      async (): Promise<{ providers: {}; defaultModel?: string; telemetry: boolean }> => ({
+        providers: {},
+        defaultModel: 'k2',
+        telemetry: true,
+      }),
+    ),
+    harnessCreateSession: vi.fn(async () => session),
+    harnessResumeSession: vi.fn(async () => session),
+    harnessListSessions: vi.fn(async () => [{ id: 'ses_previous' }]),
+    harnessClose: vi.fn(),
+    harnessTrack: vi.fn(),
+    harnessGetCachedAccessToken: vi.fn(),
+    initializeTelemetry: vi.fn(),
+    setCrashPhase: vi.fn(),
+    shutdownTelemetry: vi.fn(),
+    telemetryTrack: vi.fn(),
+    setTelemetryContext: vi.fn(),
+    lifecycleTrack: vi.fn(),
+    withTelemetryContext: vi.fn(() => ({ track: vi.fn() })),
+  };
+});
+
+vi.mock('@moonshot-ai/kimi-code-sdk', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@moonshot-ai/kimi-code-sdk')>();
+  return {
+    ...actual,
+    KimiHarness: class {
+      homeDir = '/tmp/kimi-code-test-home';
+      auth = { getCachedAccessToken: mocks.harnessGetCachedAccessToken };
+      ensureConfigFile = mocks.harnessEnsureConfigFile;
+      getConfig = mocks.harnessGetConfig;
+      createSession = mocks.harnessCreateSession;
+      resumeSession = mocks.harnessResumeSession;
+      listSessions = mocks.harnessListSessions;
+      close = mocks.harnessClose;
+      track = mocks.harnessTrack;
+
+      constructor(...args: unknown[]) {
+        mocks.kimiHarnessConstructor(...args);
+      }
+    },
+  };
+});
+
+vi.mock('@moonshot-ai/kimi-code-oauth', async () => {
+  const actual = await vi.importActual<typeof import('@moonshot-ai/kimi-code-oauth')>(
+    '@moonshot-ai/kimi-code-oauth',
+  );
+  return {
+    ...actual,
+    createKimiDeviceId: vi.fn(() => 'device-1'),
+    KIMI_CODE_PROVIDER_NAME: 'kimi-code',
+  };
+});
+
+vi.mock('@moonshot-ai/kimi-telemetry', () => ({
+  initializeTelemetry: mocks.initializeTelemetry,
+  setCrashPhase: mocks.setCrashPhase,
+  shutdownTelemetry: mocks.shutdownTelemetry,
+  track: mocks.telemetryTrack,
+  setTelemetryContext: mocks.setTelemetryContext,
+  withTelemetryContext: mocks.withTelemetryContext,
+}));
+
+function opts(overrides: Partial<Parameters<typeof runPrompt>[0]> = {}) {
+  return {
+    session: undefined,
+    continue: false,
+    yolo: false,
+    plan: false,
+    model: undefined,
+    outputFormat: undefined,
+    prompt: 'say hello',
+    skillsDirs: [],
+    ...overrides,
+  };
+}
+
+function writer(columns?: number) {
+  let text = '';
+  return {
+    columns,
+    write: vi.fn((chunk: string) => {
+      text += chunk;
+      return true;
+    }),
+    text: () => text,
+  };
+}
+
+function fakeProcess() {
+  const listeners = new Map<NodeJS.Signals, () => Promise<void> | void>();
+  return {
+    once: vi.fn((signal: NodeJS.Signals, listener: () => Promise<void> | void) => {
+      listeners.set(signal, listener);
+    }),
+    off: vi.fn((signal: NodeJS.Signals, listener: () => Promise<void> | void) => {
+      if (listeners.get(signal) === listener) {
+        listeners.delete(signal);
+      }
+    }),
+    exit: vi.fn(),
+    listener: (signal: NodeJS.Signals) => listeners.get(signal),
+  };
+}
+
+async function waitForAssertion(assertion: () => void): Promise<void> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    try {
+      assertion();
+      return;
+    } catch (error) {
+      lastError = error;
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+  }
+  throw lastError;
+}
+
+describe('runPrompt', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+    mocks.eventHandlers.clear();
+  });
+
+  it('creates a fresh auto-permission session and streams assistant output to stdout', async () => {
+    const stdout = writer();
+    const stderr = writer();
+
+    await runPrompt(opts({ skillsDirs: ['/skills'] }), '1.2.3-test', { stdout, stderr });
+
+    expect(mocks.kimiHarnessConstructor).toHaveBeenCalledWith(
+      expect.objectContaining({ skillDirs: ['/skills'], uiMode: 'print' }),
+    );
+    expect(mocks.harnessCreateSession).toHaveBeenCalledWith({
+      workDir: process.cwd(),
+      model: 'k2',
+      permission: 'auto',
+    });
+    expect(mocks.session.setPermission).not.toHaveBeenCalled();
+    expect(mocks.session.setApprovalHandler).toHaveBeenCalledWith(expect.any(Function));
+    expect(mocks.session.setQuestionHandler).toHaveBeenCalledWith(expect.any(Function));
+    expect(mocks.session.prompt).toHaveBeenCalledWith('say hello');
+    expect(stdout.text()).toBe('• hello world\n\n');
+    expect(stderr.text()).toBe('To resume this session: kimi -r ses_prompt\n');
+    expect(mocks.shutdownTelemetry).toHaveBeenCalled();
+    expect(mocks.harnessClose).toHaveBeenCalled();
+  });
+
+  it('uses the CLI model override when creating a fresh prompt session', async () => {
+    await runPrompt(opts({ model: 'kimi-code/k2.5' }), '1.2.3-test', {
+      stdout: { write: vi.fn(() => true) },
+      stderr: { write: vi.fn(() => true) },
+    });
+
+    expect(mocks.harnessCreateSession).toHaveBeenCalledWith({
+      workDir: process.cwd(),
+      model: 'kimi-code/k2.5',
+      permission: 'auto',
+    });
+    expect(mocks.initializeTelemetry).toHaveBeenCalledWith(
+      expect.objectContaining({ model: 'kimi-code/k2.5' }),
+    );
+  });
+
+  it('formats thinking and assistant output as transcript blocks', async () => {
+    mocks.session.prompt.mockImplementationOnce(async () => {
+      for (const handler of mocks.eventHandlers) {
+        handler(
+          mocks.mainEvent({ type: 'turn.started', turnId: 3, origin: { kind: 'user' } }),
+        );
+        handler(
+          mocks.mainEvent({
+            type: 'thinking.delta',
+            turnId: 3,
+            delta: 'The user wants an exact reply.',
+          }),
+        );
+        handler(
+          mocks.mainEvent({
+            type: 'thinking.delta',
+            turnId: 3,
+            delta: '\nNo tools are needed.',
+          }),
+        );
+        handler(mocks.mainEvent({ type: 'assistant.delta', turnId: 3, delta: 'prompt-mode-ok' }));
+        handler(mocks.mainEvent({ type: 'turn.ended', turnId: 3, reason: 'completed' }));
+      }
+    });
+    const stdout = writer();
+    const stderr = writer();
+
+    await runPrompt(opts(), '1.2.3-test', { stdout, stderr });
+
+    expect(stderr.text()).toBe(
+      '• The user wants an exact reply.\n  No tools are needed.\n\nTo resume this session: kimi -r ses_prompt\n',
+    );
+    expect(stdout.text()).toBe('• prompt-mode-ok\n\n');
+    expect(stderr.write).toHaveBeenNthCalledWith(1, '• The user wants an exact reply.');
+    expect(stderr.write).toHaveBeenNthCalledWith(2, '\n  No tools are needed.');
+    expect(stdout.write).toHaveBeenNthCalledWith(1, '• prompt-mode-ok');
+  });
+
+  it('formats hook results as their own transcript block', async () => {
+    mocks.session.prompt.mockImplementationOnce(async () => {
+      for (const handler of mocks.eventHandlers) {
+        handler(
+          mocks.mainEvent({ type: 'turn.started', turnId: 3, origin: { kind: 'user' } }),
+        );
+        handler(
+          mocks.mainEvent({
+            type: 'hook.result',
+            turnId: 3,
+            hookEvent: 'UserPromptSubmit',
+            content: '{}',
+          }),
+        );
+        handler(mocks.mainEvent({ type: 'assistant.delta', turnId: 3, delta: 'answer' }));
+        handler(mocks.mainEvent({ type: 'turn.ended', turnId: 3, reason: 'completed' }));
+      }
+    });
+    const stdout = writer();
+    const stderr = writer();
+
+    await runPrompt(opts(), '1.2.3-test', { stdout, stderr });
+
+    expect(stdout.text()).toBe('• UserPromptSubmit hook\n\n  {}\n\n• answer\n\n');
+    expect(stderr.text()).toBe('To resume this session: kimi -r ses_prompt\n');
+  });
+
+  it('wraps transcript blocks with hanging indentation when terminal width is known', async () => {
+    mocks.session.prompt.mockImplementationOnce(async () => {
+      for (const handler of mocks.eventHandlers) {
+        handler(
+          mocks.mainEvent({ type: 'turn.started', turnId: 4, origin: { kind: 'user' } }),
+        );
+        handler(mocks.mainEvent({ type: 'thinking.delta', turnId: 4, delta: 'thinking-wrap' }));
+        handler(mocks.mainEvent({ type: 'assistant.delta', turnId: 4, delta: 'answer-wrap' }));
+        handler(mocks.mainEvent({ type: 'turn.ended', turnId: 4, reason: 'completed' }));
+      }
+    });
+    const stdout = writer(10);
+    const stderr = writer(10);
+
+    await runPrompt(opts(), '1.2.3-test', { stdout, stderr });
+
+    expect(stderr.text()).toBe('• thinking\n  -wrap\n\nTo resume this session: kimi -r ses_prompt\n');
+    expect(stdout.text()).toBe('• answer-w\n  rap\n\n');
+  });
+
+  it('filters prompt output and completion to the main agent turn', async () => {
+    mocks.session.prompt.mockImplementationOnce(async () => {
+      const emit = (event: Record<string, unknown>) => {
+        for (const handler of Array.from(mocks.eventHandlers)) {
+          handler(event);
+        }
+      };
+
+      emit(mocks.mainEvent({ type: 'turn.started', turnId: 1, origin: { kind: 'user' } }));
+      emit(
+        mocks.agentEvent('child-agent', {
+          type: 'turn.started',
+          turnId: 1,
+          origin: { kind: 'user' },
+        }),
+      );
+      emit(
+        mocks.agentEvent('child-agent', {
+          type: 'assistant.delta',
+          turnId: 1,
+          delta: 'sub answer',
+        }),
+      );
+      emit(mocks.agentEvent('child-agent', { type: 'turn.ended', turnId: 1, reason: 'completed' }));
+      await Promise.resolve();
+      emit(mocks.mainEvent({ type: 'assistant.delta', turnId: 1, delta: 'main answer' }));
+      emit(mocks.mainEvent({ type: 'turn.ended', turnId: 1, reason: 'completed' }));
+    });
+    const stdout = writer();
+    const stderr = writer();
+
+    await runPrompt(opts(), '1.2.3-test', { stdout, stderr });
+
+    expect(stdout.text()).toBe('• main answer\n\n');
+    expect(stderr.text()).toBe('To resume this session: kimi -r ses_prompt\n');
+  });
+
+  it('ignores child-agent error events while the main turn continues', async () => {
+    mocks.session.prompt.mockImplementationOnce(async () => {
+      const emit = (event: Record<string, unknown>) => {
+        for (const handler of Array.from(mocks.eventHandlers)) {
+          handler(event);
+        }
+      };
+
+      emit(mocks.mainEvent({ type: 'turn.started', turnId: 1, origin: { kind: 'user' } }));
+      emit(
+        mocks.agentEvent('child-agent', {
+          type: 'error',
+          code: 'subagent.failed',
+          message: 'child failed',
+        }),
+      );
+      await Promise.resolve();
+      emit(mocks.mainEvent({ type: 'assistant.delta', turnId: 1, delta: 'main recovered' }));
+      emit(mocks.mainEvent({ type: 'turn.ended', turnId: 1, reason: 'completed' }));
+    });
+    const stdout = writer();
+    const stderr = writer();
+
+    await runPrompt(opts(), '1.2.3-test', { stdout, stderr });
+
+    expect(stdout.text()).toBe('• main recovered\n\n');
+    expect(stderr.text()).toBe('To resume this session: kimi -r ses_prompt\n');
+  });
+
+  it('resumes a concrete session and forces auto permission before prompting', async () => {
+    await runPrompt(opts({ session: 'ses_existing' }), '1.2.3-test', {
+      stdout: { write: vi.fn(() => true) },
+      stderr: { write: vi.fn(() => true) },
+    });
+
+    expect(mocks.harnessResumeSession).toHaveBeenCalledWith({ id: 'ses_existing' });
+    expect(mocks.session.getStatus).toHaveBeenCalled();
+    expect(mocks.session.setPermission).toHaveBeenNthCalledWith(1, 'auto');
+    expect(mocks.session.setPermission).toHaveBeenNthCalledWith(2, 'manual');
+  });
+
+  it('applies the CLI model override to resumed prompt sessions', async () => {
+    await runPrompt(opts({ session: 'ses_existing', model: 'kimi-code/k2.5' }), '1.2.3-test', {
+      stdout: { write: vi.fn(() => true) },
+      stderr: { write: vi.fn(() => true) },
+    });
+
+    expect(mocks.harnessResumeSession).toHaveBeenCalledWith({ id: 'ses_existing' });
+    expect(mocks.session.setModel).toHaveBeenCalledWith('kimi-code/k2.5');
+    expect(mocks.initializeTelemetry).toHaveBeenCalledWith(
+      expect.objectContaining({ model: 'kimi-code/k2.5' }),
+    );
+  });
+
+  it('writes stream-json output as assistant JSONL without transcript bullets', async () => {
+    const stdout = writer();
+    const stderr = writer();
+
+    await runPrompt(opts({ outputFormat: 'stream-json' }), '1.2.3-test', { stdout, stderr });
+
+    expect(stdout.text()).toBe('{"role":"assistant","content":"hello world"}\n');
+    expect(stderr.text()).toBe('To resume this session: kimi -r ses_prompt\n');
+  });
+
+  it('writes stream-json tool calls and tool results as JSONL messages', async () => {
+    mocks.session.prompt.mockImplementationOnce(async () => {
+      for (const handler of mocks.eventHandlers) {
+        handler(
+          mocks.mainEvent({ type: 'turn.started', turnId: 8, origin: { kind: 'user' } }),
+        );
+        handler(mocks.mainEvent({ type: 'assistant.delta', turnId: 8, delta: 'checking' }));
+        handler(
+          mocks.mainEvent({
+            type: 'tool.call.started',
+            turnId: 8,
+            toolCallId: 'tc_1',
+            name: 'Shell',
+            args: { command: 'ls' },
+          }),
+        );
+        handler(
+          mocks.mainEvent({
+            type: 'tool.result',
+            turnId: 8,
+            toolCallId: 'tc_1',
+            output: 'file1.py\nfile2.py',
+          }),
+        );
+        handler(mocks.mainEvent({ type: 'assistant.delta', turnId: 8, delta: 'done' }));
+        handler(mocks.mainEvent({ type: 'turn.ended', turnId: 8, reason: 'completed' }));
+      }
+    });
+    const stdout = writer();
+    const stderr = writer();
+
+    await runPrompt(opts({ outputFormat: 'stream-json' }), '1.2.3-test', { stdout, stderr });
+
+    expect(stdout.text()).toBe(
+      [
+        '{"role":"assistant","content":"checking","tool_calls":[{"type":"function","id":"tc_1","function":{"name":"Shell","arguments":"{\\"command\\":\\"ls\\"}"}}]}',
+        '{"role":"tool","tool_call_id":"tc_1","content":"file1.py\\nfile2.py"}',
+        '{"role":"assistant","content":"done"}',
+        '',
+      ].join('\n'),
+    );
+  });
+
+  it('resumes a concrete session without a configured default model', async () => {
+    mocks.harnessGetConfig.mockResolvedValueOnce({ providers: {}, telemetry: true });
+    mocks.session.getStatus.mockResolvedValueOnce({ permission: 'manual', model: 'saved-model' });
+
+    await runPrompt(opts({ session: 'ses_existing' }), '1.2.3-test', {
+      stdout: { write: vi.fn(() => true) },
+      stderr: { write: vi.fn(() => true) },
+    });
+
+    expect(mocks.harnessResumeSession).toHaveBeenCalledWith({ id: 'ses_existing' });
+    expect(mocks.harnessCreateSession).not.toHaveBeenCalled();
+    expect(mocks.initializeTelemetry).toHaveBeenCalledWith(
+      expect.objectContaining({ model: 'saved-model' }),
+    );
+    expect(mocks.session.setPermission).toHaveBeenNthCalledWith(1, 'auto');
+    expect(mocks.session.setPermission).toHaveBeenNthCalledWith(2, 'manual');
+  });
+
+  it('continues the previous workdir session when --continue is used', async () => {
+    await runPrompt(opts({ continue: true }), '1.2.3-test', {
+      stdout: { write: vi.fn(() => true) },
+      stderr: { write: vi.fn(() => true) },
+    });
+
+    expect(mocks.harnessListSessions).toHaveBeenCalledWith({ workDir: process.cwd() });
+    expect(mocks.harnessResumeSession).toHaveBeenCalledWith({ id: 'ses_previous' });
+    expect(mocks.session.setPermission).toHaveBeenNthCalledWith(1, 'auto');
+    expect(mocks.session.setPermission).toHaveBeenNthCalledWith(2, 'manual');
+  });
+
+  it('continues a previous session without a configured default model', async () => {
+    mocks.harnessGetConfig.mockResolvedValueOnce({ providers: {}, telemetry: true });
+    mocks.session.getStatus.mockResolvedValueOnce({ permission: 'manual', model: 'saved-model' });
+
+    await runPrompt(opts({ continue: true }), '1.2.3-test', {
+      stdout: { write: vi.fn(() => true) },
+      stderr: { write: vi.fn(() => true) },
+    });
+
+    expect(mocks.harnessListSessions).toHaveBeenCalledWith({ workDir: process.cwd() });
+    expect(mocks.harnessResumeSession).toHaveBeenCalledWith({ id: 'ses_previous' });
+    expect(mocks.harnessCreateSession).not.toHaveBeenCalled();
+    expect(mocks.initializeTelemetry).toHaveBeenCalledWith(
+      expect.objectContaining({ model: 'saved-model' }),
+    );
+  });
+
+  it('restores resumed session permission even when the turn fails', async () => {
+    mocks.session.prompt.mockImplementationOnce(async () => {
+      for (const handler of mocks.eventHandlers) {
+        handler(
+          mocks.mainEvent({ type: 'turn.started', turnId: 5, origin: { kind: 'user' } }),
+        );
+        handler(
+          mocks.mainEvent({
+            type: 'turn.ended',
+            turnId: 5,
+            reason: 'failed',
+            error: { code: 'provider.error', message: 'model failed' },
+          }),
+        );
+      }
+    });
+
+    await expect(
+      runPrompt(opts({ session: 'ses_existing' }), '1.2.3-test', {
+        stdout: { write: vi.fn(() => true) },
+        stderr: { write: vi.fn(() => true) },
+      }),
+    ).rejects.toThrow('provider.error: model failed');
+
+    expect(mocks.session.setPermission).toHaveBeenNthCalledWith(1, 'auto');
+    expect(mocks.session.setPermission).toHaveBeenNthCalledWith(2, 'manual');
+    expect(mocks.session.setPermission.mock.invocationCallOrder[1]).toBeLessThan(
+      mocks.harnessClose.mock.invocationCallOrder[0]!,
+    );
+  });
+
+  it('restores resumed session permission before exiting on SIGINT', async () => {
+    let releasePrompt!: () => void;
+    mocks.session.prompt.mockImplementationOnce(async () => {
+      for (const handler of mocks.eventHandlers) {
+        handler(
+          mocks.mainEvent({ type: 'turn.started', turnId: 6, origin: { kind: 'user' } }),
+        );
+      }
+      await new Promise<void>((resolve) => {
+        releasePrompt = resolve;
+      });
+    });
+    const processMock = fakeProcess();
+    const run = runPrompt(opts({ session: 'ses_existing' }), '1.2.3-test', {
+      stdout: { write: vi.fn(() => true) },
+      stderr: { write: vi.fn(() => true) },
+      process: processMock,
+    } as Parameters<typeof runPrompt>[2] & { process: ReturnType<typeof fakeProcess> });
+
+    await waitForAssertion(() => {
+      expect(mocks.session.setPermission).toHaveBeenCalledWith('auto');
+      expect(processMock.listener('SIGINT')).toBeDefined();
+    });
+
+    await processMock.listener('SIGINT')?.();
+
+    expect(mocks.session.setPermission).toHaveBeenNthCalledWith(2, 'manual');
+    expect(mocks.session.setPermission.mock.invocationCallOrder[1]).toBeLessThan(
+      processMock.exit.mock.invocationCallOrder[0]!,
+    );
+    expect(mocks.shutdownTelemetry).toHaveBeenCalled();
+    expect(mocks.harnessClose).toHaveBeenCalled();
+    expect(processMock.exit).toHaveBeenCalledWith(130);
+
+    for (const handler of mocks.eventHandlers) {
+      handler(mocks.mainEvent({ type: 'turn.ended', turnId: 6, reason: 'completed' }));
+    }
+    releasePrompt();
+    await run;
+
+    expect(mocks.harnessClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('waits for the pending auto permission write before signal restore', async () => {
+    let releaseAutoPermission!: () => void;
+    let releasePrompt!: () => void;
+    mocks.session.setPermission.mockImplementationOnce(async () => {
+      await new Promise<void>((resolve) => {
+        releaseAutoPermission = resolve;
+      });
+    });
+    mocks.session.prompt.mockImplementationOnce(async () => {
+      for (const handler of mocks.eventHandlers) {
+        handler(
+          mocks.mainEvent({ type: 'turn.started', turnId: 7, origin: { kind: 'user' } }),
+        );
+      }
+      await new Promise<void>((resolve) => {
+        releasePrompt = resolve;
+      });
+    });
+    const processMock = fakeProcess();
+    const run = runPrompt(opts({ session: 'ses_existing' }), '1.2.3-test', {
+      stdout: { write: vi.fn(() => true) },
+      stderr: { write: vi.fn(() => true) },
+      process: processMock,
+    } as Parameters<typeof runPrompt>[2] & { process: ReturnType<typeof fakeProcess> });
+
+    await waitForAssertion(() => {
+      expect(processMock.listener('SIGINT')).toBeDefined();
+      expect(mocks.session.setPermission).toHaveBeenCalledWith('auto');
+    });
+    expect(processMock.once.mock.invocationCallOrder[0]).toBeLessThan(
+      mocks.session.setPermission.mock.invocationCallOrder[0]!,
+    );
+
+    const signalCleanup = processMock.listener('SIGINT')?.();
+    await Promise.resolve();
+
+    expect(mocks.session.setPermission).toHaveBeenCalledTimes(1);
+
+    releaseAutoPermission();
+    await signalCleanup;
+
+    expect(mocks.session.setPermission).toHaveBeenNthCalledWith(2, 'manual');
+    expect(processMock.exit).toHaveBeenCalledWith(130);
+
+    await waitForAssertion(() => {
+      expect(mocks.session.prompt).toHaveBeenCalledWith('say hello');
+    });
+    for (const handler of mocks.eventHandlers) {
+      handler(mocks.mainEvent({ type: 'turn.ended', turnId: 7, reason: 'completed' }));
+    }
+    releasePrompt();
+    await run;
+  });
+
+  it('uses auto permission so headless mode can bypass plan approval and questions', async () => {
+    await runPrompt(opts(), '1.2.3-test', {
+      stdout: { write: vi.fn(() => true) },
+      stderr: { write: vi.fn(() => true) },
+    });
+
+    expect(mocks.harnessCreateSession).toHaveBeenCalledWith(
+      expect.objectContaining({ permission: 'auto' }),
+    );
+  });
+
+  it('throws when no default model is configured', async () => {
+    mocks.harnessGetConfig.mockResolvedValueOnce({ providers: {}, telemetry: true });
+
+    await expect(
+      runPrompt(opts(), '1.2.3-test', {
+        stdout: { write: vi.fn(() => true) },
+        stderr: { write: vi.fn(() => true) },
+      }),
+    ).rejects.toThrow('No model configured. Set default_model in config.toml.');
+
+    expect(mocks.harnessClose).toHaveBeenCalled();
+  });
+
+  it('rejects when the turn fails and still closes resources', async () => {
+    mocks.session.prompt.mockImplementationOnce(async () => {
+      for (const handler of mocks.eventHandlers) {
+        handler(
+          mocks.mainEvent({ type: 'turn.started', turnId: 2, origin: { kind: 'user' } }),
+        );
+        handler(
+          mocks.mainEvent({
+            type: 'turn.ended',
+            turnId: 2,
+            reason: 'failed',
+            error: { code: 'provider.error', message: 'model failed' },
+          }),
+        );
+      }
+    });
+
+    await expect(
+      runPrompt(opts(), '1.2.3-test', {
+        stdout: { write: vi.fn(() => true) },
+        stderr: { write: vi.fn(() => true) },
+      }),
+    ).rejects.toThrow('provider.error: model failed');
+
+    expect(mocks.shutdownTelemetry).toHaveBeenCalled();
+    expect(mocks.harnessClose).toHaveBeenCalled();
+  });
+
+  it('approval fallback approves if an unexpected approval request reaches SDK', async () => {
+    await runPrompt(opts(), '1.2.3-test', {
+      stdout: { write: vi.fn(() => true) },
+      stderr: { write: vi.fn(() => true) },
+    });
+
+    const handler = mocks.session.setApprovalHandler.mock.calls[0]![0] as () => unknown;
+    expect(handler()).toEqual({ decision: 'approved' });
+  });
+
+  it('question fallback returns null so prompt mode never opens a question UI', async () => {
+    await runPrompt(opts(), '1.2.3-test', {
+      stdout: { write: vi.fn(() => true) },
+      stderr: { write: vi.fn(() => true) },
+    });
+
+    const handler = mocks.session.setQuestionHandler.mock.calls[0]![0] as () => unknown;
+    expect(handler()).toBeNull();
+  });
+});
diff --git a/apps/kimi-code/test/cli/run-shell.test.ts b/apps/kimi-code/test/cli/run-shell.test.ts
new file mode 100644
index 000000000..64f9e02aa
--- /dev/null
+++ b/apps/kimi-code/test/cli/run-shell.test.ts
@@ -0,0 +1,535 @@
+import { execSync } from 'node:child_process';
+
+import type { createKimiDeviceId as createKimiDeviceIdFn } from '@moonshot-ai/kimi-code-oauth';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { runShell } from '#/cli/run-shell';
+
+import { captureProcessWrite, ExitCalled, mockProcessExit } from '../helpers/process';
+
+type CreateKimiDeviceId = typeof createKimiDeviceIdFn;
+
+const mocks = vi.hoisted(() => {
+  type TuiConfigFallback = {
+    theme: 'dark' | 'light' | 'auto';
+    editorCommand: string | null;
+    notifications: { enabled: boolean; condition: 'unfocused' | 'always' };
+  };
+
+  class TuiConfigParseError extends Error {
+    readonly fallback: TuiConfigFallback;
+
+    constructor(fallback: TuiConfigFallback) {
+      super('Invalid TUI config in ~/.kimi-code/tui.toml; using defaults.');
+      this.fallback = fallback;
+    }
+  }
+
+  const lifecycleTrack = vi.fn();
+
+  return {
+    loadTuiConfig: vi.fn(),
+    detectTerminalTheme: vi.fn(),
+    kimiHarnessConstructor: vi.fn(),
+    harnessEnsureConfigFile: vi.fn(),
+    harnessGetConfig: vi.fn(async () => ({
+      providers: {},
+      defaultModel: 'k2',
+      telemetry: true,
+    })),
+    harnessGetCachedAccessToken: vi.fn(),
+    harnessClose: vi.fn(),
+    detectPendingMigration: vi.fn<() => Promise<unknown>>(async () => null),
+    harnessTrack: vi.fn(),
+    kimiTuiConstructor: vi.fn(),
+    tuiStart: vi.fn(),
+    tuiGetStartupMcpMs: vi.fn(async () => 0),
+    tuiGetCurrentSessionId: vi.fn(() => ''),
+    tuiHasSessionContent: vi.fn(() => false),
+    createKimiDeviceId: vi.fn<CreateKimiDeviceId>(() => 'device-1'),
+    initializeTelemetry: vi.fn(),
+    setCrashPhase: vi.fn(),
+    shutdownTelemetry: vi.fn(),
+    telemetryTrack: vi.fn(),
+    setTelemetryContext: vi.fn(),
+    lifecycleTrack,
+    withTelemetryContext: vi.fn(() => ({
+      track: lifecycleTrack,
+    })),
+    execSync: vi.fn(),
+    TuiConfigParseError,
+  };
+});
+
+vi.mock('@moonshot-ai/kimi-code-sdk', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@moonshot-ai/kimi-code-sdk')>();
+  return {
+    ...actual,
+    KimiHarness: class {
+      homeDir = '/tmp/kimi-code-test-home';
+      auth = {
+        getCachedAccessToken: mocks.harnessGetCachedAccessToken,
+      };
+      ensureConfigFile = mocks.harnessEnsureConfigFile;
+      getConfig = mocks.harnessGetConfig;
+      close = mocks.harnessClose;
+      track = mocks.harnessTrack;
+
+      constructor(...args: unknown[]) {
+        mocks.kimiHarnessConstructor(...args);
+      }
+    },
+  };
+});
+
+vi.mock('@moonshot-ai/kimi-code-oauth', async () => {
+  const actual = await vi.importActual<typeof import('@moonshot-ai/kimi-code-oauth')>(
+    '@moonshot-ai/kimi-code-oauth',
+  );
+  return {
+    ...actual,
+    createKimiDeviceId: mocks.createKimiDeviceId,
+    KIMI_CODE_PROVIDER_NAME: 'kimi-code',
+  };
+});
+
+vi.mock('@moonshot-ai/kimi-telemetry', () => ({
+  initializeTelemetry: mocks.initializeTelemetry,
+  setCrashPhase: mocks.setCrashPhase,
+  shutdownTelemetry: mocks.shutdownTelemetry,
+  track: mocks.telemetryTrack,
+  setTelemetryContext: mocks.setTelemetryContext,
+  withTelemetryContext: mocks.withTelemetryContext,
+}));
+
+vi.mock('../../src/tui/config', () => ({
+  loadTuiConfig: mocks.loadTuiConfig,
+  TuiConfigParseError: mocks.TuiConfigParseError,
+}));
+
+vi.mock('../../src/tui/index', () => ({
+  KimiTUI: class {
+    onExit?: () => Promise<void>;
+
+    constructor(...args: unknown[]) {
+      mocks.kimiTuiConstructor(this, ...args);
+    }
+
+    start = mocks.tuiStart;
+    getStartupMcpMs = mocks.tuiGetStartupMcpMs;
+    getCurrentSessionId = mocks.tuiGetCurrentSessionId;
+    hasSessionContent = mocks.tuiHasSessionContent;
+  },
+}));
+
+vi.mock('../../src/tui/theme/detect', () => ({
+  detectTerminalTheme: mocks.detectTerminalTheme,
+}));
+
+vi.mock('../../src/migration/index', () => ({
+  detectPendingMigration: mocks.detectPendingMigration,
+}));
+
+vi.mock('node:child_process', () => ({
+  execSync: mocks.execSync,
+}));
+
+describe('runShell', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+    mocks.harnessGetConfig.mockResolvedValue({
+      providers: {},
+      defaultModel: 'k2',
+      telemetry: true,
+    });
+    mocks.tuiGetStartupMcpMs.mockResolvedValue(0);
+    mocks.tuiGetCurrentSessionId.mockReturnValue('');
+    mocks.tuiHasSessionContent.mockReturnValue(false);
+  });
+
+  it('constructs KimiHarness and KimiTUI with startup input', async () => {
+    mocks.loadTuiConfig.mockResolvedValue({
+      theme: 'dark',
+      editorCommand: null,
+      notifications: { enabled: true, condition: 'unfocused' },
+    });
+    mocks.tuiStart.mockResolvedValue(undefined);
+    mocks.tuiGetStartupMcpMs.mockResolvedValue(47);
+    mocks.tuiGetCurrentSessionId.mockReturnValue('ses-startup');
+
+    const cliOptions = {
+      session: undefined,
+      continue: false,
+      yolo: true,
+      plan: true,
+      model: undefined,
+      outputFormat: undefined,
+      prompt: undefined,
+      skillsDirs: [],
+    };
+
+    await runShell(cliOptions, '1.2.3-test');
+
+    expect(mocks.kimiHarnessConstructor).toHaveBeenCalledWith(
+      expect.objectContaining({
+        identity: expect.objectContaining({
+          userAgentProduct: 'kimi-code-cli',
+          version: '1.2.3-test',
+        }),
+      }),
+    );
+    expect(mocks.harnessEnsureConfigFile).toHaveBeenCalledOnce();
+    expect(mocks.harnessEnsureConfigFile.mock.invocationCallOrder[0]).toBeLessThan(
+      mocks.harnessGetConfig.mock.invocationCallOrder[0]!,
+    );
+    expect(execSync).toHaveBeenCalledWith('stty -ixon', { stdio: 'ignore' });
+    expect(mocks.kimiTuiConstructor).toHaveBeenCalledTimes(1);
+    expect(mocks.createKimiDeviceId).toHaveBeenCalledWith(
+      '/tmp/kimi-code-test-home',
+      expect.any(Object),
+    );
+    expect(mocks.initializeTelemetry).toHaveBeenCalledWith({
+      homeDir: '/tmp/kimi-code-test-home',
+      deviceId: 'device-1',
+      enabled: true,
+      appName: 'kimi-code-cli',
+      version: '1.2.3-test',
+      uiMode: 'shell',
+      model: 'k2',
+      getAccessToken: expect.any(Function),
+    });
+    expect(mocks.setCrashPhase).toHaveBeenCalledWith('runtime');
+
+    const [, harness, startupInput] = mocks.kimiTuiConstructor.mock.calls[0]!;
+    expect(harness).toBeTypeOf('object');
+    expect(startupInput).toMatchObject({
+      cliOptions,
+      tuiConfig: {
+        theme: 'dark',
+        editorCommand: null,
+        notifications: { enabled: true, condition: 'unfocused' },
+      },
+      version: '1.2.3-test',
+      workDir: process.cwd(),
+      resolvedTheme: 'dark',
+    });
+    expect(mocks.tuiStart).toHaveBeenCalledOnce();
+    expect(mocks.harnessTrack).not.toHaveBeenCalledWith('started', expect.anything());
+    expect(mocks.withTelemetryContext).toHaveBeenCalledWith({ sessionId: 'ses-startup' });
+    expect(mocks.lifecycleTrack).toHaveBeenCalledWith('started', {
+      resumed: false,
+      yolo: true,
+      plan: true,
+      afk: false,
+    });
+    expect(mocks.lifecycleTrack).toHaveBeenCalledWith('startup_perf', {
+      duration_ms: expect.any(Number),
+      config_ms: expect.any(Number),
+      init_ms: expect.any(Number),
+      mcp_ms: 47,
+    });
+  });
+
+  it('tracks first launch when device id creation reports first launch', async () => {
+    mocks.loadTuiConfig.mockResolvedValue({
+      theme: 'dark',
+      editorCommand: null,
+      notifications: { enabled: true, condition: 'unfocused' },
+    });
+    mocks.tuiStart.mockResolvedValue(undefined);
+    mocks.createKimiDeviceId.mockImplementationOnce((homeDir, options) => {
+      const deviceId = `device-for-${homeDir}`;
+      options?.onFirstLaunch?.(deviceId);
+      return deviceId;
+    });
+
+    await runShell(
+      {
+        session: undefined,
+        continue: false,
+        yolo: false,
+        plan: false,
+        model: undefined,
+        outputFormat: undefined,
+        prompt: undefined,
+        skillsDirs: [],
+      },
+      '1.2.3-test',
+    );
+
+    expect(mocks.createKimiDeviceId).toHaveBeenCalledWith(
+      '/tmp/kimi-code-test-home',
+      expect.objectContaining({ onFirstLaunch: expect.any(Function) }),
+    );
+    expect(mocks.harnessTrack).toHaveBeenCalledWith('first_launch');
+  });
+
+  it('marks resumed lifecycle starts from session flags', async () => {
+    mocks.loadTuiConfig.mockResolvedValue({
+      theme: 'dark',
+      editorCommand: null,
+      notifications: { enabled: true, condition: 'unfocused' },
+    });
+    mocks.tuiStart.mockResolvedValue(undefined);
+    mocks.tuiGetCurrentSessionId.mockReturnValue('ses-1');
+
+    await runShell(
+      {
+        session: 'ses-1',
+        continue: false,
+        yolo: false,
+        plan: false,
+        model: undefined,
+        outputFormat: undefined,
+        prompt: undefined,
+        skillsDirs: [],
+      },
+      '1.2.3-test',
+    );
+
+    expect(mocks.lifecycleTrack).toHaveBeenCalledWith('started', {
+      resumed: true,
+      yolo: false,
+      plan: false,
+      afk: false,
+    });
+  });
+
+  it('binds startup_perf to the session captured before MCP metrics resolve', async () => {
+    mocks.loadTuiConfig.mockResolvedValue({
+      theme: 'dark',
+      editorCommand: null,
+      notifications: { enabled: true, condition: 'unfocused' },
+    });
+    mocks.tuiStart.mockResolvedValue(undefined);
+    let currentSessionId = 'ses-startup';
+    mocks.tuiGetCurrentSessionId.mockImplementation(() => currentSessionId);
+    mocks.tuiGetStartupMcpMs.mockImplementation(async () => {
+      currentSessionId = 'ses-later';
+      return 47;
+    });
+
+    await runShell(
+      {
+        session: undefined,
+        continue: false,
+        yolo: false,
+        plan: false,
+        model: undefined,
+        outputFormat: undefined,
+        prompt: undefined,
+        skillsDirs: [],
+      },
+      '1.2.3-test',
+    );
+
+    expect(mocks.withTelemetryContext).toHaveBeenNthCalledWith(1, { sessionId: 'ses-startup' });
+    expect(mocks.withTelemetryContext).toHaveBeenNthCalledWith(2, { sessionId: 'ses-startup' });
+    expect(mocks.lifecycleTrack).toHaveBeenNthCalledWith(2, 'startup_perf', {
+      duration_ms: expect.any(Number),
+      config_ms: expect.any(Number),
+      init_ms: expect.any(Number),
+      mcp_ms: 47,
+    });
+  });
+
+  it('bridges OAuth refresh outcomes to telemetry', async () => {
+    mocks.loadTuiConfig.mockResolvedValue({
+      theme: 'dark',
+      editorCommand: null,
+      notifications: { enabled: true, condition: 'unfocused' },
+    });
+    mocks.tuiStart.mockResolvedValue(undefined);
+
+    await runShell(
+      {
+        session: undefined,
+        continue: false,
+        yolo: false,
+        plan: false,
+        model: undefined,
+        outputFormat: undefined,
+        prompt: undefined,
+        skillsDirs: [],
+      },
+      '1.2.3-test',
+    );
+
+    const [harnessOptions] = mocks.kimiHarnessConstructor.mock.calls[0] as [
+      {
+        readonly onOAuthRefresh: (
+          outcome:
+            | { readonly success: true }
+            | { readonly success: false; readonly reason: 'unauthorized' | 'network_or_other' },
+        ) => void;
+      },
+    ];
+
+    harnessOptions.onOAuthRefresh({ success: true });
+    harnessOptions.onOAuthRefresh({ success: false, reason: 'unauthorized' });
+    harnessOptions.onOAuthRefresh({ success: false, reason: 'network_or_other' });
+
+    expect(mocks.telemetryTrack).toHaveBeenCalledWith('oauth_refresh', { success: true });
+    expect(mocks.telemetryTrack).toHaveBeenCalledWith('oauth_refresh', {
+      success: false,
+      reason: 'unauthorized',
+    });
+    expect(mocks.telemetryTrack).toHaveBeenCalledWith('oauth_refresh', {
+      success: false,
+      reason: 'network_or_other',
+    });
+  });
+
+  it('detects auto theme and forwards config parse warnings as startup notice', async () => {
+    mocks.loadTuiConfig.mockRejectedValue(
+      new mocks.TuiConfigParseError({
+        theme: 'auto',
+        editorCommand: 'vim',
+        notifications: { enabled: true, condition: 'always' },
+      }),
+    );
+    mocks.detectTerminalTheme.mockResolvedValue('light');
+    mocks.tuiStart.mockResolvedValue(undefined);
+
+    await runShell(
+      {
+        session: '',
+        continue: false,
+        yolo: false,
+        plan: false,
+        model: undefined,
+        outputFormat: undefined,
+        prompt: undefined,
+        skillsDirs: [],
+      },
+      '1.2.3-test',
+    );
+
+    expect(mocks.detectTerminalTheme).toHaveBeenCalledOnce();
+    const [, , startupInput] = mocks.kimiTuiConstructor.mock.calls[0]!;
+    expect(startupInput).toMatchObject({
+      startupNotice: 'Invalid TUI config in ~/.kimi-code/tui.toml; using defaults.',
+      resolvedTheme: 'light',
+      tuiConfig: {
+        theme: 'auto',
+        editorCommand: 'vim',
+        notifications: { enabled: true, condition: 'always' },
+      },
+    });
+  });
+
+  it('closes the harness when TUI startup fails', async () => {
+    mocks.loadTuiConfig.mockResolvedValue({
+      theme: 'dark',
+      editorCommand: null,
+      notifications: { enabled: true, condition: 'unfocused' },
+    });
+    mocks.tuiStart.mockRejectedValue(new Error('boom'));
+
+    await expect(
+      runShell(
+        {
+          session: undefined,
+          continue: false,
+          yolo: false,
+          plan: false,
+          model: undefined,
+          outputFormat: undefined,
+          prompt: undefined,
+          skillsDirs: [],
+        },
+        '1.2.3-test',
+      ),
+    ).rejects.toThrow('boom');
+
+    expect(mocks.setCrashPhase).toHaveBeenCalledWith('shutdown');
+    expect(mocks.harnessTrack).toHaveBeenCalledWith('exit', { duration_s: expect.any(Number) });
+    expect(mocks.shutdownTelemetry).toHaveBeenCalledOnce();
+    expect(mocks.harnessClose).toHaveBeenCalledOnce();
+  });
+
+  it('tracks exit and prints resume instructions from the TUI exit handler', async () => {
+    mocks.loadTuiConfig.mockResolvedValue({
+      theme: 'dark',
+      editorCommand: null,
+      notifications: { enabled: true, condition: 'unfocused' },
+    });
+    mocks.tuiStart.mockResolvedValue(undefined);
+    mocks.tuiGetCurrentSessionId.mockReturnValue('ses-1');
+    mocks.tuiHasSessionContent.mockReturnValue(true);
+
+    const stdout = captureProcessWrite('stdout');
+    const stderr = captureProcessWrite('stderr');
+    const exitSpy = mockProcessExit();
+
+    try {
+      await runShell(
+        {
+          session: undefined,
+          continue: false,
+          yolo: false,
+          plan: false,
+          model: undefined,
+          outputFormat: undefined,
+          prompt: undefined,
+          skillsDirs: [],
+        },
+        '1.2.3-test',
+      );
+      const [tui] = mocks.kimiTuiConstructor.mock.calls[0]!;
+      mocks.harnessTrack.mockClear();
+      mocks.lifecycleTrack.mockClear();
+      mocks.withTelemetryContext.mockClear();
+
+      await expect((tui as { onExit: () => Promise<void> }).onExit()).rejects.toBeInstanceOf(
+        ExitCalled,
+      );
+
+      expect(mocks.setCrashPhase).toHaveBeenCalledWith('shutdown');
+      expect(mocks.withTelemetryContext).toHaveBeenCalledWith({ sessionId: 'ses-1' });
+      expect(mocks.lifecycleTrack).toHaveBeenCalledWith('exit', {
+        duration_s: expect.any(Number),
+      });
+      expect(mocks.harnessTrack).not.toHaveBeenCalledWith('exit', expect.anything());
+      expect(mocks.shutdownTelemetry).toHaveBeenCalledOnce();
+      expect(stdout.text()).toBe(' Bye!\n');
+      expect(stderr.text()).toContain(' To resume this session: kimi -r ses-1');
+    } finally {
+      exitSpy.mockRestore();
+      stdout.restore();
+      stderr.restore();
+    }
+  });
+
+  it('surfaces an invalid target config as an error for kimi migrate, not silently', async () => {
+    mocks.loadTuiConfig.mockResolvedValue({
+      theme: 'dark',
+      editorCommand: null,
+      notifications: { enabled: true, condition: 'unfocused' },
+    });
+    mocks.detectPendingMigration.mockResolvedValue({ totalSessions: 1 });
+    mocks.harnessGetConfig.mockRejectedValue(
+      new Error('Invalid configuration in ~/.kimi-code/config.toml'),
+    );
+
+    // A broken config.toml must fail loudly — `kimi migrate` must not swallow
+    // it and proceed, or the user never learns their config is broken.
+    await expect(
+      runShell(
+        {
+          session: undefined,
+          continue: false,
+          yolo: false,
+          plan: false,
+          model: undefined,
+          outputFormat: undefined,
+          prompt: undefined,
+          skillsDirs: [],
+        },
+        '1.2.3-test',
+        { migrateOnly: true },
+      ),
+    ).rejects.toThrow('Invalid configuration');
+    expect(mocks.tuiStart).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/kimi-code/test/cli/session-flag-picker.test.ts b/apps/kimi-code/test/cli/session-flag-picker.test.ts
new file mode 100644
index 000000000..1f24560fa
--- /dev/null
+++ b/apps/kimi-code/test/cli/session-flag-picker.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+
+import { createProgram } from '#/cli/commands';
+import type { CLIOptions } from '#/cli/options';
+import { OptionConflictError, validateOptions } from '#/cli/options';
+
+function parse(argv: string[]): CLIOptions {
+  let captured: CLIOptions | undefined;
+  const program = createProgram(
+    '0.0.0-test',
+    (opts) => {
+      captured = opts;
+    },
+    () => {},
+  );
+  program.exitOverride();
+  program.configureOutput({
+    writeOut: () => {},
+    writeErr: () => {},
+  });
+  program.parse(['node', 'kimi', ...argv]);
+  if (captured === undefined) {
+    throw new Error('Main action handler was not called');
+  }
+  return captured;
+}
+
+describe('--session / -r / -S picker routing', () => {
+  describe('argParser: no-arg forms coerce to empty string', () => {
+    it('--session with no id → session === ""', () => {
+      const opts = parse(['--session']);
+      expect(opts.session).toBe('');
+    });
+
+    it('-S with no id → session === ""', () => {
+      const opts = parse(['-S']);
+      expect(opts.session).toBe('');
+    });
+
+    it('-r with no id → session === ""', () => {
+      const opts = parse(['-r']);
+      expect(opts.session).toBe('');
+    });
+  });
+
+  describe('argParser: id forms keep the id verbatim', () => {
+    it('--session foo → session === "foo"', () => {
+      const opts = parse(['--session', 'foo']);
+      expect(opts.session).toBe('foo');
+    });
+
+    it('-S foo → session === "foo"', () => {
+      const opts = parse(['-S', 'foo']);
+      expect(opts.session).toBe('foo');
+    });
+
+    it('-r foo → session === "foo" (hidden alias)', () => {
+      const opts = parse(['-r', 'foo']);
+      expect(opts.session).toBe('foo');
+    });
+  });
+
+  describe('validateOptions: empty session vs ui mode', () => {
+    it('empty session + shell mode → OK, session stays ""', () => {
+      const { options, uiMode } = validateOptions(parse(['--session']));
+      expect(uiMode).toBe('shell');
+      expect(options.session).toBe('');
+    });
+
+    // Note: --print / --wire are held back from the first release, so
+    // the "picker + print/wire" combinations can't be constructed via
+    // Commander anymore. The validateOptions guard still lives in
+    // source for when those flags return.
+  });
+
+  // Silence unused-import warning kept for the preserved guard tests.
+  void OptionConflictError;
+});
diff --git a/apps/kimi-code/test/cli/update/cache.test.ts b/apps/kimi-code/test/cli/update/cache.test.ts
new file mode 100644
index 000000000..a1ba436bc
--- /dev/null
+++ b/apps/kimi-code/test/cli/update/cache.test.ts
@@ -0,0 +1,62 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { readUpdateCache, writeUpdateCache } from '#/cli/update/cache';
+import { emptyUpdateCache } from '#/cli/update/types';
+import { getUpdateStateFile } from '#/utils/paths';
+
+const originalEnv = { ...process.env };
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'kimi-update-cache-'));
+  process.env['KIMI_CODE_HOME'] = dir;
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+  process.env = { ...originalEnv };
+});
+
+describe('update cache', () => {
+  it('returns an empty cache when the file is missing', async () => {
+    await expect(readUpdateCache()).resolves.toEqual(emptyUpdateCache());
+  });
+
+  it('falls back to an empty cache when the file is corrupt', async () => {
+    mkdirSync(join(dir, 'updates'), { recursive: true });
+    writeFileSync(getUpdateStateFile(), '{"broken"', 'utf-8');
+    await expect(readUpdateCache()).resolves.toEqual(emptyUpdateCache());
+  });
+
+  it('falls back to an empty cache when the file has the old npm.json shape', async () => {
+    mkdirSync(join(dir, 'updates'), { recursive: true });
+    writeFileSync(
+      getUpdateStateFile(),
+      JSON.stringify({
+        packageName: '@moonshot-ai/kimi-code',
+        checkedAt: '2026-04-23T08:00:00.000Z',
+        distTags: { beta: '0.0.1-beta.1' },
+      }),
+      'utf-8',
+    );
+    await expect(readUpdateCache()).resolves.toEqual(emptyUpdateCache());
+  });
+
+  it('writes and reads back the cache from updates/latest.json', async () => {
+    const cache = {
+      source: 'cdn',
+      checkedAt: '2026-04-23T08:00:00.000Z',
+      latest: '0.5.0',
+    } as const;
+
+    await writeUpdateCache(cache);
+
+    expect(getUpdateStateFile()).toBe(join(dir, 'updates', 'latest.json'));
+    await expect(readUpdateCache()).resolves.toEqual(cache);
+  });
+});
diff --git a/apps/kimi-code/test/cli/update/cdn.test.ts b/apps/kimi-code/test/cli/update/cdn.test.ts
new file mode 100644
index 000000000..3127bd71d
--- /dev/null
+++ b/apps/kimi-code/test/cli/update/cdn.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { fetchLatestVersionFromCdn } from '#/cli/update/cdn';
+import { KIMI_CODE_CDN_LATEST_URL } from '#/constant/app';
+
+function mockFetchOk(body: string): typeof fetch {
+  return vi.fn(async () => ({
+    ok: true,
+    status: 200,
+    text: async () => body,
+  })) as unknown as typeof fetch;
+}
+
+function mockFetchStatus(status: number): typeof fetch {
+  return vi.fn(async () => ({
+    ok: status >= 200 && status < 300,
+    status,
+    text: async () => '',
+  })) as unknown as typeof fetch;
+}
+
+describe('fetchLatestVersionFromCdn', () => {
+  it('returns the trimmed semver returned by CDN /latest', async () => {
+    const f = mockFetchOk('  0.5.0\n');
+    await expect(fetchLatestVersionFromCdn(f)).resolves.toBe('0.5.0');
+    expect(f).toHaveBeenCalledWith(KIMI_CODE_CDN_LATEST_URL);
+  });
+
+  it('throws when response is non-2xx', async () => {
+    await expect(fetchLatestVersionFromCdn(mockFetchStatus(404))).rejects.toThrow(/HTTP 404/);
+  });
+
+  it('throws when body is not valid semver', async () => {
+    await expect(fetchLatestVersionFromCdn(mockFetchOk('not-a-version'))).rejects.toThrow(
+      /invalid semver/,
+    );
+  });
+
+  it('throws when body is empty', async () => {
+    await expect(fetchLatestVersionFromCdn(mockFetchOk('   '))).rejects.toThrow(/invalid semver/);
+  });
+
+  it('propagates the underlying fetch error', async () => {
+    const f = vi.fn(async () => {
+      throw new Error('network down');
+    }) as unknown as typeof fetch;
+    await expect(fetchLatestVersionFromCdn(f)).rejects.toThrow(/network down/);
+  });
+});
diff --git a/apps/kimi-code/test/cli/update/preflight.test.ts b/apps/kimi-code/test/cli/update/preflight.test.ts
new file mode 100644
index 000000000..dc115c9e4
--- /dev/null
+++ b/apps/kimi-code/test/cli/update/preflight.test.ts
@@ -0,0 +1,269 @@
+import type * as ChildProcess from 'node:child_process';
+import { EventEmitter } from 'node:events';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { readUpdateCache } from '#/cli/update/cache';
+import { runUpdatePreflight } from '#/cli/update/preflight';
+import { promptForInstallConfirmation } from '#/cli/update/prompt';
+import type * as PromptModule from '#/cli/update/prompt';
+import { refreshUpdateCache } from '#/cli/update/refresh';
+import type * as RefreshModule from '#/cli/update/refresh';
+import { detectInstallSource } from '#/cli/update/source';
+import { emptyUpdateCache, type UpdateCache } from '#/cli/update/types';
+
+const mocks = vi.hoisted(() => ({
+  readUpdateCache: vi.fn(),
+  detectInstallSource: vi.fn(),
+  promptForInstallConfirmation: vi.fn(),
+  refreshUpdateCache: vi.fn(),
+  spawn: vi.fn(),
+}));
+
+vi.mock('../../../src/cli/update/cache', () => ({
+  readUpdateCache: mocks.readUpdateCache,
+}));
+
+vi.mock('../../../src/cli/update/source', () => ({
+  detectInstallSource: mocks.detectInstallSource,
+}));
+
+vi.mock('../../../src/cli/update/prompt', async () => {
+  const actual = await vi.importActual<typeof PromptModule>('../../../src/cli/update/prompt.js');
+  return {
+    ...actual,
+    promptForInstallConfirmation: mocks.promptForInstallConfirmation,
+  };
+});
+
+vi.mock('../../../src/cli/update/refresh', async () => {
+  const actual = await vi.importActual<typeof RefreshModule>('../../../src/cli/update/refresh.js');
+  return {
+    ...actual,
+    refreshUpdateCache: mocks.refreshUpdateCache,
+  };
+});
+
+vi.mock('node:child_process', async () => {
+  const actual = await vi.importActual<typeof ChildProcess>('node:child_process');
+  return {
+    ...actual,
+    spawn: mocks.spawn,
+  };
+});
+
+function cacheWith(version: string): UpdateCache {
+  return {
+    source: 'cdn',
+    checkedAt: '2026-04-23T08:00:00.000Z',
+    latest: version,
+  };
+}
+
+function captureOutput(): {
+  stdout: string[];
+  stderr: string[];
+  options: {
+    stdout: { write(chunk: string): boolean };
+    stderr: { write(chunk: string): boolean };
+    isTTY: boolean;
+  };
+} {
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  return {
+    stdout,
+    stderr,
+    options: {
+      stdout: { write: (chunk: string) => { stdout.push(chunk); return true; } },
+      stderr: { write: (chunk: string) => { stderr.push(chunk); return true; } },
+      isTTY: true,
+    },
+  };
+}
+
+function mockSpawnExit(code: number, signal: NodeJS.Signals | null = null): void {
+  mocks.spawn.mockImplementation(() => {
+    const child = new EventEmitter();
+    queueMicrotask(() => { child.emit('exit', code, signal); });
+    return child;
+  });
+}
+
+describe('runUpdatePreflight', () => {
+  afterEach(() => { vi.clearAllMocks(); });
+
+  it('continues on first launch with empty cache, still refreshes in background', async () => {
+    mocks.readUpdateCache.mockResolvedValue(emptyUpdateCache());
+    mocks.refreshUpdateCache.mockResolvedValue(emptyUpdateCache());
+    const { options } = captureOutput();
+
+    await expect(runUpdatePreflight('0.4.0', options)).resolves.toBe('continue');
+    expect(readUpdateCache).toHaveBeenCalledTimes(1);
+    expect(refreshUpdateCache).toHaveBeenCalledTimes(1);
+    expect(detectInstallSource).not.toHaveBeenCalled();
+  });
+
+  it('skips when non-interactive', async () => {
+    mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    const { options } = captureOutput();
+    await expect(
+      runUpdatePreflight('0.4.0', { ...options, isTTY: false }),
+    ).resolves.toBe('continue');
+    expect(detectInstallSource).not.toHaveBeenCalled();
+  });
+
+  it('npm-global: prompts and spawns npm install -g', async () => {
+    mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.detectInstallSource.mockResolvedValue('npm-global');
+    mocks.promptForInstallConfirmation.mockResolvedValue(true);
+    mockSpawnExit(0);
+    const { stdout, options } = captureOutput();
+
+    await expect(runUpdatePreflight('0.4.0', options)).resolves.toBe('exit');
+    expect(mocks.promptForInstallConfirmation).toHaveBeenCalledWith(
+      expect.objectContaining({
+        installCommand: 'npm install -g @moonshot-ai/kimi-code@0.5.0',
+        installSource: 'npm-global',
+      }),
+    );
+    expect(mocks.spawn).toHaveBeenCalledWith(
+      expect.stringMatching(/^npm(\.cmd)?$/),
+      ['install', '-g', '@moonshot-ai/kimi-code@0.5.0'],
+      { stdio: 'inherit' },
+    );
+    expect(stdout.join('')).toContain('Updated @moonshot-ai/kimi-code to 0.5.0');
+  });
+
+  it('pnpm-global: spawns pnpm add -g', async () => {
+    mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.detectInstallSource.mockResolvedValue('pnpm-global');
+    mocks.promptForInstallConfirmation.mockResolvedValue(true);
+    mockSpawnExit(0);
+    const { options } = captureOutput();
+    await runUpdatePreflight('0.4.0', options);
+    expect(mocks.spawn).toHaveBeenCalledWith(
+      expect.stringMatching(/^pnpm(\.cmd)?$/),
+      ['add', '-g', '@moonshot-ai/kimi-code@0.5.0'],
+      { stdio: 'inherit' },
+    );
+  });
+
+  it('yarn-global: spawns yarn global add', async () => {
+    mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.detectInstallSource.mockResolvedValue('yarn-global');
+    mocks.promptForInstallConfirmation.mockResolvedValue(true);
+    mockSpawnExit(0);
+    const { options } = captureOutput();
+    await runUpdatePreflight('0.4.0', options);
+    expect(mocks.spawn).toHaveBeenCalledWith(
+      expect.stringMatching(/^yarn(\.cmd)?$/),
+      ['global', 'add', '@moonshot-ai/kimi-code@0.5.0'],
+      { stdio: 'inherit' },
+    );
+  });
+
+  it('bun-global: spawns bun add -g', async () => {
+    mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.detectInstallSource.mockResolvedValue('bun-global');
+    mocks.promptForInstallConfirmation.mockResolvedValue(true);
+    mockSpawnExit(0);
+    const { options } = captureOutput();
+    await runUpdatePreflight('0.4.0', options);
+    expect(mocks.spawn).toHaveBeenCalledWith(
+      expect.stringMatching(/^bun(\.exe)?$/),
+      ['add', '-g', '@moonshot-ai/kimi-code@0.5.0'],
+      { stdio: 'inherit' },
+    );
+  });
+
+  it('native on darwin: spawns bash -c curl|bash', async () => {
+    mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.detectInstallSource.mockResolvedValue('native');
+    mocks.promptForInstallConfirmation.mockResolvedValue(true);
+    mockSpawnExit(0);
+    const originalPlatform = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'darwin' });
+    try {
+      const { options } = captureOutput();
+      await runUpdatePreflight('0.4.0', options);
+      expect(mocks.spawn).toHaveBeenCalledWith(
+        'bash',
+        ['-c', expect.stringContaining('curl -fsSL https://code.kimi.com/kimi-code/install.sh')],
+        { stdio: 'inherit' },
+      );
+    } finally {
+      Object.defineProperty(process, 'platform', { value: originalPlatform });
+    }
+  });
+
+  it('native on win32: prints manual powershell command, does not spawn', async () => {
+    mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.detectInstallSource.mockResolvedValue('native');
+    const originalPlatform = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'win32' });
+    try {
+      const { stdout, options } = captureOutput();
+      await expect(runUpdatePreflight('0.4.0', options)).resolves.toBe('continue');
+      expect(stdout.join('')).toContain('irm https://code.kimi.com/kimi-code/install.ps1 | iex');
+      expect(promptForInstallConfirmation).not.toHaveBeenCalled();
+      expect(mocks.spawn).not.toHaveBeenCalled();
+    } finally {
+      Object.defineProperty(process, 'platform', { value: originalPlatform });
+    }
+  });
+
+  it('unsupported: prints fallback npm command', async () => {
+    mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.detectInstallSource.mockResolvedValue('unsupported');
+    const { stdout, options } = captureOutput();
+    await expect(runUpdatePreflight('0.4.0', options)).resolves.toBe('continue');
+    expect(stdout.join('')).toContain('npm install -g @moonshot-ai/kimi-code@0.5.0');
+    expect(mocks.spawn).not.toHaveBeenCalled();
+  });
+
+  it('declined install continues without spawn', async () => {
+    mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.detectInstallSource.mockResolvedValue('npm-global');
+    mocks.promptForInstallConfirmation.mockResolvedValue(false);
+    const { options } = captureOutput();
+    await expect(runUpdatePreflight('0.4.0', options)).resolves.toBe('continue');
+    expect(mocks.spawn).not.toHaveBeenCalled();
+  });
+
+  it('warns and continues when spawn exits non-zero', async () => {
+    mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.detectInstallSource.mockResolvedValue('npm-global');
+    mocks.promptForInstallConfirmation.mockResolvedValue(true);
+    mockSpawnExit(1);
+    const { stderr, options } = captureOutput();
+    await expect(runUpdatePreflight('0.4.0', options)).resolves.toBe('continue');
+    expect(stderr.join('')).toContain('warning: failed to install');
+  });
+
+  it('tracks update_prompted telemetry', async () => {
+    mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+    mocks.detectInstallSource.mockResolvedValue('npm-global');
+    mocks.promptForInstallConfirmation.mockResolvedValue(false);
+    const { options } = captureOutput();
+    const track = vi.fn();
+    await runUpdatePreflight('0.4.0', { ...options, track });
+    expect(track).toHaveBeenCalledWith('update_prompted', expect.objectContaining({
+      current: '0.4.0',
+      latest: '0.5.0',
+      decision: 'prompt-install',
+      source: 'npm-global',
+    }));
+  });
+});
diff --git a/apps/kimi-code/test/cli/update/prompt.test.ts b/apps/kimi-code/test/cli/update/prompt.test.ts
new file mode 100644
index 000000000..b898ab654
--- /dev/null
+++ b/apps/kimi-code/test/cli/update/prompt.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  createInstallPromptChoices,
+  getDefaultInstallPromptSelection,
+  moveInstallPromptSelection,
+} from '#/cli/update/prompt';
+
+describe('install prompt helpers', () => {
+  it('defaults the selection to "Install update now"', () => {
+    const choices = createInstallPromptChoices({ version: '0.0.2-beta.1' });
+
+    expect(getDefaultInstallPromptSelection(choices)).toBe(0);
+    expect(choices[0]).toEqual({
+      value: 'install',
+      label: 'Install update now (0.0.2-beta.1)',
+    });
+    expect(choices[1]).toEqual({
+      value: 'skip',
+      label: 'Continue with current version',
+    });
+  });
+
+  it('moves selection with arrow directions and clamps at the edges', () => {
+    expect(moveInstallPromptSelection(1, 'up', 2)).toBe(0);
+    expect(moveInstallPromptSelection(0, 'up', 2)).toBe(0);
+    expect(moveInstallPromptSelection(0, 'down', 2)).toBe(1);
+    expect(moveInstallPromptSelection(1, 'down', 2)).toBe(1);
+  });
+});
diff --git a/apps/kimi-code/test/cli/update/refresh.test.ts b/apps/kimi-code/test/cli/update/refresh.test.ts
new file mode 100644
index 000000000..16a18d2f3
--- /dev/null
+++ b/apps/kimi-code/test/cli/update/refresh.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { refreshUpdateCache } from '#/cli/update/refresh';
+
+describe('refreshUpdateCache', () => {
+  it('writes a fresh cache on successful fetch', async () => {
+    const writeCache = vi.fn(async () => {});
+    const result = await refreshUpdateCache({
+      fetchLatest: async () => '0.5.0',
+      writeCache,
+      now: () => new Date('2026-05-20T12:34:56.000Z'),
+    });
+
+    expect(result).toEqual({
+      source: 'cdn',
+      checkedAt: '2026-05-20T12:34:56.000Z',
+      latest: '0.5.0',
+    });
+    expect(writeCache).toHaveBeenCalledWith({
+      source: 'cdn',
+      checkedAt: '2026-05-20T12:34:56.000Z',
+      latest: '0.5.0',
+    });
+  });
+
+  it('propagates fetch errors and skips writeCache so the cache is preserved', async () => {
+    const writeCache = vi.fn(async () => {});
+    await expect(
+      refreshUpdateCache({
+        fetchLatest: async () => {
+          throw new Error('network down');
+        },
+        writeCache,
+        now: () => new Date(),
+      }),
+    ).rejects.toThrow(/network down/);
+
+    expect(writeCache).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/kimi-code/test/cli/update/select.test.ts b/apps/kimi-code/test/cli/update/select.test.ts
new file mode 100644
index 000000000..a616a4867
--- /dev/null
+++ b/apps/kimi-code/test/cli/update/select.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import { selectUpdateTarget } from '#/cli/update/select';
+
+describe('selectUpdateTarget', () => {
+  it('returns the latest version when it is newer than current', () => {
+    expect(selectUpdateTarget('0.4.0', '0.5.0')).toEqual({ version: '0.5.0' });
+  });
+
+  it('returns null when latest equals current', () => {
+    expect(selectUpdateTarget('0.5.0', '0.5.0')).toBeNull();
+  });
+
+  it('returns null when latest is older than current', () => {
+    expect(selectUpdateTarget('0.6.0', '0.5.0')).toBeNull();
+  });
+
+  it('returns null when latest is null (cache empty)', () => {
+    expect(selectUpdateTarget('0.5.0', null)).toBeNull();
+  });
+
+  it('returns null when current is not a valid semver', () => {
+    expect(selectUpdateTarget('not-a-version', '0.5.0')).toBeNull();
+  });
+
+  it('returns null when latest is not a valid semver', () => {
+    expect(selectUpdateTarget('0.5.0', 'not-a-version')).toBeNull();
+  });
+
+  it('handles prerelease semver comparisons correctly', () => {
+    expect(selectUpdateTarget('0.5.0-rc.1', '0.5.0')).toEqual({ version: '0.5.0' });
+    expect(selectUpdateTarget('0.5.0', '0.5.0-rc.1')).toBeNull();
+  });
+});
diff --git a/apps/kimi-code/test/cli/update/source.test.ts b/apps/kimi-code/test/cli/update/source.test.ts
new file mode 100644
index 000000000..20bba5cd1
--- /dev/null
+++ b/apps/kimi-code/test/cli/update/source.test.ts
@@ -0,0 +1,149 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  classifyByPathHeuristic,
+  classifyInstallSource,
+  detectInstallSource,
+} from '#/cli/update/source';
+
+describe('classifyByPathHeuristic', () => {
+  it('returns null for an npm-style global path (handled by classifyInstallSource)', () => {
+    expect(classifyByPathHeuristic('/usr/local/lib/node_modules/@moonshot-ai/kimi-code')).toBeNull();
+  });
+
+  it('detects pnpm global on macOS', () => {
+    expect(
+      classifyByPathHeuristic('/Users/me/Library/pnpm/global/5/node_modules/@moonshot-ai/kimi-code'),
+    ).toBe('pnpm-global');
+  });
+
+  it('detects pnpm global on Linux', () => {
+    expect(
+      classifyByPathHeuristic('/home/me/.local/share/pnpm/global/5/node_modules/@moonshot-ai/kimi-code'),
+    ).toBe('pnpm-global');
+  });
+
+  it('detects pnpm global on Windows (normalized backslashes)', () => {
+    expect(
+      classifyByPathHeuristic('C:\\Users\\me\\AppData\\Local\\pnpm\\global\\5\\node_modules\\@moonshot-ai/kimi-code'),
+    ).toBe('pnpm-global');
+  });
+
+  it('detects yarn classic global', () => {
+    expect(
+      classifyByPathHeuristic('/Users/me/.config/yarn/global/node_modules/@moonshot-ai/kimi-code'),
+    ).toBe('yarn-global');
+  });
+
+  it('detects yarn berry global (~/.yarn/global)', () => {
+    expect(
+      classifyByPathHeuristic('/Users/me/.yarn/global/node_modules/@moonshot-ai/kimi-code'),
+    ).toBe('yarn-global');
+  });
+
+  it('detects bun global', () => {
+    expect(
+      classifyByPathHeuristic('/Users/me/.bun/install/global/node_modules/@moonshot-ai/kimi-code'),
+    ).toBe('bun-global');
+  });
+
+  it('returns null for an unknown layout', () => {
+    expect(classifyByPathHeuristic('/Users/me/dev/@moonshot-ai/kimi-code')).toBeNull();
+  });
+});
+
+describe('classifyInstallSource (npm prefix matching)', () => {
+  it('matches a macOS/Linux npm global package path', () => {
+    expect(
+      classifyInstallSource('/usr/local/lib/node_modules/@moonshot-ai/kimi-code', '/usr/local', 'darwin'),
+    ).toBe('npm-global');
+  });
+
+  it('returns unsupported when the package path does not match the prefix', () => {
+    expect(
+      classifyInstallSource('/Users/me/dev/@moonshot-ai/kimi-code', '/usr/local', 'darwin'),
+    ).toBe('unsupported');
+  });
+});
+
+describe('detectInstallSource', () => {
+  it('returns pnpm-global when packageRoot matches pnpm heuristic', async () => {
+    await expect(
+      detectInstallSource({
+        getPackageRoot: () =>
+          '/Users/me/Library/pnpm/global/5/node_modules/@moonshot-ai/kimi-code',
+        getGlobalPrefix: async () => '/usr/local',
+        detectNative: () => false,
+        platform: 'darwin',
+      }),
+    ).resolves.toBe('pnpm-global');
+  });
+
+  it('returns yarn-global when packageRoot matches yarn heuristic', async () => {
+    await expect(
+      detectInstallSource({
+        getPackageRoot: () => '/Users/me/.config/yarn/global/node_modules/@moonshot-ai/kimi-code',
+        getGlobalPrefix: async () => '/usr/local',
+        detectNative: () => false,
+        platform: 'darwin',
+      }),
+    ).resolves.toBe('yarn-global');
+  });
+
+  it('returns bun-global when packageRoot matches bun heuristic', async () => {
+    await expect(
+      detectInstallSource({
+        getPackageRoot: () => '/Users/me/.bun/install/global/node_modules/@moonshot-ai/kimi-code',
+        getGlobalPrefix: async () => '/usr/local',
+        detectNative: () => false,
+        platform: 'darwin',
+      }),
+    ).resolves.toBe('bun-global');
+  });
+
+  it('returns npm-global when packageRoot matches npm prefix', async () => {
+    await expect(
+      detectInstallSource({
+        getPackageRoot: () => '/usr/local/lib/node_modules/@moonshot-ai/kimi-code',
+        getGlobalPrefix: async () => '/usr/local',
+        detectNative: () => false,
+        platform: 'darwin',
+      }),
+    ).resolves.toBe('npm-global');
+  });
+
+  it('returns native when SEA isSea() is true (highest priority)', async () => {
+    await expect(
+      detectInstallSource({
+        getPackageRoot: () => '/usr/local/lib/node_modules/@moonshot-ai/kimi-code',
+        getGlobalPrefix: async () => '/usr/local',
+        detectNative: () => true,
+        platform: 'darwin',
+      }),
+    ).resolves.toBe('native');
+  });
+
+  it('returns unsupported when nothing matches', async () => {
+    await expect(
+      detectInstallSource({
+        getPackageRoot: () => '/Users/me/dev/@moonshot-ai/kimi-code',
+        getGlobalPrefix: async () => '/usr/local',
+        detectNative: () => false,
+        platform: 'darwin',
+      }),
+    ).resolves.toBe('unsupported');
+  });
+
+  it('returns unsupported when npm prefix lookup throws', async () => {
+    await expect(
+      detectInstallSource({
+        getPackageRoot: () => '/Users/me/dev/@moonshot-ai/kimi-code',
+        getGlobalPrefix: async () => {
+          throw new Error('prefix failed');
+        },
+        detectNative: () => false,
+        platform: 'darwin',
+      }),
+    ).resolves.toBe('unsupported');
+  });
+});
diff --git a/apps/kimi-code/test/cli/version.test.ts b/apps/kimi-code/test/cli/version.test.ts
new file mode 100644
index 000000000..f17240eff
--- /dev/null
+++ b/apps/kimi-code/test/cli/version.test.ts
@@ -0,0 +1,28 @@
+import { readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildKimiDefaultHeaders,
+  getHostPackageJsonPath,
+  getHostPackageRoot,
+  getVersion,
+} from '#/cli/version';
+
+describe('cli version helpers', () => {
+  it('resolves the host package manifest near apps/kimi-code and reads its version', () => {
+    const pkgPath = getHostPackageJsonPath();
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version: string };
+
+    expect(pkgPath.endsWith('/apps/kimi-code/package.json')).toBe(true);
+    expect(getHostPackageRoot()).toBe(dirname(pkgPath));
+    expect(getVersion()).toBe(pkg.version);
+  });
+
+  it('builds default headers with the kimi-code-cli user-agent', () => {
+    const headers = buildKimiDefaultHeaders('1.2.3');
+
+    expect(headers['User-Agent']).toBe('kimi-code-cli/1.2.3');
+  });
+});
diff --git a/apps/kimi-code/test/e2e/local-logging-export.e2e.test.ts b/apps/kimi-code/test/e2e/local-logging-export.e2e.test.ts
new file mode 100644
index 000000000..8421105f0
--- /dev/null
+++ b/apps/kimi-code/test/e2e/local-logging-export.e2e.test.ts
@@ -0,0 +1,143 @@
+import { readFile, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as zlib from 'node:zlib';
+
+import { Command } from 'commander';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { registerExportCommand } from '#/cli/sub/export';
+import { createKimiCodeHostIdentity } from '#/cli/version';
+import { KimiHarness, log } from '@moonshot-ai/kimi-code-sdk';
+import { __resetRootLoggerForTest } from '../../../../packages/agent-core/src/logging/logger';
+
+const SESSION_LOG = 'logs/kimi-code.log';
+const GLOBAL_LOG = 'logs/global/kimi-code.log';
+const MAIN_WIRE = 'agents/main/wire.jsonl';
+const ENABLED = process.env['KIMI_E2E'] === '1';
+
+let homeDir: string;
+let workDir: string;
+let oldHome: string | undefined;
+
+beforeEach(async () => {
+  await __resetRootLoggerForTest();
+  homeDir = await mkdtemp(join(tmpdir(), 'kimi-cli-log-home-'));
+  workDir = await mkdtemp(join(tmpdir(), 'kimi-cli-log-work-'));
+  oldHome = process.env['KIMI_CODE_HOME'];
+  process.env['KIMI_CODE_HOME'] = homeDir;
+});
+
+afterEach(async () => {
+  await __resetRootLoggerForTest();
+  if (oldHome === undefined) {
+    delete process.env['KIMI_CODE_HOME'];
+  } else {
+    process.env['KIMI_CODE_HOME'] = oldHome;
+  }
+  await rm(homeDir, { recursive: true, force: true });
+  await rm(workDir, { recursive: true, force: true });
+});
+
+describe.skipIf(!ENABLED)('local logging export e2e', () => {
+  it('exports session log and global log by default, and allows skipping global log', async () => {
+    const harness = new KimiHarness({
+      homeDir,
+      identity: createKimiCodeHostIdentity('0.1.1'),
+    });
+    try {
+      const session = await harness.createSession({
+        id: 'ses_cli_logging_export',
+        workDir,
+      });
+      log.warn('cli logging export marker', { sessionId: session.id });
+      log.warn('cli global marker');
+
+      const defaultZip = join(workDir, 'default.zip');
+      await runKimiExport([session.id, '-o', defaultZip]);
+      const defaultEntries = readZipEntries(await readFile(defaultZip));
+      expect(defaultEntries.has(MAIN_WIRE)).toBe(true);
+      expect(defaultEntries.has(SESSION_LOG)).toBe(true);
+      expect(defaultEntries.has(GLOBAL_LOG)).toBe(true);
+      expect(defaultEntries.get(SESSION_LOG)!.toString('utf-8')).toContain(
+        'cli logging export marker',
+      );
+      expect(defaultEntries.get(GLOBAL_LOG)!.toString('utf-8')).toContain('cli global marker');
+      const defaultManifest = JSON.parse(
+        defaultEntries.get('manifest.json')!.toString('utf-8'),
+      ) as Record<string, unknown>;
+      expect(defaultManifest['sessionLogPath']).toBe(SESSION_LOG);
+      expect(defaultManifest['globalLogPath']).toBe(GLOBAL_LOG);
+
+      const noGlobalZip = join(workDir, 'no-global.zip');
+      await runKimiExport([session.id, '-o', noGlobalZip, '--no-include-global-log']);
+      const noGlobalEntries = readZipEntries(await readFile(noGlobalZip));
+      expect(noGlobalEntries.has(GLOBAL_LOG)).toBe(false);
+      const noGlobalManifest = JSON.parse(
+        noGlobalEntries.get('manifest.json')!.toString('utf-8'),
+      ) as Record<string, unknown>;
+      expect(noGlobalManifest['globalLogPath']).toBeUndefined();
+    } finally {
+      await harness.close().catch(() => {});
+    }
+  }, 15_000);
+});
+
+async function runKimiExport(args: string[]): Promise<void> {
+  const program = new Command('kimi');
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  registerExportCommand(program, {
+    stdout: {
+      write: (chunk) => {
+        stdout.push(chunk);
+        return true;
+      },
+    },
+    stderr: {
+      write: (chunk) => {
+        stderr.push(chunk);
+        return true;
+      },
+    },
+    exit: (code: number): never => {
+      throw new Error(`kimi export exited ${code}: ${stderr.join('')}`);
+    },
+  });
+  await program.parseAsync(['node', 'kimi', 'export', ...args]);
+}
+
+function readZipEntries(buf: Buffer): Map<string, Buffer> {
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 65_557); i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) {
+      eocd = i;
+      break;
+    }
+  }
+  if (eocd === -1) throw new Error('zip eocd not found');
+  const entryCount = buf.readUInt16LE(eocd + 10);
+  const cdOffset = buf.readUInt32LE(eocd + 16);
+  const entries = new Map<string, Buffer>();
+  let pos = cdOffset;
+  for (let i = 0; i < entryCount; i++) {
+    if (buf.readUInt32LE(pos) !== 0x02014b50) throw new Error('bad cd entry');
+    const method = buf.readUInt16LE(pos + 10);
+    const compressedSize = buf.readUInt32LE(pos + 20);
+    const fnameLen = buf.readUInt16LE(pos + 28);
+    const extraLen = buf.readUInt16LE(pos + 30);
+    const commentLen = buf.readUInt16LE(pos + 32);
+    const lfhOffset = buf.readUInt32LE(pos + 42);
+    const filename = buf.toString('utf8', pos + 46, pos + 46 + fnameLen);
+    if (buf.readUInt32LE(lfhOffset) !== 0x04034b50) throw new Error('bad lfh');
+    const lfhFnameLen = buf.readUInt16LE(lfhOffset + 26);
+    const lfhExtraLen = buf.readUInt16LE(lfhOffset + 28);
+    const dataStart = lfhOffset + 30 + lfhFnameLen + lfhExtraLen;
+    const compressed = buf.subarray(dataStart, dataStart + compressedSize);
+    const data = method === 0 ? compressed : method === 8 ? zlib.inflateRawSync(compressed) : null;
+    if (data === null) throw new Error('unsupported compression');
+    entries.set(filename, data);
+    pos += 46 + fnameLen + extraLen + commentLen;
+  }
+  return entries;
+}
diff --git a/apps/kimi-code/test/e2e/real-llm-smoke.e2e.test.ts b/apps/kimi-code/test/e2e/real-llm-smoke.e2e.test.ts
new file mode 100644
index 000000000..ffa93ba06
--- /dev/null
+++ b/apps/kimi-code/test/e2e/real-llm-smoke.e2e.test.ts
@@ -0,0 +1,81 @@
+/**
+ * Real-LLM smoke. Opt-in only — runs when `KIMI_E2E_REAL=1` is set, so
+ * `make test` / CI never touches the network. Goes through the SDK's
+ * `KimiHarness` entry and round-trips one real prompt. Requires provider
+ * credentials on disk.
+ *
+ * Env knobs:
+ *   KIMI_E2E_REAL     — set to "1" to enable this suite
+ *   KIMI_E2E_MODEL    — model alias override (default: config's default)
+ *   KIMI_E2E_PROMPT   — prompt text (default: "Reply with a single word: hi")
+ *   KIMI_E2E_WORKDIR  — workspace directory (default: /tmp/kimi-e2e)
+ */
+
+import { mkdirSync } from 'node:fs';
+import process from 'node:process';
+
+import { KimiHarness, type Event } from '@moonshot-ai/kimi-code-sdk';
+import { describe, expect, test } from 'vitest';
+
+import { createKimiCodeHostIdentity, getVersion } from '#/cli/version';
+
+const DEFAULT_PROMPT = 'Reply with a single word: hi';
+const DEFAULT_WORKDIR = '/tmp/kimi-e2e';
+const TURN_TIMEOUT_MS = 60_000;
+
+const ENABLED = process.env['KIMI_E2E_REAL'] === '1';
+type TurnEndedEvent = Extract<Event, { readonly type: 'turn.ended' }>;
+
+describe.skipIf(!ENABLED)('SDK e2e — real LLM smoke', () => {
+  test(
+    'round-trips a single prompt through KimiHarness',
+    async () => {
+      const workDir = process.env['KIMI_E2E_WORKDIR'] ?? DEFAULT_WORKDIR;
+      const prompt = process.env['KIMI_E2E_PROMPT'] ?? DEFAULT_PROMPT;
+      const modelAlias = process.env['KIMI_E2E_MODEL'];
+      mkdirSync(workDir, { recursive: true });
+
+      const version = getVersion();
+      process.stderr.write(
+        `[smoke] workDir=${workDir}${modelAlias !== undefined ? ` model=${modelAlias}` : ''}\n` +
+          `[smoke] prompt=${JSON.stringify(prompt)}\n`,
+      );
+
+      const harness = new KimiHarness({
+        identity: createKimiCodeHostIdentity(version),
+      });
+
+      try {
+        const session = await harness.createSession({
+          workDir,
+          model: modelAlias,
+        });
+        process.stderr.write(`[smoke] session created: ${session.id}\n`);
+
+        const turnEnded = new Promise<TurnEndedEvent>((resolve) => {
+          const off = session.onEvent((event) => {
+            const payload = JSON.stringify(event).slice(0, 500);
+            process.stdout.write(`[smoke][event:${event.type}] ${payload}\n`);
+            if (event.type === 'turn.ended') {
+              off();
+              resolve(event);
+            }
+          });
+        });
+
+        await session.prompt(prompt);
+        process.stderr.write('[smoke] prompt dispatched\n');
+
+        const event = await turnEnded;
+        process.stderr.write(`[smoke] turn.ended reason=${event.reason}\n`);
+        if (event.error !== undefined) {
+          process.stderr.write(`[smoke] error=${event.error.message}\n`);
+        }
+        expect(event.reason).toBe('completed');
+      } finally {
+        await harness.close().catch(() => {});
+      }
+    },
+    TURN_TIMEOUT_MS + 10_000,
+  );
+});
diff --git a/apps/kimi-code/test/helpers/process.ts b/apps/kimi-code/test/helpers/process.ts
new file mode 100644
index 000000000..5a861724b
--- /dev/null
+++ b/apps/kimi-code/test/helpers/process.ts
@@ -0,0 +1,32 @@
+import { vi } from 'vitest';
+
+export class ExitCalled extends Error {
+  constructor(public readonly code: number) {
+    super(`exit(${code})`);
+  }
+}
+
+export function mockProcessExit(): { mockRestore(): void } {
+  return vi.spyOn(process, 'exit').mockImplementation(((code?: string | number | null) => {
+    throw new ExitCalled(Number(code ?? 0));
+  }) as never);
+}
+
+export function captureProcessWrite(stream: 'stdout' | 'stderr'): {
+  readonly chunks: string[];
+  readonly text: () => string;
+  readonly restore: () => void;
+} {
+  const chunks: string[] = [];
+  const target = process[stream];
+  const spy = vi.spyOn(target, 'write').mockImplementation(((chunk: string | Uint8Array) => {
+    chunks.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'));
+    return true;
+  }) as never);
+
+  return {
+    chunks,
+    text: () => chunks.join(''),
+    restore: () =>{  spy.mockRestore(); },
+  };
+}
diff --git a/apps/kimi-code/test/migration/badge.test.ts b/apps/kimi-code/test/migration/badge.test.ts
new file mode 100644
index 000000000..68fb72bf3
--- /dev/null
+++ b/apps/kimi-code/test/migration/badge.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+
+import { formatSessionLabel } from '#/migration/badge';
+
+describe('formatSessionLabel', () => {
+  it('prepends [imported] when metadata.imported_from_kimi_cli === true', () => {
+    const label = formatSessionLabel({
+      title: 'Refactor sessions list',
+      metadata: { imported_from_kimi_cli: true },
+    });
+    expect(label).toBe('[imported] Refactor sessions list');
+  });
+
+  it('does not prepend [imported] when metadata is missing', () => {
+    const label = formatSessionLabel({ title: 'Plain session' });
+    expect(label).toBe('Plain session');
+  });
+
+  it('does not prepend [imported] when metadata is empty', () => {
+    const label = formatSessionLabel({ title: 'Plain session', metadata: {} });
+    expect(label).toBe('Plain session');
+  });
+
+  it('only triggers on the literal boolean true (not truthy values)', () => {
+    const label = formatSessionLabel({
+      title: 'truthy but not true',
+      metadata: { imported_from_kimi_cli: 'yes' as unknown },
+    });
+    expect(label).toBe('truthy but not true');
+  });
+
+  it('does not prepend [imported] when flag is false', () => {
+    const label = formatSessionLabel({
+      title: 'native session',
+      metadata: { imported_from_kimi_cli: false },
+    });
+    expect(label).toBe('native session');
+  });
+
+  it('preserves the title even when it is empty', () => {
+    const label = formatSessionLabel({
+      title: '',
+      metadata: { imported_from_kimi_cli: true },
+    });
+    expect(label).toBe('[imported] ');
+  });
+});
diff --git a/apps/kimi-code/test/migration/command.test.ts b/apps/kimi-code/test/migration/command.test.ts
new file mode 100644
index 000000000..2124dd70b
--- /dev/null
+++ b/apps/kimi-code/test/migration/command.test.ts
@@ -0,0 +1,29 @@
+/**
+ * `kimi migrate` — a bare, flagless subcommand that delegates to a host
+ * handler. The migration UI is the native pi-tui screen, covered separately
+ * by `migration-screen.test.ts`.
+ */
+
+import { Command } from 'commander';
+import { describe, expect, it, vi } from 'vitest';
+
+import { registerMigrateCommand } from '#/migration/command';
+
+describe('registerMigrateCommand', () => {
+  it('adds a flagless migrate subcommand to the program', () => {
+    const program = new Command('kimi');
+    registerMigrateCommand(program, () => {});
+    const sub = program.commands.find((c) => c.name() === 'migrate');
+    expect(sub).toBeDefined();
+    expect(sub!.description()).toContain('Migrate');
+    expect(sub!.options).toHaveLength(0);
+  });
+
+  it('invokes the host handler when `migrate` runs', () => {
+    const program = new Command('kimi');
+    const onMigrate = vi.fn();
+    registerMigrateCommand(program, onMigrate);
+    program.parse(['migrate'], { from: 'user' });
+    expect(onMigrate).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/apps/kimi-code/test/migration/detect-pending.test.ts b/apps/kimi-code/test/migration/detect-pending.test.ts
new file mode 100644
index 000000000..c674d054d
--- /dev/null
+++ b/apps/kimi-code/test/migration/detect-pending.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { detectPendingMigration } from '#/migration/detect-pending';
+
+let src: string;
+let tgt: string;
+beforeEach(async () => {
+  src = await mkdtemp(join(tmpdir(), 'detect-pending-src-'));
+  tgt = await mkdtemp(join(tmpdir(), 'detect-pending-tgt-'));
+});
+afterEach(async () => {
+  await rm(src, { recursive: true, force: true });
+  await rm(tgt, { recursive: true, force: true });
+});
+
+describe('detectPendingMigration', () => {
+  it('returns null when source dir does not exist', async () => {
+    const plan = await detectPendingMigration({ sourceHome: join(src, 'nope'), targetHome: tgt });
+    expect(plan).toBeNull();
+  });
+
+  it('returns null when the migrated marker exists', async () => {
+    await writeFile(join(src, '.migrated-to-kimi-code'), '{}', 'utf-8');
+    const plan = await detectPendingMigration({ sourceHome: src, targetHome: tgt });
+    expect(plan).toBeNull();
+  });
+
+  it('returns null when the skip marker exists in target', async () => {
+    await writeFile(join(src, 'config.toml'), '', 'utf-8');
+    await writeFile(join(tgt, '.skip-migration-from-kimi-cli'), '', 'utf-8');
+    const plan = await detectPendingMigration({ sourceHome: src, targetHome: tgt });
+    expect(plan).toBeNull();
+  });
+
+  it('returns null when source has nothing worth migrating', async () => {
+    // empty source dir, no config/mcp/credentials/sessions
+    const plan = await detectPendingMigration({ sourceHome: src, targetHome: tgt });
+    expect(plan).toBeNull();
+  });
+
+  it('returns a MigrationPlan when source has migratable data', async () => {
+    await writeFile(join(src, 'config.toml'), 'default_thinking = true\n', 'utf-8');
+    const plan = await detectPendingMigration({ sourceHome: src, targetHome: tgt });
+    expect(plan).not.toBeNull();
+    expect(plan?.hasConfig).toBe(true);
+  });
+
+  it('returns a MigrationPlan when source has only user-history', async () => {
+    await mkdir(join(src, 'user-history'), { recursive: true });
+    await writeFile(join(src, 'user-history', 'shell.txt'), 'ls\n', 'utf-8');
+    const plan = await detectPendingMigration({ sourceHome: src, targetHome: tgt });
+    expect(plan).not.toBeNull();
+    expect(plan?.hasUserHistory).toBe(true);
+  });
+
+  it('does not suppress when the marker targeted a different home', async () => {
+    await writeFile(join(src, 'config.toml'), 'default_thinking = true\n', 'utf-8');
+    await writeFile(
+      join(src, '.migrated-to-kimi-code'),
+      JSON.stringify({ version: 1, target_path: '/some/other/home' }),
+      'utf-8',
+    );
+    const plan = await detectPendingMigration({ sourceHome: src, targetHome: tgt });
+    expect(plan).not.toBeNull(); // this target was never migrated → still offer
+  });
+
+  it('suppresses when the marker targeted this home', async () => {
+    await writeFile(join(src, 'config.toml'), 'default_thinking = true\n', 'utf-8');
+    await writeFile(
+      join(src, '.migrated-to-kimi-code'),
+      JSON.stringify({ version: 1, target_path: tgt }),
+      'utf-8',
+    );
+    const plan = await detectPendingMigration({ sourceHome: src, targetHome: tgt });
+    expect(plan).toBeNull();
+  });
+});
diff --git a/apps/kimi-code/test/migration/migration-screen.test.ts b/apps/kimi-code/test/migration/migration-screen.test.ts
new file mode 100644
index 000000000..90b34dca3
--- /dev/null
+++ b/apps/kimi-code/test/migration/migration-screen.test.ts
@@ -0,0 +1,617 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  MigrationScreenComponent,
+  type MigrationScreenResult,
+} from '#/migration/migration-screen';
+import { darkColors } from '#/tui/theme/colors';
+import type {
+  MigrationPlan,
+  MigrationReport,
+  RunMigrationInput,
+} from '@moonshot-ai/migration-legacy';
+
+function makePlan(over: Partial<MigrationPlan> = {}): MigrationPlan {
+  return {
+    sourceHome: '/x/.kimi',
+    hasConfig: true,
+    hasMcp: true,
+    hasUserHistory: true,
+    oauthCredentials: ['kimi-code.json'],
+    workdirs: [],
+    detectedPlugins: [],
+    detectedMcpOauthServers: [],
+    totalSessions: 1365,
+    ...over,
+  };
+}
+
+function render(c: MigrationScreenComponent): string {
+  return c.render(80).join('\n');
+}
+
+describe('MigrationScreenComponent — ask phase', () => {
+  it('ask1 renders the intro block and three options', () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    const out = render(c);
+    expect(out).toContain('Migrate from kimi-cli');
+    expect(out).toContain('1365 sessions');
+    expect(out).toContain('Migrate now');
+    expect(out).toContain('Ask me later');
+    expect(out).toContain('Never ask again');
+  });
+
+  it('ask1 summary shows the kimi-cli login hint when OAuth credentials are detected', async () => {
+    // OAuth credentials are detected but not migrated — surface that up front
+    // so the pre-migration summary is consistent with the result screen's
+    // "⚠ kimi-cli login not migrated — run /login" line.
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    const out = render(c);
+    expect(out).toContain('kimi-cli login');
+  });
+
+  it('ask1 renders a non-empty summary when the only detected data is an OAuth login', async () => {
+    // Legacy install with nothing but `credentials/*.json` would otherwise
+    // render the summary line as blank — `summarizePlan` no longer treats
+    // OAuth as a migrated kind. The OAuth hint must keep that line useful.
+    const c = new MigrationScreenComponent({
+      plan: makePlan({
+        hasConfig: false,
+        hasMcp: false,
+        hasUserHistory: false,
+        totalSessions: 0,
+        workdirs: [],
+      }),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    const out = render(c);
+    expect(out).toContain('kimi-cli login');
+    // ...and the summary line is not blank — the OAuth hint is its content.
+    expect(out).toMatch(/Found an existing kimi-cli installation:\n\s+\S/);
+  });
+
+  it('picking "Ask me later" at ask1 completes with decision=later', () => {
+    let result: { decision: string } | undefined;
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: (r) => {
+        result = r;
+      },
+    });
+    c.handleInput('\u001B[B'); // Down -> "Ask me later"
+    c.handleInput('\r'); // Enter
+    expect(result?.decision).toBe('later');
+  });
+
+  it('"Migrate now" -> "Config only" advances ask1 -> ask2 and resolves scope.sessions=false', async () => {
+    let captured: RunMigrationInput | undefined;
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      runMigration: async (input) => {
+        captured = input;
+        return makeReport();
+      },
+      onComplete: () => {},
+    });
+    c.handleInput('\r'); // ask1: "Migrate now"
+    c.handleInput('\r'); // ask2: "Config only" (first option)
+    await new Promise((r) => setTimeout(r, 0));
+    expect(captured?.scope.sessions).toBe(false);
+  });
+
+  it('"Migrate now" -> "Config + sessions" begins migration immediately with sessions=true', async () => {
+    let captured: RunMigrationInput | undefined;
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      runMigration: async (input) => {
+        captured = input;
+        return makeReport();
+      },
+      onComplete: () => {},
+    });
+    c.handleInput('\r'); // ask1: Migrate now
+    c.handleInput('\u001B[B'); // ask2: down -> Also migrate sessions
+    c.handleInput('\r'); // ask2 select -> "Config + N sessions" begins migration immediately
+    await new Promise((r) => setTimeout(r, 0));
+    expect(captured?.scope.sessions).toBe(true);
+  });
+
+  it('ask2 shows the detected session count alongside the "config only" option', () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan({ totalSessions: 1365 }),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    c.handleInput('\r'); // ask1: Migrate now -> ask2
+    const out = render(c);
+    expect(out).toContain('Config only');
+    // Concrete count so the user sees the cost of "+ sessions" up front.
+    expect(out).toContain('Config + 1365 sessions');
+    expect(out).not.toContain('Most recent');
+    expect(out).not.toContain('Migrate now');
+  });
+
+  it('ask2 falls back to "Config + all sessions" when no sessions were detected', () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan({ totalSessions: 0 }),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    c.handleInput('\r'); // ask1 -> ask2
+    const out = render(c);
+    expect(out).toContain('Config + all sessions');
+    // "Config + 0 sessions" would read as an obvious dead-end.
+    expect(out).not.toContain('Config + 0 sessions');
+  });
+
+  it('skipDecisionStep starts at the scope question with the now/later/never gate hidden', () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      skipDecisionStep: true,
+      onComplete: () => {},
+    });
+    const out = render(c);
+    expect(out).toContain('Migrate chat sessions too?');
+    expect(out).not.toContain('Migrate now');
+    expect(out).not.toContain('Never ask again');
+  });
+
+  it('skipDecisionStep -> "Config only" resolves scope without the decision step', async () => {
+    let captured: RunMigrationInput | undefined;
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      skipDecisionStep: true,
+      runMigration: async (input) => {
+        captured = input;
+        return makeReport();
+      },
+      onComplete: () => {},
+    });
+    c.handleInput('\r'); // ask2: "Config only" (first option) — no ask1 gate
+    await new Promise((r) => setTimeout(r, 0));
+    expect(captured?.scope.sessions).toBe(false);
+  });
+});
+
+describe('MigrationScreenComponent — progress phase', () => {
+  it('renders a step checklist and the session counter when in progress', () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    // expose progress rendering via the test hook (see Step 5.2)
+    c._testEnterProgress();
+    c._testUpdateStep('config done');
+    c._testUpdateSessionProgress(32, 50);
+    const out = c.render(80).join('\n');
+    expect(out).toContain('Migrating from kimi-cli');
+    expect(out).toContain('32 / 50');
+    expect(out).toContain('Config');
+  });
+
+  it('animates the progress spinner while a migration step runs', async () => {
+    vi.useFakeTimers();
+    try {
+      const c = new MigrationScreenComponent({
+        plan: makePlan(),
+        sourceHome: '/x/.kimi',
+        targetHome: '/y/.kimi-code',
+        colors: darkColors,
+        skipDecisionStep: true,
+        // A migration that never settles keeps the screen in the progress
+        // phase so the spinner animation can be observed.
+        runMigration: () => new Promise<MigrationReport>(() => {}),
+        onComplete: () => {},
+      });
+      c.handleInput('\r'); // ask2: "Config only" -> migration begins
+      c._testUpdateSessionProgress(1, 3); // surface the spinner line
+      const before = c.render(80).join('\n');
+      vi.advanceTimersByTime(400); // several spinner frames
+      const after = c.render(80).join('\n');
+      // Before the fix nothing advanced the spinner — the frame, and the whole
+      // progress render, stayed frozen on the first braille glyph.
+      expect(after).not.toBe(before);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('tracks Config and MCP as independent steps', () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    c._testEnterProgress();
+    c._testUpdateStep('config done'); // config finished; MCP has not started
+    const out = c.render(80).join('\n');
+    // Four checklist rows (config, mcp, user-history, sessions). With only
+    // config done, exactly one shows ✓ and the other three show ◐ — MCP is
+    // its own step and stays pending.
+    expect((out.match(/✓/g) ?? []).length).toBe(1);
+    expect((out.match(/◐/g) ?? []).length).toBe(3);
+  });
+});
+
+function makeReport(
+  over: Partial<MigrationReport['summary']['sessions']> = {},
+  summaryOver: Partial<MigrationReport['summary']> = {},
+  noticesOver: Partial<MigrationReport['notices']> = {},
+): MigrationReport {
+  return {
+    startedAt: 's',
+    completedAt: 'e',
+    migratorVersion: '0.1.1',
+    source: '/x/.kimi',
+    target: '/y/.kimi-code',
+    summary: {
+      config: {
+        migrated: true,
+        tuiExtracted: false,
+        droppedProviders: [],
+        droppedModels: [],
+        droppedKeys: [],
+        configConflicts: [],
+        wroteSiblingDueToConflict: false,
+        wroteTuiSibling: false,
+        migratedHooks: 0,
+        droppedHooks: 0,
+        siblingContents: { providers: [], models: [], hooks: 0 },
+      },
+      mcp: { mergedServers: [], keptNewForConflicts: [], droppedServers: [], wroteSiblingDueToConflict: false },
+      userHistory: { copied: 12, skippedExisting: 0 },
+      sessions: {
+        scope: 'all',
+        bucketsScanned: 0,
+        bucketsSkippedNonlocalKaos: 0,
+        bucketsSkippedNoWorkdirFound: 0,
+        sessionsAttempted: 50,
+        sessionsMigrated: 50,
+        sessionsAlreadyMigrated: 0,
+        sessionsSkippedPlaceholder: 0,
+        sessionsSkippedEmpty: 0,
+        sessionsSkippedMalformed: 0,
+        sessionsFailed: [],
+        sessionsConflicts: [],
+        ...over,
+      },
+      ...summaryOver,
+    },
+    notices: {
+      mcpOauthServersRequiringReauth: [],
+      oauthLoginsRequiringRelogin: [],
+      detectedPlugins: ['p1', 'p2'],
+      configConflictNotice: null,
+      tuiConflictNotice: null,
+      ...noticesOver,
+    },
+  };
+}
+
+describe('MigrationScreenComponent — result phase', () => {
+  it('renders the report summary including plugin notices', () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    c._testShowResult(makeReport());
+    const out = c.render(80).join('\n');
+    expect(out).toContain('Migration complete');
+    expect(out).toContain('50 sessions migrated');
+    expect(out).toContain('2 kimi-cli plugins');
+  });
+
+  it('renders migrated hooks in the ✓ line and dropped hooks as a warning', () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    c._testShowResult(
+      makeReport(
+        {},
+        {
+          config: {
+            migrated: true,
+            tuiExtracted: false,
+            droppedProviders: [],
+            droppedModels: [],
+            droppedKeys: [],
+            configConflicts: [],
+            wroteSiblingDueToConflict: false,
+            wroteTuiSibling: false,
+            migratedHooks: 2,
+            droppedHooks: 1,
+            siblingContents: { providers: [], models: [], hooks: 0 },
+          },
+        },
+      ),
+    );
+    const out = c.render(80).join('\n');
+    expect(out).toContain('· hooks'); // appears in the ✓ migrated-kinds line
+    expect(out).toContain('1 hooks dropped');
+  });
+
+  it('Enter on the result screen completes with the prior decision', () => {
+    let result: MigrationScreenResult | undefined;
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: (r) => {
+        result = r;
+      },
+    });
+    c._testShowResult(makeReport());
+    c.handleInput('\r');
+    expect(result?.decision).toBe('now');
+    expect(result?.migrated).toBe(true);
+  });
+
+  it('omits a data class from the result when it was not migrated', () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    // config skipped (e.g. a malformed legacy config.toml).
+    c._testShowResult(
+      makeReport(
+        {},
+        {
+          config: {
+            migrated: false,
+            tuiExtracted: false,
+            droppedProviders: [],
+            droppedModels: [],
+            droppedKeys: [],
+            configConflicts: [],
+            wroteSiblingDueToConflict: false,
+            wroteTuiSibling: false,
+            migratedHooks: 0,
+            droppedHooks: 0,
+            siblingContents: { providers: [], models: [], hooks: 0 },
+          },
+        },
+      ),
+    );
+    const out = c.render(80).join('\n');
+    // REPL history (copied) is still shown...
+    expect(out).toContain('REPL history');
+    // ...but config must not be claimed as migrated.
+    expect(out).not.toContain('config');
+  });
+
+  it('surfaces conflict and failure warnings on the result screen', () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    c._testShowResult(
+      makeReport(
+        { sessionsFailed: [{ sourcePath: '/s', reason: 'bad' }] },
+        {
+          config: {
+            migrated: true,
+            tuiExtracted: false,
+            droppedProviders: [],
+            droppedModels: [],
+            droppedKeys: [],
+            configConflicts: [],
+            wroteSiblingDueToConflict: true,
+            wroteTuiSibling: false,
+            migratedHooks: 0,
+            droppedHooks: 0,
+            siblingContents: { providers: [], models: [], hooks: 0 },
+          },
+          mcp: { mergedServers: ['m'], keptNewForConflicts: [], droppedServers: [], wroteSiblingDueToConflict: true },
+        },
+      ),
+    );
+    const out = c.render(80).join('\n');
+    expect(out).toContain('config.migrated-from-kimi-cli.toml');
+    expect(out).toContain('mcp.migrated-from-kimi-cli.json');
+    expect(out).toContain('1 sessions failed');
+  });
+
+  it('lists sibling-file contents in the config-fallback warning so the user knows what to merge', () => {
+    // When the target's `config.toml` could not be parsed and migration writes
+    // to `config.migrated-from-kimi-cli.toml` instead, the result screen must
+    // (a) name the sibling, (b) say what's in it so the user knows what to
+    // merge by hand, and (c) describe the trigger accurately (parse failure,
+    // not "unreadable"). Otherwise users have to crack the file open to find
+    // out — and they may not realize hooks landed in there at all.
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    c._testShowResult(
+      makeReport(
+        {},
+        {
+          config: {
+            migrated: true,
+            tuiExtracted: false,
+            droppedProviders: [],
+            droppedModels: [],
+            droppedKeys: [],
+            configConflicts: [],
+            wroteSiblingDueToConflict: true,
+            wroteTuiSibling: false,
+            migratedHooks: 0,
+            droppedHooks: 0,
+            siblingContents: {
+              providers: ['openai', 'managed:kimi-code'],
+              models: ['gpt4'],
+              hooks: 3,
+            },
+          },
+        },
+      ),
+    );
+    const out = c.render(80).join('\n');
+    expect(out).toContain('config.migrated-from-kimi-cli.toml');
+    // Accurate trigger description (file parses, not "unreadable").
+    expect(out).toContain('could not be parsed');
+    // Enumeration of what's inside the sibling.
+    expect(out).toContain('2 providers');
+    expect(out).toContain('1 model');
+    expect(out).toContain('3 hooks');
+  });
+
+  it('shows skipped empty sessions as a muted line, not a failure', () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    c._testShowResult(makeReport({ sessionsSkippedEmpty: 3 }));
+    const out = c.render(80).join('\n');
+    expect(out).toContain('3 empty sessions skipped');
+    // It is informational, not a failure.
+    expect(out).not.toContain('3 sessions failed');
+  });
+
+  it('lists kept config settings on the result screen when kimi-cli differed', () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    c._testShowResult(
+      makeReport(
+        {},
+        {
+          config: {
+            migrated: true,
+            tuiExtracted: false,
+            droppedProviders: [],
+            droppedModels: [],
+            droppedKeys: [],
+            configConflicts: ['default_model', 'providers.kimi'],
+            wroteSiblingDueToConflict: false,
+            wroteTuiSibling: false,
+            migratedHooks: 0,
+            droppedHooks: 0,
+            siblingContents: { providers: [], models: [], hooks: 0 },
+          },
+        },
+      ),
+    );
+    const out = c.render(80).join('\n');
+    expect(out).toContain('2 config conflicts kept yours');
+    expect(out).toContain('default_model · providers.kimi');
+  });
+
+  it('surfaces MCP servers that need re-authentication', () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+    });
+    c._testShowResult(makeReport({}, {}, { mcpOauthServersRequiringReauth: ['srv-a', 'srv-b'] }));
+    const out = c.render(80).join('\n');
+    expect(out).toContain('2 MCP servers need re-authentication');
+  });
+});
+
+describe('MigrationScreenComponent — execution wiring', () => {
+  it('runs migration after the ask phase and lands on the result phase', async () => {
+    const fakeReport = makeReport();
+    let onCompleteResult: MigrationScreenResult | undefined;
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: (r) => {
+        onCompleteResult = r;
+      },
+      // injected runner for testability — no filesystem access
+      runMigration: async (_input) => fakeReport,
+    });
+    c.handleInput('\r'); // ask1: Migrate now
+    c.handleInput('\r'); // ask2: Config only -> begins migration
+    // migration is async; wait a tick
+    await new Promise((res) => setTimeout(res, 0));
+    expect(c.render(80).join('\n')).toContain('Migration complete');
+    c.handleInput('\r'); // dismiss result
+    expect(onCompleteResult?.decision).toBe('now');
+    expect(onCompleteResult?.migrated).toBe(true);
+  });
+
+  it('lands on the failure screen when the runner rejects', async () => {
+    const c = new MigrationScreenComponent({
+      plan: makePlan(),
+      sourceHome: '/x/.kimi',
+      targetHome: '/y/.kimi-code',
+      colors: darkColors,
+      onComplete: () => {},
+      runMigration: async () => {
+        throw new Error('boom');
+      },
+    });
+    c.handleInput('\r'); // ask1: Migrate now
+    c.handleInput('\r'); // ask2: Config only -> begins migration
+    await new Promise((res) => setTimeout(res, 0));
+    expect(c.render(80).join('\n')).toContain('Migration failed');
+  });
+});
diff --git a/apps/kimi-code/test/native/cache-base.test.ts b/apps/kimi-code/test/native/cache-base.test.ts
new file mode 100644
index 000000000..896aefabc
--- /dev/null
+++ b/apps/kimi-code/test/native/cache-base.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+
+import { getNativeCacheBase } from '#/native/native-assets';
+
+describe('getNativeCacheBase precedence', () => {
+  const baseOptions = { homeDir: '/home/u' };
+
+  it('uses KIMI_CODE_CACHE_DIR when set (highest precedence)', () => {
+    const got = getNativeCacheBase({
+      ...baseOptions,
+      env: { KIMI_CODE_CACHE_DIR: '/custom/cache' },
+    });
+    expect(got).toBe('/custom/cache');
+  });
+
+  it('ignores KIMI_CODE_HOME (no longer affects native cache)', () => {
+    const got = getNativeCacheBase({
+      ...baseOptions,
+      env: { KIMI_CODE_HOME: '/legacy' },
+      platform: 'darwin',
+    });
+    expect(got).toBe('/home/u/Library/Caches/kimi-code');
+  });
+
+  it('uses platform default on macOS when no env set', () => {
+    const got = getNativeCacheBase({
+      ...baseOptions,
+      env: {},
+      platform: 'darwin',
+    });
+    expect(got).toBe('/home/u/Library/Caches/kimi-code');
+  });
+
+  it('uses XDG_CACHE_HOME on Linux when set', () => {
+    const got = getNativeCacheBase({
+      ...baseOptions,
+      env: { XDG_CACHE_HOME: '/xdg' },
+      platform: 'linux',
+    });
+    expect(got).toBe('/xdg/kimi-code');
+  });
+
+  it('uses LOCALAPPDATA on Windows when set', () => {
+    const got = getNativeCacheBase({
+      ...baseOptions,
+      env: { LOCALAPPDATA: 'C:\\Users\\u\\AppData\\Local' },
+      platform: 'win32',
+    });
+    expect(got).toBe('C:\\Users\\u\\AppData\\Local\\kimi-code');
+  });
+});
diff --git a/apps/kimi-code/test/native/cache-gc.test.ts b/apps/kimi-code/test/native/cache-gc.test.ts
new file mode 100644
index 000000000..4f9203a15
--- /dev/null
+++ b/apps/kimi-code/test/native/cache-gc.test.ts
@@ -0,0 +1,103 @@
+import { mkdirSync, statSync, utimesSync, writeFileSync, readdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { cleanupStaleNativeCache } from '#/native/native-assets';
+
+describe('cleanupStaleNativeCache', () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'kimi-cache-gc-'));
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  function makeHashDir(version: string, target: string, hash: string, mtimeOffset = 0): string {
+    const dir = join(root, 'native', version, target, hash);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'marker.txt'), hash);
+    const now = Math.floor(Date.now() / 1000);
+    utimesSync(dir, now + mtimeOffset, now + mtimeOffset);
+    return dir;
+  }
+
+  it('keeps currentRoot + most recently modified sibling, deletes the rest', () => {
+    const v = '1.0.0';
+    const t = 'darwin-arm64';
+    const oldest = makeHashDir(v, t, 'aaaa', -300);
+    const middle = makeHashDir(v, t, 'bbbb', -200);
+    const recent = makeHashDir(v, t, 'cccc', -100);
+    const current = makeHashDir(v, t, 'dddd', 0);
+
+    const result = cleanupStaleNativeCache({
+      cacheBase: root,
+      version: v,
+      target: t,
+      currentRoot: current,
+    });
+
+    expect(result.kept.toSorted()).toEqual([recent, current].toSorted());
+    expect(result.removed.toSorted()).toEqual([oldest, middle].toSorted());
+
+    expect(readdirSync(join(root, 'native', v, t)).toSorted()).toEqual(['cccc', 'dddd']);
+  });
+
+  it('no-op when only currentRoot exists', () => {
+    const v = '1.0.0';
+    const t = 'darwin-arm64';
+    const current = makeHashDir(v, t, 'dddd');
+
+    const result = cleanupStaleNativeCache({
+      cacheBase: root,
+      version: v,
+      target: t,
+      currentRoot: current,
+    });
+
+    expect(result.kept).toEqual([current]);
+    expect(result.removed).toEqual([]);
+  });
+
+  it('no-op when target dir does not exist', () => {
+    const result = cleanupStaleNativeCache({
+      cacheBase: root,
+      version: '1.0.0',
+      target: 'darwin-arm64',
+      currentRoot: join(root, 'native', '1.0.0', 'darwin-arm64', 'absent'),
+    });
+    expect(result.kept).toEqual([]);
+    expect(result.removed).toEqual([]);
+  });
+
+  it('does not touch other targets or versions', () => {
+    const current = makeHashDir('1.0.0', 'darwin-arm64', 'dddd');
+    const otherTarget = makeHashDir('1.0.0', 'linux-x64', 'eeee');
+    const otherVersion = makeHashDir('0.9.0', 'darwin-arm64', 'ffff');
+
+    cleanupStaleNativeCache({
+      cacheBase: root,
+      version: '1.0.0',
+      target: 'darwin-arm64',
+      currentRoot: current,
+    });
+
+    expect(statSync(otherTarget).isDirectory()).toBe(true);
+    expect(statSync(otherVersion).isDirectory()).toBe(true);
+  });
+
+  it('errors array is empty on clean run', () => {
+    const current = makeHashDir('1.0.0', 'darwin-arm64', 'dddd');
+    const result = cleanupStaleNativeCache({
+      cacheBase: root,
+      version: '1.0.0',
+      target: 'darwin-arm64',
+      currentRoot: current,
+    });
+    expect(result.errors).toEqual([]);
+  });
+});
diff --git a/apps/kimi-code/test/native/native-assets.test.ts b/apps/kimi-code/test/native/native-assets.test.ts
new file mode 100644
index 000000000..1946a6ccc
--- /dev/null
+++ b/apps/kimi-code/test/native/native-assets.test.ts
@@ -0,0 +1,128 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  getNativeCacheBase,
+  getNativePackageRoot,
+  NATIVE_ASSET_MANIFEST_VERSION,
+  type NativeAssetManifest,
+  type NativeAssetSource,
+} from '#/native/native-assets';
+import { loadNativePackage } from '#/native/native-require';
+
+function sha256(bytes: Buffer | string): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function fakeManifest(files: Record<string, string>): {
+  manifest: NativeAssetManifest;
+  source: NativeAssetSource;
+} {
+  const assetEntries = Object.entries(files).map(([relativePath, content]) => {
+    const assetKey = `native/test-target/${relativePath}`;
+    return {
+      assetKey,
+      relativePath,
+      sha256: sha256(content),
+    };
+  });
+  const manifest: NativeAssetManifest = {
+    version: NATIVE_ASSET_MANIFEST_VERSION,
+    target: 'test-target',
+    packages: [
+      {
+        name: 'fake-native',
+        root: 'node_modules/fake-native',
+        files: assetEntries,
+      },
+    ],
+  };
+  const manifestKey = 'native/test-target/manifest.json';
+  const assets = new Map<string, Buffer>([
+    [manifestKey, Buffer.from(JSON.stringify(manifest))],
+    ...Object.entries(files).map(([relativePath, content]) => [
+      `native/test-target/${relativePath}`,
+      Buffer.from(content),
+    ] as const),
+  ]);
+  return {
+    manifest,
+    source: {
+      getAssetKeys: () => [...assets.keys()],
+      getRawAsset: (assetKey) => {
+        const asset = assets.get(assetKey);
+        if (asset === undefined) throw new Error(`missing test asset: ${assetKey}`);
+        return asset;
+      },
+    },
+  };
+}
+
+describe('native assets', () => {
+  it('uses KIMI_CODE_CACHE_DIR as the native cache base when present', () => {
+    expect(
+      getNativeCacheBase({
+        env: { KIMI_CODE_CACHE_DIR: '/tmp/kimi-cache' },
+        homeDir: '/home/kimi',
+        platform: 'linux',
+      }),
+    ).toBe('/tmp/kimi-cache');
+  });
+
+  it('extracts package assets and repairs corrupted cache files', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'kimi-native-assets-'));
+    try {
+      const { manifest, source } = fakeManifest({
+        'node_modules/fake-native/package.json': '{"main":"index.js"}',
+        'node_modules/fake-native/index.js': "module.exports = { value: 'ok' };\n",
+      });
+
+      const packageRoot = getNativePackageRoot('fake-native', {
+        cacheBase: dir,
+        manifest,
+        source,
+        version: 'test',
+      });
+      expect(packageRoot).toBe(join(dir, 'native', 'test', 'test-target', sha256(JSON.stringify(manifest)), 'node_modules', 'fake-native'));
+      expect(readFileSync(join(packageRoot ?? '', 'index.js'), 'utf-8')).toContain("value: 'ok'");
+
+      writeFileSync(join(packageRoot ?? '', 'index.js'), 'broken');
+      const repairedRoot = getNativePackageRoot('fake-native', {
+        cacheBase: dir,
+        manifest,
+        source,
+        version: 'test',
+      });
+      expect(repairedRoot).toBe(packageRoot);
+      expect(readFileSync(join(repairedRoot ?? '', 'index.js'), 'utf-8')).toContain("value: 'ok'");
+      expect(existsSync(join(dir, 'native', 'test', 'test-target'))).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('loads a package from extracted native assets', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'kimi-native-require-'));
+    try {
+      const { manifest, source } = fakeManifest({
+        'node_modules/fake-native/package.json': '{"main":"index.js"}',
+        'node_modules/fake-native/index.js': "module.exports = { value: 'ok' };\n",
+      });
+
+      const pkg = loadNativePackage<{ value: string }>('fake-native', {
+        cacheBase: dir,
+        manifest,
+        source,
+        version: 'test',
+      });
+
+      expect(pkg).toEqual({ value: 'ok' });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/apps/kimi-code/test/scripts/native/exec.test.ts b/apps/kimi-code/test/scripts/native/exec.test.ts
new file mode 100644
index 000000000..87f581191
--- /dev/null
+++ b/apps/kimi-code/test/scripts/native/exec.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+
+import { commandForExecFile } from '../../../scripts/native/exec.mjs';
+
+describe('commandForExecFile', () => {
+  it('returns command as-is on non-Windows', () => {
+    const result = commandForExecFile('postject', ['kimi', 'NODE_SEA_BLOB', './blob'], 'darwin');
+    expect(result).toEqual({ command: 'postject', args: ['kimi', 'NODE_SEA_BLOB', './blob'] });
+  });
+
+  it('returns command as-is on Windows for non-batch files', () => {
+    const result = commandForExecFile('postject.exe', ['kimi.exe'], 'win32');
+    expect(result).toEqual({ command: 'postject.exe', args: ['kimi.exe'] });
+  });
+
+  it('wraps .cmd files through cmd.exe on Windows', () => {
+    const result = commandForExecFile('postject.cmd', ['kimi.exe', 'NODE_SEA_BLOB'], 'win32', {
+      ComSpec: 'C:\\Windows\\System32\\cmd.exe',
+    });
+    expect(result.command).toBe('C:\\Windows\\System32\\cmd.exe');
+    expect(result.args).toEqual([
+      '/d',
+      '/s',
+      '/c',
+      '""postject.cmd" "kimi.exe" "NODE_SEA_BLOB""',
+    ]);
+    expect(result.options?.windowsVerbatimArguments).toBe(true);
+  });
+
+  it('wraps .bat files through cmd.exe on Windows', () => {
+    const result = commandForExecFile('foo.bat', [], 'win32', { ComSpec: 'cmd.exe' });
+    expect(result.command).toBe('cmd.exe');
+  });
+
+  it('escapes embedded double quotes in args', () => {
+    const result = commandForExecFile('foo.cmd', ['hello "world"'], 'win32', {
+      ComSpec: 'cmd.exe',
+    });
+    expect(result.args[3]).toBe('""foo.cmd" "hello ""world""""');
+  });
+
+  it('falls back to cmd.exe when ComSpec missing', () => {
+    const result = commandForExecFile('foo.cmd', [], 'win32', {});
+    expect(result.command).toBe('cmd.exe');
+  });
+});
diff --git a/apps/kimi-code/test/scripts/native/manifest.test.ts b/apps/kimi-code/test/scripts/native/manifest.test.ts
new file mode 100644
index 000000000..3f8b6892f
--- /dev/null
+++ b/apps/kimi-code/test/scripts/native/manifest.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  NATIVE_ASSET_MANIFEST_VERSION,
+  buildManifestKey,
+  isManifestVersionSupported,
+} from '../../../scripts/native/manifest.mjs';
+
+describe('NATIVE_ASSET_MANIFEST_VERSION', () => {
+  it('is a positive integer', () => {
+    expect(Number.isInteger(NATIVE_ASSET_MANIFEST_VERSION)).toBe(true);
+    expect(NATIVE_ASSET_MANIFEST_VERSION).toBeGreaterThan(0);
+  });
+});
+
+describe('buildManifestKey', () => {
+  it('namespaces by target', () => {
+    expect(buildManifestKey('darwin-arm64')).toBe('native/darwin-arm64/manifest.json');
+    expect(buildManifestKey('linux-x64')).toBe('native/linux-x64/manifest.json');
+  });
+});
+
+describe('isManifestVersionSupported', () => {
+  it('accepts current version', () => {
+    expect(isManifestVersionSupported(NATIVE_ASSET_MANIFEST_VERSION)).toBe(true);
+  });
+
+  it('rejects other versions', () => {
+    expect(isManifestVersionSupported(NATIVE_ASSET_MANIFEST_VERSION + 1)).toBe(false);
+    expect(isManifestVersionSupported(0)).toBe(false);
+  });
+});
diff --git a/apps/kimi-code/test/scripts/native/native-deps.test.ts b/apps/kimi-code/test/scripts/native/native-deps.test.ts
new file mode 100644
index 000000000..c96b642e6
--- /dev/null
+++ b/apps/kimi-code/test/scripts/native/native-deps.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  nativeDeps,
+  resolveTargetDeps,
+  isSupportedTarget,
+  SUPPORTED_TARGETS,
+} from '../../../scripts/native/native-deps.mjs';
+
+describe('SUPPORTED_TARGETS', () => {
+  it('contains the six published targets', () => {
+    expect([...SUPPORTED_TARGETS].toSorted()).toEqual(
+      [
+        'darwin-arm64',
+        'darwin-x64',
+        'linux-arm64',
+        'linux-x64',
+        'win32-arm64',
+        'win32-x64',
+      ].toSorted(),
+    );
+  });
+});
+
+describe('isSupportedTarget', () => {
+  it('accepts every supported target', () => {
+    for (const t of SUPPORTED_TARGETS) {
+      expect(isSupportedTarget(t)).toBe(true);
+    }
+  });
+
+  it('rejects unknown targets', () => {
+    expect(isSupportedTarget('linux-x64-musl')).toBe(false);
+    expect(isSupportedTarget('darwin-arm')).toBe(false);
+  });
+});
+
+describe('resolveTargetDeps', () => {
+  it('returns one descriptor per package for darwin-arm64', () => {
+    const deps = resolveTargetDeps('darwin-arm64');
+    const names = deps.map((d) => d.resolvedName);
+    expect(names).toContain('@mariozechner/clipboard');
+    expect(names).toContain('@mariozechner/clipboard-darwin-arm64');
+    expect(names).toContain('koffi');
+  });
+
+  it('picks the right clipboard subpackage per target', () => {
+    expect(
+      resolveTargetDeps('linux-x64').map((d) => d.resolvedName),
+    ).toContain('@mariozechner/clipboard-linux-x64-gnu');
+    expect(
+      resolveTargetDeps('win32-x64').map((d) => d.resolvedName),
+    ).toContain('@mariozechner/clipboard-win32-x64-msvc');
+    expect(
+      resolveTargetDeps('win32-arm64').map((d) => d.resolvedName),
+    ).toContain('@mariozechner/clipboard-win32-arm64-msvc');
+  });
+
+  it('encodes koffi native file path with target triplet', () => {
+    const linuxKoffi = resolveTargetDeps('linux-arm64').find((d) => d.resolvedName === 'koffi');
+    expect(linuxKoffi?.nativeFileRelatives).toEqual(['build/koffi/linux_arm64/koffi.node']);
+    const macKoffi = resolveTargetDeps('darwin-x64').find((d) => d.resolvedName === 'koffi');
+    expect(macKoffi?.nativeFileRelatives).toEqual(['build/koffi/darwin_x64/koffi.node']);
+    const winArmKoffi = resolveTargetDeps('win32-arm64').find((d) => d.resolvedName === 'koffi');
+    expect(winArmKoffi?.nativeFileRelatives).toEqual(['build/koffi/win32_arm64/koffi.node']);
+  });
+
+  it('throws on unsupported target', () => {
+    expect(() => resolveTargetDeps('linux-x64-musl')).toThrow(/unsupported/i);
+  });
+});
+
+describe('nativeDeps registry shape', () => {
+  it('has clipboard host (collect=js-only)', () => {
+    const host = nativeDeps.find((d) => d.id === 'clipboard-host');
+    expect(host?.collect).toBe('js-only');
+  });
+
+  it('has clipboard-target (collect=native-files, parent=clipboard-host)', () => {
+    const target = nativeDeps.find((d) => d.id === 'clipboard-target');
+    expect(target?.collect).toBe('native-files');
+    expect(target?.parent).toBe('clipboard-host');
+  });
+
+  it('has koffi (collect=js-and-native-file, parent=pi-tui)', () => {
+    const koffi = nativeDeps.find((d) => d.id === 'koffi');
+    expect(koffi?.collect).toBe('js-and-native-file');
+    expect(koffi?.parent).toBe('pi-tui');
+  });
+});
diff --git a/apps/kimi-code/test/scripts/native/paths.test.ts b/apps/kimi-code/test/scripts/native/paths.test.ts
new file mode 100644
index 000000000..80209f457
--- /dev/null
+++ b/apps/kimi-code/test/scripts/native/paths.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  appRoot,
+  executableName,
+  nativeIntermediatesDir,
+  nativeBinDir,
+  nativeBinPath,
+  nativeBlobPath,
+  nativeJsBundlePath,
+  nativeManifestKey,
+  nativeSeaConfigPath,
+  targetTriple,
+  nativeDistRoot,
+  nativeManifestDir,
+  nativeArtifactsDir,
+  nativeSmokeHome,
+  SEA_SENTINEL_FUSE,
+} from '../../../scripts/native/paths.mjs';
+
+describe('targetTriple', () => {
+  it('returns platform-arch when env unset', () => {
+    expect(targetTriple({ platform: 'darwin', arch: 'arm64', env: {} })).toBe('darwin-arm64');
+    expect(targetTriple({ platform: 'linux', arch: 'x64', env: {} })).toBe('linux-x64');
+    expect(targetTriple({ platform: 'win32', arch: 'x64', env: {} })).toBe('win32-x64');
+  });
+
+  it('honors KIMI_CODE_BUILD_TARGET override', () => {
+    expect(
+      targetTriple({
+        platform: 'darwin',
+        arch: 'arm64',
+        env: { KIMI_CODE_BUILD_TARGET: 'linux-arm64' },
+      }),
+    ).toBe('linux-arm64');
+  });
+});
+
+describe('executableName', () => {
+  it('returns kimi.exe on win32', () => {
+    expect(executableName('win32')).toBe('kimi.exe');
+  });
+
+  it('returns kimi on other platforms', () => {
+    expect(executableName('darwin')).toBe('kimi');
+    expect(executableName('linux')).toBe('kimi');
+  });
+});
+
+describe('path helpers', () => {
+  it('returns absolute intermediates dir under app root', () => {
+    expect(nativeIntermediatesDir()).toBe(`${appRoot}/dist-native/intermediates`);
+  });
+
+  it('returns absolute bin dir per target', () => {
+    expect(nativeBinDir('darwin-arm64')).toBe(`${appRoot}/dist-native/bin/darwin-arm64`);
+  });
+
+  it('returns absolute bin path with executable name', () => {
+    expect(nativeBinPath('darwin-arm64', 'darwin')).toBe(
+      `${appRoot}/dist-native/bin/darwin-arm64/kimi`,
+    );
+    expect(nativeBinPath('win32-x64', 'win32')).toBe(
+      `${appRoot}/dist-native/bin/win32-x64/kimi.exe`,
+    );
+  });
+
+  it('returns intermediate artifact paths', () => {
+    expect(nativeJsBundlePath()).toBe(`${appRoot}/dist-native/intermediates/main.cjs`);
+    expect(nativeBlobPath()).toBe(`${appRoot}/dist-native/intermediates/kimi.blob`);
+    expect(nativeSeaConfigPath()).toBe(
+      `${appRoot}/dist-native/intermediates/sea-config.json`,
+    );
+  });
+
+  it('returns manifest key for target', () => {
+    expect(nativeManifestKey('darwin-arm64')).toBe('native/darwin-arm64/manifest.json');
+  });
+
+  it('returns native dist root', () => {
+    expect(nativeDistRoot()).toBe(`${appRoot}/dist-native`);
+  });
+
+  it('returns manifest dir for target', () => {
+    expect(nativeManifestDir('darwin-arm64')).toBe(
+      `${appRoot}/dist-native/intermediates/native-assets/darwin-arm64`,
+    );
+  });
+
+  it('returns artifacts dir', () => {
+    expect(nativeArtifactsDir()).toBe(`${appRoot}/dist-native/artifacts`);
+  });
+
+  it('returns smoke home', () => {
+    expect(nativeSmokeHome()).toBe(`${appRoot}/dist-native/smoke-home`);
+  });
+
+  it('has correct SEA sentinel fuse value', () => {
+    expect(SEA_SENTINEL_FUSE).toBe('NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2');
+  });
+});
diff --git a/apps/kimi-code/test/scripts/native/release-artifacts.test.ts b/apps/kimi-code/test/scripts/native/release-artifacts.test.ts
new file mode 100644
index 000000000..791fd14e0
--- /dev/null
+++ b/apps/kimi-code/test/scripts/native/release-artifacts.test.ts
@@ -0,0 +1,150 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { inflateRawSync } from 'node:zlib';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { appRoot } from '../../../scripts/native/paths.mjs';
+
+const execFileAsync = promisify(execFile);
+const packageScript = resolve(appRoot, 'scripts/native/package.mjs');
+const manifestScript = resolve(appRoot, 'scripts/native/produce-manifest.mjs');
+const artifactsDir = resolve(appRoot, 'dist-native/artifacts');
+const target = 'test-zip-artifact';
+const executableName = process.platform === 'win32' ? 'kimi.exe' : 'kimi';
+const fakeBinary = resolve(appRoot, 'dist-native/bin', target, executableName);
+
+function sha256(bytes: Buffer | string): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function zipEntryNames(zipPath: string): readonly string[] {
+  const zip = readFileSync(zipPath);
+  const eocdOffset = findEndOfCentralDirectory(zip);
+  const entryCount = zip.readUInt16LE(eocdOffset + 10);
+  let offset = zip.readUInt32LE(eocdOffset + 16);
+  const names: string[] = [];
+
+  for (let i = 0; i < entryCount; i += 1) {
+    expect(zip.readUInt32LE(offset)).toBe(0x02014b50);
+    const nameLength = zip.readUInt16LE(offset + 28);
+    const extraLength = zip.readUInt16LE(offset + 30);
+    const commentLength = zip.readUInt16LE(offset + 32);
+    names.push(zip.subarray(offset + 46, offset + 46 + nameLength).toString('utf-8'));
+    offset += 46 + nameLength + extraLength + commentLength;
+  }
+
+  return names;
+}
+
+function readZipEntry(zipPath: string, expectedName: string): Buffer {
+  const zip = readFileSync(zipPath);
+  const eocdOffset = findEndOfCentralDirectory(zip);
+  const entryCount = zip.readUInt16LE(eocdOffset + 10);
+  let offset = zip.readUInt32LE(eocdOffset + 16);
+
+  for (let i = 0; i < entryCount; i += 1) {
+    expect(zip.readUInt32LE(offset)).toBe(0x02014b50);
+    const method = zip.readUInt16LE(offset + 10);
+    const compressedSize = zip.readUInt32LE(offset + 20);
+    const nameLength = zip.readUInt16LE(offset + 28);
+    const extraLength = zip.readUInt16LE(offset + 30);
+    const commentLength = zip.readUInt16LE(offset + 32);
+    const localHeaderOffset = zip.readUInt32LE(offset + 42);
+    const name = zip.subarray(offset + 46, offset + 46 + nameLength).toString('utf-8');
+    if (name === expectedName) {
+      return readLocalEntry(zip, localHeaderOffset, method, compressedSize);
+    }
+    offset += 46 + nameLength + extraLength + commentLength;
+  }
+
+  throw new Error(`zip entry not found: ${expectedName}`);
+}
+
+function readLocalEntry(
+  zip: Buffer,
+  localHeaderOffset: number,
+  method: number,
+  compressedSize: number,
+): Buffer {
+  expect(zip.readUInt32LE(localHeaderOffset)).toBe(0x04034b50);
+  const nameLength = zip.readUInt16LE(localHeaderOffset + 26);
+  const extraLength = zip.readUInt16LE(localHeaderOffset + 28);
+  const dataStart = localHeaderOffset + 30 + nameLength + extraLength;
+  const compressed = zip.subarray(dataStart, dataStart + compressedSize);
+  if (method === 0) return compressed;
+  if (method === 8) return inflateRawSync(compressed);
+  throw new Error(`unsupported zip compression method: ${String(method)}`);
+}
+
+function findEndOfCentralDirectory(zip: Buffer): number {
+  for (let offset = zip.length - 22; offset >= 0; offset -= 1) {
+    if (zip.readUInt32LE(offset) === 0x06054b50) return offset;
+  }
+  throw new Error('end of central directory not found');
+}
+
+describe('native release artifacts', () => {
+  afterEach(() => {
+    rmSync(resolve(appRoot, 'dist-native/bin', target), { recursive: true, force: true });
+    rmSync(resolve(artifactsDir, `kimi-code-${target}.zip`), { force: true });
+    rmSync(resolve(artifactsDir, `kimi-code-${target}.zip.sha256`), { force: true });
+  });
+
+  it('packages the native binary as a zip archive and checksums the archive', async () => {
+    const binaryContent = 'native binary payload\n';
+    mkdirSync(resolve(appRoot, 'dist-native/bin', target), { recursive: true });
+    writeFileSync(fakeBinary, binaryContent, { mode: 0o755 });
+
+    await execFileAsync(process.execPath, [packageScript], {
+      cwd: appRoot,
+      env: { ...process.env, KIMI_CODE_BUILD_TARGET: target },
+    });
+
+    const archivePath = resolve(artifactsDir, `kimi-code-${target}.zip`);
+    const checksumPath = `${archivePath}.sha256`;
+    expect(existsSync(archivePath)).toBe(true);
+    expect(existsSync(checksumPath)).toBe(true);
+    expect(zipEntryNames(archivePath)).toEqual([executableName]);
+    expect(readZipEntry(archivePath, executableName).toString('utf-8')).toBe(binaryContent);
+    expect(readFileSync(checksumPath, 'utf-8')).toBe(
+      `${sha256(readFileSync(archivePath))}  kimi-code-${target}.zip\n`,
+    );
+  });
+
+  it('produces a manifest from zip archive checksums', async () => {
+    const releaseDir = await mkdtemp(join(tmpdir(), 'kimi-manifest-zip-'));
+    const archiveBytes = Buffer.from('fake zip bytes');
+    const checksum = sha256(archiveBytes);
+    await writeFile(join(releaseDir, 'kimi-code-darwin-arm64.zip'), archiveBytes);
+    await writeFile(
+      join(releaseDir, 'kimi-code-darwin-arm64.zip.sha256'),
+      `${checksum}  kimi-code-darwin-arm64.zip\n`,
+    );
+
+    await execFileAsync(process.execPath, [manifestScript, releaseDir, '@moonshot-ai/kimi-code@0.5.0']);
+
+    const manifest = JSON.parse(
+      await readFile(join(releaseDir, 'manifest.json'), 'utf-8'),
+    ) as {
+      version: string;
+      tag: string;
+      platforms: Record<string, { filename: string; checksum: string }>;
+    };
+    expect(manifest).toEqual({
+      version: '0.5.0',
+      tag: '@moonshot-ai/kimi-code@0.5.0',
+      platforms: {
+        'darwin-arm64': {
+          filename: 'kimi-code-darwin-arm64.zip',
+          checksum,
+        },
+      },
+    });
+  });
+});
diff --git a/apps/kimi-code/test/scripts/native/sign-args.test.ts b/apps/kimi-code/test/scripts/native/sign-args.test.ts
new file mode 100644
index 000000000..803f1820a
--- /dev/null
+++ b/apps/kimi-code/test/scripts/native/sign-args.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildCodesignArgs } from '../../../scripts/native/04-sign.mjs';
+
+describe('buildCodesignArgs', () => {
+  it('returns ad-hoc args for identity "-"', () => {
+    const args = buildCodesignArgs({
+      identity: '-',
+      executable: '/path/kimi',
+      entitlementsPath: '/path/entitlements.plist',
+      keychainPath: null,
+    });
+    expect(args).toEqual(['--sign', '-', '/path/kimi']);
+  });
+
+  it('returns hardened-runtime args for Developer ID identity', () => {
+    const args = buildCodesignArgs({
+      identity: 'Developer ID Application: Moonshot AI (ABCD1234)',
+      executable: '/path/kimi',
+      entitlementsPath: '/path/entitlements.plist',
+      keychainPath: '/tmp/sign.keychain-db',
+    });
+    expect(args).toEqual([
+      '--sign',
+      'Developer ID Application: Moonshot AI (ABCD1234)',
+      '--options',
+      'runtime',
+      '--entitlements',
+      '/path/entitlements.plist',
+      '--timestamp',
+      '--keychain',
+      '/tmp/sign.keychain-db',
+      '--force',
+      '/path/kimi',
+    ]);
+  });
+
+  it('omits --keychain when keychainPath is null but uses Developer ID otherwise', () => {
+    const args = buildCodesignArgs({
+      identity: 'Developer ID Application: Moonshot AI (ABCD1234)',
+      executable: '/path/kimi',
+      entitlementsPath: '/path/entitlements.plist',
+      keychainPath: null,
+    });
+    expect(args).toContain('--entitlements');
+    expect(args).not.toContain('--keychain');
+  });
+});
diff --git a/apps/kimi-code/test/scripts/nix/update-pnpm-deps.test.ts b/apps/kimi-code/test/scripts/nix/update-pnpm-deps.test.ts
new file mode 100644
index 000000000..87aaf27ec
--- /dev/null
+++ b/apps/kimi-code/test/scripts/nix/update-pnpm-deps.test.ts
@@ -0,0 +1,152 @@
+import { execFile } from 'node:child_process';
+import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+const execFileAsync = promisify(execFile);
+
+const repoRoot = resolve(import.meta.dirname, '../../../../..');
+const scriptPath = join(repoRoot, 'build/nix/update-pnpm-deps.sh');
+
+const currentHash = 'sha256-LZ9Bkm3pG2ib7NcdqcP/kmoYWsNjXQ8PoEIlg/94oVo=';
+const fakeHash = 'sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=';
+const newHash = 'sha256-NNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN=';
+
+const tempRoots: string[] = [];
+
+describe('update-pnpm-deps.sh', () => {
+  afterEach(async () => {
+    await Promise.all(tempRoots.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  it('exits without patching fakeHash when the current pnpmDeps hash still builds', async () => {
+    const fixture = await createFixtureRepo(currentHash);
+    const result = await runUpdateScript(fixture, { currentValid: true });
+
+    await expect(readFile(join(fixture.root, 'flake.nix'), 'utf-8')).resolves.toContain(currentHash);
+    await expect(readFile(join(fixture.root, 'flake.nix'), 'utf-8')).resolves.not.toContain(fakeHash);
+    await expect(readFile(fixture.nixLogPath, 'utf-8')).resolves.toBe('current\n');
+    expect(result.stdout).toContain('pnpmDeps hash still valid');
+
+    const cache = JSON.parse(
+      await readFile(join(fixture.root, '.git/kimi-code/pnpm-deps-hashes-v1.json'), 'utf-8'),
+    ) as Record<string, { hash: string }>;
+    expect(Object.values(cache)).toContainEqual(expect.objectContaining({ hash: currentHash }));
+  });
+
+  it('writes a local cache after discovery and verifies the cached hash on the next run', async () => {
+    const fixture = await createFixtureRepo(currentHash);
+
+    await runUpdateScript(fixture, { currentValid: false });
+    await expect(readFile(join(fixture.root, 'flake.nix'), 'utf-8')).resolves.toContain(newHash);
+
+    const cache = JSON.parse(
+      await readFile(join(fixture.root, '.git/kimi-code/pnpm-deps-hashes-v1.json'), 'utf-8'),
+    ) as Record<string, { hash: string }>;
+    expect(Object.values(cache)).toContainEqual(expect.objectContaining({ hash: newHash }));
+
+    await writeFile(join(fixture.root, 'flake.nix'), flakeWithHash(currentHash));
+    await writeFile(fixture.nixLogPath, '');
+
+    const result = await runUpdateScript(fixture, { currentValid: false });
+
+    await expect(readFile(join(fixture.root, 'flake.nix'), 'utf-8')).resolves.toContain(newHash);
+    await expect(readFile(fixture.nixLogPath, 'utf-8')).resolves.toBe('current\nnew\n');
+    expect(result.stdout).toContain('cache hit');
+  });
+});
+
+async function createFixtureRepo(hash: string): Promise<{ binDir: string; nixLogPath: string; root: string }> {
+  const root = await mkdtemp(join(tmpdir(), 'kimi-update-pnpm-deps-'));
+  tempRoots.push(root);
+
+  await writeFile(join(root, 'flake.nix'), flakeWithHash(hash));
+  await writeFile(join(root, 'flake.lock'), '{}\n');
+  await writeFile(join(root, '.npmrc'), 'engine-strict=true\n');
+  await writeFile(join(root, 'package.json'), '{"name":"root"}\n');
+  await writeFile(join(root, 'pnpm-lock.yaml'), 'lockfileVersion: 9.0\n');
+  await writeFile(join(root, 'pnpm-workspace.yaml'), 'packages:\n  - "apps/*"\n');
+  await mkdir(join(root, 'apps/example'), { recursive: true });
+  await writeFile(join(root, 'apps/example/package.json'), '{"name":"example"}\n');
+
+  await execFileAsync('git', ['init'], { cwd: root });
+
+  const binDir = join(root, 'bin');
+  const nixLogPath = join(root, 'nix.log');
+  await mkdir(binDir);
+  await writeFile(nixLogPath, '');
+  await writeFile(
+    join(binDir, 'nix'),
+    `#!/usr/bin/env bash
+set -euo pipefail
+
+state=unknown
+if grep -Fq "$CURRENT_HASH" flake.nix; then
+  state=current
+elif grep -Fq "$FAKE_HASH" flake.nix; then
+  state=fake
+elif grep -Fq "$NEW_HASH" flake.nix; then
+  state=new
+fi
+
+printf '%s\\n' "$state" >> "$NIX_LOG"
+
+case "$state" in
+  current)
+    if [ "\${CURRENT_VALID:-0}" = "1" ]; then
+      exit 0
+    fi
+    echo "current hash invalid" >&2
+    exit 1
+    ;;
+  fake)
+    echo "error: hash mismatch" >&2
+    echo "       got:    $NEW_HASH" >&2
+    exit 1
+    ;;
+  new)
+    exit 0
+    ;;
+  *)
+    echo "unexpected hash state: $state" >&2
+    exit 1
+    ;;
+esac
+`,
+  );
+  await chmod(join(binDir, 'nix'), 0o755);
+
+  return { binDir, nixLogPath, root };
+}
+
+async function runUpdateScript(
+  fixture: { binDir: string; nixLogPath: string; root: string },
+  options: { currentValid: boolean },
+): Promise<{ stdout: string; stderr: string }> {
+  return execFileAsync('bash', [scriptPath], {
+    cwd: fixture.root,
+    env: {
+      ...process.env,
+      CURRENT_HASH: currentHash,
+      CURRENT_VALID: options.currentValid ? '1' : '0',
+      FAKE_HASH: fakeHash,
+      NEW_HASH: newHash,
+      NIX_LOG: fixture.nixLogPath,
+      PATH: `${fixture.binDir}:${process.env['PATH'] ?? ''}`,
+    },
+  });
+}
+
+function flakeWithHash(hash: string): string {
+  return `{
+  outputs = { self, nixpkgs }: {
+    packages.x86_64-linux.kimi-code-pnpm-deps = {
+      hash = "${hash}";
+    };
+  };
+}
+`;
+}
diff --git a/apps/kimi-code/test/tui/actions/replay-hydrate-agent-group.test.ts b/apps/kimi-code/test/tui/actions/replay-hydrate-agent-group.test.ts
new file mode 100644
index 000000000..31197ace8
--- /dev/null
+++ b/apps/kimi-code/test/tui/actions/replay-hydrate-agent-group.test.ts
@@ -0,0 +1,352 @@
+
+import { Text } from '@earendil-works/pi-tui';
+import type { Session } from '@moonshot-ai/kimi-code-sdk';
+import { describe, expect, it, vi } from 'vitest';
+
+import { hydrateProjectedEntries, hydrateTranscriptFromReplay } from '#/tui/actions/replay-ops';
+import { AgentGroupComponent } from '#/tui/components/messages/agent-group';
+import { ToolCallComponent } from '#/tui/components/messages/tool-call';
+import { createTUIState, type KimiTUIOptions, type TUIState } from '#/tui/kimi-tui';
+import type { AppState, ToolCallBlockData, TranscriptEntry } from '#/tui/types';
+
+function makeAppState(): AppState {
+  return {
+    model: 'k2',
+    workDir: '/tmp/proj-a',
+    sessionId: 'sess-1',
+    yolo: false,
+    permissionMode: 'manual',
+    planMode: false,
+    thinking: false,
+    contextUsage: 0,
+    contextTokens: 0,
+    maxContextTokens: 100,
+    isStreaming: false,
+    isCompacting: false,
+    isReplaying: false,
+    streamingPhase: 'idle',
+    streamingStartTime: 0,
+    theme: 'dark',
+    version: '0.0.0-test',
+    editorCommand: null,
+    notifications: { enabled: true, condition: 'unfocused' },
+    availableModels: {},
+    availableProviders: {},
+    sessionTitle: null,
+  };
+}
+
+function makeTuiState(): TUIState {
+  const options: KimiTUIOptions = {
+    initialAppState: makeAppState(),
+    startup: {
+      continueLast: false,
+      yolo: false,
+      plan: false,
+    },
+    resolvedTheme: 'dark',
+  };
+  const state = createTUIState(options);
+  vi.spyOn(state.ui, 'requestRender').mockImplementation(() => {});
+  return state;
+}
+
+function appendEntry(state: TUIState, entry: TranscriptEntry): void {
+  state.transcriptEntries.push(entry);
+  if (entry.toolCallData !== undefined) {
+    const tc = new ToolCallComponent(
+      entry.toolCallData,
+      entry.toolCallData.result,
+      state.theme.colors,
+      state.ui,
+      state.theme.markdownTheme,
+    );
+    state.pendingToolComponents.set(entry.toolCallData.id, tc);
+    state.transcriptContainer.addChild(tc);
+    return;
+  }
+  state.transcriptContainer.addChild(new Text(entry.content, 0, 0));
+}
+
+function hydrate(state: TUIState, entries: readonly TranscriptEntry[]): void {
+  hydrateProjectedEntries(state, entries, (entry) => {
+    appendEntry(state, entry);
+  });
+}
+
+function setTodoList(
+  state: TUIState,
+  todos: Parameters<TUIState['todoPanel']['setTodos']>[0],
+): void {
+  state.todoPanel.setTodos(todos);
+  state.todoPanelContainer.clear();
+  if (!state.todoPanel.isEmpty()) {
+    state.todoPanelContainer.addChild(state.todoPanel);
+  }
+}
+
+function sessionWithToolStore(toolStore: Record<string, unknown>): Session {
+  return {
+    getResumeState: () => ({
+      sessionMetadata: {},
+      agents: {
+        main: {
+          type: 'main',
+          config: {
+            modelAlias: 'k2',
+            provider: undefined,
+            modelCapabilities: { max_context_tokens: 100 },
+          },
+          context: { history: [], tokenCount: 0 },
+          replay: [],
+          permission: { mode: 'manual' },
+          plan: null,
+          usage: {},
+          tools: [],
+          toolStore,
+          background: [],
+        },
+      },
+    }),
+  } as unknown as Session;
+}
+
+let entryIdSeq = 0;
+function makeAgentEntry(
+  id: string,
+  step: number,
+  turnId: string,
+  result?: { is_error?: boolean },
+): TranscriptEntry {
+  entryIdSeq += 1;
+  const tc: ToolCallBlockData = {
+    id,
+    name: 'Agent',
+    args: { description: id },
+    step,
+    turnId,
+    ...(result !== undefined
+      ? { result: { tool_call_id: id, output: 'done', is_error: result.is_error ?? false } }
+      : {}),
+  };
+  return {
+    id: `e${String(entryIdSeq)}`,
+    kind: 'tool_call',
+    turnId,
+    renderMode: 'plain',
+    content: '',
+    toolCallData: tc,
+  };
+}
+
+function makeBashEntry(id: string, step: number, turnId: string): TranscriptEntry {
+  entryIdSeq += 1;
+  const tc: ToolCallBlockData = {
+    id,
+    name: 'Bash',
+    args: { command: 'pwd' },
+    step,
+    turnId,
+  };
+  return {
+    id: `e${String(entryIdSeq)}`,
+    kind: 'tool_call',
+    turnId,
+    renderMode: 'plain',
+    content: '',
+    toolCallData: tc,
+  };
+}
+
+function makeUserEntry(turnId: string, content: string): TranscriptEntry {
+  entryIdSeq += 1;
+  return {
+    id: `e${String(entryIdSeq)}`,
+    kind: 'user',
+    turnId,
+    renderMode: 'plain',
+    content,
+  };
+}
+
+describe('hydrateProjectedEntries', () => {
+  it('hydrates the visible todo panel from resumed tool store state', async () => {
+    const state = makeTuiState();
+    const errors: string[] = [];
+
+    const ok = await hydrateTranscriptFromReplay(
+      state,
+      {
+        setAppState: (patch) => {
+          state.appState = { ...state.appState, ...patch };
+        },
+        appendEntry: (entry) => {
+          appendEntry(state, entry);
+        },
+        setTodoList: (todos) => {
+          setTodoList(state, todos);
+        },
+        emitError: (message) => {
+          errors.push(message);
+        },
+      },
+      sessionWithToolStore({
+        todo: [
+          { title: 'Review resume snapshot', status: 'done' },
+          { title: 'Render todo panel', status: 'in_progress' },
+          { title: '', status: 'pending' },
+        ],
+      }),
+    );
+
+    expect(ok).toBe(true);
+    expect(errors).toEqual([]);
+    expect(state.todoPanel.getTodos()).toEqual([
+      { title: 'Review resume snapshot', status: 'done' },
+      { title: 'Render todo panel', status: 'in_progress' },
+    ]);
+    expect(state.todoPanelContainer.children).toContain(state.todoPanel);
+  });
+
+  it('clears the todo panel when resumed state has no todo store entry', async () => {
+    const state = makeTuiState();
+    setTodoList(state, [{ title: 'stale todo', status: 'pending' }]);
+
+    const ok = await hydrateTranscriptFromReplay(
+      state,
+      {
+        setAppState: (patch) => {
+          state.appState = { ...state.appState, ...patch };
+        },
+        appendEntry: (entry) => {
+          appendEntry(state, entry);
+        },
+        setTodoList: (todos) => {
+          setTodoList(state, todos);
+        },
+        emitError: () => {},
+      },
+      sessionWithToolStore({}),
+    );
+
+    expect(ok).toBe(true);
+    expect(state.todoPanel.getTodos()).toEqual([]);
+    expect(state.todoPanelContainer.children).not.toContain(state.todoPanel);
+  });
+
+  it('groups 2 adjacent same-step Agents into a single AgentGroupComponent', () => {
+    const state = makeTuiState();
+    const entries: TranscriptEntry[] = [
+      makeAgentEntry('a1', 1, 't1', { is_error: false }),
+      makeAgentEntry('a2', 1, 't1', { is_error: false }),
+    ];
+
+    hydrate(state, entries);
+
+    const children = state.transcriptContainer.children;
+    expect(children.length).toBe(1);
+    expect(children[0]).toBeInstanceOf(AgentGroupComponent);
+    expect((children[0] as AgentGroupComponent).size()).toBe(2);
+    // ToolCallComponent still registers in pendingToolComponents because
+    // later wire event routing depends on this mapping.
+    expect(state.pendingToolComponents.has('a1')).toBe(true);
+    expect(state.pendingToolComponents.has('a2')).toBe(true);
+  });
+
+  it('keeps cross-step Agents independent', () => {
+    const state = makeTuiState();
+    const entries: TranscriptEntry[] = [
+      makeAgentEntry('a1', 1, 't1'),
+      makeAgentEntry('a2', 2, 't1'),
+    ];
+
+    hydrate(state, entries);
+    const children = state.transcriptContainer.children;
+    expect(children.length).toBe(2);
+    expect(children[0]).toBeInstanceOf(ToolCallComponent);
+    expect(children[1]).toBeInstanceOf(ToolCallComponent);
+  });
+
+  it('does not group when a non-Agent tool sits between Agents', () => {
+    const state = makeTuiState();
+    const entries: TranscriptEntry[] = [
+      makeAgentEntry('a1', 1, 't1'),
+      makeBashEntry('b1', 1, 't1'),
+      makeAgentEntry('a2', 1, 't1'),
+    ];
+
+    hydrate(state, entries);
+    const children = state.transcriptContainer.children;
+    expect(children.length).toBe(3);
+    for (const child of children) expect(child).toBeInstanceOf(ToolCallComponent);
+  });
+
+  it('a single Agent is left as a standalone ToolCallComponent', () => {
+    const state = makeTuiState();
+    hydrate(state, [makeAgentEntry('a1', 1, 't1')]);
+    const children = state.transcriptContainer.children;
+    expect(children.length).toBe(1);
+    expect(children[0]).toBeInstanceOf(ToolCallComponent);
+  });
+
+  it('user message between Agents prevents grouping', () => {
+    const state = makeTuiState();
+    const entries: TranscriptEntry[] = [
+      makeAgentEntry('a1', 1, 't1'),
+      makeUserEntry('t1', 'hello'),
+      makeAgentEntry('a2', 1, 't1'),
+    ];
+
+    hydrate(state, entries);
+    const children = state.transcriptContainer.children;
+    expect(children.length).toBe(3);
+    expect(children[0]).toBeInstanceOf(ToolCallComponent);
+    expect(children[2]).toBeInstanceOf(ToolCallComponent);
+  });
+
+  it('replay does not write pendingAgentGroup (it stays null after hydration)', () => {
+    const state = makeTuiState();
+    hydrate(state, [makeAgentEntry('a1', 1, 't1'), makeAgentEntry('a2', 1, 't1')]);
+    expect(state.pendingAgentGroup).toBeNull();
+  });
+
+  it('background Agent replay hydrates only background status rows, not AgentGroupComponent', () => {
+    const state = makeTuiState();
+    hydrate(state, [
+      {
+        id: 'e-background-started',
+        kind: 'status',
+        renderMode: 'plain',
+        content: 'explore agent started in background',
+      },
+      {
+        id: 'e-background-completed',
+        kind: 'status',
+        renderMode: 'plain',
+        content: 'explore agent completed in background',
+      },
+    ]);
+
+    expect(
+      state.transcriptContainer.children.some((child) => child instanceof AgentGroupComponent),
+    ).toBe(false);
+    expect(
+      state.transcriptContainer.children.some((child) => child instanceof ToolCallComponent),
+    ).toBe(false);
+  });
+
+  it('group with mixed completed/failed children renders correct phase tails', () => {
+    const state = makeTuiState();
+    hydrate(state, [
+      makeAgentEntry('a1', 1, 't1', { is_error: false }),
+      makeAgentEntry('a2', 1, 't1', { is_error: true }),
+    ]);
+    const group = state.transcriptContainer.children[0] as AgentGroupComponent;
+    const out = group
+      .render(120)
+      .join('\n')
+      .replaceAll(/\[[0-9;]*m/g, '');
+    expect(out).toContain('✓ Completed');
+    expect(out).toContain('✗ Failed');
+  });
+});
diff --git a/apps/kimi-code/test/tui/activity-pane.test.ts b/apps/kimi-code/test/tui/activity-pane.test.ts
new file mode 100644
index 000000000..d0eef5d08
--- /dev/null
+++ b/apps/kimi-code/test/tui/activity-pane.test.ts
@@ -0,0 +1,112 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { KimiTUI, type KimiTUIStartupInput, type TUIState } from '#/tui/kimi-tui';
+
+interface ActivityDriver {
+  state: TUIState;
+  updateActivityPane(): void;
+}
+
+function makeStartupInput(): KimiTUIStartupInput {
+  return {
+    cliOptions: {
+      session: undefined,
+      continue: false,
+      yolo: false,
+      plan: false,
+      model: undefined,
+      outputFormat: undefined,
+      prompt: undefined,
+      skillsDirs: [],
+    },
+    tuiConfig: {
+      theme: 'dark',
+      editorCommand: null,
+      notifications: { enabled: true, condition: 'unfocused' },
+    },
+    version: '0.0.0-test',
+    workDir: '/tmp/proj-a',
+    resolvedTheme: 'dark',
+  };
+}
+
+function makeDriverWithTerminalProgress(): {
+  driver: ActivityDriver;
+  state: TUIState;
+  setProgress: ReturnType<typeof vi.fn<(active: boolean) => void>>;
+} {
+  const setProgress = vi.fn<(active: boolean) => void>();
+  const driver = new KimiTUI({} as never, makeStartupInput()) as unknown as ActivityDriver;
+  vi.spyOn(driver.state.ui, 'requestRender').mockImplementation(() => {});
+  driver.state.terminal = { columns: 80, setProgress } as unknown as TUIState['terminal'];
+  return { driver, state: driver.state, setProgress };
+}
+
+describe('updateActivityPane terminal progress', () => {
+  it('toggles terminal progress when the activity pane enters and leaves work mode', () => {
+    vi.useFakeTimers();
+    try {
+      const { driver, state, setProgress } = makeDriverWithTerminalProgress();
+
+      state.livePane = { ...state.livePane, mode: 'waiting' };
+      driver.updateActivityPane();
+
+      expect(setProgress).toHaveBeenCalledTimes(1);
+      expect(setProgress).toHaveBeenLastCalledWith(true);
+      expect(state.terminalState.progressActive).toBe(true);
+
+      state.livePane = { ...state.livePane, mode: 'idle' };
+      driver.updateActivityPane();
+
+      expect(setProgress).toHaveBeenCalledTimes(2);
+      expect(setProgress).toHaveBeenLastCalledWith(false);
+      expect(state.terminalState.progressActive).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('keeps compaction visible as terminal progress even though the pane is hidden', () => {
+    const { driver, state, setProgress } = makeDriverWithTerminalProgress();
+    state.appState.isCompacting = true;
+    state.appState.streamingPhase = 'waiting';
+
+    driver.updateActivityPane();
+    driver.updateActivityPane();
+
+    expect(setProgress).toHaveBeenCalledTimes(1);
+    expect(setProgress).toHaveBeenLastCalledWith(true);
+
+    state.appState.isCompacting = false;
+    state.appState.streamingPhase = 'idle';
+    driver.updateActivityPane();
+
+    expect(setProgress).toHaveBeenCalledTimes(2);
+    expect(setProgress).toHaveBeenLastCalledWith(false);
+  });
+
+  it('keeps terminal progress active without showing a thinking spinner', () => {
+    vi.useFakeTimers();
+    try {
+      const { driver, state, setProgress } = makeDriverWithTerminalProgress();
+      state.livePane = { ...state.livePane, mode: 'idle' };
+      state.appState.streamingPhase = 'thinking';
+
+      driver.updateActivityPane();
+
+      expect(setProgress).toHaveBeenCalledTimes(1);
+      expect(setProgress).toHaveBeenLastCalledWith(true);
+      expect(state.activitySpinner).toBeUndefined();
+      expect(state.activityContainer.children).toHaveLength(0);
+
+      state.appState.streamingPhase = 'idle';
+      driver.updateActivityPane();
+
+      expect(setProgress).toHaveBeenCalledTimes(2);
+      expect(setProgress).toHaveBeenLastCalledWith(false);
+      expect(state.activitySpinner).toBeUndefined();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
diff --git a/apps/kimi-code/test/tui/background-task-status.test.ts b/apps/kimi-code/test/tui/background-task-status.test.ts
new file mode 100644
index 000000000..e8033d45f
--- /dev/null
+++ b/apps/kimi-code/test/tui/background-task-status.test.ts
@@ -0,0 +1,104 @@
+import type { BackgroundTaskInfo, BackgroundTaskStatus } from '@moonshot-ai/kimi-code-sdk';
+import { describe, expect, it } from 'vitest';
+
+import { formatBackgroundTaskTranscript } from '@/tui/utils/background-task-status';
+
+function task(overrides: Partial<BackgroundTaskInfo> = {}): BackgroundTaskInfo {
+  return {
+    taskId: 'bash-abcd1234',
+    command: 'npm run dev',
+    description: 'dev server',
+    status: 'running',
+    pid: 1234,
+    exitCode: null,
+    startedAt: Date.now() - 1000,
+    endedAt: null,
+    ...overrides,
+  };
+}
+
+describe('formatBackgroundTaskTranscript', () => {
+  it('renders a bash started entry', () => {
+    const data = formatBackgroundTaskTranscript(task({ status: 'running' }));
+    expect(data.phase).toBe('started');
+    expect(data.headline).toContain('bash task started');
+    expect(data.detail).toBe('dev server');
+  });
+
+  it('renders an agent started entry', () => {
+    const data = formatBackgroundTaskTranscript(
+      task({ taskId: 'agent-deadbeef', status: 'running' }),
+    );
+    expect(data.headline).toContain('agent task started');
+  });
+
+  it('renders a completed entry with exit code in detail', () => {
+    const data = formatBackgroundTaskTranscript(
+      task({ status: 'completed', exitCode: 0, endedAt: Date.now() }),
+    );
+    expect(data.phase).toBe('completed');
+    expect(data.headline).toContain('completed');
+    expect(data.detail).toContain('exit 0');
+  });
+
+  it('renders a failed entry with non-zero exit', () => {
+    const data = formatBackgroundTaskTranscript(
+      task({ status: 'failed', exitCode: 2, endedAt: Date.now() }),
+    );
+    expect(data.phase).toBe('failed');
+    expect(data.headline).toContain('failed');
+    expect(data.detail).toContain('exit 2');
+  });
+
+  it('renders a killed entry with stop reason', () => {
+    const data = formatBackgroundTaskTranscript(
+      task({ status: 'killed', stopReason: 'user', endedAt: Date.now() }),
+    );
+    expect(data.phase).toBe('failed');
+    expect(data.headline).toContain('stopped');
+    expect(data.detail).toContain('user');
+  });
+
+  it('renders a lost entry with restart note', () => {
+    const data = formatBackgroundTaskTranscript(task({ status: 'lost', endedAt: Date.now() }));
+    expect(data.phase).toBe('failed');
+    expect(data.headline).toContain('lost');
+    expect(data.detail).toContain('session restarted');
+  });
+
+  it('surfaces awaiting_approval reason', () => {
+    const data = formatBackgroundTaskTranscript(
+      task({ status: 'awaiting_approval', approvalReason: 'needs network' }),
+    );
+    expect(data.phase).toBe('started');
+    expect(data.headline).toContain('awaiting');
+    expect(data.detail).toContain('needs network');
+  });
+
+  it('surfaces timedOut for agent deadlines', () => {
+    const data = formatBackgroundTaskTranscript(
+      task({
+        taskId: 'agent-aaaaaaaa',
+        status: 'failed',
+        exitCode: 1,
+        timedOut: true,
+        endedAt: Date.now(),
+      }),
+    );
+    expect(data.detail).toContain('timed out');
+  });
+
+  it('handles every BackgroundTaskStatus without throwing', () => {
+    const statuses: BackgroundTaskStatus[] = [
+      'running',
+      'awaiting_approval',
+      'completed',
+      'failed',
+      'killed',
+      'lost',
+    ];
+    for (const status of statuses) {
+      expect(() => formatBackgroundTaskTranscript(task({ status }))).not.toThrow();
+    }
+  });
+});
diff --git a/apps/kimi-code/test/tui/commands/registry.test.ts b/apps/kimi-code/test/tui/commands/registry.test.ts
new file mode 100644
index 000000000..3685857b8
--- /dev/null
+++ b/apps/kimi-code/test/tui/commands/registry.test.ts
@@ -0,0 +1,105 @@
+import {
+  BUILTIN_SLASH_COMMANDS,
+  findBuiltInSlashCommand,
+  parseSlashInput,
+  resolveSlashCommandAvailability,
+  sortSlashCommands,
+  type KimiSlashCommand,
+} from '#/tui/commands/index';
+import { describe, expect, it } from 'vitest';
+
+describe('parseSlashInput', () => {
+  it('parses command names and trimmed args', () => {
+    expect(parseSlashInput('/help')).toEqual({ name: 'help', args: '' });
+    expect(parseSlashInput('/model   kimi-k2  ')).toEqual({
+      name: 'model',
+      args: 'kimi-k2',
+    });
+  });
+
+  it('returns null for non-commands and path-like input', () => {
+    expect(parseSlashInput('hello')).toBeNull();
+    expect(parseSlashInput('/')).toBeNull();
+    expect(parseSlashInput('/   ')).toBeNull();
+    expect(parseSlashInput('/some/path')).toBeNull();
+    expect(parseSlashInput('/some/path with args')).toBeNull();
+  });
+});
+
+describe('built-in slash command registry', () => {
+  it('finds built-ins by name or alias', () => {
+    expect(findBuiltInSlashCommand('exit')?.name).toBe('exit');
+    expect(findBuiltInSlashCommand('quit')?.name).toBe('exit');
+    expect(findBuiltInSlashCommand('q')?.name).toBe('exit');
+    expect(findBuiltInSlashCommand('clear')?.name).toBe('new');
+    expect(findBuiltInSlashCommand('mcp')?.name).toBe('mcp');
+    expect(findBuiltInSlashCommand('status')?.name).toBe('status');
+    expect(findBuiltInSlashCommand('usage')?.aliases).not.toContain('status');
+    expect(findBuiltInSlashCommand('unknown')).toBeUndefined();
+  });
+
+  it('marks plan clear as idle-only while normal plan toggles are always available', () => {
+    const plan = findBuiltInSlashCommand('plan');
+    expect(plan).toBeDefined();
+    expect(resolveSlashCommandAvailability(plan!, '')).toBe('always');
+    expect(resolveSlashCommandAvailability(plan!, 'on')).toBe('always');
+    expect(resolveSlashCommandAvailability(plan!, 'clear')).toBe('idle-only');
+  });
+
+  it('defaults commands without explicit availability to idle-only', () => {
+    const command: KimiSlashCommand = {
+      name: 'example',
+      aliases: [],
+      description: 'Example command',
+    };
+
+    expect(resolveSlashCommandAvailability(command, '')).toBe('idle-only');
+  });
+
+  it('sorts commands by priority descending and name ascending', () => {
+    const commands: KimiSlashCommand[] = [
+      { name: 'zebra', aliases: [], description: 'Z', priority: 100 },
+      { name: 'alpha', aliases: [], description: 'A', priority: 100 },
+      { name: 'middle', aliases: [], description: 'M', priority: 50 },
+      { name: 'plain', aliases: [], description: 'P' },
+    ];
+
+    expect(sortSlashCommands(commands).map((command) => command.name)).toEqual([
+      'alpha',
+      'zebra',
+      'middle',
+      'plain',
+    ]);
+  });
+
+  it('contains the expected command names once', () => {
+    const names = BUILTIN_SLASH_COMMANDS.map((command) => command.name);
+
+    expect(new Set(names).size).toBe(names.length);
+    expect(names).toEqual(
+      expect.arrayContaining([
+        'compact',
+        'editor',
+        'exit',
+        'fork',
+        'help',
+        'init',
+        'login',
+        'logout',
+        'mcp',
+        'model',
+        'new',
+        'permission',
+        'plan',
+        'sessions',
+        'settings',
+        'status',
+        'theme',
+        'title',
+        'usage',
+        'version',
+        'yolo',
+      ]),
+    );
+  });
+});
diff --git a/apps/kimi-code/test/tui/commands/resolve.test.ts b/apps/kimi-code/test/tui/commands/resolve.test.ts
new file mode 100644
index 000000000..ae043d5f4
--- /dev/null
+++ b/apps/kimi-code/test/tui/commands/resolve.test.ts
@@ -0,0 +1,117 @@
+import {
+  resolveSkillCommand,
+  resolveSlashCommandInput,
+  slashBusyMessage,
+  slashCommandBusyReason,
+} from '#/tui/commands/index';
+import { describe, expect, it } from 'vitest';
+
+function resolve(
+  input: string,
+  overrides: Partial<Parameters<typeof resolveSlashCommandInput>[0]> = {},
+) {
+  return resolveSlashCommandInput({
+    input,
+    skillCommandMap: new Map<string, string>(),
+    isStreaming: false,
+    isCompacting: false,
+    ...overrides,
+  });
+}
+
+describe('resolveSlashCommandInput', () => {
+  it('returns not-command for normal text', () => {
+    expect(resolve('hello')).toEqual({ kind: 'not-command' });
+  });
+
+  it('resolves built-in commands by name and alias', () => {
+    expect(resolve('/help')).toMatchObject({ kind: 'builtin', name: 'help', args: '' });
+    expect(resolve('/q')).toMatchObject({ kind: 'builtin', name: 'exit', args: '' });
+    expect(resolve('/clear')).toMatchObject({ kind: 'builtin', name: 'new', args: '' });
+    expect(resolve('/fork')).toMatchObject({ kind: 'builtin', name: 'fork', args: '' });
+    expect(resolve('/title New title')).toMatchObject({
+      kind: 'builtin',
+      name: 'title',
+      args: 'New title',
+    });
+    expect(resolve('/init')).toMatchObject({ kind: 'builtin', name: 'init', args: '' });
+  });
+
+  it('blocks idle-only built-ins while streaming', () => {
+    expect(resolve('/new', { isStreaming: true })).toEqual({
+      kind: 'blocked',
+      commandName: 'new',
+      reason: 'streaming',
+    });
+    expect(resolve('/init', { isStreaming: true })).toEqual({
+      kind: 'blocked',
+      commandName: 'init',
+      reason: 'streaming',
+    });
+  });
+
+  it('allows always-available built-ins while streaming', () => {
+    expect(resolve('/plan on', { isStreaming: true })).toMatchObject({
+      kind: 'builtin',
+      name: 'plan',
+      args: 'on',
+    });
+    expect(resolve('/mcp', { isStreaming: true })).toMatchObject({
+      kind: 'builtin',
+      name: 'mcp',
+      args: '',
+    });
+    expect(resolve('/mcp', { isCompacting: true })).toMatchObject({
+      kind: 'builtin',
+      name: 'mcp',
+      args: '',
+    });
+  });
+
+  it('blocks plan clear while compacting because it is idle-only', () => {
+    expect(resolve('/plan clear', { isCompacting: true })).toEqual({
+      kind: 'blocked',
+      commandName: 'plan',
+      reason: 'compacting',
+    });
+  });
+
+  it('resolves skill commands and blocks them while busy', () => {
+    const skillCommandMap = new Map([['skill:review', 'review']]);
+
+    expect(resolve('/skill:review src/app.ts', { skillCommandMap })).toEqual({
+      kind: 'skill',
+      commandName: 'skill:review',
+      skillName: 'review',
+      args: 'src/app.ts',
+    });
+    expect(resolve('/skill:review src/app.ts', { skillCommandMap, isStreaming: true })).toEqual({
+      kind: 'blocked',
+      commandName: 'skill:review',
+      reason: 'streaming',
+    });
+  });
+
+  it('returns message for unknown slash input', () => {
+    expect(resolve('/does-not-exist arg')).toEqual({
+      kind: 'message',
+      input: '/does-not-exist arg',
+    });
+  });
+});
+
+describe('slash command busy helpers', () => {
+  it('resolves skill command aliases with and without skill prefix', () => {
+    const map = new Map([['skill:review', 'review']]);
+
+    expect(resolveSkillCommand(map, 'skill:review')).toBe('review');
+    expect(resolveSkillCommand(map, 'review')).toBe('review');
+  });
+
+  it('formats busy messages', () => {
+    expect(slashCommandBusyReason({ isStreaming: true, isCompacting: false })).toBe('streaming');
+    expect(slashCommandBusyReason({ isStreaming: false, isCompacting: true })).toBe('compacting');
+    expect(slashBusyMessage('new', 'streaming')).toContain('Cannot /new while streaming');
+    expect(slashBusyMessage('new', 'compacting')).toContain('Cannot /new while compacting');
+  });
+});
diff --git a/apps/kimi-code/test/tui/commands/skills.test.ts b/apps/kimi-code/test/tui/commands/skills.test.ts
new file mode 100644
index 000000000..81a176813
--- /dev/null
+++ b/apps/kimi-code/test/tui/commands/skills.test.ts
@@ -0,0 +1,57 @@
+import { buildSkillSlashCommands, isUserActivatableSkill } from '#/tui/commands/index';
+import type { SkillSummary } from '@moonshot-ai/kimi-code-sdk';
+import { describe, expect, it } from 'vitest';
+
+function skill(
+  name: string,
+  type?: SkillSummary['type'],
+  extra: Partial<SkillSummary> = {},
+): SkillSummary {
+  return {
+    name,
+    type,
+    description: `${name} skill`,
+    ...extra,
+  } as SkillSummary;
+}
+
+describe('skill slash commands', () => {
+  it('allows user-activatable skill types', () => {
+    expect(isUserActivatableSkill(skill('default'))).toBe(true);
+    expect(isUserActivatableSkill(skill('prompt', 'prompt'))).toBe(true);
+    expect(isUserActivatableSkill(skill('inline', 'inline'))).toBe(true);
+    expect(isUserActivatableSkill(skill('flow', 'flow'))).toBe(true);
+  });
+
+  it('filters non-user-activatable skill types', () => {
+    expect(isUserActivatableSkill(skill('agent', 'agent'))).toBe(false);
+  });
+
+  it('builds slash commands and command map entries with skill prefixes', () => {
+    const built = buildSkillSlashCommands([
+      skill('review', 'prompt'),
+      skill('agent-only', 'agent'),
+      skill('commit', 'flow'),
+    ]);
+
+    expect(built.commands.map((command) => command.name)).toEqual(['skill:review', 'skill:commit']);
+    expect(built.commands[0]).toMatchObject({
+      name: 'skill:review',
+      aliases: [],
+      description: 'review skill',
+    });
+    expect([...built.commandMap.entries()]).toEqual([
+      ['skill:review', 'review'],
+      ['skill:commit', 'commit'],
+    ]);
+  });
+
+  it('keeps disableModelInvocation skills slash-invocable', () => {
+    const built = buildSkillSlashCommands([
+      skill('mcp-config', 'inline', { disableModelInvocation: true, source: 'builtin' }),
+    ]);
+
+    expect(built.commands.map((command) => command.name)).toEqual(['skill:mcp-config']);
+    expect(built.commandMap.get('skill:mcp-config')).toBe('mcp-config');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/chrome/device-code-box.test.ts b/apps/kimi-code/test/tui/components/chrome/device-code-box.test.ts
new file mode 100644
index 000000000..f7cea9b92
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/chrome/device-code-box.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+
+import { DeviceCodeBoxComponent } from '#/tui/components/chrome/device-code-box';
+import { darkColors } from '#/tui/theme/colors';
+
+function strip(text: string): string {
+  return text.replaceAll(/\[[0-9;]*m/g, '');
+}
+
+const url = 'https://www.kimi.com/code/authorize_device?user_code=N32D-W3YD';
+const code = 'N32D-W3YD';
+const title = 'Sign in to Kimi Code';
+const hint = 'Press Ctrl-C to cancel';
+
+describe('DeviceCodeBoxComponent', () => {
+  it('renders a rounded border that frames the title, url and code', () => {
+    const component = new DeviceCodeBoxComponent({
+      title,
+      url,
+      code,
+      hint,
+      colors: darkColors,
+    });
+
+    const lines = component.render(80).map(strip);
+    const joined = lines.join('\n');
+
+    expect(lines[1]?.startsWith('╭')).toBe(true);
+    expect(lines[1]?.endsWith('╮')).toBe(true);
+    expect(lines.at(-2)?.startsWith('╰')).toBe(true);
+    expect(lines.at(-2)?.endsWith('╯')).toBe(true);
+
+    expect(joined).toContain(title);
+    expect(joined).toContain(url);
+    expect(joined).toContain(code);
+    expect(joined).toContain(hint);
+    expect(joined).toContain('Verification code');
+  });
+
+  it('truncates long urls when the terminal is narrow', () => {
+    const component = new DeviceCodeBoxComponent({
+      title,
+      url,
+      code,
+      colors: darkColors,
+    });
+
+    const lines = component.render(40).map(strip);
+    const urlLine = lines.find((line) => line.includes('https://'));
+    expect(urlLine).toBeDefined();
+    expect(urlLine).toContain('…');
+    expect(urlLine?.length).toBeLessThanOrEqual(40);
+  });
+
+  it('omits the hint row when no hint is provided', () => {
+    const component = new DeviceCodeBoxComponent({
+      title,
+      url,
+      code,
+      colors: darkColors,
+    });
+
+    const joined = component.render(80).map(strip).join('\n');
+    expect(joined).not.toContain('Press Ctrl-C');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/chrome/gutter-container.test.ts b/apps/kimi-code/test/tui/components/chrome/gutter-container.test.ts
new file mode 100644
index 000000000..c26e97a17
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/chrome/gutter-container.test.ts
@@ -0,0 +1,57 @@
+import type { Component } from '@earendil-works/pi-tui';
+import { describe, expect, it, vi } from 'vitest';
+
+import { GutterContainer } from '#/tui/components/chrome/gutter-container';
+
+class FakeChild implements Component {
+  constructor(
+    private readonly lines: (innerWidth: number) => string[],
+  ) {}
+  invalidate(): void {}
+  render(width: number): string[] {
+    return this.lines(width);
+  }
+}
+
+describe('GutterContainer', () => {
+  it('prefixes every child line with `left` spaces', () => {
+    const c = new GutterContainer(2, 2);
+    c.addChild(new FakeChild(() => ['hello', 'world']));
+    expect(c.render(20)).toEqual(['  hello', '  world']);
+  });
+
+  it('shrinks the width passed to children by left + right', () => {
+    const seenWidth = vi.fn<(w: number) => string[]>(() => ['x']);
+    const c = new GutterContainer(2, 3);
+    c.addChild(new FakeChild(seenWidth));
+    c.render(20);
+    expect(seenWidth).toHaveBeenCalledWith(15);
+  });
+
+  it('clamps inner width to at least 1 when gutters would otherwise consume it', () => {
+    const seenWidth = vi.fn<(w: number) => string[]>(() => ['x']);
+    const c = new GutterContainer(5, 5);
+    c.addChild(new FakeChild(seenWidth));
+    c.render(2);
+    expect(seenWidth).toHaveBeenCalledWith(1);
+  });
+
+  it('stacks lines from multiple children in order', () => {
+    const c = new GutterContainer(1, 0);
+    c.addChild(new FakeChild(() => ['a1', 'a2']));
+    c.addChild(new FakeChild(() => ['b1']));
+    expect(c.render(10)).toEqual([' a1', ' a2', ' b1']);
+  });
+
+  it('returns an empty array when there are no children', () => {
+    const c = new GutterContainer(2, 2);
+    expect(c.render(20)).toEqual([]);
+  });
+
+  it('preserves ANSI sequences within child lines (only the leading pad is plain)', () => {
+    const colored = 'red';
+    const c = new GutterContainer(2, 2);
+    c.addChild(new FakeChild(() => [colored]));
+    expect(c.render(20)).toEqual([`  ${colored}`]);
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/dialogs/approval-panel.test.ts b/apps/kimi-code/test/tui/components/dialogs/approval-panel.test.ts
new file mode 100644
index 000000000..451c08ba5
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/dialogs/approval-panel.test.ts
@@ -0,0 +1,414 @@
+import { CURSOR_MARKER } from '@earendil-works/pi-tui';
+import { describe, expect, it } from 'vitest';
+
+import { ApprovalPanelComponent } from '#/tui/components/dialogs/approval-panel';
+import type { PendingApproval } from '#/tui/reverse-rpc/types';
+import { getColorPalette } from '#/tui/theme/colors';
+
+import { captureProcessWrite } from '../../../helpers/process';
+
+const COLORS = getColorPalette('dark');
+
+function strip(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+function makePending(): PendingApproval {
+  return {
+    data: {
+      id: 'approval_1',
+      tool_call_id: 'tool_1',
+      tool_name: 'WriteFile',
+      action: 'write a file',
+      description: 'Update README.md',
+      display: [],
+      choices: [
+        { label: 'Approve once', response: 'approved' },
+        { label: 'Approve for this session', response: 'approved_for_session' },
+        { label: 'Reject', response: 'rejected' },
+        { label: 'Reject with feedback', response: 'rejected', requires_feedback: true },
+      ],
+    },
+  };
+}
+
+function makeDialog(): {
+  dialog: ApprovalPanelComponent;
+  responses: Array<{
+    response: string;
+    feedback?: string | undefined;
+    selected_label?: string | undefined;
+  }>;
+} {
+  const responses: Array<{
+    response: string;
+    feedback?: string | undefined;
+    selected_label?: string | undefined;
+  }> = [];
+  const dialog = new ApprovalPanelComponent(
+    makePending(),
+    (response) => responses.push(response),
+    COLORS,
+  );
+  return { dialog, responses };
+}
+
+describe('ApprovalPanelComponent', () => {
+  it('renders only numeric approval shortcuts in the hint', () => {
+    const { dialog } = makeDialog();
+    const out = strip(dialog.render(80).join('\n'));
+    expect(out).toContain('1/2/3/4 choose');
+    expect(out).not.toContain('y/a/n/f');
+  });
+
+  it('renders dangerous shell warnings with simple copy and no icon', () => {
+    const pending: PendingApproval = {
+      data: {
+        id: 'approval_danger',
+        tool_call_id: 'tool_danger',
+        tool_name: 'Bash',
+        action: 'run',
+        description: '',
+        display: [
+          {
+            type: 'shell',
+            language: 'bash',
+            command: 'rm -rf /tmp/cache',
+            danger: 'recursive delete',
+          },
+        ],
+        choices: [{ label: 'Approve once', response: 'approved' }],
+      },
+    };
+    const dialog = new ApprovalPanelComponent(pending, () => {}, COLORS);
+
+    const out = strip(dialog.render(80).join('\n'));
+    expect(out).toContain('Dangerous: recursive delete');
+    expect(out).not.toContain('potentially destructive');
+    expect(out).not.toContain('⚠');
+  });
+
+  it('numeric shortcuts still drive approval actions', () => {
+    const { dialog, responses } = makeDialog();
+    dialog.handleInput('2');
+    expect(responses).toEqual([{ response: 'approved_for_session', feedback: undefined }]);
+  });
+
+  it('shortcut 4 enters feedback mode and submits the typed feedback', () => {
+    const { dialog, responses } = makeDialog();
+    dialog.handleInput('4');
+    dialog.handleInput('n');
+    dialog.handleInput('o');
+    dialog.handleInput('\r');
+    expect(responses).toEqual([{ response: 'rejected', feedback: 'no' }]);
+  });
+
+  it('renders feedback input inline with the selected choice', () => {
+    const { dialog } = makeDialog();
+    dialog.handleInput('4');
+
+    const out = strip(dialog.render(80).join('\n'));
+    expect(out).toContain('▶ 4. Reject with feedback');
+    expect(out).not.toContain('\n  > ');
+  });
+
+  it('legacy y/a/n/f shortcuts no longer trigger approval actions', () => {
+    for (const key of ['y', 'a', 'n', 'f']) {
+      const { dialog, responses } = makeDialog();
+      dialog.handleInput(key);
+      expect(responses).toEqual([]);
+    }
+  });
+
+  it('feedback input supports left/right cursor editing', () => {
+    const { dialog, responses } = makeDialog();
+    dialog.handleInput('4');
+    dialog.handleInput('n');
+    dialog.handleInput('o');
+    dialog.handleInput('\u001B[D');
+    dialog.handleInput('!');
+    dialog.handleInput('\r');
+    expect(responses).toEqual([{ response: 'rejected', feedback: 'n!o' }]);
+  });
+
+  it('feedback input keeps editor shortcuts like ctrl+b / ctrl+f', () => {
+    const { dialog, responses } = makeDialog();
+    dialog.handleInput('4');
+    dialog.handleInput('a');
+    dialog.handleInput('b');
+    dialog.handleInput('c');
+    dialog.handleInput('\u0002');
+    dialog.handleInput('\u0002');
+    dialog.handleInput('X');
+    dialog.handleInput('\u0006');
+    dialog.handleInput('Y');
+    dialog.handleInput('\r');
+    expect(responses).toEqual([{ response: 'rejected', feedback: 'aXbYc' }]);
+  });
+
+  it('renders an IME cursor marker while editing feedback', () => {
+    const { dialog } = makeDialog();
+    dialog.focused = true;
+    dialog.handleInput('4');
+
+    const out = dialog.render(80).join('\n');
+    expect(out).toContain(CURSOR_MARKER);
+  });
+
+  it.each(['\u0003', '\u0004', '\u001B'])(
+    'shortcut %j rejects approval immediately',
+    (key) => {
+      const { dialog, responses } = makeDialog();
+      dialog.handleInput(key);
+      expect(responses).toEqual([{ response: 'rejected' }]);
+    },
+  );
+
+  it('renders ExitPlanMode with plan-specific header and plan-review choices', () => {
+    const pending: PendingApproval = {
+      data: {
+        id: 'approval_plan',
+        tool_call_id: 'tool_plan',
+        tool_name: 'ExitPlanMode',
+        action: 'review plan',
+        description: '',
+        display: [],
+        choices: [
+          { label: 'Approve', response: 'approved' },
+          { label: 'Reject', response: 'rejected' },
+          { label: 'Revise', response: 'rejected', requires_feedback: true },
+        ],
+      },
+    };
+    const dialog = new ApprovalPanelComponent(pending, () => {}, COLORS);
+
+    const out = strip(dialog.render(80).join('\n'));
+    expect(out).toContain('Ready to build with this plan?');
+    expect(out).not.toContain('Approve ExitPlanMode?');
+    expect(out).toContain('Approve');
+    expect(out).toContain('Reject');
+    expect(out).toContain('Revise');
+    expect(out).not.toContain('Approve for this session');
+    expect(out).not.toContain('Investigate');
+  });
+
+  it('renders an Edit diff collapsed by default and expands on ctrl+e', () => {
+    const responses: Array<{ response: string }> = [];
+    const oldLines: string[] = [];
+    const newLines: string[] = [];
+    for (let i = 1; i <= 30; i++) {
+      oldLines.push(`old${String(i)}`);
+      newLines.push(`new${String(i)}`);
+    }
+    const pending: PendingApproval = {
+      data: {
+        id: 'approval_diff',
+        tool_call_id: 'tool_diff',
+        tool_name: 'Edit',
+        action: 'edit',
+        description: '',
+        display: [
+          {
+            type: 'diff',
+            path: 'src/foo.ts',
+            old_text: oldLines.join('\n'),
+            new_text: newLines.join('\n'),
+          },
+        ],
+        choices: [{ label: 'Approve once', response: 'approved' }],
+      },
+    };
+    let globalToggleCalls = 0;
+    const dialog = new ApprovalPanelComponent(
+      pending,
+      (r) => responses.push(r),
+      COLORS,
+      () => globalToggleCalls++,
+    );
+
+    const collapsed = strip(dialog.render(120).join('\n'));
+    expect(collapsed).not.toMatch(/\bedit\s+src\/foo\.ts\b/);
+    expect(collapsed).toContain('+30');
+    expect(collapsed).toContain('-30');
+    expect(collapsed).toContain('ctrl+e expand');
+    expect(collapsed).toContain('ctrl+e to expand');
+    expect(collapsed).toMatch(/old\d+|new\d+/);
+    expect(collapsed).not.toContain('new30');
+
+    dialog.handleInput('\u0005'); // Ctrl+E — local toggle, no global callback.
+
+    const expanded = strip(dialog.render(120).join('\n'));
+    expect(expanded).toContain('new30');
+    expect(expanded).toContain('ctrl+e collapse');
+    expect(expanded).not.toContain('more changes hidden');
+    expect(globalToggleCalls).toBe(0);
+    expect(responses).toEqual([]);
+  });
+
+  it('forwards ctrl+o to the global tool-output toggle without changing local expansion', () => {
+    const pending: PendingApproval = {
+      data: {
+        id: 'approval_forward',
+        tool_call_id: 'tool_forward',
+        tool_name: 'Edit',
+        action: 'edit',
+        description: '',
+        display: [
+          {
+            type: 'diff',
+            path: 'src/foo.ts',
+            old_text: Array.from({ length: 30 }, (_, i) => `old${String(i + 1)}`).join('\n'),
+            new_text: Array.from({ length: 30 }, (_, i) => `new${String(i + 1)}`).join('\n'),
+          },
+        ],
+        choices: [{ label: 'Approve once', response: 'approved' }],
+      },
+    };
+    let globalToggleCalls = 0;
+    const dialog = new ApprovalPanelComponent(pending, () => {}, COLORS, () => globalToggleCalls++);
+
+    dialog.handleInput('\u000F'); // Ctrl+O — forwarded; local stays collapsed.
+
+    const after = strip(dialog.render(120).join('\n'));
+    expect(globalToggleCalls).toBe(1);
+    expect(after).toContain('ctrl+e expand');
+    expect(after).not.toContain('new30');
+  });
+
+  it('also forwards ctrl+e to the global plan-expand toggle while toggling local content', () => {
+    const pending: PendingApproval = {
+      data: {
+        id: 'approval_plan_forward',
+        tool_call_id: 'tool_plan_forward',
+        tool_name: 'Edit',
+        action: 'edit',
+        description: '',
+        display: [
+          {
+            type: 'diff',
+            path: 'src/foo.ts',
+            old_text: Array.from({ length: 30 }, (_, i) => `old${String(i + 1)}`).join('\n'),
+            new_text: Array.from({ length: 30 }, (_, i) => `new${String(i + 1)}`).join('\n'),
+          },
+        ],
+        choices: [{ label: 'Approve once', response: 'approved' }],
+      },
+    };
+    let planToggles = 0;
+    const dialog = new ApprovalPanelComponent(
+      pending,
+      () => {},
+      COLORS,
+      undefined,
+      () => planToggles++,
+    );
+
+    dialog.handleInput('\u0005'); // Ctrl+E
+    const out = strip(dialog.render(120).join('\n'));
+    expect(planToggles).toBe(1);
+    expect(out).toContain('ctrl+e collapse'); // local also expanded
+    expect(out).toContain('new30');
+  });
+
+  it('renders Write as a syntax-highlighted code block (file_content), not a diff', () => {
+    const responses: Array<{ response: string }> = [];
+    const lines: string[] = [];
+    for (let i = 1; i <= 30; i++) lines.push(`const x${String(i)} = ${String(i)};`);
+    const pending: PendingApproval = {
+      data: {
+        id: 'approval_write',
+        tool_call_id: 'tool_write',
+        tool_name: 'Write',
+        action: 'write',
+        description: '',
+        display: [{ type: 'file_content', path: 'src/new.ts', content: lines.join('\n') }],
+        choices: [{ label: 'Approve once', response: 'approved' }],
+      },
+    };
+    const dialog = new ApprovalPanelComponent(pending, (r) => responses.push(r), COLORS);
+
+    const collapsed = strip(dialog.render(120).join('\n'));
+    // No diff markers, no +N -M header.
+    expect(collapsed).not.toMatch(/^\s*\+\d+/m);
+    expect(collapsed).not.toMatch(/^\s*-\d+/m);
+    expect(collapsed).toContain('src/new.ts');
+    expect(collapsed).toContain('const x1 = 1;');
+    expect(collapsed).toContain('const x10 = 10;');
+    expect(collapsed).not.toContain('const x25 = 25;');
+    expect(collapsed).toContain('20 more lines hidden (ctrl+e to expand)');
+    expect(collapsed).toContain('ctrl+e expand');
+
+    dialog.handleInput('\u0005'); // Ctrl+E
+    const expanded = strip(dialog.render(120).join('\n'));
+    expect(expanded).toContain('const x30 = 30;');
+    expect(expanded).not.toContain('more lines hidden');
+    expect(responses).toEqual([]);
+  });
+
+  it('renders unknown file_content extensions as plain text without stderr noise', () => {
+    const pending: PendingApproval = {
+      data: {
+        id: 'approval_unknown_write',
+        tool_call_id: 'tool_unknown_write',
+        tool_name: 'Write',
+        action: 'write',
+        description: '',
+        display: [{ type: 'file_content', path: 'demo.abcxyz', content: 'hello\nworld' }],
+        choices: [{ label: 'Approve once', response: 'approved' }],
+      },
+    };
+    const stderr = captureProcessWrite('stderr');
+    try {
+      const dialog = new ApprovalPanelComponent(pending, () => {}, COLORS);
+      const collapsed = strip(dialog.render(120).join('\n'));
+      expect(collapsed).toContain('hello');
+
+      dialog.handleInput('\u0005'); // Ctrl+E
+      const expanded = strip(dialog.render(120).join('\n'));
+      expect(expanded).toContain('world');
+      expect(stderr.text()).not.toContain('Could not find the language');
+    } finally {
+      stderr.restore();
+    }
+  });
+
+  it('returns feedback for plan-review revise choice', () => {
+    const responses: Array<{
+      response: string;
+      feedback?: string | undefined;
+      selected_label?: string | undefined;
+    }> = [];
+    const pending: PendingApproval = {
+      data: {
+        id: 'approval_plan',
+        tool_call_id: 'tool_plan',
+        tool_name: 'ExitPlanMode',
+        action: 'review plan',
+        description: '',
+        display: [],
+        choices: [
+          { label: 'Approve', response: 'approved' },
+          {
+            label: 'Revise',
+            response: 'rejected',
+            selected_label: 'Revise',
+            requires_feedback: true,
+          },
+        ],
+      },
+    };
+    const dialog = new ApprovalPanelComponent(
+      pending,
+      (response) => responses.push(response),
+      COLORS,
+    );
+
+    dialog.handleInput('2');
+    dialog.handleInput('n');
+    dialog.handleInput('o');
+    dialog.handleInput('\r');
+    expect(responses).toEqual([
+      { response: 'rejected', feedback: 'no', selected_label: 'Revise' },
+    ]);
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/dialogs/choice-picker.test.ts b/apps/kimi-code/test/tui/components/dialogs/choice-picker.test.ts
new file mode 100644
index 000000000..9f6d453c1
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/dialogs/choice-picker.test.ts
@@ -0,0 +1,202 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { ChoicePickerComponent } from '#/tui/components/dialogs/choice-picker';
+import { EditorSelectorComponent } from '#/tui/components/dialogs/editor-selector';
+import { ModelSelectorComponent } from '#/tui/components/dialogs/model-selector';
+import { PermissionSelectorComponent } from '#/tui/components/dialogs/permission-selector';
+import { SettingsSelectorComponent } from '#/tui/components/dialogs/settings-selector';
+import { ThemeSelectorComponent } from '#/tui/components/dialogs/theme-selector';
+import { darkColors } from '#/tui/theme/colors';
+
+const ANSI_SGR = /\u001B\[[0-9;]*m/g;
+
+function strip(text: string): string {
+  return text.replaceAll(ANSI_SGR, '');
+}
+
+describe('ChoicePickerComponent', () => {
+  it('renders optional descriptions below choice labels', () => {
+    const picker = new ChoicePickerComponent({
+      title: 'Select permission mode',
+      options: [
+        {
+          value: 'manual',
+          label: 'Manual',
+          description: 'Ask before commands, edits, and other risky actions.',
+        },
+        {
+          value: 'auto',
+          label: 'Auto',
+          description: 'Automatically approve tool actions and plan transitions.',
+        },
+      ],
+      currentValue: 'manual',
+      colors: darkColors,
+      onSelect: vi.fn(),
+      onCancel: vi.fn(),
+    });
+
+    const out = picker.render(120).map(strip);
+
+    expect(out).toContain('  ❯ Manual ← current');
+    expect(out).toContain('    Ask before commands, edits, and other risky actions.');
+    expect(out).toContain('    Automatically approve tool actions and plan transitions.');
+  });
+
+  it('renders domain selector wrappers with their configured options', () => {
+    const onSelect = vi.fn();
+    const onCancel = vi.fn();
+
+    const editor = new EditorSelectorComponent({
+      currentValue: 'vim',
+      colors: darkColors,
+      onSelect,
+      onCancel,
+    });
+    expect(editor.render(120).map(strip)).toContain('  ❯ Vim ← current');
+
+    const model = new ModelSelectorComponent({
+      models: {
+        kimi: {
+          provider: 'managed:kimi-code',
+          model: 'kimi-k2',
+          maxContextSize: 200_000,
+          displayName: 'Kimi K2',
+          capabilities: ['thinking'],
+        },
+      },
+      currentValue: 'kimi',
+      currentThinking: true,
+      colors: darkColors,
+      onSelect,
+      onCancel,
+    });
+    const modelOutput = model.render(120).map(strip);
+    expect(modelOutput).toContain('  ❯ Kimi K2 (Kimi Code) ← current');
+    expect(modelOutput).toContain(' Thinking');
+    expect(modelOutput).toContain('  [ On ]    Off  ');
+
+    const theme = new ThemeSelectorComponent({
+      currentValue: 'light',
+      colors: darkColors,
+      onSelect,
+      onCancel,
+    });
+    expect(theme.render(120).map(strip)).toContain('  ❯ Light ← current');
+
+    const permission = new PermissionSelectorComponent({
+      currentValue: 'manual',
+      colors: darkColors,
+      onSelect,
+      onCancel,
+    });
+    expect(permission.render(120).map(strip)).toContain('  ❯ Manual ← current');
+
+    const settings = new SettingsSelectorComponent({
+      colors: darkColors,
+      onSelect,
+      onCancel,
+    });
+    const settingsOutput = settings.render(120).map(strip);
+    expect(settingsOutput).toContain('  ❯ Model');
+    expect(settingsOutput).toContain('    Switch the active model and thinking mode.');
+  });
+
+  it('submits the selected model and inline thinking state', () => {
+    const onSelect = vi.fn();
+    const picker = new ModelSelectorComponent({
+      models: {
+        kimi: {
+          provider: 'managed:kimi-code',
+          model: 'kimi-k2',
+          maxContextSize: 200_000,
+          displayName: 'Kimi K2',
+          capabilities: ['thinking'],
+        },
+      },
+      currentValue: 'kimi',
+      currentThinking: true,
+      colors: darkColors,
+      onSelect,
+      onCancel: vi.fn(),
+    });
+
+    picker.handleInput('\u001B[C');
+    picker.handleInput('\r');
+
+    expect(onSelect).toHaveBeenCalledWith({ alias: 'kimi', thinking: false });
+  });
+
+  it('forces always-thinking models on and unsupported models off', () => {
+    const onSelect = vi.fn();
+    const picker = new ModelSelectorComponent({
+      models: {
+        always: {
+          provider: 'managed:kimi-code',
+          model: 'kimi-thinking',
+          maxContextSize: 200_000,
+          displayName: 'Kimi Thinking',
+          capabilities: ['always_thinking'],
+        },
+        plain: {
+          provider: 'managed:kimi-code',
+          model: 'kimi-plain',
+          maxContextSize: 200_000,
+          displayName: 'Kimi Plain',
+          capabilities: ['tool_use'],
+        },
+      },
+      currentValue: 'always',
+      currentThinking: false,
+      colors: darkColors,
+      onSelect,
+      onCancel: vi.fn(),
+    });
+
+    expect(picker.render(120).map(strip)).toContain('  [ Always on ]');
+    picker.handleInput('\u001B[C');
+    picker.handleInput('\r');
+    expect(onSelect).toHaveBeenLastCalledWith({ alias: 'always', thinking: true });
+
+    picker.handleInput('\u001B[B');
+    expect(picker.render(120).map(strip)).toContain('  [ Off ] unsupported');
+    picker.handleInput('\u001B[D');
+    picker.handleInput('\r');
+    expect(onSelect).toHaveBeenLastCalledWith({ alias: 'plain', thinking: false });
+  });
+
+  it('keeps the thinking draft when moving across models', () => {
+    const onSelect = vi.fn();
+    const picker = new ModelSelectorComponent({
+      models: {
+        plain: {
+          provider: 'managed:kimi-code',
+          model: 'kimi-plain',
+          maxContextSize: 200_000,
+          displayName: 'Kimi Plain',
+          capabilities: ['tool_use'],
+        },
+        thinking: {
+          provider: 'managed:kimi-code',
+          model: 'kimi-thinking',
+          maxContextSize: 200_000,
+          displayName: 'Kimi Thinking',
+          capabilities: ['thinking'],
+        },
+      },
+      currentValue: 'plain',
+      currentThinking: false,
+      colors: darkColors,
+      onSelect,
+      onCancel: vi.fn(),
+    });
+
+    picker.handleInput('\u001B[B');
+    picker.handleInput('\u001B[D');
+    picker.handleInput('\u001B[A');
+    picker.handleInput('\u001B[B');
+    picker.handleInput('\r');
+
+    expect(onSelect).toHaveBeenCalledWith({ alias: 'thinking', thinking: true });
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/dialogs/compaction.test.ts b/apps/kimi-code/test/tui/components/dialogs/compaction.test.ts
new file mode 100644
index 000000000..b49501978
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/dialogs/compaction.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+
+import { CompactionComponent } from '#/tui/components/dialogs/compaction';
+import { darkColors } from '#/tui/theme/colors';
+
+function strip(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+describe('CompactionComponent', () => {
+  it('renders the custom instruction below the compacting label', () => {
+    const component = new CompactionComponent(darkColors, undefined, 'keep the recent files only');
+
+    try {
+      const lines = component.render(120).map(strip);
+      const text = lines.join('\n');
+
+      expect(text).toContain('Compacting context...');
+      expect(text).toContain('  keep the recent files only');
+    } finally {
+      component.dispose();
+    }
+  });
+
+  it('renders a cancelled terminal state', () => {
+    const component = new CompactionComponent(darkColors);
+
+    try {
+      component.markCanceled();
+      const lines = component.render(120).map(strip);
+      const text = lines.join('\n');
+
+      expect(text).toContain('Compaction cancelled');
+      expect(text).not.toContain('Compacting context...');
+    } finally {
+      component.dispose();
+    }
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/dialogs/feedback-input-dialog.test.ts b/apps/kimi-code/test/tui/components/dialogs/feedback-input-dialog.test.ts
new file mode 100644
index 000000000..13fcdd589
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/dialogs/feedback-input-dialog.test.ts
@@ -0,0 +1,108 @@
+import chalk from 'chalk';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import {
+  FeedbackInputDialogComponent,
+  type FeedbackInputDialogResult,
+} from '#/tui/components/dialogs/feedback-input-dialog';
+import { darkColors } from '#/tui/theme/colors';
+
+const ESC = String.fromCodePoint(27);
+const CTRL_C = String.fromCodePoint(3);
+const ANSI_RE = new RegExp(`${ESC}\\[[0-9;]*m`, 'g');
+
+function strip(text: string): string {
+  return text.replaceAll(ANSI_RE, '');
+}
+
+beforeAll(() => {
+  chalk.level = 3;
+});
+
+function makeDialog(): {
+  dialog: FeedbackInputDialogComponent;
+  collected: FeedbackInputDialogResult[];
+} {
+  const collected: FeedbackInputDialogResult[] = [];
+  const dialog = new FeedbackInputDialogComponent((result) => {
+    collected.push(result);
+  }, darkColors);
+  dialog.focused = true;
+  return { dialog, collected };
+}
+
+describe('FeedbackInputDialogComponent', () => {
+  it('renders a blue rounded box with title, subtitle, and footer', () => {
+    const { dialog } = makeDialog();
+    const text = strip(dialog.render(60).join('\n'));
+
+    expect(text).toContain('╭');
+    expect(text).toContain('╮');
+    expect(text).toContain('╰');
+    expect(text).toContain('╯');
+    expect(text).toContain('Send feedback to Kimi Code');
+    expect(text).toContain("Tell us what's working or what's not.");
+    expect(text).toContain('Enter to submit');
+    expect(text).toContain('Esc to cancel');
+  });
+
+  it('uses the primary color for the border', () => {
+    const { dialog } = makeDialog();
+    const rendered = dialog.render(60).join('\n');
+    const sample = chalk.hex(darkColors.primary)('x');
+    const ansiOpen = sample.split('x')[0]!;
+    expect(rendered).toContain(`${ansiOpen}╭`);
+    expect(rendered).toContain(`${ansiOpen}╰`);
+  });
+
+  it('typing then pressing Enter submits the trimmed value', () => {
+    const { dialog, collected } = makeDialog();
+    for (const ch of 'hello world ') {
+      dialog.handleInput(ch);
+    }
+    dialog.handleInput('\r');
+    expect(collected).toEqual([{ kind: 'ok', value: 'hello world' }]);
+  });
+
+  it('Enter on an empty input does not submit and shows an inline empty hint', () => {
+    const { dialog, collected } = makeDialog();
+    dialog.handleInput('\r');
+    expect(collected).toEqual([]);
+    const text = strip(dialog.render(60).join('\n'));
+    expect(text).toContain('Feedback cannot be empty.');
+    expect(text).not.toContain("Tell us what's working or what's not.");
+  });
+
+  it('typing again after the empty hint clears the hint', () => {
+    const { dialog, collected } = makeDialog();
+    dialog.handleInput('\r');
+    expect(strip(dialog.render(60).join('\n'))).toContain('Feedback cannot be empty.');
+    dialog.handleInput('a');
+    const text = strip(dialog.render(60).join('\n'));
+    expect(text).toContain("Tell us what's working or what's not.");
+    expect(text).not.toContain('Feedback cannot be empty.');
+    expect(collected).toEqual([]);
+  });
+
+  it('Esc cancels the dialog', () => {
+    const { dialog, collected } = makeDialog();
+    dialog.handleInput(ESC);
+    expect(collected).toEqual([{ kind: 'cancel' }]);
+  });
+
+  it('Ctrl-C cancels the dialog', () => {
+    const { dialog, collected } = makeDialog();
+    dialog.handleInput(CTRL_C);
+    expect(collected).toEqual([{ kind: 'cancel' }]);
+  });
+
+  it('does not fire onDone twice', () => {
+    const { dialog, collected } = makeDialog();
+    dialog.handleInput('h');
+    dialog.handleInput('i');
+    dialog.handleInput('\r');
+    dialog.handleInput('\r');
+    dialog.handleInput(ESC);
+    expect(collected).toEqual([{ kind: 'ok', value: 'hi' }]);
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/dialogs/question-dialog.test.ts b/apps/kimi-code/test/tui/components/dialogs/question-dialog.test.ts
new file mode 100644
index 000000000..6a492f406
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/dialogs/question-dialog.test.ts
@@ -0,0 +1,439 @@
+import { CURSOR_MARKER } from '@earendil-works/pi-tui';
+import chalk from 'chalk';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { QuestionDialogComponent } from '#/tui/components/dialogs/question-dialog';
+import type { PendingQuestion } from '#/tui/reverse-rpc/types';
+import { darkColors } from '#/tui/theme/colors';
+
+function strip(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+beforeAll(() => {
+  chalk.level = 3;
+});
+
+function makePending(
+  questions: PendingQuestion['data']['questions'],
+  requestId = 'q_1',
+): PendingQuestion {
+  return {
+    data: {
+      id: requestId,
+      tool_call_id: 'tc_1',
+      questions,
+    },
+  };
+}
+
+function makeDialog(
+  pending: PendingQuestion,
+  onToggleToolOutput?: () => void,
+  onTogglePlanExpand?: () => void,
+): {
+  dialog: QuestionDialogComponent;
+  collected: string[][];
+  methods: Array<string | undefined>;
+} {
+  const collected: string[][] = [];
+  const methods: Array<string | undefined> = [];
+  const dialog = new QuestionDialogComponent(
+    pending,
+    (response) => {
+      collected.push(response.answers);
+      methods.push(response.method);
+    },
+    darkColors,
+    6,
+    onToggleToolOutput,
+    onTogglePlanExpand,
+  );
+  return { dialog, collected, methods };
+}
+
+describe('QuestionDialogComponent', () => {
+  it('single-select answers auto-advance and only submit from the review tab', () => {
+    const pending = makePending([
+      {
+        question: 'Q1?',
+        multi_select: false,
+        options: [{ label: 'A1' }, { label: 'B1' }],
+      },
+      {
+        question: 'Q2?',
+        multi_select: false,
+        options: [{ label: 'A2' }, { label: 'B2' }],
+      },
+    ]);
+    const { dialog, collected, methods } = makeDialog(pending);
+
+    dialog.handleInput('2');
+    expect(collected).toEqual([]);
+    expect(strip(dialog.render(80).join('\n'))).toMatch(/Q2\?/);
+
+    dialog.handleInput('\r');
+    expect(collected).toEqual([]);
+
+    const reviewRaw = dialog.render(80).join('\n');
+    const review = strip(reviewRaw);
+    expect(review).toContain('Review your answer before submit');
+    expect(review).toContain('Ready to submit your answers?');
+    expect(review).not.toContain('? Ready to submit your answers?');
+    expect(review).not.toContain('Please answer all questions before submitting.');
+    expect(reviewRaw).toContain(
+      chalk.hex(darkColors.text).bold(' Review your answer before submit'),
+    );
+    expect(reviewRaw).toContain(chalk.hex(darkColors.text)(' Ready to submit your answers?'));
+    expect(review).toContain('B1');
+    expect(review).toContain('A2');
+
+    dialog.handleInput('1');
+    expect(collected).toEqual([['B1', 'A2']]);
+    expect(methods).toEqual(['enter']);
+  });
+
+  it('last single-select question goes straight to review instead of wrapping back', () => {
+    const pending = makePending([
+      {
+        question: 'Q1?',
+        multi_select: false,
+        options: [{ label: 'A1' }, { label: 'B1' }],
+      },
+      {
+        question: 'Q2?',
+        multi_select: false,
+        options: [{ label: 'A2' }, { label: 'B2' }],
+      },
+    ]);
+    const { dialog, collected } = makeDialog(pending);
+
+    dialog.handleInput('\t');
+    dialog.handleInput('2');
+
+    const review = strip(dialog.render(80).join('\n'));
+    expect(review).toContain('Review your answer before submit');
+    expect(review).toContain('Some questions are still unanswered.');
+    expect(review).toContain('B2');
+    expect(review).toContain('Not answered');
+    expect(collected).toEqual([]);
+  });
+
+  it('renders optional body text above options', () => {
+    const pending = makePending([
+      {
+        question: 'Approve this plan?',
+        body: '# Plan\n\n1. Make the focused change.',
+        multi_select: false,
+        options: [{ label: 'Approve' }, { label: 'Reject' }],
+      },
+    ]);
+    const { dialog } = makeDialog(pending);
+    const out = strip(dialog.render(80).join('\n'));
+    expect(out).toContain('# Plan');
+    expect(out).toContain('1. Make the focused change.');
+    expect(out).toContain('Approve');
+    expect(out).toContain('Other');
+  });
+
+  it('multi-select uses space and number keys to toggle choices', () => {
+    const pending = makePending([
+      {
+        question: 'Pick many?',
+        multi_select: true,
+        options: [{ label: 'A' }, { label: 'B' }, { label: 'C' }],
+      },
+    ]);
+    const { dialog, collected } = makeDialog(pending);
+
+    dialog.handleInput(' ');
+    dialog.handleInput('\u001B[B');
+    dialog.handleInput('\u001B[B');
+    dialog.handleInput('3');
+    dialog.handleInput('\t');
+
+    const review = strip(dialog.render(80).join('\n'));
+    expect(review).toContain('A, C');
+    expect(review).not.toContain('Not answered');
+    expect(collected).toEqual([]);
+  });
+
+  it('review shows an unanswered warning and still allows submit', () => {
+    const pending = makePending([
+      {
+        question: 'Q1?',
+        multi_select: false,
+        options: [{ label: 'A1' }, { label: 'B1' }],
+      },
+      {
+        question: 'Q2?',
+        multi_select: false,
+        options: [{ label: 'A2' }, { label: 'B2' }],
+      },
+    ]);
+    const { dialog, collected } = makeDialog(pending);
+
+    dialog.handleInput('\t');
+    dialog.handleInput('2');
+
+    const before = strip(dialog.render(80).join('\n'));
+    expect(before).toContain('Not answered');
+    expect(before).toContain('Some questions are still unanswered.');
+
+    dialog.handleInput('\r');
+    expect(collected).toHaveLength(1);
+    expect(collected[0]?.[0]).toBeUndefined();
+    expect(collected[0]?.[1]).toBe('B2');
+  });
+
+  it('review cancel dismisses the whole request', () => {
+    const pending = makePending([
+      {
+        question: 'Pick one?',
+        multi_select: false,
+        options: [{ label: 'A' }, { label: 'B' }],
+      },
+    ]);
+    const { dialog, collected } = makeDialog(pending);
+
+    dialog.handleInput('\t');
+    dialog.handleInput('2');
+
+    expect(collected).toEqual([[]]);
+  });
+
+  it('single-select Other input is inline and auto-advances after commit', () => {
+    const pending = makePending([
+      {
+        question: 'Pick one?',
+        multi_select: false,
+        other_label: 'Custom',
+        other_description: 'Type your own answer',
+        options: [{ label: 'A' }, { label: 'B' }],
+      },
+    ]);
+    const { dialog, collected, methods } = makeDialog(pending);
+
+    dialog.handleInput('3');
+    let out = strip(dialog.render(80).join('\n'));
+    expect(out).toContain('→ [3] Custom:');
+    expect(out).not.toContain('Type your own answer');
+
+    dialog.handleInput('H');
+    dialog.handleInput('i');
+    dialog.handleInput('\r');
+
+    out = strip(dialog.render(80).join('\n'));
+    expect(out).toContain('Review your answer before submit');
+    expect(out).toContain('Ready to submit your answers?');
+    expect(out).not.toContain('? Ready to submit your answers?');
+    expect(out).toContain('Hi');
+
+    dialog.handleInput('1');
+    expect(collected).toEqual([['Hi']]);
+    expect(methods).toEqual(['enter']);
+  });
+
+  it('Other input supports left/right cursor editing before commit', () => {
+    const pending = makePending([
+      {
+        question: 'Pick one?',
+        multi_select: false,
+        other_label: 'Custom',
+        options: [{ label: 'A' }, { label: 'B' }],
+      },
+    ]);
+    const { dialog } = makeDialog(pending);
+
+    dialog.handleInput('3');
+    dialog.handleInput('H');
+    dialog.handleInput('i');
+    dialog.handleInput('\u001B[D');
+    dialog.handleInput('!');
+    dialog.handleInput('\r');
+
+    const out = strip(dialog.render(80).join('\n'));
+    expect(out).toContain('H!i');
+    expect(out).toContain('Review your answer before submit');
+  });
+
+  it('renders an IME cursor marker while editing Other when focused', () => {
+    const pending = makePending([
+      {
+        question: 'Pick one?',
+        multi_select: false,
+        other_label: 'Custom',
+        options: [{ label: 'A' }, { label: 'B' }],
+      },
+    ]);
+    const { dialog } = makeDialog(pending);
+
+    dialog.focused = true;
+    dialog.handleInput('3');
+
+    const out = dialog.render(80).join('\n');
+    expect(out).toContain(CURSOR_MARKER);
+  });
+
+  it('keeps selected options green even when the cursor returns to them', () => {
+    const pending = makePending([
+      {
+        question: 'Pick one?',
+        multi_select: false,
+        options: [{ label: 'A' }, { label: 'B' }],
+      },
+    ]);
+    const { dialog } = makeDialog(pending);
+
+    dialog.handleInput('\r');
+    dialog.handleInput('\u001B[D');
+
+    const out = dialog.render(80).join('\n');
+    expect(out).toContain(chalk.hex(darkColors.success).bold('  → [1] A'));
+    expect(out).not.toContain(chalk.hex(darkColors.primary)('  → [1] A'));
+  });
+
+  it('stretches the border to the full available width', () => {
+    const pending = makePending([
+      {
+        question: 'Pick one?',
+        multi_select: false,
+        options: [{ label: 'A' }, { label: 'B' }],
+      },
+    ]);
+    const { dialog } = makeDialog(pending);
+
+    const lines = dialog.render(80);
+    expect(strip(lines[0] ?? '')).toHaveLength(80);
+    expect(strip(lines.at(-1) ?? '')).toHaveLength(80);
+  });
+
+  it('does not show the submit tab as completed when all questions are answered', () => {
+    const pending = makePending([
+      {
+        question: 'Q1?',
+        multi_select: false,
+        options: [{ label: 'A1' }, { label: 'B1' }],
+      },
+      {
+        question: 'Q2?',
+        multi_select: false,
+        options: [{ label: 'A2' }, { label: 'B2' }],
+      },
+    ]);
+    const { dialog } = makeDialog(pending);
+
+    dialog.handleInput('\r');
+    dialog.handleInput('\r');
+
+    const out = strip(dialog.render(80).join('\n'));
+    expect(out).toContain(' Submit ');
+    expect(out).not.toContain('(✓) Submit');
+    expect(out).not.toContain('(○) Submit');
+  });
+
+  it('renders the active tab with a highlighted background instead of the circle marker', () => {
+    const pending = makePending([
+      {
+        question: 'Q1?',
+        header: 'First',
+        multi_select: false,
+        options: [{ label: 'A1' }, { label: 'B1' }],
+      },
+      {
+        question: 'Q2?',
+        header: 'Second',
+        multi_select: false,
+        options: [{ label: 'A2' }, { label: 'B2' }],
+      },
+    ]);
+    const { dialog } = makeDialog(pending);
+
+    const out = dialog.render(80).join('\n');
+    expect(out).toContain(chalk.bgHex(darkColors.primary).hex(darkColors.text).bold(' First '));
+    expect(out).not.toContain('(●) First');
+  });
+
+  it('preserves Other drafts across tabs and question navigation', () => {
+    const pending = makePending([
+      {
+        question: 'Pick toppings?',
+        multi_select: true,
+        options: [{ label: 'Cheese' }, { label: 'Pepperoni' }],
+      },
+    ]);
+    const { dialog } = makeDialog(pending);
+
+    dialog.handleInput('3');
+    dialog.handleInput('M');
+    dialog.handleInput('u');
+    dialog.handleInput('s');
+    dialog.handleInput('h');
+    dialog.handleInput('r');
+    dialog.handleInput('o');
+    dialog.handleInput('o');
+    dialog.handleInput('m');
+    dialog.handleInput('\t');
+
+    let out = strip(dialog.render(80).join('\n'));
+    expect(out).toContain('Not answered');
+
+    dialog.handleInput('\u001B[D');
+    out = strip(dialog.render(80).join('\n'));
+    expect(out).toContain('Other: Mushroom');
+
+    dialog.handleInput('\r');
+    dialog.handleInput('\r');
+    dialog.handleInput('\t');
+    out = strip(dialog.render(80).join('\n'));
+    expect(out).toContain('Mushroom');
+  });
+
+  it('escape dismisses with empty answers array', () => {
+    const pending = makePending([
+      {
+        question: 'Pick one?',
+        multi_select: false,
+        options: [{ label: 'A' }, { label: 'B' }],
+      },
+    ]);
+    const { dialog, collected } = makeDialog(pending);
+    dialog.handleInput('\u001B');
+    expect(collected).toEqual([[]]);
+  });
+
+  it.each(['\u0003', '\u0004'])('ctrl shortcut %j dismisses question dialog', (key) => {
+    const pending = makePending([
+      {
+        question: 'Pick one?',
+        multi_select: false,
+        options: [{ label: 'A' }, { label: 'B' }],
+      },
+    ]);
+    const { dialog, collected } = makeDialog(pending);
+    dialog.handleInput(key);
+    expect(collected).toEqual([[]]);
+  });
+  it('forwards ctrl+o to the global tool-output toggle without answering', () => {
+    let toggles = 0;
+    const pending = makePending([
+      { question: 'Q?', multi_select: false, options: [{ label: 'A' }] },
+    ]);
+    const { dialog, collected } = makeDialog(pending, () => toggles++);
+    dialog.handleInput('\u000F'); // Ctrl+O
+    expect(toggles).toBe(1);
+    expect(collected).toEqual([]);
+  });
+
+  it('forwards ctrl+e to the global plan-expand toggle without answering', () => {
+    let planToggles = 0;
+    const pending = makePending([
+      { question: 'Q?', multi_select: false, options: [{ label: 'A' }] },
+    ]);
+    const { dialog, collected } = makeDialog(pending, undefined, () => planToggles++);
+    dialog.handleInput('\u0005'); // Ctrl+E
+    expect(planToggles).toBe(1);
+    expect(collected).toEqual([]);
+  });
+
+});
diff --git a/apps/kimi-code/test/tui/components/dialogs/session-picker.test.ts b/apps/kimi-code/test/tui/components/dialogs/session-picker.test.ts
new file mode 100644
index 000000000..c8e919637
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/dialogs/session-picker.test.ts
@@ -0,0 +1,264 @@
+import { visibleWidth } from '@earendil-works/pi-tui';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { SessionPickerComponent } from '#/tui/components/dialogs/session-picker';
+import { getColorPalette } from '#/tui/theme/colors';
+
+function stripAnsi(text: string): string {
+  return text.replaceAll(/\[[0-?]*[ -/]*[@-~]/g, '');
+}
+
+function renderPlain(component: SessionPickerComponent, width = 120): string {
+  return stripAnsi(component.render(width).join('\n'));
+}
+
+describe('SessionPickerComponent', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('renders millisecond updated_at timestamps as relative times', () => {
+    const now = new Date('2026-05-11T12:00:00.000Z').getTime();
+    vi.spyOn(Date, 'now').mockReturnValue(now);
+
+    const component = new SessionPickerComponent({
+      sessions: [
+        {
+          id: 'ses_minutes',
+          title: 'minutes old',
+          work_dir: '/tmp/project',
+          updated_at: now - 2 * 60 * 1000,
+        },
+        {
+          id: 'ses_hours',
+          title: 'hours old',
+          work_dir: '/tmp/project',
+          updated_at: now - 3 * 60 * 60 * 1000,
+        },
+      ],
+      loading: false,
+      currentSessionId: 'ses_other',
+      colors: getColorPalette('dark'),
+      onSelect: vi.fn(),
+      onCancel: vi.fn(),
+    });
+
+    const output = renderPlain(component);
+
+    expect(output).toContain('2m ago');
+    expect(output).toContain('3h ago');
+    expect(output).not.toContain('just now');
+  });
+
+  it('renders title, full session id, work_dir, and last_prompt for each session', () => {
+    const now = new Date('2026-05-11T12:00:00.000Z').getTime();
+    vi.spyOn(Date, 'now').mockReturnValue(now);
+
+    const component = new SessionPickerComponent({
+      sessions: [
+        {
+          id: 'ses_01HXYABCDEFGHIJK',
+          title: 'Refactor sessions list',
+          last_prompt: 'please redesign the picker UI',
+          work_dir: '/tmp/project',
+          updated_at: now - 60 * 1000,
+        },
+      ],
+      loading: false,
+      currentSessionId: 'ses_other',
+      colors: getColorPalette('dark'),
+      onSelect: vi.fn(),
+      onCancel: vi.fn(),
+    });
+
+    const output = renderPlain(component);
+
+    expect(output).toContain('Refactor sessions list');
+    // Session id is rendered in full, never abbreviated with an ellipsis.
+    expect(output).toContain('ses_01HXYABCDEFGHIJK');
+    expect(output).not.toMatch(/ses_01\S*…/);
+    expect(output).toContain('/tmp/project');
+    expect(output).toContain('please redesign the picker UI');
+  });
+
+  it('omits the last-prompt row when last_prompt is missing', () => {
+    const now = new Date('2026-05-11T12:00:00.000Z').getTime();
+    vi.spyOn(Date, 'now').mockReturnValue(now);
+
+    const component = new SessionPickerComponent({
+      sessions: [
+        {
+          id: 'ses_no_prompt',
+          title: 'no prompt yet',
+          work_dir: '/tmp/project',
+          updated_at: now - 60 * 1000,
+        },
+      ],
+      loading: false,
+      currentSessionId: 'ses_other',
+      colors: getColorPalette('dark'),
+      onSelect: vi.fn(),
+      onCancel: vi.fn(),
+    });
+
+    const output = renderPlain(component);
+
+    expect(output).not.toMatch(/^\s*›/m);
+  });
+
+  it('truncates overly long last_prompt content', () => {
+    const now = new Date('2026-05-11T12:00:00.000Z').getTime();
+    vi.spyOn(Date, 'now').mockReturnValue(now);
+
+    const longPrompt = 'a'.repeat(500);
+    const component = new SessionPickerComponent({
+      sessions: [
+        {
+          id: 'ses_long',
+          title: 'long prompt',
+          last_prompt: longPrompt,
+          work_dir: '/tmp/project',
+          updated_at: now - 60 * 1000,
+        },
+      ],
+      loading: false,
+      currentSessionId: 'ses_other',
+      colors: getColorPalette('dark'),
+      onSelect: vi.fn(),
+      onCancel: vi.fn(),
+    });
+
+    const lines = component.render(60).map((line) => stripAnsi(line));
+    const promptLine = lines.find((line) => line.trimStart().startsWith('›'));
+    expect(promptLine).toBeDefined();
+    expect(promptLine!.length).toBeLessThanOrEqual(60);
+    expect(promptLine!.endsWith('…')).toBe(true);
+    expect(promptLine).not.toContain(longPrompt);
+  });
+
+  it('marks the current session with a (current) badge', () => {
+    const now = new Date('2026-05-11T12:00:00.000Z').getTime();
+    vi.spyOn(Date, 'now').mockReturnValue(now);
+
+    const component = new SessionPickerComponent({
+      sessions: [
+        {
+          id: 'ses_current',
+          title: 'this is current',
+          work_dir: '/tmp/project',
+          updated_at: now,
+        },
+        {
+          id: 'ses_other',
+          title: 'not current',
+          work_dir: '/tmp/project',
+          updated_at: now - 60 * 1000,
+        },
+      ],
+      loading: false,
+      currentSessionId: 'ses_current',
+      colors: getColorPalette('dark'),
+      onSelect: vi.fn(),
+      onCancel: vi.fn(),
+    });
+
+    const lines = component.render(120).map((line) => stripAnsi(line));
+    const currentLine = lines.find((line) => line.includes('this is current'));
+    const otherLine = lines.find((line) => line.includes('not current'));
+    expect(currentLine).toContain('(current)');
+    expect(otherLine).not.toContain('(current)');
+  });
+
+  it('places the relative time on the same line as the title, not right-aligned', () => {
+    const now = new Date('2026-05-11T12:00:00.000Z').getTime();
+    vi.spyOn(Date, 'now').mockReturnValue(now);
+
+    const component = new SessionPickerComponent({
+      sessions: [
+        {
+          id: 'ses_inline_time',
+          title: 'Short title',
+          work_dir: '/tmp/project',
+          updated_at: now - 5 * 60 * 1000,
+        },
+      ],
+      loading: false,
+      currentSessionId: 'ses_other',
+      colors: getColorPalette('dark'),
+      onSelect: vi.fn(),
+      onCancel: vi.fn(),
+    });
+
+    const lines = component.render(120).map((line) => stripAnsi(line));
+    const headerLine = lines.find((line) => line.includes('Short title'));
+    expect(headerLine).toBeDefined();
+    // Title and time sit side-by-side with only the small inline separator.
+    expect(headerLine).toMatch(/Short title\s{1,4}5m ago/);
+    // No long run of trailing spaces, i.e. not right-aligned.
+    expect(headerLine).not.toMatch(/Short title\s{8,}/);
+  });
+
+  it('prepends [imported] badge before the title for sessions migrated from kimi-cli', () => {
+    const now = new Date('2026-05-11T12:00:00.000Z').getTime();
+    vi.spyOn(Date, 'now').mockReturnValue(now);
+
+    const component = new SessionPickerComponent({
+      sessions: [
+        {
+          id: 'ses_imported',
+          title: 'Migrated session',
+          work_dir: '/tmp/project',
+          updated_at: now - 60 * 1000,
+          metadata: { imported_from_kimi_cli: true },
+        },
+        {
+          id: 'ses_native',
+          title: 'Fresh session',
+          work_dir: '/tmp/project',
+          updated_at: now - 60 * 1000,
+        },
+      ],
+      loading: false,
+      currentSessionId: 'ses_other',
+      colors: getColorPalette('dark'),
+      onSelect: vi.fn(),
+      onCancel: vi.fn(),
+    });
+
+    const lines = component.render(120).map((line) => stripAnsi(line));
+    const importedLine = lines.find((line) => line.includes('Migrated session'));
+    const nativeLine = lines.find((line) => line.includes('Fresh session'));
+    expect(importedLine).toContain('[imported] Migrated session');
+    expect(nativeLine).not.toContain('[imported]');
+  });
+
+  it('keeps every rendered line within the terminal width even for CJK content', () => {
+    const now = new Date('2026-05-11T12:00:00.000Z').getTime();
+    vi.spyOn(Date, 'now').mockReturnValue(now);
+
+    const component = new SessionPickerComponent({
+      sessions: [
+        {
+          id: 'ses_cjk_long_session_id_value',
+          title: '现在要重构一下 TUI 的 sessions 列表，要渲染几个字段，让 UI 更好看',
+          last_prompt:
+            '我们要渲染几个：sessionid title lastPrompt。工作目录，修改时间。需要重新设计下 UI。',
+          work_dir: '/Users/someone/Desktop/中文目录/very-long-project-folder-name',
+          updated_at: now - 5 * 60 * 1000,
+        },
+      ],
+      loading: false,
+      currentSessionId: 'ses_cjk_long_session_id_value',
+      colors: getColorPalette('dark'),
+      onSelect: vi.fn(),
+      onCancel: vi.fn(),
+    });
+
+    for (const width of [40, 80, 120, 238]) {
+      const lines = component.render(width);
+      for (const line of lines) {
+        expect(visibleWidth(line)).toBeLessThanOrEqual(width);
+      }
+    }
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/editor/custom-editor.test.ts b/apps/kimi-code/test/tui/components/editor/custom-editor.test.ts
new file mode 100644
index 000000000..58469bf21
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/editor/custom-editor.test.ts
@@ -0,0 +1,102 @@
+import type {
+  AutocompleteItem,
+  AutocompleteProvider,
+  AutocompleteSuggestions,
+  TUI,
+} from '@earendil-works/pi-tui';
+import { describe, expect, it, vi } from 'vitest';
+
+import { CustomEditor } from '#/tui/components/editor/custom-editor';
+import { getColorPalette } from '#/tui/theme/index';
+
+function makeEditor(): CustomEditor {
+  const tui = {
+    requestRender: vi.fn(),
+  } as unknown as TUI;
+  return new CustomEditor(tui, { ...getColorPalette('dark') });
+}
+
+async function flushAutocomplete(): Promise<void> {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+function providerReturning(items: AutocompleteItem[]): AutocompleteProvider {
+  return {
+    getSuggestions: vi.fn(async () => ({ items, prefix: '/' })),
+    applyCompletion: vi.fn((lines, cursorLine, cursorCol) => ({ lines, cursorLine, cursorCol })),
+  };
+}
+
+describe('CustomEditor autocomplete Escape handling', () => {
+  it('escape closes a visible slash command menu without firing app-level escape', async () => {
+    const editor = makeEditor();
+    const onEscape = vi.fn();
+    editor.onEscape = onEscape;
+    editor.setAutocompleteProvider(providerReturning([{ value: 'help', label: 'help' }]));
+
+    editor.handleInput('/');
+    await flushAutocomplete();
+
+    expect(editor.isShowingAutocomplete()).toBe(true);
+
+    editor.handleInput('\u001B');
+
+    expect(editor.isShowingAutocomplete()).toBe(false);
+    expect(onEscape).not.toHaveBeenCalled();
+  });
+
+  it('escape cancels an in-flight slash command menu request', async () => {
+    const editor = makeEditor();
+    const onEscape = vi.fn();
+    let resolveSuggestions: (items: AutocompleteItem[]) => void = () => {};
+    const provider: AutocompleteProvider = {
+      getSuggestions: vi.fn(
+        () =>
+          new Promise<AutocompleteSuggestions | null>((resolve) => {
+            resolveSuggestions = (items) =>{  resolve({ items, prefix: '/' }); };
+          }),
+      ),
+      applyCompletion: vi.fn((lines, cursorLine, cursorCol) => ({ lines, cursorLine, cursorCol })),
+    };
+    editor.onEscape = onEscape;
+    editor.setAutocompleteProvider(provider);
+
+    editor.handleInput('/');
+    await flushAutocomplete();
+    editor.handleInput('\u001B');
+    resolveSuggestions([{ value: 'help', label: 'help' }]);
+    await flushAutocomplete();
+
+    expect(editor.isShowingAutocomplete()).toBe(false);
+    expect(onEscape).not.toHaveBeenCalled();
+  });
+});
+
+describe('CustomEditor Kitty key release handling', () => {
+  it('ignores Kitty key release events instead of inserting their CSI-u payload', () => {
+    const editor = makeEditor();
+
+    editor.handleInput('\u001B[47;1:3u');
+    editor.handleInput('\u001B[110;1:3u');
+
+    expect(editor.getText()).toBe('');
+  });
+});
+
+describe('CustomEditor shortcut telemetry hooks', () => {
+  it('reports newline and undo shortcuts before delegating to the base editor', () => {
+    const editor = makeEditor();
+    const onInsertNewline = vi.fn();
+    const onUndo = vi.fn();
+    editor.onInsertNewline = onInsertNewline;
+    editor.onUndo = onUndo;
+
+    editor.handleInput('a');
+    editor.handleInput('\n');
+    editor.handleInput('\u001F');
+
+    expect(onInsertNewline).toHaveBeenCalledOnce();
+    expect(onUndo).toHaveBeenCalledOnce();
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/editor/file-mention-provider.test.ts b/apps/kimi-code/test/tui/components/editor/file-mention-provider.test.ts
new file mode 100644
index 000000000..496aa4ce3
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/editor/file-mention-provider.test.ts
@@ -0,0 +1,215 @@
+import { describe, it, expect } from 'vitest';
+
+import { FileMentionProvider } from '#/tui/components/editor/file-mention-provider';
+import type { GitLsFilesCache, GitSnapshot } from '#/utils/git/git-ls-files';
+
+function stubGitCache(
+  files: string[] | null,
+  opts: { mtimes?: Record<string, number>; recency?: string[] } = {},
+): GitLsFilesCache {
+  const snapshot: GitSnapshot | null =
+    files === null
+      ? null
+      : {
+          files,
+          mtimeByPath: new Map(Object.entries(opts.mtimes ?? {})),
+          recencyOrder: new Map((opts.recency ?? []).map((p, i) => [p, i])),
+        };
+  return {
+    isGitRepo: () => files !== null,
+    getSnapshot: () => snapshot,
+    list: () => (files === null ? null : files.slice()),
+  };
+}
+
+function ctrl(): AbortSignal {
+  return new AbortController().signal;
+}
+
+const NO_FD = null;
+
+describe('FileMentionProvider — @ prefix detection + git-backed suggestions', () => {
+  it('returns null when there is no @ mention and the dir is empty', async () => {
+    const provider = new FileMentionProvider([], '/nonexistent', NO_FD, stubGitCache([]));
+    const result = await provider.getSuggestions(['hello world'], 0, 11, { signal: ctrl() });
+    // pi-tui inner will also return null for non-path plain text.
+    expect(result).toBeNull();
+  });
+
+  it('bare @ surfaces the first files as a starting list', async () => {
+    const files = ['a.ts', 'b.ts', 'src/c.ts'];
+    const provider = new FileMentionProvider([], '/repo', NO_FD, stubGitCache(files));
+    const result = await provider.getSuggestions(['@'], 0, 1, { signal: ctrl() });
+    expect(result).not.toBeNull();
+    expect(result!.prefix).toBe('@');
+    expect(result!.items.map((i) => i.value)).toEqual(['@a.ts', '@b.ts', '@src/c.ts']);
+  });
+
+  it('ranks basename-prefix > substring > fuzzy', async () => {
+    const files = [
+      'docs/readme.md', // basename starts with "read"
+      'src/readability.ts', // basename starts with "read"
+      'lib/threader.ts', // basename contains "read" (substring)
+    ];
+    const provider = new FileMentionProvider([], '/repo', NO_FD, stubGitCache(files));
+    const result = await provider.getSuggestions(['@read'], 0, 5, { signal: ctrl() });
+    expect(result).not.toBeNull();
+    const values = result!.items.map((i) => i.value);
+    const readabilityIdx = values.indexOf('@src/readability.ts');
+    const readmeIdx = values.indexOf('@docs/readme.md');
+    const threadIdx = values.indexOf('@lib/threader.ts');
+    // Both starts-with entries rank ahead of the substring entry.
+    expect(readabilityIdx).toBeGreaterThanOrEqual(0);
+    expect(readmeIdx).toBeGreaterThanOrEqual(0);
+    expect(threadIdx).toBeGreaterThan(Math.max(readabilityIdx, readmeIdx));
+  });
+
+  it('empty query prefers recently-edited files over everything else', async () => {
+    const files = ['a.ts', 'b.ts', 'c.ts', 'd.ts', 'e.ts'];
+    const provider = new FileMentionProvider(
+      [],
+      '/repo',
+      NO_FD,
+      stubGitCache(files, {
+        recency: ['d.ts', 'b.ts'], // d most recent, then b
+      }),
+    );
+    const result = await provider.getSuggestions(['@'], 0, 1, { signal: ctrl() });
+    const values = result!.items.map((i) => i.value);
+    // Recency layer fills first, then alphabetical layer.
+    expect(values.slice(0, 2)).toEqual(['@d.ts', '@b.ts']);
+    expect(values.slice(2)).toEqual(['@a.ts', '@c.ts', '@e.ts']);
+  });
+
+  it('empty query falls back to mtime when no recency info', async () => {
+    const files = ['old.ts', 'newer.ts', 'newest.ts'];
+    const provider = new FileMentionProvider(
+      [],
+      '/repo',
+      NO_FD,
+      stubGitCache(files, {
+        mtimes: { 'old.ts': 1000, 'newer.ts': 2000, 'newest.ts': 3000 },
+      }),
+    );
+    const result = await provider.getSuggestions(['@'], 0, 1, { signal: ctrl() });
+    const values = result!.items.map((i) => i.value);
+    expect(values).toEqual(['@newest.ts', '@newer.ts', '@old.ts']);
+  });
+
+  it('empty query falls back to basename alphabetical when no signals', async () => {
+    const files = ['zoo/apple.ts', 'banana.ts', 'cherry.ts'];
+    const provider = new FileMentionProvider([], '/repo', NO_FD, stubGitCache(files));
+    const result = await provider.getSuggestions(['@'], 0, 1, { signal: ctrl() });
+    const values = result!.items.map((i) => i.value);
+    // Sorted by basename alphabetical: apple, banana, cherry
+    expect(values).toEqual(['@zoo/apple.ts', '@banana.ts', '@cherry.ts']);
+  });
+
+  it('hides dot-dir files from the default list', async () => {
+    const files = ['.agents/skills/x.md', '.github/workflows/y.yml', 'src/a.ts', 'README.md'];
+    const provider = new FileMentionProvider([], '/repo', NO_FD, stubGitCache(files));
+    const result = await provider.getSuggestions(['@'], 0, 1, { signal: ctrl() });
+    const values = result!.items.map((i) => i.value);
+    expect(values).toContain('@README.md');
+    expect(values).toContain('@src/a.ts');
+    expect(values).not.toContain('@.agents/skills/x.md');
+    expect(values).not.toContain('@.github/workflows/y.yml');
+  });
+
+  it('shows dot-dir files when the query explicitly opts in (starts with .)', async () => {
+    const files = ['.agents/skills/foo.md', '.agents/README.md', 'src/a.ts'];
+    const provider = new FileMentionProvider([], '/repo', NO_FD, stubGitCache(files));
+    const result = await provider.getSuggestions(['@.agents'], 0, 8, { signal: ctrl() });
+    expect(result).not.toBeNull();
+    const values = result!.items.map((i) => i.value);
+    expect(values.some((v) => v.startsWith('@.agents/'))).toBe(true);
+  });
+
+  it('within a category, recency ranks higher than mtime', async () => {
+    const files = ['older-recent.ts', 'never-touched-but-new.ts'];
+    const provider = new FileMentionProvider(
+      [],
+      '/repo',
+      NO_FD,
+      stubGitCache(files, {
+        mtimes: { 'older-recent.ts': 1000, 'never-touched-but-new.ts': 9999 },
+        recency: ['older-recent.ts'],
+      }),
+    );
+    // Query hits both via fuzzy (they both contain letters from 'nr').
+    // Use basename-startswith shared prefix to force cat 0 tie.
+    const tied = ['aa-recent.ts', 'aa-newer.ts'];
+    const provider2 = new FileMentionProvider(
+      [],
+      '/repo',
+      NO_FD,
+      stubGitCache(tied, {
+        mtimes: { 'aa-recent.ts': 1000, 'aa-newer.ts': 9999 },
+        recency: ['aa-recent.ts'],
+      }),
+    );
+    const result = await provider2.getSuggestions(['@aa'], 0, 3, { signal: ctrl() });
+    const values = result!.items.map((i) => i.value);
+    expect(values[0]).toBe('@aa-recent.ts');
+    expect(values[1]).toBe('@aa-newer.ts');
+    void provider; // silence unused
+  });
+
+  it('scoped @src/ limits to files under src/', async () => {
+    const files = ['src/a.ts', 'src/b.ts', 'lib/c.ts'];
+    const provider = new FileMentionProvider([], '/repo', NO_FD, stubGitCache(files));
+    const result = await provider.getSuggestions(['@src/'], 0, 5, { signal: ctrl() });
+    expect(result).not.toBeNull();
+    const values = result!.items.map((i) => i.value);
+    // Empty query after src/ shouldn't match lib/c.ts via basename ranking;
+    // but our git-backed path doesn't apply scope directly — the query is
+    // "src/" and we fall back to fuzzy on the raw path. Both src/ paths
+    // contain "src/" and rank higher than lib/c.ts.
+    expect(values[0]).toMatch(/^@src\//);
+    expect(values[1]).toMatch(/^@src\//);
+  });
+
+  it('does not trigger the @ branch when @ is preceded by a non-delimiter', async () => {
+    // "email@example" — @ is not at a token boundary; our extractAtPrefix
+    // returns null and the inner provider handles the text.
+    const provider = new FileMentionProvider([], '/nonexistent', NO_FD, stubGitCache(['a.ts']));
+    const result = await provider.getSuggestions(['email@example'], 0, 13, { signal: ctrl() });
+    // Inner provider returns null for this kind of free text.
+    expect(result).toBeNull();
+  });
+
+  it('handles multiple @ mentions on one line by completing the last one', async () => {
+    const files = ['alpha.ts', 'beta.ts'];
+    const provider = new FileMentionProvider([], '/repo', NO_FD, stubGitCache(files));
+    // "read @alpha.ts and @bet" — cursor at end, inside the second @.
+    const line = 'read @alpha.ts and @bet';
+    const result = await provider.getSuggestions([line], 0, line.length, { signal: ctrl() });
+    expect(result).not.toBeNull();
+    expect(result!.prefix).toBe('@bet');
+    const values = result!.items.map((i) => i.value);
+    expect(values).toContain('@beta.ts');
+    expect(values).not.toContain('@alpha.ts');
+  });
+
+  it('applyCompletion delegates to inner (replaces prefix with value)', () => {
+    const provider = new FileMentionProvider([], '/repo', NO_FD, stubGitCache(['src/a.ts']));
+    const out = provider.applyCompletion(
+      ['hey @src'],
+      0,
+      8, // cursor just after @src
+      { value: '@src/a.ts', label: 'a.ts' },
+      '@src',
+    );
+    // pi-tui appends a trailing space after a non-directory completion
+    // so the user can type the next token immediately.
+    expect(out.lines[0]).toBe('hey @src/a.ts ');
+  });
+
+  it('falls through to inner when the git cache is null (non-git dir)', async () => {
+    const provider = new FileMentionProvider([], '/nonexistent', NO_FD, stubGitCache(null));
+    // No files visible via readdir either, but it shouldn't throw.
+    const result = await provider.getSuggestions(['@foo'], 0, 4, { signal: ctrl() });
+    // pi-tui readdir on a nonexistent basePath returns [] → null.
+    expect(result).toBeNull();
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/editor/normalize-caps-locked-ctrl.test.ts b/apps/kimi-code/test/tui/components/editor/normalize-caps-locked-ctrl.test.ts
new file mode 100644
index 000000000..2d2151f72
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/editor/normalize-caps-locked-ctrl.test.ts
@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+
+import { normalizeCapsLockedCtrl } from '#/tui/components/editor/custom-editor';
+
+// Kitty keyboard protocol emits `ESC[<codepoint>;<modifier+1>[:eventType]u`.
+// Modifier mask bits: shift=1, alt=2, ctrl=4, super=8, hyper=16, meta=32,
+// caps_lock=64, num_lock=128. The pi-tui bug this helper works around is
+// that when caps_lock is on, terminals report the codepoint of ctrl+letter
+// as the *uppercase* ASCII letter (e.g. 68 = 'D' instead of 100 = 'd'),
+// which pi-tui's matcher compares literally and fails. We rewrite the
+// sequence back to the unlocked form before dispatching.
+
+describe('normalizeCapsLockedCtrl', () => {
+  it('rewrites ctrl+D reported with caps_lock back to ctrl+d', () => {
+    // ctrl(4) + caps_lock(64) = 68, reported = 69
+    expect(normalizeCapsLockedCtrl('\u001B[68;69u')).toBe('\u001B[100;5u');
+  });
+
+  it('rewrites ctrl+C / ctrl+O / ctrl+S under caps_lock', () => {
+    expect(normalizeCapsLockedCtrl('\u001B[67;69u')).toBe('\u001B[99;5u');
+    expect(normalizeCapsLockedCtrl('\u001B[79;69u')).toBe('\u001B[111;5u');
+    expect(normalizeCapsLockedCtrl('\u001B[83;69u')).toBe('\u001B[115;5u');
+  });
+
+  it('preserves the trailing event-type sub-parameter', () => {
+    // `:3u` = key release event
+    expect(normalizeCapsLockedCtrl('\u001B[68;69:3u')).toBe('\u001B[100;5:3u');
+    // multiple sub-parameters still survive
+    expect(normalizeCapsLockedCtrl('\u001B[68;69:3:1u')).toBe('\u001B[100;5:3:1u');
+  });
+
+  it('leaves plain uppercase typed with only caps_lock alone', () => {
+    // User intentionally typing an uppercase letter — do not downgrade.
+    // caps_lock(64) alone = 64, reported = 65
+    expect(normalizeCapsLockedCtrl('\u001B[68;65u')).toBe('\u001B[68;65u');
+  });
+
+  it('leaves ctrl+letter without caps_lock alone', () => {
+    // ctrl(4) alone = 4, reported = 5
+    expect(normalizeCapsLockedCtrl('\u001B[68;5u')).toBe('\u001B[68;5u');
+    expect(normalizeCapsLockedCtrl('\u001B[100;5u')).toBe('\u001B[100;5u');
+  });
+
+  it('leaves ctrl+shift+letter with caps_lock alone', () => {
+    // shift(1) + ctrl(4) + caps_lock(64) = 69, reported = 70.
+    // User explicitly wants the shifted form — don't rewrite.
+    expect(normalizeCapsLockedCtrl('\u001B[68;70u')).toBe('\u001B[68;70u');
+  });
+
+  it('rewrites ctrl+alt+letter under caps_lock (shift not involved)', () => {
+    // alt(2) + ctrl(4) + caps_lock(64) = 70, reported = 71
+    expect(normalizeCapsLockedCtrl('\u001B[68;71u')).toBe('\u001B[100;7u');
+  });
+
+  it('ignores codepoints outside A-Z even with ctrl+caps_lock', () => {
+    // Digit '1' (49) — uppercase mapping would be nonsense.
+    expect(normalizeCapsLockedCtrl('\u001B[49;69u')).toBe('\u001B[49;69u');
+    // Symbol '[' (91) — just past 'Z'.
+    expect(normalizeCapsLockedCtrl('\u001B[91;69u')).toBe('\u001B[91;69u');
+    // '@' (64) — just before 'A'.
+    expect(normalizeCapsLockedCtrl('\u001B[64;69u')).toBe('\u001B[64;69u');
+  });
+
+  it('passes through non-CSI-u input unchanged', () => {
+    // Plain printable character
+    expect(normalizeCapsLockedCtrl('H')).toBe('H');
+    // Legacy ctrl+d control byte
+    expect(normalizeCapsLockedCtrl('\u0004')).toBe('\u0004');
+    // Legacy ctrl+c control byte
+    expect(normalizeCapsLockedCtrl('\u0003')).toBe('\u0003');
+    // Arrow key CSI (not CSI-u)
+    expect(normalizeCapsLockedCtrl('\u001B[A')).toBe('\u001B[A');
+    // Empty string
+    expect(normalizeCapsLockedCtrl('')).toBe('');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/editor/prompt-symbol.test.ts b/apps/kimi-code/test/tui/components/editor/prompt-symbol.test.ts
new file mode 100644
index 000000000..c7537551d
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/editor/prompt-symbol.test.ts
@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+
+import { injectPromptSymbol } from '#/tui/components/editor/custom-editor';
+
+describe('injectPromptSymbol', () => {
+  it('places a "> " prompt at columns 2-3 (col 0 = border, col 1 = single-space gap)', () => {
+    expect(injectPromptSymbol('    hello world')).toBe('  > hello world');
+  });
+
+  it('preserves overall visible width (prompt occupies padding slots)', () => {
+    const original = '    hello       ';
+    expect(injectPromptSymbol(original)).toHaveLength(original.length);
+  });
+
+  it('preserves trailing ANSI escapes (e.g. cursor inverse marker)', () => {
+    const line = '    [7m [0m         ';
+    const out = injectPromptSymbol(line);
+    expect(out).toBe('  > [7m [0m         ');
+  });
+
+  it('emits no SGR (terminal default foreground renders the symbol)', () => {
+    const out = injectPromptSymbol('    hello');
+    expect(out).not.toMatch(/\[/);
+  });
+
+  it('returns undefined when the line is too short', () => {
+    expect(injectPromptSymbol('   ')).toBeUndefined();
+    expect(injectPromptSymbol('')).toBeUndefined();
+  });
+
+  it('returns undefined when the leading four characters are not all spaces', () => {
+    expect(injectPromptSymbol('x   hello')).toBeUndefined();
+    expect(injectPromptSymbol(' x  hello')).toBeUndefined();
+    expect(injectPromptSymbol('  x hello')).toBeUndefined();
+    expect(injectPromptSymbol('   xhello')).toBeUndefined();
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/editor/side-borders.test.ts b/apps/kimi-code/test/tui/components/editor/side-borders.test.ts
new file mode 100644
index 000000000..11801aa71
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/editor/side-borders.test.ts
@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+
+import { wrapWithSideBorders } from '#/tui/components/editor/custom-editor';
+
+const id = (s: string): string => s;
+
+describe('wrapWithSideBorders', () => {
+  it('turns the top horizontal border into a ╭…╮ run', () => {
+    const out = wrapWithSideBorders(['──────────', '   hi     ', '──────────'], id);
+    expect(out[0]).toBe('╭────────╮');
+  });
+
+  it('turns the bottom horizontal border into a ╰…╯ run', () => {
+    const out = wrapWithSideBorders(['──────────', '   hi     ', '──────────'], id);
+    expect(out[2]).toBe('╰────────╯');
+  });
+
+  it('wraps content lines with │ … │, replacing the outer padding columns', () => {
+    // '   hi     ' is 10 chars; first/last spaces become │, middle keeps its length
+    const out = wrapWithSideBorders(['──────────', '   hi     ', '──────────'], id);
+    expect(out[1]).toBe('│  hi    │');
+    expect(out[1]).toHaveLength('   hi     '.length);
+  });
+
+  it('treats scroll-indicator lines (── ↑ N more ──) as horizontal borders', () => {
+    const top = '─── ↑ 5 more ────';
+    const bot = '─── ↓ 3 more ────';
+    const out = wrapWithSideBorders([top, '   x             ', bot], id);
+    expect(out[0]?.startsWith('╭')).toBe(true);
+    expect(out[0]?.endsWith('╮')).toBe(true);
+    expect(out[2]?.startsWith('╰')).toBe(true);
+    expect(out[2]?.endsWith('╯')).toBe(true);
+    // body of the indicator is preserved
+    expect(out[0]).toContain('↑ 5 more');
+    expect(out[2]).toContain('↓ 3 more');
+  });
+
+  it('handles autocomplete rows that come after the bottom border (still wrap with │)', () => {
+    const lines = [
+      '──────────',
+      '   q      ',
+      '──────────',
+      '   item1  ',
+      '   item2  ',
+    ];
+    const out = wrapWithSideBorders(lines, id);
+    expect(out[0]?.startsWith('╭')).toBe(true);
+    expect(out[2]?.startsWith('╰')).toBe(true);
+    // '   item1  ' → first/last spaces become │
+    expect(out[3]).toBe('│  item1 │');
+    expect(out[4]).toBe('│  item2 │');
+  });
+
+  it('paints corners and side borders through the provided borderColor', () => {
+    const paint = (s: string): string => `<${s}>`;
+    const out = wrapWithSideBorders(['─────', '  x  ', '─────'], paint);
+    // corners and horizontals routed through paint
+    expect(out[0]).toBe('<╭───╮>');
+    expect(out[2]).toBe('<╰───╯>');
+    // side bars on content lines also painted
+    expect(out[1]).toBe('<│> x <│>');
+  });
+
+  it('does not clobber non-space content sitting in the outer column (e.g. cursor overflow)', () => {
+    // last column holds a non-space character — leave it as-is rather than overwrite with │
+    const out = wrapWithSideBorders(['─────', '  abc', '─────'], id);
+    // first column was a space → replaced with │; last column was 'c' → kept
+    expect(out[1]).toBe('│ abc');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/editor/slash-highlight.test.ts b/apps/kimi-code/test/tui/components/editor/slash-highlight.test.ts
new file mode 100644
index 000000000..04826e604
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/editor/slash-highlight.test.ts
@@ -0,0 +1,66 @@
+import chalk from 'chalk';
+import { describe, it, expect, beforeAll } from 'vitest';
+
+import { highlightFirstSlashToken } from '#/tui/components/editor/custom-editor';
+
+beforeAll(() => {
+  // Vitest runs without a TTY so chalk auto-detects colour support as
+  // 0 (no colours). Force full colour so the highlighter actually
+  // emits the SGR escapes we're asserting on.
+  chalk.level = 3;
+});
+
+function strip(s: string): string {
+  return s.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+describe('highlightFirstSlashToken', () => {
+  it('colours /cmd when line starts with a slash', () => {
+    const out = highlightFirstSlashToken('  /help rest of input', '#ff00aa');
+    expect(out).toBeDefined();
+    // Visible text unchanged
+    expect(strip(out!)).toBe('  /help rest of input');
+    // SGR escapes surround /help
+    expect(out!).toMatch(/\u001B\[.*m\/help\u001B\[/);
+  });
+
+  it('returns undefined when the line has no slash', () => {
+    expect(highlightFirstSlashToken('hello world', '#ff00aa')).toBeUndefined();
+  });
+
+  it('returns undefined when slash is not at the leading position', () => {
+    expect(highlightFirstSlashToken('  hello /not-cmd', '#ff00aa')).toBeUndefined();
+  });
+
+  it('returns undefined for path-like slash tokens', () => {
+    expect(highlightFirstSlashToken('/user/desktop/ foo', '#ff00aa')).toBeUndefined();
+  });
+
+  it('handles /token at end of line (no trailing whitespace)', () => {
+    const out = highlightFirstSlashToken('/exit', '#ff00aa');
+    expect(out).toBeDefined();
+    expect(strip(out!)).toBe('/exit');
+  });
+
+  it('passes through pre-existing ANSI (e.g. cursor inverse) in the tail', () => {
+    // Simulate pi-tui Editor inserting an inverse-video cursor marker
+    // somewhere after the slash token.
+    const line = '/help x\u001B[7m \u001B[0m';
+    const out = highlightFirstSlashToken(line, '#ff00aa');
+    expect(out).toBeDefined();
+    // Stripped visible content unchanged
+    expect(strip(out!)).toBe(strip(line));
+    // Inverse cursor SGR is still present afterwards
+    expect(out!.includes('\u001B[7m')).toBe(true);
+  });
+
+  it('only paints the first token, not other slashes further along', () => {
+    const out = highlightFirstSlashToken('/a /b', '#ff00aa');
+    expect(out).toBeDefined();
+    // Count the SGR opens — should be exactly one for /a.
+    const opens = (out!.match(/\u001B\[[0-9;]+m/g) ?? []).length;
+    expect(opens).toBeGreaterThanOrEqual(2); // chalk hex+bold open and reset(s)
+    // /b should remain plain — the substring " /b" exists verbatim.
+    expect(out!).toContain(' /b');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/media/code-highlight.test.ts b/apps/kimi-code/test/tui/components/media/code-highlight.test.ts
new file mode 100644
index 000000000..b6df1cf22
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/media/code-highlight.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+
+import { highlightLines, langFromPath } from '#/tui/components/media/code-highlight';
+
+import { captureProcessWrite } from '../../../helpers/process';
+
+describe('code-highlight', () => {
+  it('maps known file extensions to supported highlight languages', () => {
+    expect(langFromPath('src/foo.ts')).toBe('typescript');
+    expect(langFromPath('src/foo.TS')).toBe('typescript');
+  });
+
+  it('treats unsupported file extensions as plain text', () => {
+    expect(langFromPath('src/foo.abcxyz')).toBeUndefined();
+  });
+
+  it('does not call cli-highlight for unsupported languages', () => {
+    const stderr = captureProcessWrite('stderr');
+    try {
+      expect(highlightLines('hello\nworld', 'abcxyz')).toEqual(['hello', 'world']);
+      expect(stderr.text()).not.toContain('Could not find the language');
+    } finally {
+      stderr.restore();
+    }
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/media/diff-preview.test.ts b/apps/kimi-code/test/tui/components/media/diff-preview.test.ts
new file mode 100644
index 000000000..f2a43aabd
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/media/diff-preview.test.ts
@@ -0,0 +1,180 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  computeDiffLines,
+  renderDiffLines,
+  renderDiffLinesClustered,
+} from '#/tui/components/media/diff-preview';
+import { getColorPalette } from '#/tui/theme/colors';
+
+const COLORS = getColorPalette('dark');
+
+function stripAnsi(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+describe('computeDiffLines', () => {
+  it('renders a complete diff when isIncomplete is false', () => {
+    const lines = computeDiffLines('A\nB\nC\nD', 'A\nB', 1, 1, false);
+    const kinds = lines.map((l) => l.kind);
+    expect(kinds).toEqual(['context', 'context', 'delete', 'delete']);
+  });
+
+  it('suppresses trailing deletes when isIncomplete is true', () => {
+    const lines = computeDiffLines('A\nB\nC\nD', 'A\nB', 1, 1, true);
+    const kinds = lines.map((l) => l.kind);
+    expect(kinds).toEqual(['context', 'context']);
+  });
+
+  it('suppresses all deletes when everything would be deleted and incomplete', () => {
+    const lines = computeDiffLines('A\nB\nC', '', 1, 1, true);
+    expect(lines).toEqual([]);
+  });
+
+  it('keeps trailing adds when isIncomplete is true', () => {
+    const lines = computeDiffLines('A\nB\nC', 'A\nB\nX', 1, 1, true);
+    const kinds = lines.map((l) => l.kind);
+    expect(kinds).toEqual(['context', 'context', 'delete', 'add']);
+  });
+
+  it('keeps internal delete blocks that are not trailing', () => {
+    const lines = computeDiffLines('A\nB\nC\nD', 'A\nC', 1, 1, true);
+    const kinds = lines.map((l) => l.kind);
+    expect(kinds).toEqual(['context', 'delete', 'context']);
+  });
+});
+
+describe('renderDiffLines', () => {
+  it('does not show removed count for suppressed trailing deletes', () => {
+    const output = renderDiffLines('A\nB\nC\nD', 'A\nB', 'test.ts', COLORS, true, 1, 1);
+    const text = stripAnsi(output.join('\n'));
+    expect(text).toContain('test.ts');
+    expect(text).not.toContain('-2');
+    expect(text).not.toContain('C');
+    expect(text).not.toContain('D');
+    // When trailing deletes are suppressed, only context lines remain;
+    // renderDiffLines only emits changed lines, so the body is empty.
+    expect(text).not.toContain('A');
+    expect(text).not.toContain('B');
+  });
+
+  it('shows removed count for complete diffs', () => {
+    const output = renderDiffLines('A\nB\nC\nD', 'A\nB', 'test.ts', COLORS, false, 1, 1);
+    const text = stripAnsi(output.join('\n'));
+    expect(text).toContain('-2');
+    expect(text).toContain('C');
+    expect(text).toContain('D');
+  });
+});
+
+describe('renderDiffLinesClustered', () => {
+  it('renders header with file path and counts', () => {
+    const out = renderDiffLinesClustered('A\nB\nC', 'A\nX\nC', 'foo.ts', COLORS);
+    const text = stripAnsi(out[0]!);
+    expect(text).toContain('+1');
+    expect(text).toContain('-1');
+    expect(text).toContain('foo.ts');
+  });
+
+  it('returns header only when there are no changes', () => {
+    const out = renderDiffLinesClustered('A\nB', 'A\nB', 'foo.ts', COLORS);
+    expect(out).toHaveLength(1);
+    expect(stripAnsi(out[0]!)).toContain('foo.ts');
+  });
+
+  it('shows context lines around a single change cluster', () => {
+    // Five lines, change line 3 only — context is 1 each side.
+    const oldText = ['L1', 'L2', 'L3', 'L4', 'L5'].join('\n');
+    const newText = ['L1', 'L2', 'L3X', 'L4', 'L5'].join('\n');
+    const text = stripAnsi(
+      renderDiffLinesClustered(oldText, newText, 'f.ts', COLORS, { contextLines: 1 }).join('\n'),
+    );
+    expect(text).toContain('L2');
+    expect(text).toContain('L3');
+    expect(text).toContain('L3X');
+    expect(text).toContain('L4');
+    expect(text).not.toContain('L1');
+    expect(text).not.toContain('L5');
+  });
+
+  it('elides unchanged middle between two clusters with a separator', () => {
+    const oldLines: string[] = [];
+    for (let i = 1; i <= 30; i++) oldLines.push(`L${String(i)}`);
+    const newLines = oldLines.slice();
+    newLines[1] = 'L2X'; // change near top
+    newLines[28] = 'L29X'; // change near bottom
+    const text = stripAnsi(
+      renderDiffLinesClustered(oldLines.join('\n'), newLines.join('\n'), 'f.ts', COLORS, {
+        contextLines: 2,
+      }).join('\n'),
+    );
+    expect(text).toContain('L2X');
+    expect(text).toContain('L29X');
+    expect(text).toMatch(/… \d+ unchanged lines? …/);
+    // Middle untouched lines (e.g. L15) should not appear.
+    expect(text).not.toContain('L15');
+  });
+
+  it('merges nearby change clusters when the gap is within context window', () => {
+    const oldLines: string[] = [];
+    for (let i = 1; i <= 10; i++) oldLines.push(`L${String(i)}`);
+    const newLines = oldLines.slice();
+    newLines[2] = 'L3X';
+    newLines[5] = 'L6X'; // gap of 2 lines between change indices 2 and 5 → merges with contextLines=2 (mergeGap=4)
+    const out = renderDiffLinesClustered(oldLines.join('\n'), newLines.join('\n'), 'f.ts', COLORS, {
+      contextLines: 2,
+    }).join('\n');
+    const text = stripAnsi(out);
+    expect(text).not.toMatch(/unchanged lines? …/);
+    expect(text).toContain('L3X');
+    expect(text).toContain('L6X');
+  });
+
+  it('emits a partial body even when a single cluster exceeds maxLines', () => {
+    // Worst case from prod: 100 lines fully replaced inline → single huge
+    // cluster of ~200 diff entries. With maxLines=10 the renderer must
+    // still emit ~10 leading body rows, not just the truncation footer.
+    const oldLines: string[] = [];
+    const newLines: string[] = [];
+    for (let i = 1; i <= 100; i++) {
+      oldLines.push(`old${String(i)}`);
+      newLines.push(`new${String(i)}`);
+    }
+    const out = renderDiffLinesClustered(
+      oldLines.join('\n'),
+      newLines.join('\n'),
+      'big.ts',
+      COLORS,
+      {
+        contextLines: 3,
+        maxLines: 10,
+      },
+    );
+    // header + 10 body rows + truncation footer
+    expect(out.length).toBe(12);
+    const text = stripAnsi(out.join('\n'));
+    expect(text).toContain('+100');
+    expect(text).toContain('-100');
+    expect(text).toMatch(/old\d+|new\d+/);
+    expect(text).toContain('ctrl+o to expand');
+  });
+
+  it('truncates at cluster boundary and appends the ctrl+o footer when maxLines is set', () => {
+    const oldLines: string[] = [];
+    for (let i = 1; i <= 50; i++) oldLines.push(`L${String(i)}`);
+    const newLines = oldLines.slice();
+    newLines[1] = 'L2X';
+    newLines[20] = 'L21X';
+    newLines[40] = 'L41X';
+    const text = stripAnsi(
+      renderDiffLinesClustered(oldLines.join('\n'), newLines.join('\n'), 'f.ts', COLORS, {
+        contextLines: 2,
+        maxLines: 6,
+      }).join('\n'),
+    );
+    expect(text).toContain('L2X');
+    expect(text).toMatch(/more change/);
+    expect(text).toContain('ctrl+o to expand');
+    expect(text).not.toContain('L41X');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/messages/assistant-message.test.ts b/apps/kimi-code/test/tui/components/messages/assistant-message.test.ts
new file mode 100644
index 000000000..47d0836a9
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/messages/assistant-message.test.ts
@@ -0,0 +1,53 @@
+import { visibleWidth } from '@earendil-works/pi-tui';
+import { describe, expect, it } from 'vitest';
+
+import { AssistantMessageComponent } from '#/tui/components/messages/assistant-message';
+import { STATUS_BULLET } from '#/tui/constant/symbols';
+import { darkColors } from '#/tui/theme/colors';
+import { createMarkdownTheme } from '#/tui/theme/pi-tui-theme';
+
+import { captureProcessWrite } from '../../../helpers/process';
+
+function strip(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+describe('AssistantMessageComponent', () => {
+  it('defines the shared status bullet as a stable non-emoji glyph', () => {
+    expect(STATUS_BULLET).toBe('● ');
+    expect(visibleWidth(STATUS_BULLET)).toBe(2);
+  });
+
+  it('uses the stable status bullet without stealing content width', () => {
+    const component = new AssistantMessageComponent(createMarkdownTheme(darkColors), darkColors);
+
+    component.updateContent('abcdef');
+
+    const lines = component.render(8).map(strip);
+    expect(lines).toEqual(['', `${STATUS_BULLET}abcdef`]);
+    expect(visibleWidth(lines[1] ?? '')).toBe(8);
+  });
+
+  it('renders unknown markdown fence languages as plain text without stderr noise', () => {
+    const stderr = captureProcessWrite('stderr');
+    try {
+      const theme = createMarkdownTheme(darkColors);
+      expect(theme.highlightCode?.('hello\nworld', 'abcxyz')).toEqual(['hello', 'world']);
+      expect(stderr.text()).not.toContain('Could not find the language');
+    } finally {
+      stderr.restore();
+    }
+  });
+
+  it('preserves literal hook result XML in normal assistant text', () => {
+    const component = new AssistantMessageComponent(createMarkdownTheme(darkColors), darkColors);
+
+    component.updateContent('<hook_result hook_event="UserPromptSubmit">\n{}\n</hook_result>');
+
+    const text = component.render(80).map(strip).join('\n');
+    expect(text).toContain('<hook_result hook_event="UserPromptSubmit">');
+    expect(text).toContain('{}');
+    expect(text).toContain('</hook_result>');
+    expect(text).not.toContain('UserPromptSubmit hook');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/messages/background-agent-status.test.ts b/apps/kimi-code/test/tui/components/messages/background-agent-status.test.ts
new file mode 100644
index 000000000..89def6690
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/messages/background-agent-status.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+
+import { BackgroundAgentStatusComponent } from '#/tui/components/messages/background-agent-status';
+import { STATUS_BULLET } from '#/tui/constant/symbols';
+import { darkColors } from '#/tui/theme/colors';
+
+function strip(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+describe('BackgroundAgentStatusComponent', () => {
+  it('renders started/completed with the shared bullet and failed with a red x marker', () => {
+    const started = new BackgroundAgentStatusComponent(
+      {
+        phase: 'started',
+        headline: 'explore agent started in background',
+        detail: 'Explore project structure',
+      },
+      darkColors,
+    );
+    const completed = new BackgroundAgentStatusComponent(
+      {
+        phase: 'completed',
+        headline: 'explore agent completed in background',
+        detail: 'Explore project structure',
+      },
+      darkColors,
+    );
+    const failed = new BackgroundAgentStatusComponent(
+      {
+        phase: 'failed',
+        headline: 'explore agent failed in background',
+        detail: 'Explore project structure · boom',
+      },
+      darkColors,
+    );
+
+    const startedLines = started.render(120).map((line) => strip(line).trimEnd());
+    const completedLines = completed.render(120).map((line) => strip(line).trimEnd());
+    const failedLines = failed.render(120).map((line) => strip(line).trimEnd());
+
+    expect(startedLines[0]).toBe('');
+    expect(completedLines[0]).toBe('');
+    expect(failedLines[0]).toBe('');
+
+    expect(startedLines[1]).toBe(
+      `${STATUS_BULLET}explore agent started in background (Explore project structure)`,
+    );
+    expect(completedLines[1]).toBe(
+      `${STATUS_BULLET}explore agent completed in background (Explore project structure)`,
+    );
+    expect(failedLines[1]).toBe(
+      '✗ explore agent failed in background (Explore project structure · boom)',
+    );
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/messages/notice.test.ts b/apps/kimi-code/test/tui/components/messages/notice.test.ts
new file mode 100644
index 000000000..a7a9f05e3
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/messages/notice.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+
+import { NoticeMessageComponent } from '#/tui/components/messages/status-message';
+import { darkColors } from '#/tui/theme/colors';
+
+function strip(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+describe('NoticeComponent', () => {
+  it('renders top and bottom spacing around the notice copy', () => {
+    const component = new NoticeMessageComponent(
+      'Plan mode: ON',
+      'Plan will be created here: /tmp/plans/test-plan.md',
+      darkColors,
+    );
+
+    const lines = component.render(120).map((line) => strip(line));
+    expect(lines[0]).toBe('');
+    expect(lines[1]).toContain('Plan mode: ON');
+    expect(lines[2]).toContain('Plan will be created here: /tmp/plans/test-plan.md');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/messages/shell-execution.test.ts b/apps/kimi-code/test/tui/components/messages/shell-execution.test.ts
new file mode 100644
index 000000000..86e31ded1
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/messages/shell-execution.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+
+import { ShellExecutionComponent } from '#/tui/components/messages/shell-execution';
+import { darkColors } from '#/tui/theme/colors';
+
+function strip(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+describe('ShellExecutionComponent', () => {
+  it('renders shell command previews with prompt indentation', () => {
+    const component = new ShellExecutionComponent({
+      command: 'printf hello\nprintf world',
+      colors: darkColors,
+      showCommand: true,
+    });
+
+    const output = component.render(100).map((line) => strip(line).trimEnd());
+
+    expect(output).toContain('  $ printf hello');
+    expect(output).toContain('    printf world');
+  });
+
+  it('keeps collapsed shell output short and expands on demand', () => {
+    const collapsed = new ShellExecutionComponent({
+      result: {
+        tool_call_id: 'call_shell',
+        output: ['line1', 'line2', 'line3', 'line4', 'line5'].join('\n'),
+        is_error: false,
+      },
+      colors: darkColors,
+    });
+
+    const collapsedOutput = collapsed.render(100).map(strip).join('\n');
+    expect(collapsedOutput).toContain('line1');
+    expect(collapsedOutput).toContain('line3');
+    expect(collapsedOutput).not.toContain('line4');
+    expect(collapsedOutput).toContain('... (2 more lines, ctrl+o to expand)');
+
+    const expanded = new ShellExecutionComponent({
+      result: {
+        tool_call_id: 'call_shell',
+        output: ['line1', 'line2', 'line3', 'line4', 'line5'].join('\n'),
+        is_error: false,
+      },
+      colors: darkColors,
+      expanded: true,
+    });
+
+    const expandedOutput = expanded.render(100).map(strip).join('\n');
+    expect(expandedOutput).toContain('line4');
+    expect(expandedOutput).toContain('line5');
+    expect(expandedOutput).not.toContain('ctrl+o to expand');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/messages/status-panel.test.ts b/apps/kimi-code/test/tui/components/messages/status-panel.test.ts
new file mode 100644
index 000000000..0fec0bddf
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/messages/status-panel.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildStatusReportLines } from '#/tui/components/messages/status-panel';
+import { darkColors } from '#/tui/theme/colors';
+
+function strip(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+describe('status panel report lines', () => {
+  it('formats runtime status, context, and managed usage without account or AGENTS.md rows', () => {
+    const lines = buildStatusReportLines({
+      colors: darkColors,
+      version: '1.2.3',
+      model: 'k2',
+      workDir: '/tmp/project',
+      sessionId: 'ses-1',
+      sessionTitle: 'Implement status',
+      thinking: true,
+      permissionMode: 'manual',
+      planMode: false,
+      contextUsage: 0.25,
+      contextTokens: 2500,
+      maxContextTokens: 10000,
+      availableModels: {
+        k2: {
+          provider: 'managed:kimi-code',
+          model: 'kimi-k2',
+          maxContextSize: 10000,
+          displayName: 'Kimi K2',
+        },
+      },
+      status: {
+        model: 'k2',
+        thinkingLevel: 'high',
+        permission: 'auto',
+        planMode: true,
+        contextTokens: 3000,
+        maxContextTokens: 12000,
+        contextUsage: 0.25,
+      },
+      managedUsage: {
+        summary: null,
+        limits: [
+          {
+            label: '5h limit',
+            used: 8,
+            limit: 100,
+            resetHint: 'resets in 1h',
+          },
+        ],
+      },
+    }).map(strip);
+
+    const output = lines.join('\n');
+    expect(output).toContain('>_ Kimi Code (v1.2.3)');
+    expect(output).toContain('Model        Kimi K2 (thinking on)');
+    expect(output).toContain('Directory    /tmp/project');
+    expect(output).toContain('Permissions  auto');
+    expect(output).toContain('Plan mode    on');
+    expect(output).toContain('Session      ses-1');
+    expect(output).toContain('Title        Implement status');
+    expect(output).toContain('Context window');
+    expect(output).toContain('25.0%');
+    expect(output).toContain('(3.0k / 12.0k)');
+    expect(output).toContain('Plan usage');
+    expect(output).toContain('92% left');
+    expect(output).not.toContain('Account');
+    expect(output).not.toContain('AGENTS.md');
+    expect(output).not.toContain('Runtime');
+  });
+
+  it('falls back to app state and shows status load errors as warnings', () => {
+    const lines = buildStatusReportLines({
+      colors: darkColors,
+      version: '1.2.3',
+      model: '',
+      workDir: '/tmp/project',
+      sessionId: '',
+      sessionTitle: null,
+      thinking: false,
+      permissionMode: 'manual',
+      planMode: false,
+      contextUsage: 0,
+      contextTokens: 0,
+      maxContextTokens: 0,
+      availableModels: {},
+      statusError: 'No active session',
+    }).map(strip);
+
+    const output = lines.join('\n');
+    expect(output).toContain('Model        not set');
+    expect(output).toContain('Session      none');
+    expect(output).toContain('Warning      No active session');
+    expect(output).toContain('No context window data available.');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/messages/thinking.test.ts b/apps/kimi-code/test/tui/components/messages/thinking.test.ts
new file mode 100644
index 000000000..9aa0688a8
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/messages/thinking.test.ts
@@ -0,0 +1,82 @@
+import type { TUI } from '@earendil-works/pi-tui';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ThinkingComponent } from '#/tui/components/messages/thinking';
+import { STATUS_BULLET } from '#/tui/constant/symbols';
+import { darkColors } from '#/tui/theme/colors';
+
+function strip(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+const longThinking = ['line1', 'line2', 'line3', 'line4', 'line5', 'line6', 'line7'].join('\n');
+
+describe('ThinkingComponent', () => {
+  it('shows the live spinner header before thinking content', () => {
+    const component = new ThinkingComponent('working it out', darkColors, true, 'live');
+    const out = strip(component.render(80).join('\n'));
+
+    expect(out).toContain('⠋ thinking...');
+    expect(out).not.toContain('  ⠋ thinking...');
+    expect(out).not.toContain(`${STATUS_BULLET}⠋`);
+    expect(out).toContain('  working it out');
+  });
+
+  it('keeps live thinking height-limited to the tail', () => {
+    const component = new ThinkingComponent(longThinking, darkColors, true, 'live');
+    const out = strip(component.render(80).join('\n'));
+
+    expect(out).not.toContain('line1');
+    expect(out).not.toContain('line4');
+    expect(out).toContain('line5');
+    expect(out).toContain('line7');
+    expect(out).not.toContain('ctrl+o to expand');
+  });
+
+  it('animates the live spinner and stops on finalize', () => {
+    vi.useFakeTimers();
+    const requestRender = vi.fn();
+    const component = new ThinkingComponent('step', darkColors, true, 'live', {
+      requestRender,
+    } as unknown as TUI);
+
+    expect(strip(component.render(80).join('\n'))).toContain('⠋ thinking...');
+
+    vi.advanceTimersByTime(80);
+    expect(requestRender).toHaveBeenCalled();
+    expect(strip(component.render(80).join('\n'))).toContain('⠙ thinking...');
+
+    component.finalize();
+    requestRender.mockClear();
+    vi.advanceTimersByTime(160);
+    expect(requestRender).not.toHaveBeenCalled();
+    vi.useRealTimers();
+  });
+
+  it('finalizes in place into a collapsed preview', () => {
+    const component = new ThinkingComponent(longThinking, darkColors, true, 'live');
+
+    component.finalize();
+
+    const out = strip(component.render(80).join('\n'));
+    expect(out).toContain('line1');
+    expect(out).toContain('line3');
+    expect(out).not.toContain('line4');
+    expect(out).toContain('... (4 more lines, ctrl+o to expand)');
+  });
+
+  it('expands and collapses after finalization', () => {
+    const component = new ThinkingComponent(longThinking, darkColors, true, 'live');
+    component.finalize();
+
+    component.setExpanded(true);
+    const expanded = strip(component.render(80).join('\n'));
+    expect(expanded).toContain('line7');
+    expect(expanded).not.toContain('ctrl+o to expand');
+
+    component.setExpanded(false);
+    const collapsed = strip(component.render(80).join('\n'));
+    expect(collapsed).not.toContain('line7');
+    expect(collapsed).toContain('ctrl+o to expand');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/messages/tool-call.test.ts b/apps/kimi-code/test/tui/components/messages/tool-call.test.ts
new file mode 100644
index 000000000..a71c6619b
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/messages/tool-call.test.ts
@@ -0,0 +1,1068 @@
+import type { TUI } from '@earendil-works/pi-tui';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { ToolCallComponent } from '#/tui/components/messages/tool-call';
+import { STATUS_BULLET } from '#/tui/constant/symbols';
+import { darkColors } from '#/tui/theme/colors';
+import { createMarkdownTheme } from '#/tui/theme/pi-tui-theme';
+
+import { captureProcessWrite } from '../../../helpers/process';
+
+const ESC = String.fromCodePoint(0x1b);
+const BEL = String.fromCodePoint(0x07);
+
+function strip(text: string): string {
+  return text
+    .replaceAll(/\u001B\[[0-9;]*m/g, '')
+    .replaceAll(new RegExp(`${ESC}\\]8;;[^${BEL}]*${BEL}`, 'g'), '');
+}
+
+function stubTui(rows: number): TUI {
+  return {
+    terminal: { rows },
+    requestRender: () => {},
+  } as unknown as TUI;
+}
+
+describe('ToolCallComponent', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('uses the shared non-emoji tool status bullet', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_read_marker',
+        name: 'Read',
+        args: { path: 'foo.ts' },
+      },
+      {
+        tool_call_id: 'call_read_marker',
+        output: 'content',
+        is_error: false,
+      },
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain(`${STATUS_BULLET}Used Read`);
+    expect(out).not.toContain(`\u23FA Used Read`);
+    expect(out).not.toContain(`${String.fromCodePoint(0x23fa, 0xfe0e)} Used Read`);
+  });
+
+  it('keeps collapsed tool results short and expands on demand', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_shell',
+        name: 'Bash',
+        args: { command: 'printf output' },
+      },
+      {
+        tool_call_id: 'call_shell',
+        output: ['line1', 'line2', 'line3', 'line4', 'line5'].join('\n'),
+        is_error: false,
+      },
+      darkColors,
+    );
+
+    const collapsed = strip(component.render(100).join('\n'));
+    expect(collapsed).toContain('line1');
+    expect(collapsed).toContain('line2');
+    expect(collapsed).toContain('line3');
+    expect(collapsed).not.toContain('line4');
+    expect(collapsed).toContain('... (2 more lines, ctrl+o to expand)');
+
+    component.setExpanded(true);
+
+    const expanded = strip(component.render(100).join('\n'));
+    expect(expanded).toContain('line4');
+    expect(expanded).toContain('line5');
+    expect(expanded).not.toContain('ctrl+o to expand');
+  });
+
+  it('hides tool output bodies that start with a <system tag', () => {
+    const reminderOutput =
+      '<system-reminder>\nThe task tools have not been used recently.\n</system-reminder>';
+    const component = new ToolCallComponent(
+      {
+        id: 'call_hidden',
+        name: 'Bash',
+        args: { command: 'echo hi' },
+      },
+      {
+        tool_call_id: 'call_hidden',
+        output: reminderOutput,
+        is_error: false,
+      },
+      darkColors,
+    );
+
+    const collapsed = strip(component.render(100).join('\n'));
+    expect(collapsed).toContain(`${STATUS_BULLET}Used Bash`);
+    expect(collapsed).not.toContain('system-reminder');
+    expect(collapsed).not.toContain('task tools');
+
+    component.setExpanded(true);
+    const expanded = strip(component.render(100).join('\n'));
+    expect(expanded).not.toContain('system-reminder');
+    expect(expanded).not.toContain('task tools');
+  });
+
+  it('hides <system-prefixed output even when the tool result is an error', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_hidden_err',
+        name: 'Bash',
+        args: { command: 'false' },
+      },
+      {
+        tool_call_id: 'call_hidden_err',
+        output: '<system-reminder>do not show</system-reminder>',
+        is_error: true,
+      },
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).not.toContain('system-reminder');
+    expect(out).not.toContain('do not show');
+  });
+
+  it('still renders tool output when the body merely contains <system later on', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_inline',
+        name: 'Bash',
+        args: { command: 'echo hi' },
+      },
+      {
+        tool_call_id: 'call_inline',
+        output: 'first line\n<system-reminder>nope</system-reminder>',
+        is_error: false,
+      },
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('first line');
+  });
+
+  it('renders ExitPlanMode plan from result output when args.plan is absent', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_exit',
+        name: 'ExitPlanMode',
+        args: {},
+      },
+      {
+        tool_call_id: 'call_exit',
+        output:
+          'Exited plan mode. Plan mode deactivated. All tools are now available.\n' +
+          'Plan saved to: /tmp/plan.md\n\n' +
+          '## Approved Plan:\n# File Plan\n\n1. Do the focused fix.',
+        is_error: false,
+      },
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('Current plan');
+    expect(out).toContain('# File Plan');
+    expect(out).toContain('1. Do the focused fix.');
+    expect(out).not.toContain('Plan saved to: /tmp/plan.md');
+  });
+
+  it('setPlanInfo injects plan body when args.plan is empty (plan-file mode)', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_exit_async',
+        name: 'ExitPlanMode',
+        args: {},
+      },
+      undefined,
+      darkColors,
+      undefined,
+      createMarkdownTheme(darkColors),
+    );
+
+    // A fresh tool card only shows the 'Current plan' title; no plan box renders yet.
+    const before = strip(component.render(100).join('\n'));
+    expect(before).toContain('Current plan');
+    expect(before).not.toContain('Refactor session');
+
+    component.setPlanInfo({ plan: '# Refactor session\n\n- step', path: '/tmp/refactor.md' });
+
+    const after = strip(component.render(100).join('\n'));
+    expect(after).toContain('Refactor session');
+    expect(after).toContain('plan:');
+    expect(after).toContain('refactor.md');
+    // Directory portion of the path must not leak into the visible header.
+    expect(after).not.toContain('/tmp/refactor.md');
+  });
+
+  it('caps the plan preview to the terminal height and expands on ctrl+e', () => {
+    const longPlan = `# Refactor session\n\n${Array.from({ length: 40 }, (_, i) => `- step ${String(i + 1)}`).join('\n')}`;
+    const component = new ToolCallComponent(
+      {
+        id: 'call_exit_long',
+        name: 'ExitPlanMode',
+        args: { plan: longPlan },
+      },
+      undefined,
+      darkColors,
+      stubTui(24),
+      createMarkdownTheme(darkColors),
+    );
+
+    const collapsed = strip(component.render(100).join('\n'));
+    expect(collapsed).toContain('step 1');
+    expect(collapsed).toMatch(/\.\.\. \(\d+ more lines, ctrl\+e to expand\)/);
+    expect(collapsed).not.toContain('step 40');
+
+    expect(component.setPlanExpanded(true)).toBe(true);
+    const expanded = strip(component.render(100).join('\n'));
+    expect(expanded).toContain('step 40');
+    expect(expanded).not.toContain('ctrl+e to expand');
+  });
+
+  it('plan preview controls are no-ops for non-ExitPlanMode tool calls', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_bash_plan',
+        name: 'Bash',
+        args: { command: 'echo hi' },
+      },
+      undefined,
+      darkColors,
+      undefined,
+      createMarkdownTheme(darkColors),
+    );
+
+    expect(component.setPlanExpanded(true)).toBe(false);
+    component.setPlanInfo({ plan: 'should be ignored', path: '/etc/hosts' });
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).not.toContain('should be ignored');
+    expect(out).not.toContain('plan:');
+  });
+
+  it('ctrl+o does not affect the plan preview cap', () => {
+    const longPlan = `# P\n\n${Array.from({ length: 40 }, (_, i) => `- step ${String(i + 1)}`).join('\n')}`;
+    const component = new ToolCallComponent(
+      {
+        id: 'call_exit_isolation',
+        name: 'ExitPlanMode',
+        args: { plan: longPlan },
+      },
+      undefined,
+      darkColors,
+      stubTui(24),
+      createMarkdownTheme(darkColors),
+    );
+    component.setExpanded(true);
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('ctrl+e to expand');
+    expect(out).not.toContain('step 40');
+  });
+
+  it('header chips an Approved status when ExitPlanMode result indicates approval', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_exit_approved',
+        name: 'ExitPlanMode',
+        args: {},
+      },
+      {
+        tool_call_id: 'call_exit_approved',
+        output:
+          'Exited plan mode. Plan mode deactivated. All tools are now available.\n' +
+          'Plan saved to: /tmp/plan.md\n\n' +
+          '## Approved Plan:\n# Plan body',
+        is_error: false,
+      },
+      darkColors,
+    );
+
+    const header = strip(component.render(100).join('\n')).split('\n')[1] ?? '';
+    expect(header).toMatch(/Current plan · Approved\s*$/);
+  });
+
+  it('header chips approved option label when the user picked one', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_exit_chosen',
+        name: 'ExitPlanMode',
+        args: {},
+      },
+      {
+        tool_call_id: 'call_exit_chosen',
+        output:
+          'Exited plan mode. Selected approach: Pragmatic refactor\n' +
+          'Execute ONLY the selected approach. Do not execute any unselected alternatives.\n\n' +
+          'Plan mode deactivated. All tools are now available.\n' +
+          'Plan saved to: /tmp/plan.md\n\n' +
+          '## Approved Plan:\n# body',
+        is_error: false,
+      },
+      darkColors,
+    );
+
+    const header = strip(component.render(100).join('\n')).split('\n')[1] ?? '';
+    expect(header).toContain('Current plan · Approved: Pragmatic refactor');
+  });
+
+  it('header chips Rejected and renders feedback for reject-with-suggestion', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_exit_reject_fb',
+        name: 'ExitPlanMode',
+        args: {},
+      },
+      {
+        tool_call_id: 'call_exit_reject_fb',
+        output: 'User rejected the plan. Feedback:\n\nplease rethink step 2',
+        is_error: false,
+      },
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('Current plan · Rejected');
+    expect(out).toContain('↪ Suggestion');
+    expect(out).toContain('please rethink step 2');
+  });
+
+  it('header chips Rejected without feedback when user rejected outright', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_exit_reject',
+        name: 'ExitPlanMode',
+        args: {},
+      },
+      {
+        tool_call_id: 'call_exit_reject',
+        output: 'Plan rejected by user. Plan mode remains active.',
+        is_error: false,
+      },
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('Current plan · Rejected');
+    expect(out).not.toContain('Plan mode remains active.');
+  });
+
+  it('suppresses EnterPlanMode success body so prompt scaffolding does not leak into the transcript', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_enter',
+        name: 'EnterPlanMode',
+        args: { reason: 'plan a refactor' },
+      },
+      {
+        tool_call_id: 'call_enter',
+        output:
+          'Plan mode is now active. Your workflow:\n\n' +
+          'Plan file: /tmp/plan.md\n\n' +
+          '1. Use read-only tools (Read, Grep, Glob) to investigate the codebase.\n' +
+          '2. Design a concrete, step-by-step plan.\n' +
+          '3. Write the plan to the plan file with Write or Edit.\n' +
+          '4. When the plan is ready, call ExitPlanMode for user approval.\n\n' +
+          'Do NOT edit files other than the plan file while plan mode is active.',
+        is_error: false,
+      },
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('Used EnterPlanMode');
+    expect(out).not.toContain('Plan mode is now active');
+    expect(out).not.toContain('Plan file:');
+    expect(out).not.toContain('read-only tools');
+  });
+
+  it('still surfaces EnterPlanMode error output', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_enter_err',
+        name: 'EnterPlanMode',
+        args: {},
+      },
+      {
+        tool_call_id: 'call_enter_err',
+        output: 'Plan mode is already active. Use ExitPlanMode when the plan is ready.',
+        is_error: true,
+      },
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('Plan mode is already active');
+  });
+
+  it('renders AskUserQuestion with a friendly header instead of the raw tool name', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_question',
+        name: 'AskUserQuestion',
+        args: {},
+      },
+      {
+        tool_call_id: 'call_question',
+        output: JSON.stringify({
+          answers: {
+            'Favorite editor?': 'Vim',
+          },
+        }),
+        is_error: false,
+      },
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('Collected your answers');
+    expect(out).toContain('Favorite editor?');
+    expect(out).toContain('Vim');
+    expect(out).not.toContain('AskUserQuestion');
+  });
+
+  it('appends a chip to the header once a result arrives', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_read',
+        name: 'Read',
+        args: { path: 'foo.ts' },
+      },
+      {
+        tool_call_id: 'call_read',
+        output: '1\tfoo\n2\tbar\n3\tbaz',
+        is_error: false,
+      },
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('Used Read');
+    expect(out).toContain('· 3 lines');
+  });
+
+  it('truncates a long file path from the head so the filename stays visible', () => {
+    const longPath =
+      'apps/kimi-code/src/tui/components/messages/tool-renderers/long-path/example/final-file.ts';
+    const component = new ToolCallComponent(
+      {
+        id: 'call_long_path',
+        name: 'Read',
+        args: { path: longPath },
+      },
+      undefined,
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('final-file.ts');
+    expect(out).toContain('…');
+    expect(out).not.toContain('apps/kimi-code/src/tui/components/messages/tool-renderers/long-pa…');
+  });
+
+  it('shows Read paths relative to the active workspace', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_workspace_read',
+        name: 'Read',
+        args: { path: '/tmp/proj-a/apps/kimi-code/src/main.ts' },
+      },
+      {
+        tool_call_id: 'call_workspace_read',
+        output: '1\tcontent',
+        is_error: false,
+      },
+      darkColors,
+      undefined,
+      undefined,
+      '/tmp/proj-a',
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('Used Read (apps/kimi-code/src/main.ts)');
+    expect(out).not.toContain('/tmp/proj-a/apps');
+    expect(component.getReadSnapshot().filePath).toBe('apps/kimi-code/src/main.ts');
+  });
+
+  it('keeps Read paths outside the active workspace absolute', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_external_read',
+        name: 'Read',
+        args: { path: '/tmp/proj-ab/src/main.ts' },
+      },
+      undefined,
+      darkColors,
+      undefined,
+      undefined,
+      '/tmp/proj-a',
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('Using Read (/tmp/proj-ab/src/main.ts)');
+    expect(component.getReadSnapshot().filePath).toBe('/tmp/proj-ab/src/main.ts');
+  });
+
+  it('does not append a chip while a tool is still running', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_pending',
+        name: 'Read',
+        args: { path: 'foo.ts' },
+      },
+      undefined,
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('Using Read');
+    expect(out).not.toContain('lines');
+  });
+
+  it('renders a single foreground subagent without the generic Agent tool header', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(10_000);
+    const component = new ToolCallComponent(
+      {
+        id: 'call_agent',
+        name: 'Agent',
+        args: { description: 'explore project xxx' },
+      },
+      undefined,
+      darkColors,
+    );
+
+    component.onSubagentSpawned({
+      agentId: 'sub_explore_123456',
+      agentName: 'explore',
+      runInBackground: false,
+    });
+
+    let out = strip(component.render(120).join('\n'));
+    expect(out).toContain('Explore Agent Starting (explore project xxx) · 0 tools · 0s');
+    expect(out).not.toContain('Using Agent');
+    expect(out).not.toContain('Used Agent');
+
+    vi.setSystemTime(20_000);
+    component.appendSubagentText('think1\nthink2\nthink3', 'thinking');
+    component.appendSubagentText('answer1\nanswer2\nanswer3', 'text');
+    component.appendSubToolCall({
+      id: 'sub_explore_123456:read',
+      name: 'Read',
+      args: { path: 'apps/kimi-code/src/tui/utils/background-agent-status.ts' },
+    });
+
+    out = strip(component.render(120).join('\n'));
+    expect(out).toContain('Explore Agent Running (explore project xxx) · 1 tool · 10s');
+    expect(out).toContain('Using Read (apps/kimi-code/src/tui/utils/background-agent-status.ts)');
+    expect(out).not.toContain('think1');
+    expect(out).not.toContain('think2');
+    expect(out).toContain('think3');
+    expect(out).toContain('◌ think3');
+    expect(out).not.toContain('answer1');
+    expect(out).not.toContain('answer2');
+    expect(out).toContain('answer3');
+    expect(out).toContain('└ answer3');
+
+    vi.setSystemTime(22_000);
+    component.onSubagentCompleted({ resultSummary: 'summary fallback' });
+    component.setResult({
+      tool_call_id: 'call_agent',
+      output: 'parent duplicate result',
+      is_error: false,
+    });
+    vi.setSystemTime(30_000);
+
+    out = strip(component.render(120).join('\n'));
+    expect(out).toContain('Explore Agent Completed (explore project xxx) · 1 tool · 12s');
+    expect(out).not.toContain('think3');
+    expect(out).toContain('└ answer3');
+    expect(out).not.toContain('Used Agent');
+    expect(out).not.toContain('parent duplicate result');
+    expect(out).not.toContain('summary fallback');
+  });
+
+  it('keeps the single subagent tool area to the latest four activities', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+    const component = new ToolCallComponent(
+      {
+        id: 'call_agent_tools',
+        name: 'Agent',
+        args: { description: 'inspect tools' },
+      },
+      undefined,
+      darkColors,
+    );
+    component.onSubagentSpawned({
+      agentId: 'sub_tools',
+      agentName: 'explore',
+      runInBackground: false,
+    });
+
+    for (let i = 1; i <= 4; i++) {
+      const id = `sub_tools:read-${String(i)}`;
+      component.appendSubToolCall({ id, name: 'Read', args: { path: `file${String(i)}.ts` } });
+      component.finishSubToolCall({ tool_call_id: id, output: 'ok', is_error: false });
+    }
+    component.appendSubToolCall({
+      id: 'sub_tools:grep',
+      name: 'Grep',
+      args: { pattern: 'auth' },
+    });
+
+    const out = strip(component.render(120).join('\n'));
+    expect(out).toContain('Explore Agent Running (inspect tools) · 5 tools · 0s');
+    expect(out).not.toContain('file1.ts');
+    expect(out).toContain('Used Read (file2.ts)');
+    expect(out).toContain('Used Read (file3.ts)');
+    expect(out).toContain('Used Read (file4.ts)');
+    expect(out).not.toContain('… Using Grep (auth)');
+    expect(out).toContain('• Using Grep (auth)');
+    expect(out).toContain('Using Grep (auth)');
+  });
+
+  it('keeps the single subagent tool window stable when older tools update', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+    const component = new ToolCallComponent(
+      {
+        id: 'call_agent_stable_tools',
+        name: 'Agent',
+        args: { description: 'inspect tools' },
+      },
+      undefined,
+      darkColors,
+    );
+    component.onSubagentSpawned({
+      agentId: 'sub_tools',
+      agentName: 'explore',
+      runInBackground: false,
+    });
+
+    for (let i = 1; i <= 5; i++) {
+      component.appendSubToolCall({
+        id: `sub_tools:read-${String(i)}`,
+        name: 'Read',
+        args: { path: `file${String(i)}.ts` },
+      });
+    }
+    component.appendSubToolCallDelta({
+      id: 'sub_tools:read-1',
+      name: 'Read',
+      argumentsPart: '{"path":"file1-updated.ts"}',
+    });
+    component.finishSubToolCall({
+      tool_call_id: 'sub_tools:read-1',
+      output: 'ok',
+      is_error: false,
+    });
+
+    const out = strip(component.render(120).join('\n'));
+    expect(out).not.toContain('file1-updated.ts');
+    expect(out).toContain('Using Read (file2.ts)');
+    expect(out).toContain('Using Read (file3.ts)');
+    expect(out).toContain('Using Read (file4.ts)');
+    expect(out).toContain('Using Read (file5.ts)');
+  });
+
+  it('wraps single subagent thinking and output with hanging indentation', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+    const component = new ToolCallComponent(
+      {
+        id: 'call_agent_wrapped_text',
+        name: 'Agent',
+        args: { description: 'inspect wrapping' },
+      },
+      undefined,
+      darkColors,
+    );
+    component.onSubagentSpawned({
+      agentId: 'sub_wrapped',
+      agentName: 'explore',
+      runInBackground: false,
+    });
+    component.appendSubagentText(
+      'thinking words that should wrap with a clean hanging indent',
+      'thinking',
+    );
+    component.appendSubagentText(
+      'output words that should also wrap with a clean hanging indent',
+      'text',
+    );
+
+    const lines = strip(component.render(34).join('\n')).split('\n');
+    expect(lines).toContain('  ◌ thinking words that should    ');
+    expect(lines).toContain('    wrap with a clean hanging     ');
+    expect(lines).toContain('    indent                        ');
+    expect(lines).toContain('  └ output words that should also ');
+    expect(lines).toContain('    wrap with a clean hanging     ');
+  });
+
+  it('renders failed single subagents with the dedicated header and error text', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1000);
+    const component = new ToolCallComponent(
+      {
+        id: 'call_agent_failed',
+        name: 'Agent',
+        args: { description: 'check failure' },
+      },
+      undefined,
+      darkColors,
+    );
+    component.onSubagentSpawned({
+      agentId: 'sub_failed',
+      agentName: 'explore',
+      runInBackground: false,
+    });
+
+    vi.setSystemTime(4000);
+    component.onSubagentFailed({ error: 'subagent exceeded max_steps' });
+
+    const out = strip(component.render(120).join('\n'));
+    expect(out).toContain('Explore Agent Failed (check failure) · 0 tools · 3s');
+    expect(out).toContain('└ subagent exceeded max_steps');
+    expect(out).not.toContain('Using Agent');
+    expect(out).not.toContain('Used Agent');
+  });
+
+  it('renders the full Write content during the streaming delta window (no cap)', () => {
+    const lines: string[] = [];
+    for (let i = 1; i <= 30; i++) lines.push(`line${String(i)}`);
+    const escaped = lines.join('\\n');
+    const component = new ToolCallComponent(
+      {
+        id: 'call_write_stream',
+        name: 'Write',
+        args: { file_path: 'foo.ts', content: lines.join('\n') },
+        streamingArguments: `{"file_path":"foo.ts","content":"${escaped}`,
+      },
+      undefined,
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('Using Write');
+    // All 30 lines must be present — no 10-line cap during streaming.
+    expect(out).toContain('line1');
+    expect(out).toContain('line25');
+    expect(out).toContain('line30');
+    expect(out).not.toContain('ctrl+o to expand');
+  });
+
+  it('switches a streaming tool call to Truncated when the step ended with max_tokens', () => {
+    const lines: string[] = [];
+    for (let i = 1; i <= 10; i++) lines.push(`line${String(i)}`);
+    const escaped = lines.join('\\n');
+    const component = new ToolCallComponent(
+      {
+        id: 'call_write_truncated',
+        name: 'Write',
+        args: { file_path: 'foo.ts', content: lines.join('\n') },
+        streamingArguments: `{"file_path":"foo.ts","content":"${escaped}`,
+        truncated: true,
+      },
+      undefined,
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('Truncated Write');
+    expect(out).not.toContain('Preparing Write');
+    expect(out).toContain('Tool call arguments truncated by max_tokens');
+    // The live argument preview must NOT render once the call is
+    // truncated — leaving the half-streamed Write content on screen
+    // was the original "preparing write" bug.
+    expect(out).not.toContain('line1');
+    expect(out).not.toContain('line10');
+  });
+
+  it('renders a stable Edit progress placeholder during the streaming delta window', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(4000);
+    const oldLines: string[] = [];
+    const newLines: string[] = [];
+    for (let i = 1; i <= 20; i++) {
+      oldLines.push(`old${String(i)}`);
+      newLines.push(`new${String(i)}`);
+    }
+    const oldEscaped = oldLines.join('\\n');
+    const newEscaped = newLines.join('\\n');
+    const streaming = `{"file_path":"foo.ts","old_string":"${oldEscaped}","new_string":"${newEscaped}`;
+    const component = new ToolCallComponent(
+      {
+        id: 'call_edit_stream',
+        name: 'Edit',
+        args: {
+          file_path: 'foo.ts',
+          old_string: oldLines.join('\n'),
+          new_string: newLines.join('\n'),
+        },
+        streamingArguments: streaming,
+        streamingStartedAtMs: 0,
+      },
+      undefined,
+      darkColors,
+    );
+
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('Using Edit');
+    expect(out).toContain('foo.ts');
+    expect(out).toContain('Preparing changes for foo.ts...');
+    expect(out).toContain('4s elapsed');
+    expect(out).toMatch(/\d+(?:\.\d+)? (?:B|KB|MB)/);
+    expect(out).not.toContain('old20');
+    expect(out).not.toContain('new20');
+    expect(out).not.toMatch(/^\s*\d+\s+[+-]\s/m);
+    expect(out).not.toContain('ctrl+o to expand');
+  });
+
+  it('keeps Write preview uncapped between finalized args and result (approval window)', () => {
+    // The wire sequence is: tool.call.delta → ... → tool.call (final
+    // args, no streamingArguments) → approval pending ... → tool.result.
+    // Between tool.call and tool.result the user may sit in an approval
+    // panel; the preview must stay fully visible during that gap, only
+    // collapsing once setResult fires (bullet turns green).
+    const lines: string[] = [];
+    for (let i = 1; i <= 30; i++) lines.push(`line${String(i)}`);
+    const component = new ToolCallComponent(
+      {
+        id: 'call_write_pending',
+        name: 'Write',
+        args: { file_path: 'foo.ts', content: lines.join('\n') },
+        // No streamingArguments → finalized args; no result yet.
+      },
+      undefined,
+      darkColors,
+    );
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('line1');
+    expect(out).toContain('line25');
+    expect(out).toContain('line30');
+    expect(out).not.toContain('ctrl+o to expand');
+  });
+
+  it('snaps a long Write preview to the collapsed cap when the result arrives', () => {
+    const lines: string[] = [];
+    for (let i = 1; i <= 30; i++) lines.push(`line${String(i)}`);
+    const escaped = lines.join('\\n');
+    const component = new ToolCallComponent(
+      {
+        id: 'call_write_snap',
+        name: 'Write',
+        args: { file_path: 'big.txt', content: lines.join('\n') },
+        streamingArguments: `{"file_path":"big.txt","content":"${escaped}"}`,
+      },
+      undefined,
+      darkColors,
+    );
+    expect(strip(component.render(100).join('\n'))).toContain('line25');
+
+    component.setResult({
+      tool_call_id: 'call_write_snap',
+      output: 'Wrote big.txt',
+      is_error: false,
+    });
+
+    const after = strip(component.render(100).join('\n'));
+    expect(after).toContain('line1');
+    expect(after).not.toContain('line25');
+    expect(after).toContain('ctrl+o to expand');
+  });
+
+  it('refreshes the header when file_path arrives in a later streaming delta', () => {
+    // First delta: only an opening brace, no file_path yet.
+    const component = new ToolCallComponent(
+      {
+        id: 'call_write_path',
+        name: 'Write',
+        args: {},
+        streamingArguments: '{',
+      },
+      undefined,
+      darkColors,
+    );
+    const before = strip(component.render(100).join('\n'));
+    expect(before).toContain('Using Write');
+    expect(before).not.toContain('foo.ts');
+
+    // Later delta: file_path is now parseable from streamingArguments.
+    component.updateToolCall({
+      id: 'call_write_path',
+      name: 'Write',
+      args: { file_path: 'foo.ts' },
+      streamingArguments: '{"file_path":"foo.ts","content":"hello',
+    });
+    const after = strip(component.render(100).join('\n'));
+    expect(after).toContain('foo.ts');
+  });
+
+  it('builds the call preview when finalized args arrive after streaming', () => {
+    // Mimic the wire sequence: tool.call.delta → ... → tool.call (finalized).
+    const component = new ToolCallComponent(
+      {
+        id: 'call_write_seq',
+        name: 'Write',
+        args: { file_path: 'foo.ts', content: 'a\nb' },
+        streamingArguments: '{"file_path":"foo.ts","content":"a\\nb',
+      },
+      undefined,
+      darkColors,
+    );
+    // While streaming, body is rendered live from streamingArguments.
+    expect(strip(component.render(100).join('\n'))).toMatch(/^\s*1\s+a\s*$/m);
+
+    // Finalized tool.call: streamingArguments is undefined; the body
+    // re-renders from finalized args, content unchanged.
+    component.updateToolCall({
+      id: 'call_write_seq',
+      name: 'Write',
+      args: { file_path: 'foo.ts', content: 'a\nb' },
+    });
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toMatch(/^\s*1\s+a\s*$/m);
+    expect(out).toMatch(/^\s*2\s+b\s*$/m);
+  });
+
+  it('builds the Edit diff when finalized args arrive after streaming', () => {
+    const component = new ToolCallComponent(
+      {
+        id: 'call_edit_seq',
+        name: 'Edit',
+        args: { file_path: 'foo.ts' },
+        streamingArguments: '{"file_path":"foo.ts","old_string":"a\\nb","new_string":"a\\nB',
+        streamingStartedAtMs: Date.now(),
+      },
+      undefined,
+      darkColors,
+    );
+    expect(strip(component.render(100).join('\n'))).toContain('Preparing changes');
+    expect(strip(component.render(100).join('\n'))).not.toMatch(/^\s*\d+\s+[+-]\s/m);
+
+    component.updateToolCall({
+      id: 'call_edit_seq',
+      name: 'Edit',
+      args: { file_path: 'foo.ts', old_string: 'a\nb', new_string: 'a\nB' },
+    });
+    const out = strip(component.render(100).join('\n'));
+    expect(out).toContain('foo.ts');
+    expect(out).toMatch(/^\s*2\s+- b\s*$/m);
+    expect(out).toMatch(/^\s*2\s+\+ B\s*$/m);
+  });
+
+  it('refreshes and stops the Edit streaming progress timer', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+    const ui = { requestRender: vi.fn() };
+    const component = new ToolCallComponent(
+      {
+        id: 'call_edit_timer',
+        name: 'Edit',
+        args: { file_path: 'foo.ts' },
+        streamingArguments: '{"file_path":"foo.ts","old_string":"a',
+        streamingStartedAtMs: 0,
+      },
+      undefined,
+      darkColors,
+      ui as never,
+    );
+
+    expect(strip(component.render(100).join('\n'))).toContain('0s elapsed');
+    vi.advanceTimersByTime(1000);
+    expect(ui.requestRender).toHaveBeenCalled();
+    expect(strip(component.render(100).join('\n'))).toContain('1s elapsed');
+
+    ui.requestRender.mockClear();
+    component.setResult({
+      tool_call_id: 'call_edit_timer',
+      output: 'Replaced 1 occurrence in foo.ts',
+      is_error: false,
+    });
+    vi.advanceTimersByTime(1000);
+    expect(ui.requestRender).not.toHaveBeenCalled();
+
+    const componentToDispose = new ToolCallComponent(
+      {
+        id: 'call_edit_dispose',
+        name: 'Edit',
+        args: { file_path: 'bar.ts' },
+        streamingArguments: '{"file_path":"bar.ts","old_string":"a',
+        streamingStartedAtMs: 0,
+      },
+      undefined,
+      darkColors,
+      ui as never,
+    );
+    ui.requestRender.mockClear();
+    componentToDispose.dispose();
+    vi.advanceTimersByTime(1000);
+    expect(ui.requestRender).not.toHaveBeenCalled();
+  });
+
+  it('expands the Write call preview when ctrl+o expansion is set', () => {
+    const lines: string[] = [];
+    for (let i = 1; i <= 30; i++) lines.push(`line${String(i)}`);
+    const component = new ToolCallComponent(
+      {
+        id: 'call_write_done',
+        name: 'Write',
+        args: { file_path: 'big.txt', content: lines.join('\n') },
+      },
+      {
+        tool_call_id: 'call_write_done',
+        output: 'Wrote big.txt',
+        is_error: false,
+      },
+      darkColors,
+    );
+
+    const collapsed = strip(component.render(100).join('\n'));
+    expect(collapsed).toContain('line1');
+    expect(collapsed).toContain('line10');
+    expect(collapsed).not.toContain('line25');
+    expect(collapsed).toContain('ctrl+o to expand');
+
+    component.setExpanded(true);
+
+    const expanded = strip(component.render(100).join('\n'));
+    expect(expanded).toContain('line25');
+    expect(expanded).toContain('line30');
+    expect(expanded).not.toContain('ctrl+o to expand');
+  });
+
+  it('renders unknown Write file extensions as plain text without stderr noise', () => {
+    const stderr = captureProcessWrite('stderr');
+    try {
+      const component = new ToolCallComponent(
+        {
+          id: 'call_write_unknown_ext',
+          name: 'Write',
+          args: { file_path: 'demo.abcxyz', content: 'hello\nworld' },
+        },
+        {
+          tool_call_id: 'call_write_unknown_ext',
+          output: 'Wrote demo.abcxyz',
+          is_error: false,
+        },
+        darkColors,
+      );
+
+      const collapsed = strip(component.render(100).join('\n'));
+      expect(collapsed).toContain('hello');
+
+      component.setExpanded(true);
+      const expanded = strip(component.render(100).join('\n'));
+      expect(expanded).toContain('world');
+      expect(stderr.text()).not.toContain('Could not find the language');
+    } finally {
+      stderr.restore();
+    }
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/messages/tool-renderers/chip.test.ts b/apps/kimi-code/test/tui/components/messages/tool-renderers/chip.test.ts
new file mode 100644
index 000000000..99d253af7
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/messages/tool-renderers/chip.test.ts
@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  computeEditStats,
+  computeWriteStats,
+  pickChip,
+} from '#/tui/components/messages/tool-renderers/chip';
+import type { ToolCallBlockData, ToolResultBlockData } from '#/tui/types';
+
+function strip(text: string): string {
+  return text.replaceAll(/\[[0-9;]*m/g, '');
+}
+
+function call(name: string, args: Record<string, unknown> = {}): ToolCallBlockData {
+  return { id: 'tc', name, args };
+}
+
+function result(output: string, isError = false): ToolResultBlockData {
+  return { tool_call_id: 'tc', output, is_error: isError };
+}
+
+function chipFor(name: string, args: Record<string, unknown>, out: ToolResultBlockData): string {
+  const provider = pickChip(name);
+  return strip(provider?.(call(name, args), out) ?? '');
+}
+
+describe('chip registry', () => {
+  it('Bash has no chip (exit code is not surfaced)', () => {
+    expect(pickChip('Bash')).toBeUndefined();
+  });
+
+  it('Edit chip shows +N -M from args diff', () => {
+    const c = chipFor(
+      'Edit',
+      { path: 'foo.ts', old_string: 'a\nb\nc', new_string: 'a\nB\nc\nd' },
+      result('Replaced 1 occurrence in foo.ts'),
+    );
+    expect(c).toMatch(/\+\d+/);
+    expect(c).toMatch(/-\d+/);
+  });
+
+  it('Write chip shows N lines from content arg', () => {
+    expect(chipFor('Write', { path: 'a.txt', content: 'a\nb\nc\n' }, result('Wrote a.txt'))).toBe(
+      '3 lines',
+    );
+  });
+
+  it('Read chip shows line count', () => {
+    expect(chipFor('Read', { path: 'a.ts' }, result('1\tfoo\n2\tbar\n3\tbaz'))).toBe('3 lines');
+  });
+
+  it('Read chip handles single line as singular', () => {
+    expect(chipFor('Read', { path: 'a.ts' }, result('1\tfoo'))).toBe('1 line');
+  });
+
+  it('Grep chip shows match count', () => {
+    expect(chipFor('Grep', { pattern: 'foo' }, result('a.ts\nb.ts\nc.ts'))).toBe('3 matches');
+  });
+
+  it('Grep chip says "no matches" on empty result', () => {
+    expect(chipFor('Grep', { pattern: 'foo' }, result(''))).toBe('no matches');
+  });
+
+  it('Glob chip shows file count', () => {
+    expect(chipFor('Glob', { pattern: '**/*.ts' }, result('a.ts\nb.ts'))).toBe('2 files');
+  });
+
+  it('FetchURL chip shows size and is non-empty', () => {
+    const out = chipFor('FetchURL', { url: 'https://example.com' }, result('hello world'));
+    expect(out).toMatch(/\d+\s*B/);
+  });
+
+  it('WebSearch chip shows result count', () => {
+    expect(chipFor('WebSearch', { query: 'kimi' }, result('1. Alpha\n2. Beta\n3. Gamma'))).toBe(
+      '3 results',
+    );
+  });
+
+  it('Think tool has no chip', () => {
+    expect(pickChip('Think')).toBeUndefined();
+  });
+
+  it('Unknown tools have no chip', () => {
+    expect(pickChip('SomethingElse')).toBeUndefined();
+  });
+});
+
+describe('computeWriteStats', () => {
+  it('returns zero lines for empty content', () => {
+    expect(computeWriteStats({})).toEqual({ lines: 0 });
+    expect(computeWriteStats({ content: '' })).toEqual({ lines: 0 });
+  });
+
+  it('counts a single line with no trailing newline', () => {
+    expect(computeWriteStats({ content: 'hello' })).toEqual({ lines: 1 });
+  });
+
+  it('ignores trailing newline so "a\\nb\\n" is 2 lines', () => {
+    expect(computeWriteStats({ content: 'a\nb\n' })).toEqual({ lines: 2 });
+    expect(computeWriteStats({ content: 'a\nb' })).toEqual({ lines: 2 });
+  });
+});
+
+describe('computeEditStats', () => {
+  it('returns zero when both strings are empty', () => {
+    expect(computeEditStats({})).toEqual({ added: 0, removed: 0 });
+    expect(computeEditStats({ old_string: '', new_string: '' })).toEqual({
+      added: 0,
+      removed: 0,
+    });
+  });
+
+  it('counts added and removed lines for a replacement', () => {
+    const stats = computeEditStats({ old_string: 'a\nb\nc', new_string: 'a\nB\nc\nd' });
+    expect(stats.added).toBeGreaterThan(0);
+    expect(stats.removed).toBeGreaterThan(0);
+  });
+
+  it('counts only adds when old is empty', () => {
+    const stats = computeEditStats({ old_string: '', new_string: 'x\ny\nz' });
+    expect(stats.added).toBe(3);
+    expect(stats.removed).toBe(0);
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/messages/tool-renderers/media.test.ts b/apps/kimi-code/test/tui/components/messages/tool-renderers/media.test.ts
new file mode 100644
index 000000000..ab4a53fd6
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/messages/tool-renderers/media.test.ts
@@ -0,0 +1,150 @@
+import type { Component } from '@earendil-works/pi-tui';
+import { describe, expect, it } from 'vitest';
+
+import {
+  parseReadMediaOutput,
+  readMediaChip,
+  readMediaSummary,
+} from '#/tui/components/messages/tool-renderers/media';
+import { darkColors } from '#/tui/theme/colors';
+import type { ToolCallBlockData, ToolResultBlockData } from '#/tui/types';
+
+function strip(text: string): string {
+  return text.replaceAll(/\[[0-9;]*m/g, '');
+}
+
+function joinRender(components: Component[], width = 100): string {
+  return components.flatMap((c) => c.render(width)).join('\n');
+}
+
+function call(name: string, args: Record<string, unknown> = {}): ToolCallBlockData {
+  return { id: 'tc', name, args };
+}
+
+function result(output: string, isError = false): ToolResultBlockData {
+  return { tool_call_id: 'tc', output, is_error: isError };
+}
+
+const ctx = { expanded: false, colors: darkColors };
+const expandedCtx = { expanded: true, colors: darkColors };
+
+// 1x1 transparent png base64 (≈70 bytes once decoded)
+const PNG_B64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=';
+const PNG_DATA_URL = `data:image/png;base64,${PNG_B64}`;
+
+function imageOutput(path: string, b64 = PNG_B64, mime = 'image/png'): string {
+  return JSON.stringify([
+    { type: 'text', text: `<image path="${path}">` },
+    { type: 'image_url', imageUrl: { url: `data:${mime};base64,${b64}` } },
+    { type: 'text', text: '</image>' },
+    { type: 'text', text: `Loaded image file "${path}" (${mime}, 70 bytes, original size 1x1px).` },
+  ]);
+}
+
+function videoOutput(path: string, mime = 'video/mp4'): string {
+  return JSON.stringify([
+    { type: 'text', text: `<video path="${path}">` },
+    { type: 'video_url', videoUrl: { url: `data:${mime};base64,YWJj` } },
+    { type: 'text', text: '</video>' },
+  ]);
+}
+
+describe('parseReadMediaOutput', () => {
+  it('extracts kind, path, mime type, and bytes from an image data URL', () => {
+    const m = parseReadMediaOutput(imageOutput('/tmp/a.png'));
+    expect(m).not.toBeNull();
+    expect(m?.kind).toBe('image');
+    expect(m?.path).toBe('/tmp/a.png');
+    expect(m?.mimeType).toBe('image/png');
+    expect(m?.bytes).toBeGreaterThan(0);
+    expect(m?.originalSize).toBe('1x1px');
+  });
+
+  it('extracts video kind and mime', () => {
+    const m = parseReadMediaOutput(videoOutput('/tmp/a.mp4'));
+    expect(m?.kind).toBe('video');
+    expect(m?.mimeType).toBe('video/mp4');
+  });
+
+  it('captures non-data video URL when uploader was used', () => {
+    const out = JSON.stringify([
+      { type: 'text', text: `<video path="/tmp/a.mp4">` },
+      { type: 'video_url', videoUrl: { url: 'https://cdn.example/v/abc' } },
+      { type: 'text', text: '</video>' },
+    ]);
+    const m = parseReadMediaOutput(out);
+    expect(m?.kind).toBe('video');
+    expect(m?.url).toBe('https://cdn.example/v/abc');
+    expect(m?.bytes).toBeUndefined();
+  });
+
+  it('returns null for non-JSON output', () => {
+    expect(parseReadMediaOutput('not json')).toBeNull();
+  });
+
+  it('returns null when no media part is present', () => {
+    expect(parseReadMediaOutput(JSON.stringify([{ type: 'text', text: 'hi' }]))).toBeNull();
+  });
+});
+
+describe('readMediaChip', () => {
+  it('returns a compact summary for an image', () => {
+    const text = strip(readMediaChip(call('ReadMediaFile'), result(imageOutput('/tmp/a.png'))));
+    expect(text).toMatch(/image/);
+    expect(text).toContain('image/png');
+    expect(text).toMatch(/B|KB|MB/);
+  });
+
+  it('returns empty string on error so the truncated body shows the error', () => {
+    expect(readMediaChip(call('ReadMediaFile'), result('boom', true))).toBe('');
+  });
+
+  it('returns empty string when output is unparseable', () => {
+    expect(readMediaChip(call('ReadMediaFile'), result('garbage'))).toBe('');
+  });
+});
+
+describe('readMediaSummary renderer', () => {
+  it('renders an empty body when collapsed (chip carries the info)', () => {
+    const out = joinRender(
+      readMediaSummary(call('ReadMediaFile'), result(imageOutput('/tmp/a.png')), ctx),
+    );
+    expect(out.trim()).toBe('');
+  });
+
+  it('renders path + meta line when expanded — never the base64 blob', () => {
+    const out = strip(
+      joinRender(
+        readMediaSummary(call('ReadMediaFile'), result(imageOutput('/tmp/a.png')), expandedCtx),
+      ),
+    );
+    expect(out).toContain('/tmp/a.png');
+    expect(out).toContain('image/png');
+    // Crucially: the base64 must never reach the screen.
+    expect(out).not.toContain(PNG_B64);
+    expect(out).not.toContain(PNG_DATA_URL);
+  });
+
+  it('falls back to truncated renderer for errors', () => {
+    const out = strip(
+      joinRender(
+        readMediaSummary(
+          call('ReadMediaFile', { path: '/tmp/x.png' }),
+          result('File not found', true),
+          ctx,
+        ),
+      ),
+    );
+    expect(out).toContain('File not found');
+  });
+
+  it('falls back to truncated renderer when the output is not the media envelope', () => {
+    const out = strip(
+      joinRender(
+        readMediaSummary(call('ReadMediaFile'), result('"some plain string output"'), ctx),
+      ),
+    );
+    expect(out).toContain('some plain string output');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/messages/tool-renderers/registry.test.ts b/apps/kimi-code/test/tui/components/messages/tool-renderers/registry.test.ts
new file mode 100644
index 000000000..aebe87435
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/messages/tool-renderers/registry.test.ts
@@ -0,0 +1,165 @@
+import type { Component } from '@earendil-works/pi-tui';
+import { describe, expect, it } from 'vitest';
+
+import { pickResultRenderer } from '#/tui/components/messages/tool-renderers/registry';
+import { darkColors } from '#/tui/theme/colors';
+import type { ToolCallBlockData, ToolResultBlockData } from '#/tui/types';
+
+function strip(text: string): string {
+  return text.replaceAll(/\[[0-9;]*m/g, '');
+}
+
+function joinRender(components: Component[], width = 100): string {
+  return components.flatMap((c) => c.render(width)).join('\n');
+}
+
+function call(name: string, args: Record<string, unknown> = {}): ToolCallBlockData {
+  return { id: 'tc', name, args };
+}
+
+function result(output: string, isError = false): ToolResultBlockData {
+  return { tool_call_id: 'tc', output, is_error: isError };
+}
+
+const ctx = { expanded: false, colors: darkColors };
+const expandedCtx = { expanded: true, colors: darkColors };
+
+describe('tool-result registry', () => {
+  it('falls back to truncated renderer for unknown tools', () => {
+    const renderer = pickResultRenderer('SomethingUnknown');
+    const out = strip(joinRender(renderer(call('SomethingUnknown'), result('a\nb\nc\nd\ne'), ctx)));
+    expect(out).toContain('a');
+    expect(out).toContain('b');
+    expect(out).toContain('c');
+    expect(out).not.toContain('\nd');
+    expect(out).toContain('... (2 more lines, ctrl+o to expand)');
+  });
+
+  it('uses truncated renderer for Bash to preserve raw output UX', () => {
+    const renderer = pickResultRenderer('Bash');
+    const out = strip(joinRender(renderer(call('Bash'), result('one\ntwo\nthree\nfour'), ctx)));
+    expect(out).toContain('one');
+    expect(out).toContain('... (1 more lines, ctrl+o to expand)');
+  });
+
+  it('Read renders no body when collapsed (header chip carries the count)', () => {
+    const renderer = pickResultRenderer('Read');
+    const out = joinRender(
+      renderer(call('Read', { path: 'foo.ts' }), result('1\tfoo\n2\tbar'), ctx),
+    );
+    expect(out.trim()).toBe('');
+  });
+
+  it('Read expands to the raw file content when expanded', () => {
+    const renderer = pickResultRenderer('Read');
+    const out = strip(
+      joinRender(renderer(call('Read', { path: 'foo.ts' }), result('1\tfoo\n2\tbar'), expandedCtx)),
+    );
+    expect(out).toContain('foo');
+    expect(out).toContain('bar');
+  });
+
+  it('Grep glance lists path samples below the chip', () => {
+    const renderer = pickResultRenderer('Grep');
+    const out = strip(
+      joinRender(
+        renderer(
+          call('Grep', { pattern: 'foo' }),
+          result('src/a.ts\nsrc/b.ts\nsrc/c.ts\nsrc/d.ts\nsrc/e.ts'),
+          ctx,
+        ),
+      ),
+    );
+    expect(out).toContain('src/a.ts');
+    expect(out).toContain('src/b.ts');
+    expect(out).toContain('src/c.ts');
+    expect(out).toContain('+2 more');
+    expect(out).not.toContain('src/d.ts');
+  });
+
+  it('Grep glance strips trailing :line:text in content mode', () => {
+    const renderer = pickResultRenderer('Grep');
+    const out = strip(
+      joinRender(
+        renderer(
+          call('Grep', { pattern: 'foo' }),
+          result('src/a.ts:42:    foo()\nsrc/b.ts:7:foo'),
+          ctx,
+        ),
+      ),
+    );
+    expect(out).toContain('src/a.ts:42');
+    expect(out).not.toContain('foo()');
+  });
+
+  it('Grep with empty result renders nothing in collapsed state', () => {
+    const renderer = pickResultRenderer('Grep');
+    const out = joinRender(renderer(call('Grep', { pattern: 'foo' }), result(''), ctx));
+    expect(out.trim()).toBe('');
+  });
+
+  it('Glob glance lists path samples', () => {
+    const renderer = pickResultRenderer('Glob');
+    const out = strip(
+      joinRender(
+        renderer(call('Glob', { pattern: '**/*.ts' }), result('a.ts\nb.ts\nc.ts\nd.ts'), ctx),
+      ),
+    );
+    expect(out).toContain('a.ts');
+    expect(out).toContain('b.ts');
+    expect(out).toContain('c.ts');
+    expect(out).toContain('+1 more');
+  });
+
+  it('FetchURL renders no body when collapsed', () => {
+    const renderer = pickResultRenderer('FetchURL');
+    const out = joinRender(
+      renderer(call('FetchURL', { url: 'https://example.com/x' }), result('<body>...'), ctx),
+    );
+    expect(out.trim()).toBe('');
+  });
+
+  it('WebSearch renders no body when collapsed', () => {
+    const renderer = pickResultRenderer('WebSearch');
+    const out = joinRender(
+      renderer(call('WebSearch', { query: 'kimi' }), result('1. Alpha\n2. Beta'), ctx),
+    );
+    expect(out.trim()).toBe('');
+  });
+
+  it('Edit renders no body when collapsed', () => {
+    const renderer = pickResultRenderer('Edit');
+    const out = joinRender(
+      renderer(
+        call('Edit', { path: 'foo.ts', old_string: 'a', new_string: 'b' }),
+        result('Replaced 1 occurrence in foo.ts'),
+        ctx,
+      ),
+    );
+    expect(out.trim()).toBe('');
+  });
+
+  it('Write renders no body when collapsed', () => {
+    const renderer = pickResultRenderer('Write');
+    const out = joinRender(
+      renderer(call('Write', { path: 'a.txt', content: 'a\nb\n' }), result('Wrote'), ctx),
+    );
+    expect(out.trim()).toBe('');
+  });
+
+  it('Think renders no body even with a thought arg', () => {
+    const renderer = pickResultRenderer('Think');
+    const out = joinRender(renderer(call('Think', { thought: 'hello' }), result('Recorded.'), ctx));
+    expect(out.trim()).toBe('');
+  });
+
+  it('Errors always fall back to truncated renderer regardless of tool', () => {
+    const renderer = pickResultRenderer('Read');
+    const out = strip(
+      joinRender(
+        renderer(call('Read', { path: 'foo.ts' }), result('ENOENT: foo.ts not found', true), ctx),
+      ),
+    );
+    expect(out).toContain('ENOENT: foo.ts not found');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/messages/usage-panel.test.ts b/apps/kimi-code/test/tui/components/messages/usage-panel.test.ts
new file mode 100644
index 000000000..e7d6c2c79
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/messages/usage-panel.test.ts
@@ -0,0 +1,67 @@
+import { visibleWidth } from '@earendil-works/pi-tui';
+import { describe, expect, it } from 'vitest';
+
+import { buildUsageReportLines, UsagePanelComponent } from '#/tui/components/messages/usage-panel';
+import { darkColors } from '#/tui/theme/colors';
+
+function strip(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+describe('UsagePanelComponent', () => {
+  it('formats session, context, and managed usage sections', () => {
+    const lines = buildUsageReportLines({
+      colors: darkColors,
+      sessionUsage: {
+        byModel: {
+          kimi: {
+            inputOther: 1000,
+            inputCacheRead: 500,
+            inputCacheCreation: 500,
+            output: 250,
+          },
+        },
+      } as never,
+      contextUsage: 0.25,
+      contextTokens: 2500,
+      maxContextTokens: 10000,
+      managedUsage: {
+        summary: {
+          label: 'daily',
+          used: 20,
+          limit: 100,
+          resetHint: 'resets tomorrow',
+        },
+        limits: [],
+      },
+    }).map(strip);
+
+    expect(lines).toContain('Session usage');
+    expect(lines).toContain('  kimi  input 2.0k  output 250  total 2.3k');
+    expect(lines).toContain('Context window');
+    expect(lines.join('\n')).toContain('25.0%');
+    expect(lines).toContain('Plan usage');
+    expect(lines.join('\n')).toContain('80% left');
+    expect(lines.join('\n')).toContain('(resets tomorrow)');
+  });
+
+  it('wraps preformatted usage lines in a bordered panel', () => {
+    const component = new UsagePanelComponent(['Session usage'], darkColors.primary);
+    const output = component.render(80).map(strip);
+
+    expect(output[0]).toContain(' Usage ');
+    expect(output[1]).toContain('Session usage');
+  });
+
+  it('truncates lines wider than the terminal so the panel never overflows', () => {
+    const longLine = 'error: ' + 'x'.repeat(200);
+    const component = new UsagePanelComponent([longLine], darkColors.primary);
+    const width = 60;
+
+    const output = component.render(width);
+
+    for (const line of output) {
+      expect(visibleWidth(line)).toBeLessThanOrEqual(width);
+    }
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/messages/user-message.test.ts b/apps/kimi-code/test/tui/components/messages/user-message.test.ts
new file mode 100644
index 000000000..ab1d5752b
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/messages/user-message.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+
+import { UserMessageComponent } from '#/tui/components/messages/user-message';
+import { darkColors } from '#/tui/theme/colors';
+
+function stripAnsi(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+describe('UserMessageComponent', () => {
+  it('renders video placeholders as plain text, not inline image escapes', () => {
+    const component = new UserMessageComponent(
+      'please inspect [video #1 sample.mov]',
+      darkColors,
+      [],
+    );
+
+    const out = stripAnsi(component.render(80).join('\n'));
+
+    expect(out).toContain('[video #1 sample.mov]');
+    expect(out).not.toContain('\u001B_G');
+    expect(out).not.toContain('\u001B]1337;File=');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/panels/footer-bg-agents.test.ts b/apps/kimi-code/test/tui/components/panels/footer-bg-agents.test.ts
new file mode 100644
index 000000000..e66e7f11f
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/panels/footer-bg-agents.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+
+import { FooterComponent } from '#/tui/components/chrome/footer';
+import { darkColors } from '#/tui/theme/colors';
+import type { AppState } from '#/tui/types';
+
+const ANSI_SGR = /\[[0-9;]*m/g;
+function strip(text: string): string {
+  return text.replaceAll(ANSI_SGR, '');
+}
+
+function baseState(overrides: Partial<AppState> = {}): AppState {
+  return {
+    model: 'k2',
+    workDir: '/tmp/proj',
+    sessionId: 'sess_1',
+    yolo: false,
+    permissionMode: 'manual',
+    planMode: false,
+    thinking: false,
+    contextUsage: 0,
+    contextTokens: 0,
+    maxContextTokens: 200_000,
+    isStreaming: false,
+    isCompacting: false,
+    isReplaying: false,
+    streamingPhase: 'idle',
+    streamingStartTime: 0,
+    theme: 'dark',
+    version: 'test',
+    editorCommand: null,
+    notifications: { enabled: true, condition: 'unfocused' },
+    availableModels: {},
+    ...overrides,
+  } as AppState;
+}
+
+describe('FooterComponent — background task / agent badges', () => {
+  it('omits both badges when counts are 0', () => {
+    const footer = new FooterComponent(baseState(), darkColors);
+    const [line1] = footer.render(120);
+    expect(line1).toBeDefined();
+    expect(strip(line1!)).not.toMatch(/tasks? running/);
+    expect(strip(line1!)).not.toMatch(/agents? running/);
+  });
+
+  it('renders the task badge alone when only bash tasks are running', () => {
+    const footer = new FooterComponent(baseState(), darkColors);
+    footer.setBackgroundCounts({ bashTasks: 1, agentTasks: 0 });
+    const out = strip(footer.render(120)[0]!);
+    expect(out).toMatch(/\[1 task running\]/);
+    expect(out).not.toMatch(/agents? running/);
+  });
+
+  it('renders the agent badge alone when only agent tasks are running', () => {
+    const footer = new FooterComponent(baseState(), darkColors);
+    footer.setBackgroundCounts({ bashTasks: 0, agentTasks: 1 });
+    const out = strip(footer.render(120)[0]!);
+    expect(out).toMatch(/\[1 agent running\]/);
+    expect(out).not.toMatch(/tasks? running/);
+  });
+
+  it('renders both badges side by side when both are non-zero', () => {
+    const footer = new FooterComponent(baseState(), darkColors);
+    footer.setBackgroundCounts({ bashTasks: 2, agentTasks: 3 });
+    const out = strip(footer.render(120)[0]!);
+    expect(out).toMatch(/\[2 tasks running\]/);
+    expect(out).toMatch(/\[3 agents running\]/);
+    // Task badge appears before agent badge in the line.
+    expect(out.indexOf('2 tasks')).toBeLessThan(out.indexOf('3 agents'));
+  });
+
+  it('pluralizes correctly across both badges', () => {
+    const footer = new FooterComponent(baseState(), darkColors);
+    footer.setBackgroundCounts({ bashTasks: 1, agentTasks: 1 });
+    const out = strip(footer.render(120)[0]!);
+    expect(out).toMatch(/\[1 task running\]/);
+    expect(out).toMatch(/\[1 agent running\]/);
+  });
+
+  it('updates badges live via setBackgroundCounts', () => {
+    const footer = new FooterComponent(baseState(), darkColors);
+    footer.setBackgroundCounts({ bashTasks: 2, agentTasks: 1 });
+    expect(strip(footer.render(120)[0]!)).toMatch(/\[2 tasks running\]/);
+    footer.setBackgroundCounts({ bashTasks: 0, agentTasks: 0 });
+    const after = strip(footer.render(120)[0]!);
+    expect(after).not.toMatch(/tasks? running/);
+    expect(after).not.toMatch(/agents? running/);
+  });
+
+  it('clamps negative counts to 0', () => {
+    const footer = new FooterComponent(baseState(), darkColors);
+    footer.setBackgroundCounts({ bashTasks: -5, agentTasks: -2 });
+    const out = strip(footer.render(120)[0]!);
+    expect(out).not.toMatch(/tasks? running/);
+    expect(out).not.toMatch(/agents? running/);
+  });
+
+  it('drops the badges when terminal is too narrow to fit them', () => {
+    const footer = new FooterComponent(baseState(), darkColors);
+    footer.setBackgroundCounts({ bashTasks: 4, agentTasks: 3 });
+    // Extremely narrow width: footer primary content fills the line, so leftLine wins.
+    const [line1] = footer.render(20);
+    expect(line1).toBeDefined();
+    expect(strip(line1!)).not.toMatch(/\[4 tasks running\]/);
+    expect(strip(line1!)).not.toMatch(/\[3 agents running\]/);
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/panels/footer-context.test.ts b/apps/kimi-code/test/tui/components/panels/footer-context.test.ts
new file mode 100644
index 000000000..4861b68cd
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/panels/footer-context.test.ts
@@ -0,0 +1,150 @@
+import { describe, it, expect } from 'vitest';
+import chalk from 'chalk';
+
+import { FooterComponent, formatFooterGitBadge } from '#/tui/components/chrome/footer';
+import { darkColors } from '#/tui/theme/colors';
+import type { AppState } from '#/tui/types';
+
+const ANSI_SGR = /\u001B\[[0-9;]*m/g;
+function strip(text: string): string {
+  return text.replaceAll(ANSI_SGR, '');
+}
+
+function hexToSgr(hex: string): string {
+  const value = hex.replace(/^#/, '');
+  const r = Number.parseInt(value.slice(0, 2), 16);
+  const g = Number.parseInt(value.slice(2, 4), 16);
+  const b = Number.parseInt(value.slice(4, 6), 16);
+  return `\u001B[38;2;${String(r)};${String(g)};${String(b)}m`;
+}
+
+function baseState(overrides: Partial<AppState> = {}): AppState {
+  return {
+    model: 'k2',
+    workDir: '/tmp',
+    sessionId: 'sess_1',
+    yolo: false,
+    permissionMode: 'manual',
+    planMode: false,
+    thinking: false,
+    contextUsage: 0,
+    contextTokens: 0,
+    maxContextTokens: 0,
+    isStreaming: false,
+    isCompacting: false,
+    isReplaying: false,
+    streamingPhase: 'idle',
+    streamingStartTime: 0,
+    theme: 'dark',
+    version: 'test',
+    editorCommand: null,
+    notifications: { enabled: true, condition: 'unfocused' },
+    availableModels: {},
+    ...overrides,
+  } as AppState;
+}
+
+describe('FooterComponent — context NaN resilience', () => {
+  it('NaN usage → renders 0.0% (never literal "NaN%")', () => {
+    const fc = new FooterComponent(baseState({ contextUsage: Number.NaN }), darkColors);
+    const out = strip(fc.render(120).join(''));
+    expect(out).not.toMatch(/NaN/);
+    expect(out).toMatch(/context: 0\.0%/);
+  });
+
+  it('undefined-ish (coerced) usage → renders 0.0%', () => {
+    const fc = new FooterComponent(
+      baseState({ contextUsage: undefined as unknown as number }),
+      darkColors,
+    );
+    const out = strip(fc.render(120).join(''));
+    expect(out).not.toMatch(/NaN/);
+    expect(out).toMatch(/context: 0\.0%/);
+  });
+
+  it('clamps ratios above 1.0 → renders 100.0%', () => {
+    const fc = new FooterComponent(baseState({ contextUsage: 1.5 }), darkColors);
+    const out = strip(fc.render(120).join(''));
+    expect(out).toMatch(/context: 100\.0%/);
+  });
+
+  it('ratio 0.427 → renders 42.7%', () => {
+    const fc = new FooterComponent(baseState({ contextUsage: 0.427 }), darkColors);
+    const out = strip(fc.render(200).join(''));
+    expect(out).toMatch(/context: 42\.7%/);
+  });
+
+  it('tokens provided but max=0 → falls back to percent-only, no division-by-zero artefact', () => {
+    const fc = new FooterComponent(
+      baseState({ contextUsage: 0, contextTokens: 500, maxContextTokens: 0 }),
+      darkColors,
+    );
+    const out = strip(fc.render(200).join(''));
+    expect(out).not.toMatch(/Infinity|NaN/);
+    expect(out).toMatch(/context: 0\.0%/);
+    // With maxTokens=0, token-count annotation is suppressed.
+    expect(out).not.toMatch(/\(500\//);
+  });
+
+  it('setState updates visible model and context values', () => {
+    const footer = new FooterComponent(baseState({ model: 'k2', contextUsage: 0 }), darkColors);
+
+    footer.setState(baseState({ model: 'kimi-k2-5', contextUsage: 0.5 }));
+
+    const out = strip(footer.render(200).join(''));
+    expect(out).toContain('kimi-k2-5');
+    expect(out).not.toContain(' k2 ');
+    expect(out).toMatch(/context: 50\.0%/);
+  });
+
+  it('shows "thinking" label when thinking is enabled, hides it when disabled', () => {
+    const on = new FooterComponent(baseState({ model: 'k2', thinking: true }), darkColors);
+    const off = new FooterComponent(baseState({ model: 'k2', thinking: false }), darkColors);
+
+    expect(strip(on.render(120)[0]!)).toContain('thinking');
+    expect(strip(off.render(120)[0]!)).not.toContain('thinking');
+  });
+
+  it('renders transient hints on the context line', () => {
+    const footer = new FooterComponent(baseState(), darkColors);
+
+    footer.setTransientHint('Press Ctrl-C again to exit');
+
+    const [, line2] = footer.render(120);
+    expect(strip(line2 ?? '')).toContain('Press Ctrl-C again to exit');
+    expect(strip(line2 ?? '')).toContain('context: 0.0%');
+  });
+
+  it('highlights the pull request badge separately from git status text', () => {
+    const previousLevel = chalk.level;
+    chalk.level = 3;
+    try {
+      const out = formatFooterGitBadge(
+        {
+          branch: 'feature/footer',
+          dirty: false,
+          ahead: 0,
+          behind: 0,
+          diffAdded: 0,
+          diffDeleted: 0,
+          pullRequest: {
+            number: 6,
+            url: 'https://github.com/acme/repo/pull/6',
+          },
+        },
+        darkColors,
+      );
+
+      const primaryIndex = out.indexOf(hexToSgr(darkColors.primary));
+      const statusIndex = out.indexOf(hexToSgr(darkColors.status));
+      const badgeIndex = out.indexOf('[PR#6]');
+      expect(statusIndex).toBeGreaterThanOrEqual(0);
+      expect(primaryIndex).toBeGreaterThanOrEqual(0);
+      expect(primaryIndex).toBeLessThan(badgeIndex);
+      expect(strip(out)).toContain('feature/footer ');
+      expect(strip(out)).toContain('[PR#6]');
+    } finally {
+      chalk.level = previousLevel;
+    }
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/panels/help-panel.test.ts b/apps/kimi-code/test/tui/components/panels/help-panel.test.ts
new file mode 100644
index 000000000..8b3489899
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/panels/help-panel.test.ts
@@ -0,0 +1,102 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import type { KimiSlashCommand } from '#/tui/commands/index';
+import { HelpPanelComponent } from '#/tui/components/dialogs/help-panel';
+import { darkColors } from '#/tui/theme/colors';
+
+function cmd(name: string, description: string, aliases: string[] = []): KimiSlashCommand {
+  return {
+    name,
+    aliases,
+    description,
+  };
+}
+
+function strip(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+describe('HelpPanelComponent', () => {
+  it('renders keyboard shortcuts + slash commands sections', () => {
+    const panel = new HelpPanelComponent({
+      commands: [cmd('exit', 'Exit', ['quit', 'q'])],
+      colors: darkColors,
+      onClose: () => {},
+    });
+    const out = strip(panel.render(80).join('\n'));
+    expect(out).toMatch(/help/);
+    expect(out).toMatch(/Keyboard shortcuts/);
+    expect(out).toMatch(/Shift-Tab/);
+    expect(out).toMatch(/Ctrl-O/);
+    expect(out).toMatch(/Slash commands/);
+    expect(out).toMatch(/\/exit \(\/quit, \/q\)/);
+    expect(out).toMatch(/Exit/);
+  });
+
+  it('sorts slash commands by name', () => {
+    const panel = new HelpPanelComponent({
+      commands: [cmd('zebra', 'Z'), cmd('alpha', 'A'), cmd('mango', 'M')],
+      colors: darkColors,
+      onClose: () => {},
+    });
+    const out = strip(panel.render(80).join('\n'));
+    const alphaIdx = out.indexOf('/alpha');
+    const mangoIdx = out.indexOf('/mango');
+    const zebraIdx = out.indexOf('/zebra');
+    expect(alphaIdx).toBeGreaterThan(-1);
+    expect(alphaIdx).toBeLessThan(mangoIdx);
+    expect(mangoIdx).toBeLessThan(zebraIdx);
+  });
+
+  it('Escape fires onClose', () => {
+    const onClose = vi.fn();
+    const panel = new HelpPanelComponent({
+      commands: [],
+      colors: darkColors,
+      onClose,
+    });
+    panel.handleInput('\u001B'); // Esc
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('q / Enter also close the panel', () => {
+    const onClose = vi.fn();
+    const panel = new HelpPanelComponent({
+      commands: [],
+      colors: darkColors,
+      onClose,
+    });
+    panel.handleInput('q');
+    panel.handleInput('\r');
+    expect(onClose).toHaveBeenCalledTimes(2);
+  });
+
+  it('clips to maxVisible with a "showing X-Y of Z" tail', () => {
+    const many = Array.from({ length: 30 }, (_, i) => cmd(`cmd${String(i)}`, `Desc ${String(i)}`));
+    const panel = new HelpPanelComponent({
+      commands: many,
+      colors: darkColors,
+      onClose: () => {},
+      maxVisible: 6,
+    });
+    const out = strip(panel.render(80).join('\n'));
+    expect(out).toMatch(/showing 1-6 of/);
+  });
+
+  it('arrow keys shift the scroll window', () => {
+    const many = Array.from({ length: 30 }, (_, i) => cmd(`cmd${String(i)}`, 'd'));
+    const panel = new HelpPanelComponent({
+      commands: many,
+      colors: darkColors,
+      onClose: () => {},
+      maxVisible: 6,
+    });
+    panel.handleInput('\u001B[B'); // ↓
+    panel.handleInput('\u001B[B'); // ↓
+    const out = strip(panel.render(80).join('\n'));
+    expect(out).toMatch(/showing 3-8 of/);
+    panel.handleInput('\u001B[A'); // ↑
+    const out2 = strip(panel.render(80).join('\n'));
+    expect(out2).toMatch(/showing 2-7 of/);
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/panels/plan-box.test.ts b/apps/kimi-code/test/tui/components/panels/plan-box.test.ts
new file mode 100644
index 000000000..04f1f84bb
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/panels/plan-box.test.ts
@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+
+import { PlanBoxComponent } from '#/tui/components/messages/plan-box';
+import { darkColors } from '#/tui/theme/colors';
+import { createMarkdownTheme } from '#/tui/theme/pi-tui-theme';
+
+const ESC = String.fromCodePoint(0x1b);
+const BEL = String.fromCodePoint(0x07);
+
+// Strip CSI styling and OSC 8 hyperlink sequences from rendered output so
+// visible text can be matched directly.
+function strip(text: string): string {
+  return text
+    .replaceAll(new RegExp(`${ESC}\\[[0-9;]*m`, 'g'), '')
+    .replaceAll(new RegExp(`${ESC}\\]8;;[^${BEL}]*${BEL}`, 'g'), '');
+}
+
+const theme = createMarkdownTheme(darkColors);
+
+describe('PlanBoxComponent', () => {
+  it('falls back to bare " plan " title when no path is provided', () => {
+    const box = new PlanBoxComponent('# Hello', theme, darkColors.success);
+    const out = strip(box.render(60).join('\n'));
+    const top = out.split('\n')[0]!;
+    expect(top).toContain('┌ plan ');
+    expect(top).not.toContain('plan:');
+  });
+
+  it('renders " plan: <basename> " in the top border without the directory prefix', () => {
+    const box = new PlanBoxComponent(
+      '# Hello',
+      theme,
+      darkColors.success,
+      '/tmp/projects/foo/.kimi-code/plans/very-long-slug-name.md',
+    );
+    const out = strip(box.render(80).join('\n'));
+    const top = out.split('\n')[0]!;
+    expect(top).toContain(' plan: very-long-slug-name.md ');
+    expect(top).not.toContain('/tmp/');
+    expect(top).not.toContain('…/');
+  });
+
+  it('wraps the basename in an OSC 8 hyperlink targeting file://', () => {
+    const box = new PlanBoxComponent('# Hello', theme, darkColors.success, '/tmp/plan.md');
+    const top = box.render(60)[0]!;
+    expect(top).toContain(`${ESC}]8;;file:///tmp/plan.md${BEL}plan.md${ESC}]8;;${BEL}`);
+    // After stripping OSC + CSI, visible width must respect the requested render width.
+    expect(strip(top).length).toBeLessThanOrEqual(60);
+  });
+
+  it('skips the hyperlink for non-absolute paths but still shows the basename', () => {
+    const box = new PlanBoxComponent('# Hello', theme, darkColors.success, 'relative/plan.md');
+    const top = box.render(60)[0]!;
+    expect(top).not.toContain(`${ESC}]8;`);
+    expect(strip(top)).toContain(' plan: plan.md ');
+  });
+
+  it('degrades to bare " plan " when even the basename does not fit', () => {
+    const box = new PlanBoxComponent('# Hello', theme, darkColors.success, '/tmp/plan.md');
+    const out = strip(box.render(14).join('\n'));
+    const top = out.split('\n')[0]!;
+    expect(top).toContain(' plan ');
+    expect(top).not.toContain('plan:');
+  });
+
+  it('renders all lines when content fits under maxContentLines', () => {
+    const plan = Array.from({ length: 5 }, (_, i) => `- step ${String(i + 1)}`).join('\n');
+    const box = new PlanBoxComponent(plan, theme, darkColors.success, undefined, {
+      maxContentLines: 20,
+    });
+    const out = strip(box.render(80).join('\n'));
+    expect(out).toContain('step 1');
+    expect(out).toContain('step 5');
+    expect(out).not.toContain('ctrl+e to expand');
+  });
+
+  it('truncates content over maxContentLines with a footer inside the box', () => {
+    const plan = Array.from({ length: 30 }, (_, i) => `- step ${String(i + 1)}`).join('\n');
+    const box = new PlanBoxComponent(plan, theme, darkColors.success, undefined, {
+      maxContentLines: 10,
+    });
+    const rendered = box.render(80);
+    const out = strip(rendered.join('\n'));
+    expect(out).toContain('step 1');
+    expect(out).toContain('step 9');
+    expect(out).not.toContain('step 10');
+    expect(out).toMatch(/\.\.\. \(\d+ more lines, ctrl\+e to expand\)/);
+    // Footer must live inside the bordered box, not after it.
+    const footerIdx = rendered.findIndex((line) => strip(line).includes('ctrl+e to expand'));
+    const bottomIdx = rendered.findIndex((line) => strip(line).includes('└'));
+    expect(footerIdx).toBeGreaterThan(-1);
+    expect(footerIdx).toBeLessThan(bottomIdx);
+    expect(strip(rendered[footerIdx]!)).toMatch(/^\s+│.*│\s*$/);
+  });
+
+  it('renders the full plan when expanded is true, ignoring maxContentLines', () => {
+    const plan = Array.from({ length: 30 }, (_, i) => `- step ${String(i + 1)}`).join('\n');
+    const box = new PlanBoxComponent(plan, theme, darkColors.success, undefined, {
+      maxContentLines: 10,
+      expanded: true,
+    });
+    const out = strip(box.render(80).join('\n'));
+    expect(out).toContain('step 30');
+    expect(out).not.toContain('ctrl+e to expand');
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/panels/todo-panel.test.ts b/apps/kimi-code/test/tui/components/panels/todo-panel.test.ts
new file mode 100644
index 000000000..373d2d0c4
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/panels/todo-panel.test.ts
@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+
+import { TodoPanelComponent, type TodoItem } from '#/tui/components/chrome/todo-panel';
+import { darkColors } from '#/tui/theme/colors';
+
+function strip(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+describe('TodoPanelComponent', () => {
+  it('returns no lines when empty (so the layout slot collapses)', () => {
+    const panel = new TodoPanelComponent(darkColors);
+    expect(panel.render(80)).toEqual([]);
+    expect(panel.isEmpty()).toBe(true);
+  });
+
+  it('renders a Todo header + one row per entry', () => {
+    const panel = new TodoPanelComponent(darkColors);
+    panel.setTodos([
+      { title: 'Investigate parser', status: 'done' },
+      { title: 'Add tests', status: 'in_progress' },
+      { title: 'Open PR', status: 'pending' },
+    ]);
+    const lines = panel.render(80).map(strip);
+    const joined = lines.join('\n');
+    expect(joined).toMatch(/Todo/);
+    expect(joined).toMatch(/✓ Investigate parser/);
+    expect(joined).toMatch(/● Add tests/);
+    expect(joined).toMatch(/○ Open PR/);
+  });
+
+  it('setTodos replaces the list (not appends)', () => {
+    const panel = new TodoPanelComponent(darkColors);
+    panel.setTodos([{ title: 'old', status: 'pending' }]);
+    panel.setTodos([{ title: 'new', status: 'in_progress' }]);
+    const out = strip(panel.render(80).join('\n'));
+    expect(out).toMatch(/● new/);
+    expect(out).not.toMatch(/old/);
+  });
+
+  it('clear() wipes the list and reverts to empty', () => {
+    const panel = new TodoPanelComponent(darkColors);
+    panel.setTodos([{ title: 'x', status: 'pending' }]);
+    panel.clear();
+    expect(panel.isEmpty()).toBe(true);
+    expect(panel.render(80)).toEqual([]);
+  });
+
+  it('defensive copy: external mutation does not leak into the panel', () => {
+    const panel = new TodoPanelComponent(darkColors);
+    const source: TodoItem[] = [{ title: 'foo', status: 'pending' }];
+    panel.setTodos(source);
+    source[0] = { title: 'hacked', status: 'done' };
+    const out = strip(panel.render(80).join('\n'));
+    expect(out).toMatch(/○ foo/);
+    expect(out).not.toMatch(/hacked/);
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/panes/activity-pane.test.ts b/apps/kimi-code/test/tui/components/panes/activity-pane.test.ts
new file mode 100644
index 000000000..383c43693
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/panes/activity-pane.test.ts
@@ -0,0 +1,29 @@
+import { Text } from '@earendil-works/pi-tui';
+import { describe, expect, it } from 'vitest';
+
+import { ActivityPaneComponent } from '#/tui/components/panes/activity-pane';
+
+describe('ActivityPaneComponent', () => {
+  it('renders waiting loader after a spacer', () => {
+    const component = new ActivityPaneComponent({
+      mode: 'waiting',
+      spinner: new Text('loading', 0, 0) as never,
+    });
+
+    expect(component.render(80).map((line) => line.trimEnd())).toEqual(['', 'loading']);
+  });
+
+  it('renders composing spinner after a spacer', () => {
+    const component = new ActivityPaneComponent({
+      mode: 'composing',
+      spinner: new Text('working', 0, 0) as never,
+    });
+
+    expect(component.render(80).map((line) => line.trimEnd())).toEqual(['', 'working']);
+  });
+
+  it('renders nothing for hidden and thinking modes', () => {
+    expect(new ActivityPaneComponent({ mode: 'hidden' }).render(80)).toEqual([]);
+    expect(new ActivityPaneComponent({ mode: 'thinking' }).render(80)).toEqual([]);
+  });
+});
diff --git a/apps/kimi-code/test/tui/components/panes/queue-pane.test.ts b/apps/kimi-code/test/tui/components/panes/queue-pane.test.ts
new file mode 100644
index 000000000..fbb5e4979
--- /dev/null
+++ b/apps/kimi-code/test/tui/components/panes/queue-pane.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+
+import { QueuePaneComponent } from '#/tui/components/panes/queue-pane';
+import { darkColors } from '#/tui/theme/colors';
+
+function stripAnsi(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+describe('QueuePaneComponent', () => {
+  it('renders queued messages with the steer hint', () => {
+    const component = new QueuePaneComponent({
+      colors: darkColors,
+      isCompacting: false,
+      isStreaming: true,
+      canSteerImmediately: true,
+      messages: [
+        { text: 'first message' },
+        { text: '/skill:review src/app.ts' },
+      ],
+    });
+
+    const output = stripAnsi(component.render(120).join('\n'));
+
+    expect(output).toContain('❯ first message');
+    expect(output).toContain('❯ /skill:review src/app.ts');
+    expect(output).toContain('ctrl-s to steer immediately');
+  });
+
+  it('renders compaction hint when waiting for compaction', () => {
+    const component = new QueuePaneComponent({
+      colors: darkColors,
+      isCompacting: true,
+      isStreaming: false,
+      canSteerImmediately: true,
+      messages: [{ text: 'after compact' }],
+    });
+
+    const output = stripAnsi(component.render(120).join('\n'));
+
+    expect(output).toContain('will send after compaction');
+  });
+
+  it('omits the steer hint when immediate steering is disabled', () => {
+    const component = new QueuePaneComponent({
+      colors: darkColors,
+      isCompacting: false,
+      isStreaming: true,
+      canSteerImmediately: false,
+      messages: [{ text: 'after init' }],
+    });
+
+    const output = stripAnsi(component.render(120).join('\n'));
+
+    expect(output).toContain('will send after current task');
+    expect(output).not.toContain('ctrl-s to steer immediately');
+  });
+});
diff --git a/apps/kimi-code/test/tui/config.test.ts b/apps/kimi-code/test/tui/config.test.ts
new file mode 100644
index 000000000..a7ddf4509
--- /dev/null
+++ b/apps/kimi-code/test/tui/config.test.ts
@@ -0,0 +1,111 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  DEFAULT_TUI_CONFIG,
+  INVALID_TUI_CONFIG_MESSAGE,
+  loadTuiConfig,
+  parseTuiConfig,
+  saveTuiConfig,
+  TuiConfigParseError,
+} from '#/tui/config';
+
+let dir: string;
+let filePath: string;
+
+beforeEach(() => {
+  dir = join(tmpdir(), `kimi-tui-config-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(dir, { recursive: true });
+  filePath = join(dir, 'tui.toml');
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('TUI config', () => {
+  it('creates the default config when the file does not exist', async () => {
+    const result = await loadTuiConfig(filePath);
+
+    expect(result).toEqual(DEFAULT_TUI_CONFIG);
+    const text = readFileSync(filePath, 'utf-8');
+    expect(text).toContain('Terminal UI preferences for kimi-code.');
+    expect(text).toContain('theme = "auto"');
+    expect(text).toContain('command = ""');
+    expect(text).toContain('[notifications]');
+    expect(text).toContain('enabled = true');
+    expect(text).toContain('notification_condition = "unfocused"');
+  });
+
+  it('parses valid TOML', () => {
+    const config = parseTuiConfig(`
+theme = "light"
+
+[editor]
+command = "code --wait"
+
+[notifications]
+enabled = false
+notification_condition = "always"
+`);
+
+    expect(config).toEqual({
+      theme: 'light',
+      editorCommand: 'code --wait',
+      notifications: { enabled: false, condition: 'always' },
+    });
+  });
+
+  it('normalizes an empty editor command to auto-detect', () => {
+    const config = parseTuiConfig(`
+[editor]
+command = "   "
+`);
+
+    expect(config).toEqual({
+      theme: 'auto',
+      editorCommand: null,
+      notifications: { enabled: true, condition: 'unfocused' },
+    });
+  });
+
+  it('falls back to default notifications when the section is omitted', () => {
+    const config = parseTuiConfig(`theme = "dark"`);
+
+    expect(config.notifications).toEqual({ enabled: true, condition: 'unfocused' });
+  });
+
+  it('throws TuiConfigParseError with fallback when parsing fails, leaving the file untouched', async () => {
+    writeFileSync(filePath, '[[[', 'utf-8');
+
+    const error = await loadTuiConfig(filePath).then(
+      () => null,
+      (error: unknown) => error,
+    );
+
+    expect(error).toBeInstanceOf(TuiConfigParseError);
+    expect((error as TuiConfigParseError).message).toBe(INVALID_TUI_CONFIG_MESSAGE);
+    expect((error as TuiConfigParseError).fallback).toEqual(DEFAULT_TUI_CONFIG);
+    expect(readFileSync(filePath, 'utf-8')).toBe('[[[');
+  });
+
+  it('saves and reloads the normalized config', async () => {
+    await saveTuiConfig(
+      {
+        theme: 'light',
+        editorCommand: 'vim',
+        notifications: { enabled: false, condition: 'always' },
+      },
+      filePath,
+    );
+
+    expect(await loadTuiConfig(filePath)).toEqual({
+      theme: 'light',
+      editorCommand: 'vim',
+      notifications: { enabled: false, condition: 'always' },
+    });
+  });
+});
diff --git a/apps/kimi-code/test/tui/create-tui-state.test.ts b/apps/kimi-code/test/tui/create-tui-state.test.ts
new file mode 100644
index 000000000..4da743841
--- /dev/null
+++ b/apps/kimi-code/test/tui/create-tui-state.test.ts
@@ -0,0 +1,103 @@
+
+import { describe, it, expect } from 'vitest';
+
+import { createTUIState, type KimiTUIOptions } from '#/tui/kimi-tui';
+import type { AppState } from '#/tui/types';
+
+function fakeInitialAppState(): AppState {
+  return {
+    model: 'test-model',
+    workDir: '/tmp/kimi-test',
+    sessionId: 'sess-1',
+    yolo: false,
+    permissionMode: 'manual',
+    planMode: false,
+    thinking: false,
+    contextUsage: 0,
+    contextTokens: 0,
+    maxContextTokens: 0,
+    isStreaming: false,
+    isCompacting: false,
+    isReplaying: false,
+    streamingPhase: 'idle',
+    streamingStartTime: 0,
+    theme: 'dark',
+    version: '0.0.0-test',
+    editorCommand: null,
+    notifications: { enabled: true, condition: 'unfocused' },
+    availableModels: {},
+    availableProviders: {},
+    sessionTitle: null,
+  };
+}
+
+describe('createTUIState', () => {
+  it('initializes all fields with sensible defaults', () => {
+    const opts: KimiTUIOptions = {
+      initialAppState: fakeInitialAppState(),
+      startup: {
+        continueLast: false,
+        yolo: false,
+        plan: false,
+      },
+    };
+    const state = createTUIState(opts);
+
+    // UI objects are created.
+    expect(state.ui).toBeDefined();
+    expect(state.terminal).toBeDefined();
+    expect(state.transcriptContainer).toBeDefined();
+    expect(state.activityContainer).toBeDefined();
+    expect(state.todoPanelContainer).toBeDefined();
+    expect(state.queueContainer).toBeDefined();
+    expect(state.editorContainer).toBeDefined();
+    expect(state.editor).toBeDefined();
+    expect(state.footer).toBeDefined();
+    expect(state.todoPanel).toBeDefined();
+    expect(state.theme.colors).toBeDefined();
+    expect(state.theme.markdownTheme).toBeDefined();
+
+    // App state is cloned from initialAppState, not reused by reference.
+    expect(state.appState).not.toBe(opts.initialAppState);
+    expect(state.appState.model).toBe('test-model');
+    expect(state.appState.sessionId).toBe('sess-1');
+    expect(state.startupState).toBe('pending');
+    expect(state.startupNotice).toBeUndefined();
+
+    // LivePane defaults.
+    expect(state.livePane.mode).toBe('idle');
+    expect(state.livePane.pendingApproval).toBeNull();
+    expect(state.livePane.pendingQuestion).toBeNull();
+
+    // Empty collections.
+    expect(state.transcriptEntries).toHaveLength(0);
+    expect(state.queuedMessages).toHaveLength(0);
+    expect(state.pendingToolComponents.size).toBe(0);
+    expect(state.activeToolCalls.size).toBe(0);
+    expect(state.streamingToolCallArguments.size).toBe(0);
+    expect(state.backgroundAgents.size).toBe(0);
+    expect(state.backgroundAgentMetadata.size).toBe(0);
+    expect(state.renderedSkillActivationIds.size).toBe(0);
+
+    // Boolean, counter, and optional-field defaults.
+    expect(state.toolOutputExpanded).toBe(false);
+    expect(state.showingSessionPicker).toBe(false);
+    expect(state.showingHelpPanel).toBe(false);
+    expect(state.externalEditorRunning).toBe(false);
+    expect(state.loadingSessions).toBe(false);
+    expect(state.currentTurnId).toBeUndefined();
+    expect(state.currentStep).toBe(0);
+    expect(state.assistantStreamActive).toBe(false);
+    expect(state.assistantDraft).toBe('');
+    expect(state.thinkingDraft).toBe('');
+    expect(state.lastHistoryContent).toBeUndefined();
+    expect(state.lastActivityMode).toBeUndefined();
+    expect(state.activitySpinner).toBeUndefined();
+    expect(state.activitySpinnerStyle).toBeUndefined();
+    expect(state.streamingComponent).toBeUndefined();
+    expect(state.streamingTranscriptEntry).toBeUndefined();
+    expect(state.activeCompactionBlock).toBeUndefined();
+    expect(state.pendingAgentGroup).toBeNull();
+    expect(state.pendingReadGroup).toBeNull();
+  });
+});
diff --git a/apps/kimi-code/test/tui/input/image-attachment-store.test.ts b/apps/kimi-code/test/tui/input/image-attachment-store.test.ts
new file mode 100644
index 000000000..cb3e88c59
--- /dev/null
+++ b/apps/kimi-code/test/tui/input/image-attachment-store.test.ts
@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  ImageAttachmentStore,
+  formatPlaceholder,
+  formatVideoPlaceholder,
+} from '#/tui/utils/image-attachment-store';
+
+describe('ImageAttachmentStore', () => {
+  it('assigns monotonically increasing ids starting at 1', () => {
+    const s = new ImageAttachmentStore();
+    const a = s.addImage(new Uint8Array([1]), 'image/png', 10, 20);
+    const b = s.addVideo('video/quicktime', '/tmp/sample.mov');
+    expect(a.id).toBe(1);
+    expect(b.id).toBe(2);
+  });
+
+  it('builds the canonical placeholder string', () => {
+    expect(formatPlaceholder(1, 640, 480)).toBe('[image #1 (640×480)]');
+    expect(formatPlaceholder(42, 3840, 2160)).toBe('[image #42 (3840×2160)]');
+  });
+
+  it('builds video placeholders with sanitized labels', () => {
+    expect(formatVideoPlaceholder(1, 'sample.mov')).toBe('[video #1 sample.mov]');
+    expect(formatVideoPlaceholder(2, 'bad[name]\u0000.mov')).toBe('[video #2 bad_name__.mov]');
+  });
+
+  it('uses the video filename basename as the placeholder label', () => {
+    const s = new ImageAttachmentStore();
+    const att = s.addVideo('video/mp4', '/tmp/clips/sample.mp4');
+    expect(att.filename).toBe('sample.mp4');
+    expect(att.sourcePath).toBe('/tmp/clips/sample.mp4');
+    expect(att.placeholder).toBe('[video #1 sample.mp4]');
+  });
+
+  it('get() returns stored attachment', () => {
+    const s = new ImageAttachmentStore();
+    const bytes = new Uint8Array([9, 8, 7]);
+    const att = s.addImage(bytes, 'image/jpeg', 100, 200);
+    expect(s.get(att.id)).toBe(att);
+    expect(s.get(99)).toBeUndefined();
+  });
+
+  it('keeps pasted image bytes in memory', () => {
+    const s = new ImageAttachmentStore();
+    const bytes = new Uint8Array([9, 8, 7]);
+    const att = s.addImage(bytes, 'image/jpeg', 100, 200);
+    expect(att.bytes).toBe(bytes);
+    expect(att.mime).toBe('image/jpeg');
+  });
+
+  it('clear() resets ids and empties storage', () => {
+    const s = new ImageAttachmentStore();
+    s.addImage(new Uint8Array(), 'image/png', 10, 10);
+    s.addImage(new Uint8Array(), 'image/png', 10, 10);
+    expect(s.size()).toBe(2);
+    s.clear();
+    expect(s.size()).toBe(0);
+    const next = s.addImage(new Uint8Array(), 'image/png', 10, 10);
+    expect(next.id).toBe(1);
+  });
+});
diff --git a/apps/kimi-code/test/tui/input/image-placeholder.test.ts b/apps/kimi-code/test/tui/input/image-placeholder.test.ts
new file mode 100644
index 000000000..cdc74e913
--- /dev/null
+++ b/apps/kimi-code/test/tui/input/image-placeholder.test.ts
@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+
+import { ImageAttachmentStore } from '#/tui/utils/image-attachment-store';
+import { extractMediaAttachments } from '#/tui/utils/image-placeholder';
+
+function storeWith(
+  bytes: Uint8Array,
+  width = 640,
+  height = 480,
+): { store: ImageAttachmentStore; placeholder: string } {
+  const store = new ImageAttachmentStore();
+  const att = store.addImage(bytes, 'image/png', width, height);
+  return { store, placeholder: att.placeholder };
+}
+
+describe('extractMediaAttachments', () => {
+  it('returns no parts and hasMedia=false for plain text', () => {
+    const store = new ImageAttachmentStore();
+    const r = extractMediaAttachments('hello world', store);
+    expect(r.hasMedia).toBe(false);
+    expect(r.parts).toEqual([]);
+    expect(r.imageAttachmentIds).toEqual([]);
+    expect(r.videoAttachmentIds).toEqual([]);
+  });
+
+  it('extracts a single matching placeholder into an image content part', () => {
+    const { store, placeholder } = storeWith(new Uint8Array([0xaa, 0xbb]));
+    const r = extractMediaAttachments(`describe ${placeholder} please`, store);
+    expect(r.hasMedia).toBe(true);
+    expect(r.imageAttachmentIds).toEqual([1]);
+    expect(r.parts).toEqual([
+      { type: 'text', text: 'describe ' },
+      { type: 'image_url', imageUrl: { url: 'data:image/png;base64,qrs=' } },
+      { type: 'text', text: ' please' },
+    ]);
+  });
+
+  it('keeps matched-placeholder order with multiple images', () => {
+    const store = new ImageAttachmentStore();
+    const a = store.addImage(new Uint8Array([1]), 'image/png', 10, 10);
+    const b = store.addImage(new Uint8Array([2]), 'image/png', 20, 20);
+    const text = `first ${a.placeholder} then ${b.placeholder} end`;
+    const r = extractMediaAttachments(text, store);
+    expect(r.imageAttachmentIds).toEqual([1, 2]);
+    expect(r.parts).toEqual([
+      { type: 'text', text: 'first ' },
+      { type: 'image_url', imageUrl: { url: 'data:image/png;base64,AQ==' } },
+      { type: 'text', text: ' then ' },
+      { type: 'image_url', imageUrl: { url: 'data:image/png;base64,Ag==' } },
+      { type: 'text', text: ' end' },
+    ]);
+  });
+
+  it('keeps matched-placeholder order with mixed image and video attachments', () => {
+    const store = new ImageAttachmentStore();
+    const img = store.addImage(new Uint8Array([1]), 'image/png', 10, 10);
+    const vid = store.addVideo('video/quicktime', '/tmp/clip.mov');
+    const text = `first ${img.placeholder} then ${vid.placeholder} end`;
+    const r = extractMediaAttachments(text, store);
+    expect(r.imageAttachmentIds).toEqual([1]);
+    expect(r.videoAttachmentIds).toEqual([2]);
+    expect(r.parts).toEqual([
+      { type: 'text', text: 'first ' },
+      { type: 'image_url', imageUrl: { url: 'data:image/png;base64,AQ==' } },
+      { type: 'text', text: ' then <video path="/tmp/clip.mov"></video> end' },
+    ]);
+  });
+
+  it('leaves unresolved (typed by hand) placeholders as literal text', () => {
+    const store = new ImageAttachmentStore();
+    const r = extractMediaAttachments('try [image #999 (1×1)] and [video #42 clip.mov] now', store);
+    expect(r.hasMedia).toBe(false);
+    expect(r.parts).toEqual([]);
+  });
+
+  it('uses pasted image bytes in data URLs', () => {
+    const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+    const { store, placeholder } = storeWith(bytes);
+    const r = extractMediaAttachments(placeholder, store);
+    expect(r.parts).toHaveLength(1);
+    expect(r.parts[0]).toEqual({
+      type: 'image_url',
+      imageUrl: { url: 'data:image/png;base64,iVBORw==' },
+    });
+  });
+
+  it('escapes media paths in generated tags', () => {
+    const store = new ImageAttachmentStore();
+    const att = store.addVideo('video/mp4', '/tmp/a&"<>.mp4', 'sample.mp4');
+    const r = extractMediaAttachments(att.placeholder, store);
+    expect(r.parts).toEqual([
+      { type: 'text', text: '<video path="/tmp/a&amp;&quot;&lt;&gt;.mp4"></video>' },
+    ]);
+  });
+
+  it('expands video placeholders backed by local files to readMediaFile video tags', () => {
+    const store = new ImageAttachmentStore();
+    const att = store.addVideo('video/mp4', '/tmp/sample.mp4');
+    const r = extractMediaAttachments(att.placeholder, store);
+    expect(r.hasMedia).toBe(true);
+    expect(r.videoAttachmentIds).toEqual([1]);
+    expect(r.parts).toEqual([{ type: 'text', text: '<video path="/tmp/sample.mp4"></video>' }]);
+  });
+});
diff --git a/apps/kimi-code/test/tui/kimi-tui-message-flow.test.ts b/apps/kimi-code/test/tui/kimi-tui-message-flow.test.ts
new file mode 100644
index 000000000..f1d9dc17d
--- /dev/null
+++ b/apps/kimi-code/test/tui/kimi-tui-message-flow.test.ts
@@ -0,0 +1,1172 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  deleteAllKittyImages,
+  resetCapabilitiesCache,
+  setCapabilities,
+} from '@earendil-works/pi-tui';
+import type { ApprovalRequest, ApprovalResponse, Event } from '@moonshot-ai/kimi-code-sdk';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { ModelSelectorComponent } from '#/tui/components/dialogs/model-selector';
+import { KimiTUI, type KimiTUIStartupInput, type TUIState } from '#/tui/kimi-tui';
+import type { QueuedMessage } from '#/tui/types';
+import type { ImageAttachmentStore } from '#/tui/utils/image-attachment-store';
+
+function stripSgr(text: string): string {
+  return text.replaceAll(/\u001B\[[0-9;]*m/g, '');
+}
+
+interface MessageDriver {
+  state: TUIState;
+  init(): Promise<boolean>;
+  handleUserInput(text: string): void;
+  handleEvent(event: Event, sendQueued: (item: QueuedMessage) => void): void;
+  persistInputHistory(text: string): Promise<void>;
+  startSessionEventSubscription(): void;
+  getCurrentSessionId(): string;
+}
+
+interface FeedbackDriver extends MessageDriver {
+  handleFeedbackCommand(): Promise<void>;
+  promptFeedbackInput(): Promise<string | undefined>;
+}
+
+function makeStartupInput(): KimiTUIStartupInput {
+  return {
+    cliOptions: {
+      session: undefined,
+      continue: false,
+      yolo: false,
+      plan: false,
+      model: undefined,
+      outputFormat: undefined,
+      prompt: undefined,
+      skillsDirs: [],
+    },
+    tuiConfig: {
+      theme: 'dark',
+      editorCommand: null,
+      notifications: { enabled: true, condition: 'unfocused' },
+    },
+    version: '0.0.0-test',
+    workDir: '/tmp/proj-a',
+    resolvedTheme: 'dark',
+  };
+}
+
+function makeSession(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'ses-1',
+    model: 'k2',
+    summary: { title: null },
+    prompt: vi.fn(async () => {}),
+    steer: vi.fn(async () => {}),
+    init: vi.fn(async () => {}),
+    cancel: vi.fn(async () => {}),
+    cancelCompaction: vi.fn(async () => {}),
+    getStatus: vi.fn(async () => ({
+      model: 'k2',
+      thinkingLevel: 'off',
+      permission: 'manual',
+      planMode: false,
+      contextTokens: 0,
+      maxContextTokens: 100,
+      contextUsage: 0,
+    })),
+    setApprovalHandler: vi.fn(),
+    setQuestionHandler: vi.fn(),
+    setModel: vi.fn(async () => {}),
+    setThinking: vi.fn(async () => {}),
+    setPermission: vi.fn(async () => {}),
+    setPlanMode: vi.fn(async () => {}),
+    onEvent: vi.fn(() => vi.fn()),
+    listMcpServers: vi.fn(async () => []),
+    listSkills: vi.fn(async () => []),
+    getResumeState: vi.fn(() => ({
+      sessionMetadata: {},
+      agents: {
+        main: {
+          status: {
+            model: 'k2',
+            thinkingLevel: 'off',
+            permission: 'manual',
+            planMode: false,
+            contextTokens: 0,
+            maxContextTokens: 100,
+            contextUsage: 0,
+          },
+          context: { history: [] },
+          replay: [],
+        },
+      },
+    })),
+    close: vi.fn(async () => {}),
+    ...overrides,
+  };
+}
+
+function makeHarness(session = makeSession(), overrides: Record<string, unknown> = {}) {
+  return {
+    getConfig: vi.fn(async () => ({
+      models: {
+        k2: { model: 'moonshot-v1', maxContextSize: 100 },
+      },
+    })),
+    createSession: vi.fn(async () => session),
+    resumeSession: vi.fn(async () => session),
+    forkSession: vi.fn(async () => session),
+    listSessions: vi.fn(async () => []),
+    close: vi.fn(async () => {}),
+    track: vi.fn(),
+    setTelemetryContext: vi.fn(),
+    interactiveAgentId: 'main',
+    auth: {
+      status: vi.fn(),
+      login: vi.fn(),
+      logout: vi.fn(),
+      getManagedUsage: vi.fn(),
+      submitFeedback: vi.fn(async () => ({ kind: 'ok' })),
+    },
+    ...overrides,
+  };
+}
+
+async function makeDriver(
+  session = makeSession(),
+  harnessOverrides: Record<string, unknown> = {},
+): Promise<{
+  driver: MessageDriver;
+  session: ReturnType<typeof makeSession>;
+  harness: ReturnType<typeof makeHarness>;
+}> {
+  const harness = makeHarness(session, harnessOverrides);
+  const driver = new KimiTUI(harness as never, makeStartupInput()) as unknown as MessageDriver;
+  vi.spyOn(driver.state.ui, 'requestRender').mockImplementation(() => {});
+  vi.spyOn(driver.state.terminal, 'setProgress').mockImplementation(() => {});
+  driver.persistInputHistory = vi.fn(async () => {});
+  await driver.init();
+  return { driver, session, harness };
+}
+
+function renderTranscript(driver: MessageDriver): string {
+  return driver.state.transcriptContainer.render(120).join('\n');
+}
+
+function countOccurrences(haystack: string, needle: string): number {
+  return haystack.split(needle).length - 1;
+}
+
+const tempDirs: string[] = [];
+const originalKimiCodeHome = process.env['KIMI_CODE_HOME'];
+const originalVisual = process.env['VISUAL'];
+const originalEditor = process.env['EDITOR'];
+
+async function makeTempHome(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'kimi-code-tui-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(async () => {
+  resetCapabilitiesCache();
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+  if (originalKimiCodeHome === undefined) {
+    delete process.env['KIMI_CODE_HOME'];
+  } else {
+    process.env['KIMI_CODE_HOME'] = originalKimiCodeHome;
+  }
+  if (originalVisual === undefined) {
+    delete process.env['VISUAL'];
+  } else {
+    process.env['VISUAL'] = originalVisual;
+  }
+  if (originalEditor === undefined) {
+    delete process.env['EDITOR'];
+  } else {
+    process.env['EDITOR'] = originalEditor;
+  }
+});
+
+describe('KimiTUI message flow', () => {
+  it('tracks editor shortcut and paste hooks', async () => {
+    const { driver, harness } = await makeDriver();
+    harness.track.mockClear();
+
+    driver.state.editor.handleInput('\n');
+    driver.state.editor.handleInput('\u001F');
+    delete process.env['VISUAL'];
+    delete process.env['EDITOR'];
+    driver.state.editor.onOpenExternalEditor?.();
+    driver.state.editor.onToggleToolExpand?.();
+    driver.state.editor.onTextPaste?.();
+
+    expect(harness.track).toHaveBeenCalledWith('shortcut_newline', undefined);
+    expect(harness.track).toHaveBeenCalledWith('undo', undefined);
+    expect(harness.track).toHaveBeenCalledWith('shortcut_editor', undefined);
+    expect(harness.track).toHaveBeenCalledWith('shortcut_expand', undefined);
+    expect(harness.track).toHaveBeenCalledWith('shortcut_paste', { kind: 'text' });
+  });
+
+  it('tracks /clear as the clear alias for /new', async () => {
+    const { driver, harness } = await makeDriver(makeSession({ id: 'ses-1' }));
+    const nextSession = makeSession({ id: 'ses-2' });
+    harness.createSession.mockResolvedValueOnce(nextSession);
+    harness.track.mockClear();
+
+    driver.handleUserInput('/clear');
+
+    await vi.waitFor(() => {
+      expect(driver.getCurrentSessionId()).toBe('ses-2');
+    });
+    expect(harness.track).toHaveBeenCalledWith('input_command', { command: 'new' });
+    expect(harness.track).toHaveBeenCalledWith('clear', undefined);
+  });
+
+  it('tracks theme changes from slash commands', async () => {
+    process.env['KIMI_CODE_HOME'] = await makeTempHome();
+    const { driver, harness } = await makeDriver();
+    harness.track.mockClear();
+
+    driver.handleUserInput('/theme light');
+
+    await vi.waitFor(() => {
+      expect(driver.state.appState.theme).toBe('light');
+    });
+    expect(harness.track).toHaveBeenCalledWith('input_command', { command: 'theme' });
+    expect(harness.track).toHaveBeenCalledWith('theme_switch', { theme: 'light' });
+  });
+
+  it('tracks successful feedback submissions only after the request succeeds', async () => {
+    const { driver, harness } = await makeDriver(
+      makeSession(),
+      {
+        getConfig: vi.fn(async () => ({
+          models: {
+            k2: {
+              model: 'moonshot-v1',
+              maxContextSize: 100,
+              provider: 'managed:kimi-code',
+            },
+          },
+        })),
+      },
+    );
+    const feedbackDriver = driver as unknown as FeedbackDriver;
+    feedbackDriver.promptFeedbackInput = vi.fn(async () => 'useful feedback');
+    harness.auth.submitFeedback.mockResolvedValueOnce({ kind: 'ok' });
+    harness.track.mockClear();
+
+    await feedbackDriver.handleFeedbackCommand();
+
+    expect(harness.auth.submitFeedback).toHaveBeenCalledWith(
+      expect.objectContaining({
+        content: 'useful feedback',
+        sessionId: 'ses-1',
+        version: 'kimi-code-0.0.0-test',
+        model: 'k2',
+      }),
+    );
+    expect(harness.track).toHaveBeenCalledWith('feedback_submitted', undefined);
+  });
+
+  it('does not track feedback when the dialog is cancelled', async () => {
+    const { driver, harness } = await makeDriver(
+      makeSession(),
+      {
+        getConfig: vi.fn(async () => ({
+          models: {
+            k2: {
+              model: 'moonshot-v1',
+              maxContextSize: 100,
+              provider: 'managed:kimi-code',
+            },
+          },
+        })),
+      },
+    );
+    const feedbackDriver = driver as unknown as FeedbackDriver;
+    feedbackDriver.promptFeedbackInput = vi.fn(async () => undefined);
+    harness.track.mockClear();
+
+    await feedbackDriver.handleFeedbackCommand();
+
+    expect(harness.auth.submitFeedback).not.toHaveBeenCalled();
+    expect(harness.track).not.toHaveBeenCalledWith('feedback_submitted', undefined);
+  });
+
+  it('tracks blocked slash commands as invalid without counting them as executed commands', async () => {
+    const { driver, harness } = await makeDriver();
+    driver.state.appState.isStreaming = true;
+    harness.track.mockClear();
+
+    driver.handleUserInput('/new');
+    await Promise.resolve();
+
+    expect(harness.track).toHaveBeenCalledWith('input_command_invalid', {
+      reason: 'blocked',
+      command: 'new',
+    });
+    expect(harness.track).not.toHaveBeenCalledWith('input_command', { command: 'new' });
+  });
+
+  it('tracks Shift-Tab mode switches through the editor handler', async () => {
+    const { driver, session, harness } = await makeDriver();
+    harness.track.mockClear();
+
+    driver.state.editor.onShiftTab?.();
+
+    await vi.waitFor(() => {
+      expect(session.setPlanMode).toHaveBeenCalledWith(true);
+    });
+    expect(harness.track).toHaveBeenCalledWith('shortcut_plan_toggle', { enabled: true });
+    expect(harness.track).toHaveBeenCalledWith('shortcut_mode_switch', { to_mode: 'plan' });
+  });
+
+  it('routes /yolo through session permission state without app-layer telemetry duplication', async () => {
+    const { driver, session, harness } = await makeDriver();
+    harness.track.mockClear();
+
+    driver.handleUserInput('/yolo on');
+
+    await vi.waitFor(() => {
+      expect(session.setPermission).toHaveBeenCalledWith('yolo');
+    });
+    expect(driver.state.appState).toMatchObject({
+      yolo: true,
+      permissionMode: 'yolo',
+    });
+    expect(harness.track).toHaveBeenCalledWith('input_command', { command: 'yolo' });
+    expect(harness.track).not.toHaveBeenCalledWith('yolo_toggle', expect.anything());
+  });
+
+  it('hydrates MCP server status after subscribing to session events', async () => {
+    const session = makeSession({
+      listMcpServers: vi.fn(async () => [
+        {
+          name: 'local-tools',
+          transport: 'stdio',
+          status: 'connected',
+          toolCount: 2,
+        },
+        {
+          name: 'remote-tools',
+          transport: 'http',
+          status: 'failed',
+          toolCount: 0,
+          error: 'connection refused',
+        },
+      ]),
+    });
+    const { driver } = await makeDriver(session);
+
+    driver.startSessionEventSubscription();
+    await Promise.resolve();
+
+    expect(session.onEvent).toHaveBeenCalledOnce();
+    expect(session.listMcpServers).toHaveBeenCalledOnce();
+    const subscribeOrder = session.onEvent.mock.invocationCallOrder[0];
+    const snapshotOrder = session.listMcpServers.mock.invocationCallOrder[0];
+    if (subscribeOrder === undefined || snapshotOrder === undefined) {
+      throw new Error('Expected MCP status sync to subscribe and fetch a snapshot.');
+    }
+    expect(subscribeOrder).toBeLessThan(snapshotOrder);
+    const transcript = renderTranscript(driver);
+    expect(transcript).toContain('MCP server "local-tools" connected');
+    expect(transcript).toContain('2 tools (stdio)');
+    expect(transcript).toContain('MCP server "remote-tools" failed: connection refused');
+  });
+
+  it('deduplicates identical MCP status updates while allowing reconnect transitions', async () => {
+    const eventListeners: Array<(event: Event) => void> = [];
+    const connectedServer = {
+      name: 'local-tools',
+      transport: 'stdio',
+      status: 'connected',
+      toolCount: 2,
+    };
+    const session = makeSession({
+      onEvent: vi.fn((listener: (event: Event) => void) => {
+        eventListeners.push(listener);
+        return vi.fn();
+      }),
+      listMcpServers: vi.fn(async () => [connectedServer]),
+    });
+    const { driver } = await makeDriver(session);
+
+    driver.startSessionEventSubscription();
+    await Promise.resolve();
+    eventListeners[0]?.({
+      type: 'mcp.server.status',
+      agentId: 'main',
+      sessionId: 'ses-1',
+      server: connectedServer,
+    } as Event);
+
+    expect(countOccurrences(renderTranscript(driver), 'MCP server "local-tools" connected')).toBe(
+      1,
+    );
+
+    eventListeners[0]?.({
+      type: 'mcp.server.status',
+      agentId: 'main',
+      sessionId: 'ses-1',
+      server: {
+        ...connectedServer,
+        status: 'pending',
+        toolCount: 0,
+      },
+    } as Event);
+    eventListeners[0]?.({
+      type: 'mcp.server.status',
+      agentId: 'main',
+      sessionId: 'ses-1',
+      server: connectedServer,
+    } as Event);
+
+    expect(countOccurrences(renderTranscript(driver), 'MCP server "local-tools" connected')).toBe(
+      2,
+    );
+  });
+
+  it('does not let a late MCP snapshot overwrite a live status event', async () => {
+    const eventListeners: Array<(event: Event) => void> = [];
+    let resolveSnapshot: (
+      servers: Array<{
+        name: string;
+        transport: 'stdio' | 'http';
+        status: 'pending' | 'connected' | 'failed' | 'disabled';
+        toolCount: number;
+        error?: string;
+      }>,
+    ) => void = () => {};
+    const snapshot = new Promise((resolve) => {
+      resolveSnapshot = resolve;
+    });
+    const session = makeSession({
+      onEvent: vi.fn((listener: (event: Event) => void) => {
+        eventListeners.push(listener);
+        return vi.fn();
+      }),
+      listMcpServers: vi.fn(() => snapshot),
+    });
+    const { driver } = await makeDriver(session);
+
+    driver.startSessionEventSubscription();
+    eventListeners[0]?.({
+      type: 'mcp.server.status',
+      agentId: 'main',
+      sessionId: 'ses-1',
+      server: {
+        name: 'local-tools',
+        transport: 'stdio',
+        status: 'connected',
+        toolCount: 2,
+      },
+    } as Event);
+    resolveSnapshot([
+      {
+        name: 'local-tools',
+        transport: 'stdio',
+        status: 'failed',
+        toolCount: 0,
+        error: 'stale failure',
+      },
+    ]);
+    await Promise.resolve();
+
+    const transcript = renderTranscript(driver);
+    expect(transcript).toContain('MCP server "local-tools" connected');
+    expect(transcript).not.toContain('stale failure');
+  });
+
+  it('sends normal editor input to the active session and marks the turn as waiting', async () => {
+    const { driver, session } = await makeDriver();
+
+    driver.handleUserInput('hello');
+
+    expect(session.prompt).toHaveBeenCalledWith('hello');
+    expect(driver.state.appState.isStreaming).toBe(true);
+    expect(driver.state.appState.streamingPhase).toBe('waiting');
+    expect(driver.state.livePane.mode).toBe('waiting');
+    expect(driver.state.transcriptEntries).toEqual([
+      expect.objectContaining({
+        kind: 'user',
+        content: 'hello',
+      }),
+    ]);
+  });
+
+  it('sends pasted image placeholders as image content parts', async () => {
+    const { driver, session } = await makeDriver();
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const attachment = imageStore.addImage(new Uint8Array([0xaa, 0xbb]), 'image/png', 1, 1);
+
+    driver.handleUserInput(`describe ${attachment.placeholder}`);
+
+    expect(session.prompt).toHaveBeenCalledWith([
+      { type: 'text', text: 'describe ' },
+      { type: 'image_url', imageUrl: { url: 'data:image/png;base64,qrs=' } },
+    ]);
+    expect(driver.state.transcriptEntries).toEqual([
+      expect.objectContaining({
+        kind: 'user',
+        content: `describe ${attachment.placeholder}`,
+        imageAttachmentIds: [attachment.id],
+      }),
+    ]);
+  });
+
+  it('queues editor input instead of prompting while a turn is already streaming', async () => {
+    const { driver, session, harness } = await makeDriver();
+    driver.state.appState.isStreaming = true;
+    harness.track.mockClear();
+
+    driver.handleUserInput('queued message');
+
+    expect(session.prompt).not.toHaveBeenCalled();
+    expect(driver.state.queuedMessages).toEqual([{ text: 'queued message', agentId: 'main' }]);
+    expect(driver.state.queueContainer.children.length).toBeGreaterThan(0);
+    expect(harness.track).toHaveBeenCalledWith('input_queue', undefined);
+  });
+
+  it('cancels active streaming from Escape and Ctrl-C editor shortcuts', async () => {
+    const { driver, session } = await makeDriver();
+
+    driver.state.appState.isStreaming = true;
+    driver.state.editor.onEscape?.();
+
+    expect(session.cancel).toHaveBeenCalledTimes(1);
+
+    session.cancel.mockClear();
+    driver.state.appState.isStreaming = true;
+    driver.state.editor.onCtrlC?.();
+
+    expect(session.cancel).toHaveBeenCalledTimes(1);
+  });
+
+  it('dispatches the next queued message after the active turn ends', async () => {
+    vi.useFakeTimers();
+    try {
+      const { driver } = await makeDriver();
+      const sendQueued = vi.fn();
+      driver.state.appState.isStreaming = true;
+      driver.state.appState.streamingStartTime = 1;
+      driver.state.currentTurnId = '1';
+      driver.state.queuedMessages = [{ text: 'next' }];
+
+      driver.handleEvent(
+        {
+          type: 'turn.ended',
+          agentId: 'main',
+          sessionId: 'ses-1',
+          turnId: 1,
+          reason: 'completed',
+        } as Event,
+        sendQueued,
+      );
+      await vi.runAllTimersAsync();
+
+      expect(sendQueued).toHaveBeenCalledWith({ text: 'next' });
+      expect(driver.state.queuedMessages).toEqual([]);
+      expect(driver.state.appState.isStreaming).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('cancels manual compaction from the editor', async () => {
+    const { driver, session } = await makeDriver();
+    driver.handleEvent(
+      {
+        type: 'compaction.started',
+        agentId: 'main',
+        sessionId: 'ses-1',
+        trigger: 'manual',
+      } as Event,
+      vi.fn(),
+    );
+
+    driver.state.editor.onEscape?.();
+
+    expect(session.cancelCompaction).toHaveBeenCalledTimes(1);
+
+    session.cancelCompaction.mockClear();
+    driver.state.appState.isCompacting = true;
+    driver.state.editor.onCtrlC?.();
+
+    expect(session.cancelCompaction).toHaveBeenCalledTimes(1);
+  });
+
+  it('dispatches the next queued message after compaction is cancelled', async () => {
+    vi.useFakeTimers();
+    try {
+      const { driver } = await makeDriver();
+      const sendQueued = vi.fn();
+      driver.handleEvent(
+        {
+          type: 'compaction.started',
+          agentId: 'main',
+          sessionId: 'ses-1',
+          trigger: 'manual',
+        } as Event,
+        sendQueued,
+      );
+      driver.state.queuedMessages = [{ text: 'next' }];
+
+      driver.handleEvent(
+        {
+          type: 'compaction.cancelled',
+          agentId: 'main',
+          sessionId: 'ses-1',
+        } as Event,
+        sendQueued,
+      );
+      await vi.runAllTimersAsync();
+
+      expect(driver.state.appState.isCompacting).toBe(false);
+      expect(driver.state.appState.streamingPhase).toBe('idle');
+      expect(driver.state.queuedMessages).toEqual([]);
+      expect(sendQueued).toHaveBeenCalledWith({ text: 'next' });
+      expect(driver.state.transcriptContainer.render(120).map(stripSgr).join('\n')).toContain(
+        'Compaction cancelled',
+      );
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('renders an error instead of prompting when no model is selected', async () => {
+    const { driver, session } = await makeDriver();
+    driver.state.appState.model = '';
+
+    driver.handleUserInput('hello');
+
+    expect(session.prompt).not.toHaveBeenCalled();
+    expect(driver.state.transcriptContainer.render(120).join('\n')).toContain('LLM not set');
+  });
+
+  it('dispatches /init to the active session and clears busy state after completion', async () => {
+    let resolveInit: (() => void) | undefined;
+    const session = makeSession({
+      init: vi.fn(
+        () =>
+          new Promise<void>((resolve) => {
+            resolveInit = resolve;
+          }),
+      ),
+    });
+    const { driver, harness } = await makeDriver(session);
+    harness.track.mockClear();
+
+    driver.handleUserInput('/init');
+
+    await vi.waitFor(() => {
+      expect(session.init).toHaveBeenCalledTimes(1);
+    });
+    expect(session.prompt).not.toHaveBeenCalled();
+    expect(driver.state.appState.isStreaming).toBe(true);
+    expect(driver.state.livePane.mode).toBe('waiting');
+
+    resolveInit?.();
+
+    await vi.waitFor(() => {
+      expect(driver.state.appState.isStreaming).toBe(false);
+    });
+    expect(driver.state.livePane.mode).toBe('idle');
+    expect(harness.track).toHaveBeenCalledWith('init_complete', undefined);
+  });
+
+  it('queues Ctrl-S input instead of steering while /init is running', async () => {
+    let resolveInit: (() => void) | undefined;
+    const session = makeSession({
+      init: vi.fn(
+        () =>
+          new Promise<void>((resolve) => {
+            resolveInit = resolve;
+          }),
+      ),
+    });
+    const { driver } = await makeDriver(session);
+
+    driver.handleUserInput('/init');
+    await vi.waitFor(() => {
+      expect(session.init).toHaveBeenCalledTimes(1);
+    });
+
+    driver.state.editor.setText('apply after init');
+    driver.state.editor.onCtrlS?.();
+
+    expect(session.steer).not.toHaveBeenCalled();
+    expect(driver.state.queuedMessages).toEqual([{ text: 'apply after init', agentId: 'main' }]);
+    expect(stripSgr(driver.state.queueContainer.render(120).join('\n'))).not.toContain(
+      'ctrl-s to steer immediately',
+    );
+
+    resolveInit?.();
+
+    await vi.waitFor(() => {
+      expect(session.prompt).toHaveBeenCalledWith('apply after init');
+    });
+    expect(driver.state.queuedMessages).toEqual([]);
+  });
+
+  it('cancels the active /init request through the session', async () => {
+    let resolveInit: (() => void) | undefined;
+    const session = makeSession({
+      init: vi.fn(
+        () =>
+          new Promise<void>((resolve) => {
+            resolveInit = resolve;
+          }),
+      ),
+    });
+    const { driver } = await makeDriver(session);
+
+    driver.handleUserInput('/init');
+    await vi.waitFor(() => {
+      expect(session.init).toHaveBeenCalledTimes(1);
+    });
+
+    driver.state.editor.onEscape?.();
+
+    await vi.waitFor(() => {
+      expect(session.cancel).toHaveBeenCalledTimes(1);
+    });
+
+    resolveInit?.();
+  });
+
+  it('does not run /init when no model is selected', async () => {
+    const { driver, session } = await makeDriver();
+    driver.state.appState.model = '';
+
+    driver.handleUserInput('/init');
+
+    expect(session.init).not.toHaveBeenCalled();
+    expect(driver.state.transcriptContainer.render(120).join('\n')).toContain('LLM not set');
+  });
+
+  it('shows the login prompt for auth.login_required session errors', async () => {
+    const { driver } = await makeDriver();
+
+    driver.handleEvent(
+      {
+        type: 'error',
+        agentId: 'main',
+        sessionId: 'ses-1',
+        code: 'auth.login_required',
+        message: 'OAuth provider credentials were rejected.',
+        retryable: false,
+      } as Event,
+      vi.fn(),
+    );
+
+    const transcript = stripSgr(renderTranscript(driver));
+    expect(transcript).toContain('OAuth login expired. Send /login to login.');
+    expect(transcript).not.toContain('[auth.login_required]');
+    expect(transcript).not.toContain('kimi export');
+  });
+
+  it('appends the kimi export hint beneath session error messages', async () => {
+    const { driver } = await makeDriver();
+
+    driver.handleEvent(
+      {
+        type: 'error',
+        agentId: 'main',
+        sessionId: 'ses-1',
+        code: 'compaction.failed',
+        message: "APIStatusError: 400 the message at position 82 with role 'assistant' must not be empty",
+        retryable: false,
+      } as Event,
+      vi.fn(),
+    );
+
+    const transcript = stripSgr(driver.state.transcriptContainer.render(200).join('\n'));
+    expect(transcript).toContain('Error: [compaction.failed]');
+    expect(transcript).toContain('If this persists, run `kimi export ses-1`');
+    expect(transcript).toContain("Please don't share it publicly");
+  });
+
+  it('skips the kimi export hint when no active session id is set', async () => {
+    const { driver } = await makeDriver();
+    driver.state.appState.sessionId = '';
+
+    driver.handleEvent(
+      {
+        type: 'error',
+        agentId: 'main',
+        sessionId: '',
+        code: 'compaction.failed',
+        message: 'boom',
+        retryable: false,
+      } as Event,
+      vi.fn(),
+    );
+
+    const transcript = stripSgr(renderTranscript(driver));
+    expect(transcript).toContain('Error: [compaction.failed]');
+    expect(transcript).not.toContain('kimi export');
+  });
+
+  it('shows ExitPlanMode plan only in the current-plan card during approval', async () => {
+    const planContent = '# No Duplicate Plan\n\n- Do the non-duplicated plan work';
+    const session = makeSession({
+      getPlan: vi.fn(async () => ({
+        id: 'no-duplicate-plan',
+        content: planContent,
+        path: '/tmp/no-duplicate-plan.md',
+      })),
+    });
+    const { driver } = await makeDriver(session);
+
+    driver.handleEvent(
+      {
+        type: 'tool.call.started',
+        agentId: 'main',
+        sessionId: 'ses-1',
+        turnId: 1,
+        toolCallId: 'call_exit_plan',
+        name: 'ExitPlanMode',
+        args: {},
+      } as Event,
+      vi.fn(),
+    );
+
+    await vi.waitFor(() => {
+      const transcript = stripSgr(renderTranscript(driver));
+      expect(transcript).toContain('Current plan');
+      expect(countOccurrences(transcript, 'non-duplicated plan work')).toBe(1);
+    });
+
+    const approvalHandler = vi.mocked(session.setApprovalHandler).mock.calls[0]?.[0] as
+      | ((request: ApprovalRequest) => Promise<ApprovalResponse>)
+      | undefined;
+    if (approvalHandler === undefined) throw new Error('expected approval handler');
+    void approvalHandler({
+      turnId: 1,
+      toolCallId: 'call_exit_plan',
+      toolName: 'ExitPlanMode',
+      action: 'Review plan',
+      display: {
+        kind: 'plan_review',
+        plan: planContent,
+        path: '/tmp/no-duplicate-plan.md',
+      },
+    });
+
+    await vi.waitFor(() => {
+      const approval = stripSgr(driver.state.editorContainer.render(120).join('\n'));
+      expect(approval).toContain('Ready to build with this plan?');
+      expect(approval).not.toContain('non-duplicated plan work');
+      expect(approval).not.toContain('/tmp/no-duplicate-plan.md');
+    });
+  });
+
+  it('renders /status using the active session runtime status', async () => {
+    const session = makeSession({
+      getStatus: vi.fn(async () => ({
+        model: 'k2',
+        thinkingLevel: 'high',
+        permission: 'auto',
+        planMode: true,
+        contextTokens: 25,
+        maxContextTokens: 100,
+        contextUsage: 0.25,
+      })),
+    });
+    const { driver } = await makeDriver(session);
+    const getStatus = vi.mocked(session.getStatus);
+    const previousStatusCalls = getStatus.mock.calls.length;
+
+    driver.handleUserInput('/status');
+
+    await vi.waitFor(() => {
+      expect(getStatus).toHaveBeenCalledTimes(previousStatusCalls + 1);
+      const output = stripSgr(driver.state.transcriptContainer.render(120).join('\n'));
+      expect(output).toContain(' Status ');
+      expect(output).toContain('>_ Kimi Code');
+      expect(output).toContain('Model');
+      expect(output).toContain('thinking on');
+      expect(output).toContain('Permissions  auto');
+      expect(output).toContain('Plan mode    on');
+      expect(output).toContain('Context window');
+      expect(output).toContain('25.0%');
+    });
+  });
+
+  it('renders /mcp using a fresh MCP server snapshot', async () => {
+    const session = makeSession({
+      listMcpServers: vi.fn(async () => [
+        {
+          name: 'local-tools',
+          transport: 'stdio',
+          status: 'connected',
+          toolCount: 2,
+        },
+        {
+          name: 'remote-tools',
+          transport: 'http',
+          status: 'failed',
+          toolCount: 0,
+          error: 'connection refused',
+        },
+        {
+          name: 'linear',
+          transport: 'http',
+          status: 'needs-auth',
+          toolCount: 0,
+        },
+        {
+          name: 'disabled-tools',
+          transport: 'stdio',
+          status: 'disabled',
+          toolCount: 0,
+        },
+      ]),
+    });
+    const { driver } = await makeDriver(session);
+    const listMcpServers = vi.mocked(session.listMcpServers);
+    const previousCalls = listMcpServers.mock.calls.length;
+
+    driver.handleUserInput('/mcp');
+
+    await vi.waitFor(() => {
+      expect(listMcpServers).toHaveBeenCalledTimes(previousCalls + 1);
+      const output = stripSgr(driver.state.transcriptContainer.render(140).join('\n'));
+      expect(output).toContain(' MCP (4) ');
+      expect(output).toContain('Servers');
+      expect(output).toContain('local-tools');
+      expect(output).toContain('connected');
+      expect(output).toContain('stdio');
+      expect(output).toContain('2 tools');
+      expect(output).toContain('remote-tools');
+      expect(output).toContain('failed');
+      expect(output).toContain('connection refused');
+      expect(output).toContain('linear');
+      expect(output).toContain('needs auth');
+      expect(output).toContain('/mcp-config login linear');
+      expect(output).toContain('disabled-tools');
+      expect(output).toContain('disabled');
+      expect(output).toContain('1 connected · 1 needs auth · 1 failed · 1 disabled · 2 tools available');
+    });
+  });
+
+  it('renders an empty /mcp state when no MCP servers are configured', async () => {
+    const session = makeSession({
+      listMcpServers: vi.fn(async () => []),
+    });
+    const { driver } = await makeDriver(session);
+
+    driver.handleUserInput('/mcp');
+
+    await vi.waitFor(() => {
+      const output = stripSgr(driver.state.transcriptContainer.render(120).join('\n'));
+      expect(output).toContain('No MCP servers configured. Run /mcp-config to add one.');
+    });
+  });
+
+  it('renders /mcp list failures as command boundary errors', async () => {
+    const session = makeSession({
+      listMcpServers: vi.fn(async () => {
+        throw new Error('rpc unavailable');
+      }),
+    });
+    const { driver } = await makeDriver(session);
+
+    driver.handleUserInput('/mcp');
+
+    await vi.waitFor(() => {
+      const output = stripSgr(driver.state.transcriptContainer.render(120).join('\n'));
+      expect(output).toContain('Error: Failed to load MCP servers: rpc unavailable');
+    });
+  });
+
+  it('applies /model selection with inline thinking state', async () => {
+    const session = makeSession();
+    const { driver } = await makeDriver(session, {
+      getConfig: vi.fn(async () => ({
+        models: {
+          k2: {
+            provider: 'managed:kimi-code',
+            model: 'kimi-k2',
+            maxContextSize: 100,
+            displayName: 'Kimi K2',
+            capabilities: ['thinking'],
+          },
+          turbo: {
+            provider: 'managed:kimi-code',
+            model: 'kimi-turbo',
+            maxContextSize: 100,
+            displayName: 'Kimi Turbo',
+            capabilities: ['thinking'],
+          },
+        },
+      })),
+    });
+
+    driver.handleUserInput('/model turbo');
+
+    const picker = driver.state.editorContainer.children[0];
+    expect(picker).toBeInstanceOf(ModelSelectorComponent);
+    const pickerOutput = stripSgr((picker as ModelSelectorComponent).render(120).join('\n'));
+    expect(pickerOutput).toContain('Kimi K2 (Kimi Code) ← current');
+    expect(pickerOutput).toContain('❯ Kimi Turbo (Kimi Code)');
+    (picker as ModelSelectorComponent).handleInput('\u001B[D');
+    (picker as ModelSelectorComponent).handleInput('\r');
+
+    await vi.waitFor(() => {
+      expect(session.setModel).toHaveBeenCalledWith('turbo');
+      expect(session.setThinking).toHaveBeenCalledWith('on');
+    });
+    expect(driver.state.appState.model).toBe('turbo');
+    expect(driver.state.appState.thinking).toBe(true);
+  });
+
+  it('deletes Kitty inline images when /new clears the transcript', async () => {
+    setCapabilities({ images: 'kitty', trueColor: true, hyperlinks: true });
+    const { driver, harness } = await makeDriver(makeSession({ id: 'ses-1' }));
+    const nextSession = makeSession({ id: 'ses-2' });
+    harness.createSession.mockResolvedValueOnce(nextSession);
+    const write = vi.spyOn(driver.state.terminal, 'write').mockImplementation(() => {});
+
+    driver.handleUserInput('/new');
+
+    await vi.waitFor(() => {
+      expect(harness.createSession).toHaveBeenCalledTimes(2);
+      expect(driver.getCurrentSessionId()).toBe('ses-2');
+    });
+    expect(write).toHaveBeenCalledWith(deleteAllKittyImages());
+  });
+
+  it('forks the active session and switches to the returned session', async () => {
+    const originalTitle = process.title;
+    const source = makeSession({
+      id: 'ses-source',
+      summary: { title: 'Source title' },
+    });
+    const forked = makeSession({
+      id: 'ses-fork',
+      summary: { title: 'Fork: Source title' },
+    });
+    const forkSession = vi.fn(async () => forked);
+    const { driver, harness } = await makeDriver(source, { forkSession });
+
+    try {
+      driver.handleUserInput('/fork ignored args');
+
+      await vi.waitFor(() => {
+        expect(forkSession).toHaveBeenCalledWith({
+          id: 'ses-source',
+          title: 'Fork: Source title',
+        });
+        expect(driver.getCurrentSessionId()).toBe('ses-fork');
+      });
+      expect(process.title).toBe('Fork: Source title');
+      expect(source.close).toHaveBeenCalledOnce();
+      expect(forked.onEvent).toHaveBeenCalledOnce();
+      expect(harness.resumeSession).not.toHaveBeenCalled();
+      expect(driver.state.transcriptContainer.render(120).join('\n')).toContain(
+        'Session forked (ses-fork).',
+      );
+    } finally {
+      process.title = originalTitle;
+    }
+  });
+
+  it('keeps the current session when fork fails', async () => {
+    const forkSession = vi.fn(async () => {
+      throw new Error('fork unavailable');
+    });
+    const { driver } = await makeDriver(makeSession({ id: 'ses-source' }), { forkSession });
+
+    driver.handleUserInput('/fork');
+
+    await vi.waitFor(() => {
+      expect(forkSession).toHaveBeenCalledWith({
+        id: 'ses-source',
+        title: 'Fork: ses-source',
+      });
+      expect(driver.getCurrentSessionId()).toBe('ses-source');
+      expect(driver.state.transcriptContainer.render(120).join('\n')).toContain(
+        'Failed to fork session: fork unavailable',
+      );
+    });
+  });
+
+  it('renders newly streamed thinking expanded when ctrl+o toggle was already active', async () => {
+    const { driver } = await makeDriver();
+    driver.state.toolOutputExpanded = true;
+
+    const longThinking = ['t1', 't2', 't3', 't4', 't5', 't6', 't7'].join('\n');
+    driver.handleEvent(
+      {
+        type: 'thinking.delta',
+        agentId: 'main',
+        sessionId: 'ses-1',
+        delta: longThinking,
+      } as Event,
+      vi.fn(),
+    );
+    driver.handleEvent(
+      {
+        type: 'assistant.delta',
+        agentId: 'main',
+        sessionId: 'ses-1',
+        delta: 'answer',
+      } as Event,
+      vi.fn(),
+    );
+
+    const transcript = stripSgr(renderTranscript(driver));
+    expect(transcript).toContain('t7');
+    expect(transcript).not.toContain('ctrl+o to expand');
+  });
+
+  it('renders hook results without XML tags', async () => {
+    const { driver } = await makeDriver();
+
+    driver.handleEvent(
+      {
+        type: 'hook.result',
+        agentId: 'main',
+        sessionId: 'ses-1',
+        turnId: 1,
+        hookEvent: 'UserPromptSubmit',
+        content: '{}',
+      } as Event,
+      vi.fn(),
+    );
+
+    const transcript = stripSgr(renderTranscript(driver));
+    expect(transcript).toContain('UserPromptSubmit hook');
+    expect(transcript).toContain('{}');
+    expect(transcript).not.toContain('<hook_result');
+  });
+
+  it('renders empty hook results as empty status text', async () => {
+    const { driver } = await makeDriver();
+
+    driver.handleEvent(
+      {
+        type: 'hook.result',
+        agentId: 'main',
+        sessionId: 'ses-1',
+        turnId: 1,
+        hookEvent: 'UserPromptSubmit',
+        content: '',
+      } as Event,
+      vi.fn(),
+    );
+
+    const transcript = stripSgr(renderTranscript(driver));
+    expect(transcript).toContain('UserPromptSubmit hook');
+    expect(transcript).toContain('(empty)');
+    expect(transcript).not.toContain('<hook_result');
+  });
+});
diff --git a/apps/kimi-code/test/tui/kimi-tui-startup.test.ts b/apps/kimi-code/test/tui/kimi-tui-startup.test.ts
new file mode 100644
index 000000000..9d93ebfd5
--- /dev/null
+++ b/apps/kimi-code/test/tui/kimi-tui-startup.test.ts
@@ -0,0 +1,678 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { MigrationPlan } from "@moonshot-ai/migration-legacy";
+import { log } from "@moonshot-ai/kimi-code-sdk";
+
+import { KimiTUI, type KimiTUIStartupInput, type TUIState } from "#/tui/kimi-tui";
+import {
+  DISABLE_TERMINAL_THEME_REPORTING,
+  ENABLE_TERMINAL_THEME_REPORTING,
+  OSC11_QUERY,
+  QUERY_TERMINAL_THEME,
+  TERMINAL_THEME_LIGHT,
+} from "#/tui/utils/terminal-theme";
+
+interface StartupDriver {
+  state: TUIState;
+  init(): Promise<boolean>;
+  handleLoginCommand(): Promise<void>;
+  handleLogoutCommand(): Promise<void>;
+}
+
+interface ThemeTrackingDriver extends StartupDriver {
+  refreshTerminalThemeTracking(): void;
+}
+
+interface MigrateExitDriver extends StartupDriver {
+  start(): Promise<void>;
+  onExit?: (code?: number) => Promise<void>;
+  runMigrationScreen(plan: unknown): Promise<unknown>;
+  initMainTui(): Promise<boolean>;
+  terminalFocusTrackingDispose?: () => void;
+}
+
+const MIGRATION_PLAN: MigrationPlan = {
+  sourceHome: "/x/.kimi",
+  hasConfig: false,
+  hasMcp: false,
+  hasUserHistory: false,
+  oauthCredentials: [],
+  workdirs: [],
+  detectedPlugins: [],
+  detectedMcpOauthServers: [],
+  totalSessions: 0,
+};
+
+function makeStartupInput(
+  cliOptions: Partial<KimiTUIStartupInput["cliOptions"]> = {},
+  tuiConfig: Partial<KimiTUIStartupInput["tuiConfig"]> = {},
+  resolvedTheme: KimiTUIStartupInput["resolvedTheme"] = "dark",
+): KimiTUIStartupInput {
+  return {
+    cliOptions: {
+      session: undefined,
+      continue: false,
+      yolo: false,
+      plan: false,
+      model: undefined,
+      outputFormat: undefined,
+      prompt: undefined,
+      skillsDirs: [],
+      ...cliOptions,
+    },
+    tuiConfig: {
+      theme: "dark",
+      editorCommand: null,
+      notifications: { enabled: true, condition: "unfocused" },
+      ...tuiConfig,
+    },
+    version: "0.0.0-test",
+    workDir: "/tmp/proj-a",
+    resolvedTheme,
+  };
+}
+
+function makeSession(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "ses-1",
+    model: "k2",
+    summary: { title: "Session title" },
+    getStatus: vi.fn(async () => ({
+      model: "k2",
+      thinkingLevel: "off",
+      permission: "manual",
+      planMode: false,
+      contextTokens: 10,
+      maxContextTokens: 100,
+      contextUsage: 0.1,
+    })),
+    setApprovalHandler: vi.fn(),
+    setQuestionHandler: vi.fn(),
+    setModel: vi.fn(async () => {}),
+    setThinking: vi.fn(async () => {}),
+    setPermission: vi.fn(async () => {}),
+    setPlanMode: vi.fn(async () => {}),
+    onEvent: vi.fn(() => () => {}),
+    listSkills: vi.fn(async () => []),
+    close: vi.fn(async () => {}),
+    ...overrides,
+  };
+}
+
+function loginRequiredError(): Error & { readonly code: string } {
+  return Object.assign(new Error('OAuth provider "managed:kimi-code" requires login.'), {
+    code: "auth.login_required",
+  });
+}
+
+function makeHarness(session = makeSession(), overrides: Record<string, unknown> = {}) {
+  return {
+    getConfig: vi.fn(async () => ({
+      models: {
+        k2: { model: "moonshot-v1", maxContextSize: 100 },
+      },
+    })),
+    createSession: vi.fn(async () => session),
+    resumeSession: vi.fn(async () => session),
+    listSessions: vi.fn(async () => []),
+    close: vi.fn(async () => {}),
+    track: vi.fn(),
+    setTelemetryContext: vi.fn(),
+    auth: {
+      status: vi.fn(async () => ({ providers: [] })),
+      login: vi.fn(async () => {}),
+      logout: vi.fn(),
+      getManagedUsage: vi.fn(),
+    },
+    ...overrides,
+  };
+}
+
+function makeDriver(harness: ReturnType<typeof makeHarness>, input: KimiTUIStartupInput) {
+  const driver = new KimiTUI(harness as never, input) as unknown as StartupDriver;
+  vi.spyOn(driver.state.ui, "requestRender").mockImplementation(() => {});
+  vi.spyOn(driver.state.terminal, "setProgress").mockImplementation(() => {});
+  return driver;
+}
+
+type InputListener = Parameters<TUIState["ui"]["addInputListener"]>[0];
+const DARK_OSC11_REPORT = "\u001B]11;rgb:2828/2c2c/3434\u0007";
+const LIGHT_OSC11_REPORT = "\u001B]11;rgb:fafa/fbfb/fcfc\u0007";
+
+function captureInputListeners(driver: StartupDriver) {
+  const listeners: InputListener[] = [];
+  const removeInputListener = vi.fn<() => void>();
+  const write = vi.spyOn(driver.state.terminal, "write").mockImplementation(() => {});
+  const addInputListener = vi
+    .spyOn(driver.state.ui, "addInputListener")
+    .mockImplementation((listener: InputListener) => {
+      listeners.push(listener);
+      return removeInputListener;
+    });
+
+  return { listeners, removeInputListener, write, addInputListener };
+}
+
+describe("KimiTUI startup", () => {
+  it("creates a fresh session from startup flags and syncs runtime state", async () => {
+    const session = makeSession({
+      getStatus: vi.fn(async () => ({
+        model: "k2",
+        thinkingLevel: "off",
+        permission: "yolo",
+        planMode: true,
+        contextTokens: 25,
+        maxContextTokens: 200,
+        contextUsage: 0.125,
+      })),
+    });
+    const harness = makeHarness(session);
+    const driver = makeDriver(harness, makeStartupInput({ yolo: true, plan: true }));
+
+    await expect(driver.init()).resolves.toBe(false);
+
+    expect(harness.createSession).toHaveBeenCalledWith({
+      workDir: "/tmp/proj-a",
+      permission: "yolo",
+      planMode: true,
+    });
+    expect(session.setApprovalHandler).toHaveBeenCalledOnce();
+    expect(session.setQuestionHandler).toHaveBeenCalledOnce();
+    expect(harness.setTelemetryContext).toHaveBeenCalledWith({ sessionId: null });
+    expect(harness.setTelemetryContext).toHaveBeenLastCalledWith({ sessionId: "ses-1" });
+    expect(driver.state.startupState).toBe("ready");
+    expect(driver.state.appState).toMatchObject({
+      sessionId: "ses-1",
+      model: "k2",
+      permissionMode: "yolo",
+      yolo: true,
+      planMode: true,
+      contextTokens: 25,
+      maxContextTokens: 200,
+      contextUsage: 0.125,
+      sessionTitle: "Session title",
+    });
+  });
+
+  it("resumes the latest session for --continue and marks history for replay", async () => {
+    const session = makeSession({ id: "ses-latest" });
+    const harness = makeHarness(session, {
+      listSessions: vi.fn(async () => [{ id: "ses-latest" }, { id: "ses-old" }]),
+    });
+    const driver = makeDriver(harness, makeStartupInput({ continue: true }));
+
+    await expect(driver.init()).resolves.toBe(true);
+
+    expect(harness.resumeSession).toHaveBeenCalledWith({ id: "ses-latest" });
+    expect(harness.createSession).not.toHaveBeenCalled();
+    expect(driver.state.startupState).toBe("ready");
+    expect(driver.state.appState.sessionId).toBe("ses-latest");
+  });
+
+  it("passes the CLI model override when creating a fresh startup session", async () => {
+    const harness = makeHarness();
+    const driver = makeDriver(harness, makeStartupInput({ model: "kimi-code/k2.5" }));
+
+    await expect(driver.init()).resolves.toBe(false);
+
+    expect(harness.createSession).toHaveBeenCalledWith({
+      workDir: "/tmp/proj-a",
+      model: "kimi-code/k2.5",
+      permission: undefined,
+      planMode: undefined,
+    });
+  });
+
+  it("applies the CLI model override when resuming a startup session", async () => {
+    let model = "k2";
+    const session = makeSession({
+      setModel: vi.fn(async (nextModel: string) => {
+        model = nextModel;
+      }),
+      getStatus: vi.fn(async () => ({
+        model,
+        thinkingLevel: "off",
+        permission: "manual",
+        planMode: false,
+        contextTokens: 10,
+        maxContextTokens: 100,
+        contextUsage: 0.1,
+      })),
+    });
+    const harness = makeHarness(session, {
+      listSessions: vi.fn(async () => [{ id: "ses-latest" }]),
+    });
+    const driver = makeDriver(
+      harness,
+      makeStartupInput({ continue: true, model: "kimi-code/k2.5" }),
+    );
+
+    await expect(driver.init()).resolves.toBe(true);
+
+    expect(session.setModel).toHaveBeenCalledWith("kimi-code/k2.5");
+    expect(driver.state.appState.model).toBe("kimi-code/k2.5");
+  });
+
+  it("enters picker startup for bare --session without creating a session", async () => {
+    const harness = makeHarness();
+    const driver = makeDriver(harness, makeStartupInput({ session: "" }));
+
+    await expect(driver.init()).resolves.toBe(false);
+
+    expect(harness.createSession).not.toHaveBeenCalled();
+    expect(harness.resumeSession).not.toHaveBeenCalled();
+    expect(driver.state.startupState).toBe("picker");
+  });
+
+  it("tracks terminal theme reports while auto theme is active", () => {
+    const harness = makeHarness();
+    const driver = makeDriver(
+      harness,
+      makeStartupInput({}, { theme: "auto" }, "dark"),
+    ) as unknown as ThemeTrackingDriver;
+    const { listeners, write, addInputListener } = captureInputListeners(driver);
+
+    driver.refreshTerminalThemeTracking();
+
+    expect(addInputListener).toHaveBeenCalledOnce();
+    expect(write).toHaveBeenCalledWith(ENABLE_TERMINAL_THEME_REPORTING);
+    expect(write).toHaveBeenCalledWith(OSC11_QUERY);
+    expect(write).toHaveBeenCalledWith(QUERY_TERMINAL_THEME);
+    expect(listeners).toHaveLength(1);
+
+    write.mockClear();
+    expect(listeners[0]?.(TERMINAL_THEME_LIGHT)).toEqual({ consume: true });
+    expect(write).toHaveBeenCalledWith(OSC11_QUERY);
+    expect(driver.state.appState.theme).toBe("auto");
+    expect(driver.state.theme.resolvedTheme).toBe("dark");
+    expect(driver.state.ui.requestRender).not.toHaveBeenCalled();
+
+    expect(listeners[0]?.(DARK_OSC11_REPORT)).toEqual({ consume: true });
+    expect(driver.state.appState.theme).toBe("auto");
+    expect(driver.state.theme.resolvedTheme).toBe("dark");
+    expect(driver.state.ui.requestRender).not.toHaveBeenCalled();
+
+    expect(listeners[0]?.(LIGHT_OSC11_REPORT)).toEqual({ consume: true });
+    expect(driver.state.appState.theme).toBe("auto");
+    expect(driver.state.theme.resolvedTheme).toBe("light");
+    expect(driver.state.ui.requestRender).toHaveBeenCalled();
+  });
+
+  it("does not track terminal theme reports for explicit themes", () => {
+    const harness = makeHarness();
+    const driver = makeDriver(harness, makeStartupInput()) as unknown as ThemeTrackingDriver;
+    const { write, addInputListener } = captureInputListeners(driver);
+
+    driver.refreshTerminalThemeTracking();
+
+    expect(addInputListener).not.toHaveBeenCalled();
+    expect(write).not.toHaveBeenCalled();
+  });
+
+  it("disables terminal theme reports after leaving auto theme", () => {
+    const harness = makeHarness();
+    const driver = makeDriver(
+      harness,
+      makeStartupInput({}, { theme: "auto" }, "dark"),
+    ) as unknown as ThemeTrackingDriver;
+    const { write, removeInputListener } = captureInputListeners(driver);
+
+    driver.refreshTerminalThemeTracking();
+    driver.state.appState.theme = "dark";
+    driver.refreshTerminalThemeTracking();
+
+    expect(removeInputListener).toHaveBeenCalledOnce();
+    expect(write).toHaveBeenCalledWith(DISABLE_TERMINAL_THEME_REPORTING);
+  });
+
+  it("starts TUI without a session when fresh startup needs OAuth login", async () => {
+    const harness = makeHarness(makeSession(), {
+      createSession: vi.fn(async () => {
+        throw loginRequiredError();
+      }),
+    });
+    const driver = makeDriver(harness, makeStartupInput());
+
+    await expect(driver.init()).resolves.toBe(false);
+
+    expect(driver.state.startupState).toBe("ready");
+    expect(driver.state.startupNotice).toContain("OAuth login expired");
+    expect(driver.state.appState).toMatchObject({
+      sessionId: "",
+      model: "",
+      thinking: false,
+      contextTokens: 0,
+      maxContextTokens: 0,
+      contextUsage: 0,
+      sessionTitle: null,
+    });
+  });
+
+  it("preserves fresh startup yolo and plan intent after OAuth login", async () => {
+    const session = makeSession({
+      getStatus: vi.fn(async () => ({
+        model: "k2",
+        thinkingLevel: "off",
+        permission: "yolo",
+        planMode: true,
+        contextTokens: 10,
+        maxContextTokens: 100,
+        contextUsage: 0.1,
+      })),
+    });
+    const createSession = vi
+      .fn()
+      .mockRejectedValueOnce(loginRequiredError())
+      .mockResolvedValueOnce(session);
+    const harness = makeHarness(session, {
+      getConfig: vi.fn(async () => ({
+        defaultModel: "k2",
+        defaultThinking: false,
+        models: {
+          k2: { model: "moonshot-v1", maxContextSize: 100 },
+        },
+      })),
+      createSession,
+    });
+    const driver = makeDriver(harness, makeStartupInput({ yolo: true, plan: true }));
+
+    await expect(driver.init()).resolves.toBe(false);
+
+    expect(driver.state.appState).toMatchObject({
+      sessionId: "",
+      model: "",
+      permissionMode: "yolo",
+      yolo: true,
+      planMode: true,
+    });
+
+    vi.spyOn(driver as any, 'promptPlatformSelection').mockResolvedValue('kimi-code');
+    await driver.handleLoginCommand();
+
+    expect(createSession).toHaveBeenNthCalledWith(1, {
+      workDir: "/tmp/proj-a",
+      permission: "yolo",
+      planMode: true,
+    });
+    expect(createSession).toHaveBeenNthCalledWith(2, {
+      workDir: "/tmp/proj-a",
+      model: "k2",
+      thinking: "off",
+      permission: "yolo",
+      planMode: true,
+    });
+    expect(driver.state.appState).toMatchObject({
+      sessionId: "ses-1",
+      model: "k2",
+      permissionMode: "yolo",
+      yolo: true,
+      planMode: true,
+    });
+  });
+
+  it("does not force manual permission after OAuth login without --yolo", async () => {
+    const session = makeSession({
+      getStatus: vi.fn(async () => ({
+        model: "k2",
+        thinkingLevel: "off",
+        permission: "auto",
+        planMode: false,
+        contextTokens: 10,
+        maxContextTokens: 100,
+        contextUsage: 0.1,
+      })),
+    });
+    const createSession = vi
+      .fn()
+      .mockRejectedValueOnce(loginRequiredError())
+      .mockResolvedValueOnce(session);
+    const harness = makeHarness(session, {
+      getConfig: vi.fn(async () => ({
+        defaultModel: "k2",
+        defaultThinking: false,
+        models: {
+          k2: { model: "moonshot-v1", maxContextSize: 100 },
+        },
+      })),
+      createSession,
+    });
+    const driver = makeDriver(harness, makeStartupInput());
+
+    await expect(driver.init()).resolves.toBe(false);
+    vi.spyOn(driver as any, 'promptPlatformSelection').mockResolvedValue('kimi-code');
+    await driver.handleLoginCommand();
+
+    expect(createSession).toHaveBeenNthCalledWith(2, {
+      workDir: "/tmp/proj-a",
+      model: "k2",
+      thinking: "off",
+      permission: undefined,
+      planMode: undefined,
+    });
+    expect(driver.state.appState).toMatchObject({
+      permissionMode: "auto",
+      yolo: false,
+    });
+  });
+
+  it("syncs configured thinking after OAuth login refreshes an active session", async () => {
+    const session = makeSession();
+    const harness = makeHarness(session, {
+      getConfig: vi.fn(async () => ({
+        defaultModel: "k2",
+        defaultThinking: true,
+        models: {
+          k2: { model: "moonshot-v1", maxContextSize: 100 },
+        },
+      })),
+    });
+    const driver = makeDriver(harness, makeStartupInput());
+
+    await expect(driver.init()).resolves.toBe(false);
+    expect(driver.state.appState.thinking).toBe(false);
+
+    vi.spyOn(driver as any, 'promptPlatformSelection').mockResolvedValue('kimi-code');
+    await driver.handleLoginCommand();
+
+    expect(session.setModel).toHaveBeenCalledWith("k2");
+    expect(session.setThinking).toHaveBeenCalledWith("on");
+    expect(driver.state.appState).toMatchObject({
+      model: "k2",
+      thinking: true,
+      maxContextTokens: 100,
+    });
+    expect(harness.track).toHaveBeenCalledWith("login", {
+      provider: "managed:kimi-code",
+      already_logged_in: false,
+    });
+  });
+
+  it("tracks login with already_logged_in when a token already exists", async () => {
+    const session = makeSession();
+    const harness = makeHarness(session, {
+      auth: {
+        status: vi.fn(async () => ({
+          providers: [{ providerName: "managed:kimi-code", hasToken: true }],
+        })),
+        login: vi.fn(async () => {}),
+        logout: vi.fn(),
+        getManagedUsage: vi.fn(),
+      },
+    });
+    const driver = makeDriver(harness, makeStartupInput());
+
+    await expect(driver.init()).resolves.toBe(false);
+    harness.track.mockClear();
+
+    vi.spyOn(driver as any, 'promptPlatformSelection').mockResolvedValue('kimi-code');
+    await driver.handleLoginCommand();
+
+    expect(harness.auth.login).toHaveBeenCalledWith(
+      "managed:kimi-code",
+      expect.objectContaining({
+        signal: expect.any(AbortSignal),
+        onDeviceCode: expect.any(Function),
+      }),
+    );
+    expect(harness.track).toHaveBeenCalledWith("login", {
+      provider: "managed:kimi-code",
+      already_logged_in: true,
+    });
+  });
+
+  it("logs login failures with session context", async () => {
+    const warn = vi.spyOn(log, "warn").mockImplementation(() => {});
+    const session = makeSession();
+    const loginError = new Error("Failed to list Kimi Code models (HTTP 402).");
+    const harness = makeHarness(session, {
+      auth: {
+        status: vi.fn(async () => ({ providers: [] })),
+        login: vi.fn(async () => {
+          throw loginError;
+        }),
+        logout: vi.fn(),
+        getManagedUsage: vi.fn(),
+      },
+    });
+    const driver = makeDriver(harness, makeStartupInput());
+
+    try {
+      await expect(driver.init()).resolves.toBe(false);
+
+      vi.spyOn(driver as any, 'promptPlatformSelection').mockResolvedValue('kimi-code');
+      await driver.handleLoginCommand();
+
+      expect(harness.auth.login).toHaveBeenCalledWith(
+        "managed:kimi-code",
+        expect.objectContaining({
+          signal: expect.any(AbortSignal),
+          onDeviceCode: expect.any(Function),
+        }),
+      );
+      expect(warn).toHaveBeenCalledWith(
+        "login failed",
+        expect.objectContaining({
+          providerName: "managed:kimi-code",
+          alreadyLoggedIn: false,
+          sessionId: "ses-1",
+          error: expect.objectContaining({
+            message: "Failed to list Kimi Code models (HTTP 402).",
+          }),
+        }),
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("tracks logout after managed credentials and session state are cleared", async () => {
+    const session = makeSession();
+    const harness = makeHarness(session);
+    const driver = makeDriver(harness, makeStartupInput());
+
+    await expect(driver.init()).resolves.toBe(false);
+    harness.track.mockClear();
+
+    await driver.handleLogoutCommand();
+
+    expect(harness.auth.logout).toHaveBeenCalledWith("managed:kimi-code");
+    expect(session.close).toHaveBeenCalledOnce();
+    expect(driver.state.appState).toMatchObject({
+      sessionId: "",
+      model: "",
+      sessionTitle: null,
+    });
+    expect(harness.track).toHaveBeenCalledWith("logout", { provider: "managed:kimi-code" });
+  });
+
+  it("starts TUI without replaying when --continue needs OAuth login", async () => {
+    const harness = makeHarness(makeSession(), {
+      listSessions: vi.fn(async () => [{ id: "ses-latest" }]),
+      resumeSession: vi.fn(async () => {
+        throw loginRequiredError();
+      }),
+    });
+    const driver = makeDriver(harness, makeStartupInput({ continue: true }));
+
+    await expect(driver.init()).resolves.toBe(false);
+
+    expect(harness.resumeSession).toHaveBeenCalledWith({ id: "ses-latest" });
+    expect(harness.createSession).not.toHaveBeenCalled();
+    expect(driver.state.startupState).toBe("ready");
+    expect(driver.state.appState.sessionId).toBe("");
+  });
+
+  it("starts TUI without replaying when an explicit resume needs OAuth login", async () => {
+    const harness = makeHarness(makeSession(), {
+      listSessions: vi.fn(async () => [{ id: "ses-target" }]),
+      resumeSession: vi.fn(async () => {
+        throw loginRequiredError();
+      }),
+    });
+    const driver = makeDriver(harness, makeStartupInput({ session: "ses-target" }));
+
+    await expect(driver.init()).resolves.toBe(false);
+
+    expect(harness.resumeSession).toHaveBeenCalledWith({ id: "ses-target" });
+    expect(driver.state.startupState).toBe("ready");
+    expect(driver.state.appState.sessionId).toBe("");
+  });
+
+  it("disposes terminal focus/theme tracking on the kimi migrate exit", async () => {
+    const harness = makeHarness();
+    const driver = makeDriver(harness, {
+      ...makeStartupInput(),
+      migrationPlan: MIGRATION_PLAN,
+      migrateOnly: true,
+    }) as unknown as MigrateExitDriver;
+    // pi-tui start/stop and focus tracking touch the real TTY — stub the I/O.
+    vi.spyOn(driver.state.ui, "start").mockImplementation(() => {});
+    vi.spyOn(driver.state.ui, "stop").mockImplementation(() => {});
+    vi.spyOn(driver.state.terminal, "write").mockImplementation(() => {});
+    // The migration screen would await user input; resolve it immediately.
+    vi.spyOn(driver, "runMigrationScreen").mockResolvedValue({ decision: "later" });
+    const onExit = vi.fn(async () => {});
+    driver.onExit = onExit;
+
+    await driver.start();
+
+    // `kimi migrate` exits via process.exit; startEventLoop() installed focus
+    // tracking, so the exit path must dispose it — otherwise the terminal
+    // keeps emitting focus/OSC sequences after the command finishes.
+    expect(driver.terminalFocusTrackingDispose).toBeUndefined();
+    expect(onExit).toHaveBeenCalledWith(0);
+  });
+
+  it("disposes terminal tracking when post-migration startup fails", async () => {
+    const harness = makeHarness();
+    const driver = makeDriver(harness, {
+      ...makeStartupInput(),
+      migrationPlan: MIGRATION_PLAN,
+      migrateOnly: false,
+    }) as unknown as MigrateExitDriver;
+    vi.spyOn(driver.state.ui, "start").mockImplementation(() => {});
+    vi.spyOn(driver.state.ui, "stop").mockImplementation(() => {});
+    vi.spyOn(driver.state.terminal, "write").mockImplementation(() => {});
+    // The migration screen resolves "later"; startup then continues into
+    // initMainTui(), which fails (e.g. a session-resume error).
+    vi.spyOn(driver, "runMigrationScreen").mockResolvedValue({ decision: "later" });
+    vi.spyOn(driver, "initMainTui").mockRejectedValue(new Error("resume boom"));
+
+    await expect(driver.start()).rejects.toThrow("resume boom");
+
+    // The focus tracking installed by startEventLoop() must be torn down
+    // before the error propagates — not left active after the process exits.
+    expect(driver.terminalFocusTrackingDispose).toBeUndefined();
+  });
+
+  it("keeps non-login startup session errors fatal", async () => {
+    const harness = makeHarness(makeSession(), {
+      createSession: vi.fn(async () => {
+        throw new Error("provider config is invalid");
+      }),
+    });
+    const driver = makeDriver(harness, makeStartupInput());
+
+    await expect(driver.init()).rejects.toThrow("provider config is invalid");
+  });
+});
diff --git a/apps/kimi-code/test/tui/media-url.test.ts b/apps/kimi-code/test/tui/media-url.test.ts
new file mode 100644
index 000000000..79c73b9f9
--- /dev/null
+++ b/apps/kimi-code/test/tui/media-url.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+
+import { mediaUrlPartToText, summarizeDataUrl } from '#/tui/utils/media-url';
+
+describe('mediaUrlPartToText', () => {
+  it('keeps non-data URLs as escaped XML-like references', () => {
+    expect(mediaUrlPartToText('image', 'file:///tmp/a&b".png')).toBe(
+      '<image url="file:///tmp/a&amp;b&quot;.png">',
+    );
+  });
+
+  it('summarizes base64 data URLs without returning the payload', () => {
+    expect(mediaUrlPartToText('image', 'data:image/png;base64,qrs=')).toBe(
+      '[image image/png, 2 B]',
+    );
+  });
+
+  it('formats larger base64 payload sizes compactly', () => {
+    const oneKib = 'A'.repeat(1368);
+    expect(mediaUrlPartToText('video', `data:video/mp4;base64,${oneKib}`)).toBe(
+      '[video video/mp4, 1.0 KB]',
+    );
+  });
+});
+
+describe('summarizeDataUrl', () => {
+  it('returns undefined for regular URLs', () => {
+    expect(summarizeDataUrl('https://example.com/a.png')).toBeUndefined();
+  });
+
+  it('parses MIME and decoded byte count for base64 data URLs', () => {
+    expect(summarizeDataUrl('data:image/png;base64,AQIDBA==')).toEqual({
+      mime: 'image/png',
+      bytes: 4,
+    });
+  });
+});
diff --git a/apps/kimi-code/test/tui/printable-key-guard.test.ts b/apps/kimi-code/test/tui/printable-key-guard.test.ts
new file mode 100644
index 000000000..f7be25b1c
--- /dev/null
+++ b/apps/kimi-code/test/tui/printable-key-guard.test.ts
@@ -0,0 +1,69 @@
+/**
+ * Guard test: scan every TUI component and reject `data === '<printable>'`
+ * bare-literal comparisons. When the terminal enables the Kitty keyboard
+ * protocol (e.g. the VSCode integrated terminal), printable keys arrive as
+ * CSI-u sequences, so a bare comparison silently disables the shortcut.
+ * See `apps/kimi-code/src/tui/utils/printable-key.ts`.
+ *
+ * Every printable-character comparison must first go through
+ * `printableChar(data)`. Control characters (codepoint < 32) should use
+ * `matchesKey` with `Key.*` or stay as escape literals (`'\t'`, ...);
+ * those are exempted by the guard's regex.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+const COMPONENTS_ROOT = join(__dirname, '..', '..', 'src', 'tui', 'components');
+
+function walk(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry);
+    const s = statSync(p);
+    if (s.isDirectory()) out.push(...walk(p));
+    else if (entry.endsWith('.ts') || entry.endsWith('.tsx')) out.push(p);
+  }
+  return out;
+}
+
+// Single-character visible-ASCII (codepoint 32-126) bare-literal
+// comparisons, e.g. `data === 'q'`, `data === ' '`. The regex deliberately
+// permits escape sequences (`data === '\t'`, control-char literals),
+// multi-character sequences (`data === '[A'`), and comparisons on
+// variables other than `data` (the decoded value is usually `k` or
+// `printable`).
+const BARE_PRINTABLE = /\bdata\s*===\s*'([\u0020-\u007E])'/g;
+
+describe('TUI handleInput — printable-key guard', () => {
+  it('forbids bare-literal printable comparisons on `data` (use printableChar)', () => {
+    const offenders: { file: string; line: number; snippet: string }[] = [];
+    for (const file of walk(COMPONENTS_ROOT)) {
+      const content = readFileSync(file, 'utf8');
+      const lines = content.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (line.trimStart().startsWith('//')) continue;
+        BARE_PRINTABLE.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = BARE_PRINTABLE.exec(line)) !== null) {
+          offenders.push({
+            file: file.slice(file.indexOf('src/')),
+            line: i + 1,
+            snippet: line.trim(),
+          });
+        }
+      }
+    }
+    expect(
+      offenders,
+      `Found bare-literal \`data === '...'\` comparisons. ` +
+        `In VSCode/Kitty terminals these never match because keys arrive as ` +
+        `CSI-u sequences. Use \`printableChar(data)\` from ` +
+        `\`@/tui/utils/printable-key\` and compare the decoded value instead.\n` +
+        offenders.map((o) => `  ${o.file}:${String(o.line)}  ${o.snippet}`).join('\n'),
+    ).toEqual([]);
+  });
+});
diff --git a/apps/kimi-code/test/tui/replay-ops.test.ts b/apps/kimi-code/test/tui/replay-ops.test.ts
new file mode 100644
index 000000000..2a366e6cc
--- /dev/null
+++ b/apps/kimi-code/test/tui/replay-ops.test.ts
@@ -0,0 +1,566 @@
+import type {
+  AgentReplayRecord,
+  BackgroundTaskInfo,
+  ContentPart,
+  PromptOrigin,
+  Role,
+  ToolCall,
+} from '@moonshot-ai/kimi-code-sdk';
+import { describe, expect, it } from 'vitest';
+
+import { projectReplayRecords } from '#/tui/actions/replay-ops';
+
+interface ReplayMessageExtra {
+  readonly toolCalls?: readonly ToolCall[];
+  readonly toolCallId?: string;
+  readonly origin?: PromptOrigin;
+  readonly isError?: boolean;
+}
+
+function message(
+  role: Role,
+  content: readonly ContentPart[],
+  extra: ReplayMessageExtra = {},
+): AgentReplayRecord {
+  return {
+    type: 'message',
+    message: {
+      role,
+      content: [...content],
+      toolCalls: [...(extra.toolCalls ?? [])],
+      toolCallId: extra.toolCallId,
+      origin: extra.origin,
+      isError: extra.isError,
+    },
+  };
+}
+
+function backgroundTask(
+  taskId: string,
+  description: string,
+  status: BackgroundTaskInfo['status'] = 'running',
+): BackgroundTaskInfo {
+  return {
+    taskId,
+    command: `[agent] ${description}`,
+    description,
+    status,
+    pid: 0,
+    exitCode: status === 'completed' ? 0 : null,
+    startedAt: 1,
+    endedAt: status === 'running' || status === 'awaiting_approval' ? null : 2,
+  };
+}
+
+describe('projectReplayRecords', () => {
+  it('projects only the most recent ten visible user turns from agent replay', () => {
+    const projected = projectReplayRecords(
+      Array.from({ length: 12 }, (_, index) => [
+        message('user', [{ type: 'text', text: `prompt ${index}` }]),
+        message('assistant', [{ type: 'text', text: `answer ${index}` }]),
+      ]).flat(),
+    );
+
+    expect(
+      projected.entries.filter((entry) => entry.kind === 'user').map((entry) => entry.content),
+    ).toEqual([
+      'prompt 2',
+      'prompt 3',
+      'prompt 4',
+      'prompt 5',
+      'prompt 6',
+      'prompt 7',
+      'prompt 8',
+      'prompt 9',
+      'prompt 10',
+      'prompt 11',
+    ]);
+    expect(
+      projected.entries.filter((entry) => entry.kind === 'assistant').map((entry) => entry.content),
+    ).toEqual([
+      'answer 2',
+      'answer 3',
+      'answer 4',
+      'answer 5',
+      'answer 6',
+      'answer 7',
+      'answer 8',
+      'answer 9',
+      'answer 10',
+      'answer 11',
+    ]);
+  });
+
+  it('does not count model-triggered skill activations as user turns', () => {
+    const records: AgentReplayRecord[] = Array.from({ length: 9 }, (_, index) => [
+      message('user', [{ type: 'text', text: `prompt ${index}` }]),
+      message('assistant', [{ type: 'text', text: `answer ${index}` }]),
+    ]).flat();
+    for (const index of [0, 1, 2, 3]) {
+      records.push(
+        message('user', [{ type: 'text', text: `Skill body ${index}` }], {
+          origin: {
+            kind: 'skill_activation',
+            activationId: `act-${index}`,
+            skillName: 'review',
+            trigger: 'model-tool',
+          },
+        }),
+      );
+    }
+
+    const projected = projectReplayRecords(records);
+
+    expect(
+      projected.entries.filter((entry) => entry.kind === 'user').map((entry) => entry.content),
+    ).toEqual([
+      'prompt 0',
+      'prompt 1',
+      'prompt 2',
+      'prompt 3',
+      'prompt 4',
+      'prompt 5',
+      'prompt 6',
+      'prompt 7',
+      'prompt 8',
+    ]);
+    expect(projected.entries.filter((entry) => entry.kind === 'skill_activation')).toHaveLength(4);
+  });
+
+  it('projects UserPromptSubmit hook results as assistant transcript entries', () => {
+    const hookResult =
+      '<hook_result hook_event="UserPromptSubmit">\nhook response 1\n</hook_result>\n<hook_result hook_event="UserPromptSubmit">\nhook response 2\n</hook_result>';
+    const projected = projectReplayRecords([
+      message('user', [{ type: 'text', text: 'prompt' }]),
+      message('user', [{ type: 'text', text: hookResult }], {
+        origin: { kind: 'hook_result', event: 'UserPromptSubmit' },
+      }),
+      message('assistant', [{ type: 'text', text: 'model response' }]),
+    ]);
+
+    expect(projected.entries.map((e) => [e.kind, e.content])).toEqual([
+      ['user', 'prompt'],
+      [
+        'assistant',
+        '*UserPromptSubmit hook*\n\nhook response 1\n\n*UserPromptSubmit hook*\n\nhook response 2',
+      ],
+      ['assistant', 'model response'],
+    ]);
+  });
+
+  it('projects blocking UserPromptSubmit hook results from replayed assistant entries', () => {
+    const hookResult =
+      '<hook_result hook_event="UserPromptSubmit">\nblocked reason\n</hook_result>';
+    const projected = projectReplayRecords([
+      message('user', [{ type: 'text', text: 'blocked prompt' }]),
+      message('assistant', [{ type: 'text', text: hookResult }], {
+        origin: { kind: 'hook_result', event: 'UserPromptSubmit', blocked: true },
+      }),
+    ]);
+
+    expect(projected.entries.map((e) => [e.kind, e.content])).toEqual([
+      ['user', 'blocked prompt'],
+      ['assistant', '*UserPromptSubmit hook blocked*\n\nblocked reason'],
+    ]);
+  });
+
+  it('does not infer blocked UserPromptSubmit hook results from assistant role alone', () => {
+    const hookResult =
+      '<hook_result hook_event="UserPromptSubmit">\nlegacy hook response\n</hook_result>';
+    const projected = projectReplayRecords([
+      message('user', [{ type: 'text', text: 'prompt' }]),
+      message('assistant', [{ type: 'text', text: hookResult }], {
+        origin: { kind: 'hook_result', event: 'UserPromptSubmit' },
+      }),
+    ]);
+
+    expect(projected.entries.map((e) => [e.kind, e.content])).toEqual([
+      ['user', 'prompt'],
+      ['assistant', '*UserPromptSubmit hook*\n\nlegacy hook response'],
+    ]);
+  });
+
+  it('preserves literal hook result XML from normal assistant replies', () => {
+    const hookResult =
+      '<hook_result hook_event="UserPromptSubmit">\nhook response\n</hook_result>';
+    const projected = projectReplayRecords([
+      message('user', [{ type: 'text', text: 'show me the hook XML' }]),
+      message('assistant', [{ type: 'text', text: hookResult }]),
+    ]);
+
+    expect(projected.entries.map((e) => [e.kind, e.content])).toEqual([
+      ['user', 'show me the hook XML'],
+      ['assistant', hookResult],
+    ]);
+  });
+
+  it('projects user messages plus thinking and assistant content', () => {
+    const projected = projectReplayRecords([
+      message('user', [{ type: 'text', text: 'hello' }]),
+      message('assistant', [
+        { type: 'think', think: 'thinking...' },
+        { type: 'text', text: 'answer' },
+      ]),
+    ]);
+
+    expect(projected.entries.map((e) => [e.kind, e.content])).toEqual([
+      ['user', 'hello'],
+      ['thinking', 'thinking...'],
+      ['assistant', 'answer'],
+    ]);
+  });
+
+  it('projects skill activation origin metadata without exposing the full prompt', () => {
+    const projected = projectReplayRecords([
+      message(
+        'user',
+        [{ type: 'text', text: 'Review the requested file.\n\nUser request:\nsrc/app.ts' }],
+        {
+          origin: {
+            kind: 'skill_activation',
+            activationId: 'act-1',
+            skillName: 'review',
+            skillArgs: 'src/app.ts',
+            trigger: 'user-slash',
+          },
+        },
+      ),
+    ]);
+
+    expect(projected.entries).toHaveLength(1);
+    expect(projected.entries[0]).toEqual(
+      expect.objectContaining({
+        kind: 'skill_activation',
+        content: 'Activated skill: review',
+        skillActivationId: 'act-1',
+        skillName: 'review',
+        skillArgs: 'src/app.ts',
+      }),
+    );
+    expect(JSON.stringify(projected.entries)).not.toContain('Review the requested file');
+  });
+
+  it('deduplicates replayed skill activation cards by activation id', () => {
+    const record = message('user', [{ type: 'text', text: 'Skill body' }], {
+      origin: {
+        kind: 'skill_activation',
+        activationId: 'act-1',
+        skillName: 'review',
+        trigger: 'user-slash',
+      },
+    });
+
+    const projected = projectReplayRecords([record, record]);
+
+    expect(projected.entries).toHaveLength(1);
+    expect(projected.entries[0]).toEqual(
+      expect.objectContaining({
+        kind: 'skill_activation',
+        skillActivationId: 'act-1',
+        skillName: 'review',
+      }),
+    );
+  });
+
+  it('projects background task notifications as status rows', () => {
+    const notificationXml = [
+      '<notification id="task:agent-bg123:completed" category="task" type="task.completed" source_kind="background_task" source_id="agent-bg123">',
+      'Title: Background agent completed',
+      'Severity: info',
+      'Optimize summary completed.',
+      '<task-notification>',
+      'Subagent detailed output should stay out of the transcript row.',
+      '</task-notification>',
+      '</notification>',
+    ].join('\n');
+    const projected = projectReplayRecords([
+      message('assistant', [], {
+        toolCalls: [
+          {
+            type: 'function',
+            id: 'call_agent',
+            function: {
+              name: 'Agent',
+              arguments: JSON.stringify({
+                description: 'Optimize summary',
+                subagent_type: 'coder',
+                run_in_background: true,
+              }),
+            },
+          },
+        ],
+      }),
+      message('tool', [
+        {
+          type: 'text',
+          text: [
+            'task_id: agent-bg123',
+            'status: running',
+            'agent_id: agent-child123',
+            'actual_subagent_type: coder',
+            'automatic_notification: true',
+            '',
+            'description: Optimize summary',
+          ].join('\n'),
+        },
+      ], {
+        toolCallId: 'call_agent',
+      }),
+      message('user', [{ type: 'text', text: notificationXml }], {
+        origin: {
+          kind: 'background_task',
+          taskId: 'agent-bg123',
+          status: 'completed',
+          notificationId: 'task:agent-bg123:completed',
+        },
+      }),
+    ], [backgroundTask('agent-bg123', 'Optimize summary', 'completed')]);
+
+    expect(projected.entries.map((entry) => [entry.kind, entry.content])).toEqual([
+      ['tool_call', ''],
+      ['status', 'agent completed in background'],
+    ]);
+    expect(projected.entries[1]?.backgroundAgentStatus).toMatchObject({
+      phase: 'completed',
+      headline: 'agent completed in background',
+      detail: 'Optimize summary',
+    });
+    expect(JSON.stringify(projected.entries)).not.toContain('<notification');
+    expect(JSON.stringify(projected.entries)).not.toContain('Subagent detailed output');
+  });
+
+  it('uses background notification origin over XML attributes', () => {
+    const projected = projectReplayRecords([
+      message('user', [
+        {
+          type: 'text',
+          text: [
+            '<notification id="task:wrong:completed" category="task" type="task.completed" source_kind="background_task" source_id="wrong">',
+            'Title: Background agent completed',
+            'Severity: info',
+            'Optimize ch03 lost.',
+            '</notification>',
+          ].join('\n'),
+        },
+      ], {
+        origin: {
+          kind: 'background_task',
+          taskId: 'agent-real',
+          status: 'lost',
+          notificationId: 'task:agent-real:lost',
+        },
+      }),
+    ], [backgroundTask('agent-real', 'Real task description', 'lost')]);
+
+    expect(projected.entries).toHaveLength(1);
+    expect(projected.entries[0]).toEqual(
+      expect.objectContaining({
+        kind: 'status',
+        content: 'agent lost in background',
+        backgroundAgentStatus: expect.objectContaining({
+          phase: 'failed',
+          detail: 'Real task description',
+        }),
+      }),
+    );
+  });
+
+  it('renders multimodal user parts as stable placeholders', () => {
+    const projected = projectReplayRecords([
+      message('user', [
+        { type: 'text', text: 'look ' },
+        { type: 'image_url', imageUrl: { url: 'file:///tmp/a.png' } },
+        { type: 'video_url', videoUrl: { url: 'file:///tmp/a.mov' } },
+      ]),
+    ]);
+
+    expect(projected.entries[0]?.content).toBe(
+      'look <image url="file:///tmp/a.png"><video url="file:///tmp/a.mov">',
+    );
+  });
+
+  it('summarizes data URLs in resumed multimodal user parts', () => {
+    const projected = projectReplayRecords([
+      message('user', [
+        { type: 'text', text: 'look ' },
+        { type: 'image_url', imageUrl: { url: 'data:image/png;base64,qrs=' } },
+        { type: 'video_url', videoUrl: { url: 'data:video/mp4;base64,AQIDBA==' } },
+      ]),
+    ]);
+
+    expect(projected.entries[0]?.content).toBe('look [image image/png, 2 B][video video/mp4, 4 B]');
+    expect(projected.entries[0]?.content).not.toContain('qrs=');
+    expect(projected.entries[0]?.content).not.toContain('AQIDBA==');
+  });
+
+  it('pairs tool results with their tool call entry', () => {
+    const projected = projectReplayRecords([
+      message('assistant', [], {
+        toolCalls: [
+          {
+            type: 'function',
+            id: 'tc_1',
+            function: {
+              name: 'Bash',
+              arguments: '{"command":"pwd"}',
+            },
+          },
+        ],
+      }),
+      message('tool', [{ type: 'text', text: 'done' }], {
+        toolCallId: 'tc_1',
+      }),
+    ]);
+
+    expect(projected.entries).toHaveLength(1);
+    expect(projected.entries[0]?.toolCallData).toMatchObject({
+      id: 'tc_1',
+      name: 'Bash',
+      result: { tool_call_id: 'tc_1', output: 'done' },
+    });
+  });
+
+  it('preserves failed tool result state', () => {
+    const projected = projectReplayRecords([
+      message('assistant', [], {
+        toolCalls: [
+          {
+            type: 'function',
+            id: 'tc_1',
+            function: {
+              name: 'Bash',
+              arguments: '{"command":"false"}',
+            },
+          },
+        ],
+      }),
+      message('tool', [{ type: 'text', text: 'failed' }], {
+        toolCallId: 'tc_1',
+        isError: true,
+      }),
+    ]);
+
+    expect(projected.entries[0]?.toolCallData?.result).toMatchObject({
+      tool_call_id: 'tc_1',
+      output: 'failed',
+      is_error: true,
+    });
+  });
+
+  it('projects resumed assistant text, tool call, and tool result records in order', () => {
+    const projected = projectReplayRecords([
+      message('user', [{ type: 'text', text: 'try call a tool' }]),
+      message(
+        'assistant',
+        [
+          { type: 'think', think: 'I should call Bash.' },
+          { type: 'text', text: 'Calling Bash now.' },
+        ],
+        {
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_resume_bash',
+              function: {
+                name: 'Bash',
+                arguments: '{"command":"echo ok"}',
+              },
+            },
+          ],
+        },
+      ),
+      message('tool', [{ type: 'text', text: 'ok' }], {
+        toolCallId: 'call_resume_bash',
+      }),
+    ]);
+
+    expect(projected.entries.map((entry) => [entry.kind, entry.content])).toEqual([
+      ['user', 'try call a tool'],
+      ['thinking', 'I should call Bash.'],
+      ['assistant', 'Calling Bash now.'],
+      ['tool_call', ''],
+    ]);
+    expect(projected.entries[3]?.toolCallData).toMatchObject({
+      id: 'call_resume_bash',
+      name: 'Bash',
+      args: { command: 'echo ok' },
+      result: { tool_call_id: 'call_resume_bash', output: 'ok' },
+    });
+  });
+
+  it('keeps media-bearing tool results as a JSON envelope', () => {
+    const mediaContent: ContentPart[] = [
+      { type: 'text', text: '<image path="/tmp/a.png">' },
+      { type: 'image_url', imageUrl: { url: 'data:image/png;base64,QUJD' } },
+      { type: 'text', text: '</image>' },
+    ];
+    const projected = projectReplayRecords([
+      message('assistant', [], {
+        toolCalls: [
+          {
+            type: 'function',
+            id: 'tc_media',
+            function: {
+              name: 'ReadMediaFile',
+              arguments: '{"path":"/tmp/a.png"}',
+            },
+          },
+        ],
+      }),
+      message('tool', mediaContent, {
+        toolCallId: 'tc_media',
+      }),
+    ]);
+
+    const output = projected.entries[0]?.toolCallData?.result?.output ?? '';
+    expect(JSON.parse(output)).toEqual(mediaContent);
+  });
+
+  it('projects plan, permission, and approval replay records as notices', () => {
+    const projected = projectReplayRecords([
+      { type: 'plan_updated', enabled: true },
+      { type: 'permission_updated', mode: 'auto' },
+      { type: 'permission_updated', mode: 'yolo' },
+      { type: 'permission_updated', mode: 'manual' },
+      {
+        type: 'approval_result',
+        record: {
+          turnId: 0,
+          toolCallId: 'call_bash',
+          action: 'run command',
+          toolName: 'Bash',
+          result: {
+            decision: 'approved',
+            scope: 'session',
+            selectedLabel: 'Approve for this session',
+          },
+        },
+      },
+      { type: 'plan_updated', enabled: false },
+    ]);
+
+    expect(projected.entries.map((e) => [e.kind, e.renderMode, e.content])).toEqual([
+      ['status', 'notice', 'Plan mode: ON'],
+      ['status', 'notice', 'Permission mode: auto'],
+      ['status', 'notice', 'YOLO mode: ON'],
+      ['status', 'notice', 'YOLO mode: OFF'],
+      ['status', 'notice', 'Approved for session: run command'],
+      ['status', 'notice', 'Plan mode: OFF'],
+    ]);
+    expect(projected.entries[2]?.detail).toBe(
+      'All actions will be approved automatically. Use with caution.',
+    );
+  });
+
+  it('ignores config replay records and system injections', () => {
+    const projected = projectReplayRecords([
+      { type: 'config_updated', config: { thinkingLevel: 'off' } },
+      message('user', [{ type: 'text', text: 'ignore by origin' }], {
+        origin: { kind: 'injection', variant: 'plan_mode' },
+      }),
+      message('user', [{ type: 'text', text: 'visible' }]),
+    ]);
+
+    expect(projected.entries.map((e) => [e.kind, e.content])).toEqual([['user', 'visible']]);
+  });
+});
diff --git a/apps/kimi-code/test/tui/reverse-rpc/approval-adapter.test.ts b/apps/kimi-code/test/tui/reverse-rpc/approval-adapter.test.ts
new file mode 100644
index 000000000..72c2b6141
--- /dev/null
+++ b/apps/kimi-code/test/tui/reverse-rpc/approval-adapter.test.ts
@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+
+import { adaptApprovalRequest, adaptPanelResponse } from '#/tui/reverse-rpc/approval/adapter';
+
+describe('approval adapter', () => {
+  it('adapts generic command displays into shell blocks with approval choices', () => {
+    const adapted = adaptApprovalRequest(
+      {
+        toolCallId: 'tc-1',
+        toolName: 'EnterPlanMode',
+        action: 'run',
+        display: {
+          kind: 'generic',
+          summary: 'run',
+          detail: {
+            command: 'sudo rm -rf /tmp/cache',
+            cwd: '/tmp',
+          },
+        },
+      },
+    );
+
+    expect(adapted).toMatchObject({
+      id: 'tc-1',
+      tool_call_id: 'tc-1',
+      tool_name: 'EnterPlanMode',
+      display: [
+        {
+          type: 'shell',
+          language: 'bash',
+          command: 'sudo rm -rf /tmp/cache',
+          cwd: '/tmp',
+          danger: 'recursive delete',
+        },
+      ],
+    });
+    expect(adapted.choices.map((choice) => choice.label)).toEqual([
+      'Approve once',
+      'Approve for this session',
+      'Reject',
+      'Reject with feedback',
+    ]);
+  });
+
+  it('emits only a diff block for Edit — no separate file_op title row', () => {
+    const adapted = adaptApprovalRequest(
+      {
+        toolCallId: 'tc-edit',
+        toolName: 'Edit',
+        action: 'edit',
+        display: {
+          kind: 'generic',
+          summary: 'edit',
+          detail: {
+            file_path: 'src/foo.ts',
+            old_string: 'a\nb\nc',
+            new_string: 'a\nB\nc',
+          },
+        },
+      },
+    );
+
+    expect(adapted.display).toEqual([
+      { type: 'diff', path: 'src/foo.ts', old_text: 'a\nb\nc', new_text: 'a\nB\nc' },
+    ]);
+  });
+
+  it('emits a file_content block for Write so the new file previews as code, not diff', () => {
+    const adapted = adaptApprovalRequest(
+      {
+        toolCallId: 'tc-write',
+        toolName: 'Write',
+        action: 'write',
+        display: {
+          kind: 'generic',
+          summary: 'write',
+          detail: {
+            file_path: 'src/new.ts',
+            content: 'export const x = 1;\nexport const y = 2;',
+          },
+        },
+      },
+    );
+
+    expect(adapted.display).toEqual([
+      {
+        type: 'file_content',
+        path: 'src/new.ts',
+        content: 'export const x = 1;\nexport const y = 2;',
+      },
+    ]);
+  });
+
+  it('omits plan review content from the approval panel while keeping Python-style choices', () => {
+    const adapted = adaptApprovalRequest({
+      toolCallId: 'tc-plan',
+      toolName: 'ExitPlanMode',
+      action: 'Review plan',
+      display: {
+        kind: 'plan_review',
+        plan: '# Plan\n\n- Inspect\n- Change\n- Verify',
+        path: '/tmp/kimi-plan.md',
+      },
+    });
+
+    expect(adapted.display).toEqual([]);
+    expect(adapted.choices).toEqual([
+      { label: 'Approve', response: 'approved', selected_label: 'Approve' },
+      { label: 'Reject', response: 'rejected', selected_label: 'Reject' },
+      {
+        label: 'Revise',
+        response: 'rejected',
+        selected_label: 'Revise',
+        requires_feedback: true,
+      },
+    ]);
+  });
+
+  it('renders multi-option plan review choices ahead of reject controls', () => {
+    const adapted = adaptApprovalRequest({
+      toolCallId: 'tc-plan-options',
+      toolName: 'ExitPlanMode',
+      action: 'Review plan and choose an option',
+      display: {
+        kind: 'plan_review',
+        plan: '# Plan',
+        path: '/tmp/kimi-plan.md',
+        options: [
+          { label: 'Approach A', description: 'Small refactor' },
+          { label: 'Approach B', description: 'Full refactor' },
+        ],
+      },
+    });
+
+    expect(adapted.choices).toEqual([
+      { label: 'Approach A', response: 'approved', selected_label: 'Approach A' },
+      { label: 'Approach B', response: 'approved', selected_label: 'Approach B' },
+      { label: 'Reject', response: 'rejected', selected_label: 'Reject' },
+      {
+        label: 'Revise',
+        response: 'rejected',
+        selected_label: 'Revise',
+        requires_feedback: true,
+      },
+    ]);
+  });
+
+  it('maps approved-for-session responses into core approval payloads', () => {
+    expect(
+      adaptPanelResponse({
+        response: 'approved_for_session',
+        feedback: 'looks good',
+        selected_label: 'Approve for this session',
+      }),
+    ).toEqual({
+      decision: 'approved',
+      scope: 'session',
+      feedback: 'looks good',
+      selectedLabel: 'Approve for this session',
+    });
+  });
+});
diff --git a/apps/kimi-code/test/tui/reverse-rpc/approval.test.ts b/apps/kimi-code/test/tui/reverse-rpc/approval.test.ts
new file mode 100644
index 000000000..c2e29c6c2
--- /dev/null
+++ b/apps/kimi-code/test/tui/reverse-rpc/approval.test.ts
@@ -0,0 +1,142 @@
+import type { ApprovalRequest } from '@moonshot-ai/kimi-code-sdk';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ApprovalController } from '#/tui/reverse-rpc/approval/controller';
+import { createApprovalRequestHandler } from '#/tui/reverse-rpc/approval/handler';
+
+function approvalEvent(overrides: Partial<ApprovalRequest> = {}): ApprovalRequest {
+  return {
+    toolCallId: 'tc-1',
+    toolName: 'Bash',
+    action: 'run command',
+    display: {
+      kind: 'generic',
+      summary: 'run command',
+      detail: {
+        command: 'rm -rf /tmp/cache',
+        cwd: '/tmp',
+      },
+    },
+    ...overrides,
+  };
+}
+
+describe('approval reverse-rpc', () => {
+  it('auto-approves queued requests with the same action when the current is approved for session', async () => {
+    const controller = new ApprovalController();
+    const panel = (id: string, action: string) => ({
+      id,
+      tool_call_id: id,
+      tool_name: 'Bash',
+      action,
+      description: '',
+      display: [],
+      choices: [],
+    });
+
+    const first = controller.show(panel('tc-1', 'run command: ls'));
+    const second = controller.show(panel('tc-2', 'run command: ls'));
+    const third = controller.show(panel('tc-3', 'edit src/x.ts'));
+    const fourth = controller.show(panel('tc-4', 'run command: ls'));
+
+    controller.respond({ decision: 'approved', scope: 'session', feedback: 'ok' });
+
+    await expect(first).resolves.toEqual({
+      decision: 'approved',
+      scope: 'session',
+      feedback: 'ok',
+    });
+    // Queued same-action requests inherit a session-scoped approval without
+    // surfacing another panel. The user's feedback is not carried over —
+    // it described the first request only.
+    await expect(second).resolves.toEqual({ decision: 'approved', scope: 'session' });
+    await expect(fourth).resolves.toEqual({ decision: 'approved', scope: 'session' });
+    // A different-action request still waits for an explicit decision.
+    expect(controller.hasPending()).toBe(true);
+
+    controller.respond({ decision: 'rejected' });
+    await expect(third).resolves.toEqual({ decision: 'rejected' });
+  });
+
+  it('does not auto-approve queued requests when only approved-once is chosen', async () => {
+    const controller = new ApprovalController();
+    const panel = (id: string) => ({
+      id,
+      tool_call_id: id,
+      tool_name: 'Bash',
+      action: 'run command: ls',
+      description: '',
+      display: [],
+      choices: [],
+    });
+
+    const first = controller.show(panel('tc-1'));
+    const second = controller.show(panel('tc-2'));
+
+    controller.respond({ decision: 'approved' });
+
+    await expect(first).resolves.toEqual({ decision: 'approved' });
+    // The second same-action request must NOT be auto-resolved — approve-once
+    // is a one-shot decision, not a session rule.
+    expect(controller.hasPending()).toBe(true);
+    controller.respond({ decision: 'approved' });
+    await expect(second).resolves.toEqual({ decision: 'approved' });
+  });
+
+  it('ApprovalController cancels pending requests with a cancelled response', async () => {
+    const controller = new ApprovalController();
+    const pending = controller.show({
+      id: 'req-1',
+      tool_call_id: 'tc-1',
+      tool_name: 'Bash',
+      action: 'run',
+      description: '',
+      display: [],
+      choices: [],
+    });
+
+    controller.cancelAll('closed');
+
+    await expect(pending).resolves.toEqual({
+      decision: 'cancelled',
+      feedback: 'closed',
+    });
+  });
+
+  it('adapts approval payloads through the handler and falls back on failure', async () => {
+    const controller = new ApprovalController();
+    const show = vi.spyOn(controller, 'show').mockResolvedValue({
+      decision: 'approved',
+      scope: 'session',
+      feedback: 'looks good',
+    });
+    const handler = createApprovalRequestHandler(controller);
+
+    await expect(handler(approvalEvent())).resolves.toEqual({
+      decision: 'approved',
+      scope: 'session',
+      feedback: 'looks good',
+    });
+    expect(show).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: 'tc-1',
+        tool_call_id: 'tc-1',
+        tool_name: 'Bash',
+        display: [
+          expect.objectContaining({
+            type: 'shell',
+            command: 'rm -rf /tmp/cache',
+            cwd: '/tmp',
+            danger: 'recursive delete',
+          }),
+        ],
+      }),
+    );
+
+    show.mockRejectedValueOnce(new Error('boom'));
+    await expect(handler(approvalEvent())).resolves.toEqual({
+      decision: 'cancelled',
+      feedback: 'approval handler failed',
+    });
+  });
+});
diff --git a/apps/kimi-code/test/tui/reverse-rpc/base-controller.test.ts b/apps/kimi-code/test/tui/reverse-rpc/base-controller.test.ts
new file mode 100644
index 000000000..c755c4dd9
--- /dev/null
+++ b/apps/kimi-code/test/tui/reverse-rpc/base-controller.test.ts
@@ -0,0 +1,124 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { ReverseRpcController } from '#/tui/reverse-rpc/base-controller';
+
+class TestController extends ReverseRpcController<string, string> {
+  protected createCancelResponse(reason: string): string {
+    return `cancel:${reason}`;
+  }
+}
+
+describe('ReverseRpcController', () => {
+  it('shows a payload, resolves the pending promise on respond, and hides the panel', async () => {
+    const controller = new TestController();
+    const showPanel = vi.fn();
+    const hidePanel = vi.fn();
+    controller.setUIHooks({ showPanel, hidePanel });
+
+    const pending = controller.show('payload');
+    expect(controller.hasPending()).toBe(true);
+    expect(showPanel).toHaveBeenCalledWith('payload');
+
+    controller.respond('approved');
+
+    await expect(pending).resolves.toBe('approved');
+    expect(controller.hasPending()).toBe(false);
+    expect(hidePanel).toHaveBeenCalledOnce();
+  });
+
+  it('queues concurrent show() requests and presents them one at a time', async () => {
+    const controller = new TestController();
+    const showPanel = vi.fn();
+    const hidePanel = vi.fn();
+    controller.setUIHooks({ showPanel, hidePanel });
+
+    const first = controller.show('first');
+    const second = controller.show('second');
+    const third = controller.show('third');
+
+    // Only the first is presented; the rest stay queued.
+    expect(showPanel).toHaveBeenCalledTimes(1);
+    expect(showPanel).toHaveBeenLastCalledWith('first');
+    expect(controller.hasPending()).toBe(true);
+
+    controller.respond('answer-first');
+    await expect(first).resolves.toBe('answer-first');
+    // Advancing to the next queued request reuses the same panel without
+    // hiding it in between.
+    expect(hidePanel).not.toHaveBeenCalled();
+    expect(showPanel).toHaveBeenCalledTimes(2);
+    expect(showPanel).toHaveBeenLastCalledWith('second');
+
+    controller.respond('answer-second');
+    await expect(second).resolves.toBe('answer-second');
+    expect(showPanel).toHaveBeenCalledTimes(3);
+    expect(showPanel).toHaveBeenLastCalledWith('third');
+
+    controller.respond('answer-third');
+    await expect(third).resolves.toBe('answer-third');
+    expect(controller.hasPending()).toBe(false);
+    expect(hidePanel).toHaveBeenCalledTimes(1);
+  });
+
+  it('auto-resolves matching queued requests via the autoResolveFor hook', async () => {
+    class AutoController extends ReverseRpcController<
+      { action: string; id: string },
+      string
+    > {
+      protected createCancelResponse(reason: string): string {
+        return `cancel:${reason}`;
+      }
+      protected override autoResolveFor(
+        resolved: { action: string; id: string },
+        response: string,
+        queued: { action: string; id: string },
+      ): string | undefined {
+        if (response === 'approve_all_same' && resolved.action === queued.action) {
+          return `auto:${queued.id}`;
+        }
+        return undefined;
+      }
+    }
+    const controller = new AutoController();
+    const showPanel = vi.fn();
+    const hidePanel = vi.fn();
+    controller.setUIHooks({ showPanel, hidePanel });
+
+    const first = controller.show({ action: 'run', id: 'a' });
+    const second = controller.show({ action: 'run', id: 'b' });
+    const third = controller.show({ action: 'edit', id: 'c' });
+    const fourth = controller.show({ action: 'run', id: 'd' });
+
+    controller.respond('approve_all_same');
+
+    await expect(first).resolves.toBe('approve_all_same');
+    await expect(second).resolves.toBe('auto:b');
+    await expect(fourth).resolves.toBe('auto:d');
+    // The non-matching request advances to the panel and stays pending.
+    expect(showPanel).toHaveBeenLastCalledWith({ action: 'edit', id: 'c' });
+    expect(controller.hasPending()).toBe(true);
+
+    controller.respond('approve_all_same');
+    await expect(third).resolves.toBe('approve_all_same');
+    expect(controller.hasPending()).toBe(false);
+    expect(hidePanel).toHaveBeenCalledTimes(1);
+  });
+
+  it('cancelAll cancels the current request and every queued request', async () => {
+    const controller = new TestController();
+    const hidePanel = vi.fn();
+    controller.setUIHooks({ showPanel: vi.fn(), hidePanel });
+
+    const first = controller.show('first');
+    const second = controller.show('second');
+    const third = controller.show('third');
+
+    controller.cancelAll('shutdown');
+
+    await expect(first).resolves.toBe('cancel:shutdown');
+    await expect(second).resolves.toBe('cancel:shutdown');
+    await expect(third).resolves.toBe('cancel:shutdown');
+    expect(controller.hasPending()).toBe(false);
+    expect(hidePanel).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/apps/kimi-code/test/tui/reverse-rpc/index.test.ts b/apps/kimi-code/test/tui/reverse-rpc/index.test.ts
new file mode 100644
index 000000000..790fd00dc
--- /dev/null
+++ b/apps/kimi-code/test/tui/reverse-rpc/index.test.ts
@@ -0,0 +1,214 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { ApprovalController } from '#/tui/reverse-rpc/approval/controller';
+import { registerReverseRPCHandlers } from '#/tui/reverse-rpc/index';
+import { QuestionController } from '#/tui/reverse-rpc/question/controller';
+
+describe('registerReverseRPCHandlers', () => {
+  it('wires controller UI hooks without registering wire request handlers', async () => {
+    const approvalController = new ApprovalController();
+    const questionController = new QuestionController();
+    const uiHooks = {
+      showApprovalPanel: vi.fn(),
+      hideApprovalPanel: vi.fn(),
+      showQuestionDialog: vi.fn(),
+      hideQuestionDialog: vi.fn(),
+    };
+
+    registerReverseRPCHandlers(approvalController, questionController, uiHooks);
+
+    const approvalPending = approvalController.show({
+      id: 'req-1',
+      tool_call_id: 'tc-1',
+      tool_name: 'Bash',
+      action: 'run',
+      description: '',
+      display: [],
+      choices: [],
+    });
+    expect(uiHooks.showApprovalPanel).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'req-1' }),
+    );
+    approvalController.cancelAll('bye');
+    await expect(approvalPending).resolves.toEqual({
+      decision: 'cancelled',
+      feedback: 'bye',
+    });
+    expect(uiHooks.hideApprovalPanel).toHaveBeenCalledOnce();
+
+    const questionPending = questionController.show({
+      id: 'q-1',
+      tool_call_id: 'tc-1',
+      questions: [],
+    });
+    expect(uiHooks.showQuestionDialog).toHaveBeenCalledWith(expect.objectContaining({ id: 'q-1' }));
+    questionController.cancelAll('bye');
+    await expect(questionPending).resolves.toEqual({ answers: [] });
+    expect(uiHooks.hideQuestionDialog).toHaveBeenCalledOnce();
+  });
+
+  it('queues question dialogs behind active approval panels', async () => {
+    const approvalController = new ApprovalController();
+    const questionController = new QuestionController();
+    const uiHooks = {
+      showApprovalPanel: vi.fn(),
+      hideApprovalPanel: vi.fn(),
+      showQuestionDialog: vi.fn(),
+      hideQuestionDialog: vi.fn(),
+    };
+
+    registerReverseRPCHandlers(approvalController, questionController, uiHooks);
+
+    const approvalPending = approvalController.show({
+      id: 'approval-1',
+      tool_call_id: 'tc-1',
+      tool_name: 'Bash',
+      action: 'run',
+      description: '',
+      display: [],
+      choices: [],
+    });
+    const questionPending = questionController.show({
+      id: 'question-1',
+      tool_call_id: 'tq-1',
+      questions: [],
+    });
+
+    expect(uiHooks.showApprovalPanel).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'approval-1' }),
+    );
+    expect(uiHooks.showQuestionDialog).not.toHaveBeenCalled();
+
+    approvalController.respond({ decision: 'approved' });
+    await expect(approvalPending).resolves.toEqual({ decision: 'approved' });
+    expect(uiHooks.hideApprovalPanel).toHaveBeenCalledOnce();
+    expect(uiHooks.showQuestionDialog).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'question-1' }),
+    );
+
+    questionController.respond({ answers: ['answer'] });
+    await expect(questionPending).resolves.toEqual({ answers: ['answer'] });
+    expect(uiHooks.hideQuestionDialog).toHaveBeenCalledOnce();
+  });
+
+  it('queues approval panels behind active question dialogs', async () => {
+    const approvalController = new ApprovalController();
+    const questionController = new QuestionController();
+    const uiHooks = {
+      showApprovalPanel: vi.fn(),
+      hideApprovalPanel: vi.fn(),
+      showQuestionDialog: vi.fn(),
+      hideQuestionDialog: vi.fn(),
+    };
+
+    registerReverseRPCHandlers(approvalController, questionController, uiHooks);
+
+    const questionPending = questionController.show({
+      id: 'question-1',
+      tool_call_id: 'tq-1',
+      questions: [],
+    });
+    const approvalPending = approvalController.show({
+      id: 'approval-1',
+      tool_call_id: 'tc-1',
+      tool_name: 'Bash',
+      action: 'run',
+      description: '',
+      display: [],
+      choices: [],
+    });
+
+    expect(uiHooks.showQuestionDialog).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'question-1' }),
+    );
+    expect(uiHooks.showApprovalPanel).not.toHaveBeenCalled();
+
+    questionController.respond({ answers: ['answer'] });
+    await expect(questionPending).resolves.toEqual({ answers: ['answer'] });
+    expect(uiHooks.hideQuestionDialog).toHaveBeenCalledOnce();
+    expect(uiHooks.showApprovalPanel).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'approval-1' }),
+    );
+
+    approvalController.respond({ decision: 'approved' });
+    await expect(approvalPending).resolves.toEqual({ decision: 'approved' });
+    expect(uiHooks.hideApprovalPanel).toHaveBeenCalledOnce();
+  });
+
+  it('removes queued modals when their controller is cancelled', async () => {
+    const approvalController = new ApprovalController();
+    const questionController = new QuestionController();
+    const uiHooks = {
+      showApprovalPanel: vi.fn(),
+      hideApprovalPanel: vi.fn(),
+      showQuestionDialog: vi.fn(),
+      hideQuestionDialog: vi.fn(),
+    };
+
+    registerReverseRPCHandlers(approvalController, questionController, uiHooks);
+
+    const approvalPending = approvalController.show({
+      id: 'approval-1',
+      tool_call_id: 'tc-1',
+      tool_name: 'Bash',
+      action: 'run',
+      description: '',
+      display: [],
+      choices: [],
+    });
+    const questionPending = questionController.show({
+      id: 'question-1',
+      tool_call_id: 'tq-1',
+      questions: [],
+    });
+
+    questionController.cancelAll('closed');
+    await expect(questionPending).resolves.toEqual({ answers: [] });
+    expect(uiHooks.hideQuestionDialog).not.toHaveBeenCalled();
+
+    approvalController.respond({ decision: 'approved' });
+    await expect(approvalPending).resolves.toEqual({ decision: 'approved' });
+    expect(uiHooks.showQuestionDialog).not.toHaveBeenCalled();
+  });
+
+  it('clears active and queued modals without showing queued entries', async () => {
+    const approvalController = new ApprovalController();
+    const questionController = new QuestionController();
+    const uiHooks = {
+      showApprovalPanel: vi.fn(),
+      hideApprovalPanel: vi.fn(),
+      showQuestionDialog: vi.fn(),
+      hideQuestionDialog: vi.fn(),
+    };
+
+    const disposers = registerReverseRPCHandlers(approvalController, questionController, uiHooks);
+
+    const approvalPending = approvalController.show({
+      id: 'approval-1',
+      tool_call_id: 'tc-1',
+      tool_name: 'Bash',
+      action: 'run',
+      description: '',
+      display: [],
+      choices: [],
+    });
+    const questionPending = questionController.show({
+      id: 'question-1',
+      tool_call_id: 'tq-1',
+      questions: [],
+    });
+
+    for (const dispose of disposers) dispose();
+    expect(uiHooks.hideApprovalPanel).toHaveBeenCalledOnce();
+    expect(uiHooks.showQuestionDialog).not.toHaveBeenCalled();
+
+    approvalController.cancelAll('closed');
+    questionController.cancelAll('closed');
+    await expect(approvalPending).resolves.toEqual({
+      decision: 'cancelled',
+      feedback: 'closed',
+    });
+    await expect(questionPending).resolves.toEqual({ answers: [] });
+    expect(uiHooks.hideQuestionDialog).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/kimi-code/test/tui/reverse-rpc/question.test.ts b/apps/kimi-code/test/tui/reverse-rpc/question.test.ts
new file mode 100644
index 000000000..41de65fff
--- /dev/null
+++ b/apps/kimi-code/test/tui/reverse-rpc/question.test.ts
@@ -0,0 +1,134 @@
+import type { QuestionRequest } from '@moonshot-ai/kimi-code-sdk';
+import { describe, expect, it, vi } from 'vitest';
+
+import { QuestionController } from '#/tui/reverse-rpc/question/controller';
+import { createQuestionAskHandler } from '#/tui/reverse-rpc/question/handler';
+
+function questionEvent(overrides: Partial<QuestionRequest> = {}): QuestionRequest {
+  return {
+    toolCallId: 'q-1',
+    questions: [
+      {
+        question: 'Q1?',
+        options: [{ label: 'Alpha' }],
+      },
+    ],
+    ...overrides,
+  };
+}
+
+describe('question reverse-rpc', () => {
+  it('QuestionController cancels pending requests with an empty answer list', async () => {
+    const controller = new QuestionController();
+    const pending = controller.show({
+      id: 'req-1',
+      tool_call_id: 'tc-1',
+      questions: [],
+    });
+
+    controller.cancelAll('closed');
+
+    await expect(pending).resolves.toEqual({ answers: [] });
+  });
+
+  it('normalizes question payloads and returns the selected answer', async () => {
+    const controller = new QuestionController();
+    const show = vi
+      .spyOn(controller, 'show')
+      .mockResolvedValue({ answers: ['Alpha'], method: 'number_key' });
+    const handler = createQuestionAskHandler(controller);
+    const event = questionEvent({
+      questions: [
+        {
+          question: 'Q1?',
+          header: 'Pick',
+          body: 'Choose one',
+          multiSelect: true,
+          otherLabel: 'Other',
+          otherDescription: 'Type a custom answer',
+          options: [{ label: 'Alpha', description: 'First option' }],
+        },
+      ],
+    });
+
+    await expect(handler(event)).resolves.toEqual({
+      answers: { 'Q1?': 'Alpha' },
+      method: 'number_key',
+    });
+    expect(show).toHaveBeenCalledWith({
+      id: 'q-1',
+      tool_call_id: 'q-1',
+      questions: [
+        {
+          question: 'Q1?',
+          header: 'Pick',
+          body: 'Choose one',
+          multi_select: true,
+          other_label: 'Other',
+          other_description: 'Type a custom answer',
+          options: [{ label: 'Alpha', description: 'First option' }],
+        },
+      ],
+    });
+
+    show.mockResolvedValueOnce({ answers: [''] });
+    await expect(handler(questionEvent())).resolves.toBeNull();
+
+    show.mockRejectedValueOnce(new Error('boom'));
+    await expect(handler(questionEvent())).resolves.toBeNull();
+  });
+
+  it('maps multiple question answers by question text', async () => {
+    const controller = new QuestionController();
+    const show = vi
+      .spyOn(controller, 'show')
+      .mockResolvedValue({ answers: ['Alpha', 'SQLite'], method: 'enter' });
+    const handler = createQuestionAskHandler(controller);
+    const event = questionEvent({
+      toolCallId: 'call_question',
+      questions: [
+        {
+          question: 'Q1?',
+          options: [{ label: 'Alpha' }],
+        },
+        {
+          question: 'Storage?',
+          header: 'Store',
+          options: [{ label: 'SQLite' }],
+        },
+      ],
+    });
+
+    await expect(handler(event)).resolves.toEqual({
+      answers: {
+        'Q1?': 'Alpha',
+        'Storage?': 'SQLite',
+      },
+      method: 'enter',
+    });
+    expect(show).toHaveBeenCalledWith({
+      id: 'call_question',
+      tool_call_id: 'call_question',
+      questions: [
+        {
+          question: 'Q1?',
+          header: undefined,
+          body: undefined,
+          multi_select: false,
+          other_label: undefined,
+          other_description: undefined,
+          options: [{ label: 'Alpha', description: undefined }],
+        },
+        {
+          question: 'Storage?',
+          header: 'Store',
+          body: undefined,
+          multi_select: false,
+          other_label: undefined,
+          other_description: undefined,
+          options: [{ label: 'SQLite', description: undefined }],
+        },
+      ],
+    });
+  });
+});
diff --git a/apps/kimi-code/test/tui/task-output-viewer.test.ts b/apps/kimi-code/test/tui/task-output-viewer.test.ts
new file mode 100644
index 000000000..2cb998b42
--- /dev/null
+++ b/apps/kimi-code/test/tui/task-output-viewer.test.ts
@@ -0,0 +1,260 @@
+import type { Terminal } from '@earendil-works/pi-tui';
+import type { BackgroundTaskInfo } from '@moonshot-ai/kimi-code-sdk';
+import { describe, expect, it, vi } from 'vitest';
+
+import { TaskOutputViewer } from '@/tui/components/dialogs/task-output-viewer';
+import { darkColors } from '@/tui/theme/colors';
+
+const ANSI_SGR = /\[[0-9;]*m/g;
+function strip(text: string): string {
+  return text.replaceAll(ANSI_SGR, '');
+}
+
+function fakeTerminal(rows: number, columns = 120): Terminal {
+  return {
+    start: () => {},
+    stop: () => {},
+    drainInput: () => Promise.resolve(),
+    write: () => {},
+    get columns() {
+      return columns;
+    },
+    get rows() {
+      return rows;
+    },
+    get kittyProtocolActive() {
+      return false;
+    },
+    moveBy: () => {},
+    hideCursor: () => {},
+    showCursor: () => {},
+    clearLine: () => {},
+    clearFromCursor: () => {},
+    clearScreen: () => {},
+    setTitle: () => {},
+    setProgress: () => {},
+  };
+}
+
+function info(overrides: Partial<BackgroundTaskInfo> = {}): BackgroundTaskInfo {
+  return {
+    taskId: 'bash-aaaaaaaa',
+    command: 'npm run dev',
+    description: 'dev server',
+    status: 'running',
+    pid: 1234,
+    exitCode: null,
+    startedAt: Date.now() - 60_000,
+    endedAt: null,
+    ...overrides,
+  };
+}
+
+function makeViewer(opts: {
+  output: string;
+  taskInfo?: BackgroundTaskInfo;
+  rows?: number;
+  columns?: number;
+  onClose?: () => void;
+}): TaskOutputViewer {
+  return new TaskOutputViewer(
+    {
+      taskId: opts.taskInfo?.taskId ?? 'bash-aaaaaaaa',
+      info: opts.taskInfo ?? info(),
+      output: opts.output,
+      colors: darkColors,
+      onClose: opts.onClose ?? (() => {}),
+    },
+    fakeTerminal(opts.rows ?? 30, opts.columns ?? 120),
+  );
+}
+
+describe('TaskOutputViewer — rendering', () => {
+  it('fills exactly terminal.rows lines', () => {
+    const lines = makeViewer({ output: 'hello\nworld', rows: 24 }).render(120);
+    expect(lines.length).toBe(24);
+  });
+
+  it('shows the task header (id + status + description)', () => {
+    const out = strip(
+      makeViewer({
+        output: '',
+        taskInfo: info({ taskId: 'bash-zzzzzzzz', status: 'running', description: 'demo svc' }),
+      })
+        .render(120)
+        .join('\n'),
+    );
+    expect(out).toContain('Task output');
+    expect(out).toContain('bash-zzzzzzzz');
+    expect(out).toContain('running');
+    expect(out).toContain('demo svc');
+  });
+
+  it('shows the empty-state body when output is empty', () => {
+    const out = strip(makeViewer({ output: '' }).render(120).join('\n'));
+    expect(out).toContain('[no output captured]');
+  });
+
+  it('shows position indicator in the footer', () => {
+    const lines = ['line 1', 'line 2', 'line 3'].join('\n');
+    const out = strip(makeViewer({ output: lines, rows: 20 }).render(120).join('\n'));
+    expect(out).toMatch(/1-3 \/ 3/);
+    expect(out).toContain('100%');
+  });
+
+  it('renders all visible body lines when output fits the body height', () => {
+    const lines = ['alpha', 'bravo', 'charlie', 'delta', 'echo'].join('\n');
+    const out = strip(makeViewer({ output: lines, rows: 20 }).render(120).join('\n'));
+    expect(out).toContain('alpha');
+    expect(out).toContain('bravo');
+    expect(out).toContain('charlie');
+    expect(out).toContain('delta');
+    expect(out).toContain('echo');
+  });
+});
+
+describe('TaskOutputViewer — scrolling', () => {
+  function bigOutput(n: number): string {
+    return Array.from({ length: n }, (_, i) => `line-${String(i + 1).padStart(3, '0')}`).join('\n');
+  }
+
+  it('renders the top of the buffer initially', () => {
+    const viewer = makeViewer({ output: bigOutput(100), rows: 20 });
+    const out = strip(viewer.render(120).join('\n'));
+    expect(out).toContain('line-001');
+    expect(out).not.toContain('line-100');
+  });
+
+  it('down arrow scrolls forward by one line', () => {
+    const viewer = makeViewer({ output: bigOutput(50), rows: 12 });
+    viewer.handleInput('');
+    const out = strip(viewer.render(120).join('\n'));
+    expect(out).toContain('line-002');
+    expect(out).not.toContain('line-001');
+  });
+
+  it('PageDown scrolls a page', () => {
+    const viewer = makeViewer({ output: bigOutput(50), rows: 12 });
+    // PageDown via prompt-toolkit-style sequence "[6~"
+    viewer.handleInput('[6~');
+    const out = strip(viewer.render(120).join('\n'));
+    // body has 12 - 2 (header/footer) - 2 (top/bot border) = 8 viewable rows.
+    // PageDown shifts by (body - 1) = 7 lines.
+    expect(out).toContain('line-008');
+    expect(out).not.toContain('line-001');
+  });
+
+  it('G jumps to the bottom', () => {
+    const viewer = makeViewer({ output: bigOutput(100), rows: 14 });
+    viewer.handleInput('G');
+    const out = strip(viewer.render(120).join('\n'));
+    expect(out).toContain('line-100');
+    // Footer reads 100% at the end.
+    expect(out).toContain('100%');
+  });
+
+  it('g jumps back to the top', () => {
+    const viewer = makeViewer({ output: bigOutput(100), rows: 14 });
+    viewer.handleInput('G');
+    viewer.handleInput('g');
+    const out = strip(viewer.render(120).join('\n'));
+    expect(out).toContain('line-001');
+  });
+
+  it('scrolling clamps at the start and end', () => {
+    const viewer = makeViewer({ output: bigOutput(5), rows: 20 });
+    // Scrolling down on a buffer smaller than the body should not advance.
+    viewer.handleInput('');
+    viewer.handleInput('');
+    const out = strip(viewer.render(120).join('\n'));
+    expect(out).toContain('line-001');
+    expect(out).toContain('line-005');
+  });
+});
+
+describe('TaskOutputViewer — input', () => {
+  it('Esc invokes onClose', () => {
+    const onClose = vi.fn();
+    makeViewer({ output: 'x', onClose }).handleInput('');
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('q invokes onClose', () => {
+    const onClose = vi.fn();
+    makeViewer({ output: 'x', onClose }).handleInput('q');
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  // Under the Kitty keyboard protocol (e.g. VSCode integrated terminal),
+  // ordinary printable keys arrive as CSI-u sequences.
+  it('Kitty-encoded q invokes onClose', () => {
+    const onClose = vi.fn();
+    makeViewer({ output: 'x', onClose }).handleInput('\u001B[113u');
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('Kitty-encoded G scrolls to bottom', () => {
+    const viewer = makeViewer({
+      output: Array.from({ length: 200 }, (_, i) => `line-${String(i)}`).join('\n'),
+      rows: 10,
+    });
+    viewer.handleInput('\u001B[71u'); // G (uppercase)
+    const rendered = strip(viewer.render(120).join('\n'));
+    expect(rendered).toContain('line-199');
+  });
+});
+
+describe('TaskOutputViewer — live tail via setProps', () => {
+  function makeOutput(n: number): string {
+    return Array.from({ length: n }, (_, i) => `line-${String(i + 1).padStart(3, '0')}`).join('\n');
+  }
+
+  it('follows new lines when the viewer is already parked at the bottom', () => {
+    // 5 lines, body has ~26 viewable rows → user is at bottom by default.
+    const viewer = makeViewer({ output: makeOutput(5), rows: 30 });
+    viewer.handleInput('G');
+    // Append more lines.
+    viewer.setProps({
+      taskId: 'bash-aaaaaaaa',
+      info: info(),
+      output: makeOutput(50),
+      colors: darkColors,
+      onClose: () => {},
+    });
+    const out = strip(viewer.render(120).join('\n'));
+    expect(out).toContain('line-050');
+  });
+
+  it('preserves scroll position when the user has scrolled up', () => {
+    const viewer = makeViewer({ output: makeOutput(100), rows: 14 });
+    // Body has 14 - 4 = 10 viewable rows; max scroll = 90. Stay at top (0).
+    expect(strip(viewer.render(120).join('\n'))).toContain('line-001');
+    // Output grows. Since user is at scroll=0 (not bottom), keep them at top.
+    viewer.setProps({
+      taskId: 'bash-aaaaaaaa',
+      info: info(),
+      output: makeOutput(200),
+      colors: darkColors,
+      onClose: () => {},
+    });
+    const out = strip(viewer.render(120).join('\n'));
+    expect(out).toContain('line-001');
+    expect(out).not.toContain('line-200');
+  });
+
+  it('skips re-split when output is unchanged', () => {
+    const same = makeOutput(20);
+    const viewer = makeViewer({ output: same, rows: 30 });
+    viewer.handleInput('G');
+    const before = strip(viewer.render(120).join('\n'));
+    viewer.setProps({
+      taskId: 'bash-aaaaaaaa',
+      info: info(),
+      output: same,
+      colors: darkColors,
+      onClose: () => {},
+    });
+    const after = strip(viewer.render(120).join('\n'));
+    expect(after).toBe(before);
+  });
+});
diff --git a/apps/kimi-code/test/tui/tasks-browser.test.ts b/apps/kimi-code/test/tui/tasks-browser.test.ts
new file mode 100644
index 000000000..fd973c8fa
--- /dev/null
+++ b/apps/kimi-code/test/tui/tasks-browser.test.ts
@@ -0,0 +1,434 @@
+import type { Terminal } from '@earendil-works/pi-tui';
+import type { BackgroundTaskInfo, BackgroundTaskStatus } from '@moonshot-ai/kimi-code-sdk';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  TasksBrowserApp,
+  type TasksBrowserProps,
+  type TasksFilter,
+} from '@/tui/components/dialogs/tasks-browser';
+import { darkColors } from '@/tui/theme/colors';
+
+const ANSI_SGR = /\[[0-9;]*m/g;
+function strip(text: string): string {
+  return text.replaceAll(ANSI_SGR, '');
+}
+
+/** Minimal Terminal stub — only `rows` is read by the component. */
+function fakeTerminal(rows: number, columns = 120): Terminal {
+  return {
+    start: () => {},
+    stop: () => {},
+    drainInput: () => Promise.resolve(),
+    write: () => {},
+    get columns() {
+      return columns;
+    },
+    get rows() {
+      return rows;
+    },
+    get kittyProtocolActive() {
+      return false;
+    },
+    moveBy: () => {},
+    hideCursor: () => {},
+    showCursor: () => {},
+    clearLine: () => {},
+    clearFromCursor: () => {},
+    clearScreen: () => {},
+    setTitle: () => {},
+    setProgress: () => {},
+  };
+}
+
+function task(overrides: Partial<BackgroundTaskInfo> = {}): BackgroundTaskInfo {
+  return {
+    taskId: 'bash-abcd1234',
+    command: 'npm run dev',
+    description: 'dev server',
+    status: 'running',
+    pid: 1234,
+    exitCode: null,
+    startedAt: Date.now() - 60_000,
+    endedAt: null,
+    ...overrides,
+  };
+}
+
+function makeProps(overrides: Partial<TasksBrowserProps> = {}): TasksBrowserProps {
+  return {
+    tasks: [],
+    filter: 'all',
+    selectedTaskId: undefined,
+    tailOutput: undefined,
+    tailLoading: false,
+    flashMessage: undefined,
+    colors: darkColors,
+    onSelect: vi.fn(),
+    onToggleFilter: vi.fn(),
+    onRefresh: vi.fn(),
+    onCancel: vi.fn(),
+    onStopConfirmed: vi.fn(),
+    onOpenOutput: vi.fn(),
+    onStopIgnored: vi.fn(),
+    ...overrides,
+  } as TasksBrowserProps;
+}
+
+function makeApp(
+  props: Partial<TasksBrowserProps> = {},
+  rows = 30,
+  columns = 120,
+): TasksBrowserApp {
+  return new TasksBrowserApp(makeProps(props), fakeTerminal(rows, columns));
+}
+
+describe('TasksBrowserApp — full-screen rendering', () => {
+  it('fills exactly terminal.rows lines (height takeover)', () => {
+    const rows = 30;
+    const lines = makeApp({}, rows).render(120);
+    expect(lines.length).toBe(rows);
+  });
+
+  it('reacts to terminal height changes', () => {
+    const props = makeProps({
+      tasks: [task({ taskId: 'bash-aaaaaaaa', status: 'running' })],
+      selectedTaskId: 'bash-aaaaaaaa',
+    });
+    // Two terminals with different heights — verify render adapts.
+    const small = new TasksBrowserApp(props, fakeTerminal(15, 120)).render(120);
+    const big = new TasksBrowserApp(props, fakeTerminal(40, 120)).render(120);
+    expect(small.length).toBe(15);
+    expect(big.length).toBe(40);
+  });
+
+  it('shows the header row with TASK BROWSER title and counts', () => {
+    const props: Partial<TasksBrowserProps> = {
+      tasks: [
+        task({ taskId: 'bash-aaaaaaaa', status: 'running' }),
+        task({ taskId: 'agent-bbbbbbbb', status: 'completed' }),
+      ],
+    };
+    const out = strip(makeApp(props).render(120).join('\n'));
+    expect(out).toContain('TASK BROWSER');
+    expect(out).toContain('filter=ALL');
+    expect(out).toContain('1 running');
+    expect(out).toContain('1 completed');
+    expect(out).toContain('2 total');
+  });
+
+  it('renders three framed panes: Tasks / Detail / Preview Output', () => {
+    const out = strip(
+      makeApp({
+        tasks: [task({ taskId: 'bash-aaaaaaaa', status: 'running' })],
+        selectedTaskId: 'bash-aaaaaaaa',
+      })
+        .render(120)
+        .join('\n'),
+    );
+    expect(out).toContain('Tasks [all]');
+    expect(out).toContain('Detail');
+    expect(out).toContain('Preview Output');
+  });
+
+  it('shows the selected task details in the Detail pane', () => {
+    const out = strip(
+      makeApp({
+        tasks: [
+          task({
+            taskId: 'bash-aaaaaaaa',
+            status: 'running',
+            description: 'long running task',
+            pid: 9999,
+          }),
+        ],
+        selectedTaskId: 'bash-aaaaaaaa',
+      })
+        .render(120)
+        .join('\n'),
+    );
+    expect(out).toContain('Task ID:');
+    expect(out).toContain('bash-aaaaaaaa');
+    expect(out).toContain('long running task');
+  });
+
+  it('renders tail output in the Preview Output pane', () => {
+    const out = strip(
+      makeApp({
+        tasks: [task({ taskId: 'bash-aaaaaaaa' })],
+        selectedTaskId: 'bash-aaaaaaaa',
+        tailOutput: 'ready in 432ms\nlistening on :3000',
+      })
+        .render(120)
+        .join('\n'),
+    );
+    expect(out).toContain('ready in 432ms');
+    expect(out).toContain('listening on :3000');
+  });
+
+  it('shows a loading state when tail is loading', () => {
+    const out = strip(
+      makeApp({
+        tasks: [task({ taskId: 'bash-aaaaaaaa' })],
+        selectedTaskId: 'bash-aaaaaaaa',
+        tailLoading: true,
+      })
+        .render(120)
+        .join('\n'),
+    );
+    expect(out).toContain('[loading');
+  });
+
+  it('shows empty-state copy in the Tasks pane when no tasks', () => {
+    const out = strip(makeApp().render(120).join('\n'));
+    expect(out).toContain('No background tasks');
+  });
+
+  it('filters out terminal tasks when filter=active', () => {
+    const tasks = [
+      task({ taskId: 'bash-aaaaaaaa', status: 'running' }),
+      task({ taskId: 'bash-bbbbbbbb', status: 'completed' }),
+    ];
+    const out = strip(makeApp({ tasks, filter: 'active' }).render(120).join('\n'));
+    expect(out).toContain('bash-aaaaaaaa');
+    expect(out).not.toContain('bash-bbbbbbbb');
+  });
+
+  it('renders without throwing for every BackgroundTaskStatus', () => {
+    const statuses: BackgroundTaskStatus[] = [
+      'running',
+      'awaiting_approval',
+      'completed',
+      'failed',
+      'killed',
+      'lost',
+    ];
+    for (const status of statuses) {
+      const props = makeProps({
+        tasks: [task({ taskId: 'bash-aaaaaaaa', status })],
+        selectedTaskId: 'bash-aaaaaaaa',
+      });
+      expect(() => new TasksBrowserApp(props, fakeTerminal(30)).render(120)).not.toThrow();
+    }
+  });
+
+  it('falls back to a single line when the terminal is too small', () => {
+    const out = strip(makeApp({}, 5, 30).render(30).join('\n'));
+    expect(out).toContain('too small');
+  });
+});
+
+describe('TasksBrowserApp — input handling', () => {
+  it('Esc invokes onCancel', () => {
+    const onCancel = vi.fn();
+    const app = makeApp({ onCancel });
+    app.handleInput('');
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it('q invokes onCancel', () => {
+    const onCancel = vi.fn();
+    makeApp({ onCancel }).handleInput('q');
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it('Tab invokes onToggleFilter', () => {
+    const onToggleFilter = vi.fn();
+    makeApp({ onToggleFilter }).handleInput('\t');
+    expect(onToggleFilter).toHaveBeenCalledTimes(1);
+  });
+
+  it('R invokes onRefresh', () => {
+    const onRefresh = vi.fn();
+    makeApp({ onRefresh }).handleInput('r');
+    expect(onRefresh).toHaveBeenCalledTimes(1);
+  });
+
+  it('arrow keys move selection and invoke onSelect', () => {
+    const onSelect = vi.fn();
+    const tasks = [
+      task({ taskId: 'bash-aaaaaaaa', status: 'running', startedAt: 1 }),
+      task({ taskId: 'bash-bbbbbbbb', status: 'running', startedAt: 2 }),
+      task({ taskId: 'bash-cccccccc', status: 'running', startedAt: 3 }),
+    ];
+    const app = makeApp({ tasks, selectedTaskId: 'bash-aaaaaaaa', onSelect });
+    app.handleInput(''); // ↓
+    expect(onSelect).toHaveBeenLastCalledWith('bash-bbbbbbbb');
+    app.handleInput('j');
+    expect(onSelect).toHaveBeenLastCalledWith('bash-cccccccc');
+    app.handleInput(''); // ↑
+    expect(onSelect).toHaveBeenLastCalledWith('bash-bbbbbbbb');
+  });
+
+  it('Enter and O both invoke onOpenOutput', () => {
+    const onOpenOutput = vi.fn();
+    const app = makeApp({
+      tasks: [task({ taskId: 'bash-aaaaaaaa' })],
+      selectedTaskId: 'bash-aaaaaaaa',
+      onOpenOutput,
+    });
+    app.handleInput('o');
+    app.handleInput('\r');
+    expect(onOpenOutput).toHaveBeenCalledTimes(2);
+    expect(onOpenOutput).toHaveBeenCalledWith('bash-aaaaaaaa');
+  });
+});
+
+// When a terminal (e.g. the VSCode integrated terminal) enables the Kitty
+// keyboard protocol disambiguate flag, ordinary printable keys arrive as
+// CSI-u sequences: `r` → "\x1b[114u", `q` → "\x1b[113u". These tests pin
+// down that the tasks panel's literal-character shortcuts still fire
+// under Kitty mode.
+describe('TasksBrowserApp — Kitty CSI-u printable input', () => {
+  const kitty = (ch: string): string => `\u001B[${String(ch.codePointAt(0) ?? 0)}u`;
+
+  it('Kitty-encoded q invokes onCancel', () => {
+    const onCancel = vi.fn();
+    makeApp({ onCancel }).handleInput(kitty('q'));
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it('Kitty-encoded r invokes onRefresh', () => {
+    const onRefresh = vi.fn();
+    makeApp({ onRefresh }).handleInput(kitty('r'));
+    expect(onRefresh).toHaveBeenCalledTimes(1);
+  });
+
+  it('Kitty-encoded j moves selection down', () => {
+    const onSelect = vi.fn();
+    const tasks = [
+      task({ taskId: 'bash-aaaaaaaa', status: 'running', startedAt: 1 }),
+      task({ taskId: 'bash-bbbbbbbb', status: 'running', startedAt: 2 }),
+    ];
+    const app = makeApp({ tasks, selectedTaskId: 'bash-aaaaaaaa', onSelect });
+    app.handleInput(kitty('j'));
+    expect(onSelect).toHaveBeenLastCalledWith('bash-bbbbbbbb');
+  });
+
+  it('Kitty-encoded o invokes onOpenOutput', () => {
+    const onOpenOutput = vi.fn();
+    const app = makeApp({
+      tasks: [task({ taskId: 'bash-aaaaaaaa' })],
+      selectedTaskId: 'bash-aaaaaaaa',
+      onOpenOutput,
+    });
+    app.handleInput(kitty('o'));
+    expect(onOpenOutput).toHaveBeenCalledWith('bash-aaaaaaaa');
+  });
+
+  it('Kitty-encoded s → y confirms a stop', () => {
+    const onStopConfirmed = vi.fn();
+    const app = makeApp({
+      tasks: [task({ taskId: 'bash-aaaaaaaa', status: 'running' })],
+      selectedTaskId: 'bash-aaaaaaaa',
+      onStopConfirmed,
+    });
+    app.handleInput(kitty('s'));
+    app.handleInput(kitty('y'));
+    expect(onStopConfirmed).toHaveBeenCalledWith('bash-aaaaaaaa');
+  });
+});
+
+describe('TasksBrowserApp — stop confirmation', () => {
+  it('S → y confirms a stop and invokes onStopConfirmed', () => {
+    const onStopConfirmed = vi.fn();
+    const app = makeApp({
+      tasks: [task({ taskId: 'bash-aaaaaaaa', status: 'running' })],
+      selectedTaskId: 'bash-aaaaaaaa',
+      onStopConfirmed,
+    });
+    app.handleInput('s');
+    const after = strip(app.render(120).join('\n'));
+    expect(after).toContain('Stop bash-aaaaaaaa?');
+    app.handleInput('y');
+    expect(onStopConfirmed).toHaveBeenCalledWith('bash-aaaaaaaa');
+    expect(strip(app.render(120).join('\n'))).not.toContain('Stop bash-aaaaaaaa?');
+  });
+
+  it('S → n cancels without firing onStopConfirmed', () => {
+    const onStopConfirmed = vi.fn();
+    const app = makeApp({
+      tasks: [task({ taskId: 'bash-aaaaaaaa', status: 'running' })],
+      selectedTaskId: 'bash-aaaaaaaa',
+      onStopConfirmed,
+    });
+    app.handleInput('s');
+    app.handleInput('n');
+    expect(onStopConfirmed).not.toHaveBeenCalled();
+    expect(strip(app.render(120).join('\n'))).not.toContain('Stop bash-aaaaaaaa?');
+  });
+
+  it('S → Esc cancels the confirm without closing the panel', () => {
+    const onStopConfirmed = vi.fn();
+    const onCancel = vi.fn();
+    const app = makeApp({
+      tasks: [task({ taskId: 'bash-aaaaaaaa', status: 'running' })],
+      selectedTaskId: 'bash-aaaaaaaa',
+      onStopConfirmed,
+      onCancel,
+    });
+    app.handleInput('s');
+    app.handleInput('');
+    expect(onStopConfirmed).not.toHaveBeenCalled();
+    expect(onCancel).not.toHaveBeenCalled();
+  });
+
+  it('S on a terminal task invokes onStopIgnored and stays out of confirm mode', () => {
+    const onStopConfirmed = vi.fn();
+    const onStopIgnored = vi.fn();
+    const app = makeApp({
+      tasks: [task({ taskId: 'bash-aaaaaaaa', status: 'completed', exitCode: 0 })],
+      selectedTaskId: 'bash-aaaaaaaa',
+      onStopConfirmed,
+      onStopIgnored,
+    });
+    app.handleInput('s');
+    expect(onStopIgnored).toHaveBeenCalledWith('bash-aaaaaaaa', 'terminal');
+    expect(onStopConfirmed).not.toHaveBeenCalled();
+    expect(strip(app.render(120).join('\n'))).not.toContain('Stop bash-aaaaaaaa?');
+  });
+
+  it('navigation during confirm mode is locked out', () => {
+    const onSelect = vi.fn();
+    const onStopConfirmed = vi.fn();
+    const tasks = [
+      task({ taskId: 'bash-aaaaaaaa', status: 'running', startedAt: 1 }),
+      task({ taskId: 'bash-bbbbbbbb', status: 'running', startedAt: 2 }),
+    ];
+    const app = makeApp({ tasks, selectedTaskId: 'bash-aaaaaaaa', onSelect, onStopConfirmed });
+    app.handleInput('s');
+    onSelect.mockClear();
+    app.handleInput(''); // ↓ arrow should be swallowed
+    expect(onSelect).not.toHaveBeenCalled();
+    expect(strip(app.render(120).join('\n'))).not.toContain('Stop bash-aaaaaaaa?');
+  });
+});
+
+describe('TasksBrowserApp — setProps', () => {
+  it('keeps selection across prop updates when the task still exists', () => {
+    const tasks = [
+      task({ taskId: 'bash-aaaaaaaa', status: 'running' }),
+      task({ taskId: 'bash-bbbbbbbb', status: 'running' }),
+    ];
+    const app = makeApp({ tasks, selectedTaskId: 'bash-bbbbbbbb' });
+    app.setProps({
+      ...makeProps({
+        tasks: [...tasks, task({ taskId: 'bash-cccccccc', status: 'completed' })],
+        selectedTaskId: 'bash-bbbbbbbb',
+      }),
+    });
+    const out = strip(app.render(120).join('\n'));
+    expect(out).toContain('bash-bbbbbbbb');
+  });
+
+  it('switches the filter via setProps without throwing', () => {
+    const tasks = [task({ status: 'completed' })];
+    const filters: TasksFilter[] = ['all', 'active', 'all'];
+    const app = makeApp({ tasks });
+    for (const filter of filters) {
+      expect(() => {
+        app.setProps(makeProps({ tasks, filter }));
+      }).not.toThrow();
+    }
+  });
+});
diff --git a/apps/kimi-code/test/tui/terminal-focus.test.ts b/apps/kimi-code/test/tui/terminal-focus.test.ts
new file mode 100644
index 000000000..71246b785
--- /dev/null
+++ b/apps/kimi-code/test/tui/terminal-focus.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { TUIState } from '#/tui/kimi-tui';
+import {
+  DISABLE_TERMINAL_FOCUS_REPORTING,
+  ENABLE_TERMINAL_FOCUS_REPORTING,
+  TERMINAL_FOCUS_IN,
+  TERMINAL_FOCUS_OUT,
+  handleTerminalFocusInput,
+  installTerminalFocusTracking,
+} from '#/tui/utils/terminal-focus';
+
+describe('terminal focus tracking', () => {
+  it('updates focus state from terminal focus reporting sequences', () => {
+    const state = { focused: true };
+
+    expect(handleTerminalFocusInput(state, TERMINAL_FOCUS_OUT)).toEqual({ consume: true });
+    expect(state.focused).toBe(false);
+
+    expect(handleTerminalFocusInput(state, TERMINAL_FOCUS_IN)).toEqual({ consume: true });
+    expect(state.focused).toBe(true);
+
+    expect(handleTerminalFocusInput(state, 'x')).toBeUndefined();
+  });
+
+  it('enables focus reporting and removes the listener on dispose', () => {
+    const listeners: Array<(data: string) => { consume: true } | undefined> = [];
+    const removeInputListener = vi.fn();
+    const state = {
+      terminalState: {
+        focused: false,
+      },
+      terminal: {
+        write: vi.fn(),
+      },
+      ui: {
+        addInputListener: vi.fn((listener) => {
+          listeners.push(listener);
+          return removeInputListener;
+        }),
+      },
+    } as unknown as TUIState;
+
+    const dispose = installTerminalFocusTracking(state);
+
+    expect(state.terminalState.focused).toBe(true);
+    expect(state.terminal.write).toHaveBeenCalledWith(ENABLE_TERMINAL_FOCUS_REPORTING);
+    expect(listeners).toHaveLength(1);
+
+    listeners[0]?.(TERMINAL_FOCUS_OUT);
+    expect(state.terminalState.focused).toBe(false);
+
+    dispose();
+
+    expect(removeInputListener).toHaveBeenCalledOnce();
+    expect(state.terminal.write).toHaveBeenCalledWith(DISABLE_TERMINAL_FOCUS_REPORTING);
+    expect(state.terminalState.focused).toBe(true);
+  });
+});
diff --git a/apps/kimi-code/test/tui/terminal-notification.test.ts b/apps/kimi-code/test/tui/terminal-notification.test.ts
new file mode 100644
index 000000000..2d5d904ee
--- /dev/null
+++ b/apps/kimi-code/test/tui/terminal-notification.test.ts
@@ -0,0 +1,227 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { TUIState } from '#/tui/kimi-tui';
+import {
+  buildTerminalNotificationSequences,
+  emitTerminalNotification,
+  formatNotification,
+  isInsideTmux,
+  notifyTerminalOnce,
+  supportsOsc9Notification,
+} from '#/tui/utils/terminal-notification';
+
+function makeNotificationState(args: {
+  readonly enabled?: boolean;
+  readonly condition?: 'unfocused' | 'always';
+  readonly focused?: boolean;
+  readonly supportsOsc9?: boolean;
+  readonly insideTmux?: boolean;
+} = {}): TUIState {
+  return {
+    appState: {
+      notifications: {
+        enabled: args.enabled ?? true,
+        condition: args.condition ?? 'unfocused',
+      },
+    },
+    terminalState: {
+      notificationKeys: new Set<string>(),
+      focused: args.focused ?? false,
+      supportsOsc9: args.supportsOsc9 ?? true,
+      insideTmux: args.insideTmux ?? false,
+    },
+    terminal: {
+      write: vi.fn(),
+    },
+  } as unknown as TUIState;
+}
+
+describe('terminal notification helpers', () => {
+  it('emits OSC 9 only when the terminal supports it', () => {
+    const terminal = { write: vi.fn() };
+
+    emitTerminalNotification(
+      terminal,
+      { title: 'Kimi Code', body: 'Approval\nrequired' },
+      { supportsOsc9: true, insideTmux: false },
+    );
+
+    expect(terminal.write).toHaveBeenCalledTimes(1);
+    expect(terminal.write).toHaveBeenCalledWith(']9;Kimi Code: Approval required');
+  });
+
+  it('falls back to a bare BEL when the terminal does not support OSC 9', () => {
+    const terminal = { write: vi.fn() };
+
+    emitTerminalNotification(
+      terminal,
+      { title: 'Kimi Code', body: 'Approval required' },
+      { supportsOsc9: false, insideTmux: false },
+    );
+
+    expect(terminal.write).toHaveBeenCalledTimes(1);
+    expect(terminal.write).toHaveBeenCalledWith('');
+  });
+
+  it('wraps OSC 9 in a tmux DCS passthrough when running inside tmux', () => {
+    const terminal = { write: vi.fn() };
+
+    emitTerminalNotification(
+      terminal,
+      { title: 'Kimi Code', body: 'Approval required' },
+      { supportsOsc9: true, insideTmux: true },
+    );
+
+    expect(terminal.write).toHaveBeenCalledTimes(1);
+    expect(terminal.write).toHaveBeenCalledWith('Ptmux;]9;Kimi Code: Approval required\\');
+  });
+
+  it('skips the tmux wrap when falling back to BEL', () => {
+    const terminal = { write: vi.fn() };
+
+    emitTerminalNotification(
+      terminal,
+      { title: 'Kimi Code', body: 'Approval required' },
+      { supportsOsc9: false, insideTmux: true },
+    );
+
+    expect(terminal.write).toHaveBeenCalledWith('');
+  });
+
+  it('emits nothing when the formatted message is empty', () => {
+    const terminal = { write: vi.fn() };
+
+    emitTerminalNotification(
+      terminal,
+      { title: '', body: '' },
+      { supportsOsc9: true, insideTmux: false },
+    );
+
+    expect(terminal.write).not.toHaveBeenCalled();
+  });
+
+  it('deduplicates notifications by key on TUI state', () => {
+    const state = makeNotificationState();
+
+    notifyTerminalOnce(state, 'approval:req-1', { title: 'Approval required' });
+    notifyTerminalOnce(state, 'approval:req-1', { title: 'Approval required' });
+    notifyTerminalOnce(state, 'approval:req-2', { title: 'Approval required' });
+
+    expect(state.terminal.write).toHaveBeenCalledTimes(2);
+  });
+
+  it('suppresses notifications while the terminal is focused', () => {
+    const state = makeNotificationState({ focused: true });
+
+    notifyTerminalOnce(state, 'approval:req-1', { title: 'Approval required' });
+    state.terminalState.focused = false;
+    notifyTerminalOnce(state, 'approval:req-1', { title: 'Approval required' });
+    notifyTerminalOnce(state, 'approval:req-2', { title: 'Approval required' });
+
+    expect(state.terminal.write).toHaveBeenCalledTimes(1);
+    expect(state.terminalState.notificationKeys.has('approval:req-1')).toBe(true);
+  });
+
+  it('skips emission entirely when notifications.enabled is false', () => {
+    const state = makeNotificationState({ enabled: false });
+
+    notifyTerminalOnce(state, 'approval:req-1', { title: 'Approval required' });
+
+    expect(state.terminal.write).not.toHaveBeenCalled();
+    expect(state.terminalState.notificationKeys.has('approval:req-1')).toBe(false);
+  });
+
+  it('emits even while focused when condition is "always"', () => {
+    const state = makeNotificationState({ condition: 'always', focused: true });
+
+    notifyTerminalOnce(state, 'approval:req-1', { title: 'Approval required' });
+
+    expect(state.terminal.write).toHaveBeenCalledTimes(1);
+    expect(state.terminalState.notificationKeys.has('approval:req-1')).toBe(true);
+  });
+
+  it('uses the tmux-wrapped sequence when state.insideTmux is true', () => {
+    const state = makeNotificationState({ insideTmux: true });
+
+    notifyTerminalOnce(state, 'approval:req-1', { title: 'Approval required' });
+
+    expect(state.terminal.write).toHaveBeenCalledTimes(1);
+    expect(state.terminal.write).toHaveBeenCalledWith('Ptmux;]9;Approval required\\');
+  });
+
+  it('falls back to BEL on a TUI state that did not detect OSC 9 support', () => {
+    const state = makeNotificationState({ supportsOsc9: false });
+
+    notifyTerminalOnce(state, 'approval:req-1', { title: 'Approval required' });
+
+    expect(state.terminal.write).toHaveBeenCalledTimes(1);
+    expect(state.terminal.write).toHaveBeenCalledWith('');
+  });
+
+  it('falls back to body when the title is empty', () => {
+    expect(formatNotification({ title: '', body: 'Question?' })).toBe('Question?');
+  });
+
+  it('returns OSC 9 / BEL based on capability flag', () => {
+    expect(
+      buildTerminalNotificationSequences(
+        { title: 'A', body: 'B' },
+        { supportsOsc9: true, insideTmux: false },
+      ),
+    ).toEqual([']9;A: B']);
+    expect(
+      buildTerminalNotificationSequences(
+        { title: 'A', body: 'B' },
+        { supportsOsc9: false, insideTmux: false },
+      ),
+    ).toEqual(['']);
+  });
+
+  it('doubles ESC bytes inside the tmux DCS payload', () => {
+    const sequences = buildTerminalNotificationSequences(
+      { title: 'A', body: 'B' },
+      { supportsOsc9: true, insideTmux: true },
+    );
+
+    expect(sequences).toHaveLength(1);
+    const wrapped = sequences[0]!;
+    expect(wrapped.startsWith('Ptmux;')).toBe(true);
+    expect(wrapped.endsWith('\\')).toBe(true);
+    expect(wrapped).toContain(']9;A: B');
+  });
+});
+
+describe('supportsOsc9Notification', () => {
+  it('detects iTerm2 / WezTerm / Ghostty / Warp via TERM_PROGRAM', () => {
+    expect(supportsOsc9Notification({ TERM_PROGRAM: 'iTerm.app' })).toBe(true);
+    expect(supportsOsc9Notification({ TERM_PROGRAM: 'WezTerm' })).toBe(true);
+    expect(supportsOsc9Notification({ TERM_PROGRAM: 'ghostty' })).toBe(true);
+    expect(supportsOsc9Notification({ TERM_PROGRAM: 'WarpTerminal' })).toBe(true);
+  });
+
+  it('detects Kitty / Ghostty via TERM', () => {
+    expect(supportsOsc9Notification({ TERM: 'xterm-kitty' })).toBe(true);
+    expect(supportsOsc9Notification({ TERM: 'xterm-ghostty' })).toBe(true);
+  });
+
+  it('returns false for terminals known not to support OSC 9', () => {
+    expect(supportsOsc9Notification({ TERM_PROGRAM: 'Apple_Terminal' })).toBe(false);
+    expect(supportsOsc9Notification({ TERM_PROGRAM: 'vscode' })).toBe(false);
+    expect(supportsOsc9Notification({ TERM_PROGRAM: 'tabby' })).toBe(false);
+    expect(supportsOsc9Notification({ WT_SESSION: 'abc-123' })).toBe(false);
+    expect(supportsOsc9Notification({ ConEmuANSI: 'ON' })).toBe(false);
+    expect(supportsOsc9Notification({ TERM: 'xterm-256color' })).toBe(false);
+    expect(supportsOsc9Notification({})).toBe(false);
+  });
+});
+
+describe('isInsideTmux', () => {
+  it('detects tmux via the TMUX env var', () => {
+    expect(isInsideTmux({ TMUX: '/private/tmp/tmux-501/default,1234,0' })).toBe(true);
+  });
+
+  it('returns false when TMUX is empty or unset', () => {
+    expect(isInsideTmux({ TMUX: '' })).toBe(false);
+    expect(isInsideTmux({})).toBe(false);
+  });
+});
diff --git a/apps/kimi-code/test/tui/terminal-theme.test.ts b/apps/kimi-code/test/tui/terminal-theme.test.ts
new file mode 100644
index 000000000..68a1818b2
--- /dev/null
+++ b/apps/kimi-code/test/tui/terminal-theme.test.ts
@@ -0,0 +1,160 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { TUIState } from "#/tui/kimi-tui";
+import {
+  DISABLE_TERMINAL_THEME_REPORTING,
+  ENABLE_TERMINAL_THEME_REPORTING,
+  OSC11_QUERY,
+  QUERY_TERMINAL_THEME,
+  TERMINAL_THEME_DARK,
+  TERMINAL_THEME_LIGHT,
+  createTerminalThemeInputState,
+  hasTerminalThemeReport,
+  handleTerminalThemeInput,
+  installTerminalThemeTracking,
+} from "#/tui/utils/terminal-theme";
+
+type InputListener = Parameters<TUIState["ui"]["addInputListener"]>[0];
+const DARK_OSC11_REPORT = "\u001B]11;rgb:2828/2c2c/3434\u0007";
+const LIGHT_OSC11_REPORT = "\u001B]11;rgb:fafa/fbfb/fcfc\u0007";
+
+describe("terminal theme tracking", () => {
+  it("recognizes terminal theme reports as change notifications", () => {
+    expect(hasTerminalThemeReport(TERMINAL_THEME_DARK)).toBe(true);
+    expect(hasTerminalThemeReport(TERMINAL_THEME_LIGHT)).toBe(true);
+    expect(hasTerminalThemeReport(`x${TERMINAL_THEME_LIGHT}y`)).toBe(true);
+    expect(hasTerminalThemeReport("x")).toBe(false);
+  });
+
+  it("consumes theme reports by querying the terminal background", () => {
+    const terminal = { write: vi.fn() };
+    const onTheme = vi.fn();
+
+    expect(handleTerminalThemeInput(TERMINAL_THEME_DARK, terminal, onTheme)).toEqual({
+      consume: true,
+    });
+    expect(handleTerminalThemeInput(TERMINAL_THEME_LIGHT, terminal, onTheme)).toEqual({
+      consume: true,
+    });
+
+    expect(terminal.write).toHaveBeenCalledTimes(2);
+    expect(terminal.write).toHaveBeenCalledWith(OSC11_QUERY);
+    expect(onTheme).not.toHaveBeenCalled();
+  });
+
+  it("strips terminal theme reports without dropping coalesced input", () => {
+    const terminal = { write: vi.fn() };
+    const onTheme = vi.fn();
+
+    expect(handleTerminalThemeInput(`a${TERMINAL_THEME_LIGHT}b`, terminal, onTheme)).toEqual({
+      data: "ab",
+    });
+
+    expect(terminal.write).toHaveBeenCalledWith(OSC11_QUERY);
+    expect(onTheme).not.toHaveBeenCalled();
+  });
+
+  it("consumes OSC 11 background reports and forwards resolved themes", () => {
+    const terminal = { write: vi.fn() };
+    const onTheme = vi.fn();
+
+    expect(handleTerminalThemeInput(DARK_OSC11_REPORT, terminal, onTheme)).toEqual({
+      consume: true,
+    });
+    expect(onTheme).toHaveBeenLastCalledWith("dark");
+
+    expect(handleTerminalThemeInput(LIGHT_OSC11_REPORT, terminal, onTheme)).toEqual({
+      consume: true,
+    });
+    expect(onTheme).toHaveBeenLastCalledWith("light");
+
+    expect(handleTerminalThemeInput("x", terminal, onTheme)).toBeUndefined();
+    expect(handleTerminalThemeInput("]", terminal, onTheme)).toBeUndefined();
+    expect(onTheme).toHaveBeenCalledTimes(2);
+    expect(terminal.write).not.toHaveBeenCalled();
+  });
+
+  it("strips OSC 11 background reports without dropping coalesced input", () => {
+    const terminal = { write: vi.fn() };
+    const onTheme = vi.fn();
+
+    expect(handleTerminalThemeInput(`a${DARK_OSC11_REPORT}b`, terminal, onTheme)).toEqual({
+      data: "ab",
+    });
+
+    expect(onTheme).toHaveBeenCalledWith("dark");
+    expect(terminal.write).not.toHaveBeenCalled();
+  });
+
+  it("accumulates fragmented OSC 11 background reports", () => {
+    const terminal = { write: vi.fn() };
+    const onTheme = vi.fn();
+    const inputState = createTerminalThemeInputState();
+
+    expect(
+      handleTerminalThemeInput("\u001B]11;rgb:2828/2c2c/3", terminal, onTheme, inputState),
+    ).toEqual({ consume: true });
+    expect(onTheme).not.toHaveBeenCalled();
+
+    expect(handleTerminalThemeInput("434\u0007", terminal, onTheme, inputState)).toEqual({
+      consume: true,
+    });
+    expect(onTheme).toHaveBeenCalledWith("dark");
+    expect(inputState.osc11Buffer).toBe("");
+  });
+
+  it("forwards input that follows a fragmented OSC 11 background report", () => {
+    const terminal = { write: vi.fn() };
+    const onTheme = vi.fn();
+    const inputState = createTerminalThemeInputState();
+
+    expect(
+      handleTerminalThemeInput("\u001B]11;rgb:2828/2c2c/3", terminal, onTheme, inputState),
+    ).toEqual({ consume: true });
+
+    expect(handleTerminalThemeInput("434\u0007x", terminal, onTheme, inputState)).toEqual({
+      data: "x",
+    });
+    expect(onTheme).toHaveBeenCalledWith("dark");
+    expect(inputState.osc11Buffer).toBe("");
+  });
+
+  it("enables reporting, queries current theme, and disables on dispose", () => {
+    const listeners: InputListener[] = [];
+    const removeInputListener = vi.fn();
+    const onTheme = vi.fn();
+    const state = {
+      terminal: {
+        write: vi.fn(),
+      },
+      ui: {
+        addInputListener: vi.fn((listener: InputListener) => {
+          listeners.push(listener);
+          return removeInputListener;
+        }),
+      },
+    } as unknown as Pick<TUIState, "terminal" | "ui">;
+
+    const dispose = installTerminalThemeTracking(state, onTheme);
+
+    expect(state.terminal.write).toHaveBeenCalledWith(ENABLE_TERMINAL_THEME_REPORTING);
+    expect(state.terminal.write).toHaveBeenCalledWith(OSC11_QUERY);
+    expect(state.terminal.write).toHaveBeenCalledWith(QUERY_TERMINAL_THEME);
+    expect(listeners).toHaveLength(1);
+
+    expect(listeners[0]?.(TERMINAL_THEME_LIGHT)).toEqual({ consume: true });
+    expect(state.terminal.write).toHaveBeenCalledWith(OSC11_QUERY);
+    expect(onTheme).not.toHaveBeenCalled();
+
+    expect(listeners[0]?.("\u001B]11;rgb:2828/2c2c/3")).toEqual({ consume: true });
+    expect(onTheme).not.toHaveBeenCalled();
+
+    expect(listeners[0]?.("434\u0007")).toEqual({ consume: true });
+    expect(onTheme).toHaveBeenCalledWith("dark");
+
+    dispose();
+
+    expect(removeInputListener).toHaveBeenCalledOnce();
+    expect(state.terminal.write).toHaveBeenCalledWith(DISABLE_TERMINAL_THEME_REPORTING);
+  });
+});
diff --git a/apps/kimi-code/test/tui/utils/mcp-oauth.test.ts b/apps/kimi-code/test/tui/utils/mcp-oauth.test.ts
new file mode 100644
index 000000000..1e1808508
--- /dev/null
+++ b/apps/kimi-code/test/tui/utils/mcp-oauth.test.ts
@@ -0,0 +1,106 @@
+import {
+  MCP_OAUTH_AUTHORIZATION_URL_TOOL_UPDATE,
+  type ToolUpdate,
+} from '@moonshot-ai/kimi-code-sdk';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  McpOAuthAuthorizationUrlOpener,
+  type OpenUrl,
+  parseMcpOAuthAuthorizationUrlUpdate,
+} from '#/tui/utils/mcp-oauth';
+
+describe('parseMcpOAuthAuthorizationUrlUpdate', () => {
+  it('extracts MCP OAuth authorization URLs from structured tool updates', () => {
+    const update: ToolUpdate = {
+      kind: 'custom',
+      customKind: MCP_OAUTH_AUTHORIZATION_URL_TOOL_UPDATE,
+      customData: {
+        serverName: 'linear',
+        authorizationUrl: 'https://linear.example/oauth?state=abc',
+      },
+    };
+
+    expect(parseMcpOAuthAuthorizationUrlUpdate(update)).toEqual({
+      serverName: 'linear',
+      authorizationUrl: 'https://linear.example/oauth?state=abc',
+    });
+  });
+
+  it('ignores unrelated or malformed updates', () => {
+    const unrelated: ToolUpdate = {
+      kind: 'status',
+      text: 'https://linear.example/oauth?state=abc',
+    };
+    const malformed: ToolUpdate = {
+      kind: 'custom',
+      customKind: MCP_OAUTH_AUTHORIZATION_URL_TOOL_UPDATE,
+      customData: {
+        serverName: 'linear',
+        authorizationUrl: 'file:///tmp/callback',
+      },
+    };
+
+    expect(parseMcpOAuthAuthorizationUrlUpdate(unrelated)).toBeUndefined();
+    expect(parseMcpOAuthAuthorizationUrlUpdate(malformed)).toBeUndefined();
+  });
+});
+
+describe('McpOAuthAuthorizationUrlOpener', () => {
+  it('opens authorization URLs from structured tool progress updates', () => {
+    const openUrl = vi.fn<OpenUrl>();
+    const opener = new McpOAuthAuthorizationUrlOpener(openUrl);
+
+    opener.handleToolProgress({
+      toolCallId: 'tool-1',
+      update: authorizationUrlUpdate('https://linear.example/oauth?state=abc'),
+    });
+
+    expect(openUrl).toHaveBeenCalledTimes(1);
+    expect(openUrl).toHaveBeenCalledWith('https://linear.example/oauth?state=abc');
+  });
+
+  it('opens each authorization URL once per tool call', () => {
+    const openUrl = vi.fn<OpenUrl>();
+    const opener = new McpOAuthAuthorizationUrlOpener(openUrl);
+    const update = authorizationUrlUpdate('https://linear.example/oauth?state=abc');
+
+    opener.handleToolProgress({ toolCallId: 'tool-1', update });
+    opener.handleToolProgress({ toolCallId: 'tool-1', update });
+    opener.handleToolProgress({ toolCallId: 'tool-2', update });
+
+    expect(openUrl).toHaveBeenCalledTimes(2);
+    expect(openUrl).toHaveBeenNthCalledWith(1, 'https://linear.example/oauth?state=abc');
+    expect(openUrl).toHaveBeenNthCalledWith(2, 'https://linear.example/oauth?state=abc');
+  });
+
+  it('ignores progress updates that do not contain an MCP OAuth authorization URL', () => {
+    const openUrl = vi.fn<OpenUrl>();
+    const opener = new McpOAuthAuthorizationUrlOpener(openUrl);
+
+    opener.handleToolProgress({
+      toolCallId: 'tool-1',
+      update: {
+        kind: 'status',
+        text: 'https://linear.example/oauth?state=abc',
+      },
+    });
+    opener.handleToolProgress({
+      toolCallId: 'tool-1',
+      update: authorizationUrlUpdate('file:///tmp/callback'),
+    });
+
+    expect(openUrl).not.toHaveBeenCalled();
+  });
+});
+
+function authorizationUrlUpdate(authorizationUrl: string): ToolUpdate {
+  return {
+    kind: 'custom',
+    customKind: MCP_OAUTH_AUTHORIZATION_URL_TOOL_UPDATE,
+    customData: {
+      serverName: 'linear',
+      authorizationUrl,
+    },
+  };
+}
diff --git a/apps/kimi-code/test/utils/clipboard/clipboard-image.test.ts b/apps/kimi-code/test/utils/clipboard/clipboard-image.test.ts
new file mode 100644
index 000000000..7e802db6a
--- /dev/null
+++ b/apps/kimi-code/test/utils/clipboard/clipboard-image.test.ts
@@ -0,0 +1,161 @@
+import { mkdtempSync, rmSync, truncateSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { ClipboardMediaError, readClipboardMedia } from '#/utils/clipboard/clipboard-image';
+import type { ClipboardModule } from '#/utils/clipboard/clipboard-native';
+
+function png(width: number, height: number): Uint8Array {
+  const bytes = new Uint8Array(24);
+  bytes.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], 0);
+  bytes.set([0x00, 0x00, 0x00, 0x0d], 8);
+  bytes.set([0x49, 0x48, 0x44, 0x52], 12);
+  bytes[16] = (width >>> 24) & 0xff;
+  bytes[17] = (width >>> 16) & 0xff;
+  bytes[18] = (width >>> 8) & 0xff;
+  bytes[19] = width & 0xff;
+  bytes[20] = (height >>> 24) & 0xff;
+  bytes[21] = (height >>> 16) & 0xff;
+  bytes[22] = (height >>> 8) & 0xff;
+  bytes[23] = height & 0xff;
+  return bytes;
+}
+
+function fakeClipboard(overrides: Partial<ClipboardModule>): ClipboardModule {
+  return {
+    hasImage: vi.fn(() => false),
+    getImageBinary: vi.fn(async () => []),
+    ...overrides,
+  };
+}
+
+function noMacOsPaths(): { stdout: Buffer; ok: boolean } {
+  return { stdout: Buffer.alloc(0), ok: false };
+}
+
+describe('readClipboardMedia', () => {
+  it('reads a copied image file from its real path instead of the Finder preview icon', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'kimi-code-clip-'));
+    try {
+      const imagePath = join(dir, 'photo.png');
+      const imageBytes = png(12, 34);
+      writeFileSync(imagePath, imageBytes);
+      const getImageBinary = vi.fn(async () => Array.from(png(1, 1)));
+      const clip = fakeClipboard({
+        availableFormats: vi.fn(() => ['public.file-url', 'public.png']),
+        hasImage: vi.fn(() => true),
+        getImageBinary,
+      });
+      const runCommand = vi.fn(() => ({ stdout: Buffer.from(`${imagePath}\n`), ok: true }));
+
+      const media = await readClipboardMedia({ platform: 'darwin', clipboard: clip, runCommand });
+
+      expect(media).toEqual({
+        kind: 'image',
+        bytes: imageBytes,
+        mimeType: 'image/png',
+      });
+      expect(getImageBinary).not.toHaveBeenCalled();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('prefers a video file URL over an available image preview', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'kimi-code-clip-'));
+    try {
+      const videoPath = join(dir, 'sample.mov');
+      writeFileSync(videoPath, new Uint8Array([0, 1, 2]));
+      const getImageBinary = vi.fn(async () => [0x89, 0x50, 0x4e, 0x47]);
+      const clip = fakeClipboard({
+        availableFormats: vi.fn(() => ['public.file-url', 'public.png']),
+        hasText: vi.fn(() => true),
+        getText: vi.fn(async () => pathToFileURL(videoPath).toString()),
+        hasImage: vi.fn(() => true),
+        getImageBinary,
+      });
+
+      const media = await readClipboardMedia({
+        platform: 'darwin',
+        clipboard: clip,
+        runCommand: noMacOsPaths,
+      });
+
+      expect(media?.kind).toBe('video');
+      expect(media).toMatchObject({
+        mimeType: 'video/quicktime',
+        filename: 'sample.mov',
+        sourcePath: videoPath,
+      });
+      expect(getImageBinary).not.toHaveBeenCalled();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('falls back to native image bytes when no video file is present', async () => {
+    const clip = fakeClipboard({
+      availableFormats: vi.fn(() => ['public.png']),
+      hasText: vi.fn(() => false),
+      hasImage: vi.fn(() => true),
+      getImageBinary: vi.fn(async () => [0x89, 0x50, 0x4e, 0x47]),
+    });
+
+    const media = await readClipboardMedia({
+      platform: 'darwin',
+      clipboard: clip,
+      runCommand: noMacOsPaths,
+    });
+
+    expect(media).toEqual({
+      kind: 'image',
+      bytes: new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+      mimeType: 'image/png',
+    });
+  });
+
+  it('does not consume file-like clipboard image previews when no real file path is readable', async () => {
+    const getImageBinary = vi.fn(async () => Array.from(png(1, 1)));
+    const clip = fakeClipboard({
+      availableFormats: vi.fn(() => ['public.file-url', 'public.png']),
+      hasImage: vi.fn(() => true),
+      getImageBinary,
+    });
+
+    const media = await readClipboardMedia({
+      platform: 'darwin',
+      clipboard: clip,
+      runCommand: noMacOsPaths,
+    });
+
+    expect(media).toBeNull();
+    expect(getImageBinary).not.toHaveBeenCalled();
+  });
+
+  it('rejects pasted videos larger than 100 MB', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'kimi-code-clip-'));
+    try {
+      const videoPath = resolve(dir, 'too-big.mp4');
+      writeFileSync(videoPath, new Uint8Array([0]));
+      truncateSync(videoPath, 101 * 1024 * 1024);
+      const clip = fakeClipboard({
+        availableFormats: vi.fn(() => ['public.file-url']),
+        hasText: vi.fn(() => true),
+        getText: vi.fn(async () => pathToFileURL(videoPath).toString()),
+      });
+
+      await expect(
+        readClipboardMedia({
+          platform: 'darwin',
+          clipboard: clip,
+          runCommand: noMacOsPaths,
+        }),
+      ).rejects.toThrow(ClipboardMediaError);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/apps/kimi-code/test/utils/git/git-ls-files.test.ts b/apps/kimi-code/test/utils/git/git-ls-files.test.ts
new file mode 100644
index 000000000..d7b193a5c
--- /dev/null
+++ b/apps/kimi-code/test/utils/git/git-ls-files.test.ts
@@ -0,0 +1,113 @@
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, utimesSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+import { createGitLsFilesCache } from '#/utils/git/git-ls-files';
+
+function git(cwd: string, ...args: string[]): void {
+  execFileSync('git', args, { cwd, stdio: 'ignore' });
+}
+
+function commit(cwd: string, message: string): void {
+  git(cwd, '-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', message);
+}
+
+describe('createGitLsFilesCache', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'git-ls-files-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('returns null for a non-git directory', () => {
+    const cache = createGitLsFilesCache(dir);
+    expect(cache.isGitRepo()).toBe(false);
+    expect(cache.list()).toBeNull();
+  });
+
+  it('lists tracked files in a git repo', () => {
+    git(dir, 'init');
+    writeFileSync(join(dir, 'a.ts'), '');
+    mkdirSync(join(dir, 'src'));
+    writeFileSync(join(dir, 'src/b.ts'), '');
+    git(dir, 'add', '.');
+    commit(dir, 'init');
+
+    const cache = createGitLsFilesCache(dir);
+    expect(cache.isGitRepo()).toBe(true);
+    const snap = cache.getSnapshot();
+    expect(snap).not.toBeNull();
+    expect(snap!.files).toContain('a.ts');
+    expect(snap!.files).toContain('src/b.ts');
+    expect(snap!.mtimeByPath.has('a.ts')).toBe(true);
+    expect(snap!.mtimeByPath.get('a.ts')!).toBeGreaterThan(0);
+    expect(cache.getSnapshot()).toBe(snap);
+  });
+
+  it('includes untracked-but-not-ignored files', () => {
+    git(dir, 'init');
+    writeFileSync(join(dir, '.gitignore'), 'ignored.ts\n');
+    writeFileSync(join(dir, 'tracked.ts'), '');
+    git(dir, 'add', 'tracked.ts');
+    commit(dir, 'init');
+
+    // Create both an untracked file and one that matches .gitignore.
+    writeFileSync(join(dir, 'new.ts'), '');
+    writeFileSync(join(dir, 'ignored.ts'), '');
+
+    const cache = createGitLsFilesCache(dir);
+    const files = cache.list()!;
+    expect(files).toContain('tracked.ts');
+    expect(files).toContain('new.ts');
+    expect(files).not.toContain('ignored.ts');
+  });
+
+  it('builds a recency order from recent commits', () => {
+    git(dir, 'init');
+    writeFileSync(join(dir, 'old.ts'), '');
+    git(dir, 'add', 'old.ts');
+    commit(dir, 'old');
+    writeFileSync(join(dir, 'new.ts'), '');
+    git(dir, 'add', 'new.ts');
+    commit(dir, 'new');
+
+    const cache = createGitLsFilesCache(dir);
+    const snap = cache.getSnapshot()!;
+    const newRank = snap.recencyOrder.get('new.ts');
+    const oldRank = snap.recencyOrder.get('old.ts');
+    expect(newRank).toBeDefined();
+    expect(oldRank).toBeDefined();
+    expect(newRank!).toBeLessThan(oldRank!);
+  });
+
+  it('invalidates when .git/index mtime changes', () => {
+    git(dir, 'init');
+    writeFileSync(join(dir, 'a.ts'), '');
+    git(dir, 'add', '.');
+    commit(dir, 'init');
+
+    const cache = createGitLsFilesCache(dir);
+    const first = cache.list()!;
+    expect(first).toContain('a.ts');
+
+    // Touch .git/index forward to simulate a new commit / add.
+    const indexPath = join(dir, '.git', 'index');
+    const s = statSync(indexPath);
+    const future = new Date(s.mtimeMs + 5000);
+    utimesSync(indexPath, future, future);
+
+    writeFileSync(join(dir, 'b.ts'), '');
+    git(dir, 'add', 'b.ts');
+
+    const second = cache.list()!;
+    expect(second).not.toBe(first); // new snapshot
+    expect(second).toContain('b.ts');
+  });
+});
diff --git a/apps/kimi-code/test/utils/git/git-status.test.ts b/apps/kimi-code/test/utils/git/git-status.test.ts
new file mode 100644
index 000000000..fed27dd87
--- /dev/null
+++ b/apps/kimi-code/test/utils/git/git-status.test.ts
@@ -0,0 +1,200 @@
+/* eslint-disable import/first -- vi.mock setup must run before the imports it stubs out. */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  spawnSync: vi.fn(),
+  execFile: vi.fn(),
+}));
+
+vi.mock('node:child_process', () => ({
+  execFile: mocks.execFile,
+  spawnSync: mocks.spawnSync,
+}));
+
+import { createGitStatusCache, formatGitBadge } from '#/utils/git/git-status';
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.clearAllMocks();
+});
+
+describe('git status cache', () => {
+  it('caches branch and status reads until their TTL expires', async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-04-24T00:00:00Z'));
+    mocks.execFile.mockImplementation(
+      (
+        _cmd: string,
+        _args: string[],
+        _options: unknown,
+        callback: (error: Error | null, stdout: string, stderr: string) => void,
+      ) => {
+        callback(new Error('no pull request'), '', '');
+      },
+    );
+    mocks.spawnSync.mockImplementation((_cmd: string, args: string[]) => {
+      if (args.includes('rev-parse')) {
+        return { status: 0, stdout: 'true\n' };
+      }
+      if (args.includes('branch')) {
+        return { status: 0, stdout: 'main\n' };
+      }
+      if (args.includes('status')) {
+        return {
+          status: 0,
+          stdout: '## main...origin/main [ahead 2, behind 1]\n M src/app.ts\n',
+        };
+      }
+      if (args.includes('diff')) {
+        return { status: 0, stdout: '4\t1\tsrc/app.ts\n' };
+      }
+      return { status: 1, stdout: '' };
+    });
+
+    const cache = createGitStatusCache('/tmp/repo');
+
+    expect(cache.getStatus()).toEqual({
+      branch: 'main',
+      dirty: true,
+      ahead: 2,
+      behind: 1,
+      diffAdded: 4,
+      diffDeleted: 1,
+      pullRequest: null,
+    });
+    expect(cache.getStatus()).toEqual({
+      branch: 'main',
+      dirty: true,
+      ahead: 2,
+      behind: 1,
+      diffAdded: 4,
+      diffDeleted: 1,
+      pullRequest: null,
+    });
+    expect(mocks.spawnSync).toHaveBeenCalledTimes(4);
+    expect(mocks.execFile).toHaveBeenCalledTimes(1);
+
+    await Promise.resolve();
+
+    vi.setSystemTime(new Date('2026-04-24T00:00:06Z'));
+    cache.getStatus();
+    expect(mocks.spawnSync).toHaveBeenCalledTimes(5);
+    expect(mocks.execFile).toHaveBeenCalledTimes(1);
+
+    vi.setSystemTime(new Date('2026-04-24T00:00:16Z'));
+    cache.getStatus();
+    expect(mocks.spawnSync).toHaveBeenCalledTimes(8);
+    expect(mocks.execFile).toHaveBeenCalledTimes(1);
+  });
+
+  it('reads uncommitted diff line counts and current pull request metadata', async () => {
+    const onChange = vi.fn();
+    mocks.execFile.mockImplementation(
+      (
+        _cmd: string,
+        _args: string[],
+        _options: unknown,
+        callback: (error: Error | null, stdout: string, stderr: string) => void,
+      ) => {
+        callback(null, '{"number":12,"url":"https://github.com/acme/repo/pull/12"}\n', '');
+      },
+    );
+    mocks.spawnSync.mockImplementation((_cmd: string, args: string[]) => {
+      if (args.includes('rev-parse')) {
+        return { status: 0, stdout: 'true\n' };
+      }
+      if (args.includes('branch')) {
+        return { status: 0, stdout: 'feature/footer\n' };
+      }
+      if (args.includes('status')) {
+        return {
+          status: 0,
+          stdout: '## feature/footer...origin/feature/footer\n M src/app.ts\n',
+        };
+      }
+      if (args.includes('diff')) {
+        return {
+          status: 0,
+          stdout: '10\t3\tsrc/app.ts\n-\t-\timage.png\n0\t5\tdeleted.ts\n',
+        };
+      }
+      return { status: 1, stdout: '' };
+    });
+
+    const cache = createGitStatusCache('/tmp/repo', { onChange });
+    expect(cache.getStatus()).toEqual({
+      branch: 'feature/footer',
+      dirty: true,
+      ahead: 0,
+      behind: 0,
+      diffAdded: 10,
+      diffDeleted: 8,
+      pullRequest: null,
+    });
+
+    await Promise.resolve();
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(cache.getStatus()).toEqual({
+      branch: 'feature/footer',
+      dirty: true,
+      ahead: 0,
+      behind: 0,
+      diffAdded: 10,
+      diffDeleted: 8,
+      pullRequest: {
+        number: 12,
+        url: 'https://github.com/acme/repo/pull/12',
+      },
+    });
+  });
+
+  it('returns null when the working directory is not a git repo and formats badges', () => {
+    mocks.spawnSync.mockReturnValue({ status: 1, stdout: '' });
+    expect(createGitStatusCache('/tmp/not-a-repo').getStatus()).toBeNull();
+    expect(
+      formatGitBadge({
+        branch: 'main',
+        dirty: true,
+        ahead: 2,
+        behind: 1,
+        diffAdded: 12,
+        diffDeleted: 3,
+        pullRequest: null,
+      }),
+    ).toBe('main [+12 -3 ↑2↓1]');
+    expect(
+      formatGitBadge({
+        branch: 'main',
+        dirty: true,
+        ahead: 0,
+        behind: 0,
+        diffAdded: 0,
+        diffDeleted: 0,
+        pullRequest: null,
+      }),
+    ).toBe('main [±]');
+  });
+
+  it('formats pull request badges as terminal hyperlinks when requested', () => {
+    const linked = formatGitBadge(
+      {
+        branch: 'feature/footer',
+        dirty: false,
+        ahead: 0,
+        behind: 0,
+        diffAdded: 0,
+        diffDeleted: 0,
+        pullRequest: {
+          number: 12,
+          url: 'https://github.com/acme/repo/pull/12',
+        },
+      },
+      { linkPullRequest: true },
+    );
+
+    expect(linked).toContain('[PR#12]');
+    expect(linked).toContain('\u001B]8;;https://github.com/acme/repo/pull/12\u0007');
+    expect(linked).toContain('\u001B]8;;\u0007');
+  });
+});
diff --git a/apps/kimi-code/test/utils/history/input-history.test.ts b/apps/kimi-code/test/utils/history/input-history.test.ts
new file mode 100644
index 000000000..43269f3d7
--- /dev/null
+++ b/apps/kimi-code/test/utils/history/input-history.test.ts
@@ -0,0 +1,84 @@
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, it, expect } from 'vitest';
+
+import { loadInputHistory, appendInputHistory } from '#/utils/history/input-history';
+
+let dir: string;
+let file: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'input-history-'));
+  file = join(dir, 'history.jsonl');
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('input-history', () => {
+  it('returns empty when file does not exist', async () => {
+    expect(await loadInputHistory(file)).toEqual([]);
+  });
+
+  it('parses valid jsonl entries in order', async () => {
+    writeFileSync(
+      file,
+      [
+        JSON.stringify({ content: 'first' }),
+        JSON.stringify({ content: 'second' }),
+        '',
+        JSON.stringify({ content: 'third' }),
+      ].join('\n'),
+      'utf-8',
+    );
+    const entries = await loadInputHistory(file);
+    expect(entries).toEqual([{ content: 'first' }, { content: 'second' }, { content: 'third' }]);
+  });
+
+  it('skips malformed lines without aborting the load', async () => {
+    writeFileSync(
+      file,
+      [
+        JSON.stringify({ content: 'good' }),
+        'not json',
+        JSON.stringify({ wrong_field: 'x' }),
+        JSON.stringify({ content: 'tail' }),
+      ].join('\n'),
+      'utf-8',
+    );
+    const entries = await loadInputHistory(file);
+    expect(entries).toEqual([{ content: 'good' }, { content: 'tail' }]);
+  });
+
+  it('appends a new entry and creates the parent directory', async () => {
+    const nested = join(dir, 'nested', 'sub', 'history.jsonl');
+    const written = await appendInputHistory(nested, 'hello');
+    expect(written).toBe(true);
+    const raw = readFileSync(nested, 'utf-8').trim().split('\n');
+    expect(raw).toHaveLength(1);
+    expect(JSON.parse(raw[0]!)).toEqual({ content: 'hello' });
+  });
+
+  it('skips empty / whitespace-only entries', async () => {
+    expect(await appendInputHistory(file, '')).toBe(false);
+    expect(await appendInputHistory(file, '   ')).toBe(false);
+    expect(await loadInputHistory(file)).toEqual([]);
+  });
+
+  it('skips when content equals the previous entry (consecutive dedup)', async () => {
+    expect(await appendInputHistory(file, 'a')).toBe(true);
+    expect(await appendInputHistory(file, 'a', 'a')).toBe(false);
+    expect(await appendInputHistory(file, 'b', 'a')).toBe(true);
+    const entries = await loadInputHistory(file);
+    expect(entries).toEqual([{ content: 'a' }, { content: 'b' }]);
+  });
+
+  it('trims whitespace before persisting', async () => {
+    expect(await appendInputHistory(file, '  hi  ')).toBe(true);
+    const entries = await loadInputHistory(file);
+    expect(entries).toEqual([{ content: 'hi' }]);
+  });
+});
diff --git a/apps/kimi-code/test/utils/image/image-mime.test.ts b/apps/kimi-code/test/utils/image/image-mime.test.ts
new file mode 100644
index 000000000..bcc426bdf
--- /dev/null
+++ b/apps/kimi-code/test/utils/image/image-mime.test.ts
@@ -0,0 +1,98 @@
+import { describe, it, expect } from 'vitest';
+
+import { parseImageMeta } from '#/utils/image/image-mime';
+
+function png(width: number, height: number): Uint8Array {
+  // 8-byte PNG signature + IHDR length (4) + 'IHDR' + width (4 BE) + height (4 BE) + ...
+  const bytes = new Uint8Array(24);
+  bytes.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], 0);
+  // length = 13 (IHDR body)
+  bytes.set([0x00, 0x00, 0x00, 0x0d], 8);
+  bytes.set([0x49, 0x48, 0x44, 0x52], 12); // "IHDR"
+  // width
+  bytes[16] = (width >>> 24) & 0xff;
+  bytes[17] = (width >>> 16) & 0xff;
+  bytes[18] = (width >>> 8) & 0xff;
+  bytes[19] = width & 0xff;
+  // height
+  bytes[20] = (height >>> 24) & 0xff;
+  bytes[21] = (height >>> 16) & 0xff;
+  bytes[22] = (height >>> 8) & 0xff;
+  bytes[23] = height & 0xff;
+  return bytes;
+}
+
+function jpeg(width: number, height: number): Uint8Array {
+  // SOI + SOF0 marker with the minimal segment body.
+  // Layout: FFD8 FFC0 <len16 BE> <precision 08> <height BE> <width BE> <components 03>
+  const body = new Uint8Array([
+    0xff,
+    0xd8, // SOI
+    0xff,
+    0xc0, // SOF0
+    0x00,
+    0x11, // segment length (17 bytes including itself)
+    0x08, // precision
+    (height >> 8) & 0xff,
+    height & 0xff,
+    (width >> 8) & 0xff,
+    width & 0xff,
+    0x03, // components
+    // 3 component spec blocks (3 bytes each) — not parsed but required for realism
+    0x01,
+    0x22,
+    0x00,
+    0x02,
+    0x11,
+    0x01,
+    0x03,
+    0x11,
+    0x01,
+  ]);
+  return body;
+}
+
+function gif(width: number, height: number): Uint8Array {
+  const bytes = new Uint8Array(10);
+  // "GIF89a"
+  bytes.set([0x47, 0x49, 0x46, 0x38, 0x39, 0x61], 0);
+  bytes[6] = width & 0xff;
+  bytes[7] = (width >> 8) & 0xff;
+  bytes[8] = height & 0xff;
+  bytes[9] = (height >> 8) & 0xff;
+  return bytes;
+}
+
+describe('parseImageMeta', () => {
+  it('recognises PNG with correct dimensions', () => {
+    const meta = parseImageMeta(png(640, 480));
+    expect(meta).toEqual({ mime: 'image/png', width: 640, height: 480 });
+  });
+
+  it('recognises JPEG with correct dimensions', () => {
+    const meta = parseImageMeta(jpeg(1280, 720));
+    expect(meta).toEqual({ mime: 'image/jpeg', width: 1280, height: 720 });
+  });
+
+  it('recognises GIF (89a)', () => {
+    const meta = parseImageMeta(gif(100, 200));
+    expect(meta).toEqual({ mime: 'image/gif', width: 100, height: 200 });
+  });
+
+  it('recognises GIF (87a)', () => {
+    const bytes = gif(50, 75);
+    bytes[4] = 0x37; // '7'
+    const meta = parseImageMeta(bytes);
+    expect(meta).toEqual({ mime: 'image/gif', width: 50, height: 75 });
+  });
+
+  it('returns null for non-image bytes', () => {
+    expect(parseImageMeta(new Uint8Array([1, 2, 3, 4]))).toBeNull();
+    expect(parseImageMeta(new Uint8Array([]))).toBeNull();
+  });
+
+  it('returns null for truncated PNG', () => {
+    const full = png(10, 10);
+    expect(parseImageMeta(full.slice(0, 20))).toBeNull();
+  });
+});
diff --git a/apps/kimi-code/test/utils/paths.test.ts b/apps/kimi-code/test/utils/paths.test.ts
new file mode 100644
index 000000000..5c9d3dc03
--- /dev/null
+++ b/apps/kimi-code/test/utils/paths.test.ts
@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { getDataDir, getInputHistoryFile, getLogDir, getUpdateStateFile } from '#/utils/paths';
+
+const originalEnv = { ...process.env };
+
+beforeEach(() => {
+  delete process.env['KIMI_CODE_HOME'];
+});
+
+afterEach(() => {
+  process.env = { ...originalEnv };
+});
+
+describe('getDataDir', () => {
+  it('returns ~/.kimi-code when KIMI_CODE_HOME is not set', () => {
+    expect(getDataDir()).toBe(join(homedir(), '.kimi-code'));
+  });
+
+  it('returns KIMI_CODE_HOME when set', () => {
+    process.env['KIMI_CODE_HOME'] = '/tmp/kimi-test-data';
+    expect(getDataDir()).toBe('/tmp/kimi-test-data');
+  });
+
+  it('returns KIMI_CODE_HOME even if it is a relative path', () => {
+    process.env['KIMI_CODE_HOME'] = 'relative/path';
+    expect(getDataDir()).toBe('relative/path');
+  });
+});
+
+describe('getLogDir', () => {
+  it('returns <dataDir>/logs', () => {
+    expect(getLogDir()).toBe(join(homedir(), '.kimi-code', 'logs'));
+  });
+
+  it('respects KIMI_CODE_HOME', () => {
+    process.env['KIMI_CODE_HOME'] = '/z';
+    expect(getLogDir()).toBe(join('/z', 'logs'));
+  });
+});
+
+describe('getUpdateStateFile', () => {
+  it('returns <dataDir>/updates/latest.json', () => {
+    expect(getUpdateStateFile()).toBe(join(homedir(), '.kimi-code', 'updates', 'latest.json'));
+  });
+
+  it('respects KIMI_CODE_HOME', () => {
+    process.env['KIMI_CODE_HOME'] = '/updates-home';
+    expect(getUpdateStateFile()).toBe(join('/updates-home', 'updates', 'latest.json'));
+  });
+});
+
+describe('getInputHistoryFile', () => {
+  it('returns <dataDir>/user-history/<md5(workDir)>.jsonl', () => {
+    const workDir = '/home/user/project';
+    const hash = createHash('md5').update(workDir, 'utf-8').digest('hex');
+    expect(getInputHistoryFile(workDir)).toBe(
+      join(homedir(), '.kimi-code', 'user-history', `${hash}.jsonl`),
+    );
+  });
+
+  it('respects KIMI_CODE_HOME', () => {
+    process.env['KIMI_CODE_HOME'] = '/custom/data';
+    const hash = createHash('md5').update('/proj', 'utf-8').digest('hex');
+    expect(getInputHistoryFile('/proj')).toBe(
+      join('/custom/data', 'user-history', `${hash}.jsonl`),
+    );
+  });
+});
diff --git a/apps/kimi-code/test/utils/persistence.test.ts b/apps/kimi-code/test/utils/persistence.test.ts
new file mode 100644
index 000000000..9ebe3f55a
--- /dev/null
+++ b/apps/kimi-code/test/utils/persistence.test.ts
@@ -0,0 +1,116 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { z } from 'zod';
+
+import { appendJsonlLine, readJsonFile, readJsonlFile, writeJsonFile } from '#/utils/persistence';
+
+interface TestJson {
+  name: string;
+  count: number;
+}
+
+const TestJsonSchema: z.ZodType<TestJson> = z.object({
+  name: z.string(),
+  count: z.number().int(),
+});
+
+interface TestLine {
+  content: string;
+}
+
+const TestLineSchema: z.ZodType<TestLine> = z.object({
+  content: z.string(),
+});
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'kimi-persistence-'));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('persistence helpers', () => {
+  it('readJsonFile returns fallback when file is missing', async () => {
+    const fallback = { name: 'fallback', count: 1 };
+    await expect(
+      readJsonFile(join(dir, 'missing.json'), TestJsonSchema, fallback),
+    ).resolves.toEqual(fallback);
+  });
+
+  it('writeJsonFile writes schema-valid JSON atomically', async () => {
+    const file = join(dir, 'nested', 'state.json');
+    await writeJsonFile(file, TestJsonSchema, { name: 'ok', count: 2 });
+
+    expect(JSON.parse(readFileSync(file, 'utf-8'))).toEqual({ name: 'ok', count: 2 });
+    await expect(
+      readJsonFile(file, TestJsonSchema, { name: 'fallback', count: 0 }),
+    ).resolves.toEqual({ name: 'ok', count: 2 });
+  });
+
+  it('readJsonFile rejects schema-invalid JSON', async () => {
+    const file = join(dir, 'bad.json');
+    writeFileSync(file, JSON.stringify({ name: 'bad', count: 'nope' }), 'utf-8');
+
+    await expect(
+      readJsonFile(file, TestJsonSchema, { name: 'fallback', count: 0 }),
+    ).rejects.toThrow();
+  });
+
+  it('writeJsonFile refuses to write config.toml', async () => {
+    await expect(
+      writeJsonFile(join(dir, 'config.toml'), TestJsonSchema, { name: 'bad', count: 1 }),
+    ).rejects.toThrow(/config\.toml/);
+  });
+
+  it('readJsonlFile preserves valid line order', async () => {
+    const file = join(dir, 'history.jsonl');
+    writeFileSync(
+      file,
+      [
+        JSON.stringify({ content: 'first' }),
+        JSON.stringify({ content: 'second' }),
+        JSON.stringify({ content: 'third' }),
+      ].join('\n'),
+      'utf-8',
+    );
+
+    await expect(readJsonlFile(file, TestLineSchema)).resolves.toEqual([
+      { content: 'first' },
+      { content: 'second' },
+      { content: 'third' },
+    ]);
+  });
+
+  it('readJsonlFile skips malformed and schema-invalid lines', async () => {
+    const file = join(dir, 'history.jsonl');
+    writeFileSync(
+      file,
+      [
+        JSON.stringify({ content: 'good' }),
+        'not json',
+        JSON.stringify({ wrong: 'shape' }),
+        '',
+        JSON.stringify({ content: 'tail' }),
+      ].join('\n'),
+      'utf-8',
+    );
+
+    await expect(readJsonlFile(file, TestLineSchema)).resolves.toEqual([
+      { content: 'good' },
+      { content: 'tail' },
+    ]);
+  });
+
+  it('appendJsonlLine creates the parent directory', async () => {
+    const file = join(dir, 'nested', 'history.jsonl');
+    await appendJsonlLine(file, TestLineSchema, { content: 'hello' });
+
+    expect(readFileSync(file, 'utf-8').trim()).toBe(JSON.stringify({ content: 'hello' }));
+  });
+});
diff --git a/apps/kimi-code/test/utils/process/external-editor.test.ts b/apps/kimi-code/test/utils/process/external-editor.test.ts
new file mode 100644
index 000000000..3e135d019
--- /dev/null
+++ b/apps/kimi-code/test/utils/process/external-editor.test.ts
@@ -0,0 +1,79 @@
+/* eslint-disable import/first -- vi.mock setup must run before the imports it stubs out. */
+import { EventEmitter } from 'node:events';
+import { writeFile } from 'node:fs/promises';
+import type * as FsPromises from 'node:fs/promises';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  spawn: vi.fn(),
+  rmCalls: vi.fn(),
+}));
+
+vi.mock('node:child_process', () => ({
+  spawn: mocks.spawn,
+}));
+
+vi.mock('node:fs/promises', async () => {
+  const actual = await vi.importActual<typeof FsPromises>('node:fs/promises');
+  return {
+    ...actual,
+    rm: (...args: Parameters<typeof actual.rm>) => {
+      mocks.rmCalls(...args);
+      return actual.rm(...args);
+    },
+  };
+});
+
+import { editInExternalEditor, resolveEditorCommand } from '#/utils/process/external-editor';
+
+function shellPath(cmd: string): string {
+  const match = cmd.match(/'([^']+)'$/);
+  if (!match) throw new Error(`Could not parse temp path from: ${cmd}`);
+  return match[1]!;
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.clearAllMocks();
+});
+
+describe('external-editor helpers', () => {
+  it('prefers configured editor, then VISUAL, then EDITOR', () => {
+    vi.stubEnv('VISUAL', 'nvim');
+    vi.stubEnv('EDITOR', 'vim');
+
+    expect(resolveEditorCommand('code --wait')).toBe('code --wait');
+    expect(resolveEditorCommand(null)).toBe('nvim');
+    vi.stubEnv('VISUAL', '');
+    expect(resolveEditorCommand()).toBe('vim');
+  });
+
+  it('returns the edited contents on success and cleans up the temp directory', async () => {
+    mocks.spawn.mockImplementation((_cmd: string, args: string[]) => {
+      const child = new EventEmitter();
+      void writeFile(shellPath(args[1]!), 'edited text', 'utf8').then(() => {
+        child.emit('exit', 0);
+      });
+      return child as never;
+    });
+
+    await expect(editInExternalEditor('seed', 'code --wait')).resolves.toBe('edited text');
+    expect(mocks.spawn).toHaveBeenCalledWith(
+      '/bin/sh',
+      ['-c', expect.stringMatching(/^code --wait /)],
+      { stdio: 'inherit' },
+    );
+    expect(mocks.rmCalls).toHaveBeenCalled();
+  });
+
+  it('returns undefined when the editor exits non-zero', async () => {
+    mocks.spawn.mockImplementation(() => {
+      const child = new EventEmitter();
+      queueMicrotask(() => child.emit('exit', 1));
+      return child as never;
+    });
+
+    await expect(editInExternalEditor('seed', 'false')).resolves.toBeUndefined();
+  });
+});
diff --git a/apps/kimi-code/test/utils/process/stdin.test.ts b/apps/kimi-code/test/utils/process/stdin.test.ts
new file mode 100644
index 000000000..072c48eb0
--- /dev/null
+++ b/apps/kimi-code/test/utils/process/stdin.test.ts
@@ -0,0 +1,59 @@
+/* eslint-disable import/first -- vi.mock setup must run before the imports it stubs out. */
+import { describe, expect, it, vi, afterEach } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  createInterface: vi.fn(),
+}));
+
+vi.mock('node:readline', () => ({
+  createInterface: mocks.createInterface,
+}));
+
+import { createStdinLineReader, readStdinText } from '#/utils/process/stdin';
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('stdin helpers', () => {
+  it('reads stdin text until end and trims the result', async () => {
+    const listeners = new Map<string, (...args: unknown[]) => void>();
+    const onSpy = vi.spyOn(process.stdin, 'on').mockImplementation(((
+      event: string,
+      handler: (...args: unknown[]) => void,
+    ) => {
+      listeners.set(event, handler);
+      return process.stdin;
+    }) as never);
+    const resumeSpy = vi.spyOn(process.stdin, 'resume').mockImplementation(() => process.stdin);
+
+    const pending = readStdinText();
+    listeners.get('data')?.(Buffer.from(' hello world \n'));
+    listeners.get('end')?.();
+
+    await expect(pending).resolves.toBe('hello world');
+
+    onSpy.mockRestore();
+    resumeSpy.mockRestore();
+  });
+
+  it('yields lines from readline', async () => {
+    mocks.createInterface.mockReturnValue(
+      (async function* () {
+        yield 'one';
+        yield 'two';
+      })(),
+    );
+
+    const lines: string[] = [];
+    for await (const line of createStdinLineReader()) {
+      lines.push(line);
+    }
+
+    expect(lines).toEqual(['one', 'two']);
+    expect(mocks.createInterface).toHaveBeenCalledWith({
+      input: process.stdin,
+      crlfDelay: Infinity,
+    });
+  });
+});
diff --git a/apps/kimi-code/test/utils/usage/usage-format.test.ts b/apps/kimi-code/test/utils/usage/usage-format.test.ts
new file mode 100644
index 000000000..264bb5c55
--- /dev/null
+++ b/apps/kimi-code/test/utils/usage/usage-format.test.ts
@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  formatTokenCount,
+  renderProgressBar,
+  ratioSeverity,
+  safeUsageRatio,
+} from '#/utils/usage/usage-format';
+
+describe('formatTokenCount', () => {
+  it('passes small values through unchanged', () => {
+    expect(formatTokenCount(0)).toBe('0');
+    expect(formatTokenCount(1)).toBe('1');
+    expect(formatTokenCount(999)).toBe('999');
+  });
+
+  it('rounds integers over 1k to 1 decimal', () => {
+    expect(formatTokenCount(1_000)).toBe('1.0k');
+    expect(formatTokenCount(1_234)).toBe('1.2k');
+    expect(formatTokenCount(9_876)).toBe('9.9k');
+  });
+
+  it('switches to M above a million', () => {
+    expect(formatTokenCount(1_000_000)).toBe('1.0M');
+    expect(formatTokenCount(2_500_000)).toBe('2.5M');
+  });
+
+  it('clamps negatives and NaN to 0', () => {
+    expect(formatTokenCount(-1)).toBe('0');
+    expect(formatTokenCount(Number.NaN)).toBe('0');
+    expect(formatTokenCount(Number.POSITIVE_INFINITY)).toBe('0');
+  });
+});
+
+describe('renderProgressBar', () => {
+  it('empty bar at ratio 0', () => {
+    expect(renderProgressBar(0, 10)).toBe('░'.repeat(10));
+  });
+  it('full bar at ratio 1', () => {
+    expect(renderProgressBar(1, 10)).toBe('█'.repeat(10));
+  });
+  it('half bar at ratio 0.5', () => {
+    expect(renderProgressBar(0.5, 10)).toBe('█'.repeat(5) + '░'.repeat(5));
+  });
+  it('clamps ratios outside [0,1]', () => {
+    expect(renderProgressBar(-1, 8)).toBe('░'.repeat(8));
+    expect(renderProgressBar(2, 8)).toBe('█'.repeat(8));
+  });
+  it('coerces NaN to 0', () => {
+    expect(renderProgressBar(Number.NaN, 6)).toBe('░'.repeat(6));
+  });
+});
+
+describe('safeUsageRatio', () => {
+  it('matches footer context usage clamping semantics', () => {
+    expect(safeUsageRatio(Number.NaN)).toBe(0);
+    expect(safeUsageRatio(-1)).toBe(0);
+    expect(safeUsageRatio(0.427)).toBe(0.427);
+    expect(safeUsageRatio(1.5)).toBe(1);
+  });
+});
+
+describe('ratioSeverity', () => {
+  it('green below 0.5', () => {
+    expect(ratioSeverity(0)).toBe('ok');
+    expect(ratioSeverity(0.49)).toBe('ok');
+  });
+  it('yellow in [0.5, 0.85)', () => {
+    expect(ratioSeverity(0.5)).toBe('warn');
+    expect(ratioSeverity(0.7)).toBe('warn');
+    expect(ratioSeverity(0.849)).toBe('warn');
+  });
+  it('red at or above 0.85', () => {
+    expect(ratioSeverity(0.85)).toBe('danger');
+    expect(ratioSeverity(1)).toBe('danger');
+  });
+});
diff --git a/apps/kimi-code/tsconfig.json b/apps/kimi-code/tsconfig.json
new file mode 100644
index 000000000..ea6828176
--- /dev/null
+++ b/apps/kimi-code/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "allowJs": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src", "test", "../../packages/agent-core/src/prompt-modules.d.ts"]
+}
diff --git a/apps/kimi-code/tsdown.config.ts b/apps/kimi-code/tsdown.config.ts
new file mode 100644
index 000000000..93b0659d0
--- /dev/null
+++ b/apps/kimi-code/tsdown.config.ts
@@ -0,0 +1,31 @@
+import { resolve } from 'node:path';
+
+import { defineConfig } from 'tsdown';
+
+import { rawTextPlugin } from '../../build/raw-text-plugin.mjs';
+
+const appRoot = import.meta.dirname;
+
+export default defineConfig({
+  entry: ['./src/main.ts'],
+  format: ['esm'],
+  outDir: 'dist',
+  clean: true,
+  banner: {
+    js: [
+      '#!/usr/bin/env node',
+      "import { fileURLToPath as __cjsShimFileURLToPath } from 'node:url';",
+      "import { dirname as __cjsShimDirname } from 'node:path';",
+      'const __filename = __cjsShimFileURLToPath(import.meta.url);',
+      'const __dirname = __cjsShimDirname(__filename);',
+    ].join('\n'),
+  },
+  plugins: [rawTextPlugin()],
+  alias: {
+    '@': resolve(appRoot, 'src'),
+  },
+  deps: {
+    alwaysBundle: [/^@moonshot-ai\//],
+    neverBundle: [],
+  },
+});
diff --git a/apps/kimi-code/tsdown.native.config.ts b/apps/kimi-code/tsdown.native.config.ts
new file mode 100644
index 000000000..eec94d3ba
--- /dev/null
+++ b/apps/kimi-code/tsdown.native.config.ts
@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import { builtinModules } from 'node:module';
+import { resolve } from 'node:path';
+
+import { defineConfig } from 'tsdown';
+
+import { rawTextPlugin } from '../../build/raw-text-plugin.mjs';
+
+const appRoot = import.meta.dirname;
+const packageJson = JSON.parse(
+  readFileSync(new URL('./package.json', import.meta.url), 'utf-8'),
+) as { version: string };
+
+const builtins = new Set([
+  ...builtinModules,
+  ...builtinModules.map((name) => `node:${name}`),
+]);
+const optionalNativeDependencies = new Set(['cpu-features']);
+
+function shouldAlwaysBundle(id: string): boolean {
+  if (builtins.has(id) || id.startsWith('node:')) return false;
+  if (optionalNativeDependencies.has(id)) return false;
+  return true;
+}
+
+function buildTarget(): string {
+  return process.env['KIMI_CODE_BUILD_TARGET'] ?? `${process.platform}-${process.arch}`;
+}
+
+export default defineConfig({
+  entry: ['./src/main.ts'],
+  format: ['cjs'],
+  outDir: 'dist-native/intermediates',
+  clean: true,
+  dts: false,
+  fixedExtension: true,
+  hash: false,
+  platform: 'node',
+  target: 'node24',
+  banner: { js: '#!/usr/bin/env node' },
+  plugins: [rawTextPlugin()],
+  alias: {
+    '@': resolve(appRoot, 'src'),
+  },
+  define: {
+    __KIMI_CODE_VERSION__: JSON.stringify(packageJson.version),
+    __KIMI_CODE_CHANNEL__: JSON.stringify(process.env['KIMI_CODE_CHANNEL'] ?? ''),
+    __KIMI_CODE_COMMIT__: JSON.stringify(process.env['KIMI_CODE_COMMIT'] ?? ''),
+    __KIMI_CODE_BUILD_TARGET__: JSON.stringify(buildTarget()),
+    __KIMI_CODE_NATIVE_BUNDLE__: 'true',
+  },
+  deps: {
+    alwaysBundle: shouldAlwaysBundle,
+    neverBundle: [...optionalNativeDependencies],
+    onlyBundle: false,
+  },
+  outputOptions: {
+    codeSplitting: false,
+    entryFileNames: 'main.cjs',
+  },
+  checks: {
+    legacyCjs: false,
+  },
+});
diff --git a/apps/kimi-code/vitest.config.ts b/apps/kimi-code/vitest.config.ts
new file mode 100644
index 000000000..49cedd3dd
--- /dev/null
+++ b/apps/kimi-code/vitest.config.ts
@@ -0,0 +1,20 @@
+import { resolve } from 'node:path';
+
+import { defineConfig } from 'vitest/config';
+
+import { rawTextPlugin } from '../../build/raw-text-plugin.mjs';
+
+const appRoot = import.meta.dirname;
+
+export default defineConfig({
+  plugins: [rawTextPlugin()],
+  resolve: {
+    alias: {
+      '@': resolve(appRoot, 'src'),
+    },
+  },
+  test: {
+    name: 'cli',
+    include: ['test/**/*.test.ts', 'test/**/*.test.tsx'],
+  },
+});
diff --git a/apps/vis/package.json b/apps/vis/package.json
new file mode 100644
index 000000000..837569fcb
--- /dev/null
+++ b/apps/vis/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "@moonshot-ai/vis",
+  "version": "0.1.1",
+  "private": true,
+  "description": "Debug visualization tool for kimi-code sessions",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build:deps": "pnpm --filter @moonshot-ai/agent-core... build",
+    "predev": "pnpm run build:deps",
+    "dev": "concurrently -k -n server,web -c cyan,magenta \"pnpm --filter @moonshot-ai/vis-server dev\" \"pnpm --filter @moonshot-ai/vis-web dev\"",
+    "build": "pnpm run build:deps && pnpm --filter @moonshot-ai/vis-server build && pnpm --filter @moonshot-ai/vis-web build && node scripts/copy-web-dist.mjs",
+    "prestart": "pnpm run build",
+    "start": "node server/dist/server.mjs"
+  },
+  "devDependencies": {
+    "concurrently": "^9.1.2"
+  }
+}
diff --git a/apps/vis/scripts/copy-web-dist.mjs b/apps/vis/scripts/copy-web-dist.mjs
new file mode 100644
index 000000000..18978247f
--- /dev/null
+++ b/apps/vis/scripts/copy-web-dist.mjs
@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Copy web/dist/** into server/dist/public/ so the bundled server can serve
+// the SPA out of a single deploy artifact.
+
+import { cp, mkdir, rm, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = join(here, '..');
+const src = join(root, 'web', 'dist');
+const dst = join(root, 'server', 'dist', 'public');
+
+try {
+  await stat(src);
+} catch {
+  process.stderr.write(`[copy-web-dist] source missing: ${src}\n`);
+  process.stderr.write('Did you run `pnpm --filter @moonshot-ai/vis-web build` first?\n');
+  process.exit(1);
+}
+
+await rm(dst, { recursive: true, force: true });
+await mkdir(dirname(dst), { recursive: true });
+await cp(src, dst, { recursive: true });
+
+process.stdout.write(`[copy-web-dist] copied ${src} -> ${dst}\n`);
diff --git a/apps/vis/server/package.json b/apps/vis/server/package.json
new file mode 100644
index 000000000..65232652c
--- /dev/null
+++ b/apps/vis/server/package.json
@@ -0,0 +1,27 @@
+{
+  "name": "@moonshot-ai/vis-server",
+  "version": "0.1.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "imports": {
+    "#/*": [
+      "./src/*.ts",
+      "./src/*/index.ts"
+    ]
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsdown",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.7",
+    "@moonshot-ai/agent-core": "workspace:^",
+    "hono": "^4.7.7"
+  },
+  "devDependencies": {
+    "tsx": "^4.21.0",
+    "vitest": "4.1.4"
+  }
+}
diff --git a/apps/vis/server/src/app.ts b/apps/vis/server/src/app.ts
new file mode 100644
index 000000000..41b9abbc5
--- /dev/null
+++ b/apps/vis/server/src/app.ts
@@ -0,0 +1,138 @@
+import { timingSafeEqual } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import { Hono } from 'hono';
+
+import { contextRoute } from './routes/context';
+import { sessionDetailRoute } from './routes/session-detail';
+import { sessionsRoute } from './routes/sessions';
+import { subagentsRoute } from './routes/subagents';
+import { toolResultsRoute } from './routes/tool-results';
+import { wireRoute } from './routes/wire';
+
+/** Resolve the SPA bundle directory next to the compiled server.mjs, if it
+ * exists. Returns `null` in dev mode where the web bundle lives elsewhere. */
+async function resolvePublicDir(): Promise<string | null> {
+  try {
+    const here = import.meta.dirname;
+    const candidate = resolve(here, 'public');
+    const s = await stat(candidate);
+    if (s.isDirectory()) return candidate;
+  } catch {
+    // not present
+  }
+  return null;
+}
+
+const STATIC_EXT_MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.mjs': 'application/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.map': 'application/json; charset=utf-8',
+};
+
+function mimeFor(path: string): string {
+  const i = path.lastIndexOf('.');
+  if (i < 0) return 'application/octet-stream';
+  const ext = path.slice(i).toLowerCase();
+  return STATIC_EXT_MIME[ext] ?? 'application/octet-stream';
+}
+
+export interface CreateAppOptions {
+  readonly authToken?: string;
+}
+
+function bearerToken(value: string | undefined): string | null {
+  if (value === undefined) return null;
+  const match = /^Bearer\s+(.+)$/i.exec(value);
+  return match?.[1]?.trim() ?? null;
+}
+
+function tokenMatches(actual: string, expected: string): boolean {
+  const actualBytes = Buffer.from(actual);
+  const expectedBytes = Buffer.from(expected);
+  return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
+}
+
+/** Build a Hono app mounting /api/* routes, plus SPA static fallback. */
+export async function createApp(options: CreateAppOptions = {}): Promise<Hono> {
+  const app = new Hono();
+
+  // /api/* handlers.
+  const api = new Hono();
+  const authToken = options.authToken;
+  if (authToken !== undefined && authToken.length > 0) {
+    api.use('*', async (c, next) => {
+      const token = bearerToken(c.req.header('authorization'));
+      if (token !== null && tokenMatches(token, authToken)) {
+        await next();
+        return;
+      }
+      c.header('www-authenticate', 'Bearer realm="kimi-vis"');
+      return c.json({ error: 'unauthorized', code: 'UNAUTHORIZED' }, 401);
+    });
+  }
+  api.route('/sessions', sessionsRoute());
+  api.route('/sessions', sessionDetailRoute());
+  api.route('/sessions', wireRoute());
+  api.route('/sessions', contextRoute());
+  api.route('/sessions', subagentsRoute());
+  api.route('/sessions', toolResultsRoute());
+
+  app.route('/api', api);
+
+  // Static + SPA fallback (production only).
+  const publicDir = await resolvePublicDir();
+  if (publicDir !== null) {
+    app.get('*', async (c) => {
+      const url = new URL(c.req.url);
+      let pathname = decodeURIComponent(url.pathname);
+      if (pathname.startsWith('/api')) {
+        // Should have been routed above; 404 here.
+        return c.json({ error: `api route not found: ${pathname}`, code: 'NOT_FOUND' }, 404);
+      }
+      if (pathname === '/' || pathname === '') pathname = '/index.html';
+      const resolved = resolve(publicDir, `.${pathname}`);
+      if (!resolved.startsWith(publicDir)) {
+        return c.text('forbidden', 403);
+      }
+      try {
+        const s = await stat(resolved);
+        if (s.isFile()) {
+          const buf = await readFile(resolved);
+          const body = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+          return new Response(body, {
+            headers: { 'content-type': mimeFor(resolved) },
+          });
+        }
+      } catch {
+        // fall through to SPA fallback
+      }
+      // SPA fallback — index.html for any unknown GET so client-side
+      // React Router can resolve the route.
+      try {
+        const indexHtml = await readFile(join(publicDir, 'index.html'));
+        const body = new Uint8Array(indexHtml.buffer, indexHtml.byteOffset, indexHtml.byteLength);
+        return new Response(body, {
+          headers: { 'content-type': 'text/html; charset=utf-8' },
+        });
+      } catch {
+        return c.text('not found', 404);
+      }
+    });
+  }
+
+  return app;
+}
diff --git a/apps/vis/server/src/config.ts b/apps/vis/server/src/config.ts
new file mode 100644
index 000000000..7c9421c14
--- /dev/null
+++ b/apps/vis/server/src/config.ts
@@ -0,0 +1,156 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** Resolve KIMI_CODE_HOME (env > ~/.kimi-code). */
+function resolveKimiCodeHome(): string {
+  const envHome = process.env['KIMI_CODE_HOME'];
+  if (envHome !== undefined && envHome.length > 0) {
+    return envHome;
+  }
+  return join(homedir(), '.kimi-code');
+}
+
+/** HTTP port for the vis API server. */
+export function resolvePort(): number {
+  const raw = process.env['PORT'];
+  if (raw !== undefined && raw.length > 0) {
+    const n = Number.parseInt(raw, 10);
+    if (Number.isFinite(n) && n > 0 && n < 65536) {
+      return n;
+    }
+  }
+  return 3001;
+}
+
+/** HTTP host for the vis API server. Defaults to loopback. */
+export function resolveHost(): string {
+  const raw = process.env['VIS_HOST'] ?? process.env['HOST'];
+  const host = raw?.trim();
+  return host !== undefined && host.length > 0 ? host : '127.0.0.1';
+}
+
+export function isLoopbackHost(host: string): boolean {
+  const normalized = host.trim().toLowerCase().replaceAll('[', '').replaceAll(']', '');
+  return (
+    normalized === 'localhost' ||
+    normalized === '::1' ||
+    normalized === '0:0:0:0:0:0:0:1' ||
+    normalized.startsWith('127.')
+  );
+}
+
+export function resolveVisAuthToken(host: string = resolveHost()): string | undefined {
+  const raw = process.env['VIS_AUTH_TOKEN'];
+  const token = raw?.trim();
+  if (token !== undefined && token.length > 0) return token;
+  if (!isLoopbackHost(host)) {
+    throw new Error(
+      `VIS_AUTH_TOKEN is required when binding vis-server outside loopback (host=${host})`,
+    );
+  }
+  return undefined;
+}
+
+export const KIMI_CODE_HOME: string = resolveKimiCodeHome();
+
+export class VisPathConfig {
+  readonly sessionsDir: string;
+
+  constructor(readonly home: string) {
+    this.sessionsDir = join(home, 'sessions');
+  }
+
+  sessionDir(sessionId: string): string {
+    return (
+      this.findIndexedSessionDir(sessionId) ??
+      this.findNestedSessionDir(sessionId) ??
+      join(this.sessionsDir, sessionId)
+    );
+  }
+
+  statePath(sessionId: string): string {
+    return join(this.sessionDir(sessionId), 'state.json');
+  }
+
+  mainAgentDir(sessionId: string): string {
+    const sessionDir = this.sessionDir(sessionId);
+    const mainDir = join(sessionDir, 'agents', 'main');
+    return isDirectory(mainDir) ? mainDir : sessionDir;
+  }
+
+  wirePath(sessionId: string): string {
+    return join(this.mainAgentDir(sessionId), 'wire.jsonl');
+  }
+
+  subagentDir(sessionId: string, agentId: string): string {
+    const sessionDir = this.sessionDir(sessionId);
+    const agentDir = join(sessionDir, 'agents', agentId);
+    return isDirectory(agentDir) ? agentDir : join(sessionDir, 'subagents', agentId);
+  }
+
+  toolResultArchivePath(sessionId: string, toolCallId: string): string {
+    const sessionDir = this.sessionDir(sessionId);
+    const mainPath = join(sessionDir, 'agents', 'main', 'tool-results', `${toolCallId}.txt`);
+    return existsSync(mainPath) ? mainPath : join(sessionDir, 'tool-results', `${toolCallId}.txt`);
+  }
+
+  private findIndexedSessionDir(sessionId: string): string | null {
+    const indexPath = join(this.home, 'session_index.jsonl');
+    let raw: string;
+    try {
+      raw = readFileSync(indexPath, 'utf8');
+    } catch {
+      return null;
+    }
+    for (const line of raw.split(/\r?\n/)) {
+      if (line.trim().length === 0) continue;
+      try {
+        const parsed = JSON.parse(line) as {
+          sessionId?: unknown;
+          session_id?: unknown;
+          sessionDir?: unknown;
+          session_dir?: unknown;
+        };
+        const id = stringValue(parsed.sessionId) ?? stringValue(parsed.session_id);
+        if (id !== sessionId) continue;
+        const dir = stringValue(parsed.sessionDir) ?? stringValue(parsed.session_dir);
+        if (dir !== null && isDirectory(dir)) return dir;
+      } catch {
+        // Ignore malformed index lines.
+      }
+    }
+    return null;
+  }
+
+  private findNestedSessionDir(sessionId: string): string | null {
+    const direct = join(this.sessionsDir, sessionId);
+    if (isDirectory(direct)) return direct;
+    let entries: string[];
+    try {
+      entries = readdirSync(this.sessionsDir);
+    } catch {
+      return null;
+    }
+    for (const entry of entries) {
+      const candidate = join(this.sessionsDir, entry, sessionId);
+      if (isDirectory(candidate)) return candidate;
+    }
+    return null;
+  }
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Singleton path config pinned to the resolved KIMI_CODE_HOME. */
+export const pathConfig = new VisPathConfig(KIMI_CODE_HOME);
diff --git a/apps/vis/server/src/index.ts b/apps/vis/server/src/index.ts
new file mode 100644
index 000000000..e97d6603a
--- /dev/null
+++ b/apps/vis/server/src/index.ts
@@ -0,0 +1,32 @@
+import { serve } from '@hono/node-server';
+
+import { createApp } from './app';
+import { KIMI_CODE_HOME, resolveHost, resolvePort, resolveVisAuthToken } from './config';
+import { formatStartupBanner } from './startup-banner';
+
+async function main(): Promise<void> {
+  const host = resolveHost();
+  const authToken = resolveVisAuthToken(host);
+  const app = await createApp({ authToken });
+  const port = resolvePort();
+  serve({ fetch: app.fetch, hostname: host, port }, (info) => {
+    // Startup banner.
+    process.stdout.write(
+      formatStartupBanner({
+        authToken,
+        host,
+        kimiCodeHome: KIMI_CODE_HOME,
+        port: info.port,
+      }),
+    );
+  });
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  process.stderr.write(
+    `[vis-server] fatal: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`,
+  );
+  process.exit(1);
+}
diff --git a/apps/vis/server/src/lib/context-builder.ts b/apps/vis/server/src/lib/context-builder.ts
new file mode 100644
index 000000000..b31df2023
--- /dev/null
+++ b/apps/vis/server/src/lib/context-builder.ts
@@ -0,0 +1,500 @@
+import type {
+  AnnotatedMessage,
+  ContentPart,
+  NotificationRecord,
+  ProjectedStateSummary,
+  SessionInitializedRecord,
+  SessionState,
+  ToolCallEntry,
+  UserInputPart,
+  VisWireRecord,
+} from './types';
+
+const PERSISTED_OUTPUT_RE = /^<persisted-output path="([^"]+)">/;
+
+/**
+ * Extract the on-disk path from a `<persisted-output path="...">` marker
+ * at the start of a tool-result output. Returns null when no marker is
+ * present.
+ */
+export function extractPersistedOutputPath(text: string): string | null {
+  const m = PERSISTED_OUTPUT_RE.exec(text.trimStart());
+  return m?.[1] ?? null;
+}
+
+/**
+ * Render a notification's `data` payload as the XML string that the live
+ * ContextMemory would inject as a user-role message.
+ */
+export function renderNotificationXml(data: NotificationRecord['data']): string {
+  const id = escAttr(data.id);
+  const category = escAttr(data.category);
+  const type = escAttr(data.type);
+  const sourceKind = escAttr(data.source_kind);
+  const sourceId = escAttr(data.source_id);
+  const title = data.title;
+  const severity = data.severity;
+  const body = data.body;
+
+  const lines: string[] = [
+    `<notification id="${id}" category="${category}" type="${type}" source_kind="${sourceKind}" source_id="${sourceId}">`,
+  ];
+  if (title.length > 0) lines.push(`Title: ${title}`);
+  if (severity.length > 0) lines.push(`Severity: ${severity}`);
+  if (body.length > 0) lines.push(body);
+
+  // background_task notifications append a <task-notification> block
+  // with the last 20 lines / 3000 chars of tail_output, matching what
+  // the live projector would emit.
+  if (data.source_kind === 'background_task') {
+    const tail = (data as { tail_output?: string }).tail_output ?? '';
+    if (tail.length > 0) {
+      const tailLines = tail.split('\n');
+      const trimmed = (tailLines.length > 20 ? tailLines.slice(-20) : tailLines)
+        .join('\n')
+        .slice(-3000);
+      lines.push('<task-notification>', trimmed, '</task-notification>');
+    }
+  }
+
+  lines.push('</notification>');
+  return lines.join('\n');
+}
+
+function escAttr(s: string): string {
+  if (s.length === 0) return 'unknown';
+  return s.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
+}
+
+export interface BuildAnnotatedOptions {
+  /** When true (default), rewind-orphaned records are kept with `out_of_context: true`. */
+  preserveOutOfContext?: boolean;
+}
+
+/**
+ * Walk `records` in order and emit an `AnnotatedMessage[]` that includes
+ * notification and system_reminder synthetic user messages. Tracks a
+ * numeric turn counter so `context_edit operation:'rewind' to_turn:N`
+ * can flag later messages as out-of-context.
+ */
+export function buildAnnotatedMessages(
+  records: readonly VisWireRecord[],
+  options?: BuildAnnotatedOptions,
+): AnnotatedMessage[] {
+  const preserveOutOfContext = options?.preserveOutOfContext ?? true;
+
+  // Track (messageIndex -> turnCounterAtEmission) so a rewind can mark
+  // later emissions as out_of_context.
+  let annotated: AnnotatedMessage[] = [];
+  const msgTurnIdx: number[] = [];
+
+  let turnCounter = 0;
+
+  // An assistant message is not a single record — it's coalesced from
+  // `step_begin → (content_part|tool_call)* → step_end` atoms anchored
+  // by `step_uuid`. We buffer the in-flight step here and emit a
+  // synthetic assistant message on step_end.
+  interface StepBuffer {
+    seq: number;
+    step_uuid: string;
+    text: string;
+    think: string;
+    think_encrypted?: string | undefined;
+    tool_calls: ToolCallEntry[];
+  }
+  let currentStep: StepBuffer | null = null;
+
+  const flushStep = (): void => {
+    if (currentStep === null) return;
+    const s = currentStep;
+    const content: ContentPart[] = [];
+    if (s.think.length > 0) {
+      const part: ContentPart = { type: 'think', think: s.think };
+      if (s.think_encrypted !== undefined) part['encrypted'] = s.think_encrypted;
+      content.push(part);
+    }
+    if (s.text.length > 0) content.push({ type: 'text', text: s.text });
+    if (content.length > 0 || s.tool_calls.length > 0) {
+      pushMsg({
+        seq: s.seq,
+        message: { role: 'assistant', content, tool_calls: s.tool_calls },
+        origin: { kind: 'assistant' },
+        is_ephemeral: false,
+        out_of_context: false,
+      });
+    }
+    currentStep = null;
+  };
+
+  const pushMsg = (m: AnnotatedMessage): void => {
+    annotated.push(m);
+    msgTurnIdx.push(turnCounter);
+  };
+
+  for (const r of records) {
+    switch (r.type) {
+      case 'turn_begin': {
+        // Close any dangling step so turn boundaries stay clean.
+        flushStep();
+        turnCounter += 1;
+        break;
+      }
+
+      case 'user_message': {
+        const text = userContentToText(r.content);
+        pushMsg({
+          seq: r.seq,
+          message: {
+            role: 'user',
+            content: [{ type: 'text', text }],
+            tool_calls: [],
+          },
+          origin: { kind: 'user' },
+          is_ephemeral: false,
+          out_of_context: false,
+        });
+        break;
+      }
+
+      case 'step_begin': {
+        // Any prior unclosed step gets flushed; protocol guarantees order
+        // step_begin → … → step_end, but crashes can leave orphans.
+        flushStep();
+        currentStep = {
+          seq: r.seq,
+          step_uuid: r.uuid,
+          text: '',
+          think: '',
+          tool_calls: [],
+        };
+        break;
+      }
+
+      case 'content_part': {
+        if (currentStep === null) break;
+        if (currentStep.step_uuid !== r.step_uuid) break;
+        if (r.part.kind === 'text') {
+          currentStep.text += r.part.text;
+        } else {
+          currentStep.think += r.part.think;
+          if (r.part.encrypted !== undefined) {
+            currentStep.think_encrypted = r.part.encrypted;
+          }
+        }
+        break;
+      }
+
+      case 'tool_call': {
+        if (currentStep === null) break;
+        if (currentStep.step_uuid !== r.step_uuid) break;
+        currentStep.tool_calls.push({
+          type: 'function',
+          id: r.data.tool_call_id,
+          function: {
+            name: r.data.tool_name,
+            arguments: r.data.args === undefined ? null : JSON.stringify(r.data.args),
+          },
+        });
+        break;
+      }
+
+      case 'step_end': {
+        // step_end may carry usage; we drop it here since the annotated
+        // message already represents what the LLM emitted. Usage lives
+        // on the wire record itself for the Wire tab to show.
+        flushStep();
+        break;
+      }
+
+      case 'tool_result': {
+        const text = typeof r.output === 'string' ? r.output : JSON.stringify(r.output);
+        const msg: AnnotatedMessage = {
+          seq: r.seq,
+          message: {
+            role: 'tool',
+            content: [{ type: 'text', text }],
+            tool_calls: [],
+            tool_call_id: r.tool_call_id,
+          },
+          origin: { kind: 'tool', tool_call_id: r.tool_call_id },
+          is_ephemeral: false,
+          out_of_context: false,
+        };
+        if (typeof r.output === 'string') {
+          const persistedPath = extractPersistedOutputPath(r.output);
+          if (persistedPath !== null) {
+            msg.persisted_output_path = persistedPath;
+          }
+        }
+        pushMsg(msg);
+        break;
+      }
+
+      case 'system_reminder': {
+        const text = `<system-reminder>\n${r.content}\n</system-reminder>`;
+        pushMsg({
+          seq: r.seq,
+          message: { role: 'user', content: [{ type: 'text', text }], tool_calls: [] },
+          origin: { kind: 'system_reminder', seq: r.seq },
+          is_ephemeral: true,
+          out_of_context: false,
+        });
+        break;
+      }
+
+      case 'notification': {
+        if (!isLlmVisibleNotification(r)) break;
+        const text = renderNotificationXml(r.data);
+        pushMsg({
+          seq: r.seq,
+          message: { role: 'user', content: [{ type: 'text', text }], tool_calls: [] },
+          origin: {
+            kind: 'notification',
+            seq: r.seq,
+            notification_id: r.data.id,
+            severity: r.data.severity,
+          },
+          is_ephemeral: true,
+          out_of_context: false,
+        });
+        break;
+      }
+
+      case 'compaction': {
+        // Wholesale replacement. Drops any open step buffer — atoms
+        // before compaction are superseded by the summary.
+        currentStep = null;
+        annotated = [];
+        msgTurnIdx.length = 0;
+        pushMsg({
+          seq: r.seq,
+          message: {
+            role: 'assistant',
+            content: [{ type: 'text', text: r.summary }],
+            tool_calls: [],
+          },
+          origin: { kind: 'assistant' },
+          is_ephemeral: false,
+          out_of_context: false,
+        });
+        break;
+      }
+
+      case 'context_cleared': {
+        currentStep = null;
+        annotated = [];
+        msgTurnIdx.length = 0;
+        break;
+      }
+
+      case 'context_edit': {
+        if (r.operation === 'rewind' && typeof r.to_turn === 'number') {
+          const toTurn = r.to_turn;
+          if (preserveOutOfContext) {
+            for (let i = 0; i < annotated.length; i += 1) {
+              const emittedAtTurn = msgTurnIdx[i] ?? 0;
+              if (emittedAtTurn > toTurn) {
+                // Replace with a marked copy (immutability not required but
+                // makes the "after rewind" behaviour obvious to readers).
+                const m = annotated[i];
+                if (m !== undefined) {
+                  annotated[i] = { ...m, out_of_context: true };
+                }
+              }
+            }
+          } else {
+            // Drop messages emitted in turns past `to_turn`.
+            const keep: AnnotatedMessage[] = [];
+            const keepTurns: number[] = [];
+            for (let i = 0; i < annotated.length; i += 1) {
+              const emittedAtTurn = msgTurnIdx[i] ?? 0;
+              if (emittedAtTurn <= toTurn) {
+                const m = annotated[i];
+                if (m !== undefined) {
+                  keep.push(m);
+                  keepTurns.push(emittedAtTurn);
+                }
+              }
+            }
+            annotated = keep;
+            msgTurnIdx.length = 0;
+            msgTurnIdx.push(...keepTurns);
+          }
+        }
+        break;
+      }
+
+      case 'approval_request':
+      case 'approval_response':
+      case 'metadata':
+      case 'ownership_changed':
+      case 'session_initialized':
+      case 'skill_completed':
+      case 'skill_invoked':
+      case 'subagent_completed':
+      case 'subagent_failed':
+      case 'subagent_spawned':
+      case 'system_prompt_changed':
+      case 'team_mail':
+      case 'tool_denied':
+      case 'tools_changed':
+      case 'turn_end':
+        break;
+
+      default:
+        break;
+    }
+  }
+
+  // Flush any trailing open step (session ended mid-step).
+  flushStep();
+
+  return annotated;
+}
+
+function userContentToText(content: string | readonly UserInputPart[]): string {
+  if (typeof content === 'string') return content;
+  return content
+    .map((p) => {
+      if (p.type === 'text') return p.text;
+      if (p.type === 'image_url') return `<image url="${p.image_url.url}">`;
+      return `<video url="${p.video_url.url}">`;
+    })
+    .join('');
+}
+
+function isLlmVisibleNotification(r: NotificationRecord): boolean {
+  const targets = r.data.targets;
+  if (!targets.includes('llm')) return false;
+  // Optimistic: an absent `delivered_at` means a legacy record from before
+  // delivery tracking was added (delivery actually happened); a value of
+  // `0` means the LLM sink was intentionally skipped.
+  const deliveredAt = r.data.delivered_at;
+  if (deliveredAt === undefined) return true;
+  return deliveredAt.llm !== 0;
+}
+
+/**
+ * Build the projected-state summary by walking the wire records locally.
+ * Only the config-class state is materialized (model, system prompt,
+ * active tools, permission/plan mode, last seq, token totals).
+ */
+export function buildProjectedStateSummary(
+  records: readonly VisWireRecord[],
+  sessionInitialized: SessionInitializedRecord | null,
+  state?: SessionState | null,
+): ProjectedStateSummary {
+  const baseline =
+    sessionInitialized ??
+    ({
+      type: 'session_initialized',
+      seq: 0,
+      time: 0,
+      agent_type: 'main',
+      session_id: state?.session_id ?? 'unknown',
+      system_prompt: '',
+      active_tools: [],
+      model: state?.model,
+      permission_mode: state?.permission_mode,
+      plan_mode: state?.plan_mode,
+      workspace_dir: state?.workspace_dir,
+    } satisfies SessionInitializedRecord);
+  const breakdown = sumTokenBreakdown(records);
+  const projected = projectStateLocally(records, baseline, state);
+  return {
+    model: projected.model,
+    system_prompt: projected.system_prompt,
+    active_tools: projected.active_tools,
+    last_seq: projected.last_seq,
+    token_count: breakdown.input_tokens + breakdown.output_tokens,
+    permission_mode: projected.permission_mode,
+    plan_mode: projected.plan_mode,
+    ...breakdown,
+  };
+}
+
+function projectStateLocally(
+  records: readonly VisWireRecord[],
+  sessionInitialized: SessionInitializedRecord,
+  state?: SessionState | null,
+): Pick<
+  ProjectedStateSummary,
+  'model' | 'system_prompt' | 'active_tools' | 'last_seq' | 'permission_mode' | 'plan_mode'
+> {
+  let systemPrompt: string | null = sessionInitialized.system_prompt;
+  let activeTools = [...sessionInitialized.active_tools];
+  let model: string | null = state?.model ?? sessionInitialized.model ?? null;
+  let permissionMode: string | null = sessionInitialized.permission_mode ?? null;
+  let planMode = sessionInitialized.plan_mode ?? false;
+  let lastSeq = sessionInitialized.seq;
+  for (const record of records) {
+    lastSeq = Math.max(lastSeq, record.seq ?? 0);
+    if (record.type === 'system_prompt_changed') {
+      systemPrompt = record.new_prompt;
+    } else if (record.type === 'tools_changed') {
+      activeTools = [...record.tools];
+    } else if (record.type === 'notification') {
+      const payload = record.data.payload;
+      if (record.data.type === 'config.update' && isRecord(payload)) {
+        model = configModel(payload) ?? model;
+      } else if (record.data.type === 'permission.update' && isRecord(payload)) {
+        permissionMode = stringValue(payload['mode']) ?? permissionMode;
+      }
+    }
+  }
+  return {
+    model,
+    system_prompt: systemPrompt,
+    active_tools: activeTools,
+    last_seq: lastSeq,
+    permission_mode: state?.permission_mode ?? permissionMode,
+    plan_mode: state?.plan_mode ?? planMode,
+  };
+}
+
+function configModel(payload: Record<string, unknown>): string | null {
+  const alias = stringValue(payload['modelAlias']);
+  if (alias !== null) return alias;
+  const provider = payload['provider'];
+  if (isRecord(provider)) return stringValue(provider['model']);
+  return null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+/** Sum `step_end.usage` across all records. Mirrors the core projector's
+ *  tokenCount logic (step-level) so partial/running turns are still counted
+ *  — turn_end.usage is the turn total but it arrives only after the turn
+ *  closes, so step_end sums stay responsive on live sessions. */
+function sumTokenBreakdown(records: readonly VisWireRecord[]): {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_write_tokens: number;
+} {
+  let input = 0;
+  let output = 0;
+  let cacheRead = 0;
+  let cacheWrite = 0;
+  for (const r of records) {
+    if (r.type !== 'step_end') continue;
+    const usage = (r as { usage?: Record<string, number | undefined> }).usage;
+    if (usage === undefined) continue;
+    input += usage['input_tokens'] ?? 0;
+    output += usage['output_tokens'] ?? 0;
+    cacheRead += usage['cache_read_tokens'] ?? 0;
+    cacheWrite += usage['cache_write_tokens'] ?? 0;
+  }
+  return {
+    input_tokens: input,
+    output_tokens: output,
+    cache_read_tokens: cacheRead,
+    cache_write_tokens: cacheWrite,
+  };
+}
diff --git a/apps/vis/server/src/lib/session-delete.ts b/apps/vis/server/src/lib/session-delete.ts
new file mode 100644
index 000000000..c6e6010c6
--- /dev/null
+++ b/apps/vis/server/src/lib/session-delete.ts
@@ -0,0 +1,50 @@
+import { rm, stat } from 'node:fs/promises';
+import { basename, isAbsolute, relative, resolve } from 'node:path';
+
+import { pathConfig } from '../config';
+import { listSessions } from './session-lister';
+import type { ClearSessionsResponse, DeleteSessionResponse } from './types';
+
+export const SESSION_ID_RE = /^session_[a-zA-Z0-9_-]+$/;
+
+function isInside(root: string, target: string): boolean {
+  const rel = relative(root, target);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+function resolveSafeSessionDir(sessionId: string): string {
+  const sessionsRoot = resolve(pathConfig.sessionsDir);
+  const sessionDir = resolve(pathConfig.sessionDir(sessionId));
+  if (!isInside(sessionsRoot, sessionDir) || basename(sessionDir) !== sessionId) {
+    throw new Error(`refusing to delete unsafe session path: ${sessionDir}`);
+  }
+  return sessionDir;
+}
+
+export async function deleteSession(sessionId: string): Promise<DeleteSessionResponse | null> {
+  const sessionDir = resolveSafeSessionDir(sessionId);
+  const info = await stat(sessionDir).catch(() => null);
+  if (info?.isDirectory() !== true) return null;
+  await rm(sessionDir, { recursive: true, force: true });
+  return { session_id: sessionId, deleted: true };
+}
+
+export async function clearSessions(): Promise<ClearSessionsResponse> {
+  const sessions = await listSessions(pathConfig.sessionsDir);
+  const failed: ClearSessionsResponse['failed'] = [];
+  let deleted_count = 0;
+
+  for (const session of sessions) {
+    try {
+      const result = await deleteSession(session.session_id);
+      if (result?.deleted === true) deleted_count += 1;
+    } catch (error) {
+      failed.push({
+        session_id: session.session_id,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return { deleted_count, failed };
+}
diff --git a/apps/vis/server/src/lib/session-lister.ts b/apps/vis/server/src/lib/session-lister.ts
new file mode 100644
index 000000000..c07ec2e96
--- /dev/null
+++ b/apps/vis/server/src/lib/session-lister.ts
@@ -0,0 +1,196 @@
+import { createReadStream } from 'node:fs';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+
+import type { SessionState, SessionSummary, WireFileMetadata } from './types';
+import { readSessionLastPrompt, readSessionTitle } from './session-title';
+
+const ARCHIVE_RE = /^wire\.\d+\.jsonl$/;
+const SESSION_ID_RE = /^session_[a-zA-Z0-9_-]+$/;
+
+/** Count NDJSON body lines (excluding metadata header) without loading the
+ * full file into memory. Returns `null` if the file is unreadable. */
+async function countWireBodyLines(wirePath: string): Promise<{
+  count: number;
+  metadata: WireFileMetadata | null;
+} | null> {
+  try {
+    const stream = createReadStream(wirePath, { encoding: 'utf8' });
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+
+    let headerConsumed = false;
+    let count = 0;
+    let metadata: WireFileMetadata | null = null;
+
+    for await (const line of rl) {
+      if (line.length === 0) continue;
+      if (!headerConsumed) {
+        headerConsumed = true;
+        try {
+          const parsed = JSON.parse(line) as unknown;
+          if (
+            typeof parsed === 'object' &&
+            parsed !== null &&
+            (parsed as { type?: unknown }).type === 'metadata'
+          ) {
+            metadata = parsed as WireFileMetadata;
+          }
+        } catch {
+          // first line malformed — session is broken, not missing
+        }
+        continue;
+      }
+      count += 1;
+    }
+    return { count, metadata };
+  } catch {
+    return null;
+  }
+}
+
+async function readStateJson(statePath: string): Promise<SessionState | null> {
+  try {
+    const raw = await readFile(statePath, 'utf8');
+    return JSON.parse(raw) as SessionState;
+  } catch {
+    return null;
+  }
+}
+
+async function countSubagents(sessionDir: string): Promise<number> {
+  const agentCount = await countAgentSubagents(sessionDir);
+  if (agentCount > 0) return agentCount;
+  try {
+    const entries = await readdir(join(sessionDir, 'subagents'), { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).length;
+  } catch {
+    return 0;
+  }
+}
+
+async function countAgentSubagents(sessionDir: string): Promise<number> {
+  try {
+    const entries = await readdir(join(sessionDir, 'agents'), { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory() && e.name !== 'main').length;
+  } catch {
+    return 0;
+  }
+}
+
+async function resolveMainAgentDir(sessionDir: string): Promise<string> {
+  const mainDir = join(sessionDir, 'agents', 'main');
+  const info = await stat(mainDir).catch(() => null);
+  return info?.isDirectory() === true ? mainDir : sessionDir;
+}
+
+async function countArchives(sessionDir: string): Promise<number> {
+  try {
+    const entries = await readdir(sessionDir);
+    return entries.filter((e) => ARCHIVE_RE.test(e)).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Build a `SessionSummary` from a single session directory. Malformed
+ * state.json / missing wire.jsonl yield health markers rather than errors.
+ */
+export async function loadSessionSummary(sessionDir: string): Promise<SessionSummary> {
+  const sessionId = sessionDir.split('/').pop() ?? sessionDir;
+  const statePath = join(sessionDir, 'state.json');
+  const mainAgentDir = await resolveMainAgentDir(sessionDir);
+  const wirePath = join(mainAgentDir, 'wire.jsonl');
+
+  const state = await readStateJson(statePath);
+  const wireStat = await stat(wirePath).catch(() => null);
+  const wireInfo = wireStat === null ? null : await countWireBodyLines(wirePath);
+  const subagent_count = await countSubagents(sessionDir);
+  const archive_count = await countArchives(mainAgentDir);
+
+  let health: SessionSummary['health'];
+  if (wireStat === null) {
+    health = 'missing_wire';
+  } else if (wireInfo === null) {
+    health = 'broken';
+  } else if (state === null) {
+    // state.json missing / unreadable — still usable, flag as broken.
+    health = 'broken';
+  } else {
+    health = 'ok';
+  }
+
+  return {
+    session_id: state?.session_id ?? sessionId,
+    title: readSessionTitle(state),
+    last_prompt: readSessionLastPrompt(state),
+    created_at: state?.created_at ?? 0,
+    updated_at: state?.updated_at ?? 0,
+    last_turn_time: state?.last_turn_time ?? null,
+    model: state?.model ?? null,
+    permission_mode: state?.permission_mode ?? null,
+    last_exit_code: state?.last_exit_code ?? null,
+    custom_title: state?.custom_title ?? null,
+    tags: state?.tags ?? [],
+    archived: state?.archived ?? false,
+    workspace_dir: state?.workspace_dir ?? null,
+    wire_protocol_version: wireInfo?.metadata?.protocol_version ?? null,
+    wire_record_count: wireInfo?.count ?? 0,
+    archive_count,
+    subagent_count,
+    health,
+  };
+}
+
+/**
+ * Enumerate sessions under `sessionsDir`. Current dev stores sessions under a
+ * workdir bucket (`sessions/<workdir-key>/<sessionId>`), while older fixtures
+ * may still be direct `sessions/<sessionId>` directories.
+ */
+export async function listSessions(sessionsDir: string): Promise<SessionSummary[]> {
+  const candidates: string[] = [];
+  let entries: string[];
+  try {
+    entries = await readdir(sessionsDir);
+  } catch {
+    return [];
+  }
+  for (const entry of entries) {
+    const sessionDir = join(sessionsDir, entry);
+    const s = await stat(sessionDir).catch(() => null);
+    if (s?.isDirectory() !== true) continue;
+    if (SESSION_ID_RE.test(entry)) {
+      candidates.push(sessionDir);
+      continue;
+    }
+    let children: string[];
+    try {
+      children = await readdir(sessionDir);
+    } catch {
+      continue;
+    }
+    for (const child of children) {
+      if (!SESSION_ID_RE.test(child)) continue;
+      const childDir = join(sessionDir, child);
+      const childStat = await stat(childDir).catch(() => null);
+      if (childStat?.isDirectory() === true) candidates.push(childDir);
+    }
+  }
+
+  // Cheap pre-filter on state.json producer before doing any wire I/O.
+  const keep = await Promise.all(
+    candidates.map(async (dir) => {
+      const state = await readStateJson(join(dir, 'state.json'));
+      if (state === null) return null;
+      return state.producer?.kind === 'python' ? null : dir;
+    }),
+  );
+
+  const summaries = await Promise.all(
+    keep.filter((d): d is string => d !== null).map((dir) => loadSessionSummary(dir)),
+  );
+
+  summaries.sort((a, b) => b.updated_at - a.updated_at);
+  return summaries;
+}
diff --git a/apps/vis/server/src/lib/session-title.ts b/apps/vis/server/src/lib/session-title.ts
new file mode 100644
index 000000000..bd06a903b
--- /dev/null
+++ b/apps/vis/server/src/lib/session-title.ts
@@ -0,0 +1,25 @@
+import type { SessionState } from './types';
+
+function titleString(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function readSessionTitle(state: SessionState | null | undefined): string | null {
+  if (state === null || state === undefined) return null;
+  if (typeof state.isCustomTitle === 'boolean') {
+    const title = titleString(state.title);
+    if (title !== null) return title;
+  }
+  return (
+    titleString(state.customTitle) ??
+    titleString(state.custom_title) ??
+    titleString(state.title)
+  );
+}
+
+export function readSessionLastPrompt(state: SessionState | null | undefined): string | null {
+  if (state === null || state === undefined) return null;
+  return titleString(state.lastPrompt) ?? titleString(state.last_prompt);
+}
diff --git a/apps/vis/server/src/lib/subagent-loader.ts b/apps/vis/server/src/lib/subagent-loader.ts
new file mode 100644
index 000000000..84b316084
--- /dev/null
+++ b/apps/vis/server/src/lib/subagent-loader.ts
@@ -0,0 +1,213 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import type {
+  SubagentCompletedRecord,
+  SubagentFailedRecord,
+  SubagentNode,
+  SubagentSpawnedRecord,
+  VisWireRecord,
+} from './types';
+import { loadWireRecords } from './wire-loader';
+
+interface LifecyclePair {
+  spawned: SubagentSpawnedRecord;
+  completed: SubagentCompletedRecord | null;
+  failed: SubagentFailedRecord | null;
+}
+
+/** Directly list subagent ids for a session (only names, no tree build). */
+export async function listSubagents(sessionDir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(join(sessionDir, 'agents'));
+    const out: string[] = [];
+    for (const e of entries) {
+      if (e === 'main') continue;
+      const s = await stat(join(sessionDir, 'agents', e)).catch(() => null);
+      if (s?.isDirectory()) out.push(e);
+    }
+    if (out.length > 0) return out;
+  } catch {
+    // Fall back to legacy subagents/ below.
+  }
+  try {
+    const entries = await readdir(join(sessionDir, 'subagents'));
+    const out: string[] = [];
+    for (const e of entries) {
+      const s = await stat(join(sessionDir, 'subagents', e)).catch(() => null);
+      if (s?.isDirectory()) out.push(e);
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+function extractLifecycleRecords(records: readonly VisWireRecord[]): Map<string, LifecyclePair> {
+  const map = new Map<string, LifecyclePair>();
+  for (const r of records) {
+    if (r.type === 'subagent_spawned') {
+      const existing = map.get(r.data.agent_id);
+      if (existing === undefined) {
+        map.set(r.data.agent_id, { spawned: r, completed: null, failed: null });
+      } else {
+        existing.spawned = r;
+      }
+    } else if (r.type === 'subagent_completed') {
+      const existing = map.get(r.data.agent_id);
+      if (existing === undefined) {
+        // Rare: completion without spawn in this wire — create skeleton.
+        const fakeSpawn: SubagentSpawnedRecord = {
+          type: 'subagent_spawned',
+          seq: 0,
+          time: 0,
+          data: {
+            agent_id: r.data.agent_id,
+            parent_tool_call_id: r.data.parent_tool_call_id,
+            run_in_background: false,
+          },
+        };
+        map.set(r.data.agent_id, { spawned: fakeSpawn, completed: r, failed: null });
+      } else {
+        existing.completed = r;
+      }
+    } else if (r.type === 'subagent_failed') {
+      const existing = map.get(r.data.agent_id);
+      if (existing === undefined) {
+        const fakeSpawn: SubagentSpawnedRecord = {
+          type: 'subagent_spawned',
+          seq: 0,
+          time: 0,
+          data: {
+            agent_id: r.data.agent_id,
+            parent_tool_call_id: r.data.parent_tool_call_id,
+            run_in_background: false,
+          },
+        };
+        map.set(r.data.agent_id, { spawned: fakeSpawn, completed: null, failed: r });
+      } else {
+        existing.failed = r;
+      }
+    }
+  }
+  return map;
+}
+
+async function readSubagentMeta(
+  sessionDir: string,
+  agentId: string,
+): Promise<{ subagent_type: string | null; status: string | null }> {
+  try {
+    const raw = await readFile(join(await resolveSubagentDir(sessionDir, agentId), 'meta.json'), 'utf8');
+    const parsed = JSON.parse(raw) as { subagent_type?: unknown; status?: unknown };
+    return {
+      subagent_type: typeof parsed.subagent_type === 'string' ? parsed.subagent_type : null,
+      status: typeof parsed.status === 'string' ? parsed.status : null,
+    };
+  } catch {
+    return { subagent_type: null, status: null };
+  }
+}
+
+async function resolveSubagentDir(sessionDir: string, agentId: string): Promise<string> {
+  const agentDir = join(sessionDir, 'agents', agentId);
+  const agentStat = await stat(agentDir).catch(() => null);
+  return agentStat?.isDirectory() === true ? agentDir : join(sessionDir, 'subagents', agentId);
+}
+
+function deriveStatus(pair: LifecyclePair, metaStatus: string | null): SubagentNode['status'] {
+  if (pair.failed !== null) return 'failed';
+  if (pair.completed !== null) return 'completed';
+  if (metaStatus !== null) {
+    const allowed: ReadonlyArray<SubagentNode['status']> = [
+      'running',
+      'completed',
+      'failed',
+      'killed',
+      'lost',
+    ];
+    if ((allowed as string[]).includes(metaStatus)) {
+      return metaStatus as SubagentNode['status'];
+    }
+  }
+  return 'unknown';
+}
+
+/**
+ * Build the subagent tree for a session, recursing into each subagent's
+ * wire.jsonl to discover nested spawns. Depth-capped at `maxDepth`
+ * (default 5) to prevent runaway recursion on corrupt fixtures.
+ */
+export async function buildSubagentTree(
+  sessionDir: string,
+  mainWireRecords: readonly VisWireRecord[],
+  maxDepth = 5,
+): Promise<SubagentNode[]> {
+  const visited = new Set<string>();
+
+  async function buildLevel(
+    records: readonly VisWireRecord[],
+    depth: number,
+    parentAgentId: string | null,
+  ): Promise<SubagentNode[]> {
+    if (depth > maxDepth) return [];
+    const pairs = extractLifecycleRecords(records);
+
+    // Reserve all agentIds at this level synchronously so parallel recursion
+    // cannot re-visit a cousin branch's already-claimed agent.
+    const toProcess: Array<[string, LifecyclePair]> = [];
+    for (const [agentId, pair] of pairs) {
+      if (visited.has(agentId)) continue;
+      visited.add(agentId);
+      toProcess.push([agentId, pair]);
+    }
+
+    const nodes = await Promise.all(
+      toProcess.map(async ([agentId, pair]): Promise<SubagentNode> => {
+        const meta = await readSubagentMeta(sessionDir, agentId);
+        let children: SubagentNode[] = [];
+        const subDir = await resolveSubagentDir(sessionDir, agentId);
+        const dirStat = await stat(subDir).catch(() => null);
+        if (dirStat?.isDirectory() && depth < maxDepth) {
+          try {
+            const sub = await loadWireRecords(subDir);
+            children = await buildLevel(sub.records, depth + 1, agentId);
+          } catch {
+            // ignore — leave children empty
+          }
+        }
+
+        const status = deriveStatus(pair, meta.status);
+        let success: boolean | null;
+        if (pair.completed !== null) success = true;
+        else if (pair.failed !== null) success = false;
+        else success = null;
+
+        const resolvedParent =
+          pair.spawned.data.parent_agent_id ?? parentAgentId;
+
+        return {
+          agent_id: agentId,
+          agent_name: pair.spawned.data.agent_name ?? null,
+          subagent_type: meta.subagent_type,
+          run_in_background: pair.spawned.data.run_in_background,
+          parent_agent_id: resolvedParent,
+          depth,
+          status,
+          success,
+          result_summary: pair.completed?.data.result_summary ?? null,
+          error: pair.failed?.data.error ?? null,
+          spawn_seq: pair.spawned.seq,
+          spawn_time: pair.spawned.time,
+          children,
+        };
+      }),
+    );
+
+    // Sort deterministically — earliest spawn first.
+    nodes.sort((a, b) => a.spawn_seq - b.spawn_seq);
+    return nodes;
+  }
+
+  return buildLevel(mainWireRecords, 0, null);
+}
diff --git a/apps/vis/server/src/lib/types.ts b/apps/vis/server/src/lib/types.ts
new file mode 100644
index 000000000..90a0149e2
--- /dev/null
+++ b/apps/vis/server/src/lib/types.ts
@@ -0,0 +1,725 @@
+// Vis-local mirror of the core WireRecord interfaces. Copied so the
+// `VisWireRecord` union stays structurally equal to the core `WireRecord`
+// union; the sole cast lives in `lib/wire-loader.ts` and is safe because
+// these interfaces are field-for-field compatible.
+//
+// Plus the vis-specific response types consumed by `server/src/routes/*`
+// and the `web/` SPA.
+
+// ── Supporting types (subset of core helpers) ────────────────────────────
+
+export interface TextPart {
+  type: 'text';
+  text: string;
+}
+export interface ImageURLPart {
+  type: 'image_url';
+  image_url: { url: string };
+}
+export interface VideoURLPart {
+  type: 'video_url';
+  video_url: { url: string };
+}
+export type UserInputPart = TextPart | ImageURLPart | VideoURLPart;
+
+export interface TokenUsage {
+  input: number;
+  output: number;
+  cache_read?: number | undefined;
+  cache_write?: number | undefined;
+}
+
+// ── File metadata header ────────────────────────────────────────────────
+
+export interface WireFileMetadata {
+  type: 'metadata';
+  protocol_version: string;
+  created_at: number;
+  kimi_version?: string | undefined;
+  /** Implementation that wrote the wire file. Present on TS-native sessions. */
+  producer?: WireProducer | undefined;
+}
+
+/** Implementation that wrote the wire file (Python migration vs native TS). */
+export interface WireProducer {
+  kind: 'python' | 'typescript';
+  name: string;
+  version: string;
+}
+
+// ── Vis-synthetic timeline records ─────────────────────────────────────
+// `replayWire()` strips the file header (line 1) and session_initialized
+// (line 2) out of `records[]` and exposes them separately. To make the
+// Wire tab show EVERYTHING that lives in wire.jsonl, we splice them back
+// in as synthetic timeline records, with `seq`/`time` synthesised where
+// the on-disk record lacks them.
+
+export interface MetadataRecord {
+  type: 'metadata';
+  /** Synthetic: 0 (placed just before session_initialized). */
+  seq: number;
+  /** Synthetic: mirrors `created_at`. */
+  time: number;
+  protocol_version: string;
+  created_at: number;
+  kimi_version?: string | undefined;
+  producer?: WireProducer | undefined;
+  /** Vis-only: which wire file this header came from (useful across archives). */
+  file_name?: string | undefined;
+}
+
+// ── session_initialized ───────────────────────────────────────────────
+// Line 2 of every TS-native wire.jsonl. Carries startup baseline that
+// the projector reads as authoritative — extracted by replayWire out of
+// `records[]` onto `ReplayResult.sessionInitialized`.
+
+interface SessionInitializedCommonFields {
+  type: 'session_initialized';
+  seq: number;
+  time: number;
+  system_prompt: string;
+  active_tools: string[];
+  model?: string | undefined;
+  permission_mode?: 'default' | 'acceptEdits' | 'bypassPermissions' | undefined;
+  plan_mode?: boolean | undefined;
+  workspace_dir?: string | undefined;
+  thinking_level?: string | undefined;
+}
+
+export interface SessionInitializedMainRecord extends SessionInitializedCommonFields {
+  agent_type: 'main';
+  session_id: string;
+}
+
+export interface SessionInitializedSubRecord extends SessionInitializedCommonFields {
+  agent_type: 'sub';
+  agent_id: string;
+  agent_name?: string | undefined;
+  parent_session_id: string;
+  parent_agent_id?: string | undefined;
+  parent_tool_call_id: string;
+  run_in_background: boolean;
+}
+
+export interface SessionInitializedIndependentRecord extends SessionInitializedCommonFields {
+  agent_type: 'independent';
+  agent_id: string;
+  agent_name?: string | undefined;
+}
+
+export type SessionInitializedRecord =
+  | SessionInitializedMainRecord
+  | SessionInitializedSubRecord
+  | SessionInitializedIndependentRecord;
+
+// ── Record branches ──────────────────────────────────────────────────
+
+export interface TurnBeginRecord {
+  type: 'turn_begin';
+  seq: number;
+  time: number;
+  turn_id: string;
+  agent_type: 'main' | 'sub' | 'independent';
+  user_input?: string | undefined;
+  input_kind: 'user' | 'system_trigger';
+  trigger_source?: string | undefined;
+}
+
+export interface TurnEndRecord {
+  type: 'turn_end';
+  seq: number;
+  time: number;
+  turn_id: string;
+  agent_type: 'main' | 'sub' | 'independent';
+  success: boolean;
+  reason: 'done' | 'cancelled' | 'error' | 'interrupted';
+  usage?:
+    | {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens?: number | undefined;
+        cache_write_tokens?: number | undefined;
+        cost_usd?: number | undefined;
+      }
+    | undefined;
+  synthetic?: boolean | undefined;
+}
+
+export interface UserMessageRecord {
+  type: 'user_message';
+  seq: number;
+  time: number;
+  turn_id: string;
+  content: string | readonly UserInputPart[];
+  uuid?: string | undefined;
+}
+
+// ── Atomic streaming records (replaces assistant_message) ─────────────
+// Each LLM step is a sequence: step_begin → (content_part|tool_call)* → step_end.
+// An "assistant message" is reconstructed by coalescing these atoms by step_uuid.
+
+export interface StepBeginRecord {
+  type: 'step_begin';
+  seq: number;
+  time: number;
+  /** Unique id for this step (anchor for its content_part / tool_call atoms). */
+  uuid: string;
+  turn_id: string;
+  step: number;
+}
+
+export interface StepEndRecord {
+  type: 'step_end';
+  seq: number;
+  time: number;
+  uuid: string;
+  turn_id: string;
+  step: number;
+  usage?:
+    | {
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens?: number | undefined;
+        cache_write_tokens?: number | undefined;
+      }
+    | undefined;
+  finish_reason?: string | undefined;
+}
+
+export interface ContentPartRecord {
+  type: 'content_part';
+  seq: number;
+  time: number;
+  uuid: string;
+  turn_id: string;
+  step: number;
+  /** Anchors to the step_begin.uuid that opened this step. */
+  step_uuid: string;
+  role: 'assistant';
+  /** Inner key is `kind` (not `type`) to avoid outer-union collision. */
+  part:
+    | { kind: 'text'; text: string }
+    | { kind: 'think'; think: string; encrypted?: string | undefined };
+}
+
+export interface ToolResultRecord {
+  type: 'tool_result';
+  seq: number;
+  time: number;
+  turn_id: string;
+  tool_call_id: string;
+  output: unknown;
+  is_error?: boolean | undefined;
+  synthetic?: boolean | undefined;
+  uuid?: string | undefined;
+  parent_uuid?: string | undefined;
+}
+
+export interface CompactionRecord {
+  type: 'compaction';
+  seq: number;
+  time: number;
+  summary: string;
+  pre_compact_tokens: number;
+  post_compact_tokens: number;
+  uuid?: string | undefined;
+}
+
+export interface SystemPromptChangedRecord {
+  type: 'system_prompt_changed';
+  seq: number;
+  time: number;
+  new_prompt: string;
+}
+
+export interface ToolsChangedRecord {
+  type: 'tools_changed';
+  seq: number;
+  time: number;
+  operation: 'register' | 'remove' | 'set_active';
+  tools: string[];
+}
+
+export interface SystemReminderRecord {
+  type: 'system_reminder';
+  seq: number;
+  time: number;
+  content: string;
+  consumed_at_turn?: number | undefined;
+}
+
+export interface NotificationRecord {
+  type: 'notification';
+  seq: number;
+  time: number;
+  data: {
+    id: string;
+    category: 'task' | 'agent' | 'system' | 'team';
+    type: string;
+    source_kind: string;
+    source_id: string;
+    title: string;
+    body: string;
+    severity: 'info' | 'success' | 'warning' | 'error';
+    payload?: Record<string, unknown> | undefined;
+    targets: Array<'llm' | 'wire' | 'shell'>;
+    dedupe_key?: string | undefined;
+    delivered_at?:
+      | {
+          llm?: number | undefined;
+          wire?: number | undefined;
+          shell?: number | undefined;
+        }
+      | undefined;
+    envelope_id?: string | undefined;
+    // background_task notifications attach streamed tail output that the
+    // live projector renders into a <task-notification> block.
+    tail_output?: string | undefined;
+  };
+}
+
+// First-class tool-call record (was once telemetry-only under a different name).
+export interface ToolCallRecord {
+  type: 'tool_call';
+  seq: number;
+  time: number;
+  uuid: string;
+  turn_id: string;
+  step: number;
+  /** Anchors to the step_begin.uuid that opened this step. */
+  step_uuid: string;
+  data: {
+    tool_call_id: string;
+    tool_name: string;
+    args: unknown;
+    description?: string | undefined;
+    display?: ApprovalDisplay;
+  };
+}
+
+export interface ToolDeniedRecord {
+  type: 'tool_denied';
+  seq: number;
+  time: number;
+  turn_id: string;
+  step: number;
+  data: {
+    tool_call_id: string;
+    tool_name: string;
+    rule_id: string;
+    reason: string;
+  };
+}
+
+export type McpApprovalReason = 'elicitation' | 'auth' | 'tool_call';
+
+export type ApprovalSource =
+  | { kind: 'loop'; agent_id: string }
+  | { kind: 'subagent'; agent_id: string; subagent_type?: string | undefined }
+  | { kind: 'turn'; turn_id: string }
+  | { kind: 'session'; session_id: string }
+  | { kind: 'mcp'; server_id: string; reason: McpApprovalReason };
+
+// `ApprovalDisplay` is `ToolInputDisplay` in core. We intentionally keep the
+// shape opaque here — vis only passes it through to the UI.
+export type ApprovalDisplay = unknown;
+
+export type SkillInvocationTrigger = 'user-slash' | 'model-tool' | 'nested-skill';
+
+export interface SkillInvokedRecord {
+  type: 'skill_invoked';
+  seq: number;
+  time: number;
+  turn_id: string;
+  agent_type?: 'main' | 'sub' | 'independent' | undefined;
+  data: {
+    skill_name: string;
+    execution_mode: 'inline' | 'fork';
+    original_input: string;
+    sub_agent_id?: string | undefined;
+    invocation_trigger?: SkillInvocationTrigger | undefined;
+    query_depth?: number | undefined;
+  };
+}
+
+export interface SkillCompletedRecord {
+  type: 'skill_completed';
+  seq: number;
+  time: number;
+  turn_id: string;
+  agent_type?: 'main' | 'sub' | 'independent' | undefined;
+  data: {
+    skill_name: string;
+    execution_mode: 'inline' | 'fork';
+    success: boolean;
+    error?: string | undefined;
+    sub_agent_id?: string | undefined;
+    invocation_trigger?: SkillInvocationTrigger | undefined;
+    query_depth?: number | undefined;
+  };
+}
+
+export interface ApprovalRequestRecord {
+  type: 'approval_request';
+  seq: number;
+  time: number;
+  turn_id: string;
+  step: number;
+  data: {
+    request_id: string;
+    tool_call_id: string;
+    tool_name: string;
+    action: string;
+    display: ApprovalDisplay;
+    source: ApprovalSource;
+  };
+}
+
+export interface ApprovalResponseRecord {
+  type: 'approval_response';
+  seq: number;
+  time: number;
+  turn_id: string;
+  step: number;
+  data: {
+    request_id: string;
+    response: 'approved' | 'rejected' | 'cancelled';
+    feedback?: string | undefined;
+    selected_label?: string | undefined;
+    synthetic?: boolean | undefined;
+  };
+}
+
+export interface TeamMailRecord {
+  type: 'team_mail';
+  seq: number;
+  time: number;
+  data: {
+    mail_id: string;
+    reply_to?: string | undefined;
+    from_agent: string;
+    to_agent: string;
+    content: string;
+    summary?: string | undefined;
+  };
+}
+
+export interface SubagentSpawnedRecord {
+  type: 'subagent_spawned';
+  seq: number;
+  time: number;
+  uuid?: string | undefined;
+  data: {
+    agent_id: string;
+    agent_name?: string | undefined;
+    parent_tool_call_id: string;
+    parent_agent_id?: string | undefined;
+    parent_tool_call_uuid?: string | undefined;
+    run_in_background: boolean;
+  };
+}
+
+export interface SubagentCompletedRecord {
+  type: 'subagent_completed';
+  seq: number;
+  time: number;
+  uuid?: string | undefined;
+  parent_uuid?: string | undefined;
+  data: {
+    agent_id: string;
+    parent_tool_call_id: string;
+    result_summary: string;
+    usage?: TokenUsage | undefined;
+  };
+}
+
+export interface SubagentFailedRecord {
+  type: 'subagent_failed';
+  seq: number;
+  time: number;
+  uuid?: string | undefined;
+  parent_uuid?: string | undefined;
+  data: {
+    agent_id: string;
+    parent_tool_call_id: string;
+    error: string;
+  };
+}
+
+export interface OwnershipChangedRecord {
+  type: 'ownership_changed';
+  seq: number;
+  time: number;
+  old_owner: string | null;
+  new_owner: string;
+}
+
+export interface ContextEditRecord {
+  type: 'context_edit';
+  seq: number;
+  time: number;
+  operation: 'edit_message' | 'delete_message' | 'rewind' | 'insert_message' | 'replace_message';
+  target_seq?: number | undefined;
+  to_turn?: number | undefined;
+  after_seq?: number | undefined;
+  new_content?: string | undefined;
+  new_role?: 'user' | 'assistant' | 'system' | undefined;
+  cascade?: boolean | undefined;
+}
+
+export interface ContextClearedRecord {
+  type: 'context_cleared';
+  seq: number;
+  time: number;
+}
+
+// ── Union ─────────────────────────────────────────────────────────────
+
+export type VisWireRecord =
+  | MetadataRecord
+  | SessionInitializedRecord
+  | TurnBeginRecord
+  | TurnEndRecord
+  | UserMessageRecord
+  | ToolResultRecord
+  | CompactionRecord
+  | SystemPromptChangedRecord
+  | ToolsChangedRecord
+  | SystemReminderRecord
+  | NotificationRecord
+  | StepBeginRecord
+  | StepEndRecord
+  | ContentPartRecord
+  | ToolCallRecord
+  | ToolDeniedRecord
+  | SkillInvokedRecord
+  | SkillCompletedRecord
+  | ApprovalRequestRecord
+  | ApprovalResponseRecord
+  | TeamMailRecord
+  | SubagentSpawnedRecord
+  | SubagentCompletedRecord
+  | SubagentFailedRecord
+  | OwnershipChangedRecord
+  | ContextEditRecord
+  | ContextClearedRecord;
+
+// ── Vis-specific response types ─────────────────────────────────────────
+
+export interface ApiError {
+  error: string;
+  code:
+    | 'NOT_FOUND'
+    | 'BAD_REQUEST'
+    | 'UNAUTHORIZED'
+    | 'READ_ERROR'
+    | 'PARSE_ERROR'
+    | 'DELETE_ERROR';
+}
+
+export interface DeleteSessionResponse {
+  session_id: string;
+  deleted: true;
+}
+
+export interface ClearSessionsResponse {
+  deleted_count: number;
+  failed: Array<{ session_id: string; error: string }>;
+}
+
+export interface SessionState {
+  session_id: string;
+  title?: string;
+  isCustomTitle?: boolean;
+  customTitle?: string;
+  lastPrompt?: string;
+  last_prompt?: string;
+  model?: string;
+  last_turn_id?: string;
+  last_turn_time?: number;
+  turn_count?: number;
+  created_at: number;
+  updated_at: number;
+  workspace_dir?: string;
+  auto_approve_actions?: string[];
+  permission_mode?: 'default' | 'acceptEdits' | 'bypassPermissions';
+  thinking_level?: string;
+  custom_title?: string;
+  plan_mode?: boolean;
+  plan_slug?: string;
+  tags?: string[];
+  description?: string;
+  archived?: boolean;
+  color?: string;
+  last_exit_code?: 'clean' | 'dirty';
+  /** Implementation that wrote this session. Vis only surfaces sessions
+   *  with `kind === 'typescript'`. */
+  producer?: WireProducer;
+}
+
+export interface SessionSummary {
+  session_id: string;
+  title: string | null;
+  last_prompt: string | null;
+  created_at: number;
+  updated_at: number;
+  last_turn_time: number | null;
+  model: string | null;
+  permission_mode: string | null;
+  last_exit_code: 'clean' | 'dirty' | null;
+  custom_title: string | null;
+  tags: string[];
+  archived: boolean;
+  workspace_dir: string | null;
+  wire_protocol_version: string | null;
+  wire_record_count: number;
+  archive_count: number;
+  subagent_count: number;
+  health: 'ok' | 'broken' | 'missing_wire';
+}
+
+export interface SessionDetail {
+  session_id: string;
+  title: string | null;
+  last_prompt: string | null;
+  state: SessionState;
+  subagent_ids: string[];
+  archive_files: string[];
+  tool_result_ids: string[];
+  wire_metadata: WireFileMetadata | null;
+}
+
+export interface WireResponse {
+  session_id: string;
+  agent_id: string | null;
+  files_read: string[];
+  health: 'ok' | 'broken';
+  broken_reason?: string;
+  warnings: string[];
+  records: VisWireRecord[];
+}
+
+export interface ContentPart {
+  type: 'text' | 'think' | 'image_url' | 'video_url';
+  [key: string]: unknown;
+}
+
+export interface ToolCallEntry {
+  type: 'function';
+  id: string;
+  function: { name: string; arguments: string | null };
+}
+
+export type MessageOrigin =
+  | { kind: 'user' }
+  | { kind: 'assistant' }
+  | { kind: 'tool'; tool_call_id: string }
+  | { kind: 'system_reminder'; seq: number }
+  | { kind: 'notification'; seq: number; notification_id: string; severity: string };
+
+export interface AnnotatedMessage {
+  seq: number;
+  message: {
+    role: 'user' | 'assistant' | 'tool';
+    content: ContentPart[];
+    tool_calls: ToolCallEntry[];
+    tool_call_id?: string;
+  };
+  origin: MessageOrigin;
+  is_ephemeral: boolean;
+  out_of_context: boolean;
+  persisted_output_path?: string;
+}
+
+export interface ProjectedStateSummary {
+  model: string | null;
+  system_prompt: string | null;
+  active_tools: string[];
+  last_seq: number;
+  token_count: number;
+  permission_mode: string | null;
+  plan_mode: boolean;
+  /** Token breakdown, summed from every `step_end.usage` in the session.
+   *  Provides the 4-segment bar shown at the top of the Context tab.
+   *  Zero when no step_ends have been observed (e.g. pre-protocol session). */
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_write_tokens: number;
+}
+
+export interface ContextResponse {
+  session_id: string;
+  agent_id: string | null;
+  annotated_messages: AnnotatedMessage[];
+  projected_state: ProjectedStateSummary;
+}
+
+export interface SubagentNode {
+  agent_id: string;
+  agent_name: string | null;
+  subagent_type: string | null;
+  run_in_background: boolean;
+  parent_agent_id: string | null;
+  depth: number;
+  status: 'running' | 'completed' | 'failed' | 'killed' | 'lost' | 'unknown';
+  success: boolean | null;
+  result_summary: string | null;
+  error: string | null;
+  spawn_seq: number;
+  spawn_time: number;
+  children: SubagentNode[];
+}
+
+export interface SubagentTreeResponse {
+  session_id: string;
+  tree: SubagentNode[];
+}
+
+export interface SubagentMetaResponse {
+  agent_id: string;
+  session_id: string;
+  meta_json: {
+    agent_id: string;
+    subagent_type: string;
+    status: string;
+    description: string;
+    parent_tool_call_id: string;
+    created_at: number;
+    updated_at: number;
+  } | null;
+  spawned_record: {
+    agent_name?: string;
+    parent_tool_call_id: string;
+    parent_agent_id?: string;
+    run_in_background: boolean;
+    seq: number;
+    time: number;
+  } | null;
+  completed_record: {
+    parent_tool_call_id: string;
+    result_summary: string;
+    usage?: {
+      input_tokens: number;
+      output_tokens: number;
+      cache_read_tokens?: number;
+      cache_write_tokens?: number;
+    };
+    seq: number;
+    time: number;
+  } | null;
+  failed_record: {
+    parent_tool_call_id: string;
+    error: string;
+    seq: number;
+    time: number;
+  } | null;
+  depth: number;
+}
+
+export interface ToolResultFileResponse {
+  tool_call_id: string;
+  session_id: string;
+  size_bytes: number;
+  content: string;
+}
diff --git a/apps/vis/server/src/lib/wire-loader.ts b/apps/vis/server/src/lib/wire-loader.ts
new file mode 100644
index 000000000..3f29eaf54
--- /dev/null
+++ b/apps/vis/server/src/lib/wire-loader.ts
@@ -0,0 +1,179 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+import type {
+  MetadataRecord,
+  SessionInitializedRecord,
+  VisWireRecord,
+  WireFileMetadata,
+} from './types';
+import { replayWire } from './wire-replay';
+
+const ARCHIVE_RE = /^wire\.(\d+)\.jsonl$/;
+
+export interface WireLoadResult {
+  records: VisWireRecord[];
+  /** session_initialized from the newest wire file's line 2.
+   *  `null` when the session predates the line-2 header convention or
+   *  the file lacks a `session_initialized` line. */
+  session_initialized: SessionInitializedRecord | null;
+  health: 'ok' | 'broken';
+  broken_reason?: string;
+  warnings: string[];
+  files_read: string[];
+}
+
+/**
+ * Enumerate all wire files in `agentDir` (archives first, ascending by N;
+ * then current `wire.jsonl`). Re-implemented locally because the
+ * corresponding helper inside `@moonshot-ai/agent-core` is not exported.
+ */
+export async function listWireFilesManually(agentDir: string): Promise<string[]> {
+  const wireDir = await resolveWireDir(agentDir);
+  let entries: string[];
+  try {
+    entries = await readdir(wireDir);
+  } catch {
+    return [];
+  }
+
+  const archives: { path: string; n: number }[] = [];
+  let current: string | null = null;
+  for (const entry of entries) {
+    if (entry === 'wire.jsonl') {
+      current = join(wireDir, entry);
+      continue;
+    }
+    const m = ARCHIVE_RE.exec(entry);
+    if (m?.[1] !== undefined) {
+      archives.push({ path: join(wireDir, entry), n: Number.parseInt(m[1], 10) });
+    }
+  }
+  archives.sort((a, b) => a.n - b.n);
+  const out = archives.map((a) => a.path);
+  if (current !== null) {
+    out.push(current);
+  }
+  return out;
+}
+
+async function resolveWireDir(agentDir: string): Promise<string> {
+  const mainDir = join(agentDir, 'agents', 'main');
+  try {
+    const entries = await readdir(mainDir);
+    if (entries.includes('wire.jsonl')) return mainDir;
+  } catch {
+    // `agentDir` is already an agent dir or has no main agent.
+  }
+  return agentDir;
+}
+
+/**
+ * Load all wire records for an agent (main or subagent) in age order.
+ *
+ * Calls `replayWire()` per file and concatenates — core only exports the
+ * single-file replay primitive, so multi-file replay is composed here.
+ *
+ * The cast to `VisWireRecord[]` is the sole trust boundary in vis. Safe
+ * because the vis mirror types are field-for-field identical to the core
+ * `WireRecord` union and `replayWire()` only emits validated records.
+ */
+export async function loadWireRecords(agentDir: string): Promise<WireLoadResult> {
+  const files = await listWireFilesManually(agentDir);
+
+  if (files.length === 0) {
+    return {
+      records: [],
+      session_initialized: null,
+      health: 'broken',
+      broken_reason: `no wire files found under ${agentDir}`,
+      warnings: [],
+      files_read: [],
+    };
+  }
+
+  const records: VisWireRecord[] = [];
+  const warnings: string[] = [];
+  let overallHealth: 'ok' | 'broken' = 'ok';
+  let brokenReason: string | undefined;
+  const filesRead: string[] = [];
+  // session_initialized is the line-2 truth source. Keep the most-recent
+  // (current wire's) value, not archive values, so post-compaction the
+  // live model/prompt is reflected.
+  let sessionInitialized: SessionInitializedRecord | null = null;
+
+  for (const filePath of files) {
+    try {
+      const result = await replayWire(filePath);
+      filesRead.push(filePath);
+      const fileMeta = await readMetadataLine(filePath);
+      const init = result.sessionInitialized;
+      // Splice the two wire.jsonl header lines back into the timeline so
+      // the Wire tab shows EVERYTHING in the file (including system_prompt).
+      if (fileMeta !== null) {
+        const metaRecord: MetadataRecord = {
+          type: 'metadata',
+          seq: 0,
+          time: fileMeta.created_at,
+          protocol_version: fileMeta.protocol_version,
+          created_at: fileMeta.created_at,
+          file_name: basename(filePath),
+        };
+        if (fileMeta.kimi_version !== undefined) metaRecord.kimi_version = fileMeta.kimi_version;
+        if (fileMeta.producer !== undefined) metaRecord.producer = fileMeta.producer;
+        records.push(metaRecord);
+      }
+      if (init !== null) records.push(init);
+      records.push(...(result.records));
+      sessionInitialized = init;
+      for (const w of result.warnings) warnings.push(`${filePath}: ${w}`);
+      if (result.health === 'broken') {
+        overallHealth = 'broken';
+        brokenReason ??= result.brokenReason ?? `broken wire file: ${filePath}`;
+      }
+    } catch (error) {
+      // Filesystem / unexpected errors surface as a soft broken state —
+      // vis still lists the session and shows its raw records if we
+      // have any.
+      overallHealth = 'broken';
+      const reason = error instanceof Error ? error.message : String(error);
+      brokenReason ??= `${filePath}: ${reason}`;
+      warnings.push(`${filePath}: ${reason}`);
+    }
+  }
+
+  const out: WireLoadResult = {
+    records,
+    session_initialized: sessionInitialized,
+    health: overallHealth,
+    warnings,
+    files_read: filesRead,
+  };
+  if (brokenReason !== undefined) out.broken_reason = brokenReason;
+  return out;
+}
+
+/** Parse line 1 of a wire.jsonl as the file-header metadata record.
+ *  Returns null on any read/parse failure — the caller already ran
+ *  `replayWire()`, which validates the header independently, so this
+ *  helper stays forgiving: missing metadata just means we can't splice
+ *  it into the timeline, not that the session is broken. */
+async function readMetadataLine(filePath: string): Promise<WireFileMetadata | null> {
+  try {
+    const text = await readFile(filePath, 'utf8');
+    const nl = text.indexOf('\n');
+    const first = nl === -1 ? text : text.slice(0, nl);
+    if (first.length === 0) return null;
+    const parsed = JSON.parse(first) as unknown;
+    if (
+      typeof parsed !== 'object' ||
+      parsed === null ||
+      (parsed as { type?: unknown }).type !== 'metadata'
+    ) {
+      return null;
+    }
+    return parsed as WireFileMetadata;
+  } catch {
+    return null;
+  }
+}
diff --git a/apps/vis/server/src/lib/wire-replay.ts b/apps/vis/server/src/lib/wire-replay.ts
new file mode 100644
index 000000000..3060eac6e
--- /dev/null
+++ b/apps/vis/server/src/lib/wire-replay.ts
@@ -0,0 +1,488 @@
+import { readFile } from 'node:fs/promises';
+
+import type {
+  ContentPartRecord,
+  NotificationRecord,
+  SessionInitializedRecord,
+  StepBeginRecord,
+  StepEndRecord,
+  SystemReminderRecord,
+  SystemPromptChangedRecord,
+  ToolCallRecord,
+  ToolResultRecord,
+  ToolsChangedRecord,
+  TurnBeginRecord,
+  UserInputPart,
+  UserMessageRecord,
+  VisWireRecord,
+  WireFileMetadata,
+} from './types';
+
+export interface ReplayWireResult {
+  health: 'ok' | 'broken';
+  brokenReason?: string;
+  warnings: string[];
+  metadata: WireFileMetadata | null;
+  sessionInitialized: SessionInitializedRecord | null;
+  records: VisWireRecord[];
+}
+
+export async function replayWire(wirePath: string): Promise<ReplayWireResult> {
+  const raw = await readFile(wirePath, 'utf8');
+  const lines = raw.split(/\r?\n/).filter((line) => line.length > 0);
+  const warnings: string[] = [];
+  const records: VisWireRecord[] = [];
+  const rawRecords: RawWireRecord[] = [];
+  let metadata: WireFileMetadata | null = null;
+  let sessionInitialized: SessionInitializedRecord | null = null;
+  let nextTurnIndex = 0;
+  let currentTurnId = '0';
+
+  for (const [index, line] of lines.entries()) {
+    const seq = index + 1;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line) as unknown;
+    } catch (error) {
+      warnings.push(`line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    if (!isRecord(parsed) || typeof parsed['type'] !== 'string') {
+      warnings.push(`line ${index + 1}: missing record type`);
+      continue;
+    }
+    rawRecords.push({ seq, raw: parsed });
+  }
+
+  for (const [recordIndex, record] of rawRecords.entries()) {
+    const parsed = record.raw;
+    const seq = record.seq;
+    if (parsed['type'] === 'metadata') {
+      metadata ??= parsed as unknown as WireFileMetadata;
+      continue;
+    }
+    if (parsed['type'] === 'session_initialized') {
+      sessionInitialized = parsed as unknown as SessionInitializedRecord;
+      continue;
+    }
+    const normalized = normalizeRecord(
+      parsed,
+      seq,
+      currentTurnId,
+      nextTurnIndex,
+      rawRecords,
+      recordIndex,
+    );
+    records.push(...normalized.records);
+    if (normalized.currentTurnId !== undefined) currentTurnId = normalized.currentTurnId;
+    if (normalized.nextTurnIndex !== undefined) nextTurnIndex = normalized.nextTurnIndex;
+  }
+
+  const out: ReplayWireResult = {
+    health: warnings.length === 0 ? 'ok' : 'broken',
+    warnings,
+    metadata,
+    sessionInitialized,
+    records,
+  };
+  if (warnings.length > 0) out.brokenReason = warnings[0];
+  return out;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+interface RawWireRecord {
+  seq: number;
+  raw: Record<string, unknown>;
+}
+
+interface NormalizeResult {
+  records: VisWireRecord[];
+  currentTurnId?: string;
+  nextTurnIndex?: number;
+}
+
+function normalizeRecord(
+  raw: Record<string, unknown>,
+  fallbackSeq: number,
+  currentTurnId: string,
+  nextTurnIndex: number,
+  rawRecords: readonly RawWireRecord[],
+  recordIndex: number,
+): NormalizeResult {
+  const seq = numberValue(raw['seq']) ?? fallbackSeq;
+  const time = numberValue(raw['time']) ?? 0;
+  const type = stringValue(raw['type']) ?? 'unknown';
+
+  switch (type) {
+    case 'turn.prompt':
+      return normalizeTurnStart(raw, seq, time, nextTurnIndex);
+
+    case 'turn.steer': {
+      const turnId = inferSteerStartedTurnId(rawRecords, recordIndex, currentTurnId, nextTurnIndex);
+      if (turnId === undefined) return { records: [] };
+      return normalizeTurnStart(raw, seq, time, nextTurnIndex, turnId);
+    }
+
+    case 'context.user_message':
+    case 'context.append_message': {
+      // `context.append_message` (newer producer) nests `{role, content}`
+      // under a `message` field; `context.user_message` (older) puts
+      // `content` at the top level. Only surface user-authored messages —
+      // assistant messages are already represented by content.part events
+      // inside loop events.
+      if (!isUserAuthoredAppendMessage(raw)) {
+        return { records: [notificationFromRaw(raw, seq, time)] };
+      }
+      const message = isRecord(raw['message']) ? raw['message'] : undefined;
+      const rawContent = message !== undefined ? message['content'] : raw['content'];
+      const content = Array.isArray(rawContent)
+        ? (rawContent as readonly UserInputPart[])
+        : (stringValue(rawContent) ?? '');
+      const record: UserMessageRecord = {
+        type: 'user_message',
+        seq,
+        time,
+        turn_id: currentTurnId,
+        content,
+      };
+      return { records: [record] };
+    }
+
+    case 'context.delta':
+    case 'context.append_loop_event': {
+      const event = raw['event'];
+      if (!isRecord(event)) return { records: [notificationFromRaw(raw, seq, time)] };
+      const eventTurnId = stringValue(event['turnId']);
+      const records = normalizeLoopEvent(event, seq, time, currentTurnId);
+      return {
+        records,
+        currentTurnId: eventTurnId,
+      };
+    }
+
+    case 'config.update': {
+      const prompt = stringValue(raw['systemPrompt']);
+      if (prompt !== undefined) {
+        const record: SystemPromptChangedRecord = {
+          type: 'system_prompt_changed',
+          seq,
+          time,
+          new_prompt: prompt,
+        };
+        return { records: [record] };
+      }
+      return { records: [notificationFromRaw(raw, seq, time)] };
+    }
+
+    case 'tool.set_active':
+    case 'tools.set_active_tools': {
+      const names = Array.isArray(raw['names'])
+        ? raw['names'].filter((name): name is string => typeof name === 'string')
+        : [];
+      const record: ToolsChangedRecord = {
+        type: 'tools_changed',
+        seq,
+        time,
+        operation: 'set_active',
+        tools: names,
+      };
+      return { records: [record] };
+    }
+
+    case 'context.system_reminder': {
+      const record: SystemReminderRecord = {
+        type: 'system_reminder',
+        seq,
+        time,
+        content: stringValue(raw['content']) ?? '',
+      };
+      return { records: [record] };
+    }
+
+    case 'context.clear':
+      return { records: [{ type: 'context_cleared', seq, time }] };
+
+    case 'context.mark_last_user_prompt_blocked':
+      return { records: [] };
+
+    default:
+      return {
+        records: [
+          hasLegacyShape(raw)
+            ? (raw as unknown as VisWireRecord)
+            : notificationFromRaw(raw, seq, time),
+        ],
+      };
+  }
+}
+
+function normalizeTurnStart(
+  raw: Record<string, unknown>,
+  seq: number,
+  time: number,
+  nextTurnIndex: number,
+  turnId = String(nextTurnIndex),
+): NormalizeResult {
+  const input = Array.isArray(raw['input']) ? (raw['input'] as readonly UserInputPart[]) : [];
+  const record: TurnBeginRecord = {
+    type: 'turn_begin',
+    seq,
+    time,
+    turn_id: turnId,
+    agent_type: 'main',
+    input_kind: 'user',
+    user_input: inputToText(input),
+  };
+  return {
+    records: [record],
+    currentTurnId: turnId,
+    nextTurnIndex: nextTurnIndexAfter(turnId, nextTurnIndex),
+  };
+}
+
+function inferSteerStartedTurnId(
+  rawRecords: readonly RawWireRecord[],
+  recordIndex: number,
+  currentTurnId: string,
+  nextTurnIndex: number,
+): string | undefined {
+  let sawUserMessage = false;
+
+  // Wire does not persist turn.ended, so past records cannot prove whether
+  // core still had an active turn. The next explicit loop turnId is the durable
+  // signal for whether this steer stayed buffered or launched a fresh turn.
+  for (let index = recordIndex + 1; index < rawRecords.length; index += 1) {
+    const raw = rawRecords[index]?.raw;
+    if (raw === undefined) continue;
+
+    const type = stringValue(raw['type']);
+    if (type === 'turn.prompt' || type === 'turn.steer') break;
+    if (type === 'context.user_message' || type === 'context.append_message') {
+      // Only an actual user message should count as evidence that the
+      // steer launched a fresh turn. The newer `context.append_message`
+      // producer carries assistant / system roles too, and
+      // `ContextMemory.appendSystemReminder()` persists injected
+      // reminders with role: 'user' but a non-user origin — both of
+      // those would fabricate a fresh turn ID below and mis-tag
+      // subsequent records.
+      if (isUserAuthoredAppendMessage(raw)) {
+        sawUserMessage = true;
+      }
+      continue;
+    }
+    if (type !== 'context.delta' && type !== 'context.append_loop_event') continue;
+
+    const event = raw['event'];
+    if (!isRecord(event)) continue;
+
+    const eventTurnId = stringValue(event['turnId']);
+    if (eventTurnId === undefined) continue;
+    return eventTurnId === currentTurnId ? undefined : eventTurnId;
+  }
+
+  return sawUserMessage ? String(nextTurnIndex) : undefined;
+}
+
+// Distinguishes real user input from non-user content that shares the
+// `role: 'user'` slot for the LLM (system reminders, skill activation
+// payloads, injection content, compaction summaries). The older
+// `context.user_message` shape has no `origin`, so absence is treated
+// as user authorship to preserve back-compat with older wire logs.
+function isUserAuthoredAppendMessage(raw: Record<string, unknown>): boolean {
+  const message = isRecord(raw['message']) ? raw['message'] : undefined;
+  const role = stringValue(message?.['role']) ?? stringValue(raw['role']);
+  if (role !== undefined && role !== 'user') return false;
+  const origin = isRecord(message?.['origin']) ? message['origin'] : undefined;
+  const originKind = stringValue(origin?.['kind']);
+  if (originKind !== undefined && originKind !== 'user') return false;
+  return true;
+}
+
+function nextTurnIndexAfter(turnId: string, nextTurnIndex: number): number {
+  const parsed = Number.parseInt(turnId, 10);
+  if (String(parsed) === turnId && parsed >= nextTurnIndex) return parsed + 1;
+  return nextTurnIndex + 1;
+}
+
+function normalizeLoopEvent(
+  event: Record<string, unknown>,
+  seq: number,
+  time: number,
+  currentTurnId: string,
+): VisWireRecord[] {
+  const eventType = stringValue(event['type']);
+  const turnId = stringValue(event['turnId']) ?? currentTurnId;
+
+  switch (eventType) {
+    case undefined:
+      return [notificationFromRaw({ type: 'context.delta', event }, seq, time)];
+
+    case 'step.begin': {
+      const record: StepBeginRecord = {
+        type: 'step_begin',
+        seq,
+        time,
+        uuid: stringValue(event['uuid']) ?? `step_${seq}`,
+        turn_id: turnId,
+        step: numberValue(event['step']) ?? 0,
+      };
+      return [record];
+    }
+
+    case 'content.part': {
+      const rawPart = isRecord(event['part']) ? event['part'] : {};
+      const kind = rawPart['type'] === 'think' || rawPart['kind'] === 'think' ? 'think' : 'text';
+      const record: ContentPartRecord = {
+        type: 'content_part',
+        seq,
+        time,
+        uuid: stringValue(event['uuid']) ?? `part_${seq}`,
+        turn_id: turnId,
+        step: numberValue(event['step']) ?? 0,
+        step_uuid: stringValue(event['stepUuid']) ?? '',
+        role: 'assistant',
+        part:
+          kind === 'think'
+            ? { kind, think: stringValue(rawPart['think']) ?? '' }
+            : { kind, text: stringValue(rawPart['text']) ?? '' },
+      };
+      return [record];
+    }
+
+    case 'tool.call': {
+      const record: ToolCallRecord = {
+        type: 'tool_call',
+        seq,
+        time,
+        uuid: stringValue(event['uuid']) ?? `tool_${seq}`,
+        turn_id: turnId,
+        step: numberValue(event['step']) ?? 0,
+        step_uuid: stringValue(event['stepUuid']) ?? '',
+        data: {
+          tool_call_id: stringValue(event['toolCallId']) ?? `tool_${seq}`,
+          tool_name: stringValue(event['name']) ?? 'unknown',
+          args: event['args'],
+          description: stringValue(event['description']),
+          display: event['display'],
+        },
+      };
+      return [record];
+    }
+
+    case 'tool.result': {
+      const result = isRecord(event['result']) ? event['result'] : {};
+      const record: ToolResultRecord = {
+        type: 'tool_result',
+        seq,
+        time,
+        turn_id: turnId,
+        tool_call_id: stringValue(event['toolCallId']) ?? `tool_${seq}`,
+        output: result['output'],
+        is_error: result['isError'] === true,
+        parent_uuid: stringValue(event['parentUuid']),
+      };
+      return [record];
+    }
+
+    case 'step.end': {
+      const record: StepEndRecord = {
+        type: 'step_end',
+        seq,
+        time,
+        uuid: stringValue(event['uuid']) ?? `step_${seq}`,
+        turn_id: turnId,
+        step: numberValue(event['step']) ?? 0,
+        usage: normalizeUsage(event['usage']),
+        finish_reason: stringValue(event['finishReason']),
+      };
+      return [record];
+    }
+
+    default:
+      return [notificationFromRaw({ type: 'context.delta', event }, seq, time)];
+  }
+}
+
+function notificationFromRaw(
+  raw: Record<string, unknown>,
+  seq: number,
+  time: number,
+): NotificationRecord {
+  const type = stringValue(raw['type']) ?? 'unknown';
+  return {
+    type: 'notification',
+    seq,
+    time,
+    data: {
+      id: `${seq}:${type}`,
+      category: 'system',
+      type,
+      source_kind: 'wire',
+      source_id: 'vis',
+      title: type,
+      body: stringify(raw),
+      severity: 'info',
+      payload: raw,
+      targets: ['wire'],
+    },
+  };
+}
+
+function hasLegacyShape(raw: Record<string, unknown>): boolean {
+  const type = stringValue(raw['type']);
+  return (
+    type !== undefined &&
+    !type.includes('.') &&
+    typeof raw['seq'] === 'number' &&
+    typeof raw['time'] === 'number'
+  );
+}
+
+function normalizeUsage(value: unknown): StepEndRecord['usage'] {
+  if (!isRecord(value)) return undefined;
+  return {
+    input_tokens:
+      numberValue(value['input_tokens']) ??
+      numberValue(value['input']) ??
+      numberValue(value['inputOther']) ??
+      0,
+    output_tokens: numberValue(value['output_tokens']) ?? numberValue(value['output']) ?? 0,
+    cache_read_tokens:
+      numberValue(value['cache_read_tokens']) ??
+      numberValue(value['cache_read']) ??
+      numberValue(value['inputCacheRead']),
+    cache_write_tokens:
+      numberValue(value['cache_write_tokens']) ??
+      numberValue(value['cache_write']) ??
+      numberValue(value['inputCacheCreation']),
+  };
+}
+
+function inputToText(input: readonly UserInputPart[]): string {
+  return input
+    .map((part) => {
+      if (part.type === 'text') return part.text;
+      if (part.type === 'image_url') return '<image>';
+      return '<video>';
+    })
+    .join('');
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function stringify(value: unknown): string {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return '[unserializable]';
+  }
+}
diff --git a/apps/vis/server/src/routes/context.ts b/apps/vis/server/src/routes/context.ts
new file mode 100644
index 000000000..fdb1d5653
--- /dev/null
+++ b/apps/vis/server/src/routes/context.ts
@@ -0,0 +1,57 @@
+import { readFile, stat } from 'node:fs/promises';
+
+import { Hono } from 'hono';
+
+import { pathConfig } from '../config';
+import { buildAnnotatedMessages, buildProjectedStateSummary } from '../lib/context-builder';
+import type { ContextResponse, SessionState } from '../lib/types';
+import { loadWireRecords } from '../lib/wire-loader';
+
+const SESSION_ID_RE = /^session_[a-zA-Z0-9_-]+$/;
+
+export function contextRoute(): Hono {
+  const app = new Hono();
+
+  app.get('/:id/context', async (c) => {
+    const id = c.req.param('id');
+    if (!SESSION_ID_RE.test(id)) {
+      return c.json({ error: `invalid session id: ${id}`, code: 'BAD_REQUEST' }, 400);
+    }
+    const sessionDir = pathConfig.sessionDir(id);
+    try {
+      const dirStat = await stat(sessionDir);
+      if (!dirStat.isDirectory()) {
+        return c.json({ error: `session not found: ${id}`, code: 'NOT_FOUND' }, 404);
+      }
+    } catch {
+      return c.json({ error: `session not found: ${id}`, code: 'NOT_FOUND' }, 404);
+    }
+
+    try {
+      const load = await loadWireRecords(sessionDir);
+      const state = await readSessionState(id);
+      const annotated = buildAnnotatedMessages(load.records);
+      const projected = buildProjectedStateSummary(load.records, load.session_initialized, state);
+      const body: ContextResponse = {
+        session_id: id,
+        agent_id: null,
+        annotated_messages: annotated,
+        projected_state: projected,
+      };
+      return c.json(body);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      return c.json({ error: `failed to build context: ${msg}`, code: 'READ_ERROR' }, 500);
+    }
+  });
+
+  return app;
+}
+
+async function readSessionState(sessionId: string): Promise<SessionState | null> {
+  try {
+    return JSON.parse(await readFile(pathConfig.statePath(sessionId), 'utf8')) as SessionState;
+  } catch {
+    return null;
+  }
+}
diff --git a/apps/vis/server/src/routes/session-detail.ts b/apps/vis/server/src/routes/session-detail.ts
new file mode 100644
index 000000000..3ab089740
--- /dev/null
+++ b/apps/vis/server/src/routes/session-detail.ts
@@ -0,0 +1,155 @@
+import { createReadStream } from 'node:fs';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+
+import { Hono } from 'hono';
+
+import { pathConfig } from '../config';
+import { deleteSession, SESSION_ID_RE } from '../lib/session-delete';
+import { readSessionLastPrompt, readSessionTitle } from '../lib/session-title';
+import type { SessionDetail, SessionState, WireFileMetadata } from '../lib/types';
+
+const ARCHIVE_RE = /^wire\.\d+\.jsonl$/;
+
+async function readFirstLine(path: string): Promise<string | null> {
+  try {
+    const stream = createReadStream(path, { encoding: 'utf8' });
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const line of rl) {
+      rl.close();
+      stream.close();
+      return line;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+export function sessionDetailRoute(): Hono {
+  const app = new Hono();
+
+  app.get('/:id', async (c) => {
+    const id = c.req.param('id');
+    if (!SESSION_ID_RE.test(id)) {
+      return c.json({ error: `invalid session id: ${id}`, code: 'BAD_REQUEST' }, 400);
+    }
+    const sessionDir = pathConfig.sessionDir(id);
+
+    let dirStat;
+    try {
+      dirStat = await stat(sessionDir);
+    } catch {
+      return c.json({ error: `session not found: ${id}`, code: 'NOT_FOUND' }, 404);
+    }
+    if (!dirStat.isDirectory()) {
+      return c.json({ error: `session not a directory: ${id}`, code: 'NOT_FOUND' }, 404);
+    }
+
+    // state.json (best-effort).
+    let state: SessionState;
+    try {
+      const raw = await readFile(pathConfig.statePath(id), 'utf8');
+      state = JSON.parse(raw) as SessionState;
+    } catch {
+      state = {
+        session_id: id,
+        created_at: 0,
+        updated_at: 0,
+      };
+    }
+
+    // Directory listings.
+    const mainAgentDir = pathConfig.mainAgentDir(id);
+    const mainEntries = await readdir(mainAgentDir).catch(() => [] as string[]);
+    const archive_files = mainEntries.filter((e) => ARCHIVE_RE.test(e)).toSorted();
+
+    const subagent_ids: string[] = [];
+    try {
+      const subs = await readdir(join(sessionDir, 'agents'));
+      for (const s of subs) {
+        if (s === 'main') continue;
+        const ss = await stat(join(sessionDir, 'agents', s)).catch(() => null);
+        if (ss?.isDirectory()) subagent_ids.push(s);
+      }
+    } catch {
+      try {
+        const subs = await readdir(join(sessionDir, 'subagents'));
+        for (const s of subs) {
+          const ss = await stat(join(sessionDir, 'subagents', s)).catch(() => null);
+          if (ss?.isDirectory()) subagent_ids.push(s);
+        }
+      } catch {
+        // subagents dir missing is fine
+      }
+    }
+
+    const tool_result_ids: string[] = [];
+    try {
+      const files = await readdir(join(mainAgentDir, 'tool-results'));
+      for (const f of files) {
+        if (f.endsWith('.txt')) tool_result_ids.push(f.slice(0, -4));
+      }
+    } catch {
+      try {
+        const files = await readdir(join(sessionDir, 'tool-results'));
+        for (const f of files) {
+          if (f.endsWith('.txt')) tool_result_ids.push(f.slice(0, -4));
+        }
+      } catch {
+        // tool-results dir missing is fine
+      }
+    }
+
+    // wire metadata (first line of wire.jsonl)
+    let wire_metadata: WireFileMetadata | null = null;
+    const firstLine = await readFirstLine(pathConfig.wirePath(id));
+    if (firstLine !== null) {
+      try {
+        const parsed = JSON.parse(firstLine) as unknown;
+        if (
+          typeof parsed === 'object' &&
+          parsed !== null &&
+          (parsed as { type?: unknown }).type === 'metadata'
+        ) {
+          wire_metadata = parsed as WireFileMetadata;
+        }
+      } catch {
+        // ignore malformed header
+      }
+    }
+
+    const detail: SessionDetail = {
+      session_id: id,
+      title: readSessionTitle(state),
+      last_prompt: readSessionLastPrompt(state),
+      state,
+      subagent_ids,
+      archive_files,
+      tool_result_ids,
+      wire_metadata,
+    };
+    return c.json(detail);
+  });
+
+  app.delete('/:id', async (c) => {
+    const id = c.req.param('id');
+    if (!SESSION_ID_RE.test(id)) {
+      return c.json({ error: `invalid session id: ${id}`, code: 'BAD_REQUEST' }, 400);
+    }
+
+    try {
+      const result = await deleteSession(id);
+      if (result === null) {
+        return c.json({ error: `session not found: ${id}`, code: 'NOT_FOUND' }, 404);
+      }
+      return c.json(result);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      return c.json({ error: `failed to delete session: ${msg}`, code: 'DELETE_ERROR' }, 500);
+    }
+  });
+
+  return app;
+}
diff --git a/apps/vis/server/src/routes/sessions.ts b/apps/vis/server/src/routes/sessions.ts
new file mode 100644
index 000000000..4b44d476d
--- /dev/null
+++ b/apps/vis/server/src/routes/sessions.ts
@@ -0,0 +1,28 @@
+import { Hono } from 'hono';
+
+import { pathConfig } from '../config';
+import { clearSessions } from '../lib/session-delete';
+import { listSessions } from '../lib/session-lister';
+
+export function sessionsRoute(): Hono {
+  const app = new Hono();
+  app.get('/', async (c) => {
+    try {
+      const summaries = await listSessions(pathConfig.sessionsDir);
+      return c.json(summaries);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      return c.json({ error: `failed to list sessions: ${msg}`, code: 'READ_ERROR' }, 500);
+    }
+  });
+  app.delete('/', async (c) => {
+    try {
+      const result = await clearSessions();
+      return c.json(result);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      return c.json({ error: `failed to clear sessions: ${msg}`, code: 'DELETE_ERROR' }, 500);
+    }
+  });
+  return app;
+}
diff --git a/apps/vis/server/src/routes/subagents.ts b/apps/vis/server/src/routes/subagents.ts
new file mode 100644
index 000000000..5a8ee476c
--- /dev/null
+++ b/apps/vis/server/src/routes/subagents.ts
@@ -0,0 +1,226 @@
+import { readFile, stat } from 'node:fs/promises';
+
+import { Hono } from 'hono';
+
+import { pathConfig } from '../config';
+import { buildAnnotatedMessages, buildProjectedStateSummary } from '../lib/context-builder';
+import { buildSubagentTree } from '../lib/subagent-loader';
+import type {
+  ContextResponse,
+  SubagentMetaResponse,
+  SubagentNode,
+  SubagentTreeResponse,
+  WireResponse
+} from '../lib/types';
+import { loadWireRecords } from '../lib/wire-loader';
+
+const SESSION_ID_RE = /^session_[a-zA-Z0-9_-]+$/;
+// Subagent ids in the wild look like "sub_<uuid-ish>" — allow word chars and dashes.
+const AGENT_ID_RE = /^[a-zA-Z0-9_-]+$/;
+
+function findNode(tree: SubagentNode[], agentId: string): SubagentNode | null {
+  for (const node of tree) {
+    if (node.agent_id === agentId) return node;
+    const found = findNode(node.children, agentId);
+    if (found !== null) return found;
+  }
+  return null;
+}
+
+export function subagentsRoute(): Hono {
+  const app = new Hono();
+
+  app.get('/:id/subagents', async (c) => {
+    const id = c.req.param('id');
+    if (!SESSION_ID_RE.test(id)) {
+      return c.json({ error: `invalid session id: ${id}`, code: 'BAD_REQUEST' }, 400);
+    }
+    const sessionDir = pathConfig.sessionDir(id);
+    try {
+      const s = await stat(sessionDir);
+      if (!s.isDirectory())
+        return c.json({ error: `session not found: ${id}`, code: 'NOT_FOUND' }, 404);
+    } catch {
+      return c.json({ error: `session not found: ${id}`, code: 'NOT_FOUND' }, 404);
+    }
+
+    try {
+      const main = await loadWireRecords(sessionDir);
+      const tree = await buildSubagentTree(sessionDir, main.records);
+      const body: SubagentTreeResponse = { session_id: id, tree };
+      return c.json(body);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      return c.json({ error: `failed to build subagent tree: ${msg}`, code: 'READ_ERROR' }, 500);
+    }
+  });
+
+  app.get('/:id/subagents/:agentId/wire', async (c) => {
+    const id = c.req.param('id');
+    const agentId = c.req.param('agentId');
+    if (!SESSION_ID_RE.test(id) || !AGENT_ID_RE.test(agentId)) {
+      return c.json({ error: 'invalid session or agent id', code: 'BAD_REQUEST' }, 400);
+    }
+    const subDir = pathConfig.subagentDir(id, agentId);
+    try {
+      const s = await stat(subDir);
+      if (!s.isDirectory())
+        return c.json({ error: `subagent not found: ${agentId}`, code: 'NOT_FOUND' }, 404);
+    } catch {
+      return c.json({ error: `subagent not found: ${agentId}`, code: 'NOT_FOUND' }, 404);
+    }
+
+    try {
+      const result = await loadWireRecords(subDir);
+      const body: WireResponse = {
+        session_id: id,
+        agent_id: agentId,
+        files_read: result.files_read,
+        health: result.health,
+        warnings: result.warnings,
+        records: result.records,
+      };
+      if (result.broken_reason !== undefined) body.broken_reason = result.broken_reason;
+      return c.json(body);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      return c.json({ error: `failed to load subagent wire: ${msg}`, code: 'READ_ERROR' }, 500);
+    }
+  });
+
+  app.get('/:id/subagents/:agentId/context', async (c) => {
+    const id = c.req.param('id');
+    const agentId = c.req.param('agentId');
+    if (!SESSION_ID_RE.test(id) || !AGENT_ID_RE.test(agentId)) {
+      return c.json({ error: 'invalid session or agent id', code: 'BAD_REQUEST' }, 400);
+    }
+    const subDir = pathConfig.subagentDir(id, agentId);
+    try {
+      const s = await stat(subDir);
+      if (!s.isDirectory())
+        return c.json({ error: `subagent not found: ${agentId}`, code: 'NOT_FOUND' }, 404);
+    } catch {
+      return c.json({ error: `subagent not found: ${agentId}`, code: 'NOT_FOUND' }, 404);
+    }
+
+    try {
+      const load = await loadWireRecords(subDir);
+      const annotated = buildAnnotatedMessages(load.records);
+      const projected = buildProjectedStateSummary(load.records, load.session_initialized);
+      const body: ContextResponse = {
+        session_id: id,
+        agent_id: agentId,
+        annotated_messages: annotated,
+        projected_state: projected,
+      };
+      return c.json(body);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      return c.json({ error: `failed to build subagent context: ${msg}`, code: 'READ_ERROR' }, 500);
+    }
+  });
+
+  app.get('/:id/subagents/:agentId/meta', async (c) => {
+    const id = c.req.param('id');
+    const agentId = c.req.param('agentId');
+    if (!SESSION_ID_RE.test(id) || !AGENT_ID_RE.test(agentId)) {
+      return c.json({ error: 'invalid session or agent id', code: 'BAD_REQUEST' }, 400);
+    }
+    const sessionDir = pathConfig.sessionDir(id);
+    const subDir = pathConfig.subagentDir(id, agentId);
+    try {
+      const s = await stat(subDir);
+      if (!s.isDirectory())
+        return c.json({ error: `subagent not found: ${agentId}`, code: 'NOT_FOUND' }, 404);
+    } catch {
+      return c.json({ error: `subagent not found: ${agentId}`, code: 'NOT_FOUND' }, 404);
+    }
+
+    let meta_json: SubagentMetaResponse['meta_json'] = null;
+    try {
+      const raw = await readFile(`${subDir}/meta.json`, 'utf8');
+      meta_json = JSON.parse(raw) as SubagentMetaResponse['meta_json'];
+    } catch {
+      meta_json = null;
+    }
+
+    // Find the agent in the tree, then scan its direct parent's wire for
+    // lifecycle records. For nested subagents (depth >= 1), lifecycle records
+    // live on the intermediate parent's wire, not the main session wire.
+    let spawned_record: SubagentMetaResponse['spawned_record'] = null;
+    let completed_record: SubagentMetaResponse['completed_record'] = null;
+    let failed_record: SubagentMetaResponse['failed_record'] = null;
+    let depth = 0;
+
+    try {
+      const main = await loadWireRecords(sessionDir);
+      const tree = await buildSubagentTree(sessionDir, main.records);
+      const node = findNode(tree, agentId);
+      if (node !== null) depth = node.depth;
+
+      // Pick the correct wire to scan: main wire for depth 0, else the parent
+      // subagent's wire (which contains this child's spawn/complete records).
+      const parentAgentId = node?.parent_agent_id ?? null;
+      const scanRecords =
+        parentAgentId === null
+          ? main.records
+          : (await loadWireRecords(pathConfig.subagentDir(id, parentAgentId))).records;
+
+      for (const r of scanRecords) {
+        if (r.type === 'subagent_spawned' && r.data.agent_id === agentId) {
+          const entry: NonNullable<SubagentMetaResponse['spawned_record']> = {
+            parent_tool_call_id: r.data.parent_tool_call_id,
+            run_in_background: r.data.run_in_background,
+            seq: r.seq,
+            time: r.time,
+          };
+          if (r.data.agent_name !== undefined) entry.agent_name = r.data.agent_name;
+          if (r.data.parent_agent_id !== undefined) entry.parent_agent_id = r.data.parent_agent_id;
+          spawned_record = entry;
+        } else if (r.type === 'subagent_completed' && r.data.agent_id === agentId) {
+          const entry: NonNullable<SubagentMetaResponse['completed_record']> = {
+            parent_tool_call_id: r.data.parent_tool_call_id,
+            result_summary: r.data.result_summary,
+            seq: r.seq,
+            time: r.time,
+          };
+          if (r.data.usage !== undefined) {
+            const u = r.data.usage;
+            const usage: {
+              input_tokens: number;
+              output_tokens: number;
+              cache_read_tokens?: number;
+              cache_write_tokens?: number;
+            } = { input_tokens: u.input, output_tokens: u.output };
+            if (u.cache_read !== undefined) usage.cache_read_tokens = u.cache_read;
+            if (u.cache_write !== undefined) usage.cache_write_tokens = u.cache_write;
+            entry.usage = usage;
+          }
+          completed_record = entry;
+        } else if (r.type === 'subagent_failed' && r.data.agent_id === agentId) {
+          failed_record = {
+            parent_tool_call_id: r.data.parent_tool_call_id,
+            error: r.data.error,
+            seq: r.seq,
+            time: r.time,
+          };
+        }
+      }
+    } catch {
+      // Fall through — partial response is still useful.
+    }
+
+    const body: SubagentMetaResponse = {
+      agent_id: agentId,
+      session_id: id,
+      meta_json,
+      spawned_record,
+      completed_record,
+      failed_record,
+      depth,
+    };
+    return c.json(body);
+  });
+
+  return app;
+}
diff --git a/apps/vis/server/src/routes/tool-results.ts b/apps/vis/server/src/routes/tool-results.ts
new file mode 100644
index 000000000..30b67da00
--- /dev/null
+++ b/apps/vis/server/src/routes/tool-results.ts
@@ -0,0 +1,48 @@
+import { readFile, stat } from 'node:fs/promises';
+
+import { Hono } from 'hono';
+
+import { pathConfig } from '../config';
+import type { ToolResultFileResponse } from '../lib/types';
+
+const SESSION_ID_RE = /^session_[a-zA-Z0-9_-]+$/;
+// Tool call ids observed in the wild: simple identifiers, "call_..." or
+// "Agent:7". Allow a conservative character set including colon.
+const TOOL_CALL_ID_RE = /^[a-zA-Z0-9_:.-]+$/;
+
+export function toolResultsRoute(): Hono {
+  const app = new Hono();
+
+  app.get('/:id/tool-results/:toolCallId', async (c) => {
+    const id = c.req.param('id');
+    const toolCallId = c.req.param('toolCallId');
+    if (!SESSION_ID_RE.test(id)) {
+      return c.json({ error: `invalid session id: ${id}`, code: 'BAD_REQUEST' }, 400);
+    }
+    if (!TOOL_CALL_ID_RE.test(toolCallId)) {
+      return c.json({ error: `invalid tool call id: ${toolCallId}`, code: 'BAD_REQUEST' }, 400);
+    }
+    const filePath = pathConfig.toolResultArchivePath(id, toolCallId);
+    let s;
+    try {
+      s = await stat(filePath);
+    } catch {
+      return c.json({ error: `tool result not found: ${toolCallId}`, code: 'NOT_FOUND' }, 404);
+    }
+    try {
+      const content = await readFile(filePath, 'utf8');
+      const body: ToolResultFileResponse = {
+        tool_call_id: toolCallId,
+        session_id: id,
+        size_bytes: s.size,
+        content,
+      };
+      return c.json(body);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      return c.json({ error: `failed to read tool result: ${msg}`, code: 'READ_ERROR' }, 500);
+    }
+  });
+
+  return app;
+}
diff --git a/apps/vis/server/src/routes/wire.ts b/apps/vis/server/src/routes/wire.ts
new file mode 100644
index 000000000..4bd647900
--- /dev/null
+++ b/apps/vis/server/src/routes/wire.ts
@@ -0,0 +1,84 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { Hono } from 'hono';
+
+import { pathConfig } from '../config';
+import type { WireResponse } from '../lib/types';
+import { loadWireRecords } from '../lib/wire-loader';
+import { replayWire } from '../lib/wire-replay';
+
+const SESSION_ID_RE = /^session_[a-zA-Z0-9_-]+$/;
+const ARCHIVE_FILE_RE = /^wire\.\d+\.jsonl$/;
+
+export function wireRoute(): Hono {
+  const app = new Hono();
+
+  app.get('/:id/wire', async (c) => {
+    const id = c.req.param('id');
+    if (!SESSION_ID_RE.test(id)) {
+      return c.json({ error: `invalid session id: ${id}`, code: 'BAD_REQUEST' }, 400);
+    }
+    const sessionDir = pathConfig.sessionDir(id);
+    try {
+      const dirStat = await stat(sessionDir);
+      if (!dirStat.isDirectory()) {
+        return c.json({ error: `session not found: ${id}`, code: 'NOT_FOUND' }, 404);
+      }
+    } catch {
+      return c.json({ error: `session not found: ${id}`, code: 'NOT_FOUND' }, 404);
+    }
+
+    try {
+      const result = await loadWireRecords(sessionDir);
+      const body: WireResponse = {
+        session_id: id,
+        agent_id: null,
+        files_read: result.files_read,
+        health: result.health,
+        warnings: result.warnings,
+        records: result.records,
+      };
+      if (result.broken_reason !== undefined) body.broken_reason = result.broken_reason;
+      return c.json(body);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      return c.json({ error: `failed to load wire: ${msg}`, code: 'READ_ERROR' }, 500);
+    }
+  });
+
+  app.get('/:id/archives/:filename', async (c) => {
+    const id = c.req.param('id');
+    const filename = c.req.param('filename');
+    if (!SESSION_ID_RE.test(id)) {
+      return c.json({ error: `invalid session id: ${id}`, code: 'BAD_REQUEST' }, 400);
+    }
+    if (!ARCHIVE_FILE_RE.test(filename)) {
+      return c.json({ error: `invalid archive filename: ${filename}`, code: 'BAD_REQUEST' }, 400);
+    }
+    const archivePath = join(pathConfig.mainAgentDir(id), filename);
+    try {
+      await stat(archivePath);
+    } catch {
+      return c.json({ error: `archive not found: ${filename}`, code: 'NOT_FOUND' }, 404);
+    }
+    try {
+      const result = await replayWire(archivePath);
+      const body: WireResponse = {
+        session_id: id,
+        agent_id: null,
+        files_read: [archivePath],
+        health: result.health,
+        warnings: [...result.warnings],
+        records: result.records,
+      };
+      if (result.brokenReason !== undefined) body.broken_reason = result.brokenReason;
+      return c.json(body);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      return c.json({ error: `failed to replay archive: ${msg}`, code: 'READ_ERROR' }, 500);
+    }
+  });
+
+  return app;
+}
diff --git a/apps/vis/server/src/startup-banner.ts b/apps/vis/server/src/startup-banner.ts
new file mode 100644
index 000000000..55f9dd41f
--- /dev/null
+++ b/apps/vis/server/src/startup-banner.ts
@@ -0,0 +1,19 @@
+export interface StartupBannerOptions {
+  readonly authToken?: string;
+  readonly host: string;
+  readonly kimiCodeHome: string;
+  readonly port: number;
+}
+
+export function formatStartupBanner(options: StartupBannerOptions): string {
+  const authStatus = options.authToken === undefined ? 'auth=disabled' : 'auth=required';
+  return (
+    `[vis-server] listening on http://${hostForUrl(options.host)}:${String(options.port)} ` +
+    `(${authStatus}, KIMI_CODE_HOME=${options.kimiCodeHome})\n`
+  );
+}
+
+function hostForUrl(host: string): string {
+  if (host.includes(':') && !host.startsWith('[')) return `[${host}]`;
+  return host;
+}
diff --git a/apps/vis/server/test/_fixture.ts b/apps/vis/server/test/_fixture.ts
new file mode 100644
index 000000000..95cde6b18
--- /dev/null
+++ b/apps/vis/server/test/_fixture.ts
@@ -0,0 +1,251 @@
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** Minimal synthetic session dir using the current atomic wire protocol.
+ *  Real on-disk sessions under `~/.kimi-code/sessions/` use a legacy layout
+ *  that can no longer be replayed, so tests use synthetic fixtures. */
+export interface SyntheticOptions {
+  withReminder?: boolean;
+  withTools?: boolean;
+  withSubagent?: boolean;
+}
+
+export interface SyntheticResult {
+  dir: string;
+  sessionId: string;
+  cleanup(): void;
+}
+
+export function createSyntheticSession(opts: SyntheticOptions = {}): SyntheticResult {
+  const sessionId = `session_${randomBytes(6).toString('hex')}`;
+  const dir = join(tmpdir(), `vis-test-${sessionId}`);
+  mkdirSync(dir, { recursive: true });
+
+  const lines: string[] = [];
+  let seq = 1;
+  const push = (rec: Record<string, unknown>): void => {
+    lines.push(JSON.stringify(rec));
+  };
+
+  push({
+    type: 'metadata',
+    protocol_version: '1.0',
+    created_at: Date.now(),
+    producer: {
+      kind: 'typescript',
+      name: '@moonshot-ai/agent-core',
+      version: '0.0.1',
+    },
+  });
+
+  push({
+    type: 'session_initialized',
+    seq: seq++,
+    time: Date.now(),
+    agent_type: 'main',
+    session_id: sessionId,
+    system_prompt: 'You are a test assistant.',
+    model: 'test-model',
+    active_tools: opts.withTools ? ['Bash'] : [],
+    permission_mode: 'default',
+    plan_mode: false,
+    workspace_dir: '/tmp',
+  });
+
+  push({
+    type: 'turn_begin',
+    seq: seq++,
+    time: Date.now(),
+    turn_id: 'turn_1',
+    agent_type: 'main',
+    input_kind: 'user',
+    user_input: 'hi',
+  });
+
+  push({
+    type: 'user_message',
+    seq: seq++,
+    time: Date.now(),
+    turn_id: 'turn_1',
+    content: 'hi',
+  });
+
+  if (opts.withReminder) {
+    push({
+      type: 'system_reminder',
+      seq: seq++,
+      time: Date.now(),
+      content: 'test reminder',
+      consumed_at_turn: 1,
+    });
+  }
+
+  const stepUuid = 'step-1';
+  push({
+    type: 'step_begin',
+    seq: seq++,
+    time: Date.now(),
+    uuid: stepUuid,
+    turn_id: 'turn_1',
+    step: 0,
+  });
+  push({
+    type: 'content_part',
+    seq: seq++,
+    time: Date.now(),
+    uuid: 'cp-1',
+    turn_id: 'turn_1',
+    step: 0,
+    step_uuid: stepUuid,
+    role: 'assistant',
+    part: { kind: 'text', text: 'hello!' },
+  });
+
+  if (opts.withTools) {
+    push({
+      type: 'tool_call',
+      seq: seq++,
+      time: Date.now(),
+      uuid: 'tc-wire-1',
+      turn_id: 'turn_1',
+      step: 0,
+      step_uuid: stepUuid,
+      data: {
+        tool_call_id: 'tc_abc',
+        tool_name: 'Bash',
+        args: { cmd: 'echo hi' },
+      },
+    });
+  }
+
+  push({
+    type: 'step_end',
+    seq: seq++,
+    time: Date.now(),
+    uuid: stepUuid,
+    turn_id: 'turn_1',
+    step: 0,
+    usage: { input_tokens: 10, output_tokens: 5 },
+  });
+
+  if (opts.withTools) {
+    push({
+      type: 'tool_result',
+      seq: seq++,
+      time: Date.now(),
+      turn_id: 'turn_1',
+      tool_call_id: 'tc_abc',
+      output: 'hi\n',
+    });
+  }
+
+  if (opts.withSubagent) {
+    push({
+      type: 'subagent_spawned',
+      seq: seq++,
+      time: Date.now(),
+      data: {
+        agent_id: 'sub_test-1',
+        agent_name: 'coder',
+        parent_tool_call_id: 'tc_sub',
+        run_in_background: false,
+      },
+    });
+    // Write the subagent's own wire.jsonl
+    const subDir = join(dir, 'subagents', 'sub_test-1');
+    mkdirSync(subDir, { recursive: true });
+    const subLines: string[] = [
+      JSON.stringify({
+        type: 'metadata',
+        protocol_version: '1.0',
+        created_at: Date.now(),
+        producer: {
+          kind: 'typescript',
+          name: '@moonshot-ai/agent-core',
+          version: '0.0.1',
+        },
+      }),
+      JSON.stringify({
+        type: 'session_initialized',
+        seq: 1,
+        time: Date.now(),
+        agent_type: 'sub',
+        agent_id: 'sub_test-1',
+        agent_name: 'coder',
+        parent_session_id: sessionId,
+        parent_tool_call_id: 'tc_sub',
+        run_in_background: false,
+        system_prompt: 'You are a subagent.',
+        model: 'test-model',
+        active_tools: [],
+        permission_mode: 'default',
+        plan_mode: false,
+        workspace_dir: '/tmp',
+      }),
+    ];
+    writeFileSync(join(subDir, 'wire.jsonl'), subLines.join('\n') + '\n');
+    writeFileSync(
+      join(subDir, 'meta.json'),
+      JSON.stringify({
+        agent_id: 'sub_test-1',
+        subagent_type: 'coder',
+        status: 'completed',
+        description: 'test subagent',
+        parent_tool_call_id: 'tc_sub',
+        created_at: Date.now() / 1000,
+        updated_at: Date.now() / 1000,
+      }),
+    );
+
+    push({
+      type: 'subagent_completed',
+      seq: seq++,
+      time: Date.now(),
+      data: {
+        agent_id: 'sub_test-1',
+        parent_tool_call_id: 'tc_sub',
+        result_summary: 'all done',
+        usage: { input: 100, output: 50 },
+      },
+    });
+  }
+
+  push({
+    type: 'turn_end',
+    seq: seq++,
+    time: Date.now(),
+    turn_id: 'turn_1',
+    agent_type: 'main',
+    success: true,
+    reason: 'done',
+  });
+
+  writeFileSync(join(dir, 'wire.jsonl'), lines.join('\n') + '\n');
+  writeFileSync(
+    join(dir, 'state.json'),
+    JSON.stringify({
+      session_id: sessionId,
+      model: 'test-model',
+      status: 'idle',
+      created_at: Date.now(),
+      updated_at: Date.now(),
+      workspace_dir: '/tmp',
+      // Required for listSessions() producer filter.
+      producer: { kind: 'typescript', name: '@moonshot-ai/agent-core', version: '0.0.1' },
+    }),
+  );
+
+  return {
+    dir,
+    sessionId,
+    cleanup: () => {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}
diff --git a/apps/vis/server/test/app.test.ts b/apps/vis/server/test/app.test.ts
new file mode 100644
index 000000000..23b4cbf33
--- /dev/null
+++ b/apps/vis/server/test/app.test.ts
@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createApp } from '../src/app';
+import { resolveHost, resolveVisAuthToken } from '../src/config';
+import { formatStartupBanner } from '../src/startup-banner';
+
+describe('vis server access controls', () => {
+  const savedEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...savedEnv };
+  });
+
+  it('binds to loopback by default', () => {
+    delete process.env['VIS_HOST'];
+    delete process.env['HOST'];
+
+    expect(resolveHost()).toBe('127.0.0.1');
+  });
+
+  it('allows an explicit bind host', () => {
+    process.env['VIS_HOST'] = '0.0.0.0';
+
+    expect(resolveHost()).toBe('0.0.0.0');
+  });
+
+  it('requires a token when binding outside loopback', () => {
+    delete process.env['VIS_AUTH_TOKEN'];
+
+    expect(() => resolveVisAuthToken('0.0.0.0')).toThrow(/VIS_AUTH_TOKEN/);
+
+    process.env['VIS_AUTH_TOKEN'] = 'secret-token';
+    expect(resolveVisAuthToken('0.0.0.0')).toBe('secret-token');
+  });
+
+  it('requires bearer auth for API routes when a token is configured', async () => {
+    const app = await createApp({ authToken: 'secret-token' });
+
+    const anonymous = await app.request('/api/sessions');
+    expect(anonymous.status).toBe(401);
+    await expect(anonymous.json()).resolves.toMatchObject({ code: 'UNAUTHORIZED' });
+
+    const wrong = await app.request('/api/sessions', {
+      headers: { authorization: 'Bearer wrong-token' },
+    });
+    expect(wrong.status).toBe(401);
+
+    const allowed = await app.request('/api/sessions', {
+      headers: { authorization: 'Bearer secret-token' },
+    });
+    expect(allowed.status).toBe(200);
+  });
+
+  it('keeps loopback-only local API access open when no token is configured', async () => {
+    const app = await createApp();
+
+    const response = await app.request('/api/sessions');
+
+    expect(response.status).toBe(200);
+  });
+
+  it('does not include the bearer token in the startup banner', () => {
+    const banner = formatStartupBanner({
+      authToken: 'secret-token',
+      host: '127.0.0.1',
+      kimiCodeHome: '/tmp/kimi-code',
+      port: 3001,
+    });
+
+    expect(banner).toContain('auth=required');
+    expect(banner).not.toContain('secret-token');
+    expect(banner).not.toContain('token=');
+  });
+});
diff --git a/apps/vis/server/test/context-builder.test.ts b/apps/vis/server/test/context-builder.test.ts
new file mode 100644
index 000000000..9823a2ccf
--- /dev/null
+++ b/apps/vis/server/test/context-builder.test.ts
@@ -0,0 +1,242 @@
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  buildAnnotatedMessages,
+  buildProjectedStateSummary,
+  extractPersistedOutputPath,
+  renderNotificationXml,
+} from '../src/lib/context-builder';
+import type { NotificationRecord, SystemReminderRecord, VisWireRecord } from '../src/lib/types';
+import { loadWireRecords } from '../src/lib/wire-loader';
+import { createSyntheticSession, type SyntheticResult } from './_fixture';
+
+describe('context-builder', () => {
+  let fixture: SyntheticResult | null = null;
+  afterEach(() => {
+    fixture?.cleanup();
+    fixture = null;
+  });
+
+  it('extracts persisted-output path when marker is present', () => {
+    const text =
+      '<persisted-output path="/tmp/sessions/ses_foo/tool-results/call_1.txt">\nlorem ipsum\n</persisted-output>';
+    expect(extractPersistedOutputPath(text)).toBe('/tmp/sessions/ses_foo/tool-results/call_1.txt');
+  });
+
+  it('returns null when no persisted-output marker', () => {
+    expect(extractPersistedOutputPath('plain output')).toBeNull();
+  });
+
+  it('renders notification XML with attributes and body', () => {
+    const data: NotificationRecord['data'] = {
+      id: 'n1',
+      category: 'task',
+      type: 'tick',
+      source_kind: 'background_task',
+      source_id: 'bg-1',
+      title: 'Test',
+      body: 'Hello',
+      severity: 'info',
+      targets: ['llm'],
+    };
+    const xml = renderNotificationXml(data);
+    expect(xml).toContain('<notification id="n1"');
+    expect(xml).toContain('category="task"');
+    expect(xml).toContain('Title: Test');
+    expect(xml).toContain('Severity: info');
+    expect(xml).toContain('Hello');
+    expect(xml).toContain('</notification>');
+  });
+
+  it('includes synthetic system_reminder messages in the annotated stream', () => {
+    const reminder: SystemReminderRecord = {
+      type: 'system_reminder',
+      seq: 1,
+      time: 0,
+      content: 'please remember',
+    };
+    const records: VisWireRecord[] = [reminder];
+    const annotated = buildAnnotatedMessages(records);
+    expect(annotated).toHaveLength(1);
+    const m = annotated[0];
+    expect(m?.is_ephemeral).toBe(true);
+    expect(m?.origin.kind).toBe('system_reminder');
+    const content = m?.message.content[0];
+    if (content !== undefined && 'text' in content) {
+      expect(String(content['text'])).toContain('<system-reminder>');
+    }
+  });
+
+  it('includes llm-target notifications as ephemeral messages', () => {
+    const notif: NotificationRecord = {
+      type: 'notification',
+      seq: 2,
+      time: 0,
+      data: {
+        id: 'n2',
+        category: 'system',
+        type: 'info',
+        source_kind: 'system',
+        source_id: 's',
+        title: 't',
+        body: 'b',
+        severity: 'warning',
+        targets: ['llm'],
+      },
+    };
+    const annotated = buildAnnotatedMessages([notif]);
+    expect(annotated).toHaveLength(1);
+    const m = annotated[0];
+    expect(m?.origin.kind).toBe('notification');
+    if (m?.origin.kind === 'notification') {
+      expect(m.origin.severity).toBe('warning');
+    }
+    expect(m?.is_ephemeral).toBe(true);
+  });
+
+  it('drops notifications without llm in targets', () => {
+    const notif: NotificationRecord = {
+      type: 'notification',
+      seq: 2,
+      time: 0,
+      data: {
+        id: 'n3',
+        category: 'system',
+        type: 'info',
+        source_kind: 's',
+        source_id: 's',
+        title: 't',
+        body: 'b',
+        severity: 'info',
+        targets: ['wire'],
+      },
+    };
+    const annotated = buildAnnotatedMessages([notif]);
+    expect(annotated).toHaveLength(0);
+  });
+
+  it('drops notifications whose delivered_at.llm === 0', () => {
+    const notif: NotificationRecord = {
+      type: 'notification',
+      seq: 2,
+      time: 0,
+      data: {
+        id: 'n4',
+        category: 'system',
+        type: 'info',
+        source_kind: 's',
+        source_id: 's',
+        title: 't',
+        body: 'b',
+        severity: 'info',
+        targets: ['llm'],
+        delivered_at: { llm: 0 },
+      },
+    };
+    const annotated = buildAnnotatedMessages([notif]);
+    expect(annotated).toHaveLength(0);
+  });
+
+  it('marks rewind-orphaned messages as out_of_context', () => {
+    const records: VisWireRecord[] = [
+      {
+        type: 'turn_begin',
+        seq: 1,
+        time: 0,
+        turn_id: 't1',
+        agent_type: 'main',
+        input_kind: 'user',
+      },
+      { type: 'user_message', seq: 2, time: 0, turn_id: 't1', content: 'hi' },
+      {
+        type: 'turn_begin',
+        seq: 3,
+        time: 0,
+        turn_id: 't2',
+        agent_type: 'main',
+        input_kind: 'user',
+      },
+      { type: 'user_message', seq: 4, time: 0, turn_id: 't2', content: 'again' },
+      { type: 'context_edit', seq: 5, time: 0, operation: 'rewind', to_turn: 1 },
+    ];
+    const annotated = buildAnnotatedMessages(records);
+    expect(annotated).toHaveLength(2);
+    expect(annotated[0]?.out_of_context).toBe(false);
+    expect(annotated[1]?.out_of_context).toBe(true);
+  });
+
+  it('resets messages on context_cleared', () => {
+    const records: VisWireRecord[] = [
+      {
+        type: 'turn_begin',
+        seq: 1,
+        time: 0,
+        turn_id: 't1',
+        agent_type: 'main',
+        input_kind: 'user',
+      },
+      { type: 'user_message', seq: 2, time: 0, turn_id: 't1', content: 'hi' },
+      { type: 'context_cleared', seq: 3, time: 0 },
+      { type: 'user_message', seq: 4, time: 0, turn_id: 't1', content: 'after' },
+    ];
+    const annotated = buildAnnotatedMessages(records);
+    expect(annotated).toHaveLength(1);
+    const content = annotated[0]?.message.content[0];
+    if (content !== undefined && 'text' in content) {
+      expect(content['text']).toBe('after');
+    }
+  });
+
+  it('sets persisted_output_path when tool output references a file', () => {
+    const records: VisWireRecord[] = [
+      {
+        type: 'tool_result',
+        seq: 1,
+        time: 0,
+        turn_id: 't',
+        tool_call_id: 'Agent:1',
+        output:
+          '<persisted-output path="/tmp/ses_x/tool-results/Agent:1.txt">\npreview...\n</persisted-output>',
+      },
+    ];
+    const annotated = buildAnnotatedMessages(records);
+    expect(annotated[0]?.persisted_output_path).toBe('/tmp/ses_x/tool-results/Agent:1.txt');
+  });
+
+  it('coalesces step_begin / content_part / tool_call / step_end into one assistant message', async () => {
+    fixture = createSyntheticSession({ withTools: true });
+    const load = await loadWireRecords(fixture.dir);
+    const annotated = buildAnnotatedMessages(load.records);
+    const asst = annotated.filter((m) => m.origin.kind === 'assistant');
+    expect(asst.length).toBe(1);
+    const m = asst[0];
+    const text = m?.message.content.find((p) => p.type === 'text') as
+      | { type: 'text'; text: string }
+      | undefined;
+    expect(text?.text).toBe('hello!');
+    expect(m?.message.tool_calls).toHaveLength(1);
+    expect(m?.message.tool_calls[0]?.function.name).toBe('Bash');
+  });
+
+  it('builds correct origin tagging on a synthetic session with system_reminder', async () => {
+    fixture = createSyntheticSession({ withReminder: true });
+    const load = await loadWireRecords(fixture.dir);
+    const annotated = buildAnnotatedMessages(load.records);
+    const hasReminder = annotated.some((m) => m.origin.kind === 'system_reminder');
+    expect(hasReminder).toBe(true);
+    const hasUser = annotated.some((m) => m.origin.kind === 'user');
+    const hasAssistant = annotated.some((m) => m.origin.kind === 'assistant');
+    expect(hasUser).toBe(true);
+    expect(hasAssistant).toBe(true);
+  });
+
+  it('produces a projected state summary from a synthetic session', async () => {
+    fixture = createSyntheticSession({ withTools: true });
+    const load = await loadWireRecords(fixture.dir);
+    const projected = buildProjectedStateSummary(load.records, load.session_initialized);
+    expect(typeof projected.last_seq).toBe('number');
+    expect(typeof projected.token_count).toBe('number');
+    expect(Array.isArray(projected.active_tools)).toBe(true);
+    expect(projected.model).toBe('test-model');
+  });
+});
diff --git a/apps/vis/server/test/session-lister.test.ts b/apps/vis/server/test/session-lister.test.ts
new file mode 100644
index 000000000..e2123e952
--- /dev/null
+++ b/apps/vis/server/test/session-lister.test.ts
@@ -0,0 +1,116 @@
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { listSessions, loadSessionSummary } from '../src/lib/session-lister';
+import { createSyntheticSession, type SyntheticResult } from './_fixture';
+
+describe('session-lister', () => {
+  let fixture: SyntheticResult | null = null;
+  const fixtureRoots: string[] = [];
+
+  afterEach(() => {
+    fixture?.cleanup();
+    fixture = null;
+    // Cleanup enumeration roots from the second test
+    for (const root of fixtureRoots) {
+      try {
+        rmSync(root, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+    }
+    fixtureRoots.length = 0;
+  });
+
+  it('loads a single SessionSummary from a synthetic session dir', async () => {
+    fixture = createSyntheticSession({ withSubagent: true });
+    const summary = await loadSessionSummary(fixture.dir);
+    expect(summary.session_id).toBe(fixture.sessionId);
+    expect(summary.model).toBe('test-model');
+    expect(summary.workspace_dir).toBe('/tmp');
+    expect(summary.subagent_count).toBe(1);
+    expect(summary.wire_protocol_version).toBe('1.0');
+    expect(summary.wire_record_count).toBeGreaterThan(0);
+    expect(summary.health).toBe('ok');
+  });
+
+  it('enumerates session_* subdirs and sorts by updated_at desc', async () => {
+    const root = join(tmpdir(), `vis-list-${randomBytes(4).toString('hex')}`);
+    mkdirSync(root, { recursive: true });
+    fixtureRoots.push(root);
+
+    // Seed three synthetic sessions with staggered updated_at
+    for (let i = 0; i < 3; i += 1) {
+      const sessionId = `session_${randomBytes(6).toString('hex')}`;
+      const dir = join(root, sessionId);
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(
+        join(dir, 'wire.jsonl'),
+        JSON.stringify({
+          type: 'metadata',
+          protocol_version: '1.0',
+          created_at: Date.now(),
+          producer: { kind: 'typescript', name: '@moonshot-ai/agent-core', version: '0.0.1' },
+        }) + '\n',
+      );
+      writeFileSync(
+        join(dir, 'state.json'),
+        JSON.stringify({
+          session_id: sessionId,
+          model: 'test-model',
+          status: 'idle',
+          created_at: Date.now() - i * 1000,
+          updated_at: Date.now() - i * 1000,
+          workspace_dir: '/tmp',
+          producer: { kind: 'typescript', name: '@moonshot-ai/agent-core', version: '0.0.1' },
+        }),
+      );
+    }
+
+    // Drop a non-session_* entry to verify it is ignored
+    writeFileSync(join(root, 'random-file.txt'), 'x');
+
+    // Drop a session_* dir with a non-TS producer — must be filtered out
+    const pySessionId = `session_${randomBytes(6).toString('hex')}`;
+    const pyDir = join(root, pySessionId);
+    mkdirSync(pyDir, { recursive: true });
+    writeFileSync(join(pyDir, 'wire.jsonl'), '{}\n');
+    writeFileSync(
+      join(pyDir, 'state.json'),
+      JSON.stringify({
+        session_id: pySessionId,
+        created_at: Date.now(),
+        updated_at: Date.now(),
+        producer: { kind: 'python', name: 'kimi-cli', version: '0.9.0' },
+      }),
+    );
+
+    // Drop a session_* dir with no state.json — must be filtered out
+    const oldSessionId = `session_${randomBytes(6).toString('hex')}`;
+    const oldDir = join(root, oldSessionId);
+    mkdirSync(oldDir, { recursive: true });
+    writeFileSync(join(oldDir, 'wire.jsonl'), '{}\n');
+
+    const summaries = await listSessions(root);
+    expect(summaries.length).toBe(3);
+    // None of the filtered sessions should have leaked through.
+    expect(summaries.some((s) => s.session_id === pySessionId)).toBe(false);
+    expect(summaries.some((s) => s.session_id === oldSessionId)).toBe(false);
+    for (const s of summaries) {
+      expect(s.session_id.startsWith('session_')).toBe(true);
+    }
+    for (let i = 1; i < summaries.length; i += 1) {
+      const prev = summaries[i - 1];
+      const cur = summaries[i];
+      if (prev === undefined || cur === undefined) continue;
+      expect(prev.updated_at).toBeGreaterThanOrEqual(cur.updated_at);
+    }
+    for (const s of summaries) {
+      expect(['ok', 'broken', 'missing_wire']).toContain(s.health);
+    }
+  });
+});
diff --git a/apps/vis/server/test/subagent-loader.test.ts b/apps/vis/server/test/subagent-loader.test.ts
new file mode 100644
index 000000000..978e621a8
--- /dev/null
+++ b/apps/vis/server/test/subagent-loader.test.ts
@@ -0,0 +1,47 @@
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { buildSubagentTree, listSubagents } from '../src/lib/subagent-loader';
+import { loadWireRecords } from '../src/lib/wire-loader';
+import { createSyntheticSession, type SyntheticResult } from './_fixture';
+
+describe('subagent-loader', () => {
+  let fixture: SyntheticResult | null = null;
+  afterEach(() => {
+    fixture?.cleanup();
+    fixture = null;
+  });
+
+  it('lists subagent ids for a session with subagents', async () => {
+    fixture = createSyntheticSession({ withSubagent: true });
+    const ids = await listSubagents(fixture.dir);
+    expect(ids.length).toBe(1);
+    expect(ids[0]?.startsWith('sub_')).toBe(true);
+  });
+
+  it('builds a tree rooted at main', async () => {
+    fixture = createSyntheticSession({ withSubagent: true });
+    const main = await loadWireRecords(fixture.dir);
+    const tree = await buildSubagentTree(fixture.dir, main.records);
+    expect(tree.length).toBe(1);
+    const node = tree[0];
+    expect(node?.depth).toBe(0);
+    expect(node?.agent_id.startsWith('sub_')).toBe(true);
+    expect(node?.parent_agent_id).toBeNull();
+  });
+
+  it('pairs spawn with completed lifecycle records', async () => {
+    fixture = createSyntheticSession({ withSubagent: true });
+    const main = await loadWireRecords(fixture.dir);
+    const tree = await buildSubagentTree(fixture.dir, main.records);
+    const node = tree[0];
+    expect(node?.status).toBe('completed');
+    expect(node?.result_summary).toBe('all done');
+  });
+
+  it('returns empty tree for sessions without subagents', async () => {
+    fixture = createSyntheticSession();
+    const main = await loadWireRecords(fixture.dir);
+    const tree = await buildSubagentTree(fixture.dir, main.records);
+    expect(tree).toHaveLength(0);
+  });
+});
diff --git a/apps/vis/server/test/wire-loader.test.ts b/apps/vis/server/test/wire-loader.test.ts
new file mode 100644
index 000000000..c1b3357d2
--- /dev/null
+++ b/apps/vis/server/test/wire-loader.test.ts
@@ -0,0 +1,558 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, it, afterEach } from 'vitest';
+
+import { listWireFilesManually, loadWireRecords } from '../src/lib/wire-loader';
+import { createSyntheticSession, type SyntheticResult } from './_fixture';
+
+describe('wire-loader', () => {
+  let fixture: SyntheticResult | null = null;
+  afterEach(() => {
+    fixture?.cleanup();
+    fixture = null;
+  });
+
+  it('lists wire.jsonl after any archives, current file last', async () => {
+    fixture = createSyntheticSession();
+    const files = await listWireFilesManually(fixture.dir);
+    expect(files.length).toBeGreaterThan(0);
+    expect((files.at(-1) ?? '').endsWith('wire.jsonl')).toBe(true);
+  });
+
+  it('loads records from a synthetic session', async () => {
+    fixture = createSyntheticSession({ withTools: true });
+    const result = await loadWireRecords(fixture.dir);
+    expect(result.health).toBe('ok');
+    expect(result.records.length).toBeGreaterThan(0);
+    expect(result.files_read.length).toBe(1);
+    expect(result.session_initialized).not.toBeNull();
+    expect(result.session_initialized?.agent_type).toBe('main');
+  });
+
+  it('yields seq-ordered records', async () => {
+    fixture = createSyntheticSession({ withTools: true });
+    const result = await loadWireRecords(fixture.dir);
+    for (let i = 1; i < result.records.length; i += 1) {
+      const prev = result.records[i - 1];
+      const cur = result.records[i];
+      if (prev === undefined || cur === undefined) continue;
+      expect(cur.seq).toBeGreaterThanOrEqual(prev.seq);
+    }
+  });
+
+  it('splices metadata + session_initialized into records so the Wire tab can show them', async () => {
+    fixture = createSyntheticSession();
+    const result = await loadWireRecords(fixture.dir);
+    expect(result.health).toBe('ok');
+    // metadata comes first, session_initialized second.
+    expect(result.records[0]?.type).toBe('metadata');
+    expect(result.records[1]?.type).toBe('session_initialized');
+    const meta = result.records[0] as {
+      protocol_version?: string;
+      producer?: { kind?: string };
+    };
+    expect(meta.protocol_version).toBe('1.0');
+    expect(meta.producer?.kind).toBe('typescript');
+    const init = result.records[1] as { system_prompt?: string };
+    expect(init.system_prompt).toBe('You are a test assistant.');
+  });
+
+  it('returns health=broken with a message for a non-existent dir', async () => {
+    const result = await loadWireRecords('/tmp/vis-test-does-not-exist-xxxxx');
+    expect(result.health).toBe('broken');
+    expect(result.records.length).toBe(0);
+    expect(result.broken_reason).toBeTruthy();
+    expect(result.session_initialized).toBeNull();
+  });
+
+  it('treats idle turn.steer as a turn start without splitting active steer', async () => {
+    fixture = createSyntheticSession();
+    writeWire(fixture.dir, [
+      {
+        type: 'metadata',
+        protocol_version: '1.0',
+        created_at: 1,
+        producer: {
+          kind: 'typescript',
+          name: '@moonshot-ai/agent-core',
+          version: '0.0.1',
+        },
+      },
+      {
+        type: 'session_initialized',
+        seq: 1,
+        time: 1,
+        agent_type: 'main',
+        session_id: fixture.sessionId,
+        system_prompt: 'You are a test assistant.',
+        model: 'test-model',
+        active_tools: [],
+      },
+      {
+        type: 'turn.prompt',
+        seq: 2,
+        time: 2,
+        input: [{ type: 'text', text: 'first' }],
+      },
+      {
+        type: 'context.user_message',
+        seq: 3,
+        time: 3,
+        content: [{ type: 'text', text: 'first' }],
+      },
+      {
+        type: 'context.delta',
+        seq: 4,
+        time: 4,
+        event: { type: 'step.begin', uuid: 'step-1', turnId: '0', step: 1 },
+      },
+      {
+        type: 'turn.steer',
+        seq: 5,
+        time: 5,
+        input: [{ type: 'text', text: 'active steer' }],
+      },
+      {
+        type: 'context.delta',
+        seq: 6,
+        time: 6,
+        event: { type: 'step.end', uuid: 'step-1', turnId: '0', step: 1, finishReason: 'tool_use' },
+      },
+      {
+        type: 'context.user_message',
+        seq: 7,
+        time: 7,
+        content: [{ type: 'text', text: 'active steer' }],
+      },
+      {
+        type: 'context.delta',
+        seq: 8,
+        time: 8,
+        event: { type: 'step.begin', uuid: 'step-2', turnId: '0', step: 2 },
+      },
+      {
+        type: 'context.delta',
+        seq: 9,
+        time: 9,
+        event: { type: 'step.end', uuid: 'step-2', turnId: '0', step: 2, finishReason: 'end_turn' },
+      },
+      {
+        type: 'turn.steer',
+        seq: 10,
+        time: 10,
+        input: [{ type: 'text', text: 'terminal gap steer' }],
+      },
+      {
+        type: 'context.user_message',
+        seq: 11,
+        time: 11,
+        content: [{ type: 'text', text: 'terminal gap steer' }],
+      },
+      {
+        type: 'context.delta',
+        seq: 12,
+        time: 12,
+        event: { type: 'step.begin', uuid: 'step-3', turnId: '0', step: 3 },
+      },
+      {
+        type: 'context.delta',
+        seq: 13,
+        time: 13,
+        event: { type: 'step.end', uuid: 'step-3', turnId: '0', step: 3, finishReason: 'end_turn' },
+      },
+      {
+        type: 'turn.steer',
+        seq: 14,
+        time: 14,
+        input: [{ type: 'text', text: 'idle steer' }],
+      },
+      {
+        type: 'context.user_message',
+        seq: 15,
+        time: 15,
+        content: [{ type: 'text', text: 'idle steer' }],
+      },
+      {
+        type: 'context.delta',
+        seq: 16,
+        time: 16,
+        event: { type: 'step.begin', uuid: 'step-4', turnId: '1', step: 1 },
+      },
+      {
+        type: 'context.delta',
+        seq: 17,
+        time: 17,
+        event: {
+          type: 'tool.result',
+          parentUuid: 'tool-1',
+          toolCallId: 'tool-1',
+          result: { output: 'idle result' },
+        },
+      },
+    ]);
+
+    const result = await loadWireRecords(fixture.dir);
+    const turnBegins = result.records.filter((record) => record.type === 'turn_begin');
+    const userMessages = result.records.filter((record) => record.type === 'user_message');
+    const toolResult = result.records.find((record) => record.type === 'tool_result');
+
+    expect(turnBegins.map((record) => [record.turn_id, record.user_input])).toEqual([
+      ['0', 'first'],
+      ['1', 'idle steer'],
+    ]);
+    expect(userMessages.map((record) => record.turn_id)).toEqual(['0', '0', '0', '1']);
+    expect(toolResult).toMatchObject({ turn_id: '1' });
+  });
+
+  it('treats idle turn.steer after a failed pre-step turn as a new turn', async () => {
+    fixture = createSyntheticSession();
+    writeWire(fixture.dir, [
+      {
+        type: 'metadata',
+        protocol_version: '1.0',
+        created_at: 1,
+        producer: {
+          kind: 'typescript',
+          name: '@moonshot-ai/agent-core',
+          version: '0.0.1',
+        },
+      },
+      {
+        type: 'session_initialized',
+        seq: 1,
+        time: 1,
+        agent_type: 'main',
+        session_id: fixture.sessionId,
+        system_prompt: 'You are a test assistant.',
+        active_tools: [],
+      },
+      {
+        type: 'turn.prompt',
+        seq: 2,
+        time: 2,
+        input: [{ type: 'text', text: 'missing model' }],
+      },
+      {
+        type: 'context.user_message',
+        seq: 3,
+        time: 3,
+        content: [{ type: 'text', text: 'missing model' }],
+      },
+      {
+        type: 'turn.steer',
+        seq: 4,
+        time: 4,
+        input: [{ type: 'text', text: 'after failure' }],
+      },
+      {
+        type: 'context.user_message',
+        seq: 5,
+        time: 5,
+        content: [{ type: 'text', text: 'after failure' }],
+      },
+      {
+        type: 'context.delta',
+        seq: 6,
+        time: 6,
+        event: { type: 'step.begin', uuid: 'step-1', turnId: '1', step: 1 },
+      },
+    ]);
+
+    const result = await loadWireRecords(fixture.dir);
+    const turnBegins = result.records.filter((record) => record.type === 'turn_begin');
+    const userMessages = result.records.filter((record) => record.type === 'user_message');
+
+    expect(turnBegins.map((record) => [record.turn_id, record.user_input])).toEqual([
+      ['0', 'missing model'],
+      ['1', 'after failure'],
+    ]);
+    expect(userMessages.map((record) => record.turn_id)).toEqual(['0', '1']);
+  });
+  it('unwraps the newer dot-namespaced record names (append_loop_event, append_message, set_active_tools)', async () => {
+    fixture = createSyntheticSession();
+    writeWire(fixture.dir, [
+      {
+        type: 'metadata',
+        protocol_version: '1.0',
+        created_at: 1,
+        producer: { kind: 'typescript', name: '@moonshot-ai/core', version: '0.0.1' },
+      },
+      {
+        type: 'session_initialized',
+        seq: 1,
+        time: 1,
+        agent_type: 'main',
+        session_id: fixture.sessionId,
+        system_prompt: 'You are a test assistant.',
+        active_tools: [],
+      },
+      {
+        type: 'turn.prompt',
+        seq: 2,
+        time: 2,
+        input: [{ type: 'text', text: 'hi' }],
+      },
+      {
+        type: 'context.append_message',
+        seq: 3,
+        time: 3,
+        message: { role: 'user', content: [{ type: 'text', text: 'hi' }] },
+      },
+      {
+        type: 'tools.set_active_tools',
+        seq: 4,
+        time: 4,
+        names: ['Read', 'Write', 'Bash'],
+      },
+      {
+        type: 'context.append_loop_event',
+        seq: 5,
+        time: 5,
+        event: { type: 'step.begin', uuid: 'step-1', turnId: '0', step: 1 },
+      },
+      {
+        type: 'context.append_loop_event',
+        seq: 6,
+        time: 6,
+        event: {
+          type: 'tool.call',
+          uuid: 'tc-1',
+          turnId: '0',
+          step: 1,
+          stepUuid: 'step-1',
+          toolCallId: 'call-1',
+          name: 'Write',
+          args: { path: '/tmp/x', content: 'hello' },
+        },
+      },
+      {
+        type: 'context.append_loop_event',
+        seq: 7,
+        time: 7,
+        event: { type: 'step.end', uuid: 'step-1', turnId: '0', step: 1, finishReason: 'tool_use' },
+      },
+    ]);
+
+    const result = await loadWireRecords(fixture.dir);
+    expect(result.health).toBe('ok');
+    const types = result.records.map((r) => r.type);
+    expect(types).toContain('turn_begin');
+    expect(types).toContain('user_message');
+    expect(types).toContain('tools_changed');
+    expect(types).toContain('step_begin');
+    expect(types).toContain('tool_call');
+    expect(types).toContain('step_end');
+    expect(types).not.toContain('notification');
+
+    const toolCall = result.records.find((r) => r.type === 'tool_call');
+    expect(toolCall).toMatchObject({ turn_id: '0', data: { tool_name: 'Write' } });
+    const toolsChanged = result.records.find((r) => r.type === 'tools_changed');
+    expect(toolsChanged).toMatchObject({ operation: 'set_active', tools: ['Read', 'Write', 'Bash'] });
+  });
+
+  // The newer `context.append_message` producer carries assistant /
+  // system roles too. Without a role filter, inferSteerStartedTurnId
+  // would see any append_message in the lookahead window and conclude
+  // that the steer launched a fresh turn, fabricating a turn id.
+  it('ignores non-user append_message when inferring whether a turn.steer launched a fresh turn', async () => {
+    fixture = createSyntheticSession();
+    writeWire(fixture.dir, [
+      {
+        type: 'metadata',
+        protocol_version: '1.0',
+        created_at: 1,
+        producer: { kind: 'typescript', name: '@moonshot-ai/core', version: '0.0.1' },
+      },
+      {
+        type: 'session_initialized',
+        seq: 1,
+        time: 1,
+        agent_type: 'main',
+        session_id: fixture.sessionId,
+        system_prompt: 'You are a test assistant.',
+        active_tools: [],
+      },
+      {
+        type: 'turn.prompt',
+        seq: 2,
+        time: 2,
+        input: [{ type: 'text', text: 'first' }],
+      },
+      {
+        type: 'context.append_message',
+        seq: 3,
+        time: 3,
+        message: { role: 'user', content: [{ type: 'text', text: 'first' }] },
+      },
+      {
+        type: 'context.append_loop_event',
+        seq: 4,
+        time: 4,
+        event: { type: 'step.begin', uuid: 'step-1', turnId: '0', step: 1 },
+      },
+      // Steer arrives during an active turn (no later loop event reveals
+      // a new turnId, no later user message follows). Only an assistant
+      // append_message lands in the lookahead window.
+      {
+        type: 'turn.steer',
+        seq: 5,
+        time: 5,
+        input: [{ type: 'text', text: 'buffered steer' }],
+      },
+      {
+        type: 'context.append_message',
+        seq: 6,
+        time: 6,
+        message: { role: 'assistant', content: [{ type: 'text', text: 'thinking out loud' }] },
+      },
+    ]);
+
+    const result = await loadWireRecords(fixture.dir);
+    const turnBegins = result.records.filter((record) => record.type === 'turn_begin');
+    // Only the original turn.prompt should produce a turn_begin. The
+    // steer must stay buffered because the lookahead contains no user
+    // message — assistant append_messages don't count.
+    expect(turnBegins.map((record) => record.turn_id)).toEqual(['0']);
+  });
+
+  // ContextMemory.appendSystemReminder() persists injected reminders /
+  // skill activations / system triggers as role: 'user' messages for the
+  // LLM, but their origin.kind is not 'user'. Replay must not surface
+  // these as user_message records or count them when inferring whether
+  // a turn.steer launched a fresh turn.
+  it('does not surface non-user-origin append_message as user_message', async () => {
+    fixture = createSyntheticSession();
+    writeWire(fixture.dir, [
+      {
+        type: 'metadata',
+        protocol_version: '1.0',
+        created_at: 1,
+        producer: { kind: 'typescript', name: '@moonshot-ai/core', version: '0.0.1' },
+      },
+      {
+        type: 'session_initialized',
+        seq: 1,
+        time: 1,
+        agent_type: 'main',
+        session_id: fixture.sessionId,
+        system_prompt: 'You are a test assistant.',
+        active_tools: [],
+      },
+      {
+        type: 'turn.prompt',
+        seq: 2,
+        time: 2,
+        input: [{ type: 'text', text: 'hi' }],
+      },
+      {
+        type: 'context.append_message',
+        seq: 3,
+        time: 3,
+        message: {
+          role: 'user',
+          content: [{ type: 'text', text: 'hi' }],
+          origin: { kind: 'user' },
+        },
+      },
+      // System reminder: role: 'user' for the LLM, but origin.kind says
+      // it's an injection, not a real user message.
+      {
+        type: 'context.append_message',
+        seq: 4,
+        time: 4,
+        message: {
+          role: 'user',
+          content: [{ type: 'text', text: '<system-reminder>be careful</system-reminder>' }],
+          origin: { kind: 'injection', variant: 'safety' },
+        },
+      },
+      // Skill activation payload: also role: 'user' under the hood.
+      {
+        type: 'context.append_message',
+        seq: 5,
+        time: 5,
+        message: {
+          role: 'user',
+          content: [{ type: 'text', text: 'skill bootstrap' }],
+          origin: { kind: 'skill_activation', activationId: 'a1', skillName: 'plan', trigger: 'user-slash' },
+        },
+      },
+    ]);
+
+    const result = await loadWireRecords(fixture.dir);
+    const userMessages = result.records.filter((record) => record.type === 'user_message');
+    // Only the real user message at seq 3 should surface — the injection
+    // and skill_activation entries must not show as user_message.
+    expect(userMessages.map((record) => record.seq)).toEqual([3]);
+  });
+
+  it('ignores non-user-origin append_message when inferring whether a turn.steer launched a fresh turn', async () => {
+    fixture = createSyntheticSession();
+    writeWire(fixture.dir, [
+      {
+        type: 'metadata',
+        protocol_version: '1.0',
+        created_at: 1,
+        producer: { kind: 'typescript', name: '@moonshot-ai/core', version: '0.0.1' },
+      },
+      {
+        type: 'session_initialized',
+        seq: 1,
+        time: 1,
+        agent_type: 'main',
+        session_id: fixture.sessionId,
+        system_prompt: 'You are a test assistant.',
+        active_tools: [],
+      },
+      {
+        type: 'turn.prompt',
+        seq: 2,
+        time: 2,
+        input: [{ type: 'text', text: 'first' }],
+      },
+      {
+        type: 'context.append_message',
+        seq: 3,
+        time: 3,
+        message: { role: 'user', content: [{ type: 'text', text: 'first' }], origin: { kind: 'user' } },
+      },
+      {
+        type: 'context.append_loop_event',
+        seq: 4,
+        time: 4,
+        event: { type: 'step.begin', uuid: 'step-1', turnId: '0', step: 1 },
+      },
+      {
+        type: 'turn.steer',
+        seq: 5,
+        time: 5,
+        input: [{ type: 'text', text: 'buffered steer' }],
+      },
+      // Injected system reminder lands in the lookahead window. It has
+      // role: 'user' but origin.kind: 'system_trigger', so it must NOT
+      // count as evidence of a user-launched fresh turn.
+      {
+        type: 'context.append_message',
+        seq: 6,
+        time: 6,
+        message: {
+          role: 'user',
+          content: [{ type: 'text', text: '<system-reminder>focus</system-reminder>' }],
+          origin: { kind: 'system_trigger', name: 'focus-reminder' },
+        },
+      },
+    ]);
+
+    const result = await loadWireRecords(fixture.dir);
+    const turnBegins = result.records.filter((record) => record.type === 'turn_begin');
+    expect(turnBegins.map((record) => record.turn_id)).toEqual(['0']);
+  });
+});
+
+function writeWire(dir: string, records: readonly Record<string, unknown>[]): void {
+  writeFileSync(
+    join(dir, 'wire.jsonl'),
+    `${records.map((record) => JSON.stringify(record)).join('\n')}\n`,
+  );
+}
diff --git a/apps/vis/server/tsconfig.json b/apps/vis/server/tsconfig.json
new file mode 100644
index 000000000..1d7a4c2a9
--- /dev/null
+++ b/apps/vis/server/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../../tsconfig.json",
+  "include": ["src", "test"]
+}
diff --git a/apps/vis/server/tsdown.config.ts b/apps/vis/server/tsdown.config.ts
new file mode 100644
index 000000000..6e618ca51
--- /dev/null
+++ b/apps/vis/server/tsdown.config.ts
@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: { server: 'src/index.ts' },
+  format: ['esm'],
+  outDir: 'dist',
+  clean: true,
+  external: ['@moonshot-ai/agent-core', '@moonshot-ai/kosong', '@moonshot-ai/kaos'],
+});
diff --git a/apps/vis/server/vitest.config.ts b/apps/vis/server/vitest.config.ts
new file mode 100644
index 000000000..0131797f1
--- /dev/null
+++ b/apps/vis/server/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    name: 'vis-server',
+    include: ['test/**/*.test.ts'],
+  },
+});
diff --git a/apps/vis/web/index.html b/apps/vis/web/index.html
new file mode 100644
index 000000000..070aafc9b
--- /dev/null
+++ b/apps/vis/web/index.html
@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <meta name="color-scheme" content="light dark" />
+    <meta name="theme-color" content="#0b0d12" />
+    <title>kimi vis</title>
+    <!-- Pre-paint: resolve saved theme (or system preference) and set
+         data-theme before React hydrates, to avoid a flash of the wrong
+         palette. Kept tiny to not block render. -->
+    <script>
+      (function () {
+        try {
+          var v = localStorage.getItem('vis.theme');
+          var t =
+            v === 'light' || v === 'dark'
+              ? v
+              : window.matchMedia('(prefers-color-scheme: light)').matches
+                ? 'light'
+                : 'dark';
+          document.documentElement.setAttribute('data-theme', t);
+        } catch (_) {
+          document.documentElement.setAttribute('data-theme', 'dark');
+        }
+      })();
+    </script>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600&family=JetBrains+Mono:wght@400;500;600&display=swap"
+      rel="stylesheet"
+    />
+  </head>
+  <body class="antialiased">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/apps/vis/web/package.json b/apps/vis/web/package.json
new file mode 100644
index 000000000..2146e568f
--- /dev/null
+++ b/apps/vis/web/package.json
@@ -0,0 +1,39 @@
+{
+  "name": "@moonshot-ai/vis-web",
+  "version": "0.1.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "imports": {
+    "#/*": {
+      "types": [
+        "./src/*.ts",
+        "./src/*.tsx",
+        "./src/*/index.ts",
+        "./src/*/index.tsx"
+      ],
+      "default": "./src/*"
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.74.4",
+    "@tanstack/react-virtual": "^3.13.5",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "react-router-dom": "^7.5.2"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.1.4",
+    "@types/react": "^19.1.2",
+    "@types/react-dom": "^19.1.2",
+    "@vitejs/plugin-react": "^4.4.1",
+    "tailwindcss": "^4.1.4",
+    "typescript": "6.0.2",
+    "vite": "^6.3.3"
+  }
+}
diff --git a/apps/vis/web/src/App.tsx b/apps/vis/web/src/App.tsx
new file mode 100644
index 000000000..4843b677c
--- /dev/null
+++ b/apps/vis/web/src/App.tsx
@@ -0,0 +1,20 @@
+import { Route, Routes } from 'react-router-dom';
+import { AppShell } from './components/layout/AppShell';
+import { SessionListPage } from './pages/SessionListPage';
+import { SessionDetailPage } from './pages/SessionDetailPage';
+import { SubagentDetailPage } from './pages/SubagentDetailPage';
+
+export function App() {
+  return (
+    <AppShell>
+      <Routes>
+        <Route path="/" element={<SessionListPage />} />
+        <Route path="/sessions/:sessionId" element={<SessionDetailPage />} />
+        <Route
+          path="/sessions/:sessionId/subagents/:agentId"
+          element={<SubagentDetailPage />}
+        />
+      </Routes>
+    </AppShell>
+  );
+}
diff --git a/apps/vis/web/src/api.ts b/apps/vis/web/src/api.ts
new file mode 100644
index 000000000..66346694a
--- /dev/null
+++ b/apps/vis/web/src/api.ts
@@ -0,0 +1,119 @@
+import type {
+  SessionSummary,
+  SessionDetail,
+  WireResponse,
+  ContextResponse,
+  SubagentTreeResponse,
+  SubagentMetaResponse,
+  ToolResultFileResponse,
+  DeleteSessionResponse,
+  ClearSessionsResponse,
+  ApiError,
+} from './types';
+
+const TOKEN_STORAGE_KEY = 'kimi-vis-auth-token';
+
+function readTokenParam(raw: string): string | null {
+  const trimmed = raw.replace(/^[#?]/, '');
+  if (trimmed.length === 0) return null;
+  const params = new URLSearchParams(trimmed);
+  return params.get('token') ?? params.get('vis_token');
+}
+
+function deleteTokenParams(params: URLSearchParams): boolean {
+  const hadToken = params.has('token') || params.has('vis_token');
+  params.delete('token');
+  params.delete('vis_token');
+  return hadToken;
+}
+
+function scrubTokenFromUrl(): void {
+  const url = new URL(window.location.href);
+  const changedSearch = deleteTokenParams(url.searchParams);
+  const hash = url.hash.replace(/^#/, '');
+  let changedHash = false;
+  if (hash.length > 0) {
+    const hashParams = new URLSearchParams(hash);
+    changedHash = deleteTokenParams(hashParams);
+    if (changedHash) {
+      const nextHash = hashParams.toString();
+      url.hash = nextHash.length > 0 ? nextHash : '';
+    }
+  }
+  if (changedSearch || changedHash) {
+    window.history.replaceState(null, '', url.toString());
+  }
+}
+
+function authToken(): string | null {
+  if (typeof window === 'undefined') return null;
+  const fromHash = readTokenParam(window.location.hash);
+  const fromSearch = readTokenParam(window.location.search);
+  const token = fromHash ?? fromSearch;
+  if (token !== null && token.length > 0) {
+    window.localStorage.setItem(TOKEN_STORAGE_KEY, token);
+    scrubTokenFromUrl();
+    return token;
+  }
+  return window.localStorage.getItem(TOKEN_STORAGE_KEY);
+}
+
+async function request<T>(path: string, method: 'GET' | 'DELETE'): Promise<T> {
+  const headers: Record<string, string> = { accept: 'application/json' };
+  const token = authToken();
+  if (token !== null && token.length > 0) {
+    headers['authorization'] = `Bearer ${token}`;
+  }
+  const res = await fetch(path, { method, headers });
+  if (!res.ok) {
+    let err: ApiError | null = null;
+    try {
+      err = (await res.json()) as ApiError;
+    } catch {
+      /* ignore */
+    }
+    throw new Error(err?.error ?? `HTTP ${res.status} ${res.statusText}`);
+  }
+  return (await res.json()) as T;
+}
+
+function get<T>(path: string): Promise<T> {
+  return request<T>(path, 'GET');
+}
+
+function del<T>(path: string): Promise<T> {
+  return request<T>(path, 'DELETE');
+}
+
+const enc = encodeURIComponent;
+
+export const api = {
+  listSessions: () => get<SessionSummary[]>('/api/sessions'),
+
+  getSession: (id: string) => get<SessionDetail>(`/api/sessions/${enc(id)}`),
+
+  deleteSession: (id: string) => del<DeleteSessionResponse>(`/api/sessions/${enc(id)}`),
+
+  clearSessions: () => del<ClearSessionsResponse>('/api/sessions'),
+
+  getWire: (id: string) => get<WireResponse>(`/api/sessions/${enc(id)}/wire`),
+
+  getContext: (id: string) => get<ContextResponse>(`/api/sessions/${enc(id)}/context`),
+
+  getSubagents: (id: string) => get<SubagentTreeResponse>(`/api/sessions/${enc(id)}/subagents`),
+
+  getSubagentWire: (id: string, agentId: string) =>
+    get<WireResponse>(`/api/sessions/${enc(id)}/subagents/${enc(agentId)}/wire`),
+
+  getSubagentContext: (id: string, agentId: string) =>
+    get<ContextResponse>(`/api/sessions/${enc(id)}/subagents/${enc(agentId)}/context`),
+
+  getSubagentMeta: (id: string, agentId: string) =>
+    get<SubagentMetaResponse>(`/api/sessions/${enc(id)}/subagents/${enc(agentId)}/meta`),
+
+  getToolResult: (id: string, toolCallId: string) =>
+    get<ToolResultFileResponse>(`/api/sessions/${enc(id)}/tool-results/${enc(toolCallId)}`),
+
+  getArchive: (id: string, filename: string) =>
+    get<WireResponse>(`/api/sessions/${enc(id)}/archives/${enc(filename)}`),
+};
diff --git a/apps/vis/web/src/components/context/CompactionRibbon.tsx b/apps/vis/web/src/components/context/CompactionRibbon.tsx
new file mode 100644
index 000000000..ca0a0f8cb
--- /dev/null
+++ b/apps/vis/web/src/components/context/CompactionRibbon.tsx
@@ -0,0 +1,28 @@
+interface CompactionRibbonProps {
+  summary: string;
+  seq: number;
+}
+
+/**
+ * Horizontal ribbon marker where a compaction occurred in the message stream.
+ * Derivation is best-effort from the annotated message stream; if a compaction
+ * was applied, buildAnnotatedMessages emits a summary assistant message. We
+ * detect the prior "break" via seq discontinuity, but for now we render a
+ * stand-alone banner wherever the caller places it.
+ */
+export function CompactionRibbon({ summary, seq }: CompactionRibbonProps) {
+  return (
+    <div className="my-3 flex items-center gap-3">
+      <span className="h-px flex-1 bg-[var(--color-compaction)] opacity-50" />
+      <span className="font-mono text-[11px] uppercase tracking-[0.12em] text-[var(--color-compaction)]">
+        ⏪ compacted · seq {seq}
+      </span>
+      <span className="h-px flex-1 bg-[var(--color-compaction)] opacity-50" />
+      {summary ? (
+        <div className="mt-2 text-fg-2">
+          <pre className="whitespace-pre-wrap font-mono text-[12px]">{summary}</pre>
+        </div>
+      ) : null}
+    </div>
+  );
+}
diff --git a/apps/vis/web/src/components/context/ContextTab.tsx b/apps/vis/web/src/components/context/ContextTab.tsx
new file mode 100644
index 000000000..cedb1fcfd
--- /dev/null
+++ b/apps/vis/web/src/components/context/ContextTab.tsx
@@ -0,0 +1,281 @@
+import { useState } from 'react';
+
+import type { AnnotatedMessage, ProjectedStateSummary } from '../../types';
+import { Pill } from '../shared/Pill';
+import { formatBytes } from '../shared/SizePreview';
+import { EphemeralBubble } from './EphemeralBubble';
+import { MessageBubble } from './MessageBubble';
+
+interface ContextTabProps {
+  sessionId: string;
+  messages: AnnotatedMessage[];
+  projectedState: ProjectedStateSummary;
+}
+
+export function ContextTab({ sessionId, messages, projectedState }: ContextTabProps) {
+  const [hideOutOfContext, setHideOutOfContext] = useState(false);
+
+  const visible = hideOutOfContext ? messages.filter((m) => !m.out_of_context) : messages;
+
+  const stats = countKinds(messages);
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      {/* Header strip */}
+      <div className="flex shrink-0 items-center gap-3 bg-surface-1 px-3 py-2 font-mono text-[11px] text-fg-2">
+        <span className="tabular text-fg-0">{messages.length}</span>
+        <span>messages</span>
+        <span className="text-fg-3">·</span>
+        <span>model</span>
+        <span className="text-fg-0">{projectedState.model ?? 'unknown'}</span>
+        <span className="text-fg-3">·</span>
+        <TokenDots breakdown={projectedState} />
+        <span className="ml-auto flex items-center gap-3">
+          <LegendDot color="var(--color-user)" label="user" count={stats.user} />
+          <LegendDot color="var(--color-assistant)" label="asst" count={stats.assistant} />
+          <LegendDot color="var(--color-tool)" label="tool" count={stats.tool} />
+          <LegendDot color="var(--color-cat-ephemeral)" label="reminder" count={stats.reminder} />
+          <LegendDot color="var(--color-cat-meta)" label="notif" count={stats.notif} />
+          <label className="flex items-center gap-1 text-fg-2 hover:text-fg-1">
+            <input
+              type="checkbox"
+              checked={hideOutOfContext}
+              onChange={(e) =>{  setHideOutOfContext(e.target.checked); }}
+              className="accent-[var(--color-cat-conversation)]"
+            />
+            hide out-of-context
+          </label>
+        </span>
+      </div>
+      {/* Token stacked bar — 2px hairline under the header. Replaces the
+       *  border-b so the bar itself is the separator. */}
+      <TokenBar breakdown={projectedState} />
+
+      {/* Message stream */}
+      <div className="min-h-0 flex-1 overflow-y-auto">
+        <div className="flex flex-col gap-3 px-3 py-4">
+          <SystemPromptBubble text={projectedState.system_prompt} />
+          {visible.length === 0 ? (
+            <div className="px-3 py-2 font-mono text-[12px] text-fg-3">
+              no messages — session has only lifecycle/config records so far.
+            </div>
+          ) : (
+            visible.map((m) => {
+              if (m.is_ephemeral) {
+                return <EphemeralBubble key={m.seq} message={m} />;
+              }
+              return <MessageBubble key={m.seq} message={m} sessionId={sessionId} />;
+            })
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function SystemPromptBubble({ text }: { text: string | null }) {
+  const [open, setOpen] = useState(false);
+  const hasText = text !== null && text.length > 0;
+
+  if (!hasText) {
+    return (
+      <article
+        className="relative flex max-w-full min-w-0 flex-col border-l-[3px] bg-surface-1 px-3 py-2"
+        style={{ borderLeftColor: 'var(--color-cat-config)' }}
+      >
+        <header className="flex items-center gap-2">
+          <Pill tone="config" variant="solid">
+            system
+          </Pill>
+          <span className="font-mono text-[12px] text-fg-3">(no system prompt)</span>
+        </header>
+      </article>
+    );
+  }
+
+  return (
+    <article
+      className="relative flex max-w-full min-w-0 flex-col border-l-[3px] bg-surface-1"
+      style={{ borderLeftColor: 'var(--color-cat-config)' }}
+    >
+      <button
+        type="button"
+        onClick={() =>{  setOpen((v) => !v); }}
+        className="flex w-full items-center justify-between gap-3 px-3 py-2 text-left hover:bg-surface-2"
+      >
+        <span className="flex items-center gap-2">
+          <Pill tone="config" variant="solid">
+            system
+          </Pill>
+          <span className="font-mono text-[10px] text-fg-3 tabular">
+            {formatBytes(text.length)} · {text.length.toLocaleString()} chars
+          </span>
+        </span>
+        <span className="font-mono text-[11px] text-fg-1">
+          {open ? '▾ collapse' : '▸ show full'}
+        </span>
+      </button>
+      <div className="relative px-3 pb-2">
+        <pre
+          className={[
+            'whitespace-pre-wrap break-words font-mono text-[12.5px] text-fg-0',
+            open ? '' : 'max-h-[9em] overflow-hidden',
+          ].join(' ')}
+        >
+          {text}
+        </pre>
+        {!open ? (
+          <div
+            aria-hidden="true"
+            className="pointer-events-none absolute inset-x-0 bottom-0 h-14"
+            style={{
+              background: 'linear-gradient(to bottom, transparent 0%, var(--color-surface-1) 85%)',
+            }}
+          />
+        ) : null}
+      </div>
+    </article>
+  );
+}
+
+function LegendDot({ color, label, count }: { color: string; label: string; count: number }) {
+  if (count === 0) return null;
+  return (
+    <span className="flex items-center gap-1 text-fg-3">
+      <span
+        className="inline-block h-[6px] w-[6px] rounded-full"
+        style={{ backgroundColor: color }}
+      />
+      <span>{label}</span>
+      <span className="tabular text-fg-2">{count}</span>
+    </span>
+  );
+}
+
+// ─── token breakdown (input / output / cache_read / cache_write) ───
+// Colors are chosen from the existing semantic palette so the bar reads
+// coherently with the rest of the app:
+//   cache_read   = success   (saved / cached — the "good" share)
+//   input        = info      (billed input)
+//   output       = assistant (what the model produced)
+//   cache_write  = warning   (billed once, amortised next call)
+
+const TOK_COLORS = {
+  cache_read: 'var(--color-sev-success)',
+  input: 'var(--color-sev-info)',
+  output: 'var(--color-assistant)',
+  cache_write: 'var(--color-sev-warning)',
+} as const;
+
+interface TokenBreakdown {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_write_tokens: number;
+}
+
+function formatTokens(n: number): string {
+  if (n < 1000) return String(n);
+  if (n < 10_000) return (n / 1000).toFixed(1) + 'K';
+  if (n < 1_000_000) return Math.round(n / 1000) + 'K';
+  return (n / 1_000_000).toFixed(1) + 'M';
+}
+
+function TokenDots({ breakdown }: { breakdown: TokenBreakdown }) {
+  const { input_tokens, output_tokens, cache_read_tokens, cache_write_tokens } = breakdown;
+  const billedIn = input_tokens + cache_read_tokens;
+  const hitPct = billedIn > 0 ? Math.round((cache_read_tokens / billedIn) * 100) : 0;
+  const hasAny =
+    input_tokens > 0 || output_tokens > 0 || cache_read_tokens > 0 || cache_write_tokens > 0;
+  if (!hasAny) {
+    return <span className="text-fg-3">(no tokens yet)</span>;
+  }
+  return (
+    <span className="flex items-center gap-2">
+      <TokenDot color={TOK_COLORS.input} label="in" value={input_tokens} />
+      <TokenDot color={TOK_COLORS.output} label="out" value={output_tokens} />
+      <TokenDot color={TOK_COLORS.cache_read} label="cache" value={cache_read_tokens} />
+      {cache_write_tokens > 0 ? (
+        <TokenDot color={TOK_COLORS.cache_write} label="cw" value={cache_write_tokens} />
+      ) : null}
+      {cache_read_tokens > 0 ? <span className="text-fg-3 tabular">({hitPct}% hit)</span> : null}
+    </span>
+  );
+}
+
+function TokenDot({ color, label, value }: { color: string; label: string; value: number }) {
+  return (
+    <span className="flex items-center gap-1" title={`${label}: ${value.toLocaleString()}`}>
+      <span
+        className="inline-block h-[6px] w-[6px] rounded-full"
+        style={{ backgroundColor: color }}
+      />
+      <span className="tabular text-fg-0">{formatTokens(value)}</span>
+      <span className="text-fg-3">{label}</span>
+    </span>
+  );
+}
+
+/** 2px stacked bar that visually shows the 4-way token composition.
+ *  Proportions use (input + output + cache_read + cache_write) as the
+ *  total so cache_read's share is honest (it's not in the "billed"
+ *  tokenCount but it's real work done on the request). */
+function TokenBar({ breakdown }: { breakdown: TokenBreakdown }) {
+  const { input_tokens, output_tokens, cache_read_tokens, cache_write_tokens } = breakdown;
+  const total = input_tokens + output_tokens + cache_read_tokens + cache_write_tokens;
+  if (total === 0) {
+    return <div className="h-[2px] shrink-0 bg-border" />;
+  }
+  const seg = (n: number) => (n / total) * 100;
+  return (
+    <div
+      className="flex h-[2px] w-full shrink-0"
+      title={`cache_read ${cache_read_tokens.toLocaleString()} · input ${input_tokens.toLocaleString()} · output ${output_tokens.toLocaleString()} · cache_write ${cache_write_tokens.toLocaleString()}`}
+    >
+      {cache_read_tokens > 0 ? (
+        <div
+          style={{ width: `${seg(cache_read_tokens)}%`, backgroundColor: TOK_COLORS.cache_read }}
+        />
+      ) : null}
+      {input_tokens > 0 ? (
+        <div style={{ width: `${seg(input_tokens)}%`, backgroundColor: TOK_COLORS.input }} />
+      ) : null}
+      {output_tokens > 0 ? (
+        <div style={{ width: `${seg(output_tokens)}%`, backgroundColor: TOK_COLORS.output }} />
+      ) : null}
+      {cache_write_tokens > 0 ? (
+        <div
+          style={{ width: `${seg(cache_write_tokens)}%`, backgroundColor: TOK_COLORS.cache_write }}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+function countKinds(messages: AnnotatedMessage[]) {
+  let user = 0,
+    assistant = 0,
+    tool = 0,
+    reminder = 0,
+    notif = 0;
+  for (const m of messages) {
+    switch (m.origin.kind) {
+      case 'user':
+        user++;
+        break;
+      case 'assistant':
+        assistant++;
+        break;
+      case 'tool':
+        tool++;
+        break;
+      case 'system_reminder':
+        reminder++;
+        break;
+      case 'notification':
+        notif++;
+        break;
+    }
+  }
+  return { user, assistant, tool, reminder, notif };
+}
diff --git a/apps/vis/web/src/components/context/EphemeralBubble.tsx b/apps/vis/web/src/components/context/EphemeralBubble.tsx
new file mode 100644
index 000000000..17a555592
--- /dev/null
+++ b/apps/vis/web/src/components/context/EphemeralBubble.tsx
@@ -0,0 +1,101 @@
+import type { AnnotatedMessage } from '../../types';
+import { Pill } from '../shared/Pill';
+
+interface EphemeralBubbleProps {
+  message: AnnotatedMessage;
+}
+
+/**
+ * Ephemeral-injected message (system_reminder or notification).
+ * Rendered with dashed border + inset — unambiguous signal that this
+ * is NOT a real user turn.
+ */
+export function EphemeralBubble({ message }: EphemeralBubbleProps) {
+  const { origin } = message;
+  if (origin.kind === 'system_reminder') {
+    return <SystemReminderBubble m={message} />;
+  }
+  if (origin.kind === 'notification') {
+    return <NotificationBubble m={message} severity={origin.severity} />;
+  }
+  return null;
+}
+
+function SystemReminderBubble({ m }: { m: AnnotatedMessage }) {
+  const text = extractText(m);
+  // Strip XML wrapper for display (show just the inner content)
+  const inner = text
+    .replace(/^\s*<system-reminder>\n?/, '')
+    .replace(/\n?<\/system-reminder>\s*$/, '');
+
+  return (
+    <article
+      className={[
+        'ml-4 flex max-w-full min-w-0 flex-col bg-surface-2 px-3 py-2',
+        'ephemeral-border',
+        m.out_of_context ? 'opacity-50' : '',
+      ].join(' ')}
+    >
+      <header className="mb-1 flex items-center gap-2">
+        <Pill tone="ephemeral" variant="solid">system_reminder</Pill>
+        <span className="font-mono text-[10px] text-fg-3 tabular">
+          injected @ seq {m.seq}
+        </span>
+      </header>
+      <pre className="whitespace-pre-wrap break-words font-mono text-[12.5px] leading-[1.55] text-fg-1">
+        {inner}
+      </pre>
+    </article>
+  );
+}
+
+function NotificationBubble({ m, severity }: { m: AnnotatedMessage; severity: string }) {
+  const text = extractText(m);
+  // Strip <notification ...> wrapper
+  const inner = text
+    .replace(/^\s*<notification[^>]*>\n?/, '')
+    .replace(/\n?<\/notification>\s*$/, '');
+  const tone =
+    severity === 'error'
+      ? 'error'
+      : severity === 'warning'
+        ? 'warning'
+        : severity === 'success'
+          ? 'success'
+          : 'info';
+  const borderClass =
+    severity === 'error'
+      ? 'ephemeral-border-error'
+      : severity === 'warning'
+        ? 'ephemeral-border-warning'
+        : severity === 'success'
+          ? 'ephemeral-border-success'
+          : 'ephemeral-border-info';
+
+  return (
+    <article
+      className={[
+        'ml-4 flex max-w-full min-w-0 flex-col bg-surface-2 px-3 py-2',
+        'ephemeral-border',
+        borderClass,
+        m.out_of_context ? 'opacity-50' : '',
+      ].join(' ')}
+    >
+      <header className="mb-1 flex items-center gap-2">
+        <Pill tone="meta" variant="solid">notification</Pill>
+        <Pill tone={tone} variant="soft">{severity}</Pill>
+        <span className="font-mono text-[10px] text-fg-3 tabular">
+          injected @ seq {m.seq}
+        </span>
+      </header>
+      <pre className="whitespace-pre-wrap break-words font-mono text-[12.5px] leading-[1.55] text-fg-1">
+        {inner}
+      </pre>
+    </article>
+  );
+}
+
+function extractText(m: AnnotatedMessage): string {
+  const p = m.message.content.find((x) => x.type === 'text');
+  return p ? ((p['text'] as string | undefined) ?? '') : '';
+}
diff --git a/apps/vis/web/src/components/context/MessageBubble.tsx b/apps/vis/web/src/components/context/MessageBubble.tsx
new file mode 100644
index 000000000..953ad3058
--- /dev/null
+++ b/apps/vis/web/src/components/context/MessageBubble.tsx
@@ -0,0 +1,193 @@
+import { useState, type ReactNode } from 'react';
+import type { AnnotatedMessage, ContentPart, ToolCallEntry } from '../../types';
+import { Pill } from '../shared/Pill';
+import { PersistedOutputLink } from './PersistedOutputLink';
+
+interface MessageBubbleProps {
+  message: AnnotatedMessage;
+  sessionId: string;
+}
+
+export function MessageBubble({ message, sessionId }: MessageBubbleProps) {
+  const { role } = message.message;
+  if (role === 'user') return <UserBubble m={message} />;
+  if (role === 'assistant') return <AssistantBubble m={message} />;
+  return <ToolBubble m={message} sessionId={sessionId} />;
+}
+
+function baseClass(out: boolean): string {
+  return [
+    'relative flex max-w-full min-w-0 flex-col border-l-[3px] bg-surface-1 px-3 py-2',
+    out ? 'opacity-50 line-through decoration-[var(--color-sev-error)] decoration-dashed' : '',
+  ].join(' ');
+}
+
+function UserBubble({ m }: { m: AnnotatedMessage }) {
+  return (
+    <article
+      className={baseClass(m.out_of_context)}
+      style={{ borderLeftColor: 'var(--color-user)' }}
+    >
+      <header className="mb-1 flex items-center gap-2">
+        <Pill tone="user" variant="solid">user</Pill>
+        <span className="font-mono text-[10px] text-fg-3 tabular">seq {m.seq}</span>
+        {m.out_of_context ? <Pill tone="error" variant="outline">out-of-context</Pill> : null}
+      </header>
+      <MessageContent parts={m.message.content} />
+    </article>
+  );
+}
+
+function AssistantBubble({ m }: { m: AnnotatedMessage }) {
+  const thinkPart = m.message.content.find((p) => p.type === 'think');
+  const think = thinkPart ? (thinkPart['think'] as string | undefined) : undefined;
+  const textParts = m.message.content.filter((p) => p.type !== 'think');
+  return (
+    <article
+      className={baseClass(m.out_of_context)}
+      style={{ borderLeftColor: 'var(--color-assistant)' }}
+    >
+      <header className="mb-1 flex items-center gap-2">
+        <Pill tone="assistant" variant="solid">assistant</Pill>
+        <span className="font-mono text-[10px] text-fg-3 tabular">seq {m.seq}</span>
+        {think ? <Pill tone="config" variant="outline">think</Pill> : null}
+        {m.message.tool_calls.length > 0 ? (
+          <Pill tone="tools" variant="outline">
+            {m.message.tool_calls.length} tool call{m.message.tool_calls.length > 1 ? 's' : ''}
+          </Pill>
+        ) : null}
+        {m.out_of_context ? <Pill tone="error" variant="outline">out-of-context</Pill> : null}
+      </header>
+      {think ? <ThinkBlock text={think} /> : null}
+      <MessageContent parts={textParts} />
+      {m.message.tool_calls.length > 0 ? (
+        <div className="mt-2 space-y-1">
+          {m.message.tool_calls.map((tc) => <ToolCallCard key={tc.id} call={tc} />)}
+        </div>
+      ) : null}
+    </article>
+  );
+}
+
+function ToolBubble({ m, sessionId }: { m: AnnotatedMessage; sessionId: string }) {
+  const firstTextPart = m.message.content.find((p) => p.type === 'text');
+  const text = firstTextPart ? ((firstTextPart['text'] as string | undefined) ?? '') : '';
+  const hasPersisted = !!m.persisted_output_path && m.message.tool_call_id;
+  return (
+    <article
+      className={baseClass(m.out_of_context)}
+      style={{ borderLeftColor: 'var(--color-tool)' }}
+    >
+      <header className="mb-1 flex items-center gap-2">
+        <Pill tone="tool" variant="solid">tool</Pill>
+        {m.message.tool_call_id ? (
+          <span className="font-mono text-[11px] text-fg-1">
+            call {m.message.tool_call_id.slice(0, 12)}
+          </span>
+        ) : null}
+        <span className="font-mono text-[10px] text-fg-3 tabular">seq {m.seq}</span>
+        {m.out_of_context ? <Pill tone="error" variant="outline">out-of-context</Pill> : null}
+      </header>
+      {hasPersisted ? (
+        <PersistedOutputLink
+          sessionId={sessionId}
+          toolCallId={m.message.tool_call_id!}
+          path={m.persisted_output_path!}
+        />
+      ) : (
+        <pre className="whitespace-pre-wrap break-words font-mono text-[12px] text-fg-1">
+          {text}
+        </pre>
+      )}
+    </article>
+  );
+}
+
+function ThinkBlock({ text }: { text: string }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <div className="mb-2 border border-border bg-surface-0">
+      <button
+        onClick={() =>{  setOpen((v) => !v); }}
+        className="flex w-full items-center gap-2 px-2 py-1 text-left font-mono text-[11px] text-fg-2 hover:text-fg-1"
+      >
+        <span className="text-fg-3">{open ? '▾' : '▸'}</span>
+        <span className="uppercase tracking-[0.08em]">thinking</span>
+        <span className="text-fg-3 tabular">{text.length}ch</span>
+      </button>
+      {open ? (
+        <pre className="border-t border-border px-2 py-1 whitespace-pre-wrap break-words font-mono text-[12px] text-fg-1">
+          {text}
+        </pre>
+      ) : null}
+    </div>
+  );
+}
+
+function ToolCallCard({ call }: { call: ToolCallEntry }) {
+  const [open, setOpen] = useState(false);
+  const argsStr = call.function.arguments ?? '';
+  return (
+    <div className="border border-border bg-surface-0">
+      <button
+        onClick={() =>{  setOpen((v) => !v); }}
+        className="flex w-full items-center gap-2 px-2 py-1 text-left font-mono text-[11px] hover:bg-surface-2"
+      >
+        <span className="text-fg-3">{open ? '▾' : '▸'}</span>
+        <Pill tone="tools" variant="soft">call</Pill>
+        <span className="text-fg-0">{call.function.name}</span>
+        <span className="truncate text-fg-3">{truncate(argsStr, 80)}</span>
+        <span className="ml-auto text-fg-3 tabular text-[10px]">{call.id.slice(0, 10)}</span>
+      </button>
+      {open ? (
+        <pre className="border-t border-border px-2 py-1 whitespace-pre-wrap break-words font-mono text-[12px] text-fg-1">
+          {prettyJson(argsStr)}
+        </pre>
+      ) : null}
+    </div>
+  );
+}
+
+function MessageContent({ parts }: { parts: readonly ContentPart[] }): ReactNode {
+  return (
+    <div className="space-y-2">
+      {parts.map((p, i) => {
+        if (p.type === 'text') {
+          return (
+            <pre
+              key={i}
+              className="whitespace-pre-wrap break-words font-mono text-[12.5px] leading-[1.55] text-fg-0"
+            >
+              {(p['text'] as string) ?? ''}
+            </pre>
+          );
+        }
+        if (p.type === 'image_url') {
+          const url = (p['image_url'] as { url?: string } | undefined)?.url;
+          return <div key={i} className="text-fg-2 font-mono text-[11px]">[image: {url ?? '—'}]</div>;
+        }
+        if (p.type === 'video_url') {
+          const url = (p['video_url'] as { url?: string } | undefined)?.url;
+          return <div key={i} className="text-fg-2 font-mono text-[11px]">[video: {url ?? '—'}]</div>;
+        }
+        return (
+          <div key={i} className="text-fg-3 font-mono text-[11px]">
+            [{p.type}]
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function truncate(s: string, n: number): string {
+  return s.length <= n ? s : s.slice(0, n) + '…';
+}
+
+function prettyJson(s: string): string {
+  try {
+    return JSON.stringify(JSON.parse(s), null, 2);
+  } catch {
+    return s;
+  }
+}
diff --git a/apps/vis/web/src/components/context/PersistedOutputLink.tsx b/apps/vis/web/src/components/context/PersistedOutputLink.tsx
new file mode 100644
index 000000000..598a11b17
--- /dev/null
+++ b/apps/vis/web/src/components/context/PersistedOutputLink.tsx
@@ -0,0 +1,53 @@
+import { useState } from 'react';
+import { useToolResult } from '../../hooks/useContext';
+import { formatBytes } from '../shared/SizePreview';
+
+interface PersistedOutputLinkProps {
+  sessionId: string;
+  toolCallId: string;
+  path: string;
+}
+
+export function PersistedOutputLink({
+  sessionId,
+  toolCallId,
+  path,
+}: PersistedOutputLinkProps) {
+  const [load, setLoad] = useState(false);
+  const { data, isLoading, error } = useToolResult(sessionId, toolCallId, load);
+  const basename = path.split('/').pop() ?? path;
+
+  return (
+    <div className="my-1 border border-border bg-surface-0">
+      <button
+        onClick={() =>{  setLoad((v) => !v); }}
+        className="flex w-full items-center gap-2 px-2 py-1 text-left font-mono text-[11px] text-fg-2 hover:bg-surface-2 hover:text-fg-1"
+      >
+        <span className="text-fg-3">{load ? '▾' : '▸'}</span>
+        <span className="pill" style={{
+          backgroundColor: 'color-mix(in oklab, var(--color-compaction) 18%, transparent)',
+          color: 'var(--color-compaction)',
+        }}>
+          persisted
+        </span>
+        <span className="truncate">{basename}</span>
+        {data ? <span className="ml-auto text-fg-3 tabular">{formatBytes(data.size_bytes)}</span> : null}
+      </button>
+      {load ? (
+        <div className="border-t border-border">
+          {isLoading ? (
+            <div className="px-2 py-1 font-mono text-[11px] text-fg-3">loading…</div>
+          ) : error ? (
+            <div className="px-2 py-1 font-mono text-[11px] text-[var(--color-sev-error)]">
+              {(error).message}
+            </div>
+          ) : data ? (
+            <pre className="max-h-96 overflow-auto whitespace-pre-wrap break-words px-2 py-1 font-mono text-[12px] text-fg-1">
+              {data.content}
+            </pre>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
diff --git a/apps/vis/web/src/components/files/FilesTab.tsx b/apps/vis/web/src/components/files/FilesTab.tsx
new file mode 100644
index 000000000..f3bae940c
--- /dev/null
+++ b/apps/vis/web/src/components/files/FilesTab.tsx
@@ -0,0 +1,202 @@
+import { useState } from 'react';
+import { Link } from 'react-router-dom';
+
+import { useToolResult } from '../../hooks/useContext';
+import { useArchive } from '../../hooks/useWire';
+import type { SessionDetail } from '../../types';
+import { Drawer } from '../shared/Drawer';
+import { Pill } from '../shared/Pill';
+import { formatBytes } from '../shared/SizePreview';
+import { WireTab } from '../wire/WireTab';
+
+interface FilesTabProps {
+  sessionId: string;
+  detail: SessionDetail;
+}
+
+export function FilesTab({ sessionId, detail }: FilesTabProps) {
+  const [openArchive, setOpenArchive] = useState<string | null>(null);
+  const [openResult, setOpenResult] = useState<string | null>(null);
+
+  return (
+    <div className="min-h-0 flex-1 overflow-y-auto p-4">
+      {/* Archives */}
+      <section>
+        <h2 className="font-mono text-[11px] uppercase tracking-[0.12em] text-fg-3">
+          wire archives · {detail.archive_files.length}
+        </h2>
+        {detail.archive_files.length === 0 ? (
+          <p className="mt-2 font-mono text-[12px] text-fg-3">no compaction archives</p>
+        ) : (
+          <ul className="mt-2 border border-border bg-surface-0">
+            {detail.archive_files.map((f) => (
+              <li
+                key={f}
+                className="flex items-center gap-3 border-b border-border px-3 py-2 last:border-b-0"
+              >
+                <Pill tone="compaction" variant="soft">
+                  archive
+                </Pill>
+                <span className="font-mono text-[12px] text-fg-0">{f}</span>
+                <button
+                  onClick={() =>{  setOpenArchive(f); }}
+                  className="ml-auto border border-border px-2 py-0.5 font-mono text-[11px] text-fg-2 hover:border-border-strong hover:text-fg-0"
+                >
+                  view records
+                </button>
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
+
+      {/* External tool results */}
+      <section className="mt-6">
+        <h2 className="font-mono text-[11px] uppercase tracking-[0.12em] text-fg-3">
+          external tool results · {detail.tool_result_ids.length}
+        </h2>
+        {detail.tool_result_ids.length === 0 ? (
+          <p className="mt-2 font-mono text-[12px] text-fg-3">none</p>
+        ) : (
+          <ul className="mt-2 border border-border bg-surface-0">
+            {detail.tool_result_ids.map((id) => (
+              <li
+                key={id}
+                className="flex items-center gap-3 border-b border-border px-3 py-2 last:border-b-0"
+              >
+                <Pill tone="tool" variant="soft">
+                  file
+                </Pill>
+                <span className="truncate font-mono text-[12px] text-fg-0">{id}.txt</span>
+                <button
+                  onClick={() =>{  setOpenResult(id); }}
+                  className="ml-auto border border-border px-2 py-0.5 font-mono text-[11px] text-fg-2 hover:border-border-strong hover:text-fg-0"
+                >
+                  view
+                </button>
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
+
+      {/* Subagent directories — click a tile to drill into that subagent's
+          own wire + context + meta. Mirrors the Subagents tab tree but in
+          a flat, filesystem-ish view. */}
+      <section className="mt-6">
+        <h2 className="font-mono text-[11px] uppercase tracking-[0.12em] text-fg-3">
+          subagent directories · {detail.subagent_ids.length}
+        </h2>
+        {detail.subagent_ids.length === 0 ? (
+          <p className="mt-2 font-mono text-[12px] text-fg-3">none</p>
+        ) : (
+          <ul className="mt-2 grid grid-cols-1 gap-2 md:grid-cols-2">
+            {detail.subagent_ids.map((id) => (
+              <li key={id}>
+                <Link
+                  to={`/sessions/${sessionId}/subagents/${id}`}
+                  className="group block border border-border bg-surface-0 px-3 py-2 transition-colors hover:border-border-strong hover:bg-surface-1"
+                >
+                  <div className="flex items-center gap-2">
+                    <Pill tone="subagent" variant="soft">
+                      subagent
+                    </Pill>
+                    <span className="truncate font-mono text-[12px] text-fg-0">
+                      {id.replace(/^sub_/, '').slice(0, 12)}
+                    </span>
+                    <span className="ml-auto font-mono text-[10px] text-fg-3 group-hover:text-fg-1">
+                      open →
+                    </span>
+                  </div>
+                  <div className="mt-1 truncate font-mono text-[10.5px] text-fg-3">{id}</div>
+                </Link>
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
+
+      {openArchive ? (
+        <ArchiveDrawer
+          sessionId={sessionId}
+          filename={openArchive}
+          onClose={() =>{  setOpenArchive(null); }}
+        />
+      ) : null}
+      {openResult ? (
+        <ToolResultDrawer
+          sessionId={sessionId}
+          toolCallId={openResult}
+          onClose={() =>{  setOpenResult(null); }}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+function ArchiveDrawer({
+  sessionId,
+  filename,
+  onClose,
+}: {
+  sessionId: string;
+  filename: string;
+  onClose: () => void;
+}) {
+  const { data, isLoading, error } = useArchive(sessionId, filename);
+  return (
+    <Drawer open onClose={onClose} title={<span>archive · {filename}</span>} width={900}>
+      {isLoading ? (
+        <div className="p-4 font-mono text-[11px] text-fg-3">loading…</div>
+      ) : error ? (
+        <div className="p-4 font-mono text-[11px] text-[var(--color-sev-error)]">
+          {(error).message}
+        </div>
+      ) : data ? (
+        <WireTab
+          records={data.records}
+          health={data.health}
+          brokenReason={data.broken_reason}
+          warnings={data.warnings}
+        />
+      ) : null}
+    </Drawer>
+  );
+}
+
+function ToolResultDrawer({
+  sessionId,
+  toolCallId,
+  onClose,
+}: {
+  sessionId: string;
+  toolCallId: string;
+  onClose: () => void;
+}) {
+  const { data, isLoading, error } = useToolResult(sessionId, toolCallId, true);
+  return (
+    <Drawer
+      open
+      onClose={onClose}
+      title={
+        <span>
+          tool-result · {toolCallId}.txt
+          {data ? <span className="ml-2 text-fg-3">{formatBytes(data.size_bytes)}</span> : null}
+        </span>
+      }
+      width={780}
+    >
+      {isLoading ? (
+        <div className="p-4 font-mono text-[11px] text-fg-3">loading…</div>
+      ) : error ? (
+        <div className="p-4 font-mono text-[11px] text-[var(--color-sev-error)]">
+          {(error).message}
+        </div>
+      ) : data ? (
+        <pre className="whitespace-pre-wrap break-words p-4 font-mono text-[12.5px] text-fg-0">
+          {data.content}
+        </pre>
+      ) : null}
+    </Drawer>
+  );
+}
diff --git a/apps/vis/web/src/components/layout/AppShell.tsx b/apps/vis/web/src/components/layout/AppShell.tsx
new file mode 100644
index 000000000..1d7fbeea2
--- /dev/null
+++ b/apps/vis/web/src/components/layout/AppShell.tsx
@@ -0,0 +1,138 @@
+import type { ReactNode } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { Link } from 'react-router-dom';
+import { SessionRail } from '../sessions/SessionRail';
+import { useTheme, type ThemeChoice, type ResolvedTheme } from '../../hooks/useTheme';
+
+interface AppShellProps {
+  children: ReactNode;
+}
+
+export function AppShell({ children }: AppShellProps) {
+  const qc = useQueryClient();
+  const { choice, resolved, cycle } = useTheme();
+
+  return (
+    <div className="flex h-full flex-col">
+      <header className="flex h-10 shrink-0 items-center justify-between border-b border-border bg-surface-1 px-4">
+        <Link to="/" className="flex items-center gap-2">
+          <LogoMark />
+          <span className="font-mono text-[12px] uppercase tracking-[0.12em] text-fg-0">
+            kimi <span className="text-fg-2">vis</span>
+          </span>
+          <span className="ml-2 font-mono text-[10px] uppercase tracking-[0.12em] text-fg-3">
+            debug · local files
+          </span>
+        </Link>
+        <div className="flex items-center gap-2 text-[11px] text-fg-2">
+          <ThemeToggle choice={choice} resolved={resolved} onCycle={cycle} />
+          <button
+            onClick={() => {
+              void qc.invalidateQueries();
+            }}
+            className="flex items-center gap-1.5 border border-border px-2 py-0.5 font-mono text-[11px] text-fg-1 transition-colors hover:border-border-strong hover:text-fg-0"
+            title="Refresh — re-read all session data from disk"
+          >
+            <RefreshIcon />
+            refresh
+          </button>
+        </div>
+      </header>
+      <div className="flex min-h-0 flex-1">
+        <SessionRail />
+        <main className="flex min-h-0 flex-1 flex-col">{children}</main>
+      </div>
+    </div>
+  );
+}
+
+function ThemeToggle({
+  choice,
+  resolved,
+  onCycle,
+}: {
+  choice: ThemeChoice;
+  resolved: ResolvedTheme;
+  onCycle: () => void;
+}) {
+  const label = choice === 'auto' ? `auto · ${resolved}` : choice;
+  const title = `Theme: ${label}. Click to cycle (auto → light → dark → auto).`;
+  return (
+    <button
+      onClick={onCycle}
+      className="flex items-center gap-1.5 border border-border px-2 py-0.5 font-mono text-[11px] text-fg-1 transition-colors hover:border-border-strong hover:text-fg-0"
+      title={title}
+      aria-label={`Theme ${label}`}
+    >
+      {choice === 'auto' ? <AutoIcon /> : resolved === 'light' ? <SunIcon /> : <MoonIcon />}
+      <span className="tabular">{label}</span>
+    </button>
+  );
+}
+
+function LogoMark() {
+  return (
+    <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true">
+      <rect x="1" y="1" width="6" height="6" fill="var(--color-cat-conversation)" />
+      <rect x="9" y="1" width="6" height="6" fill="var(--color-cat-subagent)" />
+      <rect x="1" y="9" width="6" height="6" fill="var(--color-cat-ephemeral)" />
+      <rect x="9" y="9" width="6" height="6" fill="var(--color-cat-approval)" />
+    </svg>
+  );
+}
+
+function RefreshIcon() {
+  return (
+    <svg width="10" height="10" viewBox="0 0 12 12" aria-hidden="true">
+      <path
+        d="M10 3 A5 5 0 1 0 10.8 7"
+        stroke="currentColor"
+        strokeWidth="1.2"
+        fill="none"
+        strokeLinecap="square"
+      />
+      <path d="M7 1 L10 3 L7 5" stroke="currentColor" strokeWidth="1.2" fill="none" strokeLinecap="square" strokeLinejoin="miter" />
+    </svg>
+  );
+}
+
+function SunIcon() {
+  return (
+    <svg width="11" height="11" viewBox="0 0 12 12" aria-hidden="true">
+      <circle cx="6" cy="6" r="2" fill="currentColor" />
+      <g stroke="currentColor" strokeWidth="1" strokeLinecap="round">
+        <line x1="6" y1="0.5" x2="6" y2="2" />
+        <line x1="6" y1="10" x2="6" y2="11.5" />
+        <line x1="0.5" y1="6" x2="2" y2="6" />
+        <line x1="10" y1="6" x2="11.5" y2="6" />
+        <line x1="2" y1="2" x2="3" y2="3" />
+        <line x1="9" y1="9" x2="10" y2="10" />
+        <line x1="10" y1="2" x2="9" y2="3" />
+        <line x1="3" y1="9" x2="2" y2="10" />
+      </g>
+    </svg>
+  );
+}
+
+function MoonIcon() {
+  return (
+    <svg width="11" height="11" viewBox="0 0 12 12" aria-hidden="true">
+      <path
+        d="M9 7.5 A4.5 4.5 0 1 1 4.5 3 A3.6 3.6 0 0 0 9 7.5 Z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+}
+
+function AutoIcon() {
+  return (
+    <svg width="11" height="11" viewBox="0 0 12 12" aria-hidden="true">
+      <path
+        d="M6 1 A5 5 0 1 1 6 11 Z"
+        fill="currentColor"
+      />
+      <circle cx="6" cy="6" r="4.5" fill="none" stroke="currentColor" strokeWidth="1" />
+    </svg>
+  );
+}
diff --git a/apps/vis/web/src/components/layout/TabBar.tsx b/apps/vis/web/src/components/layout/TabBar.tsx
new file mode 100644
index 000000000..6f2d42564
--- /dev/null
+++ b/apps/vis/web/src/components/layout/TabBar.tsx
@@ -0,0 +1,56 @@
+import { useSearchParams } from 'react-router-dom';
+
+export interface TabSpec {
+  id: string;
+  label: string;
+  count?: number | null;
+}
+
+interface TabBarProps {
+  tabs: TabSpec[];
+  defaultTab: string;
+}
+
+export function TabBar({ tabs, defaultTab }: TabBarProps) {
+  const [search, setSearch] = useSearchParams();
+  const active = search.get('tab') ?? defaultTab;
+
+  return (
+    <div className="flex h-9 shrink-0 items-stretch border-b border-border bg-surface-1">
+      {tabs.map((t) => {
+        const on = t.id === active;
+        return (
+          <button
+            key={t.id}
+            onClick={() => {
+              const next = new URLSearchParams(search);
+              next.set('tab', t.id);
+              setSearch(next, { replace: true });
+            }}
+            className={[
+              'relative flex items-center gap-2 px-4 font-mono text-[11px] uppercase tracking-[0.08em] transition-colors',
+              on
+                ? 'text-fg-0'
+                : 'text-fg-2 hover:text-fg-1',
+            ].join(' ')}
+          >
+            {t.label}
+            {t.count !== null && t.count !== undefined ? (
+              <span className="font-mono text-[10px] text-fg-3 tabular">
+                {t.count}
+              </span>
+            ) : null}
+            {on ? (
+              <span className="absolute inset-x-0 bottom-[-1px] h-[2px] bg-[var(--color-cat-conversation)]" />
+            ) : null}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+export function useActiveTab(defaultTab: string): string {
+  const [search] = useSearchParams();
+  return search.get('tab') ?? defaultTab;
+}
diff --git a/apps/vis/web/src/components/sessions/SessionCard.tsx b/apps/vis/web/src/components/sessions/SessionCard.tsx
new file mode 100644
index 000000000..590c158a3
--- /dev/null
+++ b/apps/vis/web/src/components/sessions/SessionCard.tsx
@@ -0,0 +1,124 @@
+import type { MouseEvent } from 'react';
+import { useParams, Link } from 'react-router-dom';
+import type { SessionSummary } from '../../types';
+import { formatRelativeTime } from '../../util/time';
+import { Pill } from '../shared/Pill';
+
+interface SessionCardProps {
+  session: SessionSummary;
+  onDelete: (session: SessionSummary) => void;
+  deleting: boolean;
+}
+
+export function SessionCard({ session, onDelete, deleting }: SessionCardProps) {
+  const { sessionId } = useParams<{ sessionId: string }>();
+  const selected = sessionId === session.session_id;
+  const dirty = session.last_exit_code === 'dirty';
+  const workspaceLabel = session.workspace_dir
+    ? session.workspace_dir.split('/').slice(-2).join('/')
+    : '(no workspace)';
+  const shortId = session.session_id.replace(/^session_/, '').slice(0, 10);
+  const title = session.title ?? session.custom_title;
+
+  function handleDeleteClick(e: MouseEvent<HTMLButtonElement>) {
+    e.preventDefault();
+    e.stopPropagation();
+    onDelete(session);
+  }
+
+  return (
+    <div
+      className={[
+        'group relative border-b border-border transition-colors',
+        selected
+          ? 'bg-surface-2'
+          : 'hover:bg-surface-1',
+        session.archived ? 'opacity-60' : '',
+      ].join(' ')}
+    >
+      {selected ? (
+        <span className="absolute inset-y-0 left-0 w-[2px] bg-[var(--color-cat-conversation)]" />
+      ) : null}
+      <Link to={`/sessions/${session.session_id}`} className="block px-3 py-2 pr-10">
+        <div className="flex items-center justify-between gap-2">
+          <div className="flex min-w-0 items-center gap-2">
+            <span
+              className="inline-block h-[7px] w-[7px] shrink-0 rounded-full"
+              style={{
+                backgroundColor: dirty ? 'var(--color-sev-warning)' : 'var(--color-fg-3)',
+              }}
+              title={dirty ? 'dirty exit' : 'clean or unknown exit'}
+            />
+            <span className="shrink-0 font-mono text-[12px] text-fg-0">{shortId}</span>
+            {session.model ? (
+              <Pill tone="config" variant="soft" className="!py-0">
+                {session.model}
+              </Pill>
+            ) : null}
+            {session.archived ? (
+              <Pill tone="warning" variant="soft" className="!py-0">
+                archived
+              </Pill>
+            ) : null}
+          </div>
+          <span className="shrink-0 font-mono text-[10.5px] text-fg-3 tabular">
+            {formatRelativeTime(session.updated_at)}
+          </span>
+        </div>
+        <div className="mt-1 flex items-center gap-3 font-mono text-[10.5px] text-fg-2">
+          <span className="truncate" title={session.workspace_dir ?? ''}>
+            {workspaceLabel}
+          </span>
+          <span className="tabular text-fg-3">
+            {session.wire_record_count}ev
+          </span>
+          {session.subagent_count > 0 ? (
+            <span className="tabular text-[var(--color-cat-subagent)]">
+              {session.subagent_count}sub
+            </span>
+          ) : null}
+          {session.archive_count > 0 ? (
+            <span className="tabular text-[var(--color-compaction)]">
+              {session.archive_count}arch
+            </span>
+          ) : null}
+          {session.health !== 'ok' ? (
+            <span className="tabular text-[var(--color-sev-error)]">
+              {session.health}
+            </span>
+          ) : null}
+        </div>
+        {title ? (
+          <div className="mt-1 truncate font-mono text-[11px] text-fg-1" title={title}>
+            {title}
+          </div>
+        ) : null}
+        {session.last_prompt ? (
+          <div className="mt-1 truncate font-mono text-[10.5px] text-fg-3" title={session.last_prompt}>
+            prompt · {session.last_prompt}
+          </div>
+        ) : null}
+      </Link>
+      <button
+        type="button"
+        onClick={handleDeleteClick}
+        disabled={deleting}
+        className="absolute right-2 top-2 flex h-5 w-5 items-center justify-center border border-transparent text-fg-3 transition-colors hover:border-[var(--color-sev-error)] hover:text-[var(--color-sev-error)] disabled:cursor-not-allowed disabled:opacity-40"
+        title={`Delete session ${session.session_id}`}
+        aria-label={`Delete session ${session.session_id}`}
+      >
+        <TrashIcon />
+      </button>
+    </div>
+  );
+}
+
+function TrashIcon() {
+  return (
+    <svg width="11" height="11" viewBox="0 0 12 12" aria-hidden="true">
+      <path d="M2 3 H10" stroke="currentColor" strokeWidth="1.2" strokeLinecap="square" />
+      <path d="M4 3 V2 H8 V3" stroke="currentColor" strokeWidth="1.2" fill="none" />
+      <path d="M3 4 H9 L8.5 10 H3.5 Z" stroke="currentColor" strokeWidth="1.2" fill="none" />
+    </svg>
+  );
+}
diff --git a/apps/vis/web/src/components/sessions/SessionFilter.tsx b/apps/vis/web/src/components/sessions/SessionFilter.tsx
new file mode 100644
index 000000000..79581c5bb
--- /dev/null
+++ b/apps/vis/web/src/components/sessions/SessionFilter.tsx
@@ -0,0 +1,127 @@
+import type { SessionSortKey, HealthFilter } from './SessionRail';
+
+interface SessionFilterProps {
+  search: string;
+  onSearchChange: (v: string) => void;
+  showArchived: boolean;
+  onShowArchivedChange: (v: boolean) => void;
+  sortKey: SessionSortKey;
+  onSortChange: (v: SessionSortKey) => void;
+  healthFilter: HealthFilter;
+  onHealthChange: (v: HealthFilter) => void;
+  totalCount: number;
+  filteredCount: number;
+  onClearSessions: () => void;
+  clearDisabled: boolean;
+  clearBusy: boolean;
+}
+
+const SORT_OPTIONS: { value: SessionSortKey; label: string }[] = [
+  { value: 'recent', label: 'recent' },
+  { value: 'oldest', label: 'oldest' },
+  { value: 'most_records', label: 'most records' },
+  { value: 'most_subagents', label: 'most subagents' },
+];
+
+const HEALTH_OPTIONS: { value: HealthFilter; label: string }[] = [
+  { value: 'all', label: 'any' },
+  { value: 'ok', label: 'ok' },
+  { value: 'broken', label: 'broken' },
+  { value: 'missing_wire', label: 'no wire' },
+];
+
+export function SessionFilter({
+  search,
+  onSearchChange,
+  showArchived,
+  onShowArchivedChange,
+  sortKey,
+  onSortChange,
+  healthFilter,
+  onHealthChange,
+  totalCount,
+  filteredCount,
+  onClearSessions,
+  clearDisabled,
+  clearBusy,
+}: SessionFilterProps) {
+  return (
+    <div className="border-b border-border bg-surface-1 px-3 py-2">
+      <div className="relative">
+        <input
+          type="text"
+          value={search}
+          onChange={(e) =>{  onSearchChange(e.target.value); }}
+          placeholder="search id / title / workspace"
+          className="w-full border border-border bg-surface-0 px-2 py-1 font-mono text-[12px] text-fg-0 placeholder:text-fg-3 focus:border-border-strong focus:outline-none"
+        />
+      </div>
+      <div className="mt-2 grid grid-cols-2 gap-2">
+        <label className="flex items-center gap-1.5 font-mono text-[10.5px] text-fg-2">
+          <span className="text-fg-3">sort</span>
+          <select
+            value={sortKey}
+            onChange={(e) =>{  onSortChange(e.target.value as SessionSortKey); }}
+            className="flex-1 border border-border bg-surface-0 px-1 py-0.5 text-fg-1 focus:border-border-strong focus:outline-none"
+          >
+            {SORT_OPTIONS.map((o) => (
+              <option key={o.value} value={o.value}>
+                {o.label}
+              </option>
+            ))}
+          </select>
+        </label>
+        <label className="flex items-center gap-1.5 font-mono text-[10.5px] text-fg-2">
+          <span className="text-fg-3">health</span>
+          <select
+            value={healthFilter}
+            onChange={(e) =>{  onHealthChange(e.target.value as HealthFilter); }}
+            className="flex-1 border border-border bg-surface-0 px-1 py-0.5 text-fg-1 focus:border-border-strong focus:outline-none"
+          >
+            {HEALTH_OPTIONS.map((o) => (
+              <option key={o.value} value={o.value}>
+                {o.label}
+              </option>
+            ))}
+          </select>
+        </label>
+      </div>
+      <div className="mt-2 flex items-center justify-between">
+        <label className="flex items-center gap-1.5 font-mono text-[10.5px] text-fg-2 hover:text-fg-1 select-none">
+          <input
+            type="checkbox"
+            checked={showArchived}
+            onChange={(e) =>{  onShowArchivedChange(e.target.checked); }}
+            className="accent-[var(--color-cat-conversation)]"
+          />
+          show archived
+        </label>
+        <div className="flex items-center gap-2">
+          <span className="font-mono text-[10px] text-fg-3 tabular">
+            {filteredCount} / {totalCount}
+          </span>
+          <button
+            type="button"
+            onClick={onClearSessions}
+            disabled={clearDisabled}
+            className="flex items-center gap-1 border border-border px-1.5 py-0.5 font-mono text-[10px] text-fg-2 transition-colors hover:border-[var(--color-sev-error)] hover:text-[var(--color-sev-error)] disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:border-border disabled:hover:text-fg-2"
+            title="Delete all sessions shown by vis"
+          >
+            <TrashIcon />
+            {clearBusy ? 'clearing' : 'clear all'}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function TrashIcon() {
+  return (
+    <svg width="10" height="10" viewBox="0 0 12 12" aria-hidden="true">
+      <path d="M2 3 H10" stroke="currentColor" strokeWidth="1.2" strokeLinecap="square" />
+      <path d="M4 3 V2 H8 V3" stroke="currentColor" strokeWidth="1.2" fill="none" />
+      <path d="M3 4 H9 L8.5 10 H3.5 Z" stroke="currentColor" strokeWidth="1.2" fill="none" />
+    </svg>
+  );
+}
diff --git a/apps/vis/web/src/components/sessions/SessionRail.tsx b/apps/vis/web/src/components/sessions/SessionRail.tsx
new file mode 100644
index 000000000..2a73817d6
--- /dev/null
+++ b/apps/vis/web/src/components/sessions/SessionRail.tsx
@@ -0,0 +1,188 @@
+import { useMemo, useState } from 'react';
+import { useNavigate, useParams } from 'react-router-dom';
+
+import { useClearSessions, useDeleteSession, useSessions } from '../../hooks/useSession';
+import type { SessionSummary } from '../../types';
+import { SessionCard } from './SessionCard';
+import { SessionFilter } from './SessionFilter';
+
+export type SessionSortKey = 'recent' | 'oldest' | 'most_records' | 'most_subagents';
+export type HealthFilter = 'all' | 'ok' | 'broken' | 'missing_wire';
+
+function workspaceKey(s: SessionSummary): string {
+  if (!s.workspace_dir) return '(no workspace)';
+  return s.workspace_dir.split('/').slice(-2).join('/');
+}
+
+function sortSessions(sessions: readonly SessionSummary[], key: SessionSortKey): SessionSummary[] {
+  switch (key) {
+    case 'recent':
+      return sessions.toSorted((a, b) => b.updated_at - a.updated_at);
+    case 'oldest':
+      return sessions.toSorted((a, b) => a.created_at - b.created_at);
+    case 'most_records':
+      return sessions.toSorted((a, b) => b.wire_record_count - a.wire_record_count);
+    case 'most_subagents':
+      return sessions.toSorted((a, b) => b.subagent_count - a.subagent_count);
+  }
+}
+
+export function SessionRail() {
+  const { data, isLoading, error } = useSessions();
+  const deleteSession = useDeleteSession();
+  const clearSessions = useClearSessions();
+  const navigate = useNavigate();
+  const { sessionId } = useParams<{ sessionId: string }>();
+  const [search, setSearch] = useState('');
+  const [showArchived, setShowArchived] = useState(false);
+  const [sortKey, setSortKey] = useState<SessionSortKey>('recent');
+  const [healthFilter, setHealthFilter] = useState<HealthFilter>('all');
+
+  const filtered = useMemo(() => {
+    if (!data) return [];
+    const q = search.trim().toLowerCase();
+    return data.filter((s) => {
+      if (!showArchived && s.archived) return false;
+      if (healthFilter !== 'all' && s.health !== healthFilter) return false;
+      if (!q) return true;
+      const hay = [
+        s.session_id,
+        s.title ?? '',
+        s.last_prompt ?? '',
+        s.custom_title ?? '',
+        s.workspace_dir ?? '',
+        s.model ?? '',
+        ...s.tags,
+      ]
+        .join(' ')
+        .toLowerCase();
+      return hay.includes(q);
+    });
+  }, [data, search, showArchived, healthFilter]);
+
+  // Grouping-by-workspace only makes sense when sorted by time — for any
+  // other sort the user asked for a particular total ordering across
+  // sessions, so we honour it and display a flat list.
+  const grouped = useMemo(() => {
+    if (sortKey !== 'recent') return null;
+    const map = new Map<string, SessionSummary[]>();
+    for (const s of filtered) {
+      const k = workspaceKey(s);
+      const existing = map.get(k);
+      if (existing === undefined) {
+        map.set(k, [s]);
+      } else {
+        existing.push(s);
+      }
+    }
+    return [...map.entries()]
+      .map(([group, items]) => {
+        const sorted = items.toSorted((a, b) => b.updated_at - a.updated_at);
+        return [group, sorted] as const;
+      })
+      .toSorted(([, a], [, b]) => {
+        const ua = a[0]?.updated_at ?? 0;
+        const ub = b[0]?.updated_at ?? 0;
+        return ub - ua;
+      });
+  }, [filtered, sortKey]);
+
+  const flat = useMemo(
+    () => (grouped === null ? sortSessions(filtered, sortKey) : null),
+    [filtered, sortKey, grouped],
+  );
+
+  async function handleDeleteSession(session: SessionSummary) {
+    const label = session.title ?? session.last_prompt ?? session.session_id;
+    if (!window.confirm(`Delete session "${label}"?\n\nThis removes its files from KIMI_CODE_HOME.`)) {
+      return;
+    }
+    try {
+      await deleteSession.mutateAsync(session.session_id);
+      if (sessionId === session.session_id) {
+        void navigate('/');
+      }
+    } catch (deleteError) {
+      window.alert(deleteError instanceof Error ? deleteError.message : String(deleteError));
+    }
+  }
+
+  async function handleClearSessions() {
+    const total = data?.length ?? 0;
+    if (total === 0) return;
+    if (!window.confirm(`Clear all ${total} sessions shown by vis?\n\nThis removes their files from KIMI_CODE_HOME.`)) {
+      return;
+    }
+    try {
+      const result = await clearSessions.mutateAsync();
+      void navigate('/');
+      if (result.failed.length > 0) {
+        window.alert(`Deleted ${result.deleted_count} sessions; ${result.failed.length} failed.`);
+      }
+    } catch (clearError) {
+      window.alert(clearError instanceof Error ? clearError.message : String(clearError));
+    }
+  }
+
+  return (
+    <aside className="flex h-full min-h-0 w-[320px] shrink-0 flex-col border-r border-border bg-surface-1">
+      <SessionFilter
+        search={search}
+        onSearchChange={setSearch}
+        showArchived={showArchived}
+        onShowArchivedChange={setShowArchived}
+        sortKey={sortKey}
+        onSortChange={setSortKey}
+        healthFilter={healthFilter}
+        onHealthChange={setHealthFilter}
+        totalCount={data?.length ?? 0}
+        filteredCount={filtered.length}
+        onClearSessions={() => {
+          void handleClearSessions();
+        }}
+        clearDisabled={(data?.length ?? 0) === 0 || clearSessions.isPending}
+        clearBusy={clearSessions.isPending}
+      />
+      <div className="min-h-0 flex-1 overflow-y-auto">
+        {isLoading ? (
+          <div className="p-3 font-mono text-[11px] text-fg-3">loading…</div>
+        ) : error ? (
+          <div className="p-3 font-mono text-[11px] text-[var(--color-sev-error)]">
+            {(error).message}
+          </div>
+        ) : filtered.length === 0 ? (
+          <div className="p-3 font-mono text-[11px] text-fg-3">no sessions match</div>
+        ) : grouped !== null ? (
+          grouped.map(([group, items]) => (
+            <div key={group}>
+              <div className="sticky top-0 z-10 border-b border-border bg-surface-1 px-3 py-1 font-mono text-[10px] uppercase tracking-[0.12em] text-fg-3">
+                {group} <span className="text-fg-3 tabular">· {items.length}</span>
+              </div>
+              {items.map((s) => (
+                <SessionCard
+                  key={s.session_id}
+                  session={s}
+                  onDelete={(target) => {
+                    void handleDeleteSession(target);
+                  }}
+                  deleting={deleteSession.isPending && deleteSession.variables === s.session_id}
+                />
+              ))}
+            </div>
+          ))
+        ) : (
+          flat?.map((s) => (
+            <SessionCard
+              key={s.session_id}
+              session={s}
+              onDelete={(target) => {
+                void handleDeleteSession(target);
+              }}
+              deleting={deleteSession.isPending && deleteSession.variables === s.session_id}
+            />
+          ))
+        )}
+      </div>
+    </aside>
+  );
+}
diff --git a/apps/vis/web/src/components/shared/CopyButton.tsx b/apps/vis/web/src/components/shared/CopyButton.tsx
new file mode 100644
index 000000000..d287dd044
--- /dev/null
+++ b/apps/vis/web/src/components/shared/CopyButton.tsx
@@ -0,0 +1,28 @@
+import { useState } from 'react';
+
+interface CopyButtonProps {
+  value: string;
+  label?: string;
+  className?: string;
+}
+
+export function CopyButton({ value, label = 'copy', className = '' }: CopyButtonProps) {
+  const [state, setState] = useState<'idle' | 'ok' | 'err'>('idle');
+
+  return (
+    <button
+      onClick={(e) => {
+        e.stopPropagation();
+        navigator.clipboard
+          .writeText(value)
+          .then(() =>{  setState('ok'); })
+          .catch(() =>{  setState('err'); })
+          .finally(() => setTimeout(() =>{  setState('idle'); }, 1200));
+      }}
+      className={`font-mono text-[10px] text-fg-3 transition-colors hover:text-fg-1 ${className}`}
+      title={`Copy ${value}`}
+    >
+      {state === 'idle' ? label : state === 'ok' ? '✓ copied' : '✗ err'}
+    </button>
+  );
+}
diff --git a/apps/vis/web/src/components/shared/Drawer.tsx b/apps/vis/web/src/components/shared/Drawer.tsx
new file mode 100644
index 000000000..55312b785
--- /dev/null
+++ b/apps/vis/web/src/components/shared/Drawer.tsx
@@ -0,0 +1,50 @@
+import { useEffect, type ReactNode } from 'react';
+
+interface DrawerProps {
+  open: boolean;
+  onClose: () => void;
+  title?: ReactNode;
+  children: ReactNode;
+  width?: number;
+}
+
+export function Drawer({ open, onClose, title, children, width = 560 }: DrawerProps) {
+  useEffect(() => {
+    if (!open) return;
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    window.addEventListener('keydown', handler);
+    return () =>{  window.removeEventListener('keydown', handler); };
+  }, [open, onClose]);
+
+  if (!open) return null;
+
+  return (
+    <div className="fixed inset-0 z-40">
+      <div
+        className="absolute inset-0 bg-black/60"
+        onClick={onClose}
+        aria-hidden="true"
+      />
+      <aside
+        className="absolute right-0 top-0 flex h-full flex-col border-l border-border bg-surface-1 shadow-2xl"
+        style={{ width }}
+      >
+        <div className="flex h-10 shrink-0 items-center justify-between border-b border-border px-4">
+          <span className="font-mono text-[11px] uppercase tracking-[0.1em] text-fg-1">
+            {title}
+          </span>
+          <button
+            onClick={onClose}
+            className="font-mono text-[11px] text-fg-2 hover:text-fg-0"
+            aria-label="Close drawer"
+          >
+            esc ✕
+          </button>
+        </div>
+        <div className="min-h-0 flex-1 overflow-auto">{children}</div>
+      </aside>
+    </div>
+  );
+}
diff --git a/apps/vis/web/src/components/shared/JsonViewer.tsx b/apps/vis/web/src/components/shared/JsonViewer.tsx
new file mode 100644
index 000000000..2e134740f
--- /dev/null
+++ b/apps/vis/web/src/components/shared/JsonViewer.tsx
@@ -0,0 +1,155 @@
+import { useState, memo } from 'react';
+
+interface JsonViewerProps {
+  value: unknown;
+  /** Default-open nesting depth */
+  defaultOpenDepth?: number;
+}
+
+export function JsonViewer({ value, defaultOpenDepth = 2 }: JsonViewerProps) {
+  return (
+    <div className="font-mono text-[12px] leading-[1.5]">
+      <Node value={value} depth={0} defaultOpenDepth={defaultOpenDepth} keyPath="" />
+    </div>
+  );
+}
+
+interface NodeProps {
+  value: unknown;
+  depth: number;
+  defaultOpenDepth: number;
+  keyPath: string;
+  keyLabel?: string | number;
+  isLast?: boolean;
+}
+
+const Node = memo(function Node({
+  value,
+  depth,
+  defaultOpenDepth,
+  keyPath,
+  keyLabel,
+  isLast,
+}: NodeProps) {
+  const [open, setOpen] = useState(depth < defaultOpenDepth);
+
+  if (value === null)
+    return <Leaf keyLabel={keyLabel} repr="null" color="text-fg-3" isLast={isLast} />;
+  if (value === undefined)
+    return <Leaf keyLabel={keyLabel} repr="undefined" color="text-fg-3" isLast={isLast} />;
+  if (typeof value === 'boolean')
+    return <Leaf keyLabel={keyLabel} repr={String(value)} color="text-[var(--color-cat-config)]" isLast={isLast} />;
+  if (typeof value === 'number')
+    return <Leaf keyLabel={keyLabel} repr={String(value)} color="text-[var(--color-sev-info)]" isLast={isLast} />;
+  if (typeof value === 'string') {
+    const short = value.length <= 200;
+    return (
+      <Leaf
+        keyLabel={keyLabel}
+        repr={short ? JSON.stringify(value) : `"${value.slice(0, 200)}…" (${value.length} chars)`}
+        color="text-[var(--color-cat-ephemeral)]"
+        isLast={isLast}
+      />
+    );
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0)
+      return <Leaf keyLabel={keyLabel} repr="[]" color="text-fg-3" isLast={isLast} />;
+    return (
+      <div>
+        <button
+          onClick={() =>{  setOpen((v) => !v); }}
+          className="flex items-baseline gap-1 text-left hover:text-fg-0"
+        >
+          <span className="text-fg-3 w-3 shrink-0 inline-block">{open ? '▾' : '▸'}</span>
+          {keyLabel !== undefined ? (
+            <span className="text-fg-1">{keyLabel}</span>
+          ) : null}
+          {keyLabel !== undefined ? <span className="text-fg-3">:</span> : null}
+          <span className="text-fg-3">
+            [{value.length}]
+          </span>
+        </button>
+        {open ? (
+          <div className="border-l border-border ml-[5px] pl-3">
+            {value.map((v, i) => (
+              <Node
+                key={i}
+                value={v}
+                depth={depth + 1}
+                defaultOpenDepth={defaultOpenDepth}
+                keyPath={`${keyPath}[${i}]`}
+                keyLabel={i}
+                isLast={i === value.length - 1}
+              />
+            ))}
+          </div>
+        ) : null}
+      </div>
+    );
+  }
+  if (typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length === 0)
+      return <Leaf keyLabel={keyLabel} repr="{}" color="text-fg-3" isLast={isLast} />;
+    return (
+      <div>
+        <button
+          onClick={() =>{  setOpen((v) => !v); }}
+          className="flex items-baseline gap-1 text-left hover:text-fg-0"
+        >
+          <span className="text-fg-3 w-3 shrink-0 inline-block">{open ? '▾' : '▸'}</span>
+          {keyLabel !== undefined ? (
+            <span className="text-fg-1">{keyLabel}</span>
+          ) : null}
+          {keyLabel !== undefined ? <span className="text-fg-3">:</span> : null}
+          <span className="text-fg-3">
+            {'{'}
+            {entries.length}
+            {'}'}
+          </span>
+        </button>
+        {open ? (
+          <div className="border-l border-border ml-[5px] pl-3">
+            {entries.map(([k, v], i) => (
+              <Node
+                key={k}
+                value={v}
+                depth={depth + 1}
+                defaultOpenDepth={defaultOpenDepth}
+                keyPath={`${keyPath}.${k}`}
+                keyLabel={k}
+                isLast={i === entries.length - 1}
+              />
+            ))}
+          </div>
+        ) : null}
+      </div>
+    );
+  }
+  return <Leaf keyLabel={keyLabel} repr={typeof value} color="text-fg-3" isLast={isLast} />;
+});
+
+function Leaf({
+  keyLabel,
+  repr,
+  color,
+}: {
+  keyLabel?: string | number;
+  repr: string;
+  color: string;
+  isLast?: boolean;
+}) {
+  return (
+    <div className="flex items-baseline gap-1">
+      <span className="w-3 shrink-0" />
+      {keyLabel !== undefined ? (
+        <>
+          <span className="text-fg-1">{keyLabel}</span>
+          <span className="text-fg-3">:</span>
+        </>
+      ) : null}
+      <span className={color}>{repr}</span>
+    </div>
+  );
+}
diff --git a/apps/vis/web/src/components/shared/Pill.tsx b/apps/vis/web/src/components/shared/Pill.tsx
new file mode 100644
index 000000000..58180f871
--- /dev/null
+++ b/apps/vis/web/src/components/shared/Pill.tsx
@@ -0,0 +1,78 @@
+import type { ReactNode } from 'react';
+
+export type PillTone =
+  | 'conversation'
+  | 'config'
+  | 'lifecycle'
+  | 'subagent'
+  | 'approval'
+  | 'ephemeral'
+  | 'meta'
+  | 'tools'
+  | 'user'
+  | 'assistant'
+  | 'tool'
+  | 'compaction'
+  | 'turn'
+  | 'info'
+  | 'success'
+  | 'warning'
+  | 'error'
+  | 'neutral';
+
+const TONE_VAR: Record<PillTone, string> = {
+  conversation: '--color-cat-conversation',
+  config: '--color-cat-config',
+  lifecycle: '--color-cat-lifecycle',
+  subagent: '--color-cat-subagent',
+  approval: '--color-cat-approval',
+  ephemeral: '--color-cat-ephemeral',
+  meta: '--color-cat-meta',
+  tools: '--color-cat-tools',
+  user: '--color-user',
+  assistant: '--color-assistant',
+  tool: '--color-tool',
+  compaction: '--color-compaction',
+  turn: '--color-turn',
+  info: '--color-sev-info',
+  success: '--color-sev-success',
+  warning: '--color-sev-warning',
+  error: '--color-sev-error',
+  neutral: '--color-fg-2',
+};
+
+interface PillProps {
+  tone?: PillTone;
+  variant?: 'solid' | 'soft' | 'outline';
+  children: ReactNode;
+  title?: string;
+  className?: string;
+}
+
+export function Pill({
+  tone = 'neutral',
+  variant = 'soft',
+  children,
+  title,
+  className = '',
+}: PillProps) {
+  const color = `var(${TONE_VAR[tone]})`;
+  const style =
+    variant === 'solid'
+      ? { backgroundColor: color, color: 'var(--color-on-accent)' }
+      : variant === 'outline'
+        ? { border: `1px solid ${color}`, color }
+        : {
+            backgroundColor: `color-mix(in oklab, ${color} 18%, transparent)`,
+            color,
+          };
+  return (
+    <span
+      className={`pill ${className}`}
+      style={style}
+      title={title}
+    >
+      {children}
+    </span>
+  );
+}
diff --git a/apps/vis/web/src/components/shared/SizePreview.tsx b/apps/vis/web/src/components/shared/SizePreview.tsx
new file mode 100644
index 000000000..aa3e4ef88
--- /dev/null
+++ b/apps/vis/web/src/components/shared/SizePreview.tsx
@@ -0,0 +1,55 @@
+import { useState, type ReactNode } from 'react';
+
+interface SizePreviewProps {
+  label?: string;
+  /** Byte/char count for the dim label */
+  sizeBytes: number;
+  /** Preview text shown when collapsed (first ~200 chars) */
+  preview?: string;
+  /** Full content renderer */
+  children: ReactNode;
+  /** Start expanded if true */
+  defaultOpen?: boolean;
+}
+
+export function SizePreview({
+  label = 'payload',
+  sizeBytes,
+  preview,
+  children,
+  defaultOpen = false,
+}: SizePreviewProps) {
+  const [open, setOpen] = useState(defaultOpen);
+  const size = formatBytes(sizeBytes);
+  return (
+    <div className="my-1 border border-border bg-surface-0">
+      <button
+        onClick={() =>{  setOpen((v) => !v); }}
+        className="flex w-full items-center justify-between gap-2 px-2 py-1 font-mono text-[11px] text-fg-2 hover:bg-surface-2 hover:text-fg-1"
+      >
+        <span className="flex items-center gap-2">
+          <span className="text-fg-3">{open ? '▾' : '▸'}</span>
+          <span className="uppercase tracking-[0.08em]">{label}</span>
+          <span className="text-fg-3 tabular">{size}</span>
+        </span>
+        {!open && preview ? (
+          <span className="truncate text-fg-3 font-mono text-[11px]">
+            {preview.slice(0, 120)}
+            {preview.length > 120 ? '…' : ''}
+          </span>
+        ) : null}
+      </button>
+      {open ? (
+        <div className="border-t border-border px-2 py-1 font-mono text-[12px]">
+          {children}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+  return `${(n / 1024 / 1024).toFixed(2)}MB`;
+}
diff --git a/apps/vis/web/src/components/state/StateTab.tsx b/apps/vis/web/src/components/state/StateTab.tsx
new file mode 100644
index 000000000..39a105d7e
--- /dev/null
+++ b/apps/vis/web/src/components/state/StateTab.tsx
@@ -0,0 +1,217 @@
+import { useState, type ReactNode } from 'react';
+
+import type { SessionState } from '../../types';
+import { formatAbsoluteTime, formatRelativeTime } from '../../util/time';
+import { CopyButton } from '../shared/CopyButton';
+import { JsonViewer } from '../shared/JsonViewer';
+
+interface StateTabProps {
+  state: SessionState;
+  protocolVersion: string | null;
+}
+
+/** Keys whose values should be interpreted as epoch milliseconds and
+ *  decorated with both an absolute time and "2h ago" style relative label.
+ *  Matches the shape of state.json written by `@moonshot-ai/agent-core`. */
+const EPOCH_MS_KEYS = new Set(['created_at', 'updated_at', 'last_turn_time']);
+
+/** Keys whose values tend to be long paths worth copying with one click. */
+const COPY_KEYS = new Set(['workspace_dir', 'plan_slug', 'session_id']);
+
+export function StateTab({ state, protocolVersion }: StateTabProps) {
+  const [showRaw, setShowRaw] = useState(false);
+  const entries = Object.entries(state);
+
+  return (
+    <div className="min-h-0 flex-1 overflow-y-auto p-4">
+      <div className="flex items-center justify-between">
+        <div className="font-mono text-[11px] uppercase tracking-[0.12em] text-fg-3">
+          state.json
+          {protocolVersion ? ` · wire protocol ${protocolVersion}` : ''}
+        </div>
+        <div className="flex items-center gap-3">
+          <CopyButton value={JSON.stringify(state, null, 2)} label="copy json" />
+          <button
+            onClick={() =>{  setShowRaw((v) => !v); }}
+            className="font-mono text-[10px] text-fg-3 hover:text-fg-1"
+          >
+            {showRaw ? '[ hide raw ]' : '[ {…} raw json ]'}
+          </button>
+        </div>
+      </div>
+
+      <DurationRow state={state} />
+
+      <div className="mt-4 border border-border bg-surface-0">
+        <table className="w-full font-mono text-[12px]">
+          <tbody>
+            {entries.map(([k, v]) => (
+              <StateRow key={k} keyName={k} value={v} />
+            ))}
+          </tbody>
+        </table>
+      </div>
+
+      {showRaw ? (
+        <div className="mt-4 border border-border bg-surface-0 p-3">
+          <JsonViewer value={state} defaultOpenDepth={3} />
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/** Derive a human duration from created_at + updated_at when both are
+ *  valid epoch-ms numbers. Rendered just under the header as a single dim
+ *  line — omitted silently when data is missing. */
+function DurationRow({ state }: { state: SessionState }) {
+  const created = state.created_at;
+  const updated = state.updated_at;
+  if (typeof created !== 'number' || typeof updated !== 'number') return null;
+  if (updated < created) return null;
+  const ms = updated - created;
+  return (
+    <div className="mt-2 font-mono text-[11px] text-fg-3">
+      duration <span className="text-fg-1">{formatDuration(ms)}</span>
+      {' · '}
+      from <span className="text-fg-1">{formatAbsoluteTime(created)}</span>
+      {' → '}
+      <span className="text-fg-1">{formatAbsoluteTime(updated)}</span>
+    </div>
+  );
+}
+
+function StateRow({ keyName, value }: { keyName: string; value: unknown }) {
+  return (
+    <tr className="border-b border-border last:border-b-0 align-top">
+      <td className="w-[200px] border-r border-border bg-surface-1 px-3 py-1.5 text-right text-fg-2">
+        {keyName}
+      </td>
+      <td className="px-3 py-1.5 text-fg-0 break-words">
+        <ValueCell keyName={keyName} value={value} />
+      </td>
+    </tr>
+  );
+}
+
+function ValueCell({ keyName, value }: { keyName: string; value: unknown }) {
+  if (value === null || value === undefined) return <span className="text-fg-3">null</span>;
+
+  if (typeof value === 'boolean') {
+    return (
+      <span className={value ? 'text-[var(--color-sev-success)]' : 'text-fg-3'}>
+        {String(value)}
+      </span>
+    );
+  }
+
+  if (typeof value === 'number') {
+    if (EPOCH_MS_KEYS.has(keyName) && value > 1_000_000_000_000) {
+      return (
+        <span className="flex flex-wrap items-center gap-2">
+          <span className="text-[var(--color-sev-info)] tabular">{formatAbsoluteTime(value)}</span>
+          <span className="text-fg-3">·</span>
+          <span className="text-fg-2">{formatRelativeTime(value)}</span>
+          <span className="text-fg-3">·</span>
+          <span className="text-fg-3 tabular">{value}</span>
+        </span>
+      );
+    }
+    return <span className="text-[var(--color-sev-info)] tabular">{value}</span>;
+  }
+
+  if (typeof value === 'string') {
+    const withCopy = COPY_KEYS.has(keyName);
+    return (
+      <span className="flex flex-wrap items-center gap-2">
+        <span className="text-[var(--color-cat-ephemeral)] break-all">"{value}"</span>
+        {withCopy ? <CopyButton value={value} /> : null}
+      </span>
+    );
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return <span className="text-fg-3">[]</span>;
+    // Arrays of primitives render inline; arrays of objects use JsonViewer.
+    const allPrim = value.every((v) => typeof v !== 'object' || v === null);
+    if (allPrim) {
+      return (
+        <span className="flex flex-wrap items-center gap-1">
+          {(value as unknown[]).map((v, i) => (
+            <span
+              key={i}
+              className="border border-border bg-surface-1 px-1.5 py-0.5 text-[11px] text-fg-1"
+            >
+              {typeof v === 'string' ? v : String(v)}
+            </span>
+          ))}
+        </span>
+      );
+    }
+    return <JsonViewer value={value} defaultOpenDepth={2} />;
+  }
+
+  // Nested object: render as a compact sub-table so fields like `producer`
+  // read as structured data instead of a JSON.stringify blob.
+  return <NestedObject value={value as Record<string, unknown>} />;
+}
+
+function NestedObject({ value }: { value: Record<string, unknown> }) {
+  const entries = Object.entries(value);
+  if (entries.length === 0) return <span className="text-fg-3">{'{}'}</span>;
+  return (
+    <div className="inline-block border border-border bg-surface-1">
+      <table className="font-mono text-[11.5px]">
+        <tbody>
+          {entries.map(([k, v]) => (
+            <tr key={k} className="border-b border-border last:border-b-0 align-top">
+              <td className="border-r border-border px-2 py-0.5 text-right text-fg-3">{k}</td>
+              <td className="px-2 py-0.5 text-fg-0 break-all">
+                <NestedValue value={v} />
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+function NestedValue({ value }: { value: unknown }): ReactNode {
+  if (value === null || value === undefined) return <span className="text-fg-3">null</span>;
+  if (typeof value === 'boolean') {
+    return (
+      <span className={value ? 'text-[var(--color-sev-success)]' : 'text-fg-3'}>
+        {String(value)}
+      </span>
+    );
+  }
+  if (typeof value === 'number')
+    return <span className="text-[var(--color-sev-info)] tabular">{value}</span>;
+  if (typeof value === 'string')
+    return <span className="text-[var(--color-cat-ephemeral)]">"{value}"</span>;
+  if (Array.isArray(value)) {
+    return (
+      <span className="text-fg-1">
+        [{value.length} item{value.length === 1 ? '' : 's'}]
+      </span>
+    );
+  }
+  return <NestedObject value={value as Record<string, unknown>} />;
+}
+
+/** Format a duration in ms as "3h 14m" / "12m 30s" / "45s". */
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const rs = s % 60;
+  if (m < 60) return rs > 0 ? `${m}m ${rs}s` : `${m}m`;
+  const h = Math.floor(m / 60);
+  const rm = m % 60;
+  if (h < 24) return rm > 0 ? `${h}h ${rm}m` : `${h}h`;
+  const d = Math.floor(h / 24);
+  const rh = h % 24;
+  return rh > 0 ? `${d}d ${rh}h` : `${d}d`;
+}
diff --git a/apps/vis/web/src/components/subagents/SubagentNode.tsx b/apps/vis/web/src/components/subagents/SubagentNode.tsx
new file mode 100644
index 000000000..4fedaa485
--- /dev/null
+++ b/apps/vis/web/src/components/subagents/SubagentNode.tsx
@@ -0,0 +1,92 @@
+import { Link, useParams } from 'react-router-dom';
+import type { SubagentNode as SubagentNodeT } from '../../types';
+import { Pill, type PillTone } from '../shared/Pill';
+import { formatRelativeTime } from '../../util/time';
+
+const STATUS_TONE: Record<SubagentNodeT['status'], PillTone> = {
+  running: 'info',
+  completed: 'success',
+  failed: 'error',
+  killed: 'neutral',
+  lost: 'warning',
+  unknown: 'neutral',
+};
+
+interface Props {
+  node: SubagentNodeT;
+  sessionId: string;
+}
+
+export function SubagentNode({ node, sessionId }: Props) {
+  const { agentId: activeAgentId } = useParams<{ agentId?: string }>();
+  const selected = activeAgentId === node.agent_id;
+  const shortId = node.agent_id.replace(/^sub_/, '').slice(0, 10);
+
+  return (
+    <div className="my-1">
+      <Link
+        to={`/sessions/${sessionId}/subagents/${node.agent_id}`}
+        className={[
+          'relative flex items-start gap-3 border border-border bg-surface-0 px-3 py-2 transition-colors hover:bg-surface-1',
+          selected ? 'border-[var(--color-cat-subagent)]' : '',
+        ].join(' ')}
+      >
+        <span
+          className="mt-[3px] inline-block h-[7px] w-[7px] rounded-full shrink-0"
+          style={{
+            backgroundColor: `var(${STATUS_COLOR_VAR[node.status]})`,
+          }}
+          title={node.status}
+        />
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-2">
+            <Pill tone="subagent" variant="soft">
+              {node.subagent_type ?? 'unknown'}
+            </Pill>
+            <span className="font-mono text-[12px] text-fg-0">{shortId}</span>
+            <Pill tone={STATUS_TONE[node.status]} variant="outline">
+              {node.status}
+            </Pill>
+            {node.run_in_background ? (
+              <Pill tone="subagent" variant="outline">bg</Pill>
+            ) : null}
+            <span className="ml-auto font-mono text-[10.5px] text-fg-3 tabular">
+              depth {node.depth} · {formatRelativeTime(node.spawn_time)}
+            </span>
+          </div>
+          {node.agent_name ? (
+            <div className="mt-0.5 font-mono text-[11px] text-fg-2">
+              {node.agent_name}
+            </div>
+          ) : null}
+          {node.result_summary ? (
+            <div className="mt-1 font-mono text-[12px] text-fg-1 line-clamp-3">
+              {node.result_summary}
+            </div>
+          ) : null}
+          {node.error ? (
+            <div className="mt-1 font-mono text-[12px] text-[var(--color-sev-error)] line-clamp-3">
+              {node.error}
+            </div>
+          ) : null}
+        </div>
+      </Link>
+      {node.children.length > 0 ? (
+        <div className="mt-1 border-l border-border pl-3 ml-3">
+          {node.children.map((c) => (
+            <SubagentNode key={c.agent_id} node={c} sessionId={sessionId} />
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+const STATUS_COLOR_VAR: Record<SubagentNodeT['status'], string> = {
+  running: '--color-sev-info',
+  completed: '--color-sev-success',
+  failed: '--color-sev-error',
+  killed: '--color-fg-3',
+  lost: '--color-sev-warning',
+  unknown: '--color-fg-3',
+};
diff --git a/apps/vis/web/src/components/subagents/SubagentTree.tsx b/apps/vis/web/src/components/subagents/SubagentTree.tsx
new file mode 100644
index 000000000..40f8e7f20
--- /dev/null
+++ b/apps/vis/web/src/components/subagents/SubagentTree.tsx
@@ -0,0 +1,24 @@
+import type { SubagentNode as SubagentNodeT } from '../../types';
+import { SubagentNode } from './SubagentNode';
+
+interface SubagentTreeProps {
+  tree: SubagentNodeT[];
+  sessionId: string;
+}
+
+export function SubagentTree({ tree, sessionId }: SubagentTreeProps) {
+  if (tree.length === 0) {
+    return (
+      <div className="p-6 font-mono text-[12px] text-fg-3">
+        no subagents spawned in this session
+      </div>
+    );
+  }
+  return (
+    <div className="p-3">
+      {tree.map((node) => (
+        <SubagentNode key={node.agent_id} node={node} sessionId={sessionId} />
+      ))}
+    </div>
+  );
+}
diff --git a/apps/vis/web/src/components/subagents/SubagentsTab.tsx b/apps/vis/web/src/components/subagents/SubagentsTab.tsx
new file mode 100644
index 000000000..1f9879dfa
--- /dev/null
+++ b/apps/vis/web/src/components/subagents/SubagentsTab.tsx
@@ -0,0 +1,28 @@
+import { useSubagents } from '../../hooks/useSubagents';
+import { SubagentTree } from './SubagentTree';
+
+interface SubagentsTabProps {
+  sessionId: string;
+}
+
+export function SubagentsTab({ sessionId }: SubagentsTabProps) {
+  const { data, isLoading, error } = useSubagents(sessionId);
+
+  if (isLoading) {
+    return <div className="p-6 font-mono text-[12px] text-fg-3">loading subagents…</div>;
+  }
+  if (error) {
+    return (
+      <div className="p-6 font-mono text-[12px] text-[var(--color-sev-error)]">
+        {(error).message}
+      </div>
+    );
+  }
+  if (!data) return null;
+
+  return (
+    <div className="min-h-0 flex-1 overflow-y-auto">
+      <SubagentTree tree={data.tree} sessionId={sessionId} />
+    </div>
+  );
+}
diff --git a/apps/vis/web/src/components/wire/IssuesDrawer.tsx b/apps/vis/web/src/components/wire/IssuesDrawer.tsx
new file mode 100644
index 000000000..d7cbd1d78
--- /dev/null
+++ b/apps/vis/web/src/components/wire/IssuesDrawer.tsx
@@ -0,0 +1,144 @@
+import { useEffect } from 'react';
+
+import type { Issue, IssueSeverity } from '../../lib/issues';
+
+interface IssuesDrawerProps {
+  issues: Issue[];
+  onClose: () => void;
+  onJumpTo?: (seq: number) => void;
+  /** Optional predicate: "is this seq currently visible under the active
+   *  filter?". When provided, jump buttons for filtered-out seqs are
+   *  disabled and flagged. */
+  isSeqVisible?: (seq: number) => boolean;
+}
+
+const SEV_COLOR: Record<IssueSeverity, string> = {
+  error: 'var(--color-sev-error)',
+  warning: 'var(--color-sev-warning)',
+  info: 'var(--color-sev-info)',
+};
+
+const KIND_LABEL: Record<Issue['kind'], string> = {
+  subagent_failed: 'subagent failed',
+  tool_error: 'tool error',
+  tool_denied: 'tool denied',
+  turn_failed: 'turn failed',
+  step_truncated: 'step truncated',
+  wire_warning: 'wire warning',
+};
+
+export function IssuesDrawer({ issues, onClose, onJumpTo, isSeqVisible }: IssuesDrawerProps) {
+  // ESC closes — standard drawer affordance.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    window.addEventListener('keydown', onKey);
+    return () =>{  window.removeEventListener('keydown', onKey); };
+  }, [onClose]);
+
+  return (
+    <>
+      {/* Backdrop — click outside drawer to dismiss. Subtle tint so the
+          underlying Wire timeline is still readable. */}
+      <button
+        type="button"
+        aria-label="close issues"
+        onClick={onClose}
+        className="absolute inset-0 z-10 bg-black/20"
+      />
+      {/* Drawer — slides from the right. 320px wide, full height. */}
+      <aside
+        className="absolute right-0 top-0 bottom-0 z-20 flex w-[360px] flex-col border-l border-border bg-surface-1 shadow-[-8px_0_32px_rgba(0,0,0,0.25)]"
+        role="dialog"
+        aria-label="issues"
+      >
+        <header className="flex shrink-0 items-center justify-between border-b border-border px-3 py-2 font-mono text-[12px] text-fg-0">
+          <span>
+            Issues <span className="text-fg-3">·</span>{' '}
+            <span className="tabular text-fg-2">{issues.length}</span>
+          </span>
+          <button
+            type="button"
+            onClick={onClose}
+            className="font-mono text-[14px] text-fg-3 hover:text-fg-0"
+            title="close (ESC)"
+          >
+            ×
+          </button>
+        </header>
+        <div className="min-h-0 flex-1 overflow-y-auto">
+          {issues.length === 0 ? (
+            <div className="p-6 font-mono text-[12px] text-fg-3">no issues detected</div>
+          ) : (
+            <ul className="divide-y divide-border">
+              {issues.map((iss, i) => (
+                <IssueItem
+                  key={`${iss.kind}-${iss.seq ?? 'w'}-${i}`}
+                  issue={iss}
+                  onJumpTo={onJumpTo}
+                  onClose={onClose}
+                  isSeqVisible={isSeqVisible}
+                />
+              ))}
+            </ul>
+          )}
+        </div>
+      </aside>
+    </>
+  );
+}
+
+function IssueItem({
+  issue,
+  onJumpTo,
+  onClose,
+  isSeqVisible,
+}: {
+  issue: Issue;
+  onJumpTo?: (seq: number) => void;
+  onClose: () => void;
+  isSeqVisible?: (seq: number) => boolean;
+}) {
+  const color = SEV_COLOR[issue.severity];
+  const seq = issue.seq;
+  const hidden = seq !== null && isSeqVisible !== undefined && !isSeqVisible(seq);
+  const canJump = seq !== null && onJumpTo !== undefined && !hidden;
+  return (
+    <li className="px-3 py-2 hover:bg-surface-2">
+      <div className="flex items-center gap-2 font-mono text-[11px]">
+        <span
+          className="inline-block h-[8px] w-[8px] shrink-0 rounded-full"
+          style={{ backgroundColor: color }}
+          aria-hidden="true"
+        />
+        <span className="text-fg-1">{KIND_LABEL[issue.kind]}</span>
+        {seq !== null ? (
+          <>
+            <span className="text-fg-3">·</span>
+            <span className="tabular text-fg-3">seq {seq}</span>
+          </>
+        ) : null}
+        {hidden ? <span className="text-fg-3">(filtered out)</span> : null}
+        {seq !== null ? (
+          <button
+            type="button"
+            disabled={!canJump}
+            onClick={() => {
+              if (canJump) onJumpTo?.(seq);
+              onClose();
+            }}
+            className="ml-auto text-fg-3 hover:text-fg-0 disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:text-fg-3"
+            title={hidden ? 'record is filtered out' : 'scroll to + expand'}
+          >
+            jump →
+          </button>
+        ) : null}
+      </div>
+      <div className="mt-1 break-words font-mono text-[12px] text-fg-0">{issue.summary}</div>
+      {issue.detail !== undefined ? (
+        <div className="mt-0.5 break-words font-mono text-[10.5px] text-fg-3">{issue.detail}</div>
+      ) : null}
+    </li>
+  );
+}
diff --git a/apps/vis/web/src/components/wire/TypeBadge.tsx b/apps/vis/web/src/components/wire/TypeBadge.tsx
new file mode 100644
index 000000000..fbd1af1cb
--- /dev/null
+++ b/apps/vis/web/src/components/wire/TypeBadge.tsx
@@ -0,0 +1,20 @@
+import type { WireRecordType } from '../../types';
+import { Pill } from '../shared/Pill';
+import { TYPE_ICON, TYPE_TONE } from './typeMeta';
+
+interface TypeBadgeProps {
+  type: WireRecordType;
+}
+
+export function TypeBadge({ type }: TypeBadgeProps) {
+  const icon = TYPE_ICON[type];
+  const tone = TYPE_TONE[type];
+  return (
+    <Pill tone={tone} variant="soft">
+      <span className="tabular" aria-hidden="true">
+        {icon}
+      </span>
+      <span>{type}</span>
+    </Pill>
+  );
+}
diff --git a/apps/vis/web/src/components/wire/WireHeadline.tsx b/apps/vis/web/src/components/wire/WireHeadline.tsx
new file mode 100644
index 000000000..2ff6126ea
--- /dev/null
+++ b/apps/vis/web/src/components/wire/WireHeadline.tsx
@@ -0,0 +1,733 @@
+import type { ReactNode } from 'react';
+
+import { useFocus, type FocusKind } from '../../lib/focus-context';
+import type { VisWireRecord } from '../../types';
+import { Pill } from '../shared/Pill';
+import { formatBytes } from '../shared/SizePreview';
+
+export interface HeadlineRender {
+  /** Main headline content — rendered in the flex-grow slot of the row */
+  main: ReactNode;
+  /** Right-side badges / pair refs */
+  right?: ReactNode;
+}
+
+function truncate(s: unknown, n: number): string {
+  let str: string;
+  if (s === null || s === undefined) str = '';
+  else if (typeof s === 'string') str = s;
+  else if (typeof s === 'number' || typeof s === 'boolean' || typeof s === 'bigint')
+    str = String(s);
+  else {
+    try {
+      str = JSON.stringify(s);
+    } catch {
+      return '[unserializable]';
+    }
+  }
+  if (str.length <= n) return str;
+  return str.slice(0, n) + '…';
+}
+
+/** Narrow an `unknown` to a string — used for wire-record field values that
+ *  are typed `unknown` but practically always string/null in the field we read. */
+function asStr(v: unknown, fallback = '—'): string {
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  return fallback;
+}
+
+function byteLength(v: unknown): number {
+  if (typeof v === 'string') return v.length;
+  if (v === undefined || v === null) return 0;
+  try {
+    return JSON.stringify(v).length;
+  } catch {
+    return 0;
+  }
+}
+
+/** Render the collapsed-headline for a wire record. */
+export function renderHeadline(r: VisWireRecord): HeadlineRender {
+  switch (r.type) {
+    // ─── FILE HEADER / STARTUP BASELINE ───
+    case 'metadata': {
+      const pv = r['protocol_version'] as string | undefined;
+      const producer = r['producer'] as
+        | { kind?: string; name?: string; version?: string }
+        | undefined;
+      const kimiVer = r['kimi_version'] as string | undefined;
+      const fileName = r['file_name'] as string | undefined;
+      const prodStr = producer ? `${producer.name ?? '?'}@${producer.version ?? '?'}` : 'legacy';
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <Mono>protocol v{pv ?? '?'}</Mono>
+            <Dim>·</Dim>
+            <Mono className="truncate">{prodStr}</Mono>
+            {kimiVer ? <Dim className="truncate">· kimi {kimiVer}</Dim> : null}
+          </span>
+        ),
+        right: fileName ? <Dim>{fileName}</Dim> : null,
+      };
+    }
+
+    case 'session_initialized': {
+      const agentType = r['agent_type'] as string | undefined;
+      const model = r['model'] as string | undefined;
+      const sysPrompt = r['system_prompt'] as string | undefined;
+      const tools = (r['active_tools'] as string[] | undefined) ?? [];
+      const permMode = r['permission_mode'] as string | undefined;
+      const planMode = r['plan_mode'] as boolean | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <Mono>{model ?? '—'}</Mono>
+            <Dim>·</Dim>
+            <Mono>{tools.length} tools</Mono>
+            <Dim>·</Dim>
+            <Mono>{permMode ?? '—'}</Mono>
+            {planMode ? (
+              <Pill tone="config" variant="soft">
+                plan
+              </Pill>
+            ) : null}
+            <Dim>·</Dim>
+            <span className="truncate text-fg-1">
+              sp: {truncate(sysPrompt ?? '', 70) || <Dim>(empty)</Dim>}
+            </span>
+          </span>
+        ),
+        right: (
+          <Pill
+            tone={
+              agentType === 'sub'
+                ? 'subagent'
+                : agentType === 'independent'
+                  ? 'lifecycle'
+                  : 'config'
+            }
+            variant="outline"
+          >
+            {agentType ?? 'main'}
+          </Pill>
+        ),
+      };
+    }
+
+    // ─── CONVERSATION ───
+    case 'turn_begin': {
+      const agentType = r['agent_type'] as string | undefined;
+      const kind = r['input_kind'] as string | undefined;
+      const input = r['user_input'] as string | undefined;
+      const turnId = r['turn_id'] as string | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <Mono>turn #</Mono>
+            <IdBadge kind="turn_id" value={turnId} />
+            <Dim>kind={kind ?? '—'}</Dim>
+            {input ? <span className="truncate text-fg-1">· {truncate(input, 80)}</span> : null}
+          </span>
+        ),
+        right: (
+          <Pill
+            tone={
+              agentType === 'sub' ? 'subagent' : agentType === 'independent' ? 'lifecycle' : 'turn'
+            }
+            variant="outline"
+          >
+            {agentType ?? 'main'}
+          </Pill>
+        ),
+      };
+    }
+
+    case 'turn_end': {
+      const reason = r['reason'] as string | undefined;
+      const success = r['success'] as boolean | undefined;
+      const usage = r['usage'] as Record<string, unknown> | undefined;
+      const synthetic = r['synthetic'] as boolean | undefined;
+      const outputTokens = usage?.['output_tokens'] as number | undefined;
+      const cost = usage?.['cost_usd'] as number | undefined;
+      const turnId = r['turn_id'] as string | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2">
+            <Mono>turn #</Mono>
+            <IdBadge kind="turn_id" value={turnId} />
+            <span
+              className={
+                success ? 'text-[var(--color-sev-success)]' : 'text-[var(--color-sev-error)]'
+              }
+            >
+              {reason}
+            </span>
+          </span>
+        ),
+        right: (
+          <span className="flex items-center gap-2">
+            {synthetic ? (
+              <Pill tone="warning" variant="outline">
+                synthetic
+              </Pill>
+            ) : null}
+            {outputTokens !== undefined ? <Dim>{outputTokens}tok</Dim> : null}
+            {cost !== undefined ? <Dim>${cost.toFixed(4)}</Dim> : null}
+          </span>
+        ),
+      };
+    }
+
+    case 'user_message': {
+      const content = r['content'];
+      const text =
+        typeof content === 'string'
+          ? content
+          : Array.isArray(content)
+            ? (content as { type: string; text?: string }[])
+                .map((p) => (p.type === 'text' ? (p.text ?? '') : `<${p.type}>`))
+                .join('')
+            : '';
+      const parts = Array.isArray(content) ? content.length : 1;
+      return {
+        main: (
+          <span className="truncate text-fg-0">{truncate(text, 120) || <Dim>(empty)</Dim>}</span>
+        ),
+        right: parts > 1 ? <Dim>{parts} parts</Dim> : undefined,
+      };
+    }
+
+    // An "assistant message" is now a sequence of atoms: step_begin →
+    // (content_part | tool_call)* → step_end. Render each atom distinctly so
+    // the wire timeline stays a 1:1 view of the underlying records.
+    case 'step_begin': {
+      const uuid = r['uuid'] as string | undefined;
+      const step = r['step'] as number | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2">
+            <Mono>step #{step ?? '—'}</Mono>
+            <IdBadge kind="step_uuid" value={uuid} shortenTo={10} />
+          </span>
+        ),
+      };
+    }
+
+    case 'step_end': {
+      const step = r['step'] as number | undefined;
+      const finish = r['finish_reason'] as string | undefined;
+      const usage = r['usage'] as Record<string, unknown> | undefined;
+      const outputTokens = usage?.['output_tokens'] as number | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2">
+            <Mono>step #{step ?? '—'}</Mono>
+            {finish ? <Dim>{finish}</Dim> : null}
+          </span>
+        ),
+        right: outputTokens !== undefined ? <Dim>{outputTokens}tok</Dim> : undefined,
+      };
+    }
+
+    case 'content_part': {
+      const part = r['part'] as
+        | { kind: 'text' | 'think'; text?: string; think?: string }
+        | undefined;
+      if (part === undefined) {
+        return { main: <Dim>(empty part)</Dim> };
+      }
+      const body = part.kind === 'text' ? (part.text ?? '') : (part.think ?? '');
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <Pill tone={part.kind === 'think' ? 'config' : 'assistant'} variant="soft">
+              {part.kind}
+            </Pill>
+            <span className="truncate text-fg-0">{truncate(body, 100) || <Dim>(empty)</Dim>}</span>
+          </span>
+        ),
+        right: <Dim>{formatBytes(body.length)}</Dim>,
+      };
+    }
+
+    case 'tool_call': {
+      const d = (r as { data?: Record<string, unknown> }).data ?? {};
+      const name = d['tool_name'] as string | undefined;
+      const args = d['args'];
+      const preview =
+        typeof args === 'string' ? args : args !== undefined ? JSON.stringify(args) : '';
+      const activity = d['description'] as string | undefined;
+      const callId = d['tool_call_id'] as string | undefined;
+      const step = r['step'] as number | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <Mono className="text-[var(--color-cat-tools)]">{name ?? '—'}</Mono>
+            {activity ? (
+              <span className="truncate text-fg-1">— {truncate(activity, 60)}</span>
+            ) : (
+              <span className="truncate font-mono text-[12px] text-fg-1">
+                ({truncate(preview, 60)})
+              </span>
+            )}
+          </span>
+        ),
+        right: (
+          <span className="flex items-center gap-2">
+            {callId ? (
+              <span className="flex items-center gap-1">
+                <Dim>call=</Dim>
+                <IdBadge kind="tool_call_id" value={callId} shortenTo={10} />
+              </span>
+            ) : null}
+            {step !== undefined ? <Dim>step={step}</Dim> : null}
+          </span>
+        ),
+      };
+    }
+
+    case 'tool_result': {
+      const output = r['output'];
+      const isError = r['is_error'] as boolean | undefined;
+      const synthetic = r['synthetic'] as boolean | undefined;
+      const callId = r['tool_call_id'] as string | undefined;
+      const outputBytes = byteLength(output);
+      const isPersisted =
+        typeof output === 'string' && output.trimStart().startsWith('<persisted-output');
+      return {
+        main: (
+          <span className="flex items-center gap-2">
+            <Mono>call=</Mono>
+            <IdBadge kind="tool_call_id" value={callId} shortenTo={10} />
+            <Dim>
+              {typeof output === 'string'
+                ? 'string'
+                : Array.isArray(output)
+                  ? 'array'
+                  : typeof output}
+            </Dim>
+            <Dim>{formatBytes(outputBytes)}</Dim>
+            {isPersisted ? (
+              <Pill tone="compaction" variant="outline">
+                persisted
+              </Pill>
+            ) : null}
+          </span>
+        ),
+        right: (
+          <span className="flex items-center gap-2">
+            {synthetic ? (
+              <Pill tone="warning" variant="outline">
+                synthetic
+              </Pill>
+            ) : null}
+            {isError ? (
+              <Pill tone="error" variant="solid">
+                error
+              </Pill>
+            ) : null}
+          </span>
+        ),
+      };
+    }
+
+    case 'compaction': {
+      const summary = r['summary'] as string | undefined;
+      const pre = r['pre_compact_tokens'] as number | undefined;
+      const post = r['post_compact_tokens'] as number | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <Pill tone="compaction" variant="solid">
+              summary
+            </Pill>
+            {summary ? <span className="truncate text-fg-1">{truncate(summary, 80)}</span> : null}
+            {pre !== undefined && post !== undefined ? (
+              <Dim>
+                · {pre}→{post} tok
+              </Dim>
+            ) : null}
+          </span>
+        ),
+      };
+    }
+
+    // ─── CONFIG ───
+    case 'system_prompt_changed': {
+      const prompt = r['new_prompt'] as string | undefined;
+      return {
+        main: (
+          <span className="truncate text-fg-0">
+            {truncate(prompt ?? '', 60) || <Dim>(empty)</Dim>}
+          </span>
+        ),
+        right: <Dim>{formatBytes(byteLength(prompt))}</Dim>,
+      };
+    }
+
+    case 'tools_changed': {
+      const op = r['operation'] as string | undefined;
+      const tools = (r['tools'] as string[] | undefined) ?? [];
+      const head = tools.slice(0, 3).join(', ');
+      const rest = tools.length > 3 ? ` +${tools.length - 3} more` : '';
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <Pill tone="config" variant="soft">
+              {op ?? '—'}
+            </Pill>
+            <Mono className="truncate">
+              {head}
+              {rest}
+            </Mono>
+          </span>
+        ),
+      };
+    }
+
+    // ─── EPHEMERAL ───
+    case 'system_reminder': {
+      const content = r['content'] as string | undefined;
+      const consumed = r['consumed_at_turn'] as number | undefined;
+      return {
+        main: <span className="truncate text-fg-0">{truncate(content ?? '', 80)}</span>,
+        right:
+          consumed !== undefined ? (
+            <Dim>consumed@turn{consumed}</Dim>
+          ) : (
+            <Pill tone="ephemeral" variant="outline">
+              pending
+            </Pill>
+          ),
+      };
+    }
+
+    // ─── META ───
+    case 'notification': {
+      const d = (r as { data?: Record<string, unknown> }).data ?? {};
+      const severity = d['severity'] as string | undefined;
+      const title = d['title'] as string | undefined;
+      const category = d['category'] as string | undefined;
+      const targets = (d['targets'] as string[] | undefined) ?? [];
+      const sevTone =
+        severity === 'error'
+          ? 'error'
+          : severity === 'warning'
+            ? 'warning'
+            : severity === 'success'
+              ? 'success'
+              : 'info';
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <Pill tone={sevTone} variant="soft">
+              {severity ?? '—'}
+            </Pill>
+            <span className="truncate text-fg-0">{truncate(title ?? '', 80)}</span>
+            {category ? <Dim>({category})</Dim> : null}
+          </span>
+        ),
+        right:
+          targets.length > 0 ? (
+            <span className="flex items-center gap-1">
+              {targets.map((t) => (
+                <Pill key={t} tone="meta" variant="outline">
+                  {t}
+                </Pill>
+              ))}
+            </span>
+          ) : undefined,
+      };
+    }
+
+    case 'team_mail': {
+      const d = (r as { data?: Record<string, unknown> }).data ?? {};
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <Mono>
+              {asStr(d['from_agent'])} → {asStr(d['to_agent'])}
+            </Mono>
+            <span className="truncate text-fg-1">{truncate(d['content'], 60)}</span>
+          </span>
+        ),
+      };
+    }
+
+    // ─── TOOLS ───
+    // Note: the `tool_call` case is handled in the conversation section
+    // above (alongside step_begin / step_end / content_part).
+
+    case 'tool_denied': {
+      const d = (r as { data?: Record<string, unknown> }).data ?? {};
+      const name = d['tool_name'] as string | undefined;
+      const reason = d['reason'] as string | undefined;
+      const rule = d['rule_id'] as string | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <Mono className="text-[var(--color-sev-error)]">{name ?? '—'}</Mono>
+            <Dim className="truncate">— {truncate(reason ?? '', 80)}</Dim>
+          </span>
+        ),
+        right: rule ? (
+          <Pill tone="error" variant="outline">
+            rule={rule}
+          </Pill>
+        ) : undefined,
+      };
+    }
+
+    case 'skill_invoked': {
+      const d = (r as { data?: Record<string, unknown> }).data ?? {};
+      const name = d['skill_name'] as string | undefined;
+      const mode = d['execution_mode'] as string | undefined;
+      const trigger = d['invocation_trigger'] as string | undefined;
+      const depth = d['query_depth'] as number | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2">
+            <Mono className="text-[var(--color-cat-tools)]">{name ?? '—'}</Mono>
+            <Pill tone="tools" variant="outline">
+              {mode ?? 'inline'}
+            </Pill>
+            {trigger ? <Dim>{trigger}</Dim> : null}
+          </span>
+        ),
+        right: depth !== undefined && depth > 0 ? <Dim>depth={depth}</Dim> : undefined,
+      };
+    }
+
+    case 'skill_completed': {
+      const d = (r as { data?: Record<string, unknown> }).data ?? {};
+      const name = d['skill_name'] as string | undefined;
+      const success = d['success'] as boolean | undefined;
+      const error = d['error'] as string | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <Mono className="text-[var(--color-cat-tools)]">{name ?? '—'}</Mono>
+            <span
+              className={
+                success ? 'text-[var(--color-sev-success)]' : 'text-[var(--color-sev-error)]'
+              }
+            >
+              {success ? 'ok' : error ? truncate(error, 60) : 'failed'}
+            </span>
+          </span>
+        ),
+      };
+    }
+
+    // ─── APPROVAL ───
+    case 'approval_request': {
+      const d = (r as { data?: Record<string, unknown> }).data ?? {};
+      const tool = d['tool_name'] as string | undefined;
+      const action = d['action'] as string | undefined;
+      const source = d['source'] as Record<string, unknown> | undefined;
+      const display = d['display'] as Record<string, unknown> | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2">
+            <Mono>{tool ?? '—'}</Mono>
+            <Dim>· {action ?? '—'}</Dim>
+            {source ? (
+              <Pill tone="approval" variant="outline">
+                {asStr(source['kind'], '?')}
+              </Pill>
+            ) : null}
+          </span>
+        ),
+        right: display ? <Dim>display={asStr(display['kind'], '?')}</Dim> : undefined,
+      };
+    }
+
+    case 'approval_response': {
+      const d = (r as { data?: Record<string, unknown> }).data ?? {};
+      const response = d['response'] as string | undefined;
+      const feedback = d['feedback'] as string | undefined;
+      const selectedLabel = d['selected_label'] as string | undefined;
+      const synthetic = d['synthetic'] as boolean | undefined;
+      const tone =
+        response === 'approved' ? 'success' : response === 'rejected' ? 'error' : 'neutral';
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <Pill tone={tone} variant="soft">
+              {response ?? '—'}
+            </Pill>
+            {selectedLabel ? <Dim>· {selectedLabel}</Dim> : null}
+            {feedback ? <Dim className="truncate">· {truncate(feedback, 40)}</Dim> : null}
+          </span>
+        ),
+        right: synthetic ? (
+          <Pill tone="warning" variant="outline">
+            synthetic
+          </Pill>
+        ) : undefined,
+      };
+    }
+
+    // ─── SUBAGENT ───
+    case 'subagent_spawned': {
+      const d = (r as { data?: Record<string, unknown> }).data ?? {};
+      const id = d['agent_id'] as string | undefined;
+      const name = d['agent_name'] as string | undefined;
+      const bg = d['run_in_background'] as boolean | undefined;
+      const parent = d['parent_agent_id'] as string | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <Pill tone="subagent" variant="soft">
+              {name ?? 'subagent'}
+            </Pill>
+            <IdBadge kind="agent_id" value={id} shortenTo={10} />
+          </span>
+        ),
+        right: (
+          <span className="flex items-center gap-2">
+            {bg ? (
+              <Pill tone="subagent" variant="outline">
+                bg
+              </Pill>
+            ) : null}
+            {parent ? (
+              <span className="flex items-center gap-1">
+                <Dim>parent=</Dim>
+                <IdBadge kind="agent_id" value={parent} shortenTo={8} />
+              </span>
+            ) : null}
+          </span>
+        ),
+      };
+    }
+
+    case 'subagent_completed': {
+      const d = (r as { data?: Record<string, unknown> }).data ?? {};
+      const id = d['agent_id'] as string | undefined;
+      const summary = d['result_summary'] as string | undefined;
+      const usage = d['usage'] as Record<string, unknown> | undefined;
+      const out = (usage?.['output'] ?? usage?.['output_tokens']) as number | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <IdBadge kind="agent_id" value={id} shortenTo={10} />
+            <span className="truncate text-fg-1">{truncate(summary ?? '', 80)}</span>
+          </span>
+        ),
+        right: out !== undefined ? <Dim>{out}tok</Dim> : undefined,
+      };
+    }
+
+    case 'subagent_failed': {
+      const d = (r as { data?: Record<string, unknown> }).data ?? {};
+      const id = d['agent_id'] as string | undefined;
+      const error = d['error'] as string | undefined;
+      return {
+        main: (
+          <span className="flex items-center gap-2 min-w-0">
+            <IdBadge kind="agent_id" value={id} shortenTo={10} />
+            <span className="truncate text-[var(--color-sev-error)]">
+              {truncate(error ?? '', 80)}
+            </span>
+          </span>
+        ),
+      };
+    }
+
+    // ─── LIFECYCLE ───
+    case 'ownership_changed': {
+      const oldO = r['old_owner'] as string | null | undefined;
+      const newO = r['new_owner'] as string | undefined;
+      return {
+        main: (
+          <Mono>
+            {oldO ?? '(none)'} → {newO ?? '—'}
+          </Mono>
+        ),
+      };
+    }
+
+    case 'context_cleared': {
+      return { main: <Dim>context history cleared</Dim> };
+    }
+
+    case 'context_edit': {
+      const op = r['operation'] as string | undefined;
+      const target = r['target_seq'] as number | undefined;
+      const toTurn = r['to_turn'] as number | undefined;
+      const cascade = r['cascade'] as boolean | undefined;
+      const ref =
+        target !== undefined
+          ? `target=${target}`
+          : toTurn !== undefined
+            ? `to_turn=${toTurn}`
+            : '—';
+      return {
+        main: (
+          <span className="flex items-center gap-2">
+            <Pill tone="lifecycle" variant="soft">
+              {op ?? '—'}
+            </Pill>
+            <Mono>{ref}</Mono>
+          </span>
+        ),
+        right: cascade ? (
+          <Pill tone="warning" variant="outline">
+            cascade
+          </Pill>
+        ) : undefined,
+      };
+    }
+
+    default: {
+      const t = (r as Record<string, unknown>)['type'];
+      return { main: <Dim>unknown type: {String(t)}</Dim> };
+    }
+  }
+}
+
+// ─── tiny presentational helpers ───
+function Mono({ children, className = '' }: { children: ReactNode; className?: string }) {
+  return <span className={`font-mono text-[12px] text-fg-0 ${className}`}>{children}</span>;
+}
+
+function Dim({ children, className = '' }: { children: ReactNode; className?: string }) {
+  return <span className={`font-mono text-[11px] text-fg-3 ${className}`}>{children}</span>;
+}
+
+/** A click-to-focus id badge. Clicking toggles a global focus that dims
+ *  non-related rows. Re-clicking the same id (or pressing ESC) clears. */
+function IdBadge({
+  kind,
+  value,
+  shortenTo = 8,
+}: {
+  kind: FocusKind;
+  value: string | undefined;
+  shortenTo?: number;
+}) {
+  const { focus, toggle } = useFocus();
+  if (!value) return <Mono>—</Mono>;
+  const isFocused = focus?.kind === kind && focus.value === value;
+  const display = value.length > shortenTo ? value.slice(0, shortenTo) : value;
+  return (
+    <button
+      type="button"
+      onClick={(e) => {
+        e.stopPropagation();
+        toggle({ kind, value });
+      }}
+      title={`${kind}=${value} · click to focus related`}
+      className={[
+        'font-mono text-[12px] underline decoration-dotted underline-offset-2',
+        isFocused
+          ? 'text-[var(--color-sev-info)] decoration-[var(--color-sev-info)]'
+          : 'text-fg-1 decoration-fg-3 hover:text-fg-0 hover:decoration-fg-1',
+      ].join(' ')}
+    >
+      {display}
+    </button>
+  );
+}
diff --git a/apps/vis/web/src/components/wire/WireRow.tsx b/apps/vis/web/src/components/wire/WireRow.tsx
new file mode 100644
index 000000000..51118658c
--- /dev/null
+++ b/apps/vis/web/src/components/wire/WireRow.tsx
@@ -0,0 +1,134 @@
+import { memo } from 'react';
+
+import { recordMatchesFocus, useFocus } from '../../lib/focus-context';
+import type { VisWireRecord } from '../../types';
+import { TYPE_CATEGORY, TYPE_CTX_EFFECT } from '../../types';
+import { formatWallClock } from '../../util/time';
+import { TypeBadge } from './TypeBadge';
+import { renderHeadline } from './WireHeadline';
+import { WireRowDetail } from './WireRowDetail';
+
+const CAT_COLOR_VAR: Record<string, string> = {
+  conversation: '--color-cat-conversation',
+  config: '--color-cat-config',
+  lifecycle: '--color-cat-lifecycle',
+  subagent: '--color-cat-subagent',
+  approval: '--color-cat-approval',
+  ephemeral: '--color-cat-ephemeral',
+  meta: '--color-cat-meta',
+  tools: '--color-cat-tools',
+};
+
+interface WireRowProps {
+  record: VisWireRecord;
+  expanded: boolean;
+  onToggle: () => void;
+  /** For tool_call / tool_result — the counterpart record (if any). */
+  paired?: VisWireRecord | undefined;
+  /** null when `paired` is undefined; true/false when the counterpart exists. */
+  pairedInFiltered?: boolean | null;
+  /** Scroll to a seq and expand it — wired by the Wire tab via the virtualizer. */
+  onJumpTo?: (seq: number) => void;
+}
+
+export const WireRow = memo(function WireRow({
+  record,
+  expanded,
+  onToggle,
+  paired,
+  pairedInFiltered,
+  onJumpTo,
+}: WireRowProps) {
+  const cat = TYPE_CATEGORY[record.type];
+  const accentVar = CAT_COLOR_VAR[cat] ?? '--color-fg-3';
+  const ctx = TYPE_CTX_EFFECT[record.type];
+  const h = renderHeadline(record);
+  const { focus } = useFocus();
+  const related = focus === null ? true : recordMatchesFocus(record, focus);
+  const timeTitle = formatTimeTitle(record.time);
+
+  return (
+    <div
+      className={[
+        'flex items-stretch border-b border-border transition-opacity',
+        expanded ? 'bg-surface-1' : 'bg-surface-0 hover:bg-surface-1',
+        focus !== null && !related ? 'opacity-30' : '',
+        focus !== null && related ? 'ring-1 ring-inset ring-[var(--color-sev-info)]/40' : '',
+      ].join(' ')}
+    >
+      <div className="accent-bar" style={{ backgroundColor: `var(${accentVar})` }} />
+      <div className="min-w-0 flex-1">
+        <button
+          onClick={onToggle}
+          className="flex w-full items-center gap-3 px-2 py-[5px] text-left min-h-[28px]"
+        >
+          <span className="font-mono text-[11px] text-fg-3 tabular w-[52px] shrink-0 text-right">
+            {record.seq}
+          </span>
+          <span
+            className="font-mono text-[11px] text-fg-3 tabular w-[68px] shrink-0"
+            title={timeTitle}
+          >
+            {formatWallClock(record.time)}
+          </span>
+          <span className="shrink-0">
+            <TypeBadge type={record.type} />
+          </span>
+          <span className="flex-1 min-w-0 flex items-center gap-2">{h.main}</span>
+          <span className="flex items-center gap-2 shrink-0">
+            {h.right}
+            <CtxMarker effect={ctx} />
+            <Chevron open={expanded} />
+          </span>
+        </button>
+        {expanded ? (
+          <div className="border-t border-border bg-surface-1 px-2 pb-2 pt-1">
+            <WireRowDetail
+              record={record}
+              paired={paired}
+              pairedInFiltered={pairedInFiltered ?? null}
+              onJumpTo={onJumpTo}
+            />
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+});
+
+function formatTimeTitle(epochMs: number): string {
+  if (!epochMs || !Number.isFinite(epochMs)) return 'missing time';
+  const date = new Date(epochMs);
+  if (!Number.isFinite(date.getTime())) return 'invalid time';
+  return date.toISOString();
+}
+
+function Chevron({ open }: { open: boolean }) {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 10 10"
+      className={`text-fg-3 transition-transform ${open ? 'rotate-90' : ''}`}
+      aria-hidden="true"
+    >
+      <path d="M3 2 L7 5 L3 8" stroke="currentColor" strokeWidth="1" fill="none" />
+    </svg>
+  );
+}
+
+function CtxMarker({ effect }: { effect: boolean | 'conditional' }) {
+  const title =
+    effect === true
+      ? 'affects LLM context'
+      : effect === 'conditional'
+        ? 'conditionally affects LLM context'
+        : 'telemetry only — no context effect';
+  const symbol = effect === true ? '●' : effect === 'conditional' ? '◑' : '○';
+  const color = effect ? 'text-[var(--color-cat-conversation)]' : 'text-fg-3';
+  return (
+    <span className={`font-mono text-[11px] ${color}`} title={title}>
+      {symbol}
+    </span>
+  );
+}
diff --git a/apps/vis/web/src/components/wire/WireRowDetail.tsx b/apps/vis/web/src/components/wire/WireRowDetail.tsx
new file mode 100644
index 000000000..118c75138
--- /dev/null
+++ b/apps/vis/web/src/components/wire/WireRowDetail.tsx
@@ -0,0 +1,253 @@
+import { useState, type ReactNode } from 'react';
+
+import type { VisWireRecord } from '../../types';
+import { CopyButton } from '../shared/CopyButton';
+import { JsonViewer } from '../shared/JsonViewer';
+import { SizePreview } from '../shared/SizePreview';
+
+interface WireRowDetailProps {
+  record: VisWireRecord;
+  /** Counterpart in a tool_call ↔ tool_result pair (if applicable). */
+  paired?: VisWireRecord | undefined;
+  /** Whether the counterpart is visible in the current filter. null when
+   *  there is no counterpart at all. */
+  pairedInFiltered?: boolean | null;
+  /** Scroll to + expand a given seq. */
+  onJumpTo?: (seq: number) => void;
+}
+
+/** Fields that are best rendered as collapsible large-payload blocks rather than
+ *  as key-value pairs. Keyed by the path (dot-separated) from record root. */
+const LARGE_FIELDS: Record<string, true> = {
+  new_prompt: true,
+  system_prompt: true,
+  summary: true,
+  think: true,
+  text: true,
+  content: true,
+  output: true,
+  user_input: true,
+  'data.body': true,
+  'data.args': true,
+  'data.payload': true,
+  'data.tail_output': true,
+  'data.result_summary': true,
+  'data.error': true,
+  'data.reason': true,
+  'data.content': true,
+  'data.summary': true,
+  result_summary: true,
+  new_content: true,
+};
+
+const TOP_LEVEL_META = new Set(['type', 'seq', 'time']);
+
+export function WireRowDetail({ record, paired, pairedInFiltered, onJumpTo }: WireRowDetailProps) {
+  const [showRaw, setShowRaw] = useState(false);
+  const entries = Object.entries(record as Record<string, unknown>).filter(
+    ([k]) => !TOP_LEVEL_META.has(k),
+  );
+
+  return (
+    <div className="pl-[120px] pr-2 py-1 font-mono text-[12px]">
+      <div className="grid grid-cols-[140px_1fr] gap-x-3 gap-y-[2px]">
+        {entries.map(([key, value]) => renderField(key, value, key))}
+      </div>
+      {paired !== undefined ? (
+        <PairedSection
+          self={record}
+          paired={paired}
+          pairedInFiltered={pairedInFiltered ?? null}
+          onJumpTo={onJumpTo}
+        />
+      ) : null}
+      <div className="mt-2 flex items-center justify-end gap-3">
+        <CopyButton value={JSON.stringify(record, null, 2)} label="copy record json" />
+        <button
+          onClick={() =>{  setShowRaw((v) => !v); }}
+          className="font-mono text-[10px] text-fg-3 hover:text-fg-1"
+        >
+          {showRaw ? '[ hide raw json ]' : '[ {…} raw json ]'}
+        </button>
+      </div>
+      {showRaw ? (
+        <div className="mt-2 border border-border bg-surface-0 p-2">
+          <JsonViewer value={record} defaultOpenDepth={2} />
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/** Renders the "↳ paired with tool_result (seq N)" section below a
+ *  tool_call row (or the reverse). Shows a compact preview of the
+ *  counterpart and a jump button that scrolls-to + expands that row. */
+function PairedSection({
+  self,
+  paired,
+  pairedInFiltered,
+  onJumpTo,
+}: {
+  self: VisWireRecord;
+  paired: VisWireRecord;
+  pairedInFiltered: boolean | null;
+  onJumpTo?: (seq: number) => void;
+}) {
+  const selfIsCall = self.type === 'tool_call';
+  const preview = selfIsCall ? previewToolResult(paired) : previewToolCallArgs(paired);
+  const isError =
+    paired.type === 'tool_result' && (paired as { is_error?: boolean }).is_error === true;
+  const hidden = pairedInFiltered === false;
+  return (
+    <div className="mt-3 border-t border-border pt-2">
+      <div className="flex items-center gap-2 font-mono text-[11px]">
+        <span className="text-fg-3">↳ paired</span>
+        <span className="text-fg-1">{paired.type}</span>
+        <span className="text-fg-3">seq</span>
+        <span className="tabular text-fg-0">{paired.seq}</span>
+        {isError ? (
+          <span className="border border-[var(--color-sev-error)] px-1 text-[10px] text-[var(--color-sev-error)]">
+            error
+          </span>
+        ) : null}
+        {hidden ? <span className="text-fg-3">(hidden by filter)</span> : null}
+        <button
+          type="button"
+          onClick={() => onJumpTo?.(paired.seq)}
+          disabled={hidden || onJumpTo === undefined}
+          className="ml-auto border border-border px-2 py-0.5 text-fg-2 hover:border-border-strong hover:text-fg-0 disabled:opacity-40 disabled:hover:border-border disabled:hover:text-fg-2"
+          title={
+            hidden ? 'counterpart is currently filtered out' : 'scroll to + expand counterpart'
+          }
+        >
+          jump →
+        </button>
+      </div>
+      {preview.length > 0 ? (
+        <pre className="mt-1 max-h-[5.5em] overflow-hidden whitespace-pre-wrap break-words font-mono text-[11.5px] text-fg-1">
+          {preview.length > 400 ? preview.slice(0, 400) + '…' : preview}
+        </pre>
+      ) : (
+        <div className="mt-1 font-mono text-[11px] text-fg-3">(empty)</div>
+      )}
+    </div>
+  );
+}
+
+function previewToolCallArgs(call: VisWireRecord): string {
+  const args = (call as { data?: { args?: unknown } }).data?.args;
+  if (args === undefined) return '';
+  if (typeof args === 'string') return args;
+  try {
+    return JSON.stringify(args, null, 2);
+  } catch {
+    // Circular refs / BigInt / etc. — don't fall through to String(unknown)
+    // which produces "[object Object]" and hides the actual problem.
+    return '(unserialisable args)';
+  }
+}
+
+function previewToolResult(result: VisWireRecord): string {
+  const out = (result as { output?: unknown }).output;
+  if (out === undefined || out === null) return '';
+  if (typeof out === 'string') return out;
+  try {
+    return JSON.stringify(out, null, 2);
+  } catch {
+    return '(unserialisable output)';
+  }
+}
+
+function renderField(key: string, value: unknown, path: string) {
+  // Null / undefined
+  if (value === null || value === undefined) {
+    return (
+      <FieldRow key={path} label={key}>
+        <span className="text-fg-3">null</span>
+      </FieldRow>
+    );
+  }
+
+  // Large-payload fields: render via SizePreview with JsonViewer inside
+  if (LARGE_FIELDS[path] || LARGE_FIELDS[key]) {
+    if (typeof value === 'string') {
+      return (
+        <FieldRow key={path} label={key} wide>
+          <SizePreview label={key} sizeBytes={value.length} preview={value}>
+            <pre className="whitespace-pre-wrap break-words text-fg-1">{value}</pre>
+          </SizePreview>
+        </FieldRow>
+      );
+    }
+    // non-string large fields: JSON tree
+    return (
+      <FieldRow key={path} label={key} wide>
+        <SizePreview label={key} sizeBytes={JSON.stringify(value).length}>
+          <JsonViewer value={value} defaultOpenDepth={1} />
+        </SizePreview>
+      </FieldRow>
+    );
+  }
+
+  // Primitive
+  if (typeof value !== 'object') {
+    const repr =
+      typeof value === 'string'
+        ? `"${truncate(value, 160)}"`
+        : typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint'
+          ? String(value)
+          : typeof value;
+    return (
+      <FieldRow key={path} label={key}>
+        <span className={typeColor(value)}>{repr}</span>
+      </FieldRow>
+    );
+  }
+
+  // Nested object: inline JsonViewer
+  return (
+    <FieldRow key={path} label={key} wide>
+      <JsonViewer value={value} defaultOpenDepth={1} />
+    </FieldRow>
+  );
+}
+
+function FieldRow({
+  label,
+  children,
+  wide = false,
+}: {
+  label: string;
+  children: ReactNode;
+  wide?: boolean;
+}) {
+  if (wide) {
+    return (
+      <>
+        <div className="col-span-2 flex items-baseline gap-3">
+          <span className="w-[140px] shrink-0 font-mono text-[11px] text-fg-2 text-right">
+            {label}
+          </span>
+          <div className="flex-1 min-w-0">{children}</div>
+        </div>
+      </>
+    );
+  }
+  return (
+    <>
+      <span className="font-mono text-[11px] text-fg-2 text-right">{label}</span>
+      <div className="font-mono text-[12px] text-fg-0 min-w-0 break-words">{children}</div>
+    </>
+  );
+}
+
+function typeColor(v: unknown): string {
+  if (typeof v === 'boolean') return 'text-[var(--color-cat-config)]';
+  if (typeof v === 'number') return 'text-[var(--color-sev-info)]';
+  if (typeof v === 'string') return 'text-[var(--color-cat-ephemeral)]';
+  return 'text-fg-0';
+}
+
+function truncate(s: string, n: number): string {
+  return s.length <= n ? s : s.slice(0, n) + '…';
+}
diff --git a/apps/vis/web/src/components/wire/WireTab.tsx b/apps/vis/web/src/components/wire/WireTab.tsx
new file mode 100644
index 000000000..45b515d20
--- /dev/null
+++ b/apps/vis/web/src/components/wire/WireTab.tsx
@@ -0,0 +1,524 @@
+import { useVirtualizer } from '@tanstack/react-virtual';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { FocusProvider, useFocus } from '../../lib/focus-context';
+import { computeIssues, topSeverity } from '../../lib/issues';
+import {
+  buildMatchContext,
+  matchesQuery,
+  parseQuery,
+  type ParsedQuery,
+  type QueryToken,
+} from '../../lib/query-parser';
+import type { VisWireRecord, WireCategory } from '../../types';
+import { TYPE_CATEGORY } from '../../types';
+import { IssuesDrawer } from './IssuesDrawer';
+import { WireRow } from './WireRow';
+
+interface WireTabProps {
+  records: VisWireRecord[];
+  health?: 'ok' | 'broken';
+  brokenReason?: string;
+  warnings?: string[];
+}
+
+const CATEGORIES: WireCategory[] = [
+  'conversation',
+  'tools',
+  'approval',
+  'subagent',
+  'ephemeral',
+  'meta',
+  'config',
+  'lifecycle',
+];
+
+const CAT_COLOR_VAR: Record<WireCategory, string> = {
+  conversation: '--color-cat-conversation',
+  config: '--color-cat-config',
+  lifecycle: '--color-cat-lifecycle',
+  subagent: '--color-cat-subagent',
+  approval: '--color-cat-approval',
+  ephemeral: '--color-cat-ephemeral',
+  meta: '--color-cat-meta',
+  tools: '--color-cat-tools',
+};
+
+export function WireTab(props: WireTabProps) {
+  // The FocusProvider wraps the entire tab so IdBadge clicks deep inside
+  // the virtualized rows can update (and be read by) the toolbar status
+  // indicator without prop-drilling.
+  return (
+    <FocusProvider>
+      <WireTabInner {...props} />
+    </FocusProvider>
+  );
+}
+
+function WireTabInner({ records, health, brokenReason, warnings = [] }: WireTabProps) {
+  const [search, setSearch] = useState('');
+  const [excluded, setExcluded] = useState(new Set());
+  const [expanded, setExpanded] = useState(new Set());
+  const [showHelp, setShowHelp] = useState(false);
+  const [drawerOpen, setDrawerOpen] = useState(false);
+  const parentRef = useRef<HTMLDivElement>(null);
+
+  const query = useMemo<ParsedQuery>(() => parseQuery(search), [search]);
+
+  const matchCtx = useMemo(() => buildMatchContext(records, query), [records, query]);
+
+  const filtered = useMemo(() => {
+    return records.filter((r) => {
+      const cat = TYPE_CATEGORY[r.type];
+      if (excluded.has(cat)) return false;
+      return matchesQuery(r, query, matchCtx);
+    });
+  }, [records, excluded, query, matchCtx]);
+
+  // Pair map: tool_call_id → the two sides. Built from the full records[]
+  // (not `filtered`) so jumping from a filtered view still works when the
+  // counterpart has been filtered out — the detail panel will just mark it
+  // "(hidden by current filter)".
+  const pairMap = useMemo(() => {
+    const m = new Map<string, { call?: VisWireRecord; result?: VisWireRecord }>();
+    for (const r of records) {
+      if (r.type === 'tool_call') {
+        const id = (r as { data?: { tool_call_id?: string } }).data?.tool_call_id;
+        if (id !== undefined) {
+          const slot = m.get(id) ?? {};
+          slot.call = r;
+          m.set(id, slot);
+        }
+      } else if (r.type === 'tool_result') {
+        const id = (r as { tool_call_id?: string }).tool_call_id;
+        if (id !== undefined) {
+          const slot = m.get(id) ?? {};
+          slot.result = r;
+          m.set(id, slot);
+        }
+      }
+    }
+    return m;
+  }, [records]);
+
+  /** Find the counterpart for a tool_call / tool_result row (undefined otherwise). */
+  const pairedFor = useCallback(
+    (r: VisWireRecord): VisWireRecord | undefined => {
+      if (r.type === 'tool_call') {
+        const id = (r as { data?: { tool_call_id?: string } }).data?.tool_call_id;
+        return id === undefined ? undefined : pairMap.get(id)?.result;
+      }
+      if (r.type === 'tool_result') {
+        const id = (r as { tool_call_id?: string }).tool_call_id;
+        return id === undefined ? undefined : pairMap.get(id)?.call;
+      }
+      return undefined;
+    },
+    [pairMap],
+  );
+
+  // Compute per-category counts over the unfiltered set
+  const catCounts = useMemo(() => {
+    const m = new Map<WireCategory, number>();
+    for (const r of records) {
+      const c = TYPE_CATEGORY[r.type];
+      m.set(c, (m.get(c) ?? 0) + 1);
+    }
+    return m;
+  }, [records]);
+
+  const turnCount = useMemo(() => records.filter((r) => r.type === 'turn_begin').length, [records]);
+
+  // Issues are computed over the full records[] + file warnings (not the
+  // filter result) so the pill keeps showing real problems even when the
+  // user has narrowed their query. Jumping to an issue scrolls the Wire
+  // list — if the issue's seq is currently filtered out, `jumpToSeq` is
+  // a no-op and the drawer just closes.
+  const issues = useMemo(() => computeIssues(records, warnings), [records, warnings]);
+  const issuesSeverity = topSeverity(issues);
+
+  // Stable estimate — ResizeObserver (wired via `virt.measureElement` ref
+  // on each item) refines to the actual rendered height. Do NOT vary the
+  // estimate based on `expanded`: that fights the library's measurement
+  // cache and produces layout gaps when the two race.
+  const virt = useVirtualizer({
+    count: filtered.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 28,
+    overscan: 10,
+    getItemKey: (i) => filtered[i]?.seq ?? i,
+  });
+
+  const toggle = useCallback((seq: number) => {
+    // Trust the library's ResizeObserver to catch the new content size —
+    // calling `virt.measure()` manually here races with the observer and
+    // can clear freshly-written cache entries, stranding items at their
+    // `estimateSize` value and producing visible gaps.
+    setExpanded((prev) => {
+      const next = new Set(prev);
+      if (next.has(seq)) next.delete(seq);
+      else next.add(seq);
+      return next;
+    });
+  }, []);
+
+  /** Seq → index lookup built from the filtered list. Doubles as the
+   *  "is this seq currently visible?" test used by pairing + issues jumps. */
+  const filteredSeqIdx = useMemo(() => {
+    const m = new Map<number, number>();
+    for (let i = 0; i < filtered.length; i += 1) {
+      const r = filtered[i];
+      if (r !== undefined) m.set(r.seq, i);
+    }
+    return m;
+  }, [filtered]);
+
+  /** Jump to a specific seq: scroll the row into view and expand it.
+   *  No-op if the seq isn't in the current filtered set — callers can
+   *  check `filteredSeqIdx.has(seq)` ahead of time and disable the link. */
+  const jumpToSeq = useCallback(
+    (seq: number) => {
+      const idx = filteredSeqIdx.get(seq);
+      if (idx === undefined) return;
+      virt.scrollToIndex(idx, { align: 'center' });
+      setExpanded((prev) => (prev.has(seq) ? prev : new Set(prev).add(seq)));
+    },
+    [filteredSeqIdx, virt],
+  );
+
+  const toggleCat = (c: WireCategory) => {
+    setExcluded((prev) => {
+      const next = new Set(prev);
+      if (next.has(c)) next.delete(c);
+      else next.add(c);
+      return next;
+    });
+  };
+
+  const expandAll = () =>{  setExpanded(new Set(filtered.map((r) => r.seq))); };
+  const collapseAll = () =>{  setExpanded(new Set()); };
+
+  const hasStructuredTokens = query.tokens.some((t) => t.key !== null) || query.errors.length > 0;
+
+  return (
+    <div className="relative flex min-h-0 flex-1 flex-col">
+      {/* Toolbar */}
+      <div className="flex shrink-0 items-center gap-3 border-b border-border bg-surface-1 px-3 py-2">
+        <div className="relative flex items-center">
+          <input
+            type="text"
+            placeholder="type:tool_call tool:Bash error:true …"
+            value={search}
+            onChange={(e) =>{  setSearch(e.target.value); }}
+            className="w-80 border border-border bg-surface-0 px-2 py-1 pr-7 font-mono text-[12px] text-fg-0 placeholder:text-fg-3 focus:border-border-strong focus:outline-none"
+          />
+          <button
+            type="button"
+            onClick={() =>{  setShowHelp((v) => !v); }}
+            title="query syntax cheatsheet"
+            className="absolute right-1 top-1/2 -translate-y-1/2 font-mono text-[11px] text-fg-3 hover:text-fg-0"
+          >
+            ?
+          </button>
+          {showHelp ? <QueryHelp onClose={() =>{  setShowHelp(false); }} /> : null}
+        </div>
+        <div className="flex items-center gap-1">
+          {CATEGORIES.map((c) => {
+            const count = catCounts.get(c) ?? 0;
+            if (count === 0) return null;
+            const on = !excluded.has(c);
+            const color = `var(${CAT_COLOR_VAR[c]})`;
+            return (
+              <button
+                key={c}
+                onClick={() =>{  toggleCat(c); }}
+                title={`Toggle ${c} (${count})`}
+                className="pill"
+                style={
+                  on
+                    ? {
+                        backgroundColor: `color-mix(in oklab, ${color} 18%, transparent)`,
+                        color,
+                      }
+                    : {
+                        border: '1px solid var(--color-border)',
+                        color: 'var(--color-fg-3)',
+                      }
+                }
+              >
+                <span>{c}</span>
+                <span className="tabular">{count}</span>
+              </button>
+            );
+          })}
+        </div>
+        <div className="ml-auto flex items-center gap-3 font-mono text-[11px] text-fg-2">
+          <span className="tabular">
+            {filtered.length} / {records.length} ev
+          </span>
+          <span className="tabular text-fg-3">{turnCount} turns</span>
+          {issues.length > 0 && issuesSeverity !== null ? (
+            <button
+              onClick={() =>{  setDrawerOpen(true); }}
+              title={`${issues.length} issue${issues.length > 1 ? 's' : ''} — click to inspect`}
+              className="flex items-center gap-1 border px-2 py-0.5"
+              style={{
+                borderColor: `var(--color-sev-${issuesSeverity})`,
+                color: `var(--color-sev-${issuesSeverity})`,
+                backgroundColor: `color-mix(in oklab, var(--color-sev-${issuesSeverity}) 10%, transparent)`,
+              }}
+            >
+              <span>
+                {issuesSeverity === 'error' ? '⚠' : issuesSeverity === 'warning' ? '⚠' : 'ℹ'}
+              </span>
+              <span className="tabular">{issues.length}</span>
+            </button>
+          ) : null}
+          <button
+            onClick={expandAll}
+            className="border border-border px-2 py-0.5 text-fg-2 hover:border-border-strong hover:text-fg-0"
+          >
+            expand all
+          </button>
+          <button
+            onClick={collapseAll}
+            className="border border-border px-2 py-0.5 text-fg-2 hover:border-border-strong hover:text-fg-0"
+          >
+            collapse
+          </button>
+        </div>
+      </div>
+
+      {/* Query chips — one-line summary of parsed filters, each removable */}
+      {hasStructuredTokens ? (
+        <div className="flex shrink-0 flex-wrap items-center gap-1 border-b border-border bg-surface-1 px-3 py-1">
+          {query.tokens
+            .filter((t) => t.key !== null)
+            .map((t, i) => {
+              const invalid = query.errors.some((e) => e.token === t.raw);
+              return (
+                <QueryChip
+                  key={`${t.raw}-${i}`}
+                  token={t}
+                  invalid={invalid}
+                  onRemove={() =>{  setSearch((s) => removeToken(s, t.raw)); }}
+                />
+              );
+            })}
+          {query.errors.length > 0 ? (
+            <span
+              className="font-mono text-[10px] text-[var(--color-sev-warning)]"
+              title={query.errors.map((e) => `${e.token}: ${e.reason}`).join('\n')}
+            >
+              · {query.errors.length} unknown
+            </span>
+          ) : null}
+        </div>
+      ) : null}
+
+      <FocusStatus />
+
+      {/* Health warning */}
+      {health === 'broken' ? (
+        <div className="shrink-0 border-b border-[var(--color-sev-error)] bg-[color-mix(in_oklab,var(--color-sev-error)_12%,transparent)] px-3 py-1 font-mono text-[11px] text-[var(--color-sev-error)]">
+          broken: {brokenReason ?? 'unknown reason'}
+        </div>
+      ) : null}
+      {warnings.length > 0 ? (
+        <div className="shrink-0 border-b border-[var(--color-sev-warning)] bg-[color-mix(in_oklab,var(--color-sev-warning)_8%,transparent)] px-3 py-1 font-mono text-[11px] text-[var(--color-sev-warning)]">
+          {warnings.length} warning{warnings.length > 1 ? 's' : ''} · first: {warnings[0]}
+        </div>
+      ) : null}
+
+      {/* Virtualized list */}
+      <div ref={parentRef} className="min-h-0 flex-1 overflow-y-auto">
+        {filtered.length === 0 ? (
+          <div className="p-6 font-mono text-[12px] text-fg-3">
+            no records match the current filter
+          </div>
+        ) : (
+          <div
+            style={{
+              height: virt.getTotalSize(),
+              position: 'relative',
+            }}
+          >
+            {virt.getVirtualItems().map((vi) => {
+              const r = filtered[vi.index];
+              if (!r) return null;
+              // Compute the counterpart once per row — paired lookup runs
+              // inside a virtualized render loop, so duplicating the call
+              // meant ~40 redundant ops per scroll tick on deep sessions.
+              const paired = pairedFor(r);
+              const pairedInFiltered = paired === undefined ? null : filteredSeqIdx.has(paired.seq);
+              return (
+                <div
+                  key={vi.key}
+                  data-index={vi.index}
+                  ref={virt.measureElement}
+                  style={{
+                    position: 'absolute',
+                    top: 0,
+                    left: 0,
+                    width: '100%',
+                    transform: `translateY(${vi.start}px)`,
+                  }}
+                >
+                  <WireRow
+                    record={r}
+                    expanded={expanded.has(r.seq)}
+                    onToggle={() =>{  toggle(r.seq); }}
+                    paired={paired}
+                    pairedInFiltered={pairedInFiltered}
+                    onJumpTo={jumpToSeq}
+                  />
+                </div>
+              );
+            })}
+          </div>
+        )}
+      </div>
+      {drawerOpen ? (
+        <IssuesDrawer
+          issues={issues}
+          onClose={() =>{  setDrawerOpen(false); }}
+          onJumpTo={jumpToSeq}
+          isSeqVisible={(seq) => filteredSeqIdx.has(seq)}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+// ──────── helper subcomponents ────────
+
+function QueryChip({
+  token,
+  invalid,
+  onRemove,
+}: {
+  token: QueryToken;
+  invalid: boolean;
+  onRemove: () => void;
+}) {
+  const label = `${token.key}${token.op === '=' ? ':' : token.op}${token.values.join(',')}`;
+  return (
+    <span
+      className={[
+        'inline-flex items-center gap-1 border px-1.5 py-0.5 font-mono text-[10px]',
+        invalid
+          ? 'border-[var(--color-sev-error)] text-[var(--color-sev-error)]'
+          : 'border-border bg-surface-0 text-fg-1',
+      ].join(' ')}
+    >
+      <span>{label}</span>
+      <button
+        type="button"
+        onClick={onRemove}
+        className="text-fg-3 hover:text-fg-0"
+        title="remove filter"
+      >
+        ×
+      </button>
+    </span>
+  );
+}
+
+function QueryHelp({ onClose }: { onClose: () => void }) {
+  // Dismiss on: ESC, or outside click. `onMouseLeave` was too twitchy —
+  // the panel would flash shut on mouse tremor near its edge.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    const onDocClick = (e: MouseEvent) => {
+      const t = e.target as HTMLElement | null;
+      if (t?.closest('[data-query-help-root]')) return;
+      onClose();
+    };
+    window.addEventListener('keydown', onKey);
+    // defer doc listener one tick so the opening click doesn't immediately close us
+    const id = window.setTimeout(() => {
+      document.addEventListener('mousedown', onDocClick);
+    }, 0);
+    return () => {
+      window.removeEventListener('keydown', onKey);
+      window.clearTimeout(id);
+      document.removeEventListener('mousedown', onDocClick);
+    };
+  }, [onClose]);
+  return (
+    <div
+      data-query-help-root="true"
+      className="absolute left-0 top-full z-20 mt-1 w-[420px] border border-border bg-surface-0 p-3 font-mono text-[11px] text-fg-1 shadow-lg"
+    >
+      <div className="mb-1 text-fg-0">query syntax</div>
+      <ul className="space-y-0.5 text-fg-2">
+        <li>
+          <span className="text-fg-0">type:</span>tool_call · type:user_message,tool_result ·
+          type:!compaction
+        </li>
+        <li>
+          <span className="text-fg-0">tool:</span>Bash · tool:Read,Write
+        </li>
+        <li>
+          <span className="text-fg-0">turn:</span>3 · turn:turn_5
+        </li>
+        <li>
+          <span className="text-fg-0">seq:</span>
+          {'>'}100 · seq:&lt;50 · seq:&gt;=200
+        </li>
+        <li>
+          <span className="text-fg-0">error:</span>true · error:false
+        </li>
+        <li>
+          <span className="text-fg-0">agent:</span>sub_abc123 (substring)
+        </li>
+        <li>
+          <span className="text-fg-0">id:</span>abc123 (matches any id field)
+        </li>
+        <li>
+          <span className="text-fg-3">bare words → JSON substring (AND)</span>
+        </li>
+      </ul>
+      <div className="mt-2 text-fg-3">
+        tip: click an underlined id in any row to focus all related records · ESC to clear
+      </div>
+    </div>
+  );
+}
+
+function FocusStatus() {
+  const { focus, clear } = useFocus();
+  if (focus === null) return null;
+  return (
+    <div className="flex shrink-0 items-center gap-2 border-b border-[var(--color-sev-info)]/40 bg-[color-mix(in_oklab,var(--color-sev-info)_8%,transparent)] px-3 py-1 font-mono text-[11px] text-fg-1">
+      <span className="text-[var(--color-sev-info)]">◎ focus</span>
+      <span className="text-fg-2">{focus.kind}</span>
+      <span className="text-fg-3">=</span>
+      <span className="text-fg-0">
+        {focus.value.length > 24 ? focus.value.slice(0, 24) + '…' : focus.value}
+      </span>
+      <button
+        type="button"
+        onClick={clear}
+        className="ml-auto text-fg-3 hover:text-fg-0"
+        title="clear focus (ESC)"
+      >
+        clear
+      </button>
+    </div>
+  );
+}
+
+/** Remove a single structured token from the raw search string. Used when
+ *  the user clicks the × on a chip. Matches the token's `raw` text exactly,
+ *  trimming adjacent whitespace. */
+function removeToken(input: string, raw: string): string {
+  const re = new RegExp(`(^|\\s)${escapeRegExp(raw)}(?=\\s|$)`);
+  return input.replace(re, '').replaceAll(/\s+/g, ' ').trim();
+}
+
+function escapeRegExp(s: string): string {
+  return s.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
diff --git a/apps/vis/web/src/components/wire/typeMeta.ts b/apps/vis/web/src/components/wire/typeMeta.ts
new file mode 100644
index 000000000..d965a2b73
--- /dev/null
+++ b/apps/vis/web/src/components/wire/typeMeta.ts
@@ -0,0 +1,67 @@
+import type { WireCategory, WireRecordType } from '../../types';
+
+/** Unicode icon for each wire type. Chosen for distinguishability in a dense list. */
+export const TYPE_ICON: Record<WireRecordType, string> = {
+  metadata: '§',
+  session_initialized: '✧',
+  turn_begin: '▶',
+  turn_end: '◼',
+  user_message: '▷',
+  tool_result: '✓',
+  compaction: '⏪',
+  system_prompt_changed: '¶',
+  tools_changed: '⚙',
+  system_reminder: '!',
+  notification: '◉',
+  // Streaming atoms: step boundary, streamed part, tool call
+  step_begin: '┌',
+  step_end: '┘',
+  content_part: '◆',
+  tool_call: '→',
+  tool_denied: '⊘',
+  skill_invoked: '★',
+  skill_completed: '★',
+  approval_request: '?',
+  approval_response: '·',
+  team_mail: '✉',
+  subagent_spawned: '┬',
+  subagent_completed: '└',
+  subagent_failed: '×',
+  ownership_changed: '↔',
+  context_edit: '✂',
+  context_cleared: '∅',
+};
+
+/** Tone key used by <Pill/>. Most types fall back to their category color. */
+export const TYPE_TONE: Record<
+  WireRecordType,
+  WireCategory | 'user' | 'assistant' | 'tool' | 'compaction' | 'turn'
+> = {
+  metadata: 'meta',
+  session_initialized: 'config',
+  turn_begin: 'turn',
+  turn_end: 'turn',
+  user_message: 'user',
+  tool_result: 'tool',
+  compaction: 'compaction',
+  system_prompt_changed: 'config',
+  tools_changed: 'config',
+  system_reminder: 'ephemeral',
+  notification: 'meta',
+  step_begin: 'turn',
+  step_end: 'turn',
+  content_part: 'assistant',
+  tool_call: 'tools',
+  tool_denied: 'approval',
+  skill_invoked: 'tools',
+  skill_completed: 'tools',
+  approval_request: 'approval',
+  approval_response: 'approval',
+  team_mail: 'meta',
+  subagent_spawned: 'subagent',
+  subagent_completed: 'subagent',
+  subagent_failed: 'subagent',
+  ownership_changed: 'lifecycle',
+  context_edit: 'lifecycle',
+  context_cleared: 'lifecycle',
+};
diff --git a/apps/vis/web/src/hooks/useContext.ts b/apps/vis/web/src/hooks/useContext.ts
new file mode 100644
index 000000000..3b98ee925
--- /dev/null
+++ b/apps/vis/web/src/hooks/useContext.ts
@@ -0,0 +1,34 @@
+import { useQuery } from '@tanstack/react-query';
+import { api } from '../api';
+
+export function useSessionContext(sessionId: string | undefined, enabled = true) {
+  return useQuery({
+    queryKey: ['session', sessionId, 'context'] as const,
+    queryFn: () => api.getContext(sessionId!),
+    enabled: !!sessionId && enabled,
+  });
+}
+
+export function useSubagentContext(
+  sessionId: string | undefined,
+  agentId: string | undefined,
+  enabled = true,
+) {
+  return useQuery({
+    queryKey: ['session', sessionId, 'subagent', agentId, 'context'] as const,
+    queryFn: () => api.getSubagentContext(sessionId!, agentId!),
+    enabled: !!sessionId && !!agentId && enabled,
+  });
+}
+
+export function useToolResult(
+  sessionId: string | undefined,
+  toolCallId: string | undefined,
+  enabled = true,
+) {
+  return useQuery({
+    queryKey: ['session', sessionId, 'tool-result', toolCallId] as const,
+    queryFn: () => api.getToolResult(sessionId!, toolCallId!),
+    enabled: !!sessionId && !!toolCallId && enabled,
+  });
+}
diff --git a/apps/vis/web/src/hooks/useSession.ts b/apps/vis/web/src/hooks/useSession.ts
new file mode 100644
index 000000000..339541e94
--- /dev/null
+++ b/apps/vis/web/src/hooks/useSession.ts
@@ -0,0 +1,46 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { api } from '../api';
+import type { SessionSummary } from '../types';
+
+export function useSessions() {
+  return useQuery({
+    queryKey: ['sessions'] as const,
+    queryFn: () => api.listSessions(),
+  });
+}
+
+export function useSession(sessionId: string | undefined) {
+  return useQuery({
+    queryKey: ['session', sessionId] as const,
+    queryFn: () => api.getSession(sessionId!),
+    enabled: !!sessionId,
+  });
+}
+
+export function useDeleteSession() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (sessionId: string) => api.deleteSession(sessionId),
+    onSuccess: (_result, sessionId) => {
+      qc.setQueryData<SessionSummary[]>(['sessions'], (old) =>
+        old?.filter((s) => s.session_id !== sessionId),
+      );
+      qc.removeQueries({ queryKey: ['session', sessionId] });
+      void qc.invalidateQueries({ queryKey: ['sessions'] });
+    },
+  });
+}
+
+export function useClearSessions() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: () => api.clearSessions(),
+    onSuccess: (result) => {
+      if (result.failed.length === 0) {
+        qc.setQueryData<SessionSummary[]>(['sessions'], []);
+        qc.removeQueries({ queryKey: ['session'] });
+      }
+      void qc.invalidateQueries({ queryKey: ['sessions'] });
+    },
+  });
+}
diff --git a/apps/vis/web/src/hooks/useSubagents.ts b/apps/vis/web/src/hooks/useSubagents.ts
new file mode 100644
index 000000000..075a19a65
--- /dev/null
+++ b/apps/vis/web/src/hooks/useSubagents.ts
@@ -0,0 +1,21 @@
+import { useQuery } from '@tanstack/react-query';
+import { api } from '../api';
+
+export function useSubagents(sessionId: string | undefined, enabled = true) {
+  return useQuery({
+    queryKey: ['session', sessionId, 'subagents'] as const,
+    queryFn: () => api.getSubagents(sessionId!),
+    enabled: !!sessionId && enabled,
+  });
+}
+
+export function useSubagentMeta(
+  sessionId: string | undefined,
+  agentId: string | undefined,
+) {
+  return useQuery({
+    queryKey: ['session', sessionId, 'subagent', agentId, 'meta'] as const,
+    queryFn: () => api.getSubagentMeta(sessionId!, agentId!),
+    enabled: !!sessionId && !!agentId,
+  });
+}
diff --git a/apps/vis/web/src/hooks/useTheme.ts b/apps/vis/web/src/hooks/useTheme.ts
new file mode 100644
index 000000000..5255245d4
--- /dev/null
+++ b/apps/vis/web/src/hooks/useTheme.ts
@@ -0,0 +1,82 @@
+import { useCallback, useEffect, useState } from 'react';
+
+export type ThemeChoice = 'light' | 'dark' | 'auto';
+export type ResolvedTheme = 'light' | 'dark';
+
+const STORAGE_KEY = 'vis.theme';
+
+function systemTheme(): ResolvedTheme {
+  if (typeof window === 'undefined') return 'dark';
+  return window.matchMedia('(prefers-color-scheme: light)').matches
+    ? 'light'
+    : 'dark';
+}
+
+function readStored(): ThemeChoice {
+  try {
+    const v = localStorage.getItem(STORAGE_KEY);
+    if (v === 'light' || v === 'dark' || v === 'auto') return v;
+  } catch {
+    /* ignore quota/permission errors */
+  }
+  return 'auto';
+}
+
+function apply(resolved: ResolvedTheme): void {
+  const root = document.documentElement;
+  root.dataset.theme = resolved;
+  // Sync the address-bar theme-color so native chrome (URL bar, title bar)
+  // transitions too.
+  const meta = document.querySelector<HTMLMetaElement>('meta[name="theme-color"]');
+  if (meta) {
+    meta.content = resolved === 'light' ? '#fafbfc' : '#0b0d12';
+  }
+}
+
+/**
+ * Three-state theme: auto (follow system), light, dark. The resolved concrete
+ * theme is reflected on `<html data-theme="...">`. User choice is persisted
+ * in localStorage; absence ⇒ auto.
+ */
+export function useTheme(): {
+  choice: ThemeChoice;
+  resolved: ResolvedTheme;
+  cycle: () => void;
+  set: (c: ThemeChoice) => void;
+} {
+  const [choice, setChoice] = useState<ThemeChoice>(() => readStored());
+  const [sys, setSys] = useState<ResolvedTheme>(() => systemTheme());
+
+  // Listen to system changes when in auto mode.
+  useEffect(() => {
+    const m = window.matchMedia('(prefers-color-scheme: light)');
+    const handler = () =>{  setSys(m.matches ? 'light' : 'dark'); };
+    m.addEventListener('change', handler);
+    return () =>{  m.removeEventListener('change', handler); };
+  }, []);
+
+  const resolved: ResolvedTheme = choice === 'auto' ? sys : choice;
+
+  useEffect(() => {
+    apply(resolved);
+  }, [resolved]);
+
+  const set = useCallback((c: ThemeChoice) => {
+    setChoice(c);
+    try {
+      if (c === 'auto') localStorage.removeItem(STORAGE_KEY);
+      else localStorage.setItem(STORAGE_KEY, c);
+    } catch {
+      /* ignore */
+    }
+  }, []);
+
+  // Cycle: auto → light → dark → auto
+  const cycle = useCallback(() => {
+    const next: ThemeChoice =
+      choice === 'auto' ? 'light' : choice === 'light' ? 'dark' : 'auto';
+    set(next);
+  }, [choice, set]);
+
+  return { choice, resolved, cycle, set };
+}
diff --git a/apps/vis/web/src/hooks/useWire.ts b/apps/vis/web/src/hooks/useWire.ts
new file mode 100644
index 000000000..44b3b9737
--- /dev/null
+++ b/apps/vis/web/src/hooks/useWire.ts
@@ -0,0 +1,33 @@
+import { useQuery } from '@tanstack/react-query';
+import { api } from '../api';
+
+export function useWire(sessionId: string | undefined, enabled = true) {
+  return useQuery({
+    queryKey: ['session', sessionId, 'wire'] as const,
+    queryFn: () => api.getWire(sessionId!),
+    enabled: !!sessionId && enabled,
+  });
+}
+
+export function useSubagentWire(
+  sessionId: string | undefined,
+  agentId: string | undefined,
+  enabled = true,
+) {
+  return useQuery({
+    queryKey: ['session', sessionId, 'subagent', agentId, 'wire'] as const,
+    queryFn: () => api.getSubagentWire(sessionId!, agentId!),
+    enabled: !!sessionId && !!agentId && enabled,
+  });
+}
+
+export function useArchive(
+  sessionId: string | undefined,
+  filename: string | undefined,
+) {
+  return useQuery({
+    queryKey: ['session', sessionId, 'archive', filename] as const,
+    queryFn: () => api.getArchive(sessionId!, filename!),
+    enabled: !!sessionId && !!filename,
+  });
+}
diff --git a/apps/vis/web/src/lib/focus-context.tsx b/apps/vis/web/src/lib/focus-context.tsx
new file mode 100644
index 000000000..4174ba107
--- /dev/null
+++ b/apps/vis/web/src/lib/focus-context.tsx
@@ -0,0 +1,96 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+import type { ReactNode } from 'react';
+
+import type { VisWireRecord } from '../types';
+
+export type FocusKind = 'turn_id' | 'tool_call_id' | 'agent_id' | 'step_uuid';
+
+export interface Focus {
+  kind: FocusKind;
+  value: string;
+}
+
+interface FocusContextShape {
+  focus: Focus | null;
+  /** Toggle — clicking the same focused id again clears it. */
+  toggle: (f: Focus) => void;
+  clear: () => void;
+}
+
+const FocusCtx = createContext<FocusContextShape | null>(null);
+
+export function FocusProvider({ children }: { children: ReactNode }) {
+  const [focus, setFocus] = useState<Focus | null>(null);
+  const toggle = useCallback((f: Focus) => {
+    setFocus((prev) =>
+      prev !== null && prev.kind === f.kind && prev.value === f.value ? null : f,
+    );
+  }, []);
+  const clear = useCallback(() =>{  setFocus(null); }, []);
+  // ESC clears the focus — one-liner keyboard affordance.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') clear();
+    };
+    window.addEventListener('keydown', onKey);
+    return () =>{  window.removeEventListener('keydown', onKey); };
+  }, [clear]);
+  const value = useMemo<FocusContextShape>(
+    () => ({ focus, toggle, clear }),
+    [focus, toggle, clear],
+  );
+  return <FocusCtx.Provider value={value}>{children}</FocusCtx.Provider>;
+}
+
+export function useFocus(): FocusContextShape {
+  const ctx = useContext(FocusCtx);
+  if (ctx === null) {
+    // Safe default so components outside a provider don't crash.
+    return { focus: null, toggle: () => {}, clear: () => {} };
+  }
+  return ctx;
+}
+
+/**
+ * A record "belongs to" the focused id when any of its identifiers matches.
+ * Scope is intentionally broad per id kind so click-to-focus behaves like
+ * "show me everything related to this thing":
+ *
+ *   turn_id      → all records with r.turn_id === value
+ *   tool_call_id → the tool_call, its tool_result, any approval linked by id
+ *   agent_id     → spawn/completed/failed + mail records mentioning this agent
+ *   step_uuid    → the step_begin/end + content_parts + tool_calls under it
+ */
+export function recordMatchesFocus(r: VisWireRecord, focus: Focus | null): boolean {
+  if (focus === null) return true;
+  const { kind, value } = focus;
+  const rec = r as Record<string, unknown>;
+  const data = (rec['data'] as Record<string, unknown> | undefined) ?? undefined;
+
+  switch (kind) {
+    case 'turn_id':
+      return rec['turn_id'] === value;
+
+    case 'tool_call_id': {
+      if (rec['tool_call_id'] === value) return true;
+      if (data?.['tool_call_id'] === value) return true;
+      if (data?.['parent_tool_call_id'] === value) return true;
+      return false;
+    }
+
+    case 'agent_id': {
+      if (rec['agent_id'] === value) return true;
+      if (data?.['agent_id'] === value) return true;
+      if (data?.['parent_agent_id'] === value) return true;
+      if (data?.['from_agent'] === value) return true;
+      if (data?.['to_agent'] === value) return true;
+      return false;
+    }
+
+    case 'step_uuid':
+      return rec['uuid'] === value || rec['step_uuid'] === value;
+  }
+  // Unreachable — `FocusKind` is exhausted above. Here to satisfy
+  // consistent-return (switch-exhaustiveness isn't narrowed by the rule).
+  return false;
+}
diff --git a/apps/vis/web/src/lib/issues.ts b/apps/vis/web/src/lib/issues.ts
new file mode 100644
index 000000000..6bde9d7f9
--- /dev/null
+++ b/apps/vis/web/src/lib/issues.ts
@@ -0,0 +1,182 @@
+// Aggregate every "something went wrong" signal from a wire timeline
+// into a flat list consumable by the Issues drawer. Pure — no React.
+
+import type { VisWireRecord } from '../types';
+
+export type IssueSeverity = 'error' | 'warning' | 'info';
+
+export interface Issue {
+  severity: IssueSeverity;
+  /** Human-readable kind — shown as the row's title. */
+  kind:
+    | 'subagent_failed'
+    | 'tool_error'
+    | 'tool_denied'
+    | 'turn_failed'
+    | 'step_truncated'
+    | 'wire_warning';
+  /** Seq of the offending record. `null` for file-level warnings. */
+  seq: number | null;
+  /** Short summary shown on a single line. */
+  summary: string;
+  /** Optional second line / tooltip detail. */
+  detail?: string;
+}
+
+const SEVERITY_ORDER: Record<IssueSeverity, number> = {
+  error: 0,
+  warning: 1,
+  info: 2,
+};
+
+/** Scan `records` + `warnings` and produce an ordered issue list.
+ *  Sorted by severity first, then seq ascending. Warnings (no seq) go last. */
+export function computeIssues(
+  records: readonly VisWireRecord[],
+  warnings: readonly string[],
+): Issue[] {
+  const out: Issue[] = [];
+
+  for (const r of records) {
+    switch (r.type) {
+      case 'subagent_failed': {
+        const d = (r as { data?: { error?: string; agent_id?: string } }).data ?? {};
+        out.push({
+          severity: 'error',
+          kind: 'subagent_failed',
+          seq: r.seq,
+          summary: firstLine(d.error ?? '(no error message)'),
+          detail: d.agent_id ? `agent ${d.agent_id}` : undefined,
+        });
+        break;
+      }
+      case 'tool_result': {
+        const rec = r as { is_error?: boolean; output?: unknown; tool_call_id?: string };
+        if (rec.is_error === true) {
+          const text =
+            typeof rec.output === 'string'
+              ? rec.output
+              : rec.output !== undefined
+                ? (() => {
+                    try {
+                      return JSON.stringify(rec.output);
+                    } catch {
+                      return '(unserializable output)';
+                    }
+                  })()
+                : '';
+          out.push({
+            severity: 'error',
+            kind: 'tool_error',
+            seq: r.seq,
+            summary: firstLine(text) || '(no output)',
+            detail: rec.tool_call_id ? `call ${rec.tool_call_id}` : undefined,
+          });
+        }
+        break;
+      }
+      case 'tool_denied': {
+        const d =
+          (r as { data?: { tool_name?: string; reason?: string; rule_id?: string } }).data ?? {};
+        out.push({
+          severity: 'warning',
+          kind: 'tool_denied',
+          seq: r.seq,
+          summary: `${d.tool_name ?? 'tool'} — ${firstLine(d.reason ?? '(no reason)')}`,
+          detail: d.rule_id ? `rule ${d.rule_id}` : undefined,
+        });
+        break;
+      }
+      case 'turn_end': {
+        const rec = r as {
+          success?: boolean;
+          reason?: string;
+          turn_id?: string;
+          synthetic?: boolean;
+        };
+        if (rec.success === false || rec.reason === 'error' || rec.reason === 'interrupted') {
+          out.push({
+            severity: 'warning',
+            kind: 'turn_failed',
+            seq: r.seq,
+            summary: `turn ${rec.turn_id ?? ''} — ${rec.reason ?? 'unknown'}`,
+            detail: rec.synthetic === true ? 'synthetic' : undefined,
+          });
+        }
+        break;
+      }
+      case 'step_end': {
+        const rec = r as { finish_reason?: string; turn_id?: string };
+        if (rec.finish_reason === 'length' || rec.finish_reason === 'error') {
+          out.push({
+            severity: 'info',
+            kind: 'step_truncated',
+            seq: r.seq,
+            summary: `step finished with "${rec.finish_reason}"`,
+            detail: rec.turn_id ? `turn ${rec.turn_id}` : undefined,
+          });
+        }
+        break;
+      }
+      case 'approval_request':
+      case 'approval_response':
+      case 'compaction':
+      case 'content_part':
+      case 'context_cleared':
+      case 'context_edit':
+      case 'metadata':
+      case 'notification':
+      case 'ownership_changed':
+      case 'session_initialized':
+      case 'skill_completed':
+      case 'skill_invoked':
+      case 'step_begin':
+      case 'subagent_completed':
+      case 'subagent_spawned':
+      case 'system_prompt_changed':
+      case 'system_reminder':
+      case 'team_mail':
+      case 'tool_call':
+      case 'tools_changed':
+      case 'turn_begin':
+      case 'user_message':
+        break;
+      default:
+        break;
+    }
+  }
+
+  for (const w of warnings) {
+    out.push({
+      severity: 'warning',
+      kind: 'wire_warning',
+      seq: null,
+      summary: firstLine(w),
+    });
+  }
+
+  out.sort((a, b) => {
+    const d = SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+    if (d !== 0) return d;
+    const sa = a.seq ?? Number.POSITIVE_INFINITY;
+    const sb = b.seq ?? Number.POSITIVE_INFINITY;
+    return sa - sb;
+  });
+
+  return out;
+}
+
+/** Top-level summary tone used for the toolbar pill — "worst wins". */
+export function topSeverity(issues: readonly Issue[]): IssueSeverity | null {
+  if (issues.length === 0) return null;
+  for (const i of issues) if (i.severity === 'error') return 'error';
+  for (const i of issues) if (i.severity === 'warning') return 'warning';
+  return 'info';
+}
+
+function firstLine(s: string): string {
+  const trimmed = s.trim();
+  const nl = trimmed.indexOf('\n');
+  const one = nl === -1 ? trimmed : trimmed.slice(0, nl);
+  return one.length > 120 ? one.slice(0, 120) + '…' : one;
+}
diff --git a/apps/vis/web/src/lib/query-parser.ts b/apps/vis/web/src/lib/query-parser.ts
new file mode 100644
index 000000000..67c669133
--- /dev/null
+++ b/apps/vis/web/src/lib/query-parser.ts
@@ -0,0 +1,295 @@
+// Structured query language for the Wire tab's search box.
+//
+// Grammar (whitespace-separated; AND between tokens):
+//   key:value            exact/contains match on a specific field
+//   key:a,b,c            OR across values
+//   key:!value           NOT match
+//   key:>N / <N / >=N / <=N   numeric comparison (seq only)
+//   bare word            substring match on full record JSON (fallback)
+//
+// Supported keys:
+//   type   — r.type exact (OR-able, NOT-able)
+//   tool   — tool_call.data.tool_name substring (also matches paired tool_result)
+//   turn   — r.turn_id substring
+//   seq    — numeric compare on r.seq
+//   error  — boolean; true → records that represent failure/error states
+//   agent  — substring over any agent_id field
+//   id     — substring over any *_id / uuid field
+//
+// Unknown keys become `errors[]` entries; chip UI shows them in red.
+
+import type { VisWireRecord, WireRecordType } from '../types';
+
+export type TokenOp = '=' | '!=' | '>' | '<' | '>=' | '<=' | '~';
+
+export interface QueryToken {
+  /** null = bare text token (substring across whole record). */
+  key: string | null;
+  op: TokenOp;
+  /** Comma-split values; length >= 1 always. */
+  values: string[];
+  /** Source slice in the query string; useful to rewrite/remove a single chip. */
+  raw: string;
+}
+
+export interface ParsedQuery {
+  tokens: QueryToken[];
+  errors: { token: string; reason: string }[];
+}
+
+const KNOWN_KEYS = new Set(['type', 'tool', 'turn', 'seq', 'error', 'agent', 'id']);
+
+export function parseQuery(input: string): ParsedQuery {
+  const tokens: QueryToken[] = [];
+  const errors: { token: string; reason: string }[] = [];
+  // Simple whitespace split — no quoted-string support yet (keep it minimal).
+  const parts = input.split(/\s+/).filter((s) => s.length > 0);
+  for (const raw of parts) {
+    const colon = raw.indexOf(':');
+    if (colon <= 0) {
+      tokens.push({ key: null, op: '~', values: [raw], raw });
+      continue;
+    }
+    const key = raw.slice(0, colon);
+    let rest = raw.slice(colon + 1);
+    let op: TokenOp = '=';
+    if (rest.startsWith('!')) {
+      op = '!=';
+      rest = rest.slice(1);
+    } else if (rest.startsWith('>=')) {
+      op = '>=';
+      rest = rest.slice(2);
+    } else if (rest.startsWith('<=')) {
+      op = '<=';
+      rest = rest.slice(2);
+    } else if (rest.startsWith('>')) {
+      op = '>';
+      rest = rest.slice(1);
+    } else if (rest.startsWith('<')) {
+      op = '<';
+      rest = rest.slice(1);
+    }
+    const values = rest.split(',').filter((s) => s.length > 0);
+    if (values.length === 0) {
+      errors.push({ token: raw, reason: 'missing value' });
+      continue;
+    }
+    if (!KNOWN_KEYS.has(key)) {
+      errors.push({
+        token: raw,
+        reason: `unknown key "${key}" — try: ${[...KNOWN_KEYS].join(', ')}`,
+      });
+      // Still push so the chip can render (in red) and be removable.
+      tokens.push({ key, op, values, raw });
+      continue;
+    }
+    tokens.push({ key, op, values, raw });
+  }
+  return { tokens, errors };
+}
+
+/** Pre-compute helper sets used by some matchers. Call once per records[] + query. */
+export interface MatchContext {
+  /** tool_call_ids of tool_call records whose tool_name matches a `tool:` token. */
+  toolMatchingCallIds: Set<string>;
+}
+
+export function buildMatchContext(
+  records: readonly VisWireRecord[],
+  query: ParsedQuery,
+): MatchContext {
+  const ctx: MatchContext = { toolMatchingCallIds: new Set() };
+  const toolTokens = query.tokens.filter((t) => t.key === 'tool');
+  if (toolTokens.length === 0) return ctx;
+  for (const r of records) {
+    if (r.type !== 'tool_call') continue;
+    const name = getToolName(r);
+    if (name === null) continue;
+    const lower = name.toLowerCase();
+    const anyMatch = toolTokens.every((t) => matchTextToken(lower, t));
+    if (!anyMatch) continue;
+    const id = getToolCallId(r);
+    if (id !== null) ctx.toolMatchingCallIds.add(id);
+  }
+  return ctx;
+}
+
+export function matchesQuery(
+  record: VisWireRecord,
+  query: ParsedQuery,
+  ctx: MatchContext,
+): boolean {
+  if (query.tokens.length === 0) return true;
+  for (const token of query.tokens) {
+    if (!matchesOne(record, token, ctx)) return false;
+  }
+  return true;
+}
+
+function matchesOne(r: VisWireRecord, t: QueryToken, ctx: MatchContext): boolean {
+  if (t.key === null) {
+    // Bare text — fallback to JSON substring, case-insensitive.
+    const needle = (t.values[0] ?? '').toLowerCase();
+    if (needle.length === 0) return true;
+    try {
+      return JSON.stringify(r).toLowerCase().includes(needle);
+    } catch {
+      return false;
+    }
+  }
+  switch (t.key) {
+    case 'type':
+      return matchType(r.type, t);
+    case 'tool':
+      return matchTool(r, t, ctx);
+    case 'turn':
+      return matchText(getField(r, 'turn_id'), t);
+    case 'seq':
+      return matchNumber(r.seq, t);
+    case 'error':
+      return matchError(r, t);
+    case 'agent':
+      return matchAgent(r, t);
+    case 'id':
+      return matchAnyId(r, t);
+    default:
+      // Unknown key — treat as no-match so chip is clearly inert.
+      return false;
+  }
+}
+
+function matchType(type: WireRecordType, t: QueryToken): boolean {
+  const hit = t.values.includes(type);
+  return t.op === '!=' ? !hit : hit;
+}
+
+function matchTool(r: VisWireRecord, t: QueryToken, ctx: MatchContext): boolean {
+  if (r.type === 'tool_call') {
+    const name = getToolName(r);
+    return name !== null && matchTextToken(name.toLowerCase(), t);
+  }
+  if (r.type === 'tool_result') {
+    const id = getField(r, 'tool_call_id');
+    return id !== null && ctx.toolMatchingCallIds.has(id);
+  }
+  if (r.type === 'tool_denied') {
+    const name = (getField(r, 'data.tool_name') ?? '').toLowerCase();
+    return matchTextToken(name, t);
+  }
+  return false;
+}
+
+function matchText(value: string | null, t: QueryToken): boolean {
+  if (value === null) return t.op === '!=';
+  return matchTextToken(value.toLowerCase(), t);
+}
+
+function matchTextToken(haystackLower: string, t: QueryToken): boolean {
+  const hit = textHit(haystackLower, t);
+  return t.op === '!=' ? !hit : hit;
+}
+
+/** Pure "does this haystack contain any of the token values?" — no op
+ *  inversion. Callers that check multiple candidate fields must invert
+ *  the combined result themselves, otherwise `agent:!abc` over a record
+ *  that has one matching field and three null fields would incorrectly
+ *  flip for the null fields and report success. */
+function textHit(haystackLower: string, t: QueryToken): boolean {
+  return t.values.some((v) => haystackLower.includes(v.toLowerCase()));
+}
+
+function matchNumber(value: number, t: QueryToken): boolean {
+  const n = Number(t.values[0]);
+  if (!Number.isFinite(n)) return false;
+  switch (t.op) {
+    case '>':
+      return value > n;
+    case '<':
+      return value < n;
+    case '>=':
+      return value >= n;
+    case '<=':
+      return value <= n;
+    case '!=':
+      return value !== n;
+    case '=':
+    case '~':
+      return value === n;
+    default:
+      return false;
+  }
+}
+
+function matchError(r: VisWireRecord, t: QueryToken): boolean {
+  const want = (t.values[0] ?? 'true').toLowerCase() !== 'false';
+  const isError =
+    r.type === 'subagent_failed' ||
+    r.type === 'tool_denied' ||
+    (r.type === 'tool_result' && (r as { is_error?: boolean }).is_error === true) ||
+    (r.type === 'turn_end' && (r as { success?: boolean }).success === false);
+  return want ? isError : !isError;
+}
+
+function matchAgent(r: VisWireRecord, t: QueryToken): boolean {
+  const candidates: string[] = [
+    getField(r, 'agent_id'),
+    getField(r, 'data.agent_id'),
+    getField(r, 'parent_agent_id'),
+    getField(r, 'data.parent_agent_id'),
+  ].filter((c): c is string => c !== null);
+  return matchAcrossCandidates(candidates, t);
+}
+
+function matchAnyId(r: VisWireRecord, t: QueryToken): boolean {
+  const candidates: string[] = [
+    getField(r, 'uuid'),
+    getField(r, 'step_uuid'),
+    getField(r, 'turn_id'),
+    getField(r, 'tool_call_id'),
+    getField(r, 'session_id'),
+    getField(r, 'agent_id'),
+    getField(r, 'data.agent_id'),
+    getField(r, 'data.tool_call_id'),
+    getField(r, 'data.mail_id'),
+  ].filter((c): c is string => c !== null);
+  return matchAcrossCandidates(candidates, t);
+}
+
+/** op='=' : any candidate contains any token value
+ *  op='!=': NO candidate contains any token value
+ *  Handles the op inversion at the aggregate level so records with
+ *  multiple candidate fields behave sanely (the per-field `matchTextToken`
+ *  would flip on each null/non-match independently — wrong for multi-field
+ *  records). */
+function matchAcrossCandidates(candidates: string[], t: QueryToken): boolean {
+  const anyHit = candidates.some((c) => textHit(c.toLowerCase(), t));
+  return t.op === '!=' ? !anyHit : anyHit;
+}
+
+// ── field access helpers ─────────────────────────────────────────────
+
+function getField(r: VisWireRecord, path: string): string | null {
+  const parts = path.split('.');
+  let cur: unknown = r;
+  for (const p of parts) {
+    if (cur === null || cur === undefined || typeof cur !== 'object') return null;
+    cur = (cur as Record<string, unknown>)[p];
+  }
+  return typeof cur === 'string' ? cur : null;
+}
+
+function getToolName(r: VisWireRecord): string | null {
+  // Prefer `tool_call.data.tool_name`; fall back to a legacy top-level field
+  // for older records.
+  const data = (r as { data?: Record<string, unknown> }).data;
+  if (data && typeof data['tool_name'] === 'string') return data['tool_name'];
+  const top = (r as Record<string, unknown>)['tool_name'];
+  return typeof top === 'string' ? top : null;
+}
+
+function getToolCallId(r: VisWireRecord): string | null {
+  const data = (r as { data?: Record<string, unknown> }).data;
+  if (data && typeof data['tool_call_id'] === 'string') return data['tool_call_id'];
+  const top = (r as Record<string, unknown>)['tool_call_id'];
+  return typeof top === 'string' ? top : null;
+}
diff --git a/apps/vis/web/src/main.tsx b/apps/vis/web/src/main.tsx
new file mode 100644
index 000000000..7d903ffe9
--- /dev/null
+++ b/apps/vis/web/src/main.tsx
@@ -0,0 +1,30 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+import { App } from './App';
+import './theme.css';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: Infinity,
+      gcTime: 30 * 60 * 1000,
+      retry: false,
+      refetchOnWindowFocus: false,
+    },
+  },
+});
+
+const rootEl = document.querySelector('#root');
+if (!rootEl) throw new Error('#root not found');
+
+createRoot(rootEl).render(
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <App />
+      </BrowserRouter>
+    </QueryClientProvider>
+  </StrictMode>,
+);
diff --git a/apps/vis/web/src/pages/SessionDetailPage.tsx b/apps/vis/web/src/pages/SessionDetailPage.tsx
new file mode 100644
index 000000000..649b3cb0b
--- /dev/null
+++ b/apps/vis/web/src/pages/SessionDetailPage.tsx
@@ -0,0 +1,158 @@
+import { useParams } from 'react-router-dom';
+import { useSession } from '../hooks/useSession';
+import { useWire } from '../hooks/useWire';
+import { useSessionContext } from '../hooks/useContext';
+import { useSubagents } from '../hooks/useSubagents';
+import { TabBar, useActiveTab } from '../components/layout/TabBar';
+import { WireTab } from '../components/wire/WireTab';
+import { ContextTab } from '../components/context/ContextTab';
+import { SubagentsTab } from '../components/subagents/SubagentsTab';
+import { StateTab } from '../components/state/StateTab';
+import { FilesTab } from '../components/files/FilesTab';
+import { CopyButton } from '../components/shared/CopyButton';
+import { Pill } from '../components/shared/Pill';
+import { formatAbsoluteTime, formatRelativeTime } from '../util/time';
+
+type TabId = 'wire' | 'context' | 'subagents' | 'state' | 'files';
+
+export function SessionDetailPage() {
+  const { sessionId } = useParams<{ sessionId: string }>();
+  const active = useActiveTab('wire') as TabId;
+
+  const { data: session, isLoading: sessionLoading, error: sessionError } = useSession(sessionId);
+
+  // Eagerly count subagents from the session detail; fetch wire/context/subagents
+  // only when their tab is open.
+  const wireQ = useWire(sessionId, active === 'wire');
+  const contextQ = useSessionContext(sessionId, active === 'context');
+  const subQ = useSubagents(sessionId, active === 'subagents');
+
+  if (!sessionId) return <div className="p-6 text-fg-3">(no session id)</div>;
+  if (sessionLoading) return <div className="p-6 font-mono text-[12px] text-fg-3">loading session…</div>;
+  if (sessionError)
+    return (
+      <div className="p-6 font-mono text-[12px] text-[var(--color-sev-error)]">
+        {(sessionError).message}
+      </div>
+    );
+  if (!session) return null;
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      {/* Detail header */}
+      <div className="shrink-0 border-b border-border bg-surface-1 px-4 py-3">
+        <div className="flex items-center gap-3">
+          <span className="font-mono text-[14px] text-fg-0">{session.session_id}</span>
+          <CopyButton value={session.session_id} />
+          {session.state.model ? (
+            <Pill tone="config" variant="soft">{session.state.model}</Pill>
+          ) : null}
+          {session.state.archived ? (
+            <Pill tone="warning" variant="outline">archived</Pill>
+          ) : null}
+          {session.state.permission_mode === 'bypassPermissions' ? (
+            <Pill tone="error" variant="outline">yolo</Pill>
+          ) : null}
+          {session.title ? (
+            <span className="font-mono text-[12px] text-fg-1">
+              "{session.title}"
+            </span>
+          ) : null}
+        </div>
+        <div className="mt-1 flex items-center gap-3 font-mono text-[11px] text-fg-2">
+          {session.state.workspace_dir ? (
+            <span className="truncate" title={session.state.workspace_dir}>
+              {session.state.workspace_dir}
+            </span>
+          ) : null}
+          {session.state.updated_at ? (
+            <span className="text-fg-3 tabular">
+              updated {formatRelativeTime(session.state.updated_at)} ·{' '}
+              {formatAbsoluteTime(session.state.updated_at)}
+            </span>
+          ) : null}
+        </div>
+        {session.last_prompt ? (
+          <div className="mt-1 truncate font-mono text-[11px] text-fg-3" title={session.last_prompt}>
+            prompt · {session.last_prompt}
+          </div>
+        ) : null}
+      </div>
+
+      <TabBar
+        defaultTab="wire"
+        tabs={[
+          { id: 'wire', label: 'Wire', count: wireQ.data?.records.length ?? null },
+          { id: 'context', label: 'Context', count: contextQ.data?.annotated_messages.length ?? null },
+          { id: 'subagents', label: 'Subagents', count: session.subagent_ids.length },
+          { id: 'state', label: 'State', count: null },
+          { id: 'files', label: 'Files', count: session.archive_files.length + session.tool_result_ids.length },
+        ]}
+      />
+
+      <div className="flex min-h-0 flex-1 flex-col">
+        {active === 'wire' ? (
+          wireQ.isLoading ? (
+            <Centered>loading wire…</Centered>
+          ) : wireQ.error ? (
+            <ErrorView msg={(wireQ.error).message} />
+          ) : wireQ.data ? (
+            <WireTab
+              records={wireQ.data.records}
+              health={wireQ.data.health}
+              brokenReason={wireQ.data.broken_reason}
+              warnings={wireQ.data.warnings}
+            />
+          ) : null
+        ) : null}
+
+        {active === 'context' ? (
+          contextQ.isLoading ? (
+            <Centered>loading context…</Centered>
+          ) : contextQ.error ? (
+            <ErrorView msg={(contextQ.error).message} />
+          ) : contextQ.data ? (
+            <ContextTab
+              sessionId={sessionId}
+              messages={contextQ.data.annotated_messages}
+              projectedState={contextQ.data.projected_state}
+            />
+          ) : null
+        ) : null}
+
+        {active === 'subagents' ? (
+          subQ.isLoading ? (
+            <Centered>loading subagents…</Centered>
+          ) : (
+            <SubagentsTab sessionId={sessionId} />
+          )
+        ) : null}
+
+        {active === 'state' ? (
+          <StateTab
+            state={session.state}
+            protocolVersion={session.wire_metadata?.protocol_version ?? null}
+          />
+        ) : null}
+
+        {active === 'files' ? (
+          <FilesTab sessionId={sessionId} detail={session} />
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+function Centered({ children }: { children: import('react').ReactNode }) {
+  return (
+    <div className="flex flex-1 items-center justify-center p-6 font-mono text-[12px] text-fg-3">
+      {children}
+    </div>
+  );
+}
+
+function ErrorView({ msg }: { msg: string }) {
+  return (
+    <div className="p-6 font-mono text-[12px] text-[var(--color-sev-error)]">{msg}</div>
+  );
+}
diff --git a/apps/vis/web/src/pages/SessionListPage.tsx b/apps/vis/web/src/pages/SessionListPage.tsx
new file mode 100644
index 000000000..556ca63b3
--- /dev/null
+++ b/apps/vis/web/src/pages/SessionListPage.tsx
@@ -0,0 +1,35 @@
+import { useSessions } from '../hooks/useSession';
+
+export function SessionListPage() {
+  const { data } = useSessions();
+  const count = data?.length ?? 0;
+
+  return (
+    <div className="flex h-full items-center justify-center">
+      <div className="max-w-md px-8 text-center">
+        <div className="font-mono text-[11px] uppercase tracking-[0.2em] text-fg-3">
+          kimi vis
+        </div>
+        <div className="mt-3 font-mono text-[13px] text-fg-1">
+          select a session from the left rail to begin inspecting
+        </div>
+        <div className="mt-6 flex items-center justify-center gap-6 font-mono text-[11px] text-fg-2">
+          <div>
+            <div className="tabular text-[22px] text-fg-0">{count}</div>
+            <div className="text-fg-3">sessions</div>
+          </div>
+        </div>
+        <div className="mt-10 space-y-1 text-left font-mono text-[10.5px] text-fg-3">
+          <div>
+            <kbd className="mr-2 border border-border px-1 text-fg-2">/</kbd>
+            focus search
+          </div>
+          <div>
+            <kbd className="mr-2 border border-border px-1 text-fg-2">esc</kbd>
+            close drawers
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/vis/web/src/pages/SubagentDetailPage.tsx b/apps/vis/web/src/pages/SubagentDetailPage.tsx
new file mode 100644
index 000000000..c5ef4868f
--- /dev/null
+++ b/apps/vis/web/src/pages/SubagentDetailPage.tsx
@@ -0,0 +1,206 @@
+import { Link, useParams } from 'react-router-dom';
+import { useSubagentWire } from '../hooks/useWire';
+import { useSubagentContext } from '../hooks/useContext';
+import { useSubagentMeta } from '../hooks/useSubagents';
+import { TabBar, useActiveTab } from '../components/layout/TabBar';
+import { WireTab } from '../components/wire/WireTab';
+import { ContextTab } from '../components/context/ContextTab';
+import { JsonViewer } from '../components/shared/JsonViewer';
+import { Pill } from '../components/shared/Pill';
+import { formatAbsoluteTime, formatRelativeTime } from '../util/time';
+
+type TabId = 'wire' | 'context' | 'meta';
+
+export function SubagentDetailPage() {
+  const { sessionId, agentId } = useParams<{ sessionId: string; agentId: string }>();
+  const active = useActiveTab('wire') as TabId;
+
+  const wireQ = useSubagentWire(sessionId, agentId, active === 'wire');
+  const contextQ = useSubagentContext(sessionId, agentId, active === 'context');
+  const metaQ = useSubagentMeta(sessionId, agentId);
+
+  if (!sessionId || !agentId) return null;
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      {/* Breadcrumb + header */}
+      <div className="shrink-0 border-b border-border bg-surface-1 px-4 py-3">
+        <div className="flex items-center gap-2 font-mono text-[11px] text-fg-2">
+          <Link to={`/sessions/${sessionId}?tab=subagents`} className="hover:text-fg-0">
+            ‹ back to subagents
+          </Link>
+          <span className="text-fg-3">·</span>
+          <Link to={`/sessions/${sessionId}`} className="hover:text-fg-0">main</Link>
+          <span className="text-fg-3">›</span>
+          <span className="text-fg-0">
+            {agentId.replace(/^sub_/, '').slice(0, 12)}
+          </span>
+        </div>
+        <div className="mt-2 flex items-center gap-3">
+          <span className="font-mono text-[14px] text-fg-0">{agentId}</span>
+          {metaQ.data?.meta_json?.subagent_type ? (
+            <Pill tone="subagent" variant="soft">
+              {metaQ.data.meta_json.subagent_type}
+            </Pill>
+          ) : null}
+          {metaQ.data?.meta_json?.status ? (
+            <Pill tone="neutral" variant="outline">
+              {metaQ.data.meta_json.status}
+            </Pill>
+          ) : null}
+          {metaQ.data?.depth !== undefined ? (
+            <span className="font-mono text-[11px] text-fg-3 tabular">
+              depth {metaQ.data.depth}
+            </span>
+          ) : null}
+        </div>
+        {metaQ.data?.meta_json?.description ? (
+          <div className="mt-1 font-mono text-[12px] text-fg-1">
+            {metaQ.data.meta_json.description}
+          </div>
+        ) : null}
+      </div>
+
+      <TabBar
+        defaultTab="wire"
+        tabs={[
+          { id: 'wire', label: 'Wire', count: wireQ.data?.records.length ?? null },
+          { id: 'context', label: 'Context', count: contextQ.data?.annotated_messages.length ?? null },
+          { id: 'meta', label: 'Meta', count: null },
+        ]}
+      />
+
+      <div className="flex min-h-0 flex-1 flex-col">
+        {active === 'wire' ? (
+          wireQ.isLoading ? (
+            <Centered>loading wire…</Centered>
+          ) : wireQ.error ? (
+            <ErrorView msg={(wireQ.error).message} />
+          ) : wireQ.data ? (
+            <WireTab
+              records={wireQ.data.records}
+              health={wireQ.data.health}
+              brokenReason={wireQ.data.broken_reason}
+              warnings={wireQ.data.warnings}
+            />
+          ) : null
+        ) : null}
+
+        {active === 'context' ? (
+          contextQ.isLoading ? (
+            <Centered>loading context…</Centered>
+          ) : contextQ.error ? (
+            <ErrorView msg={(contextQ.error).message} />
+          ) : contextQ.data ? (
+            <ContextTab
+              sessionId={sessionId}
+              messages={contextQ.data.annotated_messages}
+              projectedState={contextQ.data.projected_state}
+            />
+          ) : null
+        ) : null}
+
+        {active === 'meta' ? <MetaView meta={metaQ.data} error={metaQ.error} /> : null}
+      </div>
+    </div>
+  );
+}
+
+function MetaView({ meta, error }: { meta: unknown; error: unknown }) {
+  if (error) {
+    return <ErrorView msg={(error as Error).message} />;
+  }
+  if (!meta) return <Centered>loading meta…</Centered>;
+  const m = meta as {
+    meta_json: unknown;
+    spawned_record: unknown;
+    completed_record: unknown;
+    failed_record: unknown;
+  };
+  return (
+    <div className="flex-1 min-h-0 overflow-y-auto p-4 space-y-6">
+      <MetaSection title="meta.json" value={m.meta_json} />
+      <MetaSection title="spawn record" subtitle="from parent wire" value={m.spawned_record} />
+      <MetaSection title="completion record" subtitle="from parent wire" value={m.completed_record} />
+      <MetaSection title="failure record" subtitle="from parent wire" value={m.failed_record} />
+      <TimestampsSection spawned={m.spawned_record} completed={m.completed_record} failed={m.failed_record} />
+    </div>
+  );
+}
+
+function MetaSection({
+  title,
+  subtitle,
+  value,
+}: {
+  title: string;
+  subtitle?: string;
+  value: unknown;
+}) {
+  return (
+    <section>
+      <h2 className="flex items-baseline gap-3 font-mono text-[11px] uppercase tracking-[0.12em] text-fg-3">
+        {title}
+        {subtitle ? <span className="text-fg-3/70">{subtitle}</span> : null}
+      </h2>
+      <div className="mt-2 border border-border bg-surface-0 p-3">
+        {value === null || value === undefined ? (
+          <span className="font-mono text-[11px] text-fg-3">(not present)</span>
+        ) : (
+          <JsonViewer value={value} defaultOpenDepth={2} />
+        )}
+      </div>
+    </section>
+  );
+}
+
+function TimestampsSection({ spawned, completed, failed }: { spawned: unknown; completed: unknown; failed: unknown }) {
+  const rows = [
+    spawned ? ['spawn', (spawned as { time?: number }).time] : null,
+    completed ? ['complete', (completed as { time?: number }).time] : null,
+    failed ? ['failure', (failed as { time?: number }).time] : null,
+  ].filter(Boolean) as [string, number | undefined][];
+  if (rows.length === 0) return null;
+  return (
+    <section>
+      <h2 className="font-mono text-[11px] uppercase tracking-[0.12em] text-fg-3">timeline</h2>
+      <div className="mt-2 border border-border bg-surface-0">
+        <table className="w-full font-mono text-[12px]">
+          <tbody>
+            {rows.map(([label, t]) => (
+              <tr key={label} className="border-b border-border last:border-b-0">
+                <td className="w-[120px] border-r border-border bg-surface-1 px-3 py-1.5 text-right text-fg-2">
+                  {label}
+                </td>
+                <td className="px-3 py-1.5 text-fg-0 tabular">
+                  {t !== undefined ? (
+                    <>
+                      {formatAbsoluteTime(t)}{' '}
+                      <span className="text-fg-3">({formatRelativeTime(t)})</span>
+                    </>
+                  ) : (
+                    <span className="text-fg-3">—</span>
+                  )}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </section>
+  );
+}
+
+function Centered({ children }: { children: import('react').ReactNode }) {
+  return (
+    <div className="flex flex-1 items-center justify-center p-6 font-mono text-[12px] text-fg-3">
+      {children}
+    </div>
+  );
+}
+
+function ErrorView({ msg }: { msg: string }) {
+  return (
+    <div className="p-6 font-mono text-[12px] text-[var(--color-sev-error)]">{msg}</div>
+  );
+}
diff --git a/apps/vis/web/src/theme.css b/apps/vis/web/src/theme.css
new file mode 100644
index 000000000..aa9f62309
--- /dev/null
+++ b/apps/vis/web/src/theme.css
@@ -0,0 +1,239 @@
+@import "tailwindcss";
+
+/* ─────────────────────────────────────────────────────────────────────────
+   Design tokens. Tailwind v4 @theme registers the variables AND generates
+   utilities like `bg-surface-0`, `text-fg-0`. Dark theme is the baseline;
+   light theme overrides the same variable names below.
+   ───────────────────────────────────────────────────────────────────────── */
+
+@theme {
+  --font-mono: "JetBrains Mono", "SF Mono", Menlo, Consolas, monospace;
+  --font-ui: "Geist", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+
+  /* Surface (dark baseline) */
+  --color-surface-0: #0b0d12;
+  --color-surface-1: #12151c;
+  --color-surface-2: #1a1e27;
+  --color-surface-3: #242936;
+  --color-border: #1f2430;
+  --color-border-strong: #2d3342;
+
+  /* Foreground (dark baseline) */
+  --color-fg-0: #e4e7ef;
+  --color-fg-1: #a8afc0;
+  --color-fg-2: #6c7488;
+  --color-fg-3: #454c5e;
+
+  /* Text color used on top of a solid accent pill (so contrast stays
+     legible regardless of which accent). Dark theme: near-black. */
+  --color-on-accent: #0b0d12;
+
+  /* Category accents (dark baseline) */
+  --color-cat-conversation: #22d3ee;
+  --color-cat-config: #a78bfa;
+  --color-cat-lifecycle: #94a3b8;
+  --color-cat-subagent: #8b5cf6;
+  --color-cat-approval: #fb923c;
+  --color-cat-ephemeral: #facc15;
+  --color-cat-meta: #6366f1;
+  --color-cat-tools: #f59e0b;
+
+  /* Conversation subfamily */
+  --color-user: #38bdf8;
+  --color-assistant: #22d3ee;
+  --color-tool: #f59e0b;
+  --color-compaction: #f97316;
+  --color-turn: #14b8a6;
+
+  /* Severity */
+  --color-sev-info: #60a5fa;
+  --color-sev-success: #4ade80;
+  --color-sev-warning: #fbbf24;
+  --color-sev-error: #f87171;
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+   Light-theme overrides. Applied when <html data-theme="light">.
+   Accents get darker variants for AA contrast on light backgrounds.
+   ───────────────────────────────────────────────────────────────────────── */
+
+:root[data-theme="light"] {
+  color-scheme: light;
+
+  --color-surface-0: #fafbfc;
+  --color-surface-1: #eef1f6;
+  --color-surface-2: #e4e8f0;
+  --color-surface-3: #d4d9e4;
+  --color-border: #dde1ea;
+  --color-border-strong: #bfc6d4;
+
+  --color-fg-0: #0f1219;
+  --color-fg-1: #3a4154;
+  --color-fg-2: #616878;
+  --color-fg-3: #9097a8;
+
+  --color-on-accent: #fafbfc;
+
+  --color-cat-conversation: #0891b2;
+  --color-cat-config: #7c3aed;
+  --color-cat-lifecycle: #475569;
+  --color-cat-subagent: #6d28d9;
+  --color-cat-approval: #c2410c;
+  --color-cat-ephemeral: #a16207;
+  --color-cat-meta: #4338ca;
+  --color-cat-tools: #b45309;
+
+  --color-user: #0369a1;
+  --color-assistant: #0891b2;
+  --color-tool: #b45309;
+  --color-compaction: #c2410c;
+  --color-turn: #0d9488;
+
+  --color-sev-info: #2563eb;
+  --color-sev-success: #15803d;
+  --color-sev-warning: #b45309;
+  --color-sev-error: #b91c1c;
+}
+
+:root[data-theme="dark"] {
+  color-scheme: dark;
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+   Base
+   ───────────────────────────────────────────────────────────────────────── */
+
+html,
+body,
+#root {
+  height: 100%;
+  margin: 0;
+}
+
+body {
+  font-family: var(--font-ui);
+  font-size: 13px;
+  line-height: 1.45;
+  background-color: var(--color-surface-0);
+  color: var(--color-fg-0);
+}
+
+/* Subtle noise grain only on dark — adds industrial texture. On light it
+   just looks dirty, so omit. */
+:root:not([data-theme="light"]) body {
+  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='160' height='160'><filter id='n'><feTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2' stitchTiles='stitch'/><feColorMatrix values='0 0 0 0 0.9  0 0 0 0 0.92  0 0 0 0 0.98  0 0 0 0.035 0'/></filter><rect width='100%25' height='100%25' filter='url(%23n)'/></svg>");
+  background-repeat: repeat;
+}
+
+/* Force-disable ligatures and contextual alternates in monospace — debug
+   tool must render characters verbatim. */
+.font-mono {
+  font-feature-settings: "liga" 0, "calt" 0, "ss01" 0;
+  font-variant-ligatures: none;
+  font-family: var(--font-mono);
+}
+
+.tabular {
+  font-variant-numeric: tabular-nums;
+}
+
+/* Scrollbar */
+* {
+  scrollbar-width: thin;
+  scrollbar-color: var(--color-border-strong) transparent;
+}
+
+*::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+
+*::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+*::-webkit-scrollbar-thumb {
+  background: var(--color-border-strong);
+  border-radius: 0;
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+
+*::-webkit-scrollbar-thumb:hover {
+  background: var(--color-fg-3);
+  background-clip: padding-box;
+  border: 2px solid transparent;
+}
+
+::selection {
+  background-color: color-mix(in oklab, var(--color-cat-conversation) 30%, transparent);
+  color: var(--color-fg-0);
+}
+
+*:focus-visible {
+  outline: 1px solid var(--color-cat-conversation);
+  outline-offset: 1px;
+}
+
+/* Button + anchor element resets — kept inside @layer base so Tailwind
+   utilities (px-*, py-*, etc.) in the utilities layer win over them.
+   Unlayered rules would otherwise beat layered utilities in the cascade. */
+@layer base {
+  button {
+    font-family: inherit;
+    font-size: inherit;
+    background: none;
+    border: none;
+    padding: 0;
+    color: inherit;
+    cursor: pointer;
+  }
+
+  a {
+    color: inherit;
+    text-decoration: none;
+  }
+}
+
+.rule {
+  border-top: 1px solid var(--color-border);
+}
+
+.accent-bar {
+  width: 3px;
+  flex-shrink: 0;
+  align-self: stretch;
+}
+
+.ephemeral-border {
+  border: 1px dashed var(--color-cat-ephemeral);
+  border-radius: 2px;
+}
+
+.ephemeral-border-info {
+  border-color: var(--color-sev-info);
+}
+.ephemeral-border-success {
+  border-color: var(--color-sev-success);
+}
+.ephemeral-border-warning {
+  border-color: var(--color-sev-warning);
+}
+.ephemeral-border-error {
+  border-color: var(--color-sev-error);
+}
+
+.pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 1px 6px;
+  font-family: var(--font-mono);
+  font-size: 10.5px;
+  font-weight: 500;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  border-radius: 2px;
+  white-space: nowrap;
+  line-height: 1.4;
+}
diff --git a/apps/vis/web/src/types.ts b/apps/vis/web/src/types.ts
new file mode 100644
index 000000000..1731b202a
--- /dev/null
+++ b/apps/vis/web/src/types.ts
@@ -0,0 +1,359 @@
+// Client-side types mirroring the server API contract.
+// Kept in sync manually — the server owns the source of truth.
+
+export type WireRecordType =
+  // File-header (line 1) and startup baseline (line 2) — vis splices
+  // these back into the timeline so the Wire tab shows every line of
+  // wire.jsonl, including the system_prompt.
+  | 'metadata'
+  | 'session_initialized'
+  | 'turn_begin'
+  | 'turn_end'
+  | 'user_message'
+  | 'tool_result'
+  | 'compaction'
+  | 'system_prompt_changed'
+  | 'tools_changed'
+  | 'system_reminder'
+  | 'notification'
+  // Atomic streaming records (replace assistant_message + tool_call_dispatched).
+  | 'step_begin'
+  | 'step_end'
+  | 'content_part'
+  | 'tool_call'
+  | 'tool_denied'
+  | 'skill_invoked'
+  | 'skill_completed'
+  | 'approval_request'
+  | 'approval_response'
+  | 'team_mail'
+  | 'subagent_spawned'
+  | 'subagent_completed'
+  | 'subagent_failed'
+  | 'ownership_changed'
+  | 'context_edit'
+  | 'context_cleared';
+
+export type WireCategory =
+  | 'conversation'
+  | 'config'
+  | 'lifecycle'
+  | 'subagent'
+  | 'approval'
+  | 'ephemeral'
+  | 'meta'
+  | 'tools';
+
+// Discriminated union — loosely typed so we can dispatch on .type without
+// needing server-synchronized exact interfaces in the client. The server's
+// own `types.ts` has the precise field types.
+export interface VisWireRecordBase {
+  type: WireRecordType;
+  seq: number;
+  time: number;
+  [key: string]: unknown;
+}
+
+export type VisWireRecord = VisWireRecordBase;
+
+export interface WireFileMetadata {
+  type: 'metadata';
+  protocol_version: string;
+  created_at: number;
+  kimi_version?: string;
+  producer?: {
+    kind: 'python' | 'typescript';
+    name: string;
+    version: string;
+  };
+}
+
+// ──────────── Session ────────────
+
+export interface SessionSummary {
+  session_id: string;
+  title: string | null;
+  last_prompt: string | null;
+  created_at: number;
+  updated_at: number;
+  last_turn_time: number | null;
+  model: string | null;
+  permission_mode: string | null;
+  last_exit_code: 'clean' | 'dirty' | null;
+  custom_title: string | null;
+  tags: string[];
+  archived: boolean;
+  workspace_dir: string | null;
+  wire_protocol_version: string | null;
+  wire_record_count: number;
+  archive_count: number;
+  subagent_count: number;
+  health: 'ok' | 'broken' | 'missing_wire';
+}
+
+export interface SessionState {
+  session_id: string;
+  title?: string;
+  isCustomTitle?: boolean;
+  customTitle?: string;
+  lastPrompt?: string;
+  last_prompt?: string;
+  model?: string;
+  last_turn_id?: string;
+  last_turn_time?: number;
+  turn_count?: number;
+  created_at: number;
+  updated_at: number;
+  workspace_dir?: string;
+  auto_approve_actions?: string[];
+  permission_mode?: 'default' | 'acceptEdits' | 'bypassPermissions';
+  thinking_level?: string;
+  custom_title?: string;
+  plan_mode?: boolean;
+  plan_slug?: string;
+  tags?: string[];
+  description?: string;
+  archived?: boolean;
+  color?: string;
+  last_exit_code?: 'clean' | 'dirty';
+  [key: string]: unknown;
+}
+
+export interface SessionDetail {
+  session_id: string;
+  title: string | null;
+  last_prompt: string | null;
+  state: SessionState;
+  subagent_ids: string[];
+  archive_files: string[];
+  tool_result_ids: string[];
+  wire_metadata: WireFileMetadata | null;
+}
+
+// ──────────── Wire ────────────
+
+export interface WireResponse {
+  session_id: string;
+  agent_id: string | null;
+  files_read: string[];
+  health: 'ok' | 'broken';
+  broken_reason?: string;
+  warnings: string[];
+  records: VisWireRecord[];
+}
+
+// ──────────── Context ────────────
+
+export type MessageOrigin =
+  | { kind: 'user' }
+  | { kind: 'assistant' }
+  | { kind: 'tool'; tool_call_id: string }
+  | { kind: 'system_reminder'; seq: number }
+  | { kind: 'notification'; seq: number; notification_id: string; severity: string };
+
+export interface ContentPart {
+  type: 'text' | 'think' | 'image_url' | 'video_url';
+  [key: string]: unknown;
+}
+
+export interface ToolCallEntry {
+  type: 'function';
+  id: string;
+  function: { name: string; arguments: string | null };
+}
+
+export interface AnnotatedMessage {
+  seq: number;
+  message: {
+    role: 'user' | 'assistant' | 'tool';
+    content: ContentPart[];
+    tool_calls: ToolCallEntry[];
+    tool_call_id?: string;
+  };
+  origin: MessageOrigin;
+  is_ephemeral: boolean;
+  out_of_context: boolean;
+  persisted_output_path?: string;
+}
+
+export interface ProjectedStateSummary {
+  model: string | null;
+  system_prompt: string | null;
+  active_tools: string[];
+  last_seq: number;
+  token_count: number;
+  permission_mode: string | null;
+  plan_mode: boolean;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_write_tokens: number;
+}
+
+export interface ContextResponse {
+  session_id: string;
+  agent_id: string | null;
+  annotated_messages: AnnotatedMessage[];
+  projected_state: ProjectedStateSummary;
+}
+
+// ──────────── Subagents ────────────
+
+export interface SubagentNode {
+  agent_id: string;
+  agent_name: string | null;
+  subagent_type: string | null;
+  run_in_background: boolean;
+  parent_agent_id: string | null;
+  depth: number;
+  status: 'running' | 'completed' | 'failed' | 'killed' | 'lost' | 'unknown';
+  success: boolean | null;
+  result_summary: string | null;
+  error: string | null;
+  spawn_seq: number;
+  spawn_time: number;
+  children: SubagentNode[];
+}
+
+export interface SubagentTreeResponse {
+  session_id: string;
+  tree: SubagentNode[];
+}
+
+export interface SubagentMetaResponse {
+  agent_id: string;
+  session_id: string;
+  meta_json: {
+    agent_id: string;
+    subagent_type: string;
+    status: string;
+    description: string;
+    parent_tool_call_id: string;
+    created_at: number;
+    updated_at: number;
+  } | null;
+  spawned_record: {
+    agent_name?: string;
+    parent_tool_call_id: string;
+    parent_agent_id?: string;
+    run_in_background: boolean;
+    seq: number;
+    time: number;
+  } | null;
+  completed_record: {
+    parent_tool_call_id: string;
+    result_summary: string;
+    usage?: {
+      input_tokens: number;
+      output_tokens: number;
+      cache_read_tokens?: number;
+      cache_write_tokens?: number;
+    };
+    seq: number;
+    time: number;
+  } | null;
+  failed_record: {
+    parent_tool_call_id: string;
+    error: string;
+    seq: number;
+    time: number;
+  } | null;
+  depth: number;
+}
+
+export interface ToolResultFileResponse {
+  tool_call_id: string;
+  session_id: string;
+  size_bytes: number;
+  content: string;
+}
+
+export interface ApiError {
+  error: string;
+  code:
+    | 'NOT_FOUND'
+    | 'BAD_REQUEST'
+    | 'UNAUTHORIZED'
+    | 'READ_ERROR'
+    | 'PARSE_ERROR'
+    | 'DELETE_ERROR';
+}
+
+export interface DeleteSessionResponse {
+  session_id: string;
+  deleted: true;
+}
+
+export interface ClearSessionsResponse {
+  deleted_count: number;
+  failed: Array<{ session_id: string; error: string }>;
+}
+
+// ──────────── Category mapping ────────────
+
+export const TYPE_CATEGORY: Record<WireRecordType, WireCategory> = {
+  metadata: 'meta',
+  session_initialized: 'config',
+  turn_begin: 'conversation',
+  turn_end: 'conversation',
+  user_message: 'conversation',
+  tool_result: 'conversation',
+  compaction: 'conversation',
+  system_prompt_changed: 'config',
+  tools_changed: 'config',
+  system_reminder: 'ephemeral',
+  notification: 'meta',
+  step_begin: 'conversation',
+  step_end: 'conversation',
+  content_part: 'conversation',
+  tool_call: 'tools',
+  tool_denied: 'approval',
+  skill_invoked: 'tools',
+  skill_completed: 'tools',
+  approval_request: 'approval',
+  approval_response: 'approval',
+  team_mail: 'meta',
+  subagent_spawned: 'subagent',
+  subagent_completed: 'subagent',
+  subagent_failed: 'subagent',
+  ownership_changed: 'lifecycle',
+  context_edit: 'lifecycle',
+  context_cleared: 'lifecycle',
+};
+
+// Context-effect marker — `true` if the record mutates the live context,
+// `false` if it is telemetry-only, `'conditional'` for records that depend
+// on per-record fields (notification targets, system_reminder delivery, …).
+export const TYPE_CTX_EFFECT: Record<WireRecordType, boolean | 'conditional'> = {
+  // File header — purely informational, not a context event.
+  metadata: false,
+  // Startup baseline — seeds system_prompt / model / active_tools that
+  // the projector uses as the context floor.
+  session_initialized: true,
+  turn_begin: false,
+  turn_end: false,
+  user_message: true,
+  tool_result: true,
+  compaction: true,
+  system_prompt_changed: true,
+  tools_changed: true,
+  system_reminder: 'conditional',
+  notification: 'conditional',
+  // Streaming atoms together rebuild an assistant message → context-affecting.
+  step_begin: true,
+  step_end: false,
+  content_part: true,
+  tool_call: true,
+  tool_denied: false,
+  skill_invoked: false,
+  skill_completed: false,
+  approval_request: false,
+  approval_response: false,
+  team_mail: false,
+  subagent_spawned: false,
+  subagent_completed: false,
+  subagent_failed: false,
+  ownership_changed: false,
+  context_edit: true,
+  context_cleared: true,
+};
diff --git a/apps/vis/web/src/util/time.ts b/apps/vis/web/src/util/time.ts
new file mode 100644
index 000000000..27246cbd6
--- /dev/null
+++ b/apps/vis/web/src/util/time.ts
@@ -0,0 +1,33 @@
+/** Format an epoch-ms timestamp as a short relative string ("2m ago", "3h ago"). */
+export function formatRelativeTime(epochMs: number): string {
+  if (!epochMs || !Number.isFinite(epochMs)) return '—';
+  const diff = Date.now() - epochMs;
+  if (diff < 0) return 'just now';
+  const s = Math.floor(diff / 1000);
+  if (s < 60) return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  if (d < 30) return `${d}d ago`;
+  const mo = Math.floor(d / 30);
+  if (mo < 12) return `${mo}mo ago`;
+  return `${Math.floor(mo / 12)}y ago`;
+}
+
+/** Format an epoch-ms timestamp as ISO-ish local time (YYYY-MM-DD HH:MM:SS). */
+export function formatAbsoluteTime(epochMs: number): string {
+  if (!epochMs || !Number.isFinite(epochMs)) return '—';
+  const d = new Date(epochMs);
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+/** Format an epoch-ms timestamp as HH:MM:SS (wall clock). */
+export function formatWallClock(epochMs: number): string {
+  if (!epochMs || !Number.isFinite(epochMs)) return '--:--:--';
+  const d = new Date(epochMs);
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
diff --git a/apps/vis/web/test/api.test.ts b/apps/vis/web/test/api.test.ts
new file mode 100644
index 000000000..ef71955f3
--- /dev/null
+++ b/apps/vis/web/test/api.test.ts
@@ -0,0 +1,39 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { api } from '../src/api';
+
+describe('vis web api auth token handling', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('scrubs token parameters from the browser URL after persisting the token', async () => {
+    const setItem = vi.fn();
+    const getItem = vi.fn();
+    const replaceState = vi.fn();
+    const location = new URL('http://localhost:3001/?foo=bar&token=secret#token=secret&tab=wire');
+
+    vi.stubGlobal('window', {
+      history: { replaceState },
+      localStorage: { getItem, setItem },
+      location,
+    });
+    const fetchMock = vi.fn(
+      async () =>
+        new Response('[]', {
+          headers: { 'content-type': 'application/json' },
+          status: 200,
+        }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await api.listSessions();
+
+    expect(setItem).toHaveBeenCalledWith('kimi-vis-auth-token', 'secret');
+    expect(fetchMock).toHaveBeenCalledWith('/api/sessions', {
+      headers: { accept: 'application/json', authorization: 'Bearer secret' },
+      method: 'GET',
+    });
+    expect(replaceState).toHaveBeenCalledWith(null, '', 'http://localhost:3001/?foo=bar#tab=wire');
+  });
+});
diff --git a/apps/vis/web/tsconfig.json b/apps/vis/web/tsconfig.json
new file mode 100644
index 000000000..e1ecfcd8a
--- /dev/null
+++ b/apps/vis/web/tsconfig.json
@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": false,
+    "types": ["vite/client"]
+  },
+  "include": ["src"]
+}
diff --git a/apps/vis/web/vite.config.ts b/apps/vis/web/vite.config.ts
new file mode 100644
index 000000000..646a173cb
--- /dev/null
+++ b/apps/vis/web/vite.config.ts
@@ -0,0 +1,22 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  server: {
+    port: 5174,
+    strictPort: true,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:3001',
+        changeOrigin: true,
+      },
+    },
+  },
+  build: {
+    outDir: 'dist',
+    emptyOutDir: true,
+    target: 'es2022',
+  },
+});
diff --git a/build/nix/update-pnpm-deps.sh b/build/nix/update-pnpm-deps.sh
new file mode 100644
index 000000000..de2eb556a
--- /dev/null
+++ b/build/nix/update-pnpm-deps.sh
@@ -0,0 +1,201 @@
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+FLAKE="$ROOT/flake.nix"
+FAKE_HASH="sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
+CACHE_VERSION="v1"
+FETCHER_VERSION="3"
+CACHE_FILE="$ROOT/.git/kimi-code/pnpm-deps-hashes-$CACHE_VERSION.json"
+RESTORE_ORIG_HASH=0
+
+ORIG_HASH="$(grep -E -o 'hash = "sha256-[A-Za-z0-9+/=]+"' "$FLAKE" \
+  | head -n 1 \
+  | sed -E 's/hash = "(.*)"/\1/')"
+if [ -z "$ORIG_HASH" ]; then
+  echo "error: could not find pnpmDeps hash in flake.nix" >&2
+  exit 1
+fi
+
+set_hash() {
+  sed -i.bak -E "s|hash = \"sha256-[A-Za-z0-9+/=]+\"|hash = \"$1\"|" "$FLAKE"
+  rm -f "$FLAKE.bak"
+}
+
+cleanup() {
+  if [ "$RESTORE_ORIG_HASH" = "1" ]; then
+    set_hash "$ORIG_HASH"
+  fi
+}
+trap cleanup EXIT
+trap 'exit 130' INT TERM
+
+hash_stream() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum | sed -E 's/[[:space:]].*$//'
+  else
+    shasum -a 256 | sed -E 's/[[:space:]].*$//'
+  fi
+}
+
+hash_file() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | sed -E 's/[[:space:]].*$//'
+  else
+    shasum -a 256 "$1" | sed -E 's/[[:space:]].*$//'
+  fi
+}
+
+print_file_fingerprint() {
+  path="$1"
+  if [ -f "$path" ]; then
+    printf 'file:%s\n' "$path"
+    hash_file "$path"
+    printf '\n'
+  else
+    printf 'missing:%s\n' "$path"
+  fi
+}
+
+input_fingerprint() {
+  {
+    printf 'cacheVersion=%s\n' "$CACHE_VERSION"
+    printf 'fetcherVersion=%s\n' "$FETCHER_VERSION"
+
+    printf 'file:flake.nix(normalized-pnpmDeps-hash)\n'
+    sed -E 's|hash = "sha256-[A-Za-z0-9+/=]+"|hash = "sha256-<normalized>"|' "$FLAKE"
+    printf '\n'
+
+    for path in \
+      .npmrc \
+      flake.lock \
+      package.json \
+      pnpm-lock.yaml \
+      pnpm-workspace.yaml
+    do
+      print_file_fingerprint "$path"
+    done
+
+    git ls-files --cached --others --exclude-standard -- \
+      '*/package.json' \
+      '.pnpmfile.cjs' \
+      'patches/**' \
+      | sort -u \
+      | while IFS= read -r path; do
+          [ -n "$path" ] || continue
+          [ "$path" = "package.json" ] && continue
+          print_file_fingerprint "$path"
+        done
+  } | hash_stream
+}
+
+read_cached_hash() {
+  [ -f "$CACHE_FILE" ] || return 0
+
+  # shellcheck disable=SC2016
+  node -e '
+const fs = require("node:fs");
+const [file, key] = process.argv.slice(1);
+const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+const entry = parsed[key];
+if (entry && typeof entry.hash === "string") {
+  console.log(entry.hash);
+}
+' "$CACHE_FILE" "$INPUT_KEY"
+}
+
+write_cached_hash() {
+  hash="$1"
+  mkdir -p "$(dirname "$CACHE_FILE")"
+
+  # shellcheck disable=SC2016
+  node -e '
+const fs = require("node:fs");
+const [file, key, hash, createdAt] = process.argv.slice(1);
+let parsed = {};
+try {
+  if (fs.existsSync(file)) {
+    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  }
+} catch {
+  parsed = {};
+}
+parsed[key] = { hash, createdAt };
+fs.writeFileSync(`${file}.tmp`, `${JSON.stringify(parsed, null, 2)}\n`);
+fs.renameSync(`${file}.tmp`, file);
+' "$CACHE_FILE" "$INPUT_KEY" "$hash" "$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+}
+
+echo "==> current pnpmDeps hash: $ORIG_HASH"
+INPUT_KEY="$(input_fingerprint)"
+
+if nix build --no-link '.#kimi-code-pnpm-deps' >/dev/null 2>&1; then
+  write_cached_hash "$ORIG_HASH"
+  echo "==> pnpmDeps hash still valid; cached input fingerprint $INPUT_KEY"
+  exit 0
+fi
+
+echo "==> current hash did not build; checking local pnpmDeps hash cache"
+CACHED_HASH=""
+if ! CACHED_HASH="$(read_cached_hash)"; then
+  echo "warning: ignoring unreadable pnpmDeps hash cache at $CACHE_FILE" >&2
+  CACHED_HASH=""
+fi
+
+if [ -n "$CACHED_HASH" ] && [ "$CACHED_HASH" != "$ORIG_HASH" ]; then
+  echo "==> cache hit for pnpmDeps input: $CACHED_HASH"
+  RESTORE_ORIG_HASH=1
+  set_hash "$CACHED_HASH"
+  if nix build --no-link '.#kimi-code-pnpm-deps' >/dev/null 2>&1; then
+    RESTORE_ORIG_HASH=0
+    write_cached_hash "$CACHED_HASH"
+    echo "==> done. pnpmDeps hash: $ORIG_HASH -> $CACHED_HASH"
+    exit 0
+  fi
+
+  echo "==> cached hash failed verification; falling back to hash discovery"
+  set_hash "$ORIG_HASH"
+  RESTORE_ORIG_HASH=0
+fi
+
+echo "==> patching flake.nix with fakeHash to provoke a mismatch"
+RESTORE_ORIG_HASH=1
+set_hash "$FAKE_HASH"
+
+echo "==> running nix build to discover the real hash"
+BUILD_OUT="$(nix build --no-link --print-build-logs '.#kimi-code-pnpm-deps' 2>&1 || true)"
+
+NEW_HASH="$(printf '%s\n' "$BUILD_OUT" \
+  | grep -E -o 'got:[[:space:]]+sha256-[A-Za-z0-9+/=]+' \
+  | head -n 1 \
+  | sed -E 's/^got:[[:space:]]+//')"
+
+if [ -z "$NEW_HASH" ]; then
+  echo "error: could not extract a new hash from nix build output." >&2
+  echo "----- nix build output -----" >&2
+  printf '%s\n' "$BUILD_OUT" >&2
+  echo "----- end output -----" >&2
+  set_hash "$ORIG_HASH"
+  RESTORE_ORIG_HASH=0
+  exit 1
+fi
+
+set_hash "$NEW_HASH"
+RESTORE_ORIG_HASH=0
+
+echo "==> verifying build with new hash"
+if ! nix build --no-link '.#kimi-code-pnpm-deps'; then
+  echo "error: verification build failed after hash update." >&2
+  echo "       flake.nix was left pointing at $NEW_HASH for inspection." >&2
+  exit 1
+fi
+
+write_cached_hash "$NEW_HASH"
+
+if [ "$NEW_HASH" = "$ORIG_HASH" ]; then
+  echo "==> hash unchanged ($ORIG_HASH); flake.nix already up to date"
+  exit 0
+fi
+
+echo "==> done. pnpmDeps hash: $ORIG_HASH -> $NEW_HASH"
diff --git a/build/raw-text-loader.mjs b/build/raw-text-loader.mjs
new file mode 100644
index 000000000..6946c97b8
--- /dev/null
+++ b/build/raw-text-loader.mjs
@@ -0,0 +1,23 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Node ESM `load` hook: import `.md` / `.yaml` files as raw-string modules.
+ *
+ * This is the runtime counterpart of `build/raw-text-plugin.mjs` (the bundler
+ * plugin). The plugin covers build (tsdown) and test (vitest); this loader
+ * covers source execution — e.g. `tsx`-run dev flows that import `kimi-core`
+ * straight from `src`, where no bundler is involved.
+ */
+export async function load(url, context, nextLoad) {
+  const filePath = url.split('?', 1)[0] ?? url;
+  if (filePath.endsWith('.md') || filePath.endsWith('.yaml')) {
+    const text = await readFile(fileURLToPath(filePath), 'utf-8');
+    return {
+      format: 'module',
+      shortCircuit: true,
+      source: `export default ${JSON.stringify(text)};`,
+    };
+  }
+  return nextLoad(url, context);
+}
diff --git a/build/raw-text-plugin.mjs b/build/raw-text-plugin.mjs
new file mode 100644
index 000000000..fba6eef62
--- /dev/null
+++ b/build/raw-text-plugin.mjs
@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * Bundler plugin that lets `.md` / `.yaml` files be imported as raw strings:
+ *
+ *   import description from './grep.md';
+ *
+ * The file content is inlined into the bundle at build time, so prompt
+ * source files never ship separately in `dist`. Shared by tsdown (build)
+ * and vitest (test) so both resolve these imports identically.
+ */
+export function rawTextPlugin() {
+  return {
+    name: 'raw-text',
+    enforce: 'pre',
+    load(id) {
+      const path = id.split('?', 1)[0] ?? id;
+      if (!path.endsWith('.md') && !path.endsWith('.yaml')) return null;
+      const text = readFileSync(path, 'utf-8');
+      return { code: `export default ${JSON.stringify(text)};`, map: null };
+    },
+  };
+}
diff --git a/build/register-raw-text-loader.mjs b/build/register-raw-text-loader.mjs
new file mode 100644
index 000000000..0c178fc34
--- /dev/null
+++ b/build/register-raw-text-loader.mjs
@@ -0,0 +1,7 @@
+import { register } from 'node:module';
+
+/**
+ * Registers the `.md` / `.yaml` raw-text loader. Pass to Node via `--import`
+ * (alongside tsx) so source-executed code can import these prompt files.
+ */
+register('./raw-text-loader.mjs', import.meta.url);
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 000000000..57a09c39d
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+.vitepress/dist
+.vitepress/cache
diff --git a/docs/.npmrc b/docs/.npmrc
new file mode 100644
index 000000000..bf2e7648b
--- /dev/null
+++ b/docs/.npmrc
@@ -0,0 +1 @@
+shamefully-hoist=true
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
new file mode 100644
index 000000000..ab968c7d0
--- /dev/null
+++ b/docs/.vitepress/config.ts
@@ -0,0 +1,184 @@
+import { defineConfig } from 'vitepress'
+import { withMermaid } from 'vitepress-plugin-mermaid'
+import llmstxt from 'vitepress-plugin-llms'
+
+const rawBase = process.env.VITEPRESS_BASE
+const base = rawBase
+  ? rawBase.startsWith('/')
+    ? rawBase.endsWith('/') ? rawBase : `${rawBase}/`
+    : `/${rawBase}/`
+  : '/'
+
+export default withMermaid(defineConfig({
+  base,
+  title: 'Kimi Code CLI Docs',
+  description: 'Kimi Code CLI Documentation',
+
+  head: [
+    ['link', { rel: 'icon', type: 'image/x-icon', href: `${base}favicon.ico` }],
+    ['meta', { name: 'theme-color', content: '#0a7aff' }],
+  ],
+
+  srcExclude: ['AGENTS.md', 'superpowers/**'],
+
+  locales: {
+    zh: {
+      label: '简体中文',
+      lang: 'zh-CN',
+      link: '/zh/',
+      title: 'Kimi Code CLI 文档',
+      description: 'Kimi Code CLI 用户文档',
+      themeConfig: {
+        nav: [
+          { text: '指南', link: '/zh/guides/getting-started', activeMatch: '/zh/guides/' },
+          { text: '定制化', link: '/zh/customization/mcp', activeMatch: '/zh/customization/' },
+          { text: '配置', link: '/zh/configuration/config-files', activeMatch: '/zh/configuration/' },
+          { text: '参考手册', link: '/zh/reference/kimi-command', activeMatch: '/zh/reference/' },
+          { text: '常见问题', link: '/zh/faq' },
+          { text: '发布说明', link: '/zh/release-notes/changelog', activeMatch: '/zh/release-notes/' },
+        ],
+        sidebar: {
+          '/zh/guides/': [
+            {
+              text: '指南',
+              items: [
+                { text: '开始使用', link: '/zh/guides/getting-started' },
+                { text: '从 kimi-cli 迁移', link: '/zh/guides/migration' },
+                { text: '常见使用案例', link: '/zh/guides/use-cases' },
+                { text: '交互与输入', link: '/zh/guides/interaction' },
+                { text: '会话与上下文', link: '/zh/guides/sessions' },
+              ],
+            },
+          ],
+          '/zh/customization/': [
+            {
+              text: '定制化',
+              items: [
+                { text: 'Model Context Protocol', link: '/zh/customization/mcp' },
+                { text: 'Agent Skills', link: '/zh/customization/skills' },
+                { text: 'Agent 与子 Agent', link: '/zh/customization/agents' },
+                { text: 'Hooks', link: '/zh/customization/hooks' },
+              ],
+            },
+          ],
+          '/zh/configuration/': [
+            {
+              text: '配置',
+              items: [
+                { text: '配置文件', link: '/zh/configuration/config-files' },
+                { text: '平台与模型', link: '/zh/configuration/providers' },
+                { text: '配置覆盖', link: '/zh/configuration/overrides' },
+                { text: '环境变量', link: '/zh/configuration/env-vars' },
+                { text: '数据路径', link: '/zh/configuration/data-locations' },
+              ],
+            },
+          ],
+          '/zh/reference/': [
+            {
+              text: '参考手册',
+              items: [
+                { text: 'kimi 命令', link: '/zh/reference/kimi-command' },
+                { text: '内置工具', link: '/zh/reference/tools' },
+                { text: '斜杠命令', link: '/zh/reference/slash-commands' },
+                { text: '键盘快捷键', link: '/zh/reference/keyboard' },
+              ],
+            },
+          ],
+          '/zh/release-notes/': [
+            {
+              text: '发布说明',
+              items: [
+                { text: '变更记录', link: '/zh/release-notes/changelog' },
+              ],
+            },
+          ],
+        },
+      },
+    },
+    en: {
+      label: 'English',
+      lang: 'en-US',
+      link: '/en/',
+      title: 'Kimi Code CLI Docs',
+      description: 'Kimi Code CLI User Documentation',
+      themeConfig: {
+        nav: [
+          { text: 'Guides', link: '/en/guides/getting-started', activeMatch: '/en/guides/' },
+          { text: 'Customization', link: '/en/customization/mcp', activeMatch: '/en/customization/' },
+          { text: 'Configuration', link: '/en/configuration/config-files', activeMatch: '/en/configuration/' },
+          { text: 'Reference', link: '/en/reference/kimi-command', activeMatch: '/en/reference/' },
+          { text: 'FAQ', link: '/en/faq' },
+          { text: 'Release Notes', link: '/en/release-notes/changelog', activeMatch: '/en/release-notes/' },
+        ],
+        sidebar: {
+          '/en/guides/': [
+            {
+              text: 'Guides',
+              items: [
+                { text: 'Getting Started', link: '/en/guides/getting-started' },
+                { text: 'Migrating from kimi-cli', link: '/en/guides/migration' },
+                { text: 'Common Use Cases', link: '/en/guides/use-cases' },
+                { text: 'Interaction and Input', link: '/en/guides/interaction' },
+                { text: 'Sessions and Context', link: '/en/guides/sessions' },
+              ],
+            },
+          ],
+          '/en/customization/': [
+            {
+              text: 'Customization',
+              items: [
+                { text: 'Model Context Protocol', link: '/en/customization/mcp' },
+                { text: 'Agent Skills', link: '/en/customization/skills' },
+                { text: 'Agents and Subagents', link: '/en/customization/agents' },
+                { text: 'Hooks', link: '/en/customization/hooks' },
+              ],
+            },
+          ],
+          '/en/configuration/': [
+            {
+              text: 'Configuration',
+              items: [
+                { text: 'Config Files', link: '/en/configuration/config-files' },
+                { text: 'Providers and Models', link: '/en/configuration/providers' },
+                { text: 'Config Overrides', link: '/en/configuration/overrides' },
+                { text: 'Environment Variables', link: '/en/configuration/env-vars' },
+                { text: 'Data Locations', link: '/en/configuration/data-locations' },
+              ],
+            },
+          ],
+          '/en/reference/': [
+            {
+              text: 'Reference',
+              items: [
+                { text: 'kimi Command', link: '/en/reference/kimi-command' },
+                { text: 'Built-in Tools', link: '/en/reference/tools' },
+                { text: 'Slash Commands', link: '/en/reference/slash-commands' },
+                { text: 'Keyboard Shortcuts', link: '/en/reference/keyboard' },
+              ],
+            },
+          ],
+          '/en/release-notes/': [
+            {
+              text: 'Release Notes',
+              items: [
+                { text: 'Changelog', link: '/en/release-notes/changelog' },
+              ],
+            },
+          ],
+        },
+      },
+    },
+  },
+
+  themeConfig: {
+    outline: [2, 3],
+    search: { provider: 'local' },
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/MoonshotAI/kimi-code' },
+    ],
+  },
+
+  vite: {
+    plugins: [llmstxt()],
+  },
+}))
diff --git a/docs/.vitepress/theme/Kimi.png b/docs/.vitepress/theme/Kimi.png
new file mode 100644
index 000000000..5b41bb609
Binary files /dev/null and b/docs/.vitepress/theme/Kimi.png differ
diff --git a/docs/.vitepress/theme/components/HomeFeatures.vue b/docs/.vitepress/theme/components/HomeFeatures.vue
new file mode 100644
index 000000000..e98c01e5f
--- /dev/null
+++ b/docs/.vitepress/theme/components/HomeFeatures.vue
@@ -0,0 +1,319 @@
+<script setup lang="ts">
+import { useData, withBase } from 'vitepress'
+import { computed } from 'vue'
+
+const { lang } = useData()
+const isZh = computed(() => lang.value.startsWith('zh'))
+
+interface Highlight {
+  icon: string
+  title: string
+  desc: string
+}
+
+interface Feature {
+  icon: string
+  title: string
+  desc: string
+  href: string
+}
+
+const highlights = computed<Highlight[]>(() => isZh.value
+  ? [
+      {
+        icon: '⚡',
+        title: '极速轻量',
+        desc: '一行命令装好的单文件 CLI，毫秒级启动，无需 Node.js，零环境干扰。',
+      },
+      {
+        icon: '🎬',
+        title: '视频也能输入',
+        desc: '屏幕录像、演示视频拖进对话——画面替你说清需求。',
+      },
+      {
+        icon: '🎨',
+        title: '精致 TUI',
+        desc: '为长时间、专注的 Agent 会话精心打磨的交互界面。',
+      },
+    ]
+  : [
+      {
+        icon: '⚡',
+        title: 'Fast & lightweight',
+        desc: 'Single-binary install with millisecond startup — no Node.js, no PATH gymnastics.',
+      },
+      {
+        icon: '🎬',
+        title: 'Video input',
+        desc: 'Drop a screen recording or demo clip in chat; the agent reads the frames and acts on them.',
+      },
+      {
+        icon: '🎨',
+        title: 'Polished TUI',
+        desc: 'A carefully tuned interface designed for long, focused agent sessions.',
+      },
+    ])
+
+const features = computed<Feature[]>(() => isZh.value
+  ? [
+      {
+        icon: '🧩',
+        title: 'Agent Skills',
+        desc: '把团队的工作流程封装成 Kimi 随时调用的技能，不必每次都重新解释。',
+        href: '/zh/customization/skills',
+      },
+      {
+        icon: '🪝',
+        title: 'Hooks',
+        desc: '在生命周期关键点注入脚本，做格式化、审批、通知或任意自定义逻辑。',
+        href: '/zh/customization/hooks',
+      },
+      {
+        icon: '🤖',
+        title: 'Sub-agents',
+        desc: '并行派发独立任务，每个子 agent 自带上下文，主对话保持清爽。',
+        href: '/zh/customization/agents',
+      },
+      {
+        icon: '🔌',
+        title: 'MCP',
+        desc: '通过 Model Context Protocol 接入任意工具、数据源与企业系统。',
+        href: '/zh/customization/mcp',
+      }
+    ]
+  : [
+      {
+        icon: '🧩',
+        title: 'Agent Skills',
+        desc: "Package your team's workflows into skills Kimi can invoke on demand.",
+        href: '/en/customization/skills',
+      },
+      {
+        icon: '🪝',
+        title: 'Hooks',
+        desc: 'Inject scripts at lifecycle checkpoints — formatting, approvals, notifications, anything.',
+        href: '/en/customization/hooks',
+      },
+      {
+        icon: '🤖',
+        title: 'Sub-agents',
+        desc: 'Dispatch isolated tasks in parallel, each with its own context — main thread stays clean.',
+        href: '/en/customization/agents',
+      },
+      {
+        icon: '🔌',
+        title: 'MCP',
+        desc: 'Plug in any tool, data source, or enterprise system via the Model Context Protocol.',
+        href: '/en/customization/mcp',
+      }
+    ])
+
+const highlightsTitle = computed(() => isZh.value ? '开箱即得' : 'Ready out of the box')
+const highlightsLede = computed(() => isZh.value
+  ? '装好就能用，关键能力默认就绪。'
+  : 'Install once. The essentials are already there.')
+
+const featuresTitle = computed(() => isZh.value ? '按需扩展' : 'Extend it your way')
+const featuresLede = computed(() => isZh.value
+  ? '内置可编程的扩展点，按自己的方式塑造工作流。'
+  : 'Programmable extension points to shape the workflow around you.')
+
+const ctaText = computed(() => isZh.value ? '了解' : 'Learn more')
+</script>
+
+<template>
+  <section class="KimiHome__section KimiHighlights">
+    <h2 class="KimiHome__sectionTitle">{{ highlightsTitle }}</h2>
+    <p class="KimiHome__sectionLede">{{ highlightsLede }}</p>
+    <div class="KimiHighlights__grid">
+      <div
+        v-for="h in highlights"
+        :key="h.title"
+        class="KimiHighlights__card"
+      >
+        <div class="KimiHighlights__icon" aria-hidden="true">{{ h.icon }}</div>
+        <h3 class="KimiHighlights__title">{{ h.title }}</h3>
+        <p class="KimiHighlights__desc">{{ h.desc }}</p>
+      </div>
+    </div>
+  </section>
+
+  <section class="KimiHome__section KimiFeatures">
+    <h2 class="KimiHome__sectionTitle">{{ featuresTitle }}</h2>
+    <p class="KimiHome__sectionLede">{{ featuresLede }}</p>
+    <div class="KimiFeatures__grid">
+      <a
+        v-for="f in features"
+        :key="f.title"
+        class="KimiFeatures__card"
+        :href="withBase(f.href)"
+      >
+        <div class="KimiFeatures__icon" aria-hidden="true">{{ f.icon }}</div>
+        <h3 class="KimiFeatures__title">{{ f.title }}</h3>
+        <p class="KimiFeatures__desc">{{ f.desc }}</p>
+        <span class="KimiFeatures__cta">
+          {{ ctaText }}
+          <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+            <path d="M6 3l5 5-5 5" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+          </svg>
+        </span>
+      </a>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+/* === Highlights (top section: non-clickable product attributes) === */
+.KimiHighlights__grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 16px;
+}
+
+@media (max-width: 720px) {
+  .KimiHighlights__grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+.KimiHighlights__card {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  padding: 22px 22px 24px;
+  border-radius: var(--kimi-radius-card);
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-soft);
+}
+
+.KimiHighlights__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  border-radius: 10px;
+  background: var(--kimi-brand-soft);
+  font-size: 18px;
+  margin-bottom: 14px;
+}
+
+.KimiHighlights__title {
+  font-size: 16px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+  margin: 0 0 6px;
+  color: var(--vp-c-text-1);
+}
+
+.KimiHighlights__desc {
+  font-size: 14px;
+  line-height: 1.55;
+  color: var(--vp-c-text-2);
+  margin: 0;
+}
+
+/* === Features (bottom section: clickable extension points) === */
+.KimiFeatures__grid {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 20px;
+}
+
+@media (max-width: 1024px) {
+  .KimiFeatures__grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+@media (max-width: 640px) {
+  .KimiFeatures__grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+.KimiFeatures__card {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  padding: 28px 24px 26px;
+  border-radius: var(--kimi-radius-card);
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  text-decoration: none;
+  transition: transform var(--kimi-transition), border-color var(--kimi-transition),
+              box-shadow var(--kimi-transition), background var(--kimi-transition);
+  overflow: hidden;
+}
+
+.KimiFeatures__card::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: var(--kimi-brand-gradient-soft);
+  opacity: 0;
+  transition: opacity var(--kimi-transition);
+  pointer-events: none;
+  border-radius: inherit;
+}
+
+.KimiFeatures__card:hover {
+  transform: translateY(-3px);
+  border-color: var(--vp-c-brand-1);
+  box-shadow: var(--vp-shadow-3);
+}
+.KimiFeatures__card:hover::before {
+  opacity: 1;
+}
+
+.KimiFeatures__icon {
+  position: relative;
+  z-index: 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 44px;
+  height: 44px;
+  border-radius: 12px;
+  background: var(--kimi-brand-soft);
+  font-size: 22px;
+  margin-bottom: 18px;
+}
+
+.KimiFeatures__title {
+  position: relative;
+  z-index: 1;
+  font-size: 18px;
+  font-weight: 700;
+  letter-spacing: -0.015em;
+  margin: 0 0 8px;
+  color: var(--vp-c-text-1);
+}
+
+.KimiFeatures__desc {
+  position: relative;
+  z-index: 1;
+  font-size: 14.5px;
+  line-height: 1.6;
+  color: var(--vp-c-text-2);
+  margin: 0 0 20px;
+}
+
+.KimiFeatures__cta {
+  position: relative;
+  z-index: 1;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--vp-c-brand-1);
+  margin-top: auto;
+  transition: transform var(--kimi-transition);
+}
+
+.KimiFeatures__card:hover .KimiFeatures__cta {
+  transform: translateX(3px);
+}
+</style>
diff --git a/docs/.vitepress/theme/components/HomeHero.vue b/docs/.vitepress/theme/components/HomeHero.vue
new file mode 100644
index 000000000..873d18b0f
--- /dev/null
+++ b/docs/.vitepress/theme/components/HomeHero.vue
@@ -0,0 +1,147 @@
+<script setup lang="ts">
+import { useData, withBase } from 'vitepress'
+import { computed } from 'vue'
+import KimiLogo from './KimiLogo.vue'
+
+const { lang } = useData()
+
+const isZh = computed(() => lang.value.startsWith('zh'))
+
+const copy = computed(() => isZh.value
+  ? {
+      titleLead: 'Kimi',
+      titleAccent: 'Code',
+      titleTail: ' CLI',
+      tagline: 'The Starting Point for Next-Gen Agents',
+      primaryText: '开始使用',
+      primaryHref: '/zh/guides/getting-started',
+      secondaryText: '在 GitHub 查看',
+      secondaryHref: 'https://github.com/MoonshotAI/kimi-code',
+    }
+  : {
+      titleLead: 'Kimi',
+      titleAccent: 'Code',
+      titleTail: ' CLI',
+      tagline: 'The Starting Point for Next-Gen Agents',
+      primaryText: 'Get started',
+      primaryHref: '/en/guides/getting-started',
+      secondaryText: 'View on GitHub',
+      secondaryHref: 'https://github.com/MoonshotAI/kimi-code',
+    })
+</script>
+
+<template>
+  <section class="KimiHero">
+    <div class="KimiHero__halo" aria-hidden="true" />
+    <div class="KimiHero__inner">
+      <div class="KimiHero__logo">
+        <KimiLogo :size="64" />
+      </div>
+      <h1 class="KimiHero__title">
+        {{ copy.titleLead }}&nbsp;<span class="KimiHero__accent">{{ copy.titleAccent }}</span>{{ copy.titleTail }}
+      </h1>
+      <p class="KimiHero__tagline">{{ copy.tagline }}</p>
+      <div class="KimiHero__actions">
+        <a class="KimiBtn KimiBtn--primary" :href="withBase(copy.primaryHref)">
+          {{ copy.primaryText }}
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+            <path d="M6 3l5 5-5 5" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+          </svg>
+        </a>
+        <a class="KimiBtn KimiBtn--ghost" :href="copy.secondaryHref" target="_blank" rel="noopener">
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+            <path d="M8 .2C3.58.2 0 3.78 0 8.2c0 3.54 2.3 6.54 5.48 7.6.4.07.55-.17.55-.38l-.01-1.5c-2.23.49-2.7-.95-2.7-.95-.37-.93-.9-1.18-.9-1.18-.73-.5.06-.49.06-.49.81.06 1.24.83 1.24.83.72 1.23 1.88.88 2.34.67.07-.52.28-.88.51-1.08-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.13 0 0 .67-.21 2.2.82a7.65 7.65 0 014 0c1.53-1.03 2.2-.82 2.2-.82.44 1.11.16 1.93.08 2.13.51.56.82 1.28.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.55.74.55 1.49l-.01 2.21c0 .21.15.46.55.38C13.7 14.74 16 11.74 16 8.2 16 3.78 12.42.2 8 .2z" />
+          </svg>
+          {{ copy.secondaryText }}
+        </a>
+      </div>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.KimiHero {
+  position: relative;
+  padding: clamp(72px, 12vw, 140px) 0 clamp(48px, 8vw, 96px);
+  overflow: hidden;
+}
+
+.KimiHero__halo {
+  position: absolute;
+  top: -120px;
+  left: 50%;
+  width: 900px;
+  height: 600px;
+  transform: translateX(-50%);
+  background:
+    radial-gradient(closest-side, rgba(10, 122, 255, 0.22), transparent 70%),
+    radial-gradient(closest-side, rgba(129, 196, 255, 0.20) 30%, transparent 75%);
+  filter: blur(40px);
+  pointer-events: none;
+  z-index: 0;
+  opacity: 0.55;
+}
+:global(.dark) .KimiHero__halo {
+  opacity: 0.85;
+  background:
+    radial-gradient(closest-side, rgba(61, 149, 255, 0.36), transparent 70%),
+    radial-gradient(closest-side, rgba(129, 196, 255, 0.30) 30%, transparent 75%);
+}
+
+.KimiHero__inner {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+}
+
+.KimiHero__logo {
+  margin-bottom: 28px;
+  filter: drop-shadow(0 12px 32px rgba(10, 122, 255, 0.28));
+}
+
+.KimiHero__title {
+  font-size: clamp(40px, 7vw, 84px);
+  font-weight: 700;
+  letter-spacing: -0.035em;
+  line-height: 1.05;
+  margin: 0 0 20px;
+  color: var(--vp-c-text-1);
+  max-width: 18ch;
+}
+
+.KimiHero__accent {
+  background: var(--kimi-brand-gradient);
+  background-clip: text;
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  color: transparent;
+}
+
+.KimiHero__tagline {
+  font-size: clamp(16px, 1.5vw, 20px);
+  line-height: 1.55;
+  color: var(--vp-c-text-2);
+  max-width: 620px;
+  margin: 0 0 40px;
+}
+
+.KimiHero__actions {
+  display: flex;
+  gap: 14px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+
+@media (max-width: 480px) {
+  .KimiHero__actions {
+    width: 100%;
+    flex-direction: column;
+  }
+  .KimiHero__actions .KimiBtn {
+    width: 100%;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/components/HomeLayout.vue b/docs/.vitepress/theme/components/HomeLayout.vue
new file mode 100644
index 000000000..1a1635c20
--- /dev/null
+++ b/docs/.vitepress/theme/components/HomeLayout.vue
@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import DefaultTheme from 'vitepress/theme'
+import { useData } from 'vitepress'
+import HomeHero from './HomeHero.vue'
+import HomeFeatures from './HomeFeatures.vue'
+import HomeQuickStart from './HomeQuickStart.vue'
+
+const { Layout } = DefaultTheme
+const { frontmatter } = useData()
+</script>
+
+<template>
+  <Layout>
+    <template v-if="frontmatter.layout === 'home'" #home-hero-before>
+      <div class="KimiHome">
+        <HomeHero />
+      </div>
+    </template>
+
+    <template v-if="frontmatter.layout === 'home'" #home-features-after>
+      <div class="KimiHome">
+        <HomeQuickStart />
+        <HomeFeatures />
+      </div>
+    </template>
+  </Layout>
+</template>
+
+<style>
+/* Hide the default hero + features rendered by VitePress when our custom home is active.
+   We keep frontmatter.layout: home so VitePress still applies layout-specific behavior. */
+.VPHome > .VPHero {
+  display: none;
+}
+.VPHome > .VPFeatures {
+  display: none;
+}
+</style>
diff --git a/docs/.vitepress/theme/components/HomeQuickStart.vue b/docs/.vitepress/theme/components/HomeQuickStart.vue
new file mode 100644
index 000000000..91c6c821a
--- /dev/null
+++ b/docs/.vitepress/theme/components/HomeQuickStart.vue
@@ -0,0 +1,210 @@
+<script setup lang="ts">
+import { useData, withBase } from 'vitepress'
+import { computed, ref } from 'vue'
+
+const { lang } = useData()
+const isZh = computed(() => lang.value.startsWith('zh'))
+
+const installMacCommand = 'curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash'
+const installWinCommand = 'irm https://code.kimi.com/kimi-code/install.ps1 | iex'
+const runCommand = 'kimi'
+
+const copy = computed(() => isZh.value
+  ? {
+      title: '一行命令开始',
+      lede: '装好之后跑 kimi，立刻在你当前的项目里开聊。',
+      macLabel: 'macOS / Linux',
+      winLabel: 'Windows (PowerShell)',
+      runLabel: '在任意目录运行',
+      copyHint: '复制',
+      copiedHint: '已复制',
+      ctaText: '查看完整安装指南',
+      ctaHref: '/zh/guides/getting-started',
+    }
+  : {
+      title: 'Get started in one line',
+      lede: 'Once installed, run kimi inside any project to start a conversation.',
+      macLabel: 'macOS / Linux',
+      winLabel: 'Windows (PowerShell)',
+      runLabel: 'Run anywhere',
+      copyHint: 'Copy',
+      copiedHint: 'Copied',
+      ctaText: 'Read the full install guide',
+      ctaHref: '/en/guides/getting-started',
+    })
+
+const copiedKey = ref<string | null>(null)
+let copiedTimer: ReturnType<typeof setTimeout> | null = null
+
+function copyText(value: string, key: string) {
+  if (typeof navigator === 'undefined' || !navigator.clipboard) return
+  navigator.clipboard.writeText(value).then(() => {
+    copiedKey.value = key
+    if (copiedTimer) clearTimeout(copiedTimer)
+    copiedTimer = setTimeout(() => { copiedKey.value = null }, 1600)
+  })
+}
+</script>
+
+<template>
+  <section class="KimiHome__section KimiQuick">
+    <h2 class="KimiHome__sectionTitle">{{ copy.title }}</h2>
+    <p class="KimiHome__sectionLede">{{ copy.lede }}</p>
+
+    <div class="KimiQuick__installs">
+      <div class="KimiQuick__block">
+        <div class="KimiQuick__label">{{ copy.macLabel }}</div>
+        <div class="KimiQuick__cmd">
+          <code><span class="KimiQuick__prompt">$</span> {{ installMacCommand }}</code>
+          <button
+            type="button"
+            class="KimiQuick__copy"
+            @click="copyText(installMacCommand, 'mac')"
+            :aria-label="copy.copyHint"
+          >
+            <template v-if="copiedKey === 'mac'">{{ copy.copiedHint }}</template>
+            <template v-else>{{ copy.copyHint }}</template>
+          </button>
+        </div>
+      </div>
+
+      <div class="KimiQuick__block">
+        <div class="KimiQuick__label">{{ copy.winLabel }}</div>
+        <div class="KimiQuick__cmd">
+          <code><span class="KimiQuick__prompt">PS&gt;</span> {{ installWinCommand }}</code>
+          <button
+            type="button"
+            class="KimiQuick__copy"
+            @click="copyText(installWinCommand, 'win')"
+            :aria-label="copy.copyHint"
+          >
+            <template v-if="copiedKey === 'win'">{{ copy.copiedHint }}</template>
+            <template v-else>{{ copy.copyHint }}</template>
+          </button>
+        </div>
+      </div>
+    </div>
+
+    <div class="KimiQuick__block KimiQuick__block--run">
+      <div class="KimiQuick__label">{{ copy.runLabel }}</div>
+      <div class="KimiQuick__cmd">
+        <code><span class="KimiQuick__prompt">$</span> {{ runCommand }}</code>
+        <button
+          type="button"
+          class="KimiQuick__copy"
+          @click="copyText(runCommand, 'run')"
+          :aria-label="copy.copyHint"
+        >
+          <template v-if="copiedKey === 'run'">{{ copy.copiedHint }}</template>
+          <template v-else>{{ copy.copyHint }}</template>
+        </button>
+      </div>
+    </div>
+
+    <a class="KimiQuick__more" :href="withBase(copy.ctaHref)">
+      {{ copy.ctaText }}
+      <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+        <path d="M6 3l5 5-5 5" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+      </svg>
+    </a>
+  </section>
+</template>
+
+<style scoped>
+.KimiQuick__installs {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  margin-bottom: 16px;
+}
+
+.KimiQuick__block {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.KimiQuick__block--run {
+  margin-bottom: 28px;
+}
+
+.KimiQuick__label {
+  font-size: 13px;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  color: var(--vp-c-text-3);
+}
+
+.KimiQuick__cmd {
+  position: relative;
+  display: flex;
+  align-items: center;
+  padding: 18px 22px;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: var(--kimi-radius-code);
+  font-family: var(--vp-font-family-mono);
+  font-size: 14.5px;
+  line-height: 1.4;
+  color: var(--vp-c-text-1);
+  overflow: hidden;
+  transition: border-color var(--kimi-transition), box-shadow var(--kimi-transition);
+}
+.KimiQuick__cmd:hover {
+  border-color: var(--vp-c-brand-1);
+  box-shadow: var(--vp-shadow-2);
+}
+.KimiQuick__cmd code {
+  flex: 1;
+  white-space: pre;
+  overflow-x: auto;
+  background: transparent !important;
+  color: inherit;
+  padding: 0;
+  font-size: inherit;
+  font-family: inherit;
+  border-radius: 0;
+}
+.KimiQuick__prompt {
+  color: var(--vp-c-brand-1);
+  margin-right: 8px;
+  user-select: none;
+  font-weight: 600;
+}
+
+.KimiQuick__copy {
+  flex: none;
+  margin-left: 12px;
+  padding: 6px 12px;
+  font-size: 12px;
+  font-weight: 600;
+  font-family: var(--vp-font-family-base);
+  letter-spacing: 0.01em;
+  color: var(--vp-c-text-2);
+  background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  cursor: pointer;
+  transition: color var(--kimi-transition), border-color var(--kimi-transition), background var(--kimi-transition);
+}
+.KimiQuick__copy:hover {
+  color: var(--vp-c-brand-1);
+  border-color: var(--vp-c-brand-1);
+}
+
+.KimiQuick__more {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 15px;
+  font-weight: 600;
+  color: var(--vp-c-brand-1);
+  text-decoration: none;
+  transition: transform var(--kimi-transition), color var(--kimi-transition);
+}
+.KimiQuick__more:hover {
+  color: var(--vp-c-brand-2);
+  transform: translateX(3px);
+}
+</style>
diff --git a/docs/.vitepress/theme/components/KimiLogo.vue b/docs/.vitepress/theme/components/KimiLogo.vue
new file mode 100644
index 000000000..2afef84d6
--- /dev/null
+++ b/docs/.vitepress/theme/components/KimiLogo.vue
@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import logoUrl from '../Kimi.png'
+
+withDefaults(defineProps<{ size?: number }>(), { size: 56 })
+</script>
+
+<template>
+  <img
+    class="KimiLogo"
+    :src="logoUrl"
+    :width="size"
+    :height="size"
+    alt="Kimi"
+  />
+</template>
+
+<style scoped>
+.KimiLogo {
+  display: block;
+  object-fit: contain;
+}
+</style>
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
new file mode 100644
index 000000000..ceb339acd
--- /dev/null
+++ b/docs/.vitepress/theme/index.ts
@@ -0,0 +1,12 @@
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import HomeLayout from './components/HomeLayout.vue'
+
+import './styles/vars.css'
+import './styles/base.css'
+import './styles/home.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout: HomeLayout,
+} satisfies Theme
diff --git a/docs/.vitepress/theme/styles/base.css b/docs/.vitepress/theme/styles/base.css
new file mode 100644
index 000000000..7a860ca7f
--- /dev/null
+++ b/docs/.vitepress/theme/styles/base.css
@@ -0,0 +1,231 @@
+/**
+ * Base overrides applied to all pages.
+ * Touches links, inline code, code blocks, custom blocks, blockquotes, navbar, sidebar.
+ */
+
+html {
+  font-feature-settings: 'cv11', 'ss01', 'ss03';
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+  font-family: var(--vp-font-family-base);
+}
+
+/* --- Top navbar: blur + remove the hard bottom line --- */
+.VPNav,
+.VPNavBar {
+  background: rgba(255, 255, 255, 0.72) !important;
+  backdrop-filter: saturate(180%) blur(14px);
+  -webkit-backdrop-filter: saturate(180%) blur(14px);
+}
+.dark .VPNav,
+.dark .VPNavBar {
+  background: rgba(13, 17, 23, 0.72) !important;
+}
+.VPNavBar.has-sidebar .content,
+.VPNavBar:not(.home) {
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+
+/* --- Sidebar: brand-tinted active item, slim left accent bar --- */
+.VPSidebarItem.is-active > .item .link .text,
+.VPSidebarItem.is-active > .item > .text {
+  color: var(--vp-c-brand-1);
+  font-weight: 600;
+}
+.VPSidebarItem.is-link.is-active > .item {
+  position: relative;
+}
+.VPSidebarItem.is-link.is-active > .item::before {
+  content: '';
+  position: absolute;
+  left: -14px;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 3px;
+  height: 16px;
+  border-radius: 2px;
+  background: var(--kimi-brand-gradient);
+}
+
+/* --- Headings: tighter tracking, no underline on h2 --- */
+.vp-doc h1,
+.vp-doc h2,
+.vp-doc h3 {
+  letter-spacing: -0.02em;
+}
+.vp-doc h2 {
+  border-top: none;
+  padding-top: 24px;
+  margin-top: 48px;
+}
+
+/* --- Links --- */
+.vp-doc a:not(.header-anchor) {
+  color: var(--vp-c-brand-1);
+  text-decoration: underline;
+  text-decoration-color: transparent;
+  text-underline-offset: 4px;
+  text-decoration-thickness: 2px;
+  transition: text-decoration-color var(--kimi-transition), color var(--kimi-transition);
+  font-weight: 500;
+}
+.vp-doc a:not(.header-anchor):hover {
+  color: var(--vp-c-brand-2);
+  text-decoration-color: currentColor;
+}
+
+/* --- Inline code --- */
+.vp-doc :not(pre) > code {
+  background: var(--kimi-brand-soft);
+  color: var(--vp-c-brand-1);
+  padding: 2px 6px;
+  border-radius: 6px;
+  font-weight: 500;
+  font-size: 0.875em;
+  border: none;
+}
+
+/* Inline code inside headings: drop the chip, keep just the brand-colored monospace word */
+.vp-doc :is(h1, h2, h3, h4, h5, h6) code {
+  background: transparent;
+  padding: 0;
+  border-radius: 0;
+  font-size: 0.9em;
+  font-weight: inherit;
+  color: var(--vp-c-brand-1);
+}
+
+/* --- Code blocks --- */
+.vp-doc div[class*='language-'] {
+  border-radius: var(--kimi-radius-code);
+  background: var(--vp-c-bg-soft);
+  margin: 20px 0;
+  box-shadow: var(--vp-shadow-1);
+}
+.vp-doc div[class*='language-'] pre {
+  padding: 20px 24px;
+}
+.vp-doc div[class*='language-'] code {
+  font-family: var(--vp-font-family-mono);
+  font-size: 13.5px;
+  line-height: 1.7;
+}
+.vp-doc div[class*='language-'] .lang {
+  color: var(--vp-c-text-3);
+  font-size: 12px;
+}
+.vp-doc div[class*='language-'] button.copy {
+  border-radius: 8px;
+}
+
+/* --- Blockquote --- */
+.vp-doc blockquote {
+  border-left: 3px solid var(--vp-c-brand-1);
+  background: var(--kimi-brand-soft);
+  padding: 14px 18px;
+  border-radius: 0 var(--kimi-radius-code) var(--kimi-radius-code) 0;
+  margin: 20px 0;
+}
+.vp-doc blockquote > p {
+  color: var(--vp-c-text-2);
+  margin: 0;
+}
+
+/* --- Custom blocks (tip / warning / danger / info) --- */
+.vp-doc .custom-block {
+  border-radius: var(--kimi-radius-code);
+  border: none;
+  padding: 16px 20px;
+  margin: 20px 0;
+}
+.vp-doc .custom-block .custom-block-title {
+  font-weight: 600;
+  letter-spacing: -0.005em;
+}
+.vp-doc .custom-block.tip {
+  background: rgba(10, 122, 255, 0.08);
+  color: var(--vp-c-text-1);
+}
+.dark .vp-doc .custom-block.tip {
+  background: rgba(61, 149, 255, 0.12);
+}
+.vp-doc .custom-block.warning {
+  background: rgba(234, 179, 8, 0.10);
+  color: var(--vp-c-text-1);
+}
+.vp-doc .custom-block.danger {
+  background: rgba(239, 68, 68, 0.10);
+  color: var(--vp-c-text-1);
+}
+.vp-doc .custom-block.info {
+  background: rgba(148, 163, 184, 0.12);
+  color: var(--vp-c-text-1);
+}
+.vp-doc .custom-block.tip .custom-block-title { color: var(--vp-c-brand-1); }
+.vp-doc .custom-block.warning .custom-block-title { color: #ca8a04; }
+.vp-doc .custom-block.danger .custom-block-title { color: #dc2626; }
+.dark .vp-doc .custom-block.warning .custom-block-title { color: #eab308; }
+.dark .vp-doc .custom-block.danger .custom-block-title { color: #ef4444; }
+
+/* --- Tables --- */
+.vp-doc table {
+  border-radius: var(--kimi-radius-code);
+  overflow: hidden;
+  border-collapse: separate;
+  border-spacing: 0;
+  display: table;
+  width: 100%;
+}
+.vp-doc tr {
+  background: transparent !important;
+  border-top: 1px solid var(--vp-c-divider);
+}
+.vp-doc tr:first-child { border-top: none; }
+.vp-doc th {
+  background: var(--vp-c-bg-soft);
+  font-weight: 600;
+  color: var(--vp-c-text-1);
+}
+
+/* --- Outline / TOC --- */
+.VPDocAsideOutline .outline-link.active,
+.VPDocAsideOutline .outline-link:hover {
+  color: var(--vp-c-brand-1);
+}
+
+/* --- Buttons globally (e.g. hero CTAs) --- */
+.VPButton.brand {
+  background: var(--kimi-brand-gradient) !important;
+  border: none !important;
+  box-shadow: var(--vp-shadow-3);
+  transition: transform var(--kimi-transition), box-shadow var(--kimi-transition);
+}
+.VPButton.brand:hover {
+  transform: translateY(-2px);
+  box-shadow: var(--vp-shadow-4);
+}
+.VPButton.alt {
+  background: transparent !important;
+  border: 1px solid var(--vp-c-divider) !important;
+  color: var(--vp-c-text-1) !important;
+  transition: border-color var(--kimi-transition), transform var(--kimi-transition);
+}
+.VPButton.alt:hover {
+  border-color: var(--vp-c-brand-1) !important;
+  transform: translateY(-2px);
+}
+
+/* --- Hero default frontmatter (used as fallback when custom Home not rendered) --- */
+.VPHero .name,
+.VPHero .text {
+  letter-spacing: -0.03em;
+}
+
+/* --- Footer --- */
+.VPFooter {
+  border-top: 1px solid var(--vp-c-divider);
+  background: transparent;
+}
diff --git a/docs/.vitepress/theme/styles/home.css b/docs/.vitepress/theme/styles/home.css
new file mode 100644
index 000000000..5ee0125b4
--- /dev/null
+++ b/docs/.vitepress/theme/styles/home.css
@@ -0,0 +1,85 @@
+/**
+ * Home-only styles. Scoped CSS in components handles most rules;
+ * shared utilities and layout container live here.
+ */
+
+.KimiHome {
+  --section-px: clamp(20px, 5vw, 64px);
+  --section-py: clamp(28px, 4vw, 56px);
+  position: relative;
+  padding: 0 var(--section-px);
+}
+
+.KimiHome__section {
+  max-width: 1152px;
+  margin: 0 auto;
+  padding: var(--section-py) 0;
+  position: relative;
+}
+
+.KimiHome__sectionTitle {
+  font-size: clamp(28px, 4vw, 40px);
+  font-weight: 700;
+  letter-spacing: -0.03em;
+  margin: 0 0 12px;
+  color: var(--vp-c-text-1);
+}
+
+.KimiHome__sectionLede {
+  font-size: 17px;
+  color: var(--vp-c-text-2);
+  margin: 0 0 40px;
+  max-width: 640px;
+  line-height: 1.6;
+}
+
+.KimiBtn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  height: 48px;
+  padding: 0 22px;
+  border-radius: var(--kimi-radius-button);
+  font-size: 15px;
+  font-weight: 600;
+  letter-spacing: -0.005em;
+  text-decoration: none;
+  transition: transform var(--kimi-transition), box-shadow var(--kimi-transition),
+              border-color var(--kimi-transition), background var(--kimi-transition);
+  white-space: nowrap;
+  cursor: pointer;
+  border: 1px solid transparent;
+}
+.KimiBtn--primary {
+  color: #ffffff;
+  background: var(--kimi-brand-gradient);
+  box-shadow: var(--vp-shadow-3);
+  border: 0;
+}
+.KimiBtn--primary:hover {
+  transform: translateY(-2px);
+  box-shadow: var(--vp-shadow-4);
+  color: #ffffff;
+}
+.KimiBtn--ghost {
+  color: var(--vp-c-text-1);
+  background: transparent;
+  border-color: var(--vp-c-divider);
+}
+.KimiBtn--ghost:hover {
+  border-color: var(--vp-c-brand-1);
+  transform: translateY(-2px);
+  color: var(--vp-c-text-1);
+}
+.KimiBtn--link {
+  color: var(--vp-c-brand-1);
+  height: auto;
+  padding: 0;
+  background: transparent;
+  border: none;
+}
+.KimiBtn--link:hover {
+  color: var(--vp-c-brand-2);
+  transform: translateX(2px);
+}
diff --git a/docs/.vitepress/theme/styles/vars.css b/docs/.vitepress/theme/styles/vars.css
new file mode 100644
index 000000000..4a4114a9c
--- /dev/null
+++ b/docs/.vitepress/theme/styles/vars.css
@@ -0,0 +1,120 @@
+/**
+ * Design tokens for the Kimi Code docs theme.
+ * Light + dark live side by side; VitePress toggles the .dark class on <html>.
+ */
+
+:root {
+  /* Brand palette — cool blue family from design board */
+  --kimi-brand-1: #0a7aff;          /* primary */
+  --kimi-brand-2: #5baeff;           /* mid */
+  --kimi-brand-3: #81c4ff;           /* soft sky */
+  --kimi-brand-deep: #043153;        /* deep navy (anchor for dark surfaces) */
+  --kimi-brand-whisper: #eff8ff;     /* near-white blue (light tints) */
+  --kimi-brand-gradient: linear-gradient(135deg, #0a7aff 0%, #5baeff 60%, #81c4ff 100%);
+  --kimi-brand-gradient-soft: linear-gradient(135deg, rgba(10, 122, 255, 0.14) 0%, rgba(91, 174, 255, 0.12) 60%, rgba(129, 196, 255, 0.10) 100%);
+  --kimi-brand-soft: rgba(10, 122, 255, 0.10);
+  --kimi-brand-soft-strong: rgba(10, 122, 255, 0.16);
+
+  /* Shape */
+  --kimi-radius-card: 16px;
+  --kimi-radius-button: 10px;
+  --kimi-radius-chip: 999px;
+  --kimi-radius-code: 12px;
+  --kimi-transition: 200ms cubic-bezier(0.4, 0, 0.2, 1);
+
+  /* Typography */
+  --vp-font-family-base:
+    'Inter', -apple-system, BlinkMacSystemFont,
+    'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei',
+    'Helvetica Neue', 'Segoe UI', Arial, sans-serif;
+  --vp-font-family-mono:
+    ui-monospace, SFMono-Regular, 'SF Mono',
+    Menlo, Consolas, 'Liberation Mono', 'Courier New', monospace;
+
+  /* Surfaces (light) — clean white + subtle blue-tinted off-white */
+  --vp-c-bg: #ffffff;
+  --vp-c-bg-alt: #f6f9fd;
+  --vp-c-bg-elv: #ffffff;
+  --vp-c-bg-soft: #eff5fc;
+
+  /* Text (light) */
+  --vp-c-text-1: #0b1a30;
+  --vp-c-text-2: #475569;
+  --vp-c-text-3: #94a3b8;
+
+  /* Borders (light) — picked up from palette E1E3E6 */
+  --vp-c-divider: #e1e3e6;
+  --vp-c-gutter: #e1e3e6;
+  --vp-c-border: #e1e3e6;
+
+  /* Brand applied to VitePress vars (light) */
+  --vp-c-brand-1: var(--kimi-brand-1);
+  --vp-c-brand-2: var(--kimi-brand-2);
+  --vp-c-brand-3: #006ae3;          /* hover, slightly deeper than primary */
+  --vp-c-brand-soft: var(--kimi-brand-soft);
+
+  /* Shadows (light) — no negative spread, avoids "kink" at rounded corners */
+  --vp-shadow-1: 0 1px 2px rgba(11, 26, 48, 0.04);
+  --vp-shadow-2: 0 6px 20px rgba(10, 122, 255, 0.15);
+  --vp-shadow-3: 0 10px 28px rgba(10, 122, 255, 0.22);
+  --vp-shadow-4: 0 18px 44px rgba(10, 122, 255, 0.30);
+
+  /* Buttons (light) */
+  --vp-button-brand-bg: var(--kimi-brand-1);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-3);
+  --vp-button-brand-active-bg: var(--vp-c-brand-3);
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-text: #ffffff;
+  --vp-button-brand-hover-text: #ffffff;
+  --vp-button-brand-active-text: #ffffff;
+
+  /* Custom blocks tinting (light) */
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: rgba(10, 122, 255, 0.07);
+  --vp-custom-block-tip-code-bg: rgba(10, 122, 255, 0.10);
+}
+
+.dark {
+  /* Surfaces (dark) — neutral dark with subtle navy undertone */
+  --vp-c-bg: #0a1422;
+  --vp-c-bg-alt: #0f1b2e;
+  --vp-c-bg-elv: #0f1b2e;
+  --vp-c-bg-soft: #15263f;
+
+  /* Text (dark) — avoid pure white */
+  --vp-c-text-1: #e2e8f0;
+  --vp-c-text-2: #94a3b8;
+  --vp-c-text-3: #64748b;
+
+  /* Borders (dark) — navy-leaning to stay in family */
+  --vp-c-divider: #1b2e47;
+  --vp-c-gutter: #1b2e47;
+  --vp-c-border: #1b2e47;
+
+  /* Brand applied (dark) — keep the pure blue family, brightened */
+  --vp-c-brand-1: #3d95ff;
+  --vp-c-brand-2: #81c4ff;
+  --vp-c-brand-3: #5baeff;
+  --vp-c-brand-soft: rgba(61, 149, 255, 0.16);
+
+  /* Softs (dark) */
+  --kimi-brand-soft: rgba(61, 149, 255, 0.16);
+  --kimi-brand-soft-strong: rgba(61, 149, 255, 0.22);
+
+  /* Shadows (dark) — brand-tinted glow, no negative spread */
+  --vp-shadow-1: 0 1px 2px rgba(0, 0, 0, 0.4);
+  --vp-shadow-2: 0 6px 24px rgba(61, 149, 255, 0.22);
+  --vp-shadow-3: 0 10px 32px rgba(61, 149, 255, 0.32);
+  --vp-shadow-4: 0 18px 48px rgba(61, 149, 255, 0.42);
+
+  /* Buttons (dark) */
+  --vp-button-brand-bg: var(--kimi-brand-1);
+  --vp-button-brand-hover-bg: #1f8cff;
+  --vp-button-brand-active-bg: #1f8cff;
+
+  /* Custom blocks tinting (dark) */
+  --vp-custom-block-tip-bg: rgba(61, 149, 255, 0.12);
+  --vp-custom-block-tip-code-bg: rgba(61, 149, 255, 0.16);
+}
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
new file mode 100644
index 000000000..14d574ea6
--- /dev/null
+++ b/docs/AGENTS.md
@@ -0,0 +1,179 @@
+# Documentation Agent Guide
+
+This repository uses VitePress for the documentation site. Most user-facing pages under `docs/en/` and `docs/zh/` are fully written; New or updated content should keep both locales in sync.
+
+## Structure
+
+- Locales live under `docs/en/` and `docs/zh/` with mirrored paths and filenames.
+- Main sections (nav + sidebar) are:
+  - Guides: getting-started, migration, use-cases, interaction, sessions
+  - Customization: mcp, skills, agents, hooks
+  - Configuration: config-files, providers, overrides, env-vars, data-locations
+  - Reference: kimi-command, tools, slash-commands, keyboard
+  - FAQ
+  - Release notes: changelog
+- Navigation and sidebar are defined in `docs/.vitepress/config.ts`. Any new or renamed page must be wired there for both locales.
+
+## Source of truth
+
+- **Changelog page**: The English version (`docs/en/release-notes/changelog.md`) is the source of truth; the Chinese changelog should be translated from it. The changelog is currently generated manually by a skill that syncs from the CLI package's `CHANGELOG.md` after each release.
+- **All other pages**: `docs/en/` and `docs/zh/` are mirrored pairs with the same paths, headings, and section structure. Edit whichever locale you are working in, and update the other locale in the same change.
+
+Keep both locales in sync before release. Machine-assisted translation is fine; review the locale you changed and its mirror for accuracy, terminology, and broken links.
+
+## Authoring workflow
+
+- Each page should keep the section ordering established by surrounding pages. Changelog and FAQ are exceptions until their placeholder content is replaced.
+- For other pages: edit either locale, then update its mirror in the same change.
+
+## Naming conventions
+
+- Filenames are kebab-case and mirror across locales (same slug in `docs/en/` and `docs/zh/`).
+- Use consistent section labels that match the sidebar titles.
+- Use backticks for flags, commands, subcommands, command arguments, file paths, code identifiers, type names, field names, field values, and keyboard shortcuts.
+
+## Wording conventions
+
+- Do not change H1 titles or nav/sidebar labels.
+- English H2+ headings use sentence case (only the first word capitalized unless it is a proper noun). Treat "Wire", "Plan mode", "YOLO mode", and "Thinking mode" as proper nouns; do not treat "agent" as a proper noun.
+- Chinese H2+ headings keep English words in sentence case; preserve proper nouns listed in the term table below.
+- Use `API key` in English and `API 密钥` in Chinese; keep `JSON`, `JSONL`, `OAuth`, `macOS`, `Node.js`, `npm`, `pnpm`, and `TypeScript` as-is.
+- Use straight double quotes with spaces for quoted content: `"被引内容"` (not curly quotes). Add a space before and after the quoted text when adjacent to CJK characters. Use corner brackets `「」` for special terms (e.g., `「工具」`, `「会话」`).
+- Prefer "终端" over "命令行" in Chinese when both are applicable (e.g., "运行在终端中", "终端界面", "终端操作").
+- Use "工具调用" / "tool call", not "工具使用" / "tool use".
+- Use inline code for tool names (e.g., `Read`, `Grep`, `Bash`).
+
+Term mapping (Chinese <-> English, and proper noun handling):
+
+| Chinese | English | Proper noun (zh) | Proper noun (en) |
+| --- | --- | --- | --- |
+| Agent | agent | yes | no |
+| 主 Agent | main agent | yes (Agent) | no |
+| 子 Agent | subagent | yes (Agent) | no |
+| Shell | shell | yes | no |
+| Plan 模式 | Plan mode | yes | yes (Plan mode) |
+| YOLO 模式 | YOLO mode | yes | yes (YOLO mode) |
+| Thinking 模式 | Thinking mode | yes | yes (Thinking mode) |
+| MCP | MCP | yes | yes |
+| Kimi Code CLI | Kimi Code CLI | yes | yes |
+| Agent Skills | Agent Skills | yes | yes |
+| Skill | skill | yes | no |
+| 系统提示词 | system prompt | no | no |
+| 提示词 | prompt | no | no |
+| 会话 | session | no | no |
+| 上下文 | context | no | no |
+| API 密钥 | API key | yes | no |
+| JSON | JSON | yes | yes |
+| JSONL | JSONL | yes | yes |
+| OAuth | OAuth | yes | yes |
+| macOS | macOS | yes | yes |
+| TypeScript | TypeScript | yes | yes |
+| Node.js | Node.js | yes | yes |
+| npm | npm | yes | yes |
+| pnpm | pnpm | yes | yes |
+| kimi | kimi | yes | yes |
+| 审批请求 | approval request | no | no |
+| 斜杠命令 | slash command | no | no |
+| 工具调用 | tool call | no | no |
+| Frontmatter | frontmatter | yes | no |
+| User 消息 | user message | yes (User) | no |
+| Assistant 消息 | assistant message | yes (Assistant) | no |
+| Tool 消息 | tool message | yes (Tool) | no |
+| 轮次 | turn | no | no |
+| 供应商 | provider | no | no |
+| Prompt Flow | Prompt Flow | yes | yes |
+| Diff | diff | yes | no |
+
+## Typography
+
+- **Spacing around mixed content**: Add a space between Chinese characters and English words, numbers, inline code, or links. Exception: no space before full-width punctuation.
+  - ✓ 在 TypeScript 中使用 `class` 关键字
+  - ✗ 在TypeScript中使用`class`关键字
+  - ✓ 详见 [配置文件](./config.md)。
+  - ✗ 详见[配置文件](./config.md)。
+- **Full-width punctuation**: Use full-width punctuation in Chinese text: `，。；：？！（）` not `, . ; : ? ! ( )`.
+- **Keyboard shortcuts**: Use hyphen between modifier and key (`Ctrl-C`, `Ctrl-D`, `Shift-Tab`, `Alt-V`), not plus sign. Exception: literal application output (e.g., the `Press Ctrl+C again to exit` hint produced by the product itself) keeps its exact rendering.
+- **Code block language**: Always specify language for fenced code blocks (e.g., ` ```sh `, ` ```toml `, ` ```json `, ` ```ts `). Exception: natural language examples (user prompts) may omit the language.
+- **Callout titles**: Use short category titles for callout blocks (`::: tip`, `::: warning`, `::: info`, `::: danger`). Put the detailed description in the block content, not the title.
+  - Chinese: use `提示` for tip, `注意` for warning, `说明` for info, `警告` for danger.
+  - English: use no title or short words like `Note` for warning.
+  - ✓ `::: tip 提示` + content starting with the key point
+  - ✓ `::: warning 注意` + content `\`KIMI_CODE_HOME\` 不影响 Skills 的搜索路径。...`
+  - ✗ `::: warning 不影响 Skills` (title too long, should be in content)
+  - ✗ `::: tip Skills 路径独立于 KIMI_CODE_HOME` (title too long)
+- **Version info blocks**: For version change callouts, use `::: info` with a category title (Added/Changed/Removed in English; 新增/变更/移除 in Chinese). The content should be a complete sentence.
+  - ✓ `::: info 新增` + content `新增于 0.2.0。`
+  - ✗ `::: info 新增于 0.2.0` (title too long)
+  - ✓ `::: info Changed` + content `Renamed in 0.2.0. ...`
+  - ✗ `::: info Renamed in 0.2.0` (title too long)
+
+## Writing style
+
+- **Natural narrative**: Organize content like writing an article, guiding readers smoothly through the material.
+- **Avoid fragmentation**: Don't turn every point into a subheading; use paragraph transitions instead.
+- **Global perspective**: "Getting Started" introduces core concepts only; detailed usage belongs in later pages.
+- **Progressive depth**: Guides → Customization → Configuration → Reference, information deepens gradually.
+- **No "next steps"**: VitePress already provides prev/next navigation; don't add manual `::: tip 接下来` blocks at page end.
+
+### Example: good vs bad
+
+Outline prompt:
+
+```
+* Install and upgrade
+  * System requirements: Node.js 24.15.0+, recommend pnpm
+  * Install, upgrade, uninstall steps
+```
+
+**Bad** (mechanical conversion to headings):
+
+```markdown
+## Install and upgrade
+
+### System requirements
+
+- Node.js 24.15.0+
+- Recommend pnpm
+
+### Install
+
+...
+
+### Upgrade
+
+...
+```
+
+**Good** (natural narrative):
+
+```markdown
+## Install and upgrade
+
+Kimi Code CLI requires Node.js 24.15.0 or later. We recommend using pnpm for installation and management.
+
+If you haven't installed pnpm yet, please refer to the pnpm installation docs first. Install Kimi Code CLI:
+
+(code block)
+
+Verify the installation:
+
+(code block)
+
+Upgrade to the latest version:
+
+(code block)
+```
+
+## Build and preview
+
+- Docs are built with VitePress from `docs/`.
+- Common commands (run inside `docs/`):
+  - `npm install`
+  - `npm run dev`
+  - `npm run build`
+  - `npm run preview`
+- The build output is `docs/.vitepress/dist`.
+
+## Changelog syncing
+
+See `sync-changelog` skill for the changelog generation workflow.
diff --git a/docs/en/configuration/config-files.md b/docs/en/configuration/config-files.md
new file mode 100644
index 000000000..9100e9ab0
--- /dev/null
+++ b/docs/en/configuration/config-files.md
@@ -0,0 +1,230 @@
+# Config files
+
+Kimi Code CLI stores its global configuration in a single TOML file that covers API providers, model aliases, agent loop parameters, background tasks, external services, and more. This page describes the location of the config file, its top-level fields, each nested structure, and a complete example.
+
+## Config file location
+
+The default config file is located at `~/.kimi-code/config.toml`. The directory and file are created automatically on first run with restrictive permissions.
+
+If you want to place the data directory elsewhere, set the `KIMI_CODE_HOME` environment variable:
+
+```sh
+export KIMI_CODE_HOME=/path/to/kimi-home
+```
+
+The config file path then becomes `$KIMI_CODE_HOME/config.toml`. Regardless of where the directory lives, the file name is always `config.toml`.
+
+::: tip
+TOML field names always use snake_case (for example, `default_model`, `max_context_size`). If a key contains `.`, you must use a quoted TOML key; otherwise TOML will treat `.` as a nested table separator.
+:::
+
+## Top-level fields
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `default_model` | `string` | — | Default model alias; must be defined in `models` |
+| `default_thinking` | `boolean` | `false` | Initial value of the Thinking toggle for new sessions; can be flipped from the model menu inside a session. Even when this is `true`, setting `[thinking].mode = "off"` will still force Thinking off. See [`thinking`](#thinking) below |
+| `default_permission_mode` | `string` | `manual` | Default permission mode for new sessions; one of `manual`, `auto`, `yolo` |
+| `default_plan_mode` | `boolean` | `false` | Whether new sessions start in Plan mode by default; omitting it is equivalent to `false` |
+| `merge_all_available_skills` | `boolean` | `true` | Whether to merge Agent Skills from all available directories |
+| `extra_skill_dirs` | `array<string>` | — | Extra skill search directories, layered on top of the default directories |
+| `telemetry` | `boolean` | `true` | Whether anonymous telemetry is enabled; only disabled when explicitly set to `false` |
+| `providers` | `table` | `{}` | API provider table; see below |
+| `models` | `table` | — | Model alias table; see below |
+| `thinking` | `table` | — | Default parameters for Thinking mode |
+| `loop_control` | `table` | — | Agent loop control parameters |
+| `background` | `table` | — | Background task runtime parameters |
+| `services` | `table` | — | Built-in external service configuration |
+| `permission` | `table` | — | Permission rule configuration; see below |
+| `hooks` | `array<table>` | — | Lifecycle hook configuration. See [Hooks](../customization/hooks.md) |
+
+## Complete example
+
+```toml
+default_model = "kimi-code/kimi-for-coding"
+default_thinking = true
+default_permission_mode = "manual"
+default_plan_mode = false
+merge_all_available_skills = true
+telemetry = true
+
+[providers."managed:kimi-code"]
+type = "kimi"
+base_url = "https://api.kimi.com/coding/v1"
+api_key = ""
+
+[models."kimi-code/kimi-for-coding"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+max_context_size = 262144
+
+[thinking]
+mode = "auto"
+
+[loop_control]
+max_steps_per_turn = 1000
+max_retries_per_step = 3
+reserved_context_size = 50000
+
+[background]
+max_running_tasks = 4
+keep_alive_on_exit = false
+agent_task_timeout_s = 900
+
+[[permission.rules]]
+decision = "allow"
+pattern = "Read"
+
+[[permission.rules]]
+decision = "deny"
+pattern = "Bash(rm -rf*)"
+
+[[hooks]]
+event = "PreToolUse"
+matcher = "Bash"
+command = "node ~/.kimi-code/hooks/check-bash.mjs"
+timeout = 5
+```
+
+## `providers`
+
+Each entry in the `providers` table defines the connection info for one API provider, keyed by a unique name.
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `type` | `string` | Yes | Provider type; one of `anthropic`, `openai`, `kimi`, `google-genai`, `openai_responses`, `vertexai` |
+| `api_key` | `string` | No | API key |
+| `base_url` | `string` | No | API base URL |
+| `oauth` | `table` | No | OAuth credential reference; see below |
+| `env` | `table<string, string>` | No | A configuration sub-table keyed by provider-specific names (such as `KIMI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_CLOUD_PROJECT`), used as fallback values for `api_key` / `base_url` and related fields. This is just a sub-table inside the config file — **it is not written into your shell environment** — and is consulted only when the corresponding field on `[providers.<name>]` is unset |
+| `custom_headers` | `table<string, string>` | No | Custom HTTP headers attached to each request |
+
+OAuth credential reference structure:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `storage` | `string` | Yes | Credential storage location; currently only `file` is supported |
+| `key` | `string` | Yes | Unique identifier of the credential entry |
+
+```toml
+[providers.openai]
+type = "openai"
+base_url = "https://api.openai.com/v1"
+api_key = "sk-xxx"
+custom_headers = { "X-Custom-Header" = "value" }
+```
+
+## `models`
+
+Each entry in the `models` table defines a model alias, keyed by a unique name.
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `provider` | `string` | Yes | Name of the provider to use; must be defined in `providers` |
+| `model` | `string` | Yes | Model identifier used when calling the API |
+| `max_context_size` | `integer` | Yes | Maximum context length in tokens; must be at least 1 |
+| `max_output_size` | `integer` | No | Per-request output budget cap (`max_tokens` on the wire). Only the `anthropic` provider currently honors it. When the alias resolves to a known Claude family, the value is clamped to that model's documented ceiling to avoid exceeding the server-side limit. Omit to use the per-model default — see [`providers.md`](./providers.md#anthropic). |
+| `capabilities` | `array<string>` | No | Capability tags to add explicitly, for example `thinking`, `image_in`, `video_in`, `audio_in`, `tool_use` |
+| `display_name` | `string` | No | Name shown in the UI; falls back to `model` when unset |
+
+`capabilities` is unioned with the capabilities that the provider capability registry matches by model-name prefix — entries can only be added, never removed. You usually do not need to set this by hand; reach for it only when the model is not covered by the registry, or when you want to force-enable a particular capability.
+
+If a model alias contains `.`, use a quoted key:
+
+```toml
+[models."gpt-4.1"]
+provider = "openai"
+model = "gpt-4.1"
+max_context_size = 1047576
+```
+
+## `thinking`
+
+`thinking` controls the default behavior of Thinking mode. Even when the top-level `default_thinking = true`, setting `mode` to `"off"` will still force Thinking off.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `mode` | `string` | — | Trigger policy; one of `auto`, `on`, `off`. `"off"` forces Thinking off; any other value or omission does not disable it, and the effective behavior is decided together by the per-session Thinking toggle and `effort` |
+| `effort` | `string` | `high` | Default effort level used when Thinking is on; one of `low`, `medium`, `high`, `xhigh`, `max`. The levels actually available depend on the provider |
+
+## `loop_control`
+
+`loop_control` governs the step count, retries, and context compaction threshold of the agent execution loop.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `max_steps_per_turn` | `integer` | `1000` | Maximum number of steps per turn |
+| `max_retries_per_step` | `integer` | `3` | Maximum retries per step |
+| `reserved_context_size` | `integer` | — | Number of tokens reserved for response generation; compaction is triggered when the context approaches this threshold |
+
+
+
+## `background`
+
+`background` controls the runtime limits for background tasks. Background tasks are launched through the `Bash` tool or the `Agent` tool's `run_in_background=true` parameter.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `max_running_tasks` | `integer` | — | Maximum number of background tasks running concurrently |
+| `keep_alive_on_exit` | `boolean` | `true` | Whether to keep still-running background tasks when the session closes. Set to `false` to request stopping background tasks when `kimi -p` finishes and exits, when an SDK session closes, or when a harness closes |
+| `agent_task_timeout_s` | `integer` | — | Maximum runtime in seconds for background agent tasks |
+
+`keep_alive_on_exit` can be overridden by the `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` environment variable; the environment variable has higher priority than `config.toml`. The schema also reserves `kill_grace_period_ms` and `print_wait_ceiling_s`; these fields currently pass schema validation only and are not read by the CLI runtime.
+
+## `services`
+
+`services` configures the built-in external services Kimi Code CLI calls. Only the two fixed keys `moonshot_search` (web search) and `moonshot_fetch` (web fetch) are recognized; other keys are ignored. Both entries share the same fields:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `base_url` | `string` | No | Service API URL |
+| `api_key` | `string` | No | API key |
+| `oauth` | `table` | No | OAuth credential reference, same structure as `providers.*.oauth` |
+| `custom_headers` | `table<string, string>` | No | Custom HTTP headers attached to each request |
+
+```toml
+[services.moonshot_search]
+base_url = "https://api.moonshot.cn/v1/search"
+api_key = "sk-xxx"
+
+[services.moonshot_fetch]
+base_url = "https://api.moonshot.cn/v1/fetch"
+api_key = "sk-xxx"
+```
+
+## `permission`
+
+`permission` configures the initial permission rules loaded when a session starts, controlling the default approval behavior for tool calls. The default permission mode for new sessions is controlled by the top-level `default_permission_mode` field; an explicit startup permission mode, such as the CLI's `--yolo` flag, overrides that default.
+
+Rules are written as a `[[permission.rules]]` array of tables, where each rule contains the following fields:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `decision` | `string` | Yes | Decision result; one of `allow`, `deny`, `ask` |
+| `scope` | `string` | No | Rule scope; one of `turn-override`, `session-runtime`, `project`, `user`; defaults to `user` |
+| `pattern` | `string` | Yes | Match pattern in the form `ToolName` or `ToolName(arg-pattern)`. `ToolName` must match the runtime tool name exactly — built-in tools are `Read`, `Write`, `Edit`, `Bash`, `Grep`, and so on (see [Built-in tools](../reference/tools.md)) |
+| `reason` | `string` | No | Rule description for debugging or auditing |
+
+Example:
+
+```toml
+[[permission.rules]]
+decision = "allow"
+pattern = "Read"
+
+[[permission.rules]]
+decision = "allow"
+pattern = "Grep"
+
+[[permission.rules]]
+decision = "deny"
+pattern = "Bash(rm -rf*)"
+
+[[permission.rules]]
+decision = "ask"
+pattern = "Bash"
+```
+
+::: tip
+MCP server declarations are configured in `~/.kimi-code/mcp.json` or the project-local `.kimi-code/mcp.json`, not in `config.toml`. The interactive configuration entry point is `/mcp-config`; see [Model Context Protocol](../customization/mcp.md).
+:::
diff --git a/docs/en/configuration/data-locations.md b/docs/en/configuration/data-locations.md
new file mode 100644
index 000000000..2d081d6ac
--- /dev/null
+++ b/docs/en/configuration/data-locations.md
@@ -0,0 +1,131 @@
+# Data Locations
+
+Kimi Code CLI stores its runtime data centrally under the `~/.kimi-code/` directory in the user's home folder. This page describes where each type of data lives, what it is for, and how to customize or clean it up.
+
+## Data root
+
+The default data root is `~/.kimi-code/`. The `~` is resolved by Node.js's `os.homedir()`, so the actual path differs slightly across platforms: on macOS it is `/Users/<name>/.kimi-code`, on Linux `/home/<name>/.kimi-code`, and on Windows `C:\Users\<name>\.kimi-code`.
+
+You can override it to any path with the `KIMI_CODE_HOME` environment variable:
+
+```sh
+export KIMI_CODE_HOME="$HOME/.config/kimi-code"
+```
+
+Once set, runtime data such as the config, sessions, logs, input history, update cache, and OAuth credentials lands under that path. For the full reference on `KIMI_CODE_HOME` and other environment variables, see [Environment variables](./env-vars.md).
+
+::: tip Exceptions
+The **built-in tool cache** (such as the auto-downloaded ripgrep binary) does not follow `KIMI_CODE_HOME`. It uses `KIMI_CODE_CACHE_DIR`, falling back to a platform cache directory — `~/Library/Caches/kimi-code` on macOS, `$XDG_CACHE_HOME/kimi-code` (default `~/.cache/kimi-code`) on Linux, and `%LOCALAPPDATA%\kimi-code` on Windows.
+
+User-level Agent Skills search directories live at `~/.kimi-code/skills` and `~/.agents/skills`; project-level Skills live under the working directory at `.kimi-code/skills` and `.agents/skills`. See [Agent Skills](../customization/skills.md) for details.
+:::
+
+## Directory layout
+
+A typical layout under the data root looks like:
+
+```
+$KIMI_CODE_HOME  (default ~/.kimi-code)
+├── config.toml             # User config
+├── mcp.json                # User-level MCP server declarations (optional)
+├── session_index.jsonl     # Session index
+├── credentials/            # OAuth credential root (directory 0o700, files 0o600)
+│   ├── <name>.json         # Hosted Kimi / Open Platform provider OAuth credentials
+│   └── mcp/                # MCP server OAuth credentials
+│       └── <key>-<suffix>.json
+├── sessions/               # Session data
+│   └── <workDirKey>/
+│       └── <sessionId>/
+│           ├── state.json
+│           ├── logs/
+│           │   └── kimi-code.log
+│           ├── tasks/          # Background task persistence
+│           │   ├── <task_id>.json
+│           │   └── <task_id>/
+│           │       └── output.log
+│           └── agents/
+│               ├── main/
+│               │   ├── wire.jsonl
+│               │   └── plans/  # Plan mode plan files
+│               └── agent-0/
+│                   └── wire.jsonl
+├── bin/
+│   └── rg                  # ripgrep cache (rg.exe on Windows)
+├── logs/                   # Global diagnostic logs
+│   └── kimi-code.log
+├── updates/
+│   └── latest.json         # Update check status
+└── user-history/
+    └── <md5(workDir)>.jsonl
+```
+
+::: tip
+The tree above shows a typical layout under the default data root (`~/.kimi-code/`). The paths for Agent Skills and the built-in tool cache have some special cases — see the "Exceptions" note above.
+:::
+
+## Config files
+
+`config.toml` is Kimi Code CLI's main config file, holding user-level settings such as providers, models, and loop control. See [Config files](./config-files.md) for details.
+
+`mcp.json` holds user-level MCP server declarations and is merged with the project-local `.kimi-code/mcp.json` at load time. The fields are the same as the project-level file; see [MCP](../customization/mcp.md) for details.
+
+OAuth credentials are stored as files under the `credentials/` subdirectory of the data root. The parent directory uses mode `0o700` and each credential file uses mode `0o600`, readable and writable only by the current user. There are two sub-locations:
+
+- **Hosted Kimi / Open Platform provider OAuth credentials** live at `credentials/<name>.json`, for example `~/.kimi-code/credentials/managed:kimi-code.json`.
+- **MCP server OAuth credentials** live under the `credentials/mcp/` subdirectory, with file names generated from the server key, for example `credentials/mcp/<key>-<suffix>.json`.
+
+Writes follow a `tmp → fsync → rename` atomic flow: strictly atomic on POSIX, best-effort on Windows.
+
+## Session data
+
+Session-related data is grouped under `sessions/`, with a top-level `session_index.jsonl` maintaining a JSONL index: one record per line containing the three fields `sessionId`, `sessionDir`, and `workDir`. Entries are appended when a session is created. When the index is loaded, each entry is validated to ensure `sessionDir` still lives under `sessions/` and that its last path component equals `sessionId`, preventing external tampering from pointing entries to illegal paths.
+
+Each session directory has a path like `sessions/<workDirKey>/<sessionId>/`, where `workDirKey` is a bucket name encoded from the working directory in the format `wd_<slug>_<first-12-chars-of-sha256>` (for example, `wd_myproject_a3f8c1d20e9b`), and `sessionId` is the session's unique identifier. The full path under `sessions/`, including each `<workDirKey>/` bucket, is created with mode `0o700` and accessible only by the current user.
+
+The internal structure of a session directory includes:
+
+- `state.json`: session title, `lastPrompt`, `createdAt`, `updatedAt`, `isCustomTitle`, `forkedFrom`, and metadata for each agent.
+- `agents/main/wire.jsonl`: the Wire event stream of the main agent, used for replay and resumption. `main` is the fixed id of the main agent.
+- `agents/main/plans/`: plan files written by the main agent in Plan mode, named `<id>.md` by plan id.
+- `agents/agent-0/`, `agents/agent-1/`, etc.: subagent instance directories, each with its own `wire.jsonl`. Subagent ids are generated by a per-session incrementing counter (`agent-` followed by an integer starting from 0).
+- `logs/kimi-code.log`: the diagnostic log for this session. It only appears after a recorded diagnostic event; an ordinary conversation may not create this file.
+- `tasks/`: background task persistence directory. Each task stores its metadata (status, pid, exit code, etc.) in `tasks/<task_id>.json`, with stdout and stderr written to `tasks/<task_id>/output.log`. Task ids use a `bash-` or `agent-` prefix followed by 8 random alphanumeric characters (for example, `bash-a1b2c3d4`).
+
+`sessionId` is restricted to `[A-Za-z0-9._-]+` and cannot be `.` or `..`, preventing path injection. The session list is sorted by `updatedAt` in descending order, where `updatedAt` is the maximum mtime of the directory and its key files. See [Sessions](../guides/sessions.md) for details.
+
+## Built-in tool cache
+
+The first time Kimi Code CLI needs ripgrep, it downloads and caches it automatically. During the download, the archive is written to the system temporary directory and verified by SHA-256 before extraction; the binary is then installed directly to `bin/rg` under the data root (or `bin/rg.exe` on Windows) and marked `0o755` so it can be executed. Subsequent runs under the same data root reuse it with no further download. If `rg` is already on the system `PATH`, the system version takes precedence; deleting `bin/` triggers a redownload the next time it is needed.
+
+## Logs and update state
+
+The top-level `logs/kimi-code.log` is the global diagnostic log. It mainly records issues that do not belong to a single session, such as startup, login, and export failures. A single session's diagnostic log lives at `<sessionDir>/logs/kimi-code.log`.
+
+When filing a bug report, prefer `kimi export` for the relevant session (see [The kimi command](../reference/kimi-command.md) for details). If a session log exists, it is included in the export by default. The global diagnostic log is also bundled by default; because it may contain events from other sessions or projects, use `--no-include-global-log` when you do not want to share it.
+
+`updates/latest.json` records the version update status detected via npm and is maintained automatically by the CLI — there is usually no need to edit it by hand.
+
+## Input history
+
+Command input history from the terminal is saved per working directory. Each working directory corresponds to one file, at `user-history/<md5(workDir)>.jsonl`, where the file name is the MD5 hash of the working directory string (UTF-8 encoded). The file format is JSONL, with one history record per line.
+
+Input history is used to browse and search previously entered prompts in the terminal interface.
+
+## Cleaning up data
+
+Deleting the data root directory (default `~/.kimi-code/`, or the path specified by `KIMI_CODE_HOME`) wipes all of Kimi Code CLI's runtime data, including config, sessions, logs, input history, and the built-in tool cache.
+
+To clean up only part of the data:
+
+| Goal | Action |
+| --- | --- |
+| Reset config | Delete `~/.kimi-code/config.toml` |
+| Clear all sessions | Delete `~/.kimi-code/sessions/` and `~/.kimi-code/session_index.jsonl` |
+| Clear diagnostic logs | Delete the `~/.kimi-code/logs/` directory |
+| Clear input history | Delete the `~/.kimi-code/user-history/` directory |
+| Reset update check state | Delete `~/.kimi-code/updates/latest.json` |
+| Force a ripgrep redownload | Delete the `~/.kimi-code/bin/` directory |
+| Clear hosted Kimi / Open Platform OAuth login state | Run `/logout` (clears only the current provider's OAuth), or delete the corresponding `~/.kimi-code/credentials/<name>.json` |
+| Clear MCP server OAuth login state | Delete the `~/.kimi-code/credentials/mcp/` directory; `/logout` **does not** clear MCP OAuth credentials |
+| Remove user-level MCP declarations | Delete `~/.kimi-code/mcp.json` |
+| Clear user-level Skills | Delete the `~/.kimi-code/skills/` directory |
diff --git a/docs/en/configuration/env-vars.md b/docs/en/configuration/env-vars.md
new file mode 100644
index 000000000..78a59591e
--- /dev/null
+++ b/docs/en/configuration/env-vars.md
@@ -0,0 +1,124 @@
+# Environment variables
+
+Kimi Code CLI uses environment variables to override default paths, switch OAuth endpoints, and adjust runtime behavior. Most variables are read when the `kimi` process starts up; a few (such as the telemetry switch, the OAuth lock, and diagnostic logging) are read when the relevant subsystem initializes. Kimi's own variables use the `KIMI_*` prefix; in addition, the CLI also reads a number of standard system variables.
+
+::: warning Note
+**Provider credentials are not in this list**: key variables such as `KIMI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GOOGLE_API_KEY` are **not** read automatically from `process.env`. They must be written into the `[providers.<name>]` section of `config.toml` (as `api_key` / `base_url`) or into the `[providers.<name>.env]` subtable; merely `export`ing them in your shell will not give a provider credentials automatically. See [Configuration overrides](./overrides.md#provider-credentials) and [Providers](./providers.md) for details.
+:::
+
+## Core paths
+
+`KIMI_CODE_HOME` overrides Kimi Code CLI's data root directory, defaulting to `~/.kimi-code`. The CLI's own application data, `kimi-core`'s config, the ripgrep cache, and OAuth credentials all land under this directory.
+
+```sh
+export KIMI_CODE_HOME="/path/to/custom/kimi-code"
+```
+
+For details on the data layout, see [Data locations](./data-locations.md).
+
+::: warning Note
+Make sure the directory is writable once you set it. Multiple `kimi` instances that share the same `KIMI_CODE_HOME` will share both the config and credential files.
+:::
+
+## Provider credential key names
+
+The following key names appear in the `[providers.<name>.env]` subtable of `config.toml`, where they serve as fallback sources for the provider's `api_key` / `base_url`. **The main `kimi` process does not read them directly from `process.env`**; only the values keyed under a `[providers.<name>.env]` subtable are recognized by the provider clients. See [Configuration overrides: provider credentials](./overrides.md#provider-credentials) for the full resolution order.
+
+| Key name | Applicable provider | Purpose | Default |
+| --- | --- | --- | --- |
+| `KIMI_API_KEY` | Kimi / Moonshot | API key | None |
+| `KIMI_BASE_URL` | Kimi / Moonshot | API base URL | `https://api.moonshot.ai/v1` |
+| `ANTHROPIC_API_KEY` | Anthropic | API key | None |
+| `ANTHROPIC_BASE_URL` | Anthropic | API base URL | Follows the Anthropic SDK default |
+| `OPENAI_API_KEY` | OpenAI (used by both `openai` and `openai_responses`) | API key | None |
+| `OPENAI_BASE_URL` | OpenAI (used by both `openai` and `openai_responses`) | API base URL | `https://api.openai.com/v1` |
+| `GOOGLE_API_KEY` | Google GenAI, Vertex AI (as a fallback for `VERTEXAI_API_KEY`) | API key | None |
+| `VERTEXAI_API_KEY` | Vertex AI | API key (when not using ADC) | None |
+| `GOOGLE_CLOUD_PROJECT` | Vertex AI | GCP project ID | None |
+| `GOOGLE_CLOUD_LOCATION` | Vertex AI | GCP region | None |
+
+For example, to pre-populate Kimi credentials in `config.toml`:
+
+```toml
+[providers.kimi.env]
+KIMI_API_KEY = "sk-xxx"
+KIMI_BASE_URL = "https://api.moonshot.ai/v1"
+```
+
+::: warning Note
+`GOOGLE_APPLICATION_CREDENTIALS` (the path to a service-account JSON file) is read by the Google SDK itself from the shell environment, making it the **only** key in this group that goes through a system environment variable. It follows Google Cloud's standard ADC flow, and the CLI is not involved in resolving it. Every other key only takes effect when written into a `[providers.<name>.env]` subtable.
+:::
+
+For the full description of provider types and fields, see [Providers](./providers.md).
+
+## OAuth and the hosted service
+
+The OAuth flow connects to Kimi's official authentication and hosted endpoints by default. The variables below can point them at a self-hosted or test environment.
+
+| Environment variable | Purpose | Default |
+| --- | --- | --- |
+| `KIMI_CODE_OAUTH_HOST` | OAuth authentication host; takes the highest precedence | — (falls back to `KIMI_OAUTH_HOST`, then to the hardcoded default below) |
+| `KIMI_OAUTH_HOST` | OAuth authentication host; used as a fallback for `KIMI_CODE_OAUTH_HOST` | — (falls back to the hardcoded default below) |
+| `KIMI_CODE_BASE_URL` | Base URL of the hosted Kimi API, used for API calls after OAuth login | `https://api.kimi.com/coding/v1` |
+
+When neither `KIMI_CODE_OAUTH_HOST` nor `KIMI_OAUTH_HOST` is set, the OAuth authentication host uses the hardcoded constant `https://auth.kimi.com`.
+
+::: warning Note
+`KIMI_CODE_BASE_URL` and the `KIMI_BASE_URL` from the previous section are two different variables: the former targets the OAuth-logged-in hosted service and defaults to `kimi.com`; the latter targets providers that use a Kimi API key directly and defaults to `moonshot.ai`. Distinguish them by use case.
+:::
+
+## Runtime switches
+
+| Environment variable | Purpose | Valid values / Default |
+| --- | --- | --- |
+| `KIMI_DISABLE_TELEMETRY` | Disable telemetry reporting | `1`, `true`, `t`, `yes`, `y` (case-insensitive) |
+| `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` | Override `[background].keep_alive_on_exit`, controlling whether still-running background tasks are kept when the session closes | True values: `1`, `true`, `yes`, `on`; false values: `0`, `false`, `no`, `off`; when unset, reads `config.toml`, then falls back to `true` |
+| `KIMI_SHELL_PATH` | Override the absolute path to Git Bash (`bash.exe`) on Windows; only needed when auto-detection fails on Windows | None |
+| `KIMI_MODEL_MAX_COMPLETION_TOKENS` | Desired budget for `max_completion_tokens` in a single-step LLM request (the actual value is further clamped by the context window and input size); set to `0` or a negative value to disable clamping entirely. **Currently effective only for providers of type `kimi`**; for Anthropic and other providers, use `[models.<alias>].max_output_size` instead (see [Config files](./config-files.md#models)) | Defaults to 32000, influenced by `loop_control.reserved_context_size` |
+
+For example, to disable telemetry on a shared host:
+
+```sh
+export KIMI_DISABLE_TELEMETRY="1"
+```
+
+`KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` has higher priority than `config.toml`. For example, running `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT=0 kimi -p "..."` temporarily requests stopping background tasks before this process exits, even if the config file sets `keep_alive_on_exit = true`.
+## Diagnostic logging
+
+The variables below control `kimi`'s diagnostic logs. Logs are written to two locations: the global diagnostic log at `$KIMI_CODE_HOME/logs/kimi-code.log`, and each session's own diagnostic log at `<sessionDir>/logs/kimi-code.log` (see [Data locations](./data-locations.md#logs-and-update-state) for path details). All of these variables are read only once at process startup.
+
+| Environment variable | Purpose | Default |
+| --- | --- | --- |
+| `KIMI_LOG_LEVEL` | Log level; one of `off`, `error`, `warn`, `info`, `debug` | `info` |
+| `KIMI_LOG_GLOBAL_MAX_BYTES` | Maximum bytes per global log file | `6291456` (6 MB) |
+| `KIMI_LOG_GLOBAL_FILES` | Number of global log files to retain | `5` |
+| `KIMI_LOG_SESSION_MAX_BYTES` | Maximum bytes per session log file | `5242880` (5 MB) |
+| `KIMI_LOG_SESSION_FILES` | Number of session log files to retain | `3` |
+
+When an integer variable fails to parse (non-positive integer or non-numeric), it silently falls back to the default value.
+
+## Clipboard bridge
+
+`KIMI_WSL_CLIPBOARD_IMAGE_PATH` is injected automatically by the CLI when it spawns the WSL clipboard helper subprocess, used to pass a temporary image path. The variable is written into the PowerShell subprocess's environment and read by the subprocess script internally; the main `kimi` process does not read this variable itself. Setting it in an external shell has **no effect** on the main `kimi` process — users do not need to manage this variable manually.
+
+## System environment variables
+
+Kimi Code CLI also reads a handful of standard system environment variables to detect the runtime environment and pick default behavior:
+
+- `HOME`: the user's home directory, used to resolve the default data path.
+- `VISUAL`, `EDITOR`: the executable invoked as the external editor, with `VISUAL` taking precedence.
+- `PATH`: used to locate external dependencies such as `rg` and `git`.
+- `NO_COLOR`: when set and non-empty, forces color and theme detection off, falling back to the dark theme. Follows the [no-color.org](https://no-color.org) convention.
+- `FORCE_COLOR`: when set to `"0"`, also disables color and theme detection, falling back to the dark theme.
+- `CI`: when non-empty and not `"0"`, disables theme detection and falls back to the dark theme; the telemetry module also reads this variable to mark the CI environment.
+- `LANG`: used to tag the locale in the telemetry context (purely as a tag; it does not change CLI behavior).
+- `TERM_PROGRAM`: used to detect terminal support for OSC 9 notifications (iTerm2, WezTerm, ghostty, WarpTerminal, etc.); also written into the telemetry context.
+- `TERM`: used to detect terminal support for OSC 9 notifications (xterm-kitty, xterm-ghostty, etc.).
+- `TMUX`: detects whether the CLI is running inside tmux, used for the terminal notification path.
+- `COLORFGBG`: detects the terminal color scheme (dark / light).
+- `DISPLAY`, `WAYLAND_DISPLAY`, `XDG_SESSION_TYPE`: detect a Linux graphical session, used by clipboard and image-related features. A `XDG_SESSION_TYPE` value of `wayland` is also treated as a Wayland session.
+- `WSL_DISTRO_NAME`, `WSLENV`: detect whether the CLI is running inside WSL, used for the PowerShell-bridged clipboard fallback.
+- `TERMUX_VERSION`: detects whether the CLI is running inside Termux.
+- `LOCALAPPDATA`: used on Windows when probing for the Git Bash installation path.
+
+These variables follow the usual conventions of each operating system; `kimi` only reads them and never modifies them.
diff --git a/docs/en/configuration/overrides.md b/docs/en/configuration/overrides.md
new file mode 100644
index 000000000..1567000dd
--- /dev/null
+++ b/docs/en/configuration/overrides.md
@@ -0,0 +1,110 @@
+# Configuration overrides
+
+Kimi Code CLI's runtime parameters come from the user config file, command-line flags, and a handful of runtime paths, endpoints, and switches read from process-level environment variables. Each layer serves a different purpose — the config file captures long-term preferences, CLI flags are well suited for temporary tweaks at this launch, and environment variables mainly locate the data directory, switch OAuth endpoints, and toggle a small number of runtime switches.
+
+Environment variables are **not a universal fallback for configuration fields** in Kimi Code CLI. They fall into three categories with different scopes, and cannot be flattened into a single linear priority list.
+
+## Three roles of environment variables
+
+1. **Config file location**: `KIMI_CODE_HOME` determines the data root holding the config file, sessions, logs, and so on, making the config file path `$KIMI_CODE_HOME/config.toml` (otherwise `~/.kimi-code/`). This is a "where to find the config" step that runs before everything else; it is not a fallback source for ordinary parameters. There is also no `KIMI_CONFIG_PATH`-style variable for pointing at an arbitrary config file.
+2. **Runtime switches**: a small number of switches such as `KIMI_DISABLE_TELEMETRY` directly turn off the corresponding subsystem. Even if `config.toml` has `telemetry = true`, telemetry is still disabled whenever this variable is set to a truthy value — its semantics are "additionally disable", not "ordinary override".
+3. **Runtime endpoints and diagnostics**: `KIMI_CODE_OAUTH_HOST`, `KIMI_OAUTH_HOST`, `KIMI_CODE_BASE_URL`, `KIMI_LOG_LEVEL`, and friends are read during OAuth and diagnostic subsystem initialization. See [Environment variables](./env-vars.md) for the full list.
+
+## Priority of ordinary runtime parameters
+
+For other runtime parameters (model alias, Plan / yolo mode, Skills directories, and so on), resolution is:
+
+1. **Command-line flags**: parameters supplied at this launch; override every other source and apply only to the current launch.
+2. **User config file**: `$KIMI_CODE_HOME/config.toml` (defaulting to `~/.kimi-code/config.toml`), used to capture long-term preferences.
+
+A few environment variables explicitly override related config fields. For example, `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` has higher priority than `[background].keep_alive_on_exit`. These exceptions are called out in [Environment variables](./env-vars.md) and in the corresponding [Config files](./config-files.md) field reference.
+
+::: warning Note
+Ordinary runtime parameters **do not** fall back to shell environment variables. For example, provider `api_key` / `base_url` are read only from fields in `config.toml` (including the `[providers.<name>.env]` subtable); they do not fall back to shell exports like `export KIMI_API_KEY`. See [Provider credentials](#provider-credentials) below.
+:::
+
+Kimi Code CLI currently reads only one user-level config file. There is no project-level (in-repo) config file mechanism. To isolate configuration between projects, point `KIMI_CODE_HOME` at a different data directory (see [Typical scenarios](#typical-scenarios) below) or temporarily override specific fields with CLI flags at launch.
+
+## Config file
+
+The config file location is controlled by the `KIMI_CODE_HOME` environment variable, falling back to `~/.kimi-code/` when unset. The file name is fixed as `config.toml`, and the directory is created with `0o700` permissions. The file can declare long-term preferences such as `default_model`, `providers`, `models`, `thinking`, and `loop_control`. See [Config files](./config-files.md) for the field reference.
+
+## Provider credentials
+
+Provider credentials (`api_key`, `base_url`) have their own resolution rules: Kimi Code CLI reads provider fields only from `config.toml` and **does not** fall back to shell environment variables. Running `export KIMI_API_KEY` in your terminal alone will not give a `[providers.<name>]` entry credentials — you have to write them into the config file explicitly.
+
+For a single provider, credentials are resolved in this order:
+
+1. `[providers.<name>].api_key` — the key written explicitly into the config file; highest priority.
+2. The corresponding key in the `[providers.<name>.env]` subtable (such as `KIMI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`) — moving the environment-variable names you would normally write in your shell into a TOML subtable. Used only when `api_key` is left empty. This is just the form of a config sub-table; it does not actually modify your process environment.
+3. If both are missing, startup fails with a message that the provider has no credentials configured.
+
+`base_url` resolves similarly to `api_key`: `[providers.<name>].base_url` is checked first, then `*_BASE_URL` keys (such as `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL`, `KIMI_BASE_URL`) in `[providers.<name>.env]`. See [Providers](./providers.md) for the full reference of provider types and fields.
+
+## Process-level environment variables
+
+Variables in `process.env` are read at Kimi Code CLI startup and fall into the three roles described above in [Three roles of environment variables](#three-roles-of-environment-variables):
+
+- **Data root and log paths**: `KIMI_CODE_HOME` switches `~/.kimi-code/`; `KIMI_LOG_LEVEL` and friends control diagnostic logs.
+- **Runtime switches**: `KIMI_DISABLE_TELEMETRY` disables telemetry (overriding `telemetry = true` in `config.toml`).
+- **OAuth endpoints and diagnostics**: `KIMI_CODE_OAUTH_HOST`, `KIMI_OAUTH_HOST`, and `KIMI_CODE_BASE_URL` control the hosted Kimi login endpoints; `KIMI_LOG_LEVEL` and friends control diagnostic logs.
+- **Background-task exit policy**: `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` overrides `[background].keep_alive_on_exit`, letting you decide for this process whether background tasks are kept on exit.
+
+See [Environment variables](./env-vars.md) for the full list of variables and their scopes.
+
+## Command-line flags
+
+Parameters supplied via CLI flags at launch have the highest priority and only apply to the current launch. Common flags:
+
+| Flag | Effect |
+| --- | --- |
+| `-S, --session [id]` | Resume the specified session; without an id, enters interactive selection |
+| `-C, --continue` | Continue the most recent session for the current working directory |
+| `-y, --yolo` | Auto-approve ordinary tool calls (aliases: `--yes`, `--auto-approve`) |
+| `--plan` | Launch in Plan mode |
+| `-m, --model <model>` | Specify the model alias to use for this launch |
+| `-p, --prompt <prompt>` | Execute a single prompt in non-interactive mode and exit |
+| `--output-format <format>` | Specify the output format for `-p` mode: `text` or `stream-json` |
+| `--skills-dir <dir>` | Replace the auto-discovered Skills directory (can be specified multiple times; applies to this launch only) |
+
+Mutually exclusive flag rules:
+
+- `--output-format` can only be used in prompt mode (`-p / --prompt`).
+- `--prompt` cannot be combined with `--yolo`, nor with `--plan`.
+- In prompt mode, `-S / --session` must be given an id; the interactive selector (bare `--session`) is not accepted.
+- `--continue` and `--session` cannot be used together.
+- Outside prompt mode, `--yolo` cannot be combined with `--continue` or `--session`; `--plan` cannot be combined with `--continue` or `--session`.
+- `--yolo` and `--plan` can be used together.
+
+::: tip Tip
+`--skills-dir` replaces the auto-discovered Skills directory for this launch and is suitable for one-off use. To persistently append search directories, set `extra_skill_dirs` at the top level of `config.toml` (see [Agent Skills](../customization/skills.md)). The two options have different semantics and can be chosen based on your needs.
+:::
+
+## Typical scenarios
+
+**Switch the data directory for isolated testing.** `KIMI_CODE_HOME` simultaneously affects the config file, session archives, ripgrep cache, and every other data location:
+
+```sh
+KIMI_CODE_HOME="$PWD/.kimi-sandbox" kimi
+```
+
+**Stage temporary credentials in the config file.** Since provider credentials are read only from `config.toml`, to use a different API key for a single launch, write it into the `[providers.<name>.env]` subtable in advance:
+
+```toml
+[providers.kimi.env]
+KIMI_API_KEY = "sk-test"
+```
+
+You can also set `api_key` directly on the provider; see [Provider credentials](#provider-credentials) above for the priority between the two.
+
+**Skip approvals for this launch.** Suitable for batch tasks you already know are safe:
+
+```sh
+kimi --yolo
+```
+
+**Enter Plan mode for this launch.** If you want the same default behavior, set `default_plan_mode = true` in the config file:
+
+```sh
+kimi --plan
+```
diff --git a/docs/en/configuration/providers.md b/docs/en/configuration/providers.md
new file mode 100644
index 000000000..a7319dd17
--- /dev/null
+++ b/docs/en/configuration/providers.md
@@ -0,0 +1,136 @@
+# Providers and models
+
+Kimi Code CLI integrates with multiple LLM platforms through a unified provider abstraction. Each provider handles one API protocol, and models are declared on top of a provider with their own name, context length, and capabilities. This page describes every provider type currently supported and how to configure them in `~/.kimi-code/config.toml`.
+
+## Overview
+
+The `type` field of each entry in the `providers` table determines which implementation is used. The currently supported types are:
+
+| Type | Protocol | Typical platforms |
+| --- | --- | --- |
+| `kimi` | OpenAI-compatible (chat completions style) | Kimi Code, Moonshot AI Open Platform |
+| `anthropic` | Anthropic Messages | Claude API |
+| `openai` | OpenAI Chat Completions | OpenAI and compatible services |
+| `openai_responses` | OpenAI Responses API | OpenAI's newer Responses endpoint |
+| `google-genai` | Google GenAI | Gemini API |
+| `vertexai` | Google GenAI on Vertex | Google Cloud Vertex AI |
+
+All providers stream model interactions by default. Thinking, vision, and tool-call capabilities are matched automatically by model name prefix, so you do not need to spell them out in the config.
+
+API keys may be written into the `api_key` field, or supplied under the `[providers.<name>.env]` sub-table. The lookup order is `api_key` > sub-table key > missing error. **Kimi Code CLI does not automatically fall back to shell environment variables** — `export KIMI_API_KEY` in your terminal alone will not give a provider credentials; you must write them into `config.toml` (see [Configuration overrides: provider credentials](./overrides.md#provider-credentials) for details). `api_key` and `oauth` are mutually exclusive on the same provider; setting both causes an error when the model is resolved. OAuth credentials are handled by the built-in login flow and do not need to be configured manually.
+
+The `[providers.<name>.env]` sub-table lets you supply credentials or endpoint overrides directly inside `config.toml`. These values are scoped to the provider and do not leak into the global shell environment:
+
+```toml
+[providers.my-anthropic.env]
+ANTHROPIC_API_KEY = "sk-ant-xxxxx"
+ANTHROPIC_BASE_URL = "https://my-proxy.example.com"
+```
+
+The most common ways to switch providers are: use the `/model` slash command inside the TUI to pick from already-configured models, or edit `config.toml` directly to adjust the `[providers.*]` and `[models.*]` tables. See [Config files](./config-files.md) for the full field reference.
+
+## `kimi`
+
+`kimi` connects to the Moonshot AI API using the OpenAI-compatible protocol.
+
+- Default `base_url`: `https://api.moonshot.ai/v1`
+- Environment variables: `KIMI_API_KEY`, `KIMI_BASE_URL`
+- Extra capability: video upload
+
+```toml
+[providers.kimi]
+type = "kimi"
+base_url = "https://api.moonshot.ai/v1"
+api_key = "sk-xxxxx"
+```
+
+The Kimi Code hosted service configures its `base_url` and credentials automatically after OAuth login; see [OAuth and credential injection](#oauth-and-credential-injection) and [Environment variables](./env-vars.md) for details.
+
+## `anthropic`
+
+`anthropic` integrates with the Claude API. Standard Claude models automatically enable vision, tool calls, and thinking where supported. For custom or unreleased models, declare `capabilities` explicitly under `[models.<alias>]`.
+
+Thinking can be controlled via `/model`, `/settings`, or configuration.
+
+- Default `base_url`: follows the Anthropic SDK default
+- Environment variables: `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`
+- Default `max_tokens`: set automatically per model. To override it (for example for testing or for an unrecognized alias), set `max_output_size` on the model alias (see [`config-files.md`](./config-files.md#models)). Recognized aliases are capped at the documented server-side ceiling.
+
+```toml
+[providers.anthropic]
+type = "anthropic"
+api_key = "sk-ant-xxxxx"
+
+[models."claude-opus-4-7"]
+provider = "anthropic"
+model = "claude-opus-4-7"
+max_context_size = 200000
+# Optional: lower the output budget for testing, or set one for a model
+# this CLI doesn't know about yet. Omit to use the per-model default
+# above.
+# max_output_size = 32000
+```
+
+## `openai`
+
+`openai` corresponds to the OpenAI Chat Completions protocol and can also be used to connect to any third-party service that speaks the same protocol (simply override `base_url`). Thinking, vision, and tool-call capabilities are inferred automatically from the model name.
+
+- Default `base_url`: `https://api.openai.com/v1`
+- Environment variables: `OPENAI_API_KEY`, `OPENAI_BASE_URL`
+
+```toml
+[providers.openai]
+type = "openai"
+base_url = "https://api.openai.com/v1"
+api_key = "sk-xxxxx"
+```
+
+## `openai_responses`
+
+`openai_responses` corresponds to OpenAI's newer Responses API. It always operates in streaming mode; capabilities are inferred automatically from the model name.
+
+- Default `base_url`: `https://api.openai.com/v1`
+- Environment variables: `OPENAI_API_KEY`, `OPENAI_BASE_URL`
+
+```toml
+[providers.openai-responses]
+type = "openai_responses"
+base_url = "https://api.openai.com/v1"
+api_key = "sk-xxxxx"
+```
+
+## `google-genai`
+
+`google-genai` connects directly to the Google Gemini API. Thinking, vision, and multimodal capabilities are inferred automatically from the model name.
+
+- Environment variable: `GOOGLE_API_KEY`
+
+```toml
+[providers.gemini]
+type = "google-genai"
+api_key = "xxxxx"
+```
+
+## `vertexai`
+
+`vertexai` shares the same implementation as `google-genai`; setting `type = "vertexai"` switches it to the Vertex AI access path.
+
+Authentication follows the standard Google Cloud flow: authenticate via `gcloud auth application-default login`, or set `GOOGLE_APPLICATION_CREDENTIALS` to a service-account JSON (this step is a generic Google SDK mechanism unrelated to Kimi Code configuration). **The project and region must be written into the `[providers.vertexai.env]` sub-table** — `export GOOGLE_CLOUD_PROJECT` or `export GOOGLE_CLOUD_LOCATION` in the shell will not be read by the CLI. When `GOOGLE_CLOUD_LOCATION` is missing, the CLI tries to infer it from `base_url`. API keys (`VERTEXAI_API_KEY` or `GOOGLE_API_KEY`) likewise go into the sub-table.
+
+```toml
+[providers.vertexai]
+type = "vertexai"
+
+[providers.vertexai.env]
+GOOGLE_CLOUD_PROJECT = "my-gcp-project"
+GOOGLE_CLOUD_LOCATION = "us-central1"
+```
+
+```sh
+gcloud auth application-default login   # one-time
+kimi
+```
+
+## OAuth and credential injection
+
+Some platforms (such as the Kimi Code hosted service) use OAuth instead of static API keys. Credentials are injected at runtime by the built-in kimi-oauth toolchain, and the login flow takes care of writing and refreshing them automatically — there is nothing to configure by hand for this in your config file.
diff --git a/docs/en/customization/agents.md b/docs/en/customization/agents.md
new file mode 100644
index 000000000..411d15f2c
--- /dev/null
+++ b/docs/en/customization/agents.md
@@ -0,0 +1,45 @@
+# Agents and subagents
+
+The agent in Kimi Code CLI is the core that drives a session. A session is always hosted by a single main agent, which may dispatch one or more subagents to handle more focused subtasks as the work progresses.
+
+The main agent is responsible for understanding the user's overall intent, planning the steps, conversing with the user, calling tools, and finally aggregating the results. Its context spans the entire session, and it is the entity the user interacts with directly in the terminal.
+
+A subagent is a temporary "assistant" spawned by the main agent. It takes a clearly defined task description, completes the work independently in its own context, and then returns the conclusion to the main agent. Subagents do not converse with the user directly, nor do they pollute the main agent's context history. This division of labor is particularly suited for work with clear boundaries that requires a lot of reading but produces a short output — such as "exploring a codebase", "reviewing a large implementation", or "planning a complex change".
+
+## Built-in subagents
+
+Kimi Code CLI ships with three built-in subagents, each targeting a different kind of task, ready to use out of the box:
+
+- **`coder`**: The default subagent, a general software engineering assistant that can read and write files, run shell commands, search code, and land concrete changes.
+- **`explore`**: Dedicated to codebase exploration. It operates read-only and will not modify any files. Suitable for quickly searching, reading, and summarizing a repository without making changes.
+- **`plan`**: For implementation planning and architectural design. Its toolset is narrowed further — not even shell commands are provided — focusing on "thinking through how to do it" rather than "doing it".
+
+## Invocation
+
+Subagents are dispatched automatically by the main agent. The main agent decides when to dispatch one based on task complexity, context usage, and the independence of the subtask — you don't need to manually specify the timing.
+
+Each dispatch surfaces as an approval request in the terminal (unless it matches an existing allow rule or you are in YOLO mode), so you can inspect the task description before it runs. You can also ask the main agent to prefer a particular type of subagent for a task — for example, "use `explore` first to map out the relevant files before making changes."
+
+Subagents can also run in the background; their results are synthesized back to the main agent automatically on a later turn, with no manual polling needed. You can also resume an existing subagent instance to continue the same task.
+
+## Context isolation and resource cost
+
+Each subagent has a completely independent context window. It cannot see the main agent's conversation history; it can only see the task description that the main agent explicitly passed. The subagent's own intermediate thoughts and tool call records do not flow back to the main agent — only the final result appears in the main agent's context.
+
+This isolation brings two direct benefits. First, the main agent's context stays concise and isn't flooded with exploratory logs over a long session. Second, multiple subagents can run in parallel without interfering with each other.
+
+The cost is that each subagent independently consumes model tokens, so it is unnecessary to dispatch a subagent for simple tasks — letting the main agent handle them directly is more economical. Subagents also cannot dispatch further subagents.
+
+## Permission inheritance
+
+A subagent's permission rules are inherited from the main agent: "always allow" rules that the main agent has accepted via `/permission` or during an approval automatically cover every subagent it dispatches, so the subagent does not need to re-approve the same kind of tool call. The `Agent` tool itself is allowed by default, so the main agent can complete multiple delegations without interrupting the user.
+
+If you want a particular kind of tool to be permanently unavailable inside subagents, you should tighten the main agent's permission rules.
+
+## Storage location in the session directory
+
+A subagent's runtime state is persisted to the session directory for later inspection and debugging. Each subagent instance corresponds to a separate subdirectory under `agents/`, which contains a `wire.jsonl` file recording prompts, message history, and final status in chronological order. Background subagents additionally expose their lifecycle through the `tasks/` subdirectory.
+
+::: warning Note
+Session directories, wire files, and task records are local debugging material and may contain user prompts, command output, repository paths, tool results, or traces of credentials. Do not commit these files to public repositories, issues, or chat transcripts directly; redact them first if you need to share them.
+:::
diff --git a/docs/en/customization/hooks.md b/docs/en/customization/hooks.md
new file mode 100644
index 000000000..404261b3a
--- /dev/null
+++ b/docs/en/customization/hooks.md
@@ -0,0 +1,150 @@
+# Hooks
+
+Hooks let you run local commands at key lifecycle points in Kimi Code CLI. They are useful for lightweight policy checks, audit logging, desktop notifications, or wiring into local automation scripts — for example, intercepting a risky tool call before it runs, or firing a notification when a background subagent finishes.
+
+Hook commands run in the local shell, and Kimi Code CLI writes the event payload as JSON to the command's stdin. The command's stdout, stderr, and exit code determine the hook result. Except for explicit blocking cases, hook failures fail open and do not interrupt the main flow because of a misbehaving script.
+
+::: warning Note
+Hooks are useful for local notifications and lightweight interception, but they should not be treated as the only security boundary. Script errors, timeouts, and ordinary non-zero exit codes fail open and continue to allow the operation; high-risk tool calls should still rely on permission approval and human review.
+:::
+
+## Configuration
+
+Declare hooks in `~/.kimi-code/config.toml` with `[[hooks]]` array tables:
+
+```toml
+[[hooks]]
+event = "PreToolUse"
+matcher = "Bash"
+command = "node ~/.kimi-code/hooks/check-bash.mjs"
+timeout = 5
+
+[[hooks]]
+event = "Notification"
+matcher = "task\\.completed"
+command = "terminal-notifier -title Kimi -message 'Background task finished'"
+```
+
+The fields are:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `event` | `string` | Yes | Event name. The value must be one of the entries in the "Events" table below; any other value causes the entire config to fail to load |
+| `matcher` | `string` | No | Regular expression matched against the event target. Missing or empty means match everything |
+| `command` | `string` | Yes | Shell command to run. Must be non-empty |
+| `timeout` | `integer` | No | Timeout in seconds, range 1–600. Defaults to 30 seconds when unset |
+
+Each `[[hooks]]` table accepts only these four fields. Misspelled or extra fields cause the configuration file to fail to parse.
+
+When one event fires, all matching hooks run in parallel. If multiple entries share the exact same `command`, that command runs only once. `matcher` uses JavaScript regular expression semantics; invalid regular expressions are silently skipped and treated as no match.
+
+Hook commands are launched through the shell (equivalent to `sh -c <command>`), and the child process's working directory is the current session's `cwd`. On non-Windows platforms, the child is placed in its own process group; on timeout or session interruption, Kimi Code CLI first sends `SIGTERM` and then `SIGKILL` 100 milliseconds later, so any grandchild processes forked inside the hook are cleaned up as well.
+
+JSON fields passed to hooks use snake_case. Every payload includes:
+
+```json
+{
+  "hook_event_name": "PreToolUse",
+  "session_id": "session_abc",
+  "cwd": "/path/to/project"
+}
+```
+
+Additional fields depend on the event type, as shown in the event table below.
+
+## Return values
+
+Hook command exit codes and stdout are interpreted as follows:
+
+| Result | Behavior |
+| --- | --- |
+| Exit code `0` | Allow. If stdout is JSON, text may be read from `message` or `hookSpecificOutput.message` |
+| Exit code `2` | Block. stderr is used as the blocking reason |
+| Any other non-zero exit code | Fail open and allow |
+| Timeout or process error | Fail open and allow |
+
+If stdout is JSON and `hookSpecificOutput.permissionDecision` is `deny`, the result is also treated as a block:
+
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Use rg instead"
+  }
+}
+```
+
+Blocking only applies to events that participate in control flow. For example, `PreToolUse` can block a tool call, and `Stop` can append one continuation message to the current turn. Observer events (such as `PostToolUse`, `PostToolUseFailure`, `PostCompact`, `SubagentStop`, `StopFailure`, and `Notification`) are dispatched asynchronously in a fire-and-forget fashion; their return values are ignored and do not change the main flow. `PreCompact` is invoked with `trigger` (not `triggerBlock`); its return value is likewise completely ignored, and it is not a blockable event.
+
+When a block takes effect, if the script does not provide a reason through stderr or JSON output, the CLI falls back to `Blocked by <event> hook` as a placeholder reason. A `PreToolUse` block is written back into context as a failed tool result, so the model can choose an alternative based on the reason.
+
+## Events
+
+The following events are triggered automatically today:
+
+| Event | Matcher | Main payload | Behavior |
+| --- | --- | --- | --- |
+| `UserPromptSubmit` | Text content submitted by the user | `prompt` (`ContentPart[]` array) | Fires only for real user messages. Text returned by the hook is wrapped as a hook result, written into session history for transcript/replay, shown to the user, and the current LLM turn continues without sending the hook result to the model; if the hook blocks, the block reason is returned to the user as an assistant message and no model call is made; if all hooks produce no output, the normal LLM turn continues |
+| `PreToolUse` | Tool name | `tool_name`, `tool_input`, `tool_call_id` | Fires before permission checks. If blocked, the tool does not run |
+| `PostToolUse` | Tool name | `tool_name`, `tool_input`, `tool_call_id`, `tool_output` | Fires after a successful tool call. `tool_output` is truncated to the first 2000 characters |
+| `PostToolUseFailure` | Tool name | `tool_name`, `tool_input`, `tool_call_id`, `error` | Fires after a tool call fails or is blocked by a hook |
+| `Stop` | Empty string | `stop_hook_active` | Fires when the model is about to stop. If blocked, the reason is appended directly to context as a system-triggered user message, and the turn may continue once |
+| `StopFailure` | Error type | `error_type`, `error_message` | Fires after the current turn fails with a non-cancellation error |
+| `SessionStart` | `startup` or `resume` | `source` | Fires after the main agent is created for a new session, or after a historical session is resumed |
+| `SessionEnd` | `exit` | `reason` | Fires after the session is closed and its metadata is flushed |
+| `SubagentStart` | Subagent name | `agent_name`, `prompt` | Fires after a subagent is configured and before it actually starts running. `prompt` is truncated to the first 500 characters |
+| `SubagentStop` | Subagent name | `agent_name`, `response` | Fires asynchronously after a subagent completes successfully; does not fire on failure. `response` is truncated to the first 500 characters |
+| `PreCompact` | `manual` or `auto` | `trigger`, `token_count` | Fires before context compaction actually starts. This event is invoked with `trigger` (not `triggerBlock`); its return value is completely ignored and blocking decisions are not read |
+| `PostCompact` | `manual` or `auto` | `trigger`, `estimated_token_count` | Fires asynchronously after context compaction is successfully written. Blocking results do not change the main flow |
+| `Notification` | Notification type | `sink`, `notification_type`, `title`, `body`, `severity`, `source_kind`, `source_id` | Currently fires when a background subagent result is written into context. `notification_type` is one of `task.completed`, `task.failed`, `task.killed`, or `task.lost`; the sink is `context` |
+
+`UserPromptSubmit` return text is wrapped as a hook result:
+
+```xml
+<hook_result hook_event="UserPromptSubmit">
+hook response
+</hook_result>
+```
+
+If multiple `UserPromptSubmit` hooks return text, each result gets its own `<hook_result>` tag. This message keeps its hook-result origin for transcript/replay, but is not sent to the model. The model sees the original user prompt and the current turn continues.
+
+If a `UserPromptSubmit` hook blocks the request, the block reason uses the same format and is returned to the user, but the turn does not continue to a model call.
+
+`Stop` block reasons are appended directly as system-triggered user messages so the current turn can continue:
+
+```text
+continue from hook
+```
+
+## Example: block risky shell commands
+
+The following hook reads `tool_input.command` from stdin before a `Bash` tool call. If the command contains `rm -rf`, the script exits with code `2` and writes the reason to stderr:
+
+::: warning Note
+This example only demonstrates how a hook blocks a tool call; it is not a complete shell safety parser. Real policies are better implemented with an allowlist, or with dedicated shell parsing that handles quoting, variable expansion, aliases, and multi-part commands.
+:::
+
+```toml
+[[hooks]]
+event = "PreToolUse"
+matcher = "Bash"
+command = "node ~/.kimi-code/hooks/block-dangerous-bash.mjs"
+timeout = 5
+```
+
+```js
+let input = '';
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+});
+process.stdin.on('end', () => {
+  const payload = JSON.parse(input);
+  const command = payload.tool_input?.command ?? '';
+  if (command.includes('rm -rf')) {
+    console.error('Blocked dangerous shell command');
+    process.exit(2);
+  }
+});
+```
+
+When the hook blocks the tool call, Kimi Code CLI writes the blocking reason back into context as a failed tool result, so the model can choose a safer alternative.
diff --git a/docs/en/customization/mcp.md b/docs/en/customization/mcp.md
new file mode 100644
index 000000000..bbde8cc47
--- /dev/null
+++ b/docs/en/customization/mcp.md
@@ -0,0 +1,83 @@
+# Model Context Protocol
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open protocol that lets models safely call tools exposed by external processes or services. Kimi Code CLI acts as an MCP client to integrate these external tools, exposing them to the agent alongside built-in tools (`Read`, `Bash`, `Grep`, etc.).
+
+## Integration scope
+
+Kimi Code CLI connects to MCP servers via stdio (local subprocess) or HTTP. Once connected, MCP tools behave the same as built-in tools: they are available to the agent, subject to permission rules, and go through the approval flow.
+
+## Configuration and login
+
+MCP server configurations live in `mcp.json` in two layers:
+
+- User-level: `~/.kimi-code/mcp.json` (or `$KIMI_CODE_HOME/mcp.json`), shared across projects
+- Project-level: `.kimi-code/mcp.json` in the current workspace
+
+Project entries override user-level entries with the same name.
+
+The easiest entry point is running `/mcp-config` in the TUI, which guides you through adding, editing, or removing servers. To check connection status, run `/mcp`.
+
+The top-level shape of `mcp.json` is:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    },
+    "linear": {
+      "url": "https://mcp.linear.app/mcp"
+    }
+  }
+}
+```
+
+Entries with `command` are stdio servers; entries with `url` are HTTP servers, so you usually do not need to write a `transport` field. HTTP servers can provide static credentials through `headers` or `bearerTokenEnvVar`. When OAuth is required, run `/mcp-config login <server-name>` to complete browser authorization.
+
+Optional fields:
+
+| Field | Type | Applies to | Description |
+| --- | --- | --- | --- |
+| `env` | `Record<string, string>` | stdio | Environment variables injected into the subprocess |
+| `cwd` | `string` | stdio | Working directory for the subprocess |
+| `headers` | `Record<string, string>` | HTTP | Static headers appended to every request |
+| `enabled` | `boolean` | both | Set to `false` to disable the server without removing the entry |
+| `startupTimeoutMs` | `number` | both | Connection timeout in milliseconds, default `30000` |
+| `toolTimeoutMs` | `number` | both | Per-tool-call timeout in milliseconds |
+| `enabledTools` | `string[]` | both | Allowlist: only expose the tools in this list |
+| `disabledTools` | `string[]` | both | Blocklist: exclude the tools in this list |
+
+::: warning Note
+Stdio entries in a project-level `.kimi-code/mcp.json` execute local commands when the session starts. Only enable project-level MCP servers in repositories you trust.
+:::
+
+## Tool naming and permissions
+
+MCP tools are exposed using the naming convention `mcp__<server>__<tool>`. Permission matching supports `*` and `**` wildcards, so `mcp__github__*` covers every tool from the `github` server.
+
+Calls that do not match any rule trigger an approval request. Choosing "Approve for this session" in the approval prompt auto-approves subsequent matching calls.
+
+You can also pre-load permanent rules in the `[[permission.rules]]` array of tables in `config.toml`:
+
+```toml
+[[permission.rules]]
+decision = "allow"
+pattern = "mcp__github__*"
+
+[[permission.rules]]
+decision = "deny"
+pattern = "mcp__filesystem__write_file"
+```
+
+The full syntax of the `pattern` field and the accepted values of other fields such as `decision`, `scope`, and `reason` are documented in [Config files](../configuration/config-files.md#permission).
+
+## Security
+
+- Only integrate MCP servers from trusted sources
+- Check that the tool name and arguments are reasonable in approval requests
+- Keep manual approval for high-risk tools, and avoid broad `mcp__*` wildcard allowlisting
+
+::: warning Note
+In YOLO mode, MCP tool calls are auto-approved like any other tool. Only use this mode when you fully trust the integrated MCP servers.
+:::
diff --git a/docs/en/customization/skills.md b/docs/en/customization/skills.md
new file mode 100644
index 000000000..f0a5fef31
--- /dev/null
+++ b/docs/en/customization/skills.md
@@ -0,0 +1,127 @@
+# Agent Skills
+
+Agent Skills are the lightweight mechanism Kimi Code CLI uses to extend a model's capabilities. A skill is a Markdown document with YAML frontmatter that describes a piece of expertise or a workflow. Kimi Code CLI scans known directories on startup and injects the discovered skills into the system prompt, so the agent knows which skills are available in the current session.
+
+Compared to pasting the same guidance into the prompt every time, skills offer these advantages: the content is captured in a file, reusable across projects and teams, can be loaded with a one-shot slash command, and can also be invoked automatically by the model when needed.
+
+## Creating a skill
+
+Skill files must be placed in a [known scan directory](#skill-locations). A skill can use one of two file structures:
+
+- **Directory form (recommended)**: create a subdirectory with the main file named `SKILL.md`. You can also place scripts, references, and other auxiliary files in the same directory. If both `<name>/SKILL.md` and a flat `<name>.md` exist in the same directory, the subdirectory wins.
+- **Flat form**: use a single `.md` file directly; the skill name defaults to the filename with `.md` removed.
+
+### File format
+
+`SKILL.md` consists of two parts: YAML frontmatter and a Markdown body.
+
+```markdown
+---
+name: code-style
+description: Project code style conventions, covering naming, indentation, comments, and file organization
+type: prompt
+whenToUse: When the user asks me to write, modify, or review the project's source code
+disableModelInvocation: false
+arguments:
+  - target
+  - mode
+---
+
+Please handle the code according to the following conventions:
+
+- Use 2-space indentation
+- Use `camelCase` for variable names and `PascalCase` for type names
+- Public functions must have TSDoc comments
+- Lines must not exceed 100 characters
+```
+
+### Frontmatter fields
+
+| Field | Description |
+| --- | --- |
+| `name` | Skill name. Required in a directory-style `SKILL.md`; in a flat `.md` file the filename is used when omitted. Names are case-insensitive. |
+| `description` | A one-line summary. The model uses it to decide when to use this skill. Required in a directory-style `SKILL.md`; in a flat `.md` file falls back to the first non-empty line of the body (truncated to 240 characters) when omitted. |
+| `type` | Skill type. Supported values: `prompt` (default), `inline` (same semantics as `prompt`), or `flow` (manual invocation only, not auto-invoked by the model). Other values are skipped. |
+| `whenToUse` | Description of the trigger scenario. Aliases `when-to-use` and `when_to_use` are also accepted. |
+| `disableModelInvocation` | Set to `true` to forbid the model from invoking this skill automatically. Aliases `disable-model-invocation` and `disable_model_invocation` are also accepted. |
+| `arguments` | Named arguments the skill accepts. Can be written as an array of strings, or as a single whitespace-separated string (e.g. `arguments: target mode`). Once declared, the body can read them with `$<name>`. Purely numeric or empty entries are ignored. |
+
+::: warning Note
+In a directory-style `SKILL.md`, both `name` and `description` **must** be filled in explicitly. Omitting either one causes the skill to fail parsing.
+:::
+
+### Body placeholders
+
+The skill body expands a small set of placeholders before being sent to the model:
+
+- `$ARGUMENTS`: the complete raw argument string passed when the skill was invoked
+- `$ARGUMENTS[0]`, `$ARGUMENTS[1]`, and shorthand `$0`, `$1`: positional arguments after whitespace splitting, starting at 0
+- `$<name>`: a named argument declared in `arguments`
+- `${KIMI_SKILL_DIR}`: the directory containing the current skill file
+
+Positional arguments respect single- and double-quoted text: in `/skill:commit "fix login" patch`, `$0` expands to `fix login`. If the body does not contain any argument placeholders, the appended text is added to the end of the body as `\n\nARGUMENTS: <text>`.
+
+## Skill locations
+
+Kimi Code CLI scans skills in four scope tiers, with more specific scopes taking higher priority:
+
+**Project > User > Extra > Built-in**
+
+User-level:
+
+- `~/.kimi-code/skills/`
+- `~/.agents/skills/`
+
+Project-level (project root = the nearest ancestor directory containing `.git`):
+
+- `.kimi-code/skills/`
+- `.agents/skills/`
+
+Extra directories are declared via the top-level `extra_skill_dirs` field in `config.toml`:
+
+```toml
+extra_skill_dirs = ["~/team-skills", ".agents/team-skills"]
+```
+
+Built-in skills ship with CLI and have the lowest priority.
+
+## Invoking a skill
+
+Users can invoke a skill explicitly with a slash command:
+
+```
+/skill:code-style
+/skill:git-commits Fix the concurrency issue in the login API
+```
+
+The model can also decide to invoke a skill automatically based on `description` and `whenToUse`, unless `disableModelInvocation` is set to `true` or `type` is `flow`. When the model invokes a skill, body placeholders are expanded first, then the content is injected into the system prompt. Skill calls are allowed to nest up to 3 levels deep; deeper invocations are terminated.
+
+## Full example
+
+```markdown
+---
+name: review-pr
+description: Review a pull request against the team's standards and produce a structured review report
+type: prompt
+whenToUse: When the user asks me to review a PR, inspect code changes, or assess commit quality
+arguments:
+  - pr_ref
+---
+
+Please review the PR specified by the user using the following process: $pr_ref
+
+1. Fetch and read the full diff of `$pr_ref`.
+2. Check against the following items one by one:
+   - Whether corresponding test cases are included
+   - Whether public APIs have documentation updates
+   - Whether new dependencies are introduced; if so, explain the rationale
+   - Whether error handling covers edge cases
+3. Refer to the checklist in the same directory: `references/checklist.md`
+4. Produce a review report containing:
+   - Overall conclusion (approve / request changes / comment)
+   - Required changes (blocking)
+   - Suggested improvements (non-blocking)
+   - Things worth acknowledging
+```
+
+Save the above as `~/.kimi-code/skills/review-pr/SKILL.md`, and put the checklist at `references/checklist.md` in the same directory. Then restart the session, and you can invoke it via `/skill:review-pr #1234`; the appended `#1234` will expand into `$pr_ref` in the body.
diff --git a/docs/en/faq.md b/docs/en/faq.md
new file mode 100644
index 000000000..a421d16db
--- /dev/null
+++ b/docs/en/faq.md
@@ -0,0 +1,3 @@
+# FAQ
+
+This page collects the questions new users hit most often, along with short answers. When a topic needs a fuller explanation, the answer links to the relevant doc at the end.
diff --git a/docs/en/guides/getting-started.md b/docs/en/guides/getting-started.md
new file mode 100644
index 000000000..120b74e6c
--- /dev/null
+++ b/docs/en/guides/getting-started.md
@@ -0,0 +1,135 @@
+# Getting started
+
+## What is Kimi Code CLI
+
+Kimi Code CLI is an AI agent that runs in the terminal, helping you carry out software development tasks and day-to-day terminal operations. It can read and edit code, run shell commands, search files, and fetch web pages, autonomously planning and adjusting the next step based on feedback as it works.
+
+It fits scenarios such as:
+
+- **Writing and modifying code**: implementing new features, fixing bugs, completing refactors
+- **Understanding a project**: exploring an unfamiliar codebase and answering questions about architecture and implementation
+- **Automating tasks**: batch-processing files, running builds and tests, chaining multiple scripts together
+
+The entire CLI is written in TypeScript, distributed through npm, and runs on Node.js.
+
+## Installation
+
+### Install script (recommended)
+
+The quickest way to install Kimi Code CLI is with the install script; no pre-installed Node.js is required:
+
+- **macOS / Linux**:
+
+```sh
+curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
+```
+
+- **Windows (PowerShell)**:
+
+```powershell
+irm https://code.kimi.com/kimi-code/install.ps1 | iex
+```
+
+This downloads the latest release, verifies the checksum, and places the `kimi` executable on your `PATH`.
+
+### npm installation
+
+If you prefer to install via npm, you need Node.js 24.15.0 or later:
+
+```sh
+node --version
+```
+
+The package name is `@moonshot-ai/kimi-code`:
+
+```sh
+npm install -g @moonshot-ai/kimi-code
+```
+
+Or with pnpm:
+
+```sh
+pnpm add -g @moonshot-ai/kimi-code
+```
+
+## Upgrade and uninstall
+
+After installation, verify that the executable is ready:
+
+```sh
+kimi --version
+```
+
+**Upgrade**: if you installed via the script, re-run it. If you installed via npm:
+
+```sh
+npm install -g @moonshot-ai/kimi-code@latest
+```
+
+**Uninstall**: if you installed via the script, remove the `kimi` executable. If you installed via npm:
+
+```sh
+npm uninstall -g @moonshot-ai/kimi-code
+```
+
+## First launch
+
+Move into the project directory you want to work in and simply run `kimi` to start the interactive UI:
+
+```sh
+cd your-project
+kimi
+```
+
+If you only want to run a single instruction without entering the interactive UI, use the `-p` flag:
+
+```sh
+kimi -p "Take a look at this project's directory structure"
+```
+
+To resume the previous session, add the `-C` flag:
+
+```sh
+kimi -C
+```
+
+On the first launch, Kimi Code CLI has no credentials yet, and you need to configure an API source before you can start a conversation. In the interactive UI, enter the slash command `/login` to begin the login flow:
+
+```
+/login
+```
+
+`/login` opens a platform selector supporting:
+
+- **Kimi Code** — OAuth device code flow; open the URL on any device, sign in, and enter the code to authorize
+- **Moonshot AI Open Platform** — log in directly with an API key
+
+To sign out, enter `/logout` to clear the current credentials.
+
+::: tip
+If you want to use Anthropic, OpenAI, Google, or other providers, edit `config.toml` directly to configure the API key. See [Providers and models](../configuration/providers.md) for details. Runtime configuration such as the model and provider is also written to `config.toml`. See [Config files](../configuration/config-files.md), [Environment variables](../configuration/env-vars.md), and [Configuration overrides](../configuration/overrides.md) for details.
+:::
+
+## Your first conversation
+
+Once login is complete, you can describe a task to Kimi Code CLI directly in natural language. For example, you can have it familiarize itself with the current project first:
+
+```
+Take a look at this project's directory structure and briefly describe what each directory is for.
+```
+
+Kimi Code CLI will automatically call file-reading, search, and web-fetching tools, browse the relevant content, and then give you an answer. Read-only operations such as reading files and searching the web are executed automatically by default without requiring confirmation. For operations that modify files or run shell commands, it asks for your confirmation before executing by default, and you can approve or reject as you see fit.
+
+You can also have it do something more concrete, such as:
+
+```
+Add a function in src/utils that converts any string to kebab-case, and add a unit test for it.
+```
+
+Kimi Code CLI plans the steps, modifies the code, runs the tests, and tells you what it did at each step.
+
+In the interactive UI, entering `/help` shows all available [slash commands](../reference/slash-commands.md) along with common keyboard shortcut hints. To exit Kimi Code CLI, enter `/exit`. You can also press `Ctrl-C` — the UI will first clear the current input and prompt you to press it again, and the second press exits. Or press `Ctrl-D` twice with the input box empty to exit.
+
+## Where data is stored
+
+Kimi Code CLI stores its local data under `~/.kimi-code/` by default, including config files, session records, logs, and the update cache. If you want to move it elsewhere, you can point to a new root directory via the `KIMI_CODE_HOME` environment variable. For the full directory layout and environment variable reference, see [Data locations](../configuration/data-locations.md) and [Environment variables](../configuration/env-vars.md).
diff --git a/docs/en/guides/interaction.md b/docs/en/guides/interaction.md
new file mode 100644
index 000000000..56279d570
--- /dev/null
+++ b/docs/en/guides/interaction.md
@@ -0,0 +1,67 @@
+# Interaction and Input
+
+Kimi Code CLI runs as an interactive TUI with an input box, conversation view, and status bar. This page covers basic operations, mode switches, the approval flow, and shortcuts. The full list is available via `/help`.
+
+## Input box basics
+
+The input box accepts free-form text; pressing `Enter` sends, and `Shift-Enter` inserts a line break. When the input box is empty, press `↑` / `↓` to browse history for the current directory.
+
+Press `Ctrl-D` twice to exit the CLI. `Ctrl-C` interrupts the current turn while streaming; press it twice in the idle state to exit. `Esc` closes dialogs and also interrupts a turn while streaming.
+
+## Slash commands and `@` mentions
+
+Anything starting with `/` is recognized as a slash command, covering session management, mode switching, configuration, and more — such as `/help`, `/new`, `/sessions`, and `/model`. See the [slash command reference](../reference/slash-commands.md) for the full list.
+
+Type `/` to open the command completion menu, which also includes commands from [Agent Skills](../customization/skills.md). If a skill name collides with a built-in command, use the full `/skill:<name>` form. Press `Esc` to dismiss.
+
+Some commands are only available while the agent is idle; interrupt the current turn first if the agent is streaming. Mode-switch and query commands such as `/yolo`, `/plan`, and `/help` are always available.
+
+Type `@` to trigger file-path completion. Selecting an entry inserts the relative path, and the agent can read the file directly. Dot-prefixed directories are hidden by default; write `@.github/` to include them explicitly.
+
+## Plan mode
+
+In Plan mode, the agent spells out its plan before taking action. Press `Shift-Tab` or `/plan` to toggle; `/plan clear` clears the current plan file (available while idle only).
+
+The agent outputs a plan and waits for your confirmation instead of making changes directly. Once the plan is ready, you can reject it (staying in Plan mode) or request changes. Leaving Plan mode still requires your confirmation, even when YOLO mode is on.
+
+## YOLO mode
+
+YOLO mode automatically approves most tool calls, skipping the approval step. Enter `/yolo` (or `/yes`) to toggle; available both idle and streaming.
+
+::: warning Note
+YOLO mode skips ordinary approvals, but not the approval required to leave Plan mode.
+:::
+
+## Approval flow
+
+When the agent invokes a tool with side effects (such as modifying a file or running a command), an approval panel pops up for your confirmation. This is skipped in YOLO mode and for plan-file writes in Plan mode.
+
+Use arrow keys to select an option and `Enter` to confirm; press `1` / `2` / `3` to select by position directly. `Esc`, `Ctrl-C`, and `Ctrl-D` all reject the request. The panel usually also offers an "Approve for this session" option to auto-allow similar calls going forward.
+
+## Working while output is streaming
+
+While the agent is thinking or making tool calls ("streaming output"), the input box is still usable:
+
+- `Esc` — interrupt the current turn.
+- `Ctrl-C` — also interrupts; press twice in the idle state to exit.
+- `Ctrl-S` — insert the current input-box content as an additional message into the in-progress turn.
+- `Ctrl-O` — globally toggle the collapsed state of all tool output.
+
+## External editor
+
+Press `Ctrl-G` to open the current input in an external editor; saved content is loaded back when the editor closes.
+
+Editor priority: `/editor` config > `$VISUAL` > `$EDITOR`. Run `/editor` first if none is configured.
+
+## Pasting images and videos
+
+Paste images or videos from the clipboard directly into the input box for multimodal models:
+
+- Unix (macOS / Linux): `Ctrl-V`
+- Windows: `Alt-V`
+
+Placeholders appear in the input box and behave like ordinary text; they are replaced with the actual content when sent. Plain text falls back to a normal paste. Media attachments are kept in the current session only.
+
+## Viewing all shortcuts
+
+Enter `/help` to open a panel listing all shortcuts and slash commands. Scroll with `↑` / `↓`, page with `PageUp` / `PageDown`, and close with `Esc`, `Enter`, or `q`.
diff --git a/docs/en/guides/migration.md b/docs/en/guides/migration.md
new file mode 100644
index 000000000..d0938ffb4
--- /dev/null
+++ b/docs/en/guides/migration.md
@@ -0,0 +1,37 @@
+# Migrating from kimi-cli
+
+Kimi Code CLI is the next-generation terminal agent — and a fresh start. If you have been using the previous generation, kimi-cli, you don't need to start over: a single command brings your configuration, MCP servers, and session history across to the new version.
+
+## Why migrate
+
+kimi-code is rebuilt on Node.js and no longer depends on Python or the `uv` toolchain, making installation and upgrades simpler. It also ships native binaries out of the box.
+
+The terminal UI has been redesigned for a faster and lighter experience.
+
+kimi-cli is transitioning to kimi-code, and migrating lets you keep your existing configuration and session history going forward.
+
+## How to migrate
+
+There are two ways to migrate.
+
+The **first time you run `kimi`** after installing kimi-code, it automatically checks whether kimi-cli data exists under `~/.kimi/`. If it finds any, a migration prompt appears, and you can choose to migrate now, do it later, or never be asked again.
+
+You can also **run it manually at any time**:
+
+```sh
+kimi migrate
+```
+
+You can choose whether to migrate chat sessions as well. If you don't need the history yet, pick **Config only**; otherwise pick **Config + N sessions** to bring everything across in one go. A summary is printed at the end.
+
+## What happens during migration
+
+**What gets migrated**: configuration (`config.toml`), MCP server configuration, input history, and whichever chat sessions you chose to migrate.
+
+**What does not get migrated**: OAuth login credentials and MCP service authorizations are not copied, so you will need to run `/login` again and re-authorize MCP servers after migrating. kimi-cli plugins are also out of scope.
+
+::: tip
+Migration **never modifies or deletes** any of the old data under `~/.kimi/`. kimi-cli keeps working as before, and the two do not interfere with each other. Migration can also be run repeatedly — sessions that have already been migrated are not imported again.
+:::
+
+After migration, sessions imported from kimi-cli are tagged with `[imported]` in the session picker so you can tell them apart from new ones.
diff --git a/docs/en/guides/sessions.md b/docs/en/guides/sessions.md
new file mode 100644
index 000000000..5619e8a2f
--- /dev/null
+++ b/docs/en/guides/sessions.md
@@ -0,0 +1,110 @@
+# Sessions and context
+
+Kimi Code CLI persists every conversation as a "session", preserving message history and metadata so you can close the terminal and resume later. This page covers resuming sessions, context compaction, and managing sessions from inside the TUI.
+
+## Session storage
+
+All sessions are stored under `$KIMI_CODE_HOME/sessions/` (default `~/.kimi-code/sessions/`), bucketed by working directory:
+
+```text
+~/.kimi-code/
+├── config.toml
+├── session_index.jsonl
+└── sessions/
+    └── <workDirKey>/
+        └── <sessionId>/
+            ├── state.json
+            └── agents/
+                ├── main/
+                │   └── wire.jsonl
+                └── <subagentId>/
+                    └── wire.jsonl
+```
+
+- `state.json` — session title and metadata.
+- `agents/*/wire.jsonl` — agent event stream.
+
+::: warning Note
+Manually editing files under `sessions/` can leave a session unrecoverable due to ordering constraints in `state.json` and `wire.jsonl`.
+:::
+
+## Starting and resuming sessions
+
+By default, `kimi` creates a new session each time. To continue where you left off:
+
+**Resume the most recent session in the current directory:**
+
+```sh
+kimi --continue
+```
+
+**Resume a specific session:**
+
+```sh
+kimi --session abc123
+```
+
+`-r` / `--resume` are equivalent aliases.
+
+**Pick interactively:**
+
+```sh
+kimi --session
+```
+
+::: warning Note
+`--continue` and `--session` are mutually exclusive; `--yolo` and `--plan` also cannot be combined with them.
+:::
+
+## Switching sessions inside the TUI
+
+- `/new` (`/clear`): switch to a new session.
+- `/sessions` (`/resume`): browse and resume past sessions.
+- `/fork`: fork the current session (see below).
+- `/title <text>` (`/rename`): set a session title for easier recognition. Without an argument, shows the current title.
+
+`/sessions` works even while streaming, but switching requires interrupting the turn first with `Esc` or `Ctrl-C`. `/new`, `/fork`, and `/compact` are only available while idle.
+
+## Context compaction
+
+Kimi Code CLI automatically compresses message history when context approaches the window limit. You can also trigger it manually:
+
+```text
+/compact
+```
+
+Pass a custom hint to tell the model what to preserve:
+
+```text
+/compact Keep the discussion related to database migrations
+```
+
+## Forking sessions
+
+To try a new line of thinking without disrupting the current conversation, use `/fork`:
+
+```text
+/fork
+```
+
+The forked session is fully independent; you can switch back to the original at any time.
+
+## Exporting sessions
+
+Package a session into a ZIP:
+
+```sh
+kimi export <sessionId>
+```
+
+Without a `sessionId`, it exports the most recent session (interactively asks for confirmation; pass `-y` to skip). Use `-o` to set the output path:
+
+```sh
+kimi export <sessionId> -o ~/Desktop/my-session.zip
+```
+
+The ZIP is written to the current working directory by default. The session's own diagnostic log is always bundled along with the session directory. The global diagnostic log at `$KIMI_CODE_HOME/logs/kimi-code.log` — which captures events that do not belong to a session, such as TUI startup and login — is also bundled by default; pass `--no-include-global-log` to skip it.
+
+::: tip Tip
+Exported files may contain sensitive information. Review the contents before sharing.
+:::
diff --git a/docs/en/guides/use-cases.md b/docs/en/guides/use-cases.md
new file mode 100644
index 000000000..d90cce51a
--- /dev/null
+++ b/docs/en/guides/use-cases.md
@@ -0,0 +1,118 @@
+# Common use cases
+
+Below are typical scenarios and prompt samples for Kimi Code CLI.
+
+## Understanding an unfamiliar project
+
+Use `kimi --plan` or press `Shift-Tab` to enter Plan mode for large-scale research. Ask it to produce a plan first and approve before execution:
+
+```
+Walk me through the overall architecture of this repository. Focus on:
+1. Where the entry point is and what happens at startup
+2. The dependency relationships between major modules
+3. How configuration and data are loaded
+At the end, draw a simple module relationship diagram.
+```
+
+For focused questions, ask directly:
+
+```
+How does the event loop under src/runtime work? Where do events originate, and who consumes them?
+```
+
+```
+How is "permission approval" implemented in this project? Which files are involved, and what are the key types?
+```
+
+For large investigations, the main agent can spawn **subagents** to handle subtasks in parallel. See [Agents](../customization/agents.md).
+
+## Implementing a new feature
+
+State the requirement and acceptance criteria clearly. Use Plan mode for complex or risky changes.
+
+```
+Add a retry utility under src/utils:
+- Function signature retry<T>(fn: () => Promise<T>, options): Promise<T>
+- Supports three options: maxAttempts, initialDelayMs, backoffFactor
+- Throws the last error on failure
+- Add a set of unit tests covering success, success after retry, and full failure
+```
+
+Tell it how to change the result — no need to edit by hand:
+
+```
+The backoff uses a fixed value. I want some jitter added to avoid thundering herd. Update the code and the tests.
+```
+
+## Fixing bugs
+
+State the symptom, reproduction conditions, and expected behavior:
+
+```
+Running npm test occasionally throws this error:
+
+  TypeError: Cannot read properties of undefined (reading 'id')
+      at SessionStore.update (src/session/store.ts:142:18)
+
+It only appears in cases that trigger multiple updates concurrently. Locate the cause, fix it, and run the full test suite once at the end to confirm.
+```
+
+Not sure where the cause is? Have it investigate first:
+
+```
+User report: after a successful login, the first page refresh sends them back to the login page; refreshing again works fine. Investigate the possible causes first, list the most suspicious spots, and wait for me to confirm a direction before making any changes.
+```
+
+For mechanical tasks, just hand it off:
+
+```
+Run the tests, fix any failing cases, and run them again to confirm everything is green.
+```
+
+## Writing tests and refactoring
+
+Tasks with clear boundaries and acceptance criteria are a great fit:
+
+```
+src/parser/markdown.ts currently has almost no tests. Add a set of unit tests covering plain paragraphs, nested lists, code blocks, tables, blockquotes, and mixed scenarios. Follow the existing test style in this project.
+```
+
+```
+Extract the repeated "read body → validate → write log → return" logic under src/handlers into a middleware. Run the tests after the changes and make sure existing behavior is unchanged.
+```
+
+For multi-file refactors, use Plan mode to confirm the plan first. Use `/fork` to explore alternative approaches.
+
+## One-off scripts and automation tasks
+
+Bulk edits, statistics, and research can be done with a single prompt:
+
+```
+Change all var declarations in .js files under src/ to const or let, preferring const when possible. Run lint after the changes to confirm.
+```
+
+```
+Analyze the access logs under logs/ for the past 7 days. Group by endpoint path and report the number of calls plus p50 and p99 response times. Output the result as a markdown table.
+```
+
+```
+Research the mainstream dependency injection options in TypeScript (tsyringe, inversify, awilix). Compare them along three dimensions: API style, decorator dependencies, and runtime overhead. Give me a recommendation within one page.
+```
+
+Use `--yolo` or `/yolo` to skip approvals, or set an allow list under [permission configuration](../configuration/config-files.md#permission) for a safer middle ground.
+
+## Generating and maintaining documentation
+
+```
+I just changed the interface signature of src/auth/login.ts. Update the corresponding JSDoc, the example code in the README, and any paragraph that mentions this interface under docs/en/guides.
+```
+
+```
+For every public function under src/api that does not have a docstring, add one. Match the style of the existing comments.
+```
+
+```
+Based on the command implementations under src/cli, generate a draft command reference listing each subcommand, its arguments, and default values. Put it under docs/en/reference for me to review later.
+```
+
+Archive or share a session with `kimi export <sessionId>`.
diff --git a/docs/en/index.md b/docs/en/index.md
new file mode 100644
index 000000000..e82ce8cc9
--- /dev/null
+++ b/docs/en/index.md
@@ -0,0 +1,13 @@
+---
+layout: home
+hero:
+  name: Kimi Code CLI
+  text: The Starting Point for Next-Gen Agents
+  actions:
+    - theme: brand
+      text: Get started
+      link: guides/getting-started
+    - theme: alt
+      text: GitHub
+      link: https://github.com/MoonshotAI/kimi-code
+---
diff --git a/docs/en/reference/keyboard.md b/docs/en/reference/keyboard.md
new file mode 100644
index 000000000..39939cd04
--- /dev/null
+++ b/docs/en/reference/keyboard.md
@@ -0,0 +1,97 @@
+# Keyboard shortcuts
+
+The TUI interactive mode of Kimi Code CLI supports the keyboard shortcuts listed below. These keys primarily take effect inside the input box; some have different behavior inside popups (such as the `/help` panel or the approval panel) or during streaming output.
+
+Type `/help` at any time inside the TUI to open the built-in shortcut list.
+
+## General shortcuts
+
+The following keys are always available in the input box:
+
+| Shortcut | Action |
+| --- | --- |
+| `Enter` | Submit the current input |
+| `Shift-Enter` | Insert a newline in the input |
+| `↑` / `↓` | Browse input history |
+| `Esc` | Close popup / cancel completion / interrupt streaming output or an in-progress context compaction |
+| `Ctrl-C` | Interrupt the current streaming output, or clear the input box |
+| `Ctrl-D` | Exit Kimi Code CLI when the input box is empty |
+
+Pressing `Ctrl-C` **during streaming output** cancels immediately with no second confirmation needed.
+
+**Exiting the program** (pressing `Ctrl-C` when the input box is empty, or pressing `Ctrl-D`) uses a "double-press to confirm" mechanism: the first press shows a hint in the status bar (for example, `Press Ctrl+C again to exit`), and only a second press of the same key actually exits. Pressing any other key in between clears the confirmation state.
+
+## Mode switching
+
+| Shortcut | Action |
+| --- | --- |
+| `Shift-Tab` | Toggle Plan mode |
+
+Press `Shift-Tab` to turn Plan mode on or off. While Plan mode is on, the agent favors read-only tools for research and planning and can write the current plan file; when needed, it can also call `Bash`, which follows the current permission mode and ordinary rules without triggering an extra independent approval just because Plan mode is active. Toggling the mode alone does not create an empty plan file. Press `Shift-Tab` again to leave Plan mode.
+
+## Input and editing
+
+| Shortcut | Action |
+| --- | --- |
+| `Ctrl-G` | Edit the current input in an external editor |
+| `Ctrl-V` | Paste an image or video from the clipboard (Unix / macOS) |
+| `Alt-V` | Paste an image or video from the clipboard (Windows) |
+| `Ctrl-E` | Expand or collapse the Plan card (when no Plan card is present, follows the system default behavior of moving the cursor to the end of the line) |
+| `Ctrl--` | Undo |
+
+Pressing `Ctrl-G` opens an external editor to edit the current input. The editor is chosen in the following order of priority:
+
+1. The editor configured by the `/editor` command
+2. The `$VISUAL` environment variable
+3. The `$EDITOR` environment variable
+
+After saving and exiting the editor, the edited content replaces the input box contents; exiting without saving leaves the input unchanged.
+
+When pasting an image or video, it appears in the input box as a placeholder, and the actual media data is sent to the model together with the message on submit. The preferred source is an image or file path on the system clipboard; on Linux, both Wayland and X11 are tried, and on WSL the Windows clipboard is also read via PowerShell as a fallback.
+
+## During streaming output
+
+While output is streaming, the input box still accepts input and supports the following extra actions:
+
+| Shortcut | Action |
+| --- | --- |
+| `Ctrl-S` | Steer: inject the current input into the running turn immediately |
+| `Esc` | Interrupt the current streaming output |
+| `Ctrl-C` | Interrupt the current streaming output |
+
+When you press `Ctrl-S`, the model sees your message at the next interruptible point, without waiting for the current turn to finish.
+
+## Tool output
+
+| Shortcut | Action |
+| --- | --- |
+| `Ctrl-O` | Expand or collapse tool output |
+
+When collapsed tool call results are present in the history, press `Ctrl-O` to toggle between collapsed and expanded views to inspect the full tool output.
+
+## Approval panel
+
+When the agent issues a tool call that requires confirmation, the TUI shows an approval panel. For the full approval flow, see [Interaction and Input](../guides/interaction.md#approval-flow); the table below lists the keys available inside the panel:
+
+| Shortcut | Action |
+| --- | --- |
+| `↑` / `↓` | Move the cursor between options |
+| `Enter` | Confirm the currently selected option |
+| `1` ~ `9` | Directly select the option with the matching number |
+| `Esc` / `Ctrl-C` / `Ctrl-D` | Reject the current request |
+| `Ctrl-E` | Expand or collapse the full content when the panel includes a diff or file preview |
+| `Ctrl-O` | Toggle the collapsed state of other tool output |
+
+Options that require additional feedback (such as "Reject" or "Revise") switch to a feedback input state after confirmation: type the feedback text directly and press `Enter` to submit, or press `Esc` to exit the feedback input and return to the option list.
+
+## Popup mode
+
+After typing `/help` to open the help panel, the following keys are available to navigate and close the panel:
+
+| Shortcut | Action |
+| --- | --- |
+| `↑` / `↓` | Scroll one line |
+| `PageUp` / `PageDown` | Scroll 10 lines |
+| `Esc` | Close the panel |
+| `Enter` | Close the panel |
+| `q` / `Q` | Close the panel |
diff --git a/docs/en/reference/kimi-command.md b/docs/en/reference/kimi-command.md
new file mode 100644
index 000000000..088e6c34e
--- /dev/null
+++ b/docs/en/reference/kimi-command.md
@@ -0,0 +1,154 @@
+# kimi Command
+
+`kimi` is the main command of Kimi Code CLI, used to start an interactive session in the terminal. When run without any arguments, it opens a new session in the current working directory; with different flags, you can resume a previous session, skip approvals, start in Plan mode, or point at custom Skills directories.
+
+```sh
+kimi [options]
+kimi <subcommand> [options]
+```
+
+## Main command options
+
+The table below lists all options supported by the `kimi` main command. All flags are optional — running `kimi` on its own is enough to enter an interactive session.
+
+| Option | Short | Description |
+| --- | --- | --- |
+| `--version` | `-V` | Print the version number and exit. |
+| `--help` | `-h` | Show help information and exit. |
+| `--session [id]` | `-S` | Resume a session. With an ID, open the specified session directly; without an ID, enter the interactive picker to choose from historical sessions. |
+| `--continue` | `-C` | Continue the most recent session in the current working directory, without manually specifying an ID. |
+| `--model <model>` | `-m` | Use a model alias for this invocation. When omitted, new sessions use `default_model` from the config file, and resumed sessions use the session's current model. |
+| `--prompt <prompt>` | `-p` | Run one prompt non-interactively and stream assistant output to stdout. This mode uses `auto` permission for tool calls and does not open the TUI. |
+| `--output-format <format>` | | Set the non-interactive output format. Supported values are `text` and `stream-json`. Only valid with `--prompt`; defaults to `text`. |
+| `--yolo` | `-y` | Auto-approve ordinary tool calls, skipping approval requests; Plan mode `Bash` approval and Plan mode exit approval are not skipped. |
+| `--plan` | | Start a new session in Plan mode, where the AI favors read-only tools for exploration and planning and can write the current plan file; Plan mode `Bash` is handled separately according to the permission mode. |
+| `--skills-dir <dir>` | | Load Skills from the specified directory, replacing the auto-discovered user and project directories. Can be passed multiple times to stack several directories. See [Custom Skills directories](#custom-skills-directories) below. |
+
+`-r` / `--resume` is a hidden alias for `--session`; `--yes` and `--auto-approve` are hidden aliases for `--yolo`. They do not appear in the help output and behave identically to their official counterparts.
+
+::: warning Note
+`--yolo` skips human confirmation for ordinary tool calls, including file writes and shell command execution. Use it only inside trusted working directories. Plan mode exit approval is not skipped by `--yolo`; in Plan mode, `Bash` also follows the same ordinary allow rules as `--yolo`.
+:::
+
+### Flag conflict rules
+
+The following combinations are rejected at startup:
+
+- `--continue` and `--session` are mutually exclusive: both mean "resume a previous session" and overlap in meaning.
+- `--yolo` cannot be combined with `--continue` or `--session`: when resuming a session, the original session's approval settings are preserved. This rule only applies to interactive mode; in `--prompt` mode, `--yolo` is rejected earlier because it is mutually exclusive with `--prompt`.
+- `--plan` cannot be combined with `--continue` or `--session`: Plan mode only applies to new sessions.
+- `--prompt` cannot be combined with `--yolo` or `--plan`: non-interactive mode always uses `auto` permission and does not enter Plan mode.
+- `--prompt` can be combined with `--continue` or `--session <id>` with an ID; bare `--session` without an ID would open the interactive picker and therefore cannot be used in non-interactive mode.
+- `--output-format` can only be used with `--prompt`; the interactive TUI does not support writing the full event stream as stdout JSONL.
+
+If you need to force YOLO or Plan mode while resuming a session, switch into them from inside the interactive session via slash commands instead.
+
+## Typical usage
+
+The most common entry point is to run `kimi` directly to start a fresh session in the current directory:
+
+```sh
+kimi
+```
+
+If the previous session was interrupted (terminal closed, network disconnected, etc.) and you want to pick up where you left off, use `--continue`:
+
+```sh
+kimi --continue
+```
+
+This automatically finds and resumes the most recent session under the current working directory. To pick a different historical session, run `kimi --session` to enter the interactive picker, or pass a known session ID directly:
+
+```sh
+kimi --session 01HZ...XYZ
+```
+
+When the task is trivial and you don't want to be interrupted by frequent approval requests, add `--yolo`:
+
+```sh
+kimi --yolo
+```
+
+If you want the AI to read the code and produce an implementation plan first, rather than immediately editing files, use `--plan` to enter Plan mode:
+
+```sh
+kimi --plan
+```
+
+### Custom Skills directories
+
+To load custom Skills directories, you have two options:
+
+- **CLI flag `--skills-dir <dir>`**: Can be passed multiple times and **replaces** the auto-discovered user and project directories. Useful for temporary overrides or use in scripts. For example, to mount two directories at once:
+
+  ```sh
+  kimi --skills-dir /path/to/team-skills --skills-dir ./local-skills
+  ```
+
+- **`extra_skill_dirs` in `config.toml`**: Appends extra directories in the config file and **stacks** them with the auto-discovered ones. Suitable for persistent configuration of team-shared Skills (see [Agent Skills](../customization/skills.md)).
+
+## Non-interactive execution
+
+Use `-p` when a script or CI job needs to run one prompt:
+
+```sh
+kimi -p "Summarize the current repository status"
+```
+
+Output uses transcript-style blocks: thinking and assistant text start with `• `, with continuation lines indented by two spaces. Assistant text is written to stdout; thinking, tool progress, and the `To resume this session: kimi -r <id>` hint are written to stderr. Prompt mode does not wait for manual approvals: ordinary tool calls, Plan approvals, and agent questions follow the `auto` permission policy. Static deny rules still block matching tool calls.
+
+To switch models for a single invocation, add `-m`:
+
+```sh
+kimi -m kimi-code/kimi-for-coding -p "Explain the latest diff"
+```
+
+If a script needs structured output, use JSONL:
+
+```sh
+kimi -p "List changed files" --output-format stream-json
+```
+
+In `stream-json` mode, each stdout line is one JSON object. Ordinary replies are emitted as assistant messages. If the model calls tools, the output first includes an assistant message with `tool_calls`, then the corresponding tool message, followed by later assistant messages. Thinking content is not written to JSONL; tool progress and the resume-session hint still go to stderr.
+
+## Subcommands
+
+### `kimi export`
+
+Bundle a session into a ZIP file for sharing, archival, or bug reports. The exported archive contains all files under the session directory, such as context records, state files, and the session diagnostic log if that session has already produced `logs/kimi-code.log`.
+
+```sh
+kimi export [sessionId] [options]
+```
+
+| Argument / Option | Short | Description |
+| --- | --- | --- |
+| `sessionId` | | The ID of the session to export. When omitted, the most recent session under the current working directory is selected automatically and a confirmation is requested. |
+| `--output <path>` | `-o` | Output path for the ZIP file. When omitted, writes to a default filename in the current directory. |
+| `--yes` | `-y` | Skip the confirmation prompt for the default session and export directly. |
+| `--no-include-global-log` | | Skip bundling the active global diagnostic log, `~/.kimi-code/logs/kimi-code.log`. It is included by default. |
+
+By default, export includes files inside the target session directory. If that directory contains `logs/kimi-code.log`, it appears in the ZIP as `logs/kimi-code.log`. The global diagnostic log at `~/.kimi-code/logs/kimi-code.log` is also bundled by default, because it may contain events from other sessions or projects. Add `--no-include-global-log` when you do not want to share it. When included, its ZIP path is `logs/global/kimi-code.log`; rotated files such as `kimi-code.log.1` are not bundled.
+
+When `sessionId` is omitted, the command first prints the session to be exported and asks for confirmation; `-y` skips this prompt, which is handy for scripts:
+
+```sh
+# Export the most recent session under the current working directory, skipping confirmation
+kimi export -y
+
+# Export a specific session to a custom path
+kimi export 01HZ...XYZ -o ./bug-report.zip
+
+# Exclude the global diagnostic log to avoid sharing events from other sessions
+kimi export 01HZ...XYZ -o ./bug-report.zip --no-include-global-log
+```
+
+### `kimi migrate`
+
+Migrate local data from an older version of kimi-cli to kimi-code. This command has no flags and runs fully interactively, guiding you through the entire migration process.
+
+```sh
+kimi migrate
+```
+
+If you previously used an older version of kimi-cli, run this command to migrate historical sessions, configuration, and other data to kimi-code to avoid data loss. For the full migration flow, what gets migrated, and things to watch out for, see [Migrating from kimi-cli](../guides/migration.md).
diff --git a/docs/en/reference/slash-commands.md b/docs/en/reference/slash-commands.md
new file mode 100644
index 000000000..b8aed9047
--- /dev/null
+++ b/docs/en/reference/slash-commands.md
@@ -0,0 +1,86 @@
+# Slash Commands
+
+Slash commands are built-in control commands provided by Kimi Code CLI in the interactive TUI, used to switch modes, manage sessions, view status, and more. Type `/` in the input box to trigger command completion; the candidate list filters in real time as you continue typing, and command aliases participate in matching as well.
+
+After typing a full command name (such as `/help`), press `Enter` to execute it. If the `/`-prefixed input does not match any built-in or skill command, it is sent to the agent as an ordinary message.
+
+::: tip Tip
+Some commands are only available in the idle state. Running them while the session is streaming a response or compacting the context will be blocked, with a hint to press `Esc` or `Ctrl-C` first to interrupt the current operation. The "Always available" column in the tables below marks commands that remain available during streaming or compacting.
+:::
+
+## Account and configuration
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/login` | — | Pick an account or platform and sign in: Kimi Code uses the OAuth device code flow, while the Moonshot AI Open Platform signs in with an API key. | No |
+| `/logout` | — | Clear the credentials of the currently selected account (Kimi Code OAuth credentials, or the corresponding open platform provider config). | No |
+| `/model` | — | Switch the LLM model used by the current session. | Yes |
+| `/settings` | `/config` | Open the settings panel inside the TUI. | Yes |
+| `/permission` | — | Choose a permission mode. | Yes |
+| `/editor` | — | Configure the external editor launched by `Ctrl-G`. | Yes |
+| `/theme` | — | Switch the terminal UI color theme. | Yes |
+
+## Session management
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/new` | `/clear` | Start a brand-new session, discarding the current context. | No |
+| `/sessions` | `/resume` | Browse historical sessions and switch to or resume one. | Yes |
+| `/tasks` | `/task` | Browse the background task list. | Yes |
+| `/fork` | — | Fork a new session from the current one, preserving the full conversation history. | No |
+| `/title [<text>]` | `/rename` | Without arguments, show the current session title; with an argument, set it as the new title (up to 200 characters). | Yes |
+| `/compact [<instruction>]` | — | Compact the current conversation context to free up token usage; optionally pass a custom instruction telling the model what to preserve during compaction. | No |
+| `/init` | — | Analyze the current codebase and generate `AGENTS.md`. | No |
+
+## Mode and runtime control
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/yolo [on\|off]` | `/yes` | Toggle auto-approve mode. Without arguments, flip the current state; pass `on`/`off` explicitly to force the corresponding state. When enabled, ordinary tool call approvals are skipped; the Plan mode exit approval is not skipped. | Yes |
+| `/plan [on\|off]` | — | Toggle Plan mode. Without arguments, flip the current state; pass `on`/`off` explicitly to force the corresponding state. Toggling alone does not create an empty plan file. | Yes |
+| `/plan clear` | — | Clear the current plan. | No |
+
+::: warning Note
+`/yolo` skips approval confirmation for ordinary tool calls. Make sure you understand the potential risks before enabling it. It does not skip the approval required to leave Plan mode; in Plan mode, `Bash` follows the same ordinary allow rules as `/yolo`.
+:::
+
+## Information and status
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/help` | `/h`, `/?` | Show keyboard shortcuts and all available commands. | Yes |
+| `/usage` | — | Show token usage, context consumption, and quota information. | Yes |
+| `/status` | — | Show the current session runtime status, including version, model, working directory, and permission mode. | Yes |
+| `/mcp` | — | List the MCP servers in the current session and their connection status. | Yes |
+| `/version` | — | Show the Kimi Code CLI version number. | Yes |
+| `/feedback` | — | Submit feedback to help improve Kimi Code CLI. | Yes |
+
+## Exit
+
+| Command | Alias | Description | Always available |
+| --- | --- | --- | --- |
+| `/exit` | `/quit`, `/q` | Exit Kimi Code CLI. | No |
+
+## Dynamic skill commands
+
+In addition to the built-in commands, user-activatable skills are automatically registered as slash commands under the `skill:` namespace:
+
+```
+/skill:<name> [extra text]
+```
+
+For example, `/skill:code-style` loads the content of the `code-style` skill and sends it to the agent; any text after the command is appended to the skill prompt, as in `/skill:git-commits fix the login failure issue`.
+
+For convenience, skill commands also support a short form `/<name>` that omits the `skill:` prefix, provided the name is not already taken by a built-in command. In other words, `/code-style` falls back to matching `/skill:code-style`.
+
+Kimi Code CLI ships with a built-in `mcp-config` skill for configuring MCP servers and handling MCP OAuth login. It still belongs to the skill namespace in completion and help (`/skill:mcp-config`), and it can also be invoked directly as `/mcp-config`.
+
+Skill types that can be exposed as slash commands include `prompt`, `inline`, `flow`, and skills without an explicitly declared type. For skill installation and authoring, see [Agent Skills](../customization/skills.md).
+
+::: info Note
+All skill commands are only available while the agent is idle; during streaming or compacting, press `Esc` or `Ctrl-C` first to interrupt the current operation.
+:::
+
+::: info Note
+Flow-type skills are also exposed via `/skill:<name>`; there is no separate `/flow:` namespace.
+:::
diff --git a/docs/en/reference/tools.md b/docs/en/reference/tools.md
new file mode 100644
index 000000000..f113f2072
--- /dev/null
+++ b/docs/en/reference/tools.md
@@ -0,0 +1,104 @@
+# Built-in tools
+
+Built-in tools are the toolset that Kimi Code CLI ships with its core engine — no MCP server installation required. During each conversation, the agent automatically selects and invokes these tools based on the task at hand; users can also inspect every tool call in detail through the approval request interface.
+
+Compared to MCP tools, built-in tools are managed directly by the runtime, their lifecycle is bound to the session, and no external process is needed. Both follow a unified approval mechanism: **read-only tools** (such as `Read`, `Grep`, `Glob`, and `WebSearch`) are auto-approved by default, while **write and execute tools** (such as `Write`, `Edit`, `Bash`, and `TaskStop`) require user approval by default. In YOLO mode, approval for ordinary tool calls is skipped, but exit approval in Plan mode is not affected.
+
+## File tools
+
+File tools handle reading, writing, and searching the local filesystem, and are the foundational tools for code analysis and modification tasks.
+
+| Tool | Default approval | Description |
+| --- | --- | --- |
+| `Read` | Auto-approved | Read the contents of a text file |
+| `Write` | Requires approval | Create or overwrite a file |
+| `Edit` | Requires approval | Exact string replacement |
+| `Grep` | Auto-approved | Full-text search powered by ripgrep |
+| `Glob` | Auto-approved | Find files by glob pattern |
+| `ReadMediaFile` | Auto-approved | Read an image or video file |
+
+**`Read`** accepts a file path (`path`) along with the optional `line_offset` (starting line number; negative values count from the end) and `n_lines` (maximum number of lines to read). At most 1000 lines or 100 KB are returned per call, with a truncation notice appended for anything beyond that limit. If the file is an image or video, the tool suggests using `ReadMediaFile` instead.
+
+**`Write`** accepts `path`, `content`, and an optional `mode` (`overwrite` or `append`; defaults to overwrite). The parent directory must already exist; `append` mode appends content to the end of the file without automatically inserting a newline.
+
+**`Edit`** accepts `path`, `old_string` (the exact text to replace), and `new_string` (the replacement text). By default it replaces only a single unique match; if the same content appears more than once in the file, the tool returns an error and suggests using `replace_all: true`. `old_string` and `new_string` must differ.
+
+**`Grep`** invokes ripgrep to search file contents. It supports regular expressions (`pattern`), a search path (`path`), file-type filtering (`type`, e.g. `ts`, `py`), glob filtering (`glob`), and an output mode (`output_mode`: `files_with_matches` / `content` / `count_matches`, defaulting to `files_with_matches`). `content` mode supports `-A`, `-B`, and `-C` context-line arguments along with `-i` (case-insensitive), `-n` (line numbers, default true), and `multiline` (cross-line matching). All modes support `offset` + `head_limit` pagination; `head_limit` defaults to 250, and passing 0 removes the limit. In `files_with_matches` mode, results are sorted by the most recent file modification time in descending order; other modes preserve ripgrep's original output order. Sensitive files such as `.env`, private keys, `.aws/credentials`, and `.gcp/credentials` are automatically filtered out; `include_ignored=true` also searches files ignored by `.gitignore` and the like, but sensitive files remain filtered.
+
+**`Glob`** matches files against a glob pattern (`pattern`) within a specified directory (`path`, defaulting to the working directory). Results are sorted by modification time in descending order, with a maximum of 1000 entries. The optional `include_dirs` (default true) controls whether directory entries are returned. Pure wildcard patterns (such as `**` or `**/*`) are rejected with a prompt to add a literal anchor; patterns containing brace expansion (`{a,b,c}`) are likewise rejected — the underlying glob engine treats `{` and `}` as literals, so such patterns silently match zero files.
+
+**`ReadMediaFile`** sends an image or video file to the model as multimodal content, accepting only `path`. The file size limit is 100 MB. Tool availability depends on the current model's vision capabilities (`image_in` / `video_in`).
+
+## Shell
+
+| Tool | Default approval | Description |
+| --- | --- | --- |
+| `Bash` | Requires approval | Execute a shell command |
+
+**`Bash`** is the most versatile and the most permission-sensitive tool. It accepts `command` (required) along with the optional `cwd` (working directory), `timeout` (milliseconds), `description` (background task description, required when `run_in_background=true`), `run_in_background` (whether to run as a background task), and `disable_timeout` (whether to disable the timeout for a background task). The foreground `timeout` defaults to 60 seconds and is capped at 5 minutes; the background `timeout` defaults to 10 minutes and is also capped at 10 minutes.
+
+In foreground mode `Bash` blocks the current turn until the command finishes or times out; in background mode it returns a task ID immediately. Background tasks time out after 10 minutes by default; if a task really needs to run without a timeout, set `disable_timeout=true`. When the task completes, fails, or is stopped, the agent is automatically notified to continue processing; during execution, the result can also be inspected explicitly via `TaskOutput`. stdin is always closed, so interactive commands receive EOF immediately. A two-phase termination strategy (SIGTERM → 5-second grace period → SIGKILL) ensures processes terminate reliably after a timeout. On Windows, Git Bash is used as the shell by default.
+
+## Network tools
+
+| Tool | Default approval | Description |
+| --- | --- | --- |
+| `WebSearch` | Auto-approved | Search the web |
+| `FetchURL` | Auto-approved | Fetch the content of a given URL |
+
+**`WebSearch`** accepts `query` (search terms) and the optional `limit` (number of results to return, 1–20, default 5) and `include_content` (whether to return the page body; default false — enabling this consumes significantly more tokens). This tool requires the host to provide a search implementation; if no implementation is injected, it does not appear in the tool list.
+
+**`FetchURL`** accepts a single `url` parameter and returns the page content. For HTML pages, the host extracts the main article body (`extracted`) rather than returning the full HTML; plain-text or Markdown pages are passed through directly (`passthrough`). Likewise requires a host-injected implementation.
+
+## Plan mode
+
+| Tool | Default approval | Description |
+| --- | --- | --- |
+| `EnterPlanMode` | Auto-approved | Enter Plan mode |
+| `ExitPlanMode` | Auto-approved (requires user plan confirmation) | Exit Plan mode and submit the plan |
+
+Plan mode is a constrained working state: once entered, `Write` and `Edit` are tightened — they may only write to the current plan file, and other paths are blocked; `TaskStop` is also blocked entirely. The remaining tools (including `Bash`) are still governed by the current permission rules, so a `Bash` command can in principle still modify files — whether it is allowed depends on the active approval policy.
+
+**`EnterPlanMode`** takes no parameters. On success it returns workflow instructions, including the plan file path if one was provided by the host.
+
+**`ExitPlanMode`** reads the current plan file contents, presents the plan to the user for approval, and then exits Plan mode. The optional `options` parameter lets the agent provide 1–3 alternative proposals (each with a `label` and `description`; the `label` is capped at 80 characters) for the user to choose from during approval. Labels must be unique and cannot use the reserved words `Approve`, `Reject`, `Reject and Exit`, or `Revise` (the system uses these to mark approval results). Once the user approves, all tools become available again; if the user requests changes, the agent remains in Plan mode.
+
+## State management
+
+| Tool | Default approval | Description |
+| --- | --- | --- |
+| `TodoList` | Auto-approved | Manage the task to-do list |
+
+**`TodoList`** maintains a visible subtask list across multi-step operations; state is stored within the agent session. The `todos` parameter accepts an array where each item has a `title` and a `status` (`pending` / `in_progress` / `done`). Omitting `todos` queries the current list; passing an empty array clears it.
+
+## Collaboration tools
+
+Collaboration tools handle inter-agent coordination, user interaction, and skill invocation.
+
+| Tool | Default approval | Description |
+| --- | --- | --- |
+| `Agent` | Auto-approved | Spawn a subagent to execute a subtask |
+| `AskUserQuestion` | Auto-approved | Ask the user a question to obtain structured input |
+| `Skill` | Auto-approved | Invoke a registered inline skill |
+
+**`Agent`** delegates a subtask to a subagent. Required parameters are `prompt` (the full task description) and `description` (a short 3–5 word summary for UI display). Optional parameters include `subagent_type` (agent type, default `coder`), `resume` (the ID of an existing agent to resume), `run_in_background` (whether to run in the background, default false), and `timeout` (timeout in seconds, 30–3600). `subagent_type` and `resume` are mutually exclusive: when resuming an existing agent, addressing is done solely by ID. When the foreground `timeout` is omitted, the subagent runs to completion with no time limit; when the background `timeout` is omitted, it falls back to `[background] agent_task_timeout_s` in `config.toml`, and if that field is also unset, there is no time limit. In foreground mode the parent agent waits for the subagent to complete before continuing; in background mode it returns a task ID immediately, and upon completion a synthetic user message automatically routes control back to the main agent, with no polling required. For details on the subagent system, see [Subagents](../customization/agents.md).
+
+**`AskUserQuestion`** presents the user with a structured multiple-choice question, suitable for disambiguation or option-selection scenarios. The `questions` parameter accepts 1–4 questions; each question requires a `question` (question text ending with `?`), `options` (2–4 choices, each with a `label` and `description`), and the optional `header` (a short category label of up to 12 characters, such as `Auth` or `Style`) and `multi_select` (whether multiple choices are allowed, default false). An "Other" option is automatically appended by the system, so there is no need to provide it manually in `options`. If the host does not implement interactive questioning, this tool returns a failure notice and the agent should instead ask the user directly in its text reply.
+
+**`Skill`** allows the agent to explicitly invoke a registered inline-type skill. It accepts `skill` (the skill name) and an optional `args` (additional argument text). Only skills with `type = "inline"` can be invoked through this tool; other types (such as `prompt` or `flow`) and skills that set `disableModelInvocation: true` in their frontmatter are rejected. To prevent recursive infinite loops, skill nesting depth is limited to 3 levels. For details on the skill system, see [Skills](../customization/skills.md).
+
+## Background tasks
+
+Background task tools manage background tasks started via `Bash` or `Agent`. When a background task reaches a terminal state such as completed, failed, stopped, or lost, its status and tail output are automatically sent back to the agent; use `TaskOutput` only when you want to inspect progress before that automatic notification arrives.
+
+| Tool | Default approval | Description |
+| --- | --- | --- |
+| `TaskList` | Auto-approved | List background tasks |
+| `TaskOutput` | Auto-approved | View the output of a background task |
+| `TaskStop` | Requires approval | Stop a running background task |
+
+**`TaskList`** returns a list of background tasks; each record includes the task ID, status, command, description, and PID. Optional parameters: `active_only` (default true, lists only running tasks) and `limit` (maximum number of entries to return, default 20, range 1–100). Tasks that have reached a terminal state also include `exit_code`; tasks explicitly terminated by `TaskStop` additionally include `reason`.
+
+**`TaskOutput`** returns the status and output of a specified task by `task_id`. The inline preview includes at most the most recent 32 KB of content; the full log is saved on disk, and the tool also returns `output_path` with a prompt to paginate it via `Read` (around 300 lines per page is recommended). Optional `block` (default false) and `timeout` (seconds to wait, default 30, range 0–3600) parameters can be used to wait for the task to finish before returning. In the response, `retrieval_status` is one of `success` / `timeout` / `not_ready`; tasks aborted by an external deadline timeout additionally include `timed_out: true` and `terminal_reason: timed_out`, and tasks explicitly terminated by `TaskStop` additionally include `stop_reason` and `terminal_reason: stopped`.
+
+**`TaskStop`** accepts `task_id` and an optional `reason` (reason for stopping, default `Stopped by TaskStop`). It is safe to call on a task that is already in a terminal state — it returns the current status without error.
diff --git a/docs/en/release-notes/changelog.md b/docs/en/release-notes/changelog.md
new file mode 100644
index 000000000..f1b68dbe0
--- /dev/null
+++ b/docs/en/release-notes/changelog.md
@@ -0,0 +1,5 @@
+# Changelog
+
+::: info Note
+Detailed release notes will be published alongside the first official release.
+:::
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 000000000..f992683cd
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,29 @@
+---
+layout: home
+hero:
+  name: Kimi Code CLI
+  text: ' '
+  actions:
+    - theme: brand
+      text: 简体中文
+      link: zh/
+    - theme: alt
+      text: English
+      link: en/
+---
+
+<script setup>
+import { onMounted } from 'vue'
+import { useRouter, withBase } from 'vitepress'
+
+const router = useRouter()
+
+onMounted(() => {
+  const lang = navigator.language || navigator.userLanguage
+  if (lang.startsWith('en')) {
+    router.go(withBase('/en/'))
+  } else {
+    router.go(withBase('/zh/'))
+  }
+})
+</script>
diff --git a/docs/media/intro.gif b/docs/media/intro.gif
new file mode 100644
index 000000000..1acb1d82b
Binary files /dev/null and b/docs/media/intro.gif differ
diff --git a/docs/package.json b/docs/package.json
new file mode 100644
index 000000000..e8f933887
--- /dev/null
+++ b/docs/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "kimi-code-docs",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "dev": "vitepress dev",
+    "build": "vitepress build",
+    "preview": "vitepress preview"
+  },
+  "devDependencies": {
+    "vitepress": "^1.5.0"
+  },
+  "dependencies": {
+    "mermaid": "^11.12.2",
+    "vitepress-plugin-llms": "^1.10.0",
+    "vitepress-plugin-mermaid": "^2.0.17"
+  }
+}
diff --git a/docs/pnpm-lock.yaml b/docs/pnpm-lock.yaml
new file mode 100644
index 000000000..a6200346d
--- /dev/null
+++ b/docs/pnpm-lock.yaml
@@ -0,0 +1,3179 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      mermaid:
+        specifier: ^11.12.2
+        version: 11.15.0
+      vitepress-plugin-llms:
+        specifier: ^1.10.0
+        version: 1.12.2
+      vitepress-plugin-mermaid:
+        specifier: ^2.0.17
+        version: 2.0.17(mermaid@11.15.0)(vitepress@1.6.4(@algolia/client-search@5.52.1)(postcss@8.5.15)(search-insights@2.17.3))
+    devDependencies:
+      vitepress:
+        specifier: ^1.5.0
+        version: 1.6.4(@algolia/client-search@5.52.1)(postcss@8.5.15)(search-insights@2.17.3)
+
+packages:
+
+  '@algolia/abtesting@1.18.1':
+    resolution: {integrity: sha512-aehCadlWOGvrT91KUIZpC0MbB8KBW9yUuvTJFd2xesR7le/IsT4nJUnjCCZ4ZqZCeTcPHPV5mo//fZ5oxcSVYw==}
+    engines: {node: '>= 14.0.0'}
+
+  '@algolia/autocomplete-core@1.17.7':
+    resolution: {integrity: sha512-BjiPOW6ks90UKl7TwMv7oNQMnzU+t/wk9mgIDi6b1tXpUek7MW0lbNOUHpvam9pe3lVCf4xPFT+lK7s+e+fs7Q==}
+
+  '@algolia/autocomplete-plugin-algolia-insights@1.17.7':
+    resolution: {integrity: sha512-Jca5Ude6yUOuyzjnz57og7Et3aXjbwCSDf/8onLHSQgw1qW3ALl9mrMWaXb5FmPVkV3EtkD2F/+NkT6VHyPu9A==}
+    peerDependencies:
+      search-insights: '>= 1 < 3'
+
+  '@algolia/autocomplete-preset-algolia@1.17.7':
+    resolution: {integrity: sha512-ggOQ950+nwbWROq2MOCIL71RE0DdQZsceqrg32UqnhDz8FlO9rL8ONHNsI2R1MH0tkgVIDKI/D0sMiUchsFdWA==}
+    peerDependencies:
+      '@algolia/client-search': '>= 4.9.1 < 6'
+      algoliasearch: '>= 4.9.1 < 6'
+
+  '@algolia/autocomplete-shared@1.17.7':
+    resolution: {integrity: sha512-o/1Vurr42U/qskRSuhBH+VKxMvkkUVTLU6WZQr+L5lGZZLYWyhdzWjW0iGXY7EkwRTjBqvN2EsR81yCTGV/kmg==}
+    peerDependencies:
+      '@algolia/client-search': '>= 4.9.1 < 6'
+      algoliasearch: '>= 4.9.1 < 6'
+
+  '@algolia/client-abtesting@5.52.1':
+    resolution: {integrity: sha512-HmXOGBOAOJPounpBzBpuY0zDYeiCpxgHnQmuA7JO6ScukcBdGp3/XM9zJk5pJx/xNGD68mbPGXWpDxGtl6BwDQ==}
+    engines: {node: '>= 14.0.0'}
+
+  '@algolia/client-analytics@5.52.1':
+    resolution: {integrity: sha512-5oo4+I8iixie9vXhCyNFCzeIr8pqA3FQ//VsLHTDvZAV4ttYOPGvYHGQq5NSalrLx5Jc3dRro/5uDOlnUMcBJg==}
+    engines: {node: '>= 14.0.0'}
+
+  '@algolia/client-common@5.52.1':
+    resolution: {integrity: sha512-qCDoZfx5MpX7XQzvQ3bC4tSEMkQWQMaF/ABtLuoze03Y/flR563CCSws02qIJ23oX7lxl92LsilZjINVyTdtLw==}
+    engines: {node: '>= 14.0.0'}
+
+  '@algolia/client-insights@5.52.1':
+    resolution: {integrity: sha512-hnGs0/lsFJ2PWDxNBz7pxreXo/Xz7gxYRcfePBUjsH26ad0kU/sgnVZd9LwWBpsQv65z2jlb5dkyaB9WE9M9FQ==}
+    engines: {node: '>= 14.0.0'}
+
+  '@algolia/client-personalization@5.52.1':
+    resolution: {integrity: sha512-2VxxNc/uBysyKvGeBdSM5n9eIDKH8kWD7wd9/yqbJAiVwU4Yv6tU1LSJusHKrXV/aCu1KW7t9Gug9QyeEmtn/Q==}
+    engines: {node: '>= 14.0.0'}
+
+  '@algolia/client-query-suggestions@5.52.1':
+    resolution: {integrity: sha512-O6mPtsw3xEfNOe6gWFpYLeAZAIljNa4Hgna3bq15PwyN7nbjTY0wXJFRbzs/0YVf75Br+SbOQUmjKxXYjDiSiQ==}
+    engines: {node: '>= 14.0.0'}
+
+  '@algolia/client-search@5.52.1':
+    resolution: {integrity: sha512-gA8oJOV1LnQQkDf91iebNnFInHuW0gRPEgLSOQ7EfipCEjYTHm5swm1DlH9H5RaRw4RrHuzHBegnlzc0MAstcg==}
+    engines: {node: '>= 14.0.0'}
+
+  '@algolia/ingestion@1.52.1':
+    resolution: {integrity: sha512-U9zZfc5xIu9wRxZkt+HceJUAD4VKHKbAyLSloJdEyMRmphXeibfrY9cxqIXBcmPeZzGhn3Imb35Dq8l19PkJhw==}
+    engines: {node: '>= 14.0.0'}
+
+  '@algolia/monitoring@1.52.1':
+    resolution: {integrity: sha512-a3SGNceHmkQfq77iG8Ka+w1pvwfZa/0lzEIgse30fL0kD+yKnd/dg0dQvSfFPAEt2f21DMcGkDSSeJlO3KdQjQ==}
+    engines: {node: '>= 14.0.0'}
+
+  '@algolia/recommend@5.52.1':
+    resolution: {integrity: sha512-z98QEguCFDpxb4S/PyrUK1igqF8tPsdbqOUUO6ON91vJ58w+Gwa6ncrI0oNXSFcrkxA5EqPKPQ2A1PBCn08TYQ==}
+    engines: {node: '>= 14.0.0'}
+
+  '@algolia/requester-browser-xhr@5.52.1':
+    resolution: {integrity: sha512-CI7+/0I11QeZM59Uc8whd2or0kqzFVjpaPn9Qpwll/krHcBAxk24WkAQ6WX+IwDVMfpont4YGbKwAmCre3vE8Q==}
+    engines: {node: '>= 14.0.0'}
+
+  '@algolia/requester-fetch@5.52.1':
+    resolution: {integrity: sha512-S6bDuw9byfOvm3T71cgdoZgrgnZq6hpdMLkx52Louh57nUAmvGQESz2aojOynQHjbTiV55smvAFbgn0qT4tJrg==}
+    engines: {node: '>= 14.0.0'}
+
+  '@algolia/requester-node-http@5.52.1':
+    resolution: {integrity: sha512-tqZXM+54rWo4mk5jL5Z/flE11nPmNEdXwFBM5py9DkOmbjeCNemfVd45FyM97XdzfZ0dl9uOJC6PYn1FpkeyQg==}
+    engines: {node: '>= 14.0.0'}
+
+  '@antfu/install-pkg@1.1.0':
+    resolution: {integrity: sha512-MGQsmw10ZyI+EJo45CdSER4zEb+p31LpDAFp2Z3gkSd1yqVZGi0Ebx++YTEMonJy4oChEMLsxZ64j8FH6sSqtQ==}
+
+  '@babel/helper-string-parser@7.27.1':
+    resolution: {integrity: sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-identifier@7.28.5':
+    resolution: {integrity: sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/parser@7.29.3':
+    resolution: {integrity: sha512-b3ctpQwp+PROvU/cttc4OYl4MzfJUWy6FZg+PMXfzmt/+39iHVF0sDfqay8TQM3JA2EUOyKcFZt75jWriQijsA==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  '@babel/types@7.29.0':
+    resolution: {integrity: sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==}
+    engines: {node: '>=6.9.0'}
+
+  '@braintree/sanitize-url@6.0.4':
+    resolution: {integrity: sha512-s3jaWicZd0pkP0jf5ysyHUI/RE7MHos6qlToFcGWXVp+ykHOy77OUMrfbgJ9it2C5bow7OIQwYYaHjk9XlBQ2A==}
+
+  '@braintree/sanitize-url@7.1.2':
+    resolution: {integrity: sha512-jigsZK+sMF/cuiB7sERuo9V7N9jx+dhmHHnQyDSVdpZwVutaBu7WvNYqMDLSgFgfB30n452TP3vjDAvFC973mA==}
+
+  '@chevrotain/types@11.1.2':
+    resolution: {integrity: sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==}
+
+  '@docsearch/css@3.8.2':
+    resolution: {integrity: sha512-y05ayQFyUmCXze79+56v/4HpycYF3uFqB78pLPrSV5ZKAlDuIAAJNhaRi8tTdRNXh05yxX/TyNnzD6LwSM89vQ==}
+
+  '@docsearch/js@3.8.2':
+    resolution: {integrity: sha512-Q5wY66qHn0SwA7Taa0aDbHiJvaFJLOJyHmooQ7y8hlwwQLQ/5WwCcoX0g7ii04Qi2DJlHsd0XXzJ8Ypw9+9YmQ==}
+
+  '@docsearch/react@3.8.2':
+    resolution: {integrity: sha512-xCRrJQlTt8N9GU0DG4ptwHRkfnSnD/YpdeaXe02iKfqs97TkZJv60yE+1eq/tjPcVnTW8dP5qLP7itifFVV5eg==}
+    peerDependencies:
+      '@types/react': '>= 16.8.0 < 19.0.0'
+      react: '>= 16.8.0 < 19.0.0'
+      react-dom: '>= 16.8.0 < 19.0.0'
+      search-insights: '>= 1 < 3'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      react:
+        optional: true
+      react-dom:
+        optional: true
+      search-insights:
+        optional: true
+
+  '@esbuild/aix-ppc64@0.21.5':
+    resolution: {integrity: sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==}
+    engines: {node: '>=12'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.21.5':
+    resolution: {integrity: sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.21.5':
+    resolution: {integrity: sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==}
+    engines: {node: '>=12'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.21.5':
+    resolution: {integrity: sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.21.5':
+    resolution: {integrity: sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.21.5':
+    resolution: {integrity: sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.21.5':
+    resolution: {integrity: sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.21.5':
+    resolution: {integrity: sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.21.5':
+    resolution: {integrity: sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.21.5':
+    resolution: {integrity: sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==}
+    engines: {node: '>=12'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.21.5':
+    resolution: {integrity: sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==}
+    engines: {node: '>=12'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.21.5':
+    resolution: {integrity: sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==}
+    engines: {node: '>=12'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.21.5':
+    resolution: {integrity: sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==}
+    engines: {node: '>=12'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.21.5':
+    resolution: {integrity: sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==}
+    engines: {node: '>=12'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.21.5':
+    resolution: {integrity: sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==}
+    engines: {node: '>=12'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.21.5':
+    resolution: {integrity: sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==}
+    engines: {node: '>=12'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.21.5':
+    resolution: {integrity: sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-x64@0.21.5':
+    resolution: {integrity: sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-x64@0.21.5':
+    resolution: {integrity: sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/sunos-x64@0.21.5':
+    resolution: {integrity: sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.21.5':
+    resolution: {integrity: sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.21.5':
+    resolution: {integrity: sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==}
+    engines: {node: '>=12'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.21.5':
+    resolution: {integrity: sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [win32]
+
+  '@iconify-json/simple-icons@1.2.83':
+    resolution: {integrity: sha512-6Pp9V++XisT9RKH7FB4RLPqUDzcmLtSma0ovOEIoEWGrXtHwBFsH7oN1z8vvCVCb95fb87QgR46/zRLyN9Y3kg==}
+
+  '@iconify/types@2.0.0':
+    resolution: {integrity: sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg==}
+
+  '@iconify/utils@3.1.3':
+    resolution: {integrity: sha512-LPKOXPn/zV+zis1oOfGWogaXVpqUybF3ZS6SCZIsz8vg0ivVp9+fVqyYB7xq0aiST/VhUQYGO1qo6uoYSiEJqw==}
+
+  '@jridgewell/sourcemap-codec@1.5.5':
+    resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==}
+
+  '@mermaid-js/mermaid-mindmap@9.3.0':
+    resolution: {integrity: sha512-IhtYSVBBRYviH1Ehu8gk69pMDF8DSRqXBRDMWrEfHoaMruHeaP2DXA3PBnuwsMaCdPQhlUUcy/7DBLAEIXvCAw==}
+
+  '@mermaid-js/parser@1.1.1':
+    resolution: {integrity: sha512-VuHdsYMK1bT6X2JbcAaWAhugTRvRBRyuZgd+c22swUeI9g/ntaxF7CY7dYarhZovofCbUNO0G7JesfmNtjYOCw==}
+
+  '@rollup/rollup-android-arm-eabi@4.60.4':
+    resolution: {integrity: sha512-F5QXMSiFebS9hKZj02XhWLLnRpJ3B3AROP0tWbFBSj+6kCbg5m9j5JoHKd4mmSVy5mS/IMQloYgYxCuJC0fxEQ==}
+    cpu: [arm]
+    os: [android]
+
+  '@rollup/rollup-android-arm64@4.60.4':
+    resolution: {integrity: sha512-GxxTKApUpzRhof7poWvCJHRF51C67u1R7D6DiluBE8wKU1u5GWE8t+v81JvJYtbawoBFX1hLv5Ei4eVjkWokaw==}
+    cpu: [arm64]
+    os: [android]
+
+  '@rollup/rollup-darwin-arm64@4.60.4':
+    resolution: {integrity: sha512-tua0TaJxMOB1R0V0RS1jFZ/RpURFDJIOR2A6jWwQeawuFyS4gBW+rntLRaQd0EQ4bd6Vp44Z2rXW+YYDBsj6IA==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rollup/rollup-darwin-x64@4.60.4':
+    resolution: {integrity: sha512-CSKq7MsP+5PFIcydhAiR1K0UhEI1A2jWXVKHPCBZ151yOutENwvnPocgVHkivu2kviURtCEB6zUQw0vs8RrhMg==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rollup/rollup-freebsd-arm64@4.60.4':
+    resolution: {integrity: sha512-+O8OkVdyvXMtJEciu2wS/pzm1IxntEEQx3z5TAVy4l32G0etZn+RsA48ARRrFm6Ri8fvqPQfgrvNxSjKAbnd3g==}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@rollup/rollup-freebsd-x64@4.60.4':
+    resolution: {integrity: sha512-Iw3oMskH3AfNuhU0MSN7vNbdi4me/NiYo2azqPz/Le16zHSa+3RRmliCMWWQmh4lcndccU40xcJuTYJZxNo/lw==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rollup/rollup-linux-arm-gnueabihf@4.60.4':
+    resolution: {integrity: sha512-EIPRXTVQpHyF8WOo219AD2yEltPehLTcTMz2fn6JsatLYSzQf00hj3rulF+yauOlF9/FtM2WpkT/hJh/KJFGhA==}
+    cpu: [arm]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm-musleabihf@4.60.4':
+    resolution: {integrity: sha512-J3Yh9PzzF1Ovah2At+lHiGQdsYgArxBbXv/zHfSyaiFQEqvNv7DcW98pCrmdjCZBrqBiKrKKe2V+aaSGWuBe/w==}
+    cpu: [arm]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm64-gnu@4.60.4':
+    resolution: {integrity: sha512-BFDEZMYfUvLn37ONE1yMBojPxnMlTFsdyNoqncT0qFq1mAfllL+ATMMJd8TeuVMiX84s1KbcxcZbXInmcO2mRg==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm64-musl@4.60.4':
+    resolution: {integrity: sha512-pc9EYOSlOgdQ2uPl1o9PF6/kLSgaUosia7gOuS8mB69IxJvlclko1MECXysjs5ryez1/5zjYqx3+xYU0TU6R1A==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rollup/rollup-linux-loong64-gnu@4.60.4':
+    resolution: {integrity: sha512-NxnomyxYerDh5n4iLrNa+sH+Z+U4BMEE46V2PgQ/hoB909i8gV1M5wPojWg9fk1jWpO3IQnOs20K4wyZuFLEFQ==}
+    cpu: [loong64]
+    os: [linux]
+
+  '@rollup/rollup-linux-loong64-musl@4.60.4':
+    resolution: {integrity: sha512-nbJnQ8a3z1mtmrwImCYhc6BGpThAyYVRQxw9uKSKG4wR6aAYno9sVjJ0zaZcW9BPJX1GbrDPf+SvdWjgTuDmnw==}
+    cpu: [loong64]
+    os: [linux]
+
+  '@rollup/rollup-linux-ppc64-gnu@4.60.4':
+    resolution: {integrity: sha512-2EU6acNrQLd8tYvo/LXW535wupT3m6fo7HKo6lr7ktQoItxTyOL1ZCR/GfGCuXl2vR+zmfI6eRXkSemafv+iVg==}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@rollup/rollup-linux-ppc64-musl@4.60.4':
+    resolution: {integrity: sha512-WeBtoMuaMxiiIrO2IYP3xs6GMWkJP2C0EoT8beTLkUPmzV1i/UcOSVw1d5r9KBODtHKilG5yFxsGRnBbK3wJ4A==}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@rollup/rollup-linux-riscv64-gnu@4.60.4':
+    resolution: {integrity: sha512-FJHFfqpKUI3A10WrWKiFbBZ7yVbGT4q4B5o1qKFFojqpaYoh9LrQgqWCmmcxQzVSXYtyB5bzkXrYzlHTs21MYA==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@rollup/rollup-linux-riscv64-musl@4.60.4':
+    resolution: {integrity: sha512-mcEl6CUT5IAUmQf1m9FYSmVqCJlpQ8r8eyftFUHG8i9OhY7BkBXSUdnLH5DOf0wCOjcP9v/QO93zpmF1SptCCw==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@rollup/rollup-linux-s390x-gnu@4.60.4':
+    resolution: {integrity: sha512-ynt3JxVd2w2buzoKDWIyiV1pJW93xlQic1THVLXilz429oijRpSHivZAgp65KBu+cMcgf1eVVjdnTLvPxgCuoQ==}
+    cpu: [s390x]
+    os: [linux]
+
+  '@rollup/rollup-linux-x64-gnu@4.60.4':
+    resolution: {integrity: sha512-Boiz5+MsaROEWDf+GGEwF8VMHGhlUoQMtIPjOgA5fv4osupqTVnJteQNKJwUcnUog2G55jYXH7KZFFiJe0TEzQ==}
+    cpu: [x64]
+    os: [linux]
+
+  '@rollup/rollup-linux-x64-musl@4.60.4':
+    resolution: {integrity: sha512-+qfSY27qIrFfI/Hom04KYFw3GKZSGU4lXus51wsb5EuySfFlWRwjkKWoE9emgRw/ukoT4Udsj4W/+xxG8VbPKg==}
+    cpu: [x64]
+    os: [linux]
+
+  '@rollup/rollup-openbsd-x64@4.60.4':
+    resolution: {integrity: sha512-VpTfOPHgVXEBeeR8hZ2O0F3aSso+JDWqTWmTmzcQKted54IAdUVbxE+j/MVxUsKa8L20HJhv3vUezVPoquqWjA==}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@rollup/rollup-openharmony-arm64@4.60.4':
+    resolution: {integrity: sha512-IPOsh5aRYuLv/nkU51X10Bf75Bsf6+gZdx1X+QP5QM6lIJFHHqbHLG0uJn/hWthzo13UAc2umiUorqZy3axoZg==}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rollup/rollup-win32-arm64-msvc@4.60.4':
+    resolution: {integrity: sha512-4QzE9E81OohJ/HKzHhsqU+zcYYojVOXlFMs1DdyMT6qXl/niOH7AVElmmEdUNHHS/oRkc++d5k6Vy85zFs0DEw==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rollup/rollup-win32-ia32-msvc@4.60.4':
+    resolution: {integrity: sha512-zTPgT1YuHHcd+Tmx7h8aml0FWFVelV5N54oHow9SLj+GfoDy/huQ+UV396N/C7KpMDMiPspRktzM1/0r1usYEA==}
+    cpu: [ia32]
+    os: [win32]
+
+  '@rollup/rollup-win32-x64-gnu@4.60.4':
+    resolution: {integrity: sha512-DRS4G7mi9lJxqEDezIkKCaUIKCrLUUDCUaCsTPCi/rtqaC6D/jjwslMQyiDU50Ka0JKpeXeRBFBAXwArY52vBw==}
+    cpu: [x64]
+    os: [win32]
+
+  '@rollup/rollup-win32-x64-msvc@4.60.4':
+    resolution: {integrity: sha512-QVTUovf40zgTqlFVrKA1uXMVvU2QWEFWfAH8Wdc48IxLvrJMQVMBRjuQyUpzZCDkakImib9eVazbWlC6ksWtJw==}
+    cpu: [x64]
+    os: [win32]
+
+  '@shikijs/core@2.5.0':
+    resolution: {integrity: sha512-uu/8RExTKtavlpH7XqnVYBrfBkUc20ngXiX9NSrBhOVZYv/7XQRKUyhtkeflY5QsxC0GbJThCerruZfsUaSldg==}
+
+  '@shikijs/engine-javascript@2.5.0':
+    resolution: {integrity: sha512-VjnOpnQf8WuCEZtNUdjjwGUbtAVKuZkVQ/5cHy/tojVVRIRtlWMYVjyWhxOmIq05AlSOv72z7hRNRGVBgQOl0w==}
+
+  '@shikijs/engine-oniguruma@2.5.0':
+    resolution: {integrity: sha512-pGd1wRATzbo/uatrCIILlAdFVKdxImWJGQ5rFiB5VZi2ve5xj3Ax9jny8QvkaV93btQEwR/rSz5ERFpC5mKNIw==}
+
+  '@shikijs/langs@2.5.0':
+    resolution: {integrity: sha512-Qfrrt5OsNH5R+5tJ/3uYBBZv3SuGmnRPejV9IlIbFH3HTGLDlkqgHymAlzklVmKBjAaVmkPkyikAV/sQ1wSL+w==}
+
+  '@shikijs/themes@2.5.0':
+    resolution: {integrity: sha512-wGrk+R8tJnO0VMzmUExHR+QdSaPUl/NKs+a4cQQRWyoc3YFbUzuLEi/KWK1hj+8BfHRKm2jNhhJck1dfstJpiw==}
+
+  '@shikijs/transformers@2.5.0':
+    resolution: {integrity: sha512-SI494W5X60CaUwgi8u4q4m4s3YAFSxln3tzNjOSYqq54wlVgz0/NbbXEb3mdLbqMBztcmS7bVTaEd2w0qMmfeg==}
+
+  '@shikijs/types@2.5.0':
+    resolution: {integrity: sha512-ygl5yhxki9ZLNuNpPitBWvcy9fsSKKaRuO4BAlMyagszQidxcpLAr0qiW/q43DtSIDxO6hEbtYLiFZNXO/hdGw==}
+
+  '@shikijs/vscode-textmate@10.0.2':
+    resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==}
+
+  '@types/d3-array@3.2.2':
+    resolution: {integrity: sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw==}
+
+  '@types/d3-axis@3.0.6':
+    resolution: {integrity: sha512-pYeijfZuBd87T0hGn0FO1vQ/cgLk6E1ALJjfkC0oJ8cbwkZl3TpgS8bVBLZN+2jjGgg38epgxb2zmoGtSfvgMw==}
+
+  '@types/d3-brush@3.0.6':
+    resolution: {integrity: sha512-nH60IZNNxEcrh6L1ZSMNA28rj27ut/2ZmI3r96Zd+1jrZD++zD3LsMIjWlvg4AYrHn/Pqz4CF3veCxGjtbqt7A==}
+
+  '@types/d3-chord@3.0.6':
+    resolution: {integrity: sha512-LFYWWd8nwfwEmTZG9PfQxd17HbNPksHBiJHaKuY1XeqscXacsS2tyoo6OdRsjf+NQYeB6XrNL3a25E3gH69lcg==}
+
+  '@types/d3-color@3.1.3':
+    resolution: {integrity: sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==}
+
+  '@types/d3-contour@3.0.6':
+    resolution: {integrity: sha512-BjzLgXGnCWjUSYGfH1cpdo41/hgdWETu4YxpezoztawmqsvCeep+8QGfiY6YbDvfgHz/DkjeIkkZVJavB4a3rg==}
+
+  '@types/d3-delaunay@6.0.4':
+    resolution: {integrity: sha512-ZMaSKu4THYCU6sV64Lhg6qjf1orxBthaC161plr5KuPHo3CNm8DTHiLw/5Eq2b6TsNP0W0iJrUOFscY6Q450Hw==}
+
+  '@types/d3-dispatch@3.0.7':
+    resolution: {integrity: sha512-5o9OIAdKkhN1QItV2oqaE5KMIiXAvDWBDPrD85e58Qlz1c1kI/J0NcqbEG88CoTwJrYe7ntUCVfeUl2UJKbWgA==}
+
+  '@types/d3-drag@3.0.7':
+    resolution: {integrity: sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==}
+
+  '@types/d3-dsv@3.0.7':
+    resolution: {integrity: sha512-n6QBF9/+XASqcKK6waudgL0pf/S5XHPPI8APyMLLUHd8NqouBGLsU8MgtO7NINGtPBtk9Kko/W4ea0oAspwh9g==}
+
+  '@types/d3-ease@3.0.2':
+    resolution: {integrity: sha512-NcV1JjO5oDzoK26oMzbILE6HW7uVXOHLQvHshBUW4UMdZGfiY6v5BeQwh9a9tCzv+CeefZQHJt5SRgK154RtiA==}
+
+  '@types/d3-fetch@3.0.7':
+    resolution: {integrity: sha512-fTAfNmxSb9SOWNB9IoG5c8Hg6R+AzUHDRlsXsDZsNp6sxAEOP0tkP3gKkNSO/qmHPoBFTxNrjDprVHDQDvo5aA==}
+
+  '@types/d3-force@3.0.10':
+    resolution: {integrity: sha512-ZYeSaCF3p73RdOKcjj+swRlZfnYpK1EbaDiYICEEp5Q6sUiqFaFQ9qgoshp5CzIyyb/yD09kD9o2zEltCexlgw==}
+
+  '@types/d3-format@3.0.4':
+    resolution: {integrity: sha512-fALi2aI6shfg7vM5KiR1wNJnZ7r6UuggVqtDA+xiEdPZQwy/trcQaHnwShLuLdta2rTymCNpxYTiMZX/e09F4g==}
+
+  '@types/d3-geo@3.1.0':
+    resolution: {integrity: sha512-856sckF0oP/diXtS4jNsiQw/UuK5fQG8l/a9VVLeSouf1/PPbBE1i1W852zVwKwYCBkFJJB7nCFTbk6UMEXBOQ==}
+
+  '@types/d3-hierarchy@3.1.7':
+    resolution: {integrity: sha512-tJFtNoYBtRtkNysX1Xq4sxtjK8YgoWUNpIiUee0/jHGRwqvzYxkq0hGVbbOGSz+JgFxxRu4K8nb3YpG3CMARtg==}
+
+  '@types/d3-interpolate@3.0.4':
+    resolution: {integrity: sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==}
+
+  '@types/d3-path@3.1.1':
+    resolution: {integrity: sha512-VMZBYyQvbGmWyWVea0EHs/BwLgxc+MKi1zLDCONksozI4YJMcTt8ZEuIR4Sb1MMTE8MMW49v0IwI5+b7RmfWlg==}
+
+  '@types/d3-polygon@3.0.2':
+    resolution: {integrity: sha512-ZuWOtMaHCkN9xoeEMr1ubW2nGWsp4nIql+OPQRstu4ypeZ+zk3YKqQT0CXVe/PYqrKpZAi+J9mTs05TKwjXSRA==}
+
+  '@types/d3-quadtree@3.0.6':
+    resolution: {integrity: sha512-oUzyO1/Zm6rsxKRHA1vH0NEDG58HrT5icx/azi9MF1TWdtttWl0UIUsjEQBBh+SIkrpd21ZjEv7ptxWys1ncsg==}
+
+  '@types/d3-random@3.0.3':
+    resolution: {integrity: sha512-Imagg1vJ3y76Y2ea0871wpabqp613+8/r0mCLEBfdtqC7xMSfj9idOnmBYyMoULfHePJyxMAw3nWhJxzc+LFwQ==}
+
+  '@types/d3-scale-chromatic@3.1.0':
+    resolution: {integrity: sha512-iWMJgwkK7yTRmWqRB5plb1kadXyQ5Sj8V/zYlFGMUBbIPKQScw+Dku9cAAMgJG+z5GYDoMjWGLVOvjghDEFnKQ==}
+
+  '@types/d3-scale@4.0.9':
+    resolution: {integrity: sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw==}
+
+  '@types/d3-selection@3.0.11':
+    resolution: {integrity: sha512-bhAXu23DJWsrI45xafYpkQ4NtcKMwWnAC/vKrd2l+nxMFuvOT3XMYTIj2opv8vq8AO5Yh7Qac/nSeP/3zjTK0w==}
+
+  '@types/d3-shape@3.1.8':
+    resolution: {integrity: sha512-lae0iWfcDeR7qt7rA88BNiqdvPS5pFVPpo5OfjElwNaT2yyekbM0C9vK+yqBqEmHr6lDkRnYNoTBYlAgJa7a4w==}
+
+  '@types/d3-time-format@4.0.3':
+    resolution: {integrity: sha512-5xg9rC+wWL8kdDj153qZcsJ0FWiFt0J5RB6LYUNZjwSnesfblqrI/bJ1wBdJ8OQfncgbJG5+2F+qfqnqyzYxyg==}
+
+  '@types/d3-time@3.0.4':
+    resolution: {integrity: sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g==}
+
+  '@types/d3-timer@3.0.2':
+    resolution: {integrity: sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==}
+
+  '@types/d3-transition@3.0.9':
+    resolution: {integrity: sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==}
+
+  '@types/d3-zoom@3.0.8':
+    resolution: {integrity: sha512-iqMC4/YlFCSlO8+2Ii1GGGliCAY4XdeG748w5vQUbevlbDu0zSjH/+jojorQVBK/se0j6DUFNPBGSqD3YWYnDw==}
+
+  '@types/d3@7.4.3':
+    resolution: {integrity: sha512-lZXZ9ckh5R8uiFVt8ogUNf+pIrK4EsWrx2Np75WvF/eTpJ0FMHNhjXk8CKEx/+gpHbNQyJWehbFaTvqmHWB3ww==}
+
+  '@types/debug@4.1.13':
+    resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==}
+
+  '@types/estree@1.0.8':
+    resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
+
+  '@types/geojson@7946.0.16':
+    resolution: {integrity: sha512-6C8nqWur3j98U6+lXDfTUWIfgvZU+EumvpHKcYjujKH7woYyLj2sUmff0tRhrqM7BohUw7Pz3ZB1jj2gW9Fvmg==}
+
+  '@types/hast@3.0.4':
+    resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==}
+
+  '@types/linkify-it@5.0.0':
+    resolution: {integrity: sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q==}
+
+  '@types/markdown-it@14.1.2':
+    resolution: {integrity: sha512-promo4eFwuiW+TfGxhi+0x3czqTYJkG8qB17ZUJiVF10Xm7NLVRSLUsfRTU/6h1e24VvRnXCx+hG7li58lkzog==}
+
+  '@types/mdast@4.0.4':
+    resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==}
+
+  '@types/mdurl@2.0.0':
+    resolution: {integrity: sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg==}
+
+  '@types/ms@2.1.0':
+    resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==}
+
+  '@types/trusted-types@2.0.7':
+    resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==}
+
+  '@types/unist@3.0.3':
+    resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
+
+  '@types/web-bluetooth@0.0.21':
+    resolution: {integrity: sha512-oIQLCGWtcFZy2JW77j9k8nHzAOpqMHLQejDA48XXMWH6tjCQHz5RCFz1bzsmROyL6PUm+LLnUiI4BCn221inxA==}
+
+  '@ungap/structured-clone@1.3.1':
+    resolution: {integrity: sha512-mUFwbeTqrVgDQxFveS+df2yfap6iuP20NAKAsBt5jDEoOTDew+zwLAOilHCeQJOVSvmgCX4ogqIrA0mnyr08yQ==}
+
+  '@upsetjs/venn.js@2.0.0':
+    resolution: {integrity: sha512-WbBhLrooyePuQ1VZxrJjtLvTc4NVfpOyKx0sKqioq9bX1C1m7Jgykkn8gLrtwumBioXIqam8DLxp88Adbue6Hw==}
+
+  '@vitejs/plugin-vue@5.2.4':
+    resolution: {integrity: sha512-7Yx/SXSOcQq5HiiV3orevHUFn+pmMB4cgbEkDYgnkUWb0WfeQ/wa2yFv6D5ICiCQOVpjA7vYDXrC7AGO8yjDHA==}
+    engines: {node: ^18.0.0 || >=20.0.0}
+    peerDependencies:
+      vite: ^5.0.0 || ^6.0.0
+      vue: ^3.2.25
+
+  '@vue/compiler-core@3.5.34':
+    resolution: {integrity: sha512-s9cLyK5mLcvZ4Agva5QgRsQyLKvts9WbU9DB6NqiZkkGEdwmcEiylj5Jbwkp680drF/NNCV8OlAJSe+yMLxaJw==}
+
+  '@vue/compiler-dom@3.5.34':
+    resolution: {integrity: sha512-EbF/T++k0e2MMZlJsBhzK8Sgwt0HcIPOhzn1CTB/lv6sQcyk+OWf8YeiLxZp3ro7MbbLcAfAJ6sEvjFWuNgUCw==}
+
+  '@vue/compiler-sfc@3.5.34':
+    resolution: {integrity: sha512-D/ihr6uZeIt6r+pVZf46RWT1fAsLFMbUP7k8G1VkiiWexriED9GrX3echHd4Abbt17zjlfiFJ8z7a3BxZOPNjg==}
+
+  '@vue/compiler-ssr@3.5.34':
+    resolution: {integrity: sha512-cDtTHKibkThKGHH1SP+WdccquNRYQDFH6rRjQCqT9G2ltFAfoR5pUftpab/z+aM5mW9HLLVQW7hfKKQe/1GBeQ==}
+
+  '@vue/devtools-api@7.7.9':
+    resolution: {integrity: sha512-kIE8wvwlcZ6TJTbNeU2HQNtaxLx3a84aotTITUuL/4bzfPxzajGBOoqjMhwZJ8L9qFYDU/lAYMEEm11dnZOD6g==}
+
+  '@vue/devtools-kit@7.7.9':
+    resolution: {integrity: sha512-PyQ6odHSgiDVd4hnTP+aDk2X4gl2HmLDfiyEnn3/oV+ckFDuswRs4IbBT7vacMuGdwY/XemxBoh302ctbsptuA==}
+
+  '@vue/devtools-shared@7.7.9':
+    resolution: {integrity: sha512-iWAb0v2WYf0QWmxCGy0seZNDPdO3Sp5+u78ORnyeonS6MT4PC7VPrryX2BpMJrwlDeaZ6BD4vP4XKjK0SZqaeA==}
+
+  '@vue/reactivity@3.5.34':
+    resolution: {integrity: sha512-y9XDjCEuBp+98k+UL5dbYkh57AHU4o6cxZedOPXw3bmrZZYLQsVHguGurq7hVrPCSrQtrnz1f9dssyFr+dMXfQ==}
+
+  '@vue/runtime-core@3.5.34':
+    resolution: {integrity: sha512-mKeBYvu8tcMSLhypAHBmriUFfWXKTCF/23Z4jiCoYK3UtWepkliViNLuR90V9XOyD62mUxs9p1jsrpK3CCGIzw==}
+
+  '@vue/runtime-dom@3.5.34':
+    resolution: {integrity: sha512-e8kZzERmCwUnBRVsgSQlAfrfU2rGoy0FFKPBXSlfEjc/O3KfA7QP0t1/2ZylrbchjmIKB4dPTd07A6WPr0eOrg==}
+
+  '@vue/server-renderer@3.5.34':
+    resolution: {integrity: sha512-nHxmJoTrKsmrkbILRhkC9gY1G3moZbJTqCzDd7DOOzG5KH9oeJ0Unqrff5f9v0pW//jES05ZkJcNtfE8JjOIew==}
+    peerDependencies:
+      vue: 3.5.34
+
+  '@vue/shared@3.5.34':
+    resolution: {integrity: sha512-24uqU4OIiX29ryC3MeWid/Xf2fa2EFRUVLb77nRhk+UrTVrh/XiGtFAFmJBAtBRbjwNdsPRP+jj/OL27Eg1NDA==}
+
+  '@vueuse/core@12.8.2':
+    resolution: {integrity: sha512-HbvCmZdzAu3VGi/pWYm5Ut+Kd9mn1ZHnn4L5G8kOQTPs/IwIAmJoBrmYk2ckLArgMXZj0AW3n5CAejLUO+PhdQ==}
+
+  '@vueuse/integrations@12.8.2':
+    resolution: {integrity: sha512-fbGYivgK5uBTRt7p5F3zy6VrETlV9RtZjBqd1/HxGdjdckBgBM4ugP8LHpjolqTj14TXTxSK1ZfgPbHYyGuH7g==}
+    peerDependencies:
+      async-validator: ^4
+      axios: ^1
+      change-case: ^5
+      drauu: ^0.4
+      focus-trap: ^7
+      fuse.js: ^7
+      idb-keyval: ^6
+      jwt-decode: ^4
+      nprogress: ^0.2
+      qrcode: ^1.5
+      sortablejs: ^1
+      universal-cookie: ^7
+    peerDependenciesMeta:
+      async-validator:
+        optional: true
+      axios:
+        optional: true
+      change-case:
+        optional: true
+      drauu:
+        optional: true
+      focus-trap:
+        optional: true
+      fuse.js:
+        optional: true
+      idb-keyval:
+        optional: true
+      jwt-decode:
+        optional: true
+      nprogress:
+        optional: true
+      qrcode:
+        optional: true
+      sortablejs:
+        optional: true
+      universal-cookie:
+        optional: true
+
+  '@vueuse/metadata@12.8.2':
+    resolution: {integrity: sha512-rAyLGEuoBJ/Il5AmFHiziCPdQzRt88VxR+Y/A/QhJ1EWtWqPBBAxTAFaSkviwEuOEZNtW8pvkPgoCZQ+HxqW1A==}
+
+  '@vueuse/shared@12.8.2':
+    resolution: {integrity: sha512-dznP38YzxZoNloI0qpEfpkms8knDtaoQ6Y/sfS0L7Yki4zh40LFHEhur0odJC6xTHG5dxWVPiUWBXn+wCG2s5w==}
+
+  algoliasearch@5.52.1:
+    resolution: {integrity: sha512-fHA8+kXTbjagw3jkLiaS7KKrH8qe2DyOsiUhGlN4cdT77PEsfqXZl7ewDk1hsg+pJnPlnE50XtLxjR91iJOpmg==}
+    engines: {node: '>= 14.0.0'}
+
+  ansi-regex@5.0.1:
+    resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
+    engines: {node: '>=8'}
+
+  ansi-styles@4.3.0:
+    resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
+    engines: {node: '>=8'}
+
+  argparse@1.0.10:
+    resolution: {integrity: sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==}
+
+  argparse@2.0.1:
+    resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
+
+  bail@2.0.2:
+    resolution: {integrity: sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==}
+
+  balanced-match@4.0.4:
+    resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
+    engines: {node: 18 || 20 || >=22}
+
+  birpc@2.9.0:
+    resolution: {integrity: sha512-KrayHS5pBi69Xi9JmvoqrIgYGDkD6mcSe/i6YKi3w5kekCLzrX4+nawcXqrj2tIp50Kw/mT/s3p+GVK0A0sKxw==}
+
+  brace-expansion@5.0.6:
+    resolution: {integrity: sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==}
+    engines: {node: 18 || 20 || >=22}
+
+  ccount@2.0.1:
+    resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==}
+
+  character-entities-html4@2.1.0:
+    resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==}
+
+  character-entities-legacy@3.0.0:
+    resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==}
+
+  character-entities@2.0.2:
+    resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==}
+
+  cliui@8.0.1:
+    resolution: {integrity: sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==}
+    engines: {node: '>=12'}
+
+  color-convert@2.0.1:
+    resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
+    engines: {node: '>=7.0.0'}
+
+  color-name@1.1.4:
+    resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
+
+  comma-separated-tokens@2.0.3:
+    resolution: {integrity: sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==}
+
+  commander@7.2.0:
+    resolution: {integrity: sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==}
+    engines: {node: '>= 10'}
+
+  commander@8.3.0:
+    resolution: {integrity: sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==}
+    engines: {node: '>= 12'}
+
+  copy-anything@4.0.5:
+    resolution: {integrity: sha512-7Vv6asjS4gMOuILabD3l739tsaxFQmC+a7pLZm02zyvs8p977bL3zEgq3yDk5rn9B0PbYgIv++jmHcuUab4RhA==}
+    engines: {node: '>=18'}
+
+  cose-base@1.0.3:
+    resolution: {integrity: sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg==}
+
+  cose-base@2.2.0:
+    resolution: {integrity: sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g==}
+
+  csstype@3.2.3:
+    resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
+
+  cytoscape-cose-bilkent@4.1.0:
+    resolution: {integrity: sha512-wgQlVIUJF13Quxiv5e1gstZ08rnZj2XaLHGoFMYXz7SkNfCDOOteKBE6SYRfA9WxxI/iBc3ajfDoc6hb/MRAHQ==}
+    peerDependencies:
+      cytoscape: ^3.2.0
+
+  cytoscape-fcose@2.2.0:
+    resolution: {integrity: sha512-ki1/VuRIHFCzxWNrsshHYPs6L7TvLu3DL+TyIGEsRcvVERmxokbf5Gdk7mFxZnTdiGtnA4cfSmjZJMviqSuZrQ==}
+    peerDependencies:
+      cytoscape: ^3.2.0
+
+  cytoscape@3.33.4:
+    resolution: {integrity: sha512-HIN5Pmd9MrX9BkV7tDwnOcEJCSFvCpc8X97h3f508J6I5FsqAY65wKOCvgH2CuP42CaahWaz4tuh32SOOIH7ww==}
+    engines: {node: '>=0.10'}
+
+  d3-array@2.12.1:
+    resolution: {integrity: sha512-B0ErZK/66mHtEsR1TkPEEkwdy+WDesimkM5gpZr5Dsg54BiTA5RXtYW5qTLIAcekaS9xfZrzBLF/OAkB3Qn1YQ==}
+
+  d3-array@3.2.4:
+    resolution: {integrity: sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==}
+    engines: {node: '>=12'}
+
+  d3-axis@3.0.0:
+    resolution: {integrity: sha512-IH5tgjV4jE/GhHkRV0HiVYPDtvfjHQlQfJHs0usq7M30XcSBvOotpmH1IgkcXsO/5gEQZD43B//fc7SRT5S+xw==}
+    engines: {node: '>=12'}
+
+  d3-brush@3.0.0:
+    resolution: {integrity: sha512-ALnjWlVYkXsVIGlOsuWH1+3udkYFI48Ljihfnh8FZPF2QS9o+PzGLBslO0PjzVoHLZ2KCVgAM8NVkXPJB2aNnQ==}
+    engines: {node: '>=12'}
+
+  d3-chord@3.0.1:
+    resolution: {integrity: sha512-VE5S6TNa+j8msksl7HwjxMHDM2yNK3XCkusIlpX5kwauBfXuyLAtNg9jCp/iHH61tgI4sb6R/EIMWCqEIdjT/g==}
+    engines: {node: '>=12'}
+
+  d3-color@3.1.0:
+    resolution: {integrity: sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==}
+    engines: {node: '>=12'}
+
+  d3-contour@4.0.2:
+    resolution: {integrity: sha512-4EzFTRIikzs47RGmdxbeUvLWtGedDUNkTcmzoeyg4sP/dvCexO47AaQL7VKy/gul85TOxw+IBgA8US2xwbToNA==}
+    engines: {node: '>=12'}
+
+  d3-delaunay@6.0.4:
+    resolution: {integrity: sha512-mdjtIZ1XLAM8bm/hx3WwjfHt6Sggek7qH043O8KEjDXN40xi3vx/6pYSVTwLjEgiXQTbvaouWKynLBiUZ6SK6A==}
+    engines: {node: '>=12'}
+
+  d3-dispatch@3.0.1:
+    resolution: {integrity: sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==}
+    engines: {node: '>=12'}
+
+  d3-drag@3.0.0:
+    resolution: {integrity: sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==}
+    engines: {node: '>=12'}
+
+  d3-dsv@3.0.1:
+    resolution: {integrity: sha512-UG6OvdI5afDIFP9w4G0mNq50dSOsXHJaRE8arAS5o9ApWnIElp8GZw1Dun8vP8OyHOZ/QJUKUJwxiiCCnUwm+Q==}
+    engines: {node: '>=12'}
+    hasBin: true
+
+  d3-ease@3.0.1:
+    resolution: {integrity: sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==}
+    engines: {node: '>=12'}
+
+  d3-fetch@3.0.1:
+    resolution: {integrity: sha512-kpkQIM20n3oLVBKGg6oHrUchHM3xODkTzjMoj7aWQFq5QEM+R6E4WkzT5+tojDY7yjez8KgCBRoj4aEr99Fdqw==}
+    engines: {node: '>=12'}
+
+  d3-force@3.0.0:
+    resolution: {integrity: sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg==}
+    engines: {node: '>=12'}
+
+  d3-format@3.1.2:
+    resolution: {integrity: sha512-AJDdYOdnyRDV5b6ArilzCPPwc1ejkHcoyFarqlPqT7zRYjhavcT3uSrqcMvsgh2CgoPbK3RCwyHaVyxYcP2Arg==}
+    engines: {node: '>=12'}
+
+  d3-geo@3.1.1:
+    resolution: {integrity: sha512-637ln3gXKXOwhalDzinUgY83KzNWZRKbYubaG+fGVuc/dxO64RRljtCTnf5ecMyE1RIdtqpkVcq0IbtU2S8j2Q==}
+    engines: {node: '>=12'}
+
+  d3-hierarchy@3.1.2:
+    resolution: {integrity: sha512-FX/9frcub54beBdugHjDCdikxThEqjnR93Qt7PvQTOHxyiNCAlvMrHhclk3cD5VeAaq9fxmfRp+CnWw9rEMBuA==}
+    engines: {node: '>=12'}
+
+  d3-interpolate@3.0.1:
+    resolution: {integrity: sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==}
+    engines: {node: '>=12'}
+
+  d3-path@1.0.9:
+    resolution: {integrity: sha512-VLaYcn81dtHVTjEHd8B+pbe9yHWpXKZUC87PzoFmsFrJqgFwDe/qxfp5MlfsfM1V5E/iVt0MmEbWQ7FVIXh/bg==}
+
+  d3-path@3.1.0:
+    resolution: {integrity: sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==}
+    engines: {node: '>=12'}
+
+  d3-polygon@3.0.1:
+    resolution: {integrity: sha512-3vbA7vXYwfe1SYhED++fPUQlWSYTTGmFmQiany/gdbiWgU/iEyQzyymwL9SkJjFFuCS4902BSzewVGsHHmHtXg==}
+    engines: {node: '>=12'}
+
+  d3-quadtree@3.0.1:
+    resolution: {integrity: sha512-04xDrxQTDTCFwP5H6hRhsRcb9xxv2RzkcsygFzmkSIOJy3PeRJP7sNk3VRIbKXcog561P9oU0/rVH6vDROAgUw==}
+    engines: {node: '>=12'}
+
+  d3-random@3.0.1:
+    resolution: {integrity: sha512-FXMe9GfxTxqd5D6jFsQ+DJ8BJS4E/fT5mqqdjovykEB2oFbTMDVdg1MGFxfQW+FBOGoB++k8swBrgwSHT1cUXQ==}
+    engines: {node: '>=12'}
+
+  d3-sankey@0.12.3:
+    resolution: {integrity: sha512-nQhsBRmM19Ax5xEIPLMY9ZmJ/cDvd1BG3UVvt5h3WRxKg5zGRbvnteTyWAbzeSvlh3tW7ZEmq4VwR5mB3tutmQ==}
+
+  d3-scale-chromatic@3.1.0:
+    resolution: {integrity: sha512-A3s5PWiZ9YCXFye1o246KoscMWqf8BsD9eRiJ3He7C9OBaxKhAd5TFCdEx/7VbKtxxTsu//1mMJFrEt572cEyQ==}
+    engines: {node: '>=12'}
+
+  d3-scale@4.0.2:
+    resolution: {integrity: sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==}
+    engines: {node: '>=12'}
+
+  d3-selection@3.0.0:
+    resolution: {integrity: sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==}
+    engines: {node: '>=12'}
+
+  d3-shape@1.3.7:
+    resolution: {integrity: sha512-EUkvKjqPFUAZyOlhY5gzCxCeI0Aep04LwIRpsZ/mLFelJiUfnK56jo5JMDSE7yyP2kLSb6LtF+S5chMk7uqPqw==}
+
+  d3-shape@3.2.0:
+    resolution: {integrity: sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==}
+    engines: {node: '>=12'}
+
+  d3-time-format@4.1.0:
+    resolution: {integrity: sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg==}
+    engines: {node: '>=12'}
+
+  d3-time@3.1.0:
+    resolution: {integrity: sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==}
+    engines: {node: '>=12'}
+
+  d3-timer@3.0.1:
+    resolution: {integrity: sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==}
+    engines: {node: '>=12'}
+
+  d3-transition@3.0.1:
+    resolution: {integrity: sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==}
+    engines: {node: '>=12'}
+    peerDependencies:
+      d3-selection: 2 - 3
+
+  d3-zoom@3.0.0:
+    resolution: {integrity: sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==}
+    engines: {node: '>=12'}
+
+  d3@7.9.0:
+    resolution: {integrity: sha512-e1U46jVP+w7Iut8Jt8ri1YsPOvFpg46k+K8TpCb0P+zjCkjkPnV7WzfDJzMHy1LnA+wj5pLT1wjO901gLXeEhA==}
+    engines: {node: '>=12'}
+
+  dagre-d3-es@7.0.14:
+    resolution: {integrity: sha512-P4rFMVq9ESWqmOgK+dlXvOtLwYg0i7u0HBGJER0LZDJT2VHIPAMZ/riPxqJceWMStH5+E61QxFra9kIS3AqdMg==}
+
+  dayjs@1.11.20:
+    resolution: {integrity: sha512-YbwwqR/uYpeoP4pu043q+LTDLFBLApUP6VxRihdfNTqu4ubqMlGDLd6ErXhEgsyvY0K6nCs7nggYumAN+9uEuQ==}
+
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  decode-named-character-reference@1.3.0:
+    resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==}
+
+  delaunator@5.1.0:
+    resolution: {integrity: sha512-AGrQ4QSgssa1NGmWmLPqN5NY2KajF5MqxetNEO+o0n3ZwZZeTmt7bBnvzHWrmkZFxGgr4HdyFgelzgi06otLuQ==}
+
+  dequal@2.0.3:
+    resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
+    engines: {node: '>=6'}
+
+  devlop@1.1.0:
+    resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==}
+
+  dompurify@3.4.5:
+    resolution: {integrity: sha512-OrwIBKsdNSVEeubdJ1HBv/wNENRM9ytAVCv7YXt//A3vPdVMNuACRqK9mXCGCBW2ln7BT/A4X0jXHo2Gu89miA==}
+
+  emoji-regex-xs@1.0.0:
+    resolution: {integrity: sha512-LRlerrMYoIDrT6jgpeZ2YYl/L8EulRTt5hQcYjy5AInh7HWXKimpqx68aknBFpGL2+/IcogTcaydJEgaTmOpDg==}
+
+  emoji-regex@8.0.0:
+    resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}
+
+  entities@4.5.0:
+    resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==}
+    engines: {node: '>=0.12'}
+
+  entities@7.0.1:
+    resolution: {integrity: sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==}
+    engines: {node: '>=0.12'}
+
+  es-toolkit@1.46.1:
+    resolution: {integrity: sha512-5eNtXOs3tbfxXOj04tjjseeWkRWaoCjdEI+96DgwzZoe6c9juL49pXlzAFTI72aWC9Y8p7168g6XIKjh7k6pyQ==}
+
+  esbuild@0.21.5:
+    resolution: {integrity: sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==}
+    engines: {node: '>=12'}
+    hasBin: true
+
+  escalade@3.2.0:
+    resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
+    engines: {node: '>=6'}
+
+  escape-string-regexp@5.0.0:
+    resolution: {integrity: sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==}
+    engines: {node: '>=12'}
+
+  esprima@4.0.1:
+    resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==}
+    engines: {node: '>=4'}
+    hasBin: true
+
+  estree-walker@2.0.2:
+    resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==}
+
+  extend-shallow@2.0.1:
+    resolution: {integrity: sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug==}
+    engines: {node: '>=0.10.0'}
+
+  extend@3.0.2:
+    resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==}
+
+  fault@2.0.1:
+    resolution: {integrity: sha512-WtySTkS4OKev5JtpHXnib4Gxiurzh5NCGvWrFaZ34m6JehfTUhKZvn9njTfw48t6JumVQOmrKqpmGcdwxnhqBQ==}
+
+  focus-trap@7.8.0:
+    resolution: {integrity: sha512-/yNdlIkpWbM0ptxno3ONTuf+2g318kh2ez3KSeZN5dZ8YC6AAmgeWz+GasYYiBJPFaYcSAPeu4GfhUaChzIJXA==}
+
+  format@0.2.2:
+    resolution: {integrity: sha512-wzsgA6WOq+09wrU1tsJ09udeR/YZRaeArL9e1wPbFg3GG2yDnC2ldKpxs4xunpFF9DgqCqOIra3bc1HWrJ37Ww==}
+    engines: {node: '>=0.4.x'}
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  get-caller-file@2.0.5:
+    resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==}
+    engines: {node: 6.* || 8.* || >= 10.*}
+
+  gray-matter@4.0.3:
+    resolution: {integrity: sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q==}
+    engines: {node: '>=6.0'}
+
+  hachure-fill@0.5.2:
+    resolution: {integrity: sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg==}
+
+  hast-util-to-html@9.0.5:
+    resolution: {integrity: sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==}
+
+  hast-util-whitespace@3.0.0:
+    resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==}
+
+  hookable@5.5.3:
+    resolution: {integrity: sha512-Yc+BQe8SvoXH1643Qez1zqLRmbA5rCL+sSmk6TVos0LWVfNIB7PGncdlId77WzLGSIB5KaWgTaNTs2lNVEI6VQ==}
+
+  html-void-elements@3.0.0:
+    resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==}
+
+  iconv-lite@0.6.3:
+    resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==}
+    engines: {node: '>=0.10.0'}
+
+  import-meta-resolve@4.2.0:
+    resolution: {integrity: sha512-Iqv2fzaTQN28s/FwZAoFq0ZSs/7hMAHJVX+w8PZl3cY19Pxk6jFFalxQoIfW2826i/fDLXv8IiEZRIT0lDuWcg==}
+
+  internmap@1.0.1:
+    resolution: {integrity: sha512-lDB5YccMydFBtasVtxnZ3MRBHuaoE8GKsppq+EchKL2U4nK/DmEpPHNH8MZe5HkMtpSiTSOZwfN0tzYjO/lJEw==}
+
+  internmap@2.0.3:
+    resolution: {integrity: sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==}
+    engines: {node: '>=12'}
+
+  is-extendable@0.1.1:
+    resolution: {integrity: sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==}
+    engines: {node: '>=0.10.0'}
+
+  is-fullwidth-code-point@3.0.0:
+    resolution: {integrity: sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==}
+    engines: {node: '>=8'}
+
+  is-plain-obj@4.1.0:
+    resolution: {integrity: sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==}
+    engines: {node: '>=12'}
+
+  is-what@5.5.0:
+    resolution: {integrity: sha512-oG7cgbmg5kLYae2N5IVd3jm2s+vldjxJzK1pcu9LfpGuQ93MQSzo0okvRna+7y5ifrD+20FE8FvjusyGaz14fw==}
+    engines: {node: '>=18'}
+
+  js-yaml@3.14.2:
+    resolution: {integrity: sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==}
+    hasBin: true
+
+  katex@0.16.47:
+    resolution: {integrity: sha512-Eeo8Ys1doU1z+x8AZsPpQu+p/QcZBI5PeOo7QGQdy2x2m0MU/hYagBbGOmXwr5KVbEfVuWv9LpnQWeehogurjg==}
+    hasBin: true
+
+  khroma@2.1.0:
+    resolution: {integrity: sha512-Ls993zuzfayK269Svk9hzpeGUKob/sIgZzyHYdjQoAdQetRKpOLj+k/QQQ/6Qi0Yz65mlROrfd+Ev+1+7dz9Kw==}
+
+  kind-of@6.0.3:
+    resolution: {integrity: sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==}
+    engines: {node: '>=0.10.0'}
+
+  layout-base@1.0.2:
+    resolution: {integrity: sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg==}
+
+  layout-base@2.0.1:
+    resolution: {integrity: sha512-dp3s92+uNI1hWIpPGH3jK2kxE2lMjdXdr+DH8ynZHpd6PUlH6x6cbuXnoMmiNumznqaNO31xu9e79F0uuZ0JFg==}
+
+  linkify-it@5.0.0:
+    resolution: {integrity: sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==}
+
+  lodash-es@4.18.1:
+    resolution: {integrity: sha512-J8xewKD/Gk22OZbhpOVSwcs60zhd95ESDwezOFuA3/099925PdHJ7OFHNTGtajL3AlZkykD32HykiMo+BIBI8A==}
+
+  longest-streak@3.1.0:
+    resolution: {integrity: sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==}
+
+  magic-string@0.30.21:
+    resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
+
+  mark.js@8.11.1:
+    resolution: {integrity: sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==}
+
+  markdown-it@14.1.1:
+    resolution: {integrity: sha512-BuU2qnTti9YKgK5N+IeMubp14ZUKUUw7yeJbkjtosvHiP0AZ5c8IAgEMk79D0eC8F23r4Ac/q8cAIFdm2FtyoA==}
+    hasBin: true
+
+  markdown-title@1.0.2:
+    resolution: {integrity: sha512-MqIQVVkz+uGEHi3TsHx/czcxxCbRIL7sv5K5DnYw/tI+apY54IbPefV/cmgxp6LoJSEx/TqcHdLs/298afG5QQ==}
+    engines: {node: '>=6'}
+
+  marked@16.4.2:
+    resolution: {integrity: sha512-TI3V8YYWvkVf3KJe1dRkpnjs68JUPyEa5vjKrp1XEEJUAOaQc+Qj+L1qWbPd0SJuAdQkFU0h73sXXqwDYxsiDA==}
+    engines: {node: '>= 20'}
+    hasBin: true
+
+  mdast-util-from-markdown@2.0.3:
+    resolution: {integrity: sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q==}
+
+  mdast-util-frontmatter@2.0.1:
+    resolution: {integrity: sha512-LRqI9+wdgC25P0URIJY9vwocIzCcksduHQ9OF2joxQoyTNVduwLAFUzjoopuRJbJAReaKrNQKAZKL3uCMugWJA==}
+
+  mdast-util-phrasing@4.1.0:
+    resolution: {integrity: sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==}
+
+  mdast-util-to-hast@13.2.1:
+    resolution: {integrity: sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==}
+
+  mdast-util-to-markdown@2.1.2:
+    resolution: {integrity: sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==}
+
+  mdast-util-to-string@4.0.0:
+    resolution: {integrity: sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==}
+
+  mdurl@2.0.0:
+    resolution: {integrity: sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==}
+
+  mermaid@11.15.0:
+    resolution: {integrity: sha512-pTMbcf3rWdtLiYGpmoTjHEpeY8seiy6sR+9nD7LOs8KfUbHE4lOUAprTRqRAcWSQ6MQpdX+YEsxShtGsINtPtw==}
+
+  micromark-core-commonmark@2.0.3:
+    resolution: {integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==}
+
+  micromark-extension-frontmatter@2.0.0:
+    resolution: {integrity: sha512-C4AkuM3dA58cgZha7zVnuVxBhDsbttIMiytjgsM2XbHAB2faRVaHRle40558FBN+DJcrLNCoqG5mlrpdU4cRtg==}
+
+  micromark-factory-destination@2.0.1:
+    resolution: {integrity: sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==}
+
+  micromark-factory-label@2.0.1:
+    resolution: {integrity: sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==}
+
+  micromark-factory-space@2.0.1:
+    resolution: {integrity: sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==}
+
+  micromark-factory-title@2.0.1:
+    resolution: {integrity: sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==}
+
+  micromark-factory-whitespace@2.0.1:
+    resolution: {integrity: sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==}
+
+  micromark-util-character@2.1.1:
+    resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==}
+
+  micromark-util-chunked@2.0.1:
+    resolution: {integrity: sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==}
+
+  micromark-util-classify-character@2.0.1:
+    resolution: {integrity: sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==}
+
+  micromark-util-combine-extensions@2.0.1:
+    resolution: {integrity: sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==}
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    resolution: {integrity: sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==}
+
+  micromark-util-decode-string@2.0.1:
+    resolution: {integrity: sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==}
+
+  micromark-util-encode@2.0.1:
+    resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==}
+
+  micromark-util-html-tag-name@2.0.1:
+    resolution: {integrity: sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==}
+
+  micromark-util-normalize-identifier@2.0.1:
+    resolution: {integrity: sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==}
+
+  micromark-util-resolve-all@2.0.1:
+    resolution: {integrity: sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==}
+
+  micromark-util-sanitize-uri@2.0.1:
+    resolution: {integrity: sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==}
+
+  micromark-util-subtokenize@2.1.0:
+    resolution: {integrity: sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==}
+
+  micromark-util-symbol@2.0.1:
+    resolution: {integrity: sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==}
+
+  micromark-util-types@2.0.2:
+    resolution: {integrity: sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==}
+
+  micromark@4.0.2:
+    resolution: {integrity: sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==}
+
+  millify@6.1.0:
+    resolution: {integrity: sha512-H/E3J6t+DQs/F2YgfDhxUVZz/dF8JXPPKTLHL/yHCcLZLtCXJDUaqvhJXQwqOVBvbyNn4T0WjLpIHd7PAw7fBA==}
+    hasBin: true
+
+  minimatch@10.2.5:
+    resolution: {integrity: sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==}
+    engines: {node: 18 || 20 || >=22}
+
+  minisearch@7.2.0:
+    resolution: {integrity: sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg==}
+
+  mitt@3.0.1:
+    resolution: {integrity: sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
+  nanoid@3.3.12:
+    resolution: {integrity: sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
+  non-layered-tidy-tree-layout@2.0.2:
+    resolution: {integrity: sha512-gkXMxRzUH+PB0ax9dUN0yYF0S25BqeAYqhgMaLUFmpXLEk7Fcu8f4emJuOAY0V8kjDICxROIKsTAKsV/v355xw==}
+
+  oniguruma-to-es@3.1.1:
+    resolution: {integrity: sha512-bUH8SDvPkH3ho3dvwJwfonjlQ4R80vjyvrU8YpxuROddv55vAEJrTuCuCVUhhsHbtlD9tGGbaNApGQckXhS8iQ==}
+
+  package-manager-detector@1.6.0:
+    resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
+
+  path-data-parser@0.1.0:
+    resolution: {integrity: sha512-NOnmBpt5Y2RWbuv0LMzsayp3lVylAHLPUTut412ZA3l+C4uw4ZVkQbjShYCQ8TCpUMdPapr4YjUqLYD6v68j+w==}
+
+  path-to-regexp@6.3.0:
+    resolution: {integrity: sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ==}
+
+  perfect-debounce@1.0.0:
+    resolution: {integrity: sha512-xCy9V055GLEqoFaHoC1SoLIaLmWctgCUaBaWxDZ7/Zx4CTyX7cJQLJOok/orfjZAh9kEYpjJa4d0KcJmCbctZA==}
+
+  picocolors@1.1.1:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
+
+  points-on-curve@0.2.0:
+    resolution: {integrity: sha512-0mYKnYYe9ZcqMCWhUjItv/oHjvgEsfKvnUTg8sAtnHr3GVy7rGkXCb6d5cSyqrWqL4k81b9CPg3urd+T7aop3A==}
+
+  points-on-path@0.2.1:
+    resolution: {integrity: sha512-25ClnWWuw7JbWZcgqY/gJ4FQWadKxGWk+3kR/7kD0tCaDtPPMj7oHu2ToLaVhfpnHrZzYby2w6tUA0eOIuUg8g==}
+
+  postcss@8.5.15:
+    resolution: {integrity: sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  preact@10.29.2:
+    resolution: {integrity: sha512-7tNmwg/7mzzAoB/8kSg6Hl37JraAZw3Z3A0JSY7VXlZwo82Xn0G7wKbNNs2qoF4ZEEsQGTwDAroNdqKs1ofJxQ==}
+
+  pretty-bytes@7.1.0:
+    resolution: {integrity: sha512-nODzvTiYVRGRqAOvE84Vk5JDPyyxsVk0/fbA/bq7RqlnhksGpset09XTxbpvLTIjoaF7K8Z8DG8yHtKGTPSYRw==}
+    engines: {node: '>=20'}
+
+  property-information@7.1.0:
+    resolution: {integrity: sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==}
+
+  punycode.js@2.3.1:
+    resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==}
+    engines: {node: '>=6'}
+
+  regex-recursion@6.0.2:
+    resolution: {integrity: sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==}
+
+  regex-utilities@2.3.0:
+    resolution: {integrity: sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==}
+
+  regex@6.1.0:
+    resolution: {integrity: sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==}
+
+  remark-frontmatter@5.0.0:
+    resolution: {integrity: sha512-XTFYvNASMe5iPN0719nPrdItC9aU0ssC4v14mH1BCi1u0n1gAocqcujWUrByftZTbLhRtiKRyjYTSIOcr69UVQ==}
+
+  remark-parse@11.0.0:
+    resolution: {integrity: sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==}
+
+  remark-stringify@11.0.0:
+    resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==}
+
+  remark@15.0.1:
+    resolution: {integrity: sha512-Eht5w30ruCXgFmxVUSlNWQ9iiimq07URKeFS3hNc8cUWy1llX4KDWfyEDZRycMc+znsN9Ux5/tJ/BFdgdOwA3A==}
+
+  require-directory@2.1.1:
+    resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
+    engines: {node: '>=0.10.0'}
+
+  rfdc@1.4.1:
+    resolution: {integrity: sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==}
+
+  robust-predicates@3.0.3:
+    resolution: {integrity: sha512-NS3levdsRIUOmiJ8FZWCP7LG3QpJyrs/TE0Zpf1yvZu8cAJJ6QMW92H1c7kWpdIHo8RvmLxN/o2JXTKHp74lUA==}
+
+  rollup@4.60.4:
+    resolution: {integrity: sha512-WHeFSbZYsPu3+bLoNRUuAO+wavNlocOPf3wSHTP7hcFKVnJeWsYlCDbr3mTS14FCizf9ccIxXA8sGL8zKeQN3g==}
+    engines: {node: '>=18.0.0', npm: '>=8.0.0'}
+    hasBin: true
+
+  roughjs@4.6.6:
+    resolution: {integrity: sha512-ZUz/69+SYpFN/g/lUlo2FXcIjRkSu3nDarreVdGGndHEBJ6cXPdKguS8JGxwj5HA5xIbVKSmLgr5b3AWxtRfvQ==}
+
+  rw@1.3.3:
+    resolution: {integrity: sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ==}
+
+  safer-buffer@2.1.2:
+    resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
+
+  search-insights@2.17.3:
+    resolution: {integrity: sha512-RQPdCYTa8A68uM2jwxoY842xDhvx3E5LFL1LxvxCNMev4o5mLuokczhzjAgGwUZBAmOKZknArSxLKmXtIi2AxQ==}
+
+  section-matter@1.0.0:
+    resolution: {integrity: sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==}
+    engines: {node: '>=4'}
+
+  shiki@2.5.0:
+    resolution: {integrity: sha512-mI//trrsaiCIPsja5CNfsyNOqgAZUb6VpJA+340toL42UpzQlXpwRV9nch69X6gaUxrr9kaOOa6e3y3uAkGFxQ==}
+
+  source-map-js@1.2.1:
+    resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
+    engines: {node: '>=0.10.0'}
+
+  space-separated-tokens@2.0.2:
+    resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==}
+
+  speakingurl@14.0.1:
+    resolution: {integrity: sha512-1POYv7uv2gXoyGFpBCmpDVSNV74IfsWlDW216UPjbWufNf+bSU6GdbDsxdcxtfwb4xlI3yxzOTKClUosxARYrQ==}
+    engines: {node: '>=0.10.0'}
+
+  sprintf-js@1.0.3:
+    resolution: {integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==}
+
+  string-width@4.2.3:
+    resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
+    engines: {node: '>=8'}
+
+  stringify-entities@4.0.4:
+    resolution: {integrity: sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==}
+
+  strip-ansi@6.0.1:
+    resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==}
+    engines: {node: '>=8'}
+
+  strip-bom-string@1.0.0:
+    resolution: {integrity: sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g==}
+    engines: {node: '>=0.10.0'}
+
+  stylis@4.4.0:
+    resolution: {integrity: sha512-5Z9ZpRzfuH6l/UAvCPAPUo3665Nk2wLaZU3x+TLHKVzIz33+sbJqbtrYoC3KD4/uVOr2Zp+L0LySezP9OHV9yA==}
+
+  superjson@2.2.6:
+    resolution: {integrity: sha512-H+ue8Zo4vJmV2nRjpx86P35lzwDT3nItnIsocgumgr0hHMQ+ZGq5vrERg9kJBo5AWGmxZDhzDo+WVIJqkB0cGA==}
+    engines: {node: '>=16'}
+
+  tabbable@6.4.0:
+    resolution: {integrity: sha512-05PUHKSNE8ou2dwIxTngl4EzcnsCDZGJ/iCLtDflR/SHB/ny14rXc+qU5P4mG9JkusiV7EivzY9Mhm55AzAvCg==}
+
+  tinyexec@1.1.2:
+    resolution: {integrity: sha512-dAqSqE/RabpBKI8+h26GfLq6Vb3JVXs30XYQjdMjaj/c2tS8IYYMbIzP599KtRj7c57/wYApb3QjgRgXmrCukA==}
+    engines: {node: '>=18'}
+
+  tokenx@1.3.0:
+    resolution: {integrity: sha512-NLdXTEZkKiO0gZuLtMoZKjCXTREXeZZt8nnnNeyoXtNZAfG/GKGSbQtLU5STspc0rMSwcA+UJfWZkbNU01iKmQ==}
+
+  trim-lines@3.0.1:
+    resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==}
+
+  trough@2.2.0:
+    resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==}
+
+  ts-dedent@2.2.0:
+    resolution: {integrity: sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ==}
+    engines: {node: '>=6.10'}
+
+  uc.micro@2.1.0:
+    resolution: {integrity: sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==}
+
+  unified@11.0.5:
+    resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==}
+
+  unist-util-is@6.0.1:
+    resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==}
+
+  unist-util-position@5.0.0:
+    resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==}
+
+  unist-util-remove@4.0.0:
+    resolution: {integrity: sha512-b4gokeGId57UVRX/eVKej5gXqGlc9+trkORhFJpu9raqZkZhU0zm8Doi05+HaiBsMEIJowL+2WtQ5ItjsngPXg==}
+
+  unist-util-stringify-position@4.0.0:
+    resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==}
+
+  unist-util-visit-parents@6.0.2:
+    resolution: {integrity: sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==}
+
+  unist-util-visit@5.1.0:
+    resolution: {integrity: sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==}
+
+  uuid@14.0.0:
+    resolution: {integrity: sha512-Qo+uWgilfSmAhXCMav1uYFynlQO7fMFiMVZsQqZRMIXp0O7rR7qjkj+cPvBHLgBqi960QCoo/PH2/6ZtVqKvrg==}
+    hasBin: true
+
+  vfile-message@4.0.3:
+    resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==}
+
+  vfile@6.0.3:
+    resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==}
+
+  vite@5.4.21:
+    resolution: {integrity: sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==}
+    engines: {node: ^18.0.0 || >=20.0.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^18.0.0 || >=20.0.0
+      less: '*'
+      lightningcss: ^1.21.0
+      sass: '*'
+      sass-embedded: '*'
+      stylus: '*'
+      sugarss: '*'
+      terser: ^5.4.0
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      less:
+        optional: true
+      lightningcss:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+
+  vitepress-plugin-llms@1.12.2:
+    resolution: {integrity: sha512-hdklo7di6E2/MwlYstH7R5QgdPHX+f5G/fp8QBq6MCiw4DWi3IOKMaous0S839FIGsPjK3QHwK6KcFwCf/XzjA==}
+    engines: {node: '>=18.0.0'}
+
+  vitepress-plugin-mermaid@2.0.17:
+    resolution: {integrity: sha512-IUzYpwf61GC6k0XzfmAmNrLvMi9TRrVRMsUyCA8KNXhg/mQ1VqWnO0/tBVPiX5UoKF1mDUwqn5QV4qAJl6JnUg==}
+    peerDependencies:
+      mermaid: 10 || 11
+      vitepress: ^1.0.0 || ^1.0.0-alpha
+
+  vitepress@1.6.4:
+    resolution: {integrity: sha512-+2ym1/+0VVrbhNyRoFFesVvBvHAVMZMK0rw60E3X/5349M1GuVdKeazuksqopEdvkKwKGs21Q729jX81/bkBJg==}
+    hasBin: true
+    peerDependencies:
+      markdown-it-mathjax3: ^4
+      postcss: ^8
+    peerDependenciesMeta:
+      markdown-it-mathjax3:
+        optional: true
+      postcss:
+        optional: true
+
+  vue@3.5.34:
+    resolution: {integrity: sha512-WdLBG9gm02OgJIG9axd5Hpx0TFLdzVgfG2evFFu8Rur5O/IoGc5cMjnjh3tPL6GnRGsYvUhBSKVPYVcxRKpMCA==}
+    peerDependencies:
+      typescript: '*'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
+  wrap-ansi@7.0.0:
+    resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
+    engines: {node: '>=10'}
+
+  y18n@5.0.8:
+    resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
+    engines: {node: '>=10'}
+
+  yargs-parser@21.1.1:
+    resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
+    engines: {node: '>=12'}
+
+  yargs@17.7.2:
+    resolution: {integrity: sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==}
+    engines: {node: '>=12'}
+
+  zwitch@2.0.4:
+    resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==}
+
+snapshots:
+
+  '@algolia/abtesting@1.18.1':
+    dependencies:
+      '@algolia/client-common': 5.52.1
+      '@algolia/requester-browser-xhr': 5.52.1
+      '@algolia/requester-fetch': 5.52.1
+      '@algolia/requester-node-http': 5.52.1
+
+  '@algolia/autocomplete-core@1.17.7(@algolia/client-search@5.52.1)(algoliasearch@5.52.1)(search-insights@2.17.3)':
+    dependencies:
+      '@algolia/autocomplete-plugin-algolia-insights': 1.17.7(@algolia/client-search@5.52.1)(algoliasearch@5.52.1)(search-insights@2.17.3)
+      '@algolia/autocomplete-shared': 1.17.7(@algolia/client-search@5.52.1)(algoliasearch@5.52.1)
+    transitivePeerDependencies:
+      - '@algolia/client-search'
+      - algoliasearch
+      - search-insights
+
+  '@algolia/autocomplete-plugin-algolia-insights@1.17.7(@algolia/client-search@5.52.1)(algoliasearch@5.52.1)(search-insights@2.17.3)':
+    dependencies:
+      '@algolia/autocomplete-shared': 1.17.7(@algolia/client-search@5.52.1)(algoliasearch@5.52.1)
+      search-insights: 2.17.3
+    transitivePeerDependencies:
+      - '@algolia/client-search'
+      - algoliasearch
+
+  '@algolia/autocomplete-preset-algolia@1.17.7(@algolia/client-search@5.52.1)(algoliasearch@5.52.1)':
+    dependencies:
+      '@algolia/autocomplete-shared': 1.17.7(@algolia/client-search@5.52.1)(algoliasearch@5.52.1)
+      '@algolia/client-search': 5.52.1
+      algoliasearch: 5.52.1
+
+  '@algolia/autocomplete-shared@1.17.7(@algolia/client-search@5.52.1)(algoliasearch@5.52.1)':
+    dependencies:
+      '@algolia/client-search': 5.52.1
+      algoliasearch: 5.52.1
+
+  '@algolia/client-abtesting@5.52.1':
+    dependencies:
+      '@algolia/client-common': 5.52.1
+      '@algolia/requester-browser-xhr': 5.52.1
+      '@algolia/requester-fetch': 5.52.1
+      '@algolia/requester-node-http': 5.52.1
+
+  '@algolia/client-analytics@5.52.1':
+    dependencies:
+      '@algolia/client-common': 5.52.1
+      '@algolia/requester-browser-xhr': 5.52.1
+      '@algolia/requester-fetch': 5.52.1
+      '@algolia/requester-node-http': 5.52.1
+
+  '@algolia/client-common@5.52.1': {}
+
+  '@algolia/client-insights@5.52.1':
+    dependencies:
+      '@algolia/client-common': 5.52.1
+      '@algolia/requester-browser-xhr': 5.52.1
+      '@algolia/requester-fetch': 5.52.1
+      '@algolia/requester-node-http': 5.52.1
+
+  '@algolia/client-personalization@5.52.1':
+    dependencies:
+      '@algolia/client-common': 5.52.1
+      '@algolia/requester-browser-xhr': 5.52.1
+      '@algolia/requester-fetch': 5.52.1
+      '@algolia/requester-node-http': 5.52.1
+
+  '@algolia/client-query-suggestions@5.52.1':
+    dependencies:
+      '@algolia/client-common': 5.52.1
+      '@algolia/requester-browser-xhr': 5.52.1
+      '@algolia/requester-fetch': 5.52.1
+      '@algolia/requester-node-http': 5.52.1
+
+  '@algolia/client-search@5.52.1':
+    dependencies:
+      '@algolia/client-common': 5.52.1
+      '@algolia/requester-browser-xhr': 5.52.1
+      '@algolia/requester-fetch': 5.52.1
+      '@algolia/requester-node-http': 5.52.1
+
+  '@algolia/ingestion@1.52.1':
+    dependencies:
+      '@algolia/client-common': 5.52.1
+      '@algolia/requester-browser-xhr': 5.52.1
+      '@algolia/requester-fetch': 5.52.1
+      '@algolia/requester-node-http': 5.52.1
+
+  '@algolia/monitoring@1.52.1':
+    dependencies:
+      '@algolia/client-common': 5.52.1
+      '@algolia/requester-browser-xhr': 5.52.1
+      '@algolia/requester-fetch': 5.52.1
+      '@algolia/requester-node-http': 5.52.1
+
+  '@algolia/recommend@5.52.1':
+    dependencies:
+      '@algolia/client-common': 5.52.1
+      '@algolia/requester-browser-xhr': 5.52.1
+      '@algolia/requester-fetch': 5.52.1
+      '@algolia/requester-node-http': 5.52.1
+
+  '@algolia/requester-browser-xhr@5.52.1':
+    dependencies:
+      '@algolia/client-common': 5.52.1
+
+  '@algolia/requester-fetch@5.52.1':
+    dependencies:
+      '@algolia/client-common': 5.52.1
+
+  '@algolia/requester-node-http@5.52.1':
+    dependencies:
+      '@algolia/client-common': 5.52.1
+
+  '@antfu/install-pkg@1.1.0':
+    dependencies:
+      package-manager-detector: 1.6.0
+      tinyexec: 1.1.2
+
+  '@babel/helper-string-parser@7.27.1': {}
+
+  '@babel/helper-validator-identifier@7.28.5': {}
+
+  '@babel/parser@7.29.3':
+    dependencies:
+      '@babel/types': 7.29.0
+
+  '@babel/types@7.29.0':
+    dependencies:
+      '@babel/helper-string-parser': 7.27.1
+      '@babel/helper-validator-identifier': 7.28.5
+
+  '@braintree/sanitize-url@6.0.4':
+    optional: true
+
+  '@braintree/sanitize-url@7.1.2': {}
+
+  '@chevrotain/types@11.1.2': {}
+
+  '@docsearch/css@3.8.2': {}
+
+  '@docsearch/js@3.8.2(@algolia/client-search@5.52.1)(search-insights@2.17.3)':
+    dependencies:
+      '@docsearch/react': 3.8.2(@algolia/client-search@5.52.1)(search-insights@2.17.3)
+      preact: 10.29.2
+    transitivePeerDependencies:
+      - '@algolia/client-search'
+      - '@types/react'
+      - react
+      - react-dom
+      - search-insights
+
+  '@docsearch/react@3.8.2(@algolia/client-search@5.52.1)(search-insights@2.17.3)':
+    dependencies:
+      '@algolia/autocomplete-core': 1.17.7(@algolia/client-search@5.52.1)(algoliasearch@5.52.1)(search-insights@2.17.3)
+      '@algolia/autocomplete-preset-algolia': 1.17.7(@algolia/client-search@5.52.1)(algoliasearch@5.52.1)
+      '@docsearch/css': 3.8.2
+      algoliasearch: 5.52.1
+    optionalDependencies:
+      search-insights: 2.17.3
+    transitivePeerDependencies:
+      - '@algolia/client-search'
+
+  '@esbuild/aix-ppc64@0.21.5':
+    optional: true
+
+  '@esbuild/android-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/android-arm@0.21.5':
+    optional: true
+
+  '@esbuild/android-x64@0.21.5':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/darwin-x64@0.21.5':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-arm@0.21.5':
+    optional: true
+
+  '@esbuild/linux-ia32@0.21.5':
+    optional: true
+
+  '@esbuild/linux-loong64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.21.5':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-s390x@0.21.5':
+    optional: true
+
+  '@esbuild/linux-x64@0.21.5':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.21.5':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.21.5':
+    optional: true
+
+  '@esbuild/sunos-x64@0.21.5':
+    optional: true
+
+  '@esbuild/win32-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/win32-ia32@0.21.5':
+    optional: true
+
+  '@esbuild/win32-x64@0.21.5':
+    optional: true
+
+  '@iconify-json/simple-icons@1.2.83':
+    dependencies:
+      '@iconify/types': 2.0.0
+
+  '@iconify/types@2.0.0': {}
+
+  '@iconify/utils@3.1.3':
+    dependencies:
+      '@antfu/install-pkg': 1.1.0
+      '@iconify/types': 2.0.0
+      import-meta-resolve: 4.2.0
+
+  '@jridgewell/sourcemap-codec@1.5.5': {}
+
+  '@mermaid-js/mermaid-mindmap@9.3.0':
+    dependencies:
+      '@braintree/sanitize-url': 6.0.4
+      cytoscape: 3.33.4
+      cytoscape-cose-bilkent: 4.1.0(cytoscape@3.33.4)
+      cytoscape-fcose: 2.2.0(cytoscape@3.33.4)
+      d3: 7.9.0
+      khroma: 2.1.0
+      non-layered-tidy-tree-layout: 2.0.2
+    optional: true
+
+  '@mermaid-js/parser@1.1.1':
+    dependencies:
+      '@chevrotain/types': 11.1.2
+
+  '@rollup/rollup-android-arm-eabi@4.60.4':
+    optional: true
+
+  '@rollup/rollup-android-arm64@4.60.4':
+    optional: true
+
+  '@rollup/rollup-darwin-arm64@4.60.4':
+    optional: true
+
+  '@rollup/rollup-darwin-x64@4.60.4':
+    optional: true
+
+  '@rollup/rollup-freebsd-arm64@4.60.4':
+    optional: true
+
+  '@rollup/rollup-freebsd-x64@4.60.4':
+    optional: true
+
+  '@rollup/rollup-linux-arm-gnueabihf@4.60.4':
+    optional: true
+
+  '@rollup/rollup-linux-arm-musleabihf@4.60.4':
+    optional: true
+
+  '@rollup/rollup-linux-arm64-gnu@4.60.4':
+    optional: true
+
+  '@rollup/rollup-linux-arm64-musl@4.60.4':
+    optional: true
+
+  '@rollup/rollup-linux-loong64-gnu@4.60.4':
+    optional: true
+
+  '@rollup/rollup-linux-loong64-musl@4.60.4':
+    optional: true
+
+  '@rollup/rollup-linux-ppc64-gnu@4.60.4':
+    optional: true
+
+  '@rollup/rollup-linux-ppc64-musl@4.60.4':
+    optional: true
+
+  '@rollup/rollup-linux-riscv64-gnu@4.60.4':
+    optional: true
+
+  '@rollup/rollup-linux-riscv64-musl@4.60.4':
+    optional: true
+
+  '@rollup/rollup-linux-s390x-gnu@4.60.4':
+    optional: true
+
+  '@rollup/rollup-linux-x64-gnu@4.60.4':
+    optional: true
+
+  '@rollup/rollup-linux-x64-musl@4.60.4':
+    optional: true
+
+  '@rollup/rollup-openbsd-x64@4.60.4':
+    optional: true
+
+  '@rollup/rollup-openharmony-arm64@4.60.4':
+    optional: true
+
+  '@rollup/rollup-win32-arm64-msvc@4.60.4':
+    optional: true
+
+  '@rollup/rollup-win32-ia32-msvc@4.60.4':
+    optional: true
+
+  '@rollup/rollup-win32-x64-gnu@4.60.4':
+    optional: true
+
+  '@rollup/rollup-win32-x64-msvc@4.60.4':
+    optional: true
+
+  '@shikijs/core@2.5.0':
+    dependencies:
+      '@shikijs/engine-javascript': 2.5.0
+      '@shikijs/engine-oniguruma': 2.5.0
+      '@shikijs/types': 2.5.0
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.4
+      hast-util-to-html: 9.0.5
+
+  '@shikijs/engine-javascript@2.5.0':
+    dependencies:
+      '@shikijs/types': 2.5.0
+      '@shikijs/vscode-textmate': 10.0.2
+      oniguruma-to-es: 3.1.1
+
+  '@shikijs/engine-oniguruma@2.5.0':
+    dependencies:
+      '@shikijs/types': 2.5.0
+      '@shikijs/vscode-textmate': 10.0.2
+
+  '@shikijs/langs@2.5.0':
+    dependencies:
+      '@shikijs/types': 2.5.0
+
+  '@shikijs/themes@2.5.0':
+    dependencies:
+      '@shikijs/types': 2.5.0
+
+  '@shikijs/transformers@2.5.0':
+    dependencies:
+      '@shikijs/core': 2.5.0
+      '@shikijs/types': 2.5.0
+
+  '@shikijs/types@2.5.0':
+    dependencies:
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.4
+
+  '@shikijs/vscode-textmate@10.0.2': {}
+
+  '@types/d3-array@3.2.2': {}
+
+  '@types/d3-axis@3.0.6':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-brush@3.0.6':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-chord@3.0.6': {}
+
+  '@types/d3-color@3.1.3': {}
+
+  '@types/d3-contour@3.0.6':
+    dependencies:
+      '@types/d3-array': 3.2.2
+      '@types/geojson': 7946.0.16
+
+  '@types/d3-delaunay@6.0.4': {}
+
+  '@types/d3-dispatch@3.0.7': {}
+
+  '@types/d3-drag@3.0.7':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-dsv@3.0.7': {}
+
+  '@types/d3-ease@3.0.2': {}
+
+  '@types/d3-fetch@3.0.7':
+    dependencies:
+      '@types/d3-dsv': 3.0.7
+
+  '@types/d3-force@3.0.10': {}
+
+  '@types/d3-format@3.0.4': {}
+
+  '@types/d3-geo@3.1.0':
+    dependencies:
+      '@types/geojson': 7946.0.16
+
+  '@types/d3-hierarchy@3.1.7': {}
+
+  '@types/d3-interpolate@3.0.4':
+    dependencies:
+      '@types/d3-color': 3.1.3
+
+  '@types/d3-path@3.1.1': {}
+
+  '@types/d3-polygon@3.0.2': {}
+
+  '@types/d3-quadtree@3.0.6': {}
+
+  '@types/d3-random@3.0.3': {}
+
+  '@types/d3-scale-chromatic@3.1.0': {}
+
+  '@types/d3-scale@4.0.9':
+    dependencies:
+      '@types/d3-time': 3.0.4
+
+  '@types/d3-selection@3.0.11': {}
+
+  '@types/d3-shape@3.1.8':
+    dependencies:
+      '@types/d3-path': 3.1.1
+
+  '@types/d3-time-format@4.0.3': {}
+
+  '@types/d3-time@3.0.4': {}
+
+  '@types/d3-timer@3.0.2': {}
+
+  '@types/d3-transition@3.0.9':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-zoom@3.0.8':
+    dependencies:
+      '@types/d3-interpolate': 3.0.4
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3@7.4.3':
+    dependencies:
+      '@types/d3-array': 3.2.2
+      '@types/d3-axis': 3.0.6
+      '@types/d3-brush': 3.0.6
+      '@types/d3-chord': 3.0.6
+      '@types/d3-color': 3.1.3
+      '@types/d3-contour': 3.0.6
+      '@types/d3-delaunay': 6.0.4
+      '@types/d3-dispatch': 3.0.7
+      '@types/d3-drag': 3.0.7
+      '@types/d3-dsv': 3.0.7
+      '@types/d3-ease': 3.0.2
+      '@types/d3-fetch': 3.0.7
+      '@types/d3-force': 3.0.10
+      '@types/d3-format': 3.0.4
+      '@types/d3-geo': 3.1.0
+      '@types/d3-hierarchy': 3.1.7
+      '@types/d3-interpolate': 3.0.4
+      '@types/d3-path': 3.1.1
+      '@types/d3-polygon': 3.0.2
+      '@types/d3-quadtree': 3.0.6
+      '@types/d3-random': 3.0.3
+      '@types/d3-scale': 4.0.9
+      '@types/d3-scale-chromatic': 3.1.0
+      '@types/d3-selection': 3.0.11
+      '@types/d3-shape': 3.1.8
+      '@types/d3-time': 3.0.4
+      '@types/d3-time-format': 4.0.3
+      '@types/d3-timer': 3.0.2
+      '@types/d3-transition': 3.0.9
+      '@types/d3-zoom': 3.0.8
+
+  '@types/debug@4.1.13':
+    dependencies:
+      '@types/ms': 2.1.0
+
+  '@types/estree@1.0.8': {}
+
+  '@types/geojson@7946.0.16': {}
+
+  '@types/hast@3.0.4':
+    dependencies:
+      '@types/unist': 3.0.3
+
+  '@types/linkify-it@5.0.0': {}
+
+  '@types/markdown-it@14.1.2':
+    dependencies:
+      '@types/linkify-it': 5.0.0
+      '@types/mdurl': 2.0.0
+
+  '@types/mdast@4.0.4':
+    dependencies:
+      '@types/unist': 3.0.3
+
+  '@types/mdurl@2.0.0': {}
+
+  '@types/ms@2.1.0': {}
+
+  '@types/trusted-types@2.0.7':
+    optional: true
+
+  '@types/unist@3.0.3': {}
+
+  '@types/web-bluetooth@0.0.21': {}
+
+  '@ungap/structured-clone@1.3.1': {}
+
+  '@upsetjs/venn.js@2.0.0':
+    optionalDependencies:
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
+  '@vitejs/plugin-vue@5.2.4(vite@5.4.21)(vue@3.5.34)':
+    dependencies:
+      vite: 5.4.21
+      vue: 3.5.34
+
+  '@vue/compiler-core@3.5.34':
+    dependencies:
+      '@babel/parser': 7.29.3
+      '@vue/shared': 3.5.34
+      entities: 7.0.1
+      estree-walker: 2.0.2
+      source-map-js: 1.2.1
+
+  '@vue/compiler-dom@3.5.34':
+    dependencies:
+      '@vue/compiler-core': 3.5.34
+      '@vue/shared': 3.5.34
+
+  '@vue/compiler-sfc@3.5.34':
+    dependencies:
+      '@babel/parser': 7.29.3
+      '@vue/compiler-core': 3.5.34
+      '@vue/compiler-dom': 3.5.34
+      '@vue/compiler-ssr': 3.5.34
+      '@vue/shared': 3.5.34
+      estree-walker: 2.0.2
+      magic-string: 0.30.21
+      postcss: 8.5.15
+      source-map-js: 1.2.1
+
+  '@vue/compiler-ssr@3.5.34':
+    dependencies:
+      '@vue/compiler-dom': 3.5.34
+      '@vue/shared': 3.5.34
+
+  '@vue/devtools-api@7.7.9':
+    dependencies:
+      '@vue/devtools-kit': 7.7.9
+
+  '@vue/devtools-kit@7.7.9':
+    dependencies:
+      '@vue/devtools-shared': 7.7.9
+      birpc: 2.9.0
+      hookable: 5.5.3
+      mitt: 3.0.1
+      perfect-debounce: 1.0.0
+      speakingurl: 14.0.1
+      superjson: 2.2.6
+
+  '@vue/devtools-shared@7.7.9':
+    dependencies:
+      rfdc: 1.4.1
+
+  '@vue/reactivity@3.5.34':
+    dependencies:
+      '@vue/shared': 3.5.34
+
+  '@vue/runtime-core@3.5.34':
+    dependencies:
+      '@vue/reactivity': 3.5.34
+      '@vue/shared': 3.5.34
+
+  '@vue/runtime-dom@3.5.34':
+    dependencies:
+      '@vue/reactivity': 3.5.34
+      '@vue/runtime-core': 3.5.34
+      '@vue/shared': 3.5.34
+      csstype: 3.2.3
+
+  '@vue/server-renderer@3.5.34(vue@3.5.34)':
+    dependencies:
+      '@vue/compiler-ssr': 3.5.34
+      '@vue/shared': 3.5.34
+      vue: 3.5.34
+
+  '@vue/shared@3.5.34': {}
+
+  '@vueuse/core@12.8.2':
+    dependencies:
+      '@types/web-bluetooth': 0.0.21
+      '@vueuse/metadata': 12.8.2
+      '@vueuse/shared': 12.8.2
+      vue: 3.5.34
+    transitivePeerDependencies:
+      - typescript
+
+  '@vueuse/integrations@12.8.2(focus-trap@7.8.0)':
+    dependencies:
+      '@vueuse/core': 12.8.2
+      '@vueuse/shared': 12.8.2
+      vue: 3.5.34
+    optionalDependencies:
+      focus-trap: 7.8.0
+    transitivePeerDependencies:
+      - typescript
+
+  '@vueuse/metadata@12.8.2': {}
+
+  '@vueuse/shared@12.8.2':
+    dependencies:
+      vue: 3.5.34
+    transitivePeerDependencies:
+      - typescript
+
+  algoliasearch@5.52.1:
+    dependencies:
+      '@algolia/abtesting': 1.18.1
+      '@algolia/client-abtesting': 5.52.1
+      '@algolia/client-analytics': 5.52.1
+      '@algolia/client-common': 5.52.1
+      '@algolia/client-insights': 5.52.1
+      '@algolia/client-personalization': 5.52.1
+      '@algolia/client-query-suggestions': 5.52.1
+      '@algolia/client-search': 5.52.1
+      '@algolia/ingestion': 1.52.1
+      '@algolia/monitoring': 1.52.1
+      '@algolia/recommend': 5.52.1
+      '@algolia/requester-browser-xhr': 5.52.1
+      '@algolia/requester-fetch': 5.52.1
+      '@algolia/requester-node-http': 5.52.1
+
+  ansi-regex@5.0.1: {}
+
+  ansi-styles@4.3.0:
+    dependencies:
+      color-convert: 2.0.1
+
+  argparse@1.0.10:
+    dependencies:
+      sprintf-js: 1.0.3
+
+  argparse@2.0.1: {}
+
+  bail@2.0.2: {}
+
+  balanced-match@4.0.4: {}
+
+  birpc@2.9.0: {}
+
+  brace-expansion@5.0.6:
+    dependencies:
+      balanced-match: 4.0.4
+
+  ccount@2.0.1: {}
+
+  character-entities-html4@2.1.0: {}
+
+  character-entities-legacy@3.0.0: {}
+
+  character-entities@2.0.2: {}
+
+  cliui@8.0.1:
+    dependencies:
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+      wrap-ansi: 7.0.0
+
+  color-convert@2.0.1:
+    dependencies:
+      color-name: 1.1.4
+
+  color-name@1.1.4: {}
+
+  comma-separated-tokens@2.0.3: {}
+
+  commander@7.2.0: {}
+
+  commander@8.3.0: {}
+
+  copy-anything@4.0.5:
+    dependencies:
+      is-what: 5.5.0
+
+  cose-base@1.0.3:
+    dependencies:
+      layout-base: 1.0.2
+
+  cose-base@2.2.0:
+    dependencies:
+      layout-base: 2.0.1
+
+  csstype@3.2.3: {}
+
+  cytoscape-cose-bilkent@4.1.0(cytoscape@3.33.4):
+    dependencies:
+      cose-base: 1.0.3
+      cytoscape: 3.33.4
+
+  cytoscape-fcose@2.2.0(cytoscape@3.33.4):
+    dependencies:
+      cose-base: 2.2.0
+      cytoscape: 3.33.4
+
+  cytoscape@3.33.4: {}
+
+  d3-array@2.12.1:
+    dependencies:
+      internmap: 1.0.1
+
+  d3-array@3.2.4:
+    dependencies:
+      internmap: 2.0.3
+
+  d3-axis@3.0.0: {}
+
+  d3-brush@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
+  d3-chord@3.0.1:
+    dependencies:
+      d3-path: 3.1.0
+
+  d3-color@3.1.0: {}
+
+  d3-contour@4.0.2:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-delaunay@6.0.4:
+    dependencies:
+      delaunator: 5.1.0
+
+  d3-dispatch@3.0.1: {}
+
+  d3-drag@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-selection: 3.0.0
+
+  d3-dsv@3.0.1:
+    dependencies:
+      commander: 7.2.0
+      iconv-lite: 0.6.3
+      rw: 1.3.3
+
+  d3-ease@3.0.1: {}
+
+  d3-fetch@3.0.1:
+    dependencies:
+      d3-dsv: 3.0.1
+
+  d3-force@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-quadtree: 3.0.1
+      d3-timer: 3.0.1
+
+  d3-format@3.1.2: {}
+
+  d3-geo@3.1.1:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-hierarchy@3.1.2: {}
+
+  d3-interpolate@3.0.1:
+    dependencies:
+      d3-color: 3.1.0
+
+  d3-path@1.0.9: {}
+
+  d3-path@3.1.0: {}
+
+  d3-polygon@3.0.1: {}
+
+  d3-quadtree@3.0.1: {}
+
+  d3-random@3.0.1: {}
+
+  d3-sankey@0.12.3:
+    dependencies:
+      d3-array: 2.12.1
+      d3-shape: 1.3.7
+
+  d3-scale-chromatic@3.1.0:
+    dependencies:
+      d3-color: 3.1.0
+      d3-interpolate: 3.0.1
+
+  d3-scale@4.0.2:
+    dependencies:
+      d3-array: 3.2.4
+      d3-format: 3.1.2
+      d3-interpolate: 3.0.1
+      d3-time: 3.1.0
+      d3-time-format: 4.1.0
+
+  d3-selection@3.0.0: {}
+
+  d3-shape@1.3.7:
+    dependencies:
+      d3-path: 1.0.9
+
+  d3-shape@3.2.0:
+    dependencies:
+      d3-path: 3.1.0
+
+  d3-time-format@4.1.0:
+    dependencies:
+      d3-time: 3.1.0
+
+  d3-time@3.1.0:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-timer@3.0.1: {}
+
+  d3-transition@3.0.1(d3-selection@3.0.0):
+    dependencies:
+      d3-color: 3.1.0
+      d3-dispatch: 3.0.1
+      d3-ease: 3.0.1
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-timer: 3.0.1
+
+  d3-zoom@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
+  d3@7.9.0:
+    dependencies:
+      d3-array: 3.2.4
+      d3-axis: 3.0.0
+      d3-brush: 3.0.0
+      d3-chord: 3.0.1
+      d3-color: 3.1.0
+      d3-contour: 4.0.2
+      d3-delaunay: 6.0.4
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-dsv: 3.0.1
+      d3-ease: 3.0.1
+      d3-fetch: 3.0.1
+      d3-force: 3.0.0
+      d3-format: 3.1.2
+      d3-geo: 3.1.1
+      d3-hierarchy: 3.1.2
+      d3-interpolate: 3.0.1
+      d3-path: 3.1.0
+      d3-polygon: 3.0.1
+      d3-quadtree: 3.0.1
+      d3-random: 3.0.1
+      d3-scale: 4.0.2
+      d3-scale-chromatic: 3.1.0
+      d3-selection: 3.0.0
+      d3-shape: 3.2.0
+      d3-time: 3.1.0
+      d3-time-format: 4.1.0
+      d3-timer: 3.0.1
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+      d3-zoom: 3.0.0
+
+  dagre-d3-es@7.0.14:
+    dependencies:
+      d3: 7.9.0
+      lodash-es: 4.18.1
+
+  dayjs@1.11.20: {}
+
+  debug@4.4.3:
+    dependencies:
+      ms: 2.1.3
+
+  decode-named-character-reference@1.3.0:
+    dependencies:
+      character-entities: 2.0.2
+
+  delaunator@5.1.0:
+    dependencies:
+      robust-predicates: 3.0.3
+
+  dequal@2.0.3: {}
+
+  devlop@1.1.0:
+    dependencies:
+      dequal: 2.0.3
+
+  dompurify@3.4.5:
+    optionalDependencies:
+      '@types/trusted-types': 2.0.7
+
+  emoji-regex-xs@1.0.0: {}
+
+  emoji-regex@8.0.0: {}
+
+  entities@4.5.0: {}
+
+  entities@7.0.1: {}
+
+  es-toolkit@1.46.1: {}
+
+  esbuild@0.21.5:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.21.5
+      '@esbuild/android-arm': 0.21.5
+      '@esbuild/android-arm64': 0.21.5
+      '@esbuild/android-x64': 0.21.5
+      '@esbuild/darwin-arm64': 0.21.5
+      '@esbuild/darwin-x64': 0.21.5
+      '@esbuild/freebsd-arm64': 0.21.5
+      '@esbuild/freebsd-x64': 0.21.5
+      '@esbuild/linux-arm': 0.21.5
+      '@esbuild/linux-arm64': 0.21.5
+      '@esbuild/linux-ia32': 0.21.5
+      '@esbuild/linux-loong64': 0.21.5
+      '@esbuild/linux-mips64el': 0.21.5
+      '@esbuild/linux-ppc64': 0.21.5
+      '@esbuild/linux-riscv64': 0.21.5
+      '@esbuild/linux-s390x': 0.21.5
+      '@esbuild/linux-x64': 0.21.5
+      '@esbuild/netbsd-x64': 0.21.5
+      '@esbuild/openbsd-x64': 0.21.5
+      '@esbuild/sunos-x64': 0.21.5
+      '@esbuild/win32-arm64': 0.21.5
+      '@esbuild/win32-ia32': 0.21.5
+      '@esbuild/win32-x64': 0.21.5
+
+  escalade@3.2.0: {}
+
+  escape-string-regexp@5.0.0: {}
+
+  esprima@4.0.1: {}
+
+  estree-walker@2.0.2: {}
+
+  extend-shallow@2.0.1:
+    dependencies:
+      is-extendable: 0.1.1
+
+  extend@3.0.2: {}
+
+  fault@2.0.1:
+    dependencies:
+      format: 0.2.2
+
+  focus-trap@7.8.0:
+    dependencies:
+      tabbable: 6.4.0
+
+  format@0.2.2: {}
+
+  fsevents@2.3.3:
+    optional: true
+
+  get-caller-file@2.0.5: {}
+
+  gray-matter@4.0.3:
+    dependencies:
+      js-yaml: 3.14.2
+      kind-of: 6.0.3
+      section-matter: 1.0.0
+      strip-bom-string: 1.0.0
+
+  hachure-fill@0.5.2: {}
+
+  hast-util-to-html@9.0.5:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/unist': 3.0.3
+      ccount: 2.0.1
+      comma-separated-tokens: 2.0.3
+      hast-util-whitespace: 3.0.0
+      html-void-elements: 3.0.0
+      mdast-util-to-hast: 13.2.1
+      property-information: 7.1.0
+      space-separated-tokens: 2.0.2
+      stringify-entities: 4.0.4
+      zwitch: 2.0.4
+
+  hast-util-whitespace@3.0.0:
+    dependencies:
+      '@types/hast': 3.0.4
+
+  hookable@5.5.3: {}
+
+  html-void-elements@3.0.0: {}
+
+  iconv-lite@0.6.3:
+    dependencies:
+      safer-buffer: 2.1.2
+
+  import-meta-resolve@4.2.0: {}
+
+  internmap@1.0.1: {}
+
+  internmap@2.0.3: {}
+
+  is-extendable@0.1.1: {}
+
+  is-fullwidth-code-point@3.0.0: {}
+
+  is-plain-obj@4.1.0: {}
+
+  is-what@5.5.0: {}
+
+  js-yaml@3.14.2:
+    dependencies:
+      argparse: 1.0.10
+      esprima: 4.0.1
+
+  katex@0.16.47:
+    dependencies:
+      commander: 8.3.0
+
+  khroma@2.1.0: {}
+
+  kind-of@6.0.3: {}
+
+  layout-base@1.0.2: {}
+
+  layout-base@2.0.1: {}
+
+  linkify-it@5.0.0:
+    dependencies:
+      uc.micro: 2.1.0
+
+  lodash-es@4.18.1: {}
+
+  longest-streak@3.1.0: {}
+
+  magic-string@0.30.21:
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  mark.js@8.11.1: {}
+
+  markdown-it@14.1.1:
+    dependencies:
+      argparse: 2.0.1
+      entities: 4.5.0
+      linkify-it: 5.0.0
+      mdurl: 2.0.0
+      punycode.js: 2.3.1
+      uc.micro: 2.1.0
+
+  markdown-title@1.0.2: {}
+
+  marked@16.4.2: {}
+
+  mdast-util-from-markdown@2.0.3:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      mdast-util-to-string: 4.0.0
+      micromark: 4.0.2
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-decode-string: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-stringify-position: 4.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-frontmatter@2.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      escape-string-regexp: 5.0.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      micromark-extension-frontmatter: 2.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-phrasing@4.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      unist-util-is: 6.0.1
+
+  mdast-util-to-hast@13.2.1:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@ungap/structured-clone': 1.3.1
+      devlop: 1.1.0
+      micromark-util-sanitize-uri: 2.0.1
+      trim-lines: 3.0.1
+      unist-util-position: 5.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+
+  mdast-util-to-markdown@2.1.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      longest-streak: 3.1.0
+      mdast-util-phrasing: 4.1.0
+      mdast-util-to-string: 4.0.0
+      micromark-util-classify-character: 2.0.1
+      micromark-util-decode-string: 2.0.1
+      unist-util-visit: 5.1.0
+      zwitch: 2.0.4
+
+  mdast-util-to-string@4.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+
+  mdurl@2.0.0: {}
+
+  mermaid@11.15.0:
+    dependencies:
+      '@braintree/sanitize-url': 7.1.2
+      '@iconify/utils': 3.1.3
+      '@mermaid-js/parser': 1.1.1
+      '@types/d3': 7.4.3
+      '@upsetjs/venn.js': 2.0.0
+      cytoscape: 3.33.4
+      cytoscape-cose-bilkent: 4.1.0(cytoscape@3.33.4)
+      cytoscape-fcose: 2.2.0(cytoscape@3.33.4)
+      d3: 7.9.0
+      d3-sankey: 0.12.3
+      dagre-d3-es: 7.0.14
+      dayjs: 1.11.20
+      dompurify: 3.4.5
+      es-toolkit: 1.46.1
+      katex: 0.16.47
+      khroma: 2.1.0
+      marked: 16.4.2
+      roughjs: 4.6.6
+      stylis: 4.4.0
+      ts-dedent: 2.2.0
+      uuid: 14.0.0
+
+  micromark-core-commonmark@2.0.3:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-factory-destination: 2.0.1
+      micromark-factory-label: 2.0.1
+      micromark-factory-space: 2.0.1
+      micromark-factory-title: 2.0.1
+      micromark-factory-whitespace: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-html-tag-name: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-frontmatter@2.0.0:
+    dependencies:
+      fault: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-destination@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-label@2.0.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-space@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-title@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-whitespace@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-character@2.1.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-chunked@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-classify-character@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-combine-extensions@2.0.1:
+    dependencies:
+      micromark-util-chunked: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-decode-string@2.0.1:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      micromark-util-character: 2.1.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-encode@2.0.1: {}
+
+  micromark-util-html-tag-name@2.0.1: {}
+
+  micromark-util-normalize-identifier@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-resolve-all@2.0.1:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-util-sanitize-uri@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-encode: 2.0.1
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-subtokenize@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-symbol@2.0.1: {}
+
+  micromark-util-types@2.0.2: {}
+
+  micromark@4.0.2:
+    dependencies:
+      '@types/debug': 4.1.13
+      debug: 4.4.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-encode: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
+  millify@6.1.0:
+    dependencies:
+      yargs: 17.7.2
+
+  minimatch@10.2.5:
+    dependencies:
+      brace-expansion: 5.0.6
+
+  minisearch@7.2.0: {}
+
+  mitt@3.0.1: {}
+
+  ms@2.1.3: {}
+
+  nanoid@3.3.12: {}
+
+  non-layered-tidy-tree-layout@2.0.2:
+    optional: true
+
+  oniguruma-to-es@3.1.1:
+    dependencies:
+      emoji-regex-xs: 1.0.0
+      regex: 6.1.0
+      regex-recursion: 6.0.2
+
+  package-manager-detector@1.6.0: {}
+
+  path-data-parser@0.1.0: {}
+
+  path-to-regexp@6.3.0: {}
+
+  perfect-debounce@1.0.0: {}
+
+  picocolors@1.1.1: {}
+
+  points-on-curve@0.2.0: {}
+
+  points-on-path@0.2.1:
+    dependencies:
+      path-data-parser: 0.1.0
+      points-on-curve: 0.2.0
+
+  postcss@8.5.15:
+    dependencies:
+      nanoid: 3.3.12
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
+  preact@10.29.2: {}
+
+  pretty-bytes@7.1.0: {}
+
+  property-information@7.1.0: {}
+
+  punycode.js@2.3.1: {}
+
+  regex-recursion@6.0.2:
+    dependencies:
+      regex-utilities: 2.3.0
+
+  regex-utilities@2.3.0: {}
+
+  regex@6.1.0:
+    dependencies:
+      regex-utilities: 2.3.0
+
+  remark-frontmatter@5.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-frontmatter: 2.0.1
+      micromark-extension-frontmatter: 2.0.0
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-parse@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      micromark-util-types: 2.0.2
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-stringify@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-to-markdown: 2.1.2
+      unified: 11.0.5
+
+  remark@15.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      remark-parse: 11.0.0
+      remark-stringify: 11.0.0
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  require-directory@2.1.1: {}
+
+  rfdc@1.4.1: {}
+
+  robust-predicates@3.0.3: {}
+
+  rollup@4.60.4:
+    dependencies:
+      '@types/estree': 1.0.8
+    optionalDependencies:
+      '@rollup/rollup-android-arm-eabi': 4.60.4
+      '@rollup/rollup-android-arm64': 4.60.4
+      '@rollup/rollup-darwin-arm64': 4.60.4
+      '@rollup/rollup-darwin-x64': 4.60.4
+      '@rollup/rollup-freebsd-arm64': 4.60.4
+      '@rollup/rollup-freebsd-x64': 4.60.4
+      '@rollup/rollup-linux-arm-gnueabihf': 4.60.4
+      '@rollup/rollup-linux-arm-musleabihf': 4.60.4
+      '@rollup/rollup-linux-arm64-gnu': 4.60.4
+      '@rollup/rollup-linux-arm64-musl': 4.60.4
+      '@rollup/rollup-linux-loong64-gnu': 4.60.4
+      '@rollup/rollup-linux-loong64-musl': 4.60.4
+      '@rollup/rollup-linux-ppc64-gnu': 4.60.4
+      '@rollup/rollup-linux-ppc64-musl': 4.60.4
+      '@rollup/rollup-linux-riscv64-gnu': 4.60.4
+      '@rollup/rollup-linux-riscv64-musl': 4.60.4
+      '@rollup/rollup-linux-s390x-gnu': 4.60.4
+      '@rollup/rollup-linux-x64-gnu': 4.60.4
+      '@rollup/rollup-linux-x64-musl': 4.60.4
+      '@rollup/rollup-openbsd-x64': 4.60.4
+      '@rollup/rollup-openharmony-arm64': 4.60.4
+      '@rollup/rollup-win32-arm64-msvc': 4.60.4
+      '@rollup/rollup-win32-ia32-msvc': 4.60.4
+      '@rollup/rollup-win32-x64-gnu': 4.60.4
+      '@rollup/rollup-win32-x64-msvc': 4.60.4
+      fsevents: 2.3.3
+
+  roughjs@4.6.6:
+    dependencies:
+      hachure-fill: 0.5.2
+      path-data-parser: 0.1.0
+      points-on-curve: 0.2.0
+      points-on-path: 0.2.1
+
+  rw@1.3.3: {}
+
+  safer-buffer@2.1.2: {}
+
+  search-insights@2.17.3: {}
+
+  section-matter@1.0.0:
+    dependencies:
+      extend-shallow: 2.0.1
+      kind-of: 6.0.3
+
+  shiki@2.5.0:
+    dependencies:
+      '@shikijs/core': 2.5.0
+      '@shikijs/engine-javascript': 2.5.0
+      '@shikijs/engine-oniguruma': 2.5.0
+      '@shikijs/langs': 2.5.0
+      '@shikijs/themes': 2.5.0
+      '@shikijs/types': 2.5.0
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.4
+
+  source-map-js@1.2.1: {}
+
+  space-separated-tokens@2.0.2: {}
+
+  speakingurl@14.0.1: {}
+
+  sprintf-js@1.0.3: {}
+
+  string-width@4.2.3:
+    dependencies:
+      emoji-regex: 8.0.0
+      is-fullwidth-code-point: 3.0.0
+      strip-ansi: 6.0.1
+
+  stringify-entities@4.0.4:
+    dependencies:
+      character-entities-html4: 2.1.0
+      character-entities-legacy: 3.0.0
+
+  strip-ansi@6.0.1:
+    dependencies:
+      ansi-regex: 5.0.1
+
+  strip-bom-string@1.0.0: {}
+
+  stylis@4.4.0: {}
+
+  superjson@2.2.6:
+    dependencies:
+      copy-anything: 4.0.5
+
+  tabbable@6.4.0: {}
+
+  tinyexec@1.1.2: {}
+
+  tokenx@1.3.0: {}
+
+  trim-lines@3.0.1: {}
+
+  trough@2.2.0: {}
+
+  ts-dedent@2.2.0: {}
+
+  uc.micro@2.1.0: {}
+
+  unified@11.0.5:
+    dependencies:
+      '@types/unist': 3.0.3
+      bail: 2.0.2
+      devlop: 1.1.0
+      extend: 3.0.2
+      is-plain-obj: 4.1.0
+      trough: 2.2.0
+      vfile: 6.0.3
+
+  unist-util-is@6.0.1:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-position@5.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-remove@4.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
+  unist-util-stringify-position@4.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-visit-parents@6.0.2:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+
+  unist-util-visit@5.1.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
+  uuid@14.0.0: {}
+
+  vfile-message@4.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-stringify-position: 4.0.0
+
+  vfile@6.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      vfile-message: 4.0.3
+
+  vite@5.4.21:
+    dependencies:
+      esbuild: 0.21.5
+      postcss: 8.5.15
+      rollup: 4.60.4
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  vitepress-plugin-llms@1.12.2:
+    dependencies:
+      gray-matter: 4.0.3
+      markdown-it: 14.1.1
+      markdown-title: 1.0.2
+      mdast-util-from-markdown: 2.0.3
+      millify: 6.1.0
+      minimatch: 10.2.5
+      path-to-regexp: 6.3.0
+      picocolors: 1.1.1
+      pretty-bytes: 7.1.0
+      remark: 15.0.1
+      remark-frontmatter: 5.0.0
+      tokenx: 1.3.0
+      unist-util-remove: 4.0.0
+      unist-util-visit: 5.1.0
+    transitivePeerDependencies:
+      - supports-color
+
+  vitepress-plugin-mermaid@2.0.17(mermaid@11.15.0)(vitepress@1.6.4(@algolia/client-search@5.52.1)(postcss@8.5.15)(search-insights@2.17.3)):
+    dependencies:
+      mermaid: 11.15.0
+      vitepress: 1.6.4(@algolia/client-search@5.52.1)(postcss@8.5.15)(search-insights@2.17.3)
+    optionalDependencies:
+      '@mermaid-js/mermaid-mindmap': 9.3.0
+
+  vitepress@1.6.4(@algolia/client-search@5.52.1)(postcss@8.5.15)(search-insights@2.17.3):
+    dependencies:
+      '@docsearch/css': 3.8.2
+      '@docsearch/js': 3.8.2(@algolia/client-search@5.52.1)(search-insights@2.17.3)
+      '@iconify-json/simple-icons': 1.2.83
+      '@shikijs/core': 2.5.0
+      '@shikijs/transformers': 2.5.0
+      '@shikijs/types': 2.5.0
+      '@types/markdown-it': 14.1.2
+      '@vitejs/plugin-vue': 5.2.4(vite@5.4.21)(vue@3.5.34)
+      '@vue/devtools-api': 7.7.9
+      '@vue/shared': 3.5.34
+      '@vueuse/core': 12.8.2
+      '@vueuse/integrations': 12.8.2(focus-trap@7.8.0)
+      focus-trap: 7.8.0
+      mark.js: 8.11.1
+      minisearch: 7.2.0
+      shiki: 2.5.0
+      vite: 5.4.21
+      vue: 3.5.34
+    optionalDependencies:
+      postcss: 8.5.15
+    transitivePeerDependencies:
+      - '@algolia/client-search'
+      - '@types/node'
+      - '@types/react'
+      - async-validator
+      - axios
+      - change-case
+      - drauu
+      - fuse.js
+      - idb-keyval
+      - jwt-decode
+      - less
+      - lightningcss
+      - nprogress
+      - qrcode
+      - react
+      - react-dom
+      - sass
+      - sass-embedded
+      - search-insights
+      - sortablejs
+      - stylus
+      - sugarss
+      - terser
+      - typescript
+      - universal-cookie
+
+  vue@3.5.34:
+    dependencies:
+      '@vue/compiler-dom': 3.5.34
+      '@vue/compiler-sfc': 3.5.34
+      '@vue/runtime-dom': 3.5.34
+      '@vue/server-renderer': 3.5.34(vue@3.5.34)
+      '@vue/shared': 3.5.34
+
+  wrap-ansi@7.0.0:
+    dependencies:
+      ansi-styles: 4.3.0
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+
+  y18n@5.0.8: {}
+
+  yargs-parser@21.1.1: {}
+
+  yargs@17.7.2:
+    dependencies:
+      cliui: 8.0.1
+      escalade: 3.2.0
+      get-caller-file: 2.0.5
+      require-directory: 2.1.1
+      string-width: 4.2.3
+      y18n: 5.0.8
+      yargs-parser: 21.1.1
+
+  zwitch@2.0.4: {}
diff --git a/docs/public/favicon.ico b/docs/public/favicon.ico
new file mode 100644
index 000000000..9b4870b72
Binary files /dev/null and b/docs/public/favicon.ico differ
diff --git a/docs/zh/configuration/config-files.md b/docs/zh/configuration/config-files.md
new file mode 100644
index 000000000..b9fe6f981
--- /dev/null
+++ b/docs/zh/configuration/config-files.md
@@ -0,0 +1,228 @@
+# 配置文件
+
+Kimi Code CLI 把全局配置保存在一份 TOML 文件中，包含 API 供应商、模型别名、Agent 循环参数、后台任务、外部服务等。这份文档介绍配置文件的位置、顶层字段、各嵌套结构，以及一份完整示例。
+
+## 配置文件位置
+
+默认配置文件位于 `~/.kimi-code/config.toml`。目录和文件会在首次运行时自动创建，并设置严格的访问权限。
+
+如果你希望把数据目录放到别处，可以通过环境变量 `KIMI_CODE_HOME` 覆盖默认路径：
+
+```sh
+export KIMI_CODE_HOME=/path/to/kimi-home
+```
+
+此时配置文件路径变为 `$KIMI_CODE_HOME/config.toml`。无论目录在哪里，文件名固定为 `config.toml`。
+
+::: tip 提示
+TOML 中的字段名一律使用 snake_case（例如 `default_model`、`max_context_size`）。如果 key 中包含 `.`，需要使用带引号的 TOML key，否则 TOML 会把 `.` 当作嵌套表分隔符。
+:::
+
+## 顶层字段
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `default_model` | `string` | — | 默认使用的模型别名，必须在 `models` 中定义 |
+| `default_thinking` | `boolean` | `false` | 新会话启动时 Thinking 开关的初始值，可在会话内通过模型菜单切换。即使该字段为 `true`，`[thinking].mode = "off"` 也会强制禁用 Thinking。详见下文 [`thinking`](#thinking) |
+| `default_permission_mode` | `string` | `manual` | 新会话的默认权限模式，可选 `manual`、`auto`、`yolo` |
+| `default_plan_mode` | `boolean` | `false` | 新会话是否默认以 Plan 模式启动；省略等同 `false` |
+| `merge_all_available_skills` | `boolean` | `true` | 是否合并所有可用目录中的 Agent Skills |
+| `extra_skill_dirs` | `array<string>` | — | 额外的 Skill 搜索目录，会叠加到默认目录之上 |
+| `telemetry` | `boolean` | `true` | 是否启用匿名遥测；仅在显式设为 `false` 时关闭 |
+| `providers` | `table` | `{}` | API 供应商表，详见下文 |
+| `models` | `table` | — | 模型别名表，详见下文 |
+| `thinking` | `table` | — | Thinking 模式默认参数 |
+| `loop_control` | `table` | — | Agent 循环控制参数 |
+| `background` | `table` | — | 后台任务运行参数 |
+| `services` | `table` | — | 内置外部服务配置 |
+| `permission` | `table` | — | 权限规则配置，详见下文 |
+| `hooks` | `array<table>` | — | 生命周期 hook 配置，详见 [Hooks](../customization/hooks.md) |
+
+## 完整示例
+
+```toml
+default_model = "kimi-code/kimi-for-coding"
+default_thinking = true
+default_permission_mode = "manual"
+default_plan_mode = false
+merge_all_available_skills = true
+telemetry = true
+
+[providers."managed:kimi-code"]
+type = "kimi"
+base_url = "https://api.kimi.com/coding/v1"
+api_key = ""
+
+[models."kimi-code/kimi-for-coding"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+max_context_size = 262144
+
+[thinking]
+mode = "auto"
+
+[loop_control]
+max_steps_per_turn = 1000
+max_retries_per_step = 3
+reserved_context_size = 50000
+
+[background]
+max_running_tasks = 4
+keep_alive_on_exit = false
+agent_task_timeout_s = 900
+
+[[permission.rules]]
+decision = "allow"
+pattern = "Read"
+
+[[permission.rules]]
+decision = "deny"
+pattern = "Bash(rm -rf*)"
+
+[[hooks]]
+event = "PreToolUse"
+matcher = "Bash"
+command = "node ~/.kimi-code/hooks/check-bash.mjs"
+timeout = 5
+```
+
+## `providers`
+
+`providers` 表中的每一项定义一个 API 供应商连接信息，以唯一的名称作为 key。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `type` | `string` | 是 | 供应商类型，可选 `anthropic`、`openai`、`kimi`、`google-genai`、`openai_responses`、`vertexai` |
+| `api_key` | `string` | 否 | API 密钥 |
+| `base_url` | `string` | 否 | API 基础 URL |
+| `oauth` | `table` | 否 | OAuth 凭据引用，详见下文 |
+| `env` | `table<string, string>` | 否 | 按供应商约定的键读取的配置子表，作为 `api_key` / `base_url` 等字段的备用来源（如 `KIMI_API_KEY`、`ANTHROPIC_API_KEY`、`GOOGLE_CLOUD_PROJECT` 等）。这只是写在配置文件里的子表，**不会真正写入到终端的环境变量**；仅在 `[providers.<name>]` 上直接字段缺省时被 CLI 读取 |
+| `custom_headers` | `table<string, string>` | 否 | 请求时附加的自定义 HTTP 头 |
+
+OAuth 凭据引用结构：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `storage` | `string` | 是 | 凭据存储位置；目前只支持 `"file"` |
+| `key` | `string` | 是 | 凭据条目的唯一标识 |
+
+```toml
+[providers.openai]
+type = "openai"
+base_url = "https://api.openai.com/v1"
+api_key = "sk-xxx"
+custom_headers = { "X-Custom-Header" = "value" }
+```
+
+## `models`
+
+`models` 表中的每一项定义一个模型别名，以唯一的名称作为 key。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `provider` | `string` | 是 | 使用的供应商名称，必须在 `providers` 中定义 |
+| `model` | `string` | 是 | 调用 API 时使用的模型标识符 |
+| `max_context_size` | `integer` | 是 | 最大上下文长度（token 数），必须大于等于 1 |
+| `max_output_size` | `integer` | 否 | 单次请求的输出预算上限（即请求层面的 `max_tokens`）。目前仅 `anthropic` 供应商会读取该字段。当别名能识别到具体的 Claude 家族时，覆盖值不会超过模型允许的上限，避免超出服务端限制。省略时使用模型推导出的默认值，详见 [`providers.md`](./providers.md#anthropic)。 |
+| `capabilities` | `array<string>` | 否 | 显式追加的模型能力标签，例如 `thinking`、`image_in`、`video_in`、`audio_in`、`tool_use` |
+| `display_name` | `string` | 否 | 在 UI 中显示的名称，未设置时回退到 `model` |
+
+`capabilities` 与供应商 capability registry 按模型名前缀自动匹配出来的能力做并集 —— 只能追加、不能移除。通常无需手写；只有当模型未被 registry 覆盖、或希望强制启用某项能力时才用得到。
+
+如果模型别名包含 `.`，需要使用带引号的 key：
+
+```toml
+[models."gpt-4.1"]
+provider = "openai"
+model = "gpt-4.1"
+max_context_size = 1047576
+```
+
+## `thinking`
+
+`thinking` 控制 Thinking 模式的默认行为。即便顶层 `default_thinking = true`，将 `mode` 设为 `"off"` 也会强制禁用 Thinking。
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `mode` | `string` | — | 触发策略，可选 `auto`、`on`、`off`。设为 `"off"` 时强制禁用 Thinking；其它取值或省略时不禁用，由会话内的 Thinking 开关与 `effort` 共同决定 |
+| `effort` | `string` | `high` | 启用 Thinking 时使用的默认强度，可选 `low`、`medium`、`high`、`xhigh`、`max`，实际可用等级由供应商决定 |
+
+## `loop_control`
+
+`loop_control` 控制 Agent 执行循环的步数、重试和上下文压缩阈值。
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `max_steps_per_turn` | `integer` | `1000` | 单轮最大步数 |
+| `max_retries_per_step` | `integer` | `3` | 单步最大重试次数 |
+| `reserved_context_size` | `integer` | — | 预留给响应生成的 token 数；上下文逼近该阈值时触发压缩 |
+
+## `background`
+
+`background` 控制后台任务的运行限制。后台任务通过 `Bash` 工具或 `Agent` 工具的 `run_in_background=true` 参数启动。
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `max_running_tasks` | `integer` | — | 同时运行的最大后台任务数 |
+| `keep_alive_on_exit` | `boolean` | `true` | 会话关闭时是否保留仍在运行的后台任务。设为 `false` 后，`kimi -p` 完成退出、SDK 关闭 session 或 harness 关闭时会请求停止后台任务 |
+| `agent_task_timeout_s` | `integer` | — | 后台 Agent 任务的最大运行时间（秒） |
+
+`keep_alive_on_exit` 可以被环境变量 `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` 覆盖；环境变量优先级高于 `config.toml`。schema 还预留了 `kill_grace_period_ms`、`print_wait_ceiling_s` 两个字段，目前仅 schema 校验通过，CLI 运行时不会读取。
+
+## `services`
+
+`services` 配置 Kimi Code CLI 调用的内置外部服务。当前仅识别 `moonshot_search`（网页搜索）和 `moonshot_fetch`（网页抓取）两个固定 key，其他 key 会被忽略。两项的字段相同：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `base_url` | `string` | 否 | 服务 API URL |
+| `api_key` | `string` | 否 | API 密钥 |
+| `oauth` | `table` | 否 | OAuth 凭据引用，结构同 `providers.*.oauth` |
+| `custom_headers` | `table<string, string>` | 否 | 请求时附加的自定义 HTTP 头 |
+
+```toml
+[services.moonshot_search]
+base_url = "https://api.moonshot.cn/v1/search"
+api_key = "sk-xxx"
+
+[services.moonshot_fetch]
+base_url = "https://api.moonshot.cn/v1/fetch"
+api_key = "sk-xxx"
+```
+
+## `permission`
+
+`permission` 配置会话启动时加载的初始权限规则，控制工具调用的默认审批行为。新会话的默认权限模式由顶层 `default_permission_mode` 控制；启动时显式传入的权限模式（例如 CLI 的 `--yolo`）会覆盖这个默认值。
+
+规则通过 `[[permission.rules]]` 数组表写出，每条规则包含以下字段：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `decision` | `string` | 是 | 决策结果，可选 `allow`、`deny`、`ask` |
+| `scope` | `string` | 否 | 规则作用域，可选 `turn-override`、`session-runtime`、`project`、`user`；默认 `user` |
+| `pattern` | `string` | 是 | 匹配模式，格式为 `ToolName` 或 `ToolName(arg-pattern)`。`ToolName` 必须与运行时真实工具名一致——内置工具是 `Read`、`Write`、`Edit`、`Bash`、`Grep` 等（详见 [内置工具](../reference/tools.md)） |
+| `reason` | `string` | 否 | 规则说明，供调试或审计使用 |
+
+示例：
+
+```toml
+[[permission.rules]]
+decision = "allow"
+pattern = "Read"
+
+[[permission.rules]]
+decision = "allow"
+pattern = "Grep"
+
+[[permission.rules]]
+decision = "deny"
+pattern = "Bash(rm -rf*)"
+
+[[permission.rules]]
+decision = "ask"
+pattern = "Bash"
+```
+
+::: tip 提示
+MCP server 的声明配置写在 `~/.kimi-code/mcp.json` 或项目内 `.kimi-code/mcp.json` 中，不在 `config.toml` 里。交互式配置入口是 `/mcp-config`，详见 [Model Context Protocol](../customization/mcp.md)。
+:::
diff --git a/docs/zh/configuration/data-locations.md b/docs/zh/configuration/data-locations.md
new file mode 100644
index 000000000..519ad5029
--- /dev/null
+++ b/docs/zh/configuration/data-locations.md
@@ -0,0 +1,131 @@
+# 数据路径
+
+Kimi Code CLI 将运行时数据集中存储在用户主目录下的 `~/.kimi-code/` 目录中。本页介绍各类数据的存放位置、用途，以及如何自定义和清理。
+
+## 数据根目录
+
+默认数据根是 `~/.kimi-code/`。`~` 由 Node.js 的 `os.homedir()` 解析，因此实际路径在不同平台略有差异：macOS 上是 `/Users/<name>/.kimi-code`，Linux 上是 `/home/<name>/.kimi-code`，Windows 上是 `C:\Users\<name>\.kimi-code`。
+
+可以通过 `KIMI_CODE_HOME` 环境变量覆盖到任意路径：
+
+```sh
+export KIMI_CODE_HOME="$HOME/.config/kimi-code"
+```
+
+设置后，配置、会话、日志、输入历史、更新缓存、OAuth 凭据等运行时数据都会落到该路径下。`KIMI_CODE_HOME` 与其他环境变量的完整说明见 [环境变量](./env-vars.md)。
+
+::: tip 例外
+**内置工具缓存**（例如自动下载的 ripgrep 二进制）不走 `KIMI_CODE_HOME`，而是走 `KIMI_CODE_CACHE_DIR`；未设置时使用平台缓存目录——macOS 上是 `~/Library/Caches/kimi-code`，Linux 上是 `$XDG_CACHE_HOME/kimi-code`（缺省 `~/.cache/kimi-code`），Windows 上是 `%LOCALAPPDATA%\kimi-code`。
+
+用户级 Agent Skills 的搜索目录位于 `~/.kimi-code/skills` 与 `~/.agents/skills`；项目级则是工作目录下的 `.kimi-code/skills` 与 `.agents/skills`。详见 [Agent Skills](../customization/skills.md)。
+:::
+
+## 目录结构
+
+数据根下的典型布局如下：
+
+```
+$KIMI_CODE_HOME  (默认 ~/.kimi-code)
+├── config.toml             # 用户配置
+├── mcp.json                # 用户级 MCP server 声明（可选）
+├── session_index.jsonl     # 会话索引
+├── credentials/            # OAuth 凭据根目录（目录 0o700、文件 0o600）
+│   ├── <name>.json         # 托管 Kimi / Open Platform 等 provider OAuth 凭据
+│   └── mcp/                # MCP server OAuth 凭据
+│       └── <key>-<suffix>.json
+├── sessions/               # 会话数据
+│   └── <workDirKey>/
+│       └── <sessionId>/
+│           ├── state.json
+│           ├── logs/
+│           │   └── kimi-code.log
+│           ├── tasks/          # 后台任务持久化
+│           │   ├── <task_id>.json
+│           │   └── <task_id>/
+│           │       └── output.log
+│           └── agents/
+│               ├── main/
+│               │   ├── wire.jsonl
+│               │   └── plans/  # Plan 模式计划文件
+│               └── agent-0/
+│                   └── wire.jsonl
+├── bin/
+│   └── rg                  # ripgrep 缓存（Windows 为 rg.exe）
+├── logs/                   # 全局诊断日志
+│   └── kimi-code.log
+├── updates/
+│   └── latest.json         # 更新检查状态
+└── user-history/
+    └── <md5(workDir)>.jsonl
+```
+
+::: tip
+上面的目录树展示的是默认数据根（`~/.kimi-code/`）下的典型布局。Agent Skills 与内置工具缓存的路径略有特殊性，详见上方"例外"提示。
+:::
+
+## 配置文件
+
+`config.toml` 是 Kimi Code CLI 的主配置文件，存放供应商、模型、循环控制等用户级设置。详见 [配置文件](./config-files.md)。
+
+`mcp.json` 是用户级 MCP server 声明，会与项目内的 `.kimi-code/mcp.json` 合并加载。字段与项目级文件相同，详见 [MCP](../customization/mcp.md)。
+
+OAuth 凭据以文件形式存放在数据根下的 `credentials/` 子目录，目录权限 `0o700`、文件权限 `0o600`，仅当前用户可读写。其中：
+
+- **托管 Kimi / Open Platform 等供应商的 OAuth 凭据**位于 `credentials/<name>.json`，例如 `~/.kimi-code/credentials/managed:kimi-code.json`。
+- **MCP server 的 OAuth 凭据**位于 `credentials/mcp/` 子目录下，文件名按 server key 自动生成，例如 `credentials/mcp/<key>-<suffix>.json`。
+
+凭据写入采用 `tmp → fsync → rename` 的原子流程；POSIX 下严格保证原子性，Windows 上则尽最大努力保证。
+
+## 会话数据
+
+会话相关的数据集中在 `sessions/` 下，并通过顶层 `session_index.jsonl` 维护一份 JSONL 索引：每行一条记录，包含 `sessionId`、`sessionDir`、`workDir` 三个字段。索引在创建会话时追加写入，加载时会校验 `sessionDir` 是否仍在 `sessions/` 下、且最后一级目录名等于 `sessionId`，以防止外部篡改指向非法路径。
+
+每个会话目录的路径形如 `sessions/<workDirKey>/<sessionId>/`，其中 `workDirKey` 是按工作目录编码出来的桶名，格式为 `wd_<slug>_<sha256前12位>`（例如 `wd_myproject_a3f8c1d20e9b`），`sessionId` 是会话的唯一标识。`sessions/` 整条路径包括 `<workDirKey>/` 桶都按 `0o700` 权限创建，仅当前用户可访问。
+
+会话目录的内部结构包含：
+
+- `state.json`：会话标题、`lastPrompt`、`createdAt`、`updatedAt`、`isCustomTitle`、`forkedFrom` 以及各个 Agent 的元数据。
+- `agents/main/wire.jsonl`：主 Agent 的 Wire 事件流（内部通信记录），用于回放和恢复。`main` 是主 Agent 的固定 id。
+- `agents/main/plans/`：Plan 模式下主 Agent 写入的计划文件，按计划 id 命名为 `<id>.md`。
+- `agents/agent-0/`、`agents/agent-1/` 等：子 Agent 实例的目录，各自包含 `wire.jsonl`。子 Agent id 由会话内的递增计数器生成（`agent-` 加从 0 起的整数）。
+- `logs/kimi-code.log`：该会话的诊断日志。只有发生被记录的诊断事件时才会出现；普通对话不一定产生这个文件。
+- `tasks/`：后台任务持久化目录。每个任务在 `tasks/<task_id>.json` 保存元信息（状态、pid、退出码等），标准输出与标准错误写入 `tasks/<task_id>/output.log`。任务 id 格式为 `bash-` 或 `agent-` 前缀加 8 位随机字母数字（如 `bash-a1b2c3d4`）。
+
+`sessionId` 仅允许 `[A-Za-z0-9._-]+` 且不能为 `.` 或 `..`，以避免路径注入。会话列表按 `updatedAt` 倒序排序，`updatedAt` 取目录与各关键文件 mtime 的最大值。详见 [会话管理](../guides/sessions.md)。
+
+## 内置工具缓存
+
+Kimi Code CLI 在首次需要 ripgrep 时会自动下载并缓存。下载过程中，压缩包写入系统临时目录，校验 SHA-256 后解压，二进制直接安装到数据根下的 `bin/rg`（Windows 上为 `bin/rg.exe`）并赋予 `0o755` 执行权限。后续在同一数据根下直接复用，无需再次下载。如果系统 `PATH` 中本来就有 `rg`，会优先使用系统版本；删除 `bin/` 会在下一次需要时触发重新下载。
+
+## 日志与更新状态
+
+顶层 `logs/kimi-code.log` 是全局诊断日志，主要记录启动、登录、导出等不属于单个会话的问题。单个会话自己的诊断日志在 `<sessionDir>/logs/kimi-code.log`。
+
+如需报告 bug，优先使用 `kimi export` 导出相关会话（详见 [kimi 命令](../reference/kimi-command.md)）；如果会话日志存在，它会默认包含在导出包里。全局诊断日志默认也会打包；因为它可能包含其它会话或其它项目的事件，不想分享时使用 `--no-include-global-log` 排除。
+
+`updates/latest.json` 记录通过 npm 检查到的版本更新状态，由 CLI 自动维护，通常无需手动编辑。
+
+## 输入历史
+
+终端中的命令输入历史按工作目录分别保存。每个工作目录对应一个文件，路径为 `user-history/<md5(workDir)>.jsonl`，其中文件名是工作目录字符串的 MD5 哈希值（UTF-8 编码）。文件格式为 JSONL，每行一条历史记录。
+
+输入历史用于在终端界面下浏览和搜索此前输入过的提示词。
+
+## 清理数据
+
+直接删除数据根目录（默认 `~/.kimi-code/`，或 `KIMI_CODE_HOME` 指定的路径）可以完全清理 Kimi Code CLI 的所有运行时数据，包括配置、会话、日志、输入历史和内置工具缓存。
+
+如只需清理部分数据：
+
+| 需求 | 操作 |
+| --- | --- |
+| 重置配置 | 删除 `~/.kimi-code/config.toml` |
+| 清理所有会话 | 删除 `~/.kimi-code/sessions/` 与 `~/.kimi-code/session_index.jsonl` |
+| 清理诊断日志 | 删除 `~/.kimi-code/logs/` 目录 |
+| 清理输入历史 | 删除 `~/.kimi-code/user-history/` 目录 |
+| 重置更新检查状态 | 删除 `~/.kimi-code/updates/latest.json` |
+| 强制重新下载 ripgrep | 删除 `~/.kimi-code/bin/` 目录 |
+| 清除托管 Kimi / Open Platform OAuth 登录态 | 运行 `/logout`（仅清理当前供应商的 OAuth），或删除对应 `~/.kimi-code/credentials/<name>.json` |
+| 清除 MCP server OAuth 登录态 | 删除 `~/.kimi-code/credentials/mcp/` 目录；`/logout` **不会**清理 MCP 的 OAuth 凭据 |
+| 移除用户级 MCP 声明 | 删除 `~/.kimi-code/mcp.json` |
+| 清空用户级 Skills | 删除 `~/.kimi-code/skills/` 目录 |
diff --git a/docs/zh/configuration/env-vars.md b/docs/zh/configuration/env-vars.md
new file mode 100644
index 000000000..7116ab400
--- /dev/null
+++ b/docs/zh/configuration/env-vars.md
@@ -0,0 +1,125 @@
+# 环境变量
+
+Kimi Code CLI 通过环境变量来覆盖默认路径、切换 OAuth 端点以及调整运行时行为。大部分变量在 `kimi` 进程启动时读取，少数（如遥测开关、OAuth 锁、诊断日志）在相关子系统初始化时读取。Kimi 自有变量使用 `KIMI_*` 前缀；此外，CLI 也会读取若干系统标准变量。
+
+::: warning 注意
+**供应商凭证不在此列**：`KIMI_API_KEY`、`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、`GOOGLE_API_KEY` 等密钥变量**不会**从 `process.env` 自动读取。它们必须写在 `config.toml` 的 `[providers.<name>]` 段（`api_key` / `base_url`）或 `[providers.<name>.env]` 子表中；仅在 shell 中 `export` 不会让某个供应商自动获得凭证。详见 [配置覆盖](./overrides.md#供应商凭证) 与 [供应商](./providers.md)。
+:::
+
+## 核心路径
+
+`KIMI_CODE_HOME` 用于覆盖 Kimi Code CLI 的数据根目录，默认值是 `~/.kimi-code`。CLI 自身的应用数据、`kimi-core` 的配置、ripgrep 缓存以及 OAuth 凭证都会落在这个目录下。
+
+```sh
+export KIMI_CODE_HOME="/path/to/custom/kimi-code"
+```
+
+数据布局的详细说明请参阅 [数据路径](./data-locations.md)。
+
+::: warning 注意
+设置后请确保目录可写。多个 `kimi` 实例如果共享同一个 `KIMI_CODE_HOME`，会共享配置与凭证文件。
+:::
+
+## 供应商凭证键名
+
+下列键名出现在 `config.toml` 的 `[providers.<name>.env]` 子表中，用作供应商 `api_key` / `base_url` 的回退来源。**`kimi` 主进程不会从 `process.env` 直接读取它们**；只有 `[providers.<name>.env]` 子表内对应键的值才会被供应商客户端识别。详细解析顺序见 [配置覆盖：供应商凭证](./overrides.md#供应商凭证)。
+
+| 键名 | 适用供应商 | 用途 | 默认值 |
+| --- | --- | --- | --- |
+| `KIMI_API_KEY` | Kimi / Moonshot | API 密钥 | 无 |
+| `KIMI_BASE_URL` | Kimi / Moonshot | API 基础 URL | `https://api.moonshot.ai/v1` |
+| `ANTHROPIC_API_KEY` | Anthropic | API 密钥 | 无 |
+| `ANTHROPIC_BASE_URL` | Anthropic | API 基础 URL | 跟随 Anthropic SDK 默认值 |
+| `OPENAI_API_KEY` | OpenAI（`openai` 与 `openai_responses` 均使用） | API 密钥 | 无 |
+| `OPENAI_BASE_URL` | OpenAI（`openai` 与 `openai_responses` 均使用） | API 基础 URL | `https://api.openai.com/v1` |
+| `GOOGLE_API_KEY` | Google GenAI、Vertex AI（作为 `VERTEXAI_API_KEY` 的备用） | API 密钥 | 无 |
+| `VERTEXAI_API_KEY` | Vertex AI | API 密钥（未使用 ADC 时） | 无 |
+| `GOOGLE_CLOUD_PROJECT` | Vertex AI | GCP 项目 ID | 无 |
+| `GOOGLE_CLOUD_LOCATION` | Vertex AI | GCP 区域 | 无 |
+
+例如在 `config.toml` 中预置 Kimi 凭证：
+
+```toml
+[providers.kimi.env]
+KIMI_API_KEY = "sk-xxx"
+KIMI_BASE_URL = "https://api.moonshot.ai/v1"
+```
+
+::: warning 注意
+`GOOGLE_APPLICATION_CREDENTIALS`（服务账号 JSON 路径）由 Google SDK 自身从终端环境变量中读取，是这组键名中**唯一**走系统环境变量的；它走的是 Google Cloud 标准的 ADC 流程，CLI 不参与解析。其它键名都需要写在 `[providers.<name>.env]` 子表里才会生效。
+:::
+
+供应商类型与字段的完整说明请参阅 [供应商](./providers.md)。
+
+## OAuth 与托管服务
+
+OAuth 流程默认连接 Kimi 官方的认证与托管端点，下列变量可以将它们指向自建或测试环境。
+
+| 环境变量 | 用途 | 默认值 |
+| --- | --- | --- |
+| `KIMI_CODE_OAUTH_HOST` | OAuth 认证 host，优先级最高 | —（未设置时回退到 `KIMI_OAUTH_HOST`，再回退到下面的硬编码默认） |
+| `KIMI_OAUTH_HOST` | OAuth 认证 host，作为 `KIMI_CODE_OAUTH_HOST` 的 fallback | —（未设置时回退到下面的硬编码默认） |
+| `KIMI_CODE_BASE_URL` | 托管 Kimi API 的 base URL，用于 OAuth 登录后的 API 调用 | `https://api.kimi.com/coding/v1` |
+
+当 `KIMI_CODE_OAUTH_HOST` 和 `KIMI_OAUTH_HOST` 都未设置时，OAuth 认证 host 使用硬编码常量 `https://auth.kimi.com`。
+
+::: warning 注意
+`KIMI_CODE_BASE_URL` 与上一节的 `KIMI_BASE_URL` 是两个不同变量：前者面向 OAuth 登录的托管服务，默认指向 `kimi.com`；后者面向直接使用 Kimi API 密钥的供应商，默认指向 `moonshot.ai`。请按场景区分。
+:::
+
+## 运行时开关
+
+| 环境变量 | 用途 | 合法值 / 默认值 |
+| --- | --- | --- |
+| `KIMI_DISABLE_TELEMETRY` | 关闭遥测上报 | `1`、`true`、`t`、`yes`、`y`（不区分大小写） |
+| `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` | 覆盖 `[background].keep_alive_on_exit`，控制会话关闭时是否保留仍在运行的后台任务 | 真值：`1`、`true`、`yes`、`on`；假值：`0`、`false`、`no`、`off`；未设置时读取 `config.toml`，再回退到 `true` |
+| `KIMI_SHELL_PATH` | 覆盖 Windows 上 Git Bash (`bash.exe`) 的绝对路径，仅在 Windows 自动探测失败时需要 | 无 |
+| `KIMI_MODEL_MAX_COMPLETION_TOKENS` | 单步 LLM 请求 `max_completion_tokens` 的期望预算（实际值按上下文窗口与输入大小再做 clamp）；设为 `0` 或负数则完全禁用 clamp。**目前只对 `kimi` 类型的供应商生效**；Anthropic 等其它供应商请改用 `[models.<alias>].max_output_size`（详见 [配置文件](./config-files.md#models)） | 默认 32000，受 `loop_control.reserved_context_size` 影响 |
+
+例如在共享主机上禁用遥测：
+
+```sh
+export KIMI_DISABLE_TELEMETRY="1"
+```
+
+`KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` 的优先级高于 `config.toml`。例如临时运行 `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT=0 kimi -p "..."` 时，即使配置文件里写了 `keep_alive_on_exit = true`，本次进程退出前也会请求停止后台任务。
+
+## 诊断日志
+
+下列变量控制 `kimi` 的诊断日志。日志会写入两个位置：全局诊断日志在 `$KIMI_CODE_HOME/logs/kimi-code.log`，每个会话自身的诊断日志在 `<sessionDir>/logs/kimi-code.log`（路径细节见 [数据路径](./data-locations.md#日志与更新状态)）。所有变量都只在进程启动时读取一次。
+
+| 环境变量 | 用途 | 默认值 |
+| --- | --- | --- |
+| `KIMI_LOG_LEVEL` | 日志级别，可选 `off`、`error`、`warn`、`info`、`debug` | `info` |
+| `KIMI_LOG_GLOBAL_MAX_BYTES` | 全局日志文件单个最大字节数 | `6291456`（6 MB） |
+| `KIMI_LOG_GLOBAL_FILES` | 全局日志文件保留份数 | `5` |
+| `KIMI_LOG_SESSION_MAX_BYTES` | 会话级日志文件单个最大字节数 | `5242880`（5 MB） |
+| `KIMI_LOG_SESSION_FILES` | 会话级日志文件保留份数 | `3` |
+
+整数类变量解析失败（非正整数、非数字）时静默回落到默认值。
+
+## 剪贴板桥接
+
+`KIMI_WSL_CLIPBOARD_IMAGE_PATH` 由 CLI 在调用 WSL 剪贴板辅助子进程时自动注入，用于传递临时图片路径。该变量写入到 PowerShell 子进程的环境中，由子进程脚本内部读取；kimi 主进程自身不读取此变量。在外部 shell 中设置它对 kimi 主进程**无效**，用户无需手动管理此变量。
+
+## 系统环境变量
+
+Kimi Code CLI 也会读取一些标准的系统环境变量，用于检测运行环境与默认行为：
+
+- `HOME`：用户主目录，用于解析默认数据路径。
+- `VISUAL`、`EDITOR`：调用外部编辑器时的可执行命令，`VISUAL` 优先。
+- `PATH`：定位 `rg`、`git` 等外部依赖。
+- `NO_COLOR`：设置且非空时，强制关闭颜色与主题检测，界面回退到深色主题。遵循 [no-color.org](https://no-color.org) 约定。
+- `FORCE_COLOR`：值为 `"0"` 时，同样关闭颜色与主题检测，界面回退到深色主题。
+- `CI`：非空且非 `"0"` 时，关闭主题检测并回退到深色主题；遥测模块也会读取此变量以标记 CI 环境。
+- `LANG`：用于在遥测上下文中标记 locale（仅作为标记，不改变 CLI 行为）。
+- `TERM_PROGRAM`：用于检测终端对 OSC 9 通知的支持（iTerm2、WezTerm、ghostty、WarpTerminal 等）；也会写入遥测上下文。
+- `TERM`：用于检测终端对 OSC 9 通知的支持（xterm-kitty、xterm-ghostty 等）。
+- `TMUX`：检测是否运行在 tmux 内，用于终端通知路径的判断。
+- `COLORFGBG`：检测终端配色（深色 / 浅色）。
+- `DISPLAY`、`WAYLAND_DISPLAY`、`XDG_SESSION_TYPE`：检测 Linux 图形会话，用于剪贴板与图片相关功能。`XDG_SESSION_TYPE` 值为 `wayland` 时也判定为 Wayland 会话。
+- `WSL_DISTRO_NAME`、`WSLENV`：检测是否运行在 WSL 内，用于剪贴板的 PowerShell 桥接回退。
+- `TERMUX_VERSION`：检测是否运行在 Termux 中。
+- `LOCALAPPDATA`：Windows 上探测 Git Bash 安装路径时使用。
+
+这些变量遵循各操作系统的常规约定，`kimi` 仅读取不修改。
diff --git a/docs/zh/configuration/overrides.md b/docs/zh/configuration/overrides.md
new file mode 100644
index 000000000..88ab6284e
--- /dev/null
+++ b/docs/zh/configuration/overrides.md
@@ -0,0 +1,110 @@
+# 配置覆盖
+
+Kimi Code CLI 的运行参数来自用户配置文件、命令行选项，以及若干在进程级环境变量上读取的运行时路径、端点与开关。三者面向不同场景 —— 配置文件保存长期偏好，命令行选项做本次启动的临时切换，环境变量主要负责定位数据目录、切换 OAuth 端点和少量运行时开关。
+
+环境变量在 Kimi Code CLI 中**不是配置字段的通用后备来源**：它们分成下面三类，作用范围互不相同，不能简单合并成一条线性优先级。
+
+## 环境变量的三类作用
+
+1. **配置文件定位**：`KIMI_CODE_HOME` 决定配置文件、会话、日志等所在的数据根目录，配置文件路径变为 `$KIMI_CODE_HOME/config.toml`，否则使用 `~/.kimi-code/`。这是先于其它解析的"在哪里找配置"步骤，不是普通参数的后备来源；也无法通过 `KIMI_CONFIG_PATH` 之类的变量任意切换配置文件路径。
+2. **运行时开关**：`KIMI_DISABLE_TELEMETRY` 等少量开关会直接关闭对应子系统。即便 `config.toml` 中 `telemetry = true`，只要这个变量被设置成真值，遥测仍会被关闭——它对相关子系统的语义是"额外禁用"，而不是"普通覆盖"。
+3. **运行端点与诊断**：`KIMI_CODE_OAUTH_HOST`、`KIMI_OAUTH_HOST`、`KIMI_CODE_BASE_URL`、`KIMI_LOG_LEVEL` 等供 OAuth 与诊断子系统初始化时读取。完整列表见 [环境变量](./env-vars.md)。
+
+## 普通运行参数的优先级
+
+对其它运行参数（模型别名、Plan / yolo 模式、Skills 目录等），按下面顺序解析：
+
+1. **命令行选项**：本次启动指定的参数，覆盖所有其他来源；仅对本次启动生效。
+2. **用户配置文件**：`$KIMI_CODE_HOME/config.toml`（缺省为 `~/.kimi-code/config.toml`），保存长期偏好。
+
+少数环境变量会明确覆盖配置文件中的相关字段，例如 `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` 的优先级高于 `[background].keep_alive_on_exit`。这类例外会在 [环境变量](./env-vars.md) 与对应的 [配置文件](./config-files.md) 字段说明里标出。
+
+::: warning 注意
+普通运行参数**不会**从 shell 环境变量取后备值。例如供应商 `api_key` / `base_url` 只读取 `config.toml` 中的字段（包括 `[providers.<name>.env]` 子表），不会回退到 `export KIMI_API_KEY` 这类终端变量；详见下文 [供应商凭证](#供应商凭证)。
+:::
+
+Kimi Code CLI 目前只读取一份用户级配置文件，没有项目级（仓库内）配置文件机制。如果需要在不同项目之间隔离配置，可以通过 `KIMI_CODE_HOME` 指向不同的数据目录（详见下文 [典型场景](#典型场景)），或在启动时用 CLI 选项临时覆盖具体字段。
+
+## 配置文件
+
+配置文件位置由 `KIMI_CODE_HOME` 环境变量控制，未设置时使用 `~/.kimi-code/`。文件名固定为 `config.toml`，目录会以 `0o700` 权限创建。文件内可声明 `default_provider`、`default_model`、`providers`、`models`、`thinking`、`loop_control` 等长期偏好。具体字段见 [配置文件](./config-files.md)。
+
+## 供应商凭证
+
+供应商凭证（`api_key`、`base_url`）的解析有自己的规则：Kimi Code CLI 只从 `config.toml` 中读取供应商字段，**不会**从 shell 环境变量取后备值。仅在终端里 `export KIMI_API_KEY` 不会让某个 `[providers.<name>]` 自动获得凭证，必须显式写到配置文件里。
+
+对单个供应商而言，凭证按以下顺序解析：
+
+1. `[providers.<name>].api_key` —— 配置文件中显式写入的密钥，优先级最高。
+2. `[providers.<name>.env]` 子表中的对应键（如 `KIMI_API_KEY`、`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、`GOOGLE_API_KEY`）—— 把习惯写在 shell 里的环境变量名搬到 TOML 子表里，仅在 `api_key` 留空时生效。这只是配置子表的形式，不会真正修改进程环境。
+3. 若两者都缺，启动时会报错并提示对应的供应商缺少凭证。
+
+`base_url` 的解析方式与 `api_key` 类似：先读 `[providers.<name>].base_url`，再读 `[providers.<name>.env]` 中的 `*_BASE_URL` 键（如 `ANTHROPIC_BASE_URL`、`OPENAI_BASE_URL`、`KIMI_BASE_URL`）。供应商类型与字段的完整说明见 [供应商](./providers.md)。
+
+## 进程级环境变量
+
+`process.env` 中的变量在 Kimi Code CLI 启动时被读取，作用分成上文 [环境变量的三类作用](#环境变量的三类作用) 中已说明的三类：
+
+- **数据根目录与日志路径**：`KIMI_CODE_HOME` 切换 `~/.kimi-code/`；`KIMI_LOG_LEVEL` 等控制诊断日志。
+- **运行时开关**：`KIMI_DISABLE_TELEMETRY` 关闭遥测（会覆盖 `config.toml` 中 `telemetry = true` 的设置）。
+- **OAuth 端点与诊断**：`KIMI_CODE_OAUTH_HOST`、`KIMI_OAUTH_HOST`、`KIMI_CODE_BASE_URL` 控制托管 Kimi 登录端点；`KIMI_LOG_LEVEL` 等控制诊断日志。
+- **后台任务退出策略**：`KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` 覆盖 `[background].keep_alive_on_exit`，用于临时决定本次进程退出时是否保留后台任务。
+
+完整变量与适用范围见 [环境变量](./env-vars.md)。
+
+## 命令行选项
+
+启动时通过 CLI 选项指定的参数优先级最高，仅对本次启动生效。常用选项：
+
+| 选项 | 作用 |
+| --- | --- |
+| `-S, --session [id]` | 恢复指定 session；不带 id 时进入交互式选择 |
+| `-C, --continue` | 续上当前工作目录的上一次 session |
+| `-y, --yolo` | 自动批准普通工具调用（别名 `--yes`、`--auto-approve`） |
+| `--plan` | 以 Plan 模式启动 |
+| `-m, --model <model>` | 指定本次启动使用的模型别名 |
+| `-p, --prompt <prompt>` | 以非交互模式执行单次提示词后退出 |
+| `--output-format <format>` | 指定 `-p` 模式的输出格式，可选 `text` 或 `stream-json` |
+| `--skills-dir <dir>` | 替换自动发现的 Skills 目录（可重复指定多个，仅对本次启动生效） |
+
+选项互斥规则：
+
+- `--output-format` 只能在 prompt 模式（`-p / --prompt`）下使用。
+- `--prompt` 不能与 `--yolo` 同用，也不能与 `--plan` 同用。
+- `--prompt` 模式下使用 `-S / --session` 必须给出 session id，不接受不带 id 的交互式选择。
+- `--continue` 与 `--session` 不能同用。
+- 在非 prompt 模式下，`--yolo` 不能与 `--continue` 或 `--session` 组合；`--plan` 不能与 `--continue` 或 `--session` 组合。
+- `--yolo` 与 `--plan` 可以同时使用。
+
+::: tip 提示
+`--skills-dir` 替换本次启动自动发现的 Skills 目录，适合一次性指定；若需长期追加搜索目录，可在 `config.toml` 顶层写 `extra_skill_dirs`（详见 [Agent Skills](../customization/skills.md)），两者语义不同，可按需选用。
+:::
+
+## 典型场景
+
+**切换数据目录用于隔离测试。** `KIMI_CODE_HOME` 会同时影响配置文件、session 存档、ripgrep 缓存等所有数据位置：
+
+```sh
+KIMI_CODE_HOME="$PWD/.kimi-sandbox" kimi
+```
+
+**在配置文件中预置临时凭证。** 由于供应商凭证只读取 `config.toml`，若要在一次启动里使用另一个 API key，可以预先把它写入 `[providers.<name>.env]` 子表：
+
+```toml
+[providers.kimi.env]
+KIMI_API_KEY = "sk-test"
+```
+
+也可以直接为该供应商写 `api_key`；两者优先级见上文 [供应商凭证](#供应商凭证)。
+
+**本次启动跳过审批。** 适用于已知安全的批处理任务：
+
+```sh
+kimi --yolo
+```
+
+**本次启动进入 Plan 模式。** 若希望默认行为也如此，可在配置文件中设置 `default_plan_mode = true`：
+
+```sh
+kimi --plan
+```
diff --git a/docs/zh/configuration/providers.md b/docs/zh/configuration/providers.md
new file mode 100644
index 000000000..bb7e79d78
--- /dev/null
+++ b/docs/zh/configuration/providers.md
@@ -0,0 +1,135 @@
+# 平台与模型
+
+Kimi Code CLI 通过统一的供应商抽象对接多家 LLM 平台。每个供应商负责一种 API 协议，模型则在供应商之上声明自己的名称、上下文长度和能力。本页介绍当前支持的所有供应商类型，以及如何在 `~/.kimi-code/config.toml` 中配置它们。
+
+## 概述
+
+`providers` 表里的 `type` 字段决定使用哪一种实现。目前支持的类型有：
+
+| 类型 | 协议 | 典型平台 |
+| --- | --- | --- |
+| `kimi` | OpenAI 兼容（chat completions 风格） | Kimi Code、Moonshot AI 开放平台 |
+| `anthropic` | Anthropic Messages | Claude API |
+| `openai` | OpenAI Chat Completions | OpenAI 及其兼容服务 |
+| `openai_responses` | OpenAI Responses API | OpenAI 较新的 Responses 接口 |
+| `google-genai` | Google GenAI | Gemini API |
+| `vertexai` | Google GenAI on Vertex | Google Cloud Vertex AI |
+
+所有供应商默认以流式方式与模型交互；thinking、视觉、工具调用等能力按模型名前缀自动匹配，无需在配置里手写。
+
+API 密钥可以写在 `api_key` 字段，也可以放在 `[providers.<name>.env]` 子表里。优先级为 `api_key` > 子表键 > 若均未配置，启动时将报错。**Kimi Code CLI 不会从 shell 环境变量自动取后备值**——仅在终端里 `export KIMI_API_KEY` 不会让某个供应商自动获得凭证，需要显式写入 `config.toml`（详见 [配置覆盖：供应商凭证](./overrides.md#供应商凭证)）。`api_key` 与 `oauth` 在同一个供应商上互斥，同时设置会在解析模型时报错；OAuth 由内置登录流程自动注入，无需手写。
+
+`[providers.<name>.env]` 子表可以在 `config.toml` 内直接提供凭证或端点覆盖，这些值仅对当前供应商生效，不会泄漏到全局 shell 环境：
+
+```toml
+[providers.my-anthropic.env]
+ANTHROPIC_API_KEY = "sk-ant-xxxxx"
+ANTHROPIC_BASE_URL = "https://my-proxy.example.com"
+```
+
+切换供应商最常见的方式有两种：在 TUI 里用 `/model` 斜杠命令选择已配置的模型，或者直接编辑 `config.toml` 调整 `[providers.*]` 与 `[models.*]` 表。完整字段说明见 [配置文件](./config-files.md)。
+
+## `kimi`
+
+`kimi` 通过 OpenAI 兼容协议对接 Moonshot AI。
+
+- 默认 `base_url`：`https://api.moonshot.ai/v1`
+- 环境变量：`KIMI_API_KEY`、`KIMI_BASE_URL`
+- 额外能力：支持视频上传
+
+```toml
+[providers.kimi]
+type = "kimi"
+base_url = "https://api.moonshot.ai/v1"
+api_key = "sk-xxxxx"
+```
+
+Kimi Code 托管服务在 OAuth 登录后会自动配置 `base_url` 与凭证，无需手动填写；详见 [OAuth 与凭证注入](#oauth-与凭证注入) 与 [环境变量](./env-vars.md)。
+
+## `anthropic`
+
+`anthropic` 用于对接 Claude API。标准 Claude 模型会自动启用视觉、工具调用及 Thinking（如支持）。若使用自定义或尚未覆盖的模型，需在 `[models.<alias>]` 中显式声明 `capabilities`。
+
+Thinking 可通过 `/model`、`/settings` 或配置控制。
+
+- 默认 `base_url`：跟随 Anthropic SDK 默认值
+- 环境变量：`ANTHROPIC_API_KEY`、`ANTHROPIC_BASE_URL`
+- 默认 `max_tokens`：按模型自动设置。如需覆盖（例如测试或为尚未识别的别名指定值），在模型别名上设置 `max_output_size`（详见 [`config-files.md`](./config-files.md#models)）。已识别别名的覆盖值会被限制在服务端允许的上限内。
+
+```toml
+[providers.anthropic]
+type = "anthropic"
+api_key = "sk-ant-xxxxx"
+
+[models."claude-opus-4-7"]
+provider = "anthropic"
+model = "claude-opus-4-7"
+max_context_size = 200000
+# 可选：在测试时降低输出预算，或为本 CLI 尚未识别的模型指定一个值。
+# 省略则使用上述按模型推导出的默认值。
+# max_output_size = 32000
+```
+
+## `openai`
+
+`openai` 对应 OpenAI Chat Completions 协议，也可用来连接任何兼容该协议的第三方服务（自行覆盖 `base_url` 即可）。thinking、视觉、工具调用等能力按模型名自动推断。
+
+- 默认 `base_url`：`https://api.openai.com/v1`
+- 环境变量：`OPENAI_API_KEY`、`OPENAI_BASE_URL`
+
+```toml
+[providers.openai]
+type = "openai"
+base_url = "https://api.openai.com/v1"
+api_key = "sk-xxxxx"
+```
+
+## `openai_responses`
+
+`openai_responses` 对应 OpenAI 较新的 Responses API。它始终以流式方式工作，能力按模型名自动推断。
+
+- 默认 `base_url`：`https://api.openai.com/v1`
+- 环境变量：`OPENAI_API_KEY`、`OPENAI_BASE_URL`
+
+```toml
+[providers.openai-responses]
+type = "openai_responses"
+base_url = "https://api.openai.com/v1"
+api_key = "sk-xxxxx"
+```
+
+## `google-genai`
+
+`google-genai` 用于直连 Google Gemini API。thinking、视觉及多模态能力按模型名自动推断。
+
+- 环境变量：`GOOGLE_API_KEY`
+
+```toml
+[providers.gemini]
+type = "google-genai"
+api_key = "xxxxx"
+```
+
+## `vertexai`
+
+`vertexai` 与 `google-genai` 共用同一份实现，`type = "vertexai"` 时切换到 Vertex AI 的访问路径。
+
+认证遵循 Google Cloud 的标准流程：通过 `gcloud auth application-default login` 或设置 `GOOGLE_APPLICATION_CREDENTIALS` 指向服务账号 JSON 完成鉴权（这一步是 Google SDK 的通用机制，与 Kimi Code 配置无关）。**项目与区域必须写在 `[providers.vertexai.env]` 子表中**——直接 `export GOOGLE_CLOUD_PROJECT`、`export GOOGLE_CLOUD_LOCATION` 不会被 CLI 读取。`GOOGLE_CLOUD_LOCATION` 缺失时，CLI 会尝试从 `base_url` 自动推断。API 密钥（`VERTEXAI_API_KEY` 或 `GOOGLE_API_KEY`）同样写在子表内。
+
+```toml
+[providers.vertexai]
+type = "vertexai"
+
+[providers.vertexai.env]
+GOOGLE_CLOUD_PROJECT = "my-gcp-project"
+GOOGLE_CLOUD_LOCATION = "us-central1"
+```
+
+```sh
+gcloud auth application-default login   # 一次性
+kimi
+```
+
+## OAuth 与凭证注入
+
+部分平台（如 Kimi Code 托管服务）使用 OAuth 而非静态 API 密钥。凭证由内置的 kimi-oauth 工具链在运行时注入，登录流程会自动负责写入与刷新，普通配置文件无需手工配置这部分内容。
diff --git a/docs/zh/customization/agents.md b/docs/zh/customization/agents.md
new file mode 100644
index 000000000..5cf2a6ef3
--- /dev/null
+++ b/docs/zh/customization/agents.md
@@ -0,0 +1,45 @@
+# Agent 与子 Agent
+
+Kimi Code CLI 中的 Agent 是驱动会话的核心。一次会话始终由一个主 Agent 主持，主 Agent 在执行任务过程中可以根据需要派发子 Agent 来处理更聚焦的子任务。
+
+主 Agent 负责理解用户的整体意图、规划步骤、与用户对话、调用工具，并最终汇总结果。它的上下文贯穿整个会话，是用户在终端中直接交互的对象。
+
+子 Agent 则是主 Agent 临时派生出来的"助手"。它接受一份明确的任务描述，在自己的上下文里独立完成工作，再把结论返回给主 Agent。子 Agent 不会与用户直接对话，也不会混入主 Agent 的上下文历史。这种分工特别适合"探索代码库"、"审阅大段实现"、"规划复杂改动"这类边界清晰、需要大量阅读但产物较短的工作。
+
+## 内置子 Agent
+
+Kimi Code CLI 内置了三种子 Agent，分别面向不同的任务形态，开箱即用：
+
+- **`coder`**：默认子 Agent，通用的软件工程助手，可以读写文件、执行命令、搜索代码并落地具体改动。
+- **`explore`**：代码库探索专用，只做只读操作，不会修改任何文件。适合在不修改文件的前提下快速搜索、阅读和总结仓库。
+- **`plan`**：实现规划与架构设计专用，工具集进一步收窄，连 Shell 命令都不提供，专注于"想清楚怎么做"而不是"动手做"。
+
+## 调用方式
+
+子 Agent 由主 Agent 自动调度。主 Agent 会根据任务复杂度、上下文消耗以及子任务的独立性，在需要时自动派发，无需用户手动指定。
+
+每次派发都会在终端中以审批请求的形式呈现（除非命中已有的 allow 规则或处于 YOLO 模式），方便你审视任务描述。你可以在与主 Agent 的对话中直接指定子 Agent 类型，例如"先用 explore 把相关文件梳理一遍再动手"。
+
+子 Agent 也可以放在后台运行，完成后结果会自动回到主 Agent，无需手动轮询。也可以唤回已有的子 Agent 实例继续推进同一任务。
+
+## 上下文隔离与资源开销
+
+每个子 Agent 都拥有完全独立的上下文窗口。它看不到主 Agent 的对话历史，只能看到主 Agent 显式传入的任务描述。子 Agent 自己的中间思考和工具调用记录不会回流到主 Agent，只有最终结果会出现在主 Agent 的上下文里。
+
+这种隔离带来两个好处：一是主 Agent 的上下文保持精炼，长会话中不会被大量探索性日志撑满；二是多个子 Agent 可以并行运行，互不干扰。
+
+需要注意的是，每个子 Agent 都会独立消耗模型 token，因此简单任务上没有必要派发子 Agent，主 Agent 直接处理反而更经济。子 Agent 也不支持继续嵌套调度。
+
+## 权限继承
+
+子 Agent 的权限规则继承自主 Agent：主 Agent 通过 `/permission` 或在审批中接受的"始终允许"规则，会自动覆盖到它派发出的所有子 Agent，子 Agent 不需要重新审批同一类工具调用。`Agent` 工具本身默认放行，因此主 Agent 可以在不打断用户的前提下完成多次委派。
+
+如果你希望某一类工具在子 Agent 中始终不可用，应该收紧主 Agent 的权限规则。
+
+## 会话目录中的存储位置
+
+子 Agent 的运行状态会持久化到当前会话目录的 `agents/` 子目录下，每个子 Agent 实例对应一个独立的子目录，其中包含按时间顺序记录提示词、消息历史与最终状态的 `wire.jsonl` 文件。后台子 Agent 还会通过 `tasks/` 子目录暴露生命周期状态。
+
+::: warning 注意
+会话目录、wire 文件和任务记录都属于本地调试材料，可能包含用户 prompt、命令输出、仓库路径、工具返回内容或凭证痕迹。不要把这些文件直接提交到公开仓库、issue 或聊天记录里；确实需要分享时，请先脱敏。
+:::
diff --git a/docs/zh/customization/hooks.md b/docs/zh/customization/hooks.md
new file mode 100644
index 000000000..f55c36e52
--- /dev/null
+++ b/docs/zh/customization/hooks.md
@@ -0,0 +1,150 @@
+# Hooks
+
+Hooks 让你在 Kimi Code CLI 的关键生命周期点运行本地命令。它适合做轻量的策略检查、审计记录、桌面通知或与本地自动化脚本联动，例如在危险工具调用前拦截，或在后台子 Agent 完成后触发通知。
+
+Hook 命令在本地 Shell 中运行，Kimi Code CLI 会把事件 payload 以 JSON 写入命令的 stdin。命令的 stdout、stderr 和退出码决定 hook 的结果；除明确阻断的情况外，hook 失败时默认放行（fail-open），不会让主流程因为脚本异常而中断。
+
+::: warning 注意
+Hooks 适合做本地提醒和轻量拦截，不应作为唯一安全边界。脚本报错、超时或返回普通非零退出码时会默认放行（fail-open）；高风险工具调用仍应依赖权限审批和人工确认。
+:::
+
+## 配置
+
+在 `~/.kimi-code/config.toml` 中使用 `[[hooks]]` 数组表声明 hook：
+
+```toml
+[[hooks]]
+event = "PreToolUse"
+matcher = "Bash"
+command = "node ~/.kimi-code/hooks/check-bash.mjs"
+timeout = 5
+
+[[hooks]]
+event = "Notification"
+matcher = "task\\.completed"
+command = "terminal-notifier -title Kimi -message 'Background task finished'"
+```
+
+字段含义如下：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `event` | `string` | 是 | 事件名，取值必须是下文「事件」表中的某一项；其他值会让整份配置加载失败 |
+| `matcher` | `string` | 否 | 用于匹配事件目标的正则表达式；缺省或空字符串表示匹配全部 |
+| `command` | `string` | 是 | 要运行的 Shell 命令，长度不能为零 |
+| `timeout` | `integer` | 否 | 超时时间，单位秒，范围 1–600；未设置时默认为 30 秒 |
+
+每个 `[[hooks]]` 表只允许出现这四个字段，写错或多写字段会导致配置文件解析失败。
+
+同一次事件触发时，命中的多个 hook 会并行运行；如果多个配置项的 `command` 完全相同，只会运行一次。`matcher` 使用 JavaScript 正则表达式语义；非法正则会被静默跳过，等同于不匹配。
+
+Hook 命令通过 Shell 启动（等价于 `sh -c <command>`），子进程的工作目录就是当前会话的 `cwd`。在非 Windows 平台上，子进程会被放入独立的进程组，超时或会话被中断时会先发送 `SIGTERM`、100 毫秒后再发送 `SIGKILL`，确保 hook 内部 fork 出的子进程也能被一并清理。
+
+传给 hook 的 JSON 字段统一使用 snake_case。每个 payload 都包含：
+
+```json
+{
+  "hook_event_name": "PreToolUse",
+  "session_id": "session_abc",
+  "cwd": "/path/to/project"
+}
+```
+
+其余字段由事件类型决定，见下文事件表。
+
+## 返回值
+
+Hook 命令的退出码和 stdout 会被解释为以下结果：
+
+| 结果 | 行为 |
+| --- | --- |
+| 退出码 `0` | 放行；如果 stdout 是 JSON，可从 `message` 或 `hookSpecificOutput.message` 读取文本 |
+| 退出码 `2` | 阻断；stderr 会作为阻断原因 |
+| 其他非零退出码 | 默认放行（fail-open） |
+| 超时或进程异常 | 默认放行（fail-open） |
+
+当 stdout 是 JSON，并且 `hookSpecificOutput.permissionDecision` 为 `deny` 时，也会被视为阻断：
+
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Use rg instead"
+  }
+}
+```
+
+阻断只对支持控制流的事件生效。例如 `PreToolUse` 可以阻断工具调用，`Stop` 可以让当前轮次追加一次继续消息。观察型事件（例如 `PostToolUse`、`PostToolUseFailure`、`PostCompact`、`SubagentStop`、`StopFailure`、`Notification`）以「即发即忘（fire-and-forget）」方式异步触发，返回值被忽略，不会改变主流程。`PreCompact` 使用 `trigger`（而非 `triggerBlock`）调用，返回值同样被完全忽略，不属于可阻断事件。
+
+阻断生效时，如果脚本未通过 stderr 或 JSON 输出提供原因，CLI 会回退到 `Blocked by <event> hook` 作为占位原因。`PreToolUse` 阻断会作为工具失败结果写回上下文，模型可以根据原因选择替代方案。
+
+## 事件
+
+当前会自动触发的事件如下：
+
+| 事件 | Matcher | 主要 payload | 行为 |
+| --- | --- | --- | --- |
+| `UserPromptSubmit` | 用户提交的文本内容 | `prompt`（`ContentPart[]` 数组） | 仅对真实 User 消息触发。hook 返回的文本会包裹为 hook 结果，写入会话历史用于 transcript/replay，并展示给用户；当前 LLM 轮次会继续，但不会把 hook 结果发给模型；若 hook 阻断，阻断原因会作为 Assistant 消息返回给用户，且不再调用模型；若所有 hook 均无输出，正常 LLM 轮次继续 |
+| `PreToolUse` | 工具名 | `tool_name`、`tool_input`、`tool_call_id` | 在权限检查前触发；阻断后工具不会执行 |
+| `PostToolUse` | 工具名 | `tool_name`、`tool_input`、`tool_call_id`、`tool_output` | 工具成功后触发；`tool_output` 被截断至前 2000 个字符 |
+| `PostToolUseFailure` | 工具名 | `tool_name`、`tool_input`、`tool_call_id`、`error` | 工具失败或被 hook 阻断后触发 |
+| `Stop` | 空字符串 | `stop_hook_active` | 模型准备停止时触发；阻断后会把原因直接作为系统触发的 User 消息追加进上下文，并最多继续一次 |
+| `StopFailure` | 错误类型 | `error_type`、`error_message` | 当前轮次因非取消错误失败后触发 |
+| `SessionStart` | `startup` 或 `resume` | `source` | 新会话主 Agent 创建后，或历史会话恢复完成后触发 |
+| `SessionEnd` | `exit` | `reason` | 会话关闭并 flush 元数据后触发 |
+| `SubagentStart` | 子 Agent 名称 | `agent_name`、`prompt` | 子 Agent 配置完成、真正开始运行前触发；`prompt` 被截断至前 500 个字符 |
+| `SubagentStop` | 子 Agent 名称 | `agent_name`、`response` | 子 Agent 成功完成后异步触发，失败时不触发；`response` 被截断至前 500 个字符 |
+| `PreCompact` | `manual` 或 `auto` | `trigger`、`token_count` | 上下文压缩真正开始前触发；此事件使用 `trigger`（非 `triggerBlock`）调用，返回值被完全忽略，阻断决策不会被读取 |
+| `PostCompact` | `manual` 或 `auto` | `trigger`、`estimated_token_count` | 上下文压缩成功写入后异步触发；阻断结果不会改变主流程 |
+| `Notification` | 通知类型 | `sink`、`notification_type`、`title`、`body`、`severity`、`source_kind`、`source_id` | 当前在后台子 Agent 结果写入上下文时触发；`notification_type` 取值为 `task.completed`、`task.failed`、`task.killed` 或 `task.lost`，sink 为 `context` |
+
+`UserPromptSubmit` 的返回文本会被包裹成一条 hook 结果：
+
+```xml
+<hook_result hook_event="UserPromptSubmit">
+hook response
+</hook_result>
+```
+
+如果多个 `UserPromptSubmit` hook 返回文本，每个结果都会拥有独立的 `<hook_result>` 标签。这条消息会带有 hook 结果来源，用于 transcript/replay，但不会发给模型。模型只看到原始用户输入，当前轮次继续。
+
+如果 `UserPromptSubmit` hook 阻断请求，阻断原因会使用同样格式返回给用户，但本轮不会继续请求模型。
+
+`Stop` 的阻断原因会直接作为系统触发的 User 消息写入上下文，让当前轮次继续：
+
+```text
+continue from hook
+```
+
+## 示例：阻断危险 Shell 命令
+
+下面的 hook 会在 `Bash` 工具调用前读取 stdin 中的 `tool_input.command`。如果命令包含 `rm -rf`，脚本以退出码 `2` 结束并把原因写到 stderr：
+
+::: warning 注意
+这个示例只演示 hook 如何阻断工具调用，不是完整的 Shell 安全解析器。真实策略更适合使用 allowlist，或用专门的 Shell 解析逻辑处理引号、变量展开、别名和多段命令。
+:::
+
+```toml
+[[hooks]]
+event = "PreToolUse"
+matcher = "Bash"
+command = "node ~/.kimi-code/hooks/block-dangerous-bash.mjs"
+timeout = 5
+```
+
+```js
+let input = '';
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+});
+process.stdin.on('end', () => {
+  const payload = JSON.parse(input);
+  const command = payload.tool_input?.command ?? '';
+  if (command.includes('rm -rf')) {
+    console.error('Blocked dangerous shell command');
+    process.exit(2);
+  }
+});
+```
+
+当 hook 阻断工具调用时，Kimi Code CLI 会把阻断原因作为工具失败结果写回上下文，模型可以据此选择更安全的替代方案。
diff --git a/docs/zh/customization/mcp.md b/docs/zh/customization/mcp.md
new file mode 100644
index 000000000..997032f79
--- /dev/null
+++ b/docs/zh/customization/mcp.md
@@ -0,0 +1,83 @@
+# Model Context Protocol
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 是一个开放协议，让模型可以安全地调用外部进程或服务暴露的工具。Kimi Code CLI 作为 MCP client 接入这些外部工具，并把它们与内置工具（`Read`、`Bash`、`Grep` 等）一起暴露给 Agent 使用。
+
+## 集成范围
+
+Kimi Code CLI 支持通过 stdio（本地子进程）和 HTTP 两种方式接入外部 MCP 服务器。接入的 MCP 工具与内置工具一样，可以被 Agent 调用、受权限规则约束、参与审批流程，行为上没有差异。
+
+## 配置与登录
+
+MCP server 配置写在 `mcp.json` 中，分为两层：
+
+- 用户级：`~/.kimi-code/mcp.json`（或 `$KIMI_CODE_HOME/mcp.json`），跨项目共享
+- 项目级：`.kimi-code/mcp.json`，仅当前仓库
+
+项目级覆盖用户级同名条目。
+
+最方便的入口是在 TUI 中运行 `/mcp-config`，它会引导你新增、编辑或删除 server。要查看当前连接状态，可运行 `/mcp`。
+
+`mcp.json` 的顶层结构如下：
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    },
+    "linear": {
+      "url": "https://mcp.linear.app/mcp"
+    }
+  }
+}
+```
+
+含 `command` 字段的条目为 stdio server，含 `url` 字段的条目为 HTTP server，通常不需要手写 `transport` 字段。HTTP server 支持通过 `headers` 或 `bearerTokenEnvVar` 提供静态凭证；需要 OAuth 时，可运行 `/mcp-config login <server-name>` 完成浏览器授权。
+
+可选字段：
+
+| 字段 | 类型 | 适用 transport | 说明 |
+| --- | --- | --- | --- |
+| `env` | `Record<string, string>` | stdio | 注入子进程的环境变量 |
+| `cwd` | `string` | stdio | 子进程工作目录 |
+| `headers` | `Record<string, string>` | HTTP | 附加到每次请求的静态请求头 |
+| `enabled` | `boolean` | 两者 | 设为 `false` 可禁用该 server |
+| `startupTimeoutMs` | `number` | 两者 | 连接超时，默认 `30000` |
+| `toolTimeoutMs` | `number` | 两者 | 单次工具调用超时 |
+| `enabledTools` | `string[]` | 两者 | 白名单 |
+| `disabledTools` | `string[]` | 两者 | 黑名单 |
+
+::: warning 注意
+项目级 `.kimi-code/mcp.json` 中的 stdio 条目会在会话启动时执行本地命令，只在你信任的仓库里启用。
+:::
+
+## 工具命名与权限
+
+MCP 工具按 `mcp__<server>__<tool>` 命名。权限匹配支持 `*` 和 `**` 通配，例如 `mcp__github__*` 命中该 server 下所有工具。
+
+未命中权限规则的调用会触发审批请求；在审批弹窗中选择 "Approve for this session" 后，后续同类调用将自动放行。
+
+也可以在 `config.toml` 的 `[[permission.rules]]` 中预置永久规则：
+
+```toml
+[[permission.rules]]
+decision = "allow"
+pattern = "mcp__github__*"
+
+[[permission.rules]]
+decision = "deny"
+pattern = "mcp__filesystem__write_file"
+```
+
+`pattern` 的完整语法及 `decision`、`scope` 等字段的取值详见 [配置文件](../configuration/config-files.md#permission)。
+
+## 安全性
+
+- 只接入可信来源的 MCP server
+- 在审批请求中检查工具名与参数是否合理
+- 对高风险工具维持手动审批，避免宽泛的 `mcp__*` 通配放行
+
+::: warning 注意
+在 YOLO 模式下，MCP 工具调用会被自动批准。仅在完全信任所接入的 MCP server 时使用此模式。
+:::
diff --git a/docs/zh/customization/skills.md b/docs/zh/customization/skills.md
new file mode 100644
index 000000000..9b0415675
--- /dev/null
+++ b/docs/zh/customization/skills.md
@@ -0,0 +1,127 @@
+# Agent Skills
+
+Agent Skills 是 Kimi Code CLI 用来扩展模型能力的轻量机制。一个 Skill 就是一份带 YAML frontmatter 的 Markdown 文档，描述某项专业知识或工作流程。Kimi Code CLI 在启动时自动扫描已知目录，把发现的 Skill 注入到系统提示词中，让 Agent 知道当前会话里有哪些可用的 Skill。
+
+相比把同样的指引每次都粘到提示词里，Skill 的好处在于：内容沉淀在文件里、可以跨项目和团队复用、可以通过斜杠命令一键加载，也可以让模型在需要时自动调用。常见用法是把代码风格、提交规范、审查流程等固化为 Skill。
+
+## 创建 Skill
+
+Skill 文件需要放在 [已知的扫描目录](#skill-存放位置) 中。一个 Skill 可以使用两种文件结构：
+
+- **目录形式（推荐）**：在 Skills 目录下创建一个子目录，主文件命名为 `SKILL.md`，必要时可在同目录下放置脚本、参考资料等辅助文件。如果同一目录下同时存在 `<name>/SKILL.md` 和同名的 `<name>.md`，以子目录为准。
+- **扁平形式**：直接使用单个 `.md` 文件，Skill 名称取文件名（去掉 `.md`）。
+
+### 文件格式
+
+`SKILL.md` 由 YAML frontmatter 和 Markdown 正文两部分组成。
+
+```markdown
+---
+name: code-style
+description: 项目代码风格规范，定义命名、缩进、注释和文件组织
+type: prompt
+whenToUse: 当用户让我编写、修改或审查项目源代码时
+disableModelInvocation: false
+arguments:
+  - target
+  - mode
+---
+
+请按下述规范处理代码：
+
+- 缩进使用 2 空格
+- 变量名使用 `camelCase`，类型名使用 `PascalCase`
+- 公开函数必须带 TSDoc 注释
+- 单行不超过 100 字符
+```
+
+### Frontmatter 字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `name` | Skill 名称。目录型 `SKILL.md` 中为必填；扁平 `.md` 文件省略时使用文件名。名称大小写不敏感。 |
+| `description` | 一行总结。模型用它来判断何时使用这个 Skill。目录型 `SKILL.md` 中为必填；扁平 `.md` 文件省略时回退到正文第一行非空内容（截到 240 字符）。 |
+| `type` | Skill 类型。可选 `prompt`（默认）、`inline`（与 `prompt` 语义相同）、`flow`（仅支持手动调用，不支持模型自动调用）。其它值会被跳过。 |
+| `whenToUse` | 触发场景描述。也接受 `when-to-use`、`when_to_use` 写法。 |
+| `disableModelInvocation` | 设为 `true` 禁止模型自动调用此 Skill。也接受 `disable-model-invocation`、`disable_model_invocation` 写法。 |
+| `arguments` | 命名参数列表，可写成字符串数组或空白分隔的字符串（如 `arguments: target mode`）。声明后，正文可用 `$<name>` 读取参数；纯数字或空字符串会被忽略。 |
+
+::: warning 注意
+目录型 `SKILL.md` 中 `name` 和 `description` **必须**显式填写，省略任意一项均会导致解析失败。
+:::
+
+### 正文占位符
+
+正文在发送给模型前会展开少量占位符：
+
+- `$ARGUMENTS`：调用时附带的完整原始参数字符串
+- `$ARGUMENTS[0]`、`$ARGUMENTS[1]` 及简写 `$0`、`$1`：按空白分词后的位置参数（从 0 开始）
+- `$<name>`：`arguments` 中声明的命名参数
+- `${KIMI_SKILL_DIR}`：当前 Skill 文件所在目录
+
+位置参数支持单双引号包裹，如 `/skill:commit "fix login" patch` 中 `$0` 展开为 `fix login`。若正文不含任何参数占位符，调用时附带的文本会以 `\n\nARGUMENTS: <文本>` 的形式追加到正文末尾。
+
+## Skill 存放位置
+
+Kimi Code CLI 按作用域分四档扫描，越具体的作用域优先级越高：
+
+**Project > User > Extra > Built-in**
+
+用户级：
+
+- `~/.kimi-code/skills/`
+- `~/.agents/skills/`
+
+项目级（项目根 = 工作目录向上最近的包含 `.git` 的目录）：
+
+- `.kimi-code/skills/`
+- `.agents/skills/`
+
+额外目录通过 `config.toml` 顶层的 `extra_skill_dirs` 字段声明：
+
+```toml
+extra_skill_dirs = ["~/team-skills", ".agents/team-skills"]
+```
+
+内置 Skills 随 CLI 一起分发，优先级最低。
+
+## 调用 Skill
+
+用户可以通过斜杠命令主动调用：
+
+```
+/skill:code-style
+/skill:git-commits 修复登录接口的并发问题
+```
+
+模型也可以根据 `description` 和 `whenToUse` 自动调用 Skill（除非 `disableModelInvocation` 设为 `true` 或 `type` 为 `flow`）。模型调用时，正文先展开占位符，再注入到系统提示中。Skill 调用时最多允许嵌套 3 层，超过后会被终止。
+
+## 完整示例
+
+```markdown
+---
+name: review-pr
+description: 按团队标准审查一个 Pull Request，输出结构化的 review 报告
+type: prompt
+whenToUse: 当用户让我审查 PR、检查代码变更或评估提交质量时
+arguments:
+  - pr_ref
+---
+
+请按照以下流程审查用户指定的 PR：$pr_ref
+
+1. 拉取并阅读 `$pr_ref` 的全部 diff。
+2. 对照以下检查项逐条核对：
+   - 是否包含对应的测试用例
+   - 公开 API 是否有文档更新
+   - 是否引入了新的依赖；若有，说明引入理由
+   - 错误处理是否覆盖了边界情况
+3. 参考同目录下的检查清单：`references/checklist.md`
+4. 输出一份 review 报告，包含：
+   - 总体结论（approve / request changes / comment）
+   - 必须修改项（blocking）
+   - 建议改进项（non-blocking）
+   - 值得肯定的地方
+```
+
+保存为 `~/.kimi-code/skills/review-pr/SKILL.md`，检查清单放在同目录的 `references/checklist.md`，然后重开会话，即可通过 `/skill:review-pr #1234` 调用，其中 `#1234` 会展开到 `$pr_ref`。
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
new file mode 100644
index 000000000..f575d64b3
--- /dev/null
+++ b/docs/zh/faq.md
@@ -0,0 +1,3 @@
+# 常见问题
+
+本页汇总新用户最常遇到的问题与简短回答。如果某一项需要更完整的解释，会在答案末尾给出相应文档的链接。
diff --git a/docs/zh/guides/getting-started.md b/docs/zh/guides/getting-started.md
new file mode 100644
index 000000000..36d519e22
--- /dev/null
+++ b/docs/zh/guides/getting-started.md
@@ -0,0 +1,135 @@
+# 开始使用
+
+## Kimi Code CLI 是什么
+
+Kimi Code CLI 是一个运行在终端中的 AI Agent，帮助你完成软件开发任务和日常的终端操作。它能阅读和编辑代码、执行 Shell 命令、搜索文件与抓取网页，并在执行过程中根据反馈自主规划和调整下一步行动。
+
+它适用于以下场景：
+
+- **编写和修改代码**：实现新功能、修复 bug、完成重构
+- **理解项目**：探索陌生的代码库，解答架构和实现层面的问题
+- **自动化任务**：批量处理文件、运行构建与测试、串联多个脚本
+
+整套 CLI 以 TypeScript 编写，通过 npm 分发，运行在 Node.js 之上。
+
+## 安装
+
+### 脚本安装（推荐）
+
+最快的安装方式是使用官方安装脚本，无需预装 Node.js：
+
+- **macOS / Linux**：
+
+```sh
+curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
+```
+
+- **Windows（PowerShell）**：
+
+```powershell
+irm https://code.kimi.com/kimi-code/install.ps1 | iex
+```
+
+脚本会自动下载最新版本、校验 checksum，并把 `kimi` 可执行文件放到你的 `PATH` 中。
+
+### npm 安装
+
+如果你更习惯通过 npm 安装，需要 Node.js 24.15.0 或更高版本：
+
+```sh
+node --version
+```
+
+包名是 `@moonshot-ai/kimi-code`：
+
+```sh
+npm install -g @moonshot-ai/kimi-code
+```
+
+或用 pnpm：
+
+```sh
+pnpm add -g @moonshot-ai/kimi-code
+```
+
+## 升级与卸载
+
+安装完成后，验证可执行文件是否就绪：
+
+```sh
+kimi --version
+```
+
+**升级**：脚本安装的用户重新运行脚本即可；npm 安装的用户执行：
+
+```sh
+npm install -g @moonshot-ai/kimi-code@latest
+```
+
+**卸载**：脚本安装的用户删除 `kimi` 可执行文件即可；npm 安装的用户执行：
+
+```sh
+npm uninstall -g @moonshot-ai/kimi-code
+```
+
+## 第一次启动
+
+进入你想要工作的项目目录，直接运行 `kimi` 启动交互界面：
+
+```sh
+cd your-project
+kimi
+```
+
+如果只想执行一条指令而不进入交互界面，可以使用 `-p` 选项：
+
+```sh
+kimi -p "帮我看一下这个项目的目录结构"
+```
+
+如需继续上一次会话，添加 `-C` 选项即可：
+
+```sh
+kimi -C
+```
+
+首次启动时，Kimi Code CLI 尚未配置任何凭证，需要配置 API 来源才能开始对话。在交互界面中输入斜杠命令 `/login` 进入登录流程：
+
+```
+/login
+```
+
+`/login` 会弹出平台选择器，支持：
+
+- **Kimi Code** — OAuth 验证码流程，在任意设备打开链接、登录并输入验证码即可授权
+- **Moonshot AI Open Platform** — 直接输入 API key 登录
+
+需要退出登录时，输入 `/logout` 即可清除当前凭证。
+
+::: tip 提示
+如果你想使用 Anthropic、OpenAI、Google 等其他供应商，需要直接编辑 `config.toml` 配置 API 密钥，详见 [平台与模型](../configuration/providers.md)。模型、供应商等运行时配置也写入 `config.toml`。配置项说明见 [配置文件](../configuration/config-files.md)、[环境变量](../configuration/env-vars.md) 和 [配置覆盖](../configuration/overrides.md)。
+:::
+
+## 第一个对话
+
+登录完成后，你就可以直接用自然语言向 Kimi Code CLI 描述任务。例如，让它先帮你熟悉一下当前项目：
+
+```
+帮我看一下这个项目的目录结构，简单介绍一下每个目录是做什么的
+```
+
+Kimi Code CLI 会自动调用文件读取、搜索和网页抓取工具，浏览相关内容之后再给出回答（读取文件、搜索网页等只读操作默认自动执行，无需确认）。对于会修改文件或执行 Shell 命令的操作，它默认会在执行前征求你的确认，你可以根据需要批准或拒绝。
+
+也可以让它做一些更具体的事，比如：
+
+```
+在 src/utils 里新增一个函数，用来把任意字符串转成 kebab-case，并补一个单元测试
+```
+
+Kimi Code CLI 会规划步骤、修改代码、运行测试，并在每一步告诉你它做了什么。
+
+在交互界面中，输入 `/help` 可以查看所有可用的 [斜杠命令](../reference/slash-commands.md)，以及常用的快捷键提示。如果想退出 Kimi Code CLI，可以输入 `/exit`；也可以按 `Ctrl-C`，界面会先清空输入框并提示再按一次，再次按下即退出；还可以在输入框为空时连按两次 `Ctrl-D` 退出。
+
+## 数据存放在哪里
+
+Kimi Code CLI 的本地数据默认保存在 `~/.kimi-code/` 目录下，包含配置文件、会话记录、日志和更新缓存等。如果你想改到别的位置，可以通过环境变量 `KIMI_CODE_HOME` 指定一个新的根目录。完整的目录结构和环境变量说明见 [数据路径](../configuration/data-locations.md) 和 [环境变量](../configuration/env-vars.md)。
diff --git a/docs/zh/guides/interaction.md b/docs/zh/guides/interaction.md
new file mode 100644
index 000000000..81985f119
--- /dev/null
+++ b/docs/zh/guides/interaction.md
@@ -0,0 +1,67 @@
+# 交互与输入
+
+Kimi Code CLI 以交互式 TUI 运行在终端中，核心是一个输入框、对话视图和状态栏。本节介绍输入操作、模式切换、审批流程和常用快捷键，完整清单可通过 `/help` 查看。
+
+## 输入框基本操作
+
+输入框接受自由文本，按 `Enter` 发送，`Shift-Enter` 换行。输入框为空时按 `↑` / `↓` 可以浏览当前工作目录的输入历史。
+
+按 `Ctrl-D` 两次退出 CLI。`Ctrl-C` 在流式输出中会中断当前轮次，空闲状态下连按两次退出。`Esc` 关闭弹窗，流式输出中也会中断轮次。
+
+## 斜杠命令与 `@` 提及
+
+以 `/` 开头的内容会识别为斜杠命令，涵盖会话管理、模式切换、配置等场景，如 `/help`、`/new`、`/sessions`、`/model` 等。完整清单见 [斜杠命令参考](../reference/slash-commands.md)。
+
+输入 `/` 后会弹出命令补全菜单，也包括来自 [Agent Skills](../customization/skills.md) 的命令。若 skill 与内置命令重名，需要用完整形式 `/skill:<name>` 调用。按 `Esc` 关闭菜单。
+
+部分命令仅在 Agent 空闲时可用，流式输出中需先中断才能调用。`/yolo`、`/plan`、`/help` 等模式切换类命令则始终可用。
+
+键入 `@` 触发文件路径补全，选中后插入相对路径，Agent 可直接读取对应文件。以点开头的目录默认隐藏，如需可显式写成 `@.github/`。
+
+## Plan 模式
+
+Plan 模式下，Agent 会先把计划写清楚再动手。按 `Shift-Tab` 或 `/plan` 切换；`/plan clear` 清除当前计划文件（仅限空闲状态）。
+
+Agent 会先输出方案等待确认，不会直接修改项目文件。计划完成后会展示内容供你审批，可选择拒绝（保持 Plan 模式）或要求修改。退出 Plan 模式仍需你确认，即使开启了 YOLO 模式也如此。
+
+## YOLO 模式
+
+YOLO 模式自动批准大多数工具调用，跳过审批确认。输入 `/yolo`（或 `/yes`）切换，空闲或流式状态下都可用。
+
+::: warning 注意
+YOLO 模式跳过普通审批，但不会跳过 Plan 模式的退出审批。
+:::
+
+## 审批流程
+
+Agent 调用可能产生副作用的工具（如修改文件、执行命令）时，会弹出审批面板让你确认。YOLO 模式和 Plan 模式下的计划文件写入除外。
+
+使用方向键选择选项，`Enter` 确认；按数字键 `1`/`2`/`3` 可直接选择对应位置。`Esc`、`Ctrl-C`、`Ctrl-D` 等同于拒绝。面板中通常有「Approve for this session」选项，选择后同类调用将自动放行。
+
+## 流式输出期间的操作
+
+Agent 思考或调用工具（流式输出）时，输入框仍可用：
+
+- `Esc` — 中断当前轮次。
+- `Ctrl-C` — 同样可以中断；空闲状态下连按两次退出 CLI。
+- `Ctrl-S` — 把输入框中的内容作为追加消息插入当前轮次。
+- `Ctrl-O` — 全局切换工具输出的折叠状态。
+
+## 外部编辑器
+
+按 `Ctrl-G` 把当前输入交给外部编辑器处理，保存后内容回填到输入框。
+
+编辑器优先级：`/editor` 配置 > `$VISUAL` > `$EDITOR`。未配置时可先运行 `/editor` 选择默认编辑器。
+
+## 粘贴图片与视频
+
+支持在输入框中直接粘贴剪贴板里的图片或视频，交给多模态模型处理：
+
+- Unix（macOS / Linux）：`Ctrl-V`
+- Windows：`Alt-V`
+
+粘贴后输入框中会出现占位符，可像普通文本一样编辑，发送时自动替换为实际内容。纯文本剪贴板会回退到普通粘贴。媒体附件仅保留在当前会话中。
+
+## 查看完整快捷键
+
+输入 `/help` 弹出包含全部快捷键和斜杠命令的面板。`↑` / `↓` 滚动，`PageUp` / `PageDown` 翻页，`Esc` / `Enter` / `q` 关闭。
diff --git a/docs/zh/guides/migration.md b/docs/zh/guides/migration.md
new file mode 100644
index 000000000..7a1b25819
--- /dev/null
+++ b/docs/zh/guides/migration.md
@@ -0,0 +1,37 @@
+# 从 kimi-cli 迁移
+
+Kimi Code CLI 是新一代的终端 Agent，也是一个全新的起点。如果你一直在使用上一代的 kimi-cli，不必从头开始——一条命令就能把配置、MCP server 与会话历史一起迁移到新版本。
+
+## 为什么迁移
+
+kimi-code 基于 Node.js 重写，不再依赖 Python 或 `uv` 工具链，安装和升级更简单，也提供开箱即用的原生二进制。
+
+终端界面重新设计，启动更快，运行更轻量。
+
+kimi-cli 会逐步过渡到 kimi-code，迁移后你可以继续使用已有的配置和会话历史。
+
+## 如何迁移
+
+迁移有两种方式。
+
+装好 kimi-code 之后**第一次运行 `kimi`** 时，它会自动检测 `~/.kimi/` 下是否存在 kimi-cli 的数据。一旦检测到，就会弹出迁移提示，你可以选择立即迁移、稍后再说，或不再提示。
+
+你也可以**随时手动运行**：
+
+```sh
+kimi migrate
+```
+
+你可以选择是否同时迁移聊天会话。如果暂时不需要历史记录，选 **Config only**；否则选 **Config + N sessions** 一并迁移。结束后会显示结果摘要。
+
+## 迁移会发生什么
+
+**会被迁移的内容**：配置（`config.toml`）、MCP 服务配置、输入历史，以及你选择迁移的聊天会话。
+
+**不会被迁移的内容**：OAuth 登录凭证和 MCP 服务的授权都不会被复制，迁移后需要在 kimi-code 里重新执行 `/login` 和重新授权 MCP 服务。kimi-cli 的插件也不在迁移范围内。
+
+::: tip 提示
+迁移**不会改动或删除** `~/.kimi/` 下的任何旧数据。kimi-cli 仍可照常使用，两者互不影响。迁移也可以重复运行，已经迁移过的会话不会被重复导入。
+:::
+
+迁移完成后，从 kimi-cli 导入的会话会带上 `[imported]` 标记，方便你与新建的会话区分。
diff --git a/docs/zh/guides/sessions.md b/docs/zh/guides/sessions.md
new file mode 100644
index 000000000..03bcdd9cd
--- /dev/null
+++ b/docs/zh/guides/sessions.md
@@ -0,0 +1,110 @@
+# 会话与上下文
+
+Kimi Code CLI 把每次对话持久化为一个「会话」，保留消息历史和元数据，可以随时关闭终端后再回来继续。本节介绍恢复会话、上下文压缩和 TUI 内的管理方法。
+
+## 会话存储
+
+所有会话保存在 `$KIMI_CODE_HOME/sessions/` 下（默认 `~/.kimi-code/sessions/`），按工作目录分组存放：
+
+```text
+~/.kimi-code/
+├── config.toml
+├── session_index.jsonl
+└── sessions/
+    └── <workDirKey>/
+        └── <sessionId>/
+            ├── state.json
+            └── agents/
+                ├── main/
+                │   └── wire.jsonl
+                └── <subagentId>/
+                    └── wire.jsonl
+```
+
+- `state.json` — 会话标题、元数据等。
+- `agents/*/wire.jsonl` — Agent 事件流。
+
+::: warning 注意
+`sessions/` 目录下的文件手动修改后可能导致会话无法恢复，建议不要手工编辑。
+:::
+
+## 启动与恢复会话
+
+默认每次执行 `kimi` 都会创建新会话。如果想接着上一次继续：
+
+**继续当前目录最近的会话：**
+
+```sh
+kimi --continue
+```
+
+**恢复指定会话：**
+
+```sh
+kimi --session abc123
+```
+
+也可以带 `-r` / `--resume`，效果相同。
+
+**交互式选择：**
+
+```sh
+kimi --session
+```
+
+::: warning 注意
+`--continue` 与 `--session` 互斥；`--yolo` 和 `--plan` 也不能与它们共用。
+:::
+
+## 在 TUI 中切换会话
+
+- `/new`（`/clear`）：切换到新会话。
+- `/sessions`（`/resume`）：浏览并恢复历史会话。
+- `/fork`：派生当前会话（详见下文）。
+- `/title <text>`（`/rename`）：设置会话标题，方便识别。不带参数时显示当前标题。
+
+`/sessions` 在流式输出期间也能浏览，但切换前需先按 `Esc` 或 `Ctrl-C` 中断。`/new`、`/fork`、`/compact` 仅在空闲时可用。
+
+## 上下文压缩
+
+对话变长时，Kimi Code CLI 会在上下文接近窗口上限时自动压缩历史消息。你也可以手动触发：
+
+```text
+/compact
+```
+
+带上自定义指引，告诉模型压缩时优先保留哪些信息：
+
+```text
+/compact 保留与数据库迁移相关的讨论
+```
+
+## 派生会话
+
+想在不破坏当前对话的前提下尝试新思路，使用 `/fork`：
+
+```text
+/fork
+```
+
+派生后的会话彼此独立，不影响原会话，你随时可以切回。
+
+## 导出会话
+
+用 `kimi export` 打包会话为 ZIP：
+
+```sh
+kimi export <sessionId>
+```
+
+不传 `sessionId` 时导出当前目录最近的会话（会交互式确认，加 `-y` 跳过）。用 `-o` 指定输出路径：
+
+```sh
+kimi export <sessionId> -o ~/Desktop/my-session.zip
+```
+
+未指定 `-o` 时，ZIP 写入当前工作目录。会话目录里的诊断日志会一并打包；此外，全局诊断日志 `$KIMI_CODE_HOME/logs/kimi-code.log`（记录 TUI 启动、登录等不属于任何会话的事件）默认也会包含进来，不需要时加 `--no-include-global-log` 跳过。
+
+::: tip 提示
+导出文件可能包含敏感信息，分享前请确认内容。
+:::
diff --git a/docs/zh/guides/use-cases.md b/docs/zh/guides/use-cases.md
new file mode 100644
index 000000000..3c70365ba
--- /dev/null
+++ b/docs/zh/guides/use-cases.md
@@ -0,0 +1,118 @@
+# 常见使用案例
+
+以下是 Kimi Code CLI 的典型使用场景和 prompt 示例。
+
+## 理解陌生项目
+
+接手陌生仓库时，用 `kimi --plan` 或按 `Shift-Tab` 进入 Plan 模式，让 Agent 先输出调研计划：
+
+```
+帮我梳理这个仓库的整体架构。重点说清楚：
+1. 入口在哪里，启动后做了什么
+2. 主要模块之间的依赖关系
+3. 配置和数据的加载流程
+最后画一张简单的模块关系图。
+```
+
+聚焦问题直接问：
+
+```
+src/runtime 下的 event loop 是怎么工作的？事件从哪里产生、又被谁消费？
+```
+
+```
+这个项目里「权限审批」是怎么实现的？涉及哪些文件，关键类型是什么？
+```
+
+大型调研可以让主 Agent 派生 **子 Agent** 并行处理子任务，详见 [Agents](../customization/agents.md)。
+
+## 实现新功能
+
+描述清楚需求和验收标准即可。复杂需求建议先用 Plan 模式生成方案。
+
+```
+在 src/utils 下新增一个 retry 工具：
+- 函数签名 retry<T>(fn: () => Promise<T>, options): Promise<T>
+- 支持 maxAttempts、initialDelayMs、backoffFactor 三个选项
+- 失败时抛出最后一次的错误
+- 并补一组单元测试覆盖成功、重试后成功、全部失败三种情况
+```
+
+如不满意，直接告诉助手即可，无需手动编辑：
+
+```
+backoff 算了一个固定值，我希望加一点抖动，避免雷击效应。改一下并更新测试。
+```
+
+## 修复 bug
+
+把现象、复现条件和期望行为一次性说清楚：
+
+```
+跑 npm test 时偶发地报这个错：
+
+  TypeError: Cannot read properties of undefined (reading 'id')
+      at SessionStore.update (src/session/store.ts:142:18)
+
+只在并发触发多个 update 的用例里出现。帮我定位原因并修复，最后跑一次完整测试确认。
+```
+
+不确定原因时，让它先调查：
+
+```
+用户反馈：登录成功后第一次刷新页面会回到登录页，再刷一次就正常了。先帮我排查可能的原因，列出几个最可疑的位置，等我确认方向后再动手改。
+```
+
+纯机械任务直接放手：
+
+```
+跑一遍测试，失败的用例都修掉，跑完再跑一次确认全绿。
+```
+
+## 写测试与重构
+
+边界清晰、验收标准明确的任务特别适合交给 Agent：
+
+```
+src/parser/markdown.ts 目前几乎没有测试。请补一组单元测试，覆盖正常段落、嵌套列表、代码块、表格、引用块和混合场景。用项目里已有的测试风格。
+```
+
+```
+把 src/handlers 下重复的「读 body → 校验 → 写日志 → 返回」逻辑抽成一个中间件。改完跑一遍测试，保证现有行为不变。
+```
+
+多文件重构建议先用 Plan 模式确认方案，可用 `/fork` 试探替代方案。
+
+## 一次性脚本与自动化任务
+
+批量改文件、跑统计、调研对比等任务用一段 prompt 就能完成：
+
+```
+把 src 目录下所有 .js 文件里的 var 声明改成 const 或 let，能用 const 的优先用 const。改完跑一次 lint 确认。
+```
+
+```
+分析 logs/ 下最近 7 天的访问日志，按接口路径统计调用次数、p50 和 p99 响应时间，结果输出成一个 markdown 表格。
+```
+
+```
+帮我调研一下 TypeScript 里几种主流的依赖注入方案（tsyringe、inversify、awilix），从 API 风格、装饰器依赖、运行时开销三个维度对比，给一份不超过一页的建议。
+```
+
+用 `--yolo` 或 `/yolo` 跳过审批，或用 [permission 配置](../configuration/config-files.md#permission) 给特定工具加白名单。
+
+## 生成与维护文档
+
+```
+我刚改了 src/auth/login.ts 的接口签名，把对应的 JSDoc、README 里的示例代码、还有 docs/zh/guides 下提到这个接口的段落都同步更新一遍。
+```
+
+```
+src/api 下所有公开函数里，凡是没有 docstring 的都补上文档注释，风格参考已有的注释。
+```
+
+```
+根据 src/cli 下的命令实现，生成一份命令参考的草稿，列出每个子命令、参数和默认值，放到 docs/zh/reference 下我后续审阅。
+```
+
+需要留档或复盘时，用 `kimi export <sessionId>` 打包为 ZIP。
diff --git a/docs/zh/index.md b/docs/zh/index.md
new file mode 100644
index 000000000..b93405a77
--- /dev/null
+++ b/docs/zh/index.md
@@ -0,0 +1,13 @@
+---
+layout: home
+hero:
+  name: Kimi Code CLI
+  text: The Starting Point for Next-Gen Agents
+  actions:
+    - theme: brand
+      text: 开始使用
+      link: guides/getting-started
+    - theme: alt
+      text: GitHub
+      link: https://github.com/MoonshotAI/kimi-code
+---
diff --git a/docs/zh/reference/keyboard.md b/docs/zh/reference/keyboard.md
new file mode 100644
index 000000000..d59b249e0
--- /dev/null
+++ b/docs/zh/reference/keyboard.md
@@ -0,0 +1,112 @@
+# 键盘快捷键
+
+Kimi Code CLI 的 TUI 交互模式支持以下键盘快捷键。键位主要在输入框中生效，部分键位在弹窗（如 `/help` 帮助面板、审批面板）或流式输出（streaming）期间有不同的行为。
+
+在 TUI 中输入 `/help` 可以随时打开内置的快捷键清单。
+
+## 通用快捷键
+
+下列键位在输入框中始终可用：
+
+
+| 快捷键           | 功能                                          |
+| ------------- | ------------------------------------------- |
+| `Enter`       | 提交当前输入                                      |
+| `Shift-Enter` | 在输入中插入换行                                    |
+| `↑` / `↓`     | 浏览输入历史                                      |
+| `Esc`         | 关闭弹窗 / 取消补全 / 中断流式输出或正在进行的上下文压缩（compaction） |
+| `Ctrl-C`      | 中断当前流式输出，或清空输入框                             |
+| `Ctrl-D`      | 在输入框为空时退出 Kimi Code CLI                     |
+
+
+**流式输出期间**按 `Ctrl-C` 会立即取消，无需二次确认。
+
+**退出程序**（输入框为空时按 `Ctrl-C`，或按 `Ctrl-D`）使用「双击确认」机制：第一次按下时，状态栏会显示提示（例如 `Press Ctrl+C again to exit`），再按一次相同的键才会真正退出。如果中途按了其他键，确认状态会自动清除。
+
+## 模式切换
+
+
+| 快捷键         | 功能         |
+| ----------- | ---------- |
+| `Shift-Tab` | 切换 Plan 模式 |
+
+
+按 `Shift-Tab` 可以开启或关闭 Plan 模式。开启后，Agent 会优先使用只读工具进行研究和规划，并可以写入当前计划文件；必要时也能调用 `Bash`，它会按当前权限模式和普通规则处理，不会因为处于 Plan 模式而额外发起独立审批。单纯切换模式不会创建空计划文件。再次按 `Shift-Tab` 即可退出 Plan 模式。
+
+## 输入与编辑
+
+
+| 快捷键      | 功能                                      |
+| -------- | --------------------------------------- |
+| `Ctrl-G` | 在外部编辑器中编辑当前输入                           |
+| `Ctrl-V` | 粘贴剪贴板中的图片或视频（Unix / macOS）              |
+| `Alt-V`  | 粘贴剪贴板中的图片或视频（Windows）                   |
+| `Ctrl-E` | 展开或折叠 Plan 卡片（无 Plan 卡片时按系统默认行为将光标移到行尾） |
+| `Ctrl--` | 撤销（Undo）                                |
+
+
+按 `Ctrl-G` 会打开外部编辑器，编辑当前输入内容。编辑器按以下优先级选择：
+
+1. `/editor` 命令配置的编辑器
+2. `$VISUAL` 环境变量
+3. `$EDITOR` 环境变量
+
+保存并退出编辑器后，编辑后的内容会替换输入框中的内容；不保存退出则保持原样。
+
+粘贴图片或视频时，会在输入框中显示为占位符，实际媒体数据在提交时一并发送给模型。粘贴的优先来源是系统剪贴板里的图片或文件路径；Linux 上 Wayland 与 X11 都会被尝试，WSL 下还会通过 PowerShell 兜底读取 Windows 剪贴板。
+
+## 流式输出期间
+
+流式输出（streaming）期间，输入框依然可以接收输入，并支持以下额外操作：
+
+
+| 快捷键      | 功能                     |
+| -------- | ---------------------- |
+| `Ctrl-S` | Steer：将当前输入立即注入正在运行的轮次 |
+| `Esc`    | 中断当前流式输出               |
+| `Ctrl-C` | 中断当前流式输出               |
+
+
+按 `Ctrl-S` 时，模型会在下一个可中断的时机立刻看到你的消息，无需等待当前轮次结束。
+
+## 工具输出
+
+
+| 快捷键      | 功能        |
+| -------- | --------- |
+| `Ctrl-O` | 展开或折叠工具输出 |
+
+
+当历史中存在折叠的工具调用结果时，按 `Ctrl-O` 可以在折叠和展开之间切换，便于查看完整的工具输出。
+
+## 审批面板
+
+当 Agent 发起需要确认的工具调用时，TUI 会弹出审批面板。详细的审批流程见 [交互与输入](../guides/interaction.md#审批流程)，下表给出面板内可用的键位：
+
+
+| 快捷键                         | 功能                            |
+| --------------------------- | ----------------------------- |
+| `↑` / `↓`                   | 在候选选项之间移动光标                   |
+| `Enter`                     | 确认当前选中的选项                     |
+| `1` ~ `9`                   | 直接选择对应序号的选项                   |
+| `Esc` / `Ctrl-C` / `Ctrl-D` | 拒绝当前请求                        |
+| `Ctrl-E`                    | 当面板包含 diff 或文件内容预览时，展开或折叠完整内容 |
+| `Ctrl-O`                    | 切换其他工具输出的折叠状态                 |
+
+
+需要附带反馈的选项（例如「Reject」「Revise」）会在确认后切换到反馈输入态：直接输入反馈文本，按 `Enter` 提交；按 `Esc` 退出反馈输入并回到候选列表。
+
+## 弹窗模式
+
+输入 `/help` 打开帮助面板后，可使用以下键位浏览和关闭面板：
+
+
+| 快捷键                   | 功能         |
+| --------------------- | ---------- |
+| `↑` / `↓`             | 单行滚动       |
+| `PageUp` / `PageDown` | 每次滚动 10 行 |
+| `Esc`                 | 关闭面板       |
+| `Enter`               | 关闭面板       |
+| `q` / `Q`             | 关闭面板       |
+
+
diff --git a/docs/zh/reference/kimi-command.md b/docs/zh/reference/kimi-command.md
new file mode 100644
index 000000000..78365bda8
--- /dev/null
+++ b/docs/zh/reference/kimi-command.md
@@ -0,0 +1,154 @@
+# kimi 命令
+
+`kimi` 是 Kimi Code CLI 的主命令，用于在终端中启动一次交互式会话。不带任何参数运行时，它会在当前工作目录下开启一个新会话；配合不同的 flag，可以续上历史会话、跳过审批、从 Plan 模式开始，或者指定自定义的 Skills 目录。
+
+```sh
+kimi [options]
+kimi <subcommand> [options]
+```
+
+## 主命令选项
+
+下表列出 `kimi` 主命令支持的全部选项。所有 flag 都是可选的，直接运行 `kimi` 即可进入交互式会话。
+
+| 选项 | 简写 | 说明 |
+| --- | --- | --- |
+| `--version` | `-V` | 打印版本号并退出。 |
+| `--help` | `-h` | 显示帮助信息并退出。 |
+| `--session [id]` | `-S` | 恢复一个会话。带 ID 时直接打开指定会话；不带 ID 时进入交互式选择器，从历史会话中挑选。 |
+| `--continue` | `-C` | 继续当前工作目录下最近一次的会话，无需手动指定 ID。 |
+| `--model <model>` | `-m` | 为本次启动指定模型别名。省略时，新会话使用配置文件中的 `default_model`，恢复会话使用会话当前模型。 |
+| `--prompt <prompt>` | `-p` | 非交互执行单次 prompt，并把 Assistant 输出流式写到 stdout。该模式会使用 `auto` 权限处理工具调用，不会打开 TUI。 |
+| `--output-format <format>` | | 设置非交互输出格式，支持 `text` 与 `stream-json`。仅可与 `--prompt` 一起使用，默认 `text`。 |
+| `--yolo` | `-y` | 自动批准普通工具调用，跳过审批请求；Plan 模式中的 `Bash` 审批和退出审批不会被跳过。 |
+| `--plan` | | 以 Plan 模式启动新会话，AI 会优先使用只读工具进行探索和规划，可以写入当前计划文件；Plan 模式中的 `Bash` 按权限模式单独处理。 |
+| `--skills-dir <dir>` | | 从指定目录加载 Skills，替换自动发现的用户和项目目录。可重复传入以叠加多个目录。详见下文 [自定义 Skills 目录](#自定义-skills-目录)。 |
+
+`-r` / `--resume` 是 `--session` 的隐藏别名；`--yes` 和 `--auto-approve` 是 `--yolo` 的隐藏别名。它们在帮助信息中不会显示，行为与对应的官方 flag 完全一致。
+
+::: warning 注意
+`--yolo` 会跳过普通工具调用的人工确认，包括文件写入和 Shell 命令执行。请只在受信任的工作目录下使用。Plan 模式的退出审批不会被 `--yolo` 跳过；Plan 模式下的 `Bash` 也按 `--yolo` 的普通放行规则处理。
+:::
+
+### flag 冲突规则
+
+以下组合会在启动时被拒绝：
+
+- `--continue` 与 `--session` 互斥：两者都表示"恢复历史会话"，含义重叠。
+- `--yolo` 不能与 `--continue` 或 `--session` 同时使用：恢复会话时会沿用原会话的审批设置。此规则仅适用于交互式模式；在 `--prompt` 模式下，`--yolo` 已因与 `--prompt` 互斥而被更早拦截。
+- `--plan` 不能与 `--continue` 或 `--session` 同时使用：Plan 模式只对新会话生效。
+- `--prompt` 不能与 `--yolo` 或 `--plan` 同时使用：非交互模式固定使用 `auto` 权限，并且不进入 Plan 模式。
+- `--prompt` 可以与 `--continue` 或带 ID 的 `--session <id>` 一起使用；不带 ID 的 `--session` 会尝试打开选择器，因此不能用于非交互模式。
+- `--output-format` 只能与 `--prompt` 一起使用；交互式 TUI 不支持把完整事件流写成 stdout JSONL。
+
+如果需要在恢复会话时强制使用 YOLO 或 Plan 模式，请改在交互式会话内通过斜杠命令切换。
+
+## 典型用法
+
+最常见的入口是直接运行 `kimi`，在当前目录开启一次全新的会话：
+
+```sh
+kimi
+```
+
+如果上一次会话被打断（关闭终端、网络断开等），想从断点继续，使用 `--continue`：
+
+```sh
+kimi --continue
+```
+
+它会自动找到当前工作目录下时间最近的那个会话并恢复。若想挑选其他历史会话，运行 `kimi --session` 进入交互式选择器，或者直接传入已知的 session ID：
+
+```sh
+kimi --session 01HZ...XYZ
+```
+
+当任务比较琐碎，不希望被频繁的审批请求打断时，可以加上 `--yolo`：
+
+```sh
+kimi --yolo
+```
+
+需要先让 AI 阅读代码、产出实现计划，而不是立刻动手修改文件时，使用 `--plan` 进入 Plan 模式：
+
+```sh
+kimi --plan
+```
+
+### 自定义 Skills 目录
+
+如果需要加载自定义的 Skills 目录，可以通过两种方式指定：
+
+- **CLI flag `--skills-dir <dir>`**：可重复传入，会**替换**自动发现的用户和项目目录，适合临时切换或在脚本中使用。例如同时挂载两个目录：
+
+  ```sh
+  kimi --skills-dir /path/to/team-skills --skills-dir ./local-skills
+  ```
+
+- **`config.toml` 的 `extra_skill_dirs`**：在配置文件中追加额外目录，与自动发现的目录**叠加**生效，适合长期配置团队共享 Skills（详见 [Agent Skills](../customization/skills.md)）。
+
+## 非交互执行
+
+需要在脚本或 CI 中运行单次 prompt 时，使用 `-p`：
+
+```sh
+kimi -p "Summarize the current repository status"
+```
+
+输出采用 transcript 样式：thinking 内容和 Assistant 正文都会以 `• ` 开头，换行后使用两个空格缩进。Assistant 正文会输出到 stdout；thinking、工具进度和 `To resume this session: kimi -r <id>` 提示输出到 stderr。`-p` 模式不会请求人工审批，普通工具调用、Plan 审批和 Agent 提问都会按 `auto` 权限策略处理。静态 deny 规则仍然会阻止匹配的工具调用。
+
+需要临时切换模型时，加上 `-m`：
+
+```sh
+kimi -m kimi-code/kimi-for-coding -p "Explain the latest diff"
+```
+
+如果脚本需要结构化读取输出，可以使用 JSONL：
+
+```sh
+kimi -p "List changed files" --output-format stream-json
+```
+
+`stream-json` 模式下，stdout 每行都是一个 JSON 对象。普通回复会输出 Assistant 消息；如果模型调用工具，会先输出带 `tool_calls` 的 Assistant 消息，再输出对应的 Tool 消息，最后继续输出后续 Assistant 消息。thinking 内容不会写入 JSONL；工具进度和恢复会话提示仍然写到 stderr。
+
+## 子命令
+
+### `kimi export`
+
+把一个会话打包成 ZIP 文件，便于分享、归档或者提交问题反馈。导出的压缩包包含会话目录下的所有文件，例如上下文记录、状态文件和会话诊断日志（如果该会话已经产生 `logs/kimi-code.log`）。
+
+```sh
+kimi export [sessionId] [options]
+```
+
+| 参数 / 选项 | 简写 | 说明 |
+| --- | --- | --- |
+| `sessionId` | | 要导出的会话 ID。省略时会自动选择当前工作目录下最近一次的会话，并要求确认。 |
+| `--output <path>` | `-o` | 输出 ZIP 文件路径。省略时写入当前目录下的默认文件名。 |
+| `--yes` | `-y` | 跳过默认会话的确认提示，直接导出。 |
+| `--no-include-global-log` | | 不打包当前活动的全局诊断日志，即 `~/.kimi-code/logs/kimi-code.log`。默认包含。 |
+
+默认导出包含目标会话目录内的文件；如果会话目录里有 `logs/kimi-code.log`，会一并出现在 ZIP 的 `logs/kimi-code.log`。全局诊断日志 `~/.kimi-code/logs/kimi-code.log` 默认也会打包，因为它可能包含其它会话或其它项目的事件，如果不想分享可以加 `--no-include-global-log`。加上后，ZIP 内路径是 `logs/global/kimi-code.log`，不会包含轮转出来的 `kimi-code.log.1` 等旧文件。
+
+省略 `sessionId` 时，命令会先打印待导出的会话信息并请求确认；用 `-y` 可以跳过确认，适合在脚本里使用：
+
+```sh
+# 导出当前工作目录最近一次会话，跳过确认
+kimi export -y
+
+# 导出指定会话到自定义路径
+kimi export 01HZ...XYZ -o ./bug-report.zip
+
+# 排除全局诊断日志，避免分享其它会话的事件
+kimi export 01HZ...XYZ -o ./bug-report.zip --no-include-global-log
+```
+
+### `kimi migrate`
+
+将旧版 kimi-cli 的本地数据迁移到 kimi-code。该命令无任何 flag，纯交互式运行，会引导你完成数据迁移的全流程。
+
+```sh
+kimi migrate
+```
+
+如果你之前使用过旧版 kimi-cli，可以运行此命令将历史会话、配置等数据迁移到 kimi-code 中，避免数据丢失。完整的迁移流程、迁移内容与注意事项见 [从 kimi-cli 迁移](../guides/migration.md)。
diff --git a/docs/zh/reference/slash-commands.md b/docs/zh/reference/slash-commands.md
new file mode 100644
index 000000000..ddecaed21
--- /dev/null
+++ b/docs/zh/reference/slash-commands.md
@@ -0,0 +1,86 @@
+# 斜杠命令
+
+斜杠命令是 Kimi Code CLI 在交互式 TUI 中提供的内置控制命令，用于切换模式、管理会话、查看状态等。在输入框中输入 `/` 即可触发命令补全，候选列表会随后续字符实时过滤；命令的别名（alias）也会一并参与匹配。
+
+输入完整命令名（如 `/help`）后按 `Enter` 即可执行。如果输入的 `/` 开头内容不匹配任何内置或 Skill 命令，则按普通消息发送给 Agent。
+
+::: tip 提示
+部分命令仅在空闲（idle）状态下可用。会话正在流式输出或正在压缩上下文时执行这些命令会被拦截，并提示先按 `Esc` 或 `Ctrl-C` 中断当前操作。下表的 「随时可用」 列标注了在流式输出 / 上下文压缩期间也可用的命令。
+:::
+
+## 账号与配置
+
+| 命令 | 别名 | 说明 | 随时可用 |
+| --- | --- | --- | --- |
+| `/login` | — | 选择账号或平台并登录：Kimi Code 走 OAuth device code 流程，Moonshot AI 开放平台通过 API 密钥登录。 | 否 |
+| `/logout` | — | 清除当前所选账号的凭据（Kimi Code OAuth 凭据，或对应开放平台的供应商配置）。 | 否 |
+| `/model` | — | 切换当前会话使用的 LLM 模型。 | 是 |
+| `/settings` | `/config` | 打开 TUI 内的设置面板。 | 是 |
+| `/permission` | — | 选择权限模式（permission mode）。 | 是 |
+| `/editor` | — | 配置 `Ctrl-G` 调起的外部编辑器。 | 是 |
+| `/theme` | — | 切换终端 UI 配色主题。 | 是 |
+
+## 会话管理
+
+| 命令 | 别名 | 说明 | 随时可用 |
+| --- | --- | --- | --- |
+| `/new` | `/clear` | 开启一个全新会话，丢弃当前上下文。 | 否 |
+| `/sessions` | `/resume` | 浏览历史会话并切换/恢复。 | 是 |
+| `/tasks` | `/task` | 浏览后台任务列表。 | 是 |
+| `/fork` | — | 基于当前会话 fork 一份新会话，保留完整对话历史。 | 否 |
+| `/title [<text>]` | `/rename` | 不带参数时显示当前会话标题；带参数时将其设置为新标题（最长 200 个字符）。 | 是 |
+| `/compact [<instruction>]` | — | 压缩当前对话上下文，释放 token 占用；可选附带一段自定义指令，提示模型在压缩时保留哪些信息。 | 否 |
+| `/init` | — | 分析当前代码库并生成 `AGENTS.md`。 | 否 |
+
+## 模式与运行控制
+
+| 命令 | 别名 | 说明 | 随时可用 |
+| --- | --- | --- | --- |
+| `/yolo [on\|off]` | `/yes` | 切换自动批准模式（auto-approve）。不带参数时按当前状态翻转；显式传 `on`/`off` 时强制设为对应状态。开启后跳过普通工具调用审批；Plan 模式的退出审批不会被跳过。 | 是 |
+| `/plan [on\|off]` | — | 切换 Plan 模式。不带参数时按当前状态翻转；显式传 `on`/`off` 时强制设为对应状态。单纯切换不会创建空计划文件。 | 是 |
+| `/plan clear` | — | 清除当前 plan 方案。 | 否 |
+
+::: warning 注意
+`/yolo` 会跳过普通工具调用的审批确认，使用前请确保了解可能的风险。Plan 模式的退出审批不会被 `/yolo` 跳过；Plan 模式下的 `Bash` 也按 `/yolo` 的普通放行规则处理。
+:::
+
+## 信息与状态
+
+| 命令 | 别名 | 说明 | 随时可用 |
+| --- | --- | --- | --- |
+| `/help` | `/h`、`/?` | 显示快捷键和所有可用命令。 | 是 |
+| `/usage` | — | 显示 token 用量、上下文占用以及配额信息。 | 是 |
+| `/status` | — | 显示当前会话运行时状态，包括版本、模型、工作目录和权限模式等。 | 是 |
+| `/mcp` | — | 列出当前会话中的 MCP server 及其连接状态。 | 是 |
+| `/version` | — | 显示 Kimi Code CLI 版本号。 | 是 |
+| `/feedback` | — | 提交反馈以改进 Kimi Code CLI。 | 是 |
+
+## 退出
+
+| 命令 | 别名 | 说明 | 随时可用 |
+| --- | --- | --- | --- |
+| `/exit` | `/quit`、`/q` | 退出 Kimi Code CLI。 | 否 |
+
+## Skill 动态命令
+
+除内置命令外，用户可激活的 Skill 会自动注册为斜杠命令，统一以 `skill:` 作为命名空间前缀：
+
+```
+/skill:<name> [附加文本]
+```
+
+例如 `/skill:code-style` 会加载名为 `code-style` 的 Skill 内容并发送给 Agent；命令后附带的文本会拼接到 Skill 提示词之后，例如 `/skill:git-commits 修复登录失败的问题`。
+
+为方便输入，Skill 命令同时支持省略 `skill:` 前缀的简写形式 `/<name>`，前提是该名称未被内置命令占用。也就是说，`/code-style` 会回退匹配到 `/skill:code-style`。
+
+Kimi Code CLI 随包内置了 `mcp-config` Skill，用于配置 MCP server 和处理 MCP OAuth 登录。它在补全和帮助里仍属于 Skill 命名空间（`/skill:mcp-config`），也可以直接输入 `/mcp-config` 调用。
+
+可作为斜杠命令暴露的 Skill 类型包括 `prompt`、`inline`、`flow` 以及未显式声明类型的 Skill。Skill 的安装与编写详见 [Agent Skills](../customization/skills.md)。
+
+::: info 说明
+所有 Skill 命令仅在空闲状态下可用，流式输出或上下文压缩期间需先按 `Esc` 或 `Ctrl-C` 中断当前操作。
+:::
+
+::: info 说明
+Flow 类型的 Skill 同样通过 `/skill:<name>` 暴露，没有独立的 `/flow:` 命名空间。
+:::
diff --git a/docs/zh/reference/tools.md b/docs/zh/reference/tools.md
new file mode 100644
index 000000000..06ef48f76
--- /dev/null
+++ b/docs/zh/reference/tools.md
@@ -0,0 +1,104 @@
+# 内置工具
+
+内置工具是 Kimi Code CLI 随核心引擎一起提供的工具集，无需安装 MCP server 即可使用。Agent 在每次对话中会根据任务需要自动选择并调用这些工具；用户也可以通过权限审批界面查看每次工具调用的细节。
+
+与 MCP 工具相比，内置工具由运行时直接管理，生命周期与会话绑定，无需外部进程。两者都遵循统一的审批机制：**只读类工具**（如 `Read`、`Grep`、`Glob`、`WebSearch` 等）默认自动放行，**写入与执行类工具**（如 `Write`、`Edit`、`Bash`、`TaskStop`）默认需要用户审批。在 YOLO 模式下，普通工具调用的审批会被跳过，但 Plan 模式下的退出审批不受影响。
+
+## 文件类
+
+文件类工具负责读取、写入、搜索本地文件系统，是代码分析和修改任务的基础工具。
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `Read` | 自动放行 | 读取文本文件内容 |
+| `Write` | 需审批 | 创建或覆盖文件 |
+| `Edit` | 需审批 | 精确字符串替换 |
+| `Grep` | 自动放行 | 基于 ripgrep 的全文搜索 |
+| `Glob` | 自动放行 | 按 glob 模式查找文件 |
+| `ReadMediaFile` | 自动放行 | 读取图片或视频文件 |
+
+**`Read`** 接受文件路径（`path`）以及可选的 `line_offset`（起始行号，支持负数从末尾倒数）和 `n_lines`（读取行数上限）。单次最多返回 1000 行或 100 KB，超出部分会附带截断提示。如果文件是图片或视频，工具会提示改用 `ReadMediaFile`。
+
+**`Write`** 接受 `path`、`content` 和可选的 `mode`（`overwrite` 或 `append`，默认覆盖）。父目录必须已存在；`append` 模式将内容追加到文件末尾，不自动添加换行。
+
+**`Edit`** 接受 `path`、`old_string`（要替换的精确文本）和 `new_string`（替换后的文本）。默认只替换唯一一处匹配，若文件中存在多处相同内容会报错并提示使用 `replace_all: true`。`old_string` 与 `new_string` 不能相同。
+
+**`Grep`** 调用 ripgrep 搜索文件内容，支持正则表达式（`pattern`）、搜索路径（`path`）、文件类型过滤（`type`，如 `ts`、`py`）、glob 过滤（`glob`）和输出模式（`output_mode`：`files_with_matches` / `content` / `count_matches`，默认 `files_with_matches`）。`content` 模式支持 `-A`、`-B`、`-C` 上下文行参数与 `-i`（忽略大小写）、`-n`（行号，默认 true）、`multiline`（跨行匹配）。所有模式均支持 `offset` + `head_limit` 分页，`head_limit` 默认 250、传 0 表示不限。`files_with_matches` 模式的结果按文件最近修改时间倒序排列；其他模式保持 ripgrep 原始输出顺序。`.env`、私钥、`.aws/credentials`、`.gcp/credentials` 等敏感文件会被自动过滤；`include_ignored=true` 可同时搜索被 `.gitignore` 等忽略的文件，但敏感文件仍保持过滤。
+
+**`Glob`** 按 glob 模式（`pattern`）在指定目录（`path`，默认为工作目录）中匹配文件，结果按修改时间倒序排列，最多返回 1000 条。可选参数 `include_dirs`（默认 true）控制是否返回目录条目。纯通配符模式（如 `**`、`**/*`）会被拒绝并提示添加字面锚点；包含花括号扩展（`{a,b,c}`）的模式同样会被拒绝——底层 glob 引擎把 `{`、`}` 当字面量处理，这类模式会静默匹配 0 个文件。
+
+**`ReadMediaFile`** 将图片或视频文件以多模态内容发送给模型，仅接受 `path`。文件大小上限为 100 MB。工具是否可用取决于当前模型的视觉能力（`image_in` / `video_in`）。
+
+## Shell
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `Bash` | 需审批 | 执行 Shell 命令 |
+
+**`Bash`** 是最通用也是权限要求最严格的工具。它接受 `command`（必填）以及可选的 `cwd`（工作目录）、`timeout`（毫秒）、`description`（后台任务描述，`run_in_background=true` 时必填）、`run_in_background`（是否以后台任务运行）和 `disable_timeout`（后台任务是否取消超时）。前台 `timeout` 默认 60 秒、最长 5 分钟；后台 `timeout` 默认 10 分钟、最长 10 分钟。
+
+前台模式下 `Bash` 会阻塞当前轮次，直到命令结束或超时；后台模式会立即返回任务 ID。后台任务默认 10 分钟后超时；如果确实需要让任务不受超时限制，可以设置 `disable_timeout=true`。任务结束、失败或被停止时会自动通知 Agent 继续处理，过程中也可通过 `TaskOutput` 主动查看结果。stdin 始终被关闭，交互式命令会立即收到 EOF。两阶段终止策略（SIGTERM → 5 秒宽限期 → SIGKILL）确保超时后进程能可靠结束。Windows 平台下默认使用 Git Bash 作为 shell。
+
+## 网络类
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `WebSearch` | 自动放行 | 网络搜索 |
+| `FetchURL` | 自动放行 | 获取指定 URL 的内容 |
+
+**`WebSearch`** 接受 `query`（搜索词）和可选的 `limit`（返回结果数，1–20，默认 5）及 `include_content`（是否返回网页正文，默认 false，开启后消耗 token 较多）。该工具需要宿主提供搜索实现，未注入实现时不会出现在工具列表中。
+
+**`FetchURL`** 接受单个 `url` 参数，返回页面内容。对于 HTML 页面，宿主会提取正文文章（`extracted`）而非返回完整 HTML；纯文本或 Markdown 页面则直接透传（`passthrough`）。同样需要宿主注入实现。
+
+## Plan 模式
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `EnterPlanMode` | 自动放行 | 进入 Plan 模式 |
+| `ExitPlanMode` | 自动放行（需用户确认计划） | 退出 Plan 模式并提交计划 |
+
+Plan 模式是一种受约束的工作状态：进入后 `Write` 与 `Edit` 工具被收紧——只允许写入当前的计划文件，其它路径会被阻断；`TaskStop` 也被完全拦截。其余工具（包括 `Bash`）仍按当前权限规则处理，因此通过 `Bash` 调用的命令理论上仍可能修改文件，是否放行取决于当前的审批策略。
+
+**`EnterPlanMode`** 不接受任何参数，进入成功后返回工作流指引，包括计划文件路径（如果宿主提供了的话）。
+
+**`ExitPlanMode`** 读取当前计划文件内容，将计划呈现给用户审批后退出 Plan 模式。可选参数 `options` 允许 Agent 提供 1–3 个备选方案（每项含 `label` 与 `description`，`label` 最长 80 字符），供用户在审批时选择；标签需互不重复，且不能使用 `Approve`、`Reject`、`Reject and Exit`、`Revise` 这些保留词（系统用它们标记审批结果）。用户批准后，所有工具重新可用；若用户要求修改，Agent 将继续留在 Plan 模式中。
+
+## 状态管理
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `TodoList` | 自动放行 | 管理任务待办列表 |
+
+**`TodoList`** 用于在多步骤操作中维护一份可见的子任务列表，状态存储在 Agent 会话内。`todos` 参数接受一个数组，每项含 `title`（标题）和 `status`（`pending` / `in_progress` / `done`）；省略 `todos` 则仅查询当前列表，传入空数组则清空列表。
+
+## 协作类
+
+协作类工具负责 Agent 间协作、用户交互和 Skill 调用。
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `Agent` | 自动放行 | 派生子 Agent 执行子任务 |
+| `AskUserQuestion` | 自动放行 | 向用户提问以获取结构化输入 |
+| `Skill` | 自动放行 | 调用已注册的 inline Skill |
+
+**`Agent`** 用于将子任务委托给子 Agent 执行。必填参数为 `prompt`（完整任务描述）和 `description`（3–5 个词的简短说明，用于 UI 展示）。可选参数包括 `subagent_type`（Agent 类型，默认 `coder`）、`resume`（恢复已有 Agent 的 ID）、`run_in_background`（是否后台运行，默认 false）和 `timeout`（超时秒数，30–3600）。`subagent_type` 与 `resume` 互斥：恢复已有 Agent 时只通过 ID 寻址。前台 `timeout` 缺省表示不超时，子 Agent 运行至完成；后台 `timeout` 缺省时回落到 `config.toml` 的 `[background] agent_task_timeout_s`，该字段也未设置则无时间上限。前台模式下父 Agent 会等待子 Agent 完成再继续；后台模式立即返回任务 ID，完成时通过合成 user 消息自动回到主 Agent，无需轮询。子 Agent 体系细节参见 [子 Agent](../customization/agents.md)。
+
+**`AskUserQuestion`** 以结构化多选题的形式向用户提问，适用于需要用户消歧或选择方案的场景。`questions` 参数接受 1–4 道题，每道题需提供 `question`（问题文本，以 `?` 结尾）、`options`（2–4 个选项，每项含 `label` 和 `description`）以及可选的 `header`（最多 12 字符的短分类标签，如 `Auth`、`Style`）和 `multi_select`（是否多选，默认 false）。系统会自动附加「其他」选项，无需在 `options` 中手工提供。若宿主未实现交互式提问能力，本工具会返回失败提示，Agent 应改为直接在文本回复中向用户提问。
+
+**`Skill`** 允许 Agent 主动调用已注册的 inline 类型 Skill。接受 `skill`（Skill 名称）和可选的 `args`（附加参数文本）。只有 `type = "inline"` 的 Skill 能通过此工具调用；其他类型（如 `prompt`、`flow`）以及在 frontmatter 中设置了 `disableModelInvocation: true` 的 Skill 会被拒绝。为防止递归死循环，Skill 嵌套调用深度上限为 3 层。Skill 体系细节参见 [Skills](../customization/skills.md)。
+
+## 后台任务
+
+后台任务工具用于管理通过 `Bash` 或 `Agent` 启动的后台任务。后台任务进入完成、失败、停止或丢失等终止状态时，会把状态和末尾输出自动送回 Agent；如果只想提前检查进度，再使用 `TaskOutput`。
+
+| 工具 | 默认审批 | 说明 |
+| --- | --- | --- |
+| `TaskList` | 自动放行 | 列出后台任务 |
+| `TaskOutput` | 自动放行 | 查看后台任务的输出 |
+| `TaskStop` | 需审批 | 停止正在运行的后台任务 |
+
+**`TaskList`** 返回后台任务列表，每条记录包含任务 ID、状态、命令、描述和 PID。可选参数 `active_only`（默认 true，仅列出运行中的任务）和 `limit`（最多返回条数，默认 20，取值范围 1–100）。已进入终止状态的任务还会附带 `exit_code`，被 `TaskStop` 显式终止的任务会附带 `reason`。
+
+**`TaskOutput`** 根据 `task_id` 返回指定任务的状态与输出。内联预览最多包含最近 32 KB 的内容；完整日志保存在磁盘上，工具会一并返回 `output_path` 并提示通过 `Read` 分页读取（建议每页约 300 行）。可选 `block`（默认 false）和 `timeout`（等待秒数，默认 30，取值范围 0–3600）参数可用于等待任务完成后再返回。返回结构中 `retrieval_status` 取 `success` / `timeout` / `not_ready`；任务因超时被外部 deadline 中止时会附带 `timed_out: true` 与 `terminal_reason: timed_out`，被 `TaskStop` 显式终止时会附带 `stop_reason` 与 `terminal_reason: stopped`。
+
+**`TaskStop`** 接受 `task_id` 和可选的 `reason`（停止原因，默认 `Stopped by TaskStop`）。对已处于终止状态的任务也能安全调用，会直接返回当前状态而不报错。
diff --git a/docs/zh/release-notes/changelog.md b/docs/zh/release-notes/changelog.md
new file mode 100644
index 000000000..d169d59f4
--- /dev/null
+++ b/docs/zh/release-notes/changelog.md
@@ -0,0 +1,5 @@
+# 变更记录
+
+::: info 说明
+本页将随首个正式版本同步发布详细变更记录。
+:::
diff --git a/flake.lock b/flake.lock
new file mode 100644
index 000000000..689872643
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1779102034,
+        "narHash": "sha256-vZJZjLo513IeI8hjzHFc6TDezUd4uCE2Eq4SNO3DNNg=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "687f05a9184cad4eaf905c48b63649e3a86f5433",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-25.11",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 000000000..b4de4f080
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,302 @@
+{
+  description = "Kimi Code CLI";
+
+  inputs = {
+    # Pinned to the 25.11 release channel because nixpkgs-unstable currently
+    # ships nodejs_24 = 24.14.1, which trips the >= 24.15.0 floor that the
+    # native SEA build enforces (see apps/kimi-code/scripts/native/build.mjs).
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
+  };
+
+  outputs =
+    { self, nixpkgs }:
+    let
+      lib = nixpkgs.lib;
+
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+
+      forAllSystems =
+        f:
+        lib.genAttrs systems (
+          system:
+          f (import nixpkgs {
+            inherit system;
+          })
+        );
+
+      minNodeVersion = "24.15.0";
+      requiredNodeMajor = "24";
+
+      # nodejsFor picks pkgs.nodejs_24 when it satisfies the minimum, otherwise
+      # falls back to pkgs.nodejs_latest. The build pipeline (tsdown target
+      # `node24`, SEA flags) assumes a 24.x runtime, so we hard-fail if neither
+      # candidate is in the 24.x line.
+      nodejsFor =
+        pkgs:
+        let
+          candidate =
+            if lib.versionAtLeast pkgs.nodejs_24.version minNodeVersion then
+              pkgs.nodejs_24
+            else
+              pkgs.nodejs_latest;
+          major = lib.versions.major candidate.version;
+        in
+        if major == requiredNodeMajor then
+          candidate
+        else
+          throw ''
+            Kimi Code requires Node.js ${requiredNodeMajor}.x (>= ${minNodeVersion}),
+            but nixpkgs only offers ${candidate.version}.
+            Pin a newer nixpkgs revision or update minNodeVersion in flake.nix.
+          '';
+
+      pnpmFor =
+        pkgs:
+        pkgs.pnpm_10.override {
+          nodejs = nodejsFor pkgs;
+        };
+
+      # ---------------------------------------------------------------------
+      # Derive workspace members from pnpm-workspace.yaml + each package.json.
+      #
+      # Source of truth is pnpm-workspace.yaml's `packages:` section. We expand
+      # each glob (or literal path) against the repo root, keep only entries
+      # that contain a package.json, and read their `name` field. Both the
+      # `src` fileset and the `pnpmWorkspaces` filter for pnpmConfigHook are
+      # derived from this list, so adding/removing a workspace only requires
+      # updating pnpm-workspace.yaml (followed by `nix run .#update-pnpm-deps`).
+      # ---------------------------------------------------------------------
+
+      # Minimal parser for the `packages:` list in pnpm-workspace.yaml. Only
+      # handles top-level `- <entry>` items under the `packages:` key; other
+      # sections (catalog, overrides) are ignored. Sufficient for the format
+      # pnpm produces and we maintain.
+      parsePnpmWorkspaceGlobs =
+        file:
+        let
+          lines = lib.splitString "\n" (builtins.readFile file);
+          isPackagesHeader = l: builtins.match "^packages:[[:space:]]*$" l != null;
+          isTopLevelKey = l: builtins.match "^[^[:space:]#].*:.*$" l != null;
+          extractItem =
+            l:
+            let
+              m = builtins.match "^[[:space:]]+-[[:space:]]+['\"]?([^'\"#[:space:]]+)['\"]?[[:space:]]*$" l;
+            in
+            if m == null then null else builtins.head m;
+          step =
+            state: line:
+            if state.done then
+              state
+            else if !state.inSection then
+              if isPackagesHeader line then state // { inSection = true; } else state
+            else
+              let
+                item = extractItem line;
+              in
+              if item != null then
+                state // { items = state.items ++ [ item ]; }
+              else if isTopLevelKey line then
+                state // { inSection = false; done = true; }
+              else
+                state;
+          result = lib.foldl' step {
+            inSection = false;
+            items = [ ];
+            done = false;
+          } lines;
+        in
+        result.items;
+
+      expandWorkspaceGlob =
+        root: glob:
+        if lib.hasSuffix "/*" glob then
+          let
+            dir = lib.removeSuffix "/*" glob;
+            absDir = root + "/${dir}";
+          in
+          if builtins.pathExists absDir then
+            map (n: "${dir}/${n}") (
+              builtins.attrNames (lib.filterAttrs (_: t: t == "directory") (builtins.readDir absDir))
+            )
+          else
+            [ ]
+        else if builtins.pathExists (root + "/${glob}") then
+          [ glob ]
+        else
+          [ ];
+
+      workspaceMembers =
+        let
+          globs = parsePnpmWorkspaceGlobs ./pnpm-workspace.yaml;
+          paths = lib.unique (lib.concatMap (expandWorkspaceGlob ./.) globs);
+        in
+        builtins.filter (p: builtins.pathExists (./. + "/${p}/package.json")) paths;
+
+      workspacePaths = map (p: ./. + "/${p}") workspaceMembers;
+
+      workspaceNames = map (
+        p: (builtins.fromJSON (builtins.readFile (./. + "/${p}/package.json"))).name
+      ) workspaceMembers;
+    in
+    {
+      packages = forAllSystems (
+        pkgs:
+        let
+          nodejs = nodejsFor pkgs;
+          pnpm = pnpmFor pkgs;
+          appPackageJson = builtins.fromJSON (builtins.readFile ./apps/kimi-code/package.json);
+          nativeTarget =
+            if pkgs.stdenv.hostPlatform.isLinux && pkgs.stdenv.hostPlatform.isAarch64 then
+              "linux-arm64"
+            else if pkgs.stdenv.hostPlatform.isLinux then
+              "linux-x64"
+            else if pkgs.stdenv.hostPlatform.isDarwin && pkgs.stdenv.hostPlatform.isAarch64 then
+              "darwin-arm64"
+            else if pkgs.stdenv.hostPlatform.isDarwin then
+              "darwin-x64"
+            else
+              throw "Unsupported Kimi Code native target for ${pkgs.stdenv.hostPlatform.system}";
+
+          kimi-code = pkgs.stdenv.mkDerivation (finalAttrs: {
+            pname = "kimi-code";
+            version = appPackageJson.version;
+
+            src = lib.fileset.toSource {
+              root = ./.;
+              fileset = lib.fileset.unions (
+                [
+                  ./build
+                  ./.npmrc
+                  ./.nvmrc
+                  ./package.json
+                  ./pnpm-lock.yaml
+                  ./pnpm-workspace.yaml
+                  ./tsconfig.json
+                  ./vitest.config.ts
+                  ./LICENSE
+                ]
+                ++ workspacePaths
+              );
+            };
+
+            pnpmWorkspaces = [ "." ] ++ workspaceNames;
+
+            pnpmDeps = pkgs.fetchPnpmDeps {
+              inherit (finalAttrs) pname version src pnpmWorkspaces;
+              inherit pnpm;
+              fetcherVersion = 3;
+              hash = "sha256-dht627zodv/xeefY7fEvSaKXavTxi+JWA3gwL18U8dk=";
+            };
+
+            nativeBuildInputs = [
+              nodejs
+              pnpm
+              (pkgs.pnpmConfigHook.override { inherit pnpm; })
+            ]
+            # The SEA inject step (postject) invalidates the macOS code
+            # signature on the copied Node executable; build.mjs then re-applies
+            # an ad-hoc signature via `codesign`. The Nix darwin sandbox does
+            # not expose /usr/bin/codesign, so we supply nixpkgs' ad-hoc-only
+            # replacement instead.
+            ++ lib.optionals pkgs.stdenv.hostPlatform.isDarwin [
+              pkgs.darwin.sigtool
+            ];
+
+            # The SEA binary is produced by `postject`-injecting a blob into a
+            # plain Node executable. Stripping rewrites section tables and can
+            # invalidate the injected blob's offsets, so leave the binary
+            # untouched after the build.
+            dontStrip = true;
+
+            buildPhase = ''
+              runHook preBuild
+              export KIMI_CODE_BUILD_TARGET=${nativeTarget}
+              ${lib.optionalString pkgs.stdenv.hostPlatform.isDarwin ''
+                # pkgs.darwin.sigtool's codesign supports `--sign -` (ad-hoc)
+                # but not the inspection mode (`-dv`) that 05-verify.mjs runs
+                # afterwards. Disable the verify step for the Nix build; the
+                # release CI keeps it via the unmodified script.
+                substituteInPlace apps/kimi-code/scripts/native/build.mjs \
+                  --replace-fail \
+                    "await runVerifyStep({ requireGatekeeper: false });" \
+                    "// runVerifyStep skipped in nix sandbox (sigtool lacks -dv)"
+              ''}
+              pnpm --filter=@moonshot-ai/kimi-code run build:native:sea
+              runHook postBuild
+            '';
+
+            installPhase = ''
+              runHook preInstall
+
+              install -Dm755 \
+                "apps/kimi-code/dist-native/bin/${nativeTarget}/kimi" \
+                "$out/bin/kimi"
+
+              runHook postInstall
+            '';
+
+            meta = {
+              description = "Kimi Code CLI";
+              homepage = "https://github.com/MoonshotAI/kimi-code";
+              license = lib.licenses.mit;
+              mainProgram = "kimi";
+              platforms = systems;
+            };
+          });
+
+          # Expose pnpmDeps as a top-level package so `nix build .#kimi-code-pnpm-deps`
+          # (used by the update-pnpm-deps app) is a stable selector that doesn't
+          # depend on attribute drilling into a derivation.
+          kimi-code-pnpm-deps = kimi-code.pnpmDeps;
+
+          update-pnpm-deps = pkgs.writeShellApplication {
+            name = "update-pnpm-deps";
+            runtimeInputs = [
+              pkgs.nix
+              pkgs.git
+              nodejs
+              pkgs.gnused
+              pkgs.gnugrep
+              pkgs.coreutils
+            ];
+            text = builtins.readFile ./build/nix/update-pnpm-deps.sh;
+          };
+        in
+        {
+          inherit kimi-code kimi-code-pnpm-deps update-pnpm-deps;
+          default = kimi-code;
+        }
+      );
+
+      apps = forAllSystems (pkgs: {
+        kimi-code = {
+          type = "app";
+          program = "${self.packages.${pkgs.system}.kimi-code}/bin/kimi";
+        };
+        update-pnpm-deps = {
+          type = "app";
+          program = "${self.packages.${pkgs.system}.update-pnpm-deps}/bin/update-pnpm-deps";
+        };
+        default = self.apps.${pkgs.system}.kimi-code;
+      });
+
+      devShells = forAllSystems (pkgs: {
+        default =
+          let
+            nodejs = nodejsFor pkgs;
+            pnpm = pnpmFor pkgs;
+          in
+          pkgs.mkShell {
+            packages = [
+              nodejs
+              pnpm
+            ];
+          };
+      });
+    };
+}
diff --git a/package.json b/package.json
new file mode 100644
index 000000000..a3ba656e3
--- /dev/null
+++ b/package.json
@@ -0,0 +1,57 @@
+{
+  "name": "@moonshot-ai/monorepo",
+  "version": "0.1.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "pnpm -r run build",
+    "build:packages": "pnpm -r --filter './packages/*' run build",
+    "dev:cli": "pnpm -C apps/kimi-code run dev",
+    "vis": "pnpm -C apps/vis run dev",
+    "dev:docs": "pnpm -C docs install --ignore-workspace && pnpm -C docs run dev",
+    "typecheck": "pnpm run build:packages && pnpm -r --filter './packages/*' run typecheck && pnpm --filter @moonshot-ai/kimi-code run typecheck",
+    "lint": "oxlint --type-aware",
+    "lint:fix": "pnpm run lint --fix",
+    "lint:pkg": "pnpm -r --filter '!@moonshot-ai/monorepo' exec publint && pnpm -r --filter './packages/*' exec attw --pack . --profile node16",
+    "sherif": "sherif",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "pnpm -r run clean",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "publish": "pnpm run typecheck && pnpm run lint && pnpm run sherif && pnpm run test && pnpm run build && pnpm run lint:pkg && changeset publish",
+    "prepare": "simple-git-hooks"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.2",
+    "@changesets/changelog-github": "0.7.0",
+    "@changesets/cli": "2.30.0",
+    "@microsoft/api-extractor": "7.58.7",
+    "@types/node": "^22.15.3",
+    "@vitest/coverage-v8": "4.1.4",
+    "lint-staged": "16.4.0",
+    "oxlint": "1.59.0",
+    "oxlint-tsgolint": "0.20.0",
+    "publint": "0.3.18",
+    "sherif": "1.11.1",
+    "simple-git-hooks": "2.13.1",
+    "tsdown": "0.22.0",
+    "tsx": "^4.21.0",
+    "typescript": "6.0.2",
+    "vitest": "4.1.4"
+  },
+  "simple-git-hooks": {
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}": [
+      "oxlint --fix --quiet",
+      "oxlint --type-aware --quiet"
+    ]
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "packageManager": "pnpm@10.33.0"
+}
diff --git a/packages/agent-core/README.md b/packages/agent-core/README.md
new file mode 100644
index 000000000..ce786952b
--- /dev/null
+++ b/packages/agent-core/README.md
@@ -0,0 +1,11 @@
+# @moonshot-ai/agent-core
+
+The unified agent engine for Kimi Code.
+
+Part of the [Kimi Code](https://github.com/MoonshotAI/kimi-code) monorepo.
+
+See the main repository for documentation, issues, and contribution guidelines.
+
+## License
+
+MIT
diff --git a/packages/agent-core/package.json b/packages/agent-core/package.json
new file mode 100644
index 000000000..87631862c
--- /dev/null
+++ b/packages/agent-core/package.json
@@ -0,0 +1,85 @@
+{
+  "name": "@moonshot-ai/agent-core",
+  "version": "0.1.1",
+  "private": true,
+  "description": "The unified agent engine for Kimi",
+  "license": "MIT",
+  "author": "Moonshot AI",
+  "homepage": "https://github.com/MoonshotAI/kimi-code/tree/main/packages/agent-core#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MoonshotAI/kimi-code.git",
+    "directory": "packages/agent-core"
+  },
+  "bugs": {
+    "url": "https://github.com/MoonshotAI/kimi-code/issues"
+  },
+  "keywords": [
+    "kimi",
+    "agent",
+    "ai",
+    "llm",
+    "session",
+    "tools"
+  ],
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "imports": {
+    "#/*": [
+      "./src/*.ts",
+      "./src/*/index.ts"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./session/store": {
+      "types": "./src/session/store/index.ts",
+      "default": "./src/session/store/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:baseline": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@antfu/utils": "^9.3.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@moonshot-ai/kaos": "workspace:^",
+    "@moonshot-ai/kosong": "workspace:^",
+    "@mozilla/readability": "^0.6.0",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
+    "js-yaml": "^4.1.1",
+    "linkedom": "^0.18.12",
+    "nunjucks": "^3.2.4",
+    "open": "^10.2.0",
+    "picomatch": "^4.0.4",
+    "proper-lockfile": "^4.1.2",
+    "regexp.escape": "^2.0.1",
+    "retry": "0.13.1",
+    "smol-toml": "^1.6.1",
+    "tar": "^7.5.13",
+    "yauzl": "^3.3.0",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/nunjucks": "^3.2.6",
+    "@types/picomatch": "^4.0.3",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/regexp.escape": "^2.0.0",
+    "@types/retry": "0.12.0",
+    "@types/tar": "^7.0.87",
+    "@types/yauzl": "^2.10.3",
+    "@types/yazl": "^2.4.6",
+    "yazl": "^3.3.1"
+  }
+}
diff --git a/packages/agent-core/src/agent/background/index.ts b/packages/agent-core/src/agent/background/index.ts
new file mode 100644
index 000000000..14af9fa52
--- /dev/null
+++ b/packages/agent-core/src/agent/background/index.ts
@@ -0,0 +1,191 @@
+import type { ContentPart } from '@moonshot-ai/kosong';
+
+import type { Agent } from '../..';
+import type { TelemetryPropertyValue } from '../../telemetry';
+import {
+  BackgroundProcessManager,
+  type BackgroundProcessManagerOptions,
+  type BackgroundTaskInfo,
+  isBackgroundTaskTerminal,
+  type ReconcileResult,
+} from '../../tools/builtin';
+import type { BackgroundTaskOrigin } from '../context';
+import { renderNotificationXml } from '../context/notification-xml';
+
+type BackgroundTaskNotification = Record<string, unknown> & {
+  readonly id: string;
+  readonly category: 'task';
+  readonly type: string;
+  readonly source_kind: 'background_task';
+  readonly source_id: string;
+  readonly title: string;
+  readonly severity: 'info' | 'warning';
+  readonly body: string;
+  readonly tail_output: string;
+};
+
+interface BackgroundTaskNotificationContext {
+  readonly content: readonly ContentPart[];
+  readonly origin: BackgroundTaskOrigin;
+  readonly notification: BackgroundTaskNotification;
+}
+
+const NOTIFICATION_TAIL_BYTES = 3_000;
+
+export class BackgroundManager extends BackgroundProcessManager {
+  private readonly scheduledNotificationKeys = new Set<string>();
+  private readonly deliveredNotificationKeys = new Set<string>();
+
+  constructor(
+    public readonly agent: Agent,
+    options: BackgroundProcessManagerOptions = {},
+  ) {
+    super(options);
+
+    this.onLifecycle((event, info) => {
+      switch (event) {
+        case 'started':
+          this.agent.emitEvent({ type: 'background.task.started', info });
+          this.agent.telemetry.track('background_task_created', {
+            kind: info.taskId.startsWith('agent-') ? 'agent' : 'bash',
+          });
+          return;
+        case 'updated':
+          this.agent.emitEvent({ type: 'background.task.updated', info });
+          return;
+        case 'terminated': {
+          this.agent.emitEvent({ type: 'background.task.terminated', info });
+          const success = info.status === 'completed';
+          const duration_s =
+            info.endedAt !== null ? (info.endedAt - info.startedAt) / 1000 : null;
+          const properties: Record<string, TelemetryPropertyValue> = {
+            kind: info.taskId.startsWith('agent-') ? 'agent' : 'bash',
+            success,
+            duration_s,
+          };
+          if (!success) {
+            properties['reason'] =
+              info.timedOut === true
+                ? 'timeout'
+                : info.status === 'killed'
+                  ? 'killed'
+                  : 'error';
+          }
+          this.agent.telemetry.track('background_task_completed', properties);
+          return;
+        }
+      }
+    });
+  }
+
+  override async reconcile(): Promise<ReconcileResult> {
+    const result = await super.reconcile();
+    await this.restoreBackgroundTaskNotifications();
+    return result;
+  }
+
+  protected override onLiveTaskTerminal(info: BackgroundTaskInfo): void | Promise<void> {
+    return this.notifyBackgroundTask(info);
+  }
+
+  private async restoreBackgroundTaskNotifications(): Promise<void> {
+    for (const info of this.list(false)) {
+      if (!isBackgroundTaskTerminal(info.status)) continue;
+      await this.restoreBackgroundTaskNotification(info);
+    }
+  }
+
+  private async notifyBackgroundTask(info: BackgroundTaskInfo): Promise<void> {
+    const context = await this.buildBackgroundTaskNotificationContext(info);
+    if (context === undefined) return;
+    this.agent.turn.steer(context.content, context.origin);
+    this.fireNotificationHook(context.notification);
+  }
+
+  private async restoreBackgroundTaskNotification(info: BackgroundTaskInfo): Promise<void> {
+    const context = await this.buildBackgroundTaskNotificationContext(info);
+    if (context === undefined) return;
+    this.agent.context.appendUserMessage(context.content, context.origin);
+    this.fireNotificationHook(context.notification);
+  }
+
+  private async buildBackgroundTaskNotificationContext(
+    info: BackgroundTaskInfo,
+  ): Promise<BackgroundTaskNotificationContext | undefined> {
+    const origin: BackgroundTaskOrigin = {
+      kind: 'background_task',
+      taskId: info.taskId,
+      status: info.status,
+      notificationId: `task:${info.taskId}:${info.status}`,
+    };
+    const notificationId = origin.notificationId;
+    const key = notificationKey(origin);
+    if (this.scheduledNotificationKeys.has(key)) return;
+    if (this.hasDeliveredNotification(origin)) return;
+
+    this.scheduledNotificationKeys.add(key);
+    const tailOutput = (await this.getOutputSnapshot(info.taskId, NOTIFICATION_TAIL_BYTES))
+      .preview;
+    if (this.hasDeliveredNotification(origin)) return;
+    const label = info.taskId.startsWith('agent-') ? 'agent' : 'task';
+    const notification: BackgroundTaskNotification = {
+      id: notificationId,
+      category: 'task',
+      type: `task.${info.status}`,
+      source_kind: 'background_task',
+      source_id: info.taskId,
+      title: `Background ${label} ${info.status}`,
+      severity: info.status === 'completed' ? 'info' : 'warning',
+      body: `${info.description} ${info.status}.`,
+      tail_output: tailOutput,
+    };
+    const content = [
+      {
+        type: 'text',
+        text: renderNotificationXml(notification),
+      },
+    ] as const;
+    return { content, origin, notification };
+  }
+
+  private fireNotificationHook(notification: BackgroundTaskNotification): void {
+    void this.agent.hooks?.fireAndForgetTrigger('Notification', {
+      matcherValue: notification.type,
+      inputData: {
+        sink: 'context',
+        notificationType: notification.type,
+        title: notification.title,
+        body: notification.body,
+        severity: notification.severity,
+        sourceKind: notification.source_kind,
+        sourceId: notification.source_id,
+      },
+    });
+  }
+
+  markDeliveredNotification(origin: BackgroundTaskOrigin): void {
+    this.deliveredNotificationKeys.add(notificationKey(origin));
+  }
+
+  private hasDeliveredNotification(origin: BackgroundTaskOrigin): boolean {
+    return this.deliveredNotificationKeys.has(notificationKey(origin));
+  }
+
+  override stop(taskId: string, reason?: string) {
+    this.agent.records.logRecord({
+      type: 'background.stop',
+      taskId,
+    });
+    return super.stop(taskId, reason);
+  }
+
+  override _reset(): void {
+    super._reset();
+    this.scheduledNotificationKeys.clear();
+    this.deliveredNotificationKeys.clear();
+  }
+}
+
+function notificationKey(origin: BackgroundTaskOrigin): string {
+  return `${origin.taskId}\0${origin.status}\0${origin.notificationId}`;
+}
diff --git a/packages/agent-core/src/agent/compaction/compaction-instruction.md b/packages/agent-core/src/agent/compaction/compaction-instruction.md
new file mode 100644
index 000000000..68a3f3b12
--- /dev/null
+++ b/packages/agent-core/src/agent/compaction/compaction-instruction.md
@@ -0,0 +1,67 @@
+
+--- This message is a direct task, not part of the above conversation ---
+
+You are now given a task to compact this conversation context according to specific priorities and output requirements.
+
+Output text only. DO NOT CALL ANY TOOLS. Calling tools will be rejected and fails the task. You already have all the information you need in the conversation history. You have only one chance.
+
+The goal of compaction is to keep essential code patterns, technical details, and architectural decisions for continuing development without losing context after the above messages are cleared work.
+
+{{ customInstruction }}
+
+<!-- Compression Priorities (in order) -->
+
+1. **Current Task State**: What is being worked on RIGHT NOW
+2. **Errors & Solutions**: All encountered errors and their resolutions
+3. **Code Evolution**: Final working versions only (remove intermediate attempts)
+4. **System Context**: Project structure, dependencies, environment setup
+5. **Design Decisions**: Architectural choices and their rationale
+6. **TODO Items**: Unfinished tasks and known issues
+
+<!-- Required Output Structure -->
+
+## Current Focus
+
+[What we're working on now]
+
+## Environment
+
+- [Key setup/config points]
+- ...
+
+## Completed Tasks
+
+- [Task]: [Brief outcome]
+- ...
+
+## Active Issues
+
+- [Issue]: [Status/Next steps]
+- ...
+
+## Code State
+
+### [Critical file name]
+
+[Brief description of the file's purpose and current state]
+
+```
+[The latest version of critical code snippets in this file, <20 lines]
+```
+
+### [Critical file name]
+
+- [Useful classes/methods/functions]: [Brief description/usage]
+- ...
+
+<!-- Omit non-critical code, intermediate attempts, and resolved errors -->
+
+## Important Context
+
+- [Any crucial information not covered above]
+- ...
+
+## All User Messages
+
+- [Detailed non tool use user message]
+- ...
diff --git a/packages/agent-core/src/agent/compaction/config.ts b/packages/agent-core/src/agent/compaction/config.ts
new file mode 100644
index 000000000..50d92f306
--- /dev/null
+++ b/packages/agent-core/src/agent/compaction/config.ts
@@ -0,0 +1,19 @@
+export interface CompactionConfig {
+  triggerRatio: number;
+  blockRatio: number;
+  reservedContextSize: number;
+  maxCompactionPerTurn: number;
+  maxRecentSteps: number;
+  maxRecentUserMessages: number;
+  maxRecentSizeRatio: number;
+}
+
+export const DEFAULT_COMPACTION_CONFIG: CompactionConfig = {
+  triggerRatio: 0.85,
+  blockRatio: 0.85, // Same as triggerRatio to disable async compaction
+  reservedContextSize: 50_000,
+  maxCompactionPerTurn: 3,
+  maxRecentSteps: 3,
+  maxRecentUserMessages: Infinity,
+  maxRecentSizeRatio: 0.2,
+};
diff --git a/packages/agent-core/src/agent/compaction/full.ts b/packages/agent-core/src/agent/compaction/full.ts
new file mode 100644
index 000000000..80f23f2bd
--- /dev/null
+++ b/packages/agent-core/src/agent/compaction/full.ts
@@ -0,0 +1,557 @@
+import {
+  ErrorCodes,
+  KimiError,
+  isKimiError,
+  makeErrorPayload,
+  toKimiErrorPayload,
+} from '#/errors';
+import {
+  APIConnectionError,
+  APIEmptyResponseError,
+  APIStatusError,
+  APITimeoutError,
+  inputTotal,
+  type GenerateResult,
+  type Message,
+  type TokenUsage,
+} from '@moonshot-ai/kosong';
+
+import type { Agent } from '..';
+import { isAbortError } from '../../loop/errors';
+import {
+  DEFAULT_MAX_RETRY_ATTEMPTS,
+  retryBackoffDelays,
+  sleepForRetry,
+} from '../../loop/retry';
+import type { TelemetryPropertyValue } from '../../telemetry';
+import {
+  applyCompletionBudget,
+  resolveCompletionBudget,
+} from '../../utils/completion-budget';
+import { renderPrompt } from '../../utils/render-prompt';
+import {
+  estimateTokens,
+  estimateTokensForMessage,
+  estimateTokensForMessages,
+} from '../../utils/tokens';
+import { sliceCompleteMessages } from '../context/complete-slice';
+import { project } from '../context/projector';
+import compactionInstructionTemplate from './compaction-instruction.md';
+import { DEFAULT_COMPACTION_CONFIG, type CompactionConfig } from './config';
+import { renderMessagesToText } from './render-messages';
+import type { CompactionBeginData, CompactionResult } from './types';
+
+export interface CompactionStrategy {
+  shouldCompact(usedSize: number, maxSize: number): boolean;
+  shouldBlock(usedSize: number, maxSize: number): boolean;
+  computeCompactCount(messages: readonly Message[], maxSize: number): number;
+  readonly checkAfterStep: boolean;
+  readonly maxCompactionPerTurn: number;
+}
+
+export class DefaultCompactionStrategy implements CompactionStrategy {
+  constructor(protected readonly config: CompactionConfig = DEFAULT_COMPACTION_CONFIG) {}
+
+  shouldCompact(usedSize: number, maxSize: number): boolean {
+    if (maxSize <= 0) return false;
+    return (
+      usedSize >= maxSize * this.config.triggerRatio ||
+      this.shouldUseReservedContext(maxSize, usedSize)
+    );
+  }
+
+  shouldBlock(usedSize: number, maxSize: number): boolean {
+    if (maxSize <= 0) return false;
+    return (
+      usedSize >= maxSize * this.config.blockRatio ||
+      this.shouldUseReservedContext(maxSize, usedSize)
+    );
+  }
+
+  private shouldUseReservedContext(maxSize: number, usedSize: number): boolean {
+    const reservedSize = this.config.reservedContextSize;
+    return reservedSize > 0 && reservedSize < maxSize && usedSize + reservedSize >= maxSize;
+  }
+
+  computeCompactCount(messages: readonly Message[], maxSize: number) {
+    let splitAt = messages.length;
+    let recentSize = 0;
+    let userMessageCount = 0;
+    let onlySeenTrailingUsers = true;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const m1 = messages[i - 1];
+      const m2 = messages[i];
+      if (m2 === undefined) continue;
+      const isTrailingAssistantPlaceholder =
+        onlySeenTrailingUsers &&
+        m2.role === 'assistant' &&
+        m2.content.length === 0 &&
+        m2.toolCalls.length === 0;
+      if (isTrailingAssistantPlaceholder) {
+        splitAt = i;
+        continue;
+      }
+      const isTrailingUserMessage = onlySeenTrailingUsers && m2.role === 'user';
+      if (!isTrailingUserMessage && messages.length - i >= this.config.maxRecentSteps) break;
+
+      if (m2.role === 'user') {
+        userMessageCount++;
+        if (!isTrailingUserMessage && userMessageCount > this.config.maxRecentUserMessages) {
+          break;
+        }
+      }
+
+      recentSize += estimateTokensForMessage(m2);
+      if (isTrailingUserMessage) {
+        splitAt = i;
+        continue;
+      }
+      if (recentSize > maxSize * this.config.maxRecentSizeRatio) {
+        break;
+      }
+      const canSplitBeforeMessage =
+        m1?.role !== m2.role && !(m1?.role === 'user' && m2.role === 'assistant') && m2.role !== 'tool';
+      if (canSplitBeforeMessage) {
+        splitAt = i;
+      }
+      if (m2.role !== 'user') {
+        onlySeenTrailingUsers = false;
+      }
+    }
+
+    return splitAt;
+  }
+
+  get checkAfterStep(): boolean {
+    return this.config.triggerRatio !== this.config.blockRatio;
+  }
+
+  get maxCompactionPerTurn(): number {
+    return this.config.maxCompactionPerTurn;
+  }
+}
+
+export interface CompactedHistory {
+  text: string;
+}
+
+type CompactionTelemetryTrigger = CompactionBeginData['source'] | 'manual-with-prompt' | 'unknown';
+
+export class FullCompaction {
+  protected compactionCountInTurn = 0;
+  protected compacting: {
+    abortController: AbortController;
+    startedAt: number;
+    telemetryTrigger: CompactionTelemetryTrigger;
+    promise: Promise<void>;
+  } | null = null;
+  protected _compactedHistory: CompactedHistory[] = [];
+  protected readonly strategy: CompactionStrategy;
+
+  constructor(
+    protected readonly agent: Agent,
+    strategy?: CompactionStrategy,
+  ) {
+    this.strategy =
+      strategy ??
+      new DefaultCompactionStrategy({
+        ...DEFAULT_COMPACTION_CONFIG,
+        reservedContextSize:
+          agent.providerManager?.config.loopControl?.reservedContextSize ??
+          DEFAULT_COMPACTION_CONFIG.reservedContextSize,
+      });
+  }
+
+  get isCompacting(): boolean {
+    return this.compacting !== null;
+  }
+
+  begin(data: Readonly<CompactionBeginData>): void {
+    this.agent.records.logRecord({
+      type: 'full_compaction.begin',
+      ...data,
+    });
+    if (this.compacting) return;
+    if (data.source === 'manual') {
+      this.compactionCountInTurn = 0;
+    } else {
+      this.compactionCountInTurn += 1;
+    }
+    if (this.compactionCountInTurn > this.strategy.maxCompactionPerTurn) return;
+    if (!this.agent.records.restoring) {
+      this.startCompactionWorker(data);
+    }
+  }
+
+  private startCompactionWorker(data: Readonly<CompactionBeginData>): void {
+    const abortController = new AbortController();
+    this.agent.emitEvent({
+      type: 'compaction.started',
+      trigger: data.source,
+      instruction: data.instruction,
+    });
+    const active = {
+      abortController,
+      startedAt: Date.now(),
+      telemetryTrigger: compactionTelemetryTrigger(data.source, data.instruction),
+      promise: Promise.resolve(),
+    };
+    this.compacting = active;
+    active.promise = this.compactionWorker(abortController.signal, data);
+  }
+
+  cancel(): void {
+    this.markCanceled();
+  }
+
+  private markCanceled(): void {
+    if (!this.compacting) return;
+    this.agent.records.logRecord({
+      type: 'full_compaction.cancel',
+    });
+    this.compacting.abortController.abort();
+    this.compacting = null;
+    this.agent.emitEvent({ type: 'compaction.cancelled' });
+  }
+
+  complete(
+    result: CompactionResult,
+    llmUsage?: TokenUsage | undefined,
+    retryCount: number = 0,
+  ): void {
+    this.agent.records.logRecord({
+      type: 'full_compaction.complete',
+      ...result,
+    });
+    const active = this.compacting;
+    this.compacting = null;
+    const history = this.agent.context.history;
+    this._compactedHistory.push({
+      text: renderMessagesToText(history),
+    });
+    this.agent.emitEvent({ type: 'compaction.completed', result });
+    if (active !== null) {
+      const properties: Record<string, TelemetryPropertyValue> = {
+        trigger_type: active.telemetryTrigger,
+        before_tokens: result.tokensBefore,
+        after_tokens: result.tokensAfter,
+        duration_ms: Date.now() - active.startedAt,
+        compacted_count: result.compactedCount,
+        retry_count: retryCount,
+      };
+      if (llmUsage !== undefined) {
+        properties['llm_input_tokens'] = inputTotal(llmUsage);
+        properties['llm_output_tokens'] = llmUsage.output;
+      }
+      this.agent.telemetry.track('compaction_finished', properties);
+    }
+  }
+
+  private get tokenCountWithPending(): number {
+    return this.agent.context.tokenCountWithPending;
+  }
+
+  private get maxContextSize() {
+    return this.agent.config.modelCapabilities.max_context_tokens;
+  }
+
+  private get shouldCompact(): boolean {
+    return this.strategy.shouldCompact(this.tokenCountWithPending, this.maxContextSize);
+  }
+
+  private get shouldBlock(): boolean {
+    return this.strategy.shouldBlock(this.tokenCountWithPending, this.maxContextSize);
+  }
+
+  resetForTurn(): void {
+    this.compactionCountInTurn = 0;
+  }
+
+  async handleOverflowError(signal: AbortSignal, error: unknown) {
+    const didStartCompaction = this.beginAutoCompaction();
+    if (!didStartCompaction && !this.compacting) throw error;
+    // Always block on overflow errors
+    await this.block(signal);
+  }
+
+  async beforeStep(signal: AbortSignal): Promise<void> {
+    this.checkAutoCompaction();
+    if (this.shouldBlock) {
+      await this.block(signal);
+    }
+  }
+
+  async afterStep(): Promise<void> {
+    if (this.strategy.checkAfterStep) {
+      this.checkAutoCompaction(false);
+    }
+    // Do not block after the step
+  }
+
+  private checkAutoCompaction(throwOnLimit: boolean = true): boolean {
+    if (this.compacting) return true;
+    if (!this.shouldCompact) return false;
+
+    return this.beginAutoCompaction(throwOnLimit);
+  }
+
+  private beginAutoCompaction(throwOnLimit: boolean = true): boolean {
+    if (this.compacting) return true;
+    const maxCompactions = this.strategy.maxCompactionPerTurn;
+    if (this.compactionCountInTurn >= maxCompactions) {
+      if (throwOnLimit) {
+        throw new KimiError(ErrorCodes.CONTEXT_OVERFLOW, `Compaction limit exceeded (${String(maxCompactions)})`, {
+          details: { maxCompactions },
+        });
+      }
+      return false;
+    }
+    const history = this.agent.context.history;
+    const compactedCount = this.computeCompactableCount(history);
+    if (compactedCount === 0) return false;
+    if (
+      this.maxContextSize > 0 &&
+      estimateTokensForMessages(project(history.slice(compactedCount))) >= this.maxContextSize
+    ) {
+      return false;
+    }
+    this.agent.fullCompaction.begin({ source: 'auto', instruction: undefined });
+    return true;
+  }
+
+  private async block(signal: AbortSignal): Promise<void> {
+    const active = this.compacting;
+    if (active) {
+      signal.addEventListener('abort', () => {
+        if (this.compacting === active) {
+          this.cancel();
+        }
+      });
+      this.agent.emitEvent({
+        type: 'compaction.blocked',
+        turnId: this.agent.turn.currentId,
+      });
+      await active.promise;
+    }
+  }
+
+  private async compactionWorker(
+    signal: AbortSignal,
+    data: Readonly<CompactionBeginData>,
+  ): Promise<void> {
+    const startedAt = Date.now();
+    let tokensBeforeForError = 0;
+    let retryCountForTelemetry = 0;
+    try {
+      const originalHistory = [...this.agent.context.history];
+      const tokensBefore = this.agent.context.tokenCount;
+      tokensBeforeForError = tokensBefore;
+      const compactedCount = this.computeCompactableCount(originalHistory);
+      if (compactedCount === 0) {
+        this.markCanceled();
+        return undefined;
+      }
+      signal.throwIfAborted();
+      await this.triggerPreCompactHook(data, tokensBefore, signal);
+      signal.throwIfAborted();
+
+      const model = this.agent.config.model;
+      const messages = [
+        ...project(originalHistory.slice(0, compactedCount)),
+        {
+          role: 'user',
+          content: [
+            {
+              type: 'text',
+              text: COMPACTION_INSTRUCTION(data.instruction),
+            },
+          ],
+          toolCalls: [],
+        } satisfies Message,
+      ];
+      const { response, retryCount } = await this.generateCompactionResponse({
+        messages,
+        signal,
+        onRetry: (count) => {
+          retryCountForTelemetry = count;
+        },
+      });
+      if (response.usage !== null) {
+        this.agent.usage.record(model, response.usage);
+      }
+
+      const summary =
+        typeof response.message.content === 'string'
+          ? response.message.content
+          : response.message.content
+              .map((part) => (part.type === 'text' ? part.text : ''))
+              .join('');
+
+      const newHistory = this.agent.context.history;
+      for (let i = 0; i < originalHistory.length; i++) {
+        if (newHistory[i] !== originalHistory[i]) {
+          // History changed during compaction, likely due to undo
+          this.cancel();
+          return undefined;
+        }
+      }
+
+      const recent = originalHistory.slice(compactedCount);
+      const tokensAfter = estimateTokens(summary) + estimateTokensForMessages(project(recent));
+
+      const result: CompactionResult = {
+        summary,
+        compactedCount,
+        tokensBefore,
+        tokensAfter,
+      };
+
+      this.complete(result, response.usage ?? undefined, retryCount);
+      this.agent.context.applyCompaction(result);
+      this.triggerPostCompactHook(data, result);
+    } catch (error) {
+      if (!isAbortError(error)) {
+        this.agent.log.error('compaction failed', {
+          code: isKimiError(error) ? error.code : undefined,
+          error,
+        });
+        this.markCanceled();
+        const payload =
+          isKimiError(error) && error.code === ErrorCodes.AUTH_LOGIN_REQUIRED
+            ? toKimiErrorPayload(error)
+            : makeErrorPayload(ErrorCodes.COMPACTION_FAILED, String(error));
+        this.agent.emitEvent({
+          type: 'error',
+          ...payload,
+        });
+        this.agent.telemetry.track('compaction_failed', {
+          trigger_type: compactionTelemetryTrigger(data.source, data.instruction),
+          before_tokens: tokensBeforeForError,
+          duration_ms: Date.now() - startedAt,
+          retry_count: retryCountForTelemetry,
+          error_type: error instanceof Error ? error.name : 'Unknown',
+        });
+      }
+    }
+  }
+
+  private async generateCompactionResponse({
+    messages,
+    signal,
+    onRetry,
+  }: {
+    readonly messages: Message[];
+    readonly signal: AbortSignal;
+    readonly onRetry?: ((retryCount: number) => void) | undefined;
+  }): Promise<{ readonly response: GenerateResult; readonly retryCount: number }> {
+    const maxAttempts =
+      this.agent.providerManager?.config.loopControl?.maxRetriesPerStep ??
+      DEFAULT_MAX_RETRY_ATTEMPTS;
+    const delays = retryBackoffDelays(maxAttempts);
+    let retryCount = 0;
+
+    // Clamp the completion budget against the compaction input. Compaction
+    // is triggered when context is already near full, so an unbounded
+    // default cap is most at risk of either exceeding the model limit or
+    // returning empty `content` on reasoning models. The cloned provider
+    // is local to this call and never persisted back to agent state.
+    const completionBudget = resolveCompletionBudget({
+      reservedContextSize:
+        this.agent.providerManager?.config.loopControl?.reservedContextSize,
+    });
+    const effectiveProvider = applyCompletionBudget({
+      provider: this.agent.config.provider,
+      budget: completionBudget,
+      capability: this.agent.config.modelCapabilities,
+      messages,
+      systemPrompt: this.agent.config.systemPrompt,
+      tools: this.agent.tools.loopTools,
+    });
+
+    for (let attempt = 1; ; attempt += 1) {
+      try {
+        const response = await this.agent.generate(
+          effectiveProvider,
+          this.agent.config.systemPrompt,
+          [...this.agent.tools.loopTools],
+          messages,
+          undefined,
+          { signal },
+        );
+        return { response, retryCount };
+      } catch (error) {
+        if (attempt >= maxAttempts || !isRetryableCompactionError(error)) {
+          throw error;
+        }
+        retryCount += 1;
+        onRetry?.(retryCount);
+        await sleepForRetry(delays[attempt - 1] ?? 0, signal);
+      }
+    }
+  }
+
+  get compactedHistory(): readonly CompactedHistory[] {
+    return this._compactedHistory;
+  }
+
+  private async triggerPreCompactHook(
+    data: Readonly<CompactionBeginData>,
+    tokenCount: number,
+    signal: AbortSignal,
+  ): Promise<void> {
+    await this.agent.hooks?.trigger('PreCompact', {
+      matcherValue: data.source,
+      signal,
+      inputData: {
+        trigger: data.source,
+        tokenCount,
+      },
+    });
+  }
+
+  private triggerPostCompactHook(
+    data: Readonly<CompactionBeginData>,
+    result: CompactionResult,
+  ): void {
+    void this.agent.hooks?.fireAndForgetTrigger('PostCompact', {
+      matcherValue: data.source,
+      inputData: {
+        trigger: data.source,
+        estimatedTokenCount: result.tokensAfter,
+      },
+    });
+  }
+
+  private computeCompactableCount(history: readonly Message[]): number {
+    return sliceCompleteMessages(
+      history,
+      this.strategy.computeCompactCount(history, this.maxContextSize),
+    );
+  }
+}
+
+export const COMPACTION_INSTRUCTION = (customInstruction = ''): string =>
+  renderPrompt(compactionInstructionTemplate, { customInstruction });
+
+function compactionTelemetryTrigger(
+  trigger: CompactionBeginData['source'] | undefined,
+  instruction: string | undefined,
+): CompactionTelemetryTrigger {
+  if (trigger === undefined) return 'unknown';
+  if (trigger === 'manual' && instruction !== undefined && instruction.length > 0) {
+    return 'manual-with-prompt';
+  }
+  return trigger;
+}
+
+function isRetryableCompactionError(error: unknown): boolean {
+  if (error instanceof APIConnectionError || error instanceof APITimeoutError) {
+    return true;
+  }
+  if (error instanceof APIEmptyResponseError) {
+    return true;
+  }
+  if (!(error instanceof APIStatusError)) return false;
+  const statusCode = (error as { readonly statusCode?: unknown }).statusCode;
+  return typeof statusCode === 'number' && [429, 500, 502, 503, 504].includes(statusCode);
+}
diff --git a/packages/agent-core/src/agent/compaction/index.ts b/packages/agent-core/src/agent/compaction/index.ts
new file mode 100644
index 000000000..d8da8bbd9
--- /dev/null
+++ b/packages/agent-core/src/agent/compaction/index.ts
@@ -0,0 +1,3 @@
+export * from './full';
+export * from './config';
+export * from './types';
diff --git a/packages/agent-core/src/agent/compaction/render-messages.ts b/packages/agent-core/src/agent/compaction/render-messages.ts
new file mode 100644
index 000000000..81a298a7d
--- /dev/null
+++ b/packages/agent-core/src/agent/compaction/render-messages.ts
@@ -0,0 +1,111 @@
+import type { Message } from '@moonshot-ai/kosong';
+
+export function renderMessagesToText(messages: readonly Message[]): string {
+  return messages.map((message, index) => renderMessageToText(message, index)).join('\n\n');
+}
+
+function renderMessageToText(message: Message, index: number): string {
+  const header = [`message ${String(index + 1)}`, `role=${message.role}`];
+  if (message.name !== undefined) {
+    header.push(`name=${JSON.stringify(message.name)}`);
+  }
+  if (message.toolCallId !== undefined) {
+    header.push(`toolCallId=${JSON.stringify(message.toolCallId)}`);
+  }
+  if (message.partial === true) {
+    header.push('partial=true');
+  }
+
+  const lines = [`--- ${header.join(' ')} ---`];
+  if (message.content.length === 0) {
+    lines.push('[empty content]');
+  } else {
+    lines.push(...message.content.map(renderContentPartToText));
+  }
+
+  if (message.toolCalls.length > 0) {
+    lines.push('tool calls:');
+    for (const toolCall of message.toolCalls) {
+      lines.push(renderToolCallToText(toolCall));
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function renderContentPartToText(part: Message['content'][number]): string {
+  switch (part.type) {
+    case 'text':
+      return renderBlock('text', part.text);
+    case 'think':
+      return renderBlock('think', part.think);
+    case 'image_url':
+      return renderMediaPart('image_url', part.imageUrl.url, part.imageUrl.id);
+    case 'audio_url':
+      return renderMediaPart('audio_url', part.audioUrl.url, part.audioUrl.id);
+    case 'video_url':
+      return renderMediaPart('video_url', part.videoUrl.url, part.videoUrl.id);
+    default:
+      return renderBlock('content', stringifyJsonish(part));
+  }
+}
+
+function renderToolCallToText(toolCall: Message['toolCalls'][number]): string {
+  const lines = [
+    `- ${toolCall.id}: ${toolCall.function.name}`,
+    renderBlock('arguments', renderToolCallArguments(toolCall.function.arguments)),
+  ];
+
+  if (toolCall.extras !== undefined) {
+    lines.push(renderBlock('extras', stringifyJsonish(toolCall.extras)));
+  }
+
+  return lines.join('\n');
+}
+
+function renderToolCallArguments(args: string | null): string {
+  if (args === null) return 'null';
+
+  try {
+    return stringifyJsonish(JSON.parse(args));
+  } catch {
+    return args;
+  }
+}
+
+function renderMediaPart(type: string, url: string, id?: string | undefined): string {
+  if (id === undefined) return `${type}: ${url}`;
+  return `${type}: ${url} (id=${id})`;
+}
+
+function renderBlock(label: string, value: string): string {
+  return `${label}:\n${indentBlock(value)}`;
+}
+
+function indentBlock(value: string): string {
+  if (value.length === 0) return '  ';
+  return value
+    .split('\n')
+    .map((line) => `  ${line}`)
+    .join('\n');
+}
+
+function stringifyJsonish(value: unknown): string {
+  const seen = new WeakSet<object>();
+  const replacer = (_key: string, nested: unknown): unknown => {
+    if (typeof nested === 'bigint') return `${nested.toString()}n`;
+    if (typeof nested === 'function') return `[Function ${nested.name || 'anonymous'}]`;
+    if (typeof nested === 'symbol') return nested.toString();
+    if (nested !== null && typeof nested === 'object') {
+      if (seen.has(nested)) return '[Circular]';
+      seen.add(nested);
+    }
+    return nested;
+  };
+
+  try {
+    return JSON.stringify(value, replacer, 2) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
diff --git a/packages/agent-core/src/agent/compaction/types.ts b/packages/agent-core/src/agent/compaction/types.ts
new file mode 100644
index 000000000..3936faef7
--- /dev/null
+++ b/packages/agent-core/src/agent/compaction/types.ts
@@ -0,0 +1,11 @@
+export interface CompactionResult {
+  summary: string;
+  compactedCount: number;
+  tokensBefore: number;
+  tokensAfter: number;
+}
+
+export interface CompactionBeginData {
+  instruction?: string;
+  source: 'manual' | 'auto';
+}
diff --git a/packages/agent-core/src/agent/config/index.ts b/packages/agent-core/src/agent/config/index.ts
new file mode 100644
index 000000000..18a33d14b
--- /dev/null
+++ b/packages/agent-core/src/agent/config/index.ts
@@ -0,0 +1,134 @@
+import {
+  createProvider,
+  UNKNOWN_CAPABILITY,
+  type ChatProvider,
+  type ModelCapability,
+  type ProviderConfig,
+} from '@moonshot-ai/kosong';
+
+import type { Agent } from '..';
+import type { ResolvedRuntimeProvider } from '../../providers/runtime-provider';
+import type { AgentConfigData, AgentConfigUpdateData } from './types';
+import { resolveThinkingEffort, type ThinkingEffort } from './thinking';
+
+export * from './types';
+export { resolveThinkingEffort, type ThinkingEffort } from './thinking';
+
+export class ConfigState {
+  private _cwd: string = '';
+  private _modelAlias: string | undefined;
+  private _profileName: string | undefined;
+  private _thinkingLevel: ThinkingEffort = 'off';
+  private _systemPrompt: string = '';
+
+  constructor(protected readonly agent: Agent) {}
+
+  update(input: AgentConfigUpdateData): void {
+    const changed = { ...input };
+    if (Object.keys(changed).length === 0) return;
+
+    if (changed.thinkingLevel !== undefined) {
+      changed.thinkingLevel = resolveThinkingEffort(
+        changed.thinkingLevel,
+        this.agent.providerManager?.config.thinking,
+      );
+    }
+    this.agent.records.logRecord({
+      type: 'config.update',
+      ...changed,
+    });
+    this.agent.replayBuilder.push({
+      type: 'config_updated',
+      config: changed,
+    });
+    if (changed.cwd !== undefined) this._cwd = changed.cwd;
+    if (Object.hasOwn(changed, 'modelAlias')) {
+      this._modelAlias = changed.modelAlias ?? undefined;
+    }
+    if (Object.hasOwn(changed, 'profileName')) this._profileName = changed.profileName;
+    if (changed.thinkingLevel !== undefined)
+      this._thinkingLevel = changed.thinkingLevel as ThinkingEffort;
+    if (changed.systemPrompt !== undefined) this._systemPrompt = changed.systemPrompt;
+    if (this.hasProvider && (changed.cwd !== undefined || Object.hasOwn(changed, 'modelAlias'))) {
+      this.agent.tools.initializeBuiltinTools();
+    }
+    this.agent.emitStatusUpdated();
+  }
+
+  data(): AgentConfigData {
+    const resolved = this.tryResolvedProviderConfig();
+    return {
+      cwd: this.cwd,
+      provider: resolved?.provider,
+      modelAlias: this._modelAlias,
+      modelCapabilities: resolved?.modelCapabilities ?? UNKNOWN_CAPABILITY,
+      profileName: this.profileName,
+      thinkingLevel: this.thinkingLevel,
+      systemPrompt: this.systemPrompt,
+    };
+  }
+
+  get cwd(): string {
+    return this._cwd;
+  }
+
+  get hasModel(): boolean {
+    return this._modelAlias !== undefined;
+  }
+
+  get hasProvider(): boolean {
+    return this.tryResolvedProviderConfig() !== undefined;
+  }
+
+  get providerConfig(): ProviderConfig {
+    const provider = this.resolvedProviderConfig?.provider;
+    if (provider === undefined) {
+      throw new Error('Provider not set');
+    }
+    return provider;
+  }
+
+  get provider(): ChatProvider {
+    return createProvider(this.providerConfig);
+  }
+
+  get model(): string {
+    if (this._modelAlias === undefined) {
+      throw new Error('Model not set');
+    }
+    return this._modelAlias;
+  }
+
+  get modelAlias(): string | undefined {
+    return this._modelAlias;
+  }
+
+  get thinkingLevel(): ThinkingEffort {
+    return this._thinkingLevel;
+  }
+
+  get profileName(): string | undefined {
+    return this._profileName;
+  }
+
+  get systemPrompt(): string {
+    return this._systemPrompt;
+  }
+
+  get modelCapabilities(): ModelCapability {
+    return this.tryResolvedProviderConfig()?.modelCapabilities ?? UNKNOWN_CAPABILITY;
+  }
+
+  private get resolvedProviderConfig(): ResolvedRuntimeProvider | undefined {
+    if (this._modelAlias === undefined) return undefined;
+    return this.agent.providerManager?.resolveProviderConfigForModel(this._modelAlias);
+  }
+
+  private tryResolvedProviderConfig(): ResolvedRuntimeProvider | undefined {
+    try {
+      return this.resolvedProviderConfig;
+    } catch {
+      return undefined;
+    }
+  }
+}
diff --git a/packages/agent-core/src/agent/config/thinking.ts b/packages/agent-core/src/agent/config/thinking.ts
new file mode 100644
index 000000000..f6a7d924a
--- /dev/null
+++ b/packages/agent-core/src/agent/config/thinking.ts
@@ -0,0 +1,31 @@
+import type { ThinkingEffort } from '@moonshot-ai/kosong';
+
+import type { ThinkingConfig } from '../../config/schema';
+
+export type { ThinkingEffort };
+
+const DEFAULT_THINKING_EFFORT: ThinkingEffort = 'high';
+
+const THINKING_EFFORTS = new Set<ThinkingEffort>(['low', 'medium', 'high', 'xhigh', 'max']);
+
+export function resolveThinkingEffort(
+  requested: string | undefined,
+  defaults: ThinkingConfig | undefined,
+): ThinkingEffort {
+  const configEffort = parseEffort(defaults?.effort) ?? DEFAULT_THINKING_EFFORT;
+  const normalized = requested?.trim().toLowerCase();
+  if (!normalized) {
+    if (defaults?.mode === 'off') return 'off';
+    return configEffort;
+  }
+  if (normalized === 'off') return 'off';
+  if (normalized === 'on') return configEffort;
+  return parseEffort(normalized) ?? configEffort;
+}
+
+function parseEffort(value: string | undefined): ThinkingEffort | undefined {
+  const normalized = value?.trim().toLowerCase();
+  return normalized !== undefined && THINKING_EFFORTS.has(normalized as ThinkingEffort)
+    ? (normalized as ThinkingEffort)
+    : undefined;
+}
diff --git a/packages/agent-core/src/agent/config/types.ts b/packages/agent-core/src/agent/config/types.ts
new file mode 100644
index 000000000..fc7a785f5
--- /dev/null
+++ b/packages/agent-core/src/agent/config/types.ts
@@ -0,0 +1,19 @@
+import type { ModelCapability, ProviderConfig } from '@moonshot-ai/kosong';
+
+export interface AgentConfigData {
+  cwd: string;
+  provider?: ProviderConfig;
+  modelAlias?: string;
+  modelCapabilities: ModelCapability;
+  profileName?: string;
+  thinkingLevel: string;
+  systemPrompt: string;
+}
+
+export type AgentConfigUpdateData = Partial<{
+  cwd: string;
+  modelAlias: string;
+  profileName: string;
+  thinkingLevel: string;
+  systemPrompt: string;
+}>;
diff --git a/packages/agent-core/src/agent/context/complete-slice.ts b/packages/agent-core/src/agent/context/complete-slice.ts
new file mode 100644
index 000000000..258cdf90e
--- /dev/null
+++ b/packages/agent-core/src/agent/context/complete-slice.ts
@@ -0,0 +1,55 @@
+import type { Message } from '@moonshot-ai/kosong';
+
+export function sliceCompleteMessages(
+  messages: readonly Message[],
+  requestedEnd: number,
+): number {
+  let normalized = Math.max(0, Math.min(messages.length, requestedEnd));
+
+  for (let i = 0; i < messages.length; i += 1) {
+    const message = messages[i];
+    if (message?.role !== 'assistant' || message.toolCalls.length === 0) continue;
+
+    const end = findToolExchangeEnd(messages, i);
+    if (end === undefined) {
+      if (normalized > i) {
+        normalized = includePromptForAssistant(messages, i);
+      }
+      continue;
+    }
+
+    if (normalized > i && normalized < end) {
+      normalized = includePromptForAssistant(messages, i);
+    }
+  }
+
+  return normalized;
+}
+
+function findToolExchangeEnd(
+  messages: readonly Message[],
+  assistantIndex: number,
+): number | undefined {
+  const assistant = messages[assistantIndex];
+  if (assistant?.role !== 'assistant') return undefined;
+
+  const pending = new Set(assistant.toolCalls.map((call) => call.id));
+  if (pending.size === 0) return assistantIndex + 1;
+
+  for (let i = assistantIndex + 1; i < messages.length; i += 1) {
+    const message = messages[i];
+    if (message?.role !== 'tool') return undefined;
+    if (message.toolCallId !== undefined) {
+      pending.delete(message.toolCallId);
+    }
+    if (pending.size === 0) return i + 1;
+  }
+
+  return undefined;
+}
+
+function includePromptForAssistant(messages: readonly Message[], assistantIndex: number): number {
+  const previous = messages[assistantIndex - 1];
+  if (previous?.role === 'user') return assistantIndex - 1;
+  return assistantIndex;
+}
diff --git a/packages/agent-core/src/agent/context/index.ts b/packages/agent-core/src/agent/context/index.ts
new file mode 100644
index 000000000..fd9141ed2
--- /dev/null
+++ b/packages/agent-core/src/agent/context/index.ts
@@ -0,0 +1,268 @@
+import { createToolMessage, type ContentPart, type Message } from '@moonshot-ai/kosong';
+
+import type { Agent } from '..';
+import type { ExecutableToolResult, LoopRecordedEvent } from '../../loop';
+import { estimateTokensForMessages } from '../../utils/tokens';
+import type { CompactionResult } from '../compaction';
+import { project } from './projector';
+import {
+  USER_PROMPT_ORIGIN,
+  type AgentContextData,
+  type ContextMessage,
+  type PromptOrigin,
+} from './types';
+
+export * from './types';
+
+const TOOL_ERROR_STATUS = '<system>ERROR: Tool execution failed.</system>';
+const TOOL_EMPTY_STATUS = '<system>Tool output is empty.</system>';
+const TOOL_EMPTY_ERROR_STATUS =
+  '<system>ERROR: Tool execution failed. Tool output is empty.</system>';
+const TOOL_OUTPUT_EMPTY_TEXT = 'Tool output is empty.';
+
+export class ContextMemory {
+  private _history: ContextMessage[] = [];
+  private _tokenCount = 0;
+  private tokenCountCoveredMessageCount = 0;
+  private openSteps: Map<string, ContextMessage> = new Map();
+  private pendingToolResultIds = new Set<string>();
+  private deferredMessages: ContextMessage[] = [];
+
+  constructor(protected readonly agent: Agent) {}
+
+  appendUserMessage(
+    content: readonly ContentPart[],
+    origin: PromptOrigin = USER_PROMPT_ORIGIN,
+  ): void {
+    this.appendMessage({
+      role: 'user',
+      content: [...content],
+      toolCalls: [],
+      origin,
+    });
+  }
+
+  appendSystemReminder(content: string, origin: PromptOrigin): void {
+    const text = `<system-reminder>\n${content}\n</system-reminder>`;
+    this.appendMessage({
+      role: 'user',
+      content: [{ type: 'text', text }],
+      toolCalls: [],
+      origin,
+    });
+  }
+
+  markLastUserPromptBlocked(hookEvent: string): void {
+    this.agent.records.logRecord({
+      type: 'context.mark_last_user_prompt_blocked',
+      hookEvent,
+    });
+    for (let i = this._history.length - 1; i >= 0; i--) {
+      const message = this._history[i];
+      if (message?.role !== 'user' || message.origin?.kind !== 'user') continue;
+      this._history[i] = {
+        ...message,
+        origin: { ...message.origin, blockedByHook: hookEvent },
+      };
+      return;
+    }
+  }
+
+  clear(): void {
+    this.agent.records.logRecord({ type: 'context.clear' });
+    this._history = [];
+    this._tokenCount = 0;
+    this.tokenCountCoveredMessageCount = 0;
+    this.openSteps.clear();
+    this.pendingToolResultIds.clear();
+    this.deferredMessages = [];
+    this.agent.injection.onContextClear();
+    this.agent.emitStatusUpdated();
+  }
+
+  applyCompaction(summary: CompactionResult): void {
+    this.agent.records.logRecord({
+      type: 'context.apply_compaction',
+      ...summary,
+    });
+    this._history = [
+      {
+        role: 'assistant',
+        content: [{ type: 'text', text: summary.summary }],
+        toolCalls: [],
+        origin: { kind: 'compaction_summary' },
+      },
+      ...this._history.slice(summary.compactedCount),
+    ];
+    this.openSteps.clear();
+    this.flushDeferredMessagesIfToolExchangeClosed();
+    this._tokenCount = summary.tokensAfter;
+    this.tokenCountCoveredMessageCount = this._history.length;
+    this.agent.injection.onContextCompacted(summary.compactedCount);
+    this.agent.emitStatusUpdated();
+  }
+
+  data(): AgentContextData {
+    return {
+      history: this.history,
+      tokenCount: this.tokenCount,
+    };
+  }
+
+  get tokenCount(): number {
+    return this._tokenCount;
+  }
+
+  get tokenCountWithPending(): number {
+    const pendingMessages = this._history.slice(this.tokenCountCoveredMessageCount);
+    return this._tokenCount + estimateTokensForMessages(project(pendingMessages));
+  }
+
+  get history(): readonly ContextMessage[] {
+    return this._history;
+  }
+
+  get messages(): Message[] {
+    return project(this.history);
+  }
+
+  appendLoopEvent(event: LoopRecordedEvent): void {
+    this.agent.records.logRecord({
+      type: 'context.append_loop_event',
+      event,
+    });
+    switch (event.type) {
+      case 'step.begin': {
+        const message: ContextMessage = {
+          role: 'assistant',
+          content: [],
+          toolCalls: [],
+        };
+        this.pushHistory(message);
+        this.openSteps.set(event.uuid, message);
+        return;
+      }
+      case 'step.end': {
+        const openStep = this.openSteps.get(event.uuid);
+        this.openSteps.delete(event.uuid);
+        if (event.usage !== undefined) {
+          const openStepIndex = openStep === undefined ? -1 : this._history.indexOf(openStep);
+          this._tokenCount =
+            event.usage.inputCacheRead +
+            event.usage.inputCacheCreation +
+            event.usage.inputOther +
+            event.usage.output;
+          this.tokenCountCoveredMessageCount =
+            openStepIndex === -1 ? this._history.length : openStepIndex + 1;
+        }
+        this.flushDeferredMessagesIfToolExchangeClosed();
+        return;
+      }
+      case 'content.part': {
+        const openStep = this.openSteps.get(event.stepUuid);
+        if (openStep === undefined) {
+          throw new Error(
+            `Received content_part for unknown step_uuid '${event.stepUuid}' (no open step_begin)`,
+          );
+        }
+        openStep.content.push(event.part);
+        return;
+      }
+      case 'tool.call': {
+        const openStep = this.openSteps.get(event.stepUuid);
+        if (openStep === undefined) {
+          throw new Error(
+            `Received tool_call for unknown step_uuid '${event.stepUuid}' (no open step_begin)`,
+          );
+        }
+        openStep.toolCalls.push({
+          type: 'function',
+          id: event.toolCallId,
+          function: {
+            name: event.name,
+            arguments: event.args === undefined ? null : JSON.stringify(event.args),
+          },
+        });
+        this.pendingToolResultIds.add(event.toolCallId);
+        return;
+      }
+      case 'tool.result': {
+        const message = createToolMessage(event.toolCallId, toolResultOutputForModel(event.result));
+        this.pushHistory({
+          ...message,
+          role: 'tool',
+          isError: event.result.isError,
+        });
+        this.pendingToolResultIds.delete(event.toolCallId);
+        this.flushDeferredMessagesIfToolExchangeClosed();
+        return;
+      }
+    }
+  }
+
+  appendMessage(message: ContextMessage): void {
+    this.agent.records.logRecord({
+      type: 'context.append_message',
+      message,
+    });
+    if (this.hasOpenToolExchange()) {
+      this.deferredMessages.push(message);
+      return;
+    }
+    this.pushHistory(message);
+  }
+
+  private flushDeferredMessagesIfToolExchangeClosed(): void {
+    if (this.pendingToolResultIds.size > 0 || this.deferredMessages.length === 0) {
+      return;
+    }
+    this.pushHistory(...this.deferredMessages);
+    this.deferredMessages = [];
+  }
+
+  private hasOpenToolExchange(): boolean {
+    return this.pendingToolResultIds.size > 0;
+  }
+
+  private pushHistory(...messages: ContextMessage[]): void {
+    this._history.push(...messages);
+    for (const message of messages) {
+      if (message.origin?.kind === 'background_task') {
+        this.agent.background.markDeliveredNotification(message.origin);
+      }
+      this.agent.replayBuilder.push({
+        type: 'message',
+        message,
+      });
+    }
+  }
+}
+
+function toolResultOutputForModel(result: ExecutableToolResult): string | ContentPart[] {
+  const output = result.output;
+  if (typeof output === 'string') {
+    if (result.isError === true) {
+      if (output.length === 0) return TOOL_EMPTY_ERROR_STATUS;
+      if (output.trimStart().startsWith('<system>ERROR:')) return output;
+      return `${TOOL_ERROR_STATUS}\n${output}`;
+    }
+    return isEmptyOutputText(output) ? TOOL_EMPTY_STATUS : output;
+  }
+
+  if (output.length === 0) {
+    return [
+      {
+        type: 'text',
+        text: result.isError === true ? TOOL_EMPTY_ERROR_STATUS : TOOL_EMPTY_STATUS,
+      },
+    ];
+  }
+  if (result.isError === true) {
+    return [{ type: 'text', text: TOOL_ERROR_STATUS }, ...output];
+  }
+  return output;
+}
+
+function isEmptyOutputText(output: string): boolean {
+  return output.length === 0 || output.trim() === TOOL_OUTPUT_EMPTY_TEXT;
+}
diff --git a/packages/agent-core/src/agent/context/notification-xml.ts b/packages/agent-core/src/agent/context/notification-xml.ts
new file mode 100644
index 000000000..72e584b48
--- /dev/null
+++ b/packages/agent-core/src/agent/context/notification-xml.ts
@@ -0,0 +1,72 @@
+/**
+ * Notification XML rendering — produces the chat-history injection text
+ * shared between the live ContextMemory and the projector.
+ *
+ * Output shape:
+ *   <notification id="..." category="..." type="..." source_kind="..." source_id="...">
+ *   Title: ...
+ *   Severity: ...
+ *   <body>
+ *   <task-notification>   (only when source_kind === 'background_task' and tail_output is non-empty)
+ *   <truncated tail>
+ *   </task-notification>
+ *   </notification>
+ *
+ * The opening-tag names (`<notification ` / `<task-notification>`) are
+ * load-bearing for the projector's `mergeAdjacentUserMessages` detector
+ * — rename requires updating the detector too.
+ */
+
+export function renderNotificationXml(data: Record<string, unknown>): string {
+  const id = stringAttr(data['id'], 'unknown');
+  const category = stringAttr(data['category'], 'unknown');
+  const type = stringAttr(data['type'], 'unknown');
+  const sourceKind = stringAttr(data['source_kind'], 'unknown');
+  const sourceId = stringAttr(data['source_id'], 'unknown');
+  const title = typeof data['title'] === 'string' ? data['title'] : '';
+  const severity = typeof data['severity'] === 'string' ? data['severity'] : '';
+  const body = typeof data['body'] === 'string' ? data['body'] : '';
+
+  const lines: string[] = [
+    `<notification id="${id}" category="${category}" type="${type}" source_kind="${sourceKind}" source_id="${sourceId}">`,
+  ];
+  if (title.length > 0) lines.push(`Title: ${title}`);
+  if (severity.length > 0) lines.push(`Severity: ${severity}`);
+  if (body.length > 0) lines.push(body);
+
+  if (data['source_kind'] === 'background_task') {
+    const tailRaw = typeof data['tail_output'] === 'string' ? data['tail_output'] : '';
+    if (tailRaw.length > 0) {
+      const truncated = truncateTailOutput(tailRaw, 20, 3000);
+      lines.push('<task-notification>');
+      lines.push(truncated);
+      lines.push('</task-notification>');
+    }
+  }
+
+  lines.push('</notification>');
+  return lines.join('\n');
+}
+
+/**
+ * Truncate tail output to at most `maxLines` lines and `maxChars`
+ * characters. Takes the *last* N lines, then trims from the front if
+ * the character budget is exceeded.
+ */
+function truncateTailOutput(raw: string, maxLines: number, maxChars: number): string {
+  const allLines = raw.split('\n');
+  const tailLines = allLines.length > maxLines ? allLines.slice(-maxLines) : allLines;
+  let result = tailLines.join('\n');
+  if (result.length > maxChars) {
+    result = result.slice(-maxChars);
+  }
+  return result;
+}
+
+function stringAttr(value: unknown, fallback: string): string {
+  if (typeof value !== 'string' || value.length === 0) return fallback;
+  // Attribute boundary safety: escape `&` and `"`. Body-text `<` / `>`
+  // stay untouched — the injection target is an LLM-visible transcript
+  // where double-escaping would be noisier than literal punctuation.
+  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
+}
diff --git a/packages/agent-core/src/agent/context/projector.ts b/packages/agent-core/src/agent/context/projector.ts
new file mode 100644
index 000000000..3b5ac10a7
--- /dev/null
+++ b/packages/agent-core/src/agent/context/projector.ts
@@ -0,0 +1,173 @@
+import type { ContentPart, Message, TextPart } from '@moonshot-ai/kosong';
+
+import { renderNotificationXml } from './notification-xml';
+
+type ProjectableMessage = Message & {
+  readonly origin?:
+    | {
+        readonly kind: string;
+        readonly event?: string | undefined;
+        readonly blockedByHook?: string | undefined;
+      }
+    | undefined;
+};
+
+const TRANSCRIPT_ONLY_HOOK_RESULT_EVENTS = new Set(['UserPromptSubmit']);
+
+export interface EphemeralInjection {
+  kind: 'memory_recall' | 'system_reminder' | 'pending_notification';
+  content: string | Record<string, unknown>;
+  position?: 'before_user' | 'after_system';
+}
+
+export function project(
+  history: readonly ProjectableMessage[],
+  ephemeralInjections?: readonly EphemeralInjection[],
+): Message[] {
+  // Keep partial or empty assistant placeholders away from providers.
+  // They can appear when a turn is aborted or errors before any content
+  // or tool call is appended.
+  const usable = history.filter((message) => {
+    if (isBlockedUserPrompt(message)) return false;
+    return (
+      !isTranscriptOnlyHookResult(message) &&
+      message.partial !== true &&
+      !(message.role === 'assistant' && message.content.length === 0 && message.toolCalls.length === 0)
+    );
+  });
+  const merged = mergeAdjacentUserMessages(usable);
+
+  const injectionMessages = ephemeralInjections?.map((injection) => renderInjection(injection));
+
+  // Ephemeral injections sit before the first history message
+  // (before_user) so things like system_reminder land right before the
+  // user turn they contextualise.
+  return injectionMessages ? [...injectionMessages, ...merged] : merged;
+}
+
+function isTranscriptOnlyHookResult(message: ProjectableMessage): boolean {
+  return (
+    message.origin?.kind === 'hook_result' &&
+    TRANSCRIPT_ONLY_HOOK_RESULT_EVENTS.has(message.origin.event ?? '')
+  );
+}
+
+function isBlockedUserPrompt(message: ProjectableMessage): boolean {
+  return message.role === 'user' && message.origin?.blockedByHook === 'UserPromptSubmit';
+}
+
+/**
+ * Render an EphemeralInjection into a synthetic user message. System
+ * reminders and pending notifications use XML wrappers so the model can
+ * distinguish host annotations from genuine user text. `memory_recall`
+ * stays as free text.
+ *
+ * The merge-guard logic downstream (`mergeAdjacentUserMessages`) uses
+ * the `<notification ` / `<system-reminder>` opening tag to detect
+ * these messages, so the exact tag names are load-bearing for
+ * projector correctness — do not rename without also updating
+ * `isInjectionUserMessage` below.
+ */
+function renderInjection(injection: EphemeralInjection): Message {
+  const text = renderInjectionText(injection);
+  return {
+    role: 'user',
+    content: [{ type: 'text', text }],
+    toolCalls: [],
+  };
+}
+
+function renderInjectionText(injection: EphemeralInjection): string {
+  const { kind, content } = injection;
+  if (kind === 'pending_notification') {
+    // Production callers pass notification metadata, but accepting a
+    // string keeps older embedders from crashing on replay/projection.
+    if (typeof content === 'string') {
+      return `<notification>\n${content}\n</notification>`;
+    }
+    return renderNotificationXml(content);
+  }
+  if (kind === 'system_reminder') {
+    const body = typeof content === 'string' ? content : JSON.stringify(content);
+    return `<system-reminder>\n${body}\n</system-reminder>`;
+  }
+  const body = typeof content === 'string' ? content : JSON.stringify(content);
+  return body;
+}
+
+/**
+ * Detect whether a user message was produced by the ephemeral injection
+ * pipeline (system_reminder or notification XML tag). Such messages
+ * must never be merged with an adjacent real user turn — doing so would
+ * smear the injection's XML wrapper into the user's actual prompt and
+ * confuse the LLM about where the system annotation ends.
+ *
+ */
+function isInjectionUserMessage(message: Message): boolean {
+  if (message.role !== 'user') return false;
+  const text = extractTextOnly(message);
+  // Cheap leading-fragment check — injections always have the opening
+  // tag at the start. We use `trimStart()` so leading whitespace
+  // doesn't defeat the check, and require `'<notification '` (with
+  // trailing space) so user text like `<notificationally` or the
+  // bare `<notification>` tag (no attributes) is not misidentified.
+  const trimmed = text.trimStart();
+  if (trimmed.startsWith('<notification ')) return true;
+  if (trimmed.startsWith('<system-reminder>')) return true;
+  if (trimmed.startsWith('<hook_result ')) return true;
+  return false;
+}
+
+function mergeAdjacentUserMessages(history: readonly Message[]): Message[] {
+  const out: Message[] = [];
+  for (const message of history) {
+    const previous = out.at(-1);
+    if (
+      message.role === 'user' &&
+      previous !== undefined &&
+      previous.role === 'user' &&
+      !isInjectionUserMessage(message) &&
+      !isInjectionUserMessage(previous)
+    ) {
+      out[out.length - 1] = mergeTwoUserMessages(previous, message);
+      continue;
+    }
+    // Clone into a fresh Message so we never mutate input arrays.
+    out.push(cloneMessage(message));
+  }
+  return out;
+}
+
+function mergeTwoUserMessages(a: Message, b: Message): Message {
+  const aText = extractTextOnly(a);
+  const bText = extractTextOnly(b);
+  const nonTextParts = [
+    ...a.content.filter((p) => p.type !== 'text'),
+    ...b.content.filter((p) => p.type !== 'text'),
+  ];
+  const mergedText: TextPart = { type: 'text', text: `${aText}\n\n${bText}` };
+  const content: ContentPart[] = [mergedText, ...nonTextParts];
+  return {
+    role: 'user',
+    content,
+    toolCalls: [],
+  };
+}
+
+function extractTextOnly(message: Message): string {
+  return message.content
+    .filter((p): p is TextPart => p.type === 'text')
+    .map((p) => p.text)
+    .join('');
+}
+
+function cloneMessage(message: Message): Message {
+  return {
+    role: message.role,
+    name: message.name,
+    content: message.content.map((p) => ({ ...p })) as ContentPart[],
+    toolCalls: message.toolCalls.map((tc) => ({ ...tc })),
+    toolCallId: message.toolCallId,
+    partial: message.partial,
+  };
+}
diff --git a/packages/agent-core/src/agent/context/types.ts b/packages/agent-core/src/agent/context/types.ts
new file mode 100644
index 000000000..b8d077009
--- /dev/null
+++ b/packages/agent-core/src/agent/context/types.ts
@@ -0,0 +1,78 @@
+import type { ContentPart, Message } from '@moonshot-ai/kosong';
+
+import type { SkillSource } from '../../skill';
+import type { BackgroundTaskStatus } from '../../tools/background';
+
+export interface UserPromptOrigin {
+  readonly kind: 'user';
+  readonly blockedByHook?: string | undefined;
+}
+
+export const USER_PROMPT_ORIGIN: UserPromptOrigin = { kind: 'user' };
+
+export interface SkillActivationOrigin {
+  readonly kind: 'skill_activation';
+  readonly activationId: string;
+  readonly skillName: string;
+  readonly skillArgs?: string | undefined;
+  readonly trigger: 'user-slash' | 'model-tool' | 'nested-skill';
+  readonly skillType?: string | undefined;
+  readonly skillPath?: string | undefined;
+  readonly skillSource?: SkillSource | undefined;
+}
+
+export interface InjectionOrigin {
+  readonly kind: 'injection';
+  readonly variant: string;
+}
+
+export interface CompactionSummaryOrigin {
+  readonly kind: 'compaction_summary';
+}
+
+export interface SystemTriggerOrigin {
+  readonly kind: 'system_trigger';
+  readonly name: string;
+}
+
+export interface BackgroundTaskOrigin {
+  readonly kind: 'background_task';
+  readonly taskId: string;
+  readonly status: BackgroundTaskStatus;
+  readonly notificationId: string;
+}
+
+export interface HookResultOrigin {
+  readonly kind: 'hook_result';
+  readonly event: string;
+  readonly blocked?: boolean;
+}
+
+export type PromptOrigin =
+  | UserPromptOrigin
+  | SkillActivationOrigin
+  | InjectionOrigin
+  | CompactionSummaryOrigin
+  | SystemTriggerOrigin
+  | BackgroundTaskOrigin
+  | HookResultOrigin;
+
+export type ContextMessage = Message & {
+  readonly origin?: PromptOrigin | undefined;
+  readonly isError?: boolean;
+};
+
+export interface UserMessageRecord {
+  content: readonly ContentPart[];
+  origin: PromptOrigin;
+}
+
+export interface SystemReminderRecord {
+  content: string;
+  origin: PromptOrigin;
+}
+
+export interface AgentContextData {
+  history: readonly ContextMessage[];
+  tokenCount: number;
+}
diff --git a/packages/agent-core/src/agent/hooks/engine.ts b/packages/agent-core/src/agent/hooks/engine.ts
new file mode 100644
index 000000000..832ecd620
--- /dev/null
+++ b/packages/agent-core/src/agent/hooks/engine.ts
@@ -0,0 +1,186 @@
+import { runHook } from './runner';
+import type {
+  HookBlockDecision,
+  HookDef,
+  HookEngineOptions,
+  HookEngineTriggerArgs,
+  HookMatcherValue,
+  HookResult,
+} from './types';
+
+const DEFAULT_HOOK_TIMEOUT_SECONDS = 30;
+
+export class HookEngine {
+  private readonly byEvent = new Map<string, HookDef[]>();
+  private readonly pendingTriggers = new Set<Promise<HookResult[]>>();
+
+  constructor(
+    hooks: readonly HookDef[] = [],
+    private readonly options: HookEngineOptions = {},
+  ) {
+    for (const hook of hooks) {
+      const entries = this.byEvent.get(hook.event) ?? [];
+      entries.push(hook);
+      this.byEvent.set(hook.event, entries);
+    }
+  }
+
+  get summary(): Record<string, number> {
+    const result: Record<string, number> = {};
+    for (const [event, hooks] of this.byEvent.entries()) {
+      result[event] = hooks.length;
+    }
+    return result;
+  }
+
+  trigger(event: string, args: HookEngineTriggerArgs = {}): Promise<HookResult[]> {
+    try {
+      return this.triggerInner(event, args).catch((): HookResult[] => []);
+    } catch {
+      return Promise.resolve([]);
+    }
+  }
+
+  async triggerBlock(
+    event: string,
+    args: HookEngineTriggerArgs = {},
+  ): Promise<HookBlockDecision | undefined> {
+    return blockDecision(event, await this.trigger(event, args));
+  }
+
+  fireAndForgetTrigger(
+    event: string,
+    args: HookEngineTriggerArgs = {},
+  ): Promise<HookResult[]> {
+    let promise: Promise<HookResult[]>;
+    try {
+      promise = this.trigger(event, args).catch((): HookResult[] => []);
+    } catch {
+      promise = Promise.resolve([]);
+    }
+    this.pendingTriggers.add(promise);
+    void promise.finally(() => {
+      this.pendingTriggers.delete(promise);
+    });
+    return promise;
+  }
+
+  private async triggerInner(
+    event: string,
+    args: HookEngineTriggerArgs,
+  ): Promise<HookResult[]> {
+    const matcherValue = matcherValueText(args.matcherValue);
+    const inputData = toHookInputData({
+      hookEventName: event,
+      sessionId: this.options.sessionId ?? '',
+      cwd: this.options.cwd ?? '',
+      ...args.inputData,
+    });
+    const matched = this.matchingHooks(event, matcherValue);
+    if (matched.length === 0) return [];
+
+    this.emitTriggered(event, matcherValue, matched.length);
+    const startedAt = Date.now();
+    const results = await Promise.all(
+      matched.map((hook) =>
+        runHook(hook.command, inputData, {
+          timeout: hook.timeout ?? DEFAULT_HOOK_TIMEOUT_SECONDS,
+          cwd: this.options.cwd === '' ? undefined : this.options.cwd,
+          signal: args.signal,
+        }),
+      ),
+    );
+    const { action, reason } = aggregateResults(event, results);
+    this.emitResolved(event, matcherValue, action, reason, Date.now() - startedAt);
+    return results;
+  }
+
+  private matchingHooks(event: string, matcherValue: string): HookDef[] {
+    const seenCommands = new Set<string>();
+    const matched: HookDef[] = [];
+
+    for (const hook of this.byEvent.get(event) ?? []) {
+      if (!matches(hook.matcher ?? '', matcherValue)) continue;
+      if (seenCommands.has(hook.command)) continue;
+      seenCommands.add(hook.command);
+      matched.push(hook);
+    }
+
+    return matched;
+  }
+
+  private emitTriggered(event: string, target: string, count: number): void {
+    try {
+      this.options.onTriggered?.(event, target, count);
+    } catch {}
+  }
+
+  private emitResolved(
+    event: string,
+    target: string,
+    action: string,
+    reason: string | undefined,
+    durationMs: number,
+  ): void {
+    try {
+      this.options.onResolved?.(event, target, action, reason, durationMs);
+    } catch {}
+  }
+}
+
+function matches(pattern: string, value: string): boolean {
+  if (pattern.length === 0) return true;
+  try {
+    return new RegExp(pattern).test(value);
+  } catch {
+    return false;
+  }
+}
+
+function matcherValueText(value: HookMatcherValue | undefined): string {
+  if (value === undefined) return '';
+  if (typeof value === 'string') return value;
+  return value
+    .filter((part) => part.type === 'text')
+    .map((part) => part.text)
+    .join(' ');
+}
+
+function aggregateResults(
+  event: string,
+  results: readonly HookResult[],
+): {
+  readonly action: 'allow' | 'block';
+  readonly reason?: string;
+} {
+  const block = blockDecision(event, results);
+  if (block !== undefined) {
+    return { action: 'block', reason: block.reason };
+  }
+  return { action: 'allow' };
+}
+
+function blockDecision(
+  event: string,
+  results: readonly HookResult[],
+): HookBlockDecision | undefined {
+  const block = results.find((result) => result.action === 'block');
+  if (block === undefined) return undefined;
+  const reason = block.reason?.trim();
+  return {
+    block: true,
+    reason: reason === undefined || reason.length === 0 ? `Blocked by ${event} hook` : reason,
+  };
+}
+
+function toHookInputData(input: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(input)) {
+    result[camelToSnake(key)] = value;
+  }
+  return result;
+}
+
+function camelToSnake(value: string): string {
+  return value.replaceAll(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
diff --git a/packages/agent-core/src/agent/hooks/index.ts b/packages/agent-core/src/agent/hooks/index.ts
new file mode 100644
index 000000000..4330aacc5
--- /dev/null
+++ b/packages/agent-core/src/agent/hooks/index.ts
@@ -0,0 +1,4 @@
+export * from './engine';
+export * from './runner';
+export * from './types';
+export * from './user-prompt';
diff --git a/packages/agent-core/src/agent/hooks/runner.ts b/packages/agent-core/src/agent/hooks/runner.ts
new file mode 100644
index 000000000..4e3c30eda
--- /dev/null
+++ b/packages/agent-core/src/agent/hooks/runner.ts
@@ -0,0 +1,228 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+
+import { z } from 'zod';
+
+import type { HookResult } from './types';
+
+export interface RunHookOptions {
+  readonly timeout: number;
+  readonly cwd?: string;
+  readonly signal?: AbortSignal;
+}
+
+const DEFAULT_TIMEOUT_SECONDS = 30;
+const KILL_GRACE_MS = 100;
+const OptionalStringSchema = z.preprocess(
+  (value) => {
+    if (value === undefined || value === null) return undefined;
+    if (typeof value === 'string') return value;
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+      return String(value);
+    }
+    return undefined;
+  },
+  z.string().optional(),
+);
+const HookSpecificOutputSchema = z.preprocess(
+  (value) => (isRecord(value) ? value : undefined),
+  z
+    .looseObject({
+      message: OptionalStringSchema,
+      permissionDecision: z.unknown().optional(),
+      permissionDecisionReason: OptionalStringSchema,
+    })
+    .optional(),
+);
+const HookJsonOutputSchema = z.looseObject({
+  message: OptionalStringSchema,
+  hookSpecificOutput: HookSpecificOutputSchema,
+});
+
+export async function runHook(
+  command: string,
+  input: Record<string, unknown>,
+  options: RunHookOptions,
+): Promise<HookResult> {
+  let child: ChildProcessWithoutNullStreams;
+  try {
+    child = spawn(command, {
+      shell: true,
+      cwd: options.cwd,
+      stdio: 'pipe',
+      detached: process.platform !== 'win32',
+    });
+  } catch (error) {
+    return allowResult({ stderr: errorMessage(error) });
+  }
+
+  return new Promise<HookResult>((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const timeoutMs = timeoutSeconds(options.timeout) * 1000;
+
+    const cleanup = () => {
+      clearTimeout(timeout);
+      options.signal?.removeEventListener('abort', onAbort);
+    };
+
+    const settle = (result: HookResult): void => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(result);
+    };
+
+    const timeout = setTimeout(() => {
+      killProcess(child);
+      settle(allowResult({ stdout, stderr, timedOut: true }));
+    }, timeoutMs);
+
+    const onAbort = (): void => {
+      killProcess(child);
+      settle(allowResult({ stdout, stderr }));
+    };
+
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    if (options.signal?.aborted === true) {
+      onAbort();
+      return;
+    }
+
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk: string) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk: string) => {
+      stderr += chunk;
+    });
+    child.on('error', (error) => {
+      settle(allowResult({ stdout, stderr: stderr + errorMessage(error) }));
+    });
+    child.on('close', (code) => {
+      settle(resultFromExitCode(code ?? 0, stdout, stderr));
+    });
+
+    child.stdin.on('error', () => {});
+    child.stdin.end(JSON.stringify(input));
+  });
+}
+
+function timeoutSeconds(timeout: number): number {
+  return Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_TIMEOUT_SECONDS;
+}
+
+function resultFromExitCode(exitCode: number, stdout: string, stderr: string): HookResult {
+  if (exitCode === 2) {
+    const message = stderr.trim();
+    return {
+      action: 'block',
+      message,
+      reason: message,
+      stdout,
+      stderr,
+      exitCode,
+    };
+  }
+
+  const structured = exitCode === 0 ? structuredOutput(stdout) : undefined;
+  if (structured?.action === 'block') {
+    return {
+      action: 'block',
+      message: structured.message ?? structured.reason,
+      reason: structured.reason,
+      stdout,
+      stderr,
+      exitCode,
+      structuredOutput: structured.structuredOutput,
+    };
+  }
+
+  return allowResult({
+    message: structured?.message,
+    stdout,
+    stderr,
+    exitCode,
+    structuredOutput: structured?.structuredOutput,
+  });
+}
+
+function structuredOutput(
+  stdout: string,
+): { action?: 'block'; reason?: string; message?: string; structuredOutput: true } | undefined {
+  const text = stdout.trim();
+  if (text.length === 0) return undefined;
+
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    const output = HookJsonOutputSchema.safeParse(parsed);
+    if (!output.success) return undefined;
+
+    const { message, hookSpecificOutput } = output.data;
+    const result = {
+      message: message ?? hookSpecificOutput?.message,
+      structuredOutput: true as const,
+    };
+    if (hookSpecificOutput?.permissionDecision !== 'deny') {
+      return result;
+    }
+    return {
+      action: 'block',
+      message: result.message,
+      reason: hookSpecificOutput.permissionDecisionReason,
+      structuredOutput: true,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function allowResult(input: {
+  readonly message?: string;
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly exitCode?: number;
+  readonly timedOut?: boolean;
+  readonly structuredOutput?: boolean;
+}): HookResult {
+  return {
+    action: 'allow',
+    message: input.message,
+    stdout: input.stdout,
+    stderr: input.stderr,
+    exitCode: input.exitCode,
+    timedOut: input.timedOut,
+    structuredOutput: input.structuredOutput,
+  };
+}
+
+function killProcess(child: ChildProcessWithoutNullStreams): void {
+  tryKillProcess(child, 'SIGTERM');
+  const killTimer = setTimeout(() => {
+    tryKillProcess(child, 'SIGKILL');
+  }, KILL_GRACE_MS);
+  killTimer.unref();
+}
+
+function tryKillProcess(child: ChildProcessWithoutNullStreams, signal: NodeJS.Signals): void {
+  try {
+    if (process.platform !== 'win32' && child.pid !== undefined) {
+      process.kill(-child.pid, signal);
+    } else {
+      child.kill(signal);
+    }
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {}
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
diff --git a/packages/agent-core/src/agent/hooks/types.ts b/packages/agent-core/src/agent/hooks/types.ts
new file mode 100644
index 000000000..f1ee9ce2b
--- /dev/null
+++ b/packages/agent-core/src/agent/hooks/types.ts
@@ -0,0 +1,67 @@
+import type { ContentPart } from '@moonshot-ai/kosong';
+
+export const HOOK_EVENT_TYPES = [
+  'PreToolUse',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'UserPromptSubmit',
+  'Stop',
+  'StopFailure',
+  'SessionStart',
+  'SessionEnd',
+  'SubagentStart',
+  'SubagentStop',
+  'PreCompact',
+  'PostCompact',
+  'Notification',
+] as const;
+
+export type HookEventType = (typeof HOOK_EVENT_TYPES)[number];
+
+export interface HookDef {
+  readonly event: HookEventType;
+  readonly matcher?: string;
+  readonly command: string;
+  readonly timeout?: number;
+}
+
+export interface HookResult {
+  readonly action: 'allow' | 'block';
+  readonly message?: string;
+  readonly reason?: string;
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly exitCode?: number;
+  readonly timedOut?: boolean;
+  readonly structuredOutput?: boolean;
+}
+
+export interface HookBlockDecision {
+  readonly block: true;
+  readonly reason: string;
+}
+
+export type HookMatcherValue = string | readonly ContentPart[];
+
+export interface HookEngineTriggerArgs {
+  readonly matcherValue?: HookMatcherValue;
+  readonly inputData?: Record<string, unknown>;
+  readonly signal?: AbortSignal;
+}
+
+export type HookTriggeredCallback = (event: string, target: string, count: number) => void;
+
+export type HookResolvedCallback = (
+  event: string,
+  target: string,
+  action: string,
+  reason: string | undefined,
+  durationMs: number,
+) => void;
+
+export interface HookEngineOptions {
+  readonly cwd?: string;
+  readonly sessionId?: string;
+  readonly onTriggered?: HookTriggeredCallback;
+  readonly onResolved?: HookResolvedCallback;
+}
diff --git a/packages/agent-core/src/agent/hooks/user-prompt.ts b/packages/agent-core/src/agent/hooks/user-prompt.ts
new file mode 100644
index 000000000..1b81c9f61
--- /dev/null
+++ b/packages/agent-core/src/agent/hooks/user-prompt.ts
@@ -0,0 +1,66 @@
+import type { HookResult } from './types';
+
+export function renderHookResult(event: string, message: string): string {
+  return `<hook_result hook_event="${event}">\n${message}\n</hook_result>`;
+}
+
+export interface RenderedHookResult {
+  readonly event: string;
+  readonly message: string;
+  readonly text: string;
+}
+
+export function renderUserPromptHookResult(
+  results: readonly HookResult[] | undefined,
+): RenderedHookResult | undefined {
+  const messages =
+    results
+      ?.filter((result) => result.action !== 'block')
+      ?.map(userPromptHookMessage)
+      .filter(isNonEmptyString) ??
+    [];
+  if (messages.length === 0) return undefined;
+  const displayMessage = messages.join('\n\n');
+  return {
+    event: 'UserPromptSubmit',
+    message: displayMessage,
+    text: messages.map((message) => renderHookResult('UserPromptSubmit', message)).join('\n'),
+  };
+}
+
+export function renderUserPromptHookBlockResult(
+  results: readonly HookResult[] | undefined,
+): RenderedHookResult | undefined {
+  const block = results?.find((result) => result.action === 'block');
+  if (block === undefined) return undefined;
+  const message = block.message?.trim();
+  if (message !== undefined && message.length > 0) {
+    return {
+      event: 'UserPromptSubmit',
+      message,
+      text: renderHookResult('UserPromptSubmit', message),
+    };
+  }
+  const reason = block.reason?.trim();
+  const result =
+    reason === undefined || reason.length === 0 ? 'Blocked by UserPromptSubmit hook' : reason;
+  return {
+    event: 'UserPromptSubmit',
+    message: result,
+    text: renderHookResult('UserPromptSubmit', result),
+  };
+}
+
+function userPromptHookMessage(result: HookResult): string | undefined {
+  if (result.timedOut === true || (result.exitCode !== undefined && result.exitCode !== 0)) {
+    return undefined;
+  }
+  const message = result.message?.trim();
+  if (message !== undefined && message.length > 0) return message;
+  const stdout = result.stdout?.trim();
+  return stdout === undefined || stdout.length === 0 ? undefined : stdout;
+}
+
+function isNonEmptyString(value: string | undefined): value is string {
+  return value !== undefined && value.length > 0;
+}
diff --git a/packages/agent-core/src/agent/index.ts b/packages/agent-core/src/agent/index.ts
new file mode 100644
index 000000000..d502ae344
--- /dev/null
+++ b/packages/agent-core/src/agent/index.ts
@@ -0,0 +1,518 @@
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+
+import { ErrorCodes, KimiError, makeErrorPayload } from '#/errors';
+import { log } from '#/logging/logger';
+import type { Logger } from '#/logging/types';
+import type { AgentAPI, AgentEvent, SDKAgentRPC, UsageStatus } from '#/rpc';
+import {
+  generate,
+  type ChatProvider,
+  type Message,
+  type Tool,
+} from '@moonshot-ai/kosong';
+
+import type { McpConnectionManager } from '../mcp';
+import {
+  resolveSystemPromptCwd,
+  type PreparedSystemPromptContext,
+  type ResolvedAgentProfile,
+} from '../profile';
+import type { ProviderManager } from '../providers/provider-manager';
+import { withProviderRequestAuth } from '../providers/request-auth';
+import type { RuntimeConfig } from '../runtime-types';
+import type { SessionSubagentHost } from '../session/subagent-host';
+import type { SkillRegistry } from '../skill';
+import { noopTelemetryClient, type TelemetryClient } from '../telemetry';
+import {
+  estimateTokens,
+  estimateTokensForMessages,
+  estimateTokensForTools,
+} from '../utils/tokens';
+import type { PromisableMethods } from '../utils/types';
+import { BackgroundManager } from './background';
+import { FullCompaction, type CompactionStrategy } from './compaction';
+import { ConfigState } from './config';
+import { ContextMemory } from './context';
+import { HookEngine } from './hooks';
+import { InjectionManager } from './injection/manager';
+import { PermissionManager, type PermissionManagerOptions } from './permission';
+import { PlanMode } from './plan';
+import {
+  AgentRecords,
+  FileSystemAgentRecordPersistence,
+  restoreAgentRecord,
+  type AgentRecord,
+  type AgentRecordPersistence,
+} from './records';
+import { ReplayBuilder } from './replay';
+import { SkillManager } from './skill';
+import { ToolManager } from './tool/index';
+import { TurnFlow } from './turn';
+import {
+  GENERATE_REQUEST_LOG_CONTEXT,
+  type GenerateOptionsWithRequestLog,
+} from './turn/kosong-llm';
+import { UsageRecorder } from './usage';
+
+export type { AgentRecord, AgentRecordPersistence } from './records';
+export type { BuiltinTool, ToolInfo, ToolSource, UserToolRegistration } from './tool';
+
+export type AgentType = 'main' | 'sub' | 'independent';
+
+export interface AgentConfig {
+  readonly runtime: RuntimeConfig;
+  readonly homedir?: string;
+  readonly skills?: SkillRegistry;
+  readonly rpc: SDKAgentRPC;
+  readonly persistence?: AgentRecordPersistence;
+  readonly type?: AgentType;
+  readonly generate?: typeof generate;
+  readonly compactionStrategy?: CompactionStrategy;
+  readonly providerManager?: ProviderManager | undefined;
+  readonly sessionId?: string;
+  readonly subagentHost?: SessionSubagentHost | undefined;
+  readonly mcp?: McpConnectionManager;
+  readonly hookEngine?: HookEngine;
+  readonly backgroundMaxRunningTasks?: number;
+  readonly backgroundSessionDir?: string;
+  readonly permission?: PermissionManagerOptions | undefined;
+  readonly onRecord?: ((record: AgentRecord) => void) | undefined;
+  /** Parent logger; the agent appends its own ctx (agentId already bound by session). */
+  readonly log?: Logger;
+  readonly telemetry?: TelemetryClient | undefined;
+}
+
+export class Agent {
+  readonly runtime: RuntimeConfig;
+  readonly homedir?: string;
+  readonly skills?: SkillManager;
+  readonly rawGenerate: typeof generate;
+  readonly rpc: SDKAgentRPC;
+  readonly telemetry: TelemetryClient;
+  readonly providerManager: ProviderManager | undefined;
+  readonly subagentHost: SessionSubagentHost | undefined;
+  readonly mcp: McpConnectionManager | undefined;
+  readonly hooks: HookEngine | undefined;
+
+  readonly type: AgentType;
+  readonly records: AgentRecords;
+  readonly fullCompaction: FullCompaction;
+  readonly context: ContextMemory;
+  readonly config: ConfigState;
+  readonly turn: TurnFlow;
+  readonly injection: InjectionManager;
+  readonly permission: PermissionManager;
+  readonly planMode: PlanMode;
+  readonly usage: UsageRecorder;
+  readonly tools: ToolManager;
+  readonly background: BackgroundManager;
+  readonly replayBuilder: ReplayBuilder;
+  readonly log: Logger;
+
+  private lastLlmConfigLogSignature?: string;
+
+  constructor(config: AgentConfig) {
+    this.log = config.log ?? log;
+    this.runtime = config.runtime;
+    this.homedir = config.homedir;
+    if (config.skills !== undefined) {
+      this.skills = new SkillManager(this, config.skills);
+    }
+    this.rawGenerate = config.generate ?? generate;
+    this.providerManager =
+      config.sessionId === undefined
+        ? config.providerManager
+        : config.providerManager?.withPromptCacheKey(config.sessionId);
+    this.subagentHost = config.subagentHost;
+    this.mcp = config.mcp;
+    this.hooks = config.hookEngine;
+
+    this.type = config.type ?? 'main';
+
+    this.rpc = config.rpc;
+    this.telemetry = config.telemetry ?? noopTelemetryClient;
+    this.records = new AgentRecords(
+      (record) => {
+        restoreAgentRecord(this, record);
+      },
+      config.persistence ??
+        (config.homedir
+          ? new FileSystemAgentRecordPersistence(join(config.homedir, 'wire.jsonl'), {
+              onError: (error) => {
+                this.emitRecordsWriteError(error);
+              },
+            })
+          : undefined),
+    );
+    this.records.onRecord = config.onRecord;
+    this.records.onError = (error, record) => {
+      this.emitRecordsWriteError(error, record);
+    };
+    this.fullCompaction = new FullCompaction(this, config.compactionStrategy);
+    this.context = new ContextMemory(this);
+    this.config = new ConfigState(this);
+    this.turn = new TurnFlow(this);
+    this.injection = new InjectionManager(this);
+    this.permission = new PermissionManager(this, config.permission);
+    this.planMode = new PlanMode(this);
+    this.usage = new UsageRecorder(this);
+    this.tools = new ToolManager(this);
+    this.background = new BackgroundManager(this, {
+      maxRunningTasks: config.backgroundMaxRunningTasks,
+      sessionDir: config.backgroundSessionDir,
+    });
+    this.replayBuilder = new ReplayBuilder(this);
+  }
+
+  get generate(): typeof generate {
+    return async (provider, systemPrompt, tools, history, callbacks, options) => {
+      if (options?.auth !== undefined) {
+        this.logLlmRequest(provider, systemPrompt, tools, history, options);
+        return this.rawGenerate(provider, systemPrompt, tools, history, callbacks, options);
+      }
+      const modelAlias = this.config.modelAlias;
+      const resolveAuth =
+        modelAlias === undefined
+          ? undefined
+          : this.providerManager?.createAuthResolverForModel(modelAlias, {
+              log: this.log,
+            });
+      return withProviderRequestAuth(resolveAuth, (auth) => {
+        const requestOptions = auth === undefined ? options : { ...options, auth };
+        this.logLlmRequest(provider, systemPrompt, tools, history, requestOptions);
+        return this.rawGenerate(provider, systemPrompt, tools, history, callbacks, requestOptions);
+      });
+    };
+  }
+
+  private logLlmRequest(
+    provider: ChatProvider,
+    systemPrompt: string,
+    tools: readonly Tool[],
+    history: readonly Message[],
+    options: Parameters<typeof generate>[5],
+  ): void {
+    const context = buildLlmRequestContext(options);
+    const configMetadata = buildLlmConfigMetadata(
+      provider,
+      this.config.modelAlias,
+      systemPrompt,
+      tools,
+    );
+    this.logLlmConfigIfChanged(
+      context,
+      configMetadata,
+      buildLlmConfigSignature(configMetadata, systemPrompt, tools),
+    );
+    this.log.info('llm request', {
+      ...context,
+      ...buildLlmRequestMetadata(systemPrompt, tools, history),
+    });
+  }
+
+  private logLlmConfigIfChanged(
+    context: LlmRequestContextFields,
+    metadata: LlmConfigMetadata,
+    signature: string,
+  ): void {
+    if (signature === this.lastLlmConfigLogSignature) return;
+    this.lastLlmConfigLogSignature = signature;
+    this.log.info('llm config', {
+      ...context,
+      ...metadata,
+    });
+  }
+
+  useProfile(profile: ResolvedAgentProfile, context?: PreparedSystemPromptContext): void {
+    const cwd = context?.cwd ?? resolveSystemPromptCwd(this.runtime.kaos, this.config.cwd);
+    const systemPrompt = profile.systemPrompt({
+      osEnv: this.runtime.osEnv,
+      cwd,
+      skills: this.skills?.registry,
+      cwdListing: context?.cwdListing,
+      agentsMd: context?.agentsMd,
+    });
+    this.config.update({ profileName: profile.name, systemPrompt });
+    this.tools.setActiveTools(profile.tools);
+  }
+
+  async resume(): Promise<void> {
+    await this.records.replay();
+    await this.background.loadFromDisk();
+    await this.background.reconcile();
+    this.turn.finishResume();
+  }
+
+  get rpcMethods(): PromisableMethods<AgentAPI> {
+    return {
+      prompt: (payload) => {
+        this.turn.prompt(payload.input);
+      },
+      steer: (payload) => {
+        this.telemetry.track('input_steer', { parts: payload.input.length });
+        this.turn.steer(payload.input);
+      },
+      cancel: (payload) => {
+        if (this.turn.hasActiveTurn) {
+          this.telemetry.track('cancel', { from: 'streaming' });
+        }
+        this.turn.cancel(payload.turnId);
+      },
+      setThinking: (payload) => {
+        const wasEnabled = this.config.thinkingLevel !== 'off';
+        this.config.update({ thinkingLevel: payload.level });
+        const enabled = this.config.thinkingLevel !== 'off';
+        if (enabled !== wasEnabled) {
+          this.telemetry.track('thinking_toggle', { enabled });
+        }
+      },
+      setPermission: (payload) => {
+        const wasYolo = this.permission.mode === 'yolo';
+        const wasAuto = this.permission.mode === 'auto';
+        this.permission.setMode(payload.mode);
+        const enabled = this.permission.mode === 'yolo';
+        if (enabled !== wasYolo) {
+          this.telemetry.track('yolo_toggle', { enabled });
+        }
+        const afkEnabled = this.permission.mode === 'auto';
+        if (afkEnabled !== wasAuto) {
+          this.telemetry.track('afk_toggle', { enabled: afkEnabled });
+        }
+      },
+      setModel: async (payload) => {
+        const previous = this.config.modelAlias;
+        const resolved = await this.providerManager?.resolveProviderForModel(payload.model);
+        if (resolved === undefined) {
+          throw new Error('Runtime provider model cannot be empty');
+        }
+        this.config.update({
+          modelAlias: resolved.modelName,
+        });
+        if (previous !== resolved.modelName) {
+          this.telemetry.track('model_switch', { model: resolved.modelName });
+        }
+        return {
+          model: resolved.modelName,
+          providerName: resolved.providerName,
+        };
+      },
+      getModel: () => {
+        return this.config.modelAlias ?? '';
+      },
+      enterPlan: async () => {
+        await this.planMode.enter();
+      },
+      cancelPlan: (payload) => {
+        this.planMode.cancel(payload.id);
+      },
+      clearPlan: () => this.planMode.clear(),
+      beginCompaction: (payload) => {
+        this.fullCompaction.begin({ source: 'manual', instruction: payload.instruction });
+      },
+      cancelCompaction: () => {
+        if (this.fullCompaction.isCompacting) {
+          this.telemetry.track('cancel', { from: 'compacting' });
+        }
+        this.fullCompaction.cancel();
+      },
+      registerTool: (payload) => {
+        this.tools.registerUserTool(payload);
+      },
+      unregisterTool: (payload) => {
+        this.tools.unregisterUserTool(payload.name);
+      },
+      setActiveTools: (payload) => {
+        this.tools.setActiveTools(payload.names);
+      },
+      stopBackground: (payload) => {
+        void this.background.stop(payload.taskId, payload.reason);
+      },
+      clearContext: () => {
+        this.context.clear();
+      },
+      activateSkill: (payload) => {
+        if (this.skills === undefined) {
+          throw new KimiError(ErrorCodes.SKILL_NOT_FOUND, `Skill "${payload.name}" was not found`);
+        }
+        this.skills.activate(payload);
+      },
+      getBackgroundOutput: (payload) => this.background.readOutput(payload.taskId, payload.tail),
+      getBackgroundOutputPath: (payload) => this.background.getOutputPath(payload.taskId),
+      getContext: () => this.context.data(),
+      getConfig: () => this.config.data(),
+      getPermission: () => this.permission.data(),
+      getPlan: () => this.planMode.data(),
+      getUsage: () => this.usage.data(),
+      getTools: () => this.tools.data(),
+      getBackground: (payload) => this.background.list(payload.activeOnly ?? false, payload.limit),
+    };
+  }
+
+  emitEvent(event: AgentEvent): void {
+    if (this.records.restoring) return;
+    void this.rpc.emitEvent(event);
+  }
+
+  emitStatusUpdated(): void {
+    if (this.records.restoring) return;
+    if (!this.config.hasModel) return;
+
+    const contextTokens = this.context.tokenCount;
+    const maxContextTokens = this.config.modelCapabilities.max_context_tokens;
+    const contextUsage =
+      maxContextTokens !== undefined && maxContextTokens > 0
+        ? contextTokens / maxContextTokens
+        : undefined;
+    const usage: UsageStatus | undefined = this.usage.status();
+    const model = this.config.model;
+
+    this.emitEvent({
+      type: 'agent.status.updated',
+      model,
+      contextTokens,
+      maxContextTokens,
+      contextUsage,
+      planMode: this.planMode.isActive,
+      permission: this.permission.mode,
+      usage,
+    });
+  }
+
+  private emitRecordsWriteError(error: unknown, record?: AgentRecord | undefined): void {
+    const message = error instanceof Error ? error.message : String(error);
+    this.log.error('wire record persist failed', {
+      agentHomedir: this.homedir,
+      recordType: record?.type,
+      error,
+    });
+    this.emitEvent({
+      type: 'error',
+      ...makeErrorPayload(
+        ErrorCodes.RECORDS_WRITE_FAILED,
+        `Failed to write agent records: ${message}`,
+        {
+          details: { recordType: record?.type },
+        },
+      ),
+    });
+  }
+}
+
+interface LlmRequestContextFields {
+  turnId?: string;
+  step?: number;
+  attempt?: number;
+  maxAttempts?: number;
+}
+
+interface LlmRequestMetadata {
+  estimatedInputTokens: number;
+  messageCount: number;
+  toolCallCount: number;
+  partialMessageCount?: number;
+}
+
+/**
+ * Fields that identify an LLM configuration for deduplication.
+ * Keep this interface simple and avoid dynamic keys — the shape is
+ * serialized with `JSON.stringify` to produce a stable signature in
+ * `logLlmConfigIfChanged`.
+ */
+interface LlmConfigMetadata {
+  provider: string;
+  model: string;
+  modelAlias?: string;
+  thinkingEffort?: string;
+  systemPromptChars: number;
+  toolCount: number;
+}
+
+function buildLlmRequestContext(options: Parameters<typeof generate>[5]): LlmRequestContextFields {
+  const context = requestLogContext(options);
+  if (context === undefined) return {};
+
+  const fields: LlmRequestContextFields = {
+    turnId: context.turnId,
+    step: context.step,
+  };
+  if (
+    context.attempt !== undefined &&
+    context.maxAttempts !== undefined &&
+    context.attempt > 1
+  ) {
+    fields.attempt = context.attempt;
+    fields.maxAttempts = context.maxAttempts;
+  }
+  return fields;
+}
+
+function buildLlmRequestMetadata(
+  systemPrompt: string,
+  tools: readonly Tool[],
+  history: readonly Message[],
+): LlmRequestMetadata {
+  let toolCallCount = 0;
+  let partialMessageCount = 0;
+
+  for (const message of history) {
+    if (message.partial === true) partialMessageCount += 1;
+    toolCallCount += message.toolCalls.length;
+  }
+
+  const estimatedInputTokens =
+    estimateTokens(systemPrompt) +
+    estimateTokensForMessages([...history]) +
+    estimateTokensForTools(tools);
+
+  const metadata: LlmRequestMetadata = {
+    estimatedInputTokens,
+    messageCount: history.length,
+    toolCallCount,
+  };
+  if (partialMessageCount > 0) {
+    metadata.partialMessageCount = partialMessageCount;
+  }
+  return metadata;
+}
+
+function buildLlmConfigMetadata(
+  provider: ChatProvider,
+  modelAlias: string | undefined,
+  systemPrompt: string,
+  tools: readonly Tool[],
+): LlmConfigMetadata {
+  return {
+    provider: provider.name,
+    model: provider.modelName,
+    modelAlias,
+    thinkingEffort: provider.thinkingEffort ?? undefined,
+    systemPromptChars: systemPrompt.length,
+    toolCount: tools.length,
+  };
+}
+
+function buildLlmConfigSignature(
+  metadata: LlmConfigMetadata,
+  systemPrompt: string,
+  tools: readonly Tool[],
+): string {
+  const toolsForSignature = tools.map(({ name, description, parameters }) => ({
+    name,
+    description,
+    parameters,
+  }));
+  return JSON.stringify({
+    ...metadata,
+    systemPromptHash: fingerprint(systemPrompt),
+    toolsHash: fingerprint(JSON.stringify(toolsForSignature)),
+  });
+}
+
+function fingerprint(content: string): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function requestLogContext(options: Parameters<typeof generate>[5]) {
+  return (options as GenerateOptionsWithRequestLog | undefined)?.[GENERATE_REQUEST_LOG_CONTEXT];
+}
diff --git a/packages/agent-core/src/agent/injection/injector.ts b/packages/agent-core/src/agent/injection/injector.ts
new file mode 100644
index 000000000..1084e32ed
--- /dev/null
+++ b/packages/agent-core/src/agent/injection/injector.ts
@@ -0,0 +1,33 @@
+import type { Agent } from '..';
+
+export abstract class DynamicInjector {
+  protected injectedAt: number | null = null;
+
+  constructor(protected readonly agent: Agent) {}
+
+  onContextClear(): void {
+    this.injectedAt = null;
+  }
+
+  onContextCompacted(compactedCount: number): void {
+    if (this.injectedAt !== null) {
+      const newInjectedAt = this.injectedAt - compactedCount + 1;
+      this.injectedAt = newInjectedAt >= 0 ? newInjectedAt : null;
+    }
+  }
+
+  async inject(): Promise<void> {
+    const injection = await this.getInjection();
+    if (injection) {
+      this.injectedAt = this.agent.context.history.length;
+      this.agent.context.appendSystemReminder(injection, {
+        kind: 'injection',
+        variant: this.injectionVariant,
+      });
+    }
+  }
+
+  protected abstract readonly injectionVariant: string;
+
+  protected abstract getInjection(): string | Promise<string | undefined> | undefined;
+}
diff --git a/packages/agent-core/src/agent/injection/manager.ts b/packages/agent-core/src/agent/injection/manager.ts
new file mode 100644
index 000000000..ffc1fcf01
--- /dev/null
+++ b/packages/agent-core/src/agent/injection/manager.ts
@@ -0,0 +1,34 @@
+import type { Agent } from '..';
+import type { DynamicInjector } from './injector';
+import { PermissionModeInjector } from './permission-mode';
+import { PlanModeInjector } from './plan-mode';
+
+export class InjectionManager {
+  private readonly injectors: DynamicInjector[];
+
+  constructor(protected readonly agent: Agent) {
+    this.injectors = [new PlanModeInjector(agent), new PermissionModeInjector(agent)];
+  }
+
+  async inject(): Promise<void> {
+    for (const injector of this.injectors) {
+      await injector.inject();
+    }
+  }
+
+  onContextClear(): void {
+    for (const injector of this.injectors) {
+      injector.onContextClear();
+    }
+  }
+
+  onContextCompacted(compactedCount: number): void {
+    for (const injector of this.injectors) {
+      try {
+        injector.onContextCompacted(compactedCount);
+      } catch {
+        continue;
+      }
+    }
+  }
+}
diff --git a/packages/agent-core/src/agent/injection/permission-mode.ts b/packages/agent-core/src/agent/injection/permission-mode.ts
new file mode 100644
index 000000000..638ed6760
--- /dev/null
+++ b/packages/agent-core/src/agent/injection/permission-mode.ts
@@ -0,0 +1,30 @@
+import type { PermissionMode } from '../permission';
+import { DynamicInjector } from './injector';
+
+const AUTO_MODE_ENTER_REMINDER = [
+  'Auto permission mode is active. Tool approvals will be handled automatically while this mode remains enabled.',
+  '  - Continue normally without pausing for approval prompts.',
+  '  - Do NOT call AskUserQuestion while auto mode is active. Make a reasonable decision and continue without asking the user.',
+].join('\n');
+
+const AUTO_MODE_EXIT_REMINDER = [
+  'Auto permission mode is no longer active. Tool approvals and permission checks are back to the current mode.',
+  '  - Continue normally, but expect approval prompts or denials when a tool requires them.',
+].join('\n');
+
+export class PermissionModeInjector extends DynamicInjector {
+  protected override readonly injectionVariant = 'permission_mode';
+  private lastMode: PermissionMode | undefined;
+
+  getInjection(): string | undefined {
+    const mode = this.agent.permission.mode;
+    const previousMode = this.lastMode;
+
+    if (mode === previousMode) return undefined;
+
+    this.lastMode = mode;
+    if (mode === 'auto') return AUTO_MODE_ENTER_REMINDER;
+    if (previousMode === 'auto') return AUTO_MODE_EXIT_REMINDER;
+    return undefined;
+  }
+}
diff --git a/packages/agent-core/src/agent/injection/plan-mode.ts b/packages/agent-core/src/agent/injection/plan-mode.ts
new file mode 100644
index 000000000..846d7b582
--- /dev/null
+++ b/packages/agent-core/src/agent/injection/plan-mode.ts
@@ -0,0 +1,181 @@
+import type { PlanFilePath } from '../plan';
+import { DynamicInjector } from './injector';
+
+const PLAN_MODE_DEDUP_MIN_TURNS = 2;
+const PLAN_MODE_FULL_REFRESH_TURNS = 5;
+
+/**
+ * Plan-mode reminder variants.
+ *
+ * `reentry` is used once when a restored planning session already has plan
+ * content. `full` is used for the first reminder and periodic refreshes.
+ * `sparse` keeps the read-only invariant visible between full reminders.
+ */
+export type PlanModeVariant = 'full' | 'sparse' | 'reentry';
+
+export class PlanModeInjector extends DynamicInjector {
+  protected override readonly injectionVariant = 'plan_mode';
+  private wasActive = false;
+
+  override onContextClear(): void {
+    super.onContextClear();
+    this.wasActive = this.agent.planMode.isActive;
+  }
+
+  override async getInjection(): Promise<string | undefined> {
+    const { isActive, planFilePath } = this.agent.planMode;
+    if (!isActive) {
+      if (!this.wasActive) {
+        return undefined;
+      }
+      this.wasActive = false;
+      this.injectedAt = null;
+      return exitReminder();
+    }
+    if (!this.wasActive) {
+      this.injectedAt = null;
+      this.wasActive = true;
+      if (await this.hasCurrentPlanContent()) {
+        return reentryReminder(planFilePath);
+      }
+    }
+    const variant = this.getVariant();
+    if (variant === null) return undefined;
+
+    return variant === 'full'
+      ? fullReminder(planFilePath)
+      : variant === 'sparse'
+        ? sparseReminder(planFilePath)
+        : reentryReminder(planFilePath);
+  }
+
+  protected getVariant(): PlanModeVariant | null {
+    if (this.injectedAt === null) return 'full';
+    const history = this.agent.context.history;
+    let assistantTurnsSince = 0;
+    for (let i = this.injectedAt + 1; i < history.length; i++) {
+      const msg = history[i];
+      if (msg === undefined) continue;
+      if (msg.role === 'assistant') {
+        assistantTurnsSince += 1;
+        continue;
+      }
+      if (msg.role === 'user') {
+        return 'full';
+      }
+    }
+    if (assistantTurnsSince >= PLAN_MODE_FULL_REFRESH_TURNS) return 'full';
+    if (assistantTurnsSince >= PLAN_MODE_DEDUP_MIN_TURNS) return 'sparse';
+    return null;
+  }
+
+  private async hasCurrentPlanContent(): Promise<boolean> {
+    try {
+      const data = await this.agent.planMode.data();
+      return data !== null && data.content.trim().length > 0;
+    } catch {
+      return false;
+    }
+  }
+}
+function withPlanFileFooter(body: string, planFilePath: PlanFilePath): string {
+  if (planFilePath === null || planFilePath.length === 0) return body;
+  return `${body}\n\nPlan file: ${planFilePath}`;
+}
+
+function fullReminder(planFilePath: PlanFilePath): string {
+  if (planFilePath === null || planFilePath.length === 0) {
+    return inlineFullReminder();
+  }
+
+  const body = `Plan mode is active. You MUST NOT make any edits (with the exception of the current plan file) or otherwise make changes to the system unless a tool request is explicitly approved. Prefer read-only tools. Use Bash only when needed; Bash follows the normal permission mode and rules. This supersedes any other instructions you have received.
+
+Workflow:
+  1. Understand — explore the codebase with Glob, Grep, Read.
+  2. Design — converge on the best approach; consider trade-offs but aim for a single recommendation.
+  3. Review — re-read key files to verify understanding.
+  4. Write Plan — modify the plan file with Write or Edit. Use Write if the plan file does not exist yet.
+  5. Exit — call ExitPlanMode for user approval.
+
+## Handling multiple approaches
+Keep it focused: at most 2-3 meaningfully different approaches. Do NOT pad with minor variations — if one approach is clearly superior, just propose that one.
+When the best approach depends on user preferences, constraints, or context you don't have, use AskUserQuestion to clarify first. This helps you write a better, more targeted plan rather than dumping multiple options for the user to sort through.
+When you do include multiple approaches in the plan, you MUST pass them as the \`options\` parameter when calling ExitPlanMode, so the user can select which approach to execute at approval time.
+NEVER write multiple approaches in the plan and call ExitPlanMode without the \`options\` parameter — the user will only see the default approval controls with no way to choose a specific approach.
+
+AskUserQuestion is for clarifying missing requirements or user preferences that affect the plan.
+Never ask about plan approval via text or AskUserQuestion.
+Your turn must end with either AskUserQuestion (to clarify requirements or preferences) or ExitPlanMode (to request plan approval). Do NOT end your turn any other way.
+Do NOT use AskUserQuestion to ask about plan approval or reference "the plan" — the user cannot see the plan until you call ExitPlanMode.`;
+  return withPlanFileFooter(body, planFilePath);
+}
+
+function sparseReminder(planFilePath: PlanFilePath): string {
+  if (planFilePath === null || planFilePath.length === 0) {
+    return inlineSparseReminder();
+  }
+
+  const body = `Plan mode still active (see full instructions earlier). Prefer read-only tools except the current plan file. Use Write or Edit to modify the plan file. If it does not exist yet, create it with Write first. Use Bash only when needed; Bash follows the normal permission mode and rules. Use AskUserQuestion to clarify user preferences when it helps you write a better plan. If the plan has multiple approaches, pass options to ExitPlanMode so the user can choose. End turns with AskUserQuestion (for clarifications) or ExitPlanMode (for approval). Never ask about plan approval via text or AskUserQuestion.`;
+  return withPlanFileFooter(body, planFilePath);
+}
+
+function reentryReminder(planFilePath: PlanFilePath): string {
+  if (planFilePath === null || planFilePath.length === 0) {
+    return inlineReentryReminder();
+  }
+
+  const body = `Plan mode is active. You MUST NOT make any edits (with the exception of the current plan file) or otherwise make changes to the system unless a tool request is explicitly approved. Prefer read-only tools. Use Bash only when needed; Bash follows the normal permission mode and rules. This supersedes any other instructions you have received.
+
+## Re-entering Plan Mode
+A plan file from a previous planning session already exists.
+Before proceeding:
+  1. Read the existing plan file to understand what was previously planned.
+  2. Evaluate the user's current request against that plan.
+  3. If different task: replace the old plan with a fresh one. If same task: update the existing plan.
+  4. You may use Write or Edit to modify the plan file. If the file does not exist yet, create it with Write first.
+  5. Use AskUserQuestion to clarify missing requirements or user preferences that affect the plan.
+  6. Always edit the plan file before calling ExitPlanMode.
+
+Your turn must end with either AskUserQuestion (to clarify requirements) or ExitPlanMode (to request plan approval).`;
+  return withPlanFileFooter(body, planFilePath);
+}
+
+function inlineFullReminder(): string {
+  return `Plan mode is active. You MUST NOT make any edits or otherwise make changes to the system unless a tool request is explicitly approved. Prefer read-only tools. Use Bash only when needed; Bash follows the normal permission mode and rules. This supersedes any other instructions you have received.
+
+Workflow:
+  1. Understand — explore the codebase with Glob, Grep, Read.
+  2. Design — converge on the best approach; consider trade-offs but aim for a single recommendation.
+  3. Review — re-read key files to verify understanding.
+  4. Wait for the host to provide a plan file path, write the plan there, then call ExitPlanMode.
+
+## Handling multiple approaches
+Keep it focused: at most 2-3 meaningfully different approaches. Do NOT pad with minor variations — if one approach is clearly superior, just propose that one.
+When the best approach depends on user preferences, constraints, or context you don't have, use AskUserQuestion to clarify first.
+When you do include multiple approaches in the plan, you MUST pass them as the \`options\` parameter when calling ExitPlanMode, so the user can select which approach to execute at approval time.
+
+AskUserQuestion is for clarifying missing requirements or user preferences that affect the plan.
+Never ask about plan approval via text or AskUserQuestion.
+Your turn must end with either AskUserQuestion (to clarify requirements or preferences) or ExitPlanMode (to request plan approval). Do NOT end your turn any other way.`;
+}
+
+function inlineSparseReminder(): string {
+  return `Plan mode still active (see full instructions earlier). Read-only; no plan file path is available in this host. Wait for the host to provide a plan file path before calling ExitPlanMode. Use AskUserQuestion to clarify user preferences when it helps you write a better plan. If the plan has multiple approaches, pass options to ExitPlanMode so the user can choose. End turns with AskUserQuestion (for clarifications) or ExitPlanMode (for approval).`;
+}
+
+function inlineReentryReminder(): string {
+  return `Plan mode is active. You MUST NOT make any edits or otherwise make changes to the system unless a tool request is explicitly approved. Prefer read-only tools. Use Bash only when needed; Bash follows the normal permission mode and rules. This supersedes any other instructions you have received.
+
+## Re-entering Plan Mode
+No plan file path is available in this host.
+Before proceeding:
+  1. Re-evaluate the user request and any existing conversation context.
+  2. Use AskUserQuestion to clarify missing requirements or user preferences that affect the plan.
+  3. Wait for the host to provide a plan file path, write the revised plan there, then call ExitPlanMode.
+
+Your turn must end with either AskUserQuestion (to clarify requirements) or ExitPlanMode (to request plan approval).`;
+}
+
+function exitReminder(): string {
+  return `Plan mode is no longer active. The read-only and plan-file-only restrictions from plan mode no longer apply. Continue with the approved plan using the normal tool and permission rules.`;
+}
diff --git a/packages/agent-core/src/agent/permission/action-label.ts b/packages/agent-core/src/agent/permission/action-label.ts
new file mode 100644
index 000000000..ad1565de4
--- /dev/null
+++ b/packages/agent-core/src/agent/permission/action-label.ts
@@ -0,0 +1,142 @@
+/**
+ * describeApprovalAction — coarse action label for approve_for_session.
+ *
+ * The label is the key used by `auto_approve_actions` set (session-level
+ * approve-for-session cache). It must be **coarse** enough that the user
+ * pressing "approve for session" on one request also unlocks *semantically
+ * equivalent* future requests — otherwise approve-for-session degrades
+ * into approve-once.
+ *
+ * Derivation priority:
+ *   1. `ApprovalDisplay.kind` mapping (the display already carries the
+ *      semantic classification the UI renders):
+ *        command    → "run command"
+ *        diff       → "edit file"
+ *        file_write → "write file"
+ *        task_stop  → "stop background task"
+ *        generic    → tool-name fallback
+ *   2. Hard-coded toolName → action map for tools that emit `generic`
+ *      display.
+ *   3. Last resort: `call <toolName>`.
+ */
+
+import type { ToolInputDisplay } from '../../tools/display/schemas';
+
+/**
+ * Hard-coded toolName → action label map. Consulted as a fallback so
+ * tools that carry `generic` displays still get a sensible label. Keys
+ * match the tool names currently wired in
+ * `packages/agent-core/src/tools/`.
+ */
+const TOOL_NAME_TO_ACTION: Readonly<Record<string, string>> = {
+  Bash: 'run command',
+  Shell: 'run command',
+  BackgroundRun: 'run background command',
+  BackgroundStop: 'stop background task',
+  Write: 'edit file',
+  Edit: 'edit file',
+  StrReplace: 'edit file',
+};
+
+/** Inverse table — action label → the representative tool-name pattern. */
+const ACTION_TO_PATTERN: Readonly<Record<string, string | null>> = {
+  'run command': 'Bash',
+  'run command in plan mode': null,
+  'run background command': 'BackgroundRun',
+  'stop background task': 'BackgroundStop',
+  'edit file': 'Write',
+  'edit file outside of working directory': 'Write',
+  'write file': 'Write',
+};
+
+export function describeApprovalAction(
+  toolName: string,
+  _args: unknown,
+  display: ToolInputDisplay,
+  override?: string,
+): string {
+  // Highest priority: explicit override from a hook.
+  if (override !== undefined && override.length > 0) {
+    return override;
+  }
+
+  // Display-driven derivation: the display kind already captures the
+  // coarse semantic class the UI renders.
+  switch (display.kind) {
+    case 'command':
+      return 'run command';
+    case 'diff':
+      return 'edit file';
+    case 'file_io':
+      switch (display.operation) {
+        case 'write':
+          return 'write file';
+        case 'edit':
+          return 'edit file';
+        case 'read':
+          return 'read file';
+        case 'glob':
+          return 'list files';
+        case 'grep':
+          return 'search files';
+      }
+      break;
+    case 'task_stop':
+      return 'stop background task';
+    case 'plan_review':
+      return 'review plan';
+    case 'agent_call':
+      return 'spawn agent';
+    case 'skill_call':
+      return 'invoke skill';
+    case 'url_fetch':
+      return 'fetch URL';
+    case 'search':
+      return 'search';
+    case 'todo_list':
+      return 'update todo list';
+    case 'background_task':
+      return 'run background task';
+    case 'generic':
+      // fall through to tool-name map
+      break;
+  }
+
+  const mapped = TOOL_NAME_TO_ACTION[toolName];
+  if (mapped !== undefined) return mapped;
+
+  // MCP tool naming: `mcp__<server>__<tool>` gets a coarse
+  // `"call MCP tool: <server>:<tool>"` label so one approve-for-session
+  // click unlocks every future call to the same server+tool combo. The
+  // server name is preserved to prevent cross-server privilege escalation.
+  if (toolName.startsWith('mcp__')) {
+    const rest = toolName.slice('mcp__'.length);
+    const sep = rest.indexOf('__');
+    if (sep >= 0) {
+      const serverName = rest.slice(0, sep);
+      const innerTool = rest.slice(sep + 2);
+      if (innerTool.length > 0) {
+        return `call MCP tool: ${serverName}:${innerTool}`;
+      }
+    }
+  }
+
+  return `call ${toolName}`;
+}
+
+/**
+ * Inverse mapping from an approve_for_session action label to the
+ * permission-rule pattern that should gate future same-action calls.
+ *
+ * When no entry matches, fall back to the concrete tool name. A `null`
+ * table entry means the action should be cached by action label only,
+ * without creating a broad PermissionRule.
+ */
+export function actionToRulePattern(
+  action: string,
+  fallbackToolName: string,
+): string | undefined {
+  const mapped = ACTION_TO_PATTERN[action];
+  if (mapped !== undefined) return mapped ?? undefined;
+  return fallbackToolName;
+}
diff --git a/packages/agent-core/src/agent/permission/check-rules.ts b/packages/agent-core/src/agent/permission/check-rules.ts
new file mode 100644
index 000000000..484cc11eb
--- /dev/null
+++ b/packages/agent-core/src/agent/permission/check-rules.ts
@@ -0,0 +1,59 @@
+import { isDefaultAutoAllowTool } from '../../tools/policies/default-permissions';
+import { matchesRule } from './matches-rule';
+import type { PermissionPathMatchOptions } from './path-glob-match';
+import type { PermissionMode, PermissionRule, PermissionRuleDecision } from './types';
+
+export interface CheckRulesResult {
+  readonly decision: PermissionRuleDecision;
+  /** Rule that produced `decision`. `undefined` for mode/default auto-allow. */
+  readonly matchedRule?: PermissionRule | undefined;
+}
+
+export function checkMatchingRules(
+  rules: readonly PermissionRule[],
+  toolName: string,
+  toolInput: unknown,
+  mode: PermissionMode,
+  pathOptions?: PermissionPathMatchOptions,
+): CheckRulesResult | undefined {
+  // Priority 1: deny wins in every mode.
+  for (const rule of rules) {
+    if (rule.decision === 'deny' && matchesRule(rule, toolName, toolInput, pathOptions)) {
+      return { decision: 'deny', matchedRule: rule };
+    }
+  }
+
+  const askRule = firstMatchingRule(rules, 'ask', toolName, toolInput, pathOptions);
+  const allowRule = firstMatchingRule(rules, 'allow', toolName, toolInput, pathOptions);
+  if (askRule === undefined && allowRule === undefined) return undefined;
+
+  if (isDefaultAutoAllowTool(toolName)) {
+    return { decision: 'allow' };
+  }
+
+  // Mode overlay: yolo treats everything non-deny as allow.
+  if (mode === 'yolo' || mode === 'auto') {
+    return { decision: 'allow' };
+  }
+
+  // Priority 2: ask before allow so unresolved ambiguity defers to the user.
+  if (askRule !== undefined) return { decision: 'ask', matchedRule: askRule };
+
+  // Priority 3: explicit allow.
+  return { decision: 'allow', matchedRule: allowRule };
+}
+
+function firstMatchingRule(
+  rules: readonly PermissionRule[],
+  decision: PermissionRuleDecision,
+  toolName: string,
+  toolInput: unknown,
+  pathOptions?: PermissionPathMatchOptions,
+): PermissionRule | undefined {
+  for (const rule of rules) {
+    if (rule.decision === decision && matchesRule(rule, toolName, toolInput, pathOptions)) {
+      return rule;
+    }
+  }
+  return undefined;
+}
diff --git a/packages/agent-core/src/agent/permission/index.ts b/packages/agent-core/src/agent/permission/index.ts
new file mode 100644
index 000000000..7628d8405
--- /dev/null
+++ b/packages/agent-core/src/agent/permission/index.ts
@@ -0,0 +1,340 @@
+import type { Agent } from '..';
+import type { PrepareToolExecutionResult, ToolExecutionHookContext } from '../../loop';
+import type { TelemetryPropertyValue } from '../../telemetry';
+import { isDefaultAutoAllowTool } from '../../tools/policies/default-permissions';
+import type { ToolInputDisplay } from '../../tools/display';
+import { actionToRulePattern, describeApprovalAction } from './action-label';
+import { checkMatchingRules, type CheckRulesResult } from './check-rules';
+import type { PermissionPathMatchOptions } from './path-glob-match';
+import { createBuiltinPermissionPolicies } from './policies';
+import type { PermissionPolicy, PermissionPolicyResult } from './policy';
+import type {
+  PermissionApprovalResultRecord,
+  PermissionData,
+  PermissionMode,
+  PermissionRule,
+} from './types';
+export * from './policy';
+export * from './types';
+
+type ApprovalTelemetryMode = 'manual' | 'yolo' | 'afk' | 'auto_session' | 'cancelled';
+
+export interface PermissionManagerOptions {
+  readonly initialRules?: readonly PermissionRule[] | undefined;
+  readonly policies?: readonly PermissionPolicy[] | undefined;
+  readonly parent?: PermissionManager | undefined;
+}
+
+export class PermissionManager {
+  rules: PermissionRule[] = [];
+  private modeOverride: PermissionMode | undefined;
+  private readonly parent: PermissionManager | undefined;
+  private readonly sessionApprovedActions = new Set<string>();
+  private readonly policies: readonly PermissionPolicy[];
+
+  constructor(
+    protected readonly agent: Agent,
+    options: PermissionManagerOptions = {},
+  ) {
+    this.rules = [...(options.initialRules ?? [])];
+    this.parent = options.parent;
+    this.policies = options.policies ?? createBuiltinPermissionPolicies();
+  }
+
+  get mode(): PermissionMode {
+    return this.modeOverride ?? this.parent?.mode ?? 'manual';
+  }
+
+  set mode(mode: PermissionMode) {
+    this.modeOverride = mode;
+  }
+
+  data(): PermissionData {
+    return {
+      mode: this.mode,
+      rules: this.effectiveRules(),
+    };
+  }
+
+  setMode(mode: PermissionMode): void {
+    this.agent.records.logRecord({
+      type: 'permission.set_mode',
+      mode,
+    });
+    this.agent.replayBuilder.push({
+      type: 'permission_updated',
+      mode,
+    });
+    this.modeOverride = mode;
+    this.agent.emitStatusUpdated();
+  }
+
+  recordApprovalResult(record: PermissionApprovalResultRecord): void {
+    this.agent.records.logRecord({
+      type: 'permission.record_approval_result',
+      ...record,
+    });
+    this.agent.replayBuilder.push({
+      type: 'approval_result',
+      record,
+    });
+    if (record.result.decision !== 'approved' || record.result.scope !== 'session') {
+      return;
+    }
+    if (this.sessionApprovedActions.has(record.action)) return;
+
+    const pattern = actionToRulePattern(record.action, record.toolName);
+    this.sessionApprovedActions.add(record.action);
+    if (pattern === undefined) return;
+
+    const rule: PermissionRule = {
+      decision: 'allow',
+      scope: 'session-runtime',
+      pattern,
+      reason: `approve_for_session: ${record.action}`,
+    };
+    if (!this.hasRule(rule)) {
+      this.rules.push(rule);
+    }
+  }
+
+  async beforeToolCall(
+    context: ToolExecutionHookContext,
+  ): Promise<PrepareToolExecutionResult | undefined> {
+    const name = context.toolCall.function.name;
+    const args = context.args;
+
+    const mode = this.mode;
+    const { decision, matchedRule } = this.checkPermission(name, args, mode);
+    if (decision === 'deny') {
+      return {
+        block: true,
+        reason: this.formatMessage(name, matchedRule?.reason),
+      };
+    }
+
+    const policyResult = await this.evaluatePolicies(context, matchedRule);
+    if (policyResult !== undefined) {
+      return this.permissionPolicyResultToPrepare(policyResult, context);
+    }
+
+    if (mode === 'auto') {
+      if (this.wouldAskInManualMode(name, args)) {
+        this.trackToolApproved(name, 'afk');
+      }
+      return undefined;
+    }
+    if (mode === 'yolo') {
+      if (this.wouldAskInManualMode(name, args)) {
+        this.trackToolApproved(name, 'yolo');
+      }
+      return undefined;
+    }
+
+    if (decision === 'allow') {
+      if (matchedRule?.scope === 'session-runtime') {
+        this.trackToolApproved(name, 'auto_session', 'session');
+      }
+      return undefined;
+    }
+
+    // decision === 'ask' → bounce through ApprovalRuntime.
+    return this.requestToolApproval(context);
+  }
+
+  private async requestToolApproval(
+    context: ToolExecutionHookContext,
+    options: {
+      readonly action?: string | undefined;
+      readonly display?: ToolInputDisplay | undefined;
+    } = {},
+  ): Promise<PrepareToolExecutionResult | undefined> {
+    const { signal } = context;
+    const id = context.toolCall.id;
+    const name = context.toolCall.function.name;
+    const args = context.args;
+    const display =
+      options.display ?? ({
+        kind: 'generic',
+        summary: `Approve ${name}`,
+        detail: args,
+      } satisfies ToolInputDisplay);
+    const action = options.action ?? describeApprovalAction(name, args, display);
+    if (this.sessionApprovedActions.has(action)) {
+      this.trackToolApproved(name, 'auto_session', 'session');
+      return undefined;
+    }
+
+    const result = await this.agent.rpc.requestApproval(
+      {
+        turnId: Number(context.turnId),
+        toolCallId: id,
+        toolName: name,
+        action,
+        display,
+      },
+      { signal },
+    );
+    this.recordApprovalResult({
+      turnId: Number(context.turnId),
+      toolCallId: id,
+      toolName: name,
+      action,
+      result,
+    });
+
+    if (result.decision === 'approved') {
+      this.trackToolApproved(
+        name,
+        approvalTelemetryMode(this.mode),
+        result.scope === 'session' ? 'session' : 'once',
+      );
+      return undefined;
+    }
+
+    this.agent.telemetry.track('tool_rejected', {
+      tool_name: name,
+      approval_mode:
+        result.decision === 'cancelled' ? 'cancelled' : approvalTelemetryMode(this.mode),
+      decision: result.decision,
+      has_feedback: result.feedback !== undefined && result.feedback.length > 0,
+    });
+
+    return {
+      block: true,
+      reason: this.formatApprovalRejectionMessage(name, result),
+    };
+  }
+
+  private async evaluatePolicies(
+    context: ToolExecutionHookContext,
+    matchedRule: PermissionRule | undefined,
+  ): Promise<PermissionPolicyResult | undefined> {
+    for (const policy of this.policies) {
+      const result = await policy.evaluate({
+        agent: this.agent,
+        mode: this.mode,
+        toolCallContext: context,
+        matchedRule,
+        recordApprovalResult: (record) => {
+          this.recordApprovalResult(record);
+        },
+      });
+      if (result !== undefined) return result;
+    }
+    return undefined;
+  }
+
+  private checkPermission(
+    toolName: string,
+    toolInput: unknown,
+    mode: PermissionMode = this.mode,
+  ): CheckRulesResult {
+    const matched = this.checkMatchingPermissionRules(toolName, toolInput, mode);
+    if (matched !== undefined) return matched;
+    if (isDefaultAutoAllowTool(toolName)) return { decision: 'allow' };
+    if (mode === 'yolo' || mode === 'auto') return { decision: 'allow' };
+    return { decision: 'ask' };
+  }
+
+  private checkMatchingPermissionRules(
+    toolName: string,
+    toolInput: unknown,
+    mode: PermissionMode,
+  ): CheckRulesResult | undefined {
+    return (
+      checkMatchingRules(this.rules, toolName, toolInput, mode, this.pathMatchOptions()) ??
+      this.parent?.checkMatchingPermissionRules(toolName, toolInput, mode)
+    );
+  }
+
+  private effectiveRules(): PermissionRule[] {
+    return [...this.rules, ...(this.parent?.effectiveRules() ?? [])];
+  }
+
+  private wouldAskInManualMode(toolName: string, toolInput: unknown): boolean {
+    return this.checkPermission(toolName, toolInput, 'manual').decision === 'ask';
+  }
+
+  private permissionPolicyResultToPrepare(
+    result: PermissionPolicyResult,
+    context: ToolExecutionHookContext,
+  ): Promise<PrepareToolExecutionResult | undefined> | PrepareToolExecutionResult | undefined {
+    switch (result.kind) {
+      case 'allow':
+        return result.executionMetadata === undefined
+          ? undefined
+          : { executionMetadata: result.executionMetadata };
+      case 'ask':
+        return this.requestToolApproval(context, result);
+      case 'result':
+        return result.result;
+    }
+  }
+
+  private hasRule(target: PermissionRule): boolean {
+    return this.rules.some((rule) => {
+      return (
+        rule.decision === target.decision &&
+        rule.scope === target.scope &&
+        rule.pattern === target.pattern &&
+        rule.reason === target.reason
+      );
+    });
+  }
+
+  protected formatMessage(toolName: string, reason?: string): string {
+    const suffix = reason !== undefined && reason.length > 0 ? ` Reason: ${reason}` : '';
+    if (this.agent.type === 'sub') {
+      return `Tool "${toolName}" was denied.${suffix} Try a different approach — don't retry the same call, don't attempt to bypass the restriction.`;
+    }
+    return `Tool "${toolName}" was denied by permission rule.${suffix}`;
+  }
+
+  protected formatApprovalRejectionMessage(
+    toolName: string,
+    result: { decision: 'approved' | 'rejected' | 'cancelled'; feedback?: string },
+  ): string {
+    const suffix =
+      result.feedback !== undefined && result.feedback.length > 0
+        ? ` Reason: ${result.feedback}`
+        : '';
+    const prefix =
+      result.decision === 'cancelled'
+        ? `Tool "${toolName}" was not run because the approval request was cancelled.`
+        : `Tool "${toolName}" was not run because the user rejected the approval request.`;
+    if (this.agent.type === 'sub') {
+      return `${prefix}${suffix} Try a different approach — don't retry the same call, don't attempt to bypass the restriction.`;
+    }
+    return `${prefix}${suffix}`;
+  }
+
+  private pathMatchOptions(): PermissionPathMatchOptions {
+    return {
+      cwd: this.agent.config.cwd,
+      pathClass: this.agent.runtime.kaos.pathClass(),
+      homeDir: this.agent.runtime.kaos.gethome(),
+    };
+  }
+
+  private trackToolApproved(
+    toolName: string,
+    approvalMode: Exclude<ApprovalTelemetryMode, 'cancelled'>,
+    scope?: 'once' | 'session',
+  ): void {
+    const properties: Record<string, TelemetryPropertyValue> = {
+      tool_name: toolName,
+      approval_mode: approvalMode,
+    };
+    if (scope !== undefined) {
+      properties['scope'] = scope;
+    }
+    this.agent.telemetry.track('tool_approved', properties);
+  }
+}
+
+function approvalTelemetryMode(
+  mode: PermissionMode,
+): Extract<ApprovalTelemetryMode, 'manual' | 'yolo' | 'afk'> {
+  return mode === 'auto' ? 'afk' : mode;
+}
diff --git a/packages/agent-core/src/agent/permission/matches-rule.ts b/packages/agent-core/src/agent/permission/matches-rule.ts
new file mode 100644
index 000000000..546567b7c
--- /dev/null
+++ b/packages/agent-core/src/agent/permission/matches-rule.ts
@@ -0,0 +1,125 @@
+/**
+ * matchesRule — pure function that decides whether a PermissionRule
+ * applies to a given tool call.
+ *
+ * Contract:
+ *   - No side effects, no `this`, no IO, no exceptions.
+ *   - Deterministic: same `(rule, toolName, args)` → same result.
+ *   - Returns boolean only; decision semantics (deny/ask/allow) are a
+ *     caller concern (see `check-rules.ts`).
+ */
+
+import picomatch from 'picomatch';
+
+import { parsePattern } from './parse-pattern';
+import { globMatch, pathGlobMatch, type PermissionPathMatchOptions } from './path-glob-match';
+import type { PermissionRule } from './types';
+
+type ArgFieldKind = 'generic' | 'path';
+
+interface ArgField {
+  readonly value: string;
+  readonly kind: ArgFieldKind;
+}
+
+/**
+ * Tool-specific argument field convention. When a rule uses an arg
+ * pattern (`Read(./src/**)`), we extract the listed field from the tool
+ * call args and match the glob against its value.
+ *
+ * Unknown tools fall back to `undefined`, which means "arg pattern
+ * cannot match" — rules with an arg pattern on an unknown tool will
+ * never fire. Rules without an arg pattern (`UnknownTool`) still match
+ * on name alone.
+ */
+function extractArgField(toolName: string, args: unknown): ArgField | undefined {
+  if (args === null || typeof args !== 'object') return undefined;
+  const rec = args as Record<string, unknown>;
+
+  switch (toolName) {
+    case 'Bash':
+    case 'Shell':
+    case 'Background':
+      return typeof rec['command'] === 'string'
+        ? { value: rec['command'], kind: 'generic' }
+        : undefined;
+    case 'Read':
+    case 'Write':
+    case 'Edit':
+    case 'ReadMediaFile':
+      return typeof rec['path'] === 'string' ? { value: rec['path'], kind: 'path' } : undefined;
+    case 'Grep':
+    case 'Glob':
+      return typeof rec['pattern'] === 'string'
+        ? { value: rec['pattern'], kind: 'generic' }
+        : undefined;
+    case 'Task':
+    case 'Agent':
+      return typeof rec['subagent_type'] === 'string'
+        ? { value: rec['subagent_type'], kind: 'generic' }
+        : undefined;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Decide whether a single rule matches a specific tool call.
+ *
+ * Algorithm:
+ *   1. Parse `rule.pattern` into `{toolName, argPattern?}`.
+ *   2. If parsed toolName is `*`, skip name check; otherwise compare with
+ *      glob semantics so `mcp__github__*` matches `mcp__github__list`.
+ *   3. If the rule has no argPattern, name match → rule fires.
+ *   4. Otherwise extract the tool-specific field value and match against
+ *      the glob. Handle the leading `!` negation prefix by flipping the
+ *      final boolean.
+ */
+export function matchesRule(
+  rule: PermissionRule,
+  toolName: string,
+  args: unknown,
+  pathOptions?: PermissionPathMatchOptions,
+): boolean {
+  let parsed;
+  try {
+    parsed = parsePattern(rule.pattern);
+  } catch {
+    // Malformed patterns never match. The loader is responsible for
+    // surfacing DSL errors at load time; matcher stays total.
+    return false;
+  }
+
+  // 1. Tool-name match (support `*` wildcard + glob-style tool names)
+  const nameGlob = parsed.toolName;
+  if (nameGlob !== '*' && !picomatch.isMatch(toolName, nameGlob)) return false;
+
+  // 2. No arg pattern → name match is enough
+  if (parsed.argPattern === undefined) return true;
+
+  // 3. Arg pattern — resolve negation and glob-match the field
+  const rawPattern = parsed.argPattern;
+  const negated = rawPattern.startsWith('!');
+  const positivePattern = negated ? rawPattern.slice(1) : rawPattern;
+
+  const fieldValue = extractArgField(toolName, args);
+  if (fieldValue === undefined) {
+    // No extractable field → positive pattern cannot match; negation
+    // semantics here mean "the field is not in the disallowed set",
+    // which by missing-field convention we treat as a non-match to
+    // avoid accidentally firing deny rules on malformed args.
+    return false;
+  }
+
+  // If the field is a path, use `pathGlobMatch` which handles normalization.
+  const hit =
+    fieldValue.kind === 'path'
+      ? pathGlobMatch(fieldValue.value, positivePattern, {
+          pathOptions,
+          conservativeCaseFold: rule.decision === 'deny' && !negated,
+        })
+      : globMatch(fieldValue.value, positivePattern);
+  return negated ? !hit : hit;
+}
+
+export type { PermissionPathMatchOptions } from './path-glob-match';
diff --git a/packages/agent-core/src/agent/permission/parse-pattern.ts b/packages/agent-core/src/agent/permission/parse-pattern.ts
new file mode 100644
index 000000000..9b76ebd28
--- /dev/null
+++ b/packages/agent-core/src/agent/permission/parse-pattern.ts
@@ -0,0 +1,50 @@
+/**
+ * DSL parser for PermissionRule `pattern` strings.
+ *
+ * Grammar:
+ *   pattern    := toolName ( "(" argPattern ")" )?
+ *   toolName   := identifier characters (e.g. `Bash`, `mcp__github__*`)
+ *   argPattern := any string (may start with `!` for negation)
+ *
+ * Examples:
+ *   "Write"            → { toolName: "Write" }
+ *   "Read(/etc/**)"    → { toolName: "Read", argPattern: "/etc/**" }
+ *   "Bash(!rm *)"      → { toolName: "Bash", argPattern: "!rm *" }
+ *   "mcp__github__*"   → { toolName: "mcp__github__*" }
+ */
+
+export interface ParsedPattern {
+  readonly toolName: string;
+  readonly argPattern?: string | undefined;
+}
+
+/**
+ * Parse a DSL pattern. Throws on malformed input (missing closing paren,
+ * empty tool name). The parser is the single source of truth for DSL
+ * syntax and is exercised by table-driven tests.
+ */
+export function parsePattern(pattern: string): ParsedPattern {
+  const trimmed = pattern.trim();
+  if (trimmed.length === 0) {
+    throw new Error('permission pattern: empty string');
+  }
+
+  const openIdx = trimmed.indexOf('(');
+  if (openIdx === -1) {
+    return { toolName: trimmed };
+  }
+
+  if (!trimmed.endsWith(')')) {
+    throw new Error(`permission pattern: missing closing paren in "${pattern}"`);
+  }
+
+  const toolName = trimmed.slice(0, openIdx);
+  const argPattern = trimmed.slice(openIdx + 1, -1);
+  if (toolName.length === 0) {
+    throw new Error(`permission pattern: empty tool name in "${pattern}"`);
+  }
+  // Empty arg pattern (`Read()`) is treated as "toolName only" — it
+  // matches every call to that tool. This aligns with the intuition
+  // that writing `Read()` is an odd but non-fatal way of saying `Read`.
+  return { toolName, argPattern: argPattern.length > 0 ? argPattern : undefined };
+}
diff --git a/packages/agent-core/src/agent/permission/path-glob-match.ts b/packages/agent-core/src/agent/permission/path-glob-match.ts
new file mode 100644
index 000000000..5cecc179e
--- /dev/null
+++ b/packages/agent-core/src/agent/permission/path-glob-match.ts
@@ -0,0 +1,156 @@
+import * as posixPath from 'node:path/posix';
+import * as win32Path from 'node:path/win32';
+
+import picomatch from 'picomatch';
+
+import { canonicalizePath, type PathClass } from '../../tools/policies/path-access';
+
+export interface PermissionPathMatchOptions {
+  readonly cwd?: string;
+  readonly pathClass?: PathClass;
+  readonly homeDir?: string;
+  readonly caseInsensitivePaths?: boolean;
+}
+
+interface PathMatchSemantics {
+  readonly pathClass: PathClass;
+  readonly path: typeof posixPath;
+}
+
+/**
+ * Match ordinary string fields, like command text or search patterns.
+ * `*` and `**` work as wildcards, but the value is not treated as a file path.
+ */
+export function globMatch(value: string, pattern: string, options?: { nocase?: boolean }): boolean {
+  if (picomatch.isMatch(value, pattern, options)) return true;
+
+  const normalizedValue = stripLeadingDotSlash(value);
+  const normalizedPattern = stripLeadingDotSlash(pattern);
+  if (normalizedValue === value && normalizedPattern === pattern) return false;
+  return picomatch.isMatch(normalizedValue, normalizedPattern, options);
+}
+
+function stripLeadingDotSlash(value: string): string {
+  return value.startsWith('./') ? value.slice(2) : value;
+}
+
+/**
+ * Match file path fields, like Read/Write/Edit `path`.
+ * Also compares normalized forms, so `./a`, `dir/../a`, and Windows
+ * separator or case variants can match the same rule.
+ */
+export function pathGlobMatch(
+  value: string,
+  pattern: string,
+  options: {
+    readonly pathOptions?: PermissionPathMatchOptions;
+    readonly conservativeCaseFold: boolean;
+  },
+): boolean {
+  const semantics = pathMatchSemantics(value, pattern, options.pathOptions);
+  const nocase =
+    options.pathOptions?.caseInsensitivePaths ??
+    (semantics.pathClass === 'win32' || options.conservativeCaseFold);
+
+  if (globMatch(value, pattern, { nocase })) return true;
+
+  for (const valueVariant of pathVariants(value, semantics, options.pathOptions)) {
+    for (const patternVariant of pathVariants(pattern, semantics, options.pathOptions)) {
+      if (globMatch(valueVariant, patternVariant, { nocase })) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Build equivalent spellings for one path string before glob matching:
+ * the original text, a leading `./` or `.\` form without that prefix,
+ * the canonical absolute path when possible, and slash-form Windows paths.
+ *
+ * Example: with cwd `/repo`, `./src/../secret.txt` adds both
+ * `src/../secret.txt` and `/repo/secret.txt`. On Windows,
+ * `C:\repo\secret.txt` also adds `C:/repo/secret.txt`.
+ */
+function pathVariants(
+  value: string,
+  semantics: PathMatchSemantics,
+  pathOptions: PermissionPathMatchOptions | undefined,
+): string[] {
+  const variants = new Set<string>();
+  addPathVariant(variants, value, semantics.pathClass);
+  addPathVariant(variants, stripLeadingDotPath(value, semantics.pathClass), semantics.pathClass);
+
+  const canonical = canonicalizePathPattern(value, semantics, pathOptions);
+  if (canonical !== undefined) addPathVariant(variants, canonical, semantics.pathClass);
+  return Array.from(variants);
+}
+
+function canonicalizePathPattern(
+  value: string,
+  semantics: PathMatchSemantics,
+  pathOptions: PermissionPathMatchOptions | undefined,
+): string | undefined {
+  const expanded = expandUserPath(value, semantics, pathOptions?.homeDir);
+  const cwd = pathOptions?.cwd ?? defaultCwdForPath(expanded, semantics);
+  if (cwd === undefined) return undefined;
+  try {
+    return canonicalizePath(expanded, cwd, semantics.pathClass);
+  } catch {
+    return undefined;
+  }
+}
+
+function expandUserPath(
+  value: string,
+  semantics: PathMatchSemantics,
+  homeDir: string | undefined,
+): string {
+  if (homeDir === undefined) return value;
+  if (value === '~') return homeDir;
+  if (value.startsWith('~/') || (semantics.pathClass === 'win32' && value.startsWith('~\\'))) {
+    return semantics.path.join(homeDir, value.slice(2));
+  }
+  return value;
+}
+
+function defaultCwdForPath(value: string, semantics: PathMatchSemantics): string | undefined {
+  if (!semantics.path.isAbsolute(value)) return undefined;
+  return semantics.path.parse(value).root;
+}
+
+function pathMatchSemantics(
+  value: string,
+  pattern: string,
+  pathOptions: PermissionPathMatchOptions | undefined,
+): PathMatchSemantics {
+  // Production callers pass the active Kaos path class. The fallback keeps
+  // the pure matcher useful for tests and direct helper calls.
+  const pathClass =
+    pathOptions?.pathClass ??
+    ([value, pattern].some((candidate) => {
+      return (
+        /^[A-Za-z]:(?:[\\/]|$)/.test(candidate) ||
+        candidate.startsWith('\\\\') ||
+        candidate.includes('\\')
+      );
+    })
+      ? 'win32'
+      : 'posix');
+  return {
+    pathClass,
+    path: pathClass === 'win32' ? win32Path : posixPath,
+  };
+}
+
+function addPathVariant(variants: Set<string>, value: string, pathClass: PathClass): void {
+  variants.add(value);
+  // Picomatch treats backslashes as escape syntax in some cases; add a
+  // slash-separated Win32 variant so nocase and globs behave predictably.
+  if (pathClass === 'win32') variants.add(value.replaceAll('\\', '/'));
+}
+
+function stripLeadingDotPath(value: string, pathClass: PathClass): string {
+  if (value.startsWith('./')) return value.slice(2);
+  if (pathClass === 'win32' && value.startsWith('.\\')) return value.slice(2);
+  return value;
+}
diff --git a/packages/agent-core/src/agent/permission/policies/ask-user-question.ts b/packages/agent-core/src/agent/permission/policies/ask-user-question.ts
new file mode 100644
index 000000000..a2edcc461
--- /dev/null
+++ b/packages/agent-core/src/agent/permission/policies/ask-user-question.ts
@@ -0,0 +1,17 @@
+import type { PermissionPolicy } from '../policy';
+
+export const AskUserQuestionAutoPermissionPolicy: PermissionPolicy = {
+  name: 'auto.ask-user-question',
+  evaluate({ mode, toolCallContext }) {
+    if (mode !== 'auto') return undefined;
+    if (toolCallContext.toolCall.function.name !== 'AskUserQuestion') return undefined;
+    return {
+      kind: 'result',
+      result: {
+        block: true,
+        reason:
+          'AskUserQuestion is disabled while auto permission mode is active. Make a reasonable decision and continue without asking the user.',
+      },
+    };
+  },
+};
diff --git a/packages/agent-core/src/agent/permission/policies/default-git-cwd-write.ts b/packages/agent-core/src/agent/permission/policies/default-git-cwd-write.ts
new file mode 100644
index 000000000..656f2089b
--- /dev/null
+++ b/packages/agent-core/src/agent/permission/policies/default-git-cwd-write.ts
@@ -0,0 +1,127 @@
+import * as posixPath from 'node:path/posix';
+
+import type { Kaos } from '@moonshot-ai/kaos';
+
+import {
+  DEFAULT_WORKSPACE_ACCESS_POLICY,
+  isWithinDirectory,
+  resolvePathAccess,
+} from '../../../tools/policies/path-access';
+import { isSensitiveFile } from '../../../tools/policies/sensitive';
+import {
+  findGitWorkTreeMarker,
+  type GitWorkTreeMarker,
+} from '../../../tools/support/git-worktree';
+import type { PermissionPolicy } from '../policy';
+
+const AUTO_REASON = 'default_git_cwd_write';
+const S_IFMT = 0o170000;
+const S_IFLNK = 0o120000;
+
+export function createDefaultGitCwdWritePolicy(): PermissionPolicy {
+  // Cache positive marker lookups only. A session that starts in a non-git
+  // directory and later `git init`s should pick up the new work tree on the
+  // next call; negative results pay one extra stat per call, which is
+  // acceptable.
+  const cache = new Map<string, GitWorkTreeMarker>();
+
+  return {
+    name: 'default.git-cwd-write',
+    async evaluate({ agent, mode, matchedRule, toolCallContext }) {
+      if (mode !== 'manual') return undefined;
+      if (matchedRule !== undefined) return undefined;
+
+      const toolName = toolCallContext.toolCall.function.name;
+      if (toolName !== 'Write' && toolName !== 'Edit') return undefined;
+
+      const kaos = agent.runtime.kaos;
+      const pathClass = kaos.pathClass();
+      if (pathClass !== 'posix') return undefined;
+
+      const cwd = agent.config.cwd;
+      if (cwd.length === 0) return undefined;
+
+      const path = readStringField(toolCallContext.args, 'path');
+      if (path === undefined) return undefined;
+
+      let access;
+      try {
+        access = resolvePathAccess(
+          path,
+          cwd,
+          { workspaceDir: cwd, additionalDirs: [] },
+          {
+            operation: 'write',
+            pathClass,
+            homeDir: kaos.gethome(),
+            policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+          },
+        );
+      } catch {
+        return undefined;
+      }
+      if (access.outsideWorkspace) return undefined;
+
+      const marker = cache.get(cwd) ?? (await findGitWorkTreeMarker(kaos, cwd));
+      if (marker === null) return undefined;
+      cache.set(cwd, marker);
+
+      if (isGitControlPath(access.path, cwd, marker)) return undefined;
+      if (isSensitiveFile(access.path.toLowerCase(), 'posix')) return undefined;
+      if (await hasSymlinkInPath(kaos, cwd, access.path)) return undefined;
+
+      agent.telemetry.track('tool_approved', {
+        tool_name: toolName,
+        approval_mode: 'manual',
+        auto_reason: AUTO_REASON,
+      });
+      return { kind: 'allow' };
+    },
+  };
+}
+
+function readStringField(args: unknown, key: string): string | undefined {
+  if (args === null || typeof args !== 'object') return undefined;
+  const value = (args as Record<string, unknown>)[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+function isGitControlPath(targetPath: string, cwd: string, marker: GitWorkTreeMarker): boolean {
+  const foldedTarget = targetPath.toLowerCase();
+  return (
+    posixPath.relative(cwd.toLowerCase(), foldedTarget).split(posixPath.sep).includes('.git') ||
+    isWithinDirectory(foldedTarget, marker.dotGitPath.toLowerCase(), 'posix') ||
+    isWithinDirectory(foldedTarget, marker.controlDirPath.toLowerCase(), 'posix')
+  );
+}
+
+async function hasSymlinkInPath(kaos: Kaos, cwd: string, targetPath: string): Promise<boolean> {
+  const relative = posixPath.relative(cwd, targetPath);
+  const parts = [cwd];
+
+  let current = cwd;
+  for (const part of relative.split(posixPath.sep)) {
+    if (part.length === 0 || part === '.') continue;
+    current = posixPath.join(current, part);
+    parts.push(current);
+  }
+
+  for (let index = 0; index < parts.length; index += 1) {
+    try {
+      const stat = await kaos.stat(parts[index]!, { followSymlinks: false });
+      if ((stat.stMode & S_IFMT) === S_IFLNK) return true;
+    } catch (error) {
+      return !(index === parts.length - 1 && isFileNotFoundError(error));
+    }
+  }
+  return false;
+}
+
+function isFileNotFoundError(error: unknown): boolean {
+  if (error === null || typeof error !== 'object') return false;
+  if ((error as { name?: unknown }).name === 'KaosFileNotFoundError') return true;
+  const code = (error as { code?: unknown }).code;
+  if (code === 'ENOENT' || code === 'ENOTDIR' || code === 2) return true;
+  const message = error instanceof Error ? error.message : '';
+  return message.includes('ENOENT') || message.includes('ENOTDIR');
+}
diff --git a/packages/agent-core/src/agent/permission/policies/index.ts b/packages/agent-core/src/agent/permission/policies/index.ts
new file mode 100644
index 000000000..07459feb2
--- /dev/null
+++ b/packages/agent-core/src/agent/permission/policies/index.ts
@@ -0,0 +1,19 @@
+import type { PermissionPolicy } from '../policy';
+import { AskUserQuestionAutoPermissionPolicy } from './ask-user-question';
+import { createDefaultGitCwdWritePolicy } from './default-git-cwd-write';
+import { createPlanPermissionPolicies } from './plan';
+import { YoloOutsideWorkspacePermissionPolicy } from './yolo-workspace-access';
+
+export function createBuiltinPermissionPolicies(): readonly PermissionPolicy[] {
+  return [
+    ...createPlanPermissionPolicies(),
+    YoloOutsideWorkspacePermissionPolicy,
+    createDefaultGitCwdWritePolicy(),
+    AskUserQuestionAutoPermissionPolicy,
+  ];
+}
+
+export { AskUserQuestionAutoPermissionPolicy } from './ask-user-question';
+export { createDefaultGitCwdWritePolicy } from './default-git-cwd-write';
+export { createPlanPermissionPolicies } from './plan';
+export { YoloOutsideWorkspacePermissionPolicy } from './yolo-workspace-access';
diff --git a/packages/agent-core/src/agent/permission/policies/plan.ts b/packages/agent-core/src/agent/permission/policies/plan.ts
new file mode 100644
index 000000000..774799227
--- /dev/null
+++ b/packages/agent-core/src/agent/permission/policies/plan.ts
@@ -0,0 +1,324 @@
+import type { ExecutableToolResult } from '../../../loop';
+import type { PermissionPolicy, PermissionPolicyContext, PermissionPolicyResult } from '../policy';
+import type { ApprovalResponse } from '../types';
+
+interface ExitPlanModeOption {
+  readonly label: string;
+  readonly description: string;
+}
+
+interface ExitPlanModeExecutionMetadata {
+  readonly selectedOption?: ExitPlanModeOption | undefined;
+  readonly planTelemetrySubmitted: true;
+  readonly planTelemetryResolved: true;
+}
+
+export const EnterPlanModePermissionPolicy: PermissionPolicy = {
+  name: 'plan.enter-plan-mode',
+  evaluate({ toolCallContext }) {
+    if (toolCallContext.toolCall.function.name !== 'EnterPlanMode') return undefined;
+    return { kind: 'allow' };
+  },
+};
+
+export const ExitPlanModePermissionPolicy: PermissionPolicy = {
+  name: 'plan.exit-plan-mode',
+  async evaluate(context) {
+    if (context.toolCallContext.toolCall.function.name !== 'ExitPlanMode') return undefined;
+    if (context.mode === 'auto') return { kind: 'allow' };
+
+    const review = await resolveExitPlanModeReview(context);
+    if (review === null) return { kind: 'allow' };
+
+    const action = exitPlanModeAction(review.options);
+    context.agent.telemetry.track('plan_submitted', {
+      has_options: review.options !== undefined,
+    });
+    let result: ApprovalResponse;
+    try {
+      result = await context.agent.rpc.requestApproval(
+        {
+          turnId: Number(context.toolCallContext.turnId),
+          toolCallId: context.toolCallContext.toolCall.id,
+          toolName: 'ExitPlanMode',
+          action,
+          display: {
+            kind: 'plan_review',
+            plan: review.plan,
+            path: review.path,
+            options: review.options,
+          },
+        },
+        { signal: context.toolCallContext.signal },
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Plan approval failed.';
+      return {
+        kind: 'result',
+        result: {
+          syntheticResult: {
+            isError: true,
+            output: `Plan approval failed: ${message}`,
+          },
+        },
+      };
+    }
+
+    context.recordApprovalResult({
+      turnId: Number(context.toolCallContext.turnId),
+      toolCallId: context.toolCallContext.toolCall.id,
+      toolName: 'ExitPlanMode',
+      action,
+      result,
+    });
+
+    trackExitPlanModeResolution(context, result);
+    return exitPlanModeApprovalResult(context, result, review.options);
+  },
+};
+
+export const PlanModeGuardPermissionPolicy: PermissionPolicy = {
+  name: 'plan.mode-guard',
+  evaluate({ agent, toolCallContext }) {
+    if (!agent.planMode.isActive) return undefined;
+
+    const name = toolCallContext.toolCall.function.name;
+    const args = toolCallContext.args;
+
+    if (name === 'Write' || name === 'Edit') {
+      const path = readStringField(args, 'path');
+      if (path === undefined) return undefined;
+      const planFilePath = agent.planMode.planFilePath;
+      if (planFilePath !== null && path === planFilePath) return { kind: 'allow' };
+      return {
+        kind: 'result',
+        result: {
+          block: true,
+          reason:
+            `Plan mode is active. You may only write to the current plan file: ${planFilePath ?? '(no plan file selected yet)'}. ` +
+            'Call ExitPlanMode to exit plan mode before editing other files.',
+        },
+      };
+    }
+
+    if (name === 'TaskStop') {
+      return {
+        kind: 'result',
+        result: {
+          block: true,
+          reason:
+            'TaskStop is not available in plan mode. ' +
+            'Call ExitPlanMode to exit plan mode before stopping a background task.',
+        },
+      };
+    }
+
+    return undefined;
+  },
+};
+
+export function createPlanPermissionPolicies(): readonly PermissionPolicy[] {
+  return [
+    EnterPlanModePermissionPolicy,
+    ExitPlanModePermissionPolicy,
+    PlanModeGuardPermissionPolicy,
+  ];
+}
+
+async function resolveExitPlanModeReview(context: PermissionPolicyContext): Promise<{
+  readonly plan: string;
+  readonly path?: string | undefined;
+  readonly options?: readonly ExitPlanModeOption[] | undefined;
+} | null> {
+  if (!context.agent.planMode.isActive) return null;
+
+  let data: Awaited<ReturnType<PermissionPolicyContext['agent']['planMode']['data']>>;
+  try {
+    data = await context.agent.planMode.data();
+  } catch {
+    return null;
+  }
+  if (data === null || data.content.trim().length === 0) return null;
+
+  return {
+    plan: data.content,
+    path: data.path,
+    options: exitPlanModeOptions(context.toolCallContext.args),
+  };
+}
+
+function exitPlanModeApprovalResult(
+  context: PermissionPolicyContext,
+  result: ApprovalResponse,
+  options: readonly ExitPlanModeOption[] | undefined,
+): PermissionPolicyResult {
+  if (result.decision === 'approved') {
+    const selected = selectedExitPlanModeOption(options, result.selectedLabel);
+    return {
+      kind: 'allow',
+      executionMetadata: exitPlanModeExecutionMetadata(selected),
+    };
+  }
+
+  if (result.decision === 'cancelled') {
+    return {
+      kind: 'result',
+      result: {
+        syntheticResult: {
+          isError: false,
+          output: 'Plan approval dismissed. Plan mode remains active.',
+        },
+      },
+    };
+  }
+
+  if (result.selectedLabel === 'Reject and Exit') {
+    const failed = exitPlanModeForRejectedPlan(context);
+    return {
+      kind: 'result',
+      result: {
+        syntheticResult:
+          failed ?? {
+            isError: true,
+            stopTurn: true,
+            output: 'Plan rejected by user. Plan mode deactivated.',
+          },
+      },
+    };
+  }
+
+  const feedback = result.feedback ?? '';
+  if (result.selectedLabel === 'Revise' || feedback.length > 0) {
+    return {
+      kind: 'result',
+      result: {
+        syntheticResult: {
+          isError: false,
+          output:
+            feedback.length > 0
+              ? `User rejected the plan. Feedback:\n\n${feedback}`
+              : 'User requested revisions. Plan mode remains active.',
+        },
+      },
+    };
+  }
+
+  return {
+    kind: 'result',
+    result: {
+      syntheticResult: {
+        isError: true,
+        stopTurn: true,
+        output: 'Plan rejected by user. Plan mode remains active.',
+      },
+    },
+  };
+}
+
+function exitPlanModeExecutionMetadata(
+  selectedOption: ExitPlanModeOption | undefined,
+): ExitPlanModeExecutionMetadata {
+  return {
+    selectedOption,
+    planTelemetrySubmitted: true,
+    planTelemetryResolved: true,
+  };
+}
+
+function trackExitPlanModeResolution(
+  context: PermissionPolicyContext,
+  result: ApprovalResponse,
+): void {
+  const selectedLabel = result.selectedLabel ?? '';
+  const normalizedSelectedLabel = normalizeOptionLabel(selectedLabel);
+  const feedback = result.feedback ?? '';
+  const hasFeedback = feedback.length > 0;
+
+  if (result.decision === 'cancelled') {
+    context.agent.telemetry.track('plan_resolved', { outcome: 'dismissed' });
+    return;
+  }
+
+  if (result.decision === 'approved') {
+    if (selectedLabel.length > 0) {
+      context.agent.telemetry.track('plan_resolved', {
+        outcome: 'approved',
+        chosen_option: selectedLabel,
+      });
+      return;
+    }
+    context.agent.telemetry.track('plan_resolved', { outcome: 'approved' });
+    return;
+  }
+
+  if (normalizedSelectedLabel === 'reject and exit') {
+    context.agent.telemetry.track('plan_resolved', { outcome: 'rejected_and_exited' });
+    return;
+  }
+
+  if (normalizedSelectedLabel === 'revise' || hasFeedback) {
+    context.agent.telemetry.track('plan_resolved', {
+      outcome: 'revise',
+      has_feedback: hasFeedback,
+    });
+    return;
+  }
+
+  context.agent.telemetry.track('plan_resolved', { outcome: 'rejected' });
+}
+
+function exitPlanModeForRejectedPlan(
+  context: PermissionPolicyContext,
+): ExecutableToolResult | undefined {
+  try {
+    context.agent.planMode.exit();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Failed to exit plan mode.';
+    return {
+      isError: true,
+      output: `Failed to exit plan mode: ${message}`,
+    };
+  }
+}
+
+function exitPlanModeOptions(args: unknown): readonly ExitPlanModeOption[] | undefined {
+  if (args === null || typeof args !== 'object') return undefined;
+  const options = (args as { readonly options?: unknown }).options;
+  if (!Array.isArray(options) || options.length < 2) return undefined;
+  const parsed: ExitPlanModeOption[] = [];
+  for (const option of options) {
+    if (option === null || typeof option !== 'object') return undefined;
+    const label = (option as { readonly label?: unknown }).label;
+    if (typeof label !== 'string') return undefined;
+    // `description` is optional in the ExitPlanMode schema (defaults to ''),
+    // so an option that omits it is still valid.
+    const description = (option as { readonly description?: unknown }).description;
+    if (description !== undefined && typeof description !== 'string') return undefined;
+    parsed.push({ label, description: description ?? '' });
+  }
+  return parsed;
+}
+
+function selectedExitPlanModeOption(
+  options: readonly ExitPlanModeOption[] | undefined,
+  label: string | undefined,
+): ExitPlanModeOption | undefined {
+  if (options === undefined || label === undefined) return undefined;
+  return options.find((option) => option.label === label);
+}
+
+function exitPlanModeAction(options: readonly ExitPlanModeOption[] | undefined): string {
+  return options !== undefined && options.length >= 2
+    ? 'Review plan and choose an option'
+    : 'Review plan';
+}
+
+function normalizeOptionLabel(label: string): string {
+  return label.trim().toLowerCase();
+}
+
+function readStringField(args: unknown, key: string): string | undefined {
+  if (args === null || typeof args !== 'object') return undefined;
+  const value = (args as Record<string, unknown>)[key];
+  return typeof value === 'string' ? value : undefined;
+}
diff --git a/packages/agent-core/src/agent/permission/policies/yolo-workspace-access.ts b/packages/agent-core/src/agent/permission/policies/yolo-workspace-access.ts
new file mode 100644
index 000000000..b95b9542c
--- /dev/null
+++ b/packages/agent-core/src/agent/permission/policies/yolo-workspace-access.ts
@@ -0,0 +1,74 @@
+import type { ToolInputDisplay } from '../../../tools/display';
+import {
+  DEFAULT_WORKSPACE_ACCESS_POLICY,
+  resolvePathAccess,
+  type PathAccessOperation,
+} from '../../../tools/policies/path-access';
+import type { PermissionPolicy } from '../policy';
+
+type FileInputDisplayOperation = Extract<ToolInputDisplay, { kind: 'file_io' }>['operation'];
+
+const FILE_ACCESS_TOOLS: Readonly<
+  Record<string, readonly [PathAccessOperation, FileInputDisplayOperation]>
+> = {
+  Read: ['read', 'read'],
+  ReadMediaFile: ['read', 'read'],
+  Write: ['write', 'write'],
+  Edit: ['write', 'edit'],
+  Grep: ['search', 'grep'],
+};
+
+export const YoloOutsideWorkspacePermissionPolicy: PermissionPolicy = {
+  name: 'yolo.outside-workspace',
+  evaluate({ agent, mode, toolCallContext }) {
+    if (mode !== 'yolo') return undefined;
+
+    const toolName = toolCallContext.toolCall.function.name;
+    const toolAccess = FILE_ACCESS_TOOLS[toolName];
+    if (toolAccess === undefined) return undefined;
+    const [operation, displayOperation] = toolAccess;
+
+    const rawPath = readStringField(toolCallContext.args, 'path');
+    if (rawPath === undefined) return undefined;
+
+    let access;
+    try {
+      access = resolvePathAccess(
+        rawPath,
+        agent.config.cwd,
+        {
+          workspaceDir: agent.config.cwd,
+          additionalDirs: agent.skills?.registry.getSkillRoots() ?? [],
+        },
+        {
+          operation,
+          pathClass: agent.runtime.kaos.pathClass(),
+          homeDir: agent.runtime.kaos.gethome(),
+          policy: {
+            ...DEFAULT_WORKSPACE_ACCESS_POLICY,
+            checkSensitive: toolName !== 'Grep',
+          },
+        },
+      );
+    } catch {
+      return undefined;
+    }
+
+    if (!access.outsideWorkspace) return undefined;
+    return {
+      kind: 'ask',
+      display: {
+        kind: 'file_io',
+        operation: displayOperation,
+        path: access.path,
+        detail: `Outside workspace: ${agent.config.cwd}`,
+      },
+    };
+  },
+};
+
+function readStringField(args: unknown, key: string): string | undefined {
+  if (args === null || typeof args !== 'object') return undefined;
+  const value = (args as Record<string, unknown>)[key];
+  return typeof value === 'string' ? value : undefined;
+}
diff --git a/packages/agent-core/src/agent/permission/policy.ts b/packages/agent-core/src/agent/permission/policy.ts
new file mode 100644
index 000000000..5baf7776e
--- /dev/null
+++ b/packages/agent-core/src/agent/permission/policy.ts
@@ -0,0 +1,42 @@
+import type { Agent } from '..';
+import type { PrepareToolExecutionResult, ToolExecutionHookContext } from '../../loop';
+import type { ToolInputDisplay } from '../../tools/display';
+import type { PermissionApprovalResultRecord, PermissionMode, PermissionRule } from './types';
+
+export interface PermissionPolicyContext {
+  readonly agent: Agent;
+  readonly mode: PermissionMode;
+  readonly toolCallContext: ToolExecutionHookContext;
+  /**
+   * The rule matched by `checkPermission()`, if any.
+   *
+   * Policies that want to defer to user-defined rules (e.g. a default-allow
+   * policy that should not override an explicit `ask`/`deny` rule) inspect
+   * this to decide whether to fire. `undefined` means the decision came
+   * from the built-in default permission table rather than a user rule.
+   */
+  readonly matchedRule: PermissionRule | undefined;
+  readonly recordApprovalResult: (record: PermissionApprovalResultRecord) => void;
+}
+
+export type PermissionPolicyResult =
+  | {
+      readonly kind: 'allow';
+      readonly executionMetadata?: unknown;
+    }
+  | {
+      readonly kind: 'result';
+      readonly result: PrepareToolExecutionResult;
+    }
+  | {
+      readonly kind: 'ask';
+      readonly action?: string | undefined;
+      readonly display?: ToolInputDisplay | undefined;
+    };
+
+export interface PermissionPolicy {
+  readonly name: string;
+  evaluate(
+    context: PermissionPolicyContext,
+  ): PermissionPolicyResult | undefined | Promise<PermissionPolicyResult | undefined>;
+}
diff --git a/packages/agent-core/src/agent/permission/types.ts b/packages/agent-core/src/agent/permission/types.ts
new file mode 100644
index 000000000..df51e55fc
--- /dev/null
+++ b/packages/agent-core/src/agent/permission/types.ts
@@ -0,0 +1,60 @@
+import type { ToolInputDisplay } from '../../tools/display';
+
+export type PermissionRuleDecision = 'allow' | 'deny' | 'ask';
+
+/**
+ * Rule provenance. `session-runtime` is the value used by the runtime
+ * "approve for session" path; `turn-override`, `project`, and `user`
+ * are reserved for static-loaded rules surfaced by external callers.
+ */
+export type PermissionRuleScope = 'turn-override' | 'session-runtime' | 'project' | 'user';
+
+/**
+ * Top-level user-facing permission posture. Controls how non-deny rules
+ * are treated when the closure is constructed. Independent of rule
+ * merging: deny rules always fire regardless of mode.
+ *
+ *   - `manual` — rule set drives decision; unmatched tool calls ask
+ *   - `yolo`   — only deny rules can block; everything else allows
+ *   - `auto`   — caller may bypass rule checks entirely
+ */
+export type PermissionMode = 'manual' | 'yolo' | 'auto';
+
+/**
+ * A single permission rule. `pattern` is the DSL form (`Read(/etc/**)`,
+ * `Bash(rm *)`, or bare `Write`). See `parse-pattern.ts` for the parser
+ * and `matches-rule.ts` for the matcher.
+ */
+export interface PermissionRule {
+  readonly decision: PermissionRuleDecision;
+  readonly scope: PermissionRuleScope;
+  readonly pattern: string;
+  readonly reason?: string | undefined;
+}
+
+export interface ApprovalRequest {
+  toolCallId: string;
+  toolName: string;
+  action: string;
+  display: ToolInputDisplay;
+}
+
+export interface ApprovalResponse {
+  decision: 'approved' | 'rejected' | 'cancelled';
+  scope?: 'session';
+  feedback?: string;
+  selectedLabel?: string;
+}
+
+export interface PermissionApprovalResultRecord {
+  readonly turnId: number;
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly action: string;
+  readonly result: ApprovalResponse;
+}
+
+export interface PermissionData {
+  mode: PermissionMode;
+  rules: PermissionRule[];
+}
diff --git a/packages/agent-core/src/agent/plan/index.ts b/packages/agent-core/src/agent/plan/index.ts
new file mode 100644
index 000000000..e2508e8af
--- /dev/null
+++ b/packages/agent-core/src/agent/plan/index.ts
@@ -0,0 +1,146 @@
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+
+import type { Agent } from '..';
+import { generateHeroSlug } from '../../utils/hero-slug';
+
+export type PlanData = null | {
+  id: string;
+  content: string;
+  path: string;
+};
+export type PlanFilePath = string | null;
+
+export class PlanMode {
+  protected _isActive = false;
+  protected _planId: null | string = null;
+  protected _planFilePath: PlanFilePath = null;
+
+  constructor(protected readonly agent: Agent) {}
+
+  createPlanId(): string {
+    return generateHeroSlug(randomUUID(), new Set());
+  }
+
+  async enter(id = this.createPlanId(), createFile = false, emitStatus = true): Promise<void> {
+    if (this._isActive) {
+      throw new Error('Already in plan mode');
+    }
+
+    this._isActive = true;
+    this._planId = id;
+    this._planFilePath = null;
+
+    let enterRecorded = false;
+    try {
+      const planFilePath = this.planFilePathFor(id);
+      this._planFilePath = planFilePath;
+      await this.ensurePlanDirectory(planFilePath);
+      this.agent.records.logRecord({ type: 'plan_mode.enter', id });
+      enterRecorded = true;
+      if (createFile) {
+        await this.writeEmptyPlanFile(planFilePath);
+      }
+    } catch (error) {
+      if (enterRecorded) {
+        this.cancel(id);
+      } else {
+        this._isActive = false;
+        this._planId = null;
+        this._planFilePath = null;
+      }
+      throw error;
+    }
+
+    if (emitStatus) this.agent.emitStatusUpdated();
+  }
+
+  restoreEnter({ id }: { readonly id: string }): void {
+    this.agent.replayBuilder.push({
+      type: 'plan_updated',
+      enabled: true,
+    });
+
+    this._isActive = true;
+    this._planId = id;
+    this._planFilePath = this.planFilePathFor(id);
+  }
+
+  cancel(id?: string): void {
+    this.agent.records.logRecord({ type: 'plan_mode.cancel', id });
+    this.agent.replayBuilder.push({
+      type: 'plan_updated',
+      enabled: false,
+    });
+    this._isActive = false;
+    this._planId = null;
+    this._planFilePath = null;
+    this.agent.emitStatusUpdated();
+  }
+
+  async clear(): Promise<void> {
+    if (!this._planFilePath) return;
+    await this.writeEmptyPlanFile(this._planFilePath);
+  }
+
+  exit(id?: string): void {
+    this.agent.records.logRecord({ type: 'plan_mode.exit', id });
+    this.agent.replayBuilder.push({
+      type: 'plan_updated',
+      enabled: false,
+    });
+    this._isActive = false;
+    this._planId = null;
+    this._planFilePath = null;
+    this.agent.emitStatusUpdated();
+  }
+
+  get isActive() {
+    return this._isActive;
+  }
+
+  get planFilePath(): PlanFilePath {
+    return this._planFilePath;
+  }
+
+  async data(): Promise<PlanData> {
+    if (!this._planId || !this._planFilePath) return null;
+    let content = '';
+    try {
+      content = await this.agent.runtime.kaos.readText(this._planFilePath);
+    } catch (error) {
+      if (!isMissingFileError(error)) throw error;
+    }
+    return {
+      id: this._planId,
+      content,
+      path: this._planFilePath,
+    };
+  }
+
+  private async writeEmptyPlanFile(path: string): Promise<void> {
+    await this.ensurePlanDirectory(path);
+    await this.agent.runtime.kaos.writeText(path, '');
+  }
+
+  private async ensurePlanDirectory(path: string): Promise<void> {
+    await this.agent.runtime.kaos.mkdir(dirname(path), {
+      parents: true,
+      existOk: true,
+    });
+  }
+
+  private planFilePathFor(id: string): string {
+    const plansDir =
+      this.agent.homedir === undefined
+        ? join(this.agent.config.cwd || this.agent.runtime.kaos.getcwd(), 'plan')
+        : join(this.agent.homedir, 'plans');
+    return join(plansDir, `${id}.md`);
+  }
+}
+
+function isMissingFileError(error: unknown): boolean {
+  if (error === null || typeof error !== 'object') return false;
+  const code = (error as { readonly code?: unknown }).code;
+  return code === 'ENOENT';
+}
diff --git a/packages/agent-core/src/agent/records/index.ts b/packages/agent-core/src/agent/records/index.ts
new file mode 100644
index 000000000..29de0cfa3
--- /dev/null
+++ b/packages/agent-core/src/agent/records/index.ts
@@ -0,0 +1,139 @@
+import type { Agent } from '..';
+import type { AgentRecord, AgentRecordPersistence } from './types';
+
+export * from './types';
+export { FileSystemAgentRecordPersistence } from './wire-file';
+export type { FileSystemAgentRecordPersistenceOptions } from './wire-file';
+
+// Contract: restore MUST NOT emit UI events, call the LLM, execute tools, or
+// touch the filesystem in a way that triggers external side effects. Each case
+// should reproduce the in-memory state the live handler left behind, nothing more.
+export function restoreAgentRecord(agent: Agent, input: AgentRecord): void {
+  switch (input.type) {
+    case 'turn.prompt':
+      agent.turn.restorePrompt();
+      return;
+    case 'turn.steer':
+      agent.turn.restoreSteer(input.input, input.origin);
+      return;
+    case 'turn.cancel':
+      agent.turn.cancel(input.turnId);
+      return;
+    case 'background.stop':
+      return;
+    case 'config.update':
+      agent.config.update(input);
+      return;
+    case 'permission.set_mode':
+      agent.permission.setMode(input.mode);
+      return;
+    case 'permission.record_approval_result':
+      agent.permission.recordApprovalResult(input);
+      return;
+    case 'usage.record':
+      agent.usage.record(input.model, input.usage, 'session');
+      return;
+    case 'full_compaction.begin':
+      agent.fullCompaction.begin(input);
+      return;
+    case 'full_compaction.cancel':
+      agent.fullCompaction.cancel();
+      return;
+    case 'full_compaction.complete':
+      agent.fullCompaction.complete(input);
+      return;
+    case 'plan_mode.enter':
+      agent.planMode.restoreEnter(input);
+      return;
+    case 'plan_mode.cancel':
+      agent.planMode.cancel(input.id);
+      return;
+    case 'plan_mode.exit':
+      agent.planMode.exit(input.id);
+      return;
+    case 'context.append_message':
+      agent.context.appendMessage(input.message);
+      return;
+    case 'context.mark_last_user_prompt_blocked':
+      agent.context.markLastUserPromptBlocked(input.hookEvent);
+      return;
+    case 'context.append_loop_event':
+      agent.context.appendLoopEvent(input.event);
+      return;
+    case 'context.clear':
+      agent.context.clear();
+      return;
+    case 'context.apply_compaction':
+      agent.context.applyCompaction(input);
+      return;
+    case 'tools.register_user_tool':
+      agent.tools.registerUserTool(input);
+      return;
+    case 'tools.unregister_user_tool':
+      agent.tools.unregisterUserTool(input.name);
+      return;
+    case 'tools.set_active_tools':
+      agent.tools.setActiveTools(input.names);
+      return;
+    case 'tools.update_store':
+      agent.tools.updateStore(input.key, input.value);
+      return;
+  }
+}
+
+export class AgentRecords {
+  private readonly records: AgentRecord[] = [];
+  private _restoring = false;
+  onRecord?: (record: AgentRecord) => void;
+  onError?: (error: unknown, record: AgentRecord) => void;
+
+  constructor(
+    private readonly restoreRecord: (record: AgentRecord) => void,
+    private readonly persistence?: AgentRecordPersistence,
+  ) {}
+
+  get restoring() {
+    return this._restoring;
+  }
+
+  logRecord(record: AgentRecord): void {
+    if (this._restoring) return;
+    const stamped: AgentRecord =
+      record.time !== undefined ? record : { ...record, time: Date.now() };
+    this.records.push(stamped);
+    this.onRecord?.(stamped);
+    void this.persistence?.append(stamped).catch((error) => {
+      this.onError?.(error, stamped);
+    });
+  }
+
+  restore(record: AgentRecord): void {
+    this._restoring = true;
+    try {
+      this.restoreRecord(record);
+    } finally {
+      this._restoring = false;
+    }
+  }
+
+  async replay(): Promise<void> {
+    if (!this.persistence) throw new Error('No persistence provided for AgentRecords');
+    for await (const record of this.persistence.read()) {
+      this.records.push(record);
+      this._restoring = true;
+      try {
+        this.restoreRecord(record);
+      } finally {
+        this._restoring = false;
+      }
+    }
+  }
+
+  snapshot(): readonly AgentRecord[] {
+    return [...this.records];
+  }
+
+  async flush(): Promise<void> {
+    await this.persistence?.flush();
+  }
+}
diff --git a/packages/agent-core/src/agent/records/types.ts b/packages/agent-core/src/agent/records/types.ts
new file mode 100644
index 000000000..83442af43
--- /dev/null
+++ b/packages/agent-core/src/agent/records/types.ts
@@ -0,0 +1,91 @@
+import type { ContentPart, TokenUsage } from '@moonshot-ai/kosong';
+
+import type { LoopRecordedEvent } from '../../loop';
+import type { ToolStoreUpdate } from '../../tools/store';
+import type { CompactionBeginData, CompactionResult } from '../compaction';
+import type { AgentConfigUpdateData } from '../config';
+import type { ContextMessage, PromptOrigin } from '../context';
+import type { PermissionApprovalResultRecord, PermissionMode } from '../permission';
+import type { UserToolRegistration } from '../tool';
+import type { UsageRecordScope } from '../usage';
+
+export interface AgentRecordEvents {
+  'turn.prompt': {
+    input: readonly ContentPart[];
+    origin: PromptOrigin;
+  };
+  'turn.steer': {
+    input: readonly ContentPart[];
+    origin: PromptOrigin;
+  };
+  'turn.cancel': { turnId?: number };
+
+  'config.update': AgentConfigUpdateData;
+
+  'permission.set_mode': {
+    mode: PermissionMode;
+  };
+  'permission.record_approval_result': PermissionApprovalResultRecord;
+
+  'full_compaction.begin': CompactionBeginData;
+
+  'plan_mode.enter': {
+    id: string;
+  };
+  'plan_mode.cancel': {
+    id?: string;
+  };
+  'plan_mode.exit': {
+    id?: string;
+  };
+
+  'tools.register_user_tool': UserToolRegistration;
+  'tools.unregister_user_tool': {
+    name: string;
+  };
+  'tools.set_active_tools': {
+    names: readonly string[];
+  };
+
+  'background.stop': {
+    taskId: string;
+  };
+
+  'usage.record': {
+    model: string;
+    usage: TokenUsage;
+    usageScope?: UsageRecordScope | undefined;
+  };
+
+  'full_compaction.cancel': {};
+  'full_compaction.complete': CompactionResult;
+
+  'context.append_message': { message: ContextMessage };
+  'context.mark_last_user_prompt_blocked': { hookEvent: string };
+  'context.append_loop_event': { event: LoopRecordedEvent };
+  'context.clear': {};
+  'context.apply_compaction': CompactionResult;
+
+  'tools.update_store': ToolStoreUpdate;
+}
+
+export type AgentRecord = {
+  [K in keyof AgentRecordEvents]: Readonly<AgentRecordEvents[K]> & {
+    readonly type: K;
+    readonly time?: number;
+  };
+}[keyof AgentRecordEvents];
+
+export type AgentRecordOf<K extends keyof AgentRecordEvents> = Extract<
+  AgentRecord,
+  { readonly type: K }
+>;
+
+export const AGENT_WIRE_PROTOCOL_VERSION = '1.0';
+
+export interface AgentRecordPersistence {
+  read(): AsyncIterable<AgentRecord>;
+  append(input: AgentRecord): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
diff --git a/packages/agent-core/src/agent/records/wire-file.ts b/packages/agent-core/src/agent/records/wire-file.ts
new file mode 100644
index 000000000..d16fe6216
--- /dev/null
+++ b/packages/agent-core/src/agent/records/wire-file.ts
@@ -0,0 +1,193 @@
+import { mkdir, open, readFile, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import { syncDir } from '../../utils/fs';
+import {
+  AGENT_WIRE_PROTOCOL_VERSION,
+  type AgentRecord,
+  type AgentRecordPersistence,
+} from './types';
+
+interface AgentWireMetadata {
+  readonly type: 'metadata';
+  readonly protocol_version: string;
+  readonly created_at: number;
+}
+
+type WireFileRecord = AgentRecord | AgentWireMetadata;
+
+export interface FileSystemAgentRecordPersistenceOptions {
+  readonly onError?: ((error: unknown) => void) | undefined;
+}
+
+class AsyncSerialQueue {
+  private tail: Promise<unknown> = Promise.resolve();
+
+  run<T>(task: () => Promise<T>): Promise<T> {
+    const next = this.tail.then(task, task);
+    this.tail = next.catch(() => {
+      /* swallow so a rejected task does not poison the chain */
+    });
+    return next;
+  }
+}
+
+// Single-writer per file: the "is file empty?" check before emitting the
+// header is racy across processes, but multi-writer wire.jsonl is unsupported.
+export class FileSystemAgentRecordPersistence implements AgentRecordPersistence {
+  private readonly queue = new AsyncSerialQueue();
+  private readonly pending: WireFileRecord[] = [];
+  private closed = false;
+  private closing = false;
+  private directorySynced = false;
+  private drainScheduled = false;
+  private lastBackgroundError: Error | undefined;
+  private headerPromise: Promise<void> | undefined;
+
+  constructor(
+    private readonly filePath: string,
+    private readonly options: FileSystemAgentRecordPersistenceOptions = {},
+  ) {}
+
+  async *read(): AsyncIterable<AgentRecord> {
+    await this.flush();
+
+    let text: string;
+    try {
+      text = await readFile(this.filePath, 'utf8');
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT') return;
+      throw error;
+    }
+
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (line === undefined || line.length === 0) continue;
+
+      let parsed: WireFileRecord;
+      try {
+        parsed = JSON.parse(line) as WireFileRecord;
+      } catch (parseError) {
+        // Tolerate a truncated trailing line — last write may have crashed
+        // mid-flush; everything before is still well-formed.
+        if (i === lines.length - 1) continue;
+        throw new Error(
+          `wire.jsonl: corrupted line ${i + 1} in ${this.filePath}: ${String(parseError)}`,
+          { cause: parseError },
+        );
+      }
+      if (parsed.type === 'metadata') continue;
+      yield parsed;
+    }
+  }
+
+  async append(input: AgentRecord): Promise<void> {
+    if (this.closed || this.closing) {
+      throw new Error('FileSystemAgentRecordPersistence: append on closed persistence');
+    }
+    await this.ensureHeader();
+    if (this.closed || this.closing) {
+      throw new Error('FileSystemAgentRecordPersistence: append on closed persistence');
+    }
+    this.pending.push(input);
+    this.scheduleDrain();
+  }
+
+  async flush(): Promise<void> {
+    await this.headerPromise;
+    try {
+      await this.queue.run(async () => {
+        while (this.pending.length > 0 && !this.closed) {
+          await this.drainBatch();
+        }
+      });
+    } catch (error) {
+      this.options.onError?.(error);
+      throw error;
+    }
+
+    if (this.lastBackgroundError !== undefined) {
+      const error = this.lastBackgroundError;
+      this.lastBackgroundError = undefined;
+      throw error;
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closing = true;
+    try {
+      await this.flush();
+      this.closed = true;
+    } catch (error) {
+      this.closing = false;
+      throw error;
+    }
+  }
+
+  private ensureHeader(): Promise<void> {
+    this.headerPromise ??= this.writeHeaderIfNeeded();
+    return this.headerPromise;
+  }
+
+  private async writeHeaderIfNeeded(): Promise<void> {
+    let isEmpty = true;
+    try {
+      const stats = await stat(this.filePath);
+      isEmpty = stats.size === 0;
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== 'ENOENT') throw error;
+    }
+    if (!isEmpty) return;
+
+    this.pending.unshift({
+      type: 'metadata',
+      protocol_version: AGENT_WIRE_PROTOCOL_VERSION,
+      created_at: Date.now(),
+    });
+  }
+
+  private scheduleDrain(): void {
+    if (this.drainScheduled || this.closed) return;
+    this.drainScheduled = true;
+    queueMicrotask(() => {
+      this.drainScheduled = false;
+      if (this.closed || this.pending.length === 0) return;
+      this.queue
+        .run(async () => {
+          while (this.pending.length > 0 && !this.closed) {
+            await this.drainBatch();
+          }
+        })
+        .catch((error) => {
+          this.lastBackgroundError = error as Error;
+          this.options.onError?.(error);
+        });
+    });
+  }
+
+  private async drainBatch(): Promise<void> {
+    if (this.pending.length === 0) return;
+
+    const batch = this.pending.splice(0);
+    const lines = batch.map((e) => JSON.stringify(e) + '\n');
+
+    await mkdir(dirname(this.filePath), { recursive: true });
+
+    const fh = await open(this.filePath, 'a');
+    try {
+      await fh.appendFile(lines.join(''), 'utf8');
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+
+    if (!this.directorySynced) {
+      await syncDir(dirname(this.filePath));
+      this.directorySynced = true;
+    }
+  }
+}
diff --git a/packages/agent-core/src/agent/replay/index.ts b/packages/agent-core/src/agent/replay/index.ts
new file mode 100644
index 000000000..0196e6225
--- /dev/null
+++ b/packages/agent-core/src/agent/replay/index.ts
@@ -0,0 +1,18 @@
+import type { Agent } from '..';
+import type { AgentReplayRecord } from '../..';
+
+export class ReplayBuilder {
+  protected readonly records: AgentReplayRecord[] = [];
+
+  constructor(public readonly agent: Agent) {}
+
+  push(record: AgentReplayRecord): void {
+    if (this.agent.records.restoring) {
+      this.records.push(record);
+    }
+  }
+
+  buildResult(): readonly AgentReplayRecord[] {
+    return this.records;
+  }
+}
diff --git a/packages/agent-core/src/agent/skill/index.ts b/packages/agent-core/src/agent/skill/index.ts
new file mode 100644
index 000000000..7d698b7eb
--- /dev/null
+++ b/packages/agent-core/src/agent/skill/index.ts
@@ -0,0 +1,72 @@
+import { randomUUID } from 'node:crypto';
+
+import type { ActivateSkillPayload } from '#/rpc';
+import type { ContentPart } from '@moonshot-ai/kosong';
+
+import type { Agent } from '..';
+import { ErrorCodes, KimiError } from '#/errors';
+import { isUserActivatableSkillType, type SkillRegistry } from '../../skill';
+import type { SkillActivationOrigin } from '../context';
+
+export class SkillManager {
+  constructor(
+    protected readonly agent: Agent,
+    public readonly registry: SkillRegistry,
+  ) {}
+
+  activate(input: ActivateSkillPayload): void {
+    const skill = this.registry.getSkill(input.name);
+    if (skill === undefined) {
+      throw new KimiError(ErrorCodes.SKILL_NOT_FOUND, `Skill "${input.name}" was not found`);
+    }
+    if (!isUserActivatableSkillType(skill.metadata.type)) {
+      throw new KimiError(ErrorCodes.SKILL_TYPE_UNSUPPORTED, `Skill "${skill.name}" cannot be activated by the user`);
+    }
+
+    this.recordActivation(
+      {
+        kind: 'skill_activation',
+        activationId: randomUUID(),
+        skillName: skill.name,
+        trigger: 'user-slash',
+        skillType: skill.metadata.type,
+        skillPath: skill.path,
+        skillSource: skill.source,
+        skillArgs: input.args,
+      },
+      [
+        {
+          type: 'text',
+          text: this.registry.renderSkillPrompt(skill, input.args ?? ''),
+        },
+      ],
+    );
+  }
+
+  recordActivation(
+    origin: SkillActivationOrigin,
+    input?: readonly ContentPart[] | undefined,
+  ): void {
+    this.agent.emitEvent({
+      type: 'skill.activated',
+      activationId: origin.activationId,
+      skillName: origin.skillName,
+      trigger: origin.trigger,
+      skillArgs: origin.skillArgs,
+      skillPath: origin.skillPath,
+      skillSource: origin.skillSource,
+    });
+    this.agent.telemetry.track('skill_invoked', {
+      skill_name: origin.skillName,
+      trigger: origin.trigger,
+    });
+    if (origin.skillType === 'flow') {
+      this.agent.telemetry.track('flow_invoked', {
+        flow_name: origin.skillName,
+      });
+    }
+    if (input !== undefined) {
+      this.agent.turn.prompt(input, origin);
+    }
+  }
+}
diff --git a/packages/agent-core/src/agent/tool/index.ts b/packages/agent-core/src/agent/tool/index.ts
new file mode 100644
index 000000000..614b8ff25
--- /dev/null
+++ b/packages/agent-core/src/agent/tool/index.ts
@@ -0,0 +1,421 @@
+import { uniq } from '@antfu/utils';
+import type { ChatProvider, Tool } from '@moonshot-ai/kosong';
+
+import type { Agent } from '..';
+import { globMatch } from '../permission/path-glob-match';
+import { makeErrorPayload } from '../../errors';
+import type { ExecutableTool } from '../../loop';
+import { createMcpAuthTool } from '../../mcp/auth-tool';
+import type { McpConnectionManager, McpServerEntry } from '../../mcp';
+import { mcpResultToExecutableOutput } from '../../mcp/output';
+import { isMcpToolName, qualifyMcpToolName } from '../../mcp/tool-naming';
+import type { MCPClient } from '../../mcp/types';
+import { DEFAULT_AGENT_PROFILES } from '../../profile';
+import { withProviderRequestAuth } from '../../providers/request-auth';
+import { extendWorkspaceWithSkillRoots } from '../../skill';
+import * as b from '../../tools/builtin';
+import type { ToolStore, ToolStoreData, ToolStoreKey } from '../../tools/store';
+import type {
+  BuiltinTool,
+  McpServerRegistrationResult,
+  McpToolCollision,
+  ToolInfo,
+  UserToolRegistration,
+} from './types';
+
+export * from './types';
+
+interface McpToolEntry {
+  readonly tool: ExecutableTool;
+  readonly serverName: string;
+}
+
+export class ToolManager {
+  protected builtinTools: Map<string, BuiltinTool> = new Map();
+  protected readonly userTools: Map<string, ExecutableTool> = new Map();
+  protected readonly mcpTools: Map<string, McpToolEntry> = new Map();
+  /** server name → list of qualified tool names registered for that server. */
+  protected readonly mcpToolsByServer: Map<string, string[]> = new Map();
+  protected enabledTools: Set<string> = new Set();
+  /** Glob patterns (e.g. `mcp__*`, `mcp__github__*`) gating which MCP tools the profile exposes. */
+  private mcpAccessPatterns: string[] = [];
+  protected readonly store: Partial<ToolStoreData> = {};
+  private mcpToolStatusUnsubscribe: (() => void) | undefined;
+
+  constructor(protected readonly agent: Agent) {
+    this.attachMcpTools();
+  }
+
+  protected get toolStore(): ToolStore {
+    return {
+      get: (key) => this.store[key],
+      set: (key, value) => {
+        this.updateStore(key, value);
+      },
+    };
+  }
+
+  attachMcpTools(): void {
+    const mcp = this.agent.mcp;
+    if (mcp === undefined) return;
+    if (this.mcpToolStatusUnsubscribe !== undefined) return;
+    for (const entry of mcp.list()) {
+      if (entry.status === 'connected') {
+        this.registerConnectedMcpServer(mcp, entry);
+      } else if (entry.status === 'needs-auth') {
+        this.registerNeedsAuthMcpServer(mcp, entry);
+      }
+    }
+    this.mcpToolStatusUnsubscribe = mcp.onStatusChange((entry) => {
+      this.handleMcpServerStatusChange(mcp, entry);
+    });
+  }
+
+  updateStore<K extends ToolStoreKey>(key: K, value: ToolStoreData[K]): void {
+    this.agent.records.logRecord({
+      type: 'tools.update_store',
+      key,
+      value,
+    });
+    this.store[key] = value;
+  }
+
+  registerUserTool(input: UserToolRegistration): void {
+    this.agent.records.logRecord({
+      type: 'tools.register_user_tool',
+      ...input,
+    });
+    const { name, description, parameters } = input;
+    const tool: ExecutableTool = {
+      name,
+      description,
+      parameters,
+      resolveExecution: (args) => {
+        return {
+          execute: async (context) => {
+            return this.agent.rpc.toolCall(
+              {
+                turnId: Number(context.turnId),
+                toolCallId: context.toolCallId,
+                args,
+              },
+              { signal: context.signal },
+            );
+          },
+        };
+      },
+    };
+    this.userTools.set(name, tool);
+    this.enabledTools.add(name);
+  }
+
+  unregisterUserTool(name: string): void {
+    this.agent.records.logRecord({
+      type: 'tools.unregister_user_tool',
+      name,
+    });
+    this.userTools.delete(name);
+    this.enabledTools.delete(name);
+  }
+
+  registerMcpServer(
+    serverName: string,
+    client: MCPClient,
+    tools: readonly Tool[],
+    enabledTools?: ReadonlySet<string>,
+  ): McpServerRegistrationResult {
+    this.unregisterMcpServer(serverName);
+    const qualifiedNames: string[] = [];
+    const collisions: McpToolCollision[] = [];
+    const seenInThisCall = new Map<string, string>();
+    for (const tool of tools) {
+      if (enabledTools !== undefined && !enabledTools.has(tool.name)) continue;
+      const qualified = qualifyMcpToolName(serverName, tool.name);
+      const firstInThisCall = seenInThisCall.get(qualified);
+      if (firstInThisCall !== undefined) {
+        collisions.push({
+          qualified,
+          toolName: tool.name,
+          collidesWith: { kind: 'same_server', toolName: firstInThisCall },
+        });
+        continue;
+      }
+      const existingEntry = this.mcpTools.get(qualified);
+      if (existingEntry !== undefined) {
+        collisions.push({
+          qualified,
+          toolName: tool.name,
+          collidesWith: { kind: 'other_server', serverName: existingEntry.serverName },
+        });
+        continue;
+      }
+      seenInThisCall.set(qualified, tool.name);
+      const wrapped: ExecutableTool = {
+        name: qualified,
+        description: tool.description,
+        parameters: tool.parameters,
+        resolveExecution: (args) => {
+          return {
+            execute: async (context) => {
+              // `args` has already been JSON-parsed and schema-validated by
+              // the loop's preflight (`loop/tool-call.ts`), so the MCP
+              // client gets a plain object directly.
+              const result = await client.callTool(
+                tool.name,
+                (args ?? {}) as Record<string, unknown>,
+                context.signal,
+              );
+              return mcpResultToExecutableOutput(result, qualified);
+            },
+          };
+        },
+      };
+      this.mcpTools.set(qualified, { tool: wrapped, serverName });
+      qualifiedNames.push(qualified);
+    }
+    this.mcpToolsByServer.set(serverName, qualifiedNames);
+    return { registered: qualifiedNames, collisions };
+  }
+
+  unregisterMcpServer(serverName: string): boolean {
+    const existing = this.mcpToolsByServer.get(serverName);
+    if (existing === undefined) return false;
+    for (const qualified of existing) {
+      this.mcpTools.delete(qualified);
+    }
+    this.mcpToolsByServer.delete(serverName);
+    return true;
+  }
+
+  private handleMcpServerStatusChange(mcp: McpConnectionManager, entry: McpServerEntry): void {
+    if (entry.status === 'connected') {
+      this.registerConnectedMcpServer(mcp, entry);
+      return;
+    }
+    if (entry.status === 'needs-auth') {
+      this.registerNeedsAuthMcpServer(mcp, entry);
+      return;
+    }
+    if (entry.status === 'failed') {
+      this.unregisterMcpServer(entry.name);
+      this.agent.emitEvent({
+        type: 'tool.list.updated',
+        reason: 'mcp.failed',
+        serverName: entry.name,
+      });
+      return;
+    }
+    if (entry.status === 'disabled' || entry.status === 'pending') {
+      const removed = this.unregisterMcpServer(entry.name);
+      if (removed) {
+        this.agent.emitEvent({
+          type: 'tool.list.updated',
+          reason: 'mcp.disconnected',
+          serverName: entry.name,
+        });
+      }
+    }
+  }
+
+  private registerNeedsAuthMcpServer(mcp: McpConnectionManager, entry: McpServerEntry): void {
+    // Replace whatever tools (real or synthetic) were registered before; a
+    // server flipping to needs-auth means previous tokens were invalidated.
+    this.unregisterMcpServer(entry.name);
+    const oauthService = mcp.oauthService;
+    const serverUrl = mcp.getHttpServerUrl(entry.name);
+    if (oauthService === undefined || serverUrl === undefined) {
+      // Misconfiguration: a server reached needs-auth without the manager
+      // owning an OAuth service or being HTTP. Treat it as a no-op so the
+      // existing failure error message keeps the user informed.
+      return;
+    }
+    const tool = createMcpAuthTool({
+      serverName: entry.name,
+      serverUrl,
+      oauthService,
+      reconnect: async () => {
+        await mcp.reconnect(entry.name);
+      },
+    });
+    this.mcpTools.set(tool.name, { tool, serverName: entry.name });
+    this.mcpToolsByServer.set(entry.name, [tool.name]);
+    // The synthetic auth tool is now in the tool list; surface it the same way
+    // a real toolset would show up so the model picks it up.
+    this.agent.emitEvent({
+      type: 'tool.list.updated',
+      reason: 'mcp.connected',
+      serverName: entry.name,
+    });
+  }
+
+  private registerConnectedMcpServer(mcp: McpConnectionManager, entry: McpServerEntry): void {
+    const resolved = mcp.resolved(entry.name);
+    if (resolved === undefined) return;
+    const result = this.registerMcpServer(
+      entry.name,
+      resolved.client,
+      resolved.tools,
+      resolved.enabledNames,
+    );
+    this.emitMcpToolCollisions(entry.name, result.collisions);
+    this.agent.emitEvent({
+      type: 'tool.list.updated',
+      reason: 'mcp.connected',
+      serverName: entry.name,
+    });
+  }
+
+  private emitMcpToolCollisions(serverName: string, collisions: readonly McpToolCollision[]): void {
+    if (collisions.length === 0) return;
+    const summary = collisions
+      .map((c) =>
+        c.collidesWith.kind === 'same_server'
+          ? `"${c.toolName}" -> ${c.qualified} (collides with "${c.collidesWith.toolName}" from the same server)`
+          : `"${c.toolName}" -> ${c.qualified} (collides with server "${c.collidesWith.serverName}")`,
+      )
+      .join('; ');
+    this.agent.emitEvent({
+      type: 'error',
+      ...makeErrorPayload(
+        'mcp.tool_name_collision',
+        `MCP server "${serverName}" registered ${collisions.length} tool name` +
+          `${collisions.length === 1 ? '' : 's'} ` +
+          `that collide with existing qualified names; the losing tools were dropped: ${summary}`,
+        { details: { serverName, collisions: collisions as readonly unknown[] } },
+      ),
+    });
+  }
+
+  setActiveTools(names: readonly string[]): void {
+    this.agent.records.logRecord({
+      type: 'tools.set_active_tools',
+      names,
+    });
+    // MCP entries are glob patterns gated separately; the rest are exact
+    // builtin/user tool names. The split keeps every caller on one string[].
+    this.enabledTools = new Set(names.filter((name) => !isMcpToolName(name)));
+    this.mcpAccessPatterns = names.filter((name) => isMcpToolName(name));
+  }
+
+  private isMcpToolEnabled(name: string): boolean {
+    return this.mcpAccessPatterns.some((pattern) => globMatch(name, pattern));
+  }
+
+  *toolInfos(): Iterable<ToolInfo> {
+    for (const tool of this.builtinTools.values()) {
+      yield {
+        name: tool.name,
+        description: tool.description,
+        active: this.enabledTools.has(tool.name),
+        source: 'builtin',
+      };
+    }
+    for (const tool of this.userTools.values()) {
+      yield {
+        name: tool.name,
+        description: tool.description,
+        active: this.enabledTools.has(tool.name),
+        source: 'user',
+      };
+    }
+    for (const entry of this.mcpTools.values()) {
+      yield {
+        name: entry.tool.name,
+        description: entry.tool.description,
+        active: this.isMcpToolEnabled(entry.tool.name),
+        source: 'mcp',
+      };
+    }
+  }
+
+  data(): readonly ToolInfo[] {
+    return Array.from(this.toolInfos());
+  }
+
+  storeData(): Readonly<Record<string, unknown>> {
+    return { ...this.store };
+  }
+
+  initializeBuiltinTools(): void {
+    const {
+      runtime: { kaos, osEnv, urlFetcher, webSearcher },
+      config: { cwd, provider, modelCapabilities },
+      background,
+    } = this.agent;
+    const videoUploader = this.createVideoUploader(provider);
+    const workspace = extendWorkspaceWithSkillRoots(
+      {
+        workspaceDir: cwd,
+        additionalDirs: [],
+      },
+      this.agent.skills?.registry.getSkillRoots() ?? [],
+    );
+    const allowBackground =
+      this.enabledTools.has('TaskList') &&
+      this.enabledTools.has('TaskOutput') &&
+      this.enabledTools.has('TaskStop');
+    this.builtinTools = new Map(
+      [
+        new b.ReadTool(kaos, workspace),
+        new b.WriteTool(kaos, workspace),
+        new b.EditTool(kaos, workspace),
+        new b.GrepTool(kaos, workspace),
+        new b.GlobTool(kaos, workspace),
+        new b.BashTool(kaos, cwd, osEnv, background, {
+          allowBackground,
+        }),
+        (modelCapabilities.image_in || modelCapabilities.video_in) &&
+          new b.ReadMediaFileTool(kaos, workspace, modelCapabilities, videoUploader),
+        new b.EnterPlanModeTool(this.agent),
+        new b.ExitPlanModeTool(this.agent),
+        new b.AskUserQuestionTool(this.agent),
+        new b.TodoListTool(this.toolStore),
+        new b.TaskListTool(background),
+        new b.TaskOutputTool(background),
+        new b.TaskStopTool(background),
+        this.agent.skills !== undefined &&
+          this.agent.skills.registry.listInvocableSkills().length > 0 &&
+          new b.SkillTool(this.agent),
+        this.agent.subagentHost &&
+          new b.AgentTool(
+            this.agent.subagentHost,
+            background,
+            DEFAULT_AGENT_PROFILES['agent']?.subagents,
+            {
+              allowBackground,
+              log: this.agent.log,
+            },
+          ),
+        webSearcher && new b.WebSearchTool(webSearcher),
+        urlFetcher && new b.FetchURLTool(urlFetcher),
+      ]
+        .filter((tool) => !!tool)
+        .map((tool) => [tool.name, tool] as const),
+    );
+  }
+
+  private createVideoUploader(provider: ChatProvider): b.VideoUploader | undefined {
+    const uploadVideo = provider.uploadVideo?.bind(provider);
+    if (uploadVideo === undefined) return undefined;
+
+    const modelAlias = this.agent.config.modelAlias;
+    const resolveAuth =
+      modelAlias === undefined
+        ? undefined
+        : this.agent.providerManager?.createAuthResolverForModel(modelAlias, {
+            log: this.agent.log,
+          });
+    return (input) => withProviderRequestAuth(resolveAuth, (auth) => uploadVideo(input, { auth }));
+  }
+
+  get loopTools(): readonly ExecutableTool[] {
+    const mcpNames = [...this.mcpTools.keys()].filter((name) => this.isMcpToolEnabled(name));
+    return uniq([...this.enabledTools, ...mcpNames])
+      .toSorted((a, b) => a.localeCompare(b))
+      .map(
+        (name) =>
+          this.userTools.get(name) ?? this.mcpTools.get(name)?.tool ?? this.builtinTools.get(name),
+      )
+      .filter((tool) => !!tool);
+  }
+}
diff --git a/packages/agent-core/src/agent/tool/types.ts b/packages/agent-core/src/agent/tool/types.ts
new file mode 100644
index 000000000..08a822d85
--- /dev/null
+++ b/packages/agent-core/src/agent/tool/types.ts
@@ -0,0 +1,31 @@
+import type { ExecutableTool } from '../../loop';
+
+export type ToolSource = 'builtin' | 'user' | 'mcp';
+
+export type BuiltinTool<Input = unknown> = ExecutableTool<Input>;
+
+export interface UserToolRegistration {
+  readonly name: string;
+  readonly description: string;
+  readonly parameters: Record<string, unknown>;
+}
+
+export interface ToolInfo {
+  readonly name: string;
+  readonly description: string;
+  readonly active: boolean;
+  readonly source: ToolSource;
+}
+
+export interface McpToolCollision {
+  readonly qualified: string;
+  readonly toolName: string;
+  readonly collidesWith:
+    | { readonly kind: 'same_server'; readonly toolName: string }
+    | { readonly kind: 'other_server'; readonly serverName: string };
+}
+
+export interface McpServerRegistrationResult {
+  readonly registered: readonly string[];
+  readonly collisions: readonly McpToolCollision[];
+}
diff --git a/packages/agent-core/src/agent/turn/canonical-args.ts b/packages/agent-core/src/agent/turn/canonical-args.ts
new file mode 100644
index 000000000..2753af2f0
--- /dev/null
+++ b/packages/agent-core/src/agent/turn/canonical-args.ts
@@ -0,0 +1,28 @@
+/**
+ * JSON canonicalization used by tool-call telemetry and dedup.
+ * Recursively sorts object keys so semantically-equal args produce identical keys.
+ */
+export function canonicalTelemetryArgs(args: unknown): string {
+  const json = JSON.stringify(sortJsonValue(args));
+  return json ?? String(args);
+}
+
+function sortJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(sortJsonValue);
+  }
+  if (!isPlainRecord(value)) {
+    return value;
+  }
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(value).toSorted()) {
+    out[key] = sortJsonValue(value[key]);
+  }
+  return out;
+}
+
+export function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
diff --git a/packages/agent-core/src/agent/turn/index.ts b/packages/agent-core/src/agent/turn/index.ts
new file mode 100644
index 000000000..1b14b2a3f
--- /dev/null
+++ b/packages/agent-core/src/agent/turn/index.ts
@@ -0,0 +1,858 @@
+import { createHash } from 'node:crypto';
+
+import {
+  APIConnectionError,
+  APIContextOverflowError,
+  APIEmptyResponseError,
+  APIStatusError,
+  APITimeoutError,
+  inputTotal,
+  type ContentPart,
+  type TokenUsage,
+} from '@moonshot-ai/kosong';
+
+import type { Agent } from '..';
+import {
+  ErrorCodes,
+  type KimiErrorPayload,
+  isKimiError,
+  makeErrorPayload,
+  toKimiErrorPayload,
+} from '#/errors';
+import { isAbortError, isMaxStepsExceededError } from '../../loop/errors';
+import {
+  createLoopEventDispatcher,
+  runTurn,
+  type ExecutableToolResult,
+  type LoopEvent,
+  type LoopRecordedEvent,
+  type LoopTurnInterruptedEvent,
+  type LoopTurnStopReason,
+} from '../../loop/index';
+import type { AgentEvent, TurnEndedEvent } from '../../rpc';
+import type { TelemetryPropertyValue } from '../../telemetry';
+import { abortable } from '../../utils/abort';
+import { resolveCompletionBudget } from '../../utils/completion-budget';
+import { USER_PROMPT_ORIGIN, type PromptOrigin } from '../context';
+import { renderUserPromptHookBlockResult, renderUserPromptHookResult } from '../hooks';
+import { canonicalTelemetryArgs, isPlainRecord } from './canonical-args';
+import { KosongLLM } from './kosong-llm';
+import { ToolCallDeduplicator } from './tool-dedup';
+
+interface ActiveTurn {
+  controller: AbortController;
+  promise: Promise<TurnEndResult>;
+}
+
+interface BufferedSteer {
+  readonly input: readonly ContentPart[];
+  readonly origin: PromptOrigin;
+}
+
+export interface TurnEndResult {
+  readonly event: TurnEndedEvent;
+  readonly stopReason?: LoopTurnStopReason;
+}
+
+const LLM_NOT_SET_MESSAGE = 'LLM not set, send "/login" to login';
+
+export class TurnFlow {
+  private steerBuffer: BufferedSteer[] = [];
+  private turnId = -1;
+  private activeTurn: 'resuming' | ActiveTurn | null = null;
+  private readonly toolCallStartedAt = new Map<string, { name: string; startedAt: number }>();
+  private readonly toolCallDupType = new Map<string, 'normal' | 'cross_step'>();
+  private readonly stepToolCallKeys = new Map<number, Set<string>>();
+  private readonly telemetryModeByTurn = new Map<number, 'agent' | 'plan'>();
+  private readonly currentStepByTurn = new Map<number, number>();
+  private readonly interruptedTelemetryTurnIds = new Set<number>();
+  private readonly stepFailureByTurn = new Map<number, LoopTurnInterruptedEvent>();
+  private currentStep = 0;
+
+  constructor(protected readonly agent: Agent) {}
+
+  // Returns the new turnId, or null if the turn was marked as resuming.
+  prompt(input: readonly ContentPart[], origin: PromptOrigin = USER_PROMPT_ORIGIN): number | null {
+    this.agent.records.logRecord({
+      type: 'turn.prompt',
+      input,
+      origin,
+    });
+    return this.launch(input, origin);
+  }
+
+  // Returns the new turnId, or null if the input was buffered as a steer
+  // message or the turn was marked as resuming.
+  steer(input: readonly ContentPart[], origin: PromptOrigin = USER_PROMPT_ORIGIN): number | null {
+    this.agent.records.logRecord({
+      type: 'turn.steer',
+      input,
+      origin,
+    });
+    if (this.activeTurn) {
+      this.steerBuffer.push({ input, origin });
+      return null;
+    }
+    return this.launch(input, origin);
+  }
+
+  private launch(input: readonly ContentPart[], origin: PromptOrigin): number | null {
+    if (this.activeTurn) {
+      this.agent.emitEvent({
+        type: 'error',
+        ...makeErrorPayload(
+          'turn.agent_busy',
+          `Cannot launch a new turn while another turn (ID ${this.turnId}) is active`,
+          { details: { turnId: this.turnId } },
+        ),
+      });
+      return null;
+    }
+
+    this.turnId += 1;
+    this.currentStep = 0;
+    this.stepToolCallKeys.clear();
+    this.toolCallDupType.clear();
+    const telemetryMode = this.telemetryMode();
+    this.telemetryModeByTurn.set(this.turnId, telemetryMode);
+    this.currentStepByTurn.set(this.turnId, 0);
+    this.agent.telemetry.track('turn_started', { mode: telemetryMode });
+    this.agent.fullCompaction.resetForTurn();
+    this.agent.usage.beginTurn();
+    this.agent.emitEvent({
+      type: 'turn.started',
+      turnId: this.turnId,
+      origin,
+    });
+    this.agent.context.appendUserMessage(input, origin);
+    const controller = new AbortController();
+    const promise = this.turnWorker(this.turnId, input, origin, controller.signal);
+    this.activeTurn = { controller, promise };
+    return this.turnId;
+  }
+
+  restorePrompt(): void {
+    if (this.activeTurn) {
+      return;
+    }
+    this.turnId += 1;
+    this.activeTurn = 'resuming';
+  }
+
+  restoreSteer(input: readonly ContentPart[], origin: PromptOrigin): void {
+    if (this.activeTurn) {
+      this.steerBuffer.push({ input, origin });
+      return;
+    }
+    this.turnId += 1;
+    this.activeTurn = 'resuming';
+  }
+
+  cancel(turnId?: number): void {
+    this.agent.records.logRecord({ type: 'turn.cancel', turnId });
+    if (turnId !== undefined && turnId !== this.currentId) {
+      return; // Ignore cancel for non-active turn
+    }
+    this.abortTurn();
+    this.agent.subagentHost?.cancelAll();
+  }
+
+  get currentId() {
+    return this.turnId;
+  }
+
+  get hasActiveTurn(): boolean {
+    return this.activeTurn !== null && this.activeTurn !== 'resuming';
+  }
+
+  waitForCurrentTurn(signal?: AbortSignal | undefined): Promise<TurnEndResult> {
+    const active = this.activeTurn;
+    if (active === null || active === 'resuming') {
+      return Promise.reject(new Error('No active turn'));
+    }
+    signal?.throwIfAborted();
+    if (signal === undefined) return active.promise;
+
+    const turnId = this.currentId;
+    const onAbort = (): void => {
+      this.agent.turn.cancel(turnId);
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+
+    return abortable(active.promise, signal).finally(() => {
+      signal.removeEventListener('abort', onAbort);
+    });
+  }
+
+  private abortTurn() {
+    if (this.activeTurn !== 'resuming') {
+      this.activeTurn?.controller.abort();
+    }
+    this.activeTurn = null;
+  }
+
+  private flushSteerBuffer(): boolean {
+    const steers = this.steerBuffer;
+    if (steers.length === 0) return false;
+    for (const steer of steers) {
+      this.agent.context.appendUserMessage(steer.input, steer.origin);
+    }
+    steers.length = 0;
+    return true;
+  }
+
+  finishResume(): void {
+    if (this.activeTurn === 'resuming') {
+      this.activeTurn = null;
+    }
+    this.steerBuffer.length = 0;
+  }
+
+  private async turnWorker(
+    turnId: number,
+    input: readonly ContentPart[],
+    origin: PromptOrigin,
+    signal: AbortSignal,
+  ): Promise<TurnEndResult> {
+    const startedAt = Date.now();
+    let ended: TurnEndedEvent;
+    let completedStopReason: LoopTurnStopReason | undefined;
+    try {
+      const promptHookEnded = await this.applyUserPromptHook(
+        turnId,
+        input,
+        origin,
+        signal,
+      );
+      if (promptHookEnded !== undefined) {
+        ended = promptHookEnded;
+      } else {
+        const stopReason = await this.runTurn(turnId, signal);
+        completedStopReason = stopReason;
+        ended = {
+          type: 'turn.ended',
+          turnId,
+          reason: stopReason === 'aborted' ? 'cancelled' : 'completed',
+        };
+        this.agent.emitEvent(ended);
+      }
+    } catch (error) {
+      if (isAbortError(error)) {
+        ended = {
+          type: 'turn.ended',
+          turnId,
+          reason: 'cancelled',
+        };
+        this.agent.emitEvent(ended);
+      } else {
+        const summary = summarizeTurnError(error, turnId);
+        void this.agent.hooks?.fireAndForgetTrigger('StopFailure', {
+          matcherValue: summary.name,
+          inputData: {
+            errorType: summary.name,
+            errorMessage: summary.message,
+          },
+        });
+        ended = {
+          type: 'turn.ended',
+          turnId,
+          reason: 'failed',
+          error: summary,
+        };
+        this.agent.emitEvent(ended);
+        this.agent.emitEvent({
+          type: 'error',
+          ...summary,
+        });
+        if (this.shouldTrackApiError(turnId)) {
+          const classification = classifyApiError(error, summary);
+          const properties: Record<string, TelemetryPropertyValue> = {
+            error_type: classification.errorType,
+            model: this.agent.config.model,
+            retryable: summary.retryable,
+            duration_ms: Date.now() - startedAt,
+          };
+          if (classification.statusCode !== undefined) {
+            properties['status_code'] = classification.statusCode;
+          }
+          const inputTokens = currentTurnInputTokens(this.agent.usage.data().currentTurn);
+          if (inputTokens !== undefined) {
+            properties['input_tokens'] = inputTokens;
+          }
+          this.agent.telemetry.track('api_error', properties);
+        }
+      }
+    } finally {
+      // The turn may have been aborted and a new turn may have started
+      if (this.currentId === turnId) {
+        this.agent.usage.endTurn();
+        this.activeTurn = null;
+      }
+    }
+    if (ended.reason !== 'completed') {
+      this.trackTurnInterrupted(turnId, this.currentStepByTurn.get(turnId) ?? this.currentStep);
+    }
+    this.telemetryModeByTurn.delete(turnId);
+    this.currentStepByTurn.delete(turnId);
+    this.interruptedTelemetryTurnIds.delete(turnId);
+    this.stepFailureByTurn.delete(turnId);
+    return {
+      event: ended,
+      stopReason: completedStopReason,
+    };
+  }
+
+  private async applyUserPromptHook(
+    turnId: number,
+    input: readonly ContentPart[],
+    origin: PromptOrigin,
+    signal: AbortSignal,
+  ): Promise<TurnEndedEvent | undefined> {
+    if (origin.kind !== 'user') return undefined;
+    signal.throwIfAborted();
+    const promptHookResults = await this.agent.hooks?.trigger('UserPromptSubmit', {
+      matcherValue: input,
+      signal,
+      inputData: { prompt: input },
+    });
+    signal.throwIfAborted();
+    const blockResult = renderUserPromptHookBlockResult(promptHookResults);
+    if (blockResult !== undefined) {
+      this.agent.context.markLastUserPromptBlocked('UserPromptSubmit');
+      this.agent.context.appendMessage({
+        role: 'assistant',
+        content: [{ type: 'text', text: blockResult.text }],
+        toolCalls: [],
+        origin: { kind: 'hook_result', event: 'UserPromptSubmit', blocked: true },
+      });
+      this.agent.emitEvent({
+        type: 'hook.result',
+        turnId,
+        hookEvent: blockResult.event,
+        content: blockResult.message,
+        blocked: true,
+      });
+      const ended: TurnEndedEvent = {
+        type: 'turn.ended',
+        turnId,
+        reason: 'completed',
+      };
+      this.agent.emitEvent(ended);
+      return ended;
+    }
+
+    const hookResult = renderUserPromptHookResult(promptHookResults);
+    if (hookResult === undefined) return undefined;
+
+    this.agent.context.appendUserMessage([{ type: 'text', text: hookResult.text }], {
+      kind: 'hook_result',
+      event: 'UserPromptSubmit',
+    });
+    this.agent.emitEvent({
+      type: 'hook.result',
+      turnId,
+      hookEvent: hookResult.event,
+      content: hookResult.message,
+    });
+    return undefined;
+  }
+
+  private async runTurn(turnId: number, signal: AbortSignal): Promise<LoopTurnStopReason> {
+    let stopHookContinuationUsed = false;
+    const deduper = new ToolCallDeduplicator();
+    await this.agent.mcp?.waitForInitialLoad(signal);
+    while (true) {
+      signal.throwIfAborted();
+      const model = this.agent.config.model;
+      const provider = this.agent.config.provider.withThinking(this.agent.config.thinkingLevel);
+      const loopControl = this.agent.providerManager?.config.loopControl;
+      const completionBudget = resolveCompletionBudget({
+        reservedContextSize: loopControl?.reservedContextSize,
+      });
+
+      try {
+        const result = await runTurn({
+          turnId: String(turnId),
+          signal,
+          llm: new KosongLLM({
+            provider,
+            modelName: model,
+            systemPrompt: this.agent.config.systemPrompt,
+            capability: this.agent.config.modelCapabilities,
+            generate: this.agent.generate,
+            completionBudget,
+          }),
+          buildMessages: () => this.agent.context.messages,
+          dispatchEvent: this.buildDispatchEvent(turnId),
+          tools: this.agent.tools.loopTools,
+          log: this.agent.log,
+          maxSteps: loopControl?.maxStepsPerTurn,
+          maxRetryAttempts: loopControl?.maxRetriesPerStep,
+          hooks: {
+            beforeStep: async ({ signal: stepSignal }) => {
+              this.flushSteerBuffer();
+              await this.agent.fullCompaction.beforeStep(stepSignal);
+              await this.agent.injection.inject();
+              deduper.beginStep();
+              return;
+            },
+            afterStep: async ({ usage }) => {
+              this.agent.usage.record(model, usage, 'turn');
+              await this.agent.fullCompaction.afterStep();
+              deduper.endStep();
+            },
+            // oxlint-disable-next-line no-loop-func -- stop hook continuation state is scoped to this turn.
+            shouldContinueAfterStop: async ({ signal }) => {
+              if (this.flushSteerBuffer()) return { continue: true };
+              signal.throwIfAborted();
+
+              // Stop hooks get one continuation; otherwise a hook that always blocks would loop forever.
+              if (stopHookContinuationUsed) return { continue: false };
+              const stopBlock = await this.agent.hooks?.triggerBlock('Stop', {
+                signal,
+                inputData: { stopHookActive: stopHookContinuationUsed },
+              });
+              signal.throwIfAborted();
+              if (stopBlock !== undefined) {
+                stopHookContinuationUsed = true;
+                this.agent.context.appendUserMessage(
+                  [{ type: 'text', text: stopBlock.reason }],
+                  {
+                    kind: 'system_trigger',
+                    name: 'stop_hook',
+                  },
+                );
+                return { continue: true };
+              }
+              return { continue: false };
+            },
+            prepareToolExecution: async (ctx) => {
+              const cached = deduper.checkSameStep(
+                ctx.toolCall.id,
+                ctx.toolCall.function.name,
+                ctx.args,
+              );
+              if (cached !== null) return { syntheticResult: cached };
+              const hookResult = await this.agent.hooks?.triggerBlock('PreToolUse', {
+                matcherValue: ctx.toolCall.function.name,
+                signal: ctx.signal,
+                inputData: {
+                  toolName: ctx.toolCall.function.name,
+                  toolInput: toolInputRecord(ctx.args),
+                  toolCallId: ctx.toolCall.id,
+                },
+              });
+              ctx.signal.throwIfAborted();
+              if (hookResult) {
+                this.agent.telemetry.track('hook_triggered', {
+                  event_type: 'PreToolUse',
+                  action: hookResult.block ? 'block' : 'allow',
+                });
+                return hookResult;
+              }
+              const permissionResult = await this.agent.permission.beforeToolCall(ctx);
+              this.agent.telemetry.track('hook_triggered', {
+                event_type: 'PreToolUse',
+                action: permissionResult?.block === true ? 'block' : 'allow',
+              });
+              return permissionResult;
+            },
+            finalizeToolResult: async (ctx) => {
+              // Resolve dedup BEFORE firing the PostToolUse hook so same-step
+              // dups (whose ctx.result is the dedup placeholder) report the
+              // original's real outcome, not an empty success.
+              const finalResult = await deduper.finalizeResult(
+                ctx.toolCall.id,
+                ctx.toolCall.function.name,
+                ctx.args,
+                ctx.result,
+              );
+              const { isError, output } = finalResult;
+              const event = isError === true ? 'PostToolUseFailure' : 'PostToolUse';
+              void this.agent.hooks?.fireAndForgetTrigger(event, {
+                matcherValue: ctx.toolCall.function.name,
+                inputData: {
+                  toolName: ctx.toolCall.function.name,
+                  toolInput: toolInputRecord(ctx.args),
+                  toolCallId: ctx.toolCall.id,
+                  error: isError === true ? toKimiErrorPayload(toolOutputText(output)) : undefined,
+                  toolOutput: isError === true ? undefined : toolOutputText(output).slice(0, 2000),
+                },
+              });
+              return finalResult;
+            },
+          },
+        });
+
+        return result.stopReason;
+      } catch (error) {
+        if (
+          error instanceof APIContextOverflowError ||
+          (isKimiError(error) && error.code === ErrorCodes.CONTEXT_OVERFLOW)
+        ) {
+          await this.agent.fullCompaction.handleOverflowError(signal, error);
+          continue; // Retry with compacted context
+        }
+        if (isMaxStepsExceededError(error)) {
+          this.agent.log.warn('turn hit max steps', {
+            turnId,
+            steps: this.currentStepByTurn.get(turnId) ?? this.currentStep,
+            limit: isKimiError(error) ? error.details?.['maxSteps'] : undefined,
+          });
+        } else {
+          this.agent.log.error('turn failed', { turnId, error });
+        }
+        throw error;
+      }
+    }
+  }
+
+  private buildDispatchEvent(turnId: number) {
+    return createLoopEventDispatcher({
+      appendTranscriptRecord: async (event: LoopRecordedEvent) => {
+        this.agent.context.appendLoopEvent(event);
+      },
+      emitLiveEvent: (event: LoopEvent) => {
+        this.trackLoopTelemetry(event, turnId);
+        const mapped = mapLoopEvent(event, turnId);
+        if (mapped !== undefined) this.agent.emitEvent(mapped);
+      },
+    });
+  }
+
+  private trackLoopTelemetry(event: LoopEvent, turnId: number): void {
+    if (event.type === 'step.begin') {
+      this.beginTrackedStep(turnId, event.step);
+      return;
+    }
+    if (event.type === 'turn.interrupted') {
+      if (event.reason === 'error' && event.activeStep !== undefined) {
+        this.stepFailureByTurn.set(turnId, event);
+      }
+      this.trackTurnInterrupted(turnId, interruptedStep(event));
+      return;
+    }
+    this.trackToolLifecycle(event, turnId);
+  }
+
+  private beginTrackedStep(turnId: number, step: number): void {
+    this.currentStepByTurn.set(turnId, step);
+    this.currentStep = step;
+    if (!this.stepToolCallKeys.has(step)) {
+      this.stepToolCallKeys.set(step, new Set());
+    }
+  }
+
+  private trackToolLifecycle(event: LoopEvent, turnId: number): void {
+    if (event.type === 'tool.call') {
+      const dupType = this.trackDuplicateToolCall(turnId, event.step, event.name, event.args);
+      this.toolCallDupType.set(
+        event.toolCallId,
+        dupType === 'cross_step' ? 'cross_step' : 'normal',
+      );
+      this.toolCallStartedAt.set(event.toolCallId, {
+        name: event.name,
+        startedAt: Date.now(),
+      });
+      return;
+    }
+    if (event.type === 'tool.result') {
+      const started = this.toolCallStartedAt.get(event.toolCallId);
+      if (started === undefined) return;
+      this.toolCallStartedAt.delete(event.toolCallId);
+      const dupType = this.toolCallDupType.get(event.toolCallId) ?? 'normal';
+      this.toolCallDupType.delete(event.toolCallId);
+      const outcome = telemetryToolOutcome(event.result);
+      const properties: Record<string, TelemetryPropertyValue> = {
+        tool_name: started.name,
+        outcome,
+        duration_ms: Date.now() - started.startedAt,
+        dup_type: dupType,
+      };
+      const errorType = outcome === 'error' ? telemetryToolErrorType(event.result) : undefined;
+      if (errorType !== undefined) {
+        properties['error_type'] = errorType;
+      }
+      this.agent.telemetry.track('tool_call', properties);
+    }
+  }
+
+  private trackDuplicateToolCall(
+    turnId: number,
+    step: number,
+    toolName: string,
+    args: unknown,
+  ): 'normal' | 'same_step' | 'cross_step' {
+    const argsText = canonicalTelemetryArgs(args);
+    const key = `${toolName}\u0000${argsText}`;
+    const stepKeys = this.stepToolCallKeys.get(step) ?? new Set<string>();
+    this.stepToolCallKeys.set(step, stepKeys);
+
+    let dupType: 'same_step' | 'cross_step' | undefined;
+    if (stepKeys.has(key)) {
+      dupType = 'same_step';
+    } else if (this.hasPriorStepToolCallKey(step, key)) {
+      dupType = 'cross_step';
+    }
+
+    stepKeys.add(key);
+    if (dupType === undefined) return 'normal';
+
+    this.agent.telemetry.track('tool_call_dedup_detected', {
+      turn_id: turnId,
+      step_no: step,
+      tool_name: toolName,
+      dup_type: dupType,
+      args_hash: createHash('sha256').update(argsText).digest('hex').slice(0, 8),
+    });
+    return dupType;
+  }
+
+  private hasPriorStepToolCallKey(step: number, key: string): boolean {
+    for (const [seenStep, keys] of this.stepToolCallKeys) {
+      if (seenStep !== step && keys.has(key)) return true;
+    }
+    return false;
+  }
+
+  private trackTurnInterrupted(turnId: number, atStep: number): void {
+    if (this.interruptedTelemetryTurnIds.has(turnId)) return;
+    this.interruptedTelemetryTurnIds.add(turnId);
+    this.agent.telemetry.track('turn_interrupted', {
+      mode: this.telemetryModeByTurn.get(turnId) ?? this.telemetryMode(),
+      at_step: atStep,
+    });
+  }
+
+  private telemetryMode(): 'agent' | 'plan' {
+    return this.agent.planMode.isActive ? 'plan' : 'agent';
+  }
+
+  private shouldTrackApiError(turnId: number): boolean {
+    const failure = this.stepFailureByTurn.get(turnId);
+    return failure?.reason === 'error' && failure.activeStep !== undefined;
+  }
+}
+
+function mapLoopEvent(event: LoopEvent, turnId: number): AgentEvent | undefined {
+  switch (event.type) {
+    case 'step.begin':
+      return {
+        type: 'turn.step.started',
+        turnId,
+        step: event.step,
+        stepId: event.uuid,
+      };
+    case 'step.end':
+      return {
+        type: 'turn.step.completed',
+        turnId,
+        step: event.step,
+        stepId: event.uuid,
+        usage: event.usage,
+        finishReason: event.finishReason,
+        providerFinishReason: event.providerFinishReason,
+        rawFinishReason: event.rawFinishReason,
+      };
+    case 'step.retrying':
+      return {
+        type: 'turn.step.retrying',
+        turnId,
+        step: event.step,
+        stepId: event.stepUuid,
+        failedAttempt: event.failedAttempt,
+        nextAttempt: event.nextAttempt,
+        maxAttempts: event.maxAttempts,
+        delayMs: event.delayMs,
+        errorName: event.errorName,
+        errorMessage: event.errorMessage,
+        statusCode: event.statusCode,
+      };
+    case 'content.part':
+      return undefined;
+    case 'tool.call':
+      return {
+        type: 'tool.call.started',
+        turnId,
+        toolCallId: event.toolCallId,
+        name: event.name,
+        args: event.args,
+        description: event.description,
+        display: event.display,
+      };
+    case 'tool.result':
+      return {
+        type: 'tool.result',
+        turnId,
+        toolCallId: event.toolCallId,
+        output: event.result.output,
+        isError: event.result.isError,
+      };
+    case 'turn.interrupted':
+      if (event.activeStep === undefined) return undefined;
+      return {
+        type: 'turn.step.interrupted',
+        turnId,
+        step: event.activeStep,
+        reason: event.reason,
+        message: event.message,
+      };
+    case 'text.delta':
+      return {
+        type: 'assistant.delta',
+        turnId,
+        delta: event.delta,
+      };
+    case 'thinking.delta':
+      return {
+        type: 'thinking.delta',
+        turnId,
+        delta: event.delta,
+      };
+    case 'tool.call.delta':
+      return {
+        type: 'tool.call.delta',
+        turnId,
+        toolCallId: event.toolCallId,
+        name: event.name,
+        argumentsPart: event.argumentsPart,
+      };
+    case 'tool.progress':
+      return {
+        type: 'tool.progress',
+        turnId,
+        toolCallId: event.toolCallId,
+        update: event.update,
+      };
+  }
+}
+
+function summarizeTurnError(error: unknown, turnId: number): KimiErrorPayload {
+  const payload = toKimiErrorPayload(error);
+  const details = { ...payload.details, turnId };
+
+  // Substitute a friendlier TUI-aware message for model-not-configured.
+  // Raw kosong text ("Model not set" / "Provider not set") is not
+  // actionable; this string points the user at the login flow.
+  if (payload.code === 'model.not_configured') {
+    return { ...payload, message: LLM_NOT_SET_MESSAGE, details };
+  }
+
+  return { ...payload, details };
+}
+
+function toolInputRecord(args: unknown): Record<string, unknown> {
+  return isPlainRecord(args) ? args : {};
+}
+
+function toolOutputText(output: ExecutableToolResult['output']): string {
+  if (typeof output === 'string') return output;
+  return output
+    .filter((part): part is Extract<(typeof output)[number], { type: 'text' }> => {
+      return typeof part === 'object' && part !== null && part.type === 'text';
+    })
+    .map((part) => part.text)
+    .join('');
+}
+
+function interruptedStep(event: LoopTurnInterruptedEvent): number {
+  return event.activeStep ?? event.attemptedSteps;
+}
+
+interface ApiErrorClassification {
+  readonly errorType: string;
+  readonly statusCode?: number;
+}
+
+function classifyApiError(error: unknown, summary: KimiErrorPayload): ApiErrorClassification {
+  const statusCode = apiStatusCode(error) ?? summaryStatusCode(summary);
+  if (statusCode !== undefined) {
+    if (statusCode === 429) return { errorType: 'rate_limit', statusCode };
+    if (statusCode === 401 || statusCode === 403) return { errorType: 'auth', statusCode };
+    if (statusCode >= 500) return { errorType: '5xx_server', statusCode };
+    if (isContextOverflowMessage(summary.message)) {
+      return { errorType: 'context_overflow', statusCode };
+    }
+    if (statusCode >= 400) return { errorType: '4xx_client', statusCode };
+    return { errorType: 'api', statusCode };
+  }
+
+  if (summary.code === ErrorCodes.PROVIDER_RATE_LIMIT) return { errorType: 'rate_limit' };
+  if (summary.code === ErrorCodes.PROVIDER_AUTH_ERROR) return { errorType: 'auth' };
+  if (summary.code === ErrorCodes.CONTEXT_OVERFLOW) return { errorType: 'context_overflow' };
+  if (isApiConnectionError(error, summary)) return { errorType: 'network' };
+  if (isApiTimeoutError(error, summary)) return { errorType: 'timeout' };
+  if (isApiEmptyResponseError(error, summary)) return { errorType: 'empty_response' };
+  return { errorType: 'other' };
+}
+
+function apiStatusCode(error: unknown): number | undefined {
+  if (error instanceof APIStatusError) {
+    const statusCode = (error as { readonly statusCode?: unknown }).statusCode;
+    return typeof statusCode === 'number' ? statusCode : undefined;
+  }
+  if (typeof error !== 'object' || error === null) return undefined;
+  const statusCode = (error as { readonly statusCode?: unknown }).statusCode;
+  if (typeof statusCode === 'number') return statusCode;
+  const status = (error as { readonly status?: unknown }).status;
+  return typeof status === 'number' ? status : undefined;
+}
+
+function summaryStatusCode(summary: KimiErrorPayload): number | undefined {
+  const statusCode = summary.details?.['statusCode'];
+  return typeof statusCode === 'number' ? statusCode : undefined;
+}
+
+function isApiConnectionError(error: unknown, summary: KimiErrorPayload): boolean {
+  return error instanceof APIConnectionError || summary.name === 'APIConnectionError';
+}
+
+function isApiTimeoutError(error: unknown, summary: KimiErrorPayload): boolean {
+  return (
+    error instanceof APITimeoutError ||
+    summary.name === 'APITimeoutError' ||
+    summary.name === 'TimeoutError'
+  );
+}
+
+function isApiEmptyResponseError(error: unknown, summary: KimiErrorPayload): boolean {
+  return error instanceof APIEmptyResponseError || summary.name === 'APIEmptyResponseError';
+}
+
+function isContextOverflowMessage(message: string): boolean {
+  const lower = message.toLowerCase();
+  return (
+    lower.includes('context length') ||
+    lower.includes('context_length') ||
+    lower.includes('max tokens') ||
+    lower.includes('maximum context') ||
+    lower.includes('too many tokens')
+  );
+}
+
+function currentTurnInputTokens(usage: TokenUsage | undefined): number | undefined {
+  if (usage === undefined) return undefined;
+  return inputTotal(usage);
+}
+
+type ToolTelemetryResult = Extract<LoopEvent, { type: 'tool.result' }>['result'];
+
+function telemetryToolOutcome(result: ToolTelemetryResult): 'success' | 'error' | 'cancelled' {
+  if (result.isError !== true) return 'success';
+  const text = toolResultText(result).toLowerCase();
+  return text.includes('aborted') || text.includes('cancelled') ? 'cancelled' : 'error';
+}
+
+function telemetryToolErrorType(result: ToolTelemetryResult): string {
+  const text = toolResultText(result);
+  if (text.startsWith('Tool "') && text.includes('" not found')) return 'ToolNotFound';
+  if (text.startsWith('Invalid args for tool "')) return 'ToolInputError';
+  if (text.includes('prepareToolExecution hook failed')) return 'HookError';
+  if (text.includes('finalizeToolResult hook failed')) return 'HookError';
+  if (text.includes('blocked')) return 'ToolBlocked';
+  return 'ToolError';
+}
+
+function toolResultText(result: ToolTelemetryResult): string {
+  return toolOutputText(result.output);
+}
diff --git a/packages/agent-core/src/agent/turn/kosong-llm.ts b/packages/agent-core/src/agent/turn/kosong-llm.ts
new file mode 100644
index 000000000..834fa4712
--- /dev/null
+++ b/packages/agent-core/src/agent/turn/kosong-llm.ts
@@ -0,0 +1,254 @@
+/**
+ * Kosong-backed implementation of the loop `LLM` interface.
+ *
+ * Bridges the new `loop/llm.ts` contract onto
+ * the kosong `generate()` streaming API:
+ *
+ *   - kosong's per-part `onMessagePart` is forwarded to loop per-delta
+ *     callbacks (`onTextDelta`, `onThinkDelta`, `onToolCallDelta`).
+ *   - loop per-block callbacks (`onTextPart`, `onThinkPart`) only fire
+ *     after the kosong stream drains, iterating over the merged
+ *     `result.message.content`. Completed
+ *     blocks land on the WAL seam, raw deltas never do.
+ *   - kosong's finish reasons are preserved as provider diagnostics. The loop
+ *     derives loop control from the normalized response shape, not from the
+ *     provider's finish-reason spelling.
+ */
+
+import {
+  APIConnectionError,
+  APIEmptyResponseError,
+  APIStatusError,
+  APITimeoutError,
+  emptyUsage,
+  generate as kosongGenerate,
+  type ChatProvider,
+  type GenerateCallbacks,
+  type Message,
+  type ModelCapability,
+  type StreamedMessagePart,
+} from '@moonshot-ai/kosong';
+
+import type { LLM, LLMChatParams, LLMChatResponse, LLMRequestLogContext } from '../../loop';
+import {
+  applyCompletionBudget,
+  type CompletionBudget,
+} from '../../utils/completion-budget';
+
+export const GENERATE_REQUEST_LOG_CONTEXT = '__kimiRequestLogContext';
+
+export type GenerateOptionsWithRequestLog = {
+  readonly signal?: AbortSignal;
+  readonly [GENERATE_REQUEST_LOG_CONTEXT]?: LLMRequestLogContext;
+};
+
+export type GenerateFn = typeof kosongGenerate;
+
+export interface KosongLLMConfig {
+  readonly provider: ChatProvider;
+  readonly modelName: string;
+  readonly systemPrompt: string;
+  readonly capability?: ModelCapability | undefined;
+  /**
+   * Optional override for the kosong `generate()` entry point. Lets the
+   * agent host (and its test harness) inject a scripted generator without
+   * having to substitute the entire LLM implementation.
+   */
+  readonly generate?: GenerateFn | undefined;
+  /**
+   * Per-request completion-token budget. When set, each `chat()` call
+   * clones the configured provider with a clamped `max_completion_tokens`
+   * derived from the current input size and model context window. The
+   * clone is local to the call and never replaces `this.provider`.
+   */
+  readonly completionBudget?: CompletionBudget | undefined;
+}
+
+export class KosongLLM implements LLM {
+  readonly systemPrompt: string;
+  readonly modelName: string;
+  readonly capability?: ModelCapability | undefined;
+
+  private readonly provider: ChatProvider;
+  private readonly generate: GenerateFn;
+  private readonly completionBudget: CompletionBudget | undefined;
+
+  constructor(config: KosongLLMConfig) {
+    this.provider = config.provider;
+    this.modelName = config.modelName;
+    this.systemPrompt = config.systemPrompt;
+    this.capability = config.capability;
+    this.generate = config.generate ?? kosongGenerate;
+    this.completionBudget = config.completionBudget;
+  }
+
+  async chat(params: LLMChatParams): Promise<LLMChatResponse> {
+    return this.chatOnce(params);
+  }
+
+  private async chatOnce(params: LLMChatParams): Promise<LLMChatResponse> {
+    const callbacks = buildKosongCallbacks(params);
+
+    // Compute and apply the per-request completion budget against a
+    // throwaway shallow clone. `effectiveProvider` is local to this call
+    // and never written back to `this.provider`, so retries (handled at
+    // a higher layer) keep using the same long-lived provider/client.
+    // The clamp must see every input the provider will serialize on the
+    // wire — system prompt and tool schemas included — or a near-full
+    // context can still slip past the limit.
+    const effectiveProvider = applyCompletionBudget({
+      provider: this.provider,
+      budget: this.completionBudget,
+      capability: this.capability,
+      messages: params.messages,
+      systemPrompt: this.systemPrompt,
+      tools: params.tools,
+    });
+
+    const result = await this.generate(
+      effectiveProvider,
+      this.systemPrompt,
+      [...params.tools],
+      [...params.messages],
+      callbacks,
+      generateOptions(params),
+    );
+
+    // Replay merged content parts onto loop per-block callbacks after the
+    // stream drained. This preserves WAL append order and stops partial
+    // parts from landing if the upstream stream aborts mid-message.
+    if (params.onTextPart !== undefined || params.onThinkPart !== undefined) {
+      for (const part of result.message.content) {
+        if (part.type === 'text' && params.onTextPart !== undefined) {
+          await params.onTextPart(part);
+        } else if (part.type === 'think' && params.onThinkPart !== undefined) {
+          await params.onThinkPart(part);
+        }
+      }
+    }
+
+    const response: LLMChatResponse = {
+      toolCalls: [...result.message.toolCalls],
+      ...(result.finishReason !== null ? { providerFinishReason: result.finishReason } : {}),
+      ...(result.rawFinishReason !== null ? { rawFinishReason: result.rawFinishReason } : {}),
+      usage: result.usage ?? emptyUsage(),
+    };
+
+    return response;
+  }
+
+  isRetryableError(error: unknown): boolean {
+    if (error instanceof APIConnectionError || error instanceof APITimeoutError) {
+      return true;
+    }
+    if (error instanceof APIEmptyResponseError) {
+      return true;
+    }
+    return error instanceof APIStatusError && [429, 500, 502, 503, 504].includes(error.statusCode);
+  }
+}
+
+function generateOptions(params: LLMChatParams): GenerateOptionsWithRequestLog {
+  const options: GenerateOptionsWithRequestLog = {
+    signal: params.signal,
+  };
+  if (params.requestLogContext !== undefined) {
+    return {
+      ...options,
+      [GENERATE_REQUEST_LOG_CONTEXT]: params.requestLogContext,
+    };
+  }
+  return options;
+}
+
+function buildKosongCallbacks(params: LLMChatParams): GenerateCallbacks {
+  type ToolCallIdentity = { readonly toolCallId: string; readonly name: string };
+  type BufferedToolCallDelta = { readonly argumentsPart?: string | undefined };
+
+  const toolCallIdentities = new Map<number | string, ToolCallIdentity>();
+  const pendingIndexedToolCallDeltas = new Map<number | string, BufferedToolCallDelta[]>();
+  let lastToolCallIdentity: ToolCallIdentity | undefined;
+
+  const emitToolCallDelta = (delta: {
+    toolCallId: string;
+    name: string;
+    argumentsPart?: string;
+  }): void => {
+    if (params.onToolCallDelta === undefined) return;
+    params.onToolCallDelta(delta);
+  };
+
+  return {
+    onMessagePart: (part: StreamedMessagePart) => {
+      if (part.type === 'text') {
+        if (params.onTextDelta === undefined) return;
+        params.onTextDelta(part.text);
+        return;
+      }
+      if (part.type === 'think') {
+        if (params.onThinkDelta === undefined) return;
+        params.onThinkDelta(part.think);
+        return;
+      }
+      if (part.type === 'function') {
+        const identity = { toolCallId: part.id, name: part.function.name };
+        lastToolCallIdentity = identity;
+        if (part._streamIndex !== undefined) {
+          toolCallIdentities.set(part._streamIndex, identity);
+        }
+        emitToolCallDelta({
+          toolCallId: part.id,
+          name: part.function.name,
+          ...(part.function.arguments !== null ? { argumentsPart: part.function.arguments } : {}),
+        });
+        if (part._streamIndex !== undefined) {
+          const pendingDeltas = pendingIndexedToolCallDeltas.get(part._streamIndex);
+          if (pendingDeltas !== undefined) {
+            pendingIndexedToolCallDeltas.delete(part._streamIndex);
+            for (const delta of pendingDeltas) {
+              emitToolCallDelta({
+                toolCallId: identity.toolCallId,
+                name: identity.name,
+                ...delta,
+              });
+            }
+          }
+        }
+        return;
+      }
+      if (part.type === 'tool_call_part') {
+        const argumentsPart = part.argumentsPart;
+        const delta = argumentsPart !== null ? { argumentsPart } : {};
+        if (part.index !== undefined) {
+          const identity = toolCallIdentities.get(part.index);
+          if (identity === undefined) {
+            const pendingDeltas = pendingIndexedToolCallDeltas.get(part.index) ?? [];
+            pendingDeltas.push(delta);
+            pendingIndexedToolCallDeltas.set(part.index, pendingDeltas);
+            return;
+          }
+          emitToolCallDelta({
+            toolCallId: identity.toolCallId,
+            name: identity.name,
+            ...delta,
+          });
+          return;
+        }
+        const identity = lastToolCallIdentity;
+        if (identity === undefined) return;
+        emitToolCallDelta({
+          toolCallId: identity.toolCallId,
+          name: identity.name,
+          ...delta,
+        });
+      }
+    },
+  };
+}
+
+export function buildMessagesWithSystem(systemPrompt: string, history: Message[]): Message[] {
+  return [
+    { role: 'system', content: [{ type: 'text', text: systemPrompt }], toolCalls: [] },
+    ...history,
+  ];
+}
diff --git a/packages/agent-core/src/agent/turn/tool-dedup.ts b/packages/agent-core/src/agent/turn/tool-dedup.ts
new file mode 100644
index 000000000..c360589aa
--- /dev/null
+++ b/packages/agent-core/src/agent/turn/tool-dedup.ts
@@ -0,0 +1,195 @@
+import type { ContentPart } from '@moonshot-ai/kosong';
+
+import type { ExecutableToolResult } from '../../loop/types';
+
+import { canonicalTelemetryArgs } from './canonical-args';
+
+const CROSS_STEP_DEDUP_TRIGGER_COUNT = 7;
+
+const REMINDER_TEXT =
+  '\n\n<system-reminder>\n' +
+  'You are repeating the exact same tool call with identical parameters.' +
+  ' Please carefully analyze the previous result. If the task is not yet complete,' +
+  ' try a different method or parameters instead of repeating the same call.' +
+  '\n</system-reminder>';
+
+interface Deferred<T> {
+  readonly promise: Promise<T>;
+  resolve(value: T): void;
+}
+
+function makeDeferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
+
+function makeKey(toolName: string, args: unknown): string {
+  return `${toolName} ${canonicalTelemetryArgs(args)}`;
+}
+
+function appendReminder(result: ExecutableToolResult): ExecutableToolResult {
+  const output = result.output;
+  let newOutput: string | ContentPart[];
+  if (typeof output === 'string') {
+    newOutput = output + REMINDER_TEXT;
+  } else {
+    const arr: ContentPart[] = [...output];
+    const last = arr.at(-1);
+    if (last !== undefined && last.type === 'text') {
+      arr[arr.length - 1] = { type: 'text', text: last.text + REMINDER_TEXT };
+    } else {
+      arr.push({ type: 'text', text: REMINDER_TEXT });
+    }
+    newOutput = arr;
+  }
+  return result.isError === true
+    ? { ...result, output: newOutput, isError: true }
+    : { ...result, output: newOutput };
+}
+
+/**
+ * Placeholder result returned from `checkSameStep` for a duplicate call. Never
+ * reaches the model — it is replaced in `finalizeResult` by awaiting the
+ * original's deferred result. The loop dispatches `tool.result` events using
+ * the finalized value, so this content is purely internal bookkeeping.
+ *
+ * It must be a non-error result so `toolResultStopsTurn` in tool-call.ts does
+ * not short-circuit the batch on the dup's behalf.
+ */
+const DEDUP_PLACEHOLDER_RESULT: ExecutableToolResult = { output: '' };
+
+/**
+ * Detects and suppresses repetitive tool calls within a single turn.
+ *
+ * Two behaviours are layered:
+ * - Same-step dedup: a duplicate `(toolName, args)` issued in the same LLM step
+ *   reuses the original call's result instead of executing the tool twice.
+ * - Cross-step dedup: when the exact same call is repeated for
+ *   `CROSS_STEP_DEDUP_TRIGGER_COUNT` consecutive occurrences (counting across
+ *   steps), the result returned to the model is suffixed with a system reminder
+ *   nudging it to try a different approach.
+ */
+export class ToolCallDeduplicator {
+  private stepDeferreds = new Map<string, Deferred<ExecutableToolResult>>();
+  private stepCalls: string[] = [];
+  private originalCallIndex = new Map<string, number>();
+  private syntheticCallIds = new Set<string>();
+  /**
+   * Records the dedup key used at `checkSameStep` time, keyed by `toolCallId`.
+   * The loop is allowed to rewrite args between `prepareToolExecution` and
+   * `finalizeToolResult` via `PrepareToolExecutionResult.updatedArgs`, so the
+   * `(toolName, args)` pair available at finalize may differ from what was
+   * registered. We pin the key at registration time and look it up by call id
+   * during finalize.
+   */
+  private callKeyByCallId = new Map<string, string>();
+  private consecutiveKey: string | null = null;
+  private consecutiveCount = 0;
+
+  beginStep(): void {
+    for (const deferred of this.stepDeferreds.values()) {
+      deferred.resolve({
+        output: 'Tool call deduplicated but original result was lost',
+        isError: true,
+      });
+    }
+    this.stepDeferreds.clear();
+    this.stepCalls = [];
+    this.originalCallIndex.clear();
+    this.syntheticCallIds.clear();
+    this.callKeyByCallId.clear();
+  }
+
+  endStep(): void {
+    for (const key of this.stepCalls) {
+      if (key === this.consecutiveKey) {
+        this.consecutiveCount += 1;
+      } else {
+        this.consecutiveKey = key;
+        this.consecutiveCount = 1;
+      }
+    }
+  }
+
+  /**
+   * Called from `prepareToolExecution`. If this `(toolName, args)` was already
+   * seen in the current step, returns a placeholder result so the loop can
+   * skip executing the tool again; the real result is patched in during
+   * `finalizeResult`. Returns `null` for the first occurrence so the normal
+   * execution path proceeds.
+   *
+   * This method is intentionally synchronous to avoid deadlocking the prepare
+   * loop on a deferred that only resolves in the finalize phase.
+   */
+  checkSameStep(toolCallId: string, toolName: string, args: unknown): ExecutableToolResult | null {
+    const key = makeKey(toolName, args);
+    const index = this.stepCalls.length;
+    this.stepCalls.push(key);
+    this.callKeyByCallId.set(toolCallId, key);
+
+    const existing = this.stepDeferreds.get(key);
+    if (existing !== undefined) {
+      this.syntheticCallIds.add(toolCallId);
+      return DEDUP_PLACEHOLDER_RESULT;
+    }
+    this.stepDeferreds.set(key, makeDeferred<ExecutableToolResult>());
+    this.originalCallIndex.set(toolCallId, index);
+    return null;
+  }
+
+  /**
+   * Called from `finalizeToolResult`, in provider order. For first-occurrence
+   * calls, projects the consecutive streak ending at this call and, if the
+   * threshold is reached, appends the system reminder, then resolves the
+   * deferred so subsequent same-step dups can fetch the real result. For
+   * synthetic duplicates, awaits the original's deferred and returns its
+   * value, discarding the placeholder.
+   */
+  async finalizeResult(
+    toolCallId: string,
+    _toolName: string,
+    _args: unknown,
+    result: ExecutableToolResult,
+  ): Promise<ExecutableToolResult> {
+    // Use the key recorded at registration time, NOT a fresh key from the args
+    // passed here — the loop may have rewritten args via updatedArgs.
+    const key = this.callKeyByCallId.get(toolCallId);
+    if (key === undefined) return result;
+    this.callKeyByCallId.delete(toolCallId);
+
+    if (this.syntheticCallIds.delete(toolCallId)) {
+      const deferred = this.stepDeferreds.get(key);
+      if (deferred === undefined) return result;
+      return deferred.promise;
+    }
+    const index = this.originalCallIndex.get(toolCallId);
+    if (index === undefined) return result;
+    this.originalCallIndex.delete(toolCallId);
+
+    let lastKey = this.consecutiveKey;
+    let streak = this.consecutiveCount;
+    for (let i = 0; i <= index; i += 1) {
+      const k = this.stepCalls[i]!;
+      if (k === lastKey) {
+        streak += 1;
+      } else {
+        lastKey = k;
+        streak = 1;
+      }
+    }
+
+    const finalResult =
+      streak >= CROSS_STEP_DEDUP_TRIGGER_COUNT ? appendReminder(result) : result;
+
+    this.stepDeferreds.get(key)?.resolve(finalResult);
+    return finalResult;
+  }
+}
+
+export const __testing = {
+  CROSS_STEP_DEDUP_TRIGGER_COUNT,
+  REMINDER_TEXT,
+};
diff --git a/packages/agent-core/src/agent/usage/index.ts b/packages/agent-core/src/agent/usage/index.ts
new file mode 100644
index 000000000..e978e7d56
--- /dev/null
+++ b/packages/agent-core/src/agent/usage/index.ts
@@ -0,0 +1,79 @@
+import type { UsageStatus } from '#/rpc';
+import { addUsage, type TokenUsage } from '@moonshot-ai/kosong';
+
+import type { Agent } from '..';
+
+export type UsageRecordScope = 'session' | 'turn';
+
+function copyUsage(usage: TokenUsage): TokenUsage {
+  return { ...usage };
+}
+
+export class UsageRecorder {
+  private readonly byModel: Record<string, TokenUsage> = {};
+  private currentTurn: TokenUsage | undefined;
+
+  constructor(protected readonly agent?: Agent) {}
+
+  beginTurn(): void {
+    this.currentTurn = undefined;
+  }
+
+  endTurn(): void {
+    this.currentTurn = undefined;
+  }
+
+  record(model: string, usage: TokenUsage, scope: UsageRecordScope = 'session'): void {
+    this.agent?.records.logRecord({
+      type: 'usage.record',
+      model,
+      usage,
+      usageScope: scope,
+    });
+    const current = this.byModel[model];
+    this.byModel[model] = current === undefined ? copyUsage(usage) : addUsage(current, usage);
+
+    if (scope === 'turn') {
+      this.currentTurn =
+        this.currentTurn === undefined ? copyUsage(usage) : addUsage(this.currentTurn, usage);
+    }
+    this.agent?.emitStatusUpdated();
+  }
+
+  data(): UsageStatus {
+    const byModel = this.byModelSnapshot();
+    const hasByModel = Object.keys(byModel).length > 0;
+    const currentTurn = this.currentTurn;
+    return {
+      byModel: hasByModel ? byModel : undefined,
+      total: hasByModel ? totalUsage(byModel) : undefined,
+      currentTurn: currentTurn === undefined ? undefined : copyUsage(currentTurn),
+    };
+  }
+
+  status(): UsageStatus | undefined {
+    const status = this.data();
+    if (
+      status.byModel === undefined &&
+      status.total === undefined &&
+      status.currentTurn === undefined
+    ) {
+      return undefined;
+    }
+    return status;
+  }
+
+  private byModelSnapshot(): Record<string, TokenUsage> {
+    return Object.fromEntries(
+      Object.entries(this.byModel).map(([model, usage]) => [model, copyUsage(usage)]),
+    );
+  }
+}
+
+function totalUsage(byModel: Record<string, TokenUsage>): TokenUsage | undefined {
+  let total: TokenUsage | undefined;
+  for (const usage of Object.values(byModel)) {
+    total = total === undefined ? copyUsage(usage) : addUsage(total, usage);
+  }
+  return total;
+}
diff --git a/packages/agent-core/src/config/index.ts b/packages/agent-core/src/config/index.ts
new file mode 100644
index 000000000..e9b03330f
--- /dev/null
+++ b/packages/agent-core/src/config/index.ts
@@ -0,0 +1,5 @@
+export * from './merge';
+export * from './path';
+export * from './resolve';
+export * from './schema';
+export * from './toml';
diff --git a/packages/agent-core/src/config/merge.ts b/packages/agent-core/src/config/merge.ts
new file mode 100644
index 000000000..ce4880b96
--- /dev/null
+++ b/packages/agent-core/src/config/merge.ts
@@ -0,0 +1,62 @@
+import { ErrorCodes, KimiError } from '#/errors';
+import {
+  KimiConfigPatchSchema,
+  formatConfigValidationError,
+  type KimiConfig,
+  type KimiConfigPatch,
+  validateConfig,
+} from '#/config/schema';
+
+export function mergeConfigPatch(config: KimiConfig, patch: KimiConfigPatch): KimiConfig {
+  const base = validateConfig(config);
+  const parsedPatch = parsePatch(patch);
+  const merged = deepMerge(base, parsedPatch);
+  return validateConfig(merged);
+}
+
+function parsePatch(patch: KimiConfigPatch): KimiConfigPatch {
+  try {
+    return stripUndefinedDeep(KimiConfigPatchSchema.parse(patch)) as KimiConfigPatch;
+  } catch (error) {
+    throw new KimiError(ErrorCodes.CONFIG_INVALID, `Invalid configuration patch: ${formatConfigValidationError(error)}`, {
+      cause: error,
+    });
+  }
+}
+
+function deepMerge(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>,
+): Record<string, unknown> {
+  const result = { ...target };
+  for (const [key, sourceValue] of Object.entries(source)) {
+    if (sourceValue === undefined) continue;
+    const targetValue = result[key];
+    if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
+      result[key] = deepMerge(targetValue, sourceValue);
+    } else {
+      result[key] = sourceValue;
+    }
+  }
+  return result;
+}
+
+function stripUndefinedDeep(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(stripUndefinedDeep);
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  const out: Record<string, unknown> = {};
+  for (const [key, entryValue] of Object.entries(value)) {
+    if (entryValue !== undefined) {
+      out[key] = stripUndefinedDeep(entryValue);
+    }
+  }
+  return out;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
diff --git a/packages/agent-core/src/config/path.ts b/packages/agent-core/src/config/path.ts
new file mode 100644
index 000000000..d8d80f45b
--- /dev/null
+++ b/packages/agent-core/src/config/path.ts
@@ -0,0 +1,18 @@
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function resolveKimiHome(homeDir?: string | undefined): string {
+  return homeDir ?? process.env['KIMI_CODE_HOME'] ?? join(homedir(), '.kimi-code');
+}
+
+export function resolveConfigPath(input: {
+  readonly homeDir?: string | undefined;
+  readonly configPath?: string | undefined;
+}): string {
+  return input.configPath ?? join(resolveKimiHome(input.homeDir), 'config.toml');
+}
+
+export function ensureKimiHome(homeDir: string): void {
+  mkdirSync(homeDir, { recursive: true, mode: 0o700 });
+}
diff --git a/packages/agent-core/src/config/resolve.ts b/packages/agent-core/src/config/resolve.ts
new file mode 100644
index 000000000..dbe1f4635
--- /dev/null
+++ b/packages/agent-core/src/config/resolve.ts
@@ -0,0 +1,26 @@
+const TRUE_BOOLEAN_ENV_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const FALSE_BOOLEAN_ENV_VALUES = new Set(['0', 'false', 'no', 'off']);
+
+export interface ResolveConfigValueInput<T> {
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly envKey: string;
+  readonly configValue?: T;
+  readonly defaultValue: T;
+  readonly parseEnv: (value: string | undefined) => T | undefined;
+}
+
+export function resolveConfigValue<T>(input: ResolveConfigValueInput<T>): T {
+  return (
+    input.parseEnv(input.env?.[input.envKey]) ??
+    input.configValue ??
+    input.defaultValue
+  );
+}
+
+export function parseBooleanEnv(value: string | undefined): boolean | undefined {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === undefined || normalized.length === 0) return undefined;
+  if (TRUE_BOOLEAN_ENV_VALUES.has(normalized)) return true;
+  if (FALSE_BOOLEAN_ENV_VALUES.has(normalized)) return false;
+  return undefined;
+}
diff --git a/packages/agent-core/src/config/schema.ts b/packages/agent-core/src/config/schema.ts
new file mode 100644
index 000000000..5c334a564
--- /dev/null
+++ b/packages/agent-core/src/config/schema.ts
@@ -0,0 +1,279 @@
+import { HOOK_EVENT_TYPES } from '#/agent/hooks/types';
+import { parsePattern } from '#/agent/permission/parse-pattern';
+import { ErrorCodes, KimiError } from '#/errors';
+import { z } from 'zod';
+
+export const ProviderTypeSchema = z.enum([
+  'anthropic',
+  'openai',
+  'kimi',
+  'google-genai',
+  'openai_responses',
+  'vertexai',
+]);
+
+export type ProviderType = z.infer<typeof ProviderTypeSchema>;
+
+export const OAuthRefSchema = z.object({
+  storage: z.enum(['file', 'keyring']),
+  key: z.string().min(1),
+});
+
+export type OAuthRef = z.infer<typeof OAuthRefSchema>;
+
+const StringRecordSchema = z.record(z.string(), z.string());
+
+export const ProviderConfigSchema = z.object({
+  type: ProviderTypeSchema,
+  apiKey: z.string().optional(),
+  baseUrl: z.string().optional(),
+  defaultModel: z.string().optional(),
+  oauth: OAuthRefSchema.optional(),
+  env: StringRecordSchema.optional(),
+  customHeaders: StringRecordSchema.optional(),
+});
+
+export type ProviderConfig = z.infer<typeof ProviderConfigSchema>;
+
+export const ModelAliasSchema = z.object({
+  provider: z.string(),
+  model: z.string(),
+  maxContextSize: z.number().int().min(1),
+  maxOutputSize: z.number().int().min(1).optional(),
+  capabilities: z.array(z.string()).optional(),
+  displayName: z.string().optional(),
+});
+
+export type ModelAlias = z.infer<typeof ModelAliasSchema>;
+
+export const ThinkingConfigSchema = z.object({
+  mode: z.enum(['auto', 'on', 'off']).optional(),
+  effort: z.string().optional(),
+});
+
+export type ThinkingConfig = z.infer<typeof ThinkingConfigSchema>;
+
+export const PermissionModeSchema = z.enum(['yolo', 'manual', 'auto']);
+
+export const PermissionRuleDecisionSchema = z.enum(['allow', 'deny', 'ask']);
+export const PermissionRuleScopeSchema = z.enum([
+  'turn-override',
+  'session-runtime',
+  'project',
+  'user',
+]);
+
+export const PermissionRuleSchema = z.object({
+  decision: PermissionRuleDecisionSchema,
+  scope: PermissionRuleScopeSchema.default('user'),
+  pattern: z.string().min(1).refine(isValidPermissionPattern, {
+    message: 'Invalid permission rule pattern',
+  }),
+  reason: z.string().optional(),
+});
+
+export const PermissionConfigSchema = z.object({
+  rules: z.array(PermissionRuleSchema).optional(),
+});
+
+export type PermissionConfig = z.infer<typeof PermissionConfigSchema>;
+
+export const LoopControlSchema = z.object({
+  maxStepsPerTurn: z.number().int().min(1).optional(),
+  maxRetriesPerStep: z.number().int().min(0).optional(),
+  maxRalphIterations: z.number().int().min(-1).optional(),
+  reservedContextSize: z.number().int().min(0).optional(),
+  compactionTriggerRatio: z.number().min(0.5).max(0.99).optional(),
+});
+
+export type LoopControl = z.infer<typeof LoopControlSchema>;
+
+export const BackgroundConfigSchema = z.object({
+  maxRunningTasks: z.number().int().min(1).optional(),
+  keepAliveOnExit: z.boolean().optional(),
+  killGracePeriodMs: z.number().int().min(0).optional(),
+  agentTaskTimeoutS: z.number().int().min(1).optional(),
+  printWaitCeilingS: z.number().int().min(1).optional(),
+});
+
+export type BackgroundConfig = z.infer<typeof BackgroundConfigSchema>;
+
+export const HookDefSchema = z
+  .object({
+    event: z.enum(HOOK_EVENT_TYPES),
+    matcher: z.string().optional(),
+    command: z.string().min(1),
+    timeout: z.number().int().min(1).max(600).optional(),
+  })
+  .strict();
+
+export type HookDefConfig = z.infer<typeof HookDefSchema>;
+
+export const MoonshotServiceConfigSchema = z.object({
+  baseUrl: z.string().optional(),
+  apiKey: z.string().optional(),
+  oauth: OAuthRefSchema.optional(),
+  customHeaders: StringRecordSchema.optional(),
+});
+
+export type MoonshotServiceConfig = z.infer<typeof MoonshotServiceConfigSchema>;
+
+export const ServicesConfigSchema = z.object({
+  moonshotSearch: MoonshotServiceConfigSchema.optional(),
+  moonshotFetch: MoonshotServiceConfigSchema.optional(),
+});
+
+export type ServicesConfig = z.infer<typeof ServicesConfigSchema>;
+
+const McpServerCommonFields = {
+  enabled: z.boolean().optional(),
+  startupTimeoutMs: z.number().int().min(1).optional(),
+  toolTimeoutMs: z.number().int().min(1).optional(),
+  enabledTools: z.array(z.string()).optional(),
+  disabledTools: z.array(z.string()).optional(),
+} as const;
+
+export const McpServerStdioConfigSchema = z.object({
+  transport: z.literal('stdio'),
+  command: z.string().min(1),
+  args: z.array(z.string()).optional(),
+  env: StringRecordSchema.optional(),
+  cwd: z.string().optional(),
+  // Reserved for future kaos-backed stdio launchers. `undefined` and `'local'`
+  // both mean direct child_process spawn for now.
+  executor: z.enum(['local', 'kaos']).optional(),
+  ...McpServerCommonFields,
+});
+
+export type McpServerStdioConfig = z.infer<typeof McpServerStdioConfigSchema>;
+
+export const McpServerHttpConfigSchema = z.object({
+  transport: z.literal('http'),
+  url: z.string().url(),
+  headers: StringRecordSchema.optional(),
+  // Indirect secret reference: the bearer token is looked up from
+  // `process.env[bearerTokenEnvVar]` at connection time, never committed.
+  bearerTokenEnvVar: z.string().min(1).optional(),
+  ...McpServerCommonFields,
+});
+
+export type McpServerHttpConfig = z.infer<typeof McpServerHttpConfigSchema>;
+
+const McpServerConfigDiscriminatedSchema = z.discriminatedUnion('transport', [
+  McpServerStdioConfigSchema,
+  McpServerHttpConfigSchema,
+]);
+
+export const McpServerConfigSchema = z.preprocess((raw) => {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return raw;
+  const obj = raw as Record<string, unknown>;
+  if ('transport' in obj) return obj;
+  if (typeof obj['command'] === 'string') return { ...obj, transport: 'stdio' };
+  if (typeof obj['url'] === 'string') return { ...obj, transport: 'http' };
+  return obj;
+}, McpServerConfigDiscriminatedSchema);
+
+export type McpServerConfig = z.infer<typeof McpServerConfigSchema>;
+
+export const KimiConfigSchema = z.object({
+  providers: z.record(z.string(), ProviderConfigSchema).default({}),
+  defaultProvider: z.string().optional(),
+  defaultModel: z.string().optional(),
+  models: z.record(z.string(), ModelAliasSchema).optional(),
+  thinking: ThinkingConfigSchema.optional(),
+  planMode: z.boolean().optional(),
+  yolo: z.boolean().optional(),
+  defaultThinking: z.boolean().optional(),
+  defaultPermissionMode: PermissionModeSchema.optional(),
+  defaultPlanMode: z.boolean().optional(),
+  permission: PermissionConfigSchema.optional(),
+  hooks: z.array(HookDefSchema).optional(),
+  services: ServicesConfigSchema.optional(),
+  mergeAllAvailableSkills: z.boolean().optional(),
+  extraSkillDirs: z.array(z.string()).optional(),
+  loopControl: LoopControlSchema.optional(),
+  background: BackgroundConfigSchema.optional(),
+  telemetry: z.boolean().optional(),
+  raw: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type KimiConfig = z.infer<typeof KimiConfigSchema>;
+
+const ProviderConfigPatchSchema = ProviderConfigSchema.partial();
+const ModelAliasPatchSchema = ModelAliasSchema.partial();
+const ThinkingConfigPatchSchema = ThinkingConfigSchema.partial();
+const PermissionConfigPatchSchema = PermissionConfigSchema.partial();
+const LoopControlPatchSchema = LoopControlSchema.partial();
+const BackgroundConfigPatchSchema = BackgroundConfigSchema.partial();
+const MoonshotServiceConfigPatchSchema = MoonshotServiceConfigSchema.partial();
+const ServicesConfigPatchSchema = z.object({
+  moonshotSearch: MoonshotServiceConfigPatchSchema.optional(),
+  moonshotFetch: MoonshotServiceConfigPatchSchema.optional(),
+});
+
+export const KimiConfigPatchSchema = z
+  .object({
+    providers: z.record(z.string(), ProviderConfigPatchSchema).optional(),
+    defaultProvider: z.string().optional(),
+    defaultModel: z.string().optional(),
+    models: z.record(z.string(), ModelAliasPatchSchema).optional(),
+    thinking: ThinkingConfigPatchSchema.optional(),
+    planMode: z.boolean().optional(),
+    yolo: z.boolean().optional(),
+    defaultThinking: z.boolean().optional(),
+    defaultPermissionMode: PermissionModeSchema.optional(),
+    defaultPlanMode: z.boolean().optional(),
+    permission: PermissionConfigPatchSchema.optional(),
+    hooks: z.array(HookDefSchema).optional(),
+    services: ServicesConfigPatchSchema.optional(),
+    mergeAllAvailableSkills: z.boolean().optional(),
+    extraSkillDirs: z.array(z.string()).optional(),
+    loopControl: LoopControlPatchSchema.optional(),
+    background: BackgroundConfigPatchSchema.optional(),
+    telemetry: z.boolean().optional(),
+  })
+  .strict();
+
+export type KimiConfigPatch = z.infer<typeof KimiConfigPatchSchema>;
+
+export function getDefaultConfig(): KimiConfig {
+  return {
+    providers: {},
+  };
+}
+
+export function validateConfig(config: unknown): KimiConfig {
+  try {
+    return KimiConfigSchema.parse(config);
+  } catch (error) {
+    throw new KimiError(ErrorCodes.CONFIG_INVALID, `Invalid configuration: ${formatConfigValidationError(error)}`, {
+      cause: error,
+    });
+  }
+}
+
+export function formatConfigValidationError(error: unknown): string {
+  const missingModelContextSize = missingModelContextSizeMessage(error);
+  if (missingModelContextSize !== undefined) return missingModelContextSize;
+  return error instanceof Error ? error.message : String(error);
+}
+
+function missingModelContextSizeMessage(error: unknown): string | undefined {
+  if (!(error instanceof z.ZodError)) return undefined;
+  for (const issue of error.issues) {
+    const [section, modelName, field] = issue.path;
+    if (section === 'models' && typeof modelName === 'string' && field === 'maxContextSize') {
+      return `Model "${modelName}" must define a positive max_context_size in config.toml.`;
+    }
+  }
+  return undefined;
+}
+
+function isValidPermissionPattern(pattern: string): boolean {
+  try {
+    parsePattern(pattern);
+    return true;
+  } catch {
+    return false;
+  }
+}
diff --git a/packages/agent-core/src/config/toml.ts b/packages/agent-core/src/config/toml.ts
new file mode 100644
index 000000000..a049c1de1
--- /dev/null
+++ b/packages/agent-core/src/config/toml.ts
@@ -0,0 +1,508 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, open } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import { ErrorCodes, KimiError } from '#/errors';
+import {
+  KimiConfigSchema,
+  formatConfigValidationError,
+  getDefaultConfig,
+  type BackgroundConfig,
+  type HookDefConfig,
+  type KimiConfig,
+  type LoopControl,
+  type ModelAlias,
+  type MoonshotServiceConfig,
+  type OAuthRef,
+  type PermissionConfig,
+  type ProviderConfig,
+  type ServicesConfig,
+  type ThinkingConfig,
+  validateConfig,
+} from '#/config/schema';
+import { atomicWrite } from '#/utils/fs';
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+
+/* ------------------------------------------------------------------ */
+/*  Key helpers – reuse generic snake / camel conversion instead of    */
+/*  maintaining per-section *_KEY_MAP tables.                         */
+/* ------------------------------------------------------------------ */
+
+function snakeToCamel(str: string): string {
+  return str.replaceAll(/_([a-z])/g, (_, ch: string) => ch.toUpperCase());
+}
+
+function camelToSnake(str: string): string {
+  return str.replaceAll(/[A-Z]/g, (ch: string) => `_${ch.toLowerCase()}`);
+}
+
+/* ------------------------------------------------------------------ */
+/*  Read / parse                                                       */
+/* ------------------------------------------------------------------ */
+
+const DEFAULT_CONFIG_FILE_TEXT = `# ~/.kimi-code/config.toml
+# Runtime settings for Kimi Code.
+# This file starts empty so built-in defaults can apply.
+# Login will populate managed Kimi provider and model entries.
+`;
+
+export async function ensureConfigFile(filePath: string): Promise<void> {
+  await mkdir(dirname(filePath), { recursive: true, mode: 0o700 });
+  let handle: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    handle = await open(filePath, 'wx', 0o600);
+    await handle.writeFile(DEFAULT_CONFIG_FILE_TEXT, 'utf-8');
+  } catch (error) {
+    if (isFileExistsError(error)) return;
+    throw error;
+  } finally {
+    await handle?.close();
+  }
+}
+
+export function readConfigFile(filePath: string): KimiConfig {
+  if (!existsSync(filePath)) {
+    return getDefaultConfig();
+  }
+  const text = readFileSync(filePath, 'utf-8');
+  return parseConfigString(text, filePath);
+}
+
+export function parseConfigString(tomlText: string, filePath = 'config.toml'): KimiConfig {
+  if (tomlText.trim().length === 0) {
+    return getDefaultConfig();
+  }
+
+  let data: Record<string, unknown>;
+  try {
+    data = parseToml(tomlText) as Record<string, unknown>;
+  } catch (error) {
+    throw new KimiError(ErrorCodes.CONFIG_INVALID, `Invalid TOML in ${filePath}: ${error instanceof Error ? error.message : String(error)}`, {
+      cause: error,
+    });
+  }
+
+  return parseConfigData(data, filePath);
+}
+
+function parseConfigData(data: Record<string, unknown>, filePath: string): KimiConfig {
+  const raw = cloneRecord(data);
+  const transformed = transformTomlData(data);
+  transformed['raw'] = raw;
+
+  try {
+    return KimiConfigSchema.parse(transformed);
+  } catch (error) {
+    throw new KimiError(ErrorCodes.CONFIG_INVALID, `Invalid configuration in ${filePath}: ${formatConfigValidationError(error)}`, {
+      cause: error,
+    });
+  }
+}
+
+export function transformTomlData(data: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    const targetKey = snakeToCamel(key);
+
+    if (targetKey === 'providers' && isPlainObject(value)) {
+      result[targetKey] = transformRecord(value, transformProviderData);
+    } else if (targetKey === 'models' && isPlainObject(value)) {
+      result[targetKey] = transformRecord(value, transformModelData);
+    } else if (targetKey === 'thinking' && isPlainObject(value)) {
+      result[targetKey] = transformPlainObject(value);
+    } else if (targetKey === 'permission' && isPlainObject(value)) {
+      result[targetKey] = transformPermissionData(value);
+    } else if (targetKey === 'services' && isPlainObject(value)) {
+      result[targetKey] = transformRecord(value, transformServiceData, snakeToCamel);
+    } else if (targetKey === 'loopControl' && isPlainObject(value)) {
+      result[targetKey] = transformLoopControlData(value);
+    } else if (targetKey === 'background' && isPlainObject(value)) {
+      result[targetKey] = transformPlainObject(value);
+    } else if (!isPlainObject(value)) {
+      result[targetKey] = value;
+    }
+  }
+  return result;
+}
+
+function transformRecord(
+  value: Record<string, unknown>,
+  transformEntry: (entry: Record<string, unknown>) => Record<string, unknown>,
+  transformName: (name: string) => string = (name) => name,
+): Record<string, unknown> {
+  const record: Record<string, unknown> = {};
+  for (const [entryName, entryConfig] of Object.entries(value)) {
+    record[transformName(entryName)] = isPlainObject(entryConfig)
+      ? transformEntry(entryConfig)
+      : entryConfig;
+  }
+  return record;
+}
+
+function transformPlainObject(data: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    out[snakeToCamel(key)] = value;
+  }
+  return out;
+}
+
+function transformProviderData(data: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    const targetKey = snakeToCamel(key);
+    if (targetKey === 'oauth') {
+      out[targetKey] = isPlainObject(value) ? transformPlainObject(value) : value;
+    } else if (targetKey === 'env' || targetKey === 'customHeaders') {
+      out[targetKey] = cloneObjectValue(value);
+    } else {
+      out[targetKey] = value;
+    }
+  }
+  return out;
+}
+
+function transformModelData(data: Record<string, unknown>): Record<string, unknown> {
+  return transformPlainObject(data);
+}
+
+function transformPermissionData(data: Record<string, unknown>): Record<string, unknown> {
+  const raw = transformPlainObject(data);
+  const out: Record<string, unknown> = {};
+
+  const rules: unknown[] = [];
+  appendPermissionRules(rules, raw['rules']);
+  appendPermissionRules(rules, raw['deny'], 'deny');
+  appendPermissionRules(rules, raw['allow'], 'allow');
+  appendPermissionRules(rules, raw['ask'], 'ask');
+  if (rules.length > 0) {
+    out['rules'] = rules;
+  }
+  return out;
+}
+
+function appendPermissionRules(
+  target: unknown[],
+  value: unknown,
+  decision?: 'allow' | 'deny' | 'ask',
+): void {
+  if (value === undefined) return;
+  const entries = Array.isArray(value) ? value : [value];
+  for (const entry of entries) {
+    target.push(transformPermissionRule(entry, decision));
+  }
+}
+
+function transformPermissionRule(value: unknown, decision?: 'allow' | 'deny' | 'ask'): unknown {
+  if (!isPlainObject(value)) return value;
+
+  const rule = transformPlainObject(value);
+  const tool = rule['tool'];
+  const match = rule['match'];
+  const pattern = rule['pattern'];
+  const out: Record<string, unknown> = {};
+
+  if (decision !== undefined) {
+    out['decision'] = decision;
+  } else {
+    out['decision'] = rule['decision'];
+  }
+  out['scope'] = rule['scope'];
+  out['reason'] = rule['reason'];
+
+  if (typeof tool === 'string') {
+    const argPattern = typeof match === 'string' ? match : pattern;
+    out['pattern'] = typeof argPattern === 'string' ? `${tool}(${argPattern})` : tool;
+  } else {
+    out['pattern'] = pattern;
+  }
+
+  return out;
+}
+
+function transformServiceData(data: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    const targetKey = snakeToCamel(key);
+    if (targetKey === 'oauth') {
+      out[targetKey] = isPlainObject(value) ? transformPlainObject(value) : value;
+    } else if (targetKey === 'customHeaders') {
+      out[targetKey] = cloneObjectValue(value);
+    } else {
+      out[targetKey] = value;
+    }
+  }
+  return out;
+}
+
+function transformLoopControlData(data: Record<string, unknown>): Record<string, unknown> {
+  const out = transformPlainObject(data);
+  if (out['maxStepsPerTurn'] === undefined && out['maxStepsPerRun'] !== undefined) {
+    out['maxStepsPerTurn'] = out['maxStepsPerRun'];
+  }
+  delete out['maxStepsPerRun'];
+  return out;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Write / stringify                                                  */
+/* ------------------------------------------------------------------ */
+
+export async function writeConfigFile(filePath: string, config: KimiConfig): Promise<void> {
+  const validated = validateConfig(config);
+  await mkdir(dirname(filePath), { recursive: true, mode: 0o700 });
+  await atomicWrite(filePath, `${stringifyToml(configToTomlData(validated))}\n`);
+}
+
+export function configToTomlData(config: KimiConfig): Record<string, unknown> {
+  const out = cloneRecord(config.raw);
+
+  // Strip deprecated fields
+  delete out['default_yolo'];
+  delete out['defaultYolo'];
+  delete out['defaultPermissionMode'];
+
+  // Top-level scalar fields
+  const scalarFields: (keyof KimiConfig)[] = [
+    'defaultProvider',
+    'defaultModel',
+    'planMode',
+    'yolo',
+    'defaultThinking',
+    'defaultPermissionMode',
+    'defaultPlanMode',
+    'mergeAllAvailableSkills',
+    'extraSkillDirs',
+    'telemetry',
+  ];
+  for (const key of scalarFields) {
+    setDefined(out, camelToSnake(key), config[key]);
+  }
+
+  setRecordSection(out, 'providers', config.providers, providerToToml);
+  setRecordSection(out, 'models', config.models, modelToToml);
+  setSection(out, 'thinking', config.thinking, thinkingToToml);
+  setSection(out, 'services', config.services, servicesToToml);
+  setSection(out, 'loop_control', config.loopControl, loopControlToToml);
+  setSection(out, 'background', config.background, backgroundToToml);
+  setSection(out, 'permission', config.permission, permissionToToml);
+  setHooks(out, config.hooks);
+
+  return out;
+}
+
+function setRecordSection<T>(
+  out: Record<string, unknown>,
+  snakeKey: string,
+  value: Record<string, T> | undefined,
+  toToml: (v: T, raw: unknown) => Record<string, unknown>,
+): void {
+  if (value === undefined) {
+    delete out[snakeKey];
+    return;
+  }
+
+  const rawSub = cloneRecord(out[snakeKey]);
+  const converted: Record<string, unknown> = {};
+  for (const [entryName, entryConfig] of Object.entries(value)) {
+    converted[entryName] = toToml(entryConfig, rawSub[entryName]);
+  }
+
+  if (Object.keys(converted).length > 0) {
+    out[snakeKey] = converted;
+  } else {
+    delete out[snakeKey];
+  }
+}
+
+function setSection<T>(
+  out: Record<string, unknown>,
+  snakeKey: string,
+  value: T | undefined,
+  toToml: (v: T, raw: unknown) => Record<string, unknown>,
+): void {
+  if (value === undefined) {
+    delete out[snakeKey];
+    return;
+  }
+  const rawSub = cloneRecord(out[snakeKey]);
+  const converted = toToml(value, rawSub);
+  if (Object.keys(converted).length > 0) {
+    out[snakeKey] = converted;
+  } else {
+    delete out[snakeKey];
+  }
+}
+
+function providerToToml(provider: ProviderConfig, rawProvider: unknown): Record<string, unknown> {
+  const out = cloneRecord(rawProvider);
+  for (const [key, value] of Object.entries(provider)) {
+    if (key === 'oauth' && value !== undefined) {
+      out[camelToSnake(key)] = oauthToToml(value as OAuthRef);
+    } else if ((key === 'env' || key === 'customHeaders') && value !== undefined) {
+      out[camelToSnake(key)] = cloneUnknown(value);
+    } else {
+      setDefined(out, camelToSnake(key), value);
+    }
+  }
+  return out;
+}
+
+function modelToToml(model: ModelAlias, rawModel: unknown): Record<string, unknown> {
+  const out = cloneRecord(rawModel);
+  for (const [key, value] of Object.entries(model)) {
+    if (key === 'capabilities' && Array.isArray(value)) {
+      out[camelToSnake(key)] = [...value];
+    } else {
+      setDefined(out, camelToSnake(key), value);
+    }
+  }
+  return out;
+}
+
+function thinkingToToml(thinking: ThinkingConfig, rawThinking: unknown): Record<string, unknown> {
+  const out = cloneRecord(rawThinking);
+  for (const [key, value] of Object.entries(thinking)) {
+    setDefined(out, camelToSnake(key), value);
+  }
+  return out;
+}
+
+function permissionToToml(
+  permission: PermissionConfig,
+  rawPermission: unknown,
+): Record<string, unknown> {
+  const out = cloneRecord(rawPermission);
+  delete out['deny'];
+  delete out['allow'];
+  delete out['ask'];
+
+  if (permission.rules !== undefined) {
+    out['rules'] = permission.rules.map(permissionRuleToToml);
+  } else {
+    delete out['rules'];
+  }
+  return out;
+}
+
+function permissionRuleToToml(
+  rule: NonNullable<PermissionConfig['rules']>[number],
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(rule)) {
+    setDefined(out, camelToSnake(key), value);
+  }
+  return out;
+}
+
+function servicesToToml(services: ServicesConfig, rawServices: unknown): Record<string, unknown> {
+  const out = cloneRecord(rawServices);
+  if (services.moonshotSearch !== undefined) {
+    out['moonshot_search'] = serviceToToml(services.moonshotSearch);
+  } else {
+    delete out['moonshot_search'];
+  }
+  if (services.moonshotFetch !== undefined) {
+    out['moonshot_fetch'] = serviceToToml(services.moonshotFetch);
+  } else {
+    delete out['moonshot_fetch'];
+  }
+  return out;
+}
+
+function serviceToToml(service: MoonshotServiceConfig): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(service)) {
+    if (key === 'oauth' && value !== undefined) {
+      out[camelToSnake(key)] = oauthToToml(value as OAuthRef);
+    } else if (key === 'customHeaders' && value !== undefined) {
+      out[camelToSnake(key)] = cloneUnknown(value);
+    } else {
+      setDefined(out, camelToSnake(key), value);
+    }
+  }
+  return out;
+}
+
+function loopControlToToml(
+  loopControl: LoopControl,
+  rawLoopControl: unknown,
+): Record<string, unknown> {
+  const out = cloneRecord(rawLoopControl);
+  for (const [key, value] of Object.entries(loopControl)) {
+    setDefined(out, camelToSnake(key), value);
+  }
+  return out;
+}
+
+function backgroundToToml(
+  background: BackgroundConfig,
+  rawBackground: unknown,
+): Record<string, unknown> {
+  const out = cloneRecord(rawBackground);
+  for (const [key, value] of Object.entries(background)) {
+    setDefined(out, camelToSnake(key), value);
+  }
+  return out;
+}
+
+function setHooks(out: Record<string, unknown>, hooks: readonly HookDefConfig[] | undefined): void {
+  if (hooks === undefined) {
+    delete out['hooks'];
+    return;
+  }
+  out['hooks'] = hooks.map(hookToToml);
+}
+
+function hookToToml(hook: HookDefConfig): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(hook)) {
+    setDefined(out, camelToSnake(key), value);
+  }
+  return out;
+}
+
+function oauthToToml(oauth: OAuthRef): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(oauth)) {
+    out[camelToSnake(key)] = value;
+  }
+  return out;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Utilities                                                          */
+/* ------------------------------------------------------------------ */
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function cloneRecord(value: unknown): Record<string, unknown> {
+  if (!isPlainObject(value)) return {};
+  return cloneUnknown(value);
+}
+
+function cloneUnknown<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function cloneObjectValue(value: unknown): unknown {
+  return isPlainObject(value) ? cloneUnknown(value) : value;
+}
+
+function setDefined(target: Record<string, unknown>, key: string, value: unknown): void {
+  if (value !== undefined) {
+    target[key] = value;
+  } else {
+    delete target[key];
+  }
+}
+
+function isFileExistsError(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    (error as { code?: unknown }).code === 'EEXIST'
+  );
+}
diff --git a/packages/agent-core/src/errors.ts b/packages/agent-core/src/errors.ts
new file mode 100644
index 000000000..5a9fb663a
--- /dev/null
+++ b/packages/agent-core/src/errors.ts
@@ -0,0 +1,5 @@
+// Barrel re-export so #/errors resolves to a single .ts file (the first
+// entry in the package imports map). vitest does not resolve cleanly through
+// the directory fallback; this thin barrel keeps the alias working uniformly
+// across node, tsc, and vitest. Real module lives under ./errors.
+export * from './errors/index';
diff --git a/packages/agent-core/src/errors/classes.ts b/packages/agent-core/src/errors/classes.ts
new file mode 100644
index 000000000..8a080ea08
--- /dev/null
+++ b/packages/agent-core/src/errors/classes.ts
@@ -0,0 +1,28 @@
+import type { KimiErrorCode } from './codes';
+
+export interface KimiErrorOptions {
+  /** JSON-serializable structured details. */
+  readonly details?: Record<string, unknown>;
+  /** Original error or value. Local-only; never serialized to the wire. */
+  readonly cause?: unknown;
+}
+
+/**
+ * The single Kimi error class.
+ *
+ * Discrimination is always by `code`. Cross-process consumers receive
+ * `KimiErrorPayload` and must branch on `code` rather than class identity.
+ */
+export class KimiError extends Error {
+  readonly code: KimiErrorCode;
+  readonly details?: Record<string, unknown>;
+  override readonly cause?: unknown;
+
+  constructor(code: KimiErrorCode, message: string, options: KimiErrorOptions = {}) {
+    super(message);
+    this.name = 'KimiError';
+    this.code = code;
+    this.details = options.details;
+    this.cause = options.cause;
+  }
+}
diff --git a/packages/agent-core/src/errors/codes.ts b/packages/agent-core/src/errors/codes.ts
new file mode 100644
index 000000000..2583a8faa
--- /dev/null
+++ b/packages/agent-core/src/errors/codes.ts
@@ -0,0 +1,377 @@
+/**
+ * Error codes for Kimi Core's public error protocol.
+ *
+ * `ErrorCodes` is the source of truth for every code Kimi Core may emit.
+ * Downstream consumers (SDK, RPC clients, telemetry, agent-facing docs)
+ * should depend on these string values rather than on class identity.
+ *
+ * Codes follow `domain.reason`. Adding a code is a minor change; renaming
+ * or removing one is a major change.
+ */
+export const ErrorCodes = {
+  CONFIG_INVALID: 'config.invalid',
+
+  SESSION_NOT_FOUND: 'session.not_found',
+  SESSION_ALREADY_EXISTS: 'session.already_exists',
+  SESSION_ID_INVALID: 'session.id_invalid',
+  SESSION_ID_REQUIRED: 'session.id_required',
+  SESSION_ID_EMPTY: 'session.id_empty',
+  SESSION_TITLE_EMPTY: 'session.title_empty',
+  SESSION_STATE_NOT_FOUND: 'session.state_not_found',
+  SESSION_STATE_INVALID: 'session.state_invalid',
+  SESSION_FORK_ACTIVE_TURN: 'session.fork_active_turn',
+  SESSION_EXPORT_NOT_FOUND: 'session.export_not_found',
+  SESSION_EXPORT_MISSING_VERSION: 'session.export_missing_version',
+  SESSION_CLOSED: 'session.closed',
+  SESSION_PERMISSION_MODE_INVALID: 'session.permission_mode_invalid',
+  SESSION_THINKING_EMPTY: 'session.thinking_empty',
+  SESSION_MODEL_EMPTY: 'session.model_empty',
+  SESSION_PLAN_MODE_INVALID: 'session.plan_mode_invalid',
+  SESSION_APPROVAL_HANDLER_ERROR: 'session.approval_handler_error',
+  SESSION_QUESTION_HANDLER_ERROR: 'session.question_handler_error',
+  SESSION_INIT_FAILED: 'session.init_failed',
+
+  AGENT_NOT_FOUND: 'agent.not_found',
+  TURN_AGENT_BUSY: 'turn.agent_busy',
+
+  MODEL_NOT_CONFIGURED: 'model.not_configured',
+  MODEL_CONFIG_INVALID: 'model.config_invalid',
+  AUTH_LOGIN_REQUIRED: 'auth.login_required',
+
+  CONTEXT_OVERFLOW: 'context.overflow',
+  LOOP_MAX_STEPS_EXCEEDED: 'loop.max_steps_exceeded',
+  PROVIDER_API_ERROR: 'provider.api_error',
+  PROVIDER_RATE_LIMIT: 'provider.rate_limit',
+  PROVIDER_AUTH_ERROR: 'provider.auth_error',
+  PROVIDER_CONNECTION_ERROR: 'provider.connection_error',
+
+  SKILL_NOT_FOUND: 'skill.not_found',
+  SKILL_TYPE_UNSUPPORTED: 'skill.type_unsupported',
+  SKILL_NAME_EMPTY: 'skill.name_empty',
+
+  RECORDS_WRITE_FAILED: 'records.write_failed',
+  COMPACTION_FAILED: 'compaction.failed',
+
+  BACKGROUND_TASK_ID_EMPTY: 'background.task_id_empty',
+  MCP_SERVER_NOT_FOUND: 'mcp.server_not_found',
+  MCP_SERVER_DISABLED: 'mcp.server_disabled',
+  MCP_STARTUP_FAILED: 'mcp.startup_failed',
+  MCP_TOOL_NAME_COLLISION: 'mcp.tool_name_collision',
+
+  REQUEST_INVALID: 'request.invalid',
+  REQUEST_WORK_DIR_REQUIRED: 'request.work_dir_required',
+  REQUEST_PROMPT_INPUT_EMPTY: 'request.prompt_input_empty',
+
+  SHELL_GIT_BASH_NOT_FOUND: 'shell.git_bash_not_found',
+
+  NOT_IMPLEMENTED: 'not_implemented',
+  INTERNAL: 'internal',
+} as const;
+
+export type KimiErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+export interface KimiErrorInfo {
+  readonly title: string;
+  readonly retryable: boolean;
+  /**
+   * Whether the code is a stable public contract. `false` reserves the
+   * right to rename or remove without a major version bump.
+   */
+  readonly public: boolean;
+  readonly action?: string;
+}
+
+export const KIMI_ERROR_INFO = {
+  'config.invalid': {
+    title: 'Invalid configuration',
+    retryable: false,
+    public: true,
+    action: 'Check config.toml and provider/model settings.',
+  },
+
+  'session.not_found': {
+    title: 'Session not found',
+    retryable: false,
+    public: true,
+    action: 'Check the session id or list available sessions.',
+  },
+  'session.already_exists': {
+    title: 'Session already exists',
+    retryable: false,
+    public: true,
+    action: 'Use a different session id or remove the existing session first.',
+  },
+  'session.id_invalid': {
+    title: 'Invalid session id',
+    retryable: false,
+    public: true,
+    action: 'Use a session id without path-traversal characters.',
+  },
+  'session.id_required': {
+    title: 'Session id required',
+    retryable: false,
+    public: true,
+    action: 'Provide a session id when calling this method.',
+  },
+  'session.id_empty': {
+    title: 'Session id is empty',
+    retryable: false,
+    public: true,
+    action: 'Provide a non-empty session id.',
+  },
+  'session.title_empty': {
+    title: 'Session title is empty',
+    retryable: false,
+    public: true,
+    action: 'Provide a non-empty session title.',
+  },
+  'session.state_not_found': {
+    title: 'Session state missing',
+    retryable: false,
+    public: true,
+    action: 'The session directory is corrupted or missing state.json.',
+  },
+  'session.state_invalid': {
+    title: 'Session state invalid',
+    retryable: false,
+    public: true,
+    action: 'The session state.json is corrupted; remove the session or repair the file.',
+  },
+  'session.fork_active_turn': {
+    title: 'Cannot fork session during active turn',
+    retryable: true,
+    public: true,
+    action: 'Wait for the active turn to complete before forking.',
+  },
+  'session.export_not_found': {
+    title: 'Session export directory missing',
+    retryable: false,
+    public: true,
+    action: 'The session has not been persisted to disk yet.',
+  },
+  'session.export_missing_version': {
+    title: 'Export version is missing',
+    retryable: false,
+    public: true,
+    action: 'Provide a version when exporting the session.',
+  },
+  'session.closed': {
+    title: 'Session is closed',
+    retryable: false,
+    public: true,
+    action: 'Create a new session.',
+  },
+  'session.permission_mode_invalid': {
+    title: 'Invalid permission mode',
+    retryable: false,
+    public: true,
+    action: 'Use one of: yolo / manual / auto.',
+  },
+  'session.thinking_empty': {
+    title: 'Thinking value is empty',
+    retryable: false,
+    public: true,
+    action: 'Provide a non-empty thinking option.',
+  },
+  'session.model_empty': {
+    title: 'Model is empty',
+    retryable: false,
+    public: true,
+    action: 'Provide a non-empty model identifier.',
+  },
+  'session.plan_mode_invalid': {
+    title: 'Invalid plan mode',
+    retryable: false,
+    public: true,
+    action: 'Provide a boolean plan mode.',
+  },
+  'session.approval_handler_error': {
+    title: 'Approval handler threw',
+    retryable: false,
+    public: true,
+    action: 'Inspect the SDK approval handler for an unhandled exception.',
+  },
+  'session.question_handler_error': {
+    title: 'Question handler threw',
+    retryable: false,
+    public: true,
+    action: 'Inspect the SDK question handler for an unhandled exception.',
+  },
+  'session.init_failed': {
+    title: 'Session init failed',
+    retryable: false,
+    public: false,
+    action: 'Review the init failure details and try again.',
+  },
+
+  'agent.not_found': {
+    title: 'Agent not found',
+    retryable: false,
+    public: true,
+    action: 'Check the agent id or list available agents.',
+  },
+  'turn.agent_busy': {
+    title: 'Agent is busy',
+    retryable: true,
+    public: true,
+    action: 'Wait for the current turn to finish or steer it.',
+  },
+
+  'model.not_configured': {
+    title: 'No model configured',
+    retryable: false,
+    public: true,
+    action: 'Set a default model in config.toml or via setModel.',
+  },
+  'model.config_invalid': {
+    title: 'Invalid model configuration',
+    retryable: false,
+    public: true,
+    action: 'Check the model and provider entries in config.toml.',
+  },
+  'auth.login_required': {
+    title: 'Login required',
+    retryable: false,
+    public: true,
+    action: 'Run the login flow for the provider before retrying.',
+  },
+
+  'context.overflow': {
+    title: 'Context window overflow',
+    retryable: true,
+    public: true,
+    action: 'Compact the conversation or start a new session.',
+  },
+  'loop.max_steps_exceeded': {
+    title: 'Turn exceeded max steps',
+    retryable: false,
+    public: true,
+    action: 'Increase loop_control.max_steps_per_turn or split the task.',
+  },
+  'provider.api_error': {
+    title: 'Provider API error',
+    retryable: false,
+    public: true,
+    action: 'Inspect details.statusCode / details.requestId; check provider status.',
+  },
+  'provider.rate_limit': {
+    title: 'Provider rate limit',
+    retryable: true,
+    public: true,
+    action: 'Retry after a delay or reduce request frequency.',
+  },
+  'provider.auth_error': {
+    title: 'Provider authentication error',
+    retryable: false,
+    public: true,
+    action: 'Re-authenticate with the provider.',
+  },
+  'provider.connection_error': {
+    title: 'Provider connection error',
+    retryable: true,
+    public: true,
+    action: 'Check network connectivity and retry.',
+  },
+
+  'skill.not_found': {
+    title: 'Skill not found',
+    retryable: false,
+    public: true,
+    action: 'List available skills via the skill registry.',
+  },
+  'skill.type_unsupported': {
+    title: 'Skill type not supported',
+    retryable: false,
+    public: true,
+    action: 'Only inline skills can be activated by the user.',
+  },
+  'skill.name_empty': {
+    title: 'Skill name is empty',
+    retryable: false,
+    public: true,
+    action: 'Provide a non-empty skill name.',
+  },
+
+  'records.write_failed': {
+    title: 'Failed to write records',
+    retryable: true,
+    public: true,
+    action: 'Check disk space and permissions on the session directory.',
+  },
+  'compaction.failed': {
+    title: 'Compaction failed',
+    retryable: false,
+    public: true,
+    action: 'Inspect logs and consider increasing compaction limits.',
+  },
+
+  'background.task_id_empty': {
+    title: 'Background task id is empty',
+    retryable: false,
+    public: true,
+    action: 'Provide a non-empty task id.',
+  },
+  'mcp.server_not_found': {
+    title: 'MCP server not found',
+    retryable: false,
+    public: true,
+    action: 'List configured MCP servers and check the requested name.',
+  },
+  'mcp.server_disabled': {
+    title: 'MCP server is disabled',
+    retryable: false,
+    public: true,
+    action: 'Enable the MCP server entry in config before reconnecting.',
+  },
+  'mcp.startup_failed': {
+    title: 'MCP server startup failed',
+    retryable: true,
+    public: true,
+    action: 'Inspect the MCP server log or call reconnect once the server is healthy.',
+  },
+  'mcp.tool_name_collision': {
+    title: 'MCP tool name collision',
+    retryable: false,
+    public: true,
+    action: 'Rename one of the colliding MCP tools or servers so their qualified names are unique.',
+  },
+
+  'request.invalid': {
+    title: 'Invalid request',
+    retryable: false,
+    public: true,
+    action: 'Check the input shape matches the API contract.',
+  },
+  'request.work_dir_required': {
+    title: 'workDir is required',
+    retryable: false,
+    public: true,
+    action: 'Provide workDir in the request payload.',
+  },
+  'request.prompt_input_empty': {
+    title: 'Prompt input is empty',
+    retryable: false,
+    public: true,
+    action: 'Provide non-empty prompt input.',
+  },
+
+  'shell.git_bash_not_found': {
+    title: 'Git Bash not found',
+    retryable: false,
+    public: true,
+    action: 'Install Git for Windows from https://gitforwindows.org/ or set KIMI_SHELL_PATH to a bash.exe.',
+  },
+
+  not_implemented: {
+    title: 'Not implemented',
+    retryable: false,
+    public: true,
+    action: 'This feature is not implemented yet.',
+  },
+  internal: {
+    title: 'Internal error',
+    retryable: false,
+    public: true,
+    action: 'Inspect logs or report the issue with diagnostics.',
+  },
+} as const satisfies Record<KimiErrorCode, KimiErrorInfo>;
diff --git a/packages/agent-core/src/errors/index.ts b/packages/agent-core/src/errors/index.ts
new file mode 100644
index 000000000..317c7f3c5
--- /dev/null
+++ b/packages/agent-core/src/errors/index.ts
@@ -0,0 +1,17 @@
+export {
+  ErrorCodes,
+  KIMI_ERROR_INFO,
+  type KimiErrorCode,
+  type KimiErrorInfo,
+} from './codes';
+export {
+  KimiError,
+  type KimiErrorOptions,
+} from './classes';
+export {
+  fromKimiErrorPayload,
+  isKimiError,
+  makeErrorPayload,
+  toKimiErrorPayload,
+  type KimiErrorPayload,
+} from './serialize';
diff --git a/packages/agent-core/src/errors/serialize.ts b/packages/agent-core/src/errors/serialize.ts
new file mode 100644
index 000000000..efbbbb453
--- /dev/null
+++ b/packages/agent-core/src/errors/serialize.ts
@@ -0,0 +1,149 @@
+import {
+  APIConnectionError,
+  APIStatusError,
+  APITimeoutError,
+  ChatProviderError,
+} from '@moonshot-ai/kosong';
+
+import { KimiError } from './classes';
+import { ErrorCodes, KIMI_ERROR_INFO, type KimiErrorCode } from './codes';
+
+/**
+ * Wire-safe payload of a Kimi error.
+ *
+ * The structure passed across process / language boundaries (RPC, events,
+ * telemetry, SDK wrappers). Class identity does not survive the boundary;
+ * downstream code must branch on `code` rather than `instanceof`.
+ *
+ * `details` is JSON-serialized. `cause` is intentionally absent -- it is
+ * local-only diagnostic state and must not cross the boundary.
+ */
+export interface KimiErrorPayload {
+  readonly code: KimiErrorCode;
+  readonly message: string;
+  readonly name?: string;
+  readonly details?: Record<string, unknown>;
+  readonly retryable: boolean;
+}
+
+/** Type guard for KimiError. */
+export function isKimiError(error: unknown): error is KimiError {
+  return error instanceof KimiError;
+}
+
+/**
+ * Build a KimiErrorPayload directly from a code + message (no Error instance
+ * needed). Use this for synthetic error events that are signaled, not thrown
+ * -- e.g. "turn busy" or "compaction failed". `retryable` is filled from
+ * KIMI_ERROR_INFO so callers cannot drift out of sync with the registry.
+ */
+export function makeErrorPayload(
+  code: KimiErrorCode,
+  message: string,
+  options?: { readonly details?: Record<string, unknown>; readonly name?: string },
+): KimiErrorPayload {
+  return {
+    code,
+    message,
+    name: options?.name,
+    details: options?.details,
+    retryable: KIMI_ERROR_INFO[code].retryable,
+  };
+}
+
+/**
+ * Normalize any value into a KimiErrorPayload.
+ *
+ * Recognized errors:
+ * - `KimiError`: passthrough.
+ * - `APIStatusError`: 429 -> rate_limit, 401 -> auth_error, otherwise -> api_error.
+ * - `APIConnectionError` / `APITimeoutError`: connection_error.
+ * - `ChatProviderError`: api_error.
+ * - Heuristic "Model not set" / "Provider not set" messages: model.not_configured.
+ *
+ * Anything else collapses to `internal`. We never echo `cause` or stack on
+ * the wire.
+ */
+export function toKimiErrorPayload(error: unknown): KimiErrorPayload {
+  if (isKimiError(error)) {
+    return {
+      code: error.code,
+      message: error.message,
+      name: error.name,
+      details: error.details,
+      retryable: KIMI_ERROR_INFO[error.code].retryable,
+    };
+  }
+
+  if (error instanceof APIStatusError) {
+    const code: KimiErrorCode =
+      error.statusCode === 429
+        ? ErrorCodes.PROVIDER_RATE_LIMIT
+        : error.statusCode === 401
+          ? ErrorCodes.PROVIDER_AUTH_ERROR
+          : ErrorCodes.PROVIDER_API_ERROR;
+    return {
+      code,
+      message: error.message,
+      name: error.name,
+      details: {
+        statusCode: error.statusCode,
+        requestId: error.requestId,
+      },
+      retryable: KIMI_ERROR_INFO[code].retryable,
+    };
+  }
+
+  if (error instanceof APIConnectionError || error instanceof APITimeoutError) {
+    return {
+      code: ErrorCodes.PROVIDER_CONNECTION_ERROR,
+      message: error.message,
+      name: error.name,
+      retryable: KIMI_ERROR_INFO[ErrorCodes.PROVIDER_CONNECTION_ERROR].retryable,
+    };
+  }
+
+  if (error instanceof ChatProviderError) {
+    return {
+      code: ErrorCodes.PROVIDER_API_ERROR,
+      message: error.message,
+      name: error.name,
+      retryable: KIMI_ERROR_INFO[ErrorCodes.PROVIDER_API_ERROR].retryable,
+    };
+  }
+
+  if (error instanceof Error) {
+    if (error.message === 'Model not set' || error.message === 'Provider not set') {
+      return {
+        code: ErrorCodes.MODEL_NOT_CONFIGURED,
+        message: error.message,
+        name: error.name,
+        retryable: KIMI_ERROR_INFO[ErrorCodes.MODEL_NOT_CONFIGURED].retryable,
+      };
+    }
+
+    return {
+      code: ErrorCodes.INTERNAL,
+      message: error.message,
+      name: error.name,
+      retryable: KIMI_ERROR_INFO[ErrorCodes.INTERNAL].retryable,
+    };
+  }
+
+  return {
+    code: ErrorCodes.INTERNAL,
+    message: String(error),
+    retryable: KIMI_ERROR_INFO[ErrorCodes.INTERNAL].retryable,
+  };
+}
+
+/**
+ * Rehydrate a KimiErrorPayload into a KimiError. Used by SDK boundary code
+ * receiving errors over RPC to re-surface them with a real class so
+ * in-process consumers can still use `instanceof`.
+ */
+export function fromKimiErrorPayload(payload: KimiErrorPayload): KimiError {
+  return new KimiError(payload.code, payload.message, {
+    details: payload.details,
+  });
+}
diff --git a/packages/agent-core/src/index.ts b/packages/agent-core/src/index.ts
new file mode 100644
index 000000000..5e972d975
--- /dev/null
+++ b/packages/agent-core/src/index.ts
@@ -0,0 +1,45 @@
+export * from './agent';
+export * from './session';
+export * from './rpc';
+export * from './config';
+export * from './session/export';
+export * from './telemetry';
+export * from './errors';
+export {
+  flushDiagnosticLogs,
+  getRootLogger,
+  log,
+  redact,
+  resolveGlobalLogPath,
+} from './logging/logger';
+export { resolveLoggingConfig } from './logging/resolve-config';
+export type { ResolveLoggingInput } from './logging/resolve-config';
+export type {
+  LogContext,
+  LogEntry,
+  LogLevel,
+  LogPayload,
+  Logger,
+  LoggingConfig,
+  RootLogger,
+  SessionAttachInput,
+  SessionLogHandle,
+} from './logging/types';
+export { USER_PROMPT_ORIGIN } from './agent/context';
+export type {
+  AgentContextData,
+  ContextMessage,
+  PromptOrigin,
+  UserPromptOrigin,
+} from './agent/context';
+export type {
+  BackgroundLifecycleEvent,
+  BackgroundTaskInfo,
+  BackgroundTaskKind,
+  BackgroundTaskStatus,
+} from './tools/background/manager';
+export type { RuntimeConfig } from './runtime-types';
+export type {
+  BearerTokenProvider,
+  OAuthTokenProviderResolver,
+} from './providers/runtime-provider';
diff --git a/packages/agent-core/src/logging/formatter.ts b/packages/agent-core/src/logging/formatter.ts
new file mode 100644
index 000000000..df37591a5
--- /dev/null
+++ b/packages/agent-core/src/logging/formatter.ts
@@ -0,0 +1,200 @@
+import type { LogContext, LogEntry } from './types';
+
+export const MSG_MAX_CHARS = 200;
+export const CTX_VALUE_MAX_CHARS = 2048;
+export const STACK_MAX_BYTES = 2048;
+export const ENTRY_MAX_BYTES = 4096;
+export const REDACT_MAX_DEPTH = 10;
+
+const REDACTED_KEYS: ReadonlySet<string> = new Set([
+  'authorization',
+  'apikey',
+  'token',
+  'refreshtoken',
+  'accesstoken',
+  'idtoken',
+  'password',
+  'secret',
+  'clientsecret',
+  'apisecret',
+  'cookie',
+  'setcookie',
+  'bearer',
+]);
+
+const SAFE_KEY_RE = /^[\w.-]+$/;
+const ELLIPSIS = '…';
+const TRUNCATED_TAIL = ` …truncated`;
+const REDACTED = '[REDACTED]';
+const RAW_SECRET_PATTERNS: readonly RegExp[] = [
+  /\b(authorization\s*[:=]\s*bearer\s+)[^\s"'`]+/gi,
+  /\b((?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|token|password|secret)\s*[:=]\s*)[^\s"'`]+/gi,
+  /\b(cookie\s*[:=]\s*)[^\r\n]+/gi,
+];
+
+const LEVEL_LABEL: Record<Exclude<LogEntry['level'], never>, string> = {
+  error: 'ERROR',
+  warn: 'WARN ',
+  info: 'INFO ',
+  debug: 'DEBUG',
+};
+
+const ANSI_LEVEL: Record<Exclude<LogEntry['level'], never>, string> = {
+  error: '\u001B[31m',
+  warn: '\u001B[33m',
+  info: '\u001B[36m',
+  debug: '\u001B[90m',
+};
+const ANSI_RESET = '\u001B[0m';
+
+function normalizeKey(key: string): string {
+  return key.toLowerCase().replaceAll(/[_\-.]/g, '');
+}
+
+export function redactCtx(ctx: LogContext): LogContext {
+  const seen = new WeakSet<object>();
+  const walk = (value: unknown, depth: number): unknown => {
+    if (depth > REDACT_MAX_DEPTH) return '[REDACTED:depth]';
+    if (value === null || typeof value !== 'object') return value;
+    if (seen.has(value)) return '[REDACTED:cycle]';
+    seen.add(value);
+    if (Array.isArray(value)) {
+      return value.map((item) => walk(item, depth + 1));
+    }
+    const out: Record<string, unknown> = {};
+    for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = REDACTED_KEYS.has(normalizeKey(key))
+        ? REDACTED
+        : walk(raw, depth + 1);
+    }
+    return out;
+  };
+  return walk(ctx, 0) as LogContext;
+}
+
+export interface FormatOptions {
+  readonly ansi?: boolean | undefined;
+  readonly omitContextKeys?: readonly string[];
+}
+
+export interface FormattedEntry {
+  readonly text: string;
+  readonly dropped: boolean;
+}
+
+function truncate(value: string, max: number): string {
+  return value.length <= max ? value : value.slice(0, max - 1) + ELLIPSIS;
+}
+
+function serializeValue(raw: unknown): string {
+  if (typeof raw === 'string') return redactString(raw);
+  if (raw === undefined) return 'undefined';
+  if (raw === null) return 'null';
+  if (
+    typeof raw === 'number' ||
+    typeof raw === 'boolean' ||
+    typeof raw === 'bigint' ||
+    typeof raw === 'symbol'
+  ) {
+    return String(raw);
+  }
+  try {
+    const json = JSON.stringify(raw);
+    if (json !== undefined) return json;
+  } catch {
+    // fall through to a stable non-contentful fallback
+  }
+  if (typeof raw === 'function') return raw.name === '' ? '[Function]' : `[Function: ${raw.name}]`;
+  return Object.prototype.toString.call(raw);
+}
+
+function redactString(value: string): string {
+  let out = value;
+  for (const pattern of RAW_SECRET_PATTERNS) {
+    out = out.replace(pattern, `$1${REDACTED}`);
+  }
+  return out;
+}
+
+function quote(value: string): string {
+  return `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', '\\n')}"`;
+}
+
+function formatPair(key: string, raw: unknown): string {
+  const limited = truncate(serializeValue(raw), CTX_VALUE_MAX_CHARS);
+  const renderedKey = SAFE_KEY_RE.test(key) ? key : quote(key);
+  const renderedVal = /[\s="\\]/.test(limited) || limited.length === 0 ? quote(limited) : limited;
+  return `${renderedKey}=${renderedVal}`;
+}
+
+function clipBytes(text: string, maxBytes: number): string {
+  if (Buffer.byteLength(text, 'utf-8') <= maxBytes) return text;
+  // Binary-search the longest prefix that fits.
+  let lo = 0;
+  let hi = text.length;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (
+      Buffer.byteLength(text.slice(0, mid), 'utf-8') <=
+      maxBytes - Buffer.byteLength(TRUNCATED_TAIL, 'utf-8')
+    ) {
+      lo = mid;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return text.slice(0, lo) + TRUNCATED_TAIL;
+}
+
+function clipStack(stack: string): string {
+  if (Buffer.byteLength(stack, 'utf-8') <= STACK_MAX_BYTES) return stack;
+  return clipBytes(stack, STACK_MAX_BYTES);
+}
+
+function indentStack(stack: string): string {
+  return stack
+    .split('\n')
+    .map((line, i) => (i === 0 ? `  ${line}` : `    ${line.trimStart()}`))
+    .join('\n');
+}
+
+export function formatEntry(entry: LogEntry, options: FormatOptions = {}): FormattedEntry {
+  const ctx = entry.ctx ? redactCtx(entry.ctx) : undefined;
+  const omitContextKeys = new Set(options.omitContextKeys ?? []);
+  const msg = truncate(entry.msg, MSG_MAX_CHARS);
+  const pairs: string[] = [];
+  if (ctx) {
+    for (const [k, v] of Object.entries(ctx)) {
+      if (omitContextKeys.has(k)) continue;
+      if (v !== undefined) pairs.push(formatPair(k, v));
+    }
+  }
+
+  const time = new Date(entry.t).toISOString();
+  const label = LEVEL_LABEL[entry.level];
+  const rendered = pairs.length === 0
+    ? `${time} ${label} ${msg}`
+    : `${time} ${label} ${msg}  ${pairs.join(' ')}`;
+
+  let head = Buffer.byteLength(rendered, 'utf-8') > ENTRY_MAX_BYTES
+    ? clipBytes(rendered, ENTRY_MAX_BYTES)
+    : rendered;
+
+  if (options.ansi === true) {
+    head = `${ANSI_LEVEL[entry.level]}${head}${ANSI_RESET}`;
+  }
+
+  if (entry.error?.stack) {
+    head = `${head}\n${indentStack(clipStack(redactString(entry.error.stack)))}`;
+  } else if (entry.error?.message) {
+    head = `${head}\n  Error: ${redactString(entry.error.message)}`;
+  }
+
+  return { text: head, dropped: false };
+}
+
+export function extractError(value: Error): { message: string; stack?: string } {
+  return typeof value.stack === 'string'
+    ? { message: value.message, stack: value.stack }
+    : { message: value.message };
+}
diff --git a/packages/agent-core/src/logging/index.ts b/packages/agent-core/src/logging/index.ts
new file mode 100644
index 000000000..51be3b8a6
--- /dev/null
+++ b/packages/agent-core/src/logging/index.ts
@@ -0,0 +1,32 @@
+export type {
+  LogContext,
+  LogEntry,
+  LogLevel,
+  LogPayload,
+  Logger,
+  LoggingConfig,
+  RootLogger,
+  SessionAttachInput,
+  SessionLogHandle,
+} from './types';
+export { LOG_LEVEL_RANK, levelEnabled } from './types';
+
+export {
+  __resetRootLoggerForTest,
+  flushDiagnosticLogs,
+  getRootLogger,
+  log,
+  redact,
+  resolveGlobalLogPath,
+} from './logger';
+
+export {
+  CTX_VALUE_MAX_CHARS,
+  ENTRY_MAX_BYTES,
+  MSG_MAX_CHARS,
+  REDACT_MAX_DEPTH,
+  STACK_MAX_BYTES,
+  extractError,
+  formatEntry,
+  redactCtx,
+} from './formatter';
diff --git a/packages/agent-core/src/logging/logger.ts b/packages/agent-core/src/logging/logger.ts
new file mode 100644
index 000000000..7112de2ca
--- /dev/null
+++ b/packages/agent-core/src/logging/logger.ts
@@ -0,0 +1,437 @@
+import { join } from 'node:path';
+
+import { extractError, formatEntry, redactCtx } from './formatter';
+import { RotatingFileSink } from './sinks';
+import {
+  type LogContext,
+  type LogEntry,
+  type LogLevel,
+  type LogPayload,
+  type Logger,
+  type LoggingConfig,
+  type RootLogger,
+  type SessionAttachInput,
+  type SessionLogHandle,
+  levelEnabled,
+} from './types';
+
+const ROOT_SYMBOL = Symbol.for('kimi.logger.root');
+const SESSION_LOG_ID = Symbol('kimi.logger.sessionLogId');
+const LLM_REQUEST_SESSION_LOG_OMITTED_CONTEXT_KEYS = ['sessionId'];
+const MAIN_LLM_REQUEST_SESSION_LOG_OMITTED_CONTEXT_KEYS = ['sessionId', 'agentId'];
+let nextSessionLogId = 0;
+
+interface SessionEntry {
+  readonly logId: string;
+  readonly sessionId: string;
+  readonly sessionDir: string;
+  readonly sink: RotatingFileSink;
+  state: 'open' | 'closing';
+  closePromise: Promise<void> | undefined;
+  refCount: number;
+}
+
+class RootLoggerImpl implements RootLogger {
+  private config: LoggingConfig | undefined;
+  private globalSink: RotatingFileSink | undefined;
+  private readonly sessions = new Map<string, SessionEntry>();
+  private readonly sessionsById = new Map<string, Set<string>>();
+
+  isConfigured(): boolean {
+    return this.config !== undefined;
+  }
+
+  getConfig(): LoggingConfig | undefined {
+    return this.config;
+  }
+
+  configure(config: LoggingConfig): Promise<void> {
+    if (this.config !== undefined && sameLoggingConfig(this.config, config)) {
+      return Promise.resolve();
+    }
+    const oldGlobalSink = this.globalSink;
+    this.config = config;
+    this.globalSink = makeGlobalSink(config);
+    return oldGlobalSink?.close() ?? Promise.resolve();
+  }
+
+  attachSession(input: SessionAttachInput): SessionLogHandle {
+    const existing = this.findOpenSession(input.sessionId, input.sessionDir);
+    if (existing !== undefined) {
+      existing.refCount += 1;
+      return makeHandle(existing);
+    }
+    const config = this.config;
+    if (config === undefined || config.level === 'off') {
+      return makeNoopHandle(input.sessionId);
+    }
+    const sink = new RotatingFileSink({
+      path: join(input.sessionDir, 'logs', 'kimi-code.log'),
+      maxBytes: config.sessionMaxBytes,
+      files: config.sessionFiles,
+    });
+    const entry: SessionEntry = {
+      logId: `session-log-${String(++nextSessionLogId)}`,
+      sessionId: input.sessionId,
+      sessionDir: input.sessionDir,
+      sink,
+      state: 'open',
+      closePromise: undefined,
+      refCount: 1,
+    };
+    this.sessions.set(entry.logId, entry);
+    this.trackSessionId(entry);
+    return makeHandle(entry);
+  }
+
+  async flush(): Promise<boolean> {
+    const tasks: Promise<boolean>[] = [];
+    if (this.globalSink !== undefined) tasks.push(this.globalSink.flush());
+    for (const entry of this.sessions.values()) {
+      tasks.push(this.flushEntry(entry));
+    }
+    if (tasks.length === 0) return true;
+    const results = await Promise.all(tasks);
+    return results.every(Boolean);
+  }
+
+  async flushGlobal(): Promise<boolean> {
+    if (this.globalSink === undefined) return true;
+    return this.globalSink.flush();
+  }
+
+  async flushSession(sessionId: string): Promise<boolean> {
+    const entries = this.getEntriesForSessionId(sessionId);
+    if (entries.length === 0) return true;
+    const results = await Promise.all(entries.map((entry) => this.flushEntry(entry)));
+    return results.every(Boolean);
+  }
+
+  flushSync(): void {
+    const deadline = Date.now() + 200;
+    this.globalSink?.flushSync();
+    for (const entry of this.sessions.values()) {
+      if (entry.state !== 'open') continue;
+      if (Date.now() > deadline) break;
+      entry.sink.flushSync();
+    }
+  }
+
+  emit(entry: LogEntry): void {
+    const config = this.config;
+    if (config === undefined || config.level === 'off') return;
+    if (!levelEnabled(config.level, entry.level)) return;
+
+    const formatted = formatEntry(entry);
+    if (formatted.dropped) return;
+
+    this.globalSink?.enqueue(formatted.text + '\n');
+
+    const session = this.resolveSessionEntry(entry);
+    if (session !== undefined) {
+      const omitContextKeys =
+        entry.msg === 'llm request' ? llmRequestSessionLogOmittedKeys(entry) : undefined;
+      const sessionFormatted = formatEntry(entry, {
+        omitContextKeys,
+      });
+      if (!sessionFormatted.dropped) {
+        session.sink.enqueue(sessionFormatted.text + '\n');
+      }
+    }
+  }
+
+  detachSession(logId: string): Promise<void> {
+    const entry = this.sessions.get(logId);
+    if (entry === undefined) return Promise.resolve();
+    if (entry.state === 'closing') return entry.closePromise ?? Promise.resolve();
+    entry.refCount -= 1;
+    if (entry.refCount > 0) return Promise.resolve();
+    entry.state = 'closing';
+    entry.closePromise = entry.sink.close().finally(() => {
+      if (this.sessions.get(logId) === entry) {
+        this.sessions.delete(logId);
+        this.untrackSessionId(entry);
+      }
+    });
+    return entry.closePromise;
+  }
+
+  /** @internal — vitest only. */
+  async __shutdownForTest(): Promise<void> {
+    const closes: Promise<void>[] = [];
+    if (this.globalSink !== undefined) closes.push(this.globalSink.close());
+    for (const entry of this.sessions.values()) {
+      if (entry.state === 'closing') {
+        if (entry.closePromise !== undefined) closes.push(entry.closePromise);
+      } else {
+        entry.state = 'closing';
+        entry.closePromise = entry.sink.close();
+        closes.push(entry.closePromise);
+      }
+    }
+    this.sessions.clear();
+    this.sessionsById.clear();
+    this.globalSink = undefined;
+    this.config = undefined;
+    await Promise.allSettled(closes);
+  }
+
+  private findOpenSession(sessionId: string, sessionDir: string): SessionEntry | undefined {
+    for (const entry of this.getEntriesForSessionId(sessionId)) {
+      if (entry.sessionDir === sessionDir && entry.state === 'open') return entry;
+    }
+    return undefined;
+  }
+
+  private trackSessionId(entry: SessionEntry): void {
+    const ids = this.sessionsById.get(entry.sessionId) ?? new Set<string>();
+    ids.add(entry.logId);
+    this.sessionsById.set(entry.sessionId, ids);
+  }
+
+  private untrackSessionId(entry: SessionEntry): void {
+    const ids = this.sessionsById.get(entry.sessionId);
+    if (ids === undefined) return;
+    ids.delete(entry.logId);
+    if (ids.size === 0) this.sessionsById.delete(entry.sessionId);
+  }
+
+  private getEntriesForSessionId(sessionId: string): SessionEntry[] {
+    const ids = this.sessionsById.get(sessionId);
+    if (ids === undefined) return [];
+    return [...ids]
+      .map((id) => this.sessions.get(id))
+      .filter((entry): entry is SessionEntry => entry !== undefined);
+  }
+
+  private resolveSessionEntry(entry: LogEntry): SessionEntry | undefined {
+    if (entry.sessionLogId !== undefined) {
+      const session = this.sessions.get(entry.sessionLogId);
+      return session?.state === 'open' ? session : undefined;
+    }
+    if (entry.sessionId === undefined) return undefined;
+    const openEntries = this.getEntriesForSessionId(entry.sessionId).filter(
+      (item) => item.state === 'open',
+    );
+    return openEntries.length === 1 ? openEntries[0] : undefined;
+  }
+
+  private async flushEntry(entry: SessionEntry): Promise<boolean> {
+    if (entry.state === 'closing') {
+      await entry.closePromise;
+      return true;
+    }
+    return entry.sink.flush();
+  }
+}
+
+function llmRequestSessionLogOmittedKeys(entry: LogEntry): readonly string[] {
+  return entry.ctx?.['agentId'] === 'main'
+    ? MAIN_LLM_REQUEST_SESSION_LOG_OMITTED_CONTEXT_KEYS
+    : LLM_REQUEST_SESSION_LOG_OMITTED_CONTEXT_KEYS;
+}
+
+function makeHandle(entry: SessionEntry): SessionLogHandle {
+  let closed = false;
+  return {
+    logger: log.createChild({
+      sessionId: entry.sessionId,
+      [SESSION_LOG_ID]: entry.logId,
+    } as LogContext),
+    async flush() {
+      if (entry.state === 'closing') {
+        await entry.closePromise;
+      } else {
+        await entry.sink.flush();
+      }
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      await getRootInternal().detachSession(entry.logId);
+    },
+  };
+}
+
+function makeNoopHandle(sessionId: string): SessionLogHandle {
+  return {
+    logger: log.createChild({ sessionId }),
+    async flush() {},
+    async close() {},
+  };
+}
+
+function getRootInternal(): RootLoggerImpl {
+  const globalAny = globalThis as Record<symbol, unknown>;
+  const existing = globalAny[ROOT_SYMBOL];
+  if (existing instanceof RootLoggerImpl) return existing;
+  const fresh = new RootLoggerImpl();
+  globalAny[ROOT_SYMBOL] = fresh;
+  return fresh;
+}
+
+export function getRootLogger(): RootLogger {
+  return getRootInternal();
+}
+
+export function flushDiagnosticLogs(): Promise<boolean> {
+  return getRootInternal().flush();
+}
+
+class LoggerImpl implements Logger {
+  constructor(private readonly boundCtx: LogContext) {}
+
+  error(message: string, payload?: LogPayload): void {
+    this.emitAt('error', message, payload);
+  }
+  warn(message: string, payload?: LogPayload): void {
+    this.emitAt('warn', message, payload);
+  }
+  info(message: string, payload?: LogPayload): void {
+    this.emitAt('info', message, payload);
+  }
+  debug(message: string, payload?: LogPayload): void {
+    this.emitAt('debug', message, payload);
+  }
+
+  createChild(ctx: LogContext): Logger {
+    return new LoggerImpl({ ...this.boundCtx, ...ctx });
+  }
+
+  private emitAt(
+    level: Exclude<LogLevel, 'off'>,
+    message: string,
+    payload: LogPayload,
+  ): void {
+    const root = getRootInternal();
+    if (!root.isConfigured()) return;
+    try {
+      const { ctx: payloadCtx, error } = resolvePayload(payload);
+      // Bound ctx wins so call-site can't overwrite ownership fields.
+      const ctx = mergeCtx(payloadCtx, this.boundCtx);
+      const sessionId = ctx?.['sessionId'];
+      const sessionLogId = (ctx as InternalLogContext | undefined)?.[SESSION_LOG_ID];
+      root.emit({
+        t: Date.now(),
+        level,
+        msg: message,
+        ctx: stripInternalCtx(ctx),
+        error,
+        sessionId: typeof sessionId === 'string' ? sessionId : undefined,
+        sessionLogId: typeof sessionLogId === 'string' ? sessionLogId : undefined,
+      });
+    } catch {
+      // Diagnostic logging is best-effort and must never affect main control flow.
+    }
+  }
+}
+
+type InternalLogContext = LogContext & { [SESSION_LOG_ID]?: unknown };
+
+function stripInternalCtx(ctx: LogContext | undefined): LogContext | undefined {
+  if (ctx === undefined) return undefined;
+  if (!(SESSION_LOG_ID in ctx)) return ctx;
+  const { [SESSION_LOG_ID]: _internal, ...visible } = ctx as InternalLogContext;
+  return visible;
+}
+
+function makeGlobalSink(config: LoggingConfig): RotatingFileSink | undefined {
+  if (config.level === 'off') return undefined;
+  return new RotatingFileSink({
+    path: config.globalLogPath,
+    maxBytes: config.globalMaxBytes,
+    files: config.globalFiles,
+  });
+}
+
+function sameLoggingConfig(a: LoggingConfig, b: LoggingConfig): boolean {
+  return (
+    a.level === b.level &&
+    a.globalLogPath === b.globalLogPath &&
+    a.globalMaxBytes === b.globalMaxBytes &&
+    a.globalFiles === b.globalFiles &&
+    a.sessionMaxBytes === b.sessionMaxBytes &&
+    a.sessionFiles === b.sessionFiles
+  );
+}
+
+function resolvePayload(
+  payload: LogPayload,
+): { ctx: LogContext | undefined; error: LogEntry['error'] } {
+  if (payload === undefined || payload === null) {
+    return { ctx: undefined, error: undefined };
+  }
+  if (payload instanceof Error) {
+    return { ctx: undefined, error: extractError(payload) };
+  }
+  if (typeof payload === 'object') {
+    // bunyan-style: a `{ error: Error }` field is hoisted out, stack extracted.
+    const obj = payload as Record<string, unknown>;
+    if (obj['error'] instanceof Error) {
+      const { error: errValue, ...rest } = obj;
+      return { ctx: rest as LogContext, error: extractError(errValue) };
+    }
+    return { ctx: obj as LogContext, error: undefined };
+  }
+  if (
+    typeof payload === 'string' ||
+    typeof payload === 'number' ||
+    typeof payload === 'boolean' ||
+    typeof payload === 'bigint' ||
+    typeof payload === 'symbol'
+  ) {
+    return { ctx: { reason: String(payload) }, error: undefined };
+  }
+  if (typeof payload === 'function') {
+    const reason = payload.name === '' ? '[Function]' : `[Function: ${payload.name}]`;
+    return { ctx: { reason }, error: undefined };
+  }
+  return { ctx: { reason: Object.prototype.toString.call(payload) }, error: undefined };
+}
+
+function mergeCtx(
+  payloadCtx: LogContext | undefined,
+  boundCtx: LogContext,
+): LogContext | undefined {
+  const boundHasKeys = Object.keys(boundCtx).length > 0;
+  if (!boundHasKeys) return payloadCtx;
+  if (payloadCtx === undefined) return { ...boundCtx };
+  return { ...payloadCtx, ...boundCtx };
+}
+
+/**
+ * Root logger. Import and use directly for events that don't belong to any
+ * session (CLI startup, harness construction, etc.):
+ *
+ *   import { log } from 'kimi-code-sdk';
+ *   log.info('kimi-code starting', { version });
+ *
+ * For events scoped to a session or agent, use the parent's `log` field:
+ *
+ *   session.log.error('mcp initial load failed', error);
+ *   agent.log.error('turn failed', { turnId, error });
+ *
+ * Late-binding: methods look up the current `RootLogger` on every call, so
+ * importing `log` at module load (before `KimiHarness` configures the root)
+ * is safe — calls during the pre-configure window are silent noops.
+ */
+export const log: Logger = new LoggerImpl({});
+
+export function redact<T>(value: T): T {
+  if (value === null || typeof value !== 'object') return value;
+  return redactCtx({ value: value as unknown })['value'] as T;
+}
+
+/** @internal — vitest only. */
+export async function __resetRootLoggerForTest(): Promise<void> {
+  const globalAny = globalThis as Record<symbol, unknown>;
+  const existing = globalAny[ROOT_SYMBOL];
+  if (existing instanceof RootLoggerImpl) {
+    await existing.__shutdownForTest();
+  }
+  globalAny[ROOT_SYMBOL] = undefined;
+}
+
+export function resolveGlobalLogPath(homeDir: string): string {
+  return join(homeDir, 'logs', 'kimi-code.log');
+}
diff --git a/packages/agent-core/src/logging/resolve-config.ts b/packages/agent-core/src/logging/resolve-config.ts
new file mode 100644
index 000000000..6bf66cde0
--- /dev/null
+++ b/packages/agent-core/src/logging/resolve-config.ts
@@ -0,0 +1,51 @@
+import { resolveGlobalLogPath } from './logger';
+import type { LogLevel, LoggingConfig } from './types';
+
+export const DEFAULT_LOG_LEVEL: LogLevel = 'info';
+export const DEFAULT_GLOBAL_MAX_BYTES = 6 * 1024 * 1024; // 6 MB
+export const DEFAULT_GLOBAL_FILES = 5; // 6 MB x 5 = 30 MB
+export const DEFAULT_SESSION_MAX_BYTES = 5 * 1024 * 1024; // 5 MB
+export const DEFAULT_SESSION_FILES = 3; // 5 MB x 3 = 15 MB
+
+export interface ResolveLoggingInput {
+  readonly homeDir: string;
+  readonly env?: NodeJS.ProcessEnv | undefined;
+}
+
+/**
+ * Build the runtime `LoggingConfig` from env vars + defaults.
+ *
+ * v1 deliberately does not read `config.toml [logging]` — the schema is in
+ * flux and reading it adds a startup-time failure surface. Users who need to
+ * override the defaults set env vars:
+ *
+ *   KIMI_LOG_LEVEL=debug
+ *   KIMI_LOG_GLOBAL_MAX_BYTES=... KIMI_LOG_GLOBAL_FILES=...
+ *   KIMI_LOG_SESSION_MAX_BYTES=... KIMI_LOG_SESSION_FILES=...
+ */
+export function resolveLoggingConfig(input: ResolveLoggingInput): LoggingConfig {
+  const env = input.env ?? process.env;
+  return {
+    level: parseLevel(env['KIMI_LOG_LEVEL']) ?? DEFAULT_LOG_LEVEL,
+    globalLogPath: resolveGlobalLogPath(input.homeDir),
+    globalMaxBytes: parsePositiveInt(env['KIMI_LOG_GLOBAL_MAX_BYTES']) ?? DEFAULT_GLOBAL_MAX_BYTES,
+    globalFiles: parsePositiveInt(env['KIMI_LOG_GLOBAL_FILES']) ?? DEFAULT_GLOBAL_FILES,
+    sessionMaxBytes:
+      parsePositiveInt(env['KIMI_LOG_SESSION_MAX_BYTES']) ?? DEFAULT_SESSION_MAX_BYTES,
+    sessionFiles: parsePositiveInt(env['KIMI_LOG_SESSION_FILES']) ?? DEFAULT_SESSION_FILES,
+  };
+}
+
+function parseLevel(value: string | undefined): LogLevel | undefined {
+  if (value === undefined) return undefined;
+  const v = value.toLowerCase().trim();
+  if (v === 'off' || v === 'error' || v === 'warn' || v === 'info' || v === 'debug') return v;
+  return undefined;
+}
+
+function parsePositiveInt(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const n = Number.parseInt(value, 10);
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  return n;
+}
diff --git a/packages/agent-core/src/logging/sinks.ts b/packages/agent-core/src/logging/sinks.ts
new file mode 100644
index 000000000..ed7c07016
--- /dev/null
+++ b/packages/agent-core/src/logging/sinks.ts
@@ -0,0 +1,224 @@
+import { mkdir, open, rename, stat, unlink } from 'node:fs/promises';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { syncDir } from '#/utils/fs';
+
+export const PENDING_MAX = 1000;
+const STDERR_NOTICE_INTERVAL_MS = 30_000;
+
+class AsyncSerialQueue {
+  private tail: Promise<unknown> = Promise.resolve();
+
+  run<T>(task: () => Promise<T>): Promise<T> {
+    const next = this.tail.then(task, task);
+    this.tail = next.catch(() => {});
+    return next;
+  }
+}
+export interface Sink {
+  enqueue(line: string): void;
+  /** Resolves to false when the pending batch could not be written. */
+  flush(): Promise<boolean>;
+  close(): Promise<void>;
+  flushSync(): void;
+}
+
+interface RotatingFileSinkOptions {
+  readonly path: string;
+  readonly maxBytes: number;
+  readonly files: number;
+}
+
+export class RotatingFileSink implements Sink {
+  private readonly queue = new AsyncSerialQueue();
+  private pending: string[] = [];
+  private dropped = 0;
+  private closed = false;
+  private failed = false;
+  private lastStderrNotice = 0;
+  private currentBytes = -1;
+  private directorySynced = false;
+
+  constructor(private readonly options: RotatingFileSinkOptions) {}
+
+  enqueue(line: string): void {
+    if (this.closed) return;
+    if (this.pending.length >= PENDING_MAX) {
+      this.pending.shift();
+      this.dropped++;
+    }
+    this.pending.push(line);
+    this.scheduleDrain();
+  }
+
+  async flush(): Promise<boolean> {
+    return this.queue.run(() => this.drain());
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    try {
+      await this.flush();
+    } catch {
+      // swallow — close must not throw
+    }
+  }
+
+  flushSync(): void {
+    if (this.closed || this.pending.length === 0) return;
+    try {
+      mkdirSync(dirname(this.options.path), { recursive: true });
+      const body = this.pending.join('') + this.takeDroppedNotice();
+      this.pending = [];
+      appendFileSync(this.options.path, body);
+    } catch (error) {
+      this.noteFailure(error);
+    }
+  }
+
+  private scheduleDrain(): void {
+    if (this.closed) return;
+    queueMicrotask(() => {
+      if (this.closed || this.pending.length === 0) return;
+      this.queue.run(() => this.drain()).catch(() => {});
+    });
+  }
+
+  private async drain(): Promise<boolean> {
+    if (this.pending.length === 0) return true;
+    const droppedLine = this.takeDroppedNotice();
+    const lines = droppedLine === '' ? [...this.pending] : [...this.pending, droppedLine];
+    this.pending = [];
+    try {
+      await mkdir(dirname(this.options.path), { recursive: true });
+      if (this.currentBytes < 0) {
+        this.currentBytes = await this.statSize(this.options.path);
+      }
+      await this.appendLines(lines);
+
+      if (!this.directorySynced) {
+        await syncDir(dirname(this.options.path));
+        this.directorySynced = true;
+      }
+
+      this.failed = false;
+      return true;
+    } catch (error) {
+      this.noteFailure(error);
+      this.restorePending(lines);
+      return false;
+    }
+  }
+
+  private restorePending(lines: readonly string[]): void {
+    const restored = [...lines, ...this.pending];
+    const overflow = restored.length - PENDING_MAX;
+    if (overflow <= 0) {
+      this.pending = restored;
+      return;
+    }
+    this.dropped += overflow;
+    this.pending = restored.slice(overflow);
+  }
+
+  private async appendLines(lines: readonly string[]): Promise<void> {
+    let chunk = '';
+    let chunkBytes = 0;
+    for (const line of lines) {
+      const lineBytes = Buffer.byteLength(line, 'utf-8');
+      if (
+        chunkBytes > 0 &&
+        (chunkBytes + lineBytes > this.options.maxBytes ||
+          this.currentBytes + chunkBytes + lineBytes > this.options.maxBytes)
+      ) {
+        await this.appendChunk(chunk);
+        chunk = '';
+        chunkBytes = 0;
+      }
+
+      if (
+        chunkBytes === 0 &&
+        this.currentBytes > 0 &&
+        this.currentBytes + lineBytes > this.options.maxBytes
+      ) {
+        await this.rotate();
+      }
+
+      chunk += line;
+      chunkBytes += lineBytes;
+    }
+    if (chunkBytes > 0) {
+      await this.appendChunk(chunk);
+    }
+  }
+
+  private async appendChunk(chunk: string): Promise<void> {
+    const fh = await open(this.options.path, 'a');
+    try {
+      await fh.appendFile(chunk, 'utf-8');
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    this.currentBytes += Buffer.byteLength(chunk, 'utf-8');
+    if (this.currentBytes >= this.options.maxBytes) {
+      await this.rotate();
+    }
+  }
+
+  private async rotate(): Promise<void> {
+    const { path, files } = this.options;
+    for (let i = files - 2; i >= 1; i--) {
+      const from = `${path}.${i}`;
+      const to = `${path}.${i + 1}`;
+      try {
+        await rename(from, to);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      }
+    }
+    try {
+      await rename(path, `${path}.1`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    // last archive may be evicted; ensure we don't keep > files
+    try {
+      await unlink(`${path}.${files}`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    this.currentBytes = 0;
+    this.directorySynced = false;
+  }
+
+  private async statSize(p: string): Promise<number> {
+    try {
+      const s = await stat(p);
+      return s.size;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 0;
+      throw error;
+    }
+  }
+
+  private takeDroppedNotice(): string {
+    if (this.dropped === 0) return '';
+    const line = `... dropped ${this.dropped} entries ...\n`;
+    this.dropped = 0;
+    return line;
+  }
+
+  private noteFailure(error: unknown): void {
+    this.failed = true;
+    const now = Date.now();
+    if (now - this.lastStderrNotice < STDERR_NOTICE_INTERVAL_MS) return;
+    this.lastStderrNotice = now;
+    const code = (error as NodeJS.ErrnoException)?.code ?? 'UNKNOWN';
+    try {
+      process.stderr.write(`[logger] write failed: ${code}\n`);
+    } catch {}
+  }
+}
diff --git a/packages/agent-core/src/logging/types.ts b/packages/agent-core/src/logging/types.ts
new file mode 100644
index 000000000..0a97b3959
--- /dev/null
+++ b/packages/agent-core/src/logging/types.ts
@@ -0,0 +1,91 @@
+export type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug';
+
+export type LogContext = Record<string, unknown>;
+
+/**
+ * Second argument to `log.error / warn / info / debug`.
+ *
+ * Three usage shapes, detected at runtime:
+ *   - `Error`     → stack is extracted onto the entry
+ *   - `LogContext` (object) → merged into entry context; if it contains
+ *                              `{ error: Error }`, that field is pulled out
+ *                              and its stack extracted (bunyan-style)
+ *   - `unknown`   → typically a `catch` binding; treated as an Error if
+ *                   it's an Error instance, otherwise stringified into a
+ *                   `reason` field
+ */
+export type LogPayload = unknown;
+
+export interface Logger {
+  error(message: string, payload?: LogPayload): void;
+  warn(message: string, payload?: LogPayload): void;
+  info(message: string, payload?: LogPayload): void;
+  debug(message: string, payload?: LogPayload): void;
+  /**
+   * Returns a new logger that adds `ctx` to every entry it emits. The bound
+   * context wins over per-call payload context, so callers can't accidentally
+   * overwrite ownership fields like `sessionId` / `agentId`:
+   *
+   *   finalCtx = { ...payloadCtx, ...boundCtx }
+   *
+   * Children chain — `parent.createChild({a: 1}).createChild({b: 2})` binds
+   * both.
+   */
+  createChild(ctx: LogContext): Logger;
+}
+
+export interface LogEntry {
+  readonly t: number;
+  readonly level: Exclude<LogLevel, 'off'>;
+  readonly msg: string;
+  readonly ctx?: LogContext | undefined;
+  readonly error?: { readonly message: string; readonly stack?: string } | undefined;
+  readonly sessionId?: string | undefined;
+  readonly sessionLogId?: string | undefined;
+}
+
+export interface LoggingConfig {
+  readonly level: LogLevel;
+  readonly globalLogPath: string;
+  readonly globalMaxBytes: number;
+  readonly globalFiles: number;
+  readonly sessionMaxBytes: number;
+  readonly sessionFiles: number;
+}
+
+export interface SessionLogHandle {
+  readonly logger: Logger;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface SessionAttachInput {
+  readonly sessionId: string;
+  readonly sessionDir: string;
+}
+
+export interface RootLogger {
+  configure(config: LoggingConfig): Promise<void>;
+  attachSession(input: SessionAttachInput): SessionLogHandle;
+  /** False if any sink could not flush its pending batch. */
+  flush(): Promise<boolean>;
+  /** False if the global sink could not flush; true when there is no global sink. */
+  flushGlobal(): Promise<boolean>;
+  /** False if the session sink could not flush; true when there is no active sink. */
+  flushSession(sessionId: string): Promise<boolean>;
+  flushSync(): void;
+  isConfigured(): boolean;
+  getConfig(): LoggingConfig | undefined;
+}
+
+export const LOG_LEVEL_RANK: Record<LogLevel, number> = {
+  off: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+};
+
+export function levelEnabled(threshold: LogLevel, level: Exclude<LogLevel, 'off'>): boolean {
+  return LOG_LEVEL_RANK[threshold] >= LOG_LEVEL_RANK[level];
+}
diff --git a/packages/agent-core/src/loop/README.md b/packages/agent-core/src/loop/README.md
new file mode 100644
index 000000000..0b2daf030
--- /dev/null
+++ b/packages/agent-core/src/loop/README.md
@@ -0,0 +1,57 @@
+# Loop
+
+`loop` is the stateless agent loop. It does not own sessions, wire
+transport, compaction execution, permissions UI, or durable protocol
+bridging. Those are host-layer responsibilities.
+
+## Internal Owners
+
+- `run-turn.ts` owns turn-level convergence: abort and compaction safe
+  points, max-step enforcement, usage aggregation, optional continuation after
+  non-tool stops, and final `TurnResult` mapping.
+- `turn-step.ts` owns one provider step: pre/post step hooks, message
+  construction, the atomic step envelope, LLM call, streaming callback
+  wiring, and the handoff to the tool-call lifecycle.
+- `tool-call.ts` owns the tool-call batch lifecycle. Classification is
+  pure; preparation dispatches recorded `tool.call` events in provider
+  order; terminal `tool.result` events are recorded in provider order before
+  `step.end` seals the step.
+- `tool-scheduler.ts` owns stateful tool execution scheduling:
+  tasks with non-conflicting resource accesses may overlap, while conflicting
+  tasks are serialized at provider-order boundaries.
+- `llm.ts`, `events.ts`, and `types.ts` define the narrow model,
+  event/transcript, message, and tool surfaces that hosts provide to the loop.
+
+## Contracts
+
+- The core loop must not import from host-layer implementations.
+- `LLM` is the only source of model metadata, optional capability metadata,
+  and system prompt.
+- `buildMessages` builds the latest model-visible messages per model step.
+- `dispatchEvent` is the only event path the loop writes to. The dispatcher
+  records `LoopRecordedEvent`s, publishes `LoopLiveOnlyEvent`s, and routes
+  shared events such as `step.begin`, `step.end`, `tool.call`, and
+  `tool.result` to both transcript and live listeners.
+- Live event listener failures are contained by `LoopEventDispatcher` and
+  must not affect the agent loop.
+- Provider usage is recorded immediately after `LLM.chat` returns, not
+  after tool execution completes. Aborted tool execution must still report
+  spent LLM usage.
+- The transcript step envelope is intentionally partial on provider abort:
+  `step.begin` may exist without `step.end`.
+- Every dispatched `tool.call` must be followed by a matching `tool.result`
+  unless the step is interrupted before the result dispatch point.
+
+## Test Boundaries
+
+The main regression guards live in `test/loop`:
+
+- `turn-lifecycle.e2e.test.ts` covers turn convergence and usage
+  aggregation.
+- `transcript.e2e.test.ts` covers step ordering and durable transcript
+  linkage.
+- `tool-call.e2e.test.ts` and `hooks.e2e.test.ts` cover tool preparation,
+  description, result finalization, and hook safety points.
+- `abort.e2e.test.ts`, `error-paths.e2e.test.ts`, and `events.e2e.test.ts`
+  cover abort convergence, error propagation, and live event containment.
+- `streaming.e2e.test.ts` covers provider streaming callback wiring.
diff --git a/packages/agent-core/src/loop/errors.ts b/packages/agent-core/src/loop/errors.ts
new file mode 100644
index 000000000..43f7199d7
--- /dev/null
+++ b/packages/agent-core/src/loop/errors.ts
@@ -0,0 +1,27 @@
+/**
+ * Loop-local error helpers.
+ */
+
+import { ErrorCodes, KimiError, isKimiError } from '#/errors';
+
+export function createMaxStepsExceededError(maxSteps: number, message?: string): KimiError {
+  return new KimiError(ErrorCodes.LOOP_MAX_STEPS_EXCEEDED, message ?? `Turn exceeded maxSteps=${maxSteps}`, {
+    details: { maxSteps },
+  });
+}
+
+export function isMaxStepsExceededError(error: unknown): boolean {
+  return isKimiError(error) && error.code === ErrorCodes.LOOP_MAX_STEPS_EXCEEDED;
+}
+
+export function isAbortError(err: unknown): boolean {
+  if (err instanceof Error) {
+    return err.name === 'AbortError';
+  }
+  return false;
+}
+
+export function errorMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
diff --git a/packages/agent-core/src/loop/events.ts b/packages/agent-core/src/loop/events.ts
new file mode 100644
index 000000000..640ee7af4
--- /dev/null
+++ b/packages/agent-core/src/loop/events.ts
@@ -0,0 +1,182 @@
+import type { FinishReason, TextPart, ThinkPart, TokenUsage } from '@moonshot-ai/kosong';
+
+import type { ToolInputDisplay } from '../tools/display';
+import type { ExecutableToolResult, LoopStepStopReason, ToolUpdate } from './types';
+
+export type LoopInterruptReason = 'aborted' | 'max_steps' | 'error';
+
+export interface LoopStepBeginEvent {
+  readonly type: 'step.begin';
+  readonly uuid: string;
+  readonly turnId: string;
+  readonly step: number;
+}
+
+export interface LoopStepEndEvent {
+  readonly type: 'step.end';
+  readonly uuid: string;
+  readonly turnId: string;
+  readonly step: number;
+  readonly usage?: TokenUsage | undefined;
+  readonly finishReason?: LoopStepStopReason | undefined;
+  /**
+   * Provider diagnostics are optional and must not drive loop control.
+   * Use `finishReason` for normalized behavior.
+   */
+  readonly providerFinishReason?: FinishReason | undefined;
+  readonly rawFinishReason?: string | undefined;
+}
+
+export interface LoopStepRetryingEvent {
+  readonly type: 'step.retrying';
+  readonly turnId: string;
+  readonly step: number;
+  readonly stepUuid: string;
+  readonly failedAttempt: number;
+  readonly nextAttempt: number;
+  readonly maxAttempts: number;
+  readonly delayMs: number;
+  readonly errorName: string;
+  readonly errorMessage: string;
+  readonly statusCode?: number;
+}
+
+export interface LoopContentPartEvent {
+  readonly type: 'content.part';
+  readonly uuid: string;
+  readonly turnId: string;
+  readonly step: number;
+  readonly stepUuid: string;
+  readonly part: TextPart | ThinkPart;
+}
+
+export interface LoopToolCallEvent {
+  readonly type: 'tool.call';
+  readonly uuid: string;
+  readonly turnId: string;
+  readonly step: number;
+  readonly stepUuid: string;
+  readonly toolCallId: string;
+  readonly name: string;
+  readonly args: unknown;
+  readonly description?: string | undefined;
+  readonly display?: ToolInputDisplay | undefined;
+}
+
+export interface LoopToolResultEvent {
+  readonly type: 'tool.result';
+  readonly parentUuid: string;
+  readonly toolCallId: string;
+  readonly result: ExecutableToolResult;
+}
+
+export interface LoopTurnInterruptedEvent {
+  readonly type: 'turn.interrupted';
+  readonly reason: LoopInterruptReason;
+  readonly attemptedSteps: number;
+  readonly activeStep?: number | undefined;
+  readonly message?: string | undefined;
+}
+
+export interface LoopTextDeltaEvent {
+  readonly type: 'text.delta';
+  readonly delta: string;
+}
+
+export interface LoopThinkingDeltaEvent {
+  readonly type: 'thinking.delta';
+  readonly delta: string;
+}
+
+export interface LoopToolCallDeltaEvent {
+  readonly type: 'tool.call.delta';
+  readonly toolCallId: string;
+  readonly name?: string | undefined;
+  readonly argumentsPart?: string | undefined;
+}
+
+export interface LoopToolProgressEvent {
+  readonly type: 'tool.progress';
+  readonly toolCallId: string;
+  readonly update: ToolUpdate;
+}
+
+export type LoopRecordedEvent =
+  | LoopStepBeginEvent
+  | LoopStepEndEvent
+  | LoopContentPartEvent
+  | LoopToolCallEvent
+  | LoopToolResultEvent;
+
+export type LoopLiveOnlyEvent =
+  | LoopTurnInterruptedEvent
+  | LoopStepRetryingEvent
+  | LoopTextDeltaEvent
+  | LoopThinkingDeltaEvent
+  | LoopToolCallDeltaEvent
+  | LoopToolProgressEvent;
+
+export type LoopEvent = LoopRecordedEvent | LoopLiveOnlyEvent;
+export type LoopLiveEventEmitter = (event: LoopEvent) => void;
+
+export type LoopEventDispatcher = {
+  (event: LoopRecordedEvent): Promise<void>;
+  (event: LoopLiveOnlyEvent): void;
+};
+
+export interface CreateLoopEventDispatcherInput {
+  readonly appendTranscriptRecord: (record: LoopRecordedEvent) => Promise<void>;
+  readonly emitLiveEvent?: LoopLiveEventEmitter | undefined;
+}
+
+export function createLoopEventDispatcher(
+  input: CreateLoopEventDispatcherInput,
+): LoopEventDispatcher {
+  function dispatchEvent(event: LoopRecordedEvent): Promise<void>;
+  function dispatchEvent(event: LoopLiveOnlyEvent): void;
+  function dispatchEvent(event: LoopEvent): Promise<void> | void {
+    if (isRecordedEvent(event)) {
+      return recordEvent(input, event);
+    }
+    safeEmitLive(input.emitLiveEvent, event);
+  }
+  return dispatchEvent;
+}
+
+function isRecordedEvent(event: LoopEvent): event is LoopRecordedEvent {
+  return (
+    event.type === 'step.begin' ||
+    event.type === 'step.end' ||
+    event.type === 'content.part' ||
+    event.type === 'tool.call' ||
+    event.type === 'tool.result'
+  );
+}
+
+async function recordEvent(
+  input: CreateLoopEventDispatcherInput,
+  event: LoopRecordedEvent,
+): Promise<void> {
+  await input.appendTranscriptRecord(event);
+  safeEmitLive(input.emitLiveEvent, event);
+}
+
+function safeEmitLive(emit: LoopLiveEventEmitter | undefined, event: LoopEvent): void {
+  if (emit === undefined) return;
+  let maybePromise: unknown;
+  try {
+    maybePromise = (emit as (event: LoopEvent) => unknown)(event);
+  } catch {
+    return;
+  }
+  if (
+    maybePromise !== undefined &&
+    maybePromise !== null &&
+    typeof (maybePromise as { then?: unknown }).then === 'function' &&
+    typeof (maybePromise as { catch?: unknown }).catch === 'function'
+  ) {
+    (maybePromise as Promise<unknown>).catch(() => {
+      // Live listeners are best-effort; their failures must not affect the turn.
+    });
+  }
+}
diff --git a/packages/agent-core/src/loop/index.ts b/packages/agent-core/src/loop/index.ts
new file mode 100644
index 000000000..c0071df54
--- /dev/null
+++ b/packages/agent-core/src/loop/index.ts
@@ -0,0 +1,70 @@
+/**
+ * Public entry point for the stateless agent loop.
+ *
+ * Higher-level orchestration may import from this module; this module must not
+ * import from host-layer implementations.
+ */
+
+export type {
+  AfterStepHook,
+  BeforeStepResult,
+  BeforeStepHook,
+  LoopHooks,
+  LoopAfterStepContext,
+  LoopStepHookContext,
+  LoopStepStopReason,
+  LoopStoppedStepContext,
+  LoopTerminalStepStopReason,
+  LoopTurnStopReason,
+  StopReason,
+  ShouldContinueAfterStopHook,
+  ShouldContinueAfterStopResult,
+  LoopMessageBuilder,
+  ExecutableTool,
+  ToolExecution,
+  ToolCall,
+  ExecutableToolContext,
+  ToolExecutionHookContext,
+  PrepareToolExecutionHook,
+  PrepareToolExecutionResult,
+  ExecutableToolResult,
+  FinalizeToolResultContext,
+  FinalizeToolResultHook,
+  ToolUpdate,
+  TurnResult,
+} from './types';
+
+export { ToolAccesses } from './tool-access';
+
+export type {
+  CreateLoopEventDispatcherInput,
+  LoopContentPartEvent,
+  LoopRecordedEvent,
+  LoopStepBeginEvent,
+  LoopStepEndEvent,
+  LoopStepRetryingEvent,
+  LoopLiveOnlyEvent,
+  LoopEvent,
+  LoopInterruptReason,
+  LoopLiveEventEmitter,
+  LoopEventDispatcher,
+  LoopTextDeltaEvent,
+  LoopThinkingDeltaEvent,
+  LoopToolCallDeltaEvent,
+  LoopToolCallEvent,
+  LoopToolProgressEvent,
+  LoopToolResultEvent,
+  LoopTurnInterruptedEvent,
+} from './events';
+export { createLoopEventDispatcher } from './events';
+
+export type {
+  LLM,
+  LLMChatParams,
+  LLMChatResponse,
+  LLMRequestLogContext,
+  ToolCallDelta,
+} from './llm';
+
+export { runTurn } from './run-turn';
+export type { RunTurnInput } from './run-turn';
diff --git a/packages/agent-core/src/loop/llm.ts b/packages/agent-core/src/loop/llm.ts
new file mode 100644
index 000000000..df8314593
--- /dev/null
+++ b/packages/agent-core/src/loop/llm.ts
@@ -0,0 +1,71 @@
+/**
+ * LLM contract for the model capability used by the stateless loop.
+ *
+ * The immutable `LLM` object owns provider/model metadata, capability metadata,
+ * and the system prompt. Other host concerns are injected through separate
+ * surfaces.
+ */
+
+import type {
+  FinishReason,
+  Message,
+  ModelCapability,
+  TextPart,
+  ThinkPart,
+  TokenUsage,
+  Tool,
+  ToolCall,
+} from '@moonshot-ai/kosong';
+
+export interface ToolCallDelta {
+  readonly toolCallId: string;
+  readonly name?: string | undefined;
+  readonly argumentsPart?: string | undefined;
+}
+
+export interface LLMRequestLogContext {
+  readonly turnId?: string;
+  readonly step?: number;
+  readonly stepUuid?: string;
+  readonly attempt?: number;
+  readonly maxAttempts?: number;
+}
+
+export interface LLMChatParams {
+  messages: Message[];
+  tools: readonly Tool[];
+  signal: AbortSignal;
+  requestLogContext?: LLMRequestLogContext;
+  onTextDelta?: ((delta: string) => void) | undefined;
+  onThinkDelta?: ((delta: string) => void) | undefined;
+  onToolCallDelta?: ((delta: ToolCallDelta) => void) | undefined;
+  /**
+   * Fires once per completed text block. Additive relative to
+   * `onTextDelta` — deltas still fire chunk-by-chunk for UI streaming.
+   * Returned promises are awaited by the adapter to preserve transcript append
+   * order. Durable transcript writes receive completed blocks only.
+   */
+  onTextPart?: ((part: TextPart) => Promise<void> | void) | undefined;
+  /**
+   * Fires once per completed thinking block. Additive relative to
+   * `onThinkDelta` — deltas still fire chunk-by-chunk for UI streaming.
+   * Returned promises are awaited by the adapter to preserve transcript append
+   * order. Durable transcript writes receive completed blocks only.
+   */
+  onThinkPart?: ((part: ThinkPart) => Promise<void> | void) | undefined;
+}
+
+export interface LLMChatResponse {
+  toolCalls: ToolCall[];
+  providerFinishReason?: FinishReason | undefined;
+  rawFinishReason?: string | undefined;
+  usage: TokenUsage;
+}
+
+export interface LLM {
+  readonly systemPrompt: string;
+  readonly modelName: string;
+  readonly capability?: ModelCapability | undefined;
+  isRetryableError?(error: unknown): boolean;
+  chat(params: LLMChatParams): Promise<LLMChatResponse>;
+}
diff --git a/packages/agent-core/src/loop/retry.ts b/packages/agent-core/src/loop/retry.ts
new file mode 100644
index 000000000..eba9247bd
--- /dev/null
+++ b/packages/agent-core/src/loop/retry.ts
@@ -0,0 +1,137 @@
+import { sleep } from '@antfu/utils';
+import * as retry from 'retry';
+
+import type { Logger } from '#/logging/types';
+
+import { abortable } from '../utils/abort';
+import type { LoopEventDispatcher } from './events';
+import { isAbortError } from './errors';
+import type { LLM, LLMChatParams, LLMChatResponse } from './llm';
+
+export const DEFAULT_MAX_RETRY_ATTEMPTS = 3;
+
+const RETRY_MIN_TIMEOUT_MS = 300;
+const RETRY_MAX_TIMEOUT_MS = 5000;
+const RETRY_FACTOR = 2;
+
+export interface ChatWithRetryInput {
+  readonly llm: LLM;
+  readonly params: LLMChatParams;
+  readonly dispatchEvent: LoopEventDispatcher;
+  readonly turnId: string;
+  readonly currentStep: number;
+  readonly stepUuid: string;
+  readonly maxAttempts?: number;
+  readonly log?: Logger | undefined;
+}
+
+export async function chatWithRetry(input: ChatWithRetryInput): Promise<LLMChatResponse> {
+  const maxAttempts = input.maxAttempts ?? DEFAULT_MAX_RETRY_ATTEMPTS;
+
+  if (input.llm.isRetryableError === undefined || maxAttempts <= 1) {
+    const effectiveMaxAttempts = Math.max(maxAttempts, 1);
+    try {
+      return await input.llm.chat(paramsForAttempt(input, 1, effectiveMaxAttempts));
+    } catch (error) {
+      logRequestFailure(input, error, 1, effectiveMaxAttempts);
+      throw error;
+    }
+  }
+
+  const delays = retryBackoffDelays(maxAttempts);
+
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await input.llm.chat(paramsForAttempt(input, attempt, maxAttempts));
+    } catch (error) {
+      if (attempt >= maxAttempts || !input.llm.isRetryableError(error)) {
+        logRequestFailure(input, error, attempt, maxAttempts);
+        throw error;
+      }
+
+      const delayMs = delays[attempt - 1] ?? 0;
+      input.params.signal.throwIfAborted();
+      input.dispatchEvent({
+        type: 'step.retrying',
+        turnId: input.turnId,
+        step: input.currentStep,
+        stepUuid: input.stepUuid,
+        failedAttempt: attempt,
+        nextAttempt: attempt + 1,
+        maxAttempts,
+        delayMs,
+        ...retryErrorFields(error),
+      });
+      await sleepForRetry(delayMs, input.params.signal);
+    }
+  }
+}
+
+function logRequestFailure(
+  input: ChatWithRetryInput,
+  error: unknown,
+  attempt: number,
+  maxAttempts: number,
+): void {
+  if (isAbortError(error) || input.params.signal.aborted) return;
+  input.log?.warn('llm request failed', {
+    turnId: input.turnId,
+    step: input.currentStep,
+    attempt,
+    maxAttempts,
+    model: input.llm.modelName,
+    ...retryErrorFields(error),
+  });
+}
+
+function paramsForAttempt(
+  input: ChatWithRetryInput,
+  attempt: number,
+  maxAttempts: number,
+): LLMChatParams {
+  return {
+    ...input.params,
+    requestLogContext: {
+      turnId: input.turnId,
+      step: input.currentStep,
+      stepUuid: input.stepUuid,
+      attempt,
+      maxAttempts,
+    },
+  };
+}
+
+export function retryBackoffDelays(maxAttempts: number): number[] {
+  return retry.timeouts({
+    retries: Math.max(maxAttempts - 1, 0),
+    minTimeout: RETRY_MIN_TIMEOUT_MS,
+    maxTimeout: RETRY_MAX_TIMEOUT_MS,
+    factor: RETRY_FACTOR,
+    randomize: true,
+  });
+}
+
+export async function sleepForRetry(delayMs: number, signal: AbortSignal): Promise<void> {
+  signal.throwIfAborted();
+  await abortable(sleep(delayMs), signal);
+}
+
+interface RetryErrorFields {
+  readonly errorName: string;
+  readonly errorMessage: string;
+  readonly statusCode?: number;
+}
+
+function retryErrorFields(error: unknown): RetryErrorFields {
+  return {
+    errorName: error instanceof Error ? error.name : typeof error,
+    errorMessage: error instanceof Error ? error.message : String(error),
+    statusCode: maybeStatusCode(error),
+  };
+}
+
+function maybeStatusCode(error: unknown): number | undefined {
+  if (typeof error !== 'object' || error === null) return undefined;
+  const statusCode = (error as { statusCode?: unknown }).statusCode;
+  return typeof statusCode === 'number' ? statusCode : undefined;
+}
diff --git a/packages/agent-core/src/loop/run-turn.ts b/packages/agent-core/src/loop/run-turn.ts
new file mode 100644
index 000000000..92e9e6f32
--- /dev/null
+++ b/packages/agent-core/src/loop/run-turn.ts
@@ -0,0 +1,141 @@
+/**
+ * Turn-level loop for a stateless agent run.
+ *
+ * Owns convergence across steps: abort checks at loop boundaries, max-step
+ * enforcement, usage aggregation, optional continuation after non-tool stops,
+ * and final `TurnResult` mapping. One-step execution lives in `turn-step.ts`.
+ */
+
+import { addUsage, emptyUsage, type TokenUsage } from '@moonshot-ai/kosong';
+
+import type { Logger } from '#/logging/types';
+
+import {
+  createMaxStepsExceededError,
+  errorMessage,
+  isAbortError,
+  isMaxStepsExceededError,
+} from './errors';
+import type { LoopInterruptReason, LoopEventDispatcher, LoopTurnInterruptedEvent } from './events';
+import type { LLM } from './llm';
+import { executeLoopStep } from './turn-step';
+import type {
+  ExecutableTool,
+  LoopHooks,
+  LoopMessageBuilder,
+  LoopTerminalStepStopReason,
+  LoopTurnStopReason,
+  TurnResult,
+} from './types';
+
+const DEFAULT_MAX_STEPS = 1000;
+
+export interface RunTurnInput {
+  readonly turnId: string;
+  readonly signal: AbortSignal;
+  readonly llm: LLM;
+  readonly buildMessages: LoopMessageBuilder;
+  readonly dispatchEvent: LoopEventDispatcher;
+  readonly tools?: readonly ExecutableTool[] | undefined;
+  readonly hooks?: LoopHooks | undefined;
+  readonly log?: Logger | undefined;
+  readonly maxSteps?: number | undefined;
+  readonly maxRetryAttempts?: number;
+}
+
+export async function runTurn(input: RunTurnInput): Promise<TurnResult> {
+  const {
+    turnId,
+    signal,
+    llm,
+    buildMessages,
+    dispatchEvent,
+    tools,
+    hooks,
+    log,
+    maxSteps = DEFAULT_MAX_STEPS,
+    maxRetryAttempts,
+  } = input;
+  let usage: TokenUsage = emptyUsage();
+  let steps = 0;
+  // Normal exits overwrite this with the completed step's stop reason.
+  let stopReason: LoopTurnStopReason = 'end_turn';
+  let activeStep: number | undefined;
+  const recordStepUsage = (stepUsage: TokenUsage): void => {
+    usage = addUsage(usage, stepUsage);
+  };
+
+  try {
+    while (true) {
+      signal.throwIfAborted();
+
+      if (steps >= maxSteps) {
+        throw createMaxStepsExceededError(maxSteps);
+      }
+
+      steps += 1;
+      activeStep = steps;
+      const stepResult = await executeLoopStep({
+        turnId,
+        signal,
+        buildMessages,
+        dispatchEvent,
+        llm,
+        tools,
+        hooks,
+        log,
+        currentStep: steps,
+        maxRetryAttempts,
+        recordUsage: recordStepUsage,
+      });
+      activeStep = undefined;
+
+      if (stepResult.stopReason === 'tool_use') {
+        continue;
+      }
+
+      const terminalStopReason: LoopTerminalStepStopReason = stepResult.stopReason;
+      stopReason = terminalStopReason;
+
+      if (
+        !(
+          await hooks?.shouldContinueAfterStop?.({
+            turnId,
+            stepNumber: steps,
+            usage: stepResult.usage,
+            stopReason: terminalStopReason,
+            signal,
+            llm,
+          })
+        )?.continue
+      ) {
+        break;
+      }
+    }
+  } catch (error) {
+    if (isAbortError(error) || signal.aborted) {
+      dispatchEvent(makeInterruptedEvent('aborted', steps, activeStep));
+      return { stopReason: 'aborted', steps, usage };
+    }
+    const reason: LoopInterruptReason = isMaxStepsExceededError(error) ? 'max_steps' : 'error';
+    dispatchEvent(makeInterruptedEvent(reason, steps, activeStep, errorMessage(error)));
+    throw error;
+  }
+
+  return { stopReason, steps, usage };
+}
+
+function makeInterruptedEvent(
+  reason: LoopInterruptReason,
+  attemptedSteps: number,
+  activeStep: number | undefined,
+  message?: string | undefined,
+): LoopTurnInterruptedEvent {
+  return {
+    type: 'turn.interrupted',
+    reason,
+    attemptedSteps,
+    ...(activeStep !== undefined ? { activeStep } : {}),
+    ...(message !== undefined ? { message } : {}),
+  };
+}
diff --git a/packages/agent-core/src/loop/tool-access.ts b/packages/agent-core/src/loop/tool-access.ts
new file mode 100644
index 000000000..f14eecb3e
--- /dev/null
+++ b/packages/agent-core/src/loop/tool-access.ts
@@ -0,0 +1,150 @@
+export type ToolFileAccessOperation = 'read' | 'write' | 'readwrite' | 'search';
+
+export type ToolResourceAccess =
+  | {
+      readonly kind: 'file';
+      readonly operation: ToolFileAccessOperation;
+      /**
+       * Canonical file path when the access can be narrowed. Omitted means the
+       * operation may touch any file in the backend file namespace.
+       */
+      readonly path?: string;
+      readonly recursive?: boolean;
+    }
+  | {
+      /**
+       * Arbitrary side effects or resources that cannot be represented as a
+       * file access. This is intentionally operation-less and globally
+       * exclusive for concurrency.
+       */
+      readonly kind: 'all';
+    };
+
+export type ToolAccesses = readonly ToolResourceAccess[];
+
+export const ToolAccesses = {
+  none(): ToolAccesses {
+    return [];
+  },
+
+  all(): ToolAccesses {
+    return [{ kind: 'all' }];
+  },
+
+  file(
+    operation: ToolFileAccessOperation,
+    path?: string,
+    options: { readonly recursive?: boolean } = {},
+  ): ToolAccesses {
+    const access: {
+      kind: 'file';
+      operation: ToolFileAccessOperation;
+      path?: string;
+      recursive?: boolean;
+    } = { kind: 'file', operation };
+    if (path !== undefined) access.path = path;
+    if (options.recursive !== undefined) access.recursive = options.recursive;
+    return [access];
+  },
+
+  readFile(path: string): ToolAccesses {
+    return ToolAccesses.file('read', path);
+  },
+
+  readTree(path: string): ToolAccesses {
+    return ToolAccesses.file('read', path, { recursive: true });
+  },
+
+  readAnyFile(): ToolAccesses {
+    return ToolAccesses.file('read');
+  },
+
+  writeFile(path: string): ToolAccesses {
+    return ToolAccesses.file('write', path);
+  },
+
+  writeTree(path: string): ToolAccesses {
+    return ToolAccesses.file('write', path, { recursive: true });
+  },
+
+  writeAnyFile(): ToolAccesses {
+    return ToolAccesses.file('write');
+  },
+
+  readWriteFile(path: string): ToolAccesses {
+    return ToolAccesses.file('readwrite', path);
+  },
+
+  readWriteTree(path: string): ToolAccesses {
+    return ToolAccesses.file('readwrite', path, { recursive: true });
+  },
+
+  readWriteAnyFile(): ToolAccesses {
+    return ToolAccesses.file('readwrite');
+  },
+
+  searchTree(path: string): ToolAccesses {
+    return ToolAccesses.file('search', path, { recursive: true });
+  },
+
+  searchAnyFile(): ToolAccesses {
+    return ToolAccesses.file('search');
+  },
+
+  conflict(left: ToolAccesses, right: ToolAccesses): boolean {
+    return left.some((leftAccess) =>
+      right.some((rightAccess) => resourceAccessesConflict(leftAccess, rightAccess)),
+    );
+  },
+};
+
+function resourceAccessesConflict(left: ToolResourceAccess, right: ToolResourceAccess): boolean {
+  if (left.kind === 'all' || right.kind === 'all') return true;
+  if (!fileOperationsConflict(left.operation, right.operation)) return false;
+  return fileAccessesOverlap(left, right);
+}
+
+function fileOperationsConflict(
+  left: ToolFileAccessOperation,
+  right: ToolFileAccessOperation,
+): boolean {
+  return fileOperationWrites(left) || fileOperationWrites(right);
+}
+
+function fileOperationWrites(operation: ToolFileAccessOperation): boolean {
+  switch (operation) {
+    case 'read':
+    case 'search':
+      return false;
+    case 'write':
+    case 'readwrite':
+      return true;
+  }
+}
+
+function fileAccessesOverlap(
+  left: Extract<ToolResourceAccess, { kind: 'file' }>,
+  right: Extract<ToolResourceAccess, { kind: 'file' }>,
+): boolean {
+  if (left.path === undefined || right.path === undefined) return true;
+
+  const leftPath = normalizePath(left.path);
+  const rightPath = normalizePath(right.path);
+  if (leftPath === rightPath) return true;
+
+  const leftPrefix = leftPath.endsWith('/') ? leftPath : `${leftPath}/`;
+  const rightPrefix = rightPath.endsWith('/') ? rightPath : `${rightPath}/`;
+  return (
+    (left.recursive === true && rightPath.startsWith(leftPrefix)) ||
+    (right.recursive === true && leftPath.startsWith(rightPrefix))
+  );
+}
+
+function normalizePath(path: string): string {
+  const normalized = path.replaceAll('\\', '/').replaceAll(/\/+/g, '/');
+  const folded = normalized.toLowerCase();
+  if (folded.length > 1 && folded.endsWith('/')) {
+    return folded.slice(0, -1);
+  }
+  return folded;
+}
diff --git a/packages/agent-core/src/loop/tool-call.ts b/packages/agent-core/src/loop/tool-call.ts
new file mode 100644
index 000000000..6981ebb51
--- /dev/null
+++ b/packages/agent-core/src/loop/tool-call.ts
@@ -0,0 +1,626 @@
+/**
+ * Tool-call lifecycle for one completed provider response.
+ *
+ * This module keeps the provider-order invariant in one place:
+ *   - validate every provider tool call before hooks or events
+ *   - run preparation hooks and compute tool-call display fields in provider order
+ *   - dispatch `tool.call` before execution starts
+ *   - execute tools with non-conflicting resource accesses concurrently
+ *   - serialize tools whose resource accesses conflict
+ *   - dispatch terminal `tool.result` events in provider order
+ *
+ * These phases are coupled by transcript ordering and abort handling, so they
+ * should be reviewed together.
+ */
+
+import type { ContentPart } from '@moonshot-ai/kosong';
+
+import type { Logger } from '#/logging/types';
+import {
+  compileToolArgsValidator,
+  validateToolArgs,
+  type JsonType,
+  type ToolArgsValidator,
+} from '../tools/args-validator';
+import { PathSecurityError } from '../tools/policies/path-access';
+
+import { errorMessage, isAbortError } from './errors';
+import type { LoopEventDispatcher, LoopToolCallEvent } from './events';
+import type { LLM, LLMChatResponse } from './llm';
+import { ToolAccesses } from './tool-access';
+import { ToolScheduler, type ToolCallTask } from './tool-scheduler';
+import type {
+  ExecutableTool,
+  LoopHooks,
+  ToolCall,
+  PrepareToolExecutionResult,
+  ExecutableToolResult,
+  RunnableToolExecution,
+  ToolExecution,
+} from './types';
+
+const GRACE_TIMEOUT_MS = 2_000;
+const TOOL_OUTPUT_EMPTY = 'Tool output is empty.';
+const TOOL_OUTPUT_NON_TEXT = 'Tool returned non-text content.';
+
+const validators = new WeakMap<ExecutableTool, ToolArgsValidator>();
+
+export interface ToolCallStepContext {
+  readonly tools?: readonly ExecutableTool[] | undefined;
+  readonly hooks?: LoopHooks | undefined;
+  readonly log?: Logger | undefined;
+  readonly dispatchEvent: LoopEventDispatcher;
+  readonly llm: LLM;
+  readonly signal: AbortSignal;
+  readonly turnId: string;
+  readonly currentStep: number;
+  readonly stepUuid: string;
+}
+
+type PreflightedToolCall = RunnableToolCall | RejectedToolCall;
+
+interface RunnableToolCall {
+  readonly kind: 'runnable';
+  readonly toolCall: ToolCall;
+  readonly toolName: string;
+  readonly tool: ExecutableTool;
+  readonly args: unknown;
+}
+
+interface RejectedToolCall {
+  readonly kind: 'rejected';
+  readonly toolCall: ToolCall;
+  readonly toolName: string;
+  readonly args: unknown;
+  readonly output: string;
+}
+
+type PrepareToolExecutionDecision =
+  | { readonly kind: 'allowed'; readonly args: unknown; readonly metadata?: unknown }
+  | { readonly kind: 'synthetic'; readonly args: unknown; readonly result: ExecutableToolResult }
+  | { readonly kind: 'blocked'; readonly args: unknown; readonly output: string }
+  | { readonly kind: 'hookFailed'; readonly args: unknown; readonly output: string };
+
+interface PendingToolResult {
+  readonly toolCall: ToolCall;
+  readonly toolName: string;
+  readonly args: unknown;
+  readonly result: ExecutableToolResult;
+  readonly stopTurn?: boolean | undefined;
+}
+
+interface PreparedToolCallTask {
+  readonly task: ToolCallTask<PendingToolResult>;
+  readonly stopBatchAfterThis?: boolean | undefined;
+}
+
+type ToolCallDisplayFields = Pick<LoopToolCallEvent, 'description' | 'display'>;
+
+export interface ToolCallBatchResult {
+  readonly stopTurn: boolean;
+}
+
+export async function runToolCallBatch(
+  step: ToolCallStepContext,
+  response: LLMChatResponse,
+): Promise<ToolCallBatchResult> {
+  if (response.toolCalls.length === 0) return { stopTurn: false };
+  const calls = response.toolCalls.map((toolCall) => preflightToolCall(step.tools, toolCall));
+  const scheduler = new ToolScheduler<PendingToolResult>();
+  const pendingResults: Array<Promise<PendingToolResult>> = [];
+  let stopTurn = false;
+
+  try {
+    for (let index = 0; index < calls.length; index += 1) {
+      const call = calls[index]!;
+      const prepared = await prepareToolCall(step, call);
+      pendingResults.push(scheduler.add(prepared.task));
+
+      if (prepared.stopBatchAfterThis === true) {
+        stopTurn = true;
+        for (const skippedCall of calls.slice(index + 1)) {
+          const skippedTask = await prepareSkippedToolCall(step, skippedCall);
+          pendingResults.push(scheduler.add(skippedTask));
+        }
+        break;
+      }
+    }
+
+    // Tool tasks may finish out of order; terminal results are still emitted in
+    // provider order. Await all tasks so each recorded `tool.call` gets a
+    // paired `tool.result`; the caller checks abort before writing `step.end`.
+    for (const pendingResult of pendingResults) {
+      const result = await finalizePendingToolResult(step, await pendingResult);
+      if (result.stopTurn === true) stopTurn = true;
+      await step.dispatchEvent({
+        type: 'tool.result',
+        parentUuid: result.toolCall.id,
+        toolCallId: result.toolCall.id,
+        result: result.result,
+      });
+    }
+  } finally {
+    // Preparation or result dispatch can throw after execution has started.
+    // Always settle spawned tasks before the caller continues so rejected
+    // execute promises cannot surface as detached unhandled rejections.
+    await Promise.allSettled(pendingResults);
+  }
+  return { stopTurn };
+}
+
+/**
+ * Provider-order validation pass. It does not run hooks, spawn tools, or write
+ * events. Validator compilation may populate the local cache.
+ */
+function preflightToolCall(
+  tools: readonly ExecutableTool[] | undefined,
+  toolCall: ToolCall,
+): PreflightedToolCall {
+  const toolName = toolCall.function.name;
+  const parsedArgs = parseToolCallArguments(toolCall.function.arguments);
+  const args = parsedArgs.success ? parsedArgs.data : {};
+  const tool = tools?.find((candidate) => candidate.name === toolName);
+  if (tool === undefined) {
+    return {
+      kind: 'rejected',
+      toolCall,
+      toolName,
+      args,
+      output: `Tool "${toolName}" not found`,
+    };
+  }
+  if (!parsedArgs.success) {
+    return {
+      kind: 'rejected',
+      toolCall,
+      toolName,
+      args,
+      output: `Invalid args for tool "${toolName}": malformed JSON in arguments: ${parsedArgs.error}`,
+    };
+  }
+  const validationError = validateExecutableToolArgs(tool, parsedArgs.data);
+  if (validationError !== null) {
+    return {
+      kind: 'rejected',
+      toolCall,
+      toolName,
+      args: parsedArgs.data,
+      output: `Invalid args for tool "${toolName}": ${validationError}`,
+    };
+  }
+  return { kind: 'runnable', toolCall, toolName, tool, args: parsedArgs.data };
+}
+
+function parseToolCallArguments(
+  raw: string | null,
+):
+  | { readonly success: true; readonly data: unknown }
+  | { readonly success: false; readonly error: string } {
+  if (raw === null || raw.length === 0) {
+    return { success: true, data: {} };
+  }
+  try {
+    return { success: true, data: JSON.parse(raw) as unknown };
+  } catch (error) {
+    return { success: false, error: errorMessage(error) };
+  }
+}
+
+function validateExecutableToolArgs(tool: ExecutableTool, args: unknown): string | null {
+  let validator = validators.get(tool);
+  if (validator === undefined) {
+    try {
+      validator = compileToolArgsValidator(tool.parameters);
+      validators.set(tool, validator);
+    } catch (error) {
+      return error instanceof Error ? error.message : String(error);
+    }
+  }
+  return validateToolArgs(validator, args as JsonType);
+}
+
+async function prepareToolCall(
+  step: ToolCallStepContext,
+  call: PreflightedToolCall,
+): Promise<PreparedToolCallTask> {
+  if (call.kind === 'rejected') {
+    await dispatchToolCall(step, call, call.args);
+    return { task: makeResolvedToolCallTask(makeErrorToolResult(call, call.args, call.output)) };
+  }
+
+  const decision = await runPrepareToolExecutionHook(step, call);
+  if (decision.kind === 'blocked') {
+    await dispatchToolCall(step, call, decision.args);
+    return {
+      task: makeResolvedToolCallTask(makeErrorToolResult(call, decision.args, decision.output)),
+    };
+  }
+
+  if (decision.kind === 'hookFailed') {
+    await dispatchToolCall(step, call, decision.args);
+    return {
+      task: makeResolvedToolCallTask(makeErrorToolResult(call, decision.args, decision.output)),
+    };
+  }
+
+  if (decision.kind === 'synthetic') {
+    await dispatchToolCall(step, call, decision.args);
+    return {
+      task: makeResolvedToolCallTask(makeToolResult(call, decision.args, decision.result)),
+      stopBatchAfterThis: toolResultStopsTurn(decision.result),
+    };
+  }
+
+  const validationError = validateExecutableToolArgs(call.tool, decision.args);
+  if (validationError !== null) {
+    await dispatchToolCall(step, call, decision.args);
+    const output = `Invalid args for tool "${call.toolName}" after prepareToolExecution hook: ${validationError}`;
+    return { task: makeResolvedToolCallTask(makeErrorToolResult(call, decision.args, output)) };
+  }
+
+  const effectiveArgs = decision.args;
+  let execution: ToolExecution;
+  try {
+    execution = call.tool.resolveExecution(effectiveArgs);
+  } catch (error) {
+    if (!(error instanceof PathSecurityError)) {
+      step.log?.warn('tool execution setup failed', {
+        toolName: call.toolName,
+        toolCallId: call.toolCall.id,
+        error,
+      });
+    }
+    const output =
+      error instanceof PathSecurityError
+        ? error.message
+        : `Tool "${call.toolName}" failed to resolve execution: ${errorMessage(error)}`;
+    await dispatchToolCall(step, call, effectiveArgs);
+    return {
+      task: makeResolvedToolCallTask(makeErrorToolResult(call, effectiveArgs, output)),
+    };
+  }
+
+  const displayFields = toolCallDisplayFieldsFromExecution(execution);
+  await dispatchToolCall(step, call, effectiveArgs, displayFields);
+
+  if (step.signal.aborted) {
+    return {
+      task: makeResolvedToolCallTask(
+        makeErrorToolResult(call, effectiveArgs, `Tool "${call.toolName}" was aborted`),
+      ),
+    };
+  }
+
+  if (execution.isError === true) {
+    return {
+      task: makeResolvedToolCallTask(makeToolResult(call, effectiveArgs, execution)),
+      stopBatchAfterThis: execution.stopTurn,
+    };
+  }
+
+  return {
+    task: {
+      accesses: execution.accesses ?? ToolAccesses.all(),
+      start: async () => ({
+        result: runRunnableToolCall(step, call, effectiveArgs, decision.metadata, execution),
+      }),
+    },
+  };
+}
+
+async function prepareSkippedToolCall(
+  step: ToolCallStepContext,
+  call: PreflightedToolCall,
+): Promise<ToolCallTask<PendingToolResult>> {
+  const output = 'Tool skipped because a previous tool call stopped the turn.';
+  await dispatchToolCall(step, call, call.args);
+  return makeResolvedToolCallTask(makeErrorToolResult(call, call.args, output));
+}
+
+function makeResolvedToolCallTask(result: PendingToolResult): ToolCallTask<PendingToolResult> {
+  return {
+    accesses: ToolAccesses.none(),
+    start: async () => ({ result: Promise.resolve(result) }),
+  };
+}
+
+/**
+ * Run `prepareToolExecution` in provider order before recording `tool.call`.
+ * Hook decisions can block a call or replace args before execution starts.
+ */
+async function runPrepareToolExecutionHook(
+  step: ToolCallStepContext,
+  call: RunnableToolCall,
+): Promise<PrepareToolExecutionDecision> {
+  const { hooks, signal, turnId, currentStep, llm } = step;
+  const { toolCall, args } = call;
+
+  if (hooks?.prepareToolExecution === undefined) {
+    return { kind: 'allowed', args };
+  }
+
+  let hookResult: PrepareToolExecutionResult | undefined;
+  try {
+    hookResult = await hooks.prepareToolExecution({
+      toolCall,
+      tool: call.tool,
+      args,
+      turnId,
+      stepNumber: currentStep,
+      signal,
+      llm,
+    });
+  } catch (error) {
+    // If the turn is cancelled while an abort-aware hook is awaited, report the
+    // call as aborted instead of treating it as a hook failure.
+    if (isAbortError(error) || signal.aborted) {
+      return {
+        kind: 'hookFailed',
+        args,
+        output: `Tool "${call.toolName}" was aborted during prepareToolExecution hook`,
+      };
+    }
+    return {
+      kind: 'hookFailed',
+      args,
+      output: `prepareToolExecution hook failed for "${call.toolName}": ${errorMessage(error)}`,
+    };
+  }
+
+  const effectiveArgs = hookResult?.updatedArgs ?? args;
+  if (hookResult?.block === true) {
+    return {
+      kind: 'blocked',
+      args: effectiveArgs,
+      output: hookResult.reason ?? `Tool call "${call.toolName}" was blocked`,
+    };
+  }
+
+  if (hookResult?.syntheticResult !== undefined) {
+    return { kind: 'synthetic', args: effectiveArgs, result: hookResult.syntheticResult };
+  }
+
+  return { kind: 'allowed', args: effectiveArgs, metadata: hookResult?.executionMetadata };
+}
+
+function toolCallDisplayFieldsFromExecution(
+  execution: ToolExecution,
+): ToolCallDisplayFields | undefined {
+  if (execution.isError === true) return undefined;
+  const description = execution.description;
+  const display = execution.display;
+  return {
+    description: description !== undefined && description.length > 0 ? description : undefined,
+    display,
+  };
+}
+
+async function runRunnableToolCall(
+  step: ToolCallStepContext,
+  call: RunnableToolCall,
+  effectiveArgs: unknown,
+  metadata: unknown,
+  execution: RunnableToolExecution,
+): Promise<PendingToolResult> {
+  const { signal } = step;
+  const { toolCall, toolName } = call;
+
+  if (signal.aborted) {
+    return makeErrorToolResult(call, effectiveArgs, `Tool "${toolName}" was aborted`);
+  }
+
+  let toolResult: ExecutableToolResult;
+  try {
+    toolResult = await executeTool(step, execution, toolCall, toolName, metadata);
+  } catch (error) {
+    const aborted = isAbortError(error) || signal.aborted;
+    if (!aborted) {
+      step.log?.warn('tool execution failed', {
+        toolName,
+        toolCallId: toolCall.id,
+        error,
+      });
+    }
+    const output = aborted
+      ? `Tool "${toolName}" was aborted`
+      : `Tool "${toolName}" failed: ${errorMessage(error)}`;
+    return makeErrorToolResult(call, effectiveArgs, output);
+  }
+
+  return makeToolResult(call, effectiveArgs, toolResult);
+}
+
+async function finalizePendingToolResult(
+  step: ToolCallStepContext,
+  pendingResult: PendingToolResult,
+): Promise<PendingToolResult> {
+  const { hooks, signal, turnId, currentStep, llm } = step;
+  if (hooks?.finalizeToolResult === undefined) {
+    return { ...pendingResult, result: normalizeToolResult(pendingResult.result) };
+  }
+
+  try {
+    const finalizedResult = await hooks.finalizeToolResult({
+      toolCall: pendingResult.toolCall,
+      args: pendingResult.args,
+      result: pendingResult.result,
+      turnId,
+      stepNumber: currentStep,
+      signal,
+      llm,
+    });
+    const effectiveResult = finalizedResult ?? pendingResult.result;
+    return {
+      ...pendingResult,
+      stopTurn: pendingResult.stopTurn === true || toolResultStopsTurn(effectiveResult),
+      result: normalizeToolResult(effectiveResult),
+    };
+  } catch (error) {
+    // This is the redaction/truncation boundary. If it fails, do not persist
+    // the raw tool output; write an error result instead.
+    const aborted = isAbortError(error) || signal.aborted;
+    if (!aborted) {
+      step.log?.warn('finalizeToolResult hook failed', {
+        toolName: pendingResult.toolName,
+        toolCallId: pendingResult.toolCall.id,
+        error,
+      });
+    }
+    const output = aborted
+      ? `Tool "${pendingResult.toolName}" aborted during finalizeToolResult hook.`
+      : `finalizeToolResult hook failed for "${pendingResult.toolName}": ${errorMessage(error)}`;
+    return {
+      ...pendingResult,
+      stopTurn: pendingResult.stopTurn,
+      result: { output, isError: true },
+    };
+  }
+}
+
+async function executeTool(
+  step: ToolCallStepContext,
+  execution: RunnableToolExecution,
+  toolCall: ToolCall,
+  toolName: string,
+  metadata: unknown,
+): Promise<ExecutableToolResult> {
+  const { dispatchEvent, signal, turnId } = step;
+
+  signal.throwIfAborted();
+
+  const executePromise = execution.execute({
+    turnId,
+    toolCallId: toolCall.id,
+    metadata,
+    signal,
+    onUpdate: (update) => {
+      if (signal.aborted) return;
+      dispatchEvent({
+        type: 'tool.progress',
+        toolCallId: toolCall.id,
+        update,
+      });
+    },
+  });
+  return raceExecuteWithGraceTimeout(executePromise, signal, toolName);
+}
+
+async function raceExecuteWithGraceTimeout(
+  executePromise: Promise<ExecutableToolResult>,
+  signal: AbortSignal,
+  toolName: string,
+): Promise<ExecutableToolResult> {
+  let graceTimer: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+
+  const graceSentinel: Promise<ExecutableToolResult> = new Promise((resolve) => {
+    const armTimer = (): void => {
+      graceTimer = setTimeout(() => {
+        resolve({
+          output: `Tool "${toolName}" aborted by grace timeout (${String(GRACE_TIMEOUT_MS)}ms)`,
+          isError: true,
+        });
+      }, GRACE_TIMEOUT_MS);
+    };
+    if (signal.aborted) {
+      armTimer();
+    } else {
+      onAbort = armTimer;
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+  });
+
+  try {
+    // Tools that ignore AbortSignal may never settle. After abort, the grace
+    // branch lets the turn finish with a synthetic error result.
+    return await Promise.race([executePromise, graceSentinel]);
+  } finally {
+    if (graceTimer !== undefined) clearTimeout(graceTimer);
+    if (onAbort !== undefined) {
+      try {
+        signal.removeEventListener('abort', onAbort);
+      } catch {
+        // Some AbortSignal polyfills do not implement removeEventListener.
+      }
+    }
+  }
+}
+
+function isMediaContentPart(part: ContentPart): boolean {
+  return part.type === 'image_url' || part.type === 'audio_url' || part.type === 'video_url';
+}
+
+function normalizeToolResult(r: ExecutableToolResult): ExecutableToolResult {
+  let output: ExecutableToolResult['output'];
+  if (typeof r.output === 'string') {
+    output = r.output.length > 0 ? r.output : TOOL_OUTPUT_EMPTY;
+  } else if (r.output.length === 0) {
+    output = TOOL_OUTPUT_EMPTY;
+  } else {
+    const hasMediaBlock = r.output.some(isMediaContentPart);
+    if (hasMediaBlock) {
+      const hasNonEmptyText = r.output.some((c) => c.type === 'text' && c.text.length > 0);
+      output = hasNonEmptyText
+        ? r.output
+        : [{ type: 'text', text: TOOL_OUTPUT_NON_TEXT }, ...r.output];
+    } else {
+      const textJoined = r.output
+        .filter((c): c is Extract<typeof c, { type: 'text' }> => c.type === 'text')
+        .map((c) => c.text)
+        .join('');
+      output = textJoined.length > 0 ? textJoined : TOOL_OUTPUT_EMPTY;
+    }
+  }
+  return r.isError === true ? { output, isError: true } : { output };
+}
+
+function makeToolResult(
+  call: PreflightedToolCall,
+  args: unknown,
+  result: ExecutableToolResult,
+): PendingToolResult {
+  return {
+    toolCall: call.toolCall,
+    toolName: call.toolName,
+    args,
+    result,
+    stopTurn: toolResultStopsTurn(result),
+  };
+}
+
+function toolResultStopsTurn(result: ExecutableToolResult): boolean {
+  return result.isError === true && result.stopTurn === true;
+}
+
+function makeErrorToolResult(
+  call: PreflightedToolCall,
+  args: unknown,
+  output: string,
+): PendingToolResult {
+  return makeToolResult(call, args, { output, isError: true });
+}
+
+/**
+ * Record `tool.call` in provider order. Reusing the provider/API tool-call id
+ * keeps transcript linkage on one canonical identity.
+ */
+async function dispatchToolCall(
+  step: ToolCallStepContext,
+  call: PreflightedToolCall,
+  args: unknown,
+  displayFields?: ToolCallDisplayFields | undefined,
+): Promise<void> {
+  const { toolCall, toolName } = call;
+  await step.dispatchEvent({
+    type: 'tool.call',
+    uuid: toolCall.id,
+    turnId: step.turnId,
+    step: step.currentStep,
+    stepUuid: step.stepUuid,
+    toolCallId: toolCall.id,
+    name: toolName,
+    args,
+    description: displayFields?.description,
+    display: displayFields?.display,
+  });
+}
diff --git a/packages/agent-core/src/loop/tool-scheduler.ts b/packages/agent-core/src/loop/tool-scheduler.ts
new file mode 100644
index 000000000..0976d3fed
--- /dev/null
+++ b/packages/agent-core/src/loop/tool-scheduler.ts
@@ -0,0 +1,100 @@
+/**
+ * Stateful execution scheduler for tool calls in one model step.
+ *
+ * The scheduler owns only execution ordering:
+ *   - tasks with non-conflicting resource accesses may overlap
+ *   - tasks with conflicting resource accesses wait for the conflicting active tasks
+ *   - drained results are handed back in provider order
+ *
+ * Validation, hooks, event construction, and result finalization stay in
+ * `tool-call.ts`.
+ */
+
+import { createControlledPromise, type ControlledPromise } from '@antfu/utils';
+
+import { ToolAccesses } from './tool-access';
+
+// Scheduler
+
+export interface ToolCallTask<Result> {
+  readonly accesses: ToolAccesses;
+  readonly start: () => Promise<{ readonly result: Promise<Result> }>;
+}
+
+interface ScheduledToolCallTask<Result> extends ToolCallTask<Result> {
+  readonly result: ControlledPromise<Result>;
+}
+
+export class ToolScheduler<Result> {
+  private readonly activeTasks: Array<ScheduledToolCallTask<Result>> = [];
+  private queuedTasks: Array<ScheduledToolCallTask<Result>> = [];
+
+  add(task: ToolCallTask<Result>): Promise<Result> {
+    const result = createControlledPromise<Result>();
+    void result.catch(() => undefined);
+
+    const scheduledTask: ScheduledToolCallTask<Result> = { ...task, result };
+    if (this.isBlocked(task, this.queuedTasks)) {
+      this.queuedTasks.push(scheduledTask);
+    } else {
+      this.start(scheduledTask);
+    }
+
+    return result;
+  }
+
+  private isBlocked(
+    task: ToolCallTask<Result>,
+    queuedBefore: readonly ToolCallTask<Result>[],
+  ): boolean {
+    return (
+      this.conflictsWithAny(task, this.activeTasks) || this.conflictsWithAny(task, queuedBefore)
+    );
+  }
+
+  private conflictsWithAny(
+    task: ToolCallTask<Result>,
+    candidates: readonly ToolCallTask<Result>[],
+  ): boolean {
+    return candidates.some((candidate) =>
+      ToolAccesses.conflict(task.accesses, candidate.accesses),
+    );
+  }
+
+  private start(task: ScheduledToolCallTask<Result>): void {
+    this.activeTasks.push(task);
+    let started: Promise<{ readonly result: Promise<Result> }>;
+    try {
+      started = task.start();
+    } catch (error) {
+      task.result.reject(error);
+      this.finish(task);
+      return;
+    }
+
+    void started
+      .then(({ result }) => result)
+      .then(task.result.resolve, task.result.reject)
+      .finally(() => {
+        this.finish(task);
+      });
+  }
+
+  private finish(task: ScheduledToolCallTask<Result>): void {
+    const index = this.activeTasks.indexOf(task);
+    if (index >= 0) this.activeTasks.splice(index, 1);
+    this.startQueuedTasks();
+  }
+
+  private startQueuedTasks(): void {
+    const stillQueued: Array<ScheduledToolCallTask<Result>> = [];
+    for (const task of this.queuedTasks) {
+      if (this.isBlocked(task, stillQueued)) {
+        stillQueued.push(task);
+      } else {
+        this.start(task);
+      }
+    }
+    this.queuedTasks = stillQueued;
+  }
+}
diff --git a/packages/agent-core/src/loop/turn-step.ts b/packages/agent-core/src/loop/turn-step.ts
new file mode 100644
index 000000000..ceceb346a
--- /dev/null
+++ b/packages/agent-core/src/loop/turn-step.ts
@@ -0,0 +1,249 @@
+/**
+ * Executes one provider step.
+ *
+ * A step owns the provider call, atomic transcript envelope, streaming callback
+ * wiring, tool-call lifecycle, and post-step hooks. Provider usage is recorded
+ * immediately after `llm.chat` returns so a later abort during tool execution
+ * does not lose model usage that was already spent.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import type { TokenUsage } from '@moonshot-ai/kosong';
+import type { Logger } from '#/logging/types';
+
+import type { LoopEventDispatcher } from './events';
+import type { LLM, LLMChatParams, LLMChatResponse } from './llm';
+import { chatWithRetry } from './retry';
+import { runToolCallBatch, type ToolCallStepContext } from './tool-call';
+import type { ExecutableTool, LoopHooks, LoopMessageBuilder, LoopStepStopReason } from './types';
+
+type ChatStreamingCallbacks = Pick<
+  LLMChatParams,
+  'onTextDelta' | 'onThinkDelta' | 'onToolCallDelta' | 'onTextPart' | 'onThinkPart'
+>;
+
+export interface ExecuteLoopStepDeps {
+  readonly turnId: string;
+  readonly signal: AbortSignal;
+  readonly buildMessages: LoopMessageBuilder;
+  readonly dispatchEvent: LoopEventDispatcher;
+  readonly llm: LLM;
+  readonly tools?: readonly ExecutableTool[] | undefined;
+  readonly hooks?: LoopHooks | undefined;
+  readonly log?: Logger | undefined;
+  readonly currentStep: number;
+  readonly maxRetryAttempts?: number;
+  readonly recordUsage: (usage: TokenUsage) => void;
+}
+
+export async function executeLoopStep(deps: ExecuteLoopStepDeps): Promise<{
+  readonly usage: TokenUsage;
+  readonly stopReason: LoopStepStopReason;
+}> {
+  const {
+    turnId,
+    signal,
+    buildMessages,
+    dispatchEvent,
+    llm,
+    tools,
+    hooks,
+    log,
+    currentStep,
+    maxRetryAttempts,
+    recordUsage,
+  } = deps;
+
+  if (hooks?.beforeStep !== undefined) {
+    const beforeStep = await hooks.beforeStep({
+      turnId,
+      stepNumber: currentStep,
+      signal,
+      llm,
+    });
+    if (beforeStep?.block === true) {
+      throw new Error(beforeStep.reason ?? `Step ${String(currentStep)} was blocked`);
+    }
+  }
+
+  signal.throwIfAborted();
+
+  const messages = await buildMessages();
+  signal.throwIfAborted();
+
+  const stepUuid = randomUUID();
+
+  const step: ToolCallStepContext = {
+    tools,
+    hooks,
+    log,
+    dispatchEvent,
+    llm,
+    signal,
+    turnId,
+    currentStep,
+    stepUuid,
+  };
+
+  await dispatchEvent({
+    type: 'step.begin',
+    uuid: stepUuid,
+    turnId,
+    step: currentStep,
+  });
+
+  const chatParams: LLMChatParams = {
+    messages,
+    tools: tools ?? [],
+    signal,
+    ...createChatStreamingCallbacks({
+      dispatchEvent,
+      turnId,
+      currentStep,
+      stepUuid,
+    }),
+  };
+  const response: LLMChatResponse = await chatWithRetry({
+    llm,
+    params: chatParams,
+    dispatchEvent,
+    turnId,
+    currentStep,
+    stepUuid,
+    maxAttempts: maxRetryAttempts,
+    log,
+  });
+  const usage = response.usage;
+  recordUsage(usage);
+  const stopReason = deriveStepStopReason(response);
+
+  // Execute tools only when the normalized response shape represents a tool
+  // step. Provider terminal diagnostics such as filtering or truncation must
+  // not trigger side-effecting tool execution even if a malformed response also
+  // contains tool calls.
+  let effectiveStopReason = stopReason;
+  if (stopReason === 'tool_use') {
+    const toolBatch = await runToolCallBatch(step, response);
+    if (toolBatch.stopTurn) effectiveStopReason = 'end_turn';
+  }
+
+  // When a tool batch runs, it drains paired `tool.result` events even when
+  // cancellation is requested. Check the signal here before sealing the step.
+  signal.throwIfAborted();
+
+  await dispatchEvent({
+    type: 'step.end',
+    uuid: stepUuid,
+    turnId,
+    step: currentStep,
+    usage,
+    finishReason: effectiveStopReason,
+    ...stepEndProviderDiagnostics(response, effectiveStopReason),
+  });
+
+  if (hooks?.afterStep !== undefined) {
+    try {
+      await hooks.afterStep({
+        turnId,
+        stepNumber: currentStep,
+        usage,
+        stopReason: effectiveStopReason,
+        signal,
+        llm,
+      });
+    } catch {
+      // The step is already sealed; observer hooks cannot change the result.
+    }
+  }
+
+  return { usage, stopReason: effectiveStopReason };
+}
+
+function deriveStepStopReason(response: LLMChatResponse): LoopStepStopReason {
+  switch (response.providerFinishReason) {
+    case 'truncated':
+      return 'max_tokens';
+    case 'filtered':
+      return 'filtered';
+    case 'paused':
+      return 'paused';
+    case 'other':
+      return 'unknown';
+    case 'completed':
+    case undefined:
+      return response.toolCalls.length > 0 ? 'tool_use' : 'end_turn';
+    case 'tool_calls':
+      return response.toolCalls.length > 0 ? 'tool_use' : 'unknown';
+    default: {
+      const _exhaustive: never = response.providerFinishReason;
+      return _exhaustive;
+    }
+  }
+}
+
+function stepEndProviderDiagnostics(
+  response: LLMChatResponse,
+  stopReason: LoopStepStopReason,
+): Pick<LLMChatResponse, 'providerFinishReason' | 'rawFinishReason'> {
+  const providerFinishReason = response.providerFinishReason;
+  if (
+    (providerFinishReason === 'completed' && stopReason === 'end_turn') ||
+    (providerFinishReason === 'tool_calls' && stopReason === 'tool_use')
+  ) {
+    return {};
+  }
+
+  return {
+    ...(providerFinishReason !== undefined ? { providerFinishReason } : {}),
+    ...(response.rawFinishReason !== undefined
+      ? { rawFinishReason: response.rawFinishReason }
+      : {}),
+  };
+}
+
+function createChatStreamingCallbacks(deps: {
+  readonly dispatchEvent: LoopEventDispatcher;
+  readonly turnId: string;
+  readonly currentStep: number;
+  readonly stepUuid: string;
+}): ChatStreamingCallbacks {
+  const { dispatchEvent, turnId, currentStep, stepUuid } = deps;
+
+  return {
+    onTextDelta: (delta) => {
+      dispatchEvent({ type: 'text.delta', delta });
+    },
+    onThinkDelta: (delta) => {
+      dispatchEvent({ type: 'thinking.delta', delta });
+    },
+    onToolCallDelta: (delta) => {
+      dispatchEvent({
+        type: 'tool.call.delta',
+        toolCallId: delta.toolCallId,
+        name: delta.name,
+        argumentsPart: delta.argumentsPart,
+      });
+    },
+    onTextPart: async (part) => {
+      await dispatchEvent({
+        type: 'content.part',
+        uuid: randomUUID(),
+        turnId,
+        step: currentStep,
+        stepUuid,
+        part,
+      });
+    },
+    onThinkPart: async (part) => {
+      await dispatchEvent({
+        type: 'content.part',
+        uuid: randomUUID(),
+        turnId,
+        step: currentStep,
+        stepUuid,
+        part,
+      });
+    },
+  };
+}
diff --git a/packages/agent-core/src/loop/types.ts b/packages/agent-core/src/loop/types.ts
new file mode 100644
index 000000000..433435c52
--- /dev/null
+++ b/packages/agent-core/src/loop/types.ts
@@ -0,0 +1,208 @@
+/**
+ * Public contracts for the stateless agent loop.
+ *
+ * This file defines the narrow surfaces that connect a Kosong conversation to
+ * tool execution, phase hooks, and turn results. Host-layer metadata, policy,
+ * archival limits, and UI concerns stay outside these contracts.
+ *
+ * Field naming is camelCase unless a reused Kosong type says otherwise.
+ * Optional fields use `?: T | undefined` intentionally under
+ * `exactOptionalPropertyTypes: true`.
+ */
+
+import type { ContentPart, Message, TokenUsage, Tool, ToolCall } from '@moonshot-ai/kosong';
+
+import type { ToolInputDisplay } from '../tools/display';
+import type { ToolAccesses } from './tool-access';
+import type { LLM } from './llm';
+
+export type { ToolCall };
+
+export type LoopMessageBuilder = () => Message[] | Promise<Message[]>;
+
+/**
+ * Stop reason for one completed model step.
+ *
+ * `tool_use` is a loop-control signal: the loop executes the requested tools and
+ * continues with another step. The other values are terminal for the current
+ * turn unless a host hook explicitly asks the loop to continue.
+ */
+export type LoopStepStopReason =
+  | 'end_turn'
+  | 'max_tokens'
+  | 'tool_use'
+  | 'filtered'
+  | 'paused'
+  | 'unknown';
+
+export type LoopTerminalStepStopReason = Exclude<LoopStepStopReason, 'tool_use'>;
+
+/**
+ * Stop reasons that can be returned in a normal `TurnResult`.
+ *
+ * `tool_use` is intentionally absent because it cannot be the final result of a
+ * completed turn. Errors and max-step exhaustion are represented by thrown
+ * errors, not by this union. Compaction is a host-level retry concern rather
+ * than a stop reason.
+ */
+export type LoopTurnStopReason = LoopTerminalStepStopReason | 'aborted';
+
+/**
+ * @deprecated Legacy umbrella union. Use `LoopStepStopReason` for per-step
+ * model responses and `LoopTurnStopReason` for `TurnResult`.
+ */
+export type StopReason = LoopStepStopReason | 'aborted';
+
+export interface TurnResult {
+  stopReason: LoopTurnStopReason;
+  steps: number;
+  usage: TokenUsage;
+}
+
+export type ExecutableToolOutput = string | ContentPart[];
+
+export interface ExecutableToolSuccessResult {
+  readonly output: ExecutableToolOutput;
+  readonly isError?: false | undefined;
+  /**
+   * Optional human-readable side channel for tool-result metadata that
+   * should not contaminate the data stream the model sees (e.g. a
+   * "Task snapshot retrieved." brief for TaskOutput). Distinct from
+   * `output`: callers rendering tool results decide whether to surface
+   * this to the user.
+   */
+  readonly message?: string | undefined;
+}
+
+export interface ExecutableToolErrorResult {
+  readonly output: ExecutableToolOutput;
+  readonly isError: true;
+  /** See {@link ExecutableToolSuccessResult.message}. */
+  readonly message?: string | undefined;
+  /**
+   * Internal loop-control hint. Tool result events strip this field before
+   * persistence; it only tells the current turn whether another model step is
+   * allowed after this tool batch.
+   */
+  readonly stopTurn?: boolean | undefined;
+}
+
+export type ExecutableToolResult = ExecutableToolSuccessResult | ExecutableToolErrorResult;
+
+export interface ToolUpdate {
+  kind: 'stdout' | 'stderr' | 'progress' | 'status' | 'custom';
+  text?: string | undefined;
+  percent?: number | undefined;
+  /** Vendor-defined event identifier when `kind === 'custom'`. */
+  customKind?: string | undefined;
+  /** Opaque payload paired with `customKind`. */
+  customData?: unknown;
+}
+
+/**
+ * Per-call context passed to tool implementations.
+ */
+export interface ExecutableToolContext {
+  readonly turnId: string;
+  readonly toolCallId: string;
+  readonly metadata?: unknown;
+  readonly signal: AbortSignal;
+  readonly onUpdate?: ((update: ToolUpdate) => void) | undefined;
+}
+
+export interface RunnableToolExecution {
+  readonly isError?: false | undefined;
+  readonly accesses?: ToolAccesses | undefined;
+  readonly display?: ToolInputDisplay | undefined;
+  readonly description?: string;
+  readonly execute: (ctx: ExecutableToolContext) => Promise<ExecutableToolResult>;
+}
+
+export type ToolExecution = RunnableToolExecution | ExecutableToolErrorResult;
+
+export interface ExecutableTool<Input = unknown> extends Tool {
+  resolveExecution(input: Input): ToolExecution;
+}
+
+/**
+ * Step hooks are aligned to recorded phase boundaries: `beforeStep` runs before
+ * `step.begin`, while `afterStep` runs after `step.end`.
+ */
+
+export interface LoopStepHookContext {
+  readonly turnId: string;
+  readonly stepNumber: number;
+  readonly signal: AbortSignal;
+  readonly llm: LLM;
+}
+
+export interface ToolExecutionHookContext extends LoopStepHookContext {
+  readonly toolCall: ToolCall;
+  readonly tool?: ExecutableTool | undefined;
+  readonly args: unknown;
+}
+
+export interface PrepareToolExecutionResult {
+  readonly block?: boolean | undefined;
+  readonly reason?: string | undefined;
+  readonly updatedArgs?: unknown;
+  readonly syntheticResult?: ExecutableToolResult | undefined;
+  readonly executionMetadata?: unknown;
+}
+
+export interface FinalizeToolResultContext extends ToolExecutionHookContext {
+  readonly result: ExecutableToolResult;
+}
+
+export interface LoopAfterStepContext extends LoopStepHookContext {
+  readonly usage: TokenUsage;
+  readonly stopReason: LoopStepStopReason;
+}
+
+export interface LoopStoppedStepContext extends LoopStepHookContext {
+  readonly usage: TokenUsage;
+  readonly stopReason: LoopTerminalStepStopReason;
+}
+
+export interface BeforeStepResult {
+  readonly block?: boolean | undefined;
+  readonly reason?: string | undefined;
+}
+
+export interface ShouldContinueAfterStopResult {
+  readonly continue: boolean;
+}
+
+export type BeforeStepHook = (ctx: LoopStepHookContext) => Promise<BeforeStepResult | undefined>;
+
+export type AfterStepHook = (ctx: LoopAfterStepContext) => Promise<void>;
+
+export type PrepareToolExecutionHook = (
+  ctx: ToolExecutionHookContext,
+) => Promise<PrepareToolExecutionResult | undefined>;
+
+export type FinalizeToolResultHook = (
+  ctx: FinalizeToolResultContext,
+) => Promise<ExecutableToolResult | undefined>;
+
+export type ShouldContinueAfterStopHook = (
+  ctx: LoopStoppedStepContext,
+) => Promise<ShouldContinueAfterStopResult | undefined>;
+
+/**
+ * Groups every awaited phase hook.
+ *
+ * Hooks can affect control flow at deterministic transcript points. Event
+ * listeners observe output and cannot change turn behavior.
+ *
+ * Tool hooks run serially in provider tool-call order before the matching
+ * durable event is recorded, so preparation and finalization decisions are
+ * resolved at stable transcript points.
+ */
+export interface LoopHooks {
+  beforeStep?: BeforeStepHook | undefined;
+  afterStep?: AfterStepHook | undefined;
+  prepareToolExecution?: PrepareToolExecutionHook | undefined;
+  finalizeToolResult?: FinalizeToolResultHook | undefined;
+  shouldContinueAfterStop?: ShouldContinueAfterStopHook | undefined;
+}
diff --git a/packages/agent-core/src/mcp/auth-tool.ts b/packages/agent-core/src/mcp/auth-tool.ts
new file mode 100644
index 000000000..37bd73652
--- /dev/null
+++ b/packages/agent-core/src/mcp/auth-tool.ts
@@ -0,0 +1,181 @@
+/**
+ * Synthetic `mcp__<server>__authenticate` tool.
+ *
+ * When an MCP HTTP server lands in the `needs-auth` state — i.e. its
+ * initial connection failed with a 401 / `UnauthorizedError` and no static
+ * bearer token is configured — the {@link ToolManager} swaps the real MCP
+ * tool list for this single tool. Calling it:
+ *
+ *  1. Asks {@link McpOAuthService} to perform RFC 9728 / RFC 8414 / RFC 7591
+ *     discovery and produce an authorization URL.
+ *  2. Streams that URL back to the model via `onUpdate({kind:'status'})`
+ *     and returns it in the tool output so the model can hand it to the
+ *     human user.
+ *  3. Blocks (up to {@link DEFAULT_AUTH_TIMEOUT_MS}) on the one-shot
+ *     localhost callback listener owned by the OAuth service.
+ *  4. Drives a manager-level `reconnect(name)` once tokens have been
+ *     persisted, which flips the entry to `connected` and lets
+ *     `ToolManager` swap the synthetic tool out for the real MCP tools.
+ *
+ * The blocking shape (option 1 in the plan) keeps the implementation
+ * simple at the cost of holding one tool call open for the duration of
+ * the human's browser flow. If the model ends up re-invoking the tool
+ * mid-flow we just start a fresh flow; the new callback server supersedes
+ * the old one.
+ */
+
+import { z } from 'zod';
+
+import {
+  type ExecutableTool,
+  type ExecutableToolContext,
+  type ExecutableToolResult,
+} from '../loop';
+import { toInputJsonSchema } from '../tools/support/input-schema';
+import {
+  MCP_OAUTH_AUTHORIZATION_URL_TOOL_UPDATE,
+  type McpOAuthAuthorizationUrlUpdateData,
+} from '../rpc/events';
+import { AlreadyAuthorizedError, type McpOAuthService } from './oauth';
+import { qualifyMcpToolName } from './tool-naming';
+
+const DEFAULT_AUTH_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
+
+const AUTH_TOOL_TOOL_NAME = 'authenticate';
+
+const DESCRIPTION_TEMPLATE = (serverName: string): string =>
+  `Authenticate with MCP server "${serverName}" via OAuth.
+
+This server requires an OAuth login that has not yet been completed. ` +
+  `Calling this tool starts the authorization flow:
+
+  1. The tool prints an authorization URL.
+  2. **You must show that URL to the user verbatim** and ask them to open it
+     in a browser, sign in, and approve the kimi-code client.
+  3. The tool blocks (up to 15 minutes) until the browser redirects back to
+     the local callback listener.
+  4. On success, kimi-code reconnects the MCP server and the real tools
+     replace this synthetic tool.
+
+Take no arguments. Treat the URL as sensitive — do not modify it or strip
+query parameters.`;
+
+export interface CreateMcpAuthToolOptions {
+  /** Friendly MCP server name as configured in `mcp.json`. */
+  readonly serverName: string;
+  /** Base URL of the MCP server (used for OAuth resource metadata discovery). */
+  readonly serverUrl: string;
+  /** OAuth orchestrator, typically `Session`-scoped. */
+  readonly oauthService: McpOAuthService;
+  /**
+   * Triggers a manager-level reconnect once tokens land on disk. Implemented
+   * by the {@link McpConnectionManager} and bound in the {@link ToolManager}
+   * `needs-auth` branch.
+   */
+  readonly reconnect: (signal?: AbortSignal) => Promise<void>;
+  /**
+   * Overrides the per-call OAuth wait timeout. Tests set this to a small
+   * number; production callers should accept the default.
+   */
+  readonly timeoutMs?: number;
+}
+
+export function createMcpAuthTool(options: CreateMcpAuthToolOptions): ExecutableTool {
+  const { serverName, serverUrl, oauthService, reconnect, timeoutMs } = options;
+  const name = qualifyMcpToolName(serverName, AUTH_TOOL_TOOL_NAME);
+  const description = DESCRIPTION_TEMPLATE(serverName);
+  // No arguments; an empty object schema keeps providers happy across SDKs.
+  const parameters = toInputJsonSchema(z.object({}));
+  const execute = async (ctx: ExecutableToolContext): Promise<ExecutableToolResult> => {
+    const { signal, onUpdate } = ctx;
+    signal.throwIfAborted();
+
+    onUpdate?.({ kind: 'status', text: `Discovering OAuth metadata for ${serverName}…` });
+
+    let flow: Awaited<ReturnType<McpOAuthService['beginAuthorization']>>;
+    try {
+      flow = await oauthService.beginAuthorization(serverName, serverUrl);
+    } catch (error) {
+      if (error instanceof AlreadyAuthorizedError) {
+        onUpdate?.({ kind: 'status', text: `Already authorized; reconnecting ${serverName}…` });
+        try {
+          await reconnect(signal);
+        } catch (reconnectError) {
+          return errorResult(serverName, reconnectError);
+        }
+        return {
+          output:
+            `MCP server "${serverName}" already had valid OAuth credentials. ` +
+            `Reconnected; real tools are available now.`,
+        };
+      }
+      return errorResult(serverName, error);
+    }
+
+    const urlText = flow.authorizationUrl.toString();
+    const customData: McpOAuthAuthorizationUrlUpdateData = {
+      serverName,
+      authorizationUrl: urlText,
+    };
+    onUpdate?.({
+      kind: 'custom',
+      customKind: MCP_OAUTH_AUTHORIZATION_URL_TOOL_UPDATE,
+      customData,
+    });
+    onUpdate?.({
+      kind: 'status',
+      text:
+        `Open this URL in your browser to authorize "${serverName}":\n` +
+        `\n${urlText}\n\n` +
+        `Waiting for the OAuth callback (timeout 15 min). ` +
+        `If you cancel, call this tool again to restart the flow.`,
+    });
+
+    try {
+      await flow.complete({ signal, timeoutMs: timeoutMs ?? DEFAULT_AUTH_TIMEOUT_MS });
+    } catch (error) {
+      return errorResult(serverName, error, urlText);
+    }
+
+    onUpdate?.({ kind: 'status', text: `Authorized — reconnecting ${serverName}…` });
+    try {
+      await reconnect(signal);
+    } catch (error) {
+      return errorResult(serverName, error);
+    }
+
+    return {
+      output:
+        `MCP server "${serverName}" authenticated successfully. ` +
+        `The real MCP tools have replaced this synthetic authenticate tool.`,
+    };
+  };
+
+  return {
+    name,
+    description,
+    parameters,
+    resolveExecution: () => {
+      return {
+        description: `Authenticating ${serverName}`,
+        execute,
+      };
+    },
+  };
+}
+
+function errorResult(
+  serverName: string,
+  error: unknown,
+  authorizationUrl?: string,
+): ExecutableToolResult {
+  const message = error instanceof Error ? error.message : String(error);
+  const suffix =
+    authorizationUrl !== undefined
+      ? `\n\nAuthorization URL (still valid if the listener has not timed out): ${authorizationUrl}`
+      : '';
+  return {
+    isError: true,
+    output: `OAuth flow for MCP server "${serverName}" did not complete: ${message}${suffix}`,
+  };
+}
diff --git a/packages/agent-core/src/mcp/client-http.ts b/packages/agent-core/src/mcp/client-http.ts
new file mode 100644
index 000000000..626c5d2bd
--- /dev/null
+++ b/packages/agent-core/src/mcp/client-http.ts
@@ -0,0 +1,231 @@
+import { ErrorCodes, KimiError } from '#/errors';
+import type { McpServerHttpConfig } from '#/config/schema';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+import {
+  buildRequestOptions,
+  KIMI_MCP_CLIENT_NAME,
+  KIMI_MCP_CLIENT_VERSION,
+  toMcpToolDefinition,
+  toMcpToolResult,
+  type UnexpectedCloseListener,
+  type UnexpectedCloseReason,
+} from './client-shared';
+import type { MCPClient, MCPToolDefinition, MCPToolResult } from './types';
+
+export interface HttpMcpClientOptions {
+  readonly clientName?: string;
+  readonly clientVersion?: string;
+  readonly toolCallTimeoutMs?: number;
+  /**
+   * Reads `process.env[name]` by default. Tests can inject a deterministic
+   * lookup function so they do not have to mutate global env.
+   */
+  readonly envLookup?: (name: string) => string | undefined;
+  /**
+   * Lets tests inject a fake `fetch` for the underlying transport.
+   */
+  readonly fetch?: typeof fetch;
+  /**
+   * OAuth client provider attached to the transport. Set only when the server
+   * has no static token configuration; the SDK uses this to handle 401s with
+   * RFC 9728 / RFC 8414 / DCR discovery and PKCE. The connection manager wires
+   * this in and surfaces `UnauthorizedError` as a `needs-auth` status.
+   */
+  readonly oauthProvider?: OAuthClientProvider;
+}
+
+/**
+ * Wraps the SDK streamable-HTTP transport as a kosong {@link MCPClient}.
+ * Static bearer tokens are looked up from `process.env[bearerTokenEnvVar]`.
+ * OAuth providers are attached separately by the connection manager.
+ */
+export class HttpMcpClient implements MCPClient {
+  private readonly client: Client;
+  private readonly transport: StreamableHTTPClientTransport;
+  private readonly toolCallTimeoutMs?: number;
+  private started = false;
+  private closed = false;
+  // See StdioMcpClient.ready — distinguishes handshake-phase failures (caller
+  // sees them via `connect()` throwing, no unexpectedClose) from post-ready
+  // disconnects (the case `onUnexpectedClose` is designed to surface).
+  private ready = false;
+  private hooksInstalled = false;
+  private unexpectedCloseListener: UnexpectedCloseListener | undefined;
+  private lastTransportError: Error | undefined;
+  // See StdioMcpClient — buffered when the listener has not been installed
+  // yet so an early close is replayed instead of dropped.
+  private pendingUnexpectedClose: UnexpectedCloseReason | undefined;
+  // Latch so `onerror` and a (theoretical) `onclose` for the same transport
+  // failure do not double-fire. Once we have decided the connection is dead,
+  // additional SDK notifications are noise.
+  private unexpectedCloseFired = false;
+
+  constructor(config: McpServerHttpConfig, options: HttpMcpClientOptions = {}) {
+    const envLookup = options.envLookup ?? ((name) => process.env[name]);
+    const headers = buildMcpHttpHeaders(config, envLookup);
+
+    this.transport = new StreamableHTTPClientTransport(new URL(config.url), {
+      requestInit: headers !== undefined ? { headers } : undefined,
+      fetch: options.fetch,
+      authProvider: options.oauthProvider,
+    });
+    this.client = new Client({
+      name: options.clientName ?? KIMI_MCP_CLIENT_NAME,
+      version: options.clientVersion ?? KIMI_MCP_CLIENT_VERSION,
+    });
+    this.toolCallTimeoutMs = options.toolCallTimeoutMs;
+  }
+
+  async connect(): Promise<void> {
+    if (this.closed) {
+      throw new Error('MCP HTTP client is closed');
+    }
+    if (this.started) return;
+    this.started = true;
+    // Install hooks BEFORE the SDK handshake; see StdioMcpClient.connect.
+    this.installTransportHooks();
+    try {
+      await this.client.connect(this.transport);
+    } catch (error) {
+      await this.closeStartedClient();
+      throw error;
+    }
+    if (this.closed) {
+      await this.closeStartedClient();
+      throw new Error('MCP HTTP client was closed during startup');
+    }
+    this.ready = true;
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    await this.closeStartedClient();
+  }
+
+  /**
+   * Register a listener for unsolicited transport drops. See
+   * `StdioMcpClient.onUnexpectedClose` for semantics. If the transport
+   * already signalled a terminal failure, the buffered reason is replayed
+   * synchronously.
+   */
+  onUnexpectedClose(listener: UnexpectedCloseListener): void {
+    this.unexpectedCloseListener = listener;
+    const pending = this.pendingUnexpectedClose;
+    if (pending !== undefined) {
+      this.pendingUnexpectedClose = undefined;
+      listener(pending);
+    }
+  }
+
+  async listTools(): Promise<MCPToolDefinition[]> {
+    const result = await this.client.listTools();
+    return result.tools.map(toMcpToolDefinition);
+  }
+
+  async callTool(
+    name: string,
+    args: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<MCPToolResult> {
+    const requestOptions = buildRequestOptions(this.toolCallTimeoutMs, signal);
+    const result = await this.client.callTool({ name, arguments: args }, undefined, requestOptions);
+    return toMcpToolResult(result);
+  }
+
+  private async closeStartedClient(): Promise<void> {
+    if (!this.started) return;
+    this.started = false;
+    await this.client.close();
+  }
+
+  private installTransportHooks(): void {
+    // Idempotent — see StdioMcpClient.installTransportHooks.
+    if (this.hooksInstalled) return;
+    this.hooksInstalled = true;
+    this.client.onclose = () => {
+      if (this.closed) return;
+      // Handshake-phase close surfaces via `client.connect()` throwing.
+      if (!this.ready) return;
+      this.fireUnexpectedClose({ error: this.lastTransportError });
+    };
+    // streamable-http's transport only calls `onclose` on its own `close()`
+    // path, so 99% of remote disconnects (SSE flap → reconnect exhaustion,
+    // POST send failure on a dead session) arrive as `onerror` instead. Mirror
+    // the way the SDK exposes a "the transport is gone" signal there by
+    // mapping the known-terminal error messages back to an unexpected close;
+    // everything else is treated as transient and only cached for diagnostics.
+    this.client.onerror = (error) => {
+      this.lastTransportError = error;
+      if (this.closed) return;
+      // During the handshake, terminal errors (Unauthorized, reconnect
+      // exhaustion) propagate through `client.connect()` and the manager's
+      // `shouldMarkNeedsAuth` / `formatStartupError`. Firing here would
+      // double-report.
+      if (!this.ready) return;
+      if (isTerminalTransportError(error)) {
+        this.fireUnexpectedClose({ error });
+      }
+    };
+  }
+
+  private fireUnexpectedClose(reason: UnexpectedCloseReason): void {
+    if (this.unexpectedCloseFired) return;
+    this.unexpectedCloseFired = true;
+    const listener = this.unexpectedCloseListener;
+    if (listener !== undefined) {
+      listener(reason);
+    } else {
+      this.pendingUnexpectedClose = reason;
+    }
+  }
+}
+
+/**
+ * Returns true when an error reported via `Client.onerror` indicates the
+ * underlying HTTP transport is dead. The streamable-http SDK does not call
+ * `onclose` for remote disconnects; instead it surfaces them through
+ * `onerror`, but only a few specific messages mean "give up" rather than
+ * "we will retry":
+ *
+ * - `UnauthorizedError` — RFC 9728/8414 auth flow gave up; the SDK won't
+ *   retry without a fresh provider call.
+ * - "Maximum reconnection attempts ... exceeded." — emitted from
+ *   `_scheduleReconnection` after the SSE reconnect budget is gone
+ *   (`streamableHttp.js`, `_scheduleReconnection`).
+ *
+ * Transient signals (per-request fetch failures, single SSE flaps that the
+ * SDK is about to reconnect from) MUST NOT match; otherwise a brief network
+ * blip would tear down every HTTP MCP entry.
+ */
+export function isTerminalTransportError(error: Error): boolean {
+  if (error.name === 'UnauthorizedError') return true;
+  if (/Maximum reconnection attempts/i.test(error.message)) return true;
+  return false;
+}
+
+export function buildMcpHttpHeaders(
+  config: McpServerHttpConfig,
+  envLookup: (name: string) => string | undefined,
+): Record<string, string> | undefined {
+  const headers: Record<string, string> = { ...config.headers };
+  if (config.bearerTokenEnvVar !== undefined) {
+    const token = envLookup(config.bearerTokenEnvVar);
+    if (token === undefined || token.length === 0) {
+      throw new KimiError(ErrorCodes.CONFIG_INVALID, `MCP HTTP bearer token env var "${config.bearerTokenEnvVar}" is not set or is empty`);
+    }
+    // Strip any case-variant 'authorization' static header before injecting the
+    // bearer; Fetch Headers folds duplicate keys into a comma-joined value,
+    // which produces an invalid auth header rather than letting the bearer win.
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === 'authorization') {
+        delete headers[key];
+      }
+    }
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
diff --git a/packages/agent-core/src/mcp/client-shared.ts b/packages/agent-core/src/mcp/client-shared.ts
new file mode 100644
index 000000000..b36d5fad8
--- /dev/null
+++ b/packages/agent-core/src/mcp/client-shared.ts
@@ -0,0 +1,91 @@
+import { getCoreVersion } from '#/version';
+
+import type { MCPToolDefinition, MCPToolResult } from './types';
+
+export const KIMI_MCP_CLIENT_NAME = 'kimi-code';
+// Resolved from agent-core's package.json so MCP servers see the real version
+// in `initialize` (used for compatibility checks, telemetry, debugging).
+// `getCoreVersion()` falls back to '0.0.0' if the package.json read fails.
+export const KIMI_MCP_CLIENT_VERSION = getCoreVersion();
+
+/**
+ * Why-context attached when a runtime client notices its underlying transport
+ * has gone away on its own — i.e. {@link RuntimeMcpClient.close} was NOT
+ * called. The connection manager turns this into a `failed` status so the
+ * UI/SDK do not keep advertising tools backed by a dead transport.
+ *
+ * - `error` is the last error reported via the SDK's `onerror` channel, if
+ *   any. Useful for HTTP where there is no stderr.
+ * - `stderr` is the tail of bytes captured from the child process's stderr;
+ *   populated only for the stdio transport.
+ */
+export interface UnexpectedCloseReason {
+  readonly error?: Error;
+  readonly stderr?: string;
+}
+
+export type UnexpectedCloseListener = (reason: UnexpectedCloseReason) => void;
+
+export interface McpRequestOptions {
+  readonly timeout?: number;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Build the `RequestOptions` object accepted by the MCP SDK's `callTool`,
+ * including either the configured tool-call timeout, an in-flight abort
+ * signal, both, or neither. Returns `undefined` when nothing needs to be
+ * passed so the SDK falls back to its defaults.
+ */
+export function buildRequestOptions(
+  toolCallTimeoutMs: number | undefined,
+  signal: AbortSignal | undefined,
+): McpRequestOptions | undefined {
+  if (toolCallTimeoutMs === undefined && signal === undefined) return undefined;
+  return { timeout: toolCallTimeoutMs, signal };
+}
+
+interface SdkListedTool {
+  readonly name: string;
+  readonly description?: string;
+  readonly inputSchema: Record<string, unknown>;
+}
+
+export function toMcpToolDefinition(tool: SdkListedTool): MCPToolDefinition {
+  return {
+    name: tool.name,
+    description: tool.description ?? '',
+    inputSchema: tool.inputSchema,
+  };
+}
+
+/**
+ * Normalise the SDK's `callTool` return into kosong's {@link MCPToolResult}.
+ * The SDK can return either the modern `{ content, isError }` shape or a
+ * legacy `{ toolResult }` shape; we collapse the legacy shape to a single
+ * text content block.
+ */
+export function toMcpToolResult(result: unknown): MCPToolResult {
+  if (typeof result === 'object' && result !== null && 'content' in result) {
+    const typed = result as { content: unknown; isError?: unknown };
+    if (Array.isArray(typed.content)) {
+      return {
+        content: typed.content as MCPToolResult['content'],
+        isError: typed.isError === true,
+      };
+    }
+  }
+  if (typeof result === 'object' && result !== null && 'toolResult' in result) {
+    const legacy = (result as { toolResult: unknown }).toolResult;
+    return {
+      content: [
+        {
+          type: 'text',
+          text: typeof legacy === 'string' ? legacy : JSON.stringify(legacy),
+        },
+      ],
+      isError: false,
+    };
+  }
+  return { content: [], isError: false };
+}
diff --git a/packages/agent-core/src/mcp/client-stdio.ts b/packages/agent-core/src/mcp/client-stdio.ts
new file mode 100644
index 000000000..55c31aeb1
--- /dev/null
+++ b/packages/agent-core/src/mcp/client-stdio.ts
@@ -0,0 +1,228 @@
+import { ErrorCodes, KimiError } from '#/errors';
+import type { McpServerStdioConfig } from '#/config/schema';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+import {
+  buildRequestOptions,
+  KIMI_MCP_CLIENT_NAME,
+  KIMI_MCP_CLIENT_VERSION,
+  toMcpToolDefinition,
+  toMcpToolResult,
+  type UnexpectedCloseListener,
+  type UnexpectedCloseReason,
+} from './client-shared';
+import type { MCPClient, MCPToolDefinition, MCPToolResult } from './types';
+
+export interface StdioMcpClientOptions {
+  readonly clientName?: string;
+  readonly clientVersion?: string;
+  readonly toolCallTimeoutMs?: number;
+}
+
+const STDERR_BUFFER_CAPACITY = 4 * 1024;
+
+/**
+ * Wraps the `@modelcontextprotocol/sdk` stdio client and exposes the small
+ * surface required by kosong's {@link MCPClient}. Lifecycle is explicit:
+ * the caller must `connect()` before use and `close()` to terminate the
+ * child process.
+ */
+export class StdioMcpClient implements MCPClient {
+  private readonly client: Client;
+  private readonly transport: StdioClientTransport;
+  private readonly toolCallTimeoutMs?: number;
+  private readonly stderrBuffer = new BoundedTail(STDERR_BUFFER_CAPACITY);
+  private started = false;
+  private closed = false;
+  // Flips to true only after `client.connect()` resolves AND the caller has
+  // not torn things down mid-startup. The `onclose` hook uses this to
+  // distinguish "transport died after the handshake" (→ unexpected close)
+  // from "transport died during the handshake" (→ `connect()` throws; the
+  // manager surfaces the failure via `formatStartupError`).
+  private ready = false;
+  private hooksInstalled = false;
+  private unexpectedCloseListener: UnexpectedCloseListener | undefined;
+  private lastTransportError: Error | undefined;
+  // Buffered when the transport closes before a listener is installed (e.g.
+  // a server that exits seconds after answering `tools/list`). Replayed when
+  // `onUnexpectedClose` registers so the close is never silently dropped.
+  private pendingUnexpectedClose: UnexpectedCloseReason | undefined;
+
+  /** Capacity (in characters) of the stderr tail captured for diagnostics. */
+  static readonly stderrBufferCapacity = STDERR_BUFFER_CAPACITY;
+
+  constructor(config: McpServerStdioConfig, options: StdioMcpClientOptions = {}) {
+    if (config.executor !== undefined && config.executor !== 'local') {
+      throw new KimiError(ErrorCodes.NOT_IMPLEMENTED, `MCP stdio executor '${config.executor}' is not yet implemented`);
+    }
+    this.transport = new StdioClientTransport({
+      command: config.command,
+      args: config.args,
+      env: mergeStdioEnv(config.env),
+      cwd: config.cwd,
+      stderr: 'pipe',
+    });
+    // `stderr: 'pipe'` means we MUST drain the stream — otherwise the child
+    // can block on a full pipe. We also keep the last few KB around so the
+    // connection manager can attach it to user-facing failure messages
+    // (`Timed out after 30000ms` on its own tells the user nothing).
+    this.transport.stderr?.on('data', (chunk: Buffer | string) => {
+      this.stderrBuffer.push(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+    });
+    this.client = new Client({
+      name: options.clientName ?? KIMI_MCP_CLIENT_NAME,
+      version: options.clientVersion ?? KIMI_MCP_CLIENT_VERSION,
+    });
+    this.toolCallTimeoutMs = options.toolCallTimeoutMs;
+  }
+
+  async connect(): Promise<void> {
+    if (this.closed) {
+      throw new Error('MCP stdio client is closed');
+    }
+    if (this.started) return;
+    this.started = true;
+    // Install transport hooks BEFORE the SDK handshake so we never lose an
+    // onclose that fires between handshake completion and our wiring. The
+    // hooks themselves gate on `this.ready`, so a close that happens DURING
+    // the handshake still flows through `client.connect()` rejecting.
+    this.installTransportHooks();
+    try {
+      await this.client.connect(this.transport);
+    } catch (error) {
+      await this.closeStartedClient();
+      throw error;
+    }
+    if (this.closed) {
+      await this.closeStartedClient();
+      throw new Error('MCP stdio client was closed during startup');
+    }
+    this.ready = true;
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    await this.closeStartedClient();
+  }
+
+  /**
+   * Register a listener that fires when the underlying transport closes on
+   * its own — i.e. the caller has not yet invoked {@link close}. At most one
+   * listener can be installed; later registrations replace earlier ones.
+   * Intentional closes never invoke the listener.
+   *
+   * If the transport already closed before this method was called, the
+   * buffered reason is replayed synchronously so the close is never dropped.
+   */
+  onUnexpectedClose(listener: UnexpectedCloseListener): void {
+    this.unexpectedCloseListener = listener;
+    const pending = this.pendingUnexpectedClose;
+    if (pending !== undefined) {
+      this.pendingUnexpectedClose = undefined;
+      listener(pending);
+    }
+  }
+
+  /**
+   * Returns the tail of bytes captured from the child's stderr since spawn.
+   * Bounded by {@link StdioMcpClient.stderrBufferCapacity} so a noisy server
+   * cannot exhaust memory.
+   */
+  stderrSnapshot(): string {
+    return this.stderrBuffer.snapshot();
+  }
+
+  async listTools(): Promise<MCPToolDefinition[]> {
+    const result = await this.client.listTools();
+    return result.tools.map(toMcpToolDefinition);
+  }
+
+  async callTool(
+    name: string,
+    args: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<MCPToolResult> {
+    const requestOptions = buildRequestOptions(this.toolCallTimeoutMs, signal);
+    const result = await this.client.callTool({ name, arguments: args }, undefined, requestOptions);
+    return toMcpToolResult(result);
+  }
+
+  private async closeStartedClient(): Promise<void> {
+    if (!this.started) return;
+    this.started = false;
+    await this.client.close();
+  }
+
+  private installTransportHooks(): void {
+    // Idempotent: `connect()` is the only caller and is itself guarded by
+    // `started`, but defending here lets future refactors call this freely.
+    if (this.hooksInstalled) return;
+    this.hooksInstalled = true;
+    // `Client.onclose` fires for THREE situations:
+    //   1. The intentional `close()` path → gated by `this.closed`.
+    //   2. Transport dying during the SDK handshake → gated by `!this.ready`;
+    //      the failure already surfaces via `client.connect()` rejecting, and
+    //      `formatStartupError` attaches stderr at the manager layer.
+    //   3. Transport dying after the handshake succeeded → the case we care
+    //      about: fire or buffer for the manager's watch listener.
+    this.client.onclose = () => {
+      if (this.closed) return;
+      if (!this.ready) return;
+      const stderr = this.stderrBuffer.snapshot();
+      const reason: UnexpectedCloseReason = {
+        error: this.lastTransportError,
+        stderr: stderr.length > 0 ? stderr : undefined,
+      };
+      const listener = this.unexpectedCloseListener;
+      if (listener !== undefined) {
+        listener(reason);
+      } else {
+        // Buffer so a listener registered moments later still sees the close.
+        this.pendingUnexpectedClose = reason;
+      }
+    };
+    this.client.onerror = (error) => {
+      // Errors are informational on their own — `_onclose` is what tells us
+      // the transport is gone — so just remember the latest one and let the
+      // close handler decide whether to surface it. During startup the thrown
+      // error from `client.connect()` already carries the message, so this
+      // capture is only load-bearing post-`ready`.
+      this.lastTransportError = error;
+    };
+  }
+}
+
+/**
+ * A bounded "tail" buffer: appends characters and drops the oldest when the
+ * total exceeds `capacity`. Used to keep the last few KB of child-process
+ * stderr around without unbounded growth.
+ */
+class BoundedTail {
+  private buffer = '';
+  constructor(private readonly capacity: number) {}
+
+  push(chunk: string): void {
+    this.buffer += chunk;
+    if (this.buffer.length > this.capacity) {
+      this.buffer = this.buffer.slice(this.buffer.length - this.capacity);
+    }
+  }
+
+  snapshot(): string {
+    return this.buffer;
+  }
+}
+
+// Inherit the parent's env so PATH/HOME/etc. survive — otherwise `npx`/`uvx`
+// style stdio servers fail to launch even with a valid config. Explicit
+// `config.env` entries still override on conflict.
+function mergeStdioEnv(configEnv?: Record<string, string>): Record<string, string> {
+  const merged: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined) merged[key] = value;
+  }
+  if (configEnv !== undefined) Object.assign(merged, configEnv);
+  return merged;
+}
diff --git a/packages/agent-core/src/mcp/config-loader.ts b/packages/agent-core/src/mcp/config-loader.ts
new file mode 100644
index 000000000..0c29abffb
--- /dev/null
+++ b/packages/agent-core/src/mcp/config-loader.ts
@@ -0,0 +1,95 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { resolveKimiHome } from '#/config/path';
+import { McpServerConfigSchema, type McpServerConfig } from '#/config/schema';
+import { ErrorCodes, KimiError } from '#/errors';
+import { z } from 'zod';
+
+const McpJsonFileSchema = z.object({
+  mcpServers: z.record(z.string(), McpServerConfigSchema).default({}),
+});
+
+export interface McpJsonPaths {
+  readonly user: string;
+  readonly project: string;
+}
+
+export interface ResolveMcpJsonPathsInput {
+  readonly cwd: string;
+  readonly homeDir?: string;
+}
+
+export function resolveMcpJsonPaths(input: ResolveMcpJsonPathsInput): McpJsonPaths {
+  return {
+    user: join(resolveKimiHome(input.homeDir), 'mcp.json'),
+    project: join(input.cwd, '.kimi-code', 'mcp.json'),
+  };
+}
+
+export interface LoadMcpServersInput {
+  readonly cwd: string;
+  readonly homeDir?: string;
+}
+
+/**
+ * Load MCP server declarations from the user-global `~/.kimi-code/mcp.json`
+ * and the project-local `<cwd>/.kimi-code/mcp.json`. Entries in the project
+ * file override user-global entries with the same key, so a repo can specialise
+ * or replace a shared definition.
+ *
+ * Note: project-local entries may spawn stdio commands at session start, so
+ * opening a session inside an untrusted checkout will execute whatever its
+ * `mcp.json` declares. Only enable this in repos you trust.
+ */
+export async function loadMcpServers(
+  input: LoadMcpServersInput,
+): Promise<Record<string, McpServerConfig>> {
+  const paths = resolveMcpJsonPaths({ cwd: input.cwd, homeDir: input.homeDir });
+  const [user, project] = await Promise.all([readMcpJson(paths.user), readMcpJson(paths.project)]);
+  return { ...user, ...project };
+}
+
+async function readMcpJson(filePath: string): Promise<Record<string, McpServerConfig>> {
+  let text: string;
+  try {
+    text = await readFile(filePath, 'utf-8');
+  } catch (error: unknown) {
+    if (isFileNotFound(error)) return {};
+    throw new KimiError(ErrorCodes.CONFIG_INVALID, `Failed to read ${filePath}: ${describeError(error)}`, {
+      cause: error,
+    });
+  }
+
+  if (text.trim().length === 0) return {};
+
+  let data: unknown;
+  try {
+    data = JSON.parse(text);
+  } catch (error: unknown) {
+    throw new KimiError(ErrorCodes.CONFIG_INVALID, `Invalid JSON in ${filePath}: ${describeError(error)}`, {
+      cause: error,
+    });
+  }
+
+  try {
+    return McpJsonFileSchema.parse(data).mcpServers;
+  } catch (error: unknown) {
+    throw new KimiError(ErrorCodes.CONFIG_INVALID, `Invalid MCP server config in ${filePath}: ${describeError(error)}`, {
+      cause: error,
+    });
+  }
+}
+
+function isFileNotFound(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    (error as { code: unknown }).code === 'ENOENT'
+  );
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
diff --git a/packages/agent-core/src/mcp/connection-manager.ts b/packages/agent-core/src/mcp/connection-manager.ts
new file mode 100644
index 000000000..fb3b861f2
--- /dev/null
+++ b/packages/agent-core/src/mcp/connection-manager.ts
@@ -0,0 +1,462 @@
+import { ErrorCodes, KimiError } from '#/errors';
+import type { McpServerConfig } from '#/config/schema';
+import { log as defaultLog } from '#/logging/logger';
+import type { Logger } from '#/logging/types';
+import type { Tool } from '@moonshot-ai/kosong';
+
+import { abortable } from '../utils/abort';
+import { HttpMcpClient } from './client-http';
+import type { UnexpectedCloseReason } from './client-shared';
+import { StdioMcpClient } from './client-stdio';
+import type { McpOAuthService } from './oauth';
+import { assertMcpInputSchema, type MCPClient } from './types';
+
+export type McpServerStatus = 'pending' | 'connected' | 'failed' | 'disabled' | 'needs-auth';
+
+export interface McpServerEntry {
+  readonly name: string;
+  readonly transport: 'stdio' | 'http';
+  readonly status: McpServerStatus;
+  readonly toolCount: number;
+  readonly error?: string;
+}
+
+interface InternalEntry {
+  readonly name: string;
+  readonly config: McpServerConfig;
+  attemptId: number;
+  status: McpServerStatus;
+  tools?: readonly Tool[];
+  enabledNames?: ReadonlySet<string>;
+  error?: string;
+  client?: RuntimeMcpClient;
+}
+
+export type McpStatusListener = (entry: McpServerEntry) => void;
+
+const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
+
+type RuntimeMcpClient = StdioMcpClient | HttpMcpClient;
+
+export interface McpConnectionManagerOptions {
+  readonly envLookup?: (name: string) => string | undefined;
+  /**
+   * Optional OAuth orchestrator. When provided, HTTP servers without a
+   * static bearer token participate in the OAuth-via-synthetic-tool flow:
+   *  - If `oauthService.hasTokens(name, url)` is true, the provider is
+   *    attached to the transport so the SDK can refresh tokens on 401.
+   *  - Connection failures that look like 401 / `UnauthorizedError` flip
+   *    the entry into `needs-auth` instead of `failed`; `/mcp-config`
+   *    drives the browser flow through the synthetic auth tool.
+   */
+  readonly oauthService?: McpOAuthService;
+  /**
+   * Parent logger. Defaults to the global `log`; Session passes its own
+   * `session.log` so MCP events land in the session log too.
+   */
+  readonly log?: Logger;
+}
+
+/**
+ * Owns the lifecycle of every configured MCP server for a Session.
+ *
+ * Servers are connected in parallel; per-server failures are isolated so a
+ * crashed or misconfigured entry never blocks Session startup. State
+ * transitions are surfaced through {@link onStatusChange} so callers (the
+ * Session) can react — registering tools onto the main agent, emitting
+ * wire events, or updating the TUI.
+ */
+export class McpConnectionManager {
+  private readonly entries = new Map<string, InternalEntry>();
+  private readonly listeners = new Set<McpStatusListener>();
+  private initialLoad: Promise<void> = Promise.resolve();
+  private initialLoadAttemptId = 0;
+  private initialLoadStartedAt: number | undefined;
+  private initialLoadFinishedAt: number | undefined;
+
+  /**
+   * OAuth orchestrator injected at construction time. Consumed by the
+   * {@link ToolManager} `needs-auth` branch to build the synthetic
+   * `authenticate` tool.
+   */
+  readonly oauthService: McpOAuthService | undefined;
+  private readonly log: Logger;
+
+  constructor(private readonly options: McpConnectionManagerOptions = {}) {
+    this.oauthService = options.oauthService;
+    this.log = options.log ?? defaultLog;
+  }
+
+  /**
+   * Returns the URL of an HTTP MCP server by name, or `undefined` for
+   * unknown / non-HTTP / disabled entries. Used by the synthetic auth tool
+   * to drive OAuth discovery against the right base URL.
+   */
+  getHttpServerUrl(name: string): string | undefined {
+    const entry = this.entries.get(name);
+    if (entry === undefined) return undefined;
+    if (entry.config.transport !== 'http') return undefined;
+    return entry.config.url;
+  }
+
+  onStatusChange(listener: McpStatusListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  list(): readonly McpServerEntry[] {
+    return Array.from(this.entries.values(), toPublicEntry);
+  }
+
+  get(name: string): McpServerEntry | undefined {
+    const entry = this.entries.get(name);
+    return entry !== undefined ? toPublicEntry(entry) : undefined;
+  }
+
+  /**
+   * Returns the MCP client, the discovered tools, and the allow-list of tool
+   * names for a given connected server, or `undefined` if the server is not
+   * currently connected. The allow-list combines the server's `enabledTools`
+   * and `disabledTools` filters; callers should only register names in the
+   * set.
+   */
+  resolved(
+    name: string,
+  ):
+    | { client: MCPClient; tools: readonly Tool[]; enabledNames: ReadonlySet<string> }
+    | undefined {
+    const entry = this.entries.get(name);
+    if (
+      entry?.status !== 'connected' ||
+      entry.tools === undefined ||
+      entry.client === undefined
+    ) {
+      return undefined;
+    }
+    return {
+      client: entry.client,
+      tools: entry.tools,
+      enabledNames: entry.enabledNames ?? new Set(entry.tools.map((t) => t.name)),
+    };
+  }
+
+  connectAll(configs: Record<string, McpServerConfig>): Promise<void> {
+    const attemptId = ++this.initialLoadAttemptId;
+    this.initialLoadStartedAt = Date.now();
+    this.initialLoadFinishedAt = undefined;
+    const initialLoad = this.connectAllNow(configs).finally(() => {
+      if (this.initialLoadAttemptId === attemptId) {
+        this.initialLoadFinishedAt = Date.now();
+      }
+    });
+    this.initialLoad = initialLoad;
+    return initialLoad;
+  }
+
+  waitForInitialLoad(signal?: AbortSignal): Promise<void> {
+    signal?.throwIfAborted();
+    if (signal === undefined) return this.initialLoad;
+    return abortable(this.initialLoad, signal);
+  }
+
+  initialLoadDurationMs(): number {
+    if (this.initialLoadStartedAt === undefined) return 0;
+    const endedAt = this.initialLoadFinishedAt ?? Date.now();
+    return Math.max(0, endedAt - this.initialLoadStartedAt);
+  }
+
+  private async connectAllNow(configs: Record<string, McpServerConfig>): Promise<void> {
+    const tasks: Promise<unknown>[] = [];
+    for (const [name, config] of Object.entries(configs)) {
+      const disabled = config.enabled === false;
+      const entry: InternalEntry = {
+        name,
+        config,
+        attemptId: 0,
+        status: disabled ? 'disabled' : 'pending',
+      };
+      this.entries.set(name, entry);
+      this.emit(entry);
+      if (!disabled) {
+        tasks.push(this.connectOne(entry, this.beginConnectAttempt(entry)));
+      }
+    }
+    await Promise.allSettled(tasks);
+  }
+
+  async reconnect(name: string): Promise<void> {
+    const entry = this.entries.get(name);
+    if (entry === undefined) {
+      throw new KimiError(ErrorCodes.MCP_SERVER_NOT_FOUND, `Unknown MCP server: ${name}`);
+    }
+    if (entry.config.enabled === false) {
+      throw new KimiError(ErrorCodes.MCP_SERVER_DISABLED, `MCP server is disabled: ${name}`);
+    }
+    const attemptId = this.beginConnectAttempt(entry);
+    await this.closeClient(entry);
+    if (!this.isCurrent(entry, attemptId)) return;
+    entry.status = 'pending';
+    entry.tools = undefined;
+    entry.enabledNames = undefined;
+    entry.error = undefined;
+    this.emit(entry);
+    await this.connectOne(entry, attemptId);
+  }
+
+  async shutdown(): Promise<void> {
+    const entries = Array.from(this.entries.values());
+    this.entries.clear();
+    const tasks = entries.map((entry) => this.closeClient(entry));
+    await Promise.allSettled(tasks);
+  }
+
+  private async connectOne(entry: InternalEntry, attemptId: number): Promise<void> {
+    const timeoutMs = entry.config.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+
+    let client: RuntimeMcpClient | undefined;
+    try {
+      const startupClient = this.createClient(entry.config, entry.name);
+      client = startupClient;
+      entry.client = startupClient;
+      const tools = await withTimeout(
+        this.connectAndDiscoverTools(startupClient),
+        timeoutMs,
+        () => {
+          // Best-effort cleanup if the startup promise is still racing.
+          void this.closeRuntimeClient(startupClient);
+        },
+      );
+      if (!this.isCurrent(entry, attemptId)) {
+        await this.closeRuntimeClient(startupClient);
+        return;
+      }
+      entry.tools = tools;
+      entry.enabledNames = computeEnabledNames(entry.config, tools);
+      entry.status = 'connected';
+      this.watchForUnexpectedClose(entry, startupClient, attemptId);
+    } catch (error) {
+      if (!this.isCurrent(entry, attemptId)) {
+        if (client !== undefined) {
+          await this.closeRuntimeClient(client);
+        }
+        return;
+      }
+      if (this.shouldMarkNeedsAuth(entry, error)) {
+        entry.status = 'needs-auth';
+        entry.error = `${entry.name} requires OAuth — run /mcp-config login ${entry.name}`;
+      } else {
+        entry.status = 'failed';
+        entry.error = formatStartupError(error, client);
+      }
+      entry.tools = undefined;
+      entry.enabledNames = undefined;
+      // Drop the client reference so a later reconnect builds a fresh one.
+      await this.closeClient(entry);
+    }
+    if (!this.isCurrent(entry, attemptId)) return;
+    this.emit(entry);
+  }
+
+  private watchForUnexpectedClose(
+    entry: InternalEntry,
+    client: RuntimeMcpClient,
+    attemptId: number,
+  ): void {
+    client.onUnexpectedClose((reason) => {
+      // The client may have outlived its entry (shutdown / reconnect already
+      // moved on). Drop the event if so — the new attempt owns the state.
+      if (!this.isCurrent(entry, attemptId)) return;
+      if (entry.client !== client) return;
+      entry.status = 'failed';
+      entry.error = formatUnexpectedCloseError(entry.name, reason);
+      entry.tools = undefined;
+      entry.enabledNames = undefined;
+      entry.client = undefined;
+      // Best-effort close; the transport is already gone, but this lets the
+      // SDK release timers and pending request handlers.
+      void this.closeRuntimeClient(client);
+      this.emit(entry);
+    });
+  }
+
+  private beginConnectAttempt(entry: InternalEntry): number {
+    entry.attemptId += 1;
+    return entry.attemptId;
+  }
+
+  private createClient(config: McpServerConfig, name: string): RuntimeMcpClient {
+    const toolCallTimeoutMs = config.toolTimeoutMs;
+    if (config.transport === 'stdio') {
+      return new StdioMcpClient(config, { toolCallTimeoutMs });
+    }
+    return new HttpMcpClient(config, {
+      toolCallTimeoutMs,
+      envLookup: this.options.envLookup,
+      oauthProvider: this.resolveOAuthProvider(config, name),
+    });
+  }
+
+  private resolveOAuthProvider(
+    config: McpServerConfig,
+    name: string,
+  ): ReturnType<McpOAuthService['getProvider']> | undefined {
+    const oauthService = this.oauthService;
+    if (oauthService === undefined) return undefined;
+    if (config.transport !== 'http') return undefined;
+    if (config.bearerTokenEnvVar !== undefined) return undefined;
+    // Only attach the provider once tokens have been minted; before that,
+    // the transport should propagate a clean 401 so we can flip the entry
+    // into `needs-auth` rather than getting tangled in the SDK's auth()
+    // flow (which would try DCR before we have an active redirect URL).
+    if (!oauthService.hasTokens(name, config.url)) return undefined;
+    return oauthService.getProvider(name, config.url);
+  }
+
+  private shouldMarkNeedsAuth(entry: InternalEntry, error: unknown): boolean {
+    if (this.oauthService === undefined) return false;
+    if (entry.config.transport !== 'http') return false;
+    if (entry.config.bearerTokenEnvVar !== undefined) return false;
+    // If the user pinned a static `headers` block, treat 401s as a bad header
+    // rather than hijacking them into the OAuth flow — the real error is more
+    // actionable than "run /mcp-config login" for a server that doesn't speak
+    // OAuth.
+    if (entry.config.headers !== undefined) return false;
+    return isUnauthorizedLikeError(error);
+  }
+
+  private async connectAndDiscoverTools(client: RuntimeMcpClient): Promise<Tool[]> {
+    await client.connect();
+    const mcpTools = await client.listTools();
+    return mcpTools.map((mcpTool) => ({
+      name: mcpTool.name,
+      description: mcpTool.description,
+      parameters: assertMcpInputSchema(mcpTool.name, mcpTool.inputSchema),
+    }));
+  }
+
+  private async closeClient(entry: InternalEntry): Promise<void> {
+    if (entry.client === undefined) return;
+    const client = entry.client;
+    entry.client = undefined;
+    await this.closeRuntimeClient(client);
+  }
+
+  private async closeRuntimeClient(client: RuntimeMcpClient): Promise<void> {
+    try {
+      await client.close();
+    } catch {
+      // Suppress close errors — the server is going away regardless and we
+      // don't want them masking the original startup failure.
+    }
+  }
+
+  private isCurrent(entry: InternalEntry, attemptId: number): boolean {
+    return this.entries.get(entry.name) === entry && entry.attemptId === attemptId;
+  }
+
+  private emit(entry: InternalEntry): void {
+    const view = toPublicEntry(entry);
+    if (view.status === 'failed' || view.status === 'needs-auth') {
+      this.log.error('mcp server unavailable', {
+        server: view.name,
+        transport: view.transport,
+        status: view.status,
+        reason: view.error,
+      });
+    }
+    for (const listener of this.listeners) {
+      try {
+        listener(view);
+      } catch {
+        // Listener faults must not break the connection manager.
+      }
+    }
+  }
+}
+
+function toPublicEntry(entry: InternalEntry): McpServerEntry {
+  return {
+    name: entry.name,
+    transport: entry.config.transport,
+    status: entry.status,
+    toolCount:
+      entry.status === 'connected' && entry.enabledNames !== undefined
+        ? entry.enabledNames.size
+        : 0,
+    error: entry.error,
+  };
+}
+
+function computeEnabledNames(config: McpServerConfig, tools: readonly Tool[]): Set<string> {
+  const all = tools.map((t) => t.name);
+  const enabledFilter =
+    config.enabledTools !== undefined ? new Set(config.enabledTools) : undefined;
+  const disabledFilter =
+    config.disabledTools !== undefined ? new Set(config.disabledTools) : undefined;
+  const allowed = new Set<string>();
+  for (const name of all) {
+    if (enabledFilter !== undefined && !enabledFilter.has(name)) continue;
+    if (disabledFilter !== undefined && disabledFilter.has(name)) continue;
+    allowed.add(name);
+  }
+  return allowed;
+}
+
+function isUnauthorizedLikeError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  if (error.name === 'UnauthorizedError') return true;
+  // SDK transport errors typically expose the HTTP status as `.code`.
+  const code = (error as { code?: unknown }).code;
+  if (typeof code === 'number' && code === 401) return true;
+  if (typeof code === 'string' && code === '401') return true;
+  // Fall back to a message sniff so server-specific error shapes still flip
+  // us into needs-auth instead of failed.
+  return /\b401\b/.test(error.message) || /unauthorized/i.test(error.message);
+}
+
+function formatStartupError(error: unknown, client: RuntimeMcpClient | undefined): string {
+  const base = error instanceof Error ? error.message : String(error);
+  const tail = stderrTail(client);
+  if (tail === undefined) return base;
+  return `${base}\nstderr: ${tail}`;
+}
+
+function formatUnexpectedCloseError(name: string, reason: UnexpectedCloseReason): string {
+  const parts = [`MCP server "${name}" closed unexpectedly`];
+  if (reason.error !== undefined) {
+    parts.push(reason.error.message);
+  }
+  if (reason.stderr !== undefined && reason.stderr.length > 0) {
+    parts.push(`stderr: ${reason.stderr.trimEnd()}`);
+  }
+  return parts.join('\n');
+}
+
+function stderrTail(client: RuntimeMcpClient | undefined): string | undefined {
+  if (client === undefined) return undefined;
+  if (!(client instanceof StdioMcpClient)) return undefined;
+  const snapshot = client.stderrSnapshot();
+  if (snapshot.length === 0) return undefined;
+  return snapshot.trimEnd();
+}
+
+async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  onTimeout?: () => void,
+): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    return await new Promise<T>((resolve, reject) => {
+      timer = setTimeout(() => {
+        onTimeout?.();
+        reject(new Error(`Timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      promise.then(resolve, reject);
+    });
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
diff --git a/packages/agent-core/src/mcp/index.ts b/packages/agent-core/src/mcp/index.ts
new file mode 100644
index 000000000..d0fef23f6
--- /dev/null
+++ b/packages/agent-core/src/mcp/index.ts
@@ -0,0 +1,5 @@
+export * from './connection-manager';
+export * from './oauth';
+export * from './session-config';
+export * from './tool-naming';
+export * from './types';
diff --git a/packages/agent-core/src/mcp/oauth/callback-server.ts b/packages/agent-core/src/mcp/oauth/callback-server.ts
new file mode 100644
index 000000000..a1c902e28
--- /dev/null
+++ b/packages/agent-core/src/mcp/oauth/callback-server.ts
@@ -0,0 +1,164 @@
+/**
+ * One-shot localhost OAuth callback listener.
+ *
+ * `startCallbackServer()` binds 127.0.0.1 on a random free port and returns a
+ * handle exposing the resulting `redirect_uri` and an awaitable
+ * `waitForCode()` that resolves with `{ code, state }` from the first
+ * `/callback` request. Any subsequent requests get a generic 404 and a
+ * non-callback path is ignored. The server is closed automatically once a
+ * code has been delivered (or `close()` is called explicitly).
+ */
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+export interface CallbackResult {
+  readonly code: string;
+  readonly state: string | undefined;
+}
+
+export interface CallbackServer {
+  readonly redirectUri: string;
+  /**
+   * Resolves with the OAuth callback payload, or rejects when:
+   *  - `signal` aborts → AbortError
+   *  - `timeoutMs` elapses → Error('OAuth callback timed out')
+   *  - the user's authorization server returns an error → Error('OAuth error: <code>')
+   */
+  waitForCode(opts: { signal?: AbortSignal; timeoutMs?: number }): Promise<CallbackResult>;
+  close(): Promise<void>;
+}
+
+const SUCCESS_HTML =
+  '<!doctype html><html><head><meta charset="utf-8"><title>Authorized</title></head>' +
+  '<body style="font-family:system-ui,sans-serif;padding:2rem;">' +
+  '<h1>Sign-in complete</h1>' +
+  '<p>You can close this tab and return to kimi-code.</p>' +
+  '</body></html>';
+
+const ERROR_HTML =
+  '<!doctype html><html><head><meta charset="utf-8"><title>OAuth error</title></head>' +
+  '<body style="font-family:system-ui,sans-serif;padding:2rem;">' +
+  '<h1>Sign-in failed</h1>' +
+  '<p>The authorization server reported an error. Return to kimi-code for details.</p>' +
+  '</body></html>';
+
+export async function startCallbackServer(): Promise<CallbackServer> {
+  let resolveCode: ((value: CallbackResult) => void) | undefined;
+  let rejectCode: ((reason: Error) => void) | undefined;
+  let settled = false;
+
+  const settle = (fn: () => void) => {
+    if (settled) return;
+    settled = true;
+    fn();
+  };
+
+  const server: Server = createServer((req, res) => {
+    handle(req, res);
+  });
+
+  function handle(req: IncomingMessage, res: ServerResponse): void {
+    if (req.method !== 'GET' || req.url === undefined) {
+      res.writeHead(404).end();
+      return;
+    }
+    let url: URL;
+    try {
+      url = new URL(req.url, 'http://localhost');
+    } catch {
+      res.writeHead(404).end();
+      return;
+    }
+    if (url.pathname !== '/callback') {
+      res.writeHead(404).end();
+      return;
+    }
+    const errorParam = url.searchParams.get('error');
+    if (errorParam !== null) {
+      const description = url.searchParams.get('error_description') ?? '';
+      res.writeHead(400, { 'content-type': 'text/html; charset=utf-8' }).end(ERROR_HTML);
+      settle(() => {
+        rejectCode?.(
+          new Error(`OAuth error: ${errorParam}${description ? ` — ${description}` : ''}`),
+        );
+      });
+      return;
+    }
+    const code = url.searchParams.get('code');
+    if (code === null || code.length === 0) {
+      res.writeHead(400, { 'content-type': 'text/html; charset=utf-8' }).end(ERROR_HTML);
+      settle(() => {
+        rejectCode?.(new Error('OAuth callback missing authorization code'));
+      });
+      return;
+    }
+    const state = url.searchParams.get('state') ?? undefined;
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }).end(SUCCESS_HTML);
+    settle(() => {
+      resolveCode?.({ code, state });
+    });
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+  const port = (server.address() as AddressInfo).port;
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+  let closed = false;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    await new Promise<void>((resolve) => {
+      server.close(() => {
+        resolve();
+      });
+    });
+  };
+
+  const waitForCode: CallbackServer['waitForCode'] = ({ signal, timeoutMs } = {}) => {
+    return new Promise<CallbackResult>((resolve, reject) => {
+      let timer: NodeJS.Timeout | undefined;
+      const onAbort = () => {
+        settle(() =>
+          rejectCode?.(
+            signal?.reason instanceof Error ? signal.reason : new Error('OAuth flow aborted'),
+          ),
+        );
+      };
+      const cleanup = () => {
+        if (timer !== undefined) clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+      };
+      resolveCode = (value) => {
+        cleanup();
+        void close();
+        resolve(value);
+      };
+      rejectCode = (reason) => {
+        cleanup();
+        void close();
+        reject(reason);
+      };
+      if (timeoutMs !== undefined) {
+        timer = setTimeout(() => {
+          settle(() => rejectCode?.(new Error('OAuth callback timed out')));
+        }, timeoutMs);
+      }
+      if (signal !== undefined) {
+        if (signal.aborted) {
+          onAbort();
+          return;
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+      }
+    });
+  };
+
+  return { redirectUri, waitForCode, close };
+}
diff --git a/packages/agent-core/src/mcp/oauth/index.ts b/packages/agent-core/src/mcp/oauth/index.ts
new file mode 100644
index 000000000..87c98552a
--- /dev/null
+++ b/packages/agent-core/src/mcp/oauth/index.ts
@@ -0,0 +1,4 @@
+export * from './callback-server';
+export * from './provider';
+export * from './service';
+export * from './store';
diff --git a/packages/agent-core/src/mcp/oauth/provider.ts b/packages/agent-core/src/mcp/oauth/provider.ts
new file mode 100644
index 000000000..be90113e7
--- /dev/null
+++ b/packages/agent-core/src/mcp/oauth/provider.ts
@@ -0,0 +1,188 @@
+/**
+ * `OAuthClientProvider` implementation backed by per-MCP-server JSON files.
+ *
+ * One provider instance per server/resource identity. The provider:
+ *  - Persists OAuth tokens, the registered DCR client info, and discovery
+ *    state under `<KIMI_CODE_HOME>/credentials/mcp/<key>-*.json`
+ *    (mode 0600; default home is `~/.kimi-code`).
+ *  - Captures the authorization URL when the SDK calls
+ *    `redirectToAuthorization` — the {@link McpOAuthService} reads that field
+ *    after the first `auth()` call returns `'REDIRECT'`.
+ *  - Keeps the PKCE verifier and OAuth `state` in-memory (one flow per
+ *    provider at a time; callers serialize via the service).
+ *
+ * The provider does **not** open browsers or run servers. The service is the
+ * orchestrator; the provider is the persistence + flow-state shim.
+ */
+
+import { randomBytes } from 'node:crypto';
+
+import type {
+  OAuthClientProvider,
+  OAuthDiscoveryState,
+} from '@modelcontextprotocol/sdk/client/auth.js';
+import type {
+  OAuthClientInformationFull,
+  OAuthClientInformationMixed,
+  OAuthClientMetadata,
+  OAuthTokens,
+} from '@modelcontextprotocol/sdk/shared/auth.js';
+
+import { JsonFileStore, canonicalMcpOAuthResource, mcpOAuthStoreKey } from './store';
+
+const TOKENS_SUFFIX = '-tokens.json';
+const CLIENT_SUFFIX = '-client.json';
+const DISCOVERY_SUFFIX = '-discovery.json';
+// Used only when the SDK probes auth during normal transport startup and no
+// callback listener is active. Interactive login overrides it with a real URL.
+const PASSIVE_REDIRECT_URI = 'http://127.0.0.1:3118/callback';
+
+export interface McpOAuthProviderOptions {
+  /** Friendly name of the MCP server; used in DCR `client_name`. */
+  readonly serverName: string;
+  /** Canonical resource identity used to isolate credentials for this server entry. */
+  readonly serverUrl: string | URL;
+  /** JSON store used for persistence. Tests inject an in-memory dir. */
+  readonly store: JsonFileStore;
+  /** Identifier embedded in DCR `client_name` ("kimi-code (server)"). */
+  readonly clientLabel?: string;
+}
+
+export class McpOAuthClientProvider implements OAuthClientProvider {
+  readonly storeKey: string;
+  readonly serverUrl: string;
+  private readonly store: JsonFileStore;
+  private readonly clientLabel: string;
+  private _redirectUrl: URL | undefined;
+  private _codeVerifier: string | undefined;
+  private _state: string | undefined;
+  private _lastAuthorizationUrl: URL | undefined;
+
+  constructor(options: McpOAuthProviderOptions) {
+    this.serverUrl = canonicalMcpOAuthResource(options.serverUrl);
+    this.storeKey = mcpOAuthStoreKey(options.serverName, this.serverUrl);
+    this.store = options.store;
+    this.clientLabel = options.clientLabel ?? `kimi-code (${options.serverName})`;
+  }
+
+  // ── flow-scoped state, set by McpOAuthService before invoking auth() ────
+
+  setRedirectUrl(url: URL): void {
+    this._redirectUrl = url;
+  }
+
+  /** URL captured from the most recent `redirectToAuthorization` call. */
+  takeAuthorizationUrl(): URL | undefined {
+    const url = this._lastAuthorizationUrl;
+    this._lastAuthorizationUrl = undefined;
+    return url;
+  }
+
+  /** OAuth `state` value generated for the most recent flow, for callback verification. */
+  expectedState(): string | undefined {
+    return this._state;
+  }
+
+  resetFlow(): void {
+    this._redirectUrl = undefined;
+    this._codeVerifier = undefined;
+    this._state = undefined;
+    this._lastAuthorizationUrl = undefined;
+  }
+
+  // ── OAuthClientProvider ─────────────────────────────────────────────────
+
+  get redirectUrl(): string | URL {
+    return this.effectiveRedirectUri();
+  }
+
+  get clientMetadata(): OAuthClientMetadata {
+    return {
+      redirect_uris: [this.effectiveRedirectUri()],
+      token_endpoint_auth_method: 'none',
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+      client_name: this.clientLabel,
+    };
+  }
+
+  state(): string {
+    this._state ??= randomBytes(16).toString('hex');
+    return this._state;
+  }
+
+  clientInformation(): OAuthClientInformationMixed | undefined {
+    return this.store.read<OAuthClientInformationFull>(`${this.storeKey}${CLIENT_SUFFIX}`);
+  }
+
+  saveClientInformation(info: OAuthClientInformationMixed): void {
+    this.store.write(`${this.storeKey}${CLIENT_SUFFIX}`, info);
+  }
+
+  tokens(): OAuthTokens | undefined {
+    return this.store.read<OAuthTokens>(`${this.storeKey}${TOKENS_SUFFIX}`);
+  }
+
+  saveTokens(tokens: OAuthTokens): void {
+    this.store.write(`${this.storeKey}${TOKENS_SUFFIX}`, tokens);
+  }
+
+  redirectToAuthorization(url: URL): void {
+    // Capture the URL for the orchestrator instead of actually opening a
+    // browser. The synthetic authenticate tool surfaces it to the model so
+    // the user can complete the flow on their own schedule.
+    this._lastAuthorizationUrl = url;
+  }
+
+  saveCodeVerifier(codeVerifier: string): void {
+    this._codeVerifier = codeVerifier;
+  }
+
+  codeVerifier(): string {
+    if (this._codeVerifier === undefined) {
+      throw new Error('McpOAuthClientProvider: PKCE code verifier not initialized');
+    }
+    return this._codeVerifier;
+  }
+
+  saveDiscoveryState(state: OAuthDiscoveryState): void {
+    this.store.write(`${this.storeKey}${DISCOVERY_SUFFIX}`, state);
+  }
+
+  discoveryState(): OAuthDiscoveryState | undefined {
+    return this.store.read<OAuthDiscoveryState>(`${this.storeKey}${DISCOVERY_SUFFIX}`);
+  }
+
+  invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): void {
+    if (scope === 'verifier') {
+      this._codeVerifier = undefined;
+      return;
+    }
+    if (scope === 'tokens' || scope === 'all') {
+      this.store.remove(`${this.storeKey}${TOKENS_SUFFIX}`);
+    }
+    if (scope === 'client' || scope === 'all') {
+      this.store.remove(`${this.storeKey}${CLIENT_SUFFIX}`);
+    }
+    if (scope === 'discovery' || scope === 'all') {
+      this.store.remove(`${this.storeKey}${DISCOVERY_SUFFIX}`);
+    }
+    if (scope === 'all') {
+      this._codeVerifier = undefined;
+    }
+  }
+
+  private effectiveRedirectUri(): string {
+    if (this._redirectUrl !== undefined) {
+      return this._redirectUrl.toString();
+    }
+    const registered = registeredRedirectUri(this.clientInformation());
+    return registered ?? PASSIVE_REDIRECT_URI;
+  }
+}
+
+function registeredRedirectUri(info: OAuthClientInformationMixed | undefined): string | undefined {
+  if (info === undefined || !('redirect_uris' in info)) return undefined;
+  const [redirectUri] = info.redirect_uris;
+  return redirectUri;
+}
diff --git a/packages/agent-core/src/mcp/oauth/service.ts b/packages/agent-core/src/mcp/oauth/service.ts
new file mode 100644
index 000000000..9b2f807de
--- /dev/null
+++ b/packages/agent-core/src/mcp/oauth/service.ts
@@ -0,0 +1,218 @@
+/**
+ * Per-process OAuth orchestrator for MCP HTTP servers.
+ *
+ * The service owns one {@link McpOAuthClientProvider} per server/resource and
+ * mediates the synthetic `mcp__<server>__authenticate` tool flow:
+ *
+ *  1. `getProvider(serverName, serverUrl)` returns the cached provider.
+ *     `HttpMcpClient` hands this to `StreamableHTTPClientTransport.authProvider`
+ *     only when the server has no static bearer token configured **and** the
+ *     provider has stored tokens for that same server URL — first-time
+ *     connections that lack tokens skip the provider entirely so a 401 surfaces
+ *     as `UnauthorizedError` from the transport instead of being swallowed by an
+ *     in-flight `auth()` attempt.
+ *  2. `beginAuthorization(serverName, serverUrl)` spins up a one-shot
+ *     localhost callback listener, sets the redirect URL on the provider,
+ *     and drives the SDK `auth()` orchestrator forward until it surfaces an
+ *     authorization URL. It returns that URL plus a `complete()` callback
+ *     that finishes the code exchange once the user finishes the browser
+ *     flow.
+ *  3. After `complete()` resolves successfully the provider has tokens on
+ *     disk; the caller (the synthetic tool) drives a manager-level
+ *     `reconnect` to swap the synthetic tool out for the real MCP tools.
+ */
+
+import { auth, type OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+
+import { startCallbackServer, type CallbackServer } from './callback-server';
+import { McpOAuthClientProvider } from './provider';
+import { JsonFileStore, mcpCredentialsDir, mcpOAuthStoreKey } from './store';
+
+export interface McpOAuthServiceOptions {
+  /** Storage backend; overrides `kimiHomeDir` when supplied. */
+  readonly store?: JsonFileStore;
+  /** Resolved Kimi home; credentials default to `<kimiHomeDir>/credentials/mcp/`. */
+  readonly kimiHomeDir?: string;
+  /** Override for the label embedded in DCR `client_name`. */
+  readonly clientLabel?: string;
+}
+
+export interface BeginAuthorizationOptions {
+  /** Override the `client_name` embedded in the DCR registration request. */
+  readonly clientLabel?: string;
+}
+
+export interface BeginAuthorizationResult {
+  /** The authorization URL the user must open in their browser. */
+  readonly authorizationUrl: URL;
+  /**
+   * Awaits the OAuth callback, validates `state`, exchanges the code for
+   * tokens, and persists them via the provider. Resolves on success;
+   * rejects on abort, timeout, or auth-server error.
+   */
+  complete(opts?: { signal?: AbortSignal; timeoutMs?: number }): Promise<void>;
+  /**
+   * Tears down the callback listener without finishing the flow. Safe to
+   * call repeatedly; called automatically by `complete()`.
+   */
+  cancel(): Promise<void>;
+}
+
+export class McpOAuthService {
+  private readonly store: JsonFileStore;
+  private readonly clientLabel: string | undefined;
+  private readonly providers = new Map<string, McpOAuthClientProvider>();
+
+  constructor(options: McpOAuthServiceOptions = {}) {
+    this.store =
+      options.store ??
+      new JsonFileStore(
+        options.kimiHomeDir === undefined ? undefined : mcpCredentialsDir(options.kimiHomeDir),
+      );
+    this.clientLabel = options.clientLabel;
+  }
+
+  /** Returns the cached provider for `serverName` + `serverUrl`, constructing it on first use. */
+  getProvider(serverName: string, serverUrl: string | URL): McpOAuthClientProvider {
+    const storeKey = mcpOAuthStoreKey(serverName, serverUrl);
+    let provider = this.providers.get(storeKey);
+    if (provider === undefined) {
+      provider = new McpOAuthClientProvider({
+        serverName,
+        serverUrl,
+        store: this.store,
+        clientLabel: this.clientLabel,
+      });
+      this.providers.set(provider.storeKey, provider);
+    }
+    return provider;
+  }
+
+  /** True once the provider has persisted tokens for this server/resource identity. */
+  hasTokens(serverName: string, serverUrl: string | URL): boolean {
+    return this.getProvider(serverName, serverUrl).tokens() !== undefined;
+  }
+
+  /**
+   * Drive the SDK `auth()` orchestrator far enough to surface an
+   * authorization URL. The caller is responsible for displaying the URL
+   * (typically via the synthetic authenticate tool) and then awaiting
+   * `complete()` to finish the code exchange.
+   */
+  async beginAuthorization(
+    serverName: string,
+    serverUrl: string | URL,
+    options: BeginAuthorizationOptions = {},
+  ): Promise<BeginAuthorizationResult> {
+    const provider = options.clientLabel === undefined
+      ? this.getProvider(serverName, serverUrl)
+      : new McpOAuthClientProvider({
+          serverName,
+          serverUrl,
+          store: this.store,
+          clientLabel: options.clientLabel,
+        });
+    if (options.clientLabel !== undefined) {
+      this.providers.set(provider.storeKey, provider);
+    }
+
+    provider.resetFlow();
+
+    let callbackServer: CallbackServer;
+    try {
+      callbackServer = await startCallbackServer();
+    } catch (error) {
+      throw wrapAuthError('failed to start OAuth callback listener', error);
+    }
+
+    provider.setRedirectUrl(new URL(callbackServer.redirectUri));
+
+    let authorizationUrl: URL | undefined;
+    try {
+      const result = await auth(provider as OAuthClientProvider, { serverUrl });
+      if (result !== 'REDIRECT') {
+        // Tokens already valid (e.g. unexpired refresh). Nothing to do.
+        await callbackServer.close();
+        throw new AlreadyAuthorizedError(serverName);
+      }
+      authorizationUrl = provider.takeAuthorizationUrl();
+      if (authorizationUrl === undefined) {
+        throw new Error('OAuth provider did not capture an authorization URL');
+      }
+    } catch (error) {
+      await callbackServer.close().catch(() => undefined);
+      provider.resetFlow();
+      if (error instanceof AlreadyAuthorizedError) throw error;
+      throw wrapAuthError(`failed to start OAuth flow for "${serverName}"`, error);
+    }
+
+    let settled = false;
+    const cancel = async (): Promise<void> => {
+      if (settled) return;
+      settled = true;
+      await callbackServer.close().catch(() => undefined);
+      provider.resetFlow();
+    };
+
+    const complete: BeginAuthorizationResult['complete'] = async (opts = {}) => {
+      if (settled) {
+        throw new Error('OAuth flow already completed or cancelled');
+      }
+      try {
+        const { code, state } = await callbackServer.waitForCode({
+          signal: opts.signal,
+          timeoutMs: opts.timeoutMs,
+        });
+        const expectedState = provider.expectedState();
+        if (expectedState !== undefined && state !== expectedState) {
+          throw new Error('OAuth state mismatch — possible CSRF; refusing token exchange');
+        }
+        const finalResult = await auth(provider as OAuthClientProvider, {
+          serverUrl,
+          authorizationCode: code,
+        });
+        if (finalResult !== 'AUTHORIZED') {
+          throw new Error(`OAuth code exchange returned "${finalResult}" instead of AUTHORIZED`);
+        }
+      } catch (error) {
+        await cancel();
+        throw wrapAuthError(`OAuth flow for "${serverName}" failed`, error);
+      }
+      settled = true;
+      await callbackServer.close().catch(() => undefined);
+      provider.resetFlow();
+    };
+
+    return { authorizationUrl, complete, cancel };
+  }
+
+  /**
+   * Clear stored credentials for a server. Use `'all'` after the user
+   * explicitly signs out; use `'tokens'` to force a re-auth while keeping
+   * the registered DCR client.
+   */
+  invalidate(
+    serverName: string,
+    serverUrl: string | URL,
+    scope: 'all' | 'client' | 'tokens' | 'discovery' = 'all',
+  ): void {
+    this.getProvider(serverName, serverUrl).invalidateCredentials(scope);
+  }
+}
+
+/** Thrown by `beginAuthorization` when stored tokens already satisfy the server. */
+export class AlreadyAuthorizedError extends Error {
+  constructor(serverName: string) {
+    super(`"${serverName}" is already authorized; no browser flow needed`);
+    this.name = 'AlreadyAuthorizedError';
+  }
+}
+
+function wrapAuthError(prefix: string, error: unknown): Error {
+  if (error instanceof Error) {
+    const wrapped = new Error(`${prefix}: ${error.message}`);
+    wrapped.cause = error;
+    return wrapped;
+  }
+  return new Error(`${prefix}: ${String(error)}`);
+}
diff --git a/packages/agent-core/src/mcp/oauth/store.ts b/packages/agent-core/src/mcp/oauth/store.ts
new file mode 100644
index 000000000..5c5e07204
--- /dev/null
+++ b/packages/agent-core/src/mcp/oauth/store.ts
@@ -0,0 +1,130 @@
+/**
+ * Small atomic JSON file store used by the MCP OAuth provider to persist
+ * tokens, registered client info, and discovery state under
+ * `<KIMI_CODE_HOME>/credentials/mcp/` (default
+ * `~/.kimi-code/credentials/mcp/`).
+ *
+ * Write semantics: write to `<file>.tmp.<pid>.<rand>` → fsync → rename.
+ * Atomic on POSIX; best-effort on Windows. Files land at mode 0600 (parent
+ * dir 0700) so other local users cannot read tokens.
+ *
+ * Read semantics: missing file → undefined. Corrupt JSON / wrong shape →
+ * undefined (never throws). The provider treats undefined as "not stored".
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import {
+  chmodSync,
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+
+export function mcpCredentialsDir(kimiHomeDir: string): string {
+  return join(kimiHomeDir, 'credentials', 'mcp');
+}
+
+export function defaultMcpCredentialsDir(): string {
+  return mcpCredentialsDir(join(homedir(), '.kimi-code'));
+}
+
+export function sanitizeStoreKey(name: string): string {
+  // Strip path-traversal segments. Tokens land under `<key>-<suffix>.json`,
+  // so the sanitized value must also be a single filename component.
+  const safe = basename(name).replaceAll(/[^a-zA-Z0-9_-]/g, '_').replaceAll(/_+/g, '_');
+  if (safe.length === 0 || safe.startsWith('.')) {
+    throw new Error(`Invalid MCP OAuth store key: "${name}"`);
+  }
+  return safe;
+}
+
+export function canonicalMcpOAuthResource(serverUrl: string | URL): string {
+  const url = new URL(serverUrl);
+  url.hash = '';
+  return url.toString();
+}
+
+export function mcpOAuthStoreKey(serverName: string, serverUrl: string | URL): string {
+  const safeName = sanitizeStoreKey(serverName);
+  const resource = canonicalMcpOAuthResource(serverUrl);
+  const digest = createHash('sha256')
+    .update(serverName)
+    .update('\0')
+    .update(resource)
+    .digest('hex')
+    .slice(0, 24);
+  return `${safeName}-${digest}`;
+}
+
+export class JsonFileStore {
+  private readonly dir: string;
+
+  constructor(dir: string = defaultMcpCredentialsDir()) {
+    this.dir = dir;
+  }
+
+  read<T>(file: string): T | undefined {
+    const path = join(this.dir, file);
+    let raw: string;
+    try {
+      raw = readFileSync(path, 'utf-8');
+    } catch {
+      return undefined;
+    }
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return undefined;
+    }
+  }
+
+  write(file: string, data: unknown): void {
+    mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    try {
+      chmodSync(this.dir, 0o700);
+    } catch {
+      // best-effort; Windows / read-only FS may refuse
+    }
+    const target = join(this.dir, file);
+    const tmp = `${target}.tmp.${process.pid}.${randomBytes(4).toString('hex')}`;
+    const buf = Buffer.from(`${JSON.stringify(data, null, 2)}\n`, 'utf-8');
+    const fd = openSync(tmp, 'w', 0o600);
+    try {
+      let written = 0;
+      while (written < buf.length) {
+        written += writeSync(fd, buf, written, buf.length - written);
+      }
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    try {
+      chmodSync(tmp, 0o600);
+      renameSync(tmp, target);
+    } catch (error) {
+      try {
+        unlinkSync(tmp);
+      } catch {
+        /* ignore */
+      }
+      throw error;
+    }
+  }
+
+  remove(file: string): void {
+    try {
+      unlinkSync(join(this.dir, file));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw error;
+      }
+    }
+  }
+}
diff --git a/packages/agent-core/src/mcp/output.ts b/packages/agent-core/src/mcp/output.ts
new file mode 100644
index 000000000..9832b04d2
--- /dev/null
+++ b/packages/agent-core/src/mcp/output.ts
@@ -0,0 +1,258 @@
+/**
+ * MCP tool-call result → ExecutableTool output pipeline.
+ *
+ * Owns the full path from "MCP protocol content blocks" to "what the agent
+ * loop feeds back to the model":
+ *  1. Convert each {@link MCPContentBlock} to a kosong `ContentPart`
+ *     (dropping unsupported shapes).
+ *  2. Wrap media-only outputs in `<mcp_tool_result name="…">` tags so the
+ *     model can attribute binary output when several tools return media.
+ *     Mirrors the in-tree `ReadMediaFile` convention.
+ *  3. Apply size limits: text/think share a 100K character budget; binary
+ *     parts (image/audio/video URLs) each carry an independent 10 MB cap and
+ *     collapse to a notice when oversize, so a single screenshot cannot
+ *     evict every text part.
+ *  4. Collapse a single-text-part result to a plain string output; otherwise
+ *     emit the `ContentPart[]` as-is.
+ *
+ * `mcpResultToExecutableOutput` is the single entry point; the per-step
+ * helpers stay private so callers cannot bypass the limits.
+ */
+
+import type { ContentPart } from '@moonshot-ai/kosong';
+
+import type { MCPContentBlock, MCPToolResult } from './types';
+
+// MCP servers can produce arbitrarily large outputs; cap what we feed back to
+// the model so a single chatty server does not blow up the context window. The
+// notice text is fed to the model verbatim so it can react (e.g. paginate),
+// which is why the limits live in the agent layer rather than in kosong.
+export const MCP_MAX_OUTPUT_CHARS = 100_000;
+const MCP_OUTPUT_TRUNCATED_TEXT = `\n\n[Output truncated: exceeded ${String(
+  MCP_MAX_OUTPUT_CHARS,
+)} character limit. Use pagination or more specific queries to get remaining content.]`;
+
+// Binary parts (image_url / audio_url / video_url) have an independent per-part
+// byte cap and do NOT share the text character budget. base64 length is not a
+// useful proxy for multimodal model cost, and a single screenshot is enough to
+// evict every text part if both compete for the same 100k budget.
+export const MCP_MAX_BINARY_PART_BYTES = 10 * 1024 * 1024;
+const MCP_MAX_BINARY_PART_CHARS = Math.ceil((MCP_MAX_BINARY_PART_BYTES * 4) / 3);
+
+function binaryPartTooLargeNotice(kind: 'image' | 'audio' | 'video', urlLength: number): string {
+  const approxMb = ((urlLength * 3) / 4 / (1024 * 1024)).toFixed(1);
+  const capMb = String(MCP_MAX_BINARY_PART_BYTES / (1024 * 1024));
+  return `[${kind}_url dropped: ~${approxMb} MB exceeds ${capMb} MB per-part limit. Try a smaller resource.]`;
+}
+
+/**
+ * Convert a single MCP content block into a kosong {@link ContentPart}.
+ *
+ * Returns `null` for block types that cannot be represented (e.g. unknown
+ * resource shapes) so the caller can drop them.
+ */
+export function convertMCPContentBlock(block: MCPContentBlock): ContentPart | null {
+  if (block.type === 'text' && typeof block.text === 'string') {
+    return { type: 'text', text: block.text };
+  }
+
+  if (block.type === 'image' && typeof block.data === 'string') {
+    const mimeType = block.mimeType ?? 'image/png';
+    return {
+      type: 'image_url',
+      imageUrl: { url: `data:${mimeType};base64,${block.data}` },
+    };
+  }
+
+  if (block.type === 'audio' && typeof block.data === 'string') {
+    const mimeType = block.mimeType ?? 'audio/mpeg';
+    return {
+      type: 'audio_url',
+      audioUrl: { url: `data:${mimeType};base64,${block.data}` },
+    };
+  }
+
+  // EmbeddedResource: payload is nested under `resource`, as
+  // TextResourceContents (`text`) or BlobResourceContents (`blob`).
+  if (block.type === 'resource' && typeof block.resource === 'object' && block.resource !== null) {
+    const res = block.resource;
+    if (typeof res.text === 'string') {
+      return { type: 'text', text: res.text };
+    }
+    if (typeof res.blob === 'string') {
+      const mimeType = res.mimeType ?? 'application/octet-stream';
+      if (mimeType.startsWith('image/')) {
+        return {
+          type: 'image_url',
+          imageUrl: { url: `data:${mimeType};base64,${res.blob}` },
+        };
+      }
+      if (mimeType.startsWith('audio/')) {
+        return {
+          type: 'audio_url',
+          audioUrl: { url: `data:${mimeType};base64,${res.blob}` },
+        };
+      }
+      if (mimeType.startsWith('video/')) {
+        return {
+          type: 'video_url',
+          videoUrl: { url: `data:${mimeType};base64,${res.blob}` },
+        };
+      }
+      return null;
+    }
+    return null;
+  }
+
+  // ResourceLink: URL reference, not an inline blob.
+  if (block.type === 'resource_link' && typeof block.uri === 'string') {
+    const mimeType = block.mimeType ?? 'application/octet-stream';
+    if (mimeType.startsWith('image/')) {
+      return { type: 'image_url', imageUrl: { url: block.uri } };
+    }
+    if (mimeType.startsWith('audio/')) {
+      return { type: 'audio_url', audioUrl: { url: block.uri } };
+    }
+    if (mimeType.startsWith('video/')) {
+      return { type: 'video_url', videoUrl: { url: block.uri } };
+    }
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Convert an `MCPToolResult` into the success-shape `ExecutableToolResult`
+ * output the agent loop expects.
+ *
+ * `qualifiedToolName` is the agent-side qualified name (e.g.
+ * `mcp__github__create_pr`) — embedded into the `<mcp_tool_result name="…">`
+ * wrap when the result is media-only, so the model can attribute binary parts.
+ */
+export function mcpResultToExecutableOutput(
+  result: MCPToolResult,
+  qualifiedToolName: string,
+): { output: string | ContentPart[]; isError: boolean } {
+  const converted: ContentPart[] = [];
+  for (const block of result.content) {
+    const part = convertMCPContentBlock(block);
+    if (part !== null) {
+      converted.push(part);
+    }
+  }
+
+  const wrapped = wrapMediaOnly(converted, qualifiedToolName);
+  const limited = applyOutputLimits(wrapped);
+  const output = collapseSingleText(limited);
+  return { output, isError: result.isError };
+}
+
+/**
+ * If `parts` contains media but no non-empty text, surround it with
+ * `<mcp_tool_result name="…">` text tags so the model can attribute the
+ * binary content. Returns the input untouched otherwise.
+ */
+function wrapMediaOnly(parts: readonly ContentPart[], qualifiedToolName: string): ContentPart[] {
+  const hasMedia = parts.some(
+    (p) => p.type === 'image_url' || p.type === 'audio_url' || p.type === 'video_url',
+  );
+  const hasNonEmptyText = parts.some((p) => p.type === 'text' && p.text.length > 0);
+  if (!hasMedia || hasNonEmptyText) return [...parts];
+  return [
+    { type: 'text', text: `<mcp_tool_result name="${qualifiedToolName}">` },
+    ...parts,
+    { type: 'text', text: '</mcp_tool_result>' },
+  ];
+}
+
+/**
+ * Apply the 100K text/think budget and the per-part 10 MB binary cap.
+ *
+ * When text/think parts get truncated, the truncation notice is appended to
+ * the last surviving text part — this keeps the single-text-part collapse
+ * working when the entire (oversized) input is a single text block.
+ */
+function applyOutputLimits(parts: readonly ContentPart[]): ContentPart[] {
+  let remaining = MCP_MAX_OUTPUT_CHARS;
+  let textTruncated = false;
+  const out: ContentPart[] = [];
+
+  for (const part of parts) {
+    if (part.type === 'text') {
+      if (remaining <= 0) {
+        textTruncated = true;
+        continue;
+      }
+      if (part.text.length > remaining) {
+        out.push({ type: 'text', text: part.text.slice(0, remaining) });
+        remaining = 0;
+        textTruncated = true;
+      } else {
+        out.push(part);
+        remaining -= part.text.length;
+      }
+      continue;
+    }
+
+    if (part.type === 'think') {
+      const size = part.think.length + (part.encrypted?.length ?? 0);
+      if (remaining <= 0) {
+        textTruncated = true;
+        continue;
+      }
+      if (size > remaining) {
+        out.push({ type: 'think', think: part.think.slice(0, remaining) });
+        remaining = 0;
+        textTruncated = true;
+      } else {
+        out.push(part);
+        remaining -= size;
+      }
+      continue;
+    }
+
+    // image_url / audio_url / video_url: per-part byte cap, independent of the
+    // text character budget. Oversized parts collapse into a per-part notice so
+    // the model can pick a smaller resource instead of silently losing the blob.
+    const url =
+      part.type === 'image_url'
+        ? part.imageUrl.url
+        : part.type === 'audio_url'
+          ? part.audioUrl.url
+          : part.videoUrl.url;
+    if (url.length > MCP_MAX_BINARY_PART_CHARS) {
+      const kind =
+        part.type === 'image_url' ? 'image' : part.type === 'audio_url' ? 'audio' : 'video';
+      out.push({ type: 'text', text: binaryPartTooLargeNotice(kind, url.length) });
+      continue;
+    }
+    out.push(part);
+  }
+
+  if (textTruncated) {
+    appendTruncationNotice(out);
+  }
+  return out;
+}
+
+function appendTruncationNotice(out: ContentPart[]): void {
+  // Merge the notice into the last text part so the very common
+  // "single oversized text" case still collapses to a plain string. Falls
+  // back to a standalone notice part if there is no text part to merge with.
+  for (let i = out.length - 1; i >= 0; i--) {
+    const candidate = out[i];
+    if (candidate?.type === 'text') {
+      out[i] = { type: 'text', text: candidate.text + MCP_OUTPUT_TRUNCATED_TEXT };
+      return;
+    }
+  }
+  out.push({ type: 'text', text: MCP_OUTPUT_TRUNCATED_TEXT });
+}
+
+function collapseSingleText(parts: readonly ContentPart[]): string | ContentPart[] {
+  if (parts.length === 1 && parts[0]?.type === 'text') {
+    return parts[0].text;
+  }
+  return [...parts];
+}
diff --git a/packages/agent-core/src/mcp/session-config.ts b/packages/agent-core/src/mcp/session-config.ts
new file mode 100644
index 000000000..874de1ea1
--- /dev/null
+++ b/packages/agent-core/src/mcp/session-config.ts
@@ -0,0 +1,23 @@
+import type { McpServerConfig } from '#/config/schema';
+
+import { loadMcpServers } from './config-loader';
+
+export interface SessionMcpConfig {
+  readonly servers: Record<string, McpServerConfig>;
+}
+
+export interface ResolveSessionMcpConfigInput {
+  readonly cwd: string;
+  readonly homeDir?: string;
+}
+
+export async function resolveSessionMcpConfig(
+  input: ResolveSessionMcpConfigInput,
+): Promise<SessionMcpConfig | undefined> {
+  const servers = await loadMcpServers({
+    cwd: input.cwd,
+    homeDir: input.homeDir,
+  });
+  if (Object.keys(servers).length === 0) return undefined;
+  return { servers };
+}
diff --git a/packages/agent-core/src/mcp/tool-naming.ts b/packages/agent-core/src/mcp/tool-naming.ts
new file mode 100644
index 000000000..87dca29a5
--- /dev/null
+++ b/packages/agent-core/src/mcp/tool-naming.ts
@@ -0,0 +1,49 @@
+const MCP_NAME_PREFIX = 'mcp__';
+const MCP_NAME_SEPARATOR = '__';
+/**
+ * Most LLM providers cap tool names around 64 characters. Leave headroom
+ * for the prefix and a separator and truncate longer names with a stable
+ * hash suffix so collisions remain extremely unlikely.
+ */
+const MAX_QUALIFIED_LENGTH = 64;
+
+/**
+ * Replace any character outside the safe ASCII set with `_`, then collapse
+ * any run of `_` into a single underscore. The collapse step guarantees neither the sanitized server
+ * nor tool name contains the `__` separator used by {@link qualifyMcpToolName},
+ * which lets {@link isMcpToolName}-aware decoders split unambiguously on the
+ * first `__` after the prefix.
+ */
+export function sanitizeMcpNamePart(part: string): string {
+  return part.replaceAll(/[^a-zA-Z0-9_-]/g, '_').replaceAll(/_+/g, '_');
+}
+
+export function isMcpToolName(name: string): boolean {
+  return name.startsWith(MCP_NAME_PREFIX);
+}
+
+/**
+ * Produce the qualified MCP tool name used inside the agent and on the wire.
+ * If the result would exceed {@link MAX_QUALIFIED_LENGTH}, a deterministic
+ * 8-char hash suffix replaces the tail so the prefix structure stays intact.
+ */
+export function qualifyMcpToolName(serverName: string, toolName: string): string {
+  const full = `${MCP_NAME_PREFIX}${sanitizeMcpNamePart(serverName)}${MCP_NAME_SEPARATOR}${sanitizeMcpNamePart(toolName)}`;
+  if (full.length <= MAX_QUALIFIED_LENGTH) return full;
+
+  const hash = stableHash8(full);
+  const head = full.slice(0, MAX_QUALIFIED_LENGTH - hash.length - 1);
+  return `${head}_${hash}`;
+}
+
+function stableHash8(input: string): string {
+  // 32-bit FNV-1a — enough to disambiguate truncated tool names within a
+  // single server's tool list. Not cryptographic; only used for collision
+  // resistance among a handful of strings.
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.codePointAt(i)!;
+    hash = Math.trunc(Math.imul(hash, 0x01000193));
+  }
+  return hash.toString(16).padStart(8, '0');
+}
diff --git a/packages/agent-core/src/mcp/types.ts b/packages/agent-core/src/mcp/types.ts
new file mode 100644
index 000000000..dee8cf4eb
--- /dev/null
+++ b/packages/agent-core/src/mcp/types.ts
@@ -0,0 +1,105 @@
+/**
+ * MCP protocol types and the minimal client contract `ToolManager` consumes.
+ *
+ * Lives in its own file (rather than `toolset.ts`) because the agent-side
+ * tool-runtime layer is `ExecutableTool`, not the legacy `Toolset` interface.
+ * What remains here is the wire-level surface: tool definitions returned by
+ * `tools/list`, the `tools/call` result shape, and the small interface that
+ * lets tests inject a fake transport without pulling in the MCP SDK type graph.
+ */
+
+/**
+ * Inline resource contents nested under an EmbeddedResource block.
+ * Exactly one of `text` or `blob` is populated, per the MCP schema's
+ * `TextResourceContents | BlobResourceContents` union.
+ */
+export interface MCPEmbeddedResourceContents {
+  uri: string;
+  mimeType?: string;
+  text?: string;
+  blob?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * A content block as returned by an MCP tool call (`tools/call`).
+ *
+ * This is a structural subset of the MCP protocol `ContentBlock` union,
+ * covering the shapes that {@link convertMCPContentBlock} knows how to convert
+ * into kosong `ContentPart`s. Additional fields are ignored.
+ */
+export interface MCPContentBlock {
+  // Known values: 'text' | 'image' | 'audio' | 'resource' | 'resource_link'.
+  // Declared as `string` to also accept future MCP content types without a
+  // type assertion.
+  type: string;
+  text?: string;
+  data?: string;
+  mimeType?: string;
+  uri?: string;
+  // EmbeddedResource carries its payload nested under `resource`, per the
+  // MCP spec — never as top-level `data`/`mimeType`.
+  resource?: MCPEmbeddedResourceContents;
+  [key: string]: unknown;
+}
+
+/**
+ * Result of a single MCP tool invocation.
+ *
+ * Matches the shape returned by the MCP protocol's `tools/call` method.
+ */
+export interface MCPToolResult {
+  content: MCPContentBlock[];
+  isError: boolean;
+}
+
+/**
+ * An MCP tool definition as returned by an MCP server's `tools/list` method.
+ */
+export interface MCPToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: unknown;
+}
+
+/**
+ * Minimal MCP client interface consumed by {@link McpConnectionManager} and
+ * {@link ToolManager}.
+ *
+ * This is a transport-agnostic seam: implementations can wrap
+ * `@modelcontextprotocol/sdk`, a bespoke stdio client, an HTTP SSE client,
+ * or a mock for testing. Keeping the surface small lets tests inject fakes
+ * without pulling in the full SDK type graph.
+ */
+export interface MCPClient {
+  /** List the tools advertised by the MCP server. */
+  listTools(): Promise<MCPToolDefinition[]>;
+  /**
+   * Invoke a tool by name with the given JSON arguments.
+   *
+   * `signal`, when provided, is forwarded to the underlying transport so an
+   * abort from the loop (e.g. user cancellation) propagates all the way to
+   * the server instead of leaving the request running in the background.
+   */
+  callTool(
+    name: string,
+    args: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<MCPToolResult>;
+}
+
+/**
+ * Validate the `inputSchema` field of an MCP tool definition. MCP advertises
+ * input schemas as JSON Schema objects; reject anything that is not a plain
+ * object so the validator compiler downstream never sees `null` or a
+ * primitive.
+ */
+export function assertMcpInputSchema(
+  toolName: string,
+  inputSchema: unknown,
+): Record<string, unknown> {
+  if (typeof inputSchema === 'object' && inputSchema !== null && !Array.isArray(inputSchema)) {
+    return inputSchema as Record<string, unknown>;
+  }
+  throw new Error(`Invalid inputSchema for MCP tool "${toolName}": schema must be a JSON object`);
+}
diff --git a/packages/agent-core/src/profile/context.ts b/packages/agent-core/src/profile/context.ts
new file mode 100644
index 000000000..ba22806fc
--- /dev/null
+++ b/packages/agent-core/src/profile/context.ts
@@ -0,0 +1,192 @@
+import * as posixPath from 'node:path/posix';
+import * as win32Path from 'node:path/win32';
+
+import type { Kaos } from '@moonshot-ai/kaos';
+
+import { listDirectory } from '../tools/support/list-directory';
+import type { SystemPromptContext } from './types';
+
+const AGENTS_MD_MAX_BYTES = 32 * 1024;
+const S_IFMT = 0o170000;
+const S_IFREG = 0o100000;
+
+export type PreparedSystemPromptContext = Pick<
+  SystemPromptContext,
+  'cwd' | 'cwdListing' | 'agentsMd'
+>;
+
+export function resolveSystemPromptCwd(kaos: Kaos, cwd: string): string {
+  return cwd === '' ? kaos.getcwd() : cwd;
+}
+
+export async function prepareSystemPromptContext(
+  kaos: Kaos,
+  cwd: string,
+): Promise<PreparedSystemPromptContext> {
+  const resolvedCwd = resolveSystemPromptCwd(kaos, cwd);
+  const [cwdListing, agentsMd] = await Promise.all([
+    listDirectory(kaos, resolvedCwd),
+    loadAgentsMd(kaos, resolvedCwd),
+  ]);
+
+  return {
+    cwd: resolvedCwd,
+    cwdListing,
+    agentsMd,
+  };
+}
+
+export async function loadAgentsMd(kaos: Kaos, workDir: string): Promise<string> {
+  const projectRoot = await findProjectRoot(kaos, workDir);
+  const dirs = dirsRootToLeaf(kaos, workDir, projectRoot);
+  const discovered: AgentFile[] = [];
+  const seen = new Set<string>();
+
+  const collect = async (path: string): Promise<boolean> => {
+    const file = await readAgentFile(kaos, path);
+    if (file === undefined) return false;
+    const key = kaos.normpath(file.path);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    discovered.push(file);
+    return true;
+  };
+
+  // User-level files come first so any project-level AGENTS.md overrides them.
+  const home = kaos.gethome();
+  await collect(joinPath(kaos, home, '.kimi-code', 'AGENTS.md'));
+
+  // Generic user-level dir (.agents) matches skill discovery.
+  const genericDirs = [joinPath(kaos, home, '.agents')];
+  const genericFiles = genericDirs.flatMap((dir) =>
+    ['AGENTS.md', 'agents.md'].map((name) => joinPath(kaos, dir, name)),
+  );
+  for (const file of genericFiles) {
+    if (await collect(file)) break;
+  }
+
+  for (const dir of dirs) {
+    await collect(joinPath(kaos, dir, '.kimi-code', 'AGENTS.md'));
+    for (const fileName of ['AGENTS.md', 'agents.md']) {
+      if (await collect(joinPath(kaos, dir, fileName))) break;
+    }
+  }
+
+  return renderAgentFiles(discovered);
+}
+
+async function findProjectRoot(kaos: Kaos, workDir: string): Promise<string> {
+  const path = pathMod(kaos);
+  const initial = kaos.normpath(workDir);
+  let current = initial;
+
+  while (true) {
+    if (await pathExists(kaos, path.join(current, '.git'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return initial;
+    current = parent;
+  }
+}
+
+function dirsRootToLeaf(kaos: Kaos, workDir: string, projectRoot: string): string[] {
+  const path = pathMod(kaos);
+  const dirs: string[] = [];
+  let current = kaos.normpath(workDir);
+
+  while (true) {
+    dirs.push(current);
+    if (current === projectRoot) break;
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  return dirs.toReversed();
+}
+
+interface AgentFile {
+  readonly path: string;
+  readonly content: string;
+}
+
+async function readAgentFile(kaos: Kaos, path: string): Promise<AgentFile | undefined> {
+  if (!(await isFile(kaos, path))) return undefined;
+  const content = (await kaos.readText(path, { errors: 'ignore' })).trim();
+  if (content.length === 0) return undefined;
+  return { path, content };
+}
+
+async function pathExists(kaos: Kaos, path: string): Promise<boolean> {
+  try {
+    await kaos.stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isFile(kaos: Kaos, path: string): Promise<boolean> {
+  try {
+    const stat = await kaos.stat(path);
+    return (stat.stMode & S_IFMT) === S_IFREG;
+  } catch {
+    return false;
+  }
+}
+
+function renderAgentFiles(files: readonly AgentFile[]): string {
+  if (files.length === 0) return '';
+
+  let remaining = AGENTS_MD_MAX_BYTES;
+  const budgeted: Array<AgentFile | undefined> = Array.from({ length: files.length });
+
+  for (let i = files.length - 1; i >= 0; i--) {
+    const file = files[i];
+    if (file === undefined) continue;
+
+    const annotation = annotationFor(file.path);
+    const separator = i < files.length - 1 ? '\n\n' : '';
+    remaining -= byteLength(annotation) + byteLength(separator);
+    if (remaining <= 0) {
+      budgeted[i] = { path: file.path, content: '' };
+      remaining = 0;
+      continue;
+    }
+
+    let content = file.content;
+    if (byteLength(content) > remaining) {
+      content = truncateUtf8(content, remaining).trim();
+    }
+    remaining -= byteLength(content);
+    budgeted[i] = { path: file.path, content };
+  }
+
+  return budgeted
+    .filter((file): file is AgentFile => file !== undefined && file.content.length > 0)
+    .map((file) => `${annotationFor(file.path)}${file.content}`)
+    .join('\n\n');
+}
+
+function truncateUtf8(text: string, maxBytes: number): string {
+  let result = text;
+  while (byteLength(result) > maxBytes) {
+    result = result.slice(0, -1);
+  }
+  return result;
+}
+
+function byteLength(text: string): number {
+  return Buffer.byteLength(text, 'utf8');
+}
+
+function annotationFor(path: string): string {
+  return `<!-- From: ${path} -->\n`;
+}
+
+function joinPath(kaos: Kaos, ...parts: string[]): string {
+  return pathMod(kaos).join(...parts);
+}
+
+function pathMod(kaos: Kaos): typeof posixPath {
+  return kaos.pathClass() === 'win32' ? win32Path : posixPath;
+}
diff --git a/packages/agent-core/src/profile/default.ts b/packages/agent-core/src/profile/default.ts
new file mode 100644
index 000000000..d3ce92304
--- /dev/null
+++ b/packages/agent-core/src/profile/default.ts
@@ -0,0 +1,26 @@
+import agentYaml from './default/agent.yaml';
+import coderYaml from './default/coder.yaml';
+import exploreYaml from './default/explore.yaml';
+import initMd from './default/init.md';
+import planYaml from './default/plan.yaml';
+import systemMd from './default/system.md';
+import { loadAgentProfilesFromSources } from './load';
+
+// Keyed by the source path the profile loader expects: profile YAML files
+// plus any file referenced through `systemPromptPath`.
+const PROFILE_SOURCES: Record<string, string> = {
+  'profile/default/agent.yaml': agentYaml,
+  'profile/default/coder.yaml': coderYaml,
+  'profile/default/explore.yaml': exploreYaml,
+  'profile/default/plan.yaml': planYaml,
+  'profile/default/system.md': systemMd,
+};
+
+export const DEFAULT_INIT_PROMPT = initMd;
+
+export const DEFAULT_AGENT_PROFILES = loadAgentProfilesFromSources(
+  ['agent.yaml', 'coder.yaml', 'explore.yaml', 'plan.yaml'].map(
+    (file) => `profile/default/${file}`,
+  ),
+  PROFILE_SOURCES,
+);
diff --git a/packages/agent-core/src/profile/default/agent.yaml b/packages/agent-core/src/profile/default/agent.yaml
new file mode 100644
index 000000000..0c0490bec
--- /dev/null
+++ b/packages/agent-core/src/profile/default/agent.yaml
@@ -0,0 +1,35 @@
+name: agent
+description: Default Kimi Code agent
+
+systemPromptPath: ./system.md
+promptVars:
+  roleAdditional: ''
+
+tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - TaskList
+  - TaskOutput
+  - TaskStop
+  - ReadMediaFile
+  - TodoList
+  - Skill
+  - WebSearch
+  - Agent
+  - FetchURL
+  - AskUserQuestion
+  - EnterPlanMode
+  - ExitPlanMode
+  - mcp__*
+
+subagents:
+  coder:
+    description: Good at general software engineering tasks.
+  explore:
+    description: Fast codebase exploration with prompt-enforced read-only behavior.
+  plan:
+    description: Read-only implementation planning and architecture design.
diff --git a/packages/agent-core/src/profile/default/coder.yaml b/packages/agent-core/src/profile/default/coder.yaml
new file mode 100644
index 000000000..22780c65c
--- /dev/null
+++ b/packages/agent-core/src/profile/default/coder.yaml
@@ -0,0 +1,18 @@
+extends: agent
+name: coder
+promptVars:
+  roleAdditional: |
+    You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. You must treat the parent agent as your caller. Do not directly ask the end user questions. If something is unclear, explain the ambiguity in your final summary to the parent agent.
+whenToUse: |
+  Use this agent for non-trivial software engineering work that may require reading files, editing code, running commands, and returning a compact but technically complete summary to the parent agent.
+tools:
+  - Bash
+  - Read
+  - ReadMediaFile
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - WebSearch
+  - FetchURL
+  - mcp__*
diff --git a/packages/agent-core/src/profile/default/explore.yaml b/packages/agent-core/src/profile/default/explore.yaml
new file mode 100644
index 000000000..84d024e58
--- /dev/null
+++ b/packages/agent-core/src/profile/default/explore.yaml
@@ -0,0 +1,36 @@
+extends: agent
+name: explore
+promptVars:
+  roleAdditional: |
+    You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. You must treat the parent agent as your caller. Do not directly ask the end user questions. If something is unclear, explain the ambiguity in your final summary to the parent agent.
+
+    You are a codebase exploration specialist. Your role is EXCLUSIVELY to search, read, and analyze existing code and resources. You do NOT have access to file editing tools.
+
+    Your strengths:
+    - Rapidly finding files using glob patterns
+    - Searching code and text with powerful regex patterns
+    - Reading and analyzing file contents
+    - Running read-only shell commands (git log, git diff, ls, find, etc.)
+
+    Guidelines:
+    - Use Glob for broad file pattern matching. Patterns MUST contain a literal anchor (extension or subdirectory); pure wildcards like `*` or `**/*` are rejected by the tool.
+    - Use Grep for searching file contents with regex
+    - Use Read when you know the specific file path
+    - Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find)
+    - NEVER use Bash for any file creation or modification commands
+    - Adapt your search depth based on the thoroughness level specified by the caller
+    - Wherever possible, spawn multiple parallel tool calls for grepping and reading files to maximize speed
+
+    If the prompt includes a <git-context> block, use it to orient yourself about the repository state before starting your investigation.
+
+    You are meant to be a fast agent. Complete the search request efficiently and report your findings clearly in a structured format.
+whenToUse: |
+  Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (e.g. "src/**/*.yaml"), search code for keywords (e.g. "database connection"), or answer questions about the codebase (e.g. "how does the auth module work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "thorough" for comprehensive analysis across multiple locations and naming conventions. Use this agent for any read-only exploration that will clearly require more than 3 search queries. Prefer launching multiple explore agents concurrently when investigating independent questions.
+tools:
+  - Bash
+  - Read
+  - ReadMediaFile
+  - Glob
+  - Grep
+  - WebSearch
+  - FetchURL
diff --git a/packages/agent-core/src/profile/default/init.md b/packages/agent-core/src/profile/default/init.md
new file mode 100644
index 000000000..25d6c561a
--- /dev/null
+++ b/packages/agent-core/src/profile/default/init.md
@@ -0,0 +1,21 @@
+You are a software engineering expert with many years of programming experience. Please explore the current project directory to understand the project's architecture and main details.
+
+Task requirements:
+1. Analyze the project structure and identify key configuration files (such as pyproject.toml, package.json, Cargo.toml, etc.).
+2. Understand the project's technology stack, build process and runtime architecture.
+3. Identify how the code is organized and main module divisions.
+4. Discover project-specific development conventions, testing strategies, and deployment processes.
+
+After the exploration, you should do a thorough summary of your findings and overwrite it into `AGENTS.md` file in the project root. You need to refer to what is already in the file when you do so.
+
+For your information, `AGENTS.md` is a file intended to be read by AI coding agents. Expect the reader of this file know nothing about the project.
+
+You should compose this file according to the actual project content. Do not make any assumptions or generalizations. Ensure the information is accurate and useful. You must use the natural language that is mainly used in the project's comments and documentation.
+
+Popular sections that people usually write in `AGENTS.md` are:
+
+- Project overview
+- Build and test commands
+- Code style guidelines
+- Testing instructions
+- Security considerations
diff --git a/packages/agent-core/src/profile/default/plan.yaml b/packages/agent-core/src/profile/default/plan.yaml
new file mode 100644
index 000000000..beb3e1c2d
--- /dev/null
+++ b/packages/agent-core/src/profile/default/plan.yaml
@@ -0,0 +1,19 @@
+extends: agent
+name: plan
+promptVars:
+  roleAdditional: |
+    You are now running as a subagent. All the `user` messages are sent by the main agent. The main agent cannot see your context, it can only see your last message when you finish the task. You must treat the parent agent as your caller. Do not directly ask the end user questions. If something is unclear, explain the ambiguity in your final summary to the parent agent.
+
+    Before designing your implementation plan, consider whether you fully understand the codebase areas relevant to the task. If not, recommend the parent agent to use the explore agent (subagent_type="explore") to investigate key questions first. In your response, clearly state:
+    1. What you already know from the information provided
+    2. What questions remain unanswered that would benefit from explore agent investigation
+    3. Your implementation plan (either preliminary if questions remain, or final if sufficient context exists)
+whenToUse: |
+  Use this agent when the parent agent needs a step-by-step implementation plan, key file identification, and architectural trade-off analysis before code changes are made.
+tools:
+  - Read
+  - ReadMediaFile
+  - Glob
+  - Grep
+  - WebSearch
+  - FetchURL
diff --git a/packages/agent-core/src/profile/default/system.md b/packages/agent-core/src/profile/default/system.md
new file mode 100644
index 000000000..0436f944b
--- /dev/null
+++ b/packages/agent-core/src/profile/default/system.md
@@ -0,0 +1,165 @@
+You are Kimi Code CLI, an interactive general AI agent running on a user's computer.
+
+Your primary goal is to help users with software engineering tasks by taking action — use the tools available to you to make real changes on the user's system. You should also answer questions when asked. Always adhere strictly to the following system instructions and the user's requirements.
+
+{{ ROLE_ADDITIONAL }}
+
+# Prompt and Tool Use
+
+The user's messages may contain questions and/or task descriptions in natural language, code snippets, logs, file paths, or other forms of information. Read them, understand them and do what the user requested. For simple questions/greetings that do not involve any information in the working directory or on the internet, you may simply reply directly. For anything else, default to taking action with tools. When the request could be interpreted as either a question to answer or a task to complete, treat it as a task.
+
+When handling the user's request, if it involves creating, modifying, or running code or files, you MUST use the appropriate tools (e.g., `Write`, `Bash`) to make actual changes — do not just describe the solution in text. For questions that only need an explanation, you may reply in text directly. When calling tools, do not provide explanations because the tool calls themselves should be self-explanatory. You MUST follow the description of each tool and its parameters when calling tools.
+
+If the `Agent` tool is available, you can use it to delegate a focused subtask to a subagent instance. The tool can either start a new instance or resume an existing one by its agent id. Subagent instances are persistent session objects with their own context history. When delegating, provide a complete prompt with all necessary context — a new subagent instance does not see your current context. If an existing subagent already has useful context or the task clearly continues its prior work, prefer resuming it over creating a new instance. Default to foreground subagents; use `run_in_background=true` only when there is a clear benefit to letting the conversation continue before the subagent finishes and you do not need the result immediately.
+
+You have the capability to output any number of tool calls in a single response. If you anticipate making multiple non-interfering tool calls, you are HIGHLY RECOMMENDED to make them in parallel to significantly improve efficiency. This is very important to your performance.
+
+The results of the tool calls will be returned to you in a tool message. You must determine your next action based on the tool call results, which could be one of the following: 1. Continue working on the task, 2. Inform the user that the task is completed or has failed, or 3. Ask the user for more information.
+
+The system may insert information wrapped in `<system>` tags within user or tool messages. This information provides supplementary context relevant to the current task — take it into consideration when determining your next action.
+
+Tool results and user messages may also include `<system-reminder>` tags. Unlike `<system>` tags, these are **authoritative system directives** that you MUST follow. They bear no direct relation to the specific tool results or user messages in which they appear. Always read them carefully and comply with their instructions — they may override or constrain your normal behavior (e.g., restricting you to read-only actions during plan mode).
+
+If the `Bash`, `TaskList`, `TaskOutput`, and `TaskStop` tools are available and you are the root agent, you can use background `Bash` for long-running shell commands. Launch it via `Bash` with `run_in_background=true` and a short `description`. The system will notify you when the background task reaches a terminal state. Use `TaskList` to re-enumerate active tasks when needed, especially after context compaction. Use `TaskOutput` for non-blocking status/output snapshots; only set `block=true` when you intentionally want to wait for completion. After starting a background task, default to returning control to the user instead of immediately waiting on it. Use `TaskStop` only when you need to cancel the task. For human users in the interactive shell, the only task-management slash command is `/tasks`. Do not tell users to run `/task`, `/tasks list`, `/tasks output`, `/tasks stop`, or any other invented slash subcommands. If you are a subagent or these tools are not available, do not assume you can create or control background tasks.
+
+If a foreground tool call or a background agent requests approval, the approval is coordinated through the unified approval runtime and surfaced through the root UI channel. Do not assume approvals are local to a single subagent turn.
+
+When responding to the user, you MUST use the SAME language as the user, unless explicitly instructed to do otherwise.
+
+# General Guidelines for Coding
+
+When building something from scratch, you should:
+
+- Understand the user's requirements.
+- Ask the user for clarification if there is anything unclear.
+- Design the architecture and make a plan for the implementation.
+- Write the code in a modular and maintainable way.
+
+Always use tools to implement your code changes:
+
+- Use `Write` to create or overwrite source files. Code that only appears in your text response is NOT saved to the file system and will not take effect.
+- Use `Bash` to run and test your code after writing it.
+- Iterate: if tests fail, read the error, fix the code with `Write` or `Edit`, and re-test with `Bash`.
+
+When working on an existing codebase, you should:
+
+- Understand the codebase by reading it with tools (`Read`, `Glob`, `Grep`) before making changes. Identify the ultimate goal and the most important criteria to achieve the goal.
+- When using `Glob`, include a literal anchor (file extension or subdirectory) in the pattern. Pure wildcards like `*` or `**/*` are rejected by the tool.
+- For a bug fix, you typically need to check error logs or failed tests, scan over the codebase to find the root cause, and figure out a fix. If user mentioned any failed tests, you should make sure they pass after the changes.
+- For a feature, you typically need to design the architecture, and write the code in a modular and maintainable way, with minimal intrusions to existing code. Add new tests if the project already has tests.
+- For a code refactoring, you typically need to update all the places that call the code you are refactoring if the interface changes. DO NOT change any existing logic especially in tests, focus only on fixing any errors caused by the interface changes.
+- Make MINIMAL changes to achieve the goal. This is very important to your performance.
+- Follow the coding style of existing code in the project.
+- For broader codebase exploration and deep research, use `Agent` with `subagent_type="explore"` — a fast, read-only agent specialized for searching and understanding codebases. Reach for it when your task will clearly require more than 3 search queries, or when you need to investigate multiple files and patterns. Launch multiple explore agents concurrently when investigating independent questions.
+
+DO NOT run `git commit`, `git push`, `git reset`, `git rebase` and/or do any other git mutations unless explicitly asked to do so. Ask for confirmation each time when you need to do git mutations, even if the user has confirmed in earlier conversations.
+
+# General Guidelines for Research and Data Processing
+
+The user may ask you to research on certain topics, process or generate certain multimedia files. When doing such tasks, you must:
+
+- Understand the user's requirements thoroughly, ask for clarification before you start if needed.
+- Make plans before doing deep or wide research, to ensure you are always on track.
+- Search on the Internet if possible, with carefully-designed search queries to improve efficiency and accuracy.
+- Use proper tools or shell commands or Python packages to process or generate images, videos, PDFs, docs, spreadsheets, presentations, or other multimedia files. Detect if there are already such tools in the environment. If you have to install third-party tools/packages, you MUST ensure that they are installed in a virtual/isolated environment.
+- Once you generate or edit any images, videos or other media files, try to read it again before proceed, to ensure that the content is as expected.
+- Avoid installing or deleting anything to/from outside of the current working directory. If you have to do so, ask the user for confirmation.
+
+# Working Environment
+
+## Operating System
+
+You are running on **{{ KIMI_OS }}**. The Bash tool executes commands using **{{ KIMI_SHELL }}**.
+{% if KIMI_OS == "Windows" %}
+
+IMPORTANT: You are on Windows. The Bash tool runs through Git Bash, so use Unix shell syntax inside Bash commands — `/dev/null` not `NUL`, and forward slashes in paths. For file operations, always prefer the built-in tools (Read, Write, Edit, Glob, Grep) over Bash commands — they work reliably across all platforms.
+{% endif %}
+
+The operating environment is not in a sandbox. Any actions you do will immediately affect the user's system. So you MUST be extremely cautious. Unless being explicitly instructed to do so, you should never access (read/write/execute) files outside of the working directory.
+
+## Date and Time
+
+The current date and time in ISO format is `{{ KIMI_NOW }}`. This is only a reference for you when searching the web, or checking file modification time, etc. If you need the exact time, use Bash tool with proper command.
+
+## Working Directory
+
+The current working directory is `{{ KIMI_WORK_DIR }}`. This should be considered as the project root if you are instructed to perform tasks on the project. Every file system operation will be relative to the working directory if you do not explicitly specify the absolute path. Tools may require absolute paths for some parameters, IF SO, YOU MUST use absolute paths for these parameters.
+
+The directory listing of current working directory is:
+
+```
+{{ KIMI_WORK_DIR_LS }}
+```
+
+Use this as your basic understanding of the project structure. The tree only shows the first two levels; entries marked "... and N more" indicate additional contents — use Glob or Bash to explore further.
+{% if KIMI_ADDITIONAL_DIRS_INFO %}
+
+## Additional Directories
+
+The following directories have been added to the workspace. You can read, write, search, and glob files in these directories as part of your workspace scope.
+
+{{ KIMI_ADDITIONAL_DIRS_INFO }}
+{% endif %}
+
+# Project Information
+
+Markdown files named `AGENTS.md` usually contain the background, structure, coding styles, user preferences and other relevant information about the project. You should use this information to understand the project and the user's preferences. `AGENTS.md` files may exist at different locations in the project, but typically there is one in the project root.
+
+> Why `AGENTS.md`?
+>
+> `README.md` files are for humans: quick starts, project descriptions, and contribution guidelines. `AGENTS.md` complements this by containing the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors.
+>
+> We intentionally kept it separate to:
+>
+> - Give agents a clear, predictable place for instructions.
+> - Keep `README`s concise and focused on human contributors.
+> - Provide precise, agent-focused guidance that complements existing `README` and docs.
+
+The `AGENTS.md` instructions (merged from all applicable directories):
+
+`````````
+{{ KIMI_AGENTS_MD }}
+`````````
+
+`AGENTS.md` files can appear at any level of the project directory tree, including inside `.kimi-code/` directories. Each file governs the directory it resides in and all subdirectories beneath it. When multiple `AGENTS.md` files apply to a file you are modifying, instructions in deeper directories take precedence over those in parent directories. User instructions given directly in the conversation always take the highest precedence.
+
+When working on files in subdirectories, always check whether those directories contain their own `AGENTS.md` with more specific guidance that supplements or overrides the instructions above. You may also check `README`/`README.md` files for more information about the project.
+
+If you modified any files/styles/structures/configurations/workflows/... mentioned in `AGENTS.md` files, you MUST update the corresponding `AGENTS.md` files to keep them up-to-date.
+
+# Skills
+
+Skills are reusable, composable capabilities that enhance your abilities. Each skill is either a self-contained directory with a `SKILL.md` file or a standalone `.md` file that contains instructions, examples, and/or reference material.
+
+## What are skills?
+
+Skills are modular extensions that provide:
+
+- Specialized knowledge: Domain-specific expertise (e.g., PDF processing, data analysis)
+- Workflow patterns: Best practices for common tasks
+- Tool integrations: Pre-configured tool chains for specific operations
+- Reference material: Documentation, templates, and examples
+
+## Available skills
+
+Skills are grouped by scope (`Project`, `User`, `Extra`, `Built-in`) so you can tell where each came from. When the user refers to "the skill in this project" or "the user-scope skill", use the scope heading to disambiguate. When multiple scopes define a skill with the same name, the more specific scope takes precedence: **Project overrides User overrides Extra overrides Built-in**.
+
+{{ KIMI_SKILLS }}
+
+## How to use skills
+
+Identify the skills that are likely to be useful for the tasks you are currently working on, read the skill file for detailed instructions, guidelines, scripts and more.
+
+Only read skill details when needed to conserve the context window.
+
+# Ultimate Reminders
+
+At any time, you should be HELPFUL, CONCISE, and ACCURATE. Be thorough in your actions — test what you build, verify what you change — not in your explanations.
+
+- Never diverge from the requirements and the goals of the task you work on. Stay on track.
+- Never give the user more than what they want.
+- Try your best to avoid any hallucination. Do fact checking before providing any factual information.
+- Think about the best approach, then take action decisively.
+- Do not give up too early.
+- ALWAYS, keep it stupidly simple. Do not overcomplicate things.
+- When the task requires creating or modifying files, always use tools to do so. Never treat displaying code in your response as a substitute for actually writing it to the file system.
diff --git a/packages/agent-core/src/profile/index.ts b/packages/agent-core/src/profile/index.ts
new file mode 100644
index 000000000..80e303814
--- /dev/null
+++ b/packages/agent-core/src/profile/index.ts
@@ -0,0 +1,5 @@
+export * from './types';
+export * from './context';
+export * from './load';
+export * from './resolve';
+export * from './default';
diff --git a/packages/agent-core/src/profile/load.ts b/packages/agent-core/src/profile/load.ts
new file mode 100644
index 000000000..613edcf63
--- /dev/null
+++ b/packages/agent-core/src/profile/load.ts
@@ -0,0 +1,125 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join, posix as posixPath } from 'node:path';
+
+import { load as loadYaml } from 'js-yaml';
+
+import { resolveAgentProfiles } from './resolve';
+import { RawAgentProfileSchema, type RawAgentProfile, type ResolvedAgentProfile } from './types';
+
+export async function loadAgentProfilesFromDir(
+  paths: readonly string[],
+): Promise<Record<string, ResolvedAgentProfile>> {
+  const rawProfiles = await loadRawAgentProfiles(paths);
+  return resolveAgentProfiles(rawProfiles);
+}
+
+export function loadAgentProfilesFromSources(
+  paths: readonly string[],
+  sources: Readonly<Record<string, string>>,
+): Record<string, ResolvedAgentProfile> {
+  const rawProfiles = paths.map((profilePath) =>
+    finalizeRawAgentProfileSource(readRequiredSource(sources, profilePath), profilePath, sources),
+  );
+  return resolveAgentProfiles(rawProfiles);
+}
+
+async function loadRawAgentProfiles(paths: readonly string[]): Promise<RawAgentProfile[]> {
+  const profiles: RawAgentProfile[] = [];
+
+  for (const profilePath of paths) {
+    let content: string;
+    try {
+      content = await readFile(profilePath, 'utf-8');
+    } catch (error) {
+      if (isFileNotFound(error)) continue;
+      throw readError('agent profile', profilePath, error);
+    }
+    profiles.push(await finalizeRawAgentProfile(content, profilePath));
+  }
+
+  return profiles;
+}
+
+async function finalizeRawAgentProfile(
+  content: string,
+  profilePath: string,
+): Promise<RawAgentProfile> {
+  const raw = parseAgentProfileYaml(content, profilePath);
+  if (raw.systemPromptPath === undefined) return raw;
+  const templatePath = join(dirname(profilePath), raw.systemPromptPath);
+  try {
+    return { ...raw, systemPromptTemplate: await readFile(templatePath, 'utf-8') };
+  } catch (error) {
+    throw new Error(
+      `Failed to read system prompt template for "${raw.name}" at ${templatePath}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      { cause: error },
+    );
+  }
+}
+
+function finalizeRawAgentProfileSource(
+  content: string,
+  profilePath: string,
+  sources: Readonly<Record<string, string>>,
+): RawAgentProfile {
+  const raw = parseAgentProfileYaml(content, profilePath);
+  if (raw.systemPromptPath === undefined) return raw;
+  const templatePath = resolveProfileSourcePath(profilePath, raw.systemPromptPath);
+  return { ...raw, systemPromptTemplate: readRequiredSource(sources, templatePath) };
+}
+
+function parseAgentProfileYaml(content: string, profilePath: string): RawAgentProfile {
+  let parsed: unknown;
+  try {
+    parsed = loadYaml(content);
+  } catch (error) {
+    throw new Error(
+      `Invalid agent profile YAML at ${profilePath}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      { cause: error },
+    );
+  }
+  const result = RawAgentProfileSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new Error(`Invalid agent profile at ${profilePath}`);
+  }
+  return result.data;
+}
+
+function resolveProfileSourcePath(profilePath: string, relativePath: string): string {
+  return normalizeSourcePath(
+    posixPath.join(posixPath.dirname(normalizeSourcePath(profilePath)), relativePath),
+  );
+}
+
+function readRequiredSource(sources: Readonly<Record<string, string>>, path: string): string {
+  const normalized = normalizeSourcePath(path);
+  const content = sources[normalized];
+  if (content === undefined) {
+    throw new Error(`Embedded agent profile source missing: ${normalized}`);
+  }
+  return content;
+}
+
+function normalizeSourcePath(path: string): string {
+  return posixPath.normalize(path.replaceAll('\\', '/')).replace(/^\.\//, '');
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isFileNotFound(error: unknown): boolean {
+  return isRecord(error) && error['code'] === 'ENOENT';
+}
+
+function readError(label: string, filePath: string, error: unknown): Error {
+  return new Error(
+    `Failed to read ${label} at ${filePath}: ${
+      error instanceof Error ? error.message : String(error)
+    }`,
+  );
+}
diff --git a/packages/agent-core/src/profile/resolve.ts b/packages/agent-core/src/profile/resolve.ts
new file mode 100644
index 000000000..001f7d19f
--- /dev/null
+++ b/packages/agent-core/src/profile/resolve.ts
@@ -0,0 +1,222 @@
+import { renderPrompt } from '../utils/render-prompt';
+import type {
+  RawAgentProfile,
+  RawSubagentProfile,
+  ResolvedAgentProfile,
+  SystemPromptContext,
+  SystemPromptRenderer,
+} from './types';
+
+interface MergedAgentProfile {
+  readonly name: string;
+  readonly description?: string | undefined;
+  readonly systemPromptTemplate: string;
+  readonly promptVars: Record<string, string>;
+  readonly tools: string[];
+  readonly whenToUse?: string | undefined;
+  readonly subagents?: Record<string, RawSubagentProfile> | undefined;
+}
+
+/**
+ * Resolve agent profiles with extends inheritance.
+ *
+ * Each resolved profile exposes its `systemPrompt` as a renderer that
+ * closes over the merged template and prompt vars. The renderer is
+ * invoked later with a {@link SystemPromptContext} to produce the
+ * concrete prompt — this lets context that only exists at runtime
+ * (cwd listing, AGENTS.md, skills) flow through without re-loading
+ * profiles.
+ */
+export function resolveAgentProfiles(
+  raw: readonly RawAgentProfile[],
+): Record<string, ResolvedAgentProfile> {
+  const profileMap = new Map<string, RawAgentProfile>();
+  const mergedCache = new Map<string, MergedAgentProfile>();
+  const resolvedCache = new Map<string, ResolvedAgentProfile>();
+
+  for (const profile of raw) {
+    if (profileMap.has(profile.name)) {
+      throw new Error(`Duplicate agent profile name: "${profile.name}"`);
+    }
+    profileMap.set(profile.name, profile);
+  }
+
+  for (const profile of raw) {
+    const merged = resolveMergedProfile(profile.name, profileMap, mergedCache, []);
+    resolvedCache.set(profile.name, toResolvedProfile(merged));
+  }
+
+  applySubagentDescriptions(mergedCache, resolvedCache);
+  linkResolvedSubagents(mergedCache, resolvedCache);
+
+  const result: Record<string, ResolvedAgentProfile> = {};
+  for (const [name, profile] of resolvedCache) {
+    result[name] = profile;
+  }
+
+  return result;
+}
+
+function resolveMergedProfile(
+  name: string,
+  profileMap: Map<string, RawAgentProfile>,
+  cache: Map<string, MergedAgentProfile>,
+  stack: string[],
+): MergedAgentProfile {
+  const cached = cache.get(name);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const cycleIndex = stack.indexOf(name);
+  if (cycleIndex !== -1) {
+    const cycle = [...stack.slice(cycleIndex), name].join(' -> ');
+    throw new Error(`Agent profile extends cycle detected: ${cycle}`);
+  }
+
+  const profile = profileMap.get(name);
+  if (profile === undefined) {
+    throw new Error(`Agent profile "${name}" not found`);
+  }
+
+  let parent: MergedAgentProfile | undefined;
+  if (profile.extends !== undefined) {
+    if (!profileMap.has(profile.extends)) {
+      throw new Error(
+        `Agent profile "${profile.name}" extends "${profile.extends}" but parent profile was not found`,
+      );
+    }
+    parent = resolveMergedProfile(profile.extends, profileMap, cache, [...stack, name]);
+  }
+
+  const merged: MergedAgentProfile = {
+    name: profile.name,
+    description: profile.description,
+    systemPromptTemplate: profile.systemPromptTemplate ?? parent?.systemPromptTemplate ?? '',
+    promptVars: {
+      ...parent?.promptVars,
+      ...profile.promptVars,
+    },
+    tools: profile.tools !== undefined ? [...profile.tools] : [...(parent?.tools ?? [])],
+    whenToUse: profile.whenToUse ?? parent?.whenToUse,
+    subagents: cloneSubagents(profile.subagents),
+  };
+
+  cache.set(profile.name, merged);
+  return merged;
+}
+
+function toResolvedProfile(merged: MergedAgentProfile): ResolvedAgentProfile {
+  return {
+    name: merged.name,
+    description: merged.description,
+    systemPrompt: createSystemPromptRenderer(merged),
+    tools: [...merged.tools],
+    whenToUse: merged.whenToUse,
+  };
+}
+
+/**
+ * Build a renderer that captures the merged template and prompt vars.
+ * The runtime SystemPromptContext is mapped to the template variables
+ * (KIMI_OS, KIMI_AGENTS_MD, ...) at render time.
+ */
+function createSystemPromptRenderer(merged: MergedAgentProfile): SystemPromptRenderer {
+  return (context: SystemPromptContext): string => {
+    const vars = buildTemplateVars(context, merged.promptVars);
+    try {
+      return renderPrompt(merged.systemPromptTemplate, vars);
+    } catch (error) {
+      throw new Error(
+        `Failed to render system prompt for agent profile "${merged.name}": ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        { cause: error },
+      );
+    }
+  };
+}
+
+function buildTemplateVars(
+  context: SystemPromptContext,
+  promptVars: Record<string, string>,
+): Record<string, string> {
+  const skills =
+    typeof context.skills === 'string'
+      ? context.skills
+      : (context.skills?.getModelSkillListing() ?? '');
+  const now =
+    context.now instanceof Date
+      ? context.now.toISOString()
+      : (context.now ?? new Date().toISOString());
+
+  return {
+    ...promptVars,
+    KIMI_OS: context.osEnv.osKind,
+    KIMI_SHELL: `${context.osEnv.shellName} (\`${context.osEnv.shellPath}\`)`,
+    KIMI_NOW: now,
+    KIMI_WORK_DIR: context.cwd,
+    KIMI_WORK_DIR_LS: context.cwdListing ?? '',
+    KIMI_AGENTS_MD: context.agentsMd ?? '',
+    KIMI_SKILLS: skills,
+    KIMI_ADDITIONAL_DIRS_INFO: context.additionalDirsInfo ?? '',
+    ROLE_ADDITIONAL:
+      context.roleAdditional ?? promptVars['ROLE_ADDITIONAL'] ?? promptVars['roleAdditional'] ?? '',
+  };
+}
+
+function applySubagentDescriptions(
+  mergedProfiles: Map<string, MergedAgentProfile>,
+  resolvedProfiles: Map<string, ResolvedAgentProfile>,
+): void {
+  for (const [ownerName, owner] of mergedProfiles) {
+    if (owner.subagents === undefined) continue;
+    for (const [subagentName, subagent] of Object.entries(owner.subagents)) {
+      const target = resolvedProfiles.get(subagentName);
+      if (target === undefined) {
+        throwMissingSubagent(ownerName, subagentName);
+      }
+      if (target.description === undefined && subagent.description !== undefined) {
+        target.description = subagent.description;
+      }
+    }
+  }
+}
+
+function linkResolvedSubagents(
+  mergedProfiles: Map<string, MergedAgentProfile>,
+  resolvedProfiles: Map<string, ResolvedAgentProfile>,
+): void {
+  for (const [ownerName, owner] of mergedProfiles) {
+    if (owner.subagents === undefined) continue;
+
+    const subagents: Record<string, ResolvedAgentProfile> = {};
+    for (const subagentName of Object.keys(owner.subagents)) {
+      const target = resolvedProfiles.get(subagentName);
+      if (target === undefined) {
+        throwMissingSubagent(ownerName, subagentName);
+      }
+      subagents[subagentName] = target;
+    }
+
+    const resolved = resolvedProfiles.get(ownerName);
+    if (resolved !== undefined) {
+      resolved.subagents = subagents;
+    }
+  }
+}
+
+function throwMissingSubagent(ownerName: string, subagentName: string): never {
+  throw new Error(
+    `Agent profile "${ownerName}" declares subagent "${subagentName}" but that agent profile was not found`,
+  );
+}
+
+function cloneSubagents(
+  subagents: Record<string, RawSubagentProfile> | undefined,
+): Record<string, RawSubagentProfile> | undefined {
+  if (subagents === undefined) return undefined;
+  return Object.fromEntries(
+    Object.entries(subagents).map(([name, subagent]) => [name, { ...subagent }]),
+  );
+}
diff --git a/packages/agent-core/src/profile/types.ts b/packages/agent-core/src/profile/types.ts
new file mode 100644
index 000000000..5e9ef5c68
--- /dev/null
+++ b/packages/agent-core/src/profile/types.ts
@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+import type { SkillRegistry } from '../skill';
+import type { Environment } from '../utils/environment';
+
+export const RawSubagentProfileSchema = z.object({
+  description: z.string().optional(),
+});
+
+export type RawSubagentProfile = z.infer<typeof RawSubagentProfileSchema>;
+
+export const RawAgentProfileSchema = z.object({
+  extends: z.string().optional(),
+  name: z.string().min(1),
+  description: z.string().optional(),
+  systemPromptPath: z.string().optional(),
+  systemPromptTemplate: z.string().optional(),
+  promptVars: z.record(z.string(), z.string()).optional(),
+  // Exact builtin/user tool names, plus optional MCP glob patterns
+  // (`mcp__*`, `mcp__github__*`) that gate which MCP tools the profile sees.
+  tools: z.array(z.string()).optional(),
+  whenToUse: z.string().optional(),
+  subagents: z.record(z.string(), RawSubagentProfileSchema).optional(),
+});
+
+export type RawAgentProfile = z.infer<typeof RawAgentProfileSchema>;
+
+/**
+ * Runtime context supplied to a system prompt renderer.
+ *
+ * Captures everything determined at render time rather than at profile-load
+ * time: the OS/shell, working directory, AGENTS.md instructions, available
+ * skills, and so on. Loaders return renderers; callers invoke them with
+ * the live context whenever a concrete prompt is needed.
+ */
+export interface SystemPromptContext {
+  readonly osEnv: Environment;
+  readonly cwd: string;
+  readonly now?: string | Date;
+  readonly cwdListing?: string;
+  readonly agentsMd?: string;
+  readonly skills?: SkillRegistry | string;
+  readonly additionalDirsInfo?: string;
+  readonly roleAdditional?: string;
+}
+
+export type SystemPromptRenderer = (context: SystemPromptContext) => string;
+
+export interface ResolvedAgentProfile {
+  name: string;
+  description?: string;
+  systemPrompt: SystemPromptRenderer;
+  tools: string[];
+  whenToUse?: string;
+  subagents?: Record<string, ResolvedAgentProfile>;
+}
diff --git a/packages/agent-core/src/prompt-modules.d.ts b/packages/agent-core/src/prompt-modules.d.ts
new file mode 100644
index 000000000..345a703a0
--- /dev/null
+++ b/packages/agent-core/src/prompt-modules.d.ts
@@ -0,0 +1,12 @@
+// Raw-string imports for prompt sources. The `raw-text-plugin` (used by both
+// tsdown and vitest) loads `.md` / `.yaml` files as their string content.
+
+declare module '*.md' {
+  const content: string;
+  export default content;
+}
+
+declare module '*.yaml' {
+  const content: string;
+  export default content;
+}
diff --git a/packages/agent-core/src/providers/index.ts b/packages/agent-core/src/providers/index.ts
new file mode 100644
index 000000000..85cca4b1c
--- /dev/null
+++ b/packages/agent-core/src/providers/index.ts
@@ -0,0 +1,2 @@
+export * from './provider-manager';
+export * from './runtime-provider';
diff --git a/packages/agent-core/src/providers/provider-manager.ts b/packages/agent-core/src/providers/provider-manager.ts
new file mode 100644
index 000000000..7c2bc14f1
--- /dev/null
+++ b/packages/agent-core/src/providers/provider-manager.ts
@@ -0,0 +1,139 @@
+import type { KimiConfig } from '../config';
+import { ErrorCodes, KimiError } from '#/errors';
+import type { Logger } from '#/logging/types';
+import { resolveThinkingEffort, type ThinkingEffort } from '../agent/config/thinking';
+import {
+  createRuntimeProviderAuthResolver,
+  resolveRuntimeProvider,
+  resolveRuntimeProviderWithOAuth,
+  type OAuthTokenProviderResolver,
+  type ProviderRequestAuthResolver,
+  type ResolvedRuntimeProvider,
+} from './runtime-provider';
+
+export interface ProviderManagerOptions {
+  readonly config: KimiConfig;
+  readonly kimiRequestHeaders?: Record<string, string> | undefined;
+  readonly resolveOAuthTokenProvider?: OAuthTokenProviderResolver | undefined;
+  readonly promptCacheKey?: string;
+}
+
+export class ProviderManager {
+  private readonly state: ProviderManagerState;
+
+  constructor(
+    private readonly options: ProviderManagerOptions,
+    state?: ProviderManagerState,
+  ) {
+    this.state = state ?? { config: options.config };
+  }
+
+  get config(): KimiConfig {
+    return this.state.config;
+  }
+
+  get providers(): KimiConfig['providers'] {
+    return this.state.config.providers;
+  }
+
+  get models(): NonNullable<KimiConfig['models']> {
+    return this.state.config.models ?? {};
+  }
+
+  updateConfig(config: KimiConfig): void {
+    this.state.config = config;
+  }
+
+  withPromptCacheKey(promptCacheKey?: string): ProviderManager {
+    return new ProviderManager(
+      {
+        ...this.options,
+        config: this.state.config,
+        promptCacheKey,
+      },
+      this.state,
+    );
+  }
+
+  resolveProviderConfigForModel(
+    model: string | undefined,
+    options?: { readonly promptCacheKey?: string },
+  ): ResolvedRuntimeProvider | undefined {
+    const selectedModel = this.resolveSelectedModel(model);
+    if (selectedModel === undefined) return undefined;
+
+    return resolveRuntimeProvider({
+      config: this.state.config,
+      model: selectedModel,
+      kimiRequestHeaders: this.options.kimiRequestHeaders,
+      promptCacheKey: options?.promptCacheKey ?? this.options.promptCacheKey,
+      validateCredentials: false,
+    });
+  }
+
+  async resolveProviderForModel(
+    model: string | undefined,
+  ): Promise<ResolvedRuntimeProvider | undefined> {
+    const selectedModel = this.resolveSelectedModel(model);
+    if (selectedModel === undefined) return undefined;
+
+    return resolveRuntimeProviderWithOAuth({
+      config: this.state.config,
+      model: selectedModel,
+      kimiRequestHeaders: this.options.kimiRequestHeaders,
+      promptCacheKey: this.options.promptCacheKey,
+      resolveOAuthTokenProvider: this.options.resolveOAuthTokenProvider,
+    });
+  }
+
+  createAuthResolverForModel(
+    model: string | undefined,
+    options?: { readonly log?: Logger },
+  ): ProviderRequestAuthResolver | undefined {
+    const selectedModel = this.resolveSelectedModel(model);
+    if (selectedModel === undefined) return undefined;
+
+    const resolved = resolveRuntimeProvider({
+      config: this.state.config,
+      model: selectedModel,
+      kimiRequestHeaders: this.options.kimiRequestHeaders,
+      promptCacheKey: this.options.promptCacheKey,
+    });
+    return createRuntimeProviderAuthResolver(
+      {
+        config: this.state.config,
+        model: selectedModel,
+        kimiRequestHeaders: this.options.kimiRequestHeaders,
+        promptCacheKey: this.options.promptCacheKey,
+        resolveOAuthTokenProvider: this.options.resolveOAuthTokenProvider,
+        log: options?.log,
+      },
+      resolved,
+    );
+  }
+
+  resolveThinkingLevel(requestedThinking?: string): ThinkingEffort {
+    return resolveThinkingEffort(requestedThinking, this.state.config.thinking);
+  }
+
+  resolveSelectedModel(requestedModel: string | undefined): string | undefined {
+    if (requestedModel !== undefined) {
+      const normalized = normalizeString(requestedModel);
+      if (normalized === undefined) {
+        throw new KimiError(ErrorCodes.MODEL_CONFIG_INVALID, 'Runtime provider model cannot be empty');
+      }
+      return normalized;
+    }
+    return normalizeString(this.state.config.defaultModel);
+  }
+}
+
+interface ProviderManagerState {
+  config: KimiConfig;
+}
+
+function normalizeString(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
diff --git a/packages/agent-core/src/providers/request-auth.ts b/packages/agent-core/src/providers/request-auth.ts
new file mode 100644
index 000000000..31a032177
--- /dev/null
+++ b/packages/agent-core/src/providers/request-auth.ts
@@ -0,0 +1,46 @@
+import { APIStatusError, type ProviderRequestAuth } from '@moonshot-ai/kosong';
+
+import { ErrorCodes, KimiError } from '#/errors';
+
+export interface ProviderRequestAuthOptions {
+  readonly forceRefresh?: boolean;
+}
+
+export type ProviderRequestAuthResolver = (
+  options?: ProviderRequestAuthOptions,
+) => Promise<ProviderRequestAuth>;
+
+export async function withProviderRequestAuth<T>(
+  resolveAuth: ProviderRequestAuthResolver | undefined,
+  request: (auth: ProviderRequestAuth | undefined) => Promise<T>,
+): Promise<T> {
+  let auth = await resolveAuth?.();
+  for (let refreshed = false; ; refreshed = true) {
+    try {
+      return await request(auth);
+    } catch (error) {
+      if (
+        auth === undefined ||
+        !(error instanceof APIStatusError) ||
+        error.statusCode !== 401
+      ) {
+        throw error;
+      }
+      if (!refreshed && resolveAuth !== undefined) {
+        auth = await resolveAuth({ forceRefresh: true });
+        continue;
+      }
+      throw new KimiError(
+        ErrorCodes.AUTH_LOGIN_REQUIRED,
+        'OAuth provider credentials were rejected. Send /login to login.',
+        {
+          cause: error,
+          details: {
+            statusCode: error.statusCode,
+            requestId: error.requestId,
+          },
+        },
+      );
+    }
+  }
+}
diff --git a/packages/agent-core/src/providers/runtime-provider.ts b/packages/agent-core/src/providers/runtime-provider.ts
new file mode 100644
index 000000000..01abe39fe
--- /dev/null
+++ b/packages/agent-core/src/providers/runtime-provider.ts
@@ -0,0 +1,409 @@
+import type { KimiConfig, ModelAlias, OAuthRef, ProviderConfig } from '#/config';
+import { ErrorCodes, KimiError, isKimiError } from '#/errors';
+import { log as defaultLog } from '#/logging/logger';
+import type { Logger } from '#/logging/types';
+import {
+  createProvider,
+  UNKNOWN_CAPABILITY,
+  type ModelCapability,
+  type ProviderConfig as KosongProviderConfig,
+} from '@moonshot-ai/kosong';
+
+import type { ProviderRequestAuthResolver } from './request-auth';
+
+export type { ProviderRequestAuthResolver };
+
+export interface ResolveRuntimeProviderInput {
+  readonly config: KimiConfig;
+  readonly model?: string | undefined;
+  readonly kimiRequestHeaders?: Record<string, string> | undefined;
+  readonly promptCacheKey?: string;
+  readonly validateCredentials?: boolean;
+}
+
+export interface BearerTokenProvider {
+  getAccessToken(options?: { readonly force?: boolean | undefined }): Promise<string>;
+}
+
+export type OAuthTokenProviderResolver = (
+  providerName: string,
+  oauthRef?: OAuthRef | undefined,
+) => BearerTokenProvider | undefined;
+
+export interface ResolveRuntimeProviderWithOAuthInput extends ResolveRuntimeProviderInput {
+  readonly resolveOAuthTokenProvider?: OAuthTokenProviderResolver | undefined;
+  /**
+   * Caller-scoped logger (typically `agent.log`). Used to report OAuth token
+   * fetch failures so they land in the session log alongside the surrounding
+   * turn / tool call. Defaults to the global `log` when absent.
+   */
+  readonly log?: Logger;
+}
+
+export interface ResolvedRuntimeProvider {
+  readonly modelName: string;
+  readonly providerName?: string | undefined;
+  readonly provider: KosongProviderConfig;
+  readonly modelCapabilities: ModelCapability;
+  readonly resolveAuth?: ProviderRequestAuthResolver;
+}
+
+export function resolveRuntimeProvider(
+  input: ResolveRuntimeProviderInput,
+): ResolvedRuntimeProvider {
+  const modelName = input.model ?? input.config.defaultModel;
+  if (modelName === undefined) {
+    throw new KimiError(
+      ErrorCodes.CONFIG_INVALID,
+      'No model is selected. Set default_model in config.toml or pass a configured model alias.',
+    );
+  }
+
+  const alias = input.config.models?.[modelName];
+  if (alias === undefined) {
+    throw new KimiError(
+      ErrorCodes.CONFIG_INVALID,
+      `Model "${modelName}" is not configured in config.toml. Add a [models."${modelName}"] entry with max_context_size.`,
+    );
+  }
+
+  const resolvedModel = alias.model;
+  const providerName = alias.provider ?? input.config.defaultProvider;
+  const providerConfig =
+    providerName === undefined ? undefined : input.config.providers[providerName];
+
+  if (providerName === undefined) {
+    throw new KimiError(
+      ErrorCodes.CONFIG_INVALID,
+      `Model "${modelName}" must define a provider in config.toml.`,
+    );
+  }
+
+  if (providerConfig === undefined) {
+    throw new KimiError(
+      ErrorCodes.CONFIG_INVALID,
+      `Provider "${providerName}" for model "${modelName}" is not configured.`,
+    );
+  }
+
+  if (!Number.isInteger(alias.maxContextSize) || alias.maxContextSize <= 0) {
+    throw new KimiError(
+      ErrorCodes.CONFIG_INVALID,
+      `Model "${modelName}" must define a positive max_context_size in config.toml.`,
+    );
+  }
+
+  // Fail-fast when an operation explicitly selects/uses a runtime provider.
+  // Session creation only records the selected model name and does not need
+  // credential validation.
+  if (
+    input.validateCredentials !== false &&
+    providerConfig.type !== 'vertexai' &&
+    providerConfig.oauth === undefined &&
+    providerApiKey(providerConfig) === undefined
+  ) {
+    throw new KimiError(
+      ErrorCodes.CONFIG_INVALID,
+      `Provider "${providerName}" has no credentials configured. Set apiKey, oauth, or a provider env API key in config.toml.`,
+    );
+  }
+
+  const provider = toKosongProviderConfig(
+    providerConfig,
+    resolvedModel,
+    input.kimiRequestHeaders,
+    alias.maxOutputSize,
+    input.promptCacheKey,
+  );
+  const modelCapabilities = resolveModelCapabilities(alias, provider);
+
+  return {
+    modelName,
+    providerName,
+    modelCapabilities,
+    provider,
+  };
+}
+
+export async function resolveRuntimeProviderWithOAuth(
+  input: ResolveRuntimeProviderWithOAuthInput,
+): Promise<ResolvedRuntimeProvider> {
+  const resolved = resolveRuntimeProvider(input);
+  const resolveAuth = createRuntimeProviderAuthResolver(input, resolved);
+  if (resolveAuth === undefined) return resolved;
+
+  // Validate login eagerly, preserving existing setModel
+  // behavior, but do not store the short-lived token in provider config.
+  await resolveAuth();
+  return {
+    ...resolved,
+    resolveAuth,
+  };
+}
+
+export function createRuntimeProviderAuthResolver(
+  input: ResolveRuntimeProviderWithOAuthInput,
+  resolved: ResolvedRuntimeProvider = resolveRuntimeProvider(input),
+): ProviderRequestAuthResolver | undefined {
+  const providerName = resolved.providerName;
+  if (providerName === undefined) return undefined;
+
+  const providerConfig = input.config.providers[providerName];
+  if (providerConfig?.oauth === undefined) return undefined;
+  if (providerApiKey(providerConfig) !== undefined) {
+    // oauth + apiKey on the same provider makes request auth ambiguous:
+    // provider construction would prefer apiKey while runtime auth resolves
+    // OAuth. Reject it so misconfiguration surfaces at model resolution.
+    throw new KimiError(
+      ErrorCodes.CONFIG_INVALID,
+      `Provider "${providerName}" has both apiKey and oauth set in config.toml — they are mutually exclusive. Remove one.`,
+    );
+  }
+
+  const tokenProvider = input.resolveOAuthTokenProvider?.(providerName, providerConfig.oauth);
+  if (tokenProvider === undefined) {
+    return async () => {
+      throw new KimiError(
+        ErrorCodes.AUTH_LOGIN_REQUIRED,
+        `OAuth provider "${providerName}" requires login before it can be used.`,
+      );
+    };
+  }
+
+  return async (options) => {
+    let apiKey: string;
+    try {
+      apiKey = await tokenProvider.getAccessToken(
+        options?.forceRefresh === true ? { force: true } : undefined,
+      );
+    } catch (error) {
+      if (!isAuthLoginRequired(error)) {
+        (input.log ?? defaultLog).warn('oauth token fetch failed', { providerName, error });
+      }
+      throw new KimiError(
+        ErrorCodes.AUTH_LOGIN_REQUIRED,
+        `OAuth provider "${providerName}" requires login before it can be used.`,
+        {
+          cause: error,
+        },
+      );
+    }
+    if (apiKey.trim().length === 0) {
+      throw new KimiError(
+        ErrorCodes.AUTH_LOGIN_REQUIRED,
+        `OAuth provider "${providerName}" requires login before it can be used.`,
+      );
+    }
+    return { apiKey };
+  };
+}
+
+function isAuthLoginRequired(error: unknown): boolean {
+  return isKimiError(error) && error.code === ErrorCodes.AUTH_LOGIN_REQUIRED;
+}
+
+function resolveModelCapabilities(
+  alias: ModelAlias & { maxContextSize: number },
+  provider: KosongProviderConfig,
+): ModelCapability {
+  const capabilities = new Set(
+    (alias.capabilities ?? []).map((capability) => capability.trim().toLowerCase()),
+  );
+  const has = (capability: string): boolean => capabilities.has(capability);
+  const capabilityProvider = createProvider(providerForCapabilityProbe(provider));
+  const providerCapability =
+    capabilityProvider.getCapability?.(provider.model) ?? UNKNOWN_CAPABILITY;
+
+  return {
+    image_in: has('image_in') || providerCapability.image_in,
+    video_in: has('video_in') || providerCapability.video_in,
+    audio_in: has('audio_in') || providerCapability.audio_in,
+    thinking: has('thinking') || has('always_thinking') || providerCapability.thinking,
+    tool_use: has('tool_use') || providerCapability.tool_use,
+    max_context_tokens: alias.maxContextSize,
+  };
+}
+
+function toKosongProviderConfig(
+  provider: ProviderConfig,
+  model: string,
+  kimiRequestHeaders?: Record<string, string> | undefined,
+  maxOutputSize?: number | undefined,
+  promptCacheKey?: string,
+): KosongProviderConfig {
+  switch (provider.type) {
+    case 'anthropic':
+      return {
+        type: 'anthropic',
+        model,
+        baseUrl: providerValue(provider.baseUrl, provider.env, 'ANTHROPIC_BASE_URL'),
+        apiKey: providerApiKey(provider),
+        ...(maxOutputSize !== undefined ? { defaultMaxTokens: maxOutputSize } : {}),
+        ...defaultHeadersField(provider.customHeaders),
+      };
+    case 'openai':
+      return {
+        type: 'openai',
+        model,
+        baseUrl: providerValue(provider.baseUrl, provider.env, 'OPENAI_BASE_URL'),
+        apiKey: providerApiKey(provider),
+        ...defaultHeadersField(provider.customHeaders),
+      };
+    case 'kimi': {
+      const defaultHeaders = {
+        ...kimiRequestHeaders,
+        ...provider.customHeaders,
+      };
+      if (Object.keys(defaultHeaders).length === 0) {
+        return {
+          type: 'kimi',
+          model,
+          baseUrl: providerValue(provider.baseUrl, provider.env, 'KIMI_BASE_URL'),
+          generationKwargs: {
+            prompt_cache_key: promptCacheKey,
+          },
+          apiKey: providerApiKey(provider),
+        };
+      }
+      return {
+        type: 'kimi',
+        model,
+        baseUrl: providerValue(provider.baseUrl, provider.env, 'KIMI_BASE_URL'),
+        generationKwargs: {
+          prompt_cache_key: promptCacheKey,
+        },
+        defaultHeaders,
+        apiKey: providerApiKey(provider),
+      };
+    }
+    case 'google-genai':
+      return {
+        type: 'google-genai',
+        model,
+        apiKey: providerApiKey(provider),
+      };
+    case 'openai_responses':
+      return {
+        type: 'openai_responses',
+        model,
+        baseUrl: providerValue(provider.baseUrl, provider.env, 'OPENAI_BASE_URL'),
+        apiKey: providerApiKey(provider),
+        ...defaultHeadersField(provider.customHeaders),
+      };
+    case 'vertexai':
+      return {
+        type: 'vertexai',
+        model,
+        vertexai: hasVertexAIServiceEnv(provider),
+        apiKey: hasVertexAIServiceEnv(provider) ? undefined : providerApiKey(provider),
+        project: vertexAIProject(provider),
+        location: vertexAILocation(provider),
+      };
+    default: {
+      const exhaustive: never = provider.type;
+      throw new KimiError(
+        ErrorCodes.MODEL_CONFIG_INVALID,
+        `Unsupported provider type: ${String(exhaustive)}`,
+      );
+    }
+  }
+}
+
+// Spread-ready `defaultHeaders` field for a kosong provider config. Returns a
+// fresh copy so resolved provider instances never share a header object, and
+// omits the key entirely when there are no headers (callers and tests rely on
+// `'defaultHeaders' in provider`).
+function defaultHeadersField(
+  headers: Record<string, string> | undefined,
+): { defaultHeaders?: Record<string, string> } {
+  if (headers === undefined || Object.keys(headers).length === 0) return {};
+  return { defaultHeaders: { ...headers } };
+}
+
+function providerForCapabilityProbe(provider: KosongProviderConfig): KosongProviderConfig {
+  if (provider.type === 'vertexai') {
+    return {
+      ...provider,
+      vertexai: false,
+      project: undefined,
+      location: undefined,
+      apiKey:
+        provider.apiKey === undefined || provider.apiKey.length === 0
+          ? 'capability-probe'
+          : provider.apiKey,
+    };
+  }
+  if (provider.apiKey !== undefined && provider.apiKey.length > 0) return provider;
+  return { ...provider, apiKey: 'capability-probe' };
+}
+
+function providerApiKey(provider: ProviderConfig): string | undefined {
+  switch (provider.type) {
+    case 'anthropic':
+      return providerValue(provider.apiKey, provider.env, 'ANTHROPIC_API_KEY');
+    case 'openai':
+    case 'openai_responses':
+      return providerValue(provider.apiKey, provider.env, 'OPENAI_API_KEY');
+    case 'kimi':
+      return providerValue(provider.apiKey, provider.env, 'KIMI_API_KEY');
+    case 'google-genai':
+      return providerValue(provider.apiKey, provider.env, 'GOOGLE_API_KEY');
+    case 'vertexai':
+      return (
+        nonEmptyString(provider.apiKey) ??
+        envValue(provider.env, 'VERTEXAI_API_KEY') ??
+        envValue(provider.env, 'GOOGLE_API_KEY')
+      );
+    default: {
+      const exhaustive: never = provider.type;
+      throw new KimiError(
+        ErrorCodes.MODEL_CONFIG_INVALID,
+        `Unsupported provider type: ${String(exhaustive)}`,
+      );
+    }
+  }
+}
+
+function hasVertexAIServiceEnv(provider: ProviderConfig): boolean {
+  return vertexAIProject(provider) !== undefined && vertexAILocation(provider) !== undefined;
+}
+
+function vertexAIProject(provider: ProviderConfig): string | undefined {
+  return envValue(provider.env, 'GOOGLE_CLOUD_PROJECT');
+}
+
+function vertexAILocation(provider: ProviderConfig): string | undefined {
+  return (
+    envValue(provider.env, 'GOOGLE_CLOUD_LOCATION') ??
+    locationFromVertexAIBaseUrl(provider.baseUrl)
+  );
+}
+
+function providerValue(
+  configured: string | undefined,
+  env: Record<string, string> | undefined,
+  envKey: string,
+): string | undefined {
+  return nonEmptyString(configured) ?? envValue(env, envKey);
+}
+
+function envValue(env: Record<string, string> | undefined, key: string): string | undefined {
+  return nonEmptyString(env?.[key]);
+}
+
+function nonEmptyString(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;
+}
+
+function locationFromVertexAIBaseUrl(baseUrl: string | undefined): string | undefined {
+  const url = nonEmptyString(baseUrl);
+  if (url === undefined) return undefined;
+  try {
+    const host = new URL(url).hostname;
+    const suffix = '-aiplatform.googleapis.com';
+    return host.endsWith(suffix) ? nonEmptyString(host.slice(0, -suffix.length)) : undefined;
+  } catch {
+    return undefined;
+  }
+}
diff --git a/packages/agent-core/src/rpc/client.ts b/packages/agent-core/src/rpc/client.ts
new file mode 100644
index 000000000..d50cb5f3f
--- /dev/null
+++ b/packages/agent-core/src/rpc/client.ts
@@ -0,0 +1,108 @@
+import type { PromisableMethods, Promisify } from '#/utils/types';
+import { createControlledPromise, objectMap } from '@antfu/utils';
+
+import {
+  fromKimiErrorPayload,
+  type KimiErrorPayload,
+  toKimiErrorPayload,
+} from '../errors';
+import { abortable } from '../utils/abort';
+import type { CoreAPI } from './core-api';
+import type { SDKAPI } from './sdk-api';
+
+export interface RPCCallOptions {
+  signal?: AbortSignal;
+}
+
+type RpcResponse =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly error: KimiErrorPayload };
+
+export type RPCMethods<T> = {
+  [K in keyof T]: T[K] extends (payload: infer Payload) => infer Return
+    ? (payload: Payload, options?: RPCCallOptions) => Promisify<Return>
+    : never;
+};
+
+export type RPCClient<Self extends Record<string, any>, Other extends Record<string, any>> = (
+  self: PromisableMethods<Self>,
+) => Promise<RPCMethods<Other>>;
+
+export function createRPC<Left extends Record<string, any>, Right extends Record<string, any>>(): [
+  RPCClient<Left, Right>,
+  RPCClient<Right, Left>,
+] {
+  const left = createControlledPromise<PromisableMethods<Left>>();
+  const right = createControlledPromise<PromisableMethods<Right>>();
+
+  function simulateNetwork<T>(data: T): Promise<T> {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        const serialized = JSON.stringify(data);
+        resolve(serialized === undefined ? (undefined as T) : JSON.parse(serialized));
+      }, 0);
+    });
+  }
+
+  function abortableRpc<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+    return signal === undefined ? promise : abortable(promise, signal);
+  }
+
+  function mapRpcFunction(fn: Function): Function {
+    return async (payload: any, options?: RPCCallOptions) => {
+      const signal = options?.signal;
+      const rpcPayload = await simulateNetwork(payload);
+      signal?.throwIfAborted();
+      let response: RpcResponse;
+      try {
+        const value = await abortableRpc(Promise.resolve(fn(rpcPayload)), signal);
+        response = { ok: true, value };
+      } catch (error) {
+        signal?.throwIfAborted();
+        response = { ok: false, error: toKimiErrorPayload(error) };
+      }
+      const remoteResponse = await simulateNetwork(response);
+      if (remoteResponse.ok) return remoteResponse.value;
+      throw fromKimiErrorPayload(remoteResponse.error);
+    };
+  }
+
+  function bindAllFunctions<T extends Record<string, any>>(obj: T): T {
+    const bound: Record<string, unknown> = {};
+    let current: object | null = obj;
+
+    while (current !== null && current !== Object.prototype) {
+      for (const key of Object.getOwnPropertyNames(current)) {
+        if (key === 'constructor' || Object.hasOwn(bound, key)) {
+          continue;
+        }
+
+        const descriptor = Object.getOwnPropertyDescriptor(current, key);
+        if (typeof descriptor?.value === 'function') {
+          bound[key] = descriptor.value.bind(obj);
+        }
+      }
+
+      current = Object.getPrototypeOf(current);
+    }
+
+    return bound as T;
+  }
+
+  async function leftClient(self: PromisableMethods<Left>): Promise<RPCMethods<Right>> {
+    left.resolve(bindAllFunctions(self));
+    return objectMap(await right, (key, fn) => [key, mapRpcFunction(fn)]) as RPCMethods<Right>;
+  }
+
+  async function rightClient(self: PromisableMethods<Right>): Promise<RPCMethods<Left>> {
+    right.resolve(bindAllFunctions(self));
+    return objectMap(await left, (key, fn) => [key, mapRpcFunction(fn)]) as RPCMethods<Left>;
+  }
+
+  return [leftClient, rightClient];
+}
+
+export type CoreRPCClient = RPCClient<CoreAPI, SDKAPI>;
+export type SDKRPCClient = RPCClient<SDKAPI, CoreAPI>;
+
+export type CoreRPC = RPCMethods<CoreAPI>;
diff --git a/packages/agent-core/src/rpc/core-api.ts b/packages/agent-core/src/rpc/core-api.ts
new file mode 100644
index 000000000..8b80597d7
--- /dev/null
+++ b/packages/agent-core/src/rpc/core-api.ts
@@ -0,0 +1,273 @@
+import type { AgentConfigData } from '#/agent/config';
+import type { AgentContextData } from '#/agent/context';
+import type { PermissionData, PermissionMode } from '#/agent/permission';
+import type { PlanData } from '#/agent/plan';
+import type { ToolInfo } from '#/agent/tool';
+import type { KimiConfig, KimiConfigPatch } from '#/config';
+import type { ResumeSessionResult } from '#/rpc/resumed';
+import type { SessionMeta } from '#/session';
+import type { BackgroundTaskInfo } from '#/tools/builtin';
+import type { ContentPart } from '@moonshot-ai/kosong';
+
+import type { UsageStatus } from './events';
+import type { WithAgentId, WithSessionId } from './types';
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { readonly [key: string]: JsonValue };
+export type JsonObject = { readonly [key: string]: JsonValue };
+
+export type Unsubscribe = () => void;
+
+export type { KimiConfig, KimiConfigPatch };
+
+export type TextPromptPart = Extract<ContentPart, { type: 'text' }>;
+export type PromptPart = Extract<ContentPart, { type: 'text' | 'image_url' | 'video_url' }>;
+
+export type PromptInput = readonly PromptPart[];
+
+export type EmptyPayload = {};
+export type SessionMetadataPatch = Partial<Omit<SessionMeta, 'agents'>>;
+
+export interface CreateSessionPayload {
+  readonly id?: string | undefined;
+  readonly workDir: string;
+  readonly model?: string | undefined;
+  readonly thinking?: string | undefined;
+  readonly permission?: PermissionMode | undefined;
+  readonly metadata?: JsonObject | undefined;
+}
+
+export interface CloseSessionPayload {
+  readonly sessionId: string;
+}
+
+export interface ResumeSessionPayload {
+  readonly sessionId: string;
+}
+
+export interface ForkSessionPayload {
+  readonly sessionId: string;
+  readonly id?: string;
+  readonly title?: string;
+  readonly metadata?: JsonObject;
+}
+
+export interface ExportSessionPayload {
+  readonly sessionId: string;
+  readonly outputPath?: string | undefined;
+  /**
+   * When true, the active global diagnostic log (`$KIMI_CODE_HOME/logs/kimi-code.log`)
+   * is copied into the zip at `logs/global/kimi-code.log`. Off by default to
+   * avoid bundling events from concurrent sessions / other projects.
+   */
+  readonly includeGlobalLog?: boolean | undefined;
+  /** Host version to record in the export manifest. */
+  readonly version: string;
+}
+
+export interface ExportSessionManifest {
+  readonly sessionId: string;
+  readonly exportedAt: string;
+  readonly kimiCodeVersion: string;
+  readonly wireProtocolVersion: string;
+  readonly os: string;
+  readonly nodejsVersion: string;
+  readonly sessionFirstActivity?: string | undefined;
+  readonly sessionLastActivity?: string | undefined;
+  readonly title?: string | undefined;
+  readonly workspaceDir?: string | undefined;
+  /** zip-relative path to the session diagnostic log when present. */
+  readonly sessionLogPath?: string | undefined;
+  /** zip-relative path to the bundled global diagnostic log (only when --include-global-log). */
+  readonly globalLogPath?: string | undefined;
+}
+
+export interface ExportSessionResult {
+  readonly zipPath: string;
+  readonly entries: readonly string[];
+  readonly sessionDir: string;
+  readonly manifest: ExportSessionManifest;
+}
+
+export interface ListSessionsPayload {
+  readonly workDir: string;
+}
+
+export interface CoreInfo {
+  readonly version: string;
+}
+
+export interface SessionSummary {
+  readonly id: string;
+  readonly title?: string | undefined;
+  readonly lastPrompt?: string;
+  readonly workDir: string;
+  readonly sessionDir: string;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+  readonly archived?: boolean | undefined;
+  readonly metadata?: JsonObject | undefined;
+}
+
+export interface PromptPayload {
+  readonly input: readonly ContentPart[];
+}
+export interface SteerPayload {
+  readonly input: readonly ContentPart[];
+}
+export interface CancelPayload {
+  readonly turnId?: number;
+}
+export interface SetThinkingPayload {
+  readonly level: string;
+}
+export interface SetPermissionPayload {
+  readonly mode: PermissionMode;
+}
+export interface SetModelPayload {
+  readonly model: string;
+}
+export interface SetModelResult {
+  readonly model: string;
+  readonly providerName?: string | undefined;
+}
+export interface CancelPlanPayload {
+  readonly id?: string;
+}
+export interface BeginCompactionPayload {
+  readonly instruction?: string;
+}
+export interface RegisterToolPayload {
+  readonly name: string;
+  readonly description: string;
+  readonly parameters: Record<string, unknown>;
+}
+export interface UnregisterToolPayload {
+  readonly name: string;
+}
+export interface SetActiveToolsPayload {
+  readonly names: readonly string[];
+}
+export interface StopBackgroundPayload {
+  readonly taskId: string;
+  /** Free-form human-readable reason persisted with the task record. */
+  readonly reason?: string;
+}
+export interface GetBackgroundOutputPayload {
+  readonly taskId: string;
+  readonly tail?: number;
+}
+export interface GetBackgroundOutputPathPayload {
+  readonly taskId: string;
+}
+export interface GetBackgroundPayload {
+  /**
+   * When omitted, returns all tasks (including terminal/lost). Pass
+   * `true` to filter down to active-only — useful for model-facing
+   * surfaces. UI/TUI consumers should leave it undefined.
+   */
+  readonly activeOnly?: boolean;
+  /** Caps the number of tasks returned. When omitted, returns all matching tasks. */
+  readonly limit?: number;
+}
+export interface SkillSummary {
+  readonly name: string;
+  readonly description: string;
+  readonly path: string;
+  readonly source: 'builtin' | 'user' | 'extra' | 'project';
+  readonly type?: string | undefined;
+  readonly disableModelInvocation?: boolean | undefined;
+}
+
+export interface ActivateSkillPayload {
+  readonly name: string;
+  readonly args?: string | undefined;
+}
+
+export interface McpServerInfo {
+  readonly name: string;
+  readonly transport: 'stdio' | 'http';
+  readonly status: 'pending' | 'connected' | 'failed' | 'disabled' | 'needs-auth';
+  readonly toolCount: number;
+  readonly error?: string;
+}
+
+export interface McpStartupMetrics {
+  readonly durationMs: number;
+}
+
+export interface ReconnectMcpServerPayload {
+  readonly name: string;
+}
+
+export interface RenameSessionPayload {
+  readonly title: string;
+}
+
+export interface UpdateSessionMetadataPayload {
+  readonly metadata: SessionMetadataPatch;
+}
+
+export type SetKimiConfigPayload = KimiConfigPatch;
+
+export interface RemoveKimiProviderPayload {
+  readonly providerId: string;
+}
+
+export interface AgentAPI {
+  prompt: (payload: PromptPayload) => void;
+  steer: (payload: SteerPayload) => void;
+  cancel: (payload: CancelPayload) => void;
+  setThinking: (payload: SetThinkingPayload) => void;
+  setPermission: (payload: SetPermissionPayload) => void;
+  setModel: (payload: SetModelPayload) => SetModelResult;
+  getModel: (payload: EmptyPayload) => string;
+  enterPlan: (payload: EmptyPayload) => void;
+  cancelPlan: (payload: CancelPlanPayload) => void;
+  clearPlan: (payload: EmptyPayload) => void;
+  beginCompaction: (payload: BeginCompactionPayload) => void;
+  cancelCompaction: (payload: EmptyPayload) => void;
+  registerTool: (payload: RegisterToolPayload) => void;
+  unregisterTool: (payload: UnregisterToolPayload) => void;
+  setActiveTools: (payload: SetActiveToolsPayload) => void;
+  stopBackground: (payload: StopBackgroundPayload) => void;
+  clearContext: (payload: EmptyPayload) => void;
+  activateSkill: (payload: ActivateSkillPayload) => void;
+  getBackgroundOutput: (payload: GetBackgroundOutputPayload) => string;
+  getBackgroundOutputPath: (payload: GetBackgroundOutputPathPayload) => string | undefined;
+  getContext: (payload: EmptyPayload) => AgentContextData;
+  getConfig: (payload: EmptyPayload) => AgentConfigData;
+  getPermission: (payload: EmptyPayload) => PermissionData;
+  getPlan: (payload: EmptyPayload) => PlanData;
+  getUsage: (payload: EmptyPayload) => UsageStatus;
+  getTools: (payload: EmptyPayload) => readonly ToolInfo[];
+  getBackground: (payload: GetBackgroundPayload) => readonly BackgroundTaskInfo[];
+}
+
+type AgentAPIWithId = WithAgentId<AgentAPI>;
+
+export interface SessionAPI extends AgentAPIWithId {
+  renameSession: (payload: RenameSessionPayload) => void;
+  updateSessionMetadata: (payload: UpdateSessionMetadataPayload) => void;
+  getSessionMetadata: (payload: EmptyPayload) => SessionMeta;
+  listSkills: (payload: EmptyPayload) => readonly SkillSummary[];
+  listMcpServers: (payload: EmptyPayload) => readonly McpServerInfo[];
+  getMcpStartupMetrics: (payload: EmptyPayload) => McpStartupMetrics;
+  reconnectMcpServer: (payload: ReconnectMcpServerPayload) => void;
+  generateAgentsMd: (payload: EmptyPayload) => void;
+}
+
+type SessionAPIWithId = WithSessionId<SessionAPI>;
+
+export interface CoreAPI extends SessionAPIWithId {
+  getCoreInfo: (payload: EmptyPayload) => CoreInfo;
+  getKimiConfig: (payload: EmptyPayload) => KimiConfig;
+  setKimiConfig: (payload: SetKimiConfigPayload) => KimiConfig;
+  removeKimiProvider: (payload: RemoveKimiProviderPayload) => KimiConfig;
+  createSession: (payload: CreateSessionPayload) => SessionSummary;
+  closeSession: (payload: CloseSessionPayload) => void;
+  resumeSession: (payload: ResumeSessionPayload) => ResumeSessionResult;
+  forkSession: (payload: ForkSessionPayload) => ResumeSessionResult;
+  listSessions: (payload: ListSessionsPayload) => readonly SessionSummary[];
+  exportSession: (payload: ExportSessionPayload) => ExportSessionResult;
+}
diff --git a/packages/agent-core/src/rpc/core-impl.ts b/packages/agent-core/src/rpc/core-impl.ts
new file mode 100644
index 000000000..189ae276d
--- /dev/null
+++ b/packages/agent-core/src/rpc/core-impl.ts
@@ -0,0 +1,739 @@
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+
+import { localKaos } from '@moonshot-ai/kaos';
+import { ErrorCodes, KimiError } from '#/errors';
+import { getRootLogger, log } from '#/logging/logger';
+import { LocalFetchURLProvider } from '#/tools/providers/local-fetch-url';
+import { MoonshotFetchURLProvider } from '#/tools/providers/moonshot-fetch-url';
+import { MoonshotWebSearchProvider } from '#/tools/providers/moonshot-web-search';
+import { detectEnvironmentFromNode } from '#/utils/environment';
+import { getCoreVersion } from '#/version';
+import type {
+  ActivateSkillPayload,
+  BeginCompactionPayload,
+  CancelPayload,
+  CancelPlanPayload,
+  CloseSessionPayload,
+  CoreAPI,
+  CoreInfo,
+  CreateSessionPayload,
+  EmptyPayload,
+  ExportSessionPayload,
+  ExportSessionResult,
+  ForkSessionPayload,
+  GetBackgroundOutputPathPayload,
+  GetBackgroundOutputPayload,
+  GetBackgroundPayload,
+  ListSessionsPayload,
+  McpServerInfo,
+  McpStartupMetrics,
+  PromptPayload,
+  ReconnectMcpServerPayload,
+  RemoveKimiProviderPayload,
+  RenameSessionPayload,
+  ResumeSessionPayload,
+  RegisterToolPayload,
+  SetKimiConfigPayload,
+  SetActiveToolsPayload,
+  SetModelPayload,
+  SetModelResult,
+  SetPermissionPayload,
+  SetThinkingPayload,
+  SkillSummary,
+  SteerPayload,
+  StopBackgroundPayload,
+  SessionSummary,
+  UnregisterToolPayload,
+  UpdateSessionMetadataPayload,
+} from './core-api';
+import type { CoreRPCClient } from './client';
+import type { ResumedAgentState, ResumeSessionResult } from './resumed';
+import type { SDKRPC } from './sdk-api';
+import { proxyWithExtraPayload } from './types';
+import type { PromisableMethods } from '#/utils/types';
+
+import { resolveSessionMcpConfig } from '../mcp';
+import { Session, type SessionMeta, type SessionSkillConfig } from '../session';
+import { SessionAPIImpl } from '../session/rpc';
+import {
+  ensureKimiHome,
+  mergeConfigPatch,
+  readConfigFile,
+  resolveConfigPath,
+  resolveKimiHome,
+  writeConfigFile,
+  type KimiConfig,
+  type MoonshotServiceConfig,
+} from '../config';
+import { exportSessionDirectory } from '../session/export';
+import { ProviderManager } from '../providers/provider-manager';
+import {
+  type BearerTokenProvider,
+  type OAuthTokenProviderResolver,
+} from '../providers/runtime-provider';
+import type { Logger } from '../logging/types';
+import type { RuntimeConfig } from '../runtime-types';
+import { normalizeWorkDir, SessionStore } from '../session/store';
+import { noopTelemetryClient, withTelemetryContext, type TelemetryClient } from '../telemetry';
+
+const KIMI_CODE_PROVIDER_NAME = 'managed:kimi-code';
+
+type AgentScopedPayload<T> = T & { readonly agentId: string };
+type SessionScopedPayload<T> = T & { readonly sessionId: string };
+type SessionAgentPayload<T> = SessionScopedPayload<AgentScopedPayload<T>>;
+type RenameSessionRequest = SessionScopedPayload<RenameSessionPayload>;
+type UpdateSessionMetadataRequest = SessionScopedPayload<UpdateSessionMetadataPayload>;
+
+export interface KimiCoreOptions {
+  readonly homeDir?: string | undefined;
+  readonly configPath?: string | undefined;
+  readonly runtime?: RuntimeConfig | undefined;
+  readonly kimiRequestHeaders?: Record<string, string> | undefined;
+  readonly resolveOAuthTokenProvider?: OAuthTokenProviderResolver | undefined;
+  readonly skillDirs?: readonly string[];
+  readonly telemetry?: TelemetryClient | undefined;
+}
+
+export class KimiCore implements PromisableMethods<CoreAPI> {
+  readonly sdk: Promise<SDKRPC>;
+  readonly homeDir: string;
+  readonly configPath: string;
+  readonly sessions = new Map<string, Session>();
+  readonly telemetry: TelemetryClient;
+
+  private runtime: RuntimeConfig | undefined;
+  private readonly userHomeDir: string;
+  private readonly kimiRequestHeaders: Record<string, string> | undefined;
+  private readonly resolveOAuthTokenProvider: OAuthTokenProviderResolver | undefined;
+  private readonly skillDirs: readonly string[];
+  private readonly providerManager: ProviderManager;
+  private readonly sessionStore: SessionStore;
+
+  constructor(
+    protected readonly rpcClient: CoreRPCClient,
+    options: KimiCoreOptions = {},
+  ) {
+    const explicitHomeDir = options.homeDir ?? process.env['KIMI_CODE_HOME'];
+    this.homeDir = resolveKimiHome(options.homeDir);
+    this.userHomeDir = explicitHomeDir ?? homedir();
+    this.configPath = resolveConfigPath({
+      homeDir: this.homeDir,
+      configPath: options.configPath,
+    });
+    this.runtime = options.runtime;
+    this.kimiRequestHeaders = options.kimiRequestHeaders;
+    this.resolveOAuthTokenProvider = options.resolveOAuthTokenProvider;
+    this.skillDirs = options.skillDirs ?? [];
+    this.telemetry = options.telemetry ?? noopTelemetryClient;
+    ensureKimiHome(this.homeDir);
+    this.providerManager = new ProviderManager({
+      config: readConfigFile(this.configPath),
+      kimiRequestHeaders: this.kimiRequestHeaders,
+      resolveOAuthTokenProvider: this.resolveOAuthTokenProvider,
+    });
+    this.sessionStore = new SessionStore(this.homeDir);
+
+    this.sdk = rpcClient(this);
+  }
+
+  async createSession(input: CreateSessionPayload): Promise<SessionSummary> {
+    const options = input;
+    const workDir = requiredWorkDir('createSession', options.workDir);
+    const config = this.reloadProviderManager();
+    const id = options.id ?? createSessionId();
+    const modelName = this.providerManager.resolveSelectedModel(options.model);
+    const thinkingLevel = this.providerManager.resolveThinkingLevel(options.thinking);
+    const permissionMode = options.permission ?? config.defaultPermissionMode;
+    const mcpConfig = await resolveSessionMcpConfig({
+      cwd: workDir,
+      homeDir: this.homeDir,
+    });
+    const summary = await this.sessionStore.create({
+      id,
+      workDir,
+    });
+    const result: SessionSummary = {
+      ...summary,
+      metadata: options.metadata,
+    };
+
+    // Session ctor attaches its own log sink. If anything in the setup-after-
+    // ctor block throws, `session.close()` releases the sink (and mcp).
+    const session = new Session({
+      runtime: await this.resolveRuntime(config),
+      id,
+      homedir: summary.sessionDir,
+      kimiHomeDir: this.homeDir,
+      rpc: proxyWithExtraPayload(await this.sdk, { sessionId: summary.id }),
+      cwd: workDir,
+      providerManager: this.providerManager,
+      background: config.background,
+      hooks: config.hooks,
+      permissionRules: config.permission?.rules,
+      skills: this.resolveSessionSkillConfig(config),
+      mcpConfig,
+      telemetry: withTelemetryContext(this.telemetry, { sessionId: summary.id }),
+    });
+    try {
+      session.metadata = {
+        ...session.metadata,
+        createdAt: new Date(summary.createdAt).toISOString(),
+        updatedAt: new Date(summary.updatedAt).toISOString(),
+        ...(summary.title !== undefined
+          ? {
+              title: summary.title,
+              isCustomTitle: true,
+            }
+          : {}),
+        custom: options.metadata === undefined ? {} : { ...options.metadata },
+      };
+      const mainAgent = await session.createMain();
+      mainAgent.config.update({
+        cwd: workDir,
+        modelAlias: modelName,
+        thinkingLevel,
+      });
+      if (permissionMode !== undefined) {
+        mainAgent.permission.setMode(permissionMode);
+      }
+      // Honor config.defaultPlanMode for fresh sessions. Resumed sessions
+      // restore their own plan state from records and never re-apply this.
+      if (config.defaultPlanMode === true) {
+        await mainAgent.planMode.enter();
+      }
+      await session.writeMetadata();
+      await session.flushMetadata();
+    } catch (error) {
+      await session.close().catch(() => {});
+      throw error;
+    }
+    this.sessions.set(id, session);
+    return result;
+  }
+
+  getCoreInfo(): CoreInfo {
+    return { version: getCoreVersion() };
+  }
+
+  async closeSession({ sessionId }: CloseSessionPayload): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      await session.close();
+      this.sessions.delete(sessionId);
+    }
+  }
+
+  async resumeSession(input: ResumeSessionPayload): Promise<ResumeSessionResult> {
+    const summary = await this.sessionStore.get(input.sessionId);
+    const active = this.sessions.get(summary.id);
+    if (active !== undefined) {
+      return resumeSessionResult(summary, active);
+    }
+
+    const config = this.reloadProviderManager();
+    const mcpConfig = await resolveSessionMcpConfig({
+      cwd: summary.workDir,
+      homeDir: this.homeDir,
+    });
+    const session = new Session({
+      runtime: await this.resolveRuntime(config),
+      id: summary.id,
+      homedir: summary.sessionDir,
+      kimiHomeDir: this.homeDir,
+      rpc: proxyWithExtraPayload(await this.sdk, { sessionId: summary.id }),
+      cwd: summary.workDir,
+      providerManager: this.providerManager,
+      background: config.background,
+      hooks: config.hooks,
+      permissionRules: config.permission?.rules,
+      skills: this.resolveSessionSkillConfig(config),
+      mcpConfig,
+      telemetry: withTelemetryContext(this.telemetry, { sessionId: summary.id }),
+      initializeMainAgent: false,
+    });
+    try {
+      await session.resume();
+      await this.refreshSessionRuntimeConfig(session, config);
+    } catch (error) {
+      await session.close().catch(() => {});
+      withTelemetryContext(this.telemetry, { sessionId: summary.id }).track('session_load_failed', {
+        reason: telemetryErrorReason(error),
+      });
+      throw error;
+    }
+    this.sessions.set(summary.id, session);
+    return resumeSessionResult(summary, session);
+  }
+
+  async forkSession(input: ForkSessionPayload): Promise<ResumeSessionResult> {
+    const source = await this.sessionStore.get(input.sessionId);
+    const active = this.sessions.get(source.id);
+    if (active !== undefined) {
+      await active.flushMetadata();
+    }
+
+    const id = input.id ?? createSessionId();
+    await this.sessionStore.fork({
+      sourceId: source.id,
+      targetId: id,
+      title: input.title,
+      metadata: input.metadata,
+    });
+    return this.resumeSession({ sessionId: id });
+  }
+
+  async listSessions(input: ListSessionsPayload): Promise<readonly SessionSummary[]> {
+    const options = input;
+    return this.sessionStore.list({
+      ...options,
+      workDir: requiredWorkDir('listSessions', options.workDir),
+    });
+  }
+
+  async renameSession({ sessionId, ...payload }: RenameSessionRequest): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (session !== undefined) {
+      await new SessionAPIImpl(session).renameSession(payload);
+      return;
+    }
+    await this.sessionStore.rename(sessionId, payload.title);
+  }
+
+  async exportSession(input: ExportSessionPayload): Promise<ExportSessionResult> {
+    const summary = await this.sessionStore.get(input.sessionId);
+    const active = this.sessions.get(input.sessionId);
+    // Closed sessions have no `Session.log`; create an ad-hoc child bound to
+    // their id so the entries still route to the session log file.
+    const exportLog =
+      active?.log ?? log.createChild({ sessionId: input.sessionId });
+    if (active !== undefined) {
+      try {
+        await active.flushMetadata();
+      } catch (error) {
+        exportLog.warn('flushMetadata failed before export', { error });
+      }
+    }
+    await warnIfLogFlushFails(exportLog, 'export session log flush failed', () =>
+      getRootLogger().flushSession(input.sessionId),
+    );
+    if (input.includeGlobalLog === true) {
+      await warnIfLogFlushFails(exportLog, 'export global log flush failed', () =>
+        getRootLogger().flushGlobal(),
+      );
+    }
+    const result = await exportSessionDirectory({
+      request: input,
+      summary,
+      homeDir: this.homeDir,
+      globalLogPath: getRootLogger().getConfig()?.globalLogPath,
+    });
+    return result;
+  }
+
+  async getKimiConfig(input: EmptyPayload = {}): Promise<KimiConfig> {
+    void input;
+    return readConfigFile(this.configPath);
+  }
+
+  async setKimiConfig(input: SetKimiConfigPayload): Promise<KimiConfig> {
+    const config = mergeConfigPatch(readConfigFile(this.configPath), input);
+    await writeConfigFile(this.configPath, config);
+    const updated = readConfigFile(this.configPath);
+    this.providerManager.updateConfig(updated);
+    return updated;
+  }
+
+  async removeKimiProvider(input: RemoveKimiProviderPayload): Promise<KimiConfig> {
+    const config = readConfigFile(this.configPath);
+    delete config.providers[input.providerId];
+
+    let removedDefault = false;
+    const existingModels = config.models ?? {};
+    for (const [key, model] of Object.entries(existingModels)) {
+      if (
+        typeof model === 'object' &&
+        model !== null &&
+        !Array.isArray(model) &&
+        model['provider'] === input.providerId
+      ) {
+        delete existingModels[key];
+        if (config.defaultModel === key) removedDefault = true;
+      }
+    }
+    config.models = existingModels;
+
+    if (removedDefault) {
+      config.defaultModel = undefined;
+    }
+
+    if (config.defaultProvider === input.providerId) {
+      config.defaultProvider = undefined;
+    }
+
+    await writeConfigFile(this.configPath, config);
+    const updated = readConfigFile(this.configPath);
+    this.providerManager.updateConfig(updated);
+    return updated;
+  }
+
+  prompt({ sessionId, ...payload }: SessionAgentPayload<PromptPayload>) {
+    return this.sessionApi(sessionId).prompt(payload);
+  }
+
+  steer({ sessionId, ...payload }: SessionAgentPayload<SteerPayload>) {
+    return this.sessionApi(sessionId).steer(payload);
+  }
+
+  cancel({ sessionId, ...payload }: SessionAgentPayload<CancelPayload>) {
+    return this.sessionApi(sessionId).cancel(payload);
+  }
+
+  async setModel({
+    sessionId,
+    ...payload
+  }: SessionAgentPayload<SetModelPayload>): Promise<SetModelResult> {
+    this.reloadProviderManager();
+    return this.sessionApi(sessionId).setModel(payload);
+  }
+
+  setThinking({ sessionId, ...payload }: SessionAgentPayload<SetThinkingPayload>) {
+    return this.sessionApi(sessionId).setThinking(payload);
+  }
+
+  setPermission({ sessionId, ...payload }: SessionAgentPayload<SetPermissionPayload>) {
+    return this.sessionApi(sessionId).setPermission(payload);
+  }
+
+  getModel({ sessionId, ...payload }: SessionAgentPayload<EmptyPayload>) {
+    return this.sessionApi(sessionId).getModel(payload);
+  }
+
+  enterPlan({ sessionId, ...payload }: SessionAgentPayload<EmptyPayload>) {
+    return this.sessionApi(sessionId).enterPlan(payload);
+  }
+
+  cancelPlan({ sessionId, ...payload }: SessionAgentPayload<CancelPlanPayload>) {
+    return this.sessionApi(sessionId).cancelPlan(payload);
+  }
+
+  clearPlan({ sessionId, ...payload }: SessionAgentPayload<EmptyPayload>) {
+    return this.sessionApi(sessionId).clearPlan(payload);
+  }
+
+  beginCompaction({ sessionId, ...payload }: SessionAgentPayload<BeginCompactionPayload>) {
+    return this.sessionApi(sessionId).beginCompaction(payload);
+  }
+
+  cancelCompaction({ sessionId, ...payload }: SessionAgentPayload<EmptyPayload>) {
+    return this.sessionApi(sessionId).cancelCompaction(payload);
+  }
+
+  registerTool({ sessionId, ...payload }: SessionAgentPayload<RegisterToolPayload>) {
+    return this.sessionApi(sessionId).registerTool(payload);
+  }
+
+  unregisterTool({ sessionId, ...payload }: SessionAgentPayload<UnregisterToolPayload>) {
+    return this.sessionApi(sessionId).unregisterTool(payload);
+  }
+
+  setActiveTools({ sessionId, ...payload }: SessionAgentPayload<SetActiveToolsPayload>) {
+    return this.sessionApi(sessionId).setActiveTools(payload);
+  }
+
+  stopBackground({ sessionId, ...payload }: SessionAgentPayload<StopBackgroundPayload>) {
+    return this.sessionApi(sessionId).stopBackground(payload);
+  }
+
+  clearContext({ sessionId, ...payload }: SessionAgentPayload<EmptyPayload>) {
+    return this.sessionApi(sessionId).clearContext(payload);
+  }
+
+  activateSkill({
+    sessionId,
+    ...payload
+  }: SessionAgentPayload<ActivateSkillPayload>): Promise<void> {
+    return this.sessionApi(sessionId).activateSkill(payload);
+  }
+
+  getBackgroundOutput({ sessionId, ...payload }: SessionAgentPayload<GetBackgroundOutputPayload>) {
+    return this.sessionApi(sessionId).getBackgroundOutput(payload);
+  }
+
+  getBackgroundOutputPath({
+    sessionId,
+    ...payload
+  }: SessionAgentPayload<GetBackgroundOutputPathPayload>) {
+    return this.sessionApi(sessionId).getBackgroundOutputPath(payload);
+  }
+
+  getContext({ sessionId, ...payload }: SessionAgentPayload<EmptyPayload>) {
+    return this.sessionApi(sessionId).getContext(payload);
+  }
+
+  getConfig({ sessionId, ...payload }: SessionAgentPayload<EmptyPayload>) {
+    return this.sessionApi(sessionId).getConfig(payload);
+  }
+
+  getPermission({ sessionId, ...payload }: SessionAgentPayload<EmptyPayload>) {
+    return this.sessionApi(sessionId).getPermission(payload);
+  }
+
+  getPlan({ sessionId, ...payload }: SessionAgentPayload<EmptyPayload>) {
+    return this.sessionApi(sessionId).getPlan(payload);
+  }
+
+  getUsage({ sessionId, ...payload }: SessionAgentPayload<EmptyPayload>) {
+    return this.sessionApi(sessionId).getUsage(payload);
+  }
+
+  getTools({ sessionId, ...payload }: SessionAgentPayload<EmptyPayload>) {
+    return this.sessionApi(sessionId).getTools(payload);
+  }
+
+  getBackground({ sessionId, ...payload }: SessionAgentPayload<GetBackgroundPayload>) {
+    return this.sessionApi(sessionId).getBackground(payload);
+  }
+
+  updateSessionMetadata({ sessionId, ...payload }: UpdateSessionMetadataRequest): Promise<void> {
+    return this.sessionApi(sessionId).updateSessionMetadata(payload);
+  }
+
+  getSessionMetadata({ sessionId, ...payload }: SessionScopedPayload<EmptyPayload>): SessionMeta {
+    return this.sessionApi(sessionId).getSessionMetadata(payload);
+  }
+
+  listSkills({
+    sessionId,
+    ...payload
+  }: SessionScopedPayload<EmptyPayload>): Promise<readonly SkillSummary[]> {
+    return this.sessionApi(sessionId).listSkills(payload);
+  }
+
+  listMcpServers({
+    sessionId,
+    ...payload
+  }: SessionScopedPayload<EmptyPayload>): readonly McpServerInfo[] {
+    return this.sessionApi(sessionId).listMcpServers(payload);
+  }
+
+  getMcpStartupMetrics({
+    sessionId,
+    ...payload
+  }: SessionScopedPayload<EmptyPayload>): Promise<McpStartupMetrics> {
+    return this.sessionApi(sessionId).getMcpStartupMetrics(payload);
+  }
+
+  reconnectMcpServer({
+    sessionId,
+    ...payload
+  }: SessionScopedPayload<ReconnectMcpServerPayload>): Promise<void> {
+    return this.sessionApi(sessionId).reconnectMcpServer(payload);
+  }
+
+  generateAgentsMd({ sessionId, ...payload }: SessionScopedPayload<EmptyPayload>): Promise<void> {
+    return this.sessionApi(sessionId).generateAgentsMd(payload);
+  }
+
+  private async resolveRuntime(config: KimiConfig): Promise<RuntimeConfig> {
+    if (this.runtime !== undefined) return this.runtime;
+    const runtime = await createRuntimeConfig({
+      config,
+      kimiRequestHeaders: this.kimiRequestHeaders,
+      resolveOAuthTokenProvider: this.resolveOAuthTokenProvider,
+    });
+    this.runtime = runtime;
+    return runtime;
+  }
+
+  private resolveSessionSkillConfig(config: KimiConfig): SessionSkillConfig {
+    const explicitDirs = this.skillDirs.length > 0 ? this.skillDirs : undefined;
+    return {
+      userHomeDir: this.userHomeDir,
+      explicitDirs,
+      extraDirs: config.extraSkillDirs,
+      mergeAllAvailableSkills: config.mergeAllAvailableSkills,
+    };
+  }
+
+  private sessionApi(sessionId: string): SessionAPIImpl {
+    const session = this.sessions.get(sessionId);
+    if (session === undefined) {
+      throw new KimiError(ErrorCodes.SESSION_NOT_FOUND, `Session "${sessionId}" was not found`, {
+        details: { sessionId },
+      });
+    }
+    return new SessionAPIImpl(session);
+  }
+
+  private reloadProviderManager(): KimiConfig {
+    const config = readConfigFile(this.configPath);
+    this.providerManager.updateConfig(config);
+    return config;
+  }
+
+  private async refreshSessionRuntimeConfig(
+    session: Session,
+    config: KimiConfig,
+  ): Promise<void> {
+    const api = new SessionAPIImpl(session);
+    // A session migrated from an external tool carries no model, and any
+    // session may reference a model alias that no longer exists in config.toml.
+    // Try the session's own model first, then fall back to the configured
+    // default, so resume degrades gracefully instead of hard-failing.
+    const requested = (await api.getModel({ agentId: 'main' })).trim();
+    const fallback = config.defaultModel?.trim() ?? '';
+    const candidates = [...new Set([requested, fallback].filter((model) => model.length > 0))];
+    for (const model of candidates) {
+      try {
+        await api.setModel({ agentId: 'main', model });
+        await session.flushMetadata();
+        return;
+      } catch (error) {
+        // Skip a candidate only when the alias is genuinely absent from
+        // config (a stale or migrated model) — that is the graceful-degrade
+        // case. A *configured* alias that fails to resolve (missing provider,
+        // no credentials, bad max_context_size) is an actionable config error
+        // the user must see; surface it instead of silently swapping models.
+        const aliasMissing = config.models?.[model] === undefined;
+        if (
+          aliasMissing &&
+          error instanceof KimiError &&
+          error.code === ErrorCodes.CONFIG_INVALID
+        ) {
+          continue;
+        }
+        throw error;
+      }
+    }
+    // No candidate resolved (the replayed alias and the configured default are
+    // both invalid/unset). Clear the stale alias so the session is honestly
+    // model-less — the TUI then prompts for a model instead of showing a
+    // selection whose next prompt fails with a config error. Not persisted:
+    // `refreshSessionRuntimeConfig` re-derives this on every resume.
+    if (requested.length > 0) {
+      session.agents.get('main')?.config.update({ modelAlias: undefined });
+    }
+  }
+}
+
+async function createRuntimeConfig(input: {
+  readonly config: KimiConfig;
+  readonly kimiRequestHeaders?: Record<string, string> | undefined;
+  readonly resolveOAuthTokenProvider?: OAuthTokenProviderResolver | undefined;
+}): Promise<RuntimeConfig> {
+  const localFetcher = new LocalFetchURLProvider();
+  const searchService = input.config.services?.moonshotSearch;
+  const fetchService = input.config.services?.moonshotFetch;
+
+  return {
+    kaos: localKaos,
+    osEnv: await detectEnvironmentFromNode(),
+    urlFetcher:
+      fetchService?.baseUrl === undefined
+        ? localFetcher
+        : new MoonshotFetchURLProvider({
+            baseUrl: fetchService.baseUrl,
+            localFallback: localFetcher,
+            defaultHeaders: input.kimiRequestHeaders,
+            ...serviceCredentials(fetchService, input.resolveOAuthTokenProvider),
+          }),
+    webSearcher:
+      searchService?.baseUrl === undefined
+        ? undefined
+        : new MoonshotWebSearchProvider({
+            baseUrl: searchService.baseUrl,
+            defaultHeaders: input.kimiRequestHeaders,
+            ...serviceCredentials(searchService, input.resolveOAuthTokenProvider),
+          }),
+  };
+}
+
+function serviceCredentials(
+  service: MoonshotServiceConfig,
+  resolveOAuthTokenProvider: OAuthTokenProviderResolver | undefined,
+): {
+  readonly apiKey?: string | undefined;
+  readonly tokenProvider?: BearerTokenProvider | undefined;
+  readonly customHeaders?: Record<string, string> | undefined;
+} {
+  const apiKey = nonEmptyString(service.apiKey);
+  return {
+    apiKey,
+    tokenProvider:
+      service.oauth !== undefined
+        ? resolveOAuthTokenProvider?.(KIMI_CODE_PROVIDER_NAME, service.oauth)
+        : undefined,
+    customHeaders: service.customHeaders,
+  };
+}
+
+function nonEmptyString(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;
+}
+
+function requiredWorkDir(operation: string, value: string): string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new KimiError(ErrorCodes.REQUEST_WORK_DIR_REQUIRED, `${operation} requires workDir`);
+  }
+  return normalizeWorkDir(value);
+}
+
+function createSessionId(): string {
+  return `session_${randomUUID()}`;
+}
+
+function telemetryErrorReason(error: unknown): string {
+  if (error instanceof KimiError) return error.code;
+  if (error instanceof Error && error.name.length > 0) return error.name;
+  return typeof error;
+}
+
+async function resumeSessionResult(
+  summary: SessionSummary,
+  session: Session,
+): Promise<ResumeSessionResult> {
+  const api = new SessionAPIImpl(session);
+  const agents: Record<string, ResumedAgentState> = {};
+  for (const [agentId, agent] of session.agents) {
+    const config = await api.getConfig({ agentId });
+    const context = await api.getContext({ agentId });
+    const permission = await api.getPermission({ agentId });
+    const plan = await api.getPlan({ agentId });
+    const usage = await api.getUsage({ agentId });
+    agents[agentId] = {
+      type: agent.type,
+      config,
+      context,
+      replay: agent.replayBuilder.buildResult(),
+      permission,
+      plan,
+      usage,
+      tools: await api.getTools({ agentId }),
+      toolStore: agent.tools.storeData(),
+      background: agent.background.list(false),
+    };
+  }
+  return {
+    ...summary,
+    sessionMetadata: api.getSessionMetadata({}),
+    agents,
+  };
+}
+
+async function warnIfLogFlushFails(
+  exportLog: Logger,
+  message: string,
+  flush: () => Promise<boolean>,
+): Promise<void> {
+  try {
+    if (await flush()) return;
+    exportLog.warn(message);
+  } catch (error) {
+    exportLog.warn(message, { error });
+  }
+  try {
+    await flush();
+  } catch {}
+}
diff --git a/packages/agent-core/src/rpc/events.ts b/packages/agent-core/src/rpc/events.ts
new file mode 100644
index 000000000..d387c49ae
--- /dev/null
+++ b/packages/agent-core/src/rpc/events.ts
@@ -0,0 +1,297 @@
+import type { FinishReason, TokenUsage } from '@moonshot-ai/kosong';
+
+import type { PromptOrigin } from '../agent/context';
+import type { KimiErrorPayload } from '../errors';
+import type { PermissionMode } from '../agent/permission';
+import type { SkillSource } from '../skill';
+import type { BackgroundTaskInfo } from '../tools/background/manager';
+import type { ToolInputDisplay } from '../tools/display';
+
+export type { ToolInputDisplay } from '../tools/display';
+export type { KimiErrorPayload } from '../errors';
+
+export interface UsageStatus {
+  readonly byModel?: Record<string, TokenUsage> | undefined;
+  readonly currentTurn?: TokenUsage | undefined;
+  readonly total?: TokenUsage | undefined;
+}
+
+export interface ToolUpdate {
+  readonly kind: 'stdout' | 'stderr' | 'progress' | 'status' | 'custom';
+  readonly text?: string | undefined;
+  readonly percent?: number | undefined;
+  readonly customKind?: string | undefined;
+  readonly customData?: unknown;
+}
+
+export const MCP_OAUTH_AUTHORIZATION_URL_TOOL_UPDATE = 'mcp.oauth.authorization_url';
+
+export interface McpOAuthAuthorizationUrlUpdateData {
+  readonly serverName: string;
+  readonly authorizationUrl: string;
+}
+
+export interface CompactionResult {
+  readonly summary: string;
+  readonly compactedCount: number;
+  readonly tokensBefore: number;
+  readonly tokensAfter: number;
+}
+
+export type TurnEndReason = 'completed' | 'cancelled' | 'failed';
+
+export interface AgentStatusUpdatedEvent {
+  readonly type: 'agent.status.updated';
+  readonly model?: string | undefined;
+  readonly contextTokens?: number | undefined;
+  readonly maxContextTokens?: number | undefined;
+  readonly contextUsage?: number | undefined;
+  readonly planMode?: boolean | undefined;
+  readonly permission?: PermissionMode | undefined;
+  readonly usage?: UsageStatus | undefined;
+}
+
+export interface SessionMetaUpdatedEvent {
+  readonly type: 'session.meta.updated';
+  readonly title?: string | undefined;
+  readonly patch?: Record<string, unknown> | undefined;
+}
+
+export interface SkillActivatedEvent {
+  readonly type: 'skill.activated';
+  readonly activationId: string;
+  readonly skillName: string;
+  readonly skillArgs?: string | undefined;
+  readonly trigger: 'user-slash' | 'model-tool' | 'nested-skill';
+  readonly skillPath?: string | undefined;
+  readonly skillSource?: SkillSource | undefined;
+}
+
+export interface ErrorEvent extends KimiErrorPayload {
+  readonly type: 'error';
+  readonly sessionId?: string | undefined;
+  readonly agentId?: string | undefined;
+}
+
+export interface TurnStartedEvent {
+  readonly type: 'turn.started';
+  readonly turnId: number;
+  readonly origin: PromptOrigin;
+}
+
+export interface TurnEndedEvent {
+  readonly type: 'turn.ended';
+  readonly turnId: number;
+  readonly reason: TurnEndReason;
+  readonly error?: KimiErrorPayload | undefined;
+}
+
+export interface TurnStepStartedEvent {
+  readonly type: 'turn.step.started';
+  readonly turnId: number;
+  readonly step: number;
+  readonly stepId?: string | undefined;
+}
+
+export interface TurnStepCompletedEvent {
+  readonly type: 'turn.step.completed';
+  readonly turnId: number;
+  readonly step: number;
+  readonly stepId?: string | undefined;
+  readonly usage?: TokenUsage | undefined;
+  readonly finishReason?: string | undefined;
+  readonly providerFinishReason?: FinishReason | undefined;
+  readonly rawFinishReason?: string | undefined;
+}
+
+export interface TurnStepRetryingEvent {
+  readonly type: 'turn.step.retrying';
+  readonly turnId: number;
+  readonly step: number;
+  readonly stepId?: string;
+  readonly failedAttempt: number;
+  readonly nextAttempt: number;
+  readonly maxAttempts: number;
+  readonly delayMs: number;
+  readonly errorName: string;
+  readonly errorMessage: string;
+  readonly statusCode?: number;
+}
+
+export interface TurnStepInterruptedEvent {
+  readonly type: 'turn.step.interrupted';
+  readonly turnId: number;
+  readonly step: number;
+  readonly stepId?: string | undefined;
+  readonly reason: string;
+  readonly message?: string | undefined;
+}
+
+export interface AssistantDeltaEvent {
+  readonly type: 'assistant.delta';
+  readonly turnId: number;
+  readonly delta: string;
+}
+
+export interface HookResultEvent {
+  readonly type: 'hook.result';
+  readonly turnId: number;
+  readonly hookEvent: string;
+  readonly content: string;
+  readonly blocked?: boolean | undefined;
+}
+
+export interface ThinkingDeltaEvent {
+  readonly type: 'thinking.delta';
+  readonly turnId: number;
+  readonly delta: string;
+}
+
+export interface ToolCallDeltaEvent {
+  readonly type: 'tool.call.delta';
+  readonly turnId: number;
+  readonly toolCallId: string;
+  readonly name?: string | undefined;
+  readonly argumentsPart?: string | undefined;
+}
+
+export interface ToolCallStartedEvent {
+  readonly type: 'tool.call.started';
+  readonly turnId: number;
+  readonly toolCallId: string;
+  readonly name: string;
+  readonly args: unknown;
+  readonly description?: string | undefined;
+  readonly display?: ToolInputDisplay | undefined;
+}
+
+export interface ToolProgressEvent {
+  readonly type: 'tool.progress';
+  readonly turnId: number;
+  readonly toolCallId: string;
+  readonly update: ToolUpdate;
+}
+
+export interface ToolResultEvent {
+  readonly type: 'tool.result';
+  readonly turnId: number;
+  readonly toolCallId: string;
+  readonly output: unknown;
+  readonly isError?: boolean | undefined;
+  readonly synthetic?: boolean | undefined;
+}
+
+export interface SubagentSpawnedEvent {
+  readonly type: 'subagent.spawned';
+  readonly subagentId: string;
+  readonly subagentName: string;
+  readonly parentToolCallId: string;
+  readonly parentToolCallUuid?: string | undefined;
+  readonly parentAgentId?: string | undefined;
+  readonly description?: string | undefined;
+  readonly runInBackground: boolean;
+}
+
+export interface SubagentCompletedEvent {
+  readonly type: 'subagent.completed';
+  readonly subagentId: string;
+  readonly parentToolCallId: string;
+  readonly resultSummary: string;
+  readonly usage?: TokenUsage | undefined;
+}
+
+export interface SubagentFailedEvent {
+  readonly type: 'subagent.failed';
+  readonly subagentId: string;
+  readonly parentToolCallId: string;
+  readonly error: string;
+}
+
+export interface CompactionStartedEvent {
+  readonly type: 'compaction.started';
+  readonly trigger: 'manual' | 'auto';
+  readonly instruction?: string | undefined;
+}
+
+export interface CompactionBlockedEvent {
+  readonly type: 'compaction.blocked';
+  readonly turnId?: number | undefined;
+}
+
+export interface CompactionCancelledEvent {
+  readonly type: 'compaction.cancelled';
+}
+
+export interface CompactionCompletedEvent {
+  readonly type: 'compaction.completed';
+  readonly result: CompactionResult;
+}
+
+export interface BackgroundTaskStartedEvent {
+  readonly type: 'background.task.started';
+  readonly info: BackgroundTaskInfo;
+}
+
+export interface BackgroundTaskUpdatedEvent {
+  readonly type: 'background.task.updated';
+  readonly info: BackgroundTaskInfo;
+}
+
+export interface BackgroundTaskTerminatedEvent {
+  readonly type: 'background.task.terminated';
+  readonly info: BackgroundTaskInfo;
+}
+
+export type ToolListUpdatedReason = 'mcp.connected' | 'mcp.disconnected' | 'mcp.failed';
+
+export interface ToolListUpdatedEvent {
+  readonly type: 'tool.list.updated';
+  readonly reason: ToolListUpdatedReason;
+  readonly serverName: string;
+}
+
+export interface McpServerStatusEvent {
+  readonly type: 'mcp.server.status';
+  readonly server: McpServerStatusPayload;
+}
+
+export interface McpServerStatusPayload {
+  readonly name: string;
+  readonly transport: 'stdio' | 'http';
+  readonly status: 'pending' | 'connected' | 'failed' | 'disabled' | 'needs-auth';
+  readonly toolCount: number;
+  readonly error?: string | undefined;
+}
+
+export type AgentEvent =
+  | ErrorEvent
+  | AgentStatusUpdatedEvent
+  | SessionMetaUpdatedEvent
+  | SkillActivatedEvent
+  | TurnStartedEvent
+  | TurnEndedEvent
+  | TurnStepStartedEvent
+  | TurnStepCompletedEvent
+  | TurnStepRetryingEvent
+  | TurnStepInterruptedEvent
+  | AssistantDeltaEvent
+  | HookResultEvent
+  | ThinkingDeltaEvent
+  | ToolCallDeltaEvent
+  | ToolCallStartedEvent
+  | ToolProgressEvent
+  | ToolResultEvent
+  | ToolListUpdatedEvent
+  | McpServerStatusEvent
+  | SubagentSpawnedEvent
+  | SubagentCompletedEvent
+  | SubagentFailedEvent
+  | CompactionStartedEvent
+  | CompactionBlockedEvent
+  | CompactionCancelledEvent
+  | CompactionCompletedEvent
+  | BackgroundTaskStartedEvent
+  | BackgroundTaskUpdatedEvent
+  | BackgroundTaskTerminatedEvent;
+
+export type Event = AgentEvent & { agentId: string; sessionId: string };
diff --git a/packages/agent-core/src/rpc/index.ts b/packages/agent-core/src/rpc/index.ts
new file mode 100644
index 000000000..1bc8f0b05
--- /dev/null
+++ b/packages/agent-core/src/rpc/index.ts
@@ -0,0 +1,7 @@
+export * from './client';
+export * from './core-api';
+export * from './core-impl';
+export * from './resumed';
+export * from './sdk-api';
+export * from './events';
+export * from './types';
diff --git a/packages/agent-core/src/rpc/resumed.ts b/packages/agent-core/src/rpc/resumed.ts
new file mode 100644
index 000000000..61eb1dd67
--- /dev/null
+++ b/packages/agent-core/src/rpc/resumed.ts
@@ -0,0 +1,39 @@
+import type { AgentType } from '#/agent';
+import type { AgentConfigData, AgentConfigUpdateData } from '#/agent/config';
+import type { AgentContextData, ContextMessage } from '#/agent/context';
+import type {
+  PermissionApprovalResultRecord,
+  PermissionData,
+  PermissionMode,
+} from '#/agent/permission';
+import type { PlanData } from '#/agent/plan';
+import type { ToolInfo } from '#/agent/tool';
+import type { SessionSummary } from '#/rpc/core-api';
+import type { UsageStatus } from '#/rpc/events';
+import type { SessionMeta } from '#/session';
+import type { BackgroundTaskInfo } from '#/tools/builtin';
+
+export type AgentReplayRecord =
+  | { type: 'message'; message: ContextMessage }
+  | { type: 'plan_updated'; enabled: boolean }
+  | { type: 'config_updated'; config: AgentConfigUpdateData }
+  | { type: 'permission_updated'; mode: PermissionMode }
+  | { type: 'approval_result'; record: PermissionApprovalResultRecord };
+
+export interface ResumedAgentState {
+  readonly type: AgentType;
+  readonly config: AgentConfigData;
+  readonly context: AgentContextData;
+  readonly replay: readonly AgentReplayRecord[];
+  readonly permission: PermissionData;
+  readonly plan: PlanData;
+  readonly usage: UsageStatus;
+  readonly tools: readonly ToolInfo[];
+  readonly toolStore?: Readonly<Record<string, unknown>>;
+  readonly background: readonly BackgroundTaskInfo[];
+}
+
+export interface ResumeSessionResult extends SessionSummary {
+  readonly sessionMetadata: SessionMeta;
+  readonly agents: Readonly<Record<string, ResumedAgentState>>;
+}
diff --git a/packages/agent-core/src/rpc/sdk-api.ts b/packages/agent-core/src/rpc/sdk-api.ts
new file mode 100644
index 000000000..3e58672be
--- /dev/null
+++ b/packages/agent-core/src/rpc/sdk-api.ts
@@ -0,0 +1,79 @@
+import type { ContentPart } from '@moonshot-ai/kosong';
+
+import type { RPCMethods } from './client';
+import type { AgentEvent, ToolInputDisplay } from './events';
+import type { WithAgentId, WithSessionId } from './types';
+
+export type ApprovalDecision = 'approved' | 'rejected' | 'cancelled';
+export type ApprovalScope = 'session';
+
+export interface ApprovalResponse {
+  readonly decision: ApprovalDecision;
+  readonly scope?: ApprovalScope | undefined;
+  readonly feedback?: string | undefined;
+  readonly selectedLabel?: string | undefined;
+}
+
+export interface ApprovalRequest {
+  readonly turnId?: number | undefined;
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly action: string;
+  readonly display: ToolInputDisplay;
+}
+
+export interface QuestionOption {
+  readonly label: string;
+  readonly description?: string;
+}
+
+export interface QuestionItem {
+  readonly question: string;
+  readonly header?: string;
+  readonly body?: string;
+  readonly options: readonly QuestionOption[];
+  readonly multiSelect?: boolean;
+  readonly otherLabel?: string;
+  readonly otherDescription?: string;
+}
+
+export type QuestionAnswerMethod = 'enter' | 'space' | 'number_key';
+export type QuestionAnswers = Record<string, string | true>;
+
+export interface QuestionResponse {
+  readonly answers: QuestionAnswers;
+  readonly method?: QuestionAnswerMethod | undefined;
+}
+
+export type QuestionResult = null | QuestionAnswers | QuestionResponse;
+
+export interface QuestionRequest {
+  readonly turnId?: number;
+  readonly toolCallId?: string;
+  readonly questions: readonly QuestionItem[];
+}
+
+export interface ToolCallRequest {
+  readonly turnId?: number | undefined;
+  readonly toolCallId: string;
+  readonly args: unknown;
+}
+
+export interface ToolCallResponse {
+  readonly output: string | ContentPart[];
+  readonly isError?: boolean | undefined;
+}
+
+export interface SDKAgentAPI {
+  emitEvent: (event: AgentEvent) => void;
+  requestApproval: (request: ApprovalRequest) => Promise<ApprovalResponse>;
+  requestQuestion: (request: QuestionRequest) => Promise<QuestionResult>;
+  toolCall: (request: ToolCallRequest) => Promise<ToolCallResponse>;
+}
+export type SDKAgentRPC = RPCMethods<SDKAgentAPI>;
+
+export type SDKSessionAPI = WithAgentId<SDKAgentAPI>;
+export type SDKSessionRPC = RPCMethods<SDKSessionAPI>;
+
+export type SDKAPI = WithSessionId<SDKSessionAPI>;
+export type SDKRPC = RPCMethods<SDKAPI>;
diff --git a/packages/agent-core/src/rpc/types.ts b/packages/agent-core/src/rpc/types.ts
new file mode 100644
index 000000000..29a5bb609
--- /dev/null
+++ b/packages/agent-core/src/rpc/types.ts
@@ -0,0 +1,29 @@
+import type { RPCMethods } from './client';
+
+type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+type WithExtraPayload<T, U> = {
+  [K in keyof T]: T[K] extends (payload: infer P) => infer R
+    ? (payload: Prettify<P & U>) => R
+    : never;
+};
+
+export type WithAgentId<T> = WithExtraPayload<T, { readonly agentId: string }>;
+export type WithSessionId<T> = WithExtraPayload<T, { readonly sessionId: string }>;
+
+export function proxyWithExtraPayload<T, U>(
+  methods: RPCMethods<WithExtraPayload<T, U>>,
+  extraPayload: U,
+): RPCMethods<T> {
+  return new Proxy(methods as any, {
+    get(target, prop) {
+      const origMethod = target[prop as keyof typeof target];
+      if (typeof origMethod !== 'function') {
+        return origMethod;
+      }
+      return (payload: any, ...args: any) => origMethod({ ...payload, ...extraPayload }, ...args);
+    },
+  });
+}
diff --git a/packages/agent-core/src/runtime-types.ts b/packages/agent-core/src/runtime-types.ts
new file mode 100644
index 000000000..3ab4fcbb8
--- /dev/null
+++ b/packages/agent-core/src/runtime-types.ts
@@ -0,0 +1,11 @@
+import type { Kaos } from '@moonshot-ai/kaos';
+
+import type { UrlFetcher, WebSearchProvider } from './tools/builtin';
+import type { Environment } from './utils/environment';
+
+export interface RuntimeConfig {
+  readonly kaos: Kaos;
+  readonly osEnv: Environment;
+  readonly urlFetcher?: UrlFetcher | undefined;
+  readonly webSearcher?: WebSearchProvider | undefined;
+}
diff --git a/packages/agent-core/src/session/export/index.ts b/packages/agent-core/src/session/export/index.ts
new file mode 100644
index 000000000..baaa03182
--- /dev/null
+++ b/packages/agent-core/src/session/export/index.ts
@@ -0,0 +1,4 @@
+export * from '#/session/export/manifest';
+export * from '#/session/export/session-export';
+export * from '#/session/export/wire-scan';
+export * from '#/session/export/zip';
diff --git a/packages/agent-core/src/session/export/manifest.ts b/packages/agent-core/src/session/export/manifest.ts
new file mode 100644
index 000000000..d5334606b
--- /dev/null
+++ b/packages/agent-core/src/session/export/manifest.ts
@@ -0,0 +1,36 @@
+import { AGENT_WIRE_PROTOCOL_VERSION } from '../../agent/records/types';
+import type { SessionWireScan } from '#/session/export/wire-scan';
+import type { ExportSessionManifest, SessionSummary } from '#/rpc/core-api';
+
+export const WIRE_PROTOCOL_VERSION = AGENT_WIRE_PROTOCOL_VERSION;
+
+export function buildExportManifest(args: {
+  readonly summary: SessionSummary;
+  readonly now: Date;
+  readonly version: string;
+  readonly wireProtocolVersion?: string | undefined;
+  readonly sessionScan: SessionWireScan;
+  readonly sessionLogPath?: string | undefined;
+  readonly globalLogPath?: string | undefined;
+}): ExportSessionManifest {
+  return {
+    sessionId: args.summary.id,
+    exportedAt: args.now.toISOString(),
+    kimiCodeVersion: args.version,
+    wireProtocolVersion: args.wireProtocolVersion ?? WIRE_PROTOCOL_VERSION,
+    os: `${process.platform} ${process.arch}`,
+    nodejsVersion: process.version.replace(/^v/, ''),
+    sessionFirstActivity:
+      args.sessionScan.firstActivityMs === undefined
+        ? undefined
+        : new Date(args.sessionScan.firstActivityMs).toISOString(),
+    sessionLastActivity:
+      args.sessionScan.lastActivityMs === undefined
+        ? undefined
+        : new Date(args.sessionScan.lastActivityMs).toISOString(),
+    title: args.summary.title,
+    workspaceDir: args.summary.workDir,
+    sessionLogPath: args.sessionLogPath,
+    globalLogPath: args.globalLogPath,
+  };
+}
diff --git a/packages/agent-core/src/session/export/session-export.ts b/packages/agent-core/src/session/export/session-export.ts
new file mode 100644
index 000000000..dc71b929a
--- /dev/null
+++ b/packages/agent-core/src/session/export/session-export.ts
@@ -0,0 +1,86 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { ErrorCodes, KimiError } from '#/errors';
+import { resolveGlobalLogPath } from '#/logging/logger';
+import { buildExportManifest } from '#/session/export/manifest';
+import { scanSessionWire } from '#/session/export/wire-scan';
+import {
+  type ExtraZipEntry,
+  collectFilesRecursive,
+  writeExportZip,
+} from '#/session/export/zip';
+import type { ExportSessionPayload, ExportSessionResult, SessionSummary } from '#/rpc/core-api';
+
+const SESSION_LOG_REL = 'logs/kimi-code.log';
+const GLOBAL_LOG_REL = 'logs/global/kimi-code.log';
+
+export async function exportSessionDirectory(input: {
+  readonly request: ExportSessionPayload;
+  readonly summary: SessionSummary;
+  readonly homeDir?: string | undefined;
+  readonly globalLogPath?: string | undefined;
+}): Promise<ExportSessionResult> {
+  const sessionDir = input.summary.sessionDir;
+  const sessionFiles = await collectFilesRecursive(sessionDir);
+  if (sessionFiles.length === 0) {
+    throw new KimiError(ErrorCodes.SESSION_EXPORT_NOT_FOUND, `Session "${input.summary.id}" has no exportable directory at "${sessionDir}"`, {
+      details: { sessionId: input.summary.id, sessionDir },
+    });
+  }
+
+  const sessionScan = await scanSessionWire(sessionDir);
+  const hasSessionLog = sessionFiles.some((f) =>
+    f.endsWith(`/${SESSION_LOG_REL}`) || f.endsWith(`\\${SESSION_LOG_REL.replaceAll('/', '\\')}`),
+  );
+
+  const extras: ExtraZipEntry[] = [];
+  let bundledGlobal = false;
+  const globalPath =
+    input.globalLogPath ??
+    (input.homeDir === undefined ? undefined : resolveGlobalLogPath(input.homeDir));
+  if (input.request.includeGlobalLog === true && globalPath !== undefined) {
+    const data = await readOptionalFile(globalPath);
+    if (data !== undefined) {
+      extras.push({ data, target: GLOBAL_LOG_REL });
+      bundledGlobal = true;
+    }
+  }
+
+  const manifest = buildExportManifest({
+    summary: input.summary,
+    now: new Date(),
+    version: input.request.version,
+    sessionScan,
+    sessionLogPath: hasSessionLog ? SESSION_LOG_REL : undefined,
+    globalLogPath: bundledGlobal ? GLOBAL_LOG_REL : undefined,
+  });
+
+  const outputPath =
+    input.request.outputPath !== undefined
+      ? resolve(input.request.outputPath)
+      : resolve(`${input.summary.id}.zip`);
+
+  const entries = await writeExportZip({
+    outputPath,
+    manifest,
+    sessionDir,
+    sessionFiles,
+    extraEntries: extras,
+  });
+
+  return {
+    zipPath: outputPath,
+    entries,
+    sessionDir,
+    manifest,
+  };
+}
+
+async function readOptionalFile(path: string): Promise<Buffer | undefined> {
+  try {
+    return await readFile(path);
+  } catch {
+    return undefined;
+  }
+}
diff --git a/packages/agent-core/src/session/export/wire-scan.ts b/packages/agent-core/src/session/export/wire-scan.ts
new file mode 100644
index 000000000..2d5aa2e2e
--- /dev/null
+++ b/packages/agent-core/src/session/export/wire-scan.ts
@@ -0,0 +1,69 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export interface SessionWireScan {
+  readonly firstActivityMs?: number | undefined;
+  readonly lastActivityMs?: number | undefined;
+  readonly lastUserMessageMs?: number | undefined;
+  readonly firstUserInput?: string | undefined;
+}
+
+export async function scanSessionWire(sessionDir: string): Promise<SessionWireScan> {
+  let raw: string;
+  try {
+    raw = await readFile(join(sessionDir, 'wire.jsonl'), 'utf-8');
+  } catch {
+    return {};
+  }
+
+  let firstActivityMs: number | undefined;
+  let lastActivityMs: number | undefined;
+  let lastUserMessageMs: number | undefined;
+  let firstUserInput: string | undefined;
+
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(trimmed) as unknown;
+    } catch {
+      continue;
+    }
+    if (typeof parsed !== 'object' || parsed === null) continue;
+    const record = parsed as {
+      type?: unknown;
+      time?: unknown;
+      userInput?: unknown;
+    };
+    const timeMs = typeof record.time === 'number' ? normalizeTimestampMs(record.time) : undefined;
+    if (timeMs !== undefined) {
+      firstActivityMs ??= timeMs;
+      lastActivityMs = timeMs;
+    }
+    if (record.type === 'turn_begin') {
+      if (timeMs !== undefined) {
+        lastUserMessageMs = timeMs;
+      }
+      if (
+        firstUserInput === undefined &&
+        typeof record.userInput === 'string' &&
+        record.userInput.trim().length > 0
+      ) {
+        firstUserInput = record.userInput;
+      }
+    }
+  }
+
+  return {
+    firstActivityMs,
+    lastActivityMs,
+    lastUserMessageMs,
+    firstUserInput,
+  };
+}
+
+export function normalizeTimestampMs(value: number): number | undefined {
+  if (!Number.isFinite(value) || value <= 0) return undefined;
+  return value > 1e12 ? Math.floor(value) : Math.floor(value * 1000);
+}
diff --git a/packages/agent-core/src/session/export/zip.ts b/packages/agent-core/src/session/export/zip.ts
new file mode 100644
index 000000000..295ac4a31
--- /dev/null
+++ b/packages/agent-core/src/session/export/zip.ts
@@ -0,0 +1,69 @@
+import { createWriteStream } from 'node:fs';
+import { mkdir, readdir, readFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import type { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+import type { ExportSessionManifest } from '#/rpc/core-api';
+import { ZipFile } from 'yazl';
+
+export async function collectFilesRecursive(root: string): Promise<string[]> {
+  try {
+    const entries = await readdir(root, { recursive: true, withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isFile())
+      .map((entry) => join(entry.parentPath, entry.name))
+      .toSorted((a, b) => a.localeCompare(b));
+  } catch {
+    return [];
+  }
+}
+
+export type ExtraZipEntry =
+  | {
+      /** Absolute path on disk. */
+      readonly source: string;
+      /** zip-relative target path. */
+      readonly target: string;
+    }
+  | {
+      readonly data: Buffer;
+      /** zip-relative target path. */
+      readonly target: string;
+    };
+
+export async function writeExportZip(args: {
+  readonly outputPath: string;
+  readonly manifest: ExportSessionManifest;
+  readonly sessionDir: string;
+  readonly sessionFiles: readonly string[];
+  readonly extraEntries?: readonly ExtraZipEntry[];
+}): Promise<readonly string[]> {
+  await mkdir(dirname(args.outputPath), { recursive: true });
+
+  const entries: string[] = ['manifest.json'];
+  const zip = new ZipFile();
+  zip.addBuffer(Buffer.from(JSON.stringify(args.manifest, null, 2), 'utf-8'), 'manifest.json');
+
+  for (const abs of args.sessionFiles) {
+    const rel = relative(args.sessionDir, abs).split(/[\\/]/).join('/');
+    const data = await readFile(abs);
+    zip.addBuffer(data, rel);
+    entries.push(rel);
+  }
+
+  for (const extra of args.extraEntries ?? []) {
+    try {
+      const data = 'data' in extra ? extra.data : await readFile(extra.source);
+      zip.addBuffer(data, extra.target);
+      entries.push(extra.target);
+    } catch {
+      // missing source is not fatal — caller decided it should be opt-in;
+      // do not abort the whole export.
+    }
+  }
+
+  zip.end();
+  await pipeline(zip.outputStream as unknown as Readable, createWriteStream(args.outputPath));
+  return entries;
+}
diff --git a/packages/agent-core/src/session/git-context.ts b/packages/agent-core/src/session/git-context.ts
new file mode 100644
index 000000000..f30edb479
--- /dev/null
+++ b/packages/agent-core/src/session/git-context.ts
@@ -0,0 +1,197 @@
+/**
+ * Git repository context for explore subagents.
+ *
+ * `collectGitContext` produces a `<git-context>` block that is prepended to a
+ * fresh explore subagent's prompt so it can orient itself in the repository
+ * before searching. Every git command is individually guarded — a single
+ * failure never aborts the whole collection — and remote URLs are sanitized
+ * so internal infrastructure is not surfaced to the model.
+ */
+
+import type { Readable } from 'node:stream';
+
+import type { Kaos } from '@moonshot-ai/kaos';
+
+const GIT_TIMEOUT_MS = 5_000;
+const MAX_DIRTY_FILES = 20;
+const MAX_COMMIT_LINE_LENGTH = 200;
+
+// Well-known public hosts whose remote URLs are safe to surface. Self-hosted
+// or unrecognized hosts are excluded to avoid leaking internal infrastructure.
+const ALLOWED_HOSTS = [
+  'github.com',
+  'gitlab.com',
+  'gitee.com',
+  'bitbucket.org',
+  'codeberg.org',
+  'git.sr.ht',
+] as const;
+
+/**
+ * Collect git context for the explore agent.
+ *
+ * Returns a formatted `<git-context>` block, or an empty string if the
+ * directory is not a git repository or no useful information was collected.
+ */
+export async function collectGitContext(kaos: Kaos, cwd: string): Promise<string> {
+  // Quick check: is this a git repo?
+  if ((await runGit(kaos, cwd, ['rev-parse', '--is-inside-work-tree'])) === null) {
+    return '';
+  }
+
+  const [remoteUrl, branch, dirtyRaw, logRaw] = await Promise.all([
+    runGit(kaos, cwd, ['remote', 'get-url', 'origin']),
+    runGit(kaos, cwd, ['branch', '--show-current']),
+    runGit(kaos, cwd, ['status', '--porcelain']),
+    runGit(kaos, cwd, ['log', '-3', '--format=%h %s']),
+  ]);
+
+  const sections: string[] = [`Working directory: ${cwd}`];
+
+  if (remoteUrl) {
+    const safeUrl = sanitizeRemoteUrl(remoteUrl);
+    if (safeUrl) {
+      sections.push(`Remote: ${safeUrl}`);
+      // Derive the project slug only from an allowed remote — deriving it from
+      // a rejected host would leak an internal owner/repo into the prompt.
+      const project = parseProjectName(safeUrl);
+      if (project) sections.push(`Project: ${project}`);
+    }
+  }
+
+  if (branch) sections.push(`Branch: ${branch}`);
+
+  if (dirtyRaw !== null) {
+    const dirtyLines = dirtyRaw.split('\n').filter((line) => line.trim().length > 0);
+    if (dirtyLines.length > 0) {
+      const total = dirtyLines.length;
+      const shown = dirtyLines.slice(0, MAX_DIRTY_FILES);
+      let body = shown.map((line) => `  ${line}`).join('\n');
+      if (total > MAX_DIRTY_FILES) {
+        body += `\n  ... and ${String(total - MAX_DIRTY_FILES)} more`;
+      }
+      sections.push(`Dirty files (${String(total)}):\n${body}`);
+    }
+  }
+
+  if (logRaw) {
+    const logLines = logRaw.split('\n').filter((line) => line.trim().length > 0);
+    if (logLines.length > 0) {
+      const body = logLines.map((line) => `  ${line.slice(0, MAX_COMMIT_LINE_LENGTH)}`).join('\n');
+      sections.push(`Recent commits:\n${body}`);
+    }
+  }
+
+  if (sections.length <= 1) {
+    // Only the working directory line — nothing useful collected.
+    return '';
+  }
+
+  return `<git-context>\n${sections.join('\n')}\n</git-context>`;
+}
+
+/**
+ * Return the remote URL if it points to a well-known public host, stripping
+ * credentials from HTTPS URLs. Returns `null` for unrecognized hosts.
+ */
+export function sanitizeRemoteUrl(remoteUrl: string): string | null {
+  // SSH format: git@host:owner/repo.git — no credentials possible.
+  for (const host of ALLOWED_HOSTS) {
+    if (remoteUrl.startsWith(`git@${host}:`)) return remoteUrl;
+  }
+
+  // HTTPS format: parse the hostname exactly and drop any userinfo.
+  let parsed: URL;
+  try {
+    parsed = new URL(remoteUrl);
+  } catch {
+    return null;
+  }
+  if ((ALLOWED_HOSTS as readonly string[]).includes(parsed.hostname)) {
+    const port = parsed.port ? `:${parsed.port}` : '';
+    return `https://${parsed.hostname}${port}${parsed.pathname}`;
+  }
+
+  return null;
+}
+
+/**
+ * Extract the project path from a git remote URL — `owner/repo`, or the full
+ * `group/subgroup/repo` for nested namespaces (e.g. GitLab subgroups).
+ * Supports scp-like SSH (`git@host:path`) and URL forms (`https://`, `ssh://`).
+ */
+export function parseProjectName(remoteUrl: string): string | null {
+  // scp-like SSH (`git@host:owner/.../repo.git`) is not a valid URL — match it
+  // directly; everything else goes through URL parsing. The whole path is kept
+  // so nested namespaces survive.
+  const scp = /^[^/]+@[^/:]+:(.+)$/.exec(remoteUrl);
+  const rawPath = scp?.[1] ?? tryUrlPath(remoteUrl);
+  if (rawPath === null) return null;
+  const project = rawPath.replace(/^\/+/, '').replace(/\/+$/, '').replace(/\.git$/, '');
+  return project.length > 0 ? project : null;
+}
+
+function tryUrlPath(remoteUrl: string): string | null {
+  try {
+    return new URL(remoteUrl).pathname;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run a single `git -C <cwd> <args>` command and return its trimmed stdout,
+ * or `null` on any failure (spawn error, non-zero exit, or timeout). The
+ * `git -C` form runs in the target directory regardless of the Kaos backend.
+ */
+async function runGit(kaos: Kaos, cwd: string, args: readonly string[]): Promise<string | null> {
+  let proc;
+  try {
+    proc = await kaos.exec('git', '-C', cwd, ...args);
+  } catch {
+    return null;
+  }
+
+  try {
+    proc.stdin.end();
+  } catch {
+    /* stdin already closed */
+  }
+
+  const work = Promise.all([collectStream(proc.stdout), proc.wait()]);
+  // Attach a rejection handler up front: if `work` rejects during the
+  // timeout-handling window (before the catch block re-awaits it), Node must
+  // not flag it as an unhandled rejection.
+  work.catch(() => {});
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timeout = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        reject(new Error(`git ${args.join(' ')} timed out`));
+      }, GIT_TIMEOUT_MS);
+    });
+    const [stdout, exitCode] = await Promise.race([work, timeout]);
+    if (exitCode !== 0) return null;
+    return stdout.trim();
+  } catch {
+    try {
+      await proc.kill('SIGKILL');
+    } catch {
+      /* process already gone */
+    }
+    // Let the stdout drain settle so the process resources are released,
+    // even though the timed-out output is discarded.
+    await work.catch(() => {});
+    return null;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+async function collectStream(stream: Readable): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as string));
+  }
+  return Buffer.concat(chunks).toString('utf-8');
+}
diff --git a/packages/agent-core/src/session/index.ts b/packages/agent-core/src/session/index.ts
new file mode 100644
index 000000000..b4c0adba5
--- /dev/null
+++ b/packages/agent-core/src/session/index.ts
@@ -0,0 +1,511 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { ErrorCodes, KimiError } from '#/errors';
+import { getRootLogger, log } from '#/logging/logger';
+import type { Logger, SessionLogHandle } from '#/logging/types';
+import type { SDKSessionRPC } from '#/rpc';
+import { proxyWithExtraPayload } from '#/rpc/types';
+
+import { Agent, type AgentConfig, type AgentType } from '../agent';
+import { HookEngine, type HookDef } from '../agent/hooks';
+import type { PermissionManagerOptions, PermissionRule } from '../agent/permission';
+import { parseBooleanEnv, resolveConfigValue, type BackgroundConfig } from '../config';
+import { makeErrorPayload } from '../errors';
+import {
+  McpConnectionManager,
+  McpOAuthService,
+  type McpServerEntry,
+  type SessionMcpConfig,
+} from '../mcp';
+import {
+  DEFAULT_AGENT_PROFILES,
+  DEFAULT_INIT_PROMPT,
+  loadAgentsMd,
+  prepareSystemPromptContext,
+  type ResolvedAgentProfile,
+} from '../profile';
+import type { ProviderManager } from '../providers/provider-manager';
+import type { RuntimeConfig } from '../runtime-types';
+import {
+  registerBuiltinSkills,
+  resolveSkillRoots,
+  SkillRegistry,
+  summarizeSkill,
+  type SkillSummary,
+} from '../skill';
+import { noopTelemetryClient, type TelemetryClient } from '../telemetry';
+import { SessionSubagentHost } from './subagent-host';
+
+export interface SessionConfig {
+  readonly runtime: RuntimeConfig;
+  readonly id?: string | undefined;
+  readonly homedir: string;
+  readonly kimiHomeDir?: string;
+  readonly rpc: SDKSessionRPC;
+  readonly cwd?: string;
+  readonly initializeMainAgent?: boolean | undefined;
+  readonly providerManager?: ProviderManager | undefined;
+  readonly background?: BackgroundConfig | undefined;
+  readonly hooks?: readonly HookDef[];
+  readonly permissionRules?: readonly PermissionRule[];
+  readonly skills?: SessionSkillConfig;
+  readonly mcpConfig?: SessionMcpConfig;
+  readonly telemetry?: TelemetryClient | undefined;
+}
+
+export interface SessionSkillConfig {
+  readonly userHomeDir?: string;
+  readonly explicitDirs?: readonly string[];
+  readonly extraDirs?: readonly string[];
+  readonly mergeAllAvailableSkills?: boolean;
+  readonly builtinDir?: string;
+}
+
+export interface AgentMeta {
+  readonly homedir: string;
+  readonly type: AgentType;
+  readonly parentAgentId: string | null;
+}
+
+export interface SessionMeta {
+  createdAt: string;
+  updatedAt: string;
+  title: string;
+  isCustomTitle: boolean;
+  lastPrompt?: string;
+  forkedFrom?: string;
+  agents: Record<string, AgentMeta>;
+  custom: Record<string, any>;
+}
+
+const BACKGROUND_KEEP_ALIVE_ON_EXIT_ENV = 'KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT';
+
+export class Session {
+  readonly rpc: SDKSessionRPC;
+  readonly telemetry: TelemetryClient;
+  readonly skills: SkillRegistry;
+  readonly agents: Map<string, Agent> = new Map();
+  readonly mcp: McpConnectionManager;
+  readonly log: Logger;
+  private readonly logHandle: SessionLogHandle | undefined;
+  readonly hookEngine: HookEngine;
+  private agentIdCounter = 0;
+  private readonly skillsReady: Promise<void>;
+  metadata: SessionMeta = {
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    title: 'New Session',
+    isCustomTitle: false,
+    agents: {},
+    custom: {},
+  };
+  private writeMetadataPromise = Promise.resolve();
+
+  constructor(public readonly config: SessionConfig) {
+    // Attach the per-session log sink up front so the constructor's
+    // fire-and-forget `loadSkills` / `loadMcpServers` failures (and
+    // anything else that races) land in the session log, not just global.
+    this.logHandle =
+      config.id === undefined
+        ? undefined
+        : getRootLogger().attachSession({
+            sessionId: config.id,
+            sessionDir: config.homedir,
+          });
+    this.log =
+      this.logHandle?.logger ??
+      (config.id === undefined ? log : log.createChild({ sessionId: config.id }));
+    this.rpc = config.rpc;
+    this.hookEngine = new HookEngine(config.hooks, {
+      cwd: config.cwd,
+      sessionId: config.id,
+    });
+    this.telemetry = config.telemetry ?? noopTelemetryClient;
+    this.skills = new SkillRegistry({ sessionId: config.id });
+    this.mcp = new McpConnectionManager({
+      oauthService: new McpOAuthService({ kimiHomeDir: config.kimiHomeDir }),
+      log: this.log,
+    });
+    this.mcp.onStatusChange((entry) => {
+      this.onMcpServerStatusChange(entry);
+    });
+    this.skillsReady = this.loadSkills()
+      .catch((error: unknown) => {
+        this.log.error('skills load failed', error);
+      })
+      .then(() => {
+        this.refreshAgentBuiltinTools();
+      });
+    void this.loadMcpServers().catch((error: unknown) => {
+      this.emitInitialMcpLoadError(error);
+    });
+  }
+
+  async createMain() {
+    const { agent } = await this.createAgent({ type: 'main' }, DEFAULT_AGENT_PROFILES['agent']);
+    await this.triggerSessionStart('startup');
+    return agent;
+  }
+
+  async resume() {
+    await this.skillsReady;
+    const { agents } = await this.readMetadata();
+    this.agents.clear();
+    const resumeTasks = Object.keys(agents).map(async (id) => {
+      const agent = this.ensureResumeAgentInstantiated(id, agents);
+      await agent.resume();
+    });
+    await Promise.all(resumeTasks);
+    // A session migrated from an external tool ships a wire without the
+    // `config.update` bootstrap events a natively-created agent writes, so the
+    // main agent comes back with an empty system prompt and no tools. Apply the
+    // default profile so the resumed session is usable. Native sessions always
+    // replay a non-empty system prompt and never enter this branch.
+    const main = this.agents.get('main');
+    const profile = DEFAULT_AGENT_PROFILES['agent'];
+    if (main !== undefined && profile !== undefined && main.config.systemPrompt === '') {
+      await this.bootstrapAgentProfile(main, profile);
+    }
+    await this.triggerSessionStart('resume');
+  }
+
+  async close(): Promise<void> {
+    try {
+      await this.stopBackgroundTasksOnExit();
+      await this.flushMetadata();
+      await this.triggerSessionEnd('exit');
+    } finally {
+      try {
+        await this.mcp.shutdown();
+      } finally {
+        await this.logHandle?.close();
+      }
+    }
+  }
+
+  private async stopBackgroundTasksOnExit(): Promise<void> {
+    const keepAliveOnExit = resolveConfigValue({
+      env: process.env,
+      envKey: BACKGROUND_KEEP_ALIVE_ON_EXIT_ENV,
+      configValue: this.config.background?.keepAliveOnExit,
+      defaultValue: true,
+      parseEnv: parseBooleanEnv,
+    });
+    if (keepAliveOnExit) return;
+    await Promise.all(
+      Array.from(this.agents.values(), (agent) =>
+        agent.background.stopAll('Session closed'),
+      ),
+    );
+  }
+
+  async createAgent(
+    config: Partial<AgentConfig>,
+    profile?: ResolvedAgentProfile,
+    parentAgentId?: string | undefined,
+  ): Promise<{ readonly id: string; readonly agent: Agent }> {
+    await this.skillsReady;
+    const type = config.type ?? 'main';
+    const id = type === 'main' ? 'main' : this.nextGeneratedAgentId();
+    const homedir = config.homedir ?? join(this.config.homedir, 'agents', id);
+    const agent = this.instantiateAgent(id, homedir, type, config, parentAgentId ?? null);
+    if (profile) {
+      await this.bootstrapAgentProfile(agent, profile);
+    } else if (this.config.cwd !== undefined) {
+      agent.config.update({ cwd: this.config.cwd });
+    }
+
+    this.agents.set(id, agent);
+    this.metadata.agents[id] = {
+      homedir,
+      type,
+      parentAgentId: parentAgentId ?? null,
+    };
+    void this.writeMetadata();
+
+    return { id, agent };
+  }
+
+  /**
+   * Applies a profile's derived config — cwd, system prompt, active tools — to
+   * an agent. Fresh creation and resume-of-an-incomplete-wire both route
+   * through here so the two paths cannot drift apart.
+   */
+  private async bootstrapAgentProfile(
+    agent: Agent,
+    profile: ResolvedAgentProfile,
+  ): Promise<void> {
+    if (this.config.cwd !== undefined) {
+      agent.config.update({ cwd: this.config.cwd });
+    }
+    const context = await prepareSystemPromptContext(this.config.runtime.kaos, agent.config.cwd);
+    agent.useProfile(profile, context);
+  }
+
+  async generateAgentsMd(): Promise<void> {
+    await this.skillsReady;
+    const mainAgent = this.requireMainAgent();
+
+    try {
+      const handle = await mainAgent.subagentHost!.spawn('coder', {
+        parentToolCallId: 'generate-agents-md',
+        prompt: DEFAULT_INIT_PROMPT,
+        description: 'Initialize AGENTS.md',
+        runInBackground: false,
+        origin: { kind: 'system_trigger', name: 'init' },
+        signal: new AbortController().signal,
+      });
+      await handle.completion;
+
+      const agentsMd = await loadAgentsMd(this.config.runtime.kaos, mainAgent.config.cwd);
+      mainAgent.context.appendSystemReminder(initCompletionReminder(agentsMd), {
+        kind: 'injection',
+        variant: 'init',
+      });
+      await mainAgent.records.flush();
+    } catch (error) {
+      throw new KimiError(
+        ErrorCodes.SESSION_INIT_FAILED,
+        error instanceof Error ? error.message : 'Init failed',
+        { cause: error },
+      );
+    }
+  }
+
+  get hasActiveTurn(): boolean {
+    for (const agent of this.agents.values()) {
+      if (agent.turn.hasActiveTurn) return true;
+    }
+    return false;
+  }
+
+  protected get metadataPath() {
+    return join(this.config.homedir, 'state.json');
+  }
+
+  writeMetadata() {
+    const text = JSON.stringify(this.metadata, null, 2);
+    const write = async () => {
+      await this.config.runtime.kaos.mkdir(this.config.homedir, { parents: true, existOk: true });
+      await this.config.runtime.kaos.writeText(this.metadataPath, text);
+    };
+    this.writeMetadataPromise = this.writeMetadataPromise.then(write, write);
+    return this.writeMetadataPromise;
+  }
+
+  async readMetadata() {
+    const text = await this.config.runtime.kaos.readText(this.metadataPath);
+    this.metadata = JSON.parse(text);
+    return this.metadata;
+  }
+
+  async flushMetadata() {
+    await this.skillsReady;
+    await this.writeMetadataPromise;
+    await Promise.all(Array.from(this.agents.values()).map((agent) => agent.records.flush()));
+  }
+
+  async listSkills(): Promise<readonly SkillSummary[]> {
+    await this.skillsReady;
+    return this.skills.listSkills().map(summarizeSkill);
+  }
+
+  private async loadSkills(): Promise<void> {
+    const roots = await resolveSkillRoots({
+      paths: {
+        userHomeDir: this.config.skills?.userHomeDir ?? homedir(),
+        workDir: this.config.cwd ?? process.cwd(),
+      },
+      explicitDirs: this.config.skills?.explicitDirs,
+      extraDirs: this.config.skills?.extraDirs,
+      mergeAllAvailableSkills: this.config.skills?.mergeAllAvailableSkills,
+      builtinDir: this.config.skills?.builtinDir,
+    });
+    await this.skills.loadRoots(roots);
+    registerBuiltinSkills(this.skills);
+  }
+
+  private async loadMcpServers(): Promise<void> {
+    const servers = this.config.mcpConfig?.servers;
+    if (servers === undefined || Object.keys(servers).length === 0) return;
+    await this.mcp.connectAll(servers);
+    const entries = this.mcp.list().filter((entry) => entry.status !== 'disabled');
+    const totalCount = entries.length;
+    if (totalCount === 0) return;
+
+    const connectedCount = entries.filter((entry) => entry.status === 'connected').length;
+    if (connectedCount > 0) {
+      this.telemetry.track('mcp_connected', {
+        server_count: connectedCount,
+        total_count: totalCount,
+      });
+    }
+
+    const failedCount = entries.filter((entry) => entry.status === 'failed').length;
+    if (failedCount > 0) {
+      this.telemetry.track('mcp_failed', {
+        failed_count: failedCount,
+        total_count: totalCount,
+      });
+    }
+  }
+
+  private emitInitialMcpLoadError(error: unknown): void {
+    const message = error instanceof Error ? error.message : String(error);
+    this.log.error('mcp initial load failed', error);
+    void this.rpc.emitEvent({
+      type: 'error',
+      agentId: 'main',
+      ...makeErrorPayload(ErrorCodes.MCP_STARTUP_FAILED, message),
+    });
+  }
+
+  private onMcpServerStatusChange(entry: McpServerEntry): void {
+    // Always surface server-level status changes to clients so the TUI/SDK
+    // can keep its dashboard in sync, even before the main agent exists.
+    void this.rpc.emitEvent({
+      type: 'mcp.server.status',
+      agentId: 'main',
+      server: {
+        name: entry.name,
+        transport: entry.transport,
+        status: entry.status,
+        toolCount: entry.toolCount,
+        error: entry.error,
+      },
+    });
+  }
+
+  private backgroundTaskTimeoutMs(): number | undefined {
+    const timeoutS = this.config.background?.agentTaskTimeoutS;
+    return timeoutS === undefined ? undefined : timeoutS * 1000;
+  }
+
+  private refreshAgentBuiltinTools(): void {
+    for (const agent of this.agents.values()) {
+      if (!agent.config.hasProvider) continue;
+      agent.tools.initializeBuiltinTools();
+    }
+  }
+
+  private instantiateAgent(
+    id: string,
+    homedir: string,
+    type: AgentType,
+    config: Partial<AgentConfig> = {},
+    parentAgentId: string | null = null,
+  ): Agent {
+    return new Agent({
+      ...config,
+      type,
+      runtime: this.config.runtime,
+      homedir,
+      skills: this.skills,
+      rpc: proxyWithExtraPayload(this.rpc, { agentId: id }),
+      providerManager: this.config.providerManager,
+      sessionId: this.config.id,
+      hookEngine: config.hookEngine ?? this.hookEngine,
+      subagentHost:
+        config.subagentHost ?? new SessionSubagentHost(this, id, this.backgroundTaskTimeoutMs()),
+      mcp: this.mcp,
+      backgroundMaxRunningTasks: this.config.background?.maxRunningTasks,
+      backgroundSessionDir: homedir,
+      permission: this.permissionOptions(parentAgentId, config.permission),
+      telemetry: this.telemetry,
+      log: this.log.createChild({ agentId: id }),
+    });
+  }
+
+  private permissionOptions(
+    parentAgentId: string | null,
+    input?: PermissionManagerOptions | undefined,
+  ): PermissionManagerOptions {
+    if (parentAgentId === null) {
+      return {
+        ...input,
+        initialRules: input?.initialRules ?? this.config.permissionRules,
+      };
+    }
+    return {
+      ...input,
+      parent: input?.parent ?? this.agents.get(parentAgentId)?.permission,
+    };
+  }
+
+  private ensureResumeAgentInstantiated(
+    id: string,
+    agents: Record<string, AgentMeta>,
+    stack: readonly string[] = [],
+  ): Agent {
+    const existing = this.agents.get(id);
+    if (existing !== undefined) return existing;
+    if (stack.includes(id)) {
+      throw new KimiError(
+        ErrorCodes.SESSION_STATE_INVALID,
+        `Session agent parent chain contains a cycle: ${[...stack, id].join(' -> ')}`,
+      );
+    }
+
+    const meta = agents[id];
+    if (meta === undefined) {
+      throw new KimiError(ErrorCodes.SESSION_STATE_INVALID, `Session agent "${id}" is missing`);
+    }
+
+    const parentAgentId = meta.parentAgentId ?? null;
+    if (parentAgentId !== null) {
+      this.ensureResumeAgentInstantiated(parentAgentId, agents, [...stack, id]);
+    }
+
+    const agent = this.instantiateAgent(id, meta.homedir, meta.type, {}, parentAgentId);
+    this.agents.set(id, agent);
+    return agent;
+  }
+
+  private nextGeneratedAgentId(): string {
+    while (true) {
+      const id = `agent-${this.agentIdCounter++}`;
+      if (this.agents.has(id)) continue;
+      if (this.metadata.agents[id] !== undefined) continue;
+      return id;
+    }
+  }
+
+  private requireMainAgent(): Agent {
+    const agent = this.agents.get('main');
+    if (agent === undefined) {
+      throw new KimiError(ErrorCodes.AGENT_NOT_FOUND, 'Main agent was not found');
+    }
+    return agent;
+  }
+
+  private async triggerSessionStart(source: 'startup' | 'resume'): Promise<void> {
+    await this.hookEngine.trigger('SessionStart', {
+      matcherValue: source,
+      inputData: { source },
+    });
+  }
+
+  private async triggerSessionEnd(reason: 'exit'): Promise<void> {
+    await this.hookEngine.trigger('SessionEnd', {
+      matcherValue: reason,
+      inputData: { reason },
+    });
+  }
+}
+
+export * from './subagent-host';
+
+function initCompletionReminder(agentsMd: string): string {
+  const latest =
+    agentsMd.trim().length === 0
+      ? 'No AGENTS.md content was found after `/init` completed.'
+      : agentsMd;
+  return [
+    'The user just ran `/init` slash command.',
+    'The system has analyzed the codebase and generated an `AGENTS.md` file.',
+    '',
+    'Latest AGENTS.md file content:',
+    latest,
+  ].join('\n');
+}
diff --git a/packages/agent-core/src/session/prompt-metadata.ts b/packages/agent-core/src/session/prompt-metadata.ts
new file mode 100644
index 000000000..94b417346
--- /dev/null
+++ b/packages/agent-core/src/session/prompt-metadata.ts
@@ -0,0 +1,62 @@
+import type { ActivateSkillPayload, PromptPayload } from '#/rpc';
+import type { ContentPart } from '@moonshot-ai/kosong';
+
+const MAX_TITLE_LENGTH = 200;
+const MAX_LAST_PROMPT_LENGTH = 4000;
+
+export function titleFromPromptMetadataText(text: string): string {
+  return text.slice(0, MAX_TITLE_LENGTH);
+}
+
+export function promptMetadataTextFromPayload(payload: PromptPayload): string | undefined {
+  const parts: string[] = [];
+  for (const part of payload.input) {
+    const text = promptPartText(part);
+    if (text !== undefined) parts.push(text);
+  }
+  return sanitizeAndTruncatePromptText(parts.join('\n'), MAX_LAST_PROMPT_LENGTH);
+}
+
+export function promptMetadataTextFromSkill(payload: ActivateSkillPayload): string | undefined {
+  const args = payload.args?.trim();
+  return sanitizeAndTruncatePromptText(
+    args === undefined || args.length === 0 ? `/${payload.name}` : `/${payload.name} ${args}`,
+    MAX_LAST_PROMPT_LENGTH,
+  );
+}
+
+function promptPartText(part: ContentPart): string | undefined {
+  switch (part.type) {
+    case 'text':
+      return part.text;
+    case 'image_url':
+      return '[image]';
+    case 'audio_url':
+      return '[audio]';
+    case 'video_url':
+      return '[video]';
+    case 'think':
+      return undefined;
+  }
+}
+
+function sanitizeAndTruncatePromptText(text: string, maxLength: number): string | undefined {
+  const sanitized = text
+    .replaceAll(
+      /-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?-----END [^-]*PRIVATE KEY-----/gi,
+      '[redacted]',
+    )
+    .replaceAll(/\b(authorization)\s*:\s*bearer\s+\S+/gi, '$1: Bearer [redacted]')
+    .replaceAll(
+      /\b(api[_-]?key|token|secret|password|passwd|pwd)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/gi,
+      '$1=[redacted]',
+    )
+    .replaceAll(/\bsk-[A-Za-z0-9_-]{12,}\b/g, '[redacted]')
+    .replaceAll(/\b[A-Za-z0-9][A-Za-z0-9+/=_-]{39,}\b/g, '[redacted]')
+    .replaceAll(/\p{Cc}+/gu, ' ')
+    .replaceAll(/\s+/g, ' ')
+    .trim();
+
+  if (sanitized.length === 0) return undefined;
+  return sanitized.slice(0, maxLength);
+}
diff --git a/packages/agent-core/src/session/rpc.ts b/packages/agent-core/src/session/rpc.ts
new file mode 100644
index 000000000..be5eac82b
--- /dev/null
+++ b/packages/agent-core/src/session/rpc.ts
@@ -0,0 +1,261 @@
+import { ErrorCodes, KimiError } from '#/errors';
+import type {
+  ActivateSkillPayload,
+  AgentAPI,
+  BeginCompactionPayload,
+  CancelPayload,
+  CancelPlanPayload,
+  EmptyPayload,
+  GetBackgroundOutputPathPayload,
+  GetBackgroundOutputPayload,
+  GetBackgroundPayload,
+  McpServerInfo,
+  McpStartupMetrics,
+  PromptPayload,
+  ReconnectMcpServerPayload,
+  RenameSessionPayload,
+  RegisterToolPayload,
+  SessionAPI,
+  SetActiveToolsPayload,
+  SetModelPayload,
+  SetPermissionPayload,
+  SetThinkingPayload,
+  SkillSummary,
+  SteerPayload,
+  StopBackgroundPayload,
+  UnregisterToolPayload,
+  UpdateSessionMetadataPayload,
+} from '#/rpc';
+import type { PromisableMethods } from '#/utils/types';
+
+import type { Session, SessionMeta } from '.';
+import {
+  promptMetadataTextFromPayload,
+  promptMetadataTextFromSkill,
+  titleFromPromptMetadataText,
+} from './prompt-metadata';
+
+type AgentScopedPayload<T> = T & { agentId: string };
+
+export class SessionAPIImpl implements PromisableMethods<SessionAPI> {
+  constructor(protected readonly session: Session) {}
+
+  async renameSession(payload: RenameSessionPayload): Promise<void> {
+    const title = payload.title.trim();
+    if (title.length === 0) {
+      throw new KimiError(ErrorCodes.SESSION_TITLE_EMPTY, 'Session title cannot be empty');
+    }
+    this.session.metadata = {
+      ...this.session.metadata,
+      title,
+      isCustomTitle: true,
+      updatedAt: new Date().toISOString(),
+    };
+    await this.session.writeMetadata();
+  }
+
+  async updateSessionMetadata(payload: UpdateSessionMetadataPayload): Promise<void> {
+    this.session.metadata = {
+      ...this.session.metadata,
+      ...payload.metadata,
+      agents: this.session.metadata.agents,
+    };
+    await this.session.writeMetadata();
+  }
+
+  getSessionMetadata(_payload: EmptyPayload): SessionMeta {
+    return this.session.metadata;
+  }
+
+  listSkills(_payload: EmptyPayload): Promise<readonly SkillSummary[]> {
+    return this.session.listSkills();
+  }
+
+  listMcpServers(_payload: EmptyPayload): readonly McpServerInfo[] {
+    return this.session.mcp.list();
+  }
+
+  async getMcpStartupMetrics(_payload: EmptyPayload): Promise<McpStartupMetrics> {
+    await this.session.mcp.waitForInitialLoad();
+    return { durationMs: this.session.mcp.initialLoadDurationMs() };
+  }
+
+  async reconnectMcpServer(payload: ReconnectMcpServerPayload): Promise<void> {
+    await this.session.mcp.reconnect(payload.name);
+  }
+
+  generateAgentsMd(_payload: EmptyPayload): Promise<void> {
+    return this.session.generateAgentsMd();
+  }
+
+  async prompt({ agentId, ...payload }: AgentScopedPayload<PromptPayload>) {
+    if (agentId === 'main') {
+      await this.updatePromptMetadata(promptMetadataTextFromPayload(payload));
+    }
+    return this.getAgent(agentId).prompt(payload);
+  }
+
+  steer({ agentId, ...payload }: AgentScopedPayload<SteerPayload>) {
+    return this.getAgent(agentId).steer(payload);
+  }
+
+  cancel({ agentId, ...payload }: AgentScopedPayload<CancelPayload>) {
+    return this.getAgent(agentId).cancel(payload);
+  }
+
+  setModel({ agentId, ...payload }: AgentScopedPayload<SetModelPayload>) {
+    return this.getAgent(agentId).setModel(payload);
+  }
+
+  setThinking({ agentId, ...payload }: AgentScopedPayload<SetThinkingPayload>) {
+    return this.getAgent(agentId).setThinking(payload);
+  }
+
+  setPermission({ agentId, ...payload }: AgentScopedPayload<SetPermissionPayload>) {
+    return this.getAgent(agentId).setPermission(payload);
+  }
+
+  getModel({ agentId, ...payload }: AgentScopedPayload<EmptyPayload>) {
+    return this.getAgent(agentId).getModel(payload);
+  }
+
+  enterPlan({ agentId, ...payload }: AgentScopedPayload<EmptyPayload>) {
+    return this.getAgent(agentId).enterPlan(payload);
+  }
+
+  cancelPlan({ agentId, ...payload }: AgentScopedPayload<CancelPlanPayload>) {
+    return this.getAgent(agentId).cancelPlan(payload);
+  }
+
+  clearPlan({ agentId, ...payload }: AgentScopedPayload<EmptyPayload>) {
+    return this.getAgent(agentId).clearPlan(payload);
+  }
+
+  beginCompaction({ agentId, ...payload }: AgentScopedPayload<BeginCompactionPayload>) {
+    return this.getAgent(agentId).beginCompaction(payload);
+  }
+
+  cancelCompaction({ agentId, ...payload }: AgentScopedPayload<EmptyPayload>) {
+    return this.getAgent(agentId).cancelCompaction(payload);
+  }
+
+  registerTool({ agentId, ...payload }: AgentScopedPayload<RegisterToolPayload>) {
+    return this.getAgent(agentId).registerTool(payload);
+  }
+
+  unregisterTool({ agentId, ...payload }: AgentScopedPayload<UnregisterToolPayload>) {
+    return this.getAgent(agentId).unregisterTool(payload);
+  }
+
+  setActiveTools({ agentId, ...payload }: AgentScopedPayload<SetActiveToolsPayload>) {
+    return this.getAgent(agentId).setActiveTools(payload);
+  }
+
+  stopBackground({ agentId, ...payload }: AgentScopedPayload<StopBackgroundPayload>) {
+    return this.getAgent(agentId).stopBackground(payload);
+  }
+
+  clearContext({ agentId, ...payload }: AgentScopedPayload<EmptyPayload>) {
+    return this.getAgent(agentId).clearContext(payload);
+  }
+
+  async activateSkill({ agentId, ...payload }: AgentScopedPayload<ActivateSkillPayload>) {
+    await this.getAgent(agentId).activateSkill(payload);
+    if (agentId === 'main') {
+      await this.updatePromptMetadata(promptMetadataTextFromSkill(payload));
+    }
+  }
+
+  getBackgroundOutput({ agentId, ...payload }: AgentScopedPayload<GetBackgroundOutputPayload>) {
+    return this.getAgent(agentId).getBackgroundOutput(payload);
+  }
+
+  getBackgroundOutputPath({
+    agentId,
+    ...payload
+  }: AgentScopedPayload<GetBackgroundOutputPathPayload>) {
+    return this.getAgent(agentId).getBackgroundOutputPath(payload);
+  }
+
+  getContext({ agentId, ...payload }: AgentScopedPayload<EmptyPayload>) {
+    return this.getAgent(agentId).getContext(payload);
+  }
+
+  getConfig({ agentId, ...payload }: AgentScopedPayload<EmptyPayload>) {
+    return this.getAgent(agentId).getConfig(payload);
+  }
+
+  getPermission({ agentId, ...payload }: AgentScopedPayload<EmptyPayload>) {
+    return this.getAgent(agentId).getPermission(payload);
+  }
+
+  getPlan({ agentId, ...payload }: AgentScopedPayload<EmptyPayload>) {
+    return this.getAgent(agentId).getPlan(payload);
+  }
+
+  getUsage({ agentId, ...payload }: AgentScopedPayload<EmptyPayload>) {
+    return this.getAgent(agentId).getUsage(payload);
+  }
+
+  getTools({ agentId, ...payload }: AgentScopedPayload<EmptyPayload>) {
+    return this.getAgent(agentId).getTools(payload);
+  }
+
+  getBackground({ agentId, ...payload }: AgentScopedPayload<GetBackgroundPayload>) {
+    return this.getAgent(agentId).getBackground(payload);
+  }
+
+  private getAgent(agentId: string): PromisableMethods<AgentAPI> {
+    const agent = this.session.agents.get(agentId);
+    if (agent === undefined) {
+      throw new KimiError(ErrorCodes.AGENT_NOT_FOUND, `Agent "${agentId}" was not found`);
+    }
+    return agent.rpcMethods;
+  }
+
+  private needUpdateEasyTitle(metadata: SessionMeta): boolean {
+    if (hasCustomTitle(metadata)) return false;
+    if (!isUntitled(metadata.title)) return false;
+    return true;
+  }
+
+  private async updatePromptMetadata(lastPrompt: string | undefined): Promise<void> {
+    if (lastPrompt === undefined) return;
+
+    const title = this.needUpdateEasyTitle(this.session.metadata)
+      ? titleFromPromptMetadataText(lastPrompt)
+      : undefined;
+    const now = new Date().toISOString();
+    const nextMetadata = {
+      ...this.session.metadata,
+      lastPrompt,
+      updatedAt: now,
+    };
+    if (title !== undefined) {
+      nextMetadata.title = title;
+      nextMetadata.isCustomTitle = false;
+    }
+
+    this.session.metadata = nextMetadata;
+    await this.session.writeMetadata();
+    await this.session.rpc.emitEvent({
+      type: 'session.meta.updated',
+      agentId: 'main',
+      title,
+      patch: {
+        title,
+        isCustomTitle: title === undefined ? undefined : false,
+        lastPrompt,
+      },
+    });
+  }
+}
+
+function isUntitled(title: unknown): boolean {
+  return typeof title !== 'string' || title.trim().length === 0 || title === 'New Session';
+}
+
+function hasCustomTitle(metadata: SessionMeta): boolean {
+  if (metadata.isCustomTitle) return true;
+  return typeof (metadata as SessionMeta & { customTitle?: unknown }).customTitle === 'string';
+}
diff --git a/packages/agent-core/src/session/store/index.ts b/packages/agent-core/src/session/store/index.ts
new file mode 100644
index 000000000..54bba0465
--- /dev/null
+++ b/packages/agent-core/src/session/store/index.ts
@@ -0,0 +1,8 @@
+export { SessionStore } from '#/session/store/session-store';
+export type {
+  CreateSessionRecordInput,
+  ForkSessionRecordInput,
+  SessionStoreOptions,
+} from '#/session/store/session-store';
+export { sessionIndexPath } from '#/session/store/session-index';
+export { encodeWorkDirKey, normalizeWorkDir } from '#/session/store/workdir-key';
diff --git a/packages/agent-core/src/session/store/session-index.ts b/packages/agent-core/src/session/store/session-index.ts
new file mode 100644
index 000000000..6b77ed007
--- /dev/null
+++ b/packages/agent-core/src/session/store/session-index.ts
@@ -0,0 +1,79 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+export interface SessionIndexEntry {
+  readonly sessionId: string;
+  readonly sessionDir: string;
+  readonly workDir: string;
+}
+
+export function sessionIndexPath(homeDir: string): string {
+  return join(homeDir, 'session_index.jsonl');
+}
+
+export async function appendSessionIndexEntry(
+  homeDir: string,
+  entry: SessionIndexEntry,
+): Promise<void> {
+  const indexPath = sessionIndexPath(homeDir);
+  await mkdir(dirname(indexPath), { recursive: true, mode: 0o700 });
+  await appendFile(indexPath, `${JSON.stringify(entry)}\n`, 'utf-8');
+}
+
+export async function readSessionIndex(
+  homeDir: string,
+  sessionsDir: string,
+): Promise<Map<string, SessionIndexEntry>> {
+  let raw: string;
+  try {
+    raw = await readFile(sessionIndexPath(homeDir), 'utf-8');
+  } catch {
+    return new Map();
+  }
+
+  const result = new Map<string, SessionIndexEntry>();
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    const entry = parseIndexLine(trimmed);
+    if (entry === undefined) continue;
+    const sessionDir = resolve(entry.sessionDir);
+    if (!isAbsolute(entry.sessionDir)) continue;
+    if (!isAbsolute(entry.workDir)) continue;
+    if (!isPathInside(sessionsDir, sessionDir)) continue;
+    if (basename(sessionDir) !== entry.sessionId) continue;
+    result.set(entry.sessionId, {
+      sessionId: entry.sessionId,
+      sessionDir,
+      workDir: resolve(entry.workDir),
+    });
+  }
+  return result;
+}
+
+function parseIndexLine(line: string): SessionIndexEntry | undefined {
+  try {
+    const parsed = JSON.parse(line) as unknown;
+    if (typeof parsed !== 'object' || parsed === null) return undefined;
+    const entry = parsed as Partial<SessionIndexEntry>;
+    if (
+      typeof entry.sessionId !== 'string' ||
+      typeof entry.sessionDir !== 'string' ||
+      typeof entry.workDir !== 'string'
+    ) {
+      return undefined;
+    }
+    return {
+      sessionId: entry.sessionId,
+      sessionDir: entry.sessionDir,
+      workDir: entry.workDir,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function isPathInside(parent: string, child: string): boolean {
+  const rel = relative(resolve(parent), resolve(child));
+  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
diff --git a/packages/agent-core/src/session/store/session-store.ts b/packages/agent-core/src/session/store/session-store.ts
new file mode 100644
index 000000000..88a1bfcd0
--- /dev/null
+++ b/packages/agent-core/src/session/store/session-store.ts
@@ -0,0 +1,366 @@
+import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+
+import { z } from 'zod';
+
+import { ErrorCodes, KimiError } from '#/errors';
+import type { SessionIndexEntry } from '#/session/store/session-index';
+import { appendSessionIndexEntry, readSessionIndex } from '#/session/store/session-index';
+import { encodeWorkDirKey, normalizeWorkDir } from '#/session/store/workdir-key';
+import type { JsonObject, ListSessionsPayload, SessionSummary } from '#/rpc/core-api';
+
+const SessionSummaryStateSchema = z.object({
+  customTitle: z.string().optional(),
+  isCustomTitle: z.boolean().optional(),
+  lastPrompt: z.string().optional(),
+  title: z.string().optional(),
+  custom: z.record(z.string(), z.unknown()).optional(),
+});
+
+type SessionSummaryState = z.infer<typeof SessionSummaryStateSchema>;
+
+export interface CreateSessionRecordInput {
+  readonly id: string;
+  readonly workDir: string;
+}
+
+export interface ForkSessionRecordInput {
+  readonly sourceId: string;
+  readonly targetId: string;
+  readonly title?: string;
+  readonly metadata?: JsonObject;
+}
+
+export type SessionStoreOptions = Record<string, never>;
+
+export class SessionStore {
+  readonly sessionsDir: string;
+
+  constructor(
+    readonly homeDir: string,
+    _options: SessionStoreOptions = {},
+  ) {
+    this.sessionsDir = join(homeDir, 'sessions');
+  }
+
+  sessionDirFor(input: { readonly id: string; readonly workDir: string }): string {
+    assertSafeSessionId(input.id);
+    return join(this.sessionsDir, encodeWorkDirKey(normalizeWorkDir(input.workDir)), input.id);
+  }
+
+  async create(input: CreateSessionRecordInput): Promise<SessionSummary> {
+    assertSafeSessionId(input.id);
+    const workDir = normalizeWorkDir(input.workDir);
+    const indexed = await this.findSessionEntry(input.id);
+    if (indexed !== undefined) {
+      throw new KimiError(ErrorCodes.SESSION_ALREADY_EXISTS, `Session "${input.id}" already exists`);
+    }
+
+    const dir = this.sessionDirFor({ id: input.id, workDir });
+    if (await isDirectory(dir)) {
+      throw new KimiError(ErrorCodes.SESSION_ALREADY_EXISTS, `Session "${input.id}" already exists`);
+    }
+
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await appendSessionIndexEntry(this.homeDir, {
+      sessionId: input.id,
+      sessionDir: dir,
+      workDir,
+    });
+    return this.summaryFromDir(input.id, dir, workDir);
+  }
+
+  async fork(input: ForkSessionRecordInput): Promise<SessionSummary> {
+    const source = await this.findExistingSessionEntry(input.sourceId);
+    assertSafeSessionId(input.targetId);
+    const indexed = await this.findSessionEntry(input.targetId);
+    if (indexed !== undefined) {
+      throw new KimiError(ErrorCodes.SESSION_ALREADY_EXISTS, `Session "${input.targetId}" already exists`);
+    }
+
+    const targetDir = this.sessionDirFor({ id: input.targetId, workDir: source.workDir });
+    if (await isDirectory(targetDir)) {
+      throw new KimiError(ErrorCodes.SESSION_ALREADY_EXISTS, `Session "${input.targetId}" already exists`);
+    }
+
+    await mkdir(dirname(targetDir), { recursive: true, mode: 0o700 });
+    try {
+      await cp(source.sessionDir, targetDir, {
+        recursive: true,
+        force: false,
+        errorOnExist: true,
+      });
+      await this.writeForkedState(input, source.sessionDir, targetDir);
+      const summary = await this.summaryFromDir(input.targetId, targetDir, source.workDir);
+      await appendSessionIndexEntry(this.homeDir, {
+        sessionId: input.targetId,
+        sessionDir: targetDir,
+        workDir: source.workDir,
+      });
+      return summary;
+    } catch (error) {
+      await rm(targetDir, { recursive: true, force: true }).catch(() => {});
+      throw error;
+    }
+  }
+
+  async get(id: string): Promise<SessionSummary> {
+    const entry = await this.findExistingSessionEntry(id);
+    return this.summaryFromDir(id, entry.sessionDir, entry.workDir);
+  }
+
+  async rename(id: string, title: string): Promise<void> {
+    const normalized = title.trim();
+    if (normalized.length === 0) {
+      throw new KimiError(ErrorCodes.SESSION_TITLE_EMPTY, 'Session title cannot be empty');
+    }
+    const entry = await this.findExistingSessionEntry(id);
+    const statePath = join(entry.sessionDir, 'state.json');
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(await readFile(statePath, 'utf-8')) as unknown;
+    } catch (error) {
+      throw new KimiError(ErrorCodes.SESSION_STATE_NOT_FOUND, `Session "${id}" state.json was not found`, {
+        cause: error,
+      });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      throw new KimiError(ErrorCodes.SESSION_STATE_INVALID, `Session "${id}" state.json is invalid`);
+    }
+    const next: Record<string, unknown> = {
+      ...(parsed as Record<string, unknown>),
+      title: normalized,
+      isCustomTitle: true,
+    };
+    await writeFile(statePath, `${JSON.stringify(next, null, 2)}\n`, 'utf-8');
+  }
+
+  async list(options: ListSessionsPayload): Promise<readonly SessionSummary[]> {
+    const workDir = normalizeWorkDir(options.workDir);
+    const bucketDir = join(this.sessionsDir, encodeWorkDirKey(workDir));
+    let entries;
+    try {
+      entries = await readdir(bucketDir, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+
+    const sessions: SessionSummary[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const id = entry.name;
+      if (!isSafeSessionId(id)) continue;
+      const dir = join(bucketDir, id);
+      sessions.push(await this.summaryFromDir(id, dir, workDir));
+    }
+    sessions.sort(compareSessionSummary);
+    return sessions;
+  }
+
+  async assertDirectory(id: string): Promise<string> {
+    return (await this.findExistingSessionEntry(id)).sessionDir;
+  }
+
+  private async findSessionEntry(id: string): Promise<SessionIndexEntry | undefined> {
+    if (!isSafeSessionId(id)) return undefined;
+    const index = await readSessionIndex(this.homeDir, this.sessionsDir);
+    return index.get(id);
+  }
+
+  private async findExistingSessionEntry(id: string): Promise<SessionIndexEntry> {
+    const entry = await this.findSessionEntry(id);
+    if (entry !== undefined && (await isDirectory(entry.sessionDir))) return entry;
+    throw new KimiError(ErrorCodes.SESSION_NOT_FOUND, `Session "${id}" was not found`, {
+      details: { sessionId: id },
+    });
+  }
+
+  private async writeForkedState(
+    input: ForkSessionRecordInput,
+    sourceDir: string,
+    targetDir: string,
+  ): Promise<void> {
+    const statePath = join(targetDir, 'state.json');
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(await readFile(statePath, 'utf-8')) as unknown;
+    } catch (error) {
+      throw new KimiError(
+        ErrorCodes.SESSION_STATE_NOT_FOUND,
+        `Session "${input.sourceId}" state.json was not found`,
+        {
+          cause: error,
+        },
+      );
+    }
+    if (!isRecord(parsed)) {
+      throw new KimiError(
+        ErrorCodes.SESSION_STATE_INVALID,
+        `Session "${input.sourceId}" state.json is invalid`,
+      );
+    }
+
+    const title = normalizeForkTitle(input.title, parsed['title']);
+    const now = new Date().toISOString();
+    const next: Record<string, unknown> = {
+      ...parsed,
+      createdAt: now,
+      updatedAt: now,
+      title,
+      isCustomTitle: input.title === undefined ? parsed['isCustomTitle'] === true : true,
+      forkedFrom: input.sourceId,
+      agents: rewriteAgentHomedirs(parsed['agents'], sourceDir, targetDir),
+      custom: Object.assign({}, isRecord(parsed['custom']) ? parsed['custom'] : {}, input.metadata),
+    };
+    await writeFile(statePath, `${JSON.stringify(next, null, 2)}\n`, 'utf-8');
+  }
+
+  private async summaryFromDir(
+    id: string,
+    sessionDir: string,
+    workDir: string,
+  ): Promise<SessionSummary> {
+    const dirStat = await stat(sessionDir);
+    const state = await readOptionalState(sessionDir);
+    const [stateInfo, wireInfo, agentsWireMtime] = await Promise.all([
+      statIfExists(join(sessionDir, 'state.json')),
+      statIfExists(join(sessionDir, 'wire.jsonl')),
+      latestAgentWireMtime(sessionDir),
+    ]);
+    return {
+      id,
+      workDir,
+      sessionDir,
+      createdAt: timestampOrFallback(dirStat.birthtimeMs, dirStat.ctimeMs),
+      updatedAt: Math.max(
+        dirStat.mtimeMs,
+        stateInfo?.mtimeMs ?? 0,
+        wireInfo?.mtimeMs ?? 0,
+        agentsWireMtime ?? 0,
+      ),
+      title: titleFromState(state),
+      lastPrompt: state?.lastPrompt,
+      metadata: metadataFromState(state),
+    };
+  }
+}
+
+function metadataFromState(state: SessionSummaryState | undefined): JsonObject | undefined {
+  if (state === undefined || state.custom === undefined) return undefined;
+  return state.custom as JsonObject;
+}
+
+async function latestAgentWireMtime(sessionDir: string): Promise<number | undefined> {
+  const agentsDir = join(sessionDir, 'agents');
+  let entries;
+  try {
+    entries = await readdir(agentsDir, { withFileTypes: true });
+  } catch {
+    return undefined;
+  }
+
+  let latest = 0;
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const wireInfo = await statIfExists(join(agentsDir, entry.name, 'wire.jsonl'));
+    latest = Math.max(latest, wireInfo?.mtimeMs ?? 0);
+  }
+  return latest > 0 ? latest : undefined;
+}
+
+function titleFromState(state: SessionSummaryState | undefined): string | undefined {
+  if (state === undefined) return undefined;
+  if (typeof state.isCustomTitle === 'boolean' && typeof state.title === 'string') {
+    return state.title;
+  }
+  if (typeof state.customTitle === 'string') return state.customTitle;
+  return typeof state.title === 'string' ? state.title : undefined;
+}
+
+async function readOptionalState(sessionDir: string): Promise<SessionSummaryState | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(join(sessionDir, 'state.json'), 'utf-8')) as unknown;
+    const result = SessionSummaryStateSchema.safeParse(parsed);
+    return result.success ? result.data : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeForkTitle(title: string | undefined, fallback: unknown): string {
+  if (title !== undefined) {
+    const normalized = title.trim();
+    if (normalized.length === 0) {
+      throw new KimiError(ErrorCodes.SESSION_TITLE_EMPTY, 'Session title cannot be empty');
+    }
+    return normalized;
+  }
+  return typeof fallback === 'string' && fallback.trim().length > 0 ? fallback : 'New Session';
+}
+
+function rewriteAgentHomedirs(value: unknown, sourceDir: string, targetDir: string): unknown {
+  if (!isRecord(value)) return {};
+
+  const agents: Record<string, unknown> = {};
+  for (const [agentId, agentMeta] of Object.entries(value)) {
+    if (!isRecord(agentMeta)) {
+      agents[agentId] = agentMeta;
+      continue;
+    }
+    const homedir = agentMeta['homedir'];
+    agents[agentId] = {
+      ...agentMeta,
+      homedir:
+        typeof homedir === 'string' ? remapSessionPath(homedir, sourceDir, targetDir) : homedir,
+    };
+  }
+  return agents;
+}
+
+function remapSessionPath(value: string, sourceDir: string, targetDir: string): string {
+  const rel = relative(sourceDir, value);
+  if (rel === '') return targetDir;
+  if (rel.startsWith('..') || isAbsolute(rel)) return value;
+  return join(targetDir, rel);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+async function statIfExists(path: string): Promise<{ readonly mtimeMs: number } | undefined> {
+  try {
+    return await stat(path);
+  } catch {
+    return undefined;
+  }
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function timestampOrFallback(value: number, fallback: number): number {
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function assertSafeSessionId(id: string): void {
+  if (isSafeSessionId(id)) return;
+  throw new KimiError(ErrorCodes.SESSION_ID_INVALID, 'Session id contains unsupported path characters');
+}
+
+function isSafeSessionId(id: string): boolean {
+  return /^[A-Za-z0-9._-]+$/.test(id) && id !== '.' && id !== '..';
+}
+
+function compareSessionSummary(a: SessionSummary, b: SessionSummary): number {
+  if (a.updatedAt !== b.updatedAt) return b.updatedAt - a.updatedAt;
+  if (a.createdAt !== b.createdAt) return b.createdAt - a.createdAt;
+  if (a.id < b.id) return -1;
+  if (a.id > b.id) return 1;
+  return 0;
+}
diff --git a/packages/agent-core/src/session/store/workdir-key.ts b/packages/agent-core/src/session/store/workdir-key.ts
new file mode 100644
index 000000000..2b0aaafbd
--- /dev/null
+++ b/packages/agent-core/src/session/store/workdir-key.ts
@@ -0,0 +1,18 @@
+import { createHash } from 'node:crypto';
+import { basename, resolve } from 'node:path';
+
+import { slugifyWorkDirName } from '#/utils/workdir-slug';
+
+const WORKDIR_KEY_PREFIX = 'wd_';
+const HASH_LENGTH = 12;
+
+export function normalizeWorkDir(workDir: string): string {
+  return resolve(workDir);
+}
+
+export function encodeWorkDirKey(workDir: string): string {
+  const normalized = normalizeWorkDir(workDir);
+  const slug = slugifyWorkDirName(basename(normalized));
+  const hash = createHash('sha256').update(normalized).digest('hex').slice(0, HASH_LENGTH);
+  return `${WORKDIR_KEY_PREFIX}${slug}_${hash}`;
+}
diff --git a/packages/agent-core/src/session/subagent-host.ts b/packages/agent-core/src/session/subagent-host.ts
new file mode 100644
index 000000000..20b744ec2
--- /dev/null
+++ b/packages/agent-core/src/session/subagent-host.ts
@@ -0,0 +1,345 @@
+import type { TokenUsage } from '@moonshot-ai/kosong';
+
+import type { Agent } from '../agent';
+import type { PromptOrigin } from '../agent/context';
+import type { LoopTurnStopReason } from '../loop';
+import {
+  DEFAULT_AGENT_PROFILES,
+  prepareSystemPromptContext,
+  type ResolvedAgentProfile,
+} from '../profile';
+import { linkAbortSignal } from '../utils/abort';
+import { collectGitContext } from './git-context';
+import type { Session } from './index';
+import SUMMARY_CONTINUATION_PROMPT from './summary-continuation.md';
+
+/**
+ * A subagent summary shorter than this many characters triggers one
+ * follow-up turn that asks the subagent to expand it, so the parent
+ * agent receives a technically complete handoff.
+ */
+const SUMMARY_MIN_LENGTH = 200;
+const SUMMARY_CONTINUATION_ATTEMPTS = 1;
+const HOOK_TEXT_PREVIEW_LENGTH = 500;
+const SUBAGENT_MAX_TOKENS_ERROR =
+  'Subagent turn failed before completing its final summary: reason=max_tokens';
+
+type RunSubagentOptions = {
+  readonly parentToolCallId: string;
+  readonly parentToolCallUuid?: string | undefined;
+  readonly prompt: string;
+  readonly description: string;
+  readonly runInBackground: boolean;
+  readonly origin?: PromptOrigin | undefined;
+  readonly signal: AbortSignal;
+};
+
+type SubagentCompletion = {
+  readonly result: string;
+  readonly usage?: TokenUsage;
+};
+
+type ActiveChild = {
+  readonly controller: AbortController;
+  readonly runInBackground: boolean;
+};
+
+export type SubagentHandle = {
+  readonly agentId: string;
+  readonly profileName: string;
+  readonly resumed: boolean;
+  readonly completion: Promise<SubagentCompletion>;
+};
+
+export class SessionSubagentHost {
+  private readonly activeChildren = new Map<string, ActiveChild>();
+
+  constructor(
+    private readonly session: Session,
+    private readonly ownerAgentId: string,
+    readonly backgroundTaskTimeoutMs?: number | undefined,
+  ) {}
+
+  async spawn(profileName: string, options: RunSubagentOptions): Promise<SubagentHandle> {
+    options.signal.throwIfAborted();
+
+    const parent = this.session.agents.get(this.ownerAgentId);
+    if (parent === undefined) {
+      throw new Error(`Parent agent "${this.ownerAgentId}" was not found`);
+    }
+
+    const profile = this.resolveProfile(parent, profileName);
+    const { id, agent } = await this.session.createAgent(
+      { type: 'sub', generate: parent.rawGenerate },
+      undefined,
+      this.ownerAgentId,
+    );
+    const controller = new AbortController();
+    const unlinkAbortSignal = linkAbortSignal(options.signal, controller);
+    this.activeChildren.set(id, {
+      controller,
+      runInBackground: options.runInBackground,
+    });
+
+    const completion = this.runChild(
+      parent,
+      id,
+      agent,
+      profile.name,
+      {
+        ...options,
+        signal: controller.signal,
+      },
+      () => this.configureChild(parent, agent, profile),
+    ).finally(() => {
+      unlinkAbortSignal();
+      this.activeChildren.delete(id);
+    });
+
+    return {
+      agentId: id,
+      profileName: profile.name,
+      resumed: false,
+      completion,
+    };
+  }
+
+  async resume(agentId: string, options: RunSubagentOptions): Promise<SubagentHandle> {
+    options.signal.throwIfAborted();
+
+    const parent = this.session.agents.get(this.ownerAgentId);
+    if (parent === undefined) {
+      throw new Error(`Parent agent "${this.ownerAgentId}" was not found`);
+    }
+
+    const child = this.session.agents.get(agentId);
+    if (child === undefined) {
+      throw new Error(`Agent instance "${agentId}" was not found`);
+    }
+    const metadata = this.session.metadata.agents[agentId];
+    if (metadata?.type !== 'sub') {
+      throw new Error(`Agent instance "${agentId}" is not a subagent`);
+    }
+    if (metadata.parentAgentId !== this.ownerAgentId) {
+      throw new Error(`Agent instance "${agentId}" does not belong to this parent agent`);
+    }
+    if (this.activeChildren.has(agentId) || child.turn.hasActiveTurn) {
+      throw new Error(
+        `Agent instance "${agentId}" is already running and cannot be resumed concurrently`,
+      );
+    }
+
+    const profileName = child.config.profileName ?? 'subagent';
+
+    const controller = new AbortController();
+    const unlinkAbortSignal = linkAbortSignal(options.signal, controller);
+    this.activeChildren.set(agentId, {
+      controller,
+      runInBackground: options.runInBackground,
+    });
+
+    const completion = this.runChild(
+      parent,
+      agentId,
+      child,
+      profileName,
+      {
+        ...options,
+        signal: controller.signal,
+      },
+      // A resumed subagent is realigned to the parent agent's current model,
+      // so a parent setModel between the initial spawn and the resume is
+      // reflected — a subagent always uses the parent agent's model.
+      () => {
+        child.config.update({ modelAlias: parent.config.modelAlias });
+        return Promise.resolve();
+      },
+    ).finally(() => {
+      unlinkAbortSignal();
+      this.activeChildren.delete(agentId);
+    });
+
+    return {
+      agentId,
+      profileName,
+      resumed: true,
+      completion,
+    };
+  }
+
+  cancelAll(): void {
+    const foregroundChildren = Array.from(this.activeChildren).filter(
+      ([, child]) => !child.runInBackground,
+    );
+    for (const [childId, child] of foregroundChildren) {
+      this.session.agents.get(childId)?.subagentHost?.cancelAll();
+      child.controller.abort();
+    }
+  }
+
+  getProfileName(agentId: string): string | undefined {
+    const metadata = this.session.metadata.agents[agentId];
+    if (metadata?.type !== 'sub' || metadata.parentAgentId !== this.ownerAgentId) {
+      return undefined;
+    }
+    return this.session.agents.get(agentId)?.config.profileName;
+  }
+
+  private resolveProfile(parent: Agent, profileName: string): ResolvedAgentProfile {
+    const profile =
+      DEFAULT_AGENT_PROFILES[parent.config.profileName ?? 'agent']?.subagents?.[profileName] ??
+      DEFAULT_AGENT_PROFILES['agent']?.subagents?.[profileName];
+    if (profile === undefined) {
+      throw new Error(`Subagent profile "${profileName}" was not found`);
+    }
+    return profile;
+  }
+
+  private async runChild(
+    parent: Agent,
+    childId: string,
+    child: Agent,
+    profileName: string,
+    options: RunSubagentOptions,
+    prepareChild: () => Promise<void>,
+  ): Promise<SubagentCompletion> {
+    parent.emitEvent({
+      type: 'subagent.spawned',
+      subagentId: childId,
+      subagentName: profileName,
+      parentToolCallId: options.parentToolCallId,
+      parentToolCallUuid: options.parentToolCallUuid,
+      parentAgentId: this.ownerAgentId,
+      description: options.description,
+      runInBackground: options.runInBackground,
+    });
+    parent.telemetry.track('subagent_created', {
+      subagent_name: profileName,
+      run_in_background: options.runInBackground,
+    });
+
+    try {
+      await prepareChild();
+      options.signal.throwIfAborted();
+      await this.triggerSubagentStart(parent, profileName, options.prompt, options.signal);
+      options.signal.throwIfAborted();
+
+      // Explore subagents start cold; a git-context block helps them orient
+      // in the repository before searching.
+      let childPrompt = options.prompt;
+      if (profileName === 'explore') {
+        const gitContext = await collectGitContext(child.runtime.kaos, child.config.cwd);
+        if (gitContext) childPrompt = `${gitContext}\n\n${childPrompt}`;
+      }
+      const origin: PromptOrigin = options.origin ?? { kind: 'system_trigger', name: 'subagent' };
+      child.turn.prompt([{ type: 'text', text: childPrompt }], origin);
+      await runChildTurnToCompletion(child, options.signal);
+
+      // A subagent that returns an overly terse summary leaves the parent
+      // agent under-informed. Give it a bounded number of chances to expand
+      // the handoff; if it is still short after that, accept it as-is rather
+      // than retrying indefinitely.
+      let result = lastAssistantText(child);
+      let remainingContinuations = SUMMARY_CONTINUATION_ATTEMPTS;
+      while (remainingContinuations > 0 && result.length < SUMMARY_MIN_LENGTH) {
+        remainingContinuations -= 1;
+        options.signal.throwIfAborted();
+        child.turn.prompt([{ type: 'text', text: SUMMARY_CONTINUATION_PROMPT }], origin);
+        await runChildTurnToCompletion(child, options.signal);
+        result = lastAssistantText(child);
+      }
+      const usage = child.usage.data().total;
+      parent.emitEvent({
+        type: 'subagent.completed',
+        subagentId: childId,
+        parentToolCallId: options.parentToolCallId,
+        resultSummary: result,
+        usage,
+      });
+      this.triggerSubagentStop(parent, profileName, result);
+      return { result, usage };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      parent.emitEvent({
+        type: 'subagent.failed',
+        subagentId: childId,
+        parentToolCallId: options.parentToolCallId,
+        error: message,
+      });
+      throw error;
+    }
+  }
+
+  private async configureChild(
+    parent: Agent,
+    child: Agent,
+    profile: ResolvedAgentProfile,
+  ): Promise<void> {
+    // A subagent always inherits the parent agent's model.
+    child.config.update({
+      cwd: parent.config.cwd,
+      modelAlias: parent.config.modelAlias,
+      thinkingLevel: parent.config.thinkingLevel,
+    });
+
+    const context = await prepareSystemPromptContext(child.runtime.kaos, child.config.cwd);
+    child.useProfile(profile, context);
+  }
+
+  private async triggerSubagentStart(
+    parent: Agent,
+    profileName: string,
+    prompt: string,
+    signal: AbortSignal,
+  ): Promise<void> {
+    await parent.hooks?.trigger('SubagentStart', {
+      matcherValue: profileName,
+      signal,
+      inputData: {
+        agentName: profileName,
+        prompt: prompt.slice(0, HOOK_TEXT_PREVIEW_LENGTH),
+      },
+    });
+  }
+
+  private triggerSubagentStop(parent: Agent, profileName: string, result: string): void {
+    void parent.hooks?.fireAndForgetTrigger('SubagentStop', {
+      matcherValue: profileName,
+      inputData: {
+        agentName: profileName,
+        response: result.slice(0, HOOK_TEXT_PREVIEW_LENGTH),
+      },
+    });
+  }
+}
+
+async function runChildTurnToCompletion(child: Agent, signal: AbortSignal): Promise<void> {
+  const completion = await child.turn.waitForCurrentTurn(signal);
+  const turnEnded = completion.event;
+  if (turnEnded.reason !== 'completed') {
+    throw new Error(
+      turnEnded.error === undefined
+        ? `Subagent turn ${turnEnded.reason}`
+        : `[${turnEnded.error.code}] ${turnEnded.error.message}`,
+    );
+  }
+  throwIfSubagentStoppedAtMaxTokens(completion.stopReason);
+}
+
+function throwIfSubagentStoppedAtMaxTokens(stopReason: LoopTurnStopReason | undefined): void {
+  if (stopReason === 'max_tokens') {
+    throw new Error(`${SUBAGENT_MAX_TOKENS_ERROR}.`);
+  }
+}
+
+function lastAssistantText(agent: Agent): string {
+  for (const message of [...agent.context.history].toReversed()) {
+    if (message.role !== 'assistant') continue;
+    const text = message.content
+      .filter((part) => part.type === 'text')
+      .map((part) => part.text)
+      .join('');
+    if (text.trim().length > 0) return text.trim();
+  }
+  return '';
+}
diff --git a/packages/agent-core/src/session/summary-continuation.md b/packages/agent-core/src/session/summary-continuation.md
new file mode 100644
index 000000000..8efb589a5
--- /dev/null
+++ b/packages/agent-core/src/session/summary-continuation.md
@@ -0,0 +1,5 @@
+Your previous response was too brief. Please provide a more comprehensive summary that includes:
+
+1. Specific technical details and implementations
+2. Detailed findings and analysis
+3. All important information that the parent agent should know
\ No newline at end of file
diff --git a/packages/agent-core/src/skill/builtin/index.ts b/packages/agent-core/src/skill/builtin/index.ts
new file mode 100644
index 000000000..e921ec1bf
--- /dev/null
+++ b/packages/agent-core/src/skill/builtin/index.ts
@@ -0,0 +1,8 @@
+import type { SkillRegistry } from '../registry';
+import { MCP_CONFIG_SKILL } from './mcp-config';
+
+export function registerBuiltinSkills(registry: SkillRegistry): void {
+  registry.registerBuiltinSkill(MCP_CONFIG_SKILL);
+}
+
+export { MCP_CONFIG_SKILL };
diff --git a/packages/agent-core/src/skill/builtin/mcp-config.md b/packages/agent-core/src/skill/builtin/mcp-config.md
new file mode 100644
index 000000000..bf20d847a
--- /dev/null
+++ b/packages/agent-core/src/skill/builtin/mcp-config.md
@@ -0,0 +1,96 @@
+---
+name: mcp-config
+description: Configure MCP servers and handle MCP OAuth login.
+---
+
+# Interactive MCP server configuration
+
+The user invoked this skill through `/mcp-config` or `/skill:mcp-config`.
+Either they want to log into an MCP server that asked for OAuth, or they
+want to edit the `mcp.json` that lists MCP servers. The work is small and
+local — handle it on this turn yourself, no agents or planning todos.
+
+Pick the flow from the user's message and your tool list:
+
+- An `mcp__<server>__authenticate` tool is in your list, the user says
+  "log in" / "auth" / "sign in", they invoke `/mcp-config login
+  <server>`, or they quote a `needs-auth` status → **Login**.
+- Add / edit / remove / list of an `mcp.json` entry → **Config edit**.
+- Bare `/mcp-config` with no `authenticate` tool in your list →
+  **Config edit**. If there were a pending login, the authenticate tool
+  would be in your list.
+
+## Login
+
+Each MCP server in `needs-auth` exposes one `mcp__<server>__authenticate`
+tool. Call it for the server the user means — its own description owns
+the OAuth UX (printing the URL, blocking on the callback, reconnecting on
+success). Surface its output verbatim, including the authorization URL
+unchanged; the URL contains state and PKCE parameters that break if
+edited.
+
+If the user named a server that has no authenticate tool, say so in one
+sentence and stop — do **not** fall into config edit. They're trying to
+log in to a server that isn't currently waiting for login; quietly
+rewriting `mcp.json` would be the wrong fix. If multiple authenticate
+tools exist and the user didn't name one, ask which.
+
+## Config edit
+
+Config lives in two files; on key collision the project file overrides
+the user-global one:
+
+- User-global: `~/.kimi-code/mcp.json` (or `$KIMI_CODE_HOME/mcp.json` if
+  set). Use for servers you want everywhere.
+- Project-local: `<cwd>/.kimi-code/mcp.json`. Mention once that stdio
+  entries spawn commands at session start, so this should only live in
+  trusted repos.
+
+Both files wrap their entries the same way:
+
+```json
+{ "mcpServers": { "<name>": { /* entry */ } } }
+```
+
+A minimal stdio entry needs `command` (+ optional `args`, `env`, `cwd`).
+A minimal http entry needs `url`; add `bearerTokenEnvVar: "ENV_NAME"` for
+servers that authenticate with a static bearer token from the
+environment. Servers that use OAuth take no token field — the login flow
+above handles them. `transport` is inferred from `command` vs `url`, so
+omit it. For less common fields (`enabled`, `startupTimeoutMs`,
+`toolTimeoutMs`, `enabledTools`, `disabledTools`, `headers`) the source of
+truth is `McpServerStdioConfigSchema` / `McpServerHttpConfigSchema` in
+`packages/agent-core/src/config/schema.ts`.
+
+If the user only wants to **see** what's configured, read both files,
+show a merged view, and stop — no scope prompt, no write.
+
+For changes, the flow is:
+
+1. **Pick a scope.** Infer it from the user's words when you can
+   (project / repo / this checkout / cwd → project; global / everywhere /
+   all projects → user-global). When the request is genuinely scope-less,
+   use one `AskUserQuestion` to ask user-global vs project-local, defaulting
+   to user-global. Use plain text for every other question — `AskUserQuestion`
+   is a poor fit for free-form input. If the user dismisses the scope
+   question, stop; you can't safely guess where they wanted the change.
+2. **Read and announce.** Read the target file (a missing or empty file
+   is fine; you'll create `{ "mcpServers": {} }`). If JSON parsing fails,
+   surface the error verbatim and stop — silently overwriting a broken
+   file could destroy work. Then show the user the target path, what's
+   currently in it, and the entry you're about to write or delete. This
+   is for transparency, not a confirmation gate — the Edit/Write
+   permission prompt is the real gate, and your message is what gives
+   the user context when that prompt appears. In yolo / afk modes there
+   is no prompt, which is those modes' explicit contract.
+3. **Write and tell them how to reload MCP servers.** Preserve unrelated
+   entries and the `mcpServers` wrapper. MCP servers load at session
+   start, so tell the user to start a new session (for example `/new`) or
+   restart `kimi-code` for the change to take effect.
+
+## Secrets
+
+Don't store secrets (tokens, keys, passwords) as literals in
+`mcp.json` — it's a plain config file on disk. http servers should use
+`bearerTokenEnvVar` to reference an env var instead; if a stdio entry
+must inline one in `env`, warn the user before writing.
diff --git a/packages/agent-core/src/skill/builtin/mcp-config.ts b/packages/agent-core/src/skill/builtin/mcp-config.ts
new file mode 100644
index 000000000..36e60c1c7
--- /dev/null
+++ b/packages/agent-core/src/skill/builtin/mcp-config.ts
@@ -0,0 +1,23 @@
+import { parseSkillText } from '../parser';
+import type { SkillDefinition } from '../types';
+import MCP_CONFIG_BODY from './mcp-config.md';
+
+const PSEUDO_PATH = 'builtin://mcp-config';
+
+const parsed = parseSkillText({
+  skillMdPath: '/builtin/skills/mcp-config.md',
+  skillDirName: 'mcp-config',
+  source: 'builtin',
+  text: MCP_CONFIG_BODY,
+});
+
+export const MCP_CONFIG_SKILL: SkillDefinition = {
+  ...parsed,
+  path: PSEUDO_PATH,
+  dir: PSEUDO_PATH,
+  metadata: {
+    ...parsed.metadata,
+    type: parsed.metadata.type ?? 'inline',
+    disableModelInvocation: true,
+  },
+};
diff --git a/packages/agent-core/src/skill/index.ts b/packages/agent-core/src/skill/index.ts
new file mode 100644
index 000000000..924027bfa
--- /dev/null
+++ b/packages/agent-core/src/skill/index.ts
@@ -0,0 +1,5 @@
+export * from './builtin';
+export * from './parser';
+export * from './registry';
+export * from './scanner';
+export * from './types';
diff --git a/packages/agent-core/src/skill/parser.ts b/packages/agent-core/src/skill/parser.ts
new file mode 100644
index 000000000..f308112b2
--- /dev/null
+++ b/packages/agent-core/src/skill/parser.ts
@@ -0,0 +1,295 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { load as loadYaml } from 'js-yaml';
+import regexpEscape from 'regexp.escape';
+
+import type { SkillDefinition, SkillMetadata, SkillSource } from './types';
+import { isSupportedSkillType } from './types';
+
+export class FrontmatterError extends Error {
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.name = 'FrontmatterError';
+    if (cause !== undefined) {
+      Object.defineProperty(this, 'cause', { value: cause, configurable: true });
+    }
+  }
+}
+
+export class SkillParseError extends Error {
+  readonly reason?: unknown;
+
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.name = 'SkillParseError';
+    if (cause !== undefined) this.reason = cause;
+  }
+}
+
+export class UnsupportedSkillTypeError extends Error {
+  readonly skillType: string;
+
+  constructor(skillType: string) {
+    super(
+      `Skill type "${skillType}" is not supported; only "prompt", "inline", and "flow" are supported.`,
+    );
+    this.name = 'UnsupportedSkillTypeError';
+    this.skillType = skillType;
+  }
+}
+
+export interface ParseSkillOptions {
+  readonly skillMdPath: string;
+  readonly skillDirName: string;
+  readonly source: SkillSource;
+}
+
+export interface ParseSkillTextOptions extends ParseSkillOptions {
+  readonly text: string;
+}
+
+export interface SkillExpandContext {
+  readonly skillDir: string;
+  readonly sessionId?: string;
+  readonly argumentNames?: readonly string[];
+}
+
+export interface ParsedFrontmatter {
+  readonly data: unknown;
+  readonly body: string;
+}
+
+const FENCE = '---';
+const METADATA_ALIASES: Readonly<Record<string, string>> = {
+  'when-to-use': 'whenToUse',
+  when_to_use: 'whenToUse',
+  'disable-model-invocation': 'disableModelInvocation',
+  disable_model_invocation: 'disableModelInvocation',
+};
+
+export async function parseSkillFromFile(options: ParseSkillOptions): Promise<SkillDefinition> {
+  let text: string;
+  try {
+    text = await readFile(options.skillMdPath, 'utf8');
+  } catch (error) {
+    throw new SkillParseError(`Failed to read ${options.skillMdPath}`, error);
+  }
+  return parseSkillText({ ...options, text });
+}
+
+export function parseFrontmatter(text: string): ParsedFrontmatter {
+  const lines = text.split(/\r?\n/);
+  if (lines[0]?.trim() !== FENCE) {
+    return { data: null, body: text };
+  }
+
+  const close = lines.findIndex((line, index) => index > 0 && line.trim() === FENCE);
+  if (close === -1) {
+    throw new FrontmatterError('Missing closing frontmatter fence');
+  }
+
+  const yamlText = lines.slice(1, close).join('\n').trim();
+  const body = lines.slice(close + 1).join('\n');
+  if (yamlText === '') {
+    return { data: {}, body };
+  }
+
+  try {
+    return { data: loadYaml(yamlText) ?? {}, body };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new FrontmatterError(message, error);
+  }
+}
+
+export function parseSkillText(options: ParseSkillTextOptions): SkillDefinition {
+  const isDirectorySkill = path.basename(options.skillMdPath) === 'SKILL.md';
+  if (isDirectorySkill && options.text.split(/\r?\n/, 1)[0]?.trim() !== FENCE) {
+    throw new SkillParseError(`Missing frontmatter in ${options.skillMdPath}`);
+  }
+
+  let parsed;
+  try {
+    parsed = parseFrontmatter(options.text);
+  } catch (error) {
+    if (error instanceof FrontmatterError) {
+      throw new SkillParseError(
+        `Invalid frontmatter in ${options.skillMdPath}: ${error.message}`,
+        error,
+      );
+    }
+    throw error;
+  }
+
+  const frontmatter = parsed.data ?? {};
+  if (!isRecord(frontmatter)) {
+    throw new SkillParseError(
+      `Frontmatter in ${options.skillMdPath} must be a mapping at the top level`,
+    );
+  }
+
+  const metadata = normalizeMetadata(frontmatter);
+  if (!isSupportedSkillType(metadata.type)) {
+    throw new UnsupportedSkillTypeError(metadata.type ?? String(frontmatter['type']));
+  }
+
+  const name = nonEmptyString(metadata.name);
+  const description = nonEmptyString(metadata.description);
+  if (isDirectorySkill && (name === undefined || description === undefined)) {
+    const field = name === undefined ? '"name"' : '"description"';
+    throw new SkillParseError(
+      `Missing required frontmatter field ${field} in ${options.skillMdPath}`,
+    );
+  }
+
+  const skillPath = path.resolve(options.skillMdPath);
+  const content = parsed.body.trim();
+  return {
+    name: name ?? options.skillDirName,
+    description: description ?? descriptionFromBody(content),
+    path: skillPath,
+    dir: path.dirname(skillPath),
+    content,
+    metadata,
+    source: options.source,
+    mermaid: parseMermaidFlowchart(content),
+    d2: parseD2Flowchart(content),
+  };
+}
+
+export function parseMermaidFlowchart(markdown: string): string | undefined {
+  return /```mermaid\r?\n([\s\S]*?)\r?\n```/.exec(markdown)?.[1];
+}
+
+export function parseD2Flowchart(markdown: string): string | undefined {
+  return /```d2\r?\n([\s\S]*?)\r?\n```/.exec(markdown)?.[1];
+}
+
+/**
+ * Expand argument placeholders in a skill body.
+ *
+ * Placeholder syntax ($ARGUMENTS, $0, $name, etc.) is modelled after common
+ * shell/CLI conventions rather than any specific product.
+ */
+export function expandSkillParameters(
+  body: string,
+  rawArgs: string,
+  context: SkillExpandContext,
+): string {
+  const tokens = tokenizeArgs(rawArgs);
+  let content = body;
+
+  for (let index = 0; index < (context.argumentNames?.length ?? 0); index++) {
+    const name = context.argumentNames?.[index];
+    if (name === undefined) continue;
+    const escaped = regexpEscape(name);
+    content = content.replaceAll(
+      new RegExp(`\\$${escaped}(?![\\[\\w])`, 'g'),
+      tokens[index] ?? '',
+    );
+  }
+
+  content = content
+    .replaceAll(/\$ARGUMENTS\[(\d+)\]/g, (_match, indexText: string) => {
+      const index = Number.parseInt(indexText, 10);
+      return tokens[index] ?? '';
+    })
+    .replaceAll(/\$(\d+)(?!\w)/g, (_match, indexText: string) => {
+      const index = Number.parseInt(indexText, 10);
+      return tokens[index] ?? '';
+    })
+    .replaceAll('$ARGUMENTS', rawArgs);
+
+  const hasArgumentPlaceholder = content !== body;
+  content = content
+    .replaceAll('${KIMI_SKILL_DIR}', context.skillDir)
+    .replaceAll('${KIMI_SESSION_ID}', context.sessionId ?? '');
+
+  if (!hasArgumentPlaceholder && rawArgs.length > 0) {
+    return `${content}\n\nARGUMENTS: ${rawArgs}`;
+  }
+  return content;
+}
+
+export function skillArgumentNames(metadata: SkillMetadata): readonly string[] {
+  const value = metadata.arguments;
+  const isValidName = (name: string): boolean =>
+    name.trim() !== '' && !/^\d+$/.test(name);
+  if (typeof value === 'string') return value.split(/\s+/).filter(isValidName);
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === 'string' && isValidName(item));
+}
+
+function normalizeMetadata(raw: Record<string, unknown>): SkillMetadata {
+  const out: Record<string, unknown> = {};
+  for (const [rawKey, value] of Object.entries(raw)) {
+    const key = METADATA_ALIASES[rawKey] ?? rawKey;
+    out[key] = value;
+  }
+
+  const type = nonEmptyString(out['type']);
+  if (type !== undefined) out['type'] = type;
+
+  const name = nonEmptyString(out['name']);
+  if (name !== undefined) out['name'] = name;
+
+  const description = nonEmptyString(out['description']);
+  if (description !== undefined) out['description'] = description;
+
+  return out as SkillMetadata;
+}
+
+function descriptionFromBody(body: string): string {
+  const firstLine = body
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => line.length > 0);
+  if (firstLine === undefined) return 'No description provided.';
+  return firstLine.length > 240 ? `${firstLine.slice(0, 239)}…` : firstLine;
+}
+
+function tokenizeArgs(raw: string): string[] {
+  const out: string[] = [];
+  let current = '';
+  let quote: '"' | "'" | undefined;
+  let hasContent = false;
+
+  for (const char of raw) {
+    if (quote !== undefined) {
+      if (char === quote) {
+        quote = undefined;
+      } else {
+        current += char;
+        hasContent = true;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      hasContent = true;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (hasContent) {
+        out.push(current);
+        current = '';
+        hasContent = false;
+      }
+      continue;
+    }
+    current += char;
+    hasContent = true;
+  }
+
+  if (hasContent) out.push(current);
+  return out;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
diff --git a/packages/agent-core/src/skill/registry.ts b/packages/agent-core/src/skill/registry.ts
new file mode 100644
index 000000000..551b5bfc7
--- /dev/null
+++ b/packages/agent-core/src/skill/registry.ts
@@ -0,0 +1,150 @@
+import { expandSkillParameters, skillArgumentNames } from './parser';
+import { discoverSkills, type DiscoverSkillsOptions } from './scanner';
+import type { SkillDefinition, SkillRoot, SkillSource, SkippedSkill } from './types';
+import { isInlineSkillType, normalizeSkillName } from './types';
+
+const LISTING_DESC_MAX = 250;
+
+export class SkillNotFoundError extends Error {
+  readonly skillName: string;
+
+  constructor(skillName: string) {
+    super(`Skill "${skillName}" is not registered`);
+    this.name = 'SkillNotFoundError';
+    this.skillName = skillName;
+  }
+}
+
+export interface SkillRegistryOptions {
+  readonly discover?: typeof discoverSkills;
+  readonly onWarning?: (message: string, cause?: unknown) => void;
+  readonly sessionId?: string;
+}
+
+export class SkillRegistry {
+  private readonly byName = new Map<string, SkillDefinition>();
+  private readonly roots: string[] = [];
+  private readonly skipped: SkippedSkill[] = [];
+  private readonly discoverImpl: typeof discoverSkills;
+  private readonly onWarning: (message: string, cause?: unknown) => void;
+  readonly sessionId?: string;
+
+  constructor(options: SkillRegistryOptions = {}) {
+    this.discoverImpl = options.discover ?? discoverSkills;
+    this.onWarning = options.onWarning ?? (() => {});
+    this.sessionId = options.sessionId;
+  }
+
+  async loadRoots(roots: readonly SkillRoot[]): Promise<void> {
+    for (const root of roots) {
+      if (!this.roots.includes(root.path)) this.roots.push(root.path);
+    }
+
+    const skills = await this.discoverImpl({
+      roots,
+      onWarning: this.onWarning,
+      onSkippedByPolicy: (skill) => this.skipped.push(skill),
+    } satisfies DiscoverSkillsOptions);
+
+    for (const skill of skills) {
+      this.byName.set(normalizeSkillName(skill.name), skill);
+    }
+  }
+
+  registerBuiltinSkill(skill: SkillDefinition): void {
+    this.register(skill.source === 'builtin' ? skill : { ...skill, source: 'builtin' });
+  }
+
+  register(skill: SkillDefinition, options: { readonly replace?: boolean } = {}): void {
+    const key = normalizeSkillName(skill.name);
+    if (options.replace === true || !this.byName.has(key)) {
+      this.byName.set(key, skill);
+    }
+  }
+
+  getSkill(name: string): SkillDefinition | undefined {
+    return this.byName.get(normalizeSkillName(name));
+  }
+
+  renderSkillPrompt(skill: SkillDefinition, rawArgs: string): string {
+    const argumentNames = skillArgumentNames(skill.metadata);
+    return expandSkillParameters(skill.content, rawArgs, {
+      skillDir: skill.dir,
+      sessionId: this.sessionId,
+      argumentNames,
+    });
+  }
+
+  listSkills(): readonly SkillDefinition[] {
+    return [...this.byName.values()].toSorted((a, b) => a.name.localeCompare(b.name));
+  }
+
+  listInvocableSkills(): readonly SkillDefinition[] {
+    return this.listSkills().filter(
+      (skill) =>
+        skill.metadata.disableModelInvocation !== true && isInlineSkillType(skill.metadata.type),
+    );
+  }
+
+  getSkillRoots(): readonly string[] {
+    return [...this.roots];
+  }
+
+  getSkippedByPolicy(): readonly SkippedSkill[] {
+    return [...this.skipped];
+  }
+
+  getKimiSkillsDescription(): string {
+    const rendered = renderGroupedSkills(this.listSkills(), formatFullSkill);
+    return rendered.length === 0 ? 'No skills' : rendered;
+  }
+
+  getModelSkillListing(): string {
+    const lines = ['DISREGARD any earlier skill listings. Current available skills:'];
+    const listing = renderGroupedSkills(this.listInvocableSkills(), formatModelSkill);
+    if (listing.length > 0) {
+      lines.push(listing);
+    }
+    return lines.length === 1 ? '' : lines.join('\n');
+  }
+}
+
+const SOURCE_GROUPS: ReadonlyArray<{ readonly source: SkillSource; readonly label: string }> = [
+  { source: 'project', label: 'Project' },
+  { source: 'user', label: 'User' },
+  { source: 'extra', label: 'Extra' },
+  { source: 'builtin', label: 'Built-in' },
+];
+
+function renderGroupedSkills(
+  skills: readonly SkillDefinition[],
+  format: (skill: SkillDefinition) => readonly string[],
+): string {
+  const lines: string[] = [];
+  for (const group of SOURCE_GROUPS) {
+    const groupSkills = skills.filter((skill) => skill.source === group.source);
+    if (groupSkills.length === 0) continue;
+    lines.push(`### ${group.label}`);
+    for (const skill of groupSkills) {
+      lines.push(...format(skill));
+    }
+  }
+  return lines.join('\n');
+}
+
+function formatFullSkill(skill: SkillDefinition): readonly string[] {
+  return [`- ${skill.name}`, `  - Path: ${skill.path}`, `  - Description: ${skill.description}`];
+}
+
+function formatModelSkill(skill: SkillDefinition): readonly string[] {
+  const lines = [`- ${skill.name}: ${truncate(skill.description, LISTING_DESC_MAX)}`];
+  if (typeof skill.metadata.whenToUse === 'string' && skill.metadata.whenToUse.length > 0) {
+    lines.push(`  When to use: ${skill.metadata.whenToUse}`);
+  }
+  lines.push(`  Path: ${skill.path}`);
+  return lines;
+}
+
+function truncate(value: string, max: number): string {
+  return value.length > max ? value.slice(0, max) : value;
+}
diff --git a/packages/agent-core/src/skill/scanner.ts b/packages/agent-core/src/skill/scanner.ts
new file mode 100644
index 000000000..ecbe11b6e
--- /dev/null
+++ b/packages/agent-core/src/skill/scanner.ts
@@ -0,0 +1,366 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import { SkillParseError, UnsupportedSkillTypeError, parseSkillFromFile } from './parser';
+import type { SkillDefinition, SkillRoot, SkillSource, SkippedSkill } from './types';
+import { normalizeSkillName } from './types';
+
+const USER_BRAND_DIRS = ['.kimi-code/skills'] as const;
+const USER_GENERIC_DIRS = ['.agents/skills'] as const;
+const PROJECT_BRAND_DIRS = ['.kimi-code/skills'] as const;
+const PROJECT_GENERIC_DIRS = ['.agents/skills'] as const;
+
+// Bounds recursion so a directory symlink cycle inside a skill root cannot
+// loop forever. Real skill trees are 1-3 levels deep.
+const MAX_SKILL_SCAN_DEPTH = 8;
+
+export interface SkillPathContext {
+  readonly userHomeDir: string;
+  readonly workDir: string;
+}
+
+export interface ResolveSkillRootsOptions {
+  readonly paths: SkillPathContext;
+  readonly builtinDir?: string;
+  readonly explicitDirs?: readonly string[];
+  readonly extraDirs?: readonly string[];
+  readonly mergeAllAvailableSkills?: boolean;
+  readonly realpath?: (p: string) => Promise<string>;
+  readonly isDir?: (p: string) => Promise<boolean>;
+}
+
+export interface DiscoverSkillsOptions {
+  readonly roots: readonly SkillRoot[];
+  readonly onWarning?: (message: string, cause?: unknown) => void;
+  readonly onSkippedByPolicy?: (skill: SkippedSkill) => void;
+  readonly readdir?: (p: string) => Promise<readonly string[]>;
+  readonly isFile?: (p: string) => Promise<boolean>;
+  readonly isDir?: (p: string) => Promise<boolean>;
+  readonly parse?: (input: {
+    readonly skillMdPath: string;
+    readonly skillDirName: string;
+    readonly source: SkillSource;
+  }) => Promise<SkillDefinition>;
+}
+
+export interface WorkspaceWithAdditionalDirs {
+  readonly workspaceDir: string;
+  readonly additionalDirs: readonly string[];
+}
+
+export async function resolveSkillRoots(
+  options: ResolveSkillRootsOptions,
+): Promise<readonly SkillRoot[]> {
+  const isDir = options.isDir ?? defaultIsDir;
+  const realpath = options.realpath ?? ((p: string) => fs.realpath(p));
+  const roots: SkillRoot[] = [];
+  const mergeAllAvailableSkills = options.mergeAllAvailableSkills ?? true;
+  const { userHomeDir, workDir } = options.paths;
+  const projectRoot = await findProjectRoot(workDir);
+
+  if (options.explicitDirs !== undefined && options.explicitDirs.length > 0) {
+    await pushConfiguredDirs(
+      roots,
+      options.explicitDirs,
+      projectRoot,
+      userHomeDir,
+      'user',
+      isDir,
+      realpath,
+    );
+  } else {
+    await pushBrandGroup(
+      roots,
+      PROJECT_BRAND_DIRS,
+      projectRoot,
+      'project',
+      mergeAllAvailableSkills,
+      isDir,
+      realpath,
+    );
+    await pushFirstExisting(roots, PROJECT_GENERIC_DIRS, projectRoot, 'project', isDir, realpath);
+    await pushBrandGroup(
+      roots,
+      USER_BRAND_DIRS,
+      userHomeDir,
+      'user',
+      mergeAllAvailableSkills,
+      isDir,
+      realpath,
+    );
+    await pushFirstExisting(roots, USER_GENERIC_DIRS, userHomeDir, 'user', isDir, realpath);
+  }
+
+  if (options.extraDirs !== undefined) {
+    await pushConfiguredDirs(
+      roots,
+      options.extraDirs,
+      projectRoot,
+      userHomeDir,
+      'extra',
+      isDir,
+      realpath,
+    );
+  }
+
+  if (options.builtinDir !== undefined) {
+    await pushExistingRoot(roots, options.builtinDir, 'builtin', isDir, realpath);
+  }
+
+  return roots;
+}
+
+export async function discoverSkills(
+  options: DiscoverSkillsOptions,
+): Promise<readonly SkillDefinition[]> {
+  const readdir = options.readdir ?? ((p: string) => fs.readdir(p));
+  const isFile = options.isFile ?? defaultIsFile;
+  const isDir = options.isDir ?? defaultIsDir;
+  const parse = options.parse ?? parseSkillFromFile;
+  const warn = options.onWarning ?? (() => {});
+  const skip = options.onSkippedByPolicy ?? (() => {});
+  const byName = new Map<string, SkillDefinition>();
+
+  async function walkSkillDir(
+    dirPath: string,
+    source: SkillSource,
+    isTopLevel: boolean,
+    depth: number,
+  ): Promise<void> {
+    if (depth > MAX_SKILL_SCAN_DEPTH) return;
+
+    let entries: readonly string[];
+    try {
+      // Sorted so first-wins collision resolution across sibling directories
+      // is deterministic rather than dependent on filesystem readdir order.
+      entries = [...(await readdir(dirPath))].toSorted();
+    } catch (error) {
+      warn(`Failed to read skill directory ${dirPath}`, error);
+      return;
+    }
+
+    const directorySkills = new Set<string>();
+    const subdirs: string[] = [];
+    for (const entry of entries) {
+      // A directory holding SKILL.md is a skill bundle: register it and do not
+      // descend, so its bundled references/scripts are never scanned.
+      if (await isFile(path.join(dirPath, entry, 'SKILL.md'))) {
+        directorySkills.add(entry);
+        continue;
+      }
+      if (entry === 'node_modules' || entry.startsWith('.')) continue;
+      if (await isDir(path.join(dirPath, entry))) subdirs.push(entry);
+    }
+
+    for (const entry of directorySkills) {
+      await parseAndRegister({
+        parse,
+        byName,
+        skillMdPath: path.join(dirPath, entry, 'SKILL.md'),
+        skillDirName: entry,
+        source,
+        warn,
+        skip,
+      });
+    }
+
+    // Flat .md skills count only at a root's top level; deeper .md files are
+    // skill payload (e.g. references/foo.md), not skills.
+    if (isTopLevel) {
+      for (const entry of entries) {
+        if (!entry.endsWith('.md')) continue;
+        if (entry === 'SKILL.md') continue;
+        const skillName = entry.slice(0, -'.md'.length);
+        if (directorySkills.has(skillName)) {
+          warn(
+            `Ignoring flat skill ${path.join(dirPath, entry)} because ${path.join(dirPath, skillName, 'SKILL.md')} exists with the same name`,
+          );
+          continue;
+        }
+        const skillMdPath = path.join(dirPath, entry);
+        if (!(await isFile(skillMdPath))) continue;
+        await parseAndRegister({
+          parse,
+          byName,
+          skillMdPath,
+          skillDirName: skillName,
+          source,
+          warn,
+          skip,
+        });
+      }
+    }
+
+    for (const entry of subdirs) {
+      await walkSkillDir(path.join(dirPath, entry), source, false, depth + 1);
+    }
+  }
+
+  for (const root of options.roots) {
+    await walkSkillDir(root.path, root.source, true, 0);
+  }
+
+  return sortSkills([...byName.values()]);
+}
+
+export function extendWorkspaceWithSkillRoots<T extends WorkspaceWithAdditionalDirs>(
+  workspace: T,
+  skillRoots: readonly string[],
+): T {
+  const additionalDirs = [...workspace.additionalDirs];
+  for (const root of skillRoots) {
+    if (isWithin(root, workspace.workspaceDir)) continue;
+    if (additionalDirs.some((dir) => root === dir || isWithin(root, dir))) continue;
+    additionalDirs.push(root);
+  }
+  if (additionalDirs.length === workspace.additionalDirs.length) return workspace;
+  return { ...workspace, additionalDirs };
+}
+
+function sortSkills(skills: readonly SkillDefinition[]): readonly SkillDefinition[] {
+  return [...skills].toSorted((a, b) => a.name.localeCompare(b.name));
+}
+
+async function pushFirstExisting(
+  out: SkillRoot[],
+  dirs: readonly string[],
+  base: string,
+  source: SkillSource,
+  isDir: (p: string) => Promise<boolean>,
+  realpath: (p: string) => Promise<string>,
+): Promise<void> {
+  for (const dir of dirs) {
+    if (await pushExistingRoot(out, path.join(base, dir), source, isDir, realpath)) return;
+  }
+}
+
+async function pushBrandGroup(
+  out: SkillRoot[],
+  dirs: readonly string[],
+  base: string,
+  source: SkillSource,
+  mergeAllAvailableSkills: boolean,
+  isDir: (p: string) => Promise<boolean>,
+  realpath: (p: string) => Promise<string>,
+): Promise<void> {
+  if (!mergeAllAvailableSkills) {
+    await pushFirstExisting(out, dirs, base, source, isDir, realpath);
+    return;
+  }
+  for (const dir of dirs) {
+    await pushExistingRoot(out, path.join(base, dir), source, isDir, realpath);
+  }
+}
+
+async function pushConfiguredDirs(
+  out: SkillRoot[],
+  dirs: readonly string[],
+  projectRoot: string,
+  userHomeDir: string,
+  source: SkillSource,
+  isDir: (p: string) => Promise<boolean>,
+  realpath: (p: string) => Promise<string>,
+): Promise<void> {
+  for (const dir of dirs) {
+    await pushExistingRoot(
+      out,
+      resolveConfiguredDir(dir, projectRoot, userHomeDir),
+      source,
+      isDir,
+      realpath,
+    );
+  }
+}
+
+async function pushExistingRoot(
+  out: SkillRoot[],
+  dir: string,
+  source: SkillSource,
+  isDir: (p: string) => Promise<boolean>,
+  realpath: (p: string) => Promise<string>,
+): Promise<boolean> {
+  if (!(await isDir(dir))) return false;
+  const resolved = await realpath(dir);
+  if (!out.some((root) => root.path === resolved)) out.push({ path: resolved, source });
+  return true;
+}
+
+async function parseAndRegister(input: {
+  readonly parse: NonNullable<DiscoverSkillsOptions['parse']>;
+  readonly byName: Map<string, SkillDefinition>;
+  readonly skillMdPath: string;
+  readonly skillDirName: string;
+  readonly source: SkillSource;
+  readonly warn: (message: string, cause?: unknown) => void;
+  readonly skip: (skill: SkippedSkill) => void;
+}): Promise<void> {
+  try {
+    const skill = await input.parse({
+      skillMdPath: input.skillMdPath,
+      skillDirName: input.skillDirName,
+      source: input.source,
+    });
+    const key = normalizeSkillName(skill.name);
+    if (!input.byName.has(key)) input.byName.set(key, skill);
+  } catch (error) {
+    if (error instanceof UnsupportedSkillTypeError) {
+      input.skip({
+        path: input.skillMdPath,
+        type: error.skillType,
+        reason: `unsupported skill type "${error.skillType}"`,
+      });
+    } else if (error instanceof SkillParseError) {
+      input.warn(`Skipping invalid skill at ${input.skillMdPath}: ${error.message}`, error);
+    } else {
+      input.warn(`Skipping skill at ${input.skillMdPath} due to unexpected error`, error);
+    }
+  }
+}
+
+async function defaultIsDir(p: string): Promise<boolean> {
+  try {
+    return (await fs.stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function defaultIsFile(p: string): Promise<boolean> {
+  try {
+    return (await fs.stat(p)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function findProjectRoot(workDir: string): Promise<string> {
+  const start = path.resolve(workDir);
+  let current = start;
+  while (true) {
+    if (await exists(path.join(current, '.git'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return start;
+    current = parent;
+  }
+}
+
+async function exists(p: string): Promise<boolean> {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveConfiguredDir(dir: string, projectRoot: string, userHomeDir: string): string {
+  if (dir === '~') return userHomeDir;
+  if (dir.startsWith('~/')) return path.join(userHomeDir, dir.slice(2));
+  if (path.isAbsolute(dir)) return dir;
+  return path.resolve(projectRoot, dir);
+}
+
+function isWithin(child: string, parent: string): boolean {
+  const relative = path.relative(parent, child);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
diff --git a/packages/agent-core/src/skill/types.ts b/packages/agent-core/src/skill/types.ts
new file mode 100644
index 000000000..8ea89b1dd
--- /dev/null
+++ b/packages/agent-core/src/skill/types.ts
@@ -0,0 +1,77 @@
+export type SkillSource = 'project' | 'user' | 'extra' | 'builtin';
+
+export interface SkillMetadata {
+  readonly name?: string | undefined;
+  readonly description?: string | undefined;
+  readonly type?: string | undefined;
+  readonly whenToUse?: string | undefined;
+  readonly disableModelInvocation?: boolean | undefined;
+  readonly safe?: boolean | undefined;
+  readonly arguments?: readonly unknown[] | string | undefined;
+  readonly [key: string]: unknown;
+}
+
+export interface SkillDefinition {
+  readonly name: string;
+  readonly description: string;
+  readonly path: string;
+  readonly dir: string;
+  readonly content: string;
+  readonly metadata: SkillMetadata;
+  readonly source: SkillSource;
+  readonly mermaid?: string | undefined;
+  readonly d2?: string;
+}
+
+export interface SkillSummary {
+  readonly name: string;
+  readonly description: string;
+  readonly path: string;
+  readonly source: SkillSource;
+  readonly type?: string | undefined;
+  readonly disableModelInvocation?: boolean | undefined;
+}
+
+export interface SkillRoot {
+  readonly path: string;
+  readonly source: SkillSource;
+}
+
+export interface SkippedSkill {
+  readonly path: string;
+  readonly type: string;
+  readonly reason: string;
+}
+
+export interface SkillCatalog {
+  getSkill(name: string): SkillDefinition | undefined;
+  listSkills(): readonly SkillDefinition[];
+  listInvocableSkills(): readonly SkillDefinition[];
+}
+
+export function normalizeSkillName(name: string): string {
+  return name.toLowerCase();
+}
+
+export function isInlineSkillType(type: string | undefined): boolean {
+  return type === undefined || type === 'prompt' || type === 'inline';
+}
+
+export function isUserActivatableSkillType(type: string | undefined): boolean {
+  return isInlineSkillType(type) || type === 'flow';
+}
+
+export function isSupportedSkillType(type: string | undefined): boolean {
+  return isUserActivatableSkillType(type);
+}
+
+export function summarizeSkill(skill: SkillDefinition): SkillSummary {
+  return {
+    name: skill.name,
+    description: skill.description,
+    path: skill.path,
+    source: skill.source,
+    type: skill.metadata.type,
+    disableModelInvocation: skill.metadata.disableModelInvocation,
+  };
+}
diff --git a/packages/agent-core/src/telemetry.ts b/packages/agent-core/src/telemetry.ts
new file mode 100644
index 000000000..e1c9c3ad6
--- /dev/null
+++ b/packages/agent-core/src/telemetry.ts
@@ -0,0 +1,26 @@
+export type TelemetryPropertyValue = boolean | number | string | null;
+
+export type TelemetryProperties = Readonly<Record<string, TelemetryPropertyValue>>;
+
+export interface TelemetryContextPatch {
+  readonly sessionId?: string | null;
+}
+
+export interface TelemetryClient {
+  track(event: string, properties?: TelemetryProperties): void;
+  withContext?(patch: TelemetryContextPatch): TelemetryClient;
+  setContext?(patch: TelemetryContextPatch): void;
+}
+
+export const noopTelemetryClient: TelemetryClient = {
+  track: () => {},
+  withContext: () => noopTelemetryClient,
+  setContext: () => {},
+};
+
+export function withTelemetryContext(
+  telemetry: TelemetryClient,
+  patch: TelemetryContextPatch,
+): TelemetryClient {
+  return telemetry.withContext?.(patch) ?? telemetry;
+}
diff --git a/packages/agent-core/src/tools/args-validator.ts b/packages/agent-core/src/tools/args-validator.ts
new file mode 100644
index 000000000..ce967ccb0
--- /dev/null
+++ b/packages/agent-core/src/tools/args-validator.ts
@@ -0,0 +1,93 @@
+import Ajv, { type ErrorObject, type ValidateFunction } from 'ajv';
+import Ajv2019 from 'ajv/dist/2019';
+import Ajv2020 from 'ajv/dist/2020';
+import addFormats from 'ajv-formats';
+
+const DRAFT_07_AJV = new Ajv({ strict: false, allErrors: true });
+addFormats(DRAFT_07_AJV);
+
+const DRAFT_2019_AJV = new Ajv2019({ strict: false, allErrors: true });
+addFormats(DRAFT_2019_AJV);
+
+const DRAFT_2020_AJV = new Ajv2020({ strict: false, allErrors: true });
+addFormats(DRAFT_2020_AJV);
+
+const DRAFT_2019_KEYWORDS = new Set([
+  'dependentRequired',
+  'dependentSchemas',
+  'maxContains',
+  'minContains',
+  'unevaluatedItems',
+  'unevaluatedProperties',
+  '$recursiveAnchor',
+  '$recursiveRef',
+]);
+
+const DRAFT_2020_KEYWORDS = new Set(['prefixItems', '$dynamicAnchor', '$dynamicRef']);
+
+// Mixing JSON Schema dialects in a single Ajv instance is unsafe because
+// keyword semantics differ, e.g. draft-07 tuple `items` vs 2020-12 `prefixItems`.
+function ajvFor(schema: Record<string, unknown>): Ajv | Ajv2019 | Ajv2020 {
+  const $schema = schema['$schema'];
+  if (typeof $schema === 'string') {
+    if ($schema.includes('2020-12')) return DRAFT_2020_AJV;
+    if ($schema.includes('2019-09')) return DRAFT_2019_AJV;
+    return DRAFT_07_AJV;
+  }
+  if (containsSchemaKeyword(schema, DRAFT_2020_KEYWORDS)) return DRAFT_2020_AJV;
+  if (containsSchemaKeyword(schema, DRAFT_2019_KEYWORDS)) return DRAFT_2019_AJV;
+  return DRAFT_07_AJV;
+}
+
+function containsSchemaKeyword(value: unknown, keywords: ReadonlySet<string>): boolean {
+  if (Array.isArray(value)) {
+    return value.some((item) => containsSchemaKeyword(item, keywords));
+  }
+  if (typeof value !== 'object' || value === null) return false;
+  for (const [key, child] of Object.entries(value)) {
+    if (keywords.has(key)) return true;
+    if (containsSchemaKeyword(child, keywords)) return true;
+  }
+  return false;
+}
+
+export type JsonType = null | number | string | boolean | JsonArray | JsonObject;
+
+/** @internal */
+export interface JsonArray extends Array<JsonType> {}
+
+/** @internal */
+export interface JsonObject extends Record<string, JsonType> {}
+
+export type ToolArgsValidator = ValidateFunction<JsonType>;
+
+function formatValidationError(error: ErrorObject): string {
+  if (error.keyword === 'required' && 'missingProperty' in error.params) {
+    return `must have required property '${String(error.params['missingProperty'])}'`;
+  }
+
+  if (error.keyword === 'additionalProperties' && 'additionalProperty' in error.params) {
+    return `must NOT have additional property '${String(error.params['additionalProperty'])}'`;
+  }
+
+  const path = error.instancePath ? `${error.instancePath} ` : '';
+  return `${path}${error.message ?? 'is invalid'}`;
+}
+
+export function compileToolArgsValidator(schema: Record<string, unknown>): ToolArgsValidator {
+  return ajvFor(schema).compile(schema) as ToolArgsValidator;
+}
+
+export function validateToolArgs(validator: ToolArgsValidator, args: JsonType): string | null {
+  const valid = validator(args);
+  if (valid) {
+    return null;
+  }
+
+  const errors = validator.errors ?? [];
+  if (errors.length === 0) {
+    return 'Tool parameter validation failed';
+  }
+
+  return errors.map((error) => formatValidationError(error)).join('; ');
+}
diff --git a/packages/agent-core/src/tools/background/index.ts b/packages/agent-core/src/tools/background/index.ts
new file mode 100644
index 000000000..1f924b359
--- /dev/null
+++ b/packages/agent-core/src/tools/background/index.ts
@@ -0,0 +1,19 @@
+/**
+ * Background task management tools barrel.
+ */
+
+export { BackgroundProcessManager, generateTaskId } from './manager';
+export type {
+  BackgroundTaskInfo,
+  BackgroundTaskKind,
+  BackgroundTaskOutputSnapshot,
+  BackgroundTaskStatus,
+  ReconcileResult,
+} from './manager';
+export { VALID_TASK_ID } from './persist';
+export { TaskListTool, TaskListInputSchema } from './task-list';
+export type { TaskListInput } from './task-list';
+export { TaskOutputTool, TaskOutputInputSchema } from './task-output';
+export type { TaskOutputInput } from './task-output';
+export { TaskStopTool, TaskStopInputSchema } from './task-stop';
+export type { TaskStopInput } from './task-stop';
diff --git a/packages/agent-core/src/tools/background/manager.ts b/packages/agent-core/src/tools/background/manager.ts
new file mode 100644
index 000000000..97f77fc9e
--- /dev/null
+++ b/packages/agent-core/src/tools/background/manager.ts
@@ -0,0 +1,1205 @@
+/**
+ * BackgroundProcessManager — manages background shell processes.
+ *
+ * Tracks background bash tasks spawned by `BashTool` when
+ * `run_in_background=true`.
+ *
+ * Each task gets a unique ID, captures stdout+stderr to a ring buffer,
+ * and supports status query / output retrieval / stop operations.
+ *
+ * Accepts `KaosProcess` (not `ChildProcess`) so there is no unsafe cast
+ * at the BashTool call site. Lifecycle detection uses `wait()` instead
+ * of EventEmitter `on('exit')`.
+ */
+
+import { randomBytes } from 'node:crypto';
+
+import type { KaosProcess } from '@moonshot-ai/kaos';
+
+import { isAbortError } from '../../loop/errors';
+import {
+  appendTaskOutput,
+  listTasks,
+  readTaskOutput,
+  readTaskOutputBytes,
+  removeTask,
+  taskOutputExists,
+  taskOutputExistsSync,
+  taskOutputFile,
+  taskOutputSizeBytes,
+  writeTask,
+  type PersistedTask,
+} from './persist';
+
+// ── Types ────────────────────────────────────────────────────────────
+
+/**
+ * `'lost'` is a reconcile-only terminal state. Tasks loaded from disk
+ * that were marked `running` at startup but have no live KaosProcess
+ * (the previous CLI process died) are reclassified as lost.
+ *
+ * `'awaiting_approval'` is a non-terminal state entered when a background
+ * agent task is paused waiting for tool-call approval from the root
+ * agent. The BPM state machine is the single source of truth for "is
+ * this task actively running vs. gated on approval" — UI reads from BPM
+ * instead of reverse-querying the ApprovalRuntime. The loop boundary is
+ * preserved because `awaiting_approval` in BPM does not leak permission
+ * vocabulary into the loop.
+ */
+export type BackgroundTaskStatus =
+  | 'running'
+  | 'awaiting_approval'
+  | 'completed'
+  | 'failed'
+  | 'killed'
+  | 'lost';
+
+/** Terminal states tasks never leave once reached. */
+const TERMINAL_STATUSES: ReadonlySet<BackgroundTaskStatus> = new Set<BackgroundTaskStatus>([
+  'completed',
+  'failed',
+  'killed',
+  'lost',
+]);
+
+export function isBackgroundTaskTerminal(status: BackgroundTaskStatus): boolean {
+  return TERMINAL_STATUSES.has(status);
+}
+
+/** Task kinds with distinct id prefixes. */
+export type BackgroundTaskKind = 'bash' | 'agent';
+
+/** Lifecycle phases observed by `onLifecycle` subscribers. */
+export type BackgroundLifecycleEvent = 'started' | 'updated' | 'terminated';
+
+export interface BackgroundTaskInfo {
+  readonly taskId: string;
+  readonly command: string;
+  readonly description: string;
+  readonly status: BackgroundTaskStatus;
+  readonly pid: number;
+  readonly exitCode: number | null;
+  readonly startedAt: number;
+  readonly endedAt: number | null;
+  /** Populated only while `status === 'awaiting_approval'`. */
+  readonly approvalReason?: string | undefined;
+  /** True when an agent task was aborted by its deadline. */
+  readonly timedOut?: boolean | undefined;
+  /** Reason recorded when a task is explicitly stopped. */
+  readonly stopReason?: string | undefined;
+  /**
+   * Deadline (ms) supplied to `registerAgentTask`. Surfaced so shutdown
+   * wait-caps and UI can read the originally-requested timeout without
+   * round-tripping the call site. `undefined` means no deadline.
+   */
+  readonly timeoutMs?: number | undefined;
+  /** Identifier of the spawned subagent (agent tasks only). */
+  readonly agentId?: string | undefined;
+  /** Profile name of the spawned subagent (agent tasks only). */
+  readonly subagentType?: string | undefined;
+  /**
+   * Human-readable reason recorded when a non-terminal task is reclassified
+   * via reconcile (e.g. a stale heartbeat → lost).
+   */
+  readonly failureReason?: string | undefined;
+}
+
+interface ManagedProcess {
+  readonly taskId: string;
+  readonly command: string;
+  readonly description: string;
+  readonly proc: KaosProcess;
+  readonly outputChunks: string[];
+  /** Total UTF-8 bytes observed, including chunks dropped from the live ring buffer. */
+  outputSizeBytes: number;
+  status: BackgroundTaskStatus;
+  exitCode: number | null;
+  readonly startedAt: number;
+  endedAt: number | null;
+  /** Listeners awaiting task completion. */
+  readonly waiters: Array<() => void>;
+  /** True once `fireTerminalCallbacks` has already run. */
+  terminalFired: boolean;
+  /** Reason carried while awaiting approval. */
+  approvalReason?: string | undefined;
+  /** Set when a deadline fires before natural completion. */
+  timedOut?: boolean | undefined;
+  /** Reason recorded when a task is explicitly stopped. */
+  stopReason?: string | undefined;
+  /** Deadline supplied at registration; surfaced via task info. */
+  timeoutMs?: number | undefined;
+  /** Subagent identifier (agent tasks only). */
+  agentId?: string | undefined;
+  /** Subagent profile name (agent tasks only). */
+  subagentType?: string | undefined;
+  /** Non-terminal-reclassification reason (e.g. stale heartbeat). */
+  failureReason?: string | undefined;
+  /** True after stop() has requested cancellation but before terminal status is chosen. */
+  stopRequested: boolean;
+  /** Session dir captured at registration for output.log writes. */
+  readonly outputSessionDir?: string | undefined;
+  lifecyclePromise: Promise<void>;
+  persistWriteQueue: Promise<void>;
+  outputWriteQueue: Promise<void>;
+}
+
+/**
+ * Maximum bytes of combined output kept in the in-memory ring buffer per
+ * task. When exceeded, the oldest chunks are dropped.
+ *
+ * The ring buffer is a lightweight tail intended for the `/tasks` UI and
+ * terminal notifications only — it deliberately discards old output to
+ * cap memory. It is NOT the authoritative full output: the complete,
+ * never-truncated log lives on disk at `<sessionDir>/tasks/<id>/output.log`.
+ * Callers that need the full output (e.g. `TaskOutput`) must read the
+ * disk log via `getOutputSizeBytes` / `readOutputBytesFromDisk`.
+ */
+const MAX_OUTPUT_BYTES = 1024 * 1024; // 1 MiB
+
+const SIGTERM_GRACE_MS = 5_000;
+const EXIT_SETTLE_GRACE_MS = 10;
+
+const _ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
+
+/**
+ * Generate `{prefix}-{8 base36 chars}`.
+ *
+ * `randomBytes(8) % 36` has a modest modulo bias (256 % 36 = 4) but
+ * over an 8-char suffix yields ~36^8 ≈ 2.8e12 distinct ids which is
+ * more than enough uniqueness for per-session task ids.
+ */
+export function generateTaskId(kind: BackgroundTaskKind): string {
+  const bytes = randomBytes(8);
+  let suffix = '';
+  for (let i = 0; i < 8; i++) {
+    suffix += _ALPHABET[bytes[i]! % 36];
+  }
+  return `${kind}-${suffix}`;
+}
+
+/**
+ * Terminal-state info for tasks reconciled as lost on resume. They
+ * have no live KaosProcess and no captured output (the buffer died
+ * with the previous process), so list/get returns this minimal record.
+ */
+export interface ReconcileResult {
+  /** Task IDs that were marked `lost` because their process is gone. */
+  readonly lost: readonly string[];
+  /** Snapshot of each lost task's persisted info for terminal notifications. */
+  readonly lostInfo: readonly BackgroundTaskInfo[];
+}
+
+export interface BackgroundProcessManagerOptions {
+  readonly maxRunningTasks?: number;
+  readonly sessionDir?: string;
+}
+
+export interface BackgroundTaskReservation {
+  release(): void;
+}
+
+export interface BackgroundTaskOutputSnapshot {
+  readonly outputPath?: string;
+  readonly outputSizeBytes: number;
+  readonly previewBytes: number;
+  readonly truncated: boolean;
+  readonly fullOutputAvailable: boolean;
+  readonly preview: string;
+}
+
+function emptyOutputSnapshot(): BackgroundTaskOutputSnapshot {
+  return {
+    outputSizeBytes: 0,
+    previewBytes: 0,
+    truncated: false,
+    fullOutputAvailable: false,
+    preview: '',
+  };
+}
+
+// ── Manager ──────────────────────────────────────────────────────────
+
+export class BackgroundProcessManager {
+  private readonly processes = new Map<string, ManagedProcess>();
+  private reservedTaskSlots = 0;
+  /**
+   * Ghosts: tasks loaded from disk during reconcile that have no live
+   * KaosProcess. They appear in `list()` / `getTask()` with status
+   * `lost` so users see what was running before the crash/restart.
+   */
+  private readonly ghosts = new Map<string, BackgroundTaskInfo>();
+  /** When set, register/lifecycle changes persist to disk. */
+  private sessionDir: string | undefined;
+
+  /**
+   * Registered terminal-state callbacks. Fired once per task when the
+   * task reaches a terminal state (completed / failed / killed).
+   */
+  private readonly terminalCallbacks: Array<(info: BackgroundTaskInfo) => void | Promise<void>> =
+    [];
+
+  /**
+   * Registered lifecycle callbacks. Fired for every observable
+   * transition (started / updated / terminated). Errors thrown by
+   * callbacks are silently swallowed so the BPM main flow never breaks
+   * because of a buggy subscriber.
+   */
+  private readonly lifecycleCallbacks: Array<
+    (event: BackgroundLifecycleEvent, info: BackgroundTaskInfo) => void
+  > = [];
+
+  constructor(private readonly options: BackgroundProcessManagerOptions = {}) {
+    this.sessionDir = options.sessionDir;
+  }
+
+  /**
+   * Register a callback that fires when any task reaches a terminal
+   * state. The callback receives the task's `BackgroundTaskInfo`
+   * snapshot. Multiple callbacks may be registered; they are invoked in
+   * registration order. Errors thrown by callbacks are silently swallowed.
+   */
+  onTerminal(callback: (info: BackgroundTaskInfo) => void | Promise<void>): void {
+    this.terminalCallbacks.push(callback);
+  }
+
+  /**
+   * Register a callback that fires on every lifecycle transition:
+   *   - 'started':    task just registered (either bash or agent)
+   *   - 'updated':    awaiting_approval entered / cleared
+   *   - 'terminated': task reached a terminal state (also triggers
+   *                   onTerminal); fires exactly once per task.
+   *
+   * Synchronous callback. Errors are swallowed so the BPM lifecycle
+   * machinery (status updates, persistence, waiters) cannot be blocked
+   * by a buggy subscriber. Use it for fan-out to RPC events; do not put
+   * heavy work in it (defer to microtask if needed).
+   */
+  onLifecycle(callback: (event: BackgroundLifecycleEvent, info: BackgroundTaskInfo) => void): void {
+    this.lifecycleCallbacks.push(callback);
+  }
+
+  /** Fan out a lifecycle event to subscribers. */
+  private fireLifecycle(event: BackgroundLifecycleEvent, info: BackgroundTaskInfo): void {
+    for (const cb of this.lifecycleCallbacks) {
+      try {
+        cb(event, info);
+      } catch {
+        /* swallow callback errors */
+      }
+    }
+  }
+
+  /**
+   * Subclasses can react to live task completion here. Restored disk
+   * tasks reconciled as lost do not call this hook.
+   */
+  protected onLiveTaskTerminal(_info: BackgroundTaskInfo): void | Promise<void> {}
+
+  /**
+   * Fire all registered terminal callbacks for a task. Idempotent: the
+   * second invocation for the same task is a no-op so `reconcile()` /
+   * a lagging `wait()` resolver / a race between `stop()` and natural
+   * exit cannot yield duplicate notifications. This is the manager-side
+   * half of the dedupe pact with `NotificationManager.dedupe_key`.
+   */
+  private fireTerminalCallbacks(entry: ManagedProcess): void {
+    if (entry.terminalFired) return;
+    entry.terminalFired = true;
+    const info = this.toInfo(entry);
+    try {
+      const result = this.onLiveTaskTerminal(info);
+      if (result && typeof result.catch === 'function') {
+        result.catch(() => {});
+      }
+    } catch {
+      /* swallow */
+    }
+    this.fireTerminalSubscribers(info);
+  }
+
+  private fireTerminalSubscribers(info: BackgroundTaskInfo): void {
+    for (const cb of this.terminalCallbacks) {
+      try {
+        const result = cb(info);
+        if (result && typeof result.catch === 'function') {
+          result.catch(() => {});
+        }
+      } catch {
+        /* swallow callback errors */
+      }
+    }
+    this.fireLifecycle('terminated', info);
+  }
+
+  private resolveWaiters(entry: ManagedProcess): void {
+    const waiters = entry.waiters.splice(0);
+    for (const resolve of waiters) resolve();
+  }
+
+  assertCanRegister(): void {
+    const maxRunningTasks = this.options.maxRunningTasks;
+    if (maxRunningTasks === undefined) return;
+    if (this.activeTaskCount() + this.reservedTaskSlots < maxRunningTasks) return;
+    throw new Error('Too many background tasks are already running.');
+  }
+
+  reserveSlot(): BackgroundTaskReservation {
+    const maxRunningTasks = this.options.maxRunningTasks;
+    if (maxRunningTasks === undefined) {
+      return { release: () => {} };
+    }
+    this.assertCanRegister();
+    this.reservedTaskSlots++;
+    let released = false;
+    return {
+      release: () => {
+        if (released) return;
+        released = true;
+        this.reservedTaskSlots--;
+      },
+    };
+  }
+
+  private activeTaskCount(): number {
+    let count = 0;
+    for (const entry of this.processes.values()) {
+      if (!TERMINAL_STATUSES.has(entry.status)) count++;
+    }
+    return count;
+  }
+
+  /**
+   * Register a KaosProcess as a background task.
+   * Starts capturing stdout/stderr and monitors lifecycle via `wait()`.
+   * Returns the assigned task ID.
+   *
+   * `opts.kind` picks the id prefix. Defaults to `'bash'` because bash
+   * subprocess registration is the only caller on the process path
+   * today; agent tasks go through `registerAgentTask` which forces
+   * `'agent'`.
+   */
+  register(
+    proc: KaosProcess,
+    command: string,
+    description: string,
+    opts:
+      | {
+          kind?: BackgroundTaskKind;
+          /**
+           * Optional shell metadata. Carried so the `/task` UI and the
+           * background persist snapshot can surface which dialect a
+           * task was launched under. Legacy callers omitting this
+           * field keep the implicit 'bash' default.
+           */
+          shellInfo?: {
+            shellName: string;
+            shellPath: string;
+            cwd: string;
+          };
+          reservation?: BackgroundTaskReservation;
+        }
+      | undefined = undefined,
+  ): string {
+    if (opts?.reservation) {
+      opts.reservation.release();
+    } else {
+      this.assertCanRegister();
+    }
+    const kind = opts?.kind;
+    const taskId = generateTaskId(kind ?? 'bash');
+    const entry: ManagedProcess = {
+      taskId,
+      command,
+      description,
+      proc,
+      outputChunks: [],
+      outputSizeBytes: 0,
+      status: 'running',
+      exitCode: null,
+      startedAt: Date.now(),
+      endedAt: null,
+      waiters: [],
+      terminalFired: false,
+      stopRequested: false,
+      outputSessionDir: this.sessionDir,
+      lifecyclePromise: Promise.resolve(),
+      persistWriteQueue: Promise.resolve(),
+      outputWriteQueue: Promise.resolve(),
+    };
+    this.processes.set(taskId, entry);
+
+    // Capture stdout + stderr into the ring buffer.
+    for (const stream of [proc.stdout, proc.stderr]) {
+      stream.setEncoding('utf8');
+      stream.on('data', (chunk: string) => {
+        this.appendOutput(entry, chunk);
+      });
+    }
+
+    // Initial persistence (snapshot at start).
+    void this.persistLive(entry);
+    this.fireLifecycle('started', this.toInfo(entry));
+
+    // Monitor lifecycle via wait() — no EventEmitter dependency.
+    entry.lifecyclePromise = proc
+      .wait()
+      .then((exitCode) => this.settleProcessExit(entry, exitCode))
+      .catch(async (_err: unknown) => {
+        // When `proc.wait()` rejects (launch failed / stream error),
+        // still drive the task through the same terminal finalizer.
+        await this.finalizeTerminal(entry, entry.stopRequested ? 'killed' : 'failed', null);
+      });
+    void entry.lifecyclePromise;
+
+    return taskId;
+  }
+
+  /** Get info about a specific task. Falls back to reconcile ghosts. */
+  getTask(taskId: string): BackgroundTaskInfo | undefined {
+    const entry = this.processes.get(taskId);
+    if (entry !== undefined) {
+      return this.toInfo(entry);
+    }
+    return this.ghosts.get(taskId);
+  }
+
+  /**
+   * Give just-ended processes a short grace period to settle their `wait()`
+   * promise, then return with whatever lifecycle state has been finalized.
+   */
+  async settlePendingExits(): Promise<void> {
+    const pendingCompletions = this.observedExitCompletions();
+    if (pendingCompletions.length === 0) return;
+    await Promise.race([
+      Promise.allSettled(pendingCompletions).then(() => {}),
+      new Promise<void>((resolve) => {
+        setTimeout(resolve, EXIT_SETTLE_GRACE_MS);
+      }),
+    ]);
+  }
+
+  /**
+   * List tasks, optionally filtering to active-only.
+   *
+   * When `activeOnly=false`, includes reconcile ghosts (lost tasks
+   * from a prior CLI process) so the user sees what survived the
+   * restart. Active-only mode never shows ghosts (they're terminal).
+   */
+  list(activeOnly = true, limit?: number): BackgroundTaskInfo[] {
+    const result: BackgroundTaskInfo[] = [];
+    for (const entry of this.processes.values()) {
+      // An awaiting_approval task is non-terminal and therefore counts
+      // as active in listings (UI needs to show it alongside plain
+      // running tasks).
+      if (activeOnly && TERMINAL_STATUSES.has(entry.status)) continue;
+      result.push(this.toInfo(entry));
+      if (limit !== undefined && result.length >= limit) return result;
+    }
+    if (!activeOnly) {
+      for (const ghost of this.ghosts.values()) {
+        result.push(ghost);
+        if (limit !== undefined && result.length >= limit) return result;
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Await all pending `output.log` appends for a task to settle.
+   *
+   * Output chunks are persisted to disk on an async queue, so a task can
+   * reach a terminal state before its final chunks have landed on disk.
+   * Callers that read the on-disk log (`getOutputSizeBytes` /
+   * `readOutputBytesFromDisk`) should `await flushOutput()` first so they
+   * observe the complete log. No-op for unknown/ghost tasks.
+   */
+  async flushOutput(taskId: string): Promise<void> {
+    const entry = this.processes.get(taskId);
+    if (entry === undefined) return;
+    await entry.outputWriteQueue;
+  }
+
+  /**
+   * Total byte size of a task's full output as stored on disk.
+   *
+   * Reads `<sessionDir>/tasks/<id>/output.log`, which is the complete,
+   * never-truncated log — unlike the in-memory ring buffer it never drops
+   * old chunks. Returns 0 when the manager is detached, the task is
+   * unknown, or the task has produced no output yet.
+   */
+  async getOutputSizeBytes(taskId: string): Promise<number> {
+    const outputSessionDir = this.outputSessionDirFor(taskId);
+    if (outputSessionDir === undefined) return 0;
+    return taskOutputSizeBytes(outputSessionDir, taskId);
+  }
+
+  /**
+   * Read a byte range of a task's full output from the on-disk log.
+   *
+   * Reads up to `maxBytes` bytes starting at `offset` of `output.log`,
+   * straight from disk so it never loses the head of a large task the way
+   * the in-memory ring buffer would. Callers derive `offset` and `maxBytes`
+   * from a single `getOutputSizeBytes` snapshot, so the bytes returned stay
+   * consistent with the size used for metadata even when a still-running
+   * task keeps growing its log. Returns an empty string when the manager
+   * is detached, the task is unknown, or the log is absent.
+   */
+  async readOutputBytesFromDisk(
+    taskId: string,
+    offset: number,
+    maxBytes: number,
+  ): Promise<string> {
+    const outputSessionDir = this.outputSessionDirFor(taskId);
+    if (outputSessionDir === undefined) return '';
+    return readTaskOutputBytes(outputSessionDir, taskId, offset, maxBytes);
+  }
+
+  /**
+   * Return the output snapshot used by TaskOutput.
+   *
+   * Persisted logs are preferred when the task was registered with an
+   * output session directory and `output.log` has actually been created,
+   * because they are the complete, never-truncated source. Detached managers,
+   * tasks registered before a session dir was attached, and silent tasks with
+   * no persisted log fall back to the live ring buffer.
+   */
+  async getOutputSnapshot(
+    taskId: string,
+    maxPreviewBytes: number,
+  ): Promise<BackgroundTaskOutputSnapshot> {
+    if (this.getTask(taskId) === undefined) return emptyOutputSnapshot();
+
+    await this.flushOutput(taskId);
+
+    const previewLimit = Math.max(0, Math.trunc(maxPreviewBytes));
+    const outputSessionDir = this.outputSessionDirFor(taskId);
+    if (outputSessionDir !== undefined && (await taskOutputExists(outputSessionDir, taskId))) {
+      const outputSizeBytes = await taskOutputSizeBytes(outputSessionDir, taskId);
+      const previewOffset = Math.max(0, outputSizeBytes - previewLimit);
+      const previewBytes = outputSizeBytes - previewOffset;
+      const preview = await readTaskOutputBytes(
+        outputSessionDir,
+        taskId,
+        previewOffset,
+        previewBytes,
+      );
+      return {
+        outputPath: taskOutputFile(outputSessionDir, taskId),
+        outputSizeBytes,
+        previewBytes,
+        truncated: previewOffset > 0,
+        fullOutputAvailable: true,
+        preview,
+      };
+    }
+
+    const entry = this.processes.get(taskId);
+    if (entry === undefined) return emptyOutputSnapshot();
+
+    const available = Buffer.from(entry.outputChunks.join(''), 'utf-8');
+    const previewBytes = Math.min(previewLimit, available.byteLength, entry.outputSizeBytes);
+    const previewOffset = available.byteLength - previewBytes;
+    return {
+      outputSizeBytes: entry.outputSizeBytes,
+      previewBytes,
+      truncated: entry.outputSizeBytes > previewBytes,
+      fullOutputAvailable: false,
+      preview: available.subarray(previewOffset).toString('utf-8'),
+    };
+  }
+
+  /** Get the combined output of a task (tail of the ring buffer). */
+  getOutput(taskId: string, tail?: number): string {
+    const entry = this.processes.get(taskId);
+    if (!entry) return '';
+    const full = entry.outputChunks.join('');
+    if (tail !== undefined && tail < full.length) {
+      return full.slice(-tail);
+    }
+    return full;
+  }
+
+  async readOutput(taskId: string, tail?: number): Promise<string> {
+    const entry = this.processes.get(taskId);
+    const outputSessionDir = this.outputSessionDirFor(taskId);
+    if (outputSessionDir !== undefined) {
+      await entry?.outputWriteQueue;
+      const persisted = await readTaskOutput(outputSessionDir, taskId);
+      if (persisted.length > 0) {
+        if (tail !== undefined && tail < persisted.length) {
+          return persisted.slice(-tail);
+        }
+        return persisted;
+      }
+    }
+    return this.getOutput(taskId, tail);
+  }
+
+  getOutputPath(taskId: string): string | undefined {
+    const outputSessionDir = this.outputSessionDirFor(taskId);
+    if (outputSessionDir === undefined) return undefined;
+    if (!taskOutputExistsSync(outputSessionDir, taskId)) return undefined;
+    return taskOutputFile(outputSessionDir, taskId);
+  }
+
+  /** Stop a running task. SIGTERM → 5s grace → SIGKILL. */
+  async stop(taskId: string, reason?: string): Promise<BackgroundTaskInfo | undefined> {
+    const entry = this.processes.get(taskId);
+    if (!entry) return undefined;
+    // Normalize at this shared boundary: every public stop path (the TaskStop
+    // tool, SDK/RPC) funnels through here, so a blank or whitespace-only
+    // reason must never be recorded as an empty stopReason.
+    const trimmedReason = reason?.trim();
+    const stopReason =
+      trimmedReason === undefined || trimmedReason.length === 0 ? undefined : trimmedReason;
+    // Terminal tasks short-circuit. awaiting_approval tasks can still
+    // be stopped (the approval gate is lifted when we transition to
+    // 'killed').
+    if (TERMINAL_STATUSES.has(entry.status)) {
+      await entry.persistWriteQueue;
+      return this.toInfo(entry);
+    }
+
+    entry.approvalReason = undefined;
+    entry.stopRequested = true;
+    entry.stopReason = stopReason;
+
+    try {
+      await entry.proc.kill('SIGTERM');
+    } catch {
+      /* process already gone */
+    }
+
+    // Wait up to 5s for the lifecycle path to settle, then SIGKILL.
+    // Waiting on lifecyclePromise, rather than proc.wait() directly, lets a
+    // natural completion win the race instead of being overwritten here.
+    let graceTimer: ReturnType<typeof setTimeout> | undefined;
+    const graceful = await Promise.race([
+      entry.lifecyclePromise.then(
+        () => true,
+        () => true,
+      ),
+      new Promise<false>((resolve) => {
+        graceTimer = setTimeout(() => {
+          resolve(false);
+        }, SIGTERM_GRACE_MS);
+      }),
+    ]);
+    if (graceTimer !== undefined) clearTimeout(graceTimer);
+
+    if (TERMINAL_STATUSES.has(entry.status)) {
+      await entry.persistWriteQueue;
+      return this.toInfo(entry);
+    }
+
+    if (!graceful && entry.proc.exitCode === null) {
+      try {
+        await entry.proc.kill('SIGKILL');
+      } catch {
+        /* ignore */
+      }
+    }
+
+    if (TERMINAL_STATUSES.has(entry.status)) {
+      await entry.persistWriteQueue;
+      return this.toInfo(entry);
+    }
+
+    // Agent tasks whose completion promise never settles (no timeoutMs,
+    // or a truly hung coroutine) need an explicit terminal finalize here.
+    await this.finalizeTerminal(entry, 'killed', null, { stopReason });
+
+    return this.toInfo(entry);
+  }
+
+  async stopAll(reason?: string): Promise<readonly BackgroundTaskInfo[]> {
+    const taskIds = Array.from(this.processes.values())
+      .filter((entry) => !TERMINAL_STATUSES.has(entry.status))
+      .map((entry) => entry.taskId);
+    const results = await Promise.all(taskIds.map((taskId) => this.stop(taskId, reason)));
+    return results.filter((info): info is BackgroundTaskInfo => info !== undefined);
+  }
+
+  /**
+   * Wait for a task to reach a terminal state.
+   * Returns immediately if already terminal. Times out after `timeoutMs`.
+   */
+  async wait(taskId: string, timeoutMs = 30_000): Promise<BackgroundTaskInfo | undefined> {
+    const entry = this.processes.get(taskId);
+    if (!entry) return undefined;
+    if (TERMINAL_STATUSES.has(entry.status)) {
+      await entry.persistWriteQueue;
+      return this.toInfo(entry);
+    }
+
+    let terminalWaiter: (() => void) | undefined;
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        new Promise<void>((resolve) => {
+          terminalWaiter = resolve;
+          entry.waiters.push(resolve);
+        }),
+        new Promise<void>((resolve) => {
+          timeout = setTimeout(resolve, timeoutMs);
+        }),
+      ]);
+    } finally {
+      if (timeout !== undefined) clearTimeout(timeout);
+      if (terminalWaiter !== undefined) {
+        const index = entry.waiters.indexOf(terminalWaiter);
+        if (index !== -1) entry.waiters.splice(index, 1);
+      }
+    }
+
+    if (TERMINAL_STATUSES.has(entry.status)) {
+      await entry.persistWriteQueue;
+    }
+    return this.toInfo(entry);
+  }
+
+  /**
+   * Register a Promise-based agent task (no KaosProcess). Used by
+   * AgentTool for background subagent dispatch. Agent tasks appear in
+   * `list()` / `getTask()` but have pid=0 and empty output.
+   *
+   * `opts.timeoutMs` wraps the completion in an external deadline. On
+   * deadline fire, the task is marked `failed` with `timedOut=true`
+   * (distinct from a caller-driven `stop()` which uses `killed`, and
+   * distinct from an internal `TimeoutError` rejection which is a
+   * generic `failed` with `timedOut` left unset).
+   */
+  registerAgentTask(
+    completion: Promise<{ result: string }>,
+    description: string,
+    opts: {
+      timeoutMs?: number;
+      abort?: () => void;
+      reservation?: BackgroundTaskReservation;
+      /** Subagent identifier; surfaced on task info. */
+      agentId?: string;
+      /** Subagent profile name; surfaced on task info. */
+      subagentType?: string;
+    } = {},
+  ): string {
+    if (opts.reservation) {
+      opts.reservation.release();
+    } else {
+      this.assertCanRegister();
+    }
+    const taskId = generateTaskId('agent');
+    const entry: ManagedProcess = {
+      taskId,
+      command: `[agent] ${description}`,
+      description,
+      timeoutMs: opts.timeoutMs,
+      // Fall back to defaults that satisfy callers reading these fields
+      // without forcing every call site to supply them. The dedicated
+      // dispatch path in AgentTool passes the real handle.agentId /
+      // handle.profileName.
+      agentId: opts.agentId ?? taskId,
+      subagentType: opts.subagentType ?? 'agent',
+      // Dummy KaosProcess — agent tasks are Promise-based, not process-based
+      proc: {
+        stdin: { write: () => false, end: () => {} } as never,
+        stdout: { setEncoding: () => {}, on: () => {} } as never,
+        stderr: { setEncoding: () => {}, on: () => {} } as never,
+        pid: 0,
+        exitCode: null,
+        wait: () => completion.then(() => 0),
+        kill: async () => {
+          opts.abort?.();
+        },
+      } as unknown as KaosProcess,
+      outputChunks: [],
+      outputSizeBytes: 0,
+      status: 'running',
+      exitCode: null,
+      startedAt: Date.now(),
+      endedAt: null,
+      waiters: [],
+      terminalFired: false,
+      stopRequested: false,
+      outputSessionDir: this.sessionDir,
+      lifecyclePromise: Promise.resolve(),
+      persistWriteQueue: Promise.resolve(),
+      outputWriteQueue: Promise.resolve(),
+    };
+    this.processes.set(taskId, entry);
+    void this.persistLive(entry);
+    this.fireLifecycle('started', this.toInfo(entry));
+
+    // Deadline symbol distinguishes "external timeout fired" from "the
+    // agent promise itself rejected with TimeoutError" (which must
+    // remain a generic failure, not a deadline timeout).
+    const deadlineTimeout = Symbol('deadline-timeout');
+    let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+
+    const raceInputs: Array<Promise<unknown>> = [completion];
+    if (opts.timeoutMs !== undefined && opts.timeoutMs > 0) {
+      raceInputs.push(
+        new Promise((resolve) => {
+          deadlineTimer = setTimeout(() => {
+            resolve(deadlineTimeout);
+          }, opts.timeoutMs);
+        }),
+      );
+    }
+
+    const settleLifecycle = Promise.race(raceInputs)
+      .then(async (outcome) => {
+        if (outcome === deadlineTimeout) {
+          // External deadline fired before the agent resolved.
+          if (TERMINAL_STATUSES.has(entry.status)) return;
+          opts.abort?.();
+          await this.finalizeTerminal(entry, 'failed', 1, { timedOut: true });
+          return;
+        }
+        // `completion` resolved before deadline.
+        const r = outcome as { result: string };
+        if (TERMINAL_STATUSES.has(entry.status)) return;
+        this.appendOutput(entry, r.result);
+        await this.finalizeTerminal(entry, 'completed', 0);
+      })
+      .catch(async (error: unknown) => {
+        // Caller-driven stop() that ran to completion through our own
+        // abort callback: the rejection is an AbortError-shaped object.
+        // Treat as `killed` so user-initiated cancellation is recorded
+        // as a cancellation, not a failure. The shape check is
+        // load-bearing — if a non-AbortError rejection arrives while
+        // `stopRequested` is set, it means a real failure (e.g. a
+        // model error) won the race against the in-flight stop, and we
+        // must record that failure rather than hide it behind the
+        // user's cancellation.
+        if (entry.stopRequested && isAbortError(error)) {
+          await this.finalizeTerminal(entry, 'killed', null);
+          return;
+        }
+        // Runner-initiated cancellation: the background agent runner
+        // raises `RunCancelled` to signal "abort this run" (e.g. on a
+        // Ctrl+C path with no BPM-side stop()). Map to `killed`
+        // because cancellation is not a failure.
+        if (error instanceof Error && error.name === 'RunCancelled') {
+          await this.finalizeTerminal(entry, 'killed', null);
+          return;
+        }
+        // Internal rejection (including TimeoutError, model errors,
+        // and stopRequested cases where a non-abort failure won the
+        // race): generic failure. `timedOut` stays unset so consumers
+        // can distinguish this from a true external deadline.
+        await this.finalizeTerminal(entry, 'failed', 1);
+      })
+      .finally(() => {
+        if (deadlineTimer !== undefined) clearTimeout(deadlineTimer);
+      });
+
+    entry.lifecyclePromise = settleLifecycle;
+    void entry.lifecyclePromise;
+
+    return taskId;
+  }
+
+  // ── awaiting_approval state transitions ────────────────────────────
+
+  /**
+   * Mark a running task as paused pending approval. The approval reason
+   * (tool call description) is retained until the task either returns
+   * to `'running'` via `clearAwaitingApproval()` or reaches a terminal
+   * state. Calls on terminal or unknown tasks are silently ignored so
+   * the ApprovalRuntime callback path is race-safe.
+   */
+  markAwaitingApproval(taskId: string, reason: string): void {
+    const entry = this.processes.get(taskId);
+    if (!entry) return;
+    if (TERMINAL_STATUSES.has(entry.status)) return;
+    entry.status = 'awaiting_approval';
+    entry.approvalReason = reason;
+    void this.persistLive(entry);
+    this.fireLifecycle('updated', this.toInfo(entry));
+  }
+
+  /**
+   * Drop the approval gate and return to `'running'`. Clears the stored
+   * reason so stale text cannot leak into a future `awaiting_approval`
+   * cycle. No-op unless the task is currently in the awaiting_approval
+   * state.
+   */
+  clearAwaitingApproval(taskId: string): void {
+    const entry = this.processes.get(taskId);
+    if (!entry) return;
+    if (entry.status !== 'awaiting_approval') return;
+    entry.status = 'running';
+    entry.approvalReason = undefined;
+    void this.persistLive(entry);
+    this.fireLifecycle('updated', this.toInfo(entry));
+  }
+
+  // ── completion event (await lifecycle end) ────────────────────────
+
+  /**
+   * Resolve when the task reaches a terminal state. If the task is
+   * already terminal, resolves synchronously on the next microtask.
+   * Intended for integration code that wants to `await` a specific
+   * task's exit without installing a full `onTerminal` subscriber.
+   * Returns `undefined` for unknown ids (matching `getTask`). Ghost
+   * (reconciled-lost) entries are considered terminal from the
+   * manager's perspective.
+   */
+  async waitForTerminal(taskId: string): Promise<BackgroundTaskInfo | undefined> {
+    const entry = this.processes.get(taskId);
+    if (entry === undefined) return this.ghosts.get(taskId);
+    if (TERMINAL_STATUSES.has(entry.status)) {
+      await entry.persistWriteQueue;
+      return this.toInfo(entry);
+    }
+    await new Promise<void>((resolve) => {
+      entry.waiters.push(resolve);
+    });
+    await entry.persistWriteQueue;
+    return this.toInfo(entry);
+  }
+
+  /** Reset internal state (for testing). */
+  _reset(): void {
+    this.processes.clear();
+    this.ghosts.clear();
+    this.sessionDir = undefined;
+  }
+
+  // ── persistence + reconcile ────────────────────────────────────────
+
+  /**
+   * Attach the manager to a session directory for persistence. Tasks
+   * created via `register()` after this call are written to
+   * `<sessionDir>/tasks/<task_id>.json` and updated on lifecycle change.
+   * Tasks created before attach are NOT retroactively persisted.
+   */
+  attachSessionDir(sessionDir: string): void {
+    this.sessionDir = sessionDir;
+  }
+
+  /**
+   * Load persisted task records into the ghost map. Does NOT reconcile
+   * (call `reconcile()` after `loadFromDisk()`). Idempotent; subsequent
+   * calls overwrite the ghost map.
+   *
+   * Requires `attachSessionDir()` first; no-op otherwise.
+   */
+  async loadFromDisk(): Promise<void> {
+    if (this.sessionDir === undefined) return;
+    this.ghosts.clear();
+    const persisted = await listTasks(this.sessionDir);
+    for (const t of persisted) {
+      // Skip ids that already exist as live processes — live wins.
+      if (this.processes.has(t.task_id)) continue;
+      this.ghosts.set(t.task_id, persistedToInfo(t));
+    }
+  }
+
+  /**
+   * Reconcile loaded ghost tasks. Any ghost with status `running` is
+   * reclassified as `lost` (its previous CLI process died without
+   * writing a terminal state). Updates the on-disk record and returns
+   * the lost task ids so the caller can emit user-facing notifications.
+   */
+  protected async markLoadedTasksLost(): Promise<ReconcileResult> {
+    const lost: string[] = [];
+    const lostInfo: BackgroundTaskInfo[] = [];
+    for (const [id, info] of this.ghosts) {
+      // Any non-terminal ghost is lost. Includes `awaiting_approval`
+      // (the approval context died with the previous process so it
+      // cannot be resumed).
+      if (TERMINAL_STATUSES.has(info.status)) continue;
+      const updated: BackgroundTaskInfo = {
+        ...info,
+        status: 'lost',
+        endedAt: info.endedAt ?? Date.now(),
+        approvalReason: undefined,
+        failureReason: 'Background worker heartbeat expired',
+      };
+      this.ghosts.set(id, updated);
+      if (this.sessionDir !== undefined) {
+        await writeTask(this.sessionDir, infoToPersisted(updated));
+      }
+      lost.push(id);
+      lostInfo.push(updated);
+    }
+    return { lost, lostInfo };
+  }
+
+  async reconcile(): Promise<ReconcileResult> {
+    const result = await this.markLoadedTasksLost();
+    // Fire onTerminal for newly-lost ghosts so NotificationManager
+    // receives a `task.lost` notification. Dedupe on the consumer side
+    // is by `dedupe_key`; a second reconcile() on the same ghost is a
+    // no-op because the status flips to `lost` above and we guard on
+    // TERMINAL_STATUSES on the next pass.
+    for (const info of result.lostInfo) {
+      this.fireTerminalSubscribers(info);
+    }
+    return result;
+  }
+
+  /** Drop a persisted task from disk and ghost map. */
+  async forgetTask(taskId: string): Promise<void> {
+    this.ghosts.delete(taskId);
+    if (this.sessionDir !== undefined) {
+      await removeTask(this.sessionDir, taskId);
+    }
+  }
+
+  /**
+   * Persist the current state of a live ManagedProcess. Called from
+   * `register()` and the lifecycle finally block. No-op unless attached.
+   */
+  private persistLive(entry: ManagedProcess): Promise<void> {
+    if (this.sessionDir === undefined) return Promise.resolve();
+    const sessionDir = this.sessionDir;
+    const task: PersistedTask = {
+      task_id: entry.taskId,
+      command: entry.command,
+      description: entry.description,
+      pid: entry.proc.pid,
+      started_at: entry.startedAt,
+      ended_at: entry.endedAt,
+      exit_code: entry.exitCode,
+      status: entry.status,
+      approval_reason: entry.approvalReason,
+      timed_out: entry.timedOut,
+      stop_reason: entry.stopReason,
+    };
+    entry.persistWriteQueue = entry.persistWriteQueue
+      .then(() => writeTask(sessionDir, task))
+      .catch(() => {});
+    return entry.persistWriteQueue;
+  }
+
+  private appendOutput(entry: ManagedProcess, chunk: string): void {
+    entry.outputSizeBytes += Buffer.byteLength(chunk, 'utf-8');
+    entry.outputChunks.push(chunk);
+    // Enforce output cap: drop oldest chunks when over budget.
+    let total = entry.outputChunks.reduce((s, c) => s + c.length, 0);
+    while (total > MAX_OUTPUT_BYTES && entry.outputChunks.length > 1) {
+      const removed = entry.outputChunks.shift();
+      if (removed === undefined) break;
+      total -= removed.length;
+    }
+
+    const outputSessionDir = entry.outputSessionDir;
+    if (outputSessionDir === undefined) return;
+    entry.outputWriteQueue = entry.outputWriteQueue
+      .then(() => appendTaskOutput(outputSessionDir, entry.taskId, chunk))
+      .catch(() => {});
+  }
+
+  private outputSessionDirFor(taskId: string): string | undefined {
+    const entry = this.processes.get(taskId);
+    if (entry !== undefined) return entry.outputSessionDir;
+    if (this.ghosts.has(taskId)) return this.sessionDir;
+    return undefined;
+  }
+
+  private async settleProcessExit(entry: ManagedProcess, exitCode: number): Promise<void> {
+    if (TERMINAL_STATUSES.has(entry.status)) {
+      if (entry.status === 'killed' && entry.exitCode === null) {
+        entry.exitCode = exitCode;
+        entry.endedAt = Date.now();
+        await this.persistLive(entry);
+        this.fireTerminalCallbacks(entry);
+        this.resolveWaiters(entry);
+      }
+      return;
+    }
+    const status = entry.stopRequested ? 'killed' : exitCode === 0 ? 'completed' : 'failed';
+    await this.finalizeTerminal(entry, status, exitCode);
+  }
+
+  private observedExitCompletions(): Promise<void>[] {
+    const completions: Promise<void>[] = [];
+    for (const entry of this.processes.values()) {
+      if (!TERMINAL_STATUSES.has(entry.status) && entry.proc.exitCode !== null) {
+        completions.push(entry.lifecyclePromise);
+      }
+    }
+    return completions;
+  }
+
+  private toInfo(entry: ManagedProcess): BackgroundTaskInfo {
+    return {
+      taskId: entry.taskId,
+      command: entry.command,
+      description: entry.description,
+      status: entry.status,
+      pid: entry.proc.pid,
+      exitCode: entry.exitCode,
+      startedAt: entry.startedAt,
+      endedAt: entry.endedAt,
+      approvalReason: entry.approvalReason,
+      timedOut: entry.timedOut,
+      stopReason: entry.stopReason,
+      timeoutMs: entry.timeoutMs,
+      agentId: entry.agentId,
+      subagentType: entry.subagentType,
+      failureReason: entry.failureReason,
+    };
+  }
+
+  private async finalizeTerminal(
+    entry: ManagedProcess,
+    status: BackgroundTaskStatus,
+    exitCode: number | null,
+    options: { readonly timedOut?: boolean; readonly stopReason?: string } = {},
+  ): Promise<boolean> {
+    if (TERMINAL_STATUSES.has(entry.status)) return false;
+    entry.status = status;
+    entry.exitCode = exitCode;
+    entry.endedAt = Date.now();
+    entry.timedOut = options.timedOut;
+    entry.stopReason = status === 'killed' ? (options.stopReason ?? entry.stopReason) : undefined;
+    // A task that ended while still in awaiting_approval (e.g. crashed
+    // mid-prompt, deadline fired, or got killed) must not leak the
+    // stale approvalReason onto the terminal record. The awaiting →
+    // running path (clearAwaitingApproval) already clears it; mirror
+    // that here for the awaiting → terminal path.
+    entry.approvalReason = undefined;
+    entry.stopRequested = false;
+    await this.persistLive(entry);
+    this.fireTerminalCallbacks(entry);
+    this.resolveWaiters(entry);
+    return true;
+  }
+}
+
+// ── persistence shape <-> in-memory shape ──────────────────────────────
+
+function persistedToInfo(t: PersistedTask): BackgroundTaskInfo {
+  return {
+    taskId: t.task_id,
+    command: t.command,
+    description: t.description,
+    status: t.status,
+    pid: t.pid,
+    exitCode: t.exit_code,
+    startedAt: t.started_at,
+    endedAt: t.ended_at,
+    approvalReason: t.approval_reason,
+    timedOut: t.timed_out,
+    stopReason: t.stop_reason,
+  };
+}
+
+function infoToPersisted(info: BackgroundTaskInfo): PersistedTask {
+  return {
+    task_id: info.taskId,
+    command: info.command,
+    description: info.description,
+    pid: info.pid,
+    started_at: info.startedAt,
+    ended_at: info.endedAt,
+    exit_code: info.exitCode,
+    status: info.status,
+    approval_reason: info.approvalReason,
+    timed_out: info.timedOut,
+    stop_reason: info.stopReason,
+  };
+}
diff --git a/packages/agent-core/src/tools/background/persist.ts b/packages/agent-core/src/tools/background/persist.ts
new file mode 100644
index 000000000..bc4364e29
--- /dev/null
+++ b/packages/agent-core/src/tools/background/persist.ts
@@ -0,0 +1,269 @@
+/**
+ * Background task persistence helpers.
+ *
+ * Each task lives at `<sessionDir>/tasks/<task_id>.json` so a CLI
+ * restart can list previously-running tasks (now lost) and emit terminal
+ * notifications.
+ *
+ * Writes use `atomicWrite` (write-tmp-fsync-rename) so a crash mid-write
+ * never leaves a half-truncated file.
+ */
+
+import { statSync } from 'node:fs';
+import { appendFile, mkdir, open, readFile, readdir, rm, stat, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { atomicWrite } from '../../utils/fs';
+import type { BackgroundTaskStatus } from './manager';
+
+/**
+ * Task id format: `{bash|agent}-{8 chars of [0-9a-z]}`.
+ *
+ * Strictly enforced by `taskFile()` so neither path-traversal (`../`)
+ * nor a legacy `bg_<hex>` format can escape through the persistence
+ * layer.
+ */
+export const VALID_TASK_ID: RegExp = /^(bash|agent)-[0-9a-z]{8}$/;
+
+/** On-disk task representation (snake_case, Python-friendly). */
+export interface PersistedTask {
+  readonly task_id: string;
+  readonly command: string;
+  readonly description: string;
+  readonly pid: number;
+  readonly started_at: number;
+  readonly ended_at: number | null;
+  readonly exit_code: number | null;
+  readonly status: BackgroundTaskStatus;
+  /**
+   * Reason supplied when the task is marked `awaiting_approval`.
+   * Cleared (omitted) when the task leaves that state.
+   */
+  readonly approval_reason?: string | undefined;
+  /**
+   * True when an agent task was forcibly terminated by its external
+   * deadline (`registerAgentTask(..., { timeoutMs })`). An internal
+   * `TimeoutError` raised by the agent promise itself is a generic
+   * failure and does NOT set this flag.
+   */
+  readonly timed_out?: boolean | undefined;
+  /** Reason recorded when a task is explicitly stopped. */
+  readonly stop_reason?: string | undefined;
+  /**
+   * Shell origin metadata (name / path / cwd) captured when
+   * `BackgroundProcessManager.register` attached a `shellInfo` option.
+   * Persisted so restart can reconstruct the spawn environment.
+   */
+  readonly shell_info?:
+    | {
+        readonly name: string;
+        readonly path?: string | undefined;
+        readonly cwd?: string | undefined;
+      }
+    | undefined;
+}
+
+function tasksDirOf(sessionDir: string): string {
+  return join(sessionDir, 'tasks');
+}
+
+function taskFile(sessionDir: string, taskId: string): string {
+  if (!VALID_TASK_ID.test(taskId)) {
+    throw new Error(`Invalid task id: "${taskId}"`);
+  }
+  return join(tasksDirOf(sessionDir), `${taskId}.json`);
+}
+
+function taskOutputDir(sessionDir: string, taskId: string): string {
+  if (!VALID_TASK_ID.test(taskId)) {
+    throw new Error(`Invalid task id: "${taskId}"`);
+  }
+  return join(tasksDirOf(sessionDir), taskId);
+}
+
+export function taskOutputFile(sessionDir: string, taskId: string): string {
+  return join(taskOutputDir(sessionDir, taskId), 'output.log');
+}
+
+/** Atomically write a task's persisted state. Creates dirs as needed. */
+export async function writeTask(sessionDir: string, task: PersistedTask): Promise<void> {
+  await mkdir(tasksDirOf(sessionDir), { recursive: true, mode: 0o700 });
+  const target = taskFile(sessionDir, task.task_id);
+  await atomicWrite(target, JSON.stringify(task, null, 2));
+}
+
+/** Read a single task file. Returns undefined when missing/corrupt. */
+export async function readTask(
+  sessionDir: string,
+  taskId: string,
+): Promise<PersistedTask | undefined> {
+  // Path-traversal validation runs before the try/catch so callers see
+  // an explicit error instead of a misleading "missing" return.
+  const path = taskFile(sessionDir, taskId);
+  let raw: string;
+  try {
+    raw = await readFile(path, 'utf-8');
+  } catch {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    if (typeof parsed !== 'object' || parsed === null) return undefined;
+    return parsed as unknown as PersistedTask;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function appendTaskOutput(
+  sessionDir: string,
+  taskId: string,
+  chunk: string,
+): Promise<void> {
+  const path = taskOutputFile(sessionDir, taskId);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await appendFile(path, chunk, 'utf-8');
+}
+
+export async function readTaskOutput(sessionDir: string, taskId: string): Promise<string> {
+  try {
+    return await readFile(taskOutputFile(sessionDir, taskId), 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Total byte size of a task's `output.log`. Returns 0 when the log does
+ * not exist yet (the task has produced no output, or is unknown).
+ *
+ * This is the authoritative full-output size — unlike the in-memory ring
+ * buffer it is never truncated, so callers can report how much output a
+ * task has actually produced.
+ */
+export async function taskOutputSizeBytes(sessionDir: string, taskId: string): Promise<number> {
+  try {
+    const st = await stat(taskOutputFile(sessionDir, taskId));
+    return st.size;
+  } catch {
+    return 0;
+  }
+}
+
+export async function taskOutputExists(sessionDir: string, taskId: string): Promise<boolean> {
+  try {
+    return (await stat(taskOutputFile(sessionDir, taskId))).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function taskOutputExistsSync(sessionDir: string, taskId: string): boolean {
+  try {
+    return statSync(taskOutputFile(sessionDir, taskId)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read a byte window of a task's `output.log`.
+ *
+ * Reads at most `maxBytes` bytes starting at byte `offset`. A window that
+ * runs past EOF is clamped to whatever remains; an `offset` at/after EOF
+ * yields an empty string. Returns an empty string when the log is absent.
+ *
+ * Byte-level (not line-level) paging mirrors how the full log is stored
+ * on disk, so callers can page arbitrarily large logs without loading the
+ * whole file into memory.
+ */
+export async function readTaskOutputBytes(
+  sessionDir: string,
+  taskId: string,
+  offset: number,
+  maxBytes: number,
+): Promise<string> {
+  const start = Math.max(0, Math.trunc(offset));
+  const limit = Math.max(0, Math.trunc(maxBytes));
+  if (limit === 0) return '';
+  let handle;
+  try {
+    handle = await open(taskOutputFile(sessionDir, taskId), 'r');
+  } catch {
+    return '';
+  }
+  try {
+    const size = (await handle.stat()).size;
+    if (start >= size) return '';
+    const length = Math.min(limit, size - start);
+    const buffer = Buffer.allocUnsafe(length);
+    const { bytesRead } = await handle.read(buffer, 0, length, start);
+    return buffer.toString('utf-8', 0, bytesRead);
+  } catch {
+    return '';
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Enumerate all persisted tasks for a session. Skips corrupt entries. */
+export async function listTasks(sessionDir: string): Promise<PersistedTask[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(tasksDirOf(sessionDir));
+  } catch {
+    return [];
+  }
+  const out: PersistedTask[] = [];
+  for (const entry of entries) {
+    if (!entry.endsWith('.json')) continue;
+    const taskId = entry.slice(0, -'.json'.length);
+    // Silently drop: filename basename is not a valid task id (stray files,
+    // legacy bg_* leftovers, etc.).
+    if (!VALID_TASK_ID.test(taskId)) continue;
+    const task = await readTask(sessionDir, taskId);
+    // Silently drop: JSON parse failed or file disappeared between readdir
+    // and readTask. writeTask uses an atomic temp+rename pattern so a
+    // genuinely truncated file in production is rare; if it happens we
+    // accept the loss rather than emit a ghost with no recoverable
+    // metadata beyond the filename.
+    if (task === undefined) continue;
+    // Silently drop: parsed JSON is missing one or more required fields
+    // for a PersistedTask. Treated the same as a missing file.
+    if (!isValidPersistedTask(task)) continue;
+    out.push(task);
+  }
+  return out;
+}
+
+/**
+ * Validate that the parsed JSON actually shapes like a PersistedTask.
+ * Cheap shape check (not a full zod schema) — rejects the canonical
+ * "spec with missing fields" failure mode.
+ */
+function isValidPersistedTask(obj: unknown): obj is PersistedTask {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const o = obj as Record<string, unknown>;
+  return (
+    typeof o['task_id'] === 'string' &&
+    typeof o['command'] === 'string' &&
+    typeof o['description'] === 'string' &&
+    typeof o['pid'] === 'number' &&
+    typeof o['started_at'] === 'number' &&
+    (o['ended_at'] === null || typeof o['ended_at'] === 'number') &&
+    (o['exit_code'] === null || typeof o['exit_code'] === 'number') &&
+    typeof o['status'] === 'string'
+  );
+}
+
+/** Remove a task file (idempotent). */
+export async function removeTask(sessionDir: string, taskId: string): Promise<void> {
+  // Path-traversal validation outside try/catch.
+  const path = taskFile(sessionDir, taskId);
+  try {
+    await unlink(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  await rm(taskOutputDir(sessionDir, taskId), { recursive: true, force: true });
+}
diff --git a/packages/agent-core/src/tools/background/task-list.md b/packages/agent-core/src/tools/background/task-list.md
new file mode 100644
index 000000000..c2826c1ef
--- /dev/null
+++ b/packages/agent-core/src/tools/background/task-list.md
@@ -0,0 +1,24 @@
+List background tasks and their current status.
+
+Use this tool to discover which background tasks exist and where each one
+stands. It is the entry point for inspecting background work: it returns a
+task ID, status, command, description, and PID for every task it reports,
+plus the exit code and stop reason for tasks that have already finished.
+
+Guidelines:
+
+- After a context compaction, or whenever you are unsure which background
+  tasks are running or what their task IDs are, call this tool to
+  re-enumerate them instead of guessing a task ID.
+- Prefer the default `active_only=true`, which lists only non-terminal tasks.
+  Pass `active_only=false` only when you specifically need to see tasks that
+  have already finished. With `active_only=false` the result may also include
+  `lost` tasks — tasks left over from a previous process that can no longer be
+  inspected or controlled; treat them as already terminated.
+- `limit` caps how many tasks are returned. It accepts a value between 1 and
+  100 and defaults to 20 when omitted.
+- This tool only lists tasks; it does not return their output. Use it first
+  to locate the task ID you need, then call `TaskOutput` with that ID to read
+  the task's output and details.
+- This tool is read-only and does not change any state, so it is always safe
+  to call, including in plan mode.
diff --git a/packages/agent-core/src/tools/background/task-list.ts b/packages/agent-core/src/tools/background/task-list.ts
new file mode 100644
index 000000000..1a8c5ccd5
--- /dev/null
+++ b/packages/agent-core/src/tools/background/task-list.ts
@@ -0,0 +1,83 @@
+/**
+ * TaskListTool — list background tasks.
+ */
+
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../agent/tool';
+import type { ToolExecution } from '../../loop/types';
+import { toInputJsonSchema } from '../support/input-schema';
+import type { BackgroundProcessManager, BackgroundTaskInfo } from './manager';
+import { isBackgroundTaskTerminal } from './manager';
+import TASK_LIST_DESCRIPTION from './task-list.md';
+
+// ── Input schema ─────────────────────────────────────────────────────
+
+export const TaskListInputSchema = z.object({
+  active_only: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe('Whether to list only non-terminal background tasks.'),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(20)
+    .describe('Maximum number of tasks to return.')
+    .optional(),
+});
+
+export type TaskListInput = z.Infer<typeof TaskListInputSchema>;
+
+// ── Implementation ───────────────────────────────────────────────────
+
+function formatTask(t: BackgroundTaskInfo): string {
+  const lines = [
+    `task_id: ${t.taskId}`,
+    `status: ${t.status}`,
+    `command: ${t.command}`,
+    `description: ${t.description}`,
+    `pid: ${String(t.pid ?? 'N/A')}`,
+  ];
+  // Terminal tasks carry an outcome the AI needs to act on: the process
+  // exit code, and — when the task was ended via TaskStop — the stop reason.
+  if (isBackgroundTaskTerminal(t.status)) {
+    if (t.exitCode !== null) lines.push(`exit_code: ${String(t.exitCode)}`);
+    if (t.stopReason !== undefined) lines.push(`reason: ${t.stopReason}`);
+  }
+  return lines.join('\n');
+}
+
+function formatTaskList(tasks: BackgroundTaskInfo[], activeOnly: boolean): string {
+  // `active_only=false` mixes in terminal/lost tasks, so the count is no
+  // longer purely "active" — use a neutral label to avoid mislabeling them.
+  const label = activeOnly ? 'active_background_tasks' : 'background_tasks';
+  const header = `${label}: ${String(tasks.length)}`;
+  if (tasks.length === 0) return `${header}\nNo background tasks found.`;
+  return `${header}\n${tasks.map(formatTask).join('\n---\n')}`;
+}
+
+export class TaskListTool implements BuiltinTool<TaskListInput> {
+  readonly name = 'TaskList' as const;
+  readonly description = TASK_LIST_DESCRIPTION;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(TaskListInputSchema);
+
+  constructor(private readonly manager: BackgroundProcessManager) {}
+
+  resolveExecution(args: TaskListInput): ToolExecution {
+    return {
+      description: 'Listing background tasks',
+      execute: async () => {
+        await this.manager.settlePendingExits();
+        const activeOnly = args.active_only ?? true;
+        const tasks = this.manager.list(activeOnly, args.limit ?? 20);
+        return {
+          output: formatTaskList(tasks, activeOnly),
+          isError: false,
+        };
+      },
+    };
+  }
+}
diff --git a/packages/agent-core/src/tools/background/task-output.md b/packages/agent-core/src/tools/background/task-output.md
new file mode 100644
index 000000000..395f25379
--- /dev/null
+++ b/packages/agent-core/src/tools/background/task-output.md
@@ -0,0 +1,12 @@
+Retrieve output from a running or completed background task.
+
+Use this after `Bash(run_in_background=true)` when you need to inspect progress or explicitly wait for completion.
+
+Guidelines:
+- Prefer relying on automatic completion notifications. Use this tool only when you need task output before the automatic notification arrives.
+- By default this tool is non-blocking and returns a current status/output snapshot.
+- Use block=true only when you intentionally want to wait for completion or timeout.
+- This tool returns structured task metadata, a fixed-size output preview, and an output_path for the full log.
+- For a terminal task, the metadata also explains why it ended: `timed_out` when an agent task was aborted by its deadline, and `stop_reason` when the task was explicitly stopped. `terminal_reason` is a categorical label for the same event — its value is `timed_out` or `stopped` — and is emitted alongside the matching `timed_out` / `stop_reason` field. A task that ended on its own emits none of these three fields.
+- The full, never-truncated log is always available at output_path; use the `Read` tool with that path to page through it, whether or not the preview was truncated.
+- This tool works with the generic background task system and should remain the primary read path for future task types, not just bash.
diff --git a/packages/agent-core/src/tools/background/task-output.ts b/packages/agent-core/src/tools/background/task-output.ts
new file mode 100644
index 000000000..f77de21bf
--- /dev/null
+++ b/packages/agent-core/src/tools/background/task-output.ts
@@ -0,0 +1,179 @@
+/**
+ * TaskOutputTool — read output from a background task.
+ *
+ * Returns structured task metadata plus a fixed-size tail preview of the
+ * task's output. The full, never-truncated output lives on disk at
+ * `output_path`; the caller is always pointed at the `Read` tool to page
+ * through the complete log, and the preview also carries a banner when it
+ * has been truncated to a tail.
+ *
+ * For terminal tasks the output also surfaces why the task ended:
+ * `timed_out` when an agent task was aborted by its deadline, and
+ * `stop_reason` when the task was explicitly stopped via `TaskStop`.
+ */
+
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../agent/tool';
+import type { ExecutableToolResult, ToolExecution } from '../../loop/types';
+import {
+  isBackgroundTaskTerminal,
+  type BackgroundProcessManager,
+  type BackgroundTaskStatus,
+} from './manager';
+import { toInputJsonSchema } from '../support/input-schema';
+import TASK_OUTPUT_DESCRIPTION from './task-output.md';
+
+/**
+ * Maximum bytes of output included inline as a preview. Output larger
+ * than this is truncated to its tail; the full log is read separately
+ * via the `Read` tool with the returned `output_path`.
+ */
+const OUTPUT_PREVIEW_BYTES = 32 * 1024; // 32 KiB
+
+/** Number of lines the paging hint suggests reading per `Read` call. */
+const PAGING_HINT_LINES = 300;
+
+// ── Input schema ─────────────────────────────────────────────────────
+
+export const TaskOutputInputSchema = z.object({
+  task_id: z.string().describe('The background task ID to inspect.'),
+  block: z
+    .boolean()
+    .default(false)
+    .describe('Whether to wait for the task to finish before returning.')
+    .optional(),
+  timeout: z
+    .number()
+    .int()
+    .min(0)
+    .max(3600)
+    .default(30)
+    .describe('Maximum number of seconds to wait when block=true.')
+    .optional(),
+});
+
+export type TaskOutputInput = z.Infer<typeof TaskOutputInputSchema>;
+
+// ── Implementation ───────────────────────────────────────────────────
+
+function retrievalStatus(
+  status: BackgroundTaskStatus,
+  block: boolean | undefined,
+): 'success' | 'timeout' | 'not_ready' {
+  if (isBackgroundTaskTerminal(status)) return 'success';
+  return block ? 'timeout' : 'not_ready';
+}
+
+export class TaskOutputTool implements BuiltinTool<TaskOutputInput> {
+  readonly name = 'TaskOutput' as const;
+  readonly description: string = TASK_OUTPUT_DESCRIPTION;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(TaskOutputInputSchema);
+
+  constructor(private readonly manager: BackgroundProcessManager) {}
+
+  resolveExecution(args: TaskOutputInput): ToolExecution {
+    return {
+      description: `Reading output of task ${args.task_id}`,
+      execute: () => this.execute(args),
+    };
+  }
+
+  private async execute(args: TaskOutputInput): Promise<ExecutableToolResult> {
+    await this.manager.settlePendingExits();
+    const info = this.manager.getTask(args.task_id);
+    if (!info) {
+      return { isError: true, output: `Task not found: ${args.task_id}` };
+    }
+
+    if (args.block && !isBackgroundTaskTerminal(info.status)) {
+      await this.manager.wait(args.task_id, (args.timeout ?? 30) * 1000);
+    }
+
+    // Re-fetch after potential wait.
+    const current = this.manager.getTask(args.task_id);
+    if (!current) {
+      return { isError: true, output: `Task not found: ${args.task_id}` };
+    }
+
+    // A single manager-owned snapshot drives the tail window and every
+    // reported metric below. Persisted logs remain authoritative when
+    // available; detached managers fall back to their live ring buffer.
+    const output = await this.manager.getOutputSnapshot(args.task_id, OUTPUT_PREVIEW_BYTES);
+
+    const lines = [
+      `retrieval_status: ${retrievalStatus(current.status, args.block)}`,
+      `task_id: ${current.taskId}`,
+      `status: ${current.status}`,
+      `description: ${current.description}`,
+      `command: ${current.command}`,
+    ];
+    if (output.outputPath !== undefined) {
+      lines.push(`output_path: ${output.outputPath}`);
+    }
+    if (current.exitCode !== null) {
+      lines.push(`exit_code: ${String(current.exitCode)}`);
+    }
+    // Surface why a terminal task ended. `terminal_reason` is a categorical
+    // label; `timed_out` / `stop_reason` carry the concrete detail.
+    //   - timed_out: an agent task aborted by its external deadline.
+    //   - stopped:   the task was explicitly cancelled via `TaskStop`
+    //                (`stop_reason` is the reason text supplied there).
+    // A task that ended on its own (completed / failed / lost) emits none
+    // of these so the absence is itself meaningful.
+    if (current.timedOut === true) {
+      lines.push('timed_out: true', 'terminal_reason: timed_out');
+    } else if (current.stopReason !== undefined) {
+      lines.push(`stop_reason: ${current.stopReason}`, 'terminal_reason: stopped');
+    }
+    lines.push(
+      `output_size_bytes: ${String(output.outputSizeBytes)}`,
+      `output_preview_bytes: ${String(output.previewBytes)}`,
+      `output_truncated: ${String(output.truncated)}`,
+    );
+    // The full, never-truncated log is readable from disk via the `Read`
+    // tool whenever it was persisted. Surface that guidance unconditionally
+    // — even when the preview already shows everything — so the model knows
+    // it can page the complete output. The hint text adapts to whether the
+    // preview was truncated. When no full log was persisted, say so instead.
+    if (output.fullOutputAvailable && output.outputPath !== undefined) {
+      lines.push('full_output_available: true', 'full_output_tool: Read');
+      lines.push(
+        output.truncated
+          ? `full_output_hint: Only the last ${String(OUTPUT_PREVIEW_BYTES)} bytes are shown ` +
+              'above. Use the Read tool with the output_path to page through the full log ' +
+              `(parameters: path, line_offset, n_lines; read about ${String(PAGING_HINT_LINES)} ` +
+              'lines per page).'
+          : 'full_output_hint: The preview above is the complete output. Use the Read tool ' +
+              'with the output_path if you need to re-read the full log later ' +
+              `(parameters: path, line_offset, n_lines; read about ${String(PAGING_HINT_LINES)} ` +
+              'lines per page).',
+      );
+    } else {
+      lines.push('full_output_available: false');
+    }
+
+    // When the preview omits the head of the log, emit an explicit
+    // banner just before the `[output]` marker so the model knows it is
+    // looking at a tail, not the full output.
+    lines.push('');
+    if (output.truncated) {
+      lines.push(
+        output.fullOutputAvailable && output.outputPath !== undefined
+          ? `[Truncated. Full output: ${output.outputPath}]`
+          : '[Truncated. No persisted full log is available for this task.]',
+      );
+    }
+    lines.push('[output]', output.preview || '[no output available]');
+
+    // Side-channel brief for the host UI / log readers. Distinct from
+    // the `output` body which is parsed by the LLM. Kept short so log
+    // readers can render it as a one-liner.
+    return {
+      output: lines.join('\n'),
+      isError: false,
+      message: 'Task snapshot retrieved.',
+    };
+  }
+
+}
diff --git a/packages/agent-core/src/tools/background/task-stop.md b/packages/agent-core/src/tools/background/task-stop.md
new file mode 100644
index 000000000..c1ff20a01
--- /dev/null
+++ b/packages/agent-core/src/tools/background/task-stop.md
@@ -0,0 +1,13 @@
+Stop a running background task.
+
+Only use this when a task must genuinely be cancelled — for a task that is
+finishing normally, wait for its completion notification or inspect it with
+`TaskOutput` instead of stopping it.
+
+Guidelines:
+- This is a general-purpose stop capability for any background task. It is not
+  a bash-specific kill.
+- Stopping a task is destructive: it may leave partial side effects behind.
+  Use it with care.
+- If the task has already finished, this tool simply returns its current
+  status.
diff --git a/packages/agent-core/src/tools/background/task-stop.ts b/packages/agent-core/src/tools/background/task-stop.ts
new file mode 100644
index 000000000..20b93fa72
--- /dev/null
+++ b/packages/agent-core/src/tools/background/task-stop.ts
@@ -0,0 +1,87 @@
+/**
+ * TaskStopTool — stop a running background task.
+ */
+
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../agent/tool';
+import type { ToolExecution } from '../../loop/types';
+import { toInputJsonSchema } from '../support/input-schema';
+import { isBackgroundTaskTerminal, type BackgroundProcessManager } from './manager';
+import TASK_STOP_DESCRIPTION from './task-stop.md';
+
+// ── Input schema ─────────────────────────────────────────────────────
+
+export const TaskStopInputSchema = z.object({
+  task_id: z.string().describe('The background task ID to stop.'),
+  reason: z
+    .string()
+    .default('Stopped by TaskStop')
+    .describe('Short reason recorded when the task is stopped.')
+    .optional(),
+});
+
+export type TaskStopInput = z.Infer<typeof TaskStopInputSchema>;
+
+// ── Implementation ───────────────────────────────────────────────────
+
+export class TaskStopTool implements BuiltinTool<TaskStopInput> {
+  readonly name = 'TaskStop' as const;
+  readonly description = TASK_STOP_DESCRIPTION;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(TaskStopInputSchema);
+
+  constructor(private readonly manager: BackgroundProcessManager) {}
+
+  resolveExecution(args: TaskStopInput): ToolExecution {
+    return {
+      description: `Stopping task ${args.task_id}`,
+      execute: async () => {
+        await this.manager.settlePendingExits();
+        const info = this.manager.getTask(args.task_id);
+        if (!info) {
+          return { isError: true, output: `Task not found: ${args.task_id}` };
+        }
+
+        // A blank or whitespace-only reason falls back to the default. `?? default`
+        // would not cover the empty-string case, so trim and coalesce explicitly.
+        const trimmedReason = args.reason?.trim();
+        const reason =
+          trimmedReason === undefined || trimmedReason.length === 0
+            ? 'Stopped by TaskStop'
+            : trimmedReason;
+
+        if (isBackgroundTaskTerminal(info.status)) {
+          // Already-terminal tasks report their current state using the same
+          // structured multi-line format as the normal stop path below.
+          return {
+            output:
+              `task_id: ${info.taskId}\n` +
+              `status: ${info.status}\n` +
+              // A task persisted by an older build may carry a blank stopReason;
+              // `??` would not coalesce `''`, so trim-and-`||` to the placeholder.
+              `reason: ${terminalStopReason(info.stopReason)}`,
+            isError: false,
+          };
+        }
+
+        const result = await this.manager.stop(args.task_id, reason);
+        if (!result) {
+          return { isError: true, output: `Failed to stop task: ${args.task_id}` };
+        }
+
+        return {
+          output:
+            `task_id: ${result.taskId}\n` +
+            `status: ${result.status}\n` +
+            `reason: ${result.stopReason ?? reason}`,
+          isError: false,
+        };
+      },
+    };
+  }
+}
+
+function terminalStopReason(reason: string | undefined): string {
+  const trimmed = reason?.trim();
+  return trimmed === undefined || trimmed.length === 0 ? 'Task already in terminal state' : trimmed;
+}
diff --git a/packages/agent-core/src/tools/builtin/collaboration/agent-background-disabled.md b/packages/agent-core/src/tools/builtin/collaboration/agent-background-disabled.md
new file mode 100644
index 000000000..d44efcddc
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/collaboration/agent-background-disabled.md
@@ -0,0 +1 @@
+Background agent execution is disabled for this agent. Do not set `run_in_background=true`.
\ No newline at end of file
diff --git a/packages/agent-core/src/tools/builtin/collaboration/agent-background-enabled.md b/packages/agent-core/src/tools/builtin/collaboration/agent-background-enabled.md
new file mode 100644
index 000000000..0732a8cc3
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/collaboration/agent-background-enabled.md
@@ -0,0 +1,3 @@
+When `run_in_background=true`, the subagent runs detached from this turn. The completion arrives in a later turn as a synthetic user-role message containing its result — you do not need to poll, sleep, or check on its progress. Continue with other work or respond to the user. Never fabricate or predict what the result will say.
+
+For a background task, when `timeout` is omitted it falls back to the operator-configured background timeout, if one is set. If the operator has not configured a background timeout, an omitted `timeout` means the task runs with no time limit.
diff --git a/packages/agent-core/src/tools/builtin/collaboration/agent.md b/packages/agent-core/src/tools/builtin/collaboration/agent.md
new file mode 100644
index 000000000..0c6bae3bf
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/collaboration/agent.md
@@ -0,0 +1,15 @@
+Launch a subagent to handle a task. The subagent runs as a same-process loop instance with its own context and wire file.
+
+Writing the prompt:
+- The subagent starts with zero context — it has not seen this conversation. Brief it like a colleague who just walked into the room: state the goal, list what you already know, hand over the specifics.
+- Lookups (read this file, run that test): put the exact path or command in the prompt. The subagent should not have to search for things you already know.
+- Investigations (figure out X, find why Y): give the question, not prescribed steps — fixed steps become dead weight when the premise is wrong.
+- Do not delegate understanding. If the task hinges on a file path or line number, find it yourself first and write it into the prompt.
+
+Usage notes:
+- When the task continues earlier work a subagent already did, prefer resuming that agent (pass its `resume` id) over spawning a fresh instance — the resumed agent keeps its prior context.
+- A subagent's result is only visible to you, not to the user. When the user needs to see what a subagent produced, summarize the relevant parts yourself in your own reply.
+
+When NOT to use Agent: skip delegation for trivial work you can do directly — reading a file whose path you already know, searching a small known set of files, or any task that takes only a step or two. Delegation has a context-handoff cost; it pays off only when the task is substantial enough to outweigh it.
+
+Once a subagent is running, leave that scope to it: do not redo its searches or reads in parallel, and do not abandon it midway and finish the job manually. Both undo the context savings the delegation was meant to buy.
\ No newline at end of file
diff --git a/packages/agent-core/src/tools/builtin/collaboration/agent.ts b/packages/agent-core/src/tools/builtin/collaboration/agent.ts
new file mode 100644
index 000000000..062a1ff00
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/collaboration/agent.ts
@@ -0,0 +1,334 @@
+/**
+ * AgentTool — collaboration tool for spawning task subagents.
+ *
+ * Unlike the built-in tools (Read/Write/Edit/Bash/Grep/Glob), this is a
+ * "collaboration tool". It uses `SessionSubagentHost` (injected via the
+ * constructor rather than through the Runtime) to create in-process subagent
+ * loop instances.
+ *
+ * Two modes:
+ *   - **Foreground** (default): blocks the parent turn, `await handle.completion`
+ *   - **Background**: returns the agent id immediately; the result is delivered
+ *     via a notification.
+ *
+ * `ToolResult.content` is textual; the structured output exposed by
+ * `AgentToolOutputSchema` is only used for drift-guard and is not consumed at
+ * runtime.
+ */
+
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../../agent/tool';
+import type { Logger } from '../../../logging';
+import { ToolAccesses } from '../../../loop/tool-access';
+import type { ExecutableToolContext, ExecutableToolResult, ToolExecution } from '../../../loop/types';
+import type { ResolvedAgentProfile } from '../../../profile';
+import type { SessionSubagentHost, SubagentHandle } from '../../../session/subagent-host';
+import { createDeadlineAbortSignal, type DeadlineAbortSignal } from '../../../utils/abort';
+import type { BackgroundProcessManager } from '../../background/manager';
+import { toInputJsonSchema } from '../../support/input-schema';
+import AGENT_BACKGROUND_DISABLED_DESCRIPTION from './agent-background-disabled.md';
+import AGENT_BACKGROUND_DESCRIPTION from './agent-background-enabled.md';
+import AGENT_DESCRIPTION_BASE from './agent.md';
+
+// ── AgentTool input ──────────────────────────────────────────────────
+
+export const AgentToolInputSchema = z.preprocess(
+  (input) => {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+      return input;
+    }
+    const record = input as Record<string, unknown>;
+    const normalized = { ...record };
+    const hasResumeId =
+      typeof normalized['resume'] === 'string' && normalized['resume'].trim().length > 0;
+    const hasSubagentType =
+      typeof normalized['subagent_type'] === 'string' && normalized['subagent_type'].length > 0;
+    if (!hasSubagentType && !hasResumeId) {
+      normalized['subagent_type'] = 'coder';
+    } else if (!hasSubagentType) {
+      delete normalized['subagent_type'];
+    }
+    return normalized;
+  },
+  z.object({
+    prompt: z.string().describe('Full task prompt for the subagent'),
+    description: z.string().describe('Short task description (3-5 words) for UI display'),
+    subagent_type: z
+      .string()
+      .optional()
+      .describe(
+        'One of the available agent types (see "Available agent types" in this tool description). Defaults to "coder" when omitted.',
+      ),
+    resume: z
+      .string()
+      .optional()
+      .describe('Optional agent ID to resume instead of creating a new instance'),
+    run_in_background: z
+      .boolean()
+      .optional()
+      .describe(
+        'If true, return immediately without waiting for completion. Prefer false unless the task can run independently and there is a clear benefit to not waiting.',
+      ),
+    timeout: z
+      .number()
+      .int()
+      .min(30)
+      .max(3600)
+      .optional()
+      .describe(
+        'Timeout in seconds for the agent task (min 30s, max 3600s / 1hr). When omitted, a foreground task runs until completion with no timeout. The agent is stopped if it exceeds this limit.',
+      ),
+  }),
+);
+
+export type AgentToolInput = z.infer<typeof AgentToolInputSchema>;
+
+// ── AgentTool output ─────────────────────────────────────────────────
+
+export const AgentToolOutputSchema = z.object({
+  result: z.string().describe('Aggregated text output from the subagent'),
+  usage: z
+    .object({
+      input: z.number().int().nonnegative(),
+      output: z.number().int().nonnegative(),
+      cache_read: z.number().int().nonnegative().optional(),
+      cache_write: z.number().int().nonnegative().optional(),
+    })
+    .describe('Cumulative token usage'),
+});
+
+export type AgentToolOutput = z.infer<typeof AgentToolOutputSchema>;
+
+const BACKGROUND_AGENT_UNAVAILABLE =
+  'Background agent execution is not available for this agent because TaskList, TaskOutput, and TaskStop are not enabled.';
+
+// ── AgentTool class ──────────────────────────────────────────────────
+
+export class AgentTool implements BuiltinTool<AgentToolInput> {
+  readonly name: string = 'Agent';
+  readonly description: string;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(AgentToolInputSchema);
+  private readonly allowBackground: boolean;
+
+  constructor(
+    private readonly subagentHost: SessionSubagentHost,
+    private readonly backgroundManager?: BackgroundProcessManager | undefined,
+    subagents?: ResolvedAgentProfile['subagents'] | undefined,
+    options?: {
+      allowBackground?: boolean;
+      log?: Logger;
+    },
+  ) {
+    this.allowBackground = options?.allowBackground ?? this.backgroundManager !== undefined;
+    const log = options?.log;
+    const typeLines = buildSubagentDescriptions(subagents);
+    const baseDescription = `${AGENT_DESCRIPTION_BASE}\n\n${
+      this.allowBackground ? AGENT_BACKGROUND_DESCRIPTION : AGENT_BACKGROUND_DISABLED_DESCRIPTION
+    }`;
+    this.description = typeLines
+      ? `${baseDescription}\n\nAvailable agent types (pass via subagent_type):\n${typeLines}`
+      : baseDescription;
+    this.log = log;
+  }
+
+  private readonly log?: Logger;
+
+  resolveExecution(args: AgentToolInput): ToolExecution {
+    let profileName = args.subagent_type?.length ? args.subagent_type : 'coder';
+    const resumeAgentId = args.resume?.trim();
+    if (resumeAgentId !== undefined && resumeAgentId.length > 0) {
+      profileName = this.subagentHost.getProfileName?.(resumeAgentId) ?? 'subagent';
+    }
+    const prefix = args.run_in_background === true ? 'Launching background' : 'Launching';
+    return {
+      description: `${prefix} ${profileName} agent: ${args.description}`,
+      accesses: ToolAccesses.none(),
+      execute: (ctx) => this.execution(args, ctx),
+    };
+  }
+
+  private async execution(
+    args: AgentToolInput,
+    {
+    toolCallId,
+    signal,
+    }: ExecutableToolContext,
+  ): Promise<ExecutableToolResult> {
+    let foregroundDeadline: DeadlineAbortSignal | undefined;
+    try {
+      signal.throwIfAborted();
+      const runInBackground = args.run_in_background === true;
+      const requestedProfileName = args.subagent_type?.length ? args.subagent_type : undefined;
+      const resumeAgentId = args.resume?.trim();
+      if (
+        resumeAgentId !== undefined &&
+        resumeAgentId.length > 0 &&
+        requestedProfileName !== undefined
+      ) {
+        return {
+          output: 'Cannot set subagent_type when resuming an existing agent. Resume by agent id only.',
+          isError: true,
+        };
+      }
+
+      let reservation: ReturnType<BackgroundProcessManager['reserveSlot']> | undefined;
+      let backgroundManager: BackgroundProcessManager | undefined;
+      if (runInBackground) {
+        const configuredBackgroundManager = this.backgroundManager;
+        if (!this.allowBackground || configuredBackgroundManager === undefined) {
+          return {
+            output: BACKGROUND_AGENT_UNAVAILABLE,
+            isError: true,
+          };
+        }
+        try {
+          reservation = configuredBackgroundManager.reserveSlot();
+          backgroundManager = configuredBackgroundManager;
+        } catch (error) {
+          return {
+            output: error instanceof Error ? error.message : String(error),
+            isError: true,
+          };
+        }
+      }
+      const backgroundController = runInBackground ? new AbortController() : undefined;
+      const timeoutMs = args.timeout === undefined ? undefined : args.timeout * 1000;
+      foregroundDeadline =
+        !runInBackground && timeoutMs !== undefined
+          ? createDeadlineAbortSignal(signal, timeoutMs)
+          : undefined;
+
+      const options = {
+        parentToolCallId: toolCallId,
+        prompt: args.prompt,
+        description: args.description,
+        runInBackground,
+        signal: backgroundController?.signal ?? foregroundDeadline?.signal ?? signal,
+      };
+
+      let handle: SubagentHandle;
+      const operation = resumeAgentId !== undefined && resumeAgentId.length > 0 ? 'resume' : 'spawn';
+      try {
+        if (resumeAgentId !== undefined && resumeAgentId.length > 0) {
+          handle = await this.subagentHost.resume(resumeAgentId, options);
+        } else {
+          const profileName = requestedProfileName ?? 'coder';
+          handle = await this.subagentHost.spawn(profileName, options);
+        }
+      } catch (error) {
+        reservation?.release();
+        this.log?.warn('subagent launch failed', {
+          toolCallId,
+          runInBackground,
+          operation,
+          agentId: resumeAgentId,
+          subagentType: operation === 'spawn' ? requestedProfileName ?? 'coder' : undefined,
+          error,
+        });
+        throw error;
+      }
+
+      if (runInBackground) {
+        if (backgroundManager === undefined) {
+          reservation?.release();
+          return {
+            output: BACKGROUND_AGENT_UNAVAILABLE,
+            isError: true,
+          };
+        }
+        let taskId: string;
+        try {
+          taskId = backgroundManager.registerAgentTask(handle.completion, args.description, {
+            timeoutMs: timeoutMs ?? this.subagentHost.backgroundTaskTimeoutMs,
+            reservation,
+            agentId: handle.agentId,
+            subagentType: handle.profileName,
+            abort: () => {
+              backgroundController?.abort();
+            },
+          });
+        } catch (error) {
+          reservation?.release();
+          backgroundController?.abort();
+          void handle.completion.catch(() => {});
+          this.log?.warn('background agent task registration failed', {
+            toolCallId,
+            agentId: handle.agentId,
+            subagentType: handle.profileName,
+            error,
+          });
+          return {
+            output: error instanceof Error ? error.message : String(error),
+            isError: true,
+          };
+        }
+        const lines = [
+          `task_id: ${taskId}`,
+          'status: running',
+          `agent_id: ${handle.agentId}`,
+          `actual_subagent_type: ${handle.profileName}`,
+          'automatic_notification: true',
+          '',
+          `description: ${args.description}`,
+          '',
+          `next_step: The completion arrives automatically in a later turn — no polling needed. To peek at progress without blocking, call TaskOutput(task_id="${taskId}", block=false).`,
+          `resume_hint: To continue this same subagent instance later, call Agent(resume="${handle.agentId}", prompt="...").`,
+        ];
+        return { output: lines.join('\n') };
+      }
+
+      try {
+        const result = await handle.completion;
+        const lines = [
+          `agent_id: ${handle.agentId}`,
+          `actual_subagent_type: ${handle.profileName}`,
+          'status: completed',
+          '',
+          '[summary]',
+          result.result,
+        ];
+        return { output: lines.join('\n') };
+      } catch (error) {
+        const message =
+          foregroundDeadline?.timedOut() === true && args.timeout !== undefined
+            ? `Agent timed out after ${args.timeout}s.`
+            : error instanceof Error
+              ? error.message
+              : String(error);
+        const lines = [
+          `agent_id: ${handle.agentId}`,
+          `actual_subagent_type: ${handle.profileName}`,
+          'status: failed',
+          '',
+          `subagent error: ${message}`,
+        ];
+        return { output: lines.join('\n'), isError: true };
+      }
+    } catch (error) {
+      const message =
+        foregroundDeadline?.timedOut() === true && args.timeout !== undefined
+          ? `Agent timed out after ${args.timeout}s.`
+          : error instanceof Error
+            ? error.message
+            : String(error);
+      return { output: `subagent error: ${message}`, isError: true };
+    } finally {
+      foregroundDeadline?.clear();
+    }
+  }
+}
+
+function buildSubagentDescriptions(subagents: ResolvedAgentProfile['subagents']): string {
+  if (subagents === undefined) return '';
+  return Object.entries(subagents)
+    .map(([name, subagent]) => {
+      const details = [subagent.description, subagent.whenToUse].filter(
+        (part): part is string => part !== undefined && part.length > 0,
+      );
+      const header = details.length === 0 ? `- ${name}` : `- ${name}: ${details.join(' ')}`;
+      if (subagent.tools.length === 0) return header;
+      return `${header}\n  Tools: ${subagent.tools.join(', ')}`;
+    })
+    .join('\n');
+}
diff --git a/packages/agent-core/src/tools/builtin/collaboration/ask-user.md b/packages/agent-core/src/tools/builtin/collaboration/ask-user.md
new file mode 100644
index 000000000..597cd8eb9
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/collaboration/ask-user.md
@@ -0,0 +1,19 @@
+Use this tool when you need to ask the user questions with structured options during execution. This allows you to:
+1. Collect user preferences or requirements before proceeding
+2. Resolve ambiguous or underspecified instructions
+3. Let the user decide between implementation approaches as you work
+4. Present concrete options when multiple valid directions exist
+
+**When NOT to use:**
+- When you can infer the answer from context — be decisive and proceed
+- Trivial decisions that don't materially affect the outcome
+
+Overusing this tool interrupts the user's flow. Only use it when the user's input genuinely changes your next action.
+
+**Usage notes:**
+- Users always have an "Other" option for custom input — don't create one yourself
+- Use multi_select to allow multiple answers to be selected for a question
+- Keep option labels concise (1-5 words), use descriptions for trade-offs and details
+- Each question should have 2-4 meaningful, distinct options
+- You can ask 1-4 questions at a time; group related questions to minimize interruptions
+- If you recommend a specific option, list it first and append "(Recommended)" to its label
\ No newline at end of file
diff --git a/packages/agent-core/src/tools/builtin/collaboration/ask-user.ts b/packages/agent-core/src/tools/builtin/collaboration/ask-user.ts
new file mode 100644
index 000000000..a1dbf6179
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/collaboration/ask-user.ts
@@ -0,0 +1,187 @@
+/**
+ * AskUserQuestionTool — structured user question tool.
+ *
+ * The LLM calls this tool when it needs structured input from the user
+ * (multiple-choice, preference selection, disambiguation). The tool
+ * delegates to the SDK reverse-RPC question handler, which owns the
+ * actual UI interaction.
+ *
+ * Permission policy decides whether this tool is available for the
+ * current mode. Once executed, it dispatches through `requestQuestion`
+ * and awaits the user's answer.
+ */
+
+import { z } from 'zod';
+
+import type { Agent } from '../../../agent';
+import type { BuiltinTool } from '../../../agent/tool';
+import { ErrorCodes, KimiError } from '../../../errors';
+import { isAbortError } from '../../../loop/errors';
+import type { ExecutableToolContext, ExecutableToolResult, ToolExecution } from '../../../loop/types';
+import type {
+  QuestionAnswers,
+  QuestionAnswerMethod,
+  QuestionResponse,
+  QuestionResult,
+} from '../../../rpc';
+import type { TelemetryPropertyValue } from '../../../telemetry';
+import { toInputJsonSchema } from '../../support/input-schema';
+import DESCRIPTION from './ask-user.md';
+
+// ── Input schema ─────────────────────────────────────────────────────
+
+const QuestionOptionSchema = z.object({
+  label: z
+    .string()
+    .describe("Concise display text (1-5 words). If recommended, append '(Recommended)'."),
+  description: z.string().default('').describe('Brief explanation of trade-offs or implications.'),
+});
+
+const QuestionItemSchema = z.object({
+  question: z.string().describe("A specific, actionable question. End with '?'."),
+  header: z
+    .string()
+    .default('')
+    .describe("Short category tag (max 12 chars, e.g. 'Auth', 'Style')."),
+  options: z
+    .array(QuestionOptionSchema)
+    .min(2)
+    .max(4)
+    .describe(
+      "2-4 meaningful, distinct options. Do NOT include an 'Other' option — the system adds one automatically.",
+    ),
+  multi_select: z
+    .boolean()
+    .default(false)
+    .describe('Whether the user can select multiple options.'),
+});
+
+export interface AskUserQuestionInput {
+  questions: Array<{
+    question: string;
+    header: string;
+    options: Array<{ label: string; description: string }>;
+    multi_select: boolean;
+  }>;
+}
+
+export const AskUserQuestionInputSchema: z.ZodType<AskUserQuestionInput> = z.object({
+  questions: z
+    .array(QuestionItemSchema)
+    .min(1)
+    .max(4)
+    .describe('The questions to ask the user (1-4 questions).'),
+});
+
+const QUESTION_DISMISSED_MESSAGE = 'User dismissed the question without answering.';
+
+const QUESTION_UNSUPPORTED_FAILURE_MESSAGE =
+  'The connected client does not support interactive questions. Do NOT call this tool again. Ask the user directly in your text response instead.';
+
+// ── Implementation ───────────────────────────────────────────────────
+
+export class AskUserQuestionTool implements BuiltinTool<AskUserQuestionInput> {
+  readonly name = 'AskUserQuestion' as const;
+  readonly description: string = DESCRIPTION;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(AskUserQuestionInputSchema);
+
+  constructor(private readonly agent: Agent) {}
+
+  resolveExecution(args: AskUserQuestionInput): ToolExecution {
+    return {
+      description: 'Asking user questions',
+      execute: (ctx) => this.execution(args, ctx),
+    };
+  }
+
+  private async execution(
+    args: AskUserQuestionInput,
+    {
+      toolCallId,
+      signal,
+      turnId,
+    }: ExecutableToolContext,
+  ): Promise<ExecutableToolResult> {
+    try {
+      const result = await this.agent.rpc.requestQuestion(
+        {
+          turnId: numericTurnId(turnId),
+          toolCallId,
+          questions: args.questions.map((q) => ({
+            question: q.question,
+            header: q.header,
+            options: q.options.map((o) => ({
+              label: o.label,
+              description: o.description,
+            })),
+            multiSelect: q.multi_select,
+          })),
+        },
+        { signal },
+      );
+
+      const normalized = normalizeQuestionResult(result);
+      if (normalized === null || Object.keys(normalized.answers).length === 0) {
+        this.agent.telemetry.track('question_dismissed');
+        return dismissedQuestionResult();
+      }
+
+      const properties: Record<string, TelemetryPropertyValue> = {
+        answered: Object.keys(normalized.answers).length,
+      };
+      if (normalized.method !== undefined) properties['method'] = normalized.method;
+      this.agent.telemetry.track('question_answered', properties);
+      return {
+        isError: false,
+        output: JSON.stringify({ answers: normalized.answers }),
+      };
+    } catch (error) {
+      if (isAbortError(error) || signal.aborted) throw error;
+
+      if (error instanceof KimiError && error.code === ErrorCodes.NOT_IMPLEMENTED) {
+        return {
+          isError: true,
+          output: QUESTION_UNSUPPORTED_FAILURE_MESSAGE,
+        };
+      }
+
+      return dismissedQuestionResult();
+    }
+  }
+}
+
+function dismissedQuestionResult(): ExecutableToolResult {
+  return {
+    isError: false,
+    output: JSON.stringify({
+      answers: {},
+      note: QUESTION_DISMISSED_MESSAGE,
+    }),
+  };
+}
+
+function numericTurnId(turnId: string): number | undefined {
+  if (turnId.trim().length === 0) return undefined;
+  const parsed = Number(turnId);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function normalizeQuestionResult(
+  result: QuestionResult,
+): { readonly answers: QuestionAnswers; readonly method?: QuestionAnswerMethod | undefined } | null {
+  if (result === null) return null;
+  if (isQuestionResponse(result)) {
+    return {
+      answers: result.answers,
+      method: result.method,
+    };
+  }
+  return { answers: result };
+}
+
+function isQuestionResponse(result: Exclude<QuestionResult, null>): result is QuestionResponse {
+  if (typeof result !== 'object' || result === null) return false;
+  if (!Object.hasOwn(result, 'answers')) return false;
+  const answers = (result as { readonly answers?: unknown }).answers;
+  return typeof answers === 'object' && answers !== null && !Array.isArray(answers);
+}
diff --git a/packages/agent-core/src/tools/builtin/collaboration/skill-tool.md b/packages/agent-core/src/tools/builtin/collaboration/skill-tool.md
new file mode 100644
index 000000000..bc67f43f5
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/collaboration/skill-tool.md
@@ -0,0 +1 @@
+Invoke a registered skill from the current skill listing. BLOCKING REQUIREMENT: when a skill from the listing matches the user's request, you MUST call this tool (not free-form text). Do NOT call the same skill repeatedly inside one turn — recursive depth is capped at {{ MAX_SKILL_QUERY_DEPTH }}.
\ No newline at end of file
diff --git a/packages/agent-core/src/tools/builtin/collaboration/skill-tool.ts b/packages/agent-core/src/tools/builtin/collaboration/skill-tool.ts
new file mode 100644
index 000000000..1e8ec8d96
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/collaboration/skill-tool.ts
@@ -0,0 +1,168 @@
+/**
+ * SkillTool — invoke a registered skill.
+ *
+ * Collaboration tool that lets the LLM proactively invoke an inline
+ * registered skill. Inline skills record their activation through the
+ * owning agent; non-inline skill types are intentionally not model-invocable
+ * in the v1 default runtime.
+ *
+ * Anti-loop: `MAX_SKILL_QUERY_DEPTH` caps Skill→Skill recursion so a
+ * skill that re-invokes itself (or chains into another) cannot recurse
+ * without bound.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import { z } from 'zod';
+
+import type { Agent } from '../../../agent';
+import type { SkillActivationOrigin } from '../../../agent/context';
+import type { BuiltinTool } from '../../../agent/tool';
+import type { ExecutableToolResult, ToolExecution } from '../../../loop/types';
+import { isInlineSkillType, type SkillDefinition } from '../../../skill';
+import { renderPrompt } from '../../../utils/render-prompt';
+import { toInputJsonSchema } from '../../support/input-schema';
+import skillDescriptionTemplate from './skill-tool.md';
+
+export const MAX_SKILL_QUERY_DEPTH = 3;
+
+export class NestedSkillTooDeepError extends Error {
+  readonly skillName?: string;
+  readonly depth: number;
+
+  constructor(depth: number, skillName?: string) {
+    const label = skillName !== undefined ? ` "${skillName}"` : '';
+    super(
+      `Nested skill invocation${label} exceeded the maximum depth of ${String(depth)} — refusing to recurse further.`,
+    );
+    this.name = 'NestedSkillTooDeepError';
+    this.depth = depth;
+    if (skillName !== undefined) this.skillName = skillName;
+  }
+}
+
+export interface SkillToolInput {
+  skill: string;
+  args?: string;
+}
+
+export const SkillToolInputSchema: z.ZodType<SkillToolInput> = z.object({
+  skill: z.string(),
+  args: z.string().optional(),
+});
+
+export interface SkillToolOptions {
+  /**
+   * Current inline skill recursion depth.
+   */
+  readonly queryDepth?: number;
+  /**
+   * Alias for `queryDepth`. Kept so older call sites can seed the
+   * inline recursion depth without knowing the internal field name.
+   */
+  readonly initialQueryDepth?: number;
+}
+
+export class SkillTool implements BuiltinTool<SkillToolInput> {
+  readonly name = 'Skill';
+  readonly description: string = renderPrompt(skillDescriptionTemplate, {
+    MAX_SKILL_QUERY_DEPTH,
+  });
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(SkillToolInputSchema);
+
+  constructor(
+    private readonly agent: Agent,
+    private readonly options: SkillToolOptions = {},
+  ) {}
+
+  resolveExecution(args: SkillToolInput): ToolExecution {
+    return {
+      description: `Invoke skill ${args.skill}`,
+      execute: () => this.execution(args),
+    };
+  }
+
+  withInitialQueryDepth(initialQueryDepth: number): SkillTool {
+    return new SkillTool(this.agent, {
+      ...this.options,
+      initialQueryDepth,
+    });
+  }
+
+  private async execution(args: SkillToolInput): Promise<ExecutableToolResult> {
+    // Recursion hard cap. Once `currentDepth` has reached
+    // MAX_SKILL_QUERY_DEPTH, firing another Skill call would push the
+    // child to depth+1 which violates the invariant. Throw a structured
+    // error (rather than a soft tool-error) so Runtime can distinguish
+    // "LLM mis-dispatched" from "safety net fired".
+    const currentDepth = this.options.initialQueryDepth ?? this.options.queryDepth ?? 0;
+    if (currentDepth >= MAX_SKILL_QUERY_DEPTH) {
+      throw new NestedSkillTooDeepError(MAX_SKILL_QUERY_DEPTH, args.skill);
+    }
+
+    const skills = this.agent.skills;
+    if (skills === undefined) {
+      return errorResult(`Skill "${args.skill}" not found in the current skill listing.`);
+    }
+    const skill = skills.registry.getSkill(args.skill);
+    if (skill === undefined) {
+      return errorResult(`Skill "${args.skill}" not found in the current skill listing.`);
+    }
+    if (skill.metadata.disableModelInvocation === true) {
+      // Keep the exact wording "can only be triggered by the user" so
+      // contract audits and integration tests stay deterministic.
+      return errorResult(
+        `Skill "${args.skill}" can only be triggered by the user (model invocation is disabled).`,
+      );
+    }
+
+    const skillArgs = args.args ?? '';
+    if (!isInlineSkillType(skill.metadata.type)) {
+      return errorResult(
+        `Skill "${skill.name}" is not an inline skill and cannot be invoked by the model in v1.`,
+      );
+    }
+
+    const origin = skillOrigin(skill, skillArgs, currentDepth);
+    skills.recordActivation(origin);
+    const skillContent = skills.registry.renderSkillPrompt(skill, skillArgs);
+    this.agent.context.appendSystemReminder(
+      `<kimi-skill-loaded name="${escapeXml(skill.name)}" args="${escapeXml(skillArgs)}">\n` +
+        `${skillContent}\n` +
+        `</kimi-skill-loaded>`,
+      origin,
+    );
+    return {
+      output: `Skill "${skill.name}" loaded inline. Follow its instructions.`,
+    };
+  }
+}
+
+function errorResult(message: string): ExecutableToolResult {
+  return { isError: true, output: message };
+}
+
+function skillOrigin(
+  skill: SkillDefinition,
+  skillArgs: string,
+  currentDepth: number,
+): SkillActivationOrigin {
+  return {
+    kind: 'skill_activation',
+    activationId: randomUUID(),
+    skillName: skill.name,
+    skillArgs: skillArgs.length > 0 ? skillArgs : undefined,
+    trigger: currentDepth > 0 ? 'nested-skill' : 'model-tool',
+    skillType: skill.metadata.type,
+    skillPath: skill.path,
+    skillSource: skill.source,
+  };
+}
+
+function escapeXml(input: string): string {
+  return input
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}
diff --git a/packages/agent-core/src/tools/builtin/file/edit.md b/packages/agent-core/src/tools/builtin/file/edit.md
new file mode 100644
index 000000000..f5de2c551
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/file/edit.md
@@ -0,0 +1,10 @@
+Perform exact string replacements against the text view returned by Read.
+
+- When copying from Read output, omit the line-number prefix and tab; match only the file content.
+- By default, old_string must occur exactly once. If it matches multiple locations, add surrounding context or set replace_all when every occurrence should change.
+- Prefer Edit for targeted changes to existing files; use Write only for new files or complete overwrites.
+- To modify a file, always use Edit; do not run a Shell `sed` command for edits.
+- When making several independent changes, issue multiple Edit calls in parallel within a single response; edits to the same file are serialized automatically by a write lock.
+- When several parallel Edit calls target the same file, a write lock serializes them; they apply in the order the calls appear in your response. An edit fails with `old_string not found` if its old_string was taken from text an earlier edit already replaced — base every old_string on the latest Read view and order dependent edits accordingly.
+- For pure CRLF files, Read shows LF and Edit.old_string/new_string should use LF; Edit writes the file back with CRLF preserved.
+- For mixed line endings or lone carriage returns, Read displays carriage returns as \r; include actual \r escapes in old_string/new_string for those positions.
\ No newline at end of file
diff --git a/packages/agent-core/src/tools/builtin/file/edit.ts b/packages/agent-core/src/tools/builtin/file/edit.ts
new file mode 100644
index 000000000..de14c3456
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/file/edit.ts
@@ -0,0 +1,149 @@
+/**
+ * EditTool — exact string replacement in a file.
+ *
+ * Replaces the first occurrence of `old_string` with `new_string` by
+ * default. When `replace_all` is true, replaces all occurrences.
+ * Errors when `old_string` is not found or not unique (when
+ * `replace_all=false`). Path access policy is resolved before any
+ * Kaos I/O.
+ */
+
+import type { Kaos } from '@moonshot-ai/kaos';
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../../agent/tool';
+import { ToolAccesses } from '../../../loop/tool-access';
+import type { ExecutableToolResult, ToolExecution } from '../../../loop/types';
+import { resolvePathAccessPath } from '../../policies/path-access';
+import { toInputJsonSchema } from '../../support/input-schema';
+import type { WorkspaceConfig } from '../../support/workspace';
+import { materializeModelText, toModelTextView } from './line-endings';
+import EDIT_DESCRIPTION from './edit.md';
+
+// `old_string` must be non-empty: the non-replace_all branch walks
+// occurrences with `content.indexOf("", pos)`, which would loop forever
+// on an empty search string.
+export const EditInputSchema = z.object({
+  path: z
+    .string()
+    .describe(
+      'Path to the text file to edit. Relative paths resolve against the working directory; a path outside the working directory must be absolute.',
+    ),
+  old_string: z
+    .string()
+    .min(1)
+    .describe(
+      'Exact content to replace from the Read output view, without the line-number prefix. Use LF for pure CRLF files; use actual \\r escapes where Read shows \\r.',
+    ),
+  new_string: z
+    .string()
+    .describe(
+      'Replacement text in the same Read output view. LF is written back as CRLF only for pure CRLF files.',
+    ),
+  replace_all: z
+    .boolean()
+    .optional()
+    .describe('Set true only when every occurrence of old_string should be replaced.'),
+});
+
+export type EditInput = z.Infer<typeof EditInputSchema>;
+
+function replaceOnceLiteral(content: string, oldString: string, newString: string): string {
+  const index = content.indexOf(oldString);
+  if (index === -1) return content;
+  return content.slice(0, index) + newString + content.slice(index + oldString.length);
+}
+
+export class EditTool implements BuiltinTool<EditInput> {
+  readonly name = 'Edit' as const;
+  readonly description = EDIT_DESCRIPTION;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(EditInputSchema);
+
+  constructor(
+    private readonly kaos: Kaos,
+    private readonly workspace: WorkspaceConfig,
+  ) {}
+
+  resolveExecution(args: EditInput): ToolExecution {
+    const path = resolvePathAccessPath(args.path, {
+      kaos: this.kaos,
+      workspace: this.workspace,
+      operation: 'write',
+    });
+    return {
+      accesses: ToolAccesses.readWriteFile(path),
+      description: `Editing ${args.path}`,
+      execute: () => this.execution(args, path),
+    };
+  }
+
+  private async execution(args: EditInput, safePath: string): Promise<ExecutableToolResult> {
+    if (args.old_string === args.new_string) {
+      return {
+        isError: true,
+        output: 'No changes to make: old_string and new_string are exactly the same.',
+      };
+    }
+
+    try {
+      const raw = await this.kaos.readText(safePath);
+      const modelView = toModelTextView(raw);
+      const content = modelView.text;
+      const replaceAll = args.replace_all ?? false;
+
+      if (!replaceAll) {
+        let count = 0;
+        let pos = 0;
+        while (pos < content.length) {
+          const idx = content.indexOf(args.old_string, pos);
+          if (idx === -1) break;
+          count++;
+          pos = idx + args.old_string.length;
+        }
+
+        if (count === 0) {
+          return { isError: true, output: `old_string not found in ${args.path}, The file contents may be out of date. Please use the Read Tool to reload the content.
+` };
+        }
+        if (count > 1) {
+          return {
+            isError: true,
+            output:
+              `old_string is not unique in ${args.path} (found ${String(count)} occurrences). ` +
+              'To replace every occurrence, set replace_all=true. To replace only one occurrence, include more surrounding context in old_string.',
+          };
+        }
+
+        const newContent = replaceOnceLiteral(content, args.old_string, args.new_string);
+        await this.kaos.writeText(
+          safePath,
+          materializeModelText(newContent, modelView.lineEndingStyle),
+        );
+        return { output: `Replaced 1 occurrence in ${args.path}` };
+      }
+
+      const parts = content.split(args.old_string);
+      const replacementCount = parts.length - 1;
+      if (replacementCount === 0) {
+        return { isError: true, output: `old_string not found in ${args.path}, The file contents may be out of date. Please use the Read Tool to reload the content.
+` };
+      }
+
+      const newContent = parts.join(args.new_string);
+      await this.kaos.writeText(
+        safePath,
+        materializeModelText(newContent, modelView.lineEndingStyle),
+      );
+      return { output: `Replaced ${String(replacementCount)} occurrences in ${args.path}` };
+    } catch (error) {
+      const code = (error as { code?: unknown } | null)?.code;
+      if (code === 'EISDIR') {
+        return { isError: true, output: `${args.path} is not a file.` };
+      }
+      return {
+        isError: true,
+        output: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+}
diff --git a/packages/agent-core/src/tools/builtin/file/glob.md b/packages/agent-core/src/tools/builtin/file/glob.md
new file mode 100644
index 000000000..f26cc8a05
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/file/glob.md
@@ -0,0 +1,16 @@
+Find files (and optionally directories) by glob pattern, sorted by modification time (most recent first).
+
+Good patterns:
+- `*.ts` — files in the current directory matching an extension
+- `src/**/*.ts` — recursive with a subdirectory anchor and extension
+- `test_*.py` — files whose name starts with a literal prefix
+
+Rejected patterns (no literal anchor — nothing bounds the result set):
+- `**`, `**/*`, `*/*` — pure wildcards. Add an extension or subdirectory to give the walk a concrete target.
+- Anything that starts with `**/` (e.g. `**/*.md`, `**/main/*.py`). The leading `**/` has no literal anchor in front of it. Anchor it with a top-level subdirectory like `src/**/*.md`.
+- `*.{ts,tsx}` — brace expansion is not supported. Issue two calls: `*.ts` and `*.tsx`.
+
+Large-directory warning — avoid recursing into dependency/build output even with an anchor:
+- `node_modules/**/*.js`, `.venv/**/*.py`, `__pycache__/**`, `target/**` all match technically but
+  typically produce thousands of results that truncate at the match cap and waste the caller context.
+  Prefer specific subpaths like `node_modules/react/src/**/*.js`.
\ No newline at end of file
diff --git a/packages/agent-core/src/tools/builtin/file/glob.ts b/packages/agent-core/src/tools/builtin/file/glob.ts
new file mode 100644
index 000000000..d58e37c5c
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/file/glob.ts
@@ -0,0 +1,376 @@
+/**
+ * GlobTool — file pattern matching.
+ *
+ * Finds files matching a glob pattern, returned sorted by modification
+ * time (most recent first). Uses `kaos.glob`.
+ *
+ * Output convention: `content` shown to the LLM is relativized to the
+ * search base to save tokens; `output.paths` keeps absolute paths so
+ * downstream Read/Edit can consume them directly.
+ *
+ * Safety rails:
+ *   - Pure-wildcard patterns (nothing but `*` / `?` / `/`) are rejected
+ *     because they have no literal anchor — they would enumerate every
+ *     file under the search root and exhaust the caller's context on
+ *     large trees. Examples: `**`, `** / *`, `** / **`, `* / *`.
+ *     Constrained patterns (with any literal anchor such as an extension
+ *     or subdirectory) are allowed — the literal bounds the result set.
+ *   - Patterns using brace expansion (`{a,b,c}`) are rejected up-front
+ *     because the underlying `_globWalk` treats `{` / `}` as literals,
+ *     so such patterns would silently match zero files.
+ *   - `path` is validated by `resolvePathAccess` in strict mode. Explicit
+ *     paths must be absolute and within the workspace roots.
+ *   - match count is capped at `MAX_MATCHES`; a separate `YIELD_SAFETY_CAP`
+ *     (MAX_MATCHES × 2) on the raw yield stream is a secondary belt that
+ *     still terminates the stream if the kaos layer's own symlink-cycle
+ *     detection were ever absent or bypassed. Primary cycle defense lives
+ *     in `packages/kaos/src/local.ts:_globWalk` via a path-local visited
+ *     inode set.
+ */
+
+import type { Kaos } from '@moonshot-ai/kaos';
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../../agent/tool';
+import { ToolAccesses } from '../../../loop/tool-access';
+import type { ExecutableToolResult, ToolExecution } from '../../../loop/types';
+import { resolvePathAccessPath } from '../../policies/path-access';
+import type { PathClass } from '../../policies/path-access';
+import { toInputJsonSchema } from '../../support/input-schema';
+import { listDirectory } from '../../support/list-directory';
+import type { WorkspaceConfig } from '../../support/workspace';
+import GLOB_DESCRIPTION from './glob.md';
+
+export const GlobInputSchema = z.object({
+  pattern: z.string().describe('Glob pattern to match files/directories.'),
+  path: z
+    .string()
+    .optional()
+    .describe(
+      'Absolute path to the directory to search in. Defaults to the current working directory.',
+    ),
+  include_dirs: z
+    .boolean()
+    .default(true)
+    .optional()
+    .describe(
+      'Whether to include directories in results. Defaults to true. Set false to return only files.',
+    ),
+});
+
+export type GlobInput = z.Infer<typeof GlobInputSchema>;
+
+export const MAX_MATCHES = 1000;
+
+/**
+ * Path-shape hint appended to the tool description only on a Windows
+ * (`win32` path class) backend. The `path` argument accepts both native
+ * Windows paths and POSIX-style paths, but matched paths come back in
+ * Windows backslash form — a command run through Bash must convert them
+ * to forward slashes first. Injected conditionally so non-Windows
+ * sessions are not shown a hint that does not apply to them.
+ */
+export const WINDOWS_PATH_HINT =
+  '\n\nWindows note: the `path` argument accepts both Windows paths ' +
+  '(e.g. `C:\\Users\\foo`) and POSIX-style paths (e.g. `/c/Users/foo`). Matched paths are ' +
+  'returned in Windows backslash form; convert them to forward slashes before ' +
+  'using them in a Bash command.';
+
+// POSIX mode bits — same constants used by KaosPath.isDir (packages/kaos/src/path.ts:199).
+const S_IFMT = 0o170000;
+const S_IFDIR = 0o040000;
+
+/**
+ * Tool-level description shown to the LLM at tool declaration time.
+ * Tells the model — before any round-trip — which patterns are
+ * accepted, which are rejected, and which directories are too large to
+ * recurse into. Patterns with a literal anchor before a double-star are
+ * allowed; pure-wildcard patterns (a bare double-star or a double-star
+ * followed by `/<wildcard>`) are rejected outright. On a Windows backend
+ * the description also carries `WINDOWS_PATH_HINT` (path-shape guidance).
+ */
+export class GlobTool implements BuiltinTool<GlobInput> {
+  readonly name = 'Glob' as const;
+  readonly description: string;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(GlobInputSchema);
+  constructor(
+    private readonly kaos: Kaos,
+    private readonly workspace: WorkspaceConfig,
+  ) {
+    this.description =
+      this.kaos.pathClass() === 'win32'
+        ? GLOB_DESCRIPTION + WINDOWS_PATH_HINT
+        : GLOB_DESCRIPTION;
+  }
+
+  resolveExecution(args: GlobInput): ToolExecution {
+    let path: string | undefined;
+    if (args.path !== undefined) {
+      path = resolvePathAccessPath(args.path, {
+        kaos: this.kaos,
+        workspace: this.workspace,
+        operation: 'search',
+        policy: { guardMode: 'strict', checkSensitive: false },
+      });
+    }
+    const searchRoots = [path ?? this.workspace.workspaceDir];
+    return {
+      accesses: ToolAccesses.searchTree(searchRoots[0]!),
+      description: `Searching ${args.pattern}`,
+      execute: () => this.execution(args, searchRoots),
+    };
+  }
+
+  private async execution(args: GlobInput, searchRoots: string[]): Promise<ExecutableToolResult> {
+    if (startsWithDoubleStarPrefix(args.pattern)) {
+      let tree: string;
+      try {
+        tree = await listDirectory(this.kaos, this.workspace.workspaceDir);
+      } catch {
+        tree = '(listing unavailable)';
+      }
+      return {
+        isError: true,
+        output:
+          `Pattern "${args.pattern}" starts with '**' which is not allowed — ` +
+          `the leading '**/' has no literal anchor in front of it and would ` +
+          `enumerate every file under the search root, typically exhausting ` +
+          `the caller's context on large trees. Use more specific patterns ` +
+          `instead, such as "src/**/*.py" or "test/**/*.py".\n\n` +
+          `Top of ${this.workspace.workspaceDir}:\n${tree}`,
+      };
+    }
+
+    if (isPureWildcard(args.pattern)) {
+      const allowedRoots = [this.workspace.workspaceDir, ...this.workspace.additionalDirs];
+      const rootList = allowedRoots.map((d) => `  - ${d}`).join('\n');
+      let tree: string;
+      try {
+        tree = await listDirectory(this.kaos, this.workspace.workspaceDir);
+      } catch {
+        tree = '(listing unavailable)';
+      }
+      return {
+        isError: true,
+        output:
+          `Pattern "${args.pattern}" is a pure wildcard (only \`*\`, \`?\`, \`**\`, \`/\`) ` +
+          `and would enumerate every file under the search root — with no literal ` +
+          `anchor to bound the result set, this typically exhausts your context on ` +
+          `large trees. Add an extension ` +
+          `("${args.pattern === '**' || args.pattern === '**/*' ? '**/*.ts' : '**/*.md'}") ` +
+          `or a subdirectory ("src/**/*.ts") to constrain the walk.\n\n` +
+          `Allowed roots for explicit path searches:\n${rootList}\n\n` +
+          `Top of ${this.workspace.workspaceDir}:\n${tree}`,
+      };
+    }
+
+    if (containsBraceExpansion(args.pattern)) {
+      return {
+        isError: true,
+        output:
+          `Pattern "${args.pattern}" uses brace expansion (\`{a,b,...}\`), which ` +
+          `is not supported by this Glob tool. Split it into separate calls, ` +
+          `one pattern per alternative. For example, instead of "*.{ts,tsx}" ` +
+          `issue two calls: "*.ts" and "*.tsx".`,
+      };
+    }
+
+    // Default true. When false, directories yielded by kaos are
+    // filtered out using the same stat that fuels the mtime sort
+    // (no second stat per path).
+    const includeDirs = args.include_dirs ?? true;
+
+    // kaos.glob silently returns empty for missing or non-directory roots
+    // (its _globWalk catches the readdir failure and exits without yielding).
+    // Without this pre-check, a Glob against a missing path would report
+    // "No matches found" instead of "does not exist", and the model would
+    // not realize the search root itself was wrong. iterdir is the right
+    // signal: pulling one entry triggers the same readdir that kaos.glob
+    // would do, so ENOENT/ENOTDIR surface here for the realistic backends
+    // before the walker is invoked. Any other failure (e.g. an unmocked
+    // test backend that throws "not implemented") falls through silently
+    // so the existing kaos.glob path still runs.
+    for (const root of searchRoots) {
+      try {
+        const iter = this.kaos.iterdir(root);
+        await iter.next();
+        if (typeof iter.return === 'function') {
+          await iter.return(undefined);
+        }
+      } catch (error) {
+        if (error !== null && typeof error === 'object' && 'code' in error) {
+          const code = (error as { code?: string }).code;
+          if (code === 'ENOENT') {
+            return { isError: true, output: `${root} does not exist` };
+          }
+          if (code === 'ENOTDIR') {
+            return { isError: true, output: `${root} is not a directory` };
+          }
+        }
+        // Unknown failure (including unmocked test backends): fall
+        // through and let kaos.glob run; it will either yield results
+        // or its own catch path will surface the error.
+      }
+    }
+
+    try {
+      // Two counters, two jobs:
+      //   - `entries.length` caps the *unique* paths we return, so a
+      //     truncation warning only fires after MAX_MATCHES real hits.
+      //   - `yielded` counts every path the kaos stream emits, including
+      //     duplicates. Secondary safety belt: the kaos `_globWalk`
+      //     itself detects symlink cycles, so a well-formed kaos layer
+      //     never re-yields the same real
+      //     file. `yielded` still terminates the stream if that primary
+      //     defense were ever absent or bypassed (e.g. a future kaos
+      //     backend without inode tracking), so the tool layer doesn't
+      //     depend on the kaos implementation for cycle safety.
+      const seen = new Set<string>();
+      const entries: Array<{ path: string; mtime: number }> = [];
+      const YIELD_SAFETY_CAP = MAX_MATCHES * 2;
+      let yielded = 0;
+      let truncated = false;
+
+      outer: for (const root of searchRoots) {
+        for await (const filePath of this.kaos.glob(root, args.pattern)) {
+          yielded++;
+          if (yielded >= YIELD_SAFETY_CAP) {
+            truncated = true;
+            break outer;
+          }
+          if (seen.has(filePath)) continue;
+          if (entries.length >= MAX_MATCHES) {
+            truncated = true;
+            break outer;
+          }
+          seen.add(filePath);
+          let mtime = 0;
+          let isDir = false;
+          try {
+            const st = await this.kaos.stat(filePath);
+            mtime = st.stMtime ?? 0;
+            isDir = (st.stMode & S_IFMT) === S_IFDIR;
+          } catch {
+            // stat failure — use 0 mtime / assume file so it still surfaces
+          }
+          // Apply include_dirs *after* marking seen so a filtered dir
+          // doesn't re-enter via a later duplicate yield, and *before*
+          // pushing to entries so MAX_MATCHES continues to cap output
+          // (not pre-filter) size.
+          if (!includeDirs && isDir) continue;
+          entries.push({ path: filePath, mtime });
+        }
+      }
+
+      entries.sort((a, b) => b.mtime - a.mtime);
+
+      const paths = entries.map((e) => e.path);
+      // Content shown to the LLM uses paths relative to the search base
+      // to save tokens; `output.paths` keeps the absolute form so callers
+      // can feed them into Read/Edit without further resolution.
+      const pathClass = this.kaos.pathClass();
+      const relBase = searchRoots[0] ?? this.workspace.workspaceDir;
+      const displayLines = paths.map((p) => relativizeIfUnder(p, relBase, pathClass));
+
+      if (entries.length === 0 && !truncated) {
+        return { output: 'No matches found' };
+      }
+      const lines: string[] = [];
+      if (truncated) {
+        lines.push(`[Truncated at ${String(MAX_MATCHES)} matches — use a more specific pattern]`);
+        lines.push(`Only the first ${String(MAX_MATCHES)} matches are returned.`);
+      }
+      lines.push(...displayLines);
+      if (!truncated && entries.length === MAX_MATCHES) {
+        lines.push(`Found ${String(entries.length)} matches`);
+      }
+      return { output: lines.join('\n') };
+    } catch (error) {
+      if (error !== null && typeof error === 'object' && 'code' in error) {
+        const code = (error as { code?: string }).code;
+        const path = searchRoots[0] ?? this.workspace.workspaceDir;
+        if (code === 'ENOENT') {
+          return { isError: true, output: `${path} does not exist` };
+        }
+        if (code === 'ENOTDIR') {
+          return { isError: true, output: `${path} is not a directory` };
+        }
+      }
+      return { isError: true, output: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
+}
+
+/**
+ * If `candidate` is under `base`, return the portion after `base/`.
+ * Otherwise return `candidate` unchanged (absolute). Both arguments
+ * should be canonical absolute paths.
+ */
+function relativizeIfUnder(candidate: string, base: string, pathClass: PathClass): string {
+  const sep = pathClass === 'win32' ? '\\' : '/';
+  const comparableCandidate = pathClass === 'win32' ? candidate.toLowerCase() : candidate;
+  const comparableBase = pathClass === 'win32' ? base.toLowerCase() : base;
+  if (comparableCandidate === comparableBase) return '.';
+  const prefix = comparableBase.endsWith(sep) ? comparableBase : comparableBase + sep;
+  if (comparableCandidate.startsWith(prefix)) {
+    return candidate.slice(prefix.length);
+  }
+  return candidate;
+}
+
+// Return true iff `pattern` begins with the literal sequence `**` followed
+// by a `/`. Such patterns have no literal anchor in front of the recursive
+// wildcard, so the walk has nothing to bound it on the left and would
+// descend into every top-level directory of the search root before any
+// suffix constraint can filter. Rejected up-front to match the Python Glob
+// behavior — callers must anchor with a top-level subdirectory.
+function startsWithDoubleStarPrefix(pattern: string): boolean {
+  return pattern.startsWith('**/');
+}
+
+/**
+ * Return true if `pattern` is pure wildcards — only `*`, `?`, `**`, `/`.
+ * Such patterns have no literal anchor and would enumerate every file
+ * under the search root. Backslash-escaped characters (`\X`) count as
+ * literals so `\*` or `\?` still means "pattern has an anchor".
+ */
+function isPureWildcard(pattern: string): boolean {
+  if (pattern === '') return false;
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === '\\' && i + 1 < pattern.length) {
+      // escaped literal — pattern has an anchor
+      return false;
+    }
+    if (ch !== '*' && ch !== '?' && ch !== '/') {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Return true iff `pattern` looks like it uses `{a,b,c}` brace expansion. */
+function containsBraceExpansion(pattern: string): boolean {
+  let inBrace = false;
+  let sawCommaInsideBrace = false;
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === '\\' && i + 1 < pattern.length) {
+      i++;
+      continue;
+    }
+    if (ch === '{') {
+      inBrace = true;
+      sawCommaInsideBrace = false;
+      continue;
+    }
+    if (ch === '}') {
+      if (inBrace && sawCommaInsideBrace) return true;
+      inBrace = false;
+      continue;
+    }
+    if (ch === ',' && inBrace) sawCommaInsideBrace = true;
+  }
+  return false;
+}
diff --git a/packages/agent-core/src/tools/builtin/file/grep.md b/packages/agent-core/src/tools/builtin/file/grep.md
new file mode 100644
index 000000000..c0d2776b3
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/file/grep.md
@@ -0,0 +1,9 @@
+Search file contents using regular expressions (powered by ripgrep).
+
+Use Grep when the task is to find unknown content or unknown file locations. Do not use shell `grep` or `rg` directly; this tool applies workspace path policy, output limits, and sensitive-file filtering.
+ALWAYS use Grep tool instead of running `grep` or `rg` from a shell — direct shell calls bypass workspace policy, output limits, and sensitive-file filtering.
+If you already know a concrete file path and need to inspect its contents, use Read directly instead.
+
+Write patterns in ripgrep regex syntax, which differs from POSIX `grep` syntax. For example, braces are special, so escape them as `\{` to match a literal `{`.
+
+Hidden files (dotfiles such as `.gitlab-ci.yml` or `.eslintrc.json`) are searched by default. To also search files excluded by `.gitignore` (such as `node_modules` or build outputs), set `include_ignored` to `true`. Sensitive files (such as `.env`) are always skipped for safety, even when `include_ignored` is `true`.
diff --git a/packages/agent-core/src/tools/builtin/file/grep.ts b/packages/agent-core/src/tools/builtin/file/grep.ts
new file mode 100644
index 000000000..00dbcf25f
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/file/grep.ts
@@ -0,0 +1,955 @@
+/**
+ * GrepTool — content search via ripgrep.
+ *
+ * Shells out to `rg` through Kaos. Supports glob/type filtering, context
+ * lines, output modes, pagination, multiline, and case-insensitive search.
+ *
+ * Path safety is enforced before any Kaos I/O. Explicit absolute paths outside
+ * the workspace are allowed; relative paths that escape the workspace are
+ * rejected.
+ *
+ * Output is bounded and post-processed before it reaches the model:
+ *   - timeout and ambient abort both terminate the rg subprocess;
+ *   - stdout/stderr are capped while streams continue draining;
+ *   - hidden files are searched, but VCS metadata and common sensitive glob
+ *     patterns are prefiltered where possible;
+ *   - parsed path records are filtered again after rg returns, using the active
+ *     backend path class.
+ */
+
+import type { Readable } from 'node:stream';
+
+import type { Kaos, KaosProcess } from '@moonshot-ai/kaos';
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../../agent/tool';
+import { isAbortError } from '../../../loop/errors';
+import { ToolAccesses } from '../../../loop/tool-access';
+import type { ExecutableToolResult, ToolExecution } from '../../../loop/types';
+import { resolvePathAccessPath } from '../../policies/path-access';
+import type { PathClass } from '../../policies/path-access';
+import { isSensitiveFile, SENSITIVE_DOT_VARIANT_SUFFIXES } from '../../policies/sensitive';
+import { toInputJsonSchema } from '../../support/input-schema';
+import { ensureRgPath, rgUnavailableMessage } from '../../support/rg-locator';
+import { ToolResultBuilder } from '../../support/result-builder';
+import type { WorkspaceConfig } from '../../support/workspace';
+import GREP_DESCRIPTION from './grep.md';
+
+export const GrepInputSchema = z.object({
+  pattern: z.string().describe('Regular expression to search for.'),
+  path: z
+    .string()
+    .optional()
+    .describe(
+      'File or directory to search. Accepts an absolute path, or a path relative to the current working directory. Omit to search the current working directory. Use Read instead when you already know a concrete file path and need its contents.',
+    ),
+  glob: z.string().optional().describe('Optional glob filter passed to ripgrep.'),
+  type: z
+    .string()
+    .optional()
+    .describe(
+      'Optional ripgrep file type filter, such as ts or py. Prefer this over `glob` when filtering by language or file kind: it is more efficient and less error-prone than an equivalent glob pattern.',
+    ),
+  output_mode: z
+    .enum(['content', 'files_with_matches', 'count_matches'])
+    .optional()
+    .describe(
+      'Shape of the result. `content` shows matching lines (honors `-A`, `-B`, `-C`, `-n`, and `head_limit`); `files_with_matches` shows only the paths of files that contain a match (honors `head_limit`); `count_matches` shows the total number of matches. Defaults to `files_with_matches`.',
+    ),
+  '-i': z.boolean().optional().describe('Perform a case-insensitive search. Defaults to false.'),
+  '-n': z
+    .boolean()
+    .optional()
+    .describe(
+      'Prefix each matching line with its line number. Applies only when `output_mode` is `content`. Defaults to true.',
+    ),
+  '-A': z
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .describe(
+      'Number of lines to show after each match. Applies only when `output_mode` is `content`.',
+    ),
+  '-B': z
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .describe(
+      'Number of lines to show before each match. Applies only when `output_mode` is `content`.',
+    ),
+  '-C': z
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .describe(
+      'Number of lines to show before and after each match. Applies only when `output_mode` is `content`; takes precedence over `-A` and `-B`.',
+    ),
+  head_limit: z
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .describe(
+      'Limit output to the first N lines/entries after offset. Defaults to 250. Pass 0 for unlimited.',
+    ),
+  offset: z
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .describe(
+      'Number of leading lines/entries to skip before applying `head_limit`. Use it together with `head_limit` to page through large result sets. Defaults to 0.',
+    ),
+  multiline: z
+    .boolean()
+    .optional()
+    .describe(
+      'Enable multiline matching, where the pattern can span line boundaries and `.` also matches newlines. Defaults to false.',
+    ),
+  include_ignored: z
+    .boolean()
+    .optional()
+    .describe(
+      'Also search files excluded by ignore files such as `.gitignore`, `.ignore`, and `.rgignore` (for example `node_modules` or build outputs). Sensitive files (such as `.env`) remain filtered out for safety. Defaults to false.',
+    ),
+});
+
+export const GrepOutputSchema = z.object({
+  mode: z.enum(['content', 'files_with_matches', 'count_matches']),
+  numFiles: z.number().int().nonnegative(),
+  filenames: z.array(z.string()),
+  content: z.string().optional(),
+  numLines: z.number().int().nonnegative().optional(),
+  numMatches: z.number().int().nonnegative().optional(),
+  appliedLimit: z.number().int().nonnegative().optional(),
+});
+
+export type GrepInput = z.Infer<typeof GrepInputSchema>;
+export type GrepOutput = z.Infer<typeof GrepOutputSchema>;
+
+const DEFAULT_TIMEOUT_MS = 20_000;
+const SIGTERM_GRACE_MS = 5_000;
+const MAX_OUTPUT_BYTES = 10 * 1024 * 1024;
+// Column cap applied to non-content output modes only; `content` mode returns
+// matching lines in full so the cap is intentionally skipped there.
+const RG_MAX_COLUMNS = 500;
+const DEFAULT_HEAD_LIMIT = 250;
+const MTIME_STAT_CONCURRENCY = 32;
+const VCS_DIRECTORIES_TO_EXCLUDE = ['.git', '.svn', '.hg', '.bzr', '.jj', '.sl'] as const;
+// This is a conservative prefilter. The authoritative sensitive-file check
+// still happens on parsed rg records after execution.
+const SENSITIVE_KEY_BASENAMES = ['id_rsa', 'id_ed25519', 'id_ecdsa'] as const;
+const SENSITIVE_KEY_GLOBS_TO_EXCLUDE = SENSITIVE_KEY_BASENAMES.flatMap((name) => [
+  `**/${name}`,
+  `**/${name}[-_]*`,
+  ...SENSITIVE_DOT_VARIANT_SUFFIXES.map((suffix) => `**/${name}${suffix}`),
+]);
+const SENSITIVE_GLOBS_TO_EXCLUDE = [
+  '**/.env',
+  ...SENSITIVE_KEY_GLOBS_TO_EXCLUDE,
+  '**/.aws/credentials',
+  '**/.aws/credentials/**',
+  '**/.gcp/credentials',
+  '**/.gcp/credentials/**',
+] as const;
+
+// Line formats produced by ripgrep:
+//   content match with --null:   "file.py<NUL>10:matched text"
+//   context line with --null:    "file.py<NUL>9-context text"
+//   count_matches with --null:   "file.py<NUL>2"
+//   non-NUL content fallback:    "file.py:10:matched text"
+//   context divider: "--"
+// Runtime rg output uses NUL as the path boundary; the regex handles
+// line-oriented output without NUL delimiters.
+const CONTENT_LINE_RE = /^(.*?)([:-])(\d+)\2/;
+
+export class GrepTool implements BuiltinTool<GrepInput> {
+  readonly name = 'Grep' as const;
+  readonly description = GREP_DESCRIPTION;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(GrepInputSchema);
+  constructor(
+    private readonly kaos: Kaos,
+    private readonly workspace: WorkspaceConfig,
+  ) {}
+
+  resolveExecution(args: GrepInput): ToolExecution {
+    let path: string | undefined;
+    if (args.path !== undefined) {
+      path = resolvePathAccessPath(args.path, {
+        kaos: this.kaos,
+        workspace: this.workspace,
+        operation: 'search',
+        policy: { guardMode: 'absolute-outside-allowed', checkSensitive: false },
+      });
+    }
+    const searchPaths = [path ?? this.workspace.workspaceDir];
+    const searchPath = args.path ?? this.workspace.workspaceDir;
+    return {
+      accesses: ToolAccesses.searchTree(searchPaths[0]!),
+      description: `Searching for '${args.pattern}' in ${searchPath}`,
+      execute: ({ signal }) => this.execution(args, signal, searchPaths),
+    };
+  }
+
+  private async execution(
+    args: GrepInput,
+    signal: AbortSignal,
+    searchPaths: string[],
+  ): Promise<ExecutableToolResult> {
+    if (signal.aborted) {
+      return { isError: true, output: 'Aborted before search started' };
+    }
+
+    const pathClass = this.kaos.pathClass();
+    let rgPath: string;
+    try {
+      const resolution = await ensureRgPath({ signal });
+      rgPath = resolution.path;
+    } catch (error) {
+      if (isAbortError(error)) {
+        return { isError: true, output: 'Grep aborted' };
+      }
+      return { isError: true, output: rgUnavailableMessage(error) };
+    }
+
+    let runResult = await runRipgrepOnce(this.kaos, buildRgArgs(rgPath, args, searchPaths), signal);
+    if (runResult.kind === 'tool-error') return runResult.result;
+    if (shouldRetryRipgrepEagain(runResult)) {
+      runResult = await runRipgrepOnce(
+        this.kaos,
+        buildRgArgs(rgPath, args, searchPaths, true),
+        signal,
+      );
+      if (runResult.kind === 'tool-error') return runResult.result;
+    }
+
+    const { exitCode, stderrText, bufferTruncated, stderrTruncated, timedOut } = runResult;
+    let { stdoutText } = runResult;
+
+    // rg exit codes: 0 = matches, 1 = no matches, 2 = error. Timeout kills
+    // usually surface as a signal exit code; keep any complete partial records.
+    if (exitCode !== 0 && exitCode !== 1 && !timedOut) {
+      return {
+        isError: true,
+        output: formatRipgrepError(exitCode, stderrText, stderrTruncated),
+      };
+    }
+
+    const mode = args.output_mode ?? 'files_with_matches';
+    if (bufferTruncated || timedOut) {
+      stdoutText = omitIncompleteTrailingRecord(stdoutText, mode);
+    }
+    if (timedOut && stdoutText.trim() === '') {
+      return {
+        isError: true,
+        output: `Grep timed out after ${String(DEFAULT_TIMEOUT_MS / 1000)}s. Try a more specific path or pattern.`,
+      };
+    }
+    if (signal.aborted) {
+      return { isError: true, output: 'Grep aborted' };
+    }
+
+    const rawLines = parseRipgrepOutput(stdoutText, mode);
+
+    const filteredSensitive = new Set<string>();
+    const keptLines = filterSensitiveLines(rawLines, mode, filteredSensitive, pathClass);
+    let orderedLines: ParsedGrepLine[];
+    try {
+      orderedLines =
+        mode === 'files_with_matches' && !timedOut
+          ? await sortFilesWithMatchesByMtime(keptLines, this.kaos, signal)
+          : keptLines;
+    } catch (error) {
+      if (error instanceof GrepAbortedError) {
+        return { isError: true, output: 'Grep aborted' };
+      }
+      throw error;
+    }
+
+    const offset = args.offset ?? 0;
+    const headLimit = args.head_limit ?? DEFAULT_HEAD_LIMIT;
+    const afterOffset = offset > 0 ? orderedLines.slice(offset) : orderedLines;
+    const limitActive = headLimit > 0;
+    const limited = limitActive ? afterOffset.slice(0, headLimit) : afterOffset;
+    const paginationTruncated = limitActive && afterOffset.length > headLimit;
+
+    // Human-readable annotations are appended after visible matches.
+    // In count mode, the data stream must stay pure `path:count` lines
+    // — the count summary and pagination notice move to a side channel
+    // (returned via `result.message`) so they don't contaminate it.
+    // Other modes keep these notices inline in `output`.
+    const messages: string[] = [];
+    const sideChannelMessages: string[] = [];
+    if (filteredSensitive.size > 0) {
+      const displayedFilteredPaths = [...filteredSensitive].map((path) =>
+        relativizeIfUnder(path, this.workspace.workspaceDir, pathClass),
+      );
+      messages.push(
+        `Filtered ${String(filteredSensitive.size)} sensitive file(s): ${displayedFilteredPaths.join(', ')}`,
+      );
+    }
+    if (mode === 'count_matches' && orderedLines.length > 0) {
+      sideChannelMessages.push(formatCountSummary(orderedLines, filteredSensitive.size > 0));
+    }
+    if (paginationTruncated) {
+      const total = afterOffset.length + offset;
+      const nextOffset = offset + headLimit;
+      const paginationNotice = `Results truncated to ${String(headLimit)} lines (total: ${String(total)}). Use offset=${String(nextOffset)} to see more.`;
+      if (mode === 'count_matches') {
+        sideChannelMessages.push(paginationNotice);
+      } else {
+        messages.push(paginationNotice);
+      }
+    }
+    if (bufferTruncated) {
+      messages.push(
+        `[stdout truncated at ${String(MAX_OUTPUT_BYTES)} bytes; incomplete trailing line omitted]`,
+      );
+    }
+    if (timedOut) {
+      messages.push(
+        `Grep timed out after ${String(DEFAULT_TIMEOUT_MS / 1000)}s; partial results returned`,
+      );
+    }
+
+    const contentIncludesLineNumbers = mode === 'content' && args['-n'] !== false;
+    const displayedLines = limited.map((line) =>
+      formatDisplayLine(
+        line,
+        mode,
+        this.workspace.workspaceDir,
+        pathClass,
+        contentIncludesLineNumbers,
+      ),
+    );
+    const contentBody = displayedLines.join('\n');
+    const visibleBody =
+      orderedLines.length === 0 && filteredSensitive.size > 0
+        ? 'No non-sensitive matches found'
+        : contentBody;
+    const emptyResultMessage =
+      SENSITIVE_GLOBS_TO_EXCLUDE.length > 0 ? 'No non-sensitive matches found' : 'No matches found';
+    const combined =
+      visibleBody === '' && messages.length === 0
+        ? emptyResultMessage
+        : messages.length > 0
+          ? visibleBody === ''
+            ? messages.join('\n')
+            : `${visibleBody}\n${messages.join('\n')}`
+          : visibleBody;
+
+    const builder = new ToolResultBuilder();
+    builder.write(combined);
+    return builder.ok(sideChannelMessages.join('\n'));
+  }
+
+}
+
+interface RipgrepRunResult {
+  readonly kind: 'result';
+  readonly exitCode: number;
+  readonly stdoutText: string;
+  readonly stderrText: string;
+  readonly bufferTruncated: boolean;
+  readonly stderrTruncated: boolean;
+  readonly timedOut: boolean;
+}
+
+type RipgrepRunOutcome =
+  | RipgrepRunResult
+  | { readonly kind: 'tool-error'; readonly result: ExecutableToolResult };
+
+type GrepMode = 'content' | 'files_with_matches' | 'count_matches';
+
+type ParsedGrepLine =
+  | {
+      readonly kind: 'record';
+      readonly filePath: string;
+      readonly payload: string;
+    }
+  | {
+      readonly kind: 'separator';
+    }
+  | {
+      readonly kind: 'legacy';
+      readonly text: string;
+    };
+
+class GrepAbortedError extends Error {
+  constructor() {
+    super('Grep aborted');
+    this.name = 'GrepAbortedError';
+  }
+}
+
+async function runRipgrepOnce(
+  kaos: Kaos,
+  rgArgs: readonly string[],
+  signal: AbortSignal,
+): Promise<RipgrepRunOutcome> {
+  if (signal.aborted) {
+    return { kind: 'tool-error', result: { isError: true, output: 'Grep aborted' } };
+  }
+
+  let proc: KaosProcess;
+  try {
+    proc = await kaos.exec(...rgArgs);
+  } catch (error) {
+    // Spawn can still fail after path resolution, e.g. permissions or a
+    // corrupt binary. ENOENT gets the same actionable hint as locator failures.
+    const isEnoent =
+      error instanceof Error &&
+      'code' in error &&
+      (error as NodeJS.ErrnoException).code === 'ENOENT';
+    return {
+      kind: 'tool-error',
+      result: {
+        isError: true,
+        output: isEnoent
+          ? rgUnavailableMessage(error)
+          : error instanceof Error
+            ? error.message
+            : String(error),
+      },
+    };
+  }
+
+  try {
+    proc.stdin.end();
+  } catch {
+    /* already gone */
+  }
+
+  let timedOut = false;
+  let aborted = false;
+  let killed = false;
+
+  const killProc = async (): Promise<void> => {
+    if (killed) return;
+    killed = true;
+    try {
+      await proc.kill('SIGTERM');
+    } catch {
+      /* process already gone */
+    }
+    const exited = proc
+      .wait()
+      .then(() => true)
+      .catch(() => true);
+    const raced = await Promise.race([
+      exited,
+      new Promise<false>((resolve) => {
+        setTimeout(() => {
+          resolve(false);
+        }, SIGTERM_GRACE_MS);
+      }),
+    ]);
+    if (!raced && proc.exitCode === null) {
+      try {
+        await proc.kill('SIGKILL');
+      } catch {
+        /* ignore */
+      }
+    }
+  };
+
+  const onAbort = (): void => {
+    aborted = true;
+    void killProc();
+  };
+  signal.addEventListener('abort', onAbort);
+  // AbortSignal does not replay past abort events; check once after registering
+  // the listener so already-aborted calls still run the cleanup path.
+  if (signal.aborted) onAbort();
+
+  const timeoutHandle = setTimeout(() => {
+    timedOut = true;
+    void killProc();
+  }, DEFAULT_TIMEOUT_MS);
+
+  let exitCode = 0;
+  let stdoutText = '';
+  let stderrText = '';
+  let bufferTruncated = false;
+  let stderrTruncated = false;
+
+  try {
+    const [stdoutResult, stderrResult, code] = await Promise.all([
+      readStreamWithCap(proc.stdout, MAX_OUTPUT_BYTES),
+      readStreamWithCap(proc.stderr, MAX_OUTPUT_BYTES),
+      proc.wait(),
+    ]);
+    stdoutText = stdoutResult.text;
+    stderrText = stderrResult.text;
+    bufferTruncated = stdoutResult.truncated;
+    stderrTruncated = stderrResult.truncated;
+    exitCode = code;
+  } catch (error) {
+    return {
+      kind: 'tool-error',
+      result: {
+        isError: true,
+        output: error instanceof Error ? error.message : String(error),
+      },
+    };
+  } finally {
+    clearTimeout(timeoutHandle);
+    signal.removeEventListener('abort', onAbort);
+  }
+
+  if (aborted) {
+    return { kind: 'tool-error', result: { isError: true, output: 'Grep aborted' } };
+  }
+
+  return {
+    kind: 'result',
+    exitCode,
+    stdoutText,
+    stderrText,
+    bufferTruncated,
+    stderrTruncated,
+    timedOut,
+  };
+}
+
+function shouldRetryRipgrepEagain(result: RipgrepRunResult): boolean {
+  return (
+    result.exitCode !== 0 &&
+    result.exitCode !== 1 &&
+    !result.timedOut &&
+    isEagainRipgrepError(result.stderrText)
+  );
+}
+
+function isEagainRipgrepError(stderr: string): boolean {
+  return stderr.includes('os error 11') || stderr.includes('Resource temporarily unavailable');
+}
+
+async function sortFilesWithMatchesByMtime(
+  lines: readonly ParsedGrepLine[],
+  kaos: Kaos,
+  signal: AbortSignal,
+): Promise<ParsedGrepLine[]> {
+  const entries = await mapWithConcurrency(
+    lines,
+    MTIME_STAT_CONCURRENCY,
+    signal,
+    async (line, index) => {
+      const path =
+        line.kind === 'record' ? line.filePath : line.kind === 'legacy' ? line.text : undefined;
+      let mtime = 0;
+      if (path !== undefined) {
+        try {
+          mtime = (await kaos.stat(path)).stMtime ?? 0;
+        } catch {
+          // Keep stat failures visible; use mtime=0 so they sort after known files.
+        }
+      }
+      return { line, mtime, index };
+    },
+  );
+  entries.sort((a, b) => b.mtime - a.mtime || a.index - b.index);
+  return entries.map((entry) => entry.line);
+}
+
+async function mapWithConcurrency<T, U>(
+  items: readonly T[],
+  concurrency: number,
+  signal: AbortSignal,
+  mapper: (item: T, index: number) => Promise<U>,
+): Promise<U[]> {
+  if (signal.aborted) throw new GrepAbortedError();
+  if (items.length === 0) return [];
+
+  const results: U[] = [];
+  results.length = items.length;
+  let nextIndex = 0;
+  const workerCount = Math.min(Math.max(1, concurrency), items.length);
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      while (true) {
+        if (signal.aborted) return;
+        const index = nextIndex;
+        nextIndex += 1;
+        if (index >= items.length) return;
+        results[index] = await mapper(items[index] as T, index);
+      }
+    }),
+  );
+  if (signal.aborted) throw new GrepAbortedError();
+  return results;
+}
+
+function buildRgArgs(
+  rgPath: string,
+  args: GrepInput,
+  searchPaths: readonly string[],
+  singleThreaded = false,
+): string[] {
+  const cmd: string[] = [rgPath];
+  if (singleThreaded) cmd.push('-j', '1');
+  cmd.push('--hidden');
+  const mode = args.output_mode ?? 'files_with_matches';
+  // `content` mode returns matching lines verbatim. Capping columns here would
+  // make rg replace any line wider than the cap with a placeholder, silently
+  // dropping the actual match text. The cap is only useful outside `content`
+  // mode, where line text is never surfaced.
+  if (mode !== 'content') {
+    cmd.push('--max-columns', String(RG_MAX_COLUMNS));
+  }
+  cmd.push('--null');
+  for (const dir of VCS_DIRECTORIES_TO_EXCLUDE) {
+    cmd.push('--glob', `!${dir}`);
+  }
+
+  if (mode === 'files_with_matches') cmd.push('-l');
+  else if (mode === 'count_matches') {
+    // rg omits the filename when only one file is searched, so pin it on. Without
+    // this, the per-file line collapses to a bare count and the summary parser
+    // disagrees with the displayed number.
+    cmd.push('--count-matches', '--with-filename');
+  }
+
+  if (args['-i']) cmd.push('-i');
+  if (mode === 'content') {
+    cmd.push('--with-filename');
+    if (args['-n'] !== false) {
+      cmd.push('-n');
+    } else {
+      cmd.push('--field-context-separator', ':');
+    }
+    if (args['-C'] !== undefined) {
+      cmd.push('-C', String(args['-C']));
+    } else {
+      if (args['-A'] !== undefined) cmd.push('-A', String(args['-A']));
+      if (args['-B'] !== undefined) cmd.push('-B', String(args['-B']));
+    }
+  }
+  if (args.glob !== undefined) cmd.push('--glob', args.glob);
+  if (args.type !== undefined) cmd.push('--type', args.type);
+  if (args.multiline) cmd.push('-U', '--multiline-dotall');
+  if (args.include_ignored) cmd.push('--no-ignore');
+  for (const glob of SENSITIVE_GLOBS_TO_EXCLUDE) {
+    // Appended after user globs so a broad include such as `**/.env` cannot
+    // undo this first-pass exclusion. Explicit file paths are still protected
+    // by the post-processing filter because rg intentionally searches them.
+    cmd.push('--glob', `!${glob}`);
+  }
+  // Do not forward `head_limit` to `rg --max-count`: omitted means "use the
+  // tool default", head_limit=0 means "unlimited", while `rg --max-count 0`
+  // means "zero matches per file". Pagination happens in post-processing.
+
+  cmd.push('--', args.pattern, ...searchPaths);
+  return cmd;
+}
+
+function splitRgLines(text: string): string[] {
+  if (text === '') return [];
+  const lines = text.split('\n');
+  // Strip the trailing empty line left by a final newline.
+  while (lines.length > 0 && lines.at(-1) === '') {
+    lines.pop();
+  }
+  return lines.map((line) => stripTrailingCarriageReturn(line));
+}
+
+function parseRipgrepOutput(text: string, mode: GrepMode): ParsedGrepLine[] {
+  if (text === '') return [];
+  if (!text.includes('\0')) {
+    return splitRgLines(text).map((line) =>
+      mode === 'content' && line === '--' ? { kind: 'separator' } : { kind: 'legacy', text: line },
+    );
+  }
+
+  if (mode === 'files_with_matches') {
+    return text
+      .split('\0')
+      .map((filePath) => stripTrailingCarriageReturn(filePath))
+      .filter((filePath) => filePath !== '')
+      .map((filePath) => ({ kind: 'record', filePath, payload: '' }));
+  }
+
+  const records: ParsedGrepLine[] = [];
+  let cursor = 0;
+  while (cursor < text.length) {
+    if (text[cursor] === '\n') {
+      cursor += 1;
+      continue;
+    }
+    if (text.startsWith('--\r\n', cursor)) {
+      records.push({ kind: 'separator' });
+      cursor += 4;
+      continue;
+    }
+    if (text.startsWith('--\n', cursor)) {
+      records.push({ kind: 'separator' });
+      cursor += 3;
+      continue;
+    }
+
+    const nulIndex = text.indexOf('\0', cursor);
+    if (nulIndex < 0) {
+      const tail = stripTrailingCarriageReturn(text.slice(cursor));
+      if (tail !== '') records.push({ kind: 'legacy', text: tail });
+      break;
+    }
+
+    const lineEnd = text.indexOf('\n', nulIndex + 1);
+    const payloadEnd = lineEnd >= 0 ? lineEnd : text.length;
+    const filePath = text.slice(cursor, nulIndex);
+    const payload = stripTrailingCarriageReturn(text.slice(nulIndex + 1, payloadEnd));
+    records.push({ kind: 'record', filePath, payload });
+    cursor = lineEnd >= 0 ? lineEnd + 1 : text.length;
+  }
+  return records;
+}
+
+function formatDisplayLine(
+  line: ParsedGrepLine,
+  mode: GrepMode,
+  workspaceDir: string,
+  pathClass: PathClass,
+  contentIncludesLineNumbers: boolean,
+): string {
+  if (line.kind === 'separator') return '--';
+  if (line.kind === 'record') {
+    const displayPath = relativizeIfUnder(line.filePath, workspaceDir, pathClass);
+    if (mode === 'files_with_matches') return displayPath;
+    if (mode === 'count_matches') return `${displayPath}:${line.payload}`;
+    const separator = contentIncludesLineNumbers ? contentPayloadPathSeparator(line.payload) : ':';
+    return `${displayPath}${separator}${line.payload}`;
+  }
+
+  const text = line.text;
+  if (mode === 'files_with_matches') {
+    return relativizeIfUnder(text, workspaceDir, pathClass);
+  }
+  if (mode === 'count_matches') {
+    const idx = text.lastIndexOf(':');
+    if (idx <= 0) return text;
+    return relativizeIfUnder(text.slice(0, idx), workspaceDir, pathClass) + text.slice(idx);
+  }
+
+  const filePath = extractContentFilePath(text, pathClass);
+  if (filePath !== undefined) {
+    return relativizeIfUnder(filePath, workspaceDir, pathClass) + text.slice(filePath.length);
+  }
+  return text;
+}
+
+/**
+ * If `candidate` is under `base`, return the portion after `base/`.
+ * Otherwise return `candidate` unchanged. Both arguments should be
+ * canonical absolute paths in the active backend path class.
+ */
+function relativizeIfUnder(candidate: string, base: string, pathClass: PathClass): string {
+  const sep = pathClass === 'win32' ? '\\' : '/';
+  const comparableCandidate = pathClass === 'win32' ? candidate.toLowerCase() : candidate;
+  const comparableBase = pathClass === 'win32' ? base.toLowerCase() : base;
+  if (comparableCandidate === comparableBase) return '.';
+  const prefix = comparableBase.endsWith(sep) ? comparableBase : comparableBase + sep;
+  if (comparableCandidate.startsWith(prefix)) {
+    return candidate.slice(prefix.length);
+  }
+  return candidate;
+}
+
+function omitIncompleteTrailingRecord(text: string, mode: GrepMode): string {
+  if (!text.includes('\0')) return omitIncompleteTrailingLine(text);
+  if (mode === 'files_with_matches') {
+    const lastNul = text.lastIndexOf('\0');
+    return lastNul >= 0 ? text.slice(0, lastNul + 1) : '';
+  }
+
+  let cursor = 0;
+  let lastCompleteEnd = 0;
+  while (cursor < text.length) {
+    if (text[cursor] === '\n') {
+      cursor += 1;
+      lastCompleteEnd = cursor;
+      continue;
+    }
+    if (text.startsWith('--\r\n', cursor)) {
+      cursor += 4;
+      lastCompleteEnd = cursor;
+      continue;
+    }
+    if (text.startsWith('--\n', cursor)) {
+      cursor += 3;
+      lastCompleteEnd = cursor;
+      continue;
+    }
+
+    const nulIndex = text.indexOf('\0', cursor);
+    if (nulIndex < 0) break;
+    const lineEnd = text.indexOf('\n', nulIndex + 1);
+    if (lineEnd < 0) break;
+    cursor = lineEnd + 1;
+    lastCompleteEnd = cursor;
+  }
+  return text.slice(0, lastCompleteEnd);
+}
+
+function omitIncompleteTrailingLine(text: string): string {
+  const lastNewline = text.lastIndexOf('\n');
+  return lastNewline >= 0 ? text.slice(0, lastNewline) : '';
+}
+
+function formatRipgrepError(
+  exitCode: number,
+  stderrText: string,
+  stderrTruncated: boolean,
+): string {
+  const stderr = stderrText.trim();
+  if (stderr.length === 0) {
+    return `Failed to grep: ripgrep exited with code ${String(exitCode)}`;
+  }
+
+  const summary = summarizeRipgrepStderr(stderr);
+  const lines = [`Failed to grep: ${summary}`, '', 'ripgrep stderr:', stderr];
+  if (stderrTruncated) {
+    lines.push(`[stderr truncated at ${String(MAX_OUTPUT_BYTES)} bytes]`);
+  }
+  return lines.join('\n');
+}
+
+function summarizeRipgrepStderr(stderr: string): string {
+  const lines = splitRgLines(stderr)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  const errorLine = lines.findLast((line) => line.toLowerCase().startsWith('error:'));
+  return errorLine ?? lines.at(-1) ?? 'ripgrep error';
+}
+
+function filterSensitiveLines(
+  lines: readonly ParsedGrepLine[],
+  mode: GrepMode,
+  filteredPaths: Set<string>,
+  pathClass: PathClass,
+): ParsedGrepLine[] {
+  const kept: ParsedGrepLine[] = [];
+  for (const line of lines) {
+    if (line.kind === 'separator') {
+      kept.push(line);
+      continue;
+    }
+    const filePath = parsedFilePath(line, mode, pathClass);
+    if (filePath !== undefined && isSensitiveFile(filePath, pathClass)) {
+      filteredPaths.add(filePath);
+      continue;
+    }
+    kept.push(line);
+  }
+  return mode === 'content' ? normalizeContextSeparators(kept) : kept;
+}
+
+function normalizeContextSeparators(lines: readonly ParsedGrepLine[]): ParsedGrepLine[] {
+  const normalized: ParsedGrepLine[] = [];
+  for (const line of lines) {
+    if (
+      line.kind === 'separator' &&
+      (normalized.length === 0 || normalized.at(-1)?.kind === 'separator')
+    ) {
+      continue;
+    }
+    normalized.push(line);
+  }
+  while (normalized.length > 0 && normalized.at(-1)?.kind === 'separator') {
+    normalized.pop();
+  }
+  return normalized;
+}
+
+function parsedFilePath(
+  line: ParsedGrepLine,
+  mode: GrepMode,
+  pathClass: PathClass,
+): string | undefined {
+  if (line.kind === 'record') return line.filePath;
+  if (line.kind === 'separator') return undefined;
+  const text = line.text;
+  if (mode === 'files_with_matches') return text;
+  if (mode === 'count_matches') {
+    const idx = text.lastIndexOf(':');
+    return idx > 0 ? text.slice(0, idx) : text;
+  }
+  return extractContentFilePath(text, pathClass);
+}
+
+function extractContentFilePath(line: string, pathClass: PathClass): string | undefined {
+  const m = CONTENT_LINE_RE.exec(line);
+  if (m?.[1] !== undefined) return m[1];
+
+  const separatorIndex = noLineNumberContentSeparatorIndex(line, pathClass);
+  return separatorIndex > 0 ? line.slice(0, separatorIndex) : undefined;
+}
+
+function noLineNumberContentSeparatorIndex(line: string, pathClass: PathClass): number {
+  const searchFrom = pathClass === 'win32' && /^[A-Za-z]:/.test(line) ? 2 : 0;
+  return line.indexOf(':', searchFrom);
+}
+
+function contentPayloadPathSeparator(payload: string): ':' | '-' {
+  const m = /^(\d+)([:-])/.exec(payload);
+  return m?.[2] === '-' ? '-' : ':';
+}
+
+function stripTrailingCarriageReturn(value: string): string {
+  return value.endsWith('\r') ? value.slice(0, -1) : value;
+}
+
+function formatCountSummary(lines: readonly ParsedGrepLine[], redactedSensitive: boolean): string {
+  let totalMatches = 0;
+  let totalFiles = 0;
+  for (const line of lines) {
+    const rawCount =
+      line.kind === 'record'
+        ? line.payload
+        : line.kind === 'legacy'
+          ? countPayloadFromLegacyLine(line.text)
+          : undefined;
+    if (rawCount === undefined) continue;
+    const count = Number(rawCount);
+    if (!Number.isSafeInteger(count) || count < 0) continue;
+    totalMatches += count;
+    totalFiles++;
+  }
+
+  const occurrenceWord = totalMatches === 1 ? 'occurrence' : 'occurrences';
+  const fileWord = totalFiles === 1 ? 'file' : 'files';
+  const scope = redactedSensitive ? 'total non-sensitive' : 'total';
+  return `Found ${String(totalMatches)} ${scope} ${occurrenceWord} across ${String(totalFiles)} ${fileWord}.`;
+}
+
+function countPayloadFromLegacyLine(line: string): string | undefined {
+  const idx = line.lastIndexOf(':');
+  return idx > 0 ? line.slice(idx + 1) : undefined;
+}
+
+interface CappedStreamResult {
+  readonly text: string;
+  readonly truncated: boolean;
+}
+
+async function readStreamWithCap(stream: Readable, maxBytes: number): Promise<CappedStreamResult> {
+  const chunks: Buffer[] = [];
+  let total = 0;
+  let truncated = false;
+  for await (const chunk of stream) {
+    const buf: Buffer = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : (chunk as Buffer);
+    if (truncated) continue;
+    if (total + buf.length > maxBytes) {
+      const remaining = maxBytes - total;
+      if (remaining > 0) chunks.push(buf.subarray(0, remaining));
+      total = maxBytes;
+      truncated = true;
+      continue;
+    }
+    chunks.push(buf);
+    total += buf.length;
+  }
+  return { text: Buffer.concat(chunks).toString('utf8'), truncated };
+}
diff --git a/packages/agent-core/src/tools/builtin/file/line-endings.ts b/packages/agent-core/src/tools/builtin/file/line-endings.ts
new file mode 100644
index 000000000..38e117a77
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/file/line-endings.ts
@@ -0,0 +1,51 @@
+export type LineEndingStyle = 'lf' | 'crlf' | 'mixed';
+
+export interface ModelTextView {
+  text: string;
+  lineEndingStyle: LineEndingStyle;
+}
+
+export function detectLineEndingStyle(text: string): LineEndingStyle {
+  let hasCrLf = false;
+  let hasLf = false;
+  let hasLoneCr = false;
+
+  for (let i = 0; i < text.length; i++) {
+    const code = text.codePointAt(i);
+    if (code === 13) {
+      if (text.codePointAt(i + 1) === 10) {
+        hasCrLf = true;
+        i++;
+      } else {
+        hasLoneCr = true;
+      }
+    } else if (code === 10) {
+      hasLf = true;
+    }
+  }
+
+  if (hasLoneCr || (hasCrLf && hasLf)) return 'mixed';
+  if (hasCrLf) return 'crlf';
+  return 'lf';
+}
+
+export function toModelTextView(raw: string): ModelTextView {
+  const lineEndingStyle = detectLineEndingStyle(raw);
+  if (lineEndingStyle !== 'crlf') {
+    return { text: raw, lineEndingStyle };
+  }
+
+  return {
+    text: raw.replaceAll('\r\n', '\n'),
+    lineEndingStyle,
+  };
+}
+
+export function materializeModelText(text: string, lineEndingStyle: LineEndingStyle): string {
+  if (lineEndingStyle !== 'crlf') return text;
+  return text.replaceAll('\r\n', '\n').replaceAll('\n', '\r\n');
+}
+
+export function makeCarriageReturnsVisible(text: string): string {
+  return text.replaceAll('\r', '\\r');
+}
diff --git a/packages/agent-core/src/tools/builtin/file/read-media.md b/packages/agent-core/src/tools/builtin/file/read-media.md
new file mode 100644
index 000000000..0ff49fb6c
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/file/read-media.md
@@ -0,0 +1,13 @@
+Read media content from a file.
+
+**Tips:**
+- Make sure you follow the description of each tool parameter.
+- A `<system>` tag is given before the file content; it summarizes the mime type, byte size and, for images, the original pixel dimensions. When outputting coordinates, give relative coordinates first and compute absolute coordinates from the original image size. After generating or editing media via commands or scripts, read the result back before continuing.
+- The system will notify you when there is anything wrong when reading the file.
+- This tool is a tool that you typically want to use in parallel. Always read multiple files in one response when possible.
+- This tool can only read image or video files. To read text files, use the Read tool. To list directories, use `ls` via Bash for a known directory, or Glob for pattern search.
+- If the file doesn't exist or path is invalid, an error will be returned.
+- The maximum size that can be read is {{ MAX_MEDIA_MEGABYTES }}MB. An error will be returned if the file is larger than this limit.
+- The media content will be returned in a form that you can directly view and understand.
+
+**Capabilities**
\ No newline at end of file
diff --git a/packages/agent-core/src/tools/builtin/file/read-media.ts b/packages/agent-core/src/tools/builtin/file/read-media.ts
new file mode 100644
index 000000000..b486d74ff
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/file/read-media.ts
@@ -0,0 +1,264 @@
+/**
+ * ReadMediaFileTool — read image/video files as multi-modal content.
+ *
+ * Returns a 4-part wrap:
+ * `[TextPart('<system>…</system>'), TextPart('<image|video path="…">'),
+ *   ImageContent|VideoContent, TextPart('</image|video>')]`
+ * and gates on the model's `image_in` / `video_in` capability.
+ *
+ * The leading `<system>` block summarizes mime type, byte size and (for
+ * images) original pixel dimensions, guides the model to derive absolute
+ * coordinates from that original size, and reminds it to re-read any media
+ * it generates or edits.
+ *
+ * Path safety: goes through the shared path access resolver used by
+ * Read/Write/Edit.
+ */
+
+import type { Kaos } from '@moonshot-ai/kaos';
+import type {
+  ContentPart,
+  ModelCapability,
+  VideoURLPart,
+  VideoUploadInput as ProviderVideoUploadInput,
+} from '@moonshot-ai/kosong';
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../../agent/tool';
+import { ToolAccesses } from '../../../loop/tool-access';
+import type { ExecutableToolResult, ToolExecution } from '../../../loop/types';
+import { renderPrompt } from '../../../utils/render-prompt';
+import { resolvePathAccessPath } from '../../policies/path-access';
+import { MEDIA_SNIFF_BYTES, detectFileType, sniffImageDimensions } from '../../support/file-type';
+import { toInputJsonSchema } from '../../support/input-schema';
+import type { WorkspaceConfig } from '../../support/workspace';
+import readMediaDescriptionHead from './read-media.md';
+
+// ── Constants ────────────────────────────────────────────────────────
+
+const MAX_MEDIA_MEGABYTES = 100;
+const MAX_MEDIA_BYTES = MAX_MEDIA_MEGABYTES * 1024 * 1024;
+
+export type VideoUploadInput = ProviderVideoUploadInput;
+
+export type VideoUploader = (input: VideoUploadInput) => Promise<VideoURLPart>;
+
+// ── Input schema ─────────────────────────────────────────────────────
+
+export const ReadMediaFileInputSchema = z.object({
+  path: z
+    .string()
+    .describe(
+      'Path to an image or video file. Relative paths resolve against the working directory; ' +
+        'a path outside the working directory must be absolute. ' +
+        'Directories and text files are not supported.',
+    ),
+});
+
+export type ReadMediaFileInput = z.Infer<typeof ReadMediaFileInputSchema>;
+
+// ── Tool description (capability-driven) ─────────────────────────────
+
+function buildDescription(capabilities: ModelCapability): string {
+  const head = renderPrompt(readMediaDescriptionHead, { MAX_MEDIA_MEGABYTES });
+  const lines: string[] = [head];
+  const hasImage = capabilities.image_in;
+  const hasVideo = capabilities.video_in;
+  if (hasImage && hasVideo) {
+    lines.push('- This tool supports image and video files for the current model.');
+  } else if (hasImage) {
+    lines.push(
+      '- This tool supports image files for the current model.',
+      '- Video files are not supported by the current model.',
+    );
+  } else if (hasVideo) {
+    lines.push(
+      '- This tool supports video files for the current model.',
+      '- Image files are not supported by the current model.',
+    );
+  } else {
+    lines.push('- The current model does not support image or video input.');
+  }
+  return lines.join('\n');
+}
+
+// ── System summary ───────────────────────────────────────────────────
+
+/**
+ * Build the `<system>` summary that precedes the media content.
+ *
+ * Carries mime type, byte size and (for images) the original pixel
+ * dimensions. When the dimensions are known it also guides the model to
+ * derive absolute coordinates from that original size; it always reminds
+ * the model to re-read any media it generates or edits.
+ */
+function buildSystemSummary(input: {
+  readonly kind: 'image' | 'video';
+  readonly mimeType: string;
+  readonly byteSize: number;
+  readonly dimensions: { readonly width: number; readonly height: number } | null;
+}): string {
+  const parts: string[] = [
+    `Read ${input.kind} file.`,
+    `Mime type: ${input.mimeType}.`,
+    `Size: ${String(input.byteSize)} bytes.`,
+  ];
+  // Coordinate guidance is only emitted when the original size is actually
+  // known — sniffing fails for some image formats (TIFF/ICO/HEIC/…), and
+  // telling the model to use a size that is not in the block would mislead it.
+  if (input.kind === 'image' && input.dimensions) {
+    parts.push(
+      `Original dimensions: ${String(input.dimensions.width)}x${String(input.dimensions.height)} pixels.`,
+      'If you need to output coordinates, output relative coordinates first ' +
+        'and compute absolute coordinates using the original image size.',
+    );
+  }
+  parts.push(
+    'If you generate or edit images or videos via commands or scripts, ' +
+      'read the result back immediately before continuing.',
+  );
+  return `<system>${parts.join(' ')}</system>`;
+}
+
+// ── Implementation ───────────────────────────────────────────────────
+
+export class ReadMediaFileTool implements BuiltinTool<ReadMediaFileInput> {
+  readonly name = 'ReadMediaFile' as const;
+  readonly description: string;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(ReadMediaFileInputSchema);
+  constructor(
+    private readonly kaos: Kaos,
+    private readonly workspace: WorkspaceConfig,
+    private readonly capabilities: ModelCapability,
+    private readonly videoUploader?: VideoUploader | undefined,
+  ) {
+    if (!capabilities.image_in && !capabilities.video_in) {
+      const skip = new Error('ReadMediaFile requires image_in or video_in capability');
+      skip.name = 'SkipThisTool';
+      throw skip;
+    }
+    this.description = buildDescription(capabilities);
+  }
+
+  resolveExecution(args: ReadMediaFileInput): ToolExecution {
+    const path = resolvePathAccessPath(args.path, {
+      kaos: this.kaos,
+      workspace: this.workspace,
+      operation: 'read',
+    });
+    return {
+      accesses: ToolAccesses.readFile(path),
+      description: `Reading media: ${args.path}`,
+      execute: () => this.execution(args, path),
+    };
+  }
+
+  private async execution(
+    args: ReadMediaFileInput,
+    safePath: string,
+  ): Promise<ExecutableToolResult> {
+    if (!args.path) {
+      return { isError: true, output: 'File path cannot be empty.' };
+    }
+
+    try {
+      // Sniff header first — read the first 512 bytes before deciding
+      // anything about MIME.
+      const header = await this.kaos.readBytes(safePath, MEDIA_SNIFF_BYTES);
+      const fileType = detectFileType(safePath, header);
+
+      if (fileType.kind === 'text') {
+        return {
+          isError: true,
+          output: `"${args.path}" is a text file. Use Read to read text files.`,
+        };
+      }
+      if (fileType.kind === 'unknown') {
+        return {
+          isError: true,
+          output:
+            `"${args.path}" is not a supported image or video file. ` +
+            'Use Read for text files, or Bash or an MCP tool for other binary formats.',
+        };
+      }
+
+      if (fileType.kind === 'image' && !this.capabilities.image_in) {
+        return {
+          isError: true,
+          output:
+            'The current model does not support image input. ' +
+            'Tell the user to use a model with image input capability.',
+        };
+      }
+      if (fileType.kind === 'video' && !this.capabilities.video_in) {
+        return {
+          isError: true,
+          output:
+            'The current model does not support video input. ' +
+            'Tell the user to use a model with video input capability.',
+        };
+      }
+
+      const stat = await this.kaos.stat(safePath);
+      if (stat.stSize === 0) {
+        return { isError: true, output: `"${args.path}" is empty.` };
+      }
+      if (stat.stSize > MAX_MEDIA_BYTES) {
+        return {
+          isError: true,
+          output:
+            `"${args.path}" is ${String(stat.stSize)} bytes, which exceeds the ` +
+            `maximum ${String(MAX_MEDIA_MEGABYTES)}MB for media files.`,
+        };
+      }
+
+      const data = await this.kaos.readBytes(safePath);
+      const base64 = data.toString('base64');
+      let mediaPart: ContentPart;
+      if (fileType.kind === 'image') {
+        mediaPart = {
+          type: 'image_url',
+          imageUrl: { url: `data:${fileType.mimeType};base64,${base64}` },
+        };
+      } else if (this.videoUploader !== undefined) {
+        mediaPart = await this.videoUploader({
+          data,
+          mimeType: fileType.mimeType,
+          filename: safePath.split(/[\\/]/).at(-1),
+        });
+      } else {
+        mediaPart = {
+          type: 'video_url',
+          videoUrl: { url: `data:${fileType.mimeType};base64,${base64}` },
+        };
+      }
+
+      const tag = fileType.kind === 'image' ? 'image' : 'video';
+      const openText = `<${tag} path="${safePath}">`;
+      const closeText = `</${tag}>`;
+
+      const dimensions =
+        fileType.kind === 'image' ? sniffImageDimensions(data) : null;
+      const systemText = buildSystemSummary({
+        kind: fileType.kind,
+        mimeType: fileType.mimeType,
+        byteSize: stat.stSize,
+        dimensions,
+      });
+
+      const output: ContentPart[] = [
+        { type: 'text', text: systemText },
+        { type: 'text', text: openText },
+        mediaPart,
+        { type: 'text', text: closeText },
+      ];
+
+      return { output, isError: false };
+    } catch (error) {
+      return {
+        isError: true,
+        output: `Failed to read ${args.path}: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+}
diff --git a/packages/agent-core/src/tools/builtin/file/read.md b/packages/agent-core/src/tools/builtin/file/read.md
new file mode 100644
index 000000000..79bdda810
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/file/read.md
@@ -0,0 +1,17 @@
+Read a text file from the local filesystem.
+
+If the user provides a concrete file path to a text file, call Read directly. Do not `Glob`, `ls`, or otherwise pre-check known text file paths; missing or invalid file paths return errors you can handle. Do not use Read for directories; use `ls` via Bash for a known directory, or Glob when you need files/directories matching a pattern. Use `Grep` only when the task is to search for unknown content or locations.
+
+When you need several files, prefer to read them in parallel: emit multiple `Read` calls in a single response instead of reading one file per turn.
+
+- Relative paths resolve against the working directory; a path outside the working directory must be absolute.
+- Returns up to {{ MAX_LINES }} lines or {{ MAX_BYTES_KB }} KB per call, whichever comes first; lines longer than {{ MAX_LINE_LENGTH }} chars are truncated mid-line.
+- Page larger files with `line_offset` (1-based start line) and `n_lines`. Omit `n_lines` to read up to the {{ MAX_LINES }}-line cap.
+- Sensitive files (`.env` files, credential stores, SSH keys, and similar secrets) are refused to protect secrets; do not attempt to read them.
+- Only UTF-8 text files can be read. Non-UTF-8 encodings, binary files, and files containing NUL bytes are refused; use `ReadMediaFile` for images or video, and Bash or an MCP tool for other binary formats.
+- Negative line_offset reads from the end of the file (for example, -100 reads the last 100 lines); the absolute value cannot exceed {{ MAX_LINES }}.
+- Output format: `<line-number>\t<content>` per line.
+- A `<system>...</system>` status block is appended after the file content; it summarizes how much was read (line and byte counts, truncation, line-ending notes) and is not part of the file itself.
+- Pure CRLF files are displayed with LF line endings; `Edit` matches this output and preserves CRLF when writing back.
+- Mixed or lone carriage-return line endings are shown as `\r` and require exact `Edit.old_string` escapes.
+- After a successful `Edit`/`Write`, do not re-read solely to prove the write landed. When the task depends on an exact file, API, or output shape, inspect the final external contract before finishing.
diff --git a/packages/agent-core/src/tools/builtin/file/read.ts b/packages/agent-core/src/tools/builtin/file/read.ts
new file mode 100644
index 000000000..2e27b06a8
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/file/read.ts
@@ -0,0 +1,444 @@
+import type { Kaos, StatResult } from '@moonshot-ai/kaos';
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../../agent/tool';
+import { ToolAccesses } from '../../../loop/tool-access';
+import type { ExecutableToolResult, ToolExecution } from '../../../loop/types';
+import { renderPrompt } from '../../../utils/render-prompt';
+import { resolvePathAccessPath } from '../../policies/path-access';
+import { MEDIA_SNIFF_BYTES, detectFileType } from '../../support/file-type';
+import { toInputJsonSchema } from '../../support/input-schema';
+import type { WorkspaceConfig } from '../../support/workspace';
+import { makeCarriageReturnsVisible, type LineEndingStyle } from './line-endings';
+import readDescriptionTemplate from './read.md';
+
+export const MAX_LINES: number = 1000;
+export const MAX_LINE_LENGTH: number = 2000;
+export const MAX_BYTES: number = 100 * 1024;
+const S_IFMT = 0o170000;
+const S_IFREG = 0o100000;
+
+const PositiveLineOffsetSchema = z.number().int().min(1);
+const TailLineOffsetSchema = z.number().int().min(-MAX_LINES).max(-1);
+
+export const ReadInputSchema = z.object({
+  path: z
+    .string()
+    .describe(
+      'Path to a text file. Relative paths resolve against the working directory; a path outside the working directory must be absolute. Directories are not supported; use `ls` via Bash for a known directory, or Glob for pattern search.',
+    ),
+  line_offset: z
+    .union([PositiveLineOffsetSchema, TailLineOffsetSchema])
+    .optional()
+    .describe(
+      `The line number to start reading from. Omit to start at line 1. Negative values read from the end of the file; the absolute value cannot exceed ${String(MAX_LINES)}.`,
+    ),
+  n_lines: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe(
+      `The number of lines to read; the tool also applies its internal cap. Omit to read up to the internal cap of ${String(MAX_LINES)} lines.`,
+    ),
+});
+
+export const ReadOutputSchema = z.object({
+  content: z.string(),
+  lineCount: z.number().int().nonnegative(),
+});
+
+export type ReadInput = z.Infer<typeof ReadInputSchema>;
+export type ReadOutput = z.Infer<typeof ReadOutputSchema>;
+
+interface LineEndingFlags {
+  hasCrLf: boolean;
+  hasLf: boolean;
+  hasLoneCr: boolean;
+}
+
+interface ReadLineEntry {
+  readonly lineNo: number;
+  readonly rawContent: string;
+}
+
+interface RenderedLine {
+  readonly line: string;
+  readonly wasTruncated: boolean;
+}
+
+interface FinishReadResultInput {
+  readonly renderedLines: readonly string[];
+  readonly truncatedLineNumbers: readonly number[];
+  readonly maxLinesReached: boolean;
+  readonly maxBytesReached: boolean;
+  readonly lineEndingStyle: LineEndingStyle;
+  readonly startLine: number;
+  readonly totalLines: number;
+  readonly requestedLines: number;
+}
+
+function truncateLine(line: string, maxLength: number): string {
+  if (line.length <= maxLength) return line;
+  const marker = '...';
+  const target = Math.max(maxLength, marker.length);
+  return line.slice(0, target - marker.length) + marker;
+}
+
+function stripTrailingLf(line: string): string {
+  return line.endsWith('\n') ? line.slice(0, -1) : line;
+}
+
+function updateLineEndingFlags(flags: LineEndingFlags, text: string): void {
+  for (let i = 0; i < text.length; i += 1) {
+    const code = text.codePointAt(i);
+    if (code === 13) {
+      if (text.codePointAt(i + 1) === 10) {
+        flags.hasCrLf = true;
+        i += 1;
+      } else {
+        flags.hasLoneCr = true;
+      }
+    } else if (code === 10) {
+      flags.hasLf = true;
+    }
+  }
+}
+
+function lineEndingStyleFromFlags(flags: LineEndingFlags): LineEndingStyle {
+  if (flags.hasLoneCr || (flags.hasCrLf && flags.hasLf)) return 'mixed';
+  if (flags.hasCrLf) return 'crlf';
+  return 'lf';
+}
+
+function renderLine(entry: ReadLineEntry, lineEndingStyle: LineEndingStyle): RenderedLine {
+  const modelContent =
+    lineEndingStyle === 'crlf' && entry.rawContent.endsWith('\r')
+      ? entry.rawContent.slice(0, -1)
+      : entry.rawContent;
+  const truncated = truncateLine(modelContent, MAX_LINE_LENGTH);
+  const renderedContent =
+    lineEndingStyle === 'mixed' ? makeCarriageReturnsVisible(truncated) : truncated;
+  return {
+    line: `${String(entry.lineNo)}\t${renderedContent}`,
+    wasTruncated: truncated !== modelContent,
+  };
+}
+
+function renderedLineBytes(renderedLine: string, isFirst: boolean): number {
+  return (isFirst ? 0 : 1) + Buffer.byteLength(renderedLine, 'utf8');
+}
+
+function isRegularFileMode(stMode: number): boolean {
+  return (stMode & S_IFMT) === S_IFREG;
+}
+
+function isFileNotFoundError(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+  const code = (error as { code?: unknown })['code'];
+  return code === 'ENOENT' || code === 'ENOTDIR';
+}
+
+function isTextDecodeError(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+  const code = (error as { code?: unknown })['code'];
+  if (code === 'ERR_ENCODING_INVALID_ENCODED_DATA') return true;
+  if (!(error instanceof Error)) return false;
+  return /encoded data was not valid|invalid.*encoding|invalid.*utf-?8/i.test(error.message);
+}
+
+function containsNulByte(text: string): boolean {
+  return text.includes('\u0000');
+}
+
+function notReadableFileOutput(path: string): string {
+  return (
+    `"${path}" is not readable as UTF-8 text. ` +
+    'If it is an image or video, use ReadMediaFile. ' +
+    'For other binary formats, use Bash or an MCP tool if available.'
+  );
+}
+
+const READ_DESCRIPTION = renderPrompt(readDescriptionTemplate, {
+  MAX_LINES,
+  MAX_BYTES_KB: MAX_BYTES / 1024,
+  MAX_LINE_LENGTH,
+});
+
+export class ReadTool implements BuiltinTool<ReadInput> {
+  readonly name = 'Read' as const;
+  readonly description = READ_DESCRIPTION;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(ReadInputSchema);
+  constructor(
+    private readonly kaos: Kaos,
+    private readonly workspace: WorkspaceConfig,
+  ) {}
+
+  resolveExecution(args: ReadInput): ToolExecution {
+    const path = resolvePathAccessPath(args.path, {
+      kaos: this.kaos,
+      workspace: this.workspace,
+      operation: 'read',
+    });
+    return {
+      accesses: ToolAccesses.readFile(path),
+      description: `Reading ${args.path}`,
+      execute: () => this.execution(args, path),
+    };
+  }
+
+  private async execution(args: ReadInput, safePath: string): Promise<ExecutableToolResult> {
+    try {
+      let stat: StatResult;
+      try {
+        stat = await this.kaos.stat(safePath);
+      } catch (error) {
+        if (isFileNotFoundError(error)) {
+          return { isError: true, output: `"${args.path}" does not exist.` };
+        }
+        throw error;
+      }
+      if (!isRegularFileMode(stat.stMode)) {
+        return { isError: true, output: `"${args.path}" is not a file.` };
+      }
+
+      const header = await this.kaos.readBytes(safePath, MEDIA_SNIFF_BYTES);
+      const fileType = detectFileType(safePath, header);
+      if (fileType.kind === 'image' || fileType.kind === 'video') {
+        return {
+          isError: true,
+          output: `"${args.path}" is a ${fileType.kind} file. Use ReadMediaFile to read image or video files.`,
+        };
+      }
+      if (fileType.kind === 'unknown') {
+        return {
+          isError: true,
+          output: notReadableFileOutput(args.path),
+        };
+      }
+
+      const lineOffset = args.line_offset ?? 1;
+      const requestedLines = args.n_lines ?? MAX_LINES;
+      const effectiveLimit = Math.min(requestedLines, MAX_LINES);
+
+      if (lineOffset < 0) {
+        return await this.readTail(
+          safePath,
+          args.path,
+          lineOffset,
+          effectiveLimit,
+          requestedLines,
+        );
+      }
+      return await this.readForward(
+        safePath,
+        args.path,
+        lineOffset,
+        effectiveLimit,
+        requestedLines,
+      );
+    } catch (error) {
+      if (isTextDecodeError(error)) {
+        return { isError: true, output: notReadableFileOutput(args.path) };
+      }
+      return {
+        isError: true,
+        output: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  private async readForward(
+    safePath: string,
+    displayPath: string,
+    lineOffset: number,
+    effectiveLimit: number,
+    requestedLines: number,
+  ): Promise<ExecutableToolResult> {
+    const selectedEntries: ReadLineEntry[] = [];
+    const flags: LineEndingFlags = { hasCrLf: false, hasLf: false, hasLoneCr: false };
+    let currentLineNo = 0;
+    let maxLinesReached = false;
+    let collectionClosed = false;
+
+    for await (const rawLine of this.kaos.readLines(safePath, { errors: 'strict' })) {
+      if (containsNulByte(rawLine)) {
+        return { isError: true, output: notReadableFileOutput(displayPath) };
+      }
+      currentLineNo += 1;
+      updateLineEndingFlags(flags, rawLine);
+      if (collectionClosed) {
+        if (effectiveLimit >= MAX_LINES && currentLineNo >= lineOffset) {
+          maxLinesReached = true;
+        }
+        continue;
+      }
+      if (currentLineNo < lineOffset) continue;
+      if (selectedEntries.length >= effectiveLimit) {
+        if (effectiveLimit >= MAX_LINES) {
+          maxLinesReached = true;
+        }
+        collectionClosed = true;
+        continue;
+      }
+      selectedEntries.push({
+        lineNo: currentLineNo,
+        rawContent: stripTrailingLf(rawLine),
+      });
+      if (selectedEntries.length >= effectiveLimit) {
+        collectionClosed = true;
+      }
+    }
+
+    const lineEndingStyle = lineEndingStyleFromFlags(flags);
+    const renderedLines: string[] = [];
+    const truncatedLineNumbers: number[] = [];
+    let bytes = 0;
+    let maxBytesReached = false;
+
+    for (const entry of selectedEntries) {
+      const rendered = renderLine(entry, lineEndingStyle);
+      const lineBytes = renderedLineBytes(rendered.line, renderedLines.length === 0);
+      if (renderedLines.length > 0 && bytes + lineBytes > MAX_BYTES) {
+        maxBytesReached = true;
+        break;
+      }
+
+      if (rendered.wasTruncated) {
+        truncatedLineNumbers.push(entry.lineNo);
+      }
+      renderedLines.push(rendered.line);
+      bytes += lineBytes;
+      if (bytes >= MAX_BYTES) {
+        maxBytesReached = true;
+        break;
+      }
+    }
+
+    return this.finishReadResult({
+      renderedLines,
+      truncatedLineNumbers,
+      maxLinesReached,
+      maxBytesReached,
+      lineEndingStyle,
+      startLine: renderedLines.length > 0 ? lineOffset : 0,
+      totalLines: currentLineNo,
+      requestedLines,
+    });
+  }
+
+  private async readTail(
+    safePath: string,
+    displayPath: string,
+    lineOffset: number,
+    effectiveLimit: number,
+    requestedLines: number,
+  ): Promise<ExecutableToolResult> {
+    const tailCount = Math.abs(lineOffset);
+    const entries: ReadLineEntry[] = [];
+    const flags: LineEndingFlags = { hasCrLf: false, hasLf: false, hasLoneCr: false };
+    let currentLineNo = 0;
+
+    for await (const rawLine of this.kaos.readLines(safePath, { errors: 'strict' })) {
+      if (containsNulByte(rawLine)) {
+        return { isError: true, output: notReadableFileOutput(displayPath) };
+      }
+      currentLineNo += 1;
+      updateLineEndingFlags(flags, rawLine);
+      entries.push({
+        lineNo: currentLineNo,
+        rawContent: stripTrailingLf(rawLine),
+      });
+      if (entries.length > tailCount) {
+        entries.shift();
+      }
+    }
+
+    const lineEndingStyle = lineEndingStyleFromFlags(flags);
+    let renderedCandidates = entries.slice(0, effectiveLimit).map((entry) => {
+      return { entry, rendered: renderLine(entry, lineEndingStyle) };
+    });
+
+    let totalBytes = 0;
+    for (const [index, candidate] of renderedCandidates.entries()) {
+      totalBytes += renderedLineBytes(candidate.rendered.line, index === 0);
+    }
+
+    let maxBytesReached = false;
+    if (totalBytes > MAX_BYTES) {
+      maxBytesReached = true;
+      const kept: typeof renderedCandidates = [];
+      let bytes = 0;
+      for (let i = renderedCandidates.length - 1; i >= 0; i -= 1) {
+        const candidate = renderedCandidates[i];
+        if (candidate === undefined) continue;
+        const lineBytes = renderedLineBytes(candidate.rendered.line, kept.length === 0);
+        if (bytes + lineBytes > MAX_BYTES) break;
+        kept.unshift(candidate);
+        bytes += lineBytes;
+      }
+      renderedCandidates = kept;
+    }
+
+    const renderedLines: string[] = [];
+    const truncatedLineNumbers: number[] = [];
+    for (const candidate of renderedCandidates) {
+      renderedLines.push(candidate.rendered.line);
+      if (candidate.rendered.wasTruncated) {
+        truncatedLineNumbers.push(candidate.entry.lineNo);
+      }
+    }
+
+    return this.finishReadResult({
+      renderedLines,
+      truncatedLineNumbers,
+      maxLinesReached: false,
+      maxBytesReached,
+      lineEndingStyle,
+      startLine: renderedCandidates[0]?.entry.lineNo ?? 0,
+      totalLines: currentLineNo,
+      requestedLines,
+    });
+  }
+
+  private finishReadResult(input: FinishReadResultInput): ExecutableToolResult {
+    return {
+      output: this.finishOutput(input.renderedLines, this.finishMessage(input)),
+    };
+  }
+
+  private finishOutput(renderedLines: readonly string[], message: string): string {
+    const rendered = renderedLines.join('\n');
+    const status = `<system>${message}</system>`;
+    return rendered.length > 0 ? `${rendered}\n${status}` : status;
+  }
+
+  private finishMessage(input: FinishReadResultInput): string {
+    const lineCount = input.renderedLines.length;
+    const lineWord = lineCount === 1 ? 'line' : 'lines';
+    const parts =
+      lineCount > 0
+        ? [
+            `${String(lineCount)} ${lineWord} read from file starting from line ${String(input.startLine)}.`,
+          ]
+        : ['No lines read from file.'];
+
+    parts.push(`Total lines in file: ${String(input.totalLines)}.`);
+    if (input.maxLinesReached) {
+      parts.push(`Max ${String(MAX_LINES)} lines reached.`);
+    } else if (input.maxBytesReached) {
+      parts.push(`Max ${String(MAX_BYTES)} bytes reached.`);
+    } else if (lineCount < input.requestedLines) {
+      parts.push('End of file reached.');
+    }
+    if (input.truncatedLineNumbers.length > 0) {
+      parts.push(`Lines [${input.truncatedLineNumbers.join(', ')}] were truncated.`);
+    }
+    if (input.lineEndingStyle === 'mixed') {
+      parts.push(
+        'Mixed or lone carriage-return line endings are shown as \\r. Use exact \\r\\n or \\r escapes in Edit.old_string for those lines.',
+      );
+    }
+    return parts.join(' ');
+  }
+}
diff --git a/packages/agent-core/src/tools/builtin/file/write.md b/packages/agent-core/src/tools/builtin/file/write.md
new file mode 100644
index 000000000..5d82cd148
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/file/write.md
@@ -0,0 +1 @@
+Overwrite or append to a file with content exactly as provided, creating the file if needed; the parent directory must already exist. Defaults to overwrite; append adds content to the end without adding a newline. Write does not use the Read/Edit model text view and does not preserve or infer the previous line-ending style: \n stays LF, \r\n stays CRLF. Use Edit for targeted changes to existing files. When the content is very large, you can split it across multiple calls: write the first chunk with overwrite, then add the remaining chunks with append.
diff --git a/packages/agent-core/src/tools/builtin/file/write.ts b/packages/agent-core/src/tools/builtin/file/write.ts
new file mode 100644
index 000000000..593980070
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/file/write.ts
@@ -0,0 +1,144 @@
+/**
+ * WriteTool — overwrite or append to a file.
+ *
+ * Creates the file if it does not exist; parent directory must already exist.
+ * Path access policy is resolved before any Kaos I/O.
+ */
+
+import type { Kaos } from '@moonshot-ai/kaos';
+import * as posixPath from 'node:path/posix';
+import * as win32Path from 'node:path/win32';
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../../agent/tool';
+import { ToolAccesses } from '../../../loop/tool-access';
+import type { ExecutableToolResult, ToolExecution } from '../../../loop/types';
+import {
+  type PathClass,
+  resolvePathAccessPath,
+} from '../../policies/path-access';
+import { toInputJsonSchema } from '../../support/input-schema';
+import type { WorkspaceConfig } from '../../support/workspace';
+import WRITE_DESCRIPTION from './write.md';
+
+/** Mask isolating the file-type bits of a stat mode. */
+const S_IFMT = 0o170000;
+/** File-type bits of a directory. */
+const S_IFDIR = 0o040000;
+
+function pathMod(pathClass: PathClass): typeof posixPath {
+  return pathClass === 'win32' ? win32Path : posixPath;
+}
+
+export const WriteInputSchema = z.object({
+  path: z
+    .string()
+    .describe(
+      'Path to the file to create, append to, or completely overwrite. Relative paths resolve against the working directory; a path outside the working directory must be absolute. The parent directory must already exist.',
+    ),
+  content: z
+    .string()
+    .describe(
+      'Raw full file content to write exactly as provided. This does not use the Read/Edit text view.',
+    ),
+  mode: z
+    .enum(['overwrite', 'append'])
+    .optional()
+    .describe(
+      'Write mode. Defaults to overwrite. append adds content to the end exactly as provided and does not add a newline.',
+    ),
+});
+
+export const WriteOutputSchema = z.object({
+  /** Number of UTF-8 bytes written to disk by this call. */
+  bytesWritten: z.number().int().nonnegative(),
+});
+
+export type WriteInput = z.Infer<typeof WriteInputSchema>;
+export type WriteOutput = z.Infer<typeof WriteOutputSchema>;
+
+export class WriteTool implements BuiltinTool<WriteInput> {
+  readonly name = 'Write' as const;
+  readonly description = WRITE_DESCRIPTION;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(WriteInputSchema);
+
+  constructor(
+    private readonly kaos: Kaos,
+    private readonly workspace: WorkspaceConfig,
+  ) {}
+
+  resolveExecution(args: WriteInput): ToolExecution {
+    const path = resolvePathAccessPath(args.path, {
+      kaos: this.kaos,
+      workspace: this.workspace,
+      operation: 'write',
+    });
+    return {
+      accesses: ToolAccesses.writeFile(path),
+      description: `Writing ${args.path}`,
+      execute: () => this.execution(args, path),
+    };
+  }
+
+  private async execution(args: WriteInput, safePath: string): Promise<ExecutableToolResult> {
+    const parentError = await this.checkParentDirectory(safePath);
+    if (parentError !== undefined) {
+      return { isError: true, output: parentError };
+    }
+
+    try {
+      const mode = args.mode ?? 'overwrite';
+      if (mode === 'append') {
+        await this.kaos.writeText(safePath, args.content, { mode: 'a' });
+      } else {
+        await this.kaos.writeText(safePath, args.content);
+      }
+      // Report the number of UTF-8 bytes this call wrote to disk. The string
+      // length would only equal the byte count for pure ASCII content, so it
+      // is not used here.
+      const bytesWritten = Buffer.byteLength(args.content, 'utf8');
+      return {
+        output: `${mode === 'append' ? 'Appended' : 'Wrote'} ${String(bytesWritten)} bytes to ${args.path}`,
+      };
+    } catch (error) {
+      const code = (error as { code?: unknown } | null)?.code;
+      if (code === 'ENOENT') {
+        return {
+          isError: true,
+          output: `Failed to write ${args.path}: parent directory does not exist.`,
+        };
+      }
+      return {
+        isError: true,
+        output: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  /**
+   * Best-effort check that the parent directory exists and is a directory.
+   *
+   * The path schema documents this precondition; probing it up front turns a
+   * bare `ENOENT` from the underlying write into an actionable message.
+   * Returns an error string when the precondition is definitively violated,
+   * or `undefined` otherwise. Any other `stat` failure (permissions, an
+   * environment without `stat`) is treated as inconclusive: the check is
+   * skipped and the write proceeds, surfacing the real I/O error if any.
+   */
+  private async checkParentDirectory(safePath: string): Promise<string | undefined> {
+    const parent = pathMod(this.kaos.pathClass()).dirname(safePath);
+    let stat;
+    try {
+      stat = await this.kaos.stat(parent);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return `Parent directory does not exist: ${parent}. Create it before writing this file.`;
+      }
+      return undefined;
+    }
+    if ((stat.stMode & S_IFMT) !== S_IFDIR) {
+      return `Parent path is not a directory: ${parent}.`;
+    }
+    return undefined;
+  }
+}
diff --git a/packages/agent-core/src/tools/builtin/index.ts b/packages/agent-core/src/tools/builtin/index.ts
new file mode 100644
index 000000000..046d47557
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/index.ts
@@ -0,0 +1,19 @@
+export * from '../background/manager';
+export * from '../background/task-list';
+export * from '../background/task-output';
+export * from '../background/task-stop';
+export * from './collaboration/agent';
+export * from './collaboration/ask-user';
+export * from './collaboration/skill-tool';
+export * from './file/edit';
+export * from './file/glob';
+export * from './file/grep';
+export * from './file/read';
+export * from './file/read-media';
+export * from './file/write';
+export * from './planning/enter-plan-mode';
+export * from './planning/exit-plan-mode';
+export * from './shell/bash';
+export * from './state/todo-list';
+export * from './web/fetch-url';
+export * from './web/web-search';
diff --git a/packages/agent-core/src/tools/builtin/planning/enter-plan-mode.md b/packages/agent-core/src/tools/builtin/planning/enter-plan-mode.md
new file mode 100644
index 000000000..d792e71b7
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/planning/enter-plan-mode.md
@@ -0,0 +1,32 @@
+Use this tool proactively when you're about to start a non-trivial implementation task.
+Getting user sign-off on your approach via ExitPlanMode before writing code prevents wasted effort.
+
+Use it when ANY of these conditions apply:
+
+1. New Feature Implementation - e.g. "Add a caching layer to the API"
+2. Multiple Valid Approaches - e.g. "Optimize database queries" (indexing vs rewrite vs caching)
+3. Code Modifications - e.g. "Refactor auth module to support OAuth"
+4. Architectural Decisions - e.g. "Add WebSocket support"
+5. Multi-File Changes - involves more than 2-3 files
+6. Unclear Requirements - need exploration to understand scope
+7. User Preferences Matter - if user input would materially change the implementation approach, use EnterPlanMode to structure the decision
+
+Permission mode notes:
+- EnterPlanMode enters plan mode automatically without an approval prompt in all permission modes.
+- In yolo and manual modes, ExitPlanMode still presents the plan to the user for approval.
+- In auto permission mode, do not use AskUserQuestion; make the best decision from available context.
+- In auto permission mode, ExitPlanMode exits plan mode without asking the user.
+- Use EnterPlanMode only when planning itself adds value.
+
+When NOT to use:
+- Single-line or few-line fixes (typos, obvious bugs, small tweaks)
+- User gave very specific, detailed instructions
+- Pure research/exploration tasks
+
+## What Happens in Plan Mode
+In plan mode, you will:
+1. Identify 2-3 key questions about the codebase that are critical to your plan. If you are not confident about the codebase structure or relevant code paths, use `Agent(subagent_type="explore")` to investigate these questions first - this is strongly recommended for non-trivial tasks.
+2. Explore the codebase using Glob, Grep, Read, and other read-only tools for any remaining quick lookups. Use Bash only when needed; Bash follows the normal permission mode and rules.
+3. Design an implementation approach based on your findings
+4. Write your plan to the current plan file with Write or Edit
+5. Present your plan to the user via ExitPlanMode for approval
diff --git a/packages/agent-core/src/tools/builtin/planning/enter-plan-mode.ts b/packages/agent-core/src/tools/builtin/planning/enter-plan-mode.ts
new file mode 100644
index 000000000..b15b78c6c
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/planning/enter-plan-mode.ts
@@ -0,0 +1,82 @@
+/**
+ * EnterPlanModeTool — plan-mode entry tool.
+ *
+ * The LLM calls this tool to enter plan mode directly. Entering plan mode
+ * does not require approval in any permission mode.
+ */
+
+
+import type { Agent } from '#/agent';
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../../agent/tool';
+import type { ToolExecution } from '../../../loop/types';
+import { toInputJsonSchema } from '../../support/input-schema';
+import DESCRIPTION from './enter-plan-mode.md';
+
+// ── Input schema ─────────────────────────────────────────────────────
+
+export const EnterPlanModeInputSchema = z.object({}).strict();
+export type EnterPlanModeInput = z.infer<typeof EnterPlanModeInputSchema>;
+
+export class EnterPlanModeTool implements BuiltinTool<EnterPlanModeInput> {
+  readonly name = 'EnterPlanMode' as const;
+  readonly description: string = DESCRIPTION;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(EnterPlanModeInputSchema);
+
+  constructor(private readonly agent: Agent) {}
+
+  resolveExecution(_args: EnterPlanModeInput): ToolExecution {
+    return {
+      description: 'Requesting to enter plan mode',
+      execute: async () => {
+        // Guard: already in plan mode
+        if (this.agent.planMode.isActive) {
+          return {
+            isError: true,
+            output: 'Plan mode is already active. Use ExitPlanMode when the plan is ready.',
+          };
+        }
+
+        try {
+          await this.agent.planMode.enter();
+        } catch (error) {
+          const message = error instanceof Error ? error.message : 'Failed to enter plan mode.';
+          return { isError: true, output: `Failed to enter plan mode: ${message}` };
+        }
+
+        this.agent.telemetry.track('plan_enter_resolved', { outcome: 'auto_approved' });
+        return { output: enteredPlanModeMessage(this.agent.planMode.planFilePath) };
+      },
+    };
+  }
+}
+
+function enteredPlanModeMessage(planPath: string | null): string {
+  if (planPath === null) {
+    return [
+      'Plan mode is now active. Your workflow:',
+      '',
+      '1. Use read-only tools (Read, Grep, Glob) to investigate the codebase. Use Bash only when needed.',
+      '2. Design a concrete, step-by-step plan.',
+      '3. Wait for the host to provide a plan file path before calling ExitPlanMode.',
+      '',
+      'Do NOT use Write or Edit while plan mode is active in this host; no plan file path is available.',
+      'Use Bash only when needed; Bash follows the normal permission mode and rules.',
+    ].join('\n');
+  }
+
+  return [
+    'Plan mode is now active. Your workflow:',
+    '',
+    `Plan file: ${planPath}`,
+    '',
+    '1. Use read-only tools (Read, Grep, Glob) to investigate the codebase. Use Bash only when needed.',
+    '2. Design a concrete, step-by-step plan.',
+    '3. Write the plan to the plan file with Write or Edit.',
+    '4. When the plan is ready, call ExitPlanMode for user approval.',
+    '',
+    'Do NOT edit files other than the plan file while plan mode is active.',
+    'Use Bash only when needed; Bash follows the normal permission mode and rules.',
+  ].join('\n');
+}
diff --git a/packages/agent-core/src/tools/builtin/planning/exit-plan-mode.md b/packages/agent-core/src/tools/builtin/planning/exit-plan-mode.md
new file mode 100644
index 000000000..b83f47f38
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/planning/exit-plan-mode.md
@@ -0,0 +1,29 @@
+Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.
+
+## How This Tool Works
+- You should have already written your plan to the plan file specified in the plan mode reminder.
+- This tool does NOT take the plan content as a parameter - it reads the plan from the file you wrote.
+- The user will see the contents of your plan file when they review it. In auto permission mode, the tool reads the file and exits plan mode without asking the user.
+
+## When to Use
+Only use this tool for tasks that require planning implementation steps. For research tasks (searching files, reading code, understanding the codebase), do NOT use this tool.
+
+## Multiple Approaches
+If your plan contains multiple alternative approaches:
+- Pass them via the `options` parameter so the user can choose which approach to execute.
+- Each option should have a concise label and a brief description of trade-offs.
+- If you recommend one option, append "(Recommended)" to its label.
+- In yolo and manual modes, the user will see all options alongside Reject and Revise choices.
+- Provide up to 3 options; the host adds the standard rejection and revision controls. When the plan offers a real choice, 2-3 distinct approaches work best.
+- Passing a single option is allowed and is equivalent to a plain plan approval (no approach choice is surfaced to the user).
+- Do NOT use "Reject", "Reject and Exit", "Revise", or "Approve" as option labels - these are reserved by the system.
+
+## Before Using
+- In auto permission mode, do NOT use AskUserQuestion; make the best decision from available context.
+- In auto permission mode, this tool exits plan mode without asking the user.
+- In yolo and manual modes, this tool still presents the plan to the user for approval.
+- If auto permission mode is not active and you have unresolved questions, use AskUserQuestion first.
+- If auto permission mode is not active and you have multiple approaches and haven't narrowed down yet, consider using AskUserQuestion first to let the user choose, then write a plan for the chosen approach only.
+- Once your plan is finalized, use THIS tool to request approval.
+- Do NOT use AskUserQuestion to ask "Is this plan OK?" or "Should I proceed?" - that is exactly what ExitPlanMode does.
+- If rejected, revise based on feedback and call ExitPlanMode again.
diff --git a/packages/agent-core/src/tools/builtin/planning/exit-plan-mode.ts b/packages/agent-core/src/tools/builtin/planning/exit-plan-mode.ts
new file mode 100644
index 000000000..32a0983bb
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/planning/exit-plan-mode.ts
@@ -0,0 +1,242 @@
+/**
+ * ExitPlanModeTool — plan-mode exit tool.
+ *
+ * The LLM calls this tool to surface a finalised plan to the user and
+ * exit plan mode. The plan must already be written to the current plan
+ * file; this tool reads that file and flips plan mode off. PermissionManager
+ * handles plan approval before this tool runs and passes any selected option
+ * through execution metadata.
+ */
+
+import type { Agent } from '#/agent';
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../../agent/tool';
+import type { ExecutableToolContext, ExecutableToolResult, ToolExecution } from '../../../loop/types';
+import { toInputJsonSchema } from '../../support/input-schema';
+import DESCRIPTION from './exit-plan-mode.md';
+
+// ── Input schema ─────────────────────────────────────────────────────
+
+/**
+ * User-selectable option surfaced at plan approval time. The LLM supplies
+ * up to 3 of these when the plan contains multiple approaches; the host's
+ * ApprovalRuntime presents them to the user and returns the chosen `label`
+ * (or `{kind:'revise', feedback}` when the user asks for revisions).
+ */
+export interface ExitPlanModeOption {
+  label: string;
+  description: string;
+}
+
+export interface ExitPlanModeInput {
+  options?: readonly ExitPlanModeOption[] | undefined;
+}
+
+const RESERVED_OPTION_LABELS = new Set(
+  ['Approve', 'Reject', 'Reject and Exit', 'Revise'].map(normalizeOptionLabel),
+);
+
+const ExitPlanModeOptionSchema = z
+  .object({
+    label: z
+      .string()
+      .min(1)
+      .max(80)
+      .describe(
+        'Short name for this option (1-8 words). Append "(Recommended)" if you recommend this option.',
+      ),
+    description: z
+      .string()
+      .default('')
+      .describe('Brief summary of this approach and its trade-offs.'),
+  })
+  .strict();
+
+export const ExitPlanModeInputSchema: z.ZodType<ExitPlanModeInput> = z
+  .object({
+    options: z
+      .array(ExitPlanModeOptionSchema)
+      .min(1)
+      .max(3)
+      .refine(hasUniqueOptionLabels, 'Option labels must be unique.')
+      .refine(hasNoReservedOptionLabels, 'Option labels must not use reserved approval labels.')
+      .optional()
+      .describe(
+        'When the plan contains multiple alternative approaches, list them here so the user can choose which one to execute. Provide up to 3 options; 2-3 distinct approaches work best when the plan offers a real choice. Passing a single option is allowed and is equivalent to a plain plan approval. Each option represents a distinct approach from the plan. Do not use "Reject", "Revise", "Approve", or "Reject and Exit" as labels.',
+      ),
+  })
+  .strict();
+
+export interface ExitPlanModePlanSource {
+  plan: string;
+  path?: string | undefined;
+}
+
+type ResolvePlanResult =
+  | { readonly ok: true; readonly plan: string; readonly path?: string | undefined }
+  | { readonly ok: false; readonly error: ExecutableToolResult };
+
+// ── Implementation ───────────────────────────────────────────────────
+
+export class ExitPlanModeTool implements BuiltinTool<ExitPlanModeInput> {
+  readonly name = 'ExitPlanMode' as const;
+  readonly description: string = DESCRIPTION;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(ExitPlanModeInputSchema);
+
+  constructor(private readonly agent: Agent) {}
+
+  resolveExecution(args: ExitPlanModeInput): ToolExecution {
+    return {
+      description: 'Presenting plan and exiting plan mode',
+      execute: (ctx) => this.execution(args, ctx),
+    };
+  }
+
+  private async execution(
+    args: ExitPlanModeInput,
+    {
+    metadata,
+    }: ExecutableToolContext,
+  ): Promise<ExecutableToolResult> {
+    if (!this.agent.planMode.isActive) {
+      return {
+        isError: true,
+        output:
+          'ExitPlanMode can only be called while plan mode is active. Use EnterPlanMode (or /plan) first.',
+      };
+    }
+
+    const resolvedPlan = await this.resolvePlan();
+    if (!resolvedPlan.ok) return resolvedPlan.error;
+
+    if (!planTelemetryWasSubmitted(metadata)) {
+      this.agent.telemetry.track('plan_submitted', {
+        has_options: args.options !== undefined && args.options.length >= 2,
+      });
+    }
+    return this.exitWithPlan(
+      resolvedPlan.plan,
+      resolvedPlan.path,
+      selectedOptionFromMetadata(metadata),
+      planTelemetryWasResolved(metadata),
+    );
+  }
+
+  private async exitWithPlan(
+    plan: string,
+    path: string | undefined,
+    option: ExitPlanModeOption | undefined = undefined,
+    telemetryResolved = false,
+  ): Promise<ExecutableToolResult> {
+    const failed = this.exitPlanMode();
+    if (failed !== undefined) return failed;
+
+    if (!telemetryResolved) {
+      this.agent.telemetry.track('plan_resolved', { outcome: 'auto_approved' });
+    }
+    const optionPrefix =
+      option === undefined
+        ? ''
+        : `Selected approach: ${option.label}\nExecute ONLY the selected approach. Do not execute any unselected alternatives.\n\n`;
+    return {
+      isError: false,
+      output: `Exited plan mode. ${optionPrefix}${formatPlanForOutput(plan, path)}`,
+    };
+  }
+
+  private exitPlanMode(): ExecutableToolResult | undefined {
+    try {
+      this.agent.planMode.exit();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Failed to exit plan mode.';
+      return {
+        isError: true,
+        output: `Failed to exit plan mode: ${message}`,
+      };
+    }
+  }
+
+  private async resolvePlan(): Promise<ResolvePlanResult> {
+    let source: ExitPlanModePlanSource | null;
+    try {
+      const data = await this.agent.planMode.data();
+      source = data === null ? null : { plan: data.content, path: data.path };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Failed to read plan file.';
+      return {
+        ok: false,
+        error: { isError: true, output: `Failed to read plan file: ${message}` },
+      };
+    }
+
+    if (source !== null && source.plan.trim().length > 0) {
+      return {
+        ok: true,
+        plan: source.plan,
+        path: source.path,
+      };
+    }
+
+    const path = source?.path ?? this.agent.planMode.planFilePath;
+    return {
+      ok: false,
+      error: {
+        isError: true,
+        output:
+          path === null
+            ? 'No plan file found. Write the plan to the current plan file first, then call ExitPlanMode.'
+            : `No plan file found. Write your plan to ${path} first, then call ExitPlanMode.`,
+      },
+    };
+  }
+}
+
+function hasUniqueOptionLabels(options: readonly ExitPlanModeOption[]): boolean {
+  const labels = new Set<string>();
+  for (const option of options) {
+    const label = normalizeOptionLabel(option.label);
+    if (labels.has(label)) return false;
+    labels.add(label);
+  }
+  return true;
+}
+
+function hasNoReservedOptionLabels(options: readonly ExitPlanModeOption[]): boolean {
+  return options.every((option) => !RESERVED_OPTION_LABELS.has(normalizeOptionLabel(option.label)));
+}
+
+function normalizeOptionLabel(label: string): string {
+  return label.trim().toLowerCase();
+}
+
+function selectedOptionFromMetadata(metadata: unknown): ExitPlanModeOption | undefined {
+  if (metadata === null || typeof metadata !== 'object') return undefined;
+  const selectedOption = (metadata as { readonly selectedOption?: unknown }).selectedOption;
+  if (selectedOption === null || typeof selectedOption !== 'object') return undefined;
+  const label = (selectedOption as { readonly label?: unknown }).label;
+  const description = (selectedOption as { readonly description?: unknown }).description;
+  if (typeof label !== 'string' || typeof description !== 'string') return undefined;
+  return { label, description };
+}
+
+function planTelemetryWasSubmitted(metadata: unknown): boolean {
+  return (
+    metadata !== null &&
+    typeof metadata === 'object' &&
+    (metadata as { readonly planTelemetrySubmitted?: unknown }).planTelemetrySubmitted === true
+  );
+}
+
+function planTelemetryWasResolved(metadata: unknown): boolean {
+  return (
+    metadata !== null &&
+    typeof metadata === 'object' &&
+    (metadata as { readonly planTelemetryResolved?: unknown }).planTelemetryResolved === true
+  );
+}
+
+function formatPlanForOutput(plan: string, path: string | undefined): string {
+  const savedTo = path !== undefined ? `Plan saved to: ${path}\n\n` : '';
+  return `Plan mode deactivated. All tools are now available.\n${savedTo}## Approved Plan:\n${plan}`;
+}
diff --git a/packages/agent-core/src/tools/builtin/shell/bash.md b/packages/agent-core/src/tools/builtin/shell/bash.md
new file mode 100644
index 000000000..a2afff7b4
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/shell/bash.md
@@ -0,0 +1,43 @@
+Execute a `{{ SHELL_NAME }}` command. Use this for shell semantics — pipes, env, processes, git, package managers, build/test runners, anything genuinely interactive or multi-step.
+
+**Translate these to a dedicated tool instead:**
+- `cat` / `head` / `tail` (known path) → `Read`
+- `sed` / `awk` (in-place edit) → `Edit`
+- `echo > file` / `cat <<EOF` → `Write`
+- `find` / recursive `ls` to locate files by name pattern → `Glob` (plain `ls <known-directory>` is fine for listing a directory)
+- `grep` / `rg` (search file contents) → `Grep`
+- `echo` / `printf` (talk to the user) → just output text directly
+
+The dedicated tools render in the per-tool permission UI and keep raw stdout out of the conversation; that is why they are worth reaching for whenever one fits.
+
+**Output:**
+The stdout and stderr will be combined and returned as a string. The output may be truncated if it is too long. If the command failed, the output will end with a `Command failed with exit code: N` line stating the non-zero exit code.
+
+If `run_in_background=true`, the command will be started as a background task and this tool will return a task ID instead of waiting for command completion. When doing that, you must provide a short `description`. Background commands default to a {{ DEFAULT_BACKGROUND_TIMEOUT_S }}s timeout and `timeout` is capped at {{ MAX_BACKGROUND_TIMEOUT_S }}s; set `disable_timeout=true` only when the task should run without a timeout. You will be automatically notified when the task completes. Use `TaskOutput` for a non-blocking status/output snapshot, and only set `block=true` when you explicitly want to wait for completion. Use `TaskStop` only if the task must be cancelled. If a human user wants to inspect background tasks themselves, point them to the `/tasks` command, which opens an interactive panel; it has no subcommands.
+
+**Guidelines for safety and security:**
+- Each shell tool call will be executed in a fresh shell environment. The shell variables, current working directory changes, and the shell history is not preserved between calls.
+- The tool call will return after the command is finished. You shall not use this tool to execute an interactive command or a command that may run forever. For possibly long-running foreground commands, set the `timeout` argument in seconds. Foreground commands default to {{ DEFAULT_TIMEOUT_S }}s and allow up to {{ MAX_TIMEOUT_S }}s.
+- Avoid using `..` to access files or directories outside of the working directory.
+- Avoid modifying files outside of the working directory unless explicitly instructed to do so.
+- Never run commands that require superuser privileges unless explicitly instructed to do so.
+
+**Guidelines for efficiency:**
+- For multiple related commands, use `&&` to chain them in a single call, e.g. `cd /path && ls -la`
+- Use `;` to run commands sequentially regardless of success/failure
+- Use `||` for conditional execution (run second command only if first fails)
+- Use pipe operations (`|`) and redirections (`>`, `>>`) to chain input and output between commands
+- Always quote file paths containing spaces with double quotes (e.g., cd "/path with spaces/")
+- Compose multi-step logic in a single call with `if` / `case` / `for` / `while` control flows.
+- Prefer `run_in_background=true` for long-running builds, tests, watchers, or servers when you need the conversation to continue before the command finishes.
+
+**Commands available:**
+The following common command categories are usually available. Availability still depends on the host, so when in doubt run `which <command>` first to confirm a command exists before relying on it.
+- Navigation and inspection: `ls`, `pwd`, `cd`, `stat`, `file`, `du`, `df`, `tree`
+- File and directory management: `cp`, `mv`, `rm`, `mkdir`, `touch`, `ln`, `chmod`, `chown`
+- Text and data processing: `wc`, `sort`, `uniq`, `cut`, `tr`, `diff`, `xargs`
+- Archives and compression: `tar`, `gzip`, `gunzip`, `zip`, `unzip`
+- Networking and transfer: `curl`, `wget`, `ping`, `ssh`, `scp`
+- Version control: `git`
+- Process and system: `ps`, `kill`, `top`, `env`, `date`, `uname`, `whoami`
+- Language and package toolchains: `node`, `npm`, `pnpm`, `yarn`, `python`, `pip` (use whichever the project actually relies on)
diff --git a/packages/agent-core/src/tools/builtin/shell/bash.ts b/packages/agent-core/src/tools/builtin/shell/bash.ts
new file mode 100644
index 000000000..148b899d0
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/shell/bash.ts
@@ -0,0 +1,473 @@
+/**
+ * BashTool — execute shell commands.
+ *
+ * Invokes bash (POSIX) according to an injected `Environment`. On Windows
+ * the shell is Git Bash; the path is resolved by `detectEnvironment`.
+ *
+ * Dependencies injected via constructor:
+ *   - `Kaos`        — shell execution abstraction (exec / execWithEnv)
+ *   - `cwd`         — default working directory for commands
+ *   - `Environment` — cross-platform probe (shellName / shellPath)
+ *   - `BackgroundProcessManager?` — optional: required iff run_in_background=true
+ *
+ * Execution goes through Kaos, never directly via node:child_process.
+ *
+ * Hardening:
+ *   - `args.timeout` (seconds) and the ambient `signal` both drive
+ *     `Promise.race`; fire-a-kill on either edge.
+ *   - stdin is closed immediately so interactive commands (`cat`, `read`,
+ *     `python -c 'input()'`) receive EOF instead of hanging.
+ *   - Two-phase kill: SIGTERM → 5s grace → SIGKILL (Kaos honours this
+ *     contract cross-platform).
+ *   - stdout/stderr stream into ToolResultBuilder; excess is replaced with a
+ *     truncation marker so a runaway command cannot OOM the host.
+ */
+
+import type { Readable } from 'node:stream';
+import { StringDecoder } from 'node:string_decoder';
+
+import type { Kaos, KaosProcess } from '@moonshot-ai/kaos';
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../../agent/tool';
+import type { ExecutableToolResult, ToolExecution } from '../../../loop/types';
+import type { Environment } from '../../../utils/environment';
+import { renderPrompt } from '../../../utils/render-prompt';
+import type { BackgroundProcessManager } from '../../background/manager';
+import { toInputJsonSchema } from '../../support/input-schema';
+import { ToolResultBuilder } from '../../support/result-builder';
+import bashDescriptionTemplate from './bash.md';
+
+const MS_PER_SECOND = 1000;
+const DEFAULT_TIMEOUT_S = 60;
+const MAX_TIMEOUT_S = 5 * 60;
+const DEFAULT_BACKGROUND_TIMEOUT_S = 10 * 60;
+const MAX_BACKGROUND_TIMEOUT_S = 24 * 60 * 60;
+const SIGTERM_GRACE_MS = 5_000;
+
+export const BashInputSchema = z
+  .object({
+    command: z.string().min(1, 'Command cannot be empty.').describe('The command to execute.'),
+    cwd: z
+      .string()
+      .optional()
+      .describe(
+        "The working directory in which to run the command. When omitted, the command runs in the session's working directory.",
+      ),
+    timeout: z
+      .number()
+      .int()
+      .positive()
+      .default(DEFAULT_TIMEOUT_S)
+      .describe(
+        `Optional timeout in seconds for the command to execute. Foreground default ${String(DEFAULT_TIMEOUT_S)}s, max ${String(MAX_TIMEOUT_S)}s. Background default ${String(DEFAULT_BACKGROUND_TIMEOUT_S)}s, max ${String(MAX_BACKGROUND_TIMEOUT_S)}s. Ignored for background commands when disable_timeout=true.`,
+      )
+      .optional(),
+    description: z
+      .string()
+      .optional()
+      .describe(
+        'A short description for the background task. Required when run_in_background is true.',
+      ),
+    run_in_background: z
+      .boolean()
+      .optional()
+      .describe('Whether to run the command as a background task.'),
+    disable_timeout: z
+      .boolean()
+      .optional()
+      .describe(
+        'If true, do not apply a timeout to the command. Only applies when run_in_background is true.',
+      ),
+  })
+  .superRefine((val, ctx) => {
+    if (val.timeout === undefined) return;
+    const isBackground = val.run_in_background === true;
+    if (!isValidTimeoutValue(val.timeout, isBackground)) {
+      const cap = isBackground ? MAX_BACKGROUND_TIMEOUT_S : MAX_TIMEOUT_S;
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['timeout'],
+        message: `timeout must be ≤ ${String(cap)}s (${isBackground ? 'background' : 'foreground'})`,
+      });
+    }
+  });
+
+export const BashOutputSchema = z.object({
+  exitCode: z.number().int(),
+  stdout: z.string(),
+  stderr: z.string(),
+});
+
+export type BashInput = z.Infer<typeof BashInputSchema>;
+export type BashOutput = z.Infer<typeof BashOutputSchema>;
+
+const SHELL_TIMEOUT_VARS = {
+  DEFAULT_TIMEOUT_S,
+  DEFAULT_BACKGROUND_TIMEOUT_S,
+  MAX_TIMEOUT_S,
+  MAX_BACKGROUND_TIMEOUT_S,
+};
+
+function timeoutCapS(isBackground: boolean): number {
+  return isBackground ? MAX_BACKGROUND_TIMEOUT_S : MAX_TIMEOUT_S;
+}
+
+function isValidTimeoutValue(timeout: number, isBackground: boolean): boolean {
+  return timeout <= timeoutCapS(isBackground);
+}
+
+function normalizeTimeoutMs(timeout: number | undefined, isBackground: boolean): number {
+  const defaultSeconds = isBackground ? DEFAULT_BACKGROUND_TIMEOUT_S : DEFAULT_TIMEOUT_S;
+  const value = timeout ?? defaultSeconds;
+  return Math.min(value, timeoutCapS(isBackground)) * MS_PER_SECOND;
+}
+
+function renderBashDescription(shellName: string): string {
+  return renderPrompt(bashDescriptionTemplate, { ...SHELL_TIMEOUT_VARS, SHELL_NAME: shellName });
+}
+
+function withoutBackgroundDescription(description: string): string {
+  return description
+    .replace(
+      /\n\nIf `run_in_background=true`,[\s\S]*?point them to the `\/tasks` command, which opens an interactive panel; it has no subcommands\./,
+      '\n\nBackground execution is disabled for this agent. Do not set `run_in_background=true`.',
+    )
+    .replace(
+      ` For possibly long-running foreground commands, set the \`timeout\` argument in seconds. Foreground commands default to ${String(DEFAULT_TIMEOUT_S)}s and allow up to ${String(MAX_TIMEOUT_S)}s.`,
+      ` For possibly long-running commands, set the \`timeout\` argument in seconds. The default is ${String(DEFAULT_TIMEOUT_S)}s; foreground commands allow up to ${String(MAX_TIMEOUT_S)}s.`,
+    )
+    .replace(
+      /\n- Prefer `run_in_background=true`[\s\S]*?conversation to continue before the command finishes\./,
+      '\n- Do not set `run_in_background=true`; background task management tools are not available.',
+    );
+}
+
+export class BashTool implements BuiltinTool<BashInput> {
+  readonly name = 'Bash' as const;
+  readonly description: string;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(BashInputSchema);
+
+  private readonly isWindowsBash: boolean;
+
+  private readonly allowBackground: boolean;
+
+  constructor(
+    private readonly kaos: Kaos,
+    private readonly cwd: string,
+    private readonly environment: Environment,
+    private readonly backgroundManager?: BackgroundProcessManager,
+    options?: {
+      allowBackground?: boolean | undefined;
+    },
+  ) {
+    this.isWindowsBash = this.environment.osKind === 'Windows';
+    this.allowBackground = options?.allowBackground ?? this.backgroundManager !== undefined;
+    const rendered = renderBashDescription(this.environment.shellName);
+    this.description = this.allowBackground ? rendered : withoutBackgroundDescription(rendered);
+  }
+
+  resolveExecution(args: BashInput): ToolExecution {
+    const preview = args.command.length > 50 ? `${args.command.slice(0, 50)}…` : args.command;
+    return {
+      description: args.run_in_background
+        ? `Starting background: ${preview}`
+        : `Running: ${preview}`,
+      execute: ({ signal }) => this.execution(args, signal),
+    };
+  }
+
+  private spawn(effectiveCwd: string, command: string): Promise<KaosProcess> {
+    const shellCwd = this.isWindowsBash ? windowsPathToPosixPath(effectiveCwd) : effectiveCwd;
+    const shellArgs = [
+      this.environment.shellPath,
+      '-c',
+      `cd ${shellQuote(shellCwd)} && ${command}`,
+    ];
+
+    const noninteractiveEnv: Record<string, string> = {
+      NO_COLOR: '1',
+      TERM: 'dumb',
+      // Default to '0' so git fails fast on private remotes if a TTY happens
+      // to be inherited; honour an explicit ambient value when the user has
+      // set one.
+      GIT_TERMINAL_PROMPT: process.env['GIT_TERMINAL_PROMPT'] ?? '0',
+      SHELL: this.environment.shellPath,
+    };
+
+    // Merge ambient env + noninteractive knobs so tools like git / node
+    // don't open a pager and paints don't colour the stream.
+    const mergedEnv: Record<string, string> = {
+      ...(process.env as Record<string, string>),
+      ...noninteractiveEnv,
+    };
+    return this.kaos.execWithEnv(shellArgs, mergedEnv);
+  }
+
+  private async execution(args: BashInput, signal: AbortSignal): Promise<ExecutableToolResult> {
+    if (signal.aborted) {
+      return { isError: true, output: 'Aborted before command started' };
+    }
+    if (args.command.length === 0) {
+      return { isError: true, output: 'Command cannot be empty.' };
+    }
+
+    if (args.run_in_background) {
+      if (!this.allowBackground) {
+        return {
+          isError: true,
+          output:
+            'Background execution is not available for this agent because TaskOutput and TaskStop are not enabled.',
+        };
+      }
+      return this.executeInBackground(args);
+    }
+
+    const timeoutMs = normalizeTimeoutMs(args.timeout, false);
+
+    let proc: KaosProcess;
+    const command = this.isWindowsBash ? rewriteWindowsNullRedirect(args.command) : args.command;
+    try {
+      const effectiveCwd = args.cwd ?? this.cwd;
+      proc = await this.spawn(effectiveCwd, command);
+    } catch (error) {
+      return {
+        isError: true,
+        output: error instanceof Error ? error.message : String(error),
+      };
+    }
+
+    try {
+      proc.stdin.end();
+    } catch {
+      // Closing stdin on a process that has already exited is a no-op on
+      // some platforms and throws on others — either is safe to ignore.
+    }
+
+    let timedOut = false;
+    let aborted = false;
+    let killed = false;
+
+    const killProc = async (): Promise<void> => {
+      if (killed) return;
+      killed = true;
+      try {
+        await proc.kill('SIGTERM');
+      } catch {
+        /* process already gone */
+      }
+      const exited = proc
+        .wait()
+        .then(() => true)
+        .catch(() => true);
+      const raced = await Promise.race([
+        exited,
+        new Promise<false>((resolve) => {
+          setTimeout(() => {
+            resolve(false);
+          }, SIGTERM_GRACE_MS);
+        }),
+      ]);
+      if (!raced && proc.exitCode === null) {
+        try {
+          await proc.kill('SIGKILL');
+        } catch {
+          /* ignore */
+        }
+      }
+    };
+
+    const onAbort = (): void => {
+      aborted = true;
+      void killProc();
+    };
+    signal.addEventListener('abort', onAbort);
+
+    const timeoutHandle = setTimeout(() => {
+      timedOut = true;
+      void killProc();
+    }, timeoutMs);
+
+    try {
+      const builder = new ToolResultBuilder();
+      const [, exitCode] = await Promise.all([
+        Promise.all([
+          readStreamIntoBuilder(proc.stdout, builder),
+          readStreamIntoBuilder(proc.stderr, builder),
+        ]),
+        proc.wait(),
+      ]);
+
+      if (timedOut) {
+        const timeoutLabel =
+          timeoutMs % 1000 === 0 ? `${String(timeoutMs / 1000)}s` : `${String(timeoutMs)}ms`;
+        return builder.error(`Command killed by timeout (${timeoutLabel})`, {
+          brief: `Killed by timeout (${timeoutLabel})`,
+        });
+      }
+      if (aborted) {
+        return builder.error('Interrupted by user', { brief: 'Interrupted by user' });
+      }
+
+      const isError = exitCode !== 0;
+      if (isError && builder.nChars === 0) {
+        builder.write(`Process exited with code ${String(exitCode)}`);
+      }
+
+      if (!isError) {
+        return builder.ok('Command executed successfully.');
+      }
+      return builder.error(`Command failed with exit code: ${String(exitCode)}.`, {
+        brief: `Failed with exit code: ${String(exitCode)}`,
+      });
+    } catch (error) {
+      return {
+        isError: true,
+        output: error instanceof Error ? error.message : String(error),
+      };
+    } finally {
+      clearTimeout(timeoutHandle);
+      signal.removeEventListener('abort', onAbort);
+    }
+  }
+
+  private async executeInBackground(args: BashInput): Promise<ExecutableToolResult> {
+    if (!this.backgroundManager) {
+      return {
+        isError: true,
+        output: 'Background execution is not available (no BackgroundProcessManager configured).',
+      };
+    }
+    const backgroundManager = this.backgroundManager;
+
+    if (!args.description?.trim()) {
+      return {
+        isError: true,
+        output: 'description is required when run_in_background is true.',
+      };
+    }
+
+    let reservation: ReturnType<BackgroundProcessManager['reserveSlot']>;
+    try {
+      reservation = backgroundManager.reserveSlot();
+    } catch (error) {
+      return {
+        isError: true,
+        output: error instanceof Error ? error.message : String(error),
+      };
+    }
+
+    const timeoutMs = args.disable_timeout ? undefined : normalizeTimeoutMs(args.timeout, true);
+
+    let proc: KaosProcess;
+    const command = this.isWindowsBash ? rewriteWindowsNullRedirect(args.command) : args.command;
+    try {
+      const effectiveCwd = args.cwd ?? this.cwd;
+      proc = await this.spawn(effectiveCwd, command);
+    } catch (error) {
+      reservation.release();
+      return {
+        isError: true,
+        output: error instanceof Error ? error.message : String(error),
+      };
+    }
+
+    try {
+      proc.stdin.end();
+    } catch {
+      /* process already gone */
+    }
+
+    let taskId: string;
+    try {
+      taskId = backgroundManager.register(proc, command, args.description.trim(), {
+        reservation,
+        shellInfo: {
+          shellName: this.environment.shellName,
+          shellPath: this.environment.shellPath,
+          cwd: args.cwd ?? this.cwd,
+        },
+      });
+    } catch (error) {
+      reservation.release();
+      try {
+        await proc.kill('SIGTERM');
+      } catch {
+        /* process already gone */
+      }
+      return {
+        isError: true,
+        output: error instanceof Error ? error.message : String(error),
+      };
+    }
+
+    if (timeoutMs !== undefined) {
+      setTimeout(() => {
+        void (async (): Promise<void> => {
+          if (proc.exitCode !== null) {
+            await backgroundManager.settlePendingExits();
+            return;
+          }
+          const info = backgroundManager.getTask(taskId);
+          if (info && info.status === 'running') {
+            void backgroundManager.stop(taskId);
+          }
+        })();
+      }, timeoutMs);
+    }
+
+    // register() synchronously inserts taskId into the manager's Map, so
+    // this lookup in the same tick cannot return undefined.
+    const status = backgroundManager.getTask(taskId)!.status;
+    const builder = new ToolResultBuilder();
+    builder.write(
+      `task_id: ${taskId}\n` +
+        `pid: ${String(proc.pid)}\n` +
+        `description: ${args.description.trim()}\n` +
+        `status: ${status}\n` +
+        `automatic_notification: true\n` +
+        'next_step: You will be automatically notified when it completes.\n' +
+        'next_step: Use TaskOutput with this task_id for a non-blocking status/output snapshot.\n' +
+        'next_step: Use TaskStop only if the task must be cancelled.\n' +
+        'human_shell_hint: Tell the human to run /tasks to open the interactive background-task panel.',
+    );
+    return builder.ok('Background task started', { brief: `Started ${taskId}` });
+  }
+}
+
+async function readStreamIntoBuilder(
+  stream: Readable,
+  builder: ToolResultBuilder,
+): Promise<void> {
+  const decoder = new StringDecoder('utf8');
+  for await (const chunk of stream) {
+    const buf: Buffer = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : (chunk as Buffer);
+    builder.write(decoder.write(buf));
+  }
+  builder.write(decoder.end());
+}
+
+function shellQuote(s: string): string {
+  return `'${s.replaceAll("'", "'\\''")}'`;
+}
+
+function windowsPathToPosixPath(path: string): string {
+  if (path.startsWith('\\\\')) {
+    return path.replaceAll('\\', '/');
+  }
+
+  const driveMatch = /^([A-Za-z]):(?:[\\/]|$)/.exec(path);
+  if (driveMatch !== null) {
+    const drive = driveMatch[1]!.toLowerCase();
+    const rest = path.slice(2).replaceAll('\\', '/');
+    return `/${drive}${rest.startsWith('/') ? rest : `/${rest}`}`;
+  }
+
+  return path.replaceAll('\\', '/');
+}
+
+const WINDOWS_NUL_REDIRECT = /(\d?&?>+\s*)[Nn][Uu][Ll](?=\s|$|[|&;)\n])/g;
+
+function rewriteWindowsNullRedirect(command: string): string {
+  return command.replace(WINDOWS_NUL_REDIRECT, '$1/dev/null');
+}
diff --git a/packages/agent-core/src/tools/builtin/state/todo-list.md b/packages/agent-core/src/tools/builtin/state/todo-list.md
new file mode 100644
index 000000000..2e83f6026
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/state/todo-list.md
@@ -0,0 +1,22 @@
+Use this tool to maintain a structured TODO list as you work through a multi-step task. This is especially useful in plan mode and for long-running investigations.
+
+**When to use:**
+- Multi-step tasks that span several tool calls
+- Tracking investigation progress across a large codebase search
+- Planning a sequence of edits before making them
+
+**When NOT to use:**
+- Single-shot answers that complete in one or two tool calls
+- Trivial requests where tracking adds no clarity
+
+**Avoid churn:**
+- Do not re-call this tool when nothing meaningful has changed since the last call — update the list only after real progress.
+- When unsure of the current state, call query mode first (omit `todos`) to check the list before deciding what to update.
+- If no available tool can move any task forward, tell the user where you are stuck instead of repeatedly re-ordering the same todos.
+
+**How to use:**
+- Call with `todos: [...]` to replace the full list. Statuses: pending / in_progress / done.
+- Call with no arguments to retrieve the current list without changing it.
+- Call with `todos: []` to clear the list.
+- Keep titles short and actionable (e.g. "Read session-control.ts", "Add planMode flag to TurnManager").
+- Update statuses as you make progress — mark one item in_progress at a time.
\ No newline at end of file
diff --git a/packages/agent-core/src/tools/builtin/state/todo-list.ts b/packages/agent-core/src/tools/builtin/state/todo-list.ts
new file mode 100644
index 000000000..22431ff22
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/state/todo-list.ts
@@ -0,0 +1,133 @@
+/**
+ * TodoListTool — structured TODO list management tool.
+ *
+ * The LLM uses this tool to maintain a visible plan of sub-tasks during
+ * plan-mode workflows and multi-step operations. A single tool serves
+ * both reads and writes:
+ *
+ *   - `resolveExecution({ todos: [...] })` — replace the full list
+ *   - `resolveExecution({ todos: [] })`    — clear the list
+ *   - `resolveExecution({})`               — query current list (no mutation)
+ *
+ * Storage: todos live in the agent-level tool store. Writes go through
+ * `tools.update_store`, so the store update is visible on wire replay.
+ */
+
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../../agent/tool';
+import type { ToolExecution } from '../../../loop/types';
+import { toInputJsonSchema } from '../../support/input-schema';
+import type { ToolStore } from '../../store';
+import DESCRIPTION from './todo-list.md';
+
+// ── TODO state shape ─────────────────────────────────────────────────
+
+export type TodoStatus = 'pending' | 'in_progress' | 'done';
+
+export interface TodoItem {
+  readonly title: string;
+  readonly status: TodoStatus;
+}
+
+declare module '../../store' {
+  interface ToolStoreData {
+    todo: readonly TodoItem[];
+  }
+}
+
+// ── Schema ───────────────────────────────────────────────────────────
+
+const TodoItemSchema = z.object({
+  title: z.string().min(1).describe('Short, actionable title for the todo.'),
+  status: z.enum(['pending', 'in_progress', 'done']).describe('Current status of the todo.'),
+});
+
+export interface TodoListInput {
+  todos?: Array<{ title: string; status: TodoStatus }>;
+}
+
+export const TodoListInputSchema: z.ZodType<TodoListInput> = z.object({
+  todos: z
+    .array(TodoItemSchema)
+    .optional()
+    .describe(
+      'The updated todo list. Omit to read the current todo list without making changes. Pass an empty array to clear the list.',
+    ),
+});
+
+const TODO_STORE_KEY = 'todo';
+
+// ── Implementation ───────────────────────────────────────────────────
+
+function renderTodoList(todos: readonly TodoItem[]): string {
+  if (todos.length === 0) {
+    return 'Todo list is empty.';
+  }
+  const lines = todos.map((t) => {
+    const marker = statusMarker(t.status);
+    return `  ${marker} ${t.title}`;
+  });
+  return ['Current todo list:', ...lines].join('\n');
+}
+
+function statusMarker(status: TodoStatus): string {
+  switch (status) {
+    case 'pending':
+      return '[pending]';
+    case 'in_progress':
+      return '[in_progress]';
+    case 'done':
+      return '[done]';
+    default: {
+      const _exhaustive: never = status;
+      return _exhaustive;
+    }
+  }
+}
+
+export class TodoListTool implements BuiltinTool<TodoListInput> {
+  readonly name = 'TodoList' as const;
+  readonly description: string = DESCRIPTION;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(TodoListInputSchema);
+
+  constructor(private readonly store: ToolStore) {}
+
+  resolveExecution(args: TodoListInput): ToolExecution {
+    const description =
+      args.todos === undefined
+        ? 'Reading todo list'
+        : args.todos.length === 0
+          ? 'Clearing todo list'
+          : 'Updating todo list';
+    return {
+      description,
+      execute: async () => {
+        // Query mode — return the current list without mutation.
+        if (args.todos === undefined) {
+          const current = this.getTodos();
+          return { isError: false, output: renderTodoList(current) };
+        }
+
+        // Write mode — replace the full list and return the new state.
+        this.setTodos(args.todos);
+        const stored = this.getTodos();
+        const output =
+          stored.length === 0 ? 'Todo list cleared.' : `Todo list updated.\n${renderTodoList(stored)}`;
+        return { isError: false, output };
+      },
+    };
+  }
+
+  private getTodos(): readonly TodoItem[] {
+    const todos = this.store.get(TODO_STORE_KEY);
+    return todos ?? [];
+  }
+
+  private setTodos(todos: readonly TodoItem[]): void {
+    this.store.set(
+      TODO_STORE_KEY,
+      todos.map((todo) => ({ title: todo.title, status: todo.status })),
+    );
+  }
+}
diff --git a/packages/agent-core/src/tools/builtin/web/fetch-url.md b/packages/agent-core/src/tools/builtin/web/fetch-url.md
new file mode 100644
index 000000000..f2356e690
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/web/fetch-url.md
@@ -0,0 +1,3 @@
+Fetch content from a URL. Returns the main text content extracted from the page. Use this when you need to read a specific web page.
+
+Only public `http`/`https` URLs are supported. Requests to private, loopback, or link-local addresses are refused, and responses larger than 10 MiB are rejected.
diff --git a/packages/agent-core/src/tools/builtin/web/fetch-url.ts b/packages/agent-core/src/tools/builtin/web/fetch-url.ts
new file mode 100644
index 000000000..6c1534651
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/web/fetch-url.ts
@@ -0,0 +1,122 @@
+/**
+ * FetchURLTool — host-injected URL fetcher.
+ *
+ * kimi-core defines the interface; the host provides the real fetch
+ * implementation via `UrlFetcher`. If no fetcher is supplied, the tool
+ * should not be registered (not exposed to the LLM).
+ */
+
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../../agent/tool';
+import { ToolAccesses } from '../../../loop/tool-access';
+import type { ExecutableToolContext, ExecutableToolResult, ToolExecution } from '../../../loop/types';
+import { toInputJsonSchema } from '../../support/input-schema';
+import { ToolResultBuilder } from '../../support/result-builder';
+import DESCRIPTION from './fetch-url.md';
+
+// ── Provider interface (host-injected) ───────────────────────────────
+
+/**
+ * How the returned content relates to the original response body.
+ *
+ * - `passthrough` — the body was already plain text / markdown and is
+ *   returned verbatim, in full.
+ * - `extracted` — the body was an HTML page; only the main article text
+ *   was extracted and returned.
+ */
+export type UrlFetchKind = 'passthrough' | 'extracted';
+
+export interface UrlFetchResult {
+  /** The text handed to the LLM. */
+  content: string;
+  /** Whether `content` is a verbatim passthrough or extracted main text. */
+  kind: UrlFetchKind;
+}
+
+export interface UrlFetcher {
+  fetch(url: string, options?: { toolCallId?: string }): Promise<UrlFetchResult>;
+}
+
+/**
+ * Thrown by a `UrlFetcher` when the upstream HTTP request completed but
+ * returned a non-success status. The tool branches on this to surface
+ * `Status: N` in the error message; non-HTTP failures (DNS, timeout,
+ * connection reset, …) keep flowing through as plain `Error`.
+ */
+export class HttpFetchError extends Error {
+  override readonly name = 'HttpFetchError';
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.status = status;
+  }
+}
+
+// ── Input schema ─────────────────────────────────────────────────────
+
+export const FetchURLInputSchema = z.object({
+  url: z.string().describe('The URL to fetch content from.'),
+});
+
+export type FetchURLInput = z.Infer<typeof FetchURLInputSchema>;
+
+// ── Implementation ───────────────────────────────────────────────────
+
+export class FetchURLTool implements BuiltinTool<FetchURLInput> {
+  readonly name = 'FetchURL' as const;
+  readonly description: string = DESCRIPTION;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(FetchURLInputSchema);
+  constructor(private readonly fetcher: UrlFetcher) {}
+
+  resolveExecution(args: FetchURLInput): ToolExecution {
+    const preview = args.url.length > 50 ? `${args.url.slice(0, 50)}…` : args.url;
+    return {
+      accesses: ToolAccesses.none(),
+      description: `Fetching: ${preview}`,
+      execute: (ctx) => this.execution(args, ctx),
+    };
+  }
+
+  private async execution(
+    args: FetchURLInput,
+    {
+    toolCallId,
+    }: ExecutableToolContext,
+  ): Promise<ExecutableToolResult> {
+    try {
+      const { content, kind } = await this.fetcher.fetch(args.url, { toolCallId });
+
+      if (!content) {
+        return {
+          output: 'The response body is empty.',
+          isError: false,
+        };
+      }
+
+      const builder = new ToolResultBuilder({ maxLineLength: null });
+      builder.write(content);
+      // Tell the LLM whether it received the whole body or only the
+      // extracted article text, so it can judge how complete the
+      // content is.
+      const message =
+        kind === 'passthrough'
+          ? 'The returned content is the full response body, returned verbatim.'
+          : 'The returned content is the main text extracted from the page.';
+      return builder.ok(message);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      if (error instanceof HttpFetchError) {
+        return {
+          isError: true,
+          output: `Failed to fetch URL. Status: ${String(error.status)}. ${msg}`,
+        };
+      }
+      return {
+        isError: true,
+        output: `Failed to fetch URL due to network error: ${args.url}. ${msg}`,
+      };
+    }
+  }
+
+}
diff --git a/packages/agent-core/src/tools/builtin/web/web-search.md b/packages/agent-core/src/tools/builtin/web/web-search.md
new file mode 100644
index 000000000..fbab5c828
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/web/web-search.md
@@ -0,0 +1,3 @@
+Search the web for information. Use this when you need up-to-date information from the internet.
+
+Each result includes its title, URL, snippet, and—when available—a publication date. When `include_content` is enabled, the full page content—when available—is appended after the snippet.
diff --git a/packages/agent-core/src/tools/builtin/web/web-search.ts b/packages/agent-core/src/tools/builtin/web/web-search.ts
new file mode 100644
index 000000000..153a14f9d
--- /dev/null
+++ b/packages/agent-core/src/tools/builtin/web/web-search.ts
@@ -0,0 +1,152 @@
+/**
+ * WebSearchTool — host-injected web search.
+ *
+ * kimi-core defines the interface; the host provides the real search
+ * implementation via `WebSearchProvider`. If no provider is supplied,
+ * the tool should not be registered (not exposed to the LLM).
+ */
+
+import { z } from 'zod';
+
+import type { BuiltinTool } from '../../../agent/tool';
+import { ToolAccesses } from '../../../loop/tool-access';
+import type { ExecutableToolContext, ExecutableToolResult, ToolExecution } from '../../../loop/types';
+import { toInputJsonSchema } from '../../support/input-schema';
+import { ToolResultBuilder } from '../../support/result-builder';
+import DESCRIPTION from './web-search.md';
+
+// ── Provider interface (host-injected) ───────────────────────────────
+
+export interface WebSearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+  date?: string | undefined;
+  content?: string | undefined;
+}
+
+export interface WebSearchProvider {
+  search(
+    query: string,
+    options?: { limit?: number; includeContent?: boolean; toolCallId?: string },
+  ): Promise<WebSearchResult[]>;
+}
+
+// ── Input schema ─────────────────────────────────────────────────────
+
+export const WebSearchInputSchema = z.object({
+  query: z.string().describe('The query text to search for.'),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(20)
+    .default(5)
+    .describe(
+      'The number of results to return. Typically you do not need to set this value. When the results do not contain what you need, you probably want to give a more concrete query.',
+    )
+    .optional(),
+  include_content: z
+    .boolean()
+    .default(false)
+    .describe(
+      'Whether to include the content of the web pages in the results. It can consume a large amount of tokens when this is set to true. You should avoid enabling this when `limit` is set to a large value.',
+    )
+    .optional(),
+});
+
+export type WebSearchInput = z.Infer<typeof WebSearchInputSchema>;
+
+// ── Implementation ───────────────────────────────────────────────────
+
+export class WebSearchTool implements BuiltinTool<WebSearchInput> {
+  readonly name = 'WebSearch' as const;
+  readonly description: string = DESCRIPTION;
+  readonly parameters: Record<string, unknown> = toInputJsonSchema(WebSearchInputSchema);
+  constructor(private readonly provider: WebSearchProvider) {}
+
+  resolveExecution(args: WebSearchInput): ToolExecution {
+    const preview = args.query.length > 40 ? `${args.query.slice(0, 40)}…` : args.query;
+    return {
+      accesses: ToolAccesses.none(),
+      description: `Searching: ${preview}`,
+      execute: (ctx) => this.execution(args, ctx),
+    };
+  }
+
+  private async execution(
+    args: WebSearchInput,
+    {
+    toolCallId,
+    }: ExecutableToolContext,
+  ): Promise<ExecutableToolResult> {
+    try {
+      const opts: { limit?: number; includeContent?: boolean; toolCallId?: string } = {
+        toolCallId,
+      };
+      if (args.limit !== undefined) opts.limit = args.limit;
+      if (args.include_content !== undefined) opts.includeContent = args.include_content;
+      const results = await this.provider.search(args.query, opts);
+      const builder = new ToolResultBuilder({ maxLineLength: null });
+
+      if (results.length === 0) {
+        builder.write('No search results found.');
+        return builder.ok();
+      }
+
+      let first = true;
+      for (const result of results) {
+        if (!first) builder.write('---\n\n');
+        first = false;
+
+        builder.write(`Title: ${result.title}\n`);
+        if (result.date) builder.write(`Date: ${result.date}\n`);
+        builder.write(`URL: ${result.url}\n`);
+        builder.write(`Snippet: ${result.snippet}\n\n`);
+        if (result.content) builder.write(`${result.content}\n\n`);
+      }
+
+      return builder.ok();
+    } catch (error) {
+      return {
+        isError: true,
+        output: classifySearchError(error),
+      };
+    }
+  }
+
+}
+
+// ── Error classification ─────────────────────────────────────────────
+
+/**
+ * Maps a thrown search error to a categorised, human-readable message.
+ *
+ * The original error text is always preserved so the model can still see the
+ * underlying detail; the prefix only adds a category so failures are easier to
+ * reason about (e.g. retry vs. surface to the user).
+ */
+function classifySearchError(error: unknown): string {
+  const name = error instanceof Error ? error.name : '';
+  const message = error instanceof Error ? error.message : String(error);
+  const lower = message.toLowerCase();
+
+  if (name === 'AbortError' || lower.includes('abort')) {
+    return `Search cancelled: ${message}`;
+  }
+  if (name === 'TimeoutError' || lower.includes('timed out') || lower.includes('timeout')) {
+    return `Search timed out: ${message}`;
+  }
+  if (lower.includes('401') || lower.includes('unauthorized') || lower.includes('auth')) {
+    return `Search failed (authentication): ${message}`;
+  }
+  if (
+    lower.includes('http ') ||
+    lower.includes('network') ||
+    lower.includes('fetch') ||
+    name === 'TypeError'
+  ) {
+    return `Search failed (network): ${message}`;
+  }
+  return `Search failed: ${message}`;
+}
diff --git a/packages/agent-core/src/tools/display/index.ts b/packages/agent-core/src/tools/display/index.ts
new file mode 100644
index 000000000..e84d06c37
--- /dev/null
+++ b/packages/agent-core/src/tools/display/index.ts
@@ -0,0 +1 @@
+export * from './schemas';
diff --git a/packages/agent-core/src/tools/display/schemas.ts b/packages/agent-core/src/tools/display/schemas.ts
new file mode 100644
index 000000000..abf180088
--- /dev/null
+++ b/packages/agent-core/src/tools/display/schemas.ts
@@ -0,0 +1,158 @@
+/**
+ * Zod schemas for the display unions.
+ *
+ * The wire-record layer validates incoming / outgoing
+ * `input_display` / `result_display` fields against these schemas.
+ */
+
+import { z } from 'zod';
+
+export const ToolInputDisplaySchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('command'),
+    command: z.string(),
+    cwd: z.string().optional(),
+    description: z.string().optional(),
+    language: z.literal('bash').optional(),
+  }),
+  z.object({
+    kind: z.literal('file_io'),
+    operation: z.enum(['read', 'write', 'edit', 'glob', 'grep']),
+    path: z.string(),
+    detail: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal('diff'),
+    path: z.string(),
+    before: z.string(),
+    after: z.string(),
+    hunks: z.number().optional(),
+  }),
+  z.object({
+    kind: z.literal('search'),
+    query: z.string(),
+    scope: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal('url_fetch'),
+    url: z.string(),
+    method: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal('agent_call'),
+    agent_name: z.string(),
+    prompt: z.string(),
+    background: z.boolean().optional(),
+  }),
+  z.object({
+    kind: z.literal('skill_call'),
+    skill_name: z.string(),
+    args: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal('todo_list'),
+    items: z.array(z.object({ title: z.string(), status: z.string() })),
+  }),
+  z.object({
+    kind: z.literal('background_task'),
+    task_id: z.string(),
+    status: z.string(),
+    description: z.string(),
+    task_kind: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal('task_stop'),
+    task_id: z.string(),
+    task_description: z.string(),
+  }),
+  z.object({
+    kind: z.literal('plan_review'),
+    plan: z.string(),
+    path: z.string().optional(),
+    options: z
+      .array(
+        z.object({
+          label: z.string(),
+          description: z.string(),
+        }),
+      )
+      .readonly()
+      .optional(),
+  }),
+  z.object({
+    kind: z.literal('generic'),
+    summary: z.string(),
+    detail: z.unknown().optional(),
+  }),
+]);
+
+export const ToolResultDisplaySchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('command_output'),
+    exit_code: z.number(),
+    stdout: z.string().optional(),
+    stderr: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal('file_content'),
+    path: z.string(),
+    content: z.string(),
+    range: z.object({ start: z.number(), end: z.number() }).optional(),
+    truncated: z.boolean().optional(),
+  }),
+  z.object({
+    kind: z.literal('diff'),
+    path: z.string(),
+    before: z.string(),
+    after: z.string(),
+    hunks: z.number().optional(),
+  }),
+  z.object({
+    kind: z.literal('search_results'),
+    query: z.string(),
+    matches: z.array(z.object({ file: z.string(), line: z.number(), text: z.string() })),
+  }),
+  z.object({
+    kind: z.literal('url_content'),
+    url: z.string(),
+    status: z.number(),
+    preview: z.string().optional(),
+    content_type: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal('agent_summary'),
+    agent_name: z.string(),
+    result: z.string().optional(),
+    steps: z.number().optional(),
+  }),
+  z.object({
+    kind: z.literal('background_task'),
+    task_id: z.string(),
+    status: z.string(),
+    description: z.string(),
+  }),
+  z.object({
+    kind: z.literal('todo_list'),
+    items: z.array(z.object({ title: z.string(), status: z.string() })),
+  }),
+  z.object({ kind: z.literal('structured'), data: z.unknown() }),
+  z.object({
+    kind: z.literal('text'),
+    text: z.string(),
+    truncated: z.boolean().optional(),
+  }),
+  z.object({
+    kind: z.literal('error'),
+    message: z.string(),
+    code: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal('generic'),
+    summary: z.string(),
+    detail: z.unknown().optional(),
+  }),
+]);
+
+// Types inferred from schemas — single source of truth.
+export type ToolInputDisplay = z.infer<typeof ToolInputDisplaySchema>;
+export type ToolResultDisplay = z.infer<typeof ToolResultDisplaySchema>;
diff --git a/packages/agent-core/src/tools/policies/default-permissions.ts b/packages/agent-core/src/tools/policies/default-permissions.ts
new file mode 100644
index 000000000..01a562e4a
--- /dev/null
+++ b/packages/agent-core/src/tools/policies/default-permissions.ts
@@ -0,0 +1,69 @@
+/**
+ * Default permission posture for built-in tools.
+ *
+ * This table captures the Python-parity distinction between tools that
+ * call Approval.request() and tools that run without an approval prompt.
+ * The rule layer still applies explicit deny rules before consulting this
+ * table.
+ */
+
+export type BuiltinToolDefaultPermission = 'auto_allow' | 'ask';
+export type KnownBuiltinToolName =
+  | 'Read'
+  | 'Grep'
+  | 'Glob'
+  | 'ReadMediaFile'
+  | 'Think'
+  | 'TodoList'
+  | 'TaskList'
+  | 'TaskOutput'
+  | 'WebSearch'
+  | 'FetchURL'
+  | 'Agent'
+  | 'AskUserQuestion'
+  | 'EnterPlanMode'
+  | 'ExitPlanMode'
+  | 'Skill'
+  | 'Bash'
+  | 'Write'
+  | 'Edit'
+  | 'TaskStop';
+
+type BuiltinToolDefaultPermissionTable = Readonly<
+  Record<KnownBuiltinToolName, BuiltinToolDefaultPermission>
+>;
+
+const BUILTIN_TOOL_DEFAULT_PERMISSION_TABLE: BuiltinToolDefaultPermissionTable = {
+  Read: 'auto_allow',
+  Grep: 'auto_allow',
+  Glob: 'auto_allow',
+  ReadMediaFile: 'auto_allow',
+  Think: 'auto_allow',
+  TodoList: 'auto_allow',
+  TaskList: 'auto_allow',
+  TaskOutput: 'auto_allow',
+  WebSearch: 'auto_allow',
+  FetchURL: 'auto_allow',
+  Agent: 'auto_allow',
+  AskUserQuestion: 'auto_allow',
+  EnterPlanMode: 'auto_allow',
+  ExitPlanMode: 'auto_allow',
+  Skill: 'auto_allow',
+  Bash: 'ask',
+  Write: 'ask',
+  Edit: 'ask',
+  TaskStop: 'ask',
+};
+
+export const BUILTIN_TOOL_DEFAULT_PERMISSIONS: BuiltinToolDefaultPermissionTable =
+  BUILTIN_TOOL_DEFAULT_PERMISSION_TABLE;
+
+export function getBuiltinToolDefaultPermission(
+  toolName: string,
+): BuiltinToolDefaultPermission | undefined {
+  return BUILTIN_TOOL_DEFAULT_PERMISSIONS[toolName as KnownBuiltinToolName];
+}
+
+export function isDefaultAutoAllowTool(toolName: string): boolean {
+  return getBuiltinToolDefaultPermission(toolName) === 'auto_allow';
+}
diff --git a/packages/agent-core/src/tools/policies/path-access.ts b/packages/agent-core/src/tools/policies/path-access.ts
new file mode 100644
index 000000000..00bcd4f9a
--- /dev/null
+++ b/packages/agent-core/src/tools/policies/path-access.ts
@@ -0,0 +1,334 @@
+/**
+ * Path safety guards used by Read/Write/Edit/Grep/Glob.
+ *
+ * Canonicalization is **lexical** only (no `realpath` / symlink following).
+ * Mirrors `KaosPath.canonical()` and keeps the guard backend-aware:
+ * callers should pass the active Kaos path class so SSH paths stay POSIX
+ * even when the host Node process is running on Windows.
+ *
+ * Shared-prefix escapes (a path like `/workspace-evil` passing a naive
+ * `startswith('/workspace')` check) are blocked by requiring a path
+ * separator (or exact equality) after the base prefix in
+ * `isWithinDirectory`.
+ */
+
+import * as nativePath from 'node:path';
+import * as posixPath from 'node:path/posix';
+import * as win32Path from 'node:path/win32';
+
+import type { Kaos } from '@moonshot-ai/kaos';
+
+import type { WorkspaceConfig } from '../support/workspace';
+import { isSensitiveFile } from './sensitive';
+
+export type PathClass = 'posix' | 'win32';
+export type PathSecurityCode = 'PATH_OUTSIDE_WORKSPACE' | 'PATH_SENSITIVE' | 'PATH_INVALID';
+export type PathAccessOperation = 'read' | 'write' | 'search';
+export type WorkspaceGuardMode = 'strict' | 'absolute-outside-allowed' | 'disabled';
+
+export interface WorkspaceAccessPolicy {
+  readonly guardMode: WorkspaceGuardMode;
+  readonly checkSensitive: boolean;
+}
+
+export const STRICT_WORKSPACE_ACCESS_POLICY: WorkspaceAccessPolicy = {
+  guardMode: 'strict',
+  checkSensitive: true,
+};
+
+export const DEFAULT_WORKSPACE_ACCESS_POLICY: WorkspaceAccessPolicy = {
+  guardMode: 'absolute-outside-allowed',
+  checkSensitive: true,
+};
+
+export interface PathAccess {
+  readonly path: string;
+  readonly outsideWorkspace: boolean;
+}
+
+export class PathSecurityError extends Error {
+  readonly code: PathSecurityCode;
+  readonly rawPath: string;
+  readonly canonicalPath: string;
+
+  constructor(code: PathSecurityCode, rawPath: string, canonicalPath: string, message: string) {
+    super(message);
+    this.name = 'PathSecurityError';
+    this.code = code;
+    this.rawPath = rawPath;
+    this.canonicalPath = canonicalPath;
+  }
+}
+
+const DEFAULT_PATH_CLASS: PathClass = nativePath.sep === '\\' ? 'win32' : 'posix';
+
+function pathMod(pathClass: PathClass): typeof posixPath {
+  return pathClass === 'win32' ? win32Path : posixPath;
+}
+
+function comparablePath(path: string, pathClass: PathClass): string {
+  return pathClass === 'win32' ? path.toLowerCase().replaceAll('/', '\\') : path;
+}
+
+function isWin32DriveRelative(path: string): boolean {
+  return /^[A-Za-z]:(?:$|[^\\/])/.test(path);
+}
+
+export function normalizeUserPath(path: string, pathClass: PathClass = DEFAULT_PATH_CLASS): string {
+  if (pathClass !== 'win32') return path;
+
+  // A bare root slash flips to backslash so downstream win32 string
+  // operations (join, isAbsolute, drive-letter detection) treat it as a
+  // native path component. Matches the py helper's behavior.
+  if (path === '/') return '\\';
+
+  if (path.startsWith('//')) {
+    return path.replaceAll('/', '\\');
+  }
+
+  const cygdriveMatch = /^\/cygdrive\/([A-Za-z])(?:\/|$)/.exec(path);
+  if (cygdriveMatch !== null) {
+    const drive = cygdriveMatch[1]!.toUpperCase();
+    const rest = path.slice(`/cygdrive/${cygdriveMatch[1]!}`.length).replaceAll('/', '\\');
+    return `${drive}:${rest === '' ? '\\' : rest}`;
+  }
+
+  const driveMatch = /^\/([A-Za-z])(?:\/|$)/.exec(path);
+  if (driveMatch !== null) {
+    const drive = driveMatch[1]!.toUpperCase();
+    const rest = path.slice(2).replaceAll('/', '\\');
+    return `${drive}:${rest === '' ? '\\' : rest}`;
+  }
+
+  return path;
+}
+
+function expandUserPath(path: string, homeDir: string | undefined, pathClass: PathClass): string {
+  if (homeDir === undefined) return path;
+  if (path === '~') return homeDir;
+  if (path.startsWith('~/') || (pathClass === 'win32' && path.startsWith('~\\'))) {
+    return pathMod(pathClass).join(homeDir, path.slice(2));
+  }
+  return path;
+}
+
+/**
+ * Lexical canonicalization: resolve relative → absolute against `cwd`,
+ * then normalize `..` / `.` segments. No filesystem I/O.
+ */
+export function canonicalizePath(
+  path: string,
+  cwd: string,
+  pathClass: PathClass = DEFAULT_PATH_CLASS,
+): string {
+  if (path === '') {
+    throw new PathSecurityError('PATH_INVALID', path, path, 'Path cannot be empty');
+  }
+  const mod = pathMod(pathClass);
+  const normalizedPath = normalizeUserPath(path, pathClass);
+  if (pathClass === 'win32' && isWin32DriveRelative(normalizedPath)) {
+    throw new PathSecurityError(
+      'PATH_INVALID',
+      path,
+      normalizedPath,
+      `"${path}" is a drive-relative Windows path. Use an absolute path like C:\\path or a path relative to the working directory.`,
+    );
+  }
+  if (!mod.isAbsolute(normalizedPath) && !mod.isAbsolute(cwd)) {
+    throw new PathSecurityError(
+      'PATH_INVALID',
+      path,
+      normalizedPath,
+      `Cannot resolve "${path}" against non-absolute cwd "${cwd}".`,
+    );
+  }
+  const abs = mod.isAbsolute(normalizedPath) ? normalizedPath : mod.resolve(cwd, normalizedPath);
+  return mod.normalize(abs);
+}
+
+/**
+ * True iff `candidate` is `base` itself or a descendant of it, compared
+ * on path-component boundaries. Both arguments must already be canonical.
+ */
+export function isWithinDirectory(
+  candidate: string,
+  base: string,
+  pathClass: PathClass = DEFAULT_PATH_CLASS,
+): boolean {
+  const mod = pathMod(pathClass);
+  const comparableCandidate = comparablePath(candidate, pathClass);
+  const comparableBase = comparablePath(base, pathClass);
+  if (comparableCandidate === comparableBase) return true;
+  const prefix = comparableBase.endsWith(mod.sep) ? comparableBase : comparableBase + mod.sep;
+  return comparableCandidate.startsWith(prefix);
+}
+
+/**
+ * True iff `candidate` (already canonical) sits inside any of the workspace
+ * roots listed in `config` (primary `workspaceDir` or any `additionalDirs`).
+ */
+export function isWithinWorkspace(
+  candidate: string,
+  config: WorkspaceConfig,
+  pathClass: PathClass = DEFAULT_PATH_CLASS,
+): boolean {
+  if (isWithinDirectory(candidate, config.workspaceDir, pathClass)) return true;
+  for (const dir of config.additionalDirs) {
+    if (isWithinDirectory(candidate, dir, pathClass)) return true;
+  }
+  return false;
+}
+
+export interface AssertPathOptions {
+  readonly mode: PathAccessOperation;
+  /** When true (default), also reject paths matching a sensitive-file pattern. */
+  readonly checkSensitive?: boolean | undefined;
+  readonly pathClass?: PathClass | undefined;
+}
+
+export interface ResolvePathAccessOptions {
+  readonly operation: PathAccessOperation;
+  readonly policy?: WorkspaceAccessPolicy | undefined;
+  readonly pathClass?: PathClass | undefined;
+  readonly homeDir?: string;
+}
+
+export interface ResolvePathAccessPathOptions {
+  readonly kaos: Pick<Kaos, 'pathClass' | 'gethome'>;
+  readonly workspace: WorkspaceConfig;
+  readonly operation: PathAccessOperation;
+  readonly policy?: WorkspaceAccessPolicy;
+  readonly expandHome?: boolean;
+}
+
+function outsideWorkspaceMessage(
+  path: string,
+  canonical: string,
+  config: WorkspaceConfig,
+  operation: PathAccessOperation,
+): string {
+  const allowed = [config.workspaceDir, ...config.additionalDirs].join(', ');
+  const verb = operation === 'write' ? 'written' : operation === 'search' ? 'searched' : 'read';
+  return (
+    `"${path}" (canonical: "${canonical}") is outside the workspace ` +
+    `and outside the working directory "${config.workspaceDir}". ` +
+    `Cannot be ${verb}. Allowed roots: ${allowed}`
+  );
+}
+
+function relativeOutsideMessage(path: string, operation: PathAccessOperation): string {
+  const verb =
+    operation === 'write'
+      ? 'write or edit a file'
+      : operation === 'search'
+        ? 'search'
+        : 'read a file';
+  return (
+    `"${path}" is not an absolute path. ` +
+    `You must provide an absolute path to ${verb} outside the working directory.`
+  );
+}
+
+export function resolvePathAccess(
+  path: string,
+  cwd: string,
+  config: WorkspaceConfig,
+  options: ResolvePathAccessOptions,
+): PathAccess {
+  const pathClass = options.pathClass ?? DEFAULT_PATH_CLASS;
+  const mod = pathMod(pathClass);
+  const normalizedPath = normalizeUserPath(path, pathClass);
+  const expandedPath = expandUserPath(normalizedPath, options.homeDir, pathClass);
+  const rawIsAbsolute = mod.isAbsolute(expandedPath);
+  const canonical = canonicalizePath(expandedPath, cwd, pathClass);
+  const outsideWorkspace = !isWithinWorkspace(canonical, config, pathClass);
+  const policy = options.policy ?? DEFAULT_WORKSPACE_ACCESS_POLICY;
+
+  if (policy.checkSensitive && isSensitiveFile(canonical, pathClass)) {
+    throw new PathSecurityError(
+      'PATH_SENSITIVE',
+      path,
+      canonical,
+      `"${path}" matches a sensitive-file pattern (env / credential / SSH key). ` +
+        `Access is blocked to protect secrets.`,
+    );
+  }
+
+  // Strict mode requires the input itself to be absolute, even if it
+  // would canonicalize to a path inside the workspace. The python Glob
+  // contract is "directory must be an absolute path"; resolving a
+  // relative argument against the workspace cwd silently re-targets the
+  // search and is rejected outright in that contract.
+  if (policy.guardMode === 'strict' && !rawIsAbsolute) {
+    throw new PathSecurityError(
+      'PATH_OUTSIDE_WORKSPACE',
+      path,
+      canonical,
+      relativeOutsideMessage(path, options.operation),
+    );
+  }
+
+  if (outsideWorkspace) {
+    switch (policy.guardMode) {
+      case 'strict':
+        throw new PathSecurityError(
+          'PATH_OUTSIDE_WORKSPACE',
+          path,
+          canonical,
+          outsideWorkspaceMessage(path, canonical, config, options.operation),
+        );
+      case 'absolute-outside-allowed':
+        if (!rawIsAbsolute) {
+          throw new PathSecurityError(
+            'PATH_OUTSIDE_WORKSPACE',
+            path,
+            canonical,
+            relativeOutsideMessage(path, options.operation),
+          );
+        }
+        break;
+      case 'disabled':
+        break;
+    }
+  }
+
+  return { path: canonical, outsideWorkspace };
+}
+
+export function resolvePathAccessPath(
+  path: string,
+  options: ResolvePathAccessPathOptions,
+): string {
+  const { kaos, workspace, operation, policy, expandHome = true } = options;
+  return resolvePathAccess(path, workspace.workspaceDir, workspace, {
+    operation,
+    policy,
+    pathClass: kaos.pathClass(),
+    homeDir: expandHome ? kaos.gethome() : undefined,
+  }).path;
+}
+
+/**
+ * Throw `PathSecurityError` if `path` is outside the workspace, a known
+ * sensitive file, or an empty string. Returns the canonical absolute path
+ * when the check passes.
+ *
+ * Note: this is purely lexical. It does NOT protect against symlink
+ * targets that point outside the workspace — that would require kaos-layer
+ * realpath support, which is not currently available.
+ */
+export function assertPathAllowed(
+  path: string,
+  cwd: string,
+  config: WorkspaceConfig,
+  options: AssertPathOptions,
+): string {
+  return resolvePathAccess(path, cwd, config, {
+    operation: options.mode,
+    pathClass: options.pathClass,
+    policy: {
+      guardMode: 'strict',
+      checkSensitive: options.checkSensitive ?? STRICT_WORKSPACE_ACCESS_POLICY.checkSensitive,
+    },
+  }).path;
+}
diff --git a/packages/agent-core/src/tools/policies/sensitive.ts b/packages/agent-core/src/tools/policies/sensitive.ts
new file mode 100644
index 000000000..6557488f5
--- /dev/null
+++ b/packages/agent-core/src/tools/policies/sensitive.ts
@@ -0,0 +1,93 @@
+/**
+ * Sensitive-file detection.
+ *
+ * The pattern list is intentionally small to avoid false positives; files
+ * matching any of these patterns are blocked from Read/Write/Edit so
+ * credentials cannot be exfiltrated through a compromised prompt. Exemptions
+ * like `.env.example` are explicitly allowed.
+ */
+
+import * as nativePath from 'node:path';
+import * as posixPath from 'node:path/posix';
+import * as win32Path from 'node:path/win32';
+
+import type { PathClass } from './path-access';
+
+const SENSITIVE_BASENAMES = new Set<string>([
+  '.env',
+  'id_rsa',
+  'id_ed25519',
+  'id_ecdsa',
+  'credentials',
+]);
+
+const SENSITIVE_PATH_SUFFIXES = [
+  ['.aws', 'credentials'],
+  ['.gcp', 'credentials'],
+];
+
+const ENV_PREFIX = '.env.';
+const ENV_EXEMPTIONS = new Set<string>(['.env.example', '.env.sample', '.env.template']);
+
+const SENSITIVE_BASENAME_PREFIXES = ['id_rsa', 'id_ed25519', 'id_ecdsa', 'credentials'];
+const PUBLIC_KEY_BASENAMES = new Set<string>(['id_rsa.pub', 'id_ed25519.pub', 'id_ecdsa.pub']);
+export const SENSITIVE_DOT_VARIANT_SUFFIXES = [
+  '.bak',
+  '.backup',
+  '.copy',
+  '.disabled',
+  '.key',
+  '.old',
+  '.orig',
+  '.pem',
+  '.save',
+  '.tmp',
+] as const;
+const SENSITIVE_DOT_VARIANT_SUFFIX_SET = new Set<string>(SENSITIVE_DOT_VARIANT_SUFFIXES);
+
+const DEFAULT_PATH_CLASS: PathClass = nativePath.sep === '\\' ? 'win32' : 'posix';
+
+function pathMod(pathClass: PathClass): typeof posixPath {
+  return pathClass === 'win32' ? win32Path : posixPath;
+}
+
+function comparable(path: string, pathClass: PathClass): string {
+  return pathClass === 'win32' ? path.toLowerCase() : path;
+}
+
+export function isSensitiveFile(path: string, pathClass: PathClass = DEFAULT_PATH_CLASS): boolean {
+  const mod = pathMod(pathClass);
+  const name = mod.basename(path);
+  const comparableName = comparable(name, pathClass);
+  const comparablePath = comparable(path, pathClass);
+
+  if (ENV_EXEMPTIONS.has(comparableName)) return false;
+  if (PUBLIC_KEY_BASENAMES.has(comparableName)) return false;
+  if (SENSITIVE_BASENAMES.has(comparableName)) return true;
+  if (comparableName.startsWith(ENV_PREFIX)) return true;
+
+  for (const prefix of SENSITIVE_BASENAME_PREFIXES) {
+    if (comparableName === prefix) return true;
+    // Catch rename-shielded variants without flagging unrelated filenames
+    // like `id_rsafoo` or ordinary JSON files like `credentials.json`.
+    if (comparableName.length > prefix.length && comparableName.startsWith(prefix)) {
+      const suffix = comparableName.slice(prefix.length);
+      const next = suffix[0];
+      if (next === '-' || next === '_') return true;
+      if (next === '.' && SENSITIVE_DOT_VARIANT_SUFFIX_SET.has(suffix)) return true;
+    }
+  }
+
+  for (const suffixParts of SENSITIVE_PATH_SUFFIXES) {
+    const suffix = suffixParts.join(mod.sep);
+    const comparableSuffix = comparable(suffix, pathClass);
+    if (
+      comparablePath.endsWith(`${mod.sep}${comparableSuffix}`) ||
+      comparablePath.includes(`${mod.sep}${comparableSuffix}${mod.sep}`)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
diff --git a/packages/agent-core/src/tools/providers/local-fetch-url.ts b/packages/agent-core/src/tools/providers/local-fetch-url.ts
new file mode 100644
index 000000000..af10a8ca3
--- /dev/null
+++ b/packages/agent-core/src/tools/providers/local-fetch-url.ts
@@ -0,0 +1,229 @@
+/**
+ * LocalFetchURLProvider — host-side URL fetcher.
+ *
+ * Flow:
+ *   1. GET the URL with a Chrome-like UA.
+ *   2. Reject HTTP >= 400 with the status code in the message.
+ *   3. Reject responses larger than `maxBytes` (content-length first,
+ *      then measured body length as a defensive second check).
+ *   4. `text/plain` / `text/markdown` → passthrough verbatim.
+ *   5. Otherwise (assumed HTML) → run Readability over a linkedom
+ *      document. Return `# ${title}\n\n${text}` (title omitted when
+ *      absent). If extraction yields no meaningful text, fall back to
+ *      common content containers (`<article>` / `<main>` / `<body>`)
+ *      before throwing a "meaningful content" error.
+ */
+
+import { Readability } from '@mozilla/readability';
+import { parseHTML as rawParseHTML } from 'linkedom';
+
+import { HttpFetchError, type UrlFetcher, type UrlFetchResult } from '../builtin';
+
+// Readability's .d.ts references the global `Document` type, but this
+// package compiles with `lib: ES2023` (no DOM). Extracting the
+// constructor parameter type keeps us off the global `Document` name
+// while still accepting whatever Readability wants.
+type ReadabilityDocument = ConstructorParameters<typeof Readability>[0];
+
+// linkedom's published types depend on DOM libs we don't load. Declare
+// the minimal surface we actually use so the rest of the file stays
+// type-safe without pulling lib.dom.d.ts into the host build.
+interface DomElementLike {
+  textContent: string | null;
+  querySelector(selector: string): DomElementLike | null;
+}
+interface DomParseResult {
+  document: DomElementLike;
+}
+const parseHTML = rawParseHTML as unknown as (html: string) => DomParseResult;
+
+const DEFAULT_USER_AGENT =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+  '(KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36';
+
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+
+export interface LocalFetchURLProviderOptions {
+  userAgent?: string;
+  fetchImpl?: typeof fetch;
+  maxBytes?: number;
+  /**
+   * Allow fetching loopback / RFC 1918 / link-local / ULA addresses.
+   * Defaults to `false` — enabled only for tests and (future) explicit
+   * opt-in. Keeps an LLM that's been prompt-injected from exfiltrating
+   * AWS/GCP metadata (169.254.169.254), probing internal services
+   * (10.x, 192.168.x), or reading local daemons (127.0.0.1:*).
+   */
+  allowPrivateAddresses?: boolean;
+}
+
+/**
+ * SSRF guard — reject non-http(s) schemes and (by default) any hostname
+ * that is, or parses as, a private / loopback / link-local / ULA IP
+ * literal. This is a *static* check against the URL string; it does NOT
+ * do DNS resolution, so a domain that resolves to a private IP via
+ * DNS-rebinding is **not** caught here. That attack is a known
+ * limitation; mitigations (e.g. pinning the resolved IP through to
+ * fetch) are left for a follow-up.
+ */
+function assertSafeFetchTarget(url: string, allowPrivate: boolean): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: "${url}"`);
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`Unsupported URL scheme "${parsed.protocol}" — only http(s) allowed.`);
+  }
+  if (allowPrivate) return;
+  // URL hostname preserves surrounding `[ ]` for IPv6 literals on some
+  // Node versions (and not others). Strip them for uniform comparison.
+  const hostRaw = parsed.hostname.toLowerCase();
+  const host = hostRaw.startsWith('[') && hostRaw.endsWith(']') ? hostRaw.slice(1, -1) : hostRaw;
+  // Literal "localhost" / loopback aliases.
+  if (host === 'localhost' || host.endsWith('.localhost')) {
+    throw new Error(`Refusing to fetch private host: "${host}"`);
+  }
+  // IPv6 loopback / ULA / link-local. Check after bracket strip.
+  if (
+    host === '::1' ||
+    host === '::' ||
+    host.startsWith('fe80:') ||
+    host.startsWith('fc') ||
+    host.startsWith('fd')
+  ) {
+    throw new Error(`Refusing to fetch private host: "${host}"`);
+  }
+  // IPv4 literal — only check when the hostname is a dotted-quad; normal
+  // domains will never match.
+  const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (v4 !== null) {
+    const octets = [v4[1], v4[2], v4[3], v4[4]].map(Number);
+    if (octets.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) {
+      throw new Error(`Invalid IPv4 literal: "${host}"`);
+    }
+    const [a, b] = octets as [number, number, number, number];
+    // 127.0.0.0/8 loopback, 10.0.0.0/8, 192.168.0.0/16,
+    // 172.16.0.0/12, 169.254.0.0/16 link-local / AWS metadata,
+    // 0.0.0.0/8 "this network", 100.64.0.0/10 CGNAT.
+    const isLoopback = a === 127;
+    const isPrivate10 = a === 10;
+    const isPrivate192 = a === 192 && b === 168;
+    const isPrivate172 = a === 172 && b >= 16 && b <= 31;
+    const isLinkLocal = a === 169 && b === 254;
+    const isZero = a === 0;
+    const isCgnat = a === 100 && b >= 64 && b <= 127;
+    if (
+      isLoopback ||
+      isPrivate10 ||
+      isPrivate192 ||
+      isPrivate172 ||
+      isLinkLocal ||
+      isZero ||
+      isCgnat
+    ) {
+      throw new Error(`Refusing to fetch private address: "${host}"`);
+    }
+  }
+}
+
+export class LocalFetchURLProvider implements UrlFetcher {
+  private readonly userAgent: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly maxBytes: number;
+  private readonly allowPrivateAddresses: boolean;
+
+  constructor(options: LocalFetchURLProviderOptions = {}) {
+    this.userAgent = options.userAgent ?? DEFAULT_USER_AGENT;
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    this.allowPrivateAddresses = options.allowPrivateAddresses ?? false;
+  }
+
+  async fetch(url: string, _options?: { toolCallId?: string }): Promise<UrlFetchResult> {
+    assertSafeFetchTarget(url, this.allowPrivateAddresses);
+
+    const response = await this.fetchImpl(url, {
+      method: 'GET',
+      headers: { 'User-Agent': this.userAgent },
+    });
+
+    if (response.status >= 400) {
+      // Drain the unused body so undici can release the socket back to
+      // the keep-alive pool instead of leaking it on error paths.
+      await response.body?.cancel().catch(() => {
+        /* already closed */
+      });
+      throw new HttpFetchError(
+        response.status,
+        `HTTP ${String(response.status)} ${response.statusText}`,
+      );
+    }
+
+    // Reject oversized responses before buffering the full body.
+    const contentLengthRaw = response.headers.get('content-length');
+    if (contentLengthRaw !== null) {
+      const cl = Number(contentLengthRaw);
+      if (Number.isFinite(cl) && cl > this.maxBytes) {
+        throw new Error(
+          `Response body too large: ${String(cl)} bytes exceeds maxBytes (${String(this.maxBytes)}).`,
+        );
+      }
+    }
+
+    const body = await response.text();
+
+    // Servers may omit content-length — measure again defensively.
+    const actualBytes = Buffer.byteLength(body, 'utf8');
+    if (actualBytes > this.maxBytes) {
+      throw new Error(
+        `Response body too large: ${String(actualBytes)} bytes exceeds maxBytes (${String(this.maxBytes)}).`,
+      );
+    }
+
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase();
+    if (contentType.startsWith('text/plain') || contentType.startsWith('text/markdown')) {
+      return { content: body, kind: 'passthrough' };
+    }
+
+    return { content: this.extractMainContent(body), kind: 'extracted' };
+  }
+
+  private extractMainContent(html: string): string {
+    // Readability mutates the DOM it parses, so parse twice — once for
+    // the primary extractor and once for the fallback path.
+    const primary = parseHTML(html);
+    try {
+      const reader = new Readability(primary.document as unknown as ReadabilityDocument, {
+        charThreshold: 0,
+      });
+      const article = reader.parse();
+      if (article !== null) {
+        const text = (article.textContent ?? '').trim();
+        if (text.length > 0) {
+          const title = (article.title ?? '').trim();
+          return title.length > 0 ? `# ${title}\n\n${text}` : text;
+        }
+      }
+    } catch {
+      // Fall through to the container-based fallback.
+    }
+
+    const { document } = parseHTML(html);
+    const titleText = (document.querySelector('title')?.textContent ?? '').trim();
+    const container =
+      document.querySelector('article') ??
+      document.querySelector('main') ??
+      document.querySelector('body');
+    const fallbackText = (container?.textContent ?? '').trim();
+
+    if (fallbackText.length === 0) {
+      throw new Error(
+        'Failed to extract meaningful content from the page. The page may require JavaScript to render.',
+      );
+    }
+
+    return titleText.length > 0 ? `# ${titleText}\n\n${fallbackText}` : fallbackText;
+  }
+}
diff --git a/packages/agent-core/src/tools/providers/moonshot-fetch-url.ts b/packages/agent-core/src/tools/providers/moonshot-fetch-url.ts
new file mode 100644
index 000000000..825781da4
--- /dev/null
+++ b/packages/agent-core/src/tools/providers/moonshot-fetch-url.ts
@@ -0,0 +1,128 @@
+/**
+ * MoonshotFetchURLProvider — host-side UrlFetcher.
+ *
+ * Flow:
+ *   1. Try Moonshot coding-fetch service (POST {url}, Bearer token from a
+ *      narrow token provider, Accept: text/markdown, host-provided headers).
+ *   2. Moonshot 200 → return the body as `extracted` content (the
+ *      service has already extracted the main page text on its side).
+ *   3. Any Moonshot failure — non-200, network error, or token
+ *      refresh failure — → delegate to `localFallback`, forwarding its
+ *      content kind, so the LLM still gets *something* when the service
+ *      is down.
+ *   4. If localFallback also throws → propagate that error.
+ */
+
+import { HttpFetchError, type UrlFetcher, type UrlFetchResult } from '../builtin';
+
+export interface BearerTokenProvider {
+  getAccessToken(options?: { readonly force?: boolean | undefined }): Promise<string>;
+}
+
+export interface MoonshotFetchURLProviderOptions {
+  tokenProvider?: BearerTokenProvider;
+  apiKey?: string;
+  baseUrl: string;
+  defaultHeaders?: Record<string, string>;
+  customHeaders?: Record<string, string>;
+  localFallback: UrlFetcher;
+  fetchImpl?: typeof fetch;
+}
+
+export class MoonshotFetchURLProvider implements UrlFetcher {
+  private readonly tokenProvider: BearerTokenProvider | undefined;
+  private readonly apiKey: string | undefined;
+  private readonly baseUrl: string;
+  private readonly defaultHeaders: Record<string, string>;
+  private readonly customHeaders: Record<string, string>;
+  private readonly localFallback: UrlFetcher;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: MoonshotFetchURLProviderOptions) {
+    this.tokenProvider = options.tokenProvider;
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl;
+    this.defaultHeaders = options.defaultHeaders ?? {};
+    this.customHeaders = options.customHeaders ?? {};
+    this.localFallback = options.localFallback;
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+  }
+
+  async fetch(url: string, options?: { toolCallId?: string }): Promise<UrlFetchResult> {
+    try {
+      const content = await this.fetchViaMoonshot(url, options?.toolCallId);
+      // The service returns text it has already extracted from the page.
+      return { content, kind: 'extracted' };
+    } catch {
+      // Forward an explicit options object even when the caller passed
+      // none, so downstream consumers always see a defined second arg.
+      return this.localFallback.fetch(url, options ?? {});
+    }
+  }
+
+  private async fetchViaMoonshot(
+    url: string,
+    toolCallId: string | undefined,
+  ): Promise<string> {
+    const bodyJson = JSON.stringify({ url });
+
+    const response = await this.post(bodyJson, toolCallId);
+
+    if (response.status !== 200) {
+      let detail = '';
+      try {
+        detail = await response.text();
+      } catch {
+        // ignore — status code alone is informative enough for the
+        // fallback path that catches this.
+      }
+      throw new HttpFetchError(
+        response.status,
+        `Moonshot fetch request failed: HTTP ${String(response.status)}. ${detail}`.trim(),
+      );
+    }
+
+    return response.text();
+  }
+
+  private async post(bodyJson: string, toolCallId: string | undefined): Promise<Response> {
+    const accessToken = await this.resolveApiKey();
+    return this.fetchImpl(this.baseUrl, {
+      method: 'POST',
+      headers: {
+        ...this.defaultHeaders,
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'text/markdown',
+        'Content-Type': 'application/json',
+        ...(toolCallId !== undefined && toolCallId.length > 0
+          ? { 'X-Msh-Tool-Call-Id': toolCallId }
+          : {}),
+        ...this.customHeaders,
+      },
+      body: bodyJson,
+    });
+  }
+
+  private async resolveApiKey(): Promise<string> {
+    if (this.tokenProvider !== undefined) {
+      try {
+        const token = await this.tokenProvider.getAccessToken();
+        if (token.trim().length > 0) {
+          return token;
+        }
+        if (this.apiKey !== undefined && this.apiKey.length > 0) {
+          return this.apiKey;
+        }
+      } catch (error) {
+        if (this.apiKey !== undefined && this.apiKey.length > 0) {
+          return this.apiKey;
+        }
+        throw error;
+      }
+    }
+    if (this.apiKey !== undefined && this.apiKey.length > 0) {
+      return this.apiKey;
+    }
+    throw new Error('Moonshot fetch service is not configured: missing API key or token provider.');
+  }
+}
diff --git a/packages/agent-core/src/tools/providers/moonshot-web-search.ts b/packages/agent-core/src/tools/providers/moonshot-web-search.ts
new file mode 100644
index 000000000..f1ef6c18b
--- /dev/null
+++ b/packages/agent-core/src/tools/providers/moonshot-web-search.ts
@@ -0,0 +1,143 @@
+/**
+ * MoonshotWebSearchProvider — host-side `WebSearchProvider`.
+ *
+ * Auth uses a narrow bearer token provider per request. Host-specific
+ * default headers are supplied by runtime and request-level overrides
+ * come from `customHeaders`.
+ */
+
+import type { WebSearchProvider, WebSearchResult } from '../builtin';
+
+export interface BearerTokenProvider {
+  getAccessToken(options?: { readonly force?: boolean | undefined }): Promise<string>;
+}
+
+export interface MoonshotWebSearchProviderOptions {
+  tokenProvider?: BearerTokenProvider;
+  apiKey?: string;
+  baseUrl: string;
+  defaultHeaders?: Record<string, string>;
+  customHeaders?: Record<string, string>;
+  fetchImpl?: typeof fetch;
+}
+
+interface MoonshotSearchResult {
+  site_name?: string;
+  title?: string;
+  url?: string;
+  snippet?: string;
+  content?: string;
+  date?: string;
+  icon?: string;
+  mime?: string;
+}
+
+interface MoonshotSearchResponse {
+  search_results?: MoonshotSearchResult[];
+}
+
+export class MoonshotWebSearchProvider implements WebSearchProvider {
+  private readonly tokenProvider: BearerTokenProvider | undefined;
+  private readonly apiKey: string | undefined;
+  private readonly baseUrl: string;
+  private readonly defaultHeaders: Record<string, string>;
+  private readonly customHeaders: Record<string, string>;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: MoonshotWebSearchProviderOptions) {
+    this.tokenProvider = options.tokenProvider;
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl;
+    this.defaultHeaders = options.defaultHeaders ?? {};
+    this.customHeaders = options.customHeaders ?? {};
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+  }
+
+  async search(
+    query: string,
+    options?: { limit?: number; includeContent?: boolean; toolCallId?: string },
+  ): Promise<WebSearchResult[]> {
+    const body = {
+      text_query: query,
+      limit: options?.limit ?? 5,
+      enable_page_crawling: options?.includeContent ?? false,
+      timeout_seconds: 30,
+    };
+    const bodyJson = JSON.stringify(body);
+
+    const toolCallId = options?.toolCallId;
+    const response = await this.post(bodyJson, toolCallId);
+
+    if (response.status === 401) {
+      const detail = await safeReadText(response);
+      throw new Error(
+        `Moonshot search request failed: HTTP 401 (auth/unauthorized). ${detail}`.trim(),
+      );
+    }
+
+    if (response.status !== 200) {
+      const detail = await safeReadText(response);
+      throw new Error(
+        `Moonshot search request failed: HTTP ${String(response.status)}. ${detail}`.trim(),
+      );
+    }
+
+    const json = (await response.json()) as MoonshotSearchResponse;
+    const raw = Array.isArray(json.search_results) ? json.search_results : [];
+
+    return raw.map((r): WebSearchResult => {
+      const out: WebSearchResult = {
+        title: r.title ?? '',
+        url: r.url ?? '',
+        snippet: r.snippet ?? '',
+      };
+      if (typeof r.date === 'string' && r.date.length > 0) out.date = r.date;
+      if (typeof r.content === 'string' && r.content.length > 0) out.content = r.content;
+      return out;
+    });
+  }
+
+  private async post(bodyJson: string, toolCallId: string | undefined): Promise<Response> {
+    const accessToken = await this.resolveApiKey();
+    return this.fetchImpl(this.baseUrl, {
+      method: 'POST',
+      headers: {
+        ...this.defaultHeaders,
+        Authorization: `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+        ...(toolCallId !== undefined && toolCallId.length > 0
+          ? { 'X-Msh-Tool-Call-Id': toolCallId }
+          : {}),
+        ...this.customHeaders,
+      },
+      body: bodyJson,
+    });
+  }
+
+  private async resolveApiKey(): Promise<string> {
+    if (this.tokenProvider !== undefined) {
+      try {
+        return await this.tokenProvider.getAccessToken();
+      } catch (error) {
+        if (this.apiKey !== undefined && this.apiKey.length > 0) {
+          return this.apiKey;
+        }
+        throw error;
+      }
+    }
+    if (this.apiKey !== undefined && this.apiKey.length > 0) {
+      return this.apiKey;
+    }
+    throw new Error(
+      'Moonshot search service is not configured: missing API key or token provider.',
+    );
+  }
+}
+
+async function safeReadText(response: Response): Promise<string> {
+  try {
+    return await response.text();
+  } catch {
+    return '';
+  }
+}
diff --git a/packages/agent-core/src/tools/store.ts b/packages/agent-core/src/tools/store.ts
new file mode 100644
index 000000000..60279b68a
--- /dev/null
+++ b/packages/agent-core/src/tools/store.ts
@@ -0,0 +1,13 @@
+export interface ToolStoreData {}
+
+export type ToolStoreKey = Extract<keyof ToolStoreData, string>;
+
+export interface ToolStore {
+  get<K extends ToolStoreKey>(key: K): ToolStoreData[K] | undefined;
+  set<K extends ToolStoreKey>(key: K, value: ToolStoreData[K]): void;
+}
+
+export interface ToolStoreUpdate<K extends ToolStoreKey = ToolStoreKey> {
+  readonly key: K;
+  readonly value: ToolStoreData[K];
+}
diff --git a/packages/agent-core/src/tools/support/file-type.ts b/packages/agent-core/src/tools/support/file-type.ts
new file mode 100644
index 000000000..56e40529d
--- /dev/null
+++ b/packages/agent-core/src/tools/support/file-type.ts
@@ -0,0 +1,383 @@
+/**
+ * file-type — magic-byte + extension detection. No npm dependency.
+ */
+
+export const MEDIA_SNIFF_BYTES = 512;
+
+export interface FileType {
+  readonly kind: 'text' | 'image' | 'video' | 'unknown';
+  readonly mimeType: string;
+}
+
+export const IMAGE_MIME_BY_SUFFIX: Readonly<Record<string, string>> = Object.freeze({
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.bmp': 'image/bmp',
+  '.tif': 'image/tiff',
+  '.tiff': 'image/tiff',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.heic': 'image/heic',
+  '.heif': 'image/heif',
+  '.avif': 'image/avif',
+  '.svgz': 'image/svg+xml',
+});
+
+export const VIDEO_MIME_BY_SUFFIX: Readonly<Record<string, string>> = Object.freeze({
+  '.mp4': 'video/mp4',
+  '.mpg': 'video/mpeg',
+  '.mpeg': 'video/mpeg',
+  '.mkv': 'video/x-matroska',
+  '.avi': 'video/x-msvideo',
+  '.mov': 'video/quicktime',
+  '.ogv': 'video/ogg',
+  '.wmv': 'video/x-ms-wmv',
+  '.webm': 'video/webm',
+  '.m4v': 'video/x-m4v',
+  '.flv': 'video/x-flv',
+  '.3gp': 'video/3gpp',
+  '.3g2': 'video/3gpp2',
+});
+
+const TEXT_MIME_BY_SUFFIX: Readonly<Record<string, string>> = Object.freeze({
+  '.svg': 'image/svg+xml',
+});
+
+export const NON_TEXT_SUFFIXES: ReadonlySet<string> = new Set<string>([
+  '.icns',
+  '.psd',
+  '.ai',
+  '.eps',
+  '.pdf',
+  '.doc',
+  '.docx',
+  '.dot',
+  '.dotx',
+  '.rtf',
+  '.odt',
+  '.xls',
+  '.xlsx',
+  '.xlsm',
+  '.xlt',
+  '.xltx',
+  '.xltm',
+  '.ods',
+  '.ppt',
+  '.pptx',
+  '.pptm',
+  '.pps',
+  '.ppsx',
+  '.odp',
+  '.pages',
+  '.numbers',
+  '.key',
+  '.zip',
+  '.rar',
+  '.7z',
+  '.tar',
+  '.gz',
+  '.tgz',
+  '.bz2',
+  '.xz',
+  '.zst',
+  '.lz',
+  '.lz4',
+  '.br',
+  '.cab',
+  '.ar',
+  '.deb',
+  '.rpm',
+  '.mp3',
+  '.wav',
+  '.flac',
+  '.ogg',
+  '.oga',
+  '.opus',
+  '.aac',
+  '.m4a',
+  '.wma',
+  '.ttf',
+  '.otf',
+  '.woff',
+  '.woff2',
+  '.exe',
+  '.dll',
+  '.so',
+  '.dylib',
+  '.bin',
+  '.apk',
+  '.ipa',
+  '.jar',
+  '.class',
+  '.pyc',
+  '.pyo',
+  '.wasm',
+  '.dmg',
+  '.iso',
+  '.img',
+  '.sqlite',
+  '.sqlite3',
+  '.db',
+  '.db3',
+]);
+
+const ASF_HEADER = Buffer.from([
+  0x30, 0x26, 0xb2, 0x75, 0x8e, 0x66, 0xcf, 0x11, 0xa6, 0xd9, 0x00, 0xaa, 0x00, 0x62, 0xce, 0x6c,
+]);
+
+const FTYP_IMAGE_BRANDS: Readonly<Record<string, string>> = Object.freeze({
+  avif: 'image/avif',
+  avis: 'image/avif',
+  heic: 'image/heic',
+  heif: 'image/heif',
+  heix: 'image/heif',
+  hevc: 'image/heic',
+  mif1: 'image/heif',
+  msf1: 'image/heif',
+});
+
+const FTYP_VIDEO_BRANDS: Readonly<Record<string, string>> = Object.freeze({
+  isom: 'video/mp4',
+  iso2: 'video/mp4',
+  iso5: 'video/mp4',
+  mp41: 'video/mp4',
+  mp42: 'video/mp4',
+  avc1: 'video/mp4',
+  mp4v: 'video/mp4',
+  m4v: 'video/x-m4v',
+  qt: 'video/quicktime',
+  '3gp4': 'video/3gpp',
+  '3gp5': 'video/3gpp',
+  '3gp6': 'video/3gpp',
+  '3gp7': 'video/3gpp',
+  '3g2': 'video/3gpp2',
+});
+
+function toBuffer(data: Buffer | Uint8Array): Buffer {
+  return Buffer.isBuffer(data) ? data : Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+}
+
+function startsWith(buf: Buffer, prefix: Buffer | readonly number[]): boolean {
+  const needle = Buffer.isBuffer(prefix) ? prefix : Buffer.from(prefix);
+  if (buf.length < needle.length) return false;
+  for (let i = 0; i < needle.length; i += 1) {
+    if (buf[i] !== needle[i]) return false;
+  }
+  return true;
+}
+
+function sniffFtypBrand(header: Buffer): string | null {
+  if (header.length < 12) return null;
+  if (header.subarray(4, 8).toString('latin1') !== 'ftyp') return null;
+  const raw = header.subarray(8, 12).toString('latin1').toLowerCase();
+  // Python `.strip()` removes ASCII whitespace including trailing NULs via
+  // the `decode(..., errors="ignore")` semantics. We approximate: trim
+  // spaces and trailing NULs so brands like `qt  ` → `qt`.
+  // oxlint-disable-next-line no-control-regex
+  return raw.replaceAll(/[\s\u0000]+$/g, '').trim();
+}
+
+export function sniffMediaFromMagic(data: Buffer | Uint8Array): FileType | null {
+  const buf = toBuffer(data);
+  const header = buf.length > MEDIA_SNIFF_BYTES ? buf.subarray(0, MEDIA_SNIFF_BYTES) : buf;
+
+  if (startsWith(header, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) {
+    return { kind: 'image', mimeType: 'image/png' };
+  }
+  if (startsWith(header, [0xff, 0xd8, 0xff])) {
+    return { kind: 'image', mimeType: 'image/jpeg' };
+  }
+  if (startsWith(header, Buffer.from('GIF87a')) || startsWith(header, Buffer.from('GIF89a'))) {
+    return { kind: 'image', mimeType: 'image/gif' };
+  }
+  if (startsWith(header, Buffer.from('BM'))) {
+    return { kind: 'image', mimeType: 'image/bmp' };
+  }
+  if (
+    startsWith(header, [0x49, 0x49, 0x2a, 0x00]) ||
+    startsWith(header, [0x4d, 0x4d, 0x00, 0x2a])
+  ) {
+    return { kind: 'image', mimeType: 'image/tiff' };
+  }
+  if (startsWith(header, [0x00, 0x00, 0x01, 0x00])) {
+    return { kind: 'image', mimeType: 'image/x-icon' };
+  }
+  if (startsWith(header, Buffer.from('RIFF')) && header.length >= 12) {
+    const chunk = header.subarray(8, 12).toString('latin1');
+    if (chunk === 'WEBP') return { kind: 'image', mimeType: 'image/webp' };
+    if (chunk === 'AVI ') return { kind: 'video', mimeType: 'video/x-msvideo' };
+  }
+  if (startsWith(header, Buffer.from('FLV'))) {
+    return { kind: 'video', mimeType: 'video/x-flv' };
+  }
+  if (startsWith(header, ASF_HEADER)) {
+    return { kind: 'video', mimeType: 'video/x-ms-wmv' };
+  }
+  if (startsWith(header, [0x1a, 0x45, 0xdf, 0xa3])) {
+    const lowered = header.toString('latin1').toLowerCase();
+    if (lowered.includes('webm')) return { kind: 'video', mimeType: 'video/webm' };
+    if (lowered.includes('matroska')) return { kind: 'video', mimeType: 'video/x-matroska' };
+  }
+  const brand = sniffFtypBrand(header);
+  if (brand !== null && brand !== '') {
+    if (brand in FTYP_IMAGE_BRANDS) {
+      return { kind: 'image', mimeType: FTYP_IMAGE_BRANDS[brand]! };
+    }
+    if (brand in FTYP_VIDEO_BRANDS) {
+      return { kind: 'video', mimeType: FTYP_VIDEO_BRANDS[brand]! };
+    }
+  }
+  return null;
+}
+
+export interface ImageDimensions {
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * Best-effort pixel-dimension reader for common raster formats.
+ *
+ * Inspects only the fixed region near the start of the file where each
+ * format records its dimensions (the IHDR/DIB header, the RIFF chunk
+ * after the `WEBP` tag, or the first JPEG SOFn segment). Returns `null`
+ * for formats whose dimensions are not locatable from that region, or
+ * when the supplied buffer is too short to cover it.
+ */
+export function sniffImageDimensions(data: Buffer | Uint8Array): ImageDimensions | null {
+  const buf = toBuffer(data);
+
+  // PNG — IHDR is the first chunk; width/height are big-endian uint32
+  // at offsets 16 and 20.
+  if (startsWith(buf, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]) && buf.length >= 24) {
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+  }
+
+  // GIF — logical-screen width/height are little-endian uint16 at
+  // offsets 6 and 8.
+  if (
+    (startsWith(buf, Buffer.from('GIF87a')) || startsWith(buf, Buffer.from('GIF89a'))) &&
+    buf.length >= 10
+  ) {
+    return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+  }
+
+  // BMP — DIB header width/height are little-endian int32 at offsets 18
+  // and 22 (height may be negative for top-down bitmaps).
+  if (startsWith(buf, Buffer.from('BM')) && buf.length >= 26) {
+    return { width: buf.readInt32LE(18), height: Math.abs(buf.readInt32LE(22)) };
+  }
+
+  // WEBP — RIFF container; VP8/VP8L/VP8X each store dimensions
+  // differently in the chunk that follows the 'WEBP' tag.
+  if (startsWith(buf, Buffer.from('RIFF')) && buf.length >= 30) {
+    const fourCc = buf.subarray(12, 16).toString('latin1');
+    if (fourCc === 'VP8 ') {
+      return {
+        width: buf.readUInt16LE(26) & 0x3fff,
+        height: buf.readUInt16LE(28) & 0x3fff,
+      };
+    }
+    if (fourCc === 'VP8L' && buf.length >= 25) {
+      const bits = buf.readUInt32LE(21);
+      return {
+        width: (bits & 0x3fff) + 1,
+        height: ((bits >> 14) & 0x3fff) + 1,
+      };
+    }
+    if (fourCc === 'VP8X') {
+      const width = 1 + (buf[24]! | (buf[25]! << 8) | (buf[26]! << 16));
+      const height = 1 + (buf[27]! | (buf[28]! << 8) | (buf[29]! << 16));
+      return { width, height };
+    }
+  }
+
+  // JPEG — scan segment markers for a Start-Of-Frame (SOFn) marker,
+  // whose payload carries height/width as big-endian uint16.
+  if (startsWith(buf, [0xff, 0xd8])) {
+    let offset = 2;
+    while (offset + 9 < buf.length) {
+      if (buf[offset] !== 0xff) {
+        offset += 1;
+        continue;
+      }
+      const marker = buf[offset + 1]!;
+      // SOFn markers carry frame dimensions; skip SOF4/SOF8/SOF12 (0xc4/0xc8/0xcc).
+      if (
+        marker >= 0xc0 &&
+        marker <= 0xcf &&
+        marker !== 0xc4 &&
+        marker !== 0xc8 &&
+        marker !== 0xcc
+      ) {
+        return {
+          height: buf.readUInt16BE(offset + 5),
+          width: buf.readUInt16BE(offset + 7),
+        };
+      }
+      // Standalone markers (RSTn, SOI, EOI) carry no length field.
+      if (marker === 0xd8 || marker === 0xd9 || (marker >= 0xd0 && marker <= 0xd7)) {
+        offset += 2;
+        continue;
+      }
+      const segmentLength = buf.readUInt16BE(offset + 2);
+      if (segmentLength < 2) break;
+      offset += 2 + segmentLength;
+    }
+  }
+
+  return null;
+}
+
+function getSuffix(path: string): string {
+  const idx = path.lastIndexOf('.');
+  if (idx === -1) return '';
+  // POSIX `.suffix` treats `foo.tar.gz` → `.gz` and `foo/.bashrc` → '' (leading-dot is "no suffix").
+  const lastSep = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+  if (idx <= lastSep + 1) return '';
+  return path.slice(idx).toLowerCase();
+}
+
+export function detectFileType(path: string, header?: Buffer | Uint8Array): FileType {
+  const suffix = getSuffix(path);
+  let mediaHint: FileType | null = null;
+  if (suffix in TEXT_MIME_BY_SUFFIX) {
+    mediaHint = { kind: 'text', mimeType: TEXT_MIME_BY_SUFFIX[suffix]! };
+  } else if (suffix in IMAGE_MIME_BY_SUFFIX) {
+    mediaHint = { kind: 'image', mimeType: IMAGE_MIME_BY_SUFFIX[suffix]! };
+  } else if (suffix in VIDEO_MIME_BY_SUFFIX) {
+    mediaHint = { kind: 'video', mimeType: VIDEO_MIME_BY_SUFFIX[suffix]! };
+  }
+
+  // When a header is supplied, cross-validate against the ext hint —
+  // a mismatch reports `unknown` rather than blindly trusting the
+  // extension. When ext hint + sniff agree on kind, prefer the ext's
+  // mimeType so the reported MIME matches what the filename advertised.
+  // A disagreement on `kind` (e.g. `.mp4` with JPEG magic) still
+  // collapses to `unknown`.
+  if (header !== undefined) {
+    const buf = toBuffer(header);
+    const sniffed = sniffMediaFromMagic(buf);
+    if (sniffed) {
+      if (mediaHint) {
+        if (sniffed.kind !== mediaHint.kind) {
+          return { kind: 'unknown', mimeType: '' };
+        }
+        return mediaHint;
+      }
+      return sniffed;
+    }
+    if (buf.includes(0x00)) {
+      return { kind: 'unknown', mimeType: '' };
+    }
+    // No sniff and no NUL: fall through to hint / text / unknown logic.
+  }
+
+  if (mediaHint) return mediaHint;
+  if (NON_TEXT_SUFFIXES.has(suffix)) {
+    return { kind: 'unknown', mimeType: '' };
+  }
+  return { kind: 'text', mimeType: 'text/plain' };
+}
diff --git a/packages/agent-core/src/tools/support/git-worktree.ts b/packages/agent-core/src/tools/support/git-worktree.ts
new file mode 100644
index 000000000..fedf55e1a
--- /dev/null
+++ b/packages/agent-core/src/tools/support/git-worktree.ts
@@ -0,0 +1,98 @@
+/**
+ * Marker-based git work-tree detection. Never spawns `git`; failures return
+ * null so callers can fall back to their safer path.
+ */
+
+import * as posixPath from 'node:path/posix';
+import * as win32Path from 'node:path/win32';
+
+import type { Kaos } from '@moonshot-ai/kaos';
+
+import type { PathClass } from '../policies/path-access';
+
+const S_IFMT = 0o170000;
+const S_IFDIR = 0o040000;
+const S_IFREG = 0o100000;
+
+export interface GitWorkTreeMarker {
+  readonly dotGitPath: string;
+  readonly controlDirPath: string;
+}
+
+function pathMod(pathClass: PathClass): typeof posixPath {
+  return pathClass === 'win32' ? win32Path : posixPath;
+}
+
+export async function findGitWorkTreeMarker(
+  kaos: Kaos,
+  cwd: string,
+): Promise<GitWorkTreeMarker | null> {
+  const pathClass = kaos.pathClass();
+  const mod = pathMod(pathClass);
+  if (cwd.length === 0 || !mod.isAbsolute(cwd)) return null;
+
+  let current = mod.normalize(cwd);
+  for (let depth = 0; depth < 256; depth += 1) {
+    const dotGitPath = mod.join(current, '.git');
+    const hit = await probeGitMarker(kaos, dotGitPath, current, pathClass);
+    if (hit !== null) return hit;
+
+    const parent = mod.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+  return null;
+}
+
+async function probeGitMarker(
+  kaos: Kaos,
+  dotGitPath: string,
+  markerParent: string,
+  pathClass: PathClass,
+): Promise<GitWorkTreeMarker | null> {
+  let stat: Awaited<ReturnType<Kaos['stat']>>;
+  try {
+    stat = await kaos.stat(dotGitPath);
+  } catch {
+    return null;
+  }
+
+  if (isMode(stat.stMode, S_IFDIR)) return { dotGitPath, controlDirPath: dotGitPath };
+  if (!isMode(stat.stMode, S_IFREG)) return null;
+
+  let content: string;
+  try {
+    content = await kaos.readText(dotGitPath);
+  } catch {
+    return null;
+  }
+  const controlDirPath = parseGitDir(content, markerParent, pathClass);
+  return controlDirPath === undefined ? null : { dotGitPath, controlDirPath };
+}
+
+function isMode(stMode: number, mode: number): boolean {
+  return (stMode & S_IFMT) === mode;
+}
+
+/** Drop UTF-8 BOM and any leading whitespace (incl. `\r\n`) before content checks. */
+function stripLeadingNoise(content: string): string {
+  let s = content;
+  if (s.codePointAt(0) === 0xfeff) s = s.slice(1);
+  return s.trimStart();
+}
+
+function parseGitDir(
+  content: string,
+  markerParent: string,
+  pathClass: PathClass,
+): string | undefined {
+  const line = stripLeadingNoise(content).split(/\r?\n/, 1)[0]?.trim();
+  if (line === undefined || !line.startsWith('gitdir:')) return undefined;
+
+  const rawPath = line.slice('gitdir:'.length).trim();
+  if (rawPath.length === 0) return undefined;
+
+  const mod = pathMod(pathClass);
+  const absolute = mod.isAbsolute(rawPath) ? rawPath : mod.join(markerParent, rawPath);
+  return mod.normalize(absolute);
+}
diff --git a/packages/agent-core/src/tools/support/input-schema.ts b/packages/agent-core/src/tools/support/input-schema.ts
new file mode 100644
index 000000000..0c0fb2d14
--- /dev/null
+++ b/packages/agent-core/src/tools/support/input-schema.ts
@@ -0,0 +1,62 @@
+/**
+ * Shared helper for deriving the JSON Schema that a tool advertises to the
+ * model for its parameters.
+ *
+ * A tool's parameter schema describes the *input* the model is expected to
+ * supply. zod v4's `toJSONSchema` defaults to the *output* view, which marks
+ * any field carrying a chain-tail `.default()` as `required` — producing a
+ * schema that simultaneously declares a `default` and lists the field as
+ * required. That contradiction also makes the runtime AJV validator reject
+ * legal calls that omit the defaulted fields.
+ *
+ * Always render parameter schemas through this helper so the `io: 'input'`
+ * view is applied uniformly and defaulted fields remain optional, while the
+ * closed-object guard (`additionalProperties: false`) is kept so unknown
+ * arguments are still rejected.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Convert a zod schema into the input JSON Schema exposed to the model.
+ *
+ * @param schema - The zod schema describing the tool's parameters.
+ * @returns A draft-07 JSON Schema rendered with the input view.
+ */
+export function toInputJsonSchema(schema: z.ZodType): Record<string, unknown> {
+  const jsonSchema = z.toJSONSchema(schema, {
+    target: 'draft-7',
+    io: 'input',
+  });
+  closeObjectNodes(jsonSchema);
+  return jsonSchema;
+}
+
+/**
+ * Re-assert `additionalProperties: false` on every object node.
+ *
+ * The input view drops `additionalProperties: false` from `z.object` nodes
+ * because, before unknown-key stripping, an *input* object may legally carry
+ * extra keys. But a tool's parameter schema is a model-facing contract that
+ * the runtime validates with AJV only — there is no zod parse/strip step
+ * before dispatch — so without the closed-object guard a misspelled argument
+ * passes validation and is silently ignored. Restoring it keeps unknown
+ * arguments rejected, matching the output view's pre-input-view behavior.
+ *
+ * Nodes that already declare `additionalProperties` (e.g. `z.record`) are
+ * left untouched.
+ */
+function closeObjectNodes(value: unknown): void {
+  if (Array.isArray(value)) {
+    for (const item of value) closeObjectNodes(item);
+    return;
+  }
+  if (typeof value !== 'object' || value === null) return;
+  const node = value as Record<string, unknown>;
+  if (node['type'] === 'object' && node['additionalProperties'] === undefined) {
+    node['additionalProperties'] = false;
+  }
+  for (const child of Object.values(node)) {
+    closeObjectNodes(child);
+  }
+}
diff --git a/packages/agent-core/src/tools/support/list-directory.ts b/packages/agent-core/src/tools/support/list-directory.ts
new file mode 100644
index 000000000..433aa9f6e
--- /dev/null
+++ b/packages/agent-core/src/tools/support/list-directory.ts
@@ -0,0 +1,127 @@
+/**
+ * list-directory — compact 2-level directory tree for LLM context.
+ *
+ * Used by GlobTool when rejecting a `**`-leading pattern: appending a
+ * snapshot of the workspace root helps the LLM re-scope its pattern
+ * without a second round-trip.
+ *
+ * Width caps keep the system-prompt token budget bounded:
+ *   - Depth 0 (root):  up to LIST_DIR_ROOT_WIDTH entries
+ *   - Depth 1 (children of root dirs): up to LIST_DIR_CHILD_WIDTH entries
+ *   - Truncated levels show "... and N more" so the LLM knows more exists.
+ */
+
+import * as posixPath from 'node:path/posix';
+import * as win32Path from 'node:path/win32';
+
+import type { Kaos } from '@moonshot-ai/kaos';
+
+export const LIST_DIR_ROOT_WIDTH = 30;
+export const LIST_DIR_CHILD_WIDTH = 10;
+
+type PathClass = 'posix' | 'win32';
+
+interface Entry {
+  readonly name: string;
+  readonly isDir: boolean;
+}
+
+async function collectEntries(
+  kaos: Kaos,
+  dirPath: string,
+  maxWidth: number,
+  pathClass: PathClass,
+): Promise<{ entries: Entry[]; total: number; readable: boolean }> {
+  const all: Entry[] = [];
+  try {
+    for await (const fullPath of kaos.iterdir(dirPath)) {
+      const name = basename(fullPath, pathClass);
+      let isDir = false;
+      try {
+        const st = await kaos.stat(fullPath);
+        // StatResult mirrors POSIX stat; derive the file type from the
+        // mode bits (S_IFMT mask → S_IFDIR == 0o040000).
+        isDir = (st.stMode & 0o170000) === 0o040000;
+      } catch {
+        // Unreadable entries keep isDir=false; still list the name.
+      }
+      all.push({ name, isDir });
+    }
+  } catch {
+    return { entries: [], total: 0, readable: false };
+  }
+  all.sort((a, b) => {
+    if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+  return { entries: all.slice(0, maxWidth), total: all.length, readable: true };
+}
+
+function pathMod(pathClass: PathClass): typeof posixPath {
+  return pathClass === 'win32' ? win32Path : posixPath;
+}
+
+function basename(p: string, pathClass: PathClass): string {
+  return pathMod(pathClass).basename(p);
+}
+
+/**
+ * Return a 2-level tree listing of `workDir` suitable for inclusion in a
+ * tool error message. Returns `"(empty directory)"` if the directory is
+ * empty, or an error marker line if the directory itself is unreadable.
+ */
+export async function listDirectory(kaos: Kaos, workDir: string): Promise<string> {
+  const lines: string[] = [];
+  const pathClass = kaos.pathClass();
+  const { entries, total, readable } = await collectEntries(
+    kaos,
+    workDir,
+    LIST_DIR_ROOT_WIDTH,
+    pathClass,
+  );
+  if (!readable) return '[not readable]';
+  const remaining = total - entries.length;
+
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry === undefined) continue;
+    const { name, isDir } = entry;
+    const isLast = i === entries.length - 1 && remaining === 0;
+    const connector = isLast ? '└── ' : '├── ';
+
+    if (isDir) {
+      lines.push(`${connector}${name}/`);
+      const childPrefix = isLast ? '    ' : '│   ';
+      const childDir = joinPath(workDir, name, pathClass);
+      const child = await collectEntries(kaos, childDir, LIST_DIR_CHILD_WIDTH, pathClass);
+      if (!child.readable) {
+        lines.push(`${childPrefix}└── [not readable]`);
+        continue;
+      }
+      const childRemaining = child.total - child.entries.length;
+      for (let j = 0; j < child.entries.length; j++) {
+        const ce = child.entries[j];
+        if (ce === undefined) continue;
+        const cIsLast = j === child.entries.length - 1 && childRemaining === 0;
+        const cConnector = cIsLast ? '└── ' : '├── ';
+        const suffix = ce.isDir ? '/' : '';
+        lines.push(`${childPrefix}${cConnector}${ce.name}${suffix}`);
+      }
+      if (childRemaining > 0) {
+        lines.push(`${childPrefix}└── ... and ${String(childRemaining)} more`);
+      }
+    } else {
+      lines.push(`${connector}${name}`);
+    }
+  }
+
+  if (remaining > 0) {
+    lines.push(`└── ... and ${String(remaining)} more entries`);
+  }
+
+  return lines.length > 0 ? lines.join('\n') : '(empty directory)';
+}
+
+function joinPath(parent: string, child: string, pathClass: PathClass): string {
+  return pathMod(pathClass).join(parent, child);
+}
diff --git a/packages/agent-core/src/tools/support/result-builder.ts b/packages/agent-core/src/tools/support/result-builder.ts
new file mode 100644
index 000000000..8618d5671
--- /dev/null
+++ b/packages/agent-core/src/tools/support/result-builder.ts
@@ -0,0 +1,149 @@
+import type {
+  ExecutableToolErrorResult,
+  ExecutableToolSuccessResult,
+} from '../../loop/types';
+
+const DEFAULT_MAX_CHARS = 50_000;
+const DEFAULT_MAX_LINE_LENGTH = 2000;
+const TRUNCATION_MARKER = '[...truncated]';
+const TRUNCATION_MESSAGE = 'Output is truncated to fit in the message.';
+
+export interface ToolResultBuilderOptions {
+  readonly maxChars?: number;
+  readonly maxLineLength?: number | null;
+}
+
+export type ExecutableToolResultBuilderResult = (
+  | ExecutableToolSuccessResult
+  | ExecutableToolErrorResult
+) & {
+  readonly output: string;
+  readonly message: string;
+  readonly truncated: boolean;
+  readonly brief?: string;
+};
+
+export class ToolResultBuilder {
+  private readonly maxChars: number;
+  private readonly maxLineLength: number | null;
+
+  private readonly buffer: string[] = [];
+  private nCharsValue = 0;
+  private truncationHappened = false;
+
+  constructor(options: ToolResultBuilderOptions = {}) {
+    this.maxChars = options.maxChars ?? DEFAULT_MAX_CHARS;
+    this.maxLineLength =
+      options.maxLineLength === undefined ? DEFAULT_MAX_LINE_LENGTH : options.maxLineLength;
+
+    if (this.maxLineLength !== null && this.maxLineLength <= TRUNCATION_MARKER.length) {
+      throw new Error('maxLineLength must be greater than the truncation marker length.');
+    }
+  }
+
+  get nChars(): number {
+    return this.nCharsValue;
+  }
+
+  write(text: string): number {
+    if (this.nCharsValue >= this.maxChars) {
+      if (text.length > 0 && !this.truncationHappened) {
+        this.buffer.push(TRUNCATION_MARKER);
+        this.nCharsValue += TRUNCATION_MARKER.length;
+        this.truncationHappened = true;
+      }
+      return 0;
+    }
+
+    const lines = text.match(/[^\r\n]*(?:\r\n|[\n\r])|[^\r\n]+/g) ?? [];
+    if (lines.length === 0) return 0;
+
+    let charsWritten = 0;
+    for (const originalLine of lines) {
+      if (this.nCharsValue >= this.maxChars) {
+        if (!this.truncationHappened) {
+          this.buffer.push(TRUNCATION_MARKER);
+          this.nCharsValue += TRUNCATION_MARKER.length;
+          this.truncationHappened = true;
+        }
+        break;
+      }
+
+      const remainingChars = this.maxChars - this.nCharsValue;
+      const limit =
+        this.maxLineLength === null
+          ? remainingChars
+          : Math.min(remainingChars, this.maxLineLength);
+      let line = originalLine;
+      if (line.length > limit) {
+        const lineBreak = /[\r\n]+$/.exec(line)?.[0] ?? '';
+        const suffix = TRUNCATION_MARKER + lineBreak;
+        const effectiveMaxLength = Math.max(limit, suffix.length);
+        line = line.slice(0, effectiveMaxLength - suffix.length) + suffix;
+      }
+      if (line !== originalLine) {
+        this.truncationHappened = true;
+      }
+
+      this.buffer.push(line);
+      charsWritten += line.length;
+      this.nCharsValue += line.length;
+    }
+
+    return charsWritten;
+  }
+
+  ok(message = '', options: { readonly brief?: string } = {}): ExecutableToolResultBuilderResult {
+    let finalMessage = message;
+    if (finalMessage.length > 0 && !finalMessage.endsWith('.')) {
+      finalMessage += '.';
+    }
+    if (this.truncationHappened) {
+      finalMessage =
+        finalMessage.length === 0 ? TRUNCATION_MESSAGE : `${finalMessage} ${TRUNCATION_MESSAGE}`;
+    }
+
+    const output = this.buffer.join('');
+    const shouldAppendMessage =
+      finalMessage.length > 0 && (this.truncationHappened || output.length === 0);
+    return {
+      isError: false,
+      output: shouldAppendMessage
+        ? output.length === 0
+          ? finalMessage
+          : output.endsWith('\n')
+            ? `${output}${finalMessage}`
+            : `${output}\n${finalMessage}`
+        : output,
+      message: finalMessage,
+      truncated: this.truncationHappened,
+      brief: options.brief,
+    };
+  }
+
+  error(
+    message: string,
+    options: { readonly brief?: string } = {},
+  ): ExecutableToolResultBuilderResult {
+    const finalMessage = this.truncationHappened
+      ? message.length === 0
+        ? TRUNCATION_MESSAGE
+        : `${message} ${TRUNCATION_MESSAGE}`
+      : message;
+    const output = this.buffer.join('');
+    return {
+      isError: true,
+      output:
+        finalMessage.length === 0
+          ? output
+          : output.length === 0
+            ? finalMessage
+            : output.endsWith('\n')
+              ? `${output}${finalMessage}`
+              : `${output}\n${finalMessage}`,
+      message: finalMessage,
+      truncated: this.truncationHappened,
+      brief: options.brief,
+    };
+  }
+}
diff --git a/packages/agent-core/src/tools/support/rg-locator.ts b/packages/agent-core/src/tools/support/rg-locator.ts
new file mode 100644
index 000000000..a551c9083
--- /dev/null
+++ b/packages/agent-core/src/tools/support/rg-locator.ts
@@ -0,0 +1,363 @@
+/**
+ * rg-locator — hybrid ripgrep binary resolution.
+ *
+ * Lookup order (first hit wins):
+ *   1. System PATH (`which rg`) — fastest, respects developer setup
+ *   2. Bundled vendor binary (hook; not wired yet — `getVendorRgPath` is a stub)
+ *   3. `<KIMI_CODE_HOME>/bin/rg` — persistent cache for this app.
+ *   4. CDN download to <KIMI_CODE_HOME>/bin/ — one-off bootstrap
+ *
+ * If steps 1-4 all fail, callers receive a structured error they can
+ * turn into a user-facing "install ripgrep" hint instead of the naked
+ * `spawn rg ENOENT`.
+ */
+
+import { createHash } from 'node:crypto';
+import { createWriteStream, existsSync } from 'node:fs';
+import { chmod, mkdir, mkdtemp, readFile, rename, rm, stat } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+import { extract as extractTar } from 'tar';
+import { type Entry, fromBuffer as yauzlFromBuffer } from 'yauzl';
+
+import { abortable } from '../../utils/abort';
+
+const RG_VERSION = '15.0.0';
+const RG_BASE_URL = 'https://code.kimi.com/kimi-code/rg';
+const DOWNLOAD_TIMEOUT_MS = 600_000;
+const RG_ARCHIVE_SHA256: Record<string, string> = {
+  'ripgrep-15.0.0-aarch64-apple-darwin.tar.gz':
+    '98bb2e61e7277ba0ea72d2ae2592497fd8d2940934a16b122448d302a6637e3b',
+  'ripgrep-15.0.0-aarch64-pc-windows-msvc.zip':
+    '572709c8770cb7f9385d725cb06d2bcd9537ec24d4dd17b1be1d65a876f8b591',
+  'ripgrep-15.0.0-aarch64-unknown-linux-gnu.tar.gz':
+    '15f8cc2fab12d88491c54d49f38589922a9d6a7353c29b0a0856727bcdf80754',
+  'ripgrep-15.0.0-x86_64-apple-darwin.tar.gz':
+    '44128c733d127ddbda461e01225a68b5f9997cfe7635242a797f645ca674a71a',
+  'ripgrep-15.0.0-x86_64-pc-windows-msvc.zip':
+    '21a98bf42c4da97ca543c010e764cc6dec8b9b7538d05f8d21874016385e0860',
+  'ripgrep-15.0.0-x86_64-unknown-linux-musl.tar.gz':
+    '253ad0fd5fef0d64cba56c70dccdacc1916d4ed70ad057cc525fcdb0c3bbd2a7',
+};
+
+export type RgResolutionSource =
+  | 'system-path'
+  | 'vendor'
+  | 'share-bin-cached'
+  | 'share-bin-downloaded';
+
+export interface RgResolution {
+  readonly path: string;
+  readonly source: RgResolutionSource;
+}
+
+export interface EnsureRgPathOptions {
+  readonly shareDir?: string | undefined;
+  /**
+   * Cancels this caller's wait. A shared bootstrap download that is already in
+   * progress may continue so other callers can still use the same result.
+   */
+  readonly signal?: AbortSignal | undefined;
+}
+
+/**
+ * Resolve the absolute path to a usable `rg` binary, downloading it
+ * into `<shareDir>/bin/` if necessary. Multiple concurrent callers are
+ * serialized by a module-level lock so the download happens at most
+ * once per process.
+ */
+export async function ensureRgPath(options: EnsureRgPathOptions = {}): Promise<RgResolution> {
+  options.signal?.throwIfAborted();
+  const resolution = resolveRgPath(options.shareDir ?? getShareDir(), options.signal);
+  return options.signal === undefined ? resolution : abortable(resolution, options.signal);
+}
+
+async function resolveRgPath(
+  shareDir: string,
+  signal?: AbortSignal | undefined,
+): Promise<RgResolution> {
+  const existing = await findExistingRg(shareDir);
+  if (existing) return existing;
+  signal?.throwIfAborted();
+  return downloadRgWithLock(shareDir);
+}
+
+/**
+ * Pure-lookup variant for test harnesses that want to assert on the
+ * resolution order without triggering a real download.
+ */
+export async function findExistingRg(shareDir: string): Promise<RgResolution | undefined> {
+  const binName = rgBinaryName();
+  const systemRg = await whichRg();
+  if (systemRg !== undefined) return { path: systemRg, source: 'system-path' };
+  const vendorPath = getVendorRgPath(binName);
+  if (vendorPath !== undefined && (await isExecutableFile(vendorPath))) {
+    return { path: vendorPath, source: 'vendor' };
+  }
+  const cachePath = join(shareDir, 'bin', binName);
+  if (await isExecutableFile(cachePath)) {
+    return { path: cachePath, source: 'share-bin-cached' };
+  }
+  return undefined;
+}
+
+let downloadPromise: Promise<RgResolution> | undefined;
+async function downloadRgWithLock(shareDir: string): Promise<RgResolution> {
+  if (downloadPromise !== undefined) return downloadPromise;
+  downloadPromise = (async () => {
+    try {
+      const existing = await findExistingRg(shareDir);
+      if (existing) return existing;
+      const binPath = await downloadAndInstallRg(shareDir);
+      return { path: binPath, source: 'share-bin-downloaded' };
+    } finally {
+      downloadPromise = undefined;
+    }
+  })();
+  return downloadPromise;
+}
+
+function rgBinaryName(): string {
+  return process.platform === 'win32' ? 'rg.exe' : 'rg';
+}
+
+function getShareDir(): string {
+  const override = process.env['KIMI_CODE_HOME'];
+  if (override !== undefined && override !== '') return override;
+  return join(homedir(), '.kimi-code');
+}
+
+function getVendorRgPath(_binName: string): string | undefined {
+  return undefined;
+}
+
+async function whichRg(): Promise<string | undefined> {
+  const pathEnv = process.env['PATH'] ?? '';
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const binName = rgBinaryName();
+  for (const dir of pathEnv.split(sep)) {
+    if (dir === '') continue;
+    const candidate = join(dir, binName);
+    try {
+      const st = await stat(candidate);
+      if (st.isFile()) return candidate;
+    } catch {
+      /* not here, try next */
+    }
+  }
+  return undefined;
+}
+
+async function isExecutableFile(p: string): Promise<boolean> {
+  try {
+    const st = await stat(p);
+    return st.isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** @internal for tests — rust-style `<arch>-<vendor>-<os>` target triple. */
+export function detectTarget(): string | undefined {
+  const arch = process.arch === 'x64' ? 'x86_64' : process.arch === 'arm64' ? 'aarch64' : undefined;
+  if (arch === undefined) return undefined;
+
+  if (process.platform === 'darwin') return `${arch}-apple-darwin`;
+  if (process.platform === 'linux') {
+    return arch === 'x86_64' ? 'x86_64-unknown-linux-musl' : 'aarch64-unknown-linux-gnu';
+  }
+  if (process.platform === 'win32') return `${arch}-pc-windows-msvc`;
+  return undefined;
+}
+
+async function downloadAndInstallRg(shareDir: string): Promise<string> {
+  const target = detectTarget();
+  if (target === undefined) {
+    throw new Error(
+      `Unsupported platform/arch for ripgrep download: ${process.platform}/${process.arch}`,
+    );
+  }
+
+  // Windows ripgrep releases ship as `.zip`; macOS / Linux as `.tar.gz`.
+  // The extraction branch inside the try block handles the format-specific
+  // unpack; the fetch + download-to-tmp pipeline is identical.
+  const isWindows = target.includes('windows');
+  const archiveExt = isWindows ? 'zip' : 'tar.gz';
+  const archiveName = `ripgrep-${RG_VERSION}-${target}.${archiveExt}`;
+  const expectedSha256 = RG_ARCHIVE_SHA256[archiveName];
+  if (expectedSha256 === undefined) {
+    throw new Error(`No pinned SHA-256 is configured for ripgrep archive ${archiveName}`);
+  }
+  const url = `${RG_BASE_URL}/${archiveName}`;
+
+  const binDir = join(shareDir, 'bin');
+  await mkdir(binDir, { recursive: true });
+  const destination = join(binDir, rgBinaryName());
+
+  const tmp = await mkdtemp(join(tmpdir(), 'kimi-rg-'));
+  try {
+    const archivePath = join(tmp, archiveName);
+
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => {
+      controller.abort();
+    }, DOWNLOAD_TIMEOUT_MS);
+    let resp: Response;
+    try {
+      resp = await fetch(url, { signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+    if (!resp.ok || resp.body === null) {
+      throw new Error(`Failed to download ripgrep: HTTP ${String(resp.status)} ${resp.statusText}`);
+    }
+    const write = createWriteStream(archivePath);
+    // Readable.fromWeb is typed as accepting a web ReadableStream; the
+    // undici/fetch body matches that shape at runtime.
+    await pipeline(Readable.fromWeb(resp.body as never), write);
+    await verifyArchiveChecksum(archivePath, archiveName, expectedSha256);
+
+    if (isWindows) {
+      await extractRgFromZip(archivePath, destination);
+      // Windows does not need `chmod +x`: execution is gated by the
+      // `.exe` extension + NTFS ACLs, which are already correct.
+    } else {
+      const extractDir = join(tmp, 'extract');
+      await mkdir(extractDir, { recursive: true });
+      // tar.gz uses hard-coded prefix because the CDN's tar.gz layout is stable
+      // and known from upstream releases; zip branch uses basename matching as
+      // a looser contract so a CDN prefix change doesn't silently fall through.
+      await extractTar({
+        file: archivePath,
+        cwd: extractDir,
+        gzip: true,
+        filter: (entryPath: string) => entryPath.endsWith(`/${rgBinaryName()}`),
+      });
+      const extracted = join(extractDir, `ripgrep-${RG_VERSION}-${target}`, rgBinaryName());
+      if (!existsSync(extracted)) {
+        throw new Error(
+          `Ripgrep archive did not contain expected binary at ${extracted}. ` +
+            'CDN content may have changed.',
+        );
+      }
+      await rename(extracted, destination);
+      await chmod(destination, 0o755);
+    }
+    return destination;
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+}
+
+/** @internal for tests — fail closed before extracting downloaded bytes. */
+export async function verifyArchiveChecksum(
+  archivePath: string,
+  archiveName: string,
+  expectedSha256: string,
+): Promise<void> {
+  const actualSha256 = createHash('sha256')
+    .update(await readFile(archivePath))
+    .digest('hex');
+  if (actualSha256 !== expectedSha256) {
+    throw new Error(
+      `Ripgrep archive checksum mismatch for ${archiveName}: expected ${expectedSha256}, ` +
+        `got ${actualSha256}. CDN content may have changed.`,
+    );
+  }
+}
+
+/**
+ * Read the downloaded `.zip` at `archivePath`, find the `rg.exe` entry
+ * (basename match), and stream it out to `destination`. Throws with
+ * the shared "CDN content may have
+ * changed" sentinel when the archive holds no matching entry — same
+ * failure semantics as the tar.gz path's `existsSync(extracted)` gate
+ * so callers see a single actionable message.
+ */
+export async function extractRgFromZip(archivePath: string, destination: string): Promise<void> {
+  const buf = await readFile(archivePath);
+  const binName = rgBinaryName(); // 'rg.exe' on win32
+  await new Promise<void>((resolve, reject) => {
+    yauzlFromBuffer(buf, { lazyEntries: true }, (openErr, zipfile) => {
+      if (openErr !== null || zipfile === undefined) {
+        reject(new Error(`Failed to open ripgrep archive: ${openErr?.message ?? 'unknown error'}`));
+        return;
+      }
+      let found = false;
+      const onEntry = (entry: Entry): void => {
+        // Match on basename (not full path) — keeps the matcher robust
+        // against CDN repackaging tweaks (e.g. an unexpected
+        // `ripgrep-X.Y.Z-TARGET/` prefix change).
+        if (basename(entry.fileName) !== binName) {
+          zipfile.readEntry();
+          return;
+        }
+        found = true;
+        zipfile.openReadStream(entry, (streamErr, stream) => {
+          if (streamErr !== null) {
+            reject(
+              new Error(`Failed to read ${entry.fileName} from archive: ${streamErr.message}`),
+            );
+            zipfile.close();
+            return;
+          }
+          const out = createWriteStream(destination);
+          void (async () => {
+            try {
+              await pipeline(stream, out);
+              zipfile.close();
+              resolve();
+            } catch (error) {
+              zipfile.close();
+              reject(error instanceof Error ? error : new Error(String(error)));
+            }
+          })();
+        });
+      };
+      zipfile.on('entry', onEntry);
+      zipfile.on('end', () => {
+        // With lazyEntries:true, `end` fires only after readEntry() is called
+        // for every central-directory entry. We stop calling readEntry() once
+        // `found` becomes true, so `end` only reaches this branch on the
+        // not-found path.
+        if (!found) {
+          reject(
+            new Error(
+              `Ripgrep archive did not contain expected binary '${binName}'. ` +
+                'CDN content may have changed.',
+            ),
+          );
+        }
+      });
+      zipfile.on('error', (err: Error) => {
+        reject(err);
+      });
+      zipfile.readEntry();
+    });
+  });
+}
+
+/**
+ * User-facing error message to show when `ensureRgPath` throws. Kept
+ * in one place so the Grep / Glob / Bash plumbing can reuse it.
+ */
+export function rgUnavailableMessage(cause: unknown): string {
+  const detail =
+    cause instanceof Error ? cause.message : typeof cause === 'string' ? cause : 'unknown error';
+  const shareBin = join(getShareDir(), 'bin', rgBinaryName());
+  return (
+    `ripgrep (rg) is not available and the automatic bootstrap failed.\n` +
+    `\n` +
+    `Error: ${detail}\n` +
+    `\n` +
+    `Fix options:\n` +
+    `  macOS:   brew install ripgrep\n` +
+    `  Ubuntu:  sudo apt-get install ripgrep\n` +
+    `  Other:   https://github.com/BurntSushi/ripgrep#installation\n` +
+    `\n` +
+    `Alternatively, drop a static rg binary at ${shareBin}`
+  );
+}
diff --git a/packages/agent-core/src/tools/support/workspace.ts b/packages/agent-core/src/tools/support/workspace.ts
new file mode 100644
index 000000000..c108c7c88
--- /dev/null
+++ b/packages/agent-core/src/tools/support/workspace.ts
@@ -0,0 +1,17 @@
+/**
+ * WorkspaceConfig — defines the roots that tools are allowed to access.
+ *
+ * Injected through each Tool's constructor. Not passed through Runtime:
+ * the Runtime keeps a small fixed shape and workspace limits live on
+ * the Tool side.
+ *
+ * Paths should already be canonicalized lexically (absolute + normalized);
+ * callers are responsible for normalizing before constructing this config.
+ */
+
+export interface WorkspaceConfig {
+  /** Primary workspace directory (absolute, canonicalized). */
+  readonly workspaceDir: string;
+  /** Extra allowed roots (e.g. `--add-dir` CLI flag). */
+  readonly additionalDirs: readonly string[];
+}
diff --git a/packages/agent-core/src/utils/abort.ts b/packages/agent-core/src/utils/abort.ts
new file mode 100644
index 000000000..61e3f1685
--- /dev/null
+++ b/packages/agent-core/src/utils/abort.ts
@@ -0,0 +1,61 @@
+export function abortError(): Error {
+  const error = new Error('Aborted');
+  error.name = 'AbortError';
+  return error;
+}
+
+export function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  signal.throwIfAborted();
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => {
+      reject(abortError());
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    promise.then(resolve, reject).finally(() => {
+      signal.removeEventListener('abort', onAbort);
+    });
+  });
+}
+
+export function linkAbortSignal(source: AbortSignal, target: AbortController): () => void {
+  const onAbort = () => {
+    target.abort(source.reason);
+  };
+  if (source.aborted) {
+    onAbort();
+    return () => {};
+  }
+  source.addEventListener('abort', onAbort, { once: true });
+  return () => {
+    source.removeEventListener('abort', onAbort);
+  };
+}
+
+export interface DeadlineAbortSignal {
+  readonly signal: AbortSignal;
+  readonly timedOut: () => boolean;
+  readonly clear: () => void;
+}
+
+export function createDeadlineAbortSignal(
+  source: AbortSignal,
+  timeoutMs: number,
+): DeadlineAbortSignal {
+  const controller = new AbortController();
+  const unlinkAbortSignal = linkAbortSignal(source, controller);
+  let didTimeout = false;
+  let timeout: ReturnType<typeof setTimeout> | undefined = setTimeout(() => {
+    didTimeout = true;
+    controller.abort(abortError());
+  }, timeoutMs);
+
+  return {
+    signal: controller.signal,
+    timedOut: () => didTimeout,
+    clear: () => {
+      if (timeout !== undefined) clearTimeout(timeout);
+      timeout = undefined;
+      unlinkAbortSignal();
+    },
+  };
+}
diff --git a/packages/agent-core/src/utils/completion-budget.ts b/packages/agent-core/src/utils/completion-budget.ts
new file mode 100644
index 000000000..abcf027bb
--- /dev/null
+++ b/packages/agent-core/src/utils/completion-budget.ts
@@ -0,0 +1,153 @@
+import type {
+  ChatProvider,
+  Message,
+  ModelCapability,
+  Tool,
+} from '@moonshot-ai/kosong';
+
+import {
+  estimateTokens,
+  estimateTokensForMessages,
+  estimateTokensForTools,
+} from './tokens';
+
+/**
+ * Desired completion-token budget for the next LLM step.
+ *
+ * The budget is a request, not a guarantee: it is clamped against the
+ * current input size and the model's context window before being applied
+ * to the provider. This avoids two failure modes for Kimi reasoning
+ * models:
+ *   1. A small cap can return HTTP 200 with empty `content` because the
+ *      whole budget was spent on `reasoning_content`.
+ *   2. A large cap may exceed the remaining context window and trigger
+ *      `Invalid request: Your request exceeded model token limit`.
+ */
+export interface CompletionBudget {
+  /** Desired completion budget when the model context window allows it. */
+  readonly desired: number;
+  /**
+   * Safety margin reserved between current input and the context limit,
+   * to absorb tokenizer estimation error and provider-side overhead.
+   */
+  readonly safetyMargin?: number | undefined;
+}
+
+const MIN_FLOOR = 1;
+const DEFAULT_SAFETY_MARGIN = 1024;
+const DEFAULT_DESIRED_BUDGET = 32000;
+
+/**
+ * Resolve the completion budget for a turn from configuration and Kimi
+ * environment variables.
+ *
+ * Priority (first wins): `KIMI_MODEL_MAX_COMPLETION_TOKENS`,
+ * `KIMI_MODEL_MAX_TOKENS` (legacy alias), `reservedContextSize`,
+ * `DEFAULT_DESIRED_BUDGET` (32000, preserves pre-PR-2332 behavior).
+ *
+ * Operators can opt out of clamping entirely by setting the env var to
+ * `0` or a negative integer; in that case this function returns
+ * `undefined`, which `applyCompletionBudget` treats as a no-op.
+ */
+export function resolveCompletionBudget(args: {
+  readonly reservedContextSize?: number | undefined;
+  readonly env?: NodeJS.ProcessEnv | undefined;
+}): CompletionBudget | undefined {
+  const env = args.env ?? process.env;
+  const fromNew = parseEnvBudget(env['KIMI_MODEL_MAX_COMPLETION_TOKENS']);
+  if (fromNew !== 'absent') {
+    return fromNew === 'disabled' ? undefined : { desired: fromNew };
+  }
+  const fromLegacy = parseEnvBudget(env['KIMI_MODEL_MAX_TOKENS']);
+  if (fromLegacy !== 'absent') {
+    return fromLegacy === 'disabled' ? undefined : { desired: fromLegacy };
+  }
+  if (args.reservedContextSize !== undefined && args.reservedContextSize > 0) {
+    return { desired: args.reservedContextSize };
+  }
+  return { desired: DEFAULT_DESIRED_BUDGET };
+}
+
+type EnvBudget = number | 'disabled' | 'absent';
+
+function parseEnvBudget(raw: string | undefined): EnvBudget {
+  if (raw === undefined || raw === '') return 'absent';
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isInteger(n)) return 'absent';
+  if (n <= 0) return 'disabled';
+  return n;
+}
+
+/**
+ * Compute the effective `max_completion_tokens` cap for the next request.
+ *
+ *   cap = clamp(desired, MIN_FLOOR, max_context_tokens - input - safetyMargin)
+ *
+ * `input` accounts for everything the provider will actually serialize:
+ * the conversation history, the system prompt, and the tool schemas.
+ * Counting only `messages` underestimates by enough to push a near-limit
+ * request past the model context window.
+ *
+ * When the model context size is unknown, the desired value is returned
+ * unchanged (floored at `MIN_FLOOR`).
+ *
+ * When the remaining window is non-positive (input already at or above
+ * the limit), `MIN_FLOOR` is returned — we can't honor a meaningful cap
+ * and the API will surface the overflow on its own.
+ *
+ * Note: the floor never exceeds `remaining`, so a near-full context
+ * cannot be pushed past the limit by `MIN_FLOOR` itself.
+ */
+export function computeCompletionBudgetCap(args: {
+  readonly budget: CompletionBudget;
+  readonly capability: ModelCapability | undefined;
+  readonly messages: readonly Message[];
+  readonly systemPrompt?: string | undefined;
+  readonly tools?: readonly Tool[] | undefined;
+}): number {
+  const desired = args.budget.desired;
+  const safetyMargin = args.budget.safetyMargin ?? DEFAULT_SAFETY_MARGIN;
+  const maxCtx = args.capability?.max_context_tokens ?? 0;
+  if (maxCtx <= 0) {
+    return Math.max(MIN_FLOOR, desired);
+  }
+  const input =
+    estimateTokensForMessages([...args.messages]) +
+    estimateTokens(args.systemPrompt ?? '') +
+    estimateTokensForTools(args.tools ?? []);
+  const remaining = maxCtx - input - safetyMargin;
+  if (remaining <= 0) {
+    return MIN_FLOOR;
+  }
+  return Math.max(MIN_FLOOR, Math.min(desired, remaining));
+}
+
+/**
+ * Apply a completion budget to a provider via its optional
+ * `withMaxCompletionTokens` capability. Returns the original provider
+ * unchanged when no budget is configured or the provider opts out.
+ *
+ * The returned provider is intentionally a shallow clone that shares the
+ * original's HTTP client. Callers MUST treat it as a single-step value
+ * and NOT persist it back to durable agent state — see the F3 discussion
+ * in `KimiChatProvider._clone()`.
+ */
+export function applyCompletionBudget(args: {
+  readonly provider: ChatProvider;
+  readonly budget: CompletionBudget | undefined;
+  readonly capability: ModelCapability | undefined;
+  readonly messages: readonly Message[];
+  readonly systemPrompt?: string | undefined;
+  readonly tools?: readonly Tool[] | undefined;
+}): ChatProvider {
+  if (args.budget === undefined) return args.provider;
+  if (args.provider.withMaxCompletionTokens === undefined) return args.provider;
+  const cap = computeCompletionBudgetCap({
+    budget: args.budget,
+    capability: args.capability,
+    messages: args.messages,
+    systemPrompt: args.systemPrompt,
+    tools: args.tools,
+  });
+  return args.provider.withMaxCompletionTokens(cap);
+}
diff --git a/packages/agent-core/src/utils/environment.ts b/packages/agent-core/src/utils/environment.ts
new file mode 100644
index 000000000..a69065a1b
--- /dev/null
+++ b/packages/agent-core/src/utils/environment.ts
@@ -0,0 +1,186 @@
+/**
+ * Environment — cross-platform probe of OS / shell.
+ *
+ * Detection is a pure function of injected probes (`platform` / `arch` /
+ * `release` / `env` / `isFile` / `findExecutable`) so the same suite runs
+ * identically on any host OS. `detectEnvironmentFromNode()` bundles the
+ * Node defaults for production callers.
+ *
+ * On Windows the probe expects Git Bash (the canonical POSIX shell that
+ * ships with Git for Windows). If it cannot be located the function
+ * throws `KimiError` with code `shell.git_bash_not_found`; the SDK layer
+ * can wrap that into a user-facing install hint. Set `KIMI_SHELL_PATH`
+ * to override.
+ */
+
+import { constants as fsConstants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import * as nodeOs from 'node:os';
+
+import { ErrorCodes, KimiError } from '#/errors';
+
+// `OsKind` carries 'macOS' / 'Linux' / 'Windows' for known platforms and
+// falls back to the raw `process.platform` string for unknown ones (e.g.
+// 'freebsd'). Typed as `string` so the union isn't inhabited-by-string.
+export type OsKind = string;
+export type ShellName = 'bash' | 'sh';
+
+export interface Environment {
+  readonly osKind: OsKind;
+  readonly osArch: string;
+  readonly osVersion: string;
+  readonly shellName: ShellName;
+  readonly shellPath: string;
+}
+
+export interface EnvironmentDeps {
+  // Accepts the full Node `Platform` enum plus arbitrary strings for
+  // forward-compatible OS kinds.
+  readonly platform: string;
+  readonly arch: string;
+  readonly release: string;
+  readonly env: Record<string, string | undefined>;
+  readonly isFile: (path: string) => Promise<boolean>;
+  readonly findExecutable: (name: string) => Promise<string | undefined>;
+}
+
+function resolveOsKind(platform: string): OsKind {
+  switch (platform) {
+    case 'darwin':
+      return 'macOS';
+    case 'linux':
+      return 'Linux';
+    case 'win32':
+      return 'Windows';
+    default:
+      return platform;
+  }
+}
+
+export async function detectEnvironment(deps: EnvironmentDeps): Promise<Environment> {
+  const osKind = resolveOsKind(deps.platform);
+  const osArch = deps.arch;
+  const osVersion = deps.release;
+
+  if (deps.platform === 'win32') {
+    const shellPath = await locateWindowsGitBash(deps);
+    return { osKind, osArch, osVersion, shellName: 'bash', shellPath };
+  }
+
+  const candidates: readonly string[] = ['/bin/bash', '/usr/bin/bash', '/usr/local/bin/bash'];
+  let found: string | undefined;
+  for (const p of candidates) {
+    if (await deps.isFile(p)) {
+      found = p;
+      break;
+    }
+  }
+  if (found !== undefined) {
+    return { osKind, osArch, osVersion, shellName: 'bash', shellPath: found };
+  }
+  return { osKind, osArch, osVersion, shellName: 'sh', shellPath: '/bin/sh' };
+}
+
+async function locateWindowsGitBash(deps: EnvironmentDeps): Promise<string> {
+  const checked: string[] = [];
+
+  const override = deps.env['KIMI_SHELL_PATH']?.trim();
+  if (override !== undefined && override.length > 0) {
+    checked.push(override);
+    if (await deps.isFile(override)) {
+      return override;
+    }
+  }
+
+  const gitExe = await deps.findExecutable('git.exe');
+  if (gitExe !== undefined) {
+    const inferred = inferGitBashFromGitExe(gitExe);
+    if (inferred !== undefined) {
+      checked.push(inferred);
+      if (await deps.isFile(inferred)) {
+        return inferred;
+      }
+    }
+  }
+
+  const candidates: string[] = [
+    'C:\\Program Files\\Git\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+  ];
+  const localAppData = deps.env['LOCALAPPDATA']?.trim();
+  if (localAppData !== undefined && localAppData.length > 0) {
+    candidates.push(`${localAppData}\\Programs\\Git\\bin\\bash.exe`);
+  }
+  for (const candidate of candidates) {
+    checked.push(candidate);
+    if (await deps.isFile(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new KimiError(
+    ErrorCodes.SHELL_GIT_BASH_NOT_FOUND,
+    `Git Bash was not found on this Windows host. Install Git for Windows from https://gitforwindows.org/ or set KIMI_SHELL_PATH to a bash.exe. Checked: ${checked.join(', ')}.`,
+  );
+}
+
+// Most Git for Windows installs put `git.exe` in `<root>\cmd\git.exe`,
+// with bash at `<root>\bin\bash.exe`. Portable installs sometimes put
+// both in `<root>\bin\`. Walk back to the parent of `cmd` / `bin` and
+// re-anchor under `bin\bash.exe`.
+function inferGitBashFromGitExe(gitExe: string): string | undefined {
+  const sep = gitExe.includes('\\') ? '\\' : '/';
+  const parts = gitExe.split(sep);
+  for (let i = parts.length - 2; i >= 0; i -= 1) {
+    const segment = parts[i];
+    if (segment === 'cmd' || segment === 'bin') {
+      const root = parts.slice(0, i).join(sep);
+      return root.length === 0 ? `bin${sep}bash.exe` : `${root}${sep}bin${sep}bash.exe`;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Production convenience — derive the deps bag from Node's ambient surface.
+ */
+export async function detectEnvironmentFromNode(): Promise<Environment> {
+  const platform = process.platform;
+  const env = process.env as Record<string, string | undefined>;
+  const isFile = async (path: string): Promise<boolean> => {
+    try {
+      await access(path, fsConstants.F_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  return detectEnvironment({
+    platform,
+    arch: process.arch,
+    release: nodeOs.release(),
+    env,
+    isFile,
+    findExecutable: (name: string) => findExecutableOnPath(name, env['PATH'], platform, isFile),
+  });
+}
+
+async function findExecutableOnPath(
+  name: string,
+  pathEnv: string | undefined,
+  platform: string,
+  isFile: (p: string) => Promise<boolean>,
+): Promise<string | undefined> {
+  if (pathEnv === undefined || pathEnv.length === 0) return undefined;
+  const listSep = platform === 'win32' ? ';' : ':';
+  const dirSep = platform === 'win32' ? '\\' : '/';
+  for (const rawDir of pathEnv.split(listSep)) {
+    const dir = rawDir.trim();
+    if (dir.length === 0) continue;
+    const candidate = dir.endsWith(dirSep) ? `${dir}${name}` : `${dir}${dirSep}${name}`;
+    if (await isFile(candidate)) {
+      return candidate;
+    }
+  }
+  return undefined;
+}
diff --git a/packages/agent-core/src/utils/fs.ts b/packages/agent-core/src/utils/fs.ts
new file mode 100644
index 000000000..79aef2e49
--- /dev/null
+++ b/packages/agent-core/src/utils/fs.ts
@@ -0,0 +1,187 @@
+/**
+ * Low-level POSIX durability primitives.
+ *
+ * Two concerns that every durable write must handle:
+ *   1. file *contents* — solved by `fh.sync()` after the write
+ *   2. directory *entries* — solved by opening the parent directory and
+ *      calling `fh.sync()` on the directory handle
+ *
+ * `fh.sync()` on a file does NOT guarantee that the directory entry
+ * pointing at that file has been committed. On POSIX a crash between
+ * the file-content fsync and the parent-directory fsync can leave the
+ * file's bytes on disk with no visible name. The primary durable path
+ * is POSIX; Windows is best-effort — NTFS's MoveFileEx commits the
+ * dirent inside the file fsync, so a separate directory fsync is a
+ * no-op (and EISDIR-fails on `open(dir, 'r')`).
+ */
+import { randomBytes } from 'node:crypto';
+import { closeSync, fsyncSync, openSync } from 'node:fs';
+import * as nodeFs from 'node:fs';
+import { open, rename, unlink } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+/**
+ * Open a directory read-only and fsync it, then close. Used to make a
+ * freshly-created or renamed file's directory entry durable.
+ *
+ * Windows: noop. `open(dir, 'r')` throws EISDIR, and NTFS commits the
+ * dirent transaction inside the file fsync anyway — the separate dir
+ * fsync would buy nothing even if we could issue it.
+ */
+export async function syncDir(dirPath: string): Promise<void> {
+  if (process.platform === 'win32') return;
+  const dirFh = await open(dirPath, 'r');
+  try {
+    await dirFh.sync();
+  } finally {
+    await dirFh.close();
+  }
+}
+/**
+ * Synchronous variant of `syncDir`. Used by batched drain paths where a
+ * single timer fire needs to be an atomic event-loop step. Windows
+ * mirrors the async variant — noop.
+ */
+export function syncDirSync(dirPath: string): void {
+  if (process.platform === 'win32') return;
+  const fd = openSync(dirPath, 'r');
+  try {
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+/**
+ * Write `content` to `filePath` atomically and durably:
+ *   1. Write content to `<filePath>.tmp`, fsync it, close it.
+ *   2. Rename `<filePath>.tmp` → `filePath` (atomic on POSIX).
+ *   3. fsync the parent directory so the rename is durable.
+ *
+ * On any failure before the rename the `.tmp` file is removed so the
+ * caller's directory is not left with a half-written leftover. A
+ * failure *after* the rename (i.e. in the parent-directory fsync) is
+ * surfaced to the caller — the content is already in place, but
+ * durability is not guaranteed.
+ */
+export async function writeFileAtomicDurable(
+  filePath: string,
+  content: string | Uint8Array,
+): Promise<void> {
+  const tmpPath = filePath + '.tmp';
+  let renamed = false;
+  try {
+    const fh = await open(tmpPath, 'w');
+    try {
+      await fh.writeFile(content);
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    // Windows pre-unlink for MoveFileEx parity.
+    if (process.platform === 'win32') {
+      try {
+        await unlink(filePath);
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== 'ENOENT') throw error;
+      }
+    }
+    await rename(tmpPath, filePath);
+    renamed = true;
+    await syncDir(dirname(filePath));
+  } finally {
+    if (!renamed) {
+      // Best-effort cleanup of the `.tmp` file if we never got to the
+      // rename. Swallow ENOENT because the file may not exist (open
+      // itself failed) or may already have been unlinked.
+      try {
+        await unlink(tmpPath);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}
+
+/**
+ * atomicWrite — cross-platform atomic file replacement.
+ *
+ * Guarantees that readers never observe a half-written file:
+ *   1. Write content to a uniquely-named temp file in the same directory.
+ *   2. fsync the temp file so the bytes are durable.
+ *   3. rename(tmp, target) — atomic on POSIX.
+ *   4. On any failure before the rename, unlink the temp file (best effort).
+ *
+ * Does NOT fsync the parent directory; callers that need full POSIX
+ * crash durability should `await syncDir(dirname(path))` after this call.
+ *
+ * NOT suitable for append-only paths (wire.jsonl). Those use
+ * `JournalWriter.append()` which writes at the current file position.
+ */
+
+/**
+ * fsync a file descriptor using the callback-based `fs.fsync`. We go
+ * through the module namespace (`nodeFs.fsync`) rather than
+ * `FileHandle.sync()` so vitest's `vi.spyOn(fs, 'fsync')` can
+ * intercept the call for fault-injection tests.
+ */
+function syncFd(fd: number): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    nodeFs.fsync(fd, (err) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+/**
+ * Atomically write `content` to `filePath`. If the target already exists
+ * it is replaced; if it does not exist it is created.
+ *
+ * @param filePath — absolute or relative path to the target file.
+ * @param content  — string or binary payload to write.
+ * @param _syncOverride — test seam: override the fsync implementation for
+ *   fault injection. Production callers must never supply this.
+ */
+export async function atomicWrite(
+  filePath: string,
+  content: string | Uint8Array,
+  _syncOverride?: (fd: number) => Promise<void>,
+): Promise<void> {
+  const hex = randomBytes(4).toString('hex');
+  const tmpPath = `${filePath}.tmp.${process.pid}.${hex}`;
+  let renamed = false;
+  try {
+    const fh = await open(tmpPath, 'w');
+    try {
+      await fh.writeFile(content);
+      await (_syncOverride ?? syncFd)(fh.fd);
+    } finally {
+      await fh.close();
+    }
+    // Windows `fs.rename` maps to MoveFileEx and fails with EPERM if
+    // the target is held by another handle. Pre-unlinking
+    // before the rename turns this into the POSIX-style "replace" case.
+    if (process.platform === 'win32') {
+      try {
+        await unlink(filePath);
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== 'ENOENT') throw error;
+      }
+    }
+    await rename(tmpPath, filePath);
+    renamed = true;
+  } finally {
+    if (!renamed) {
+      try {
+        await unlink(tmpPath);
+      } catch {
+        /* ignore — file may not exist if open itself failed */
+      }
+    }
+  }
+}
diff --git a/packages/agent-core/src/utils/hero-slug.ts b/packages/agent-core/src/utils/hero-slug.ts
new file mode 100644
index 000000000..e460a7806
--- /dev/null
+++ b/packages/agent-core/src/utils/hero-slug.ts
@@ -0,0 +1,267 @@
+/** Hero-name slug generator: produces "hero-hero-hero" with collision fallback. */
+
+import { randomInt } from 'node:crypto';
+
+export const HERO_NAMES = [
+  // --- Marvel ---
+  'iron-man',
+  'spider-man',
+  'captain-america',
+  'thor',
+  'hulk',
+  'black-widow',
+  'hawkeye',
+  'black-panther',
+  'doctor-strange',
+  'scarlet-witch',
+  'vision',
+  'falcon',
+  'war-machine',
+  'ant-man',
+  'wasp',
+  'captain-marvel',
+  'gamora',
+  'star-lord',
+  'groot',
+  'rocket',
+  'drax',
+  'mantis',
+  'nebula',
+  'shang-chi',
+  'moon-knight',
+  'ms-marvel',
+  'she-hulk',
+  'echo',
+  'wolverine',
+  'cyclops',
+  'storm',
+  'jean-grey',
+  'rogue',
+  'beast',
+  'nightcrawler',
+  'colossus',
+  'shadowcat',
+  'jubilee',
+  'cable',
+  'deadpool',
+  'bishop',
+  'magik',
+  'iceman',
+  'archangel',
+  'psylocke',
+  'dazzler',
+  'forge',
+  'havok',
+  'polaris',
+  'emma-frost',
+  'namor',
+  'silver-surfer',
+  'adam-warlock',
+  'nova',
+  'quasar',
+  'sentry',
+  'blue-marvel',
+  'spectrum',
+  'squirrel-girl',
+  'cloak',
+  'dagger',
+  'punisher',
+  'elektra',
+  'luke-cage',
+  'iron-fist',
+  'jessica-jones',
+  'daredevil',
+  'blade',
+  'ghost-rider',
+  'morbius',
+  'venom',
+  'carnage',
+  'silk',
+  'spider-gwen',
+  'miles-morales',
+  'america-chavez',
+  'kate-bishop',
+  'yelena-belova',
+  'white-tiger',
+  'moon-girl',
+  'devil-dinosaur',
+  'amadeus-cho',
+  'riri-williams',
+  'kamala-khan',
+  'sam-alexander',
+  'nova-prime',
+  'medusa',
+  'black-bolt',
+  'crystal',
+  'karnak',
+  'gorgon',
+  'lockjaw',
+  'quake',
+  'mockingbird',
+  'bobbi-morse',
+  'maria-hill',
+  'nick-fury',
+  'phil-coulson',
+  'winter-soldier',
+  'us-agent',
+  'patriot',
+  'speed',
+  'wiccan',
+  'hulkling',
+  'stature',
+  'yellowjacket',
+  'tigra',
+  'hellcat',
+  'valkyrie',
+  'sif',
+  'beta-ray-bill',
+  'hercules',
+  'wonder-man',
+  'taskmaster',
+  'domino',
+  'cannonball',
+  'sunspot',
+  'wolfsbane',
+  'warpath',
+  'multiple-man',
+  'banshee',
+  'siryn',
+  'monet',
+  'rictor',
+  'shatterstar',
+  'longshot',
+  'daken',
+  'x-23',
+  'fantomex',
+  // --- DC ---
+  'batman',
+  'superman',
+  'wonder-woman',
+  'flash',
+  'aquaman',
+  'green-lantern',
+  'martian-manhunter',
+  'cyborg',
+  'hawkgirl',
+  'green-arrow',
+  'black-canary',
+  'zatanna',
+  'constantine',
+  'shazam',
+  'blue-beetle',
+  'booster-gold',
+  'firestorm',
+  'atom',
+  'hawkman',
+  'plastic-man',
+  'red-tornado',
+  'starfire',
+  'raven',
+  'beast-boy',
+  'robin',
+  'nightwing',
+  'batgirl',
+  'batwoman',
+  'red-hood',
+  'signal',
+  'orphan',
+  'spoiler',
+  'catwoman',
+  'huntress',
+  'supergirl',
+  'superboy',
+  'power-girl',
+  'steel',
+  'stargirl',
+  'wildcat',
+  'doctor-fate',
+  'mister-terrific',
+  'hourman',
+  'sandman',
+  'spectre',
+  'phantom-stranger',
+  'swamp-thing',
+  'animal-man',
+  'deadman',
+  'vixen',
+  'black-lightning',
+  'static',
+  'icon',
+  'rocket-dc',
+  'captain-atom',
+  'fire',
+  'ice',
+  'elongated-man',
+  'metamorpho',
+  'black-hawk',
+  'crimson-avenger',
+  'doctor-mid-nite',
+  'jakeem-thunder',
+  'mister-miracle',
+  'big-barda',
+  'orion',
+  'lightray',
+  'forager',
+  'killer-frost',
+  'jessica-cruz',
+  'simon-baz',
+  'john-stewart',
+  'guy-gardner',
+  'kyle-rayner',
+  'hal-jordan',
+  'wally-west',
+  'barry-allen',
+  'jay-garrick',
+  'impulse',
+  'kid-flash',
+  'donna-troy',
+  'tempest',
+  'aqualad',
+  'miss-martian',
+  'terra',
+  'jericho',
+  'ravager',
+  'red-star',
+  'pantha',
+  'argent',
+  'damage',
+  'jade',
+  'obsidian',
+  'cyclone',
+  'atom-smasher',
+  'maxima',
+  'starman',
+  'liberty-belle',
+  'dove',
+  'hawk',
+  'blue-devil',
+  'creeper',
+  'ragman',
+  'thunder',
+] as const satisfies readonly [string, ...string[]];
+
+const MAX_ATTEMPTS = 20;
+
+function pickHero(): string {
+  return HERO_NAMES[randomInt(HERO_NAMES.length)]!;
+}
+
+function assembleSlug(): string {
+  return `${pickHero()}-${pickHero()}-${pickHero()}`;
+}
+
+export function generateHeroSlug(id: string, existing: Set<string>): string {
+  let slug = '';
+  let collided = true;
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    slug = assembleSlug();
+    if (!existing.has(slug)) {
+      collided = false;
+      break;
+    }
+  }
+  if (collided) {
+    slug = `${slug}-${id.slice(0, 8)}`;
+  }
+  return slug;
+}
diff --git a/packages/agent-core/src/utils/render-prompt.ts b/packages/agent-core/src/utils/render-prompt.ts
new file mode 100644
index 000000000..579665e8c
--- /dev/null
+++ b/packages/agent-core/src/utils/render-prompt.ts
@@ -0,0 +1,19 @@
+import nunjucks from 'nunjucks';
+
+/**
+ * Shared prompt template renderer.
+ *
+ * All prompt templates (system prompt, tool descriptions, compaction
+ * instruction, ...) use nunjucks `{{ var }}` / `{% if %}` syntax and render
+ * through this one function.
+ *
+ * - `autoescape: false` — prompt text is not HTML; `<`, `>`, `&` must pass
+ *   through verbatim.
+ * - `throwOnUndefined: true` — a missing variable is a loud error, never a
+ *   silently leaked `{{ placeholder }}` in the text sent to the model.
+ */
+const env = new nunjucks.Environment(null, { autoescape: false, throwOnUndefined: true });
+
+export function renderPrompt(template: string, vars: Record<string, unknown>): string {
+  return env.renderString(template, vars);
+}
diff --git a/packages/agent-core/src/utils/tokens.ts b/packages/agent-core/src/utils/tokens.ts
new file mode 100644
index 000000000..5ccef7d00
--- /dev/null
+++ b/packages/agent-core/src/utils/tokens.ts
@@ -0,0 +1,63 @@
+import type { ContentPart, Message, Tool } from '@moonshot-ai/kosong';
+
+/**
+ * Estimate token count from text using a character-based heuristic.
+ *   - ASCII (~4 chars per token)
+ *   - CJK and other non-ASCII (~1 char per token)
+ * The estimate is transient — the next LLM call returns the real count
+ * and supersedes this value. Used to keep `tokenCountWithPending`
+ * monotonic between LLM round-trips without paying for a tokenizer.
+ */
+export function estimateTokens(text: string): number {
+  let asciiCount = 0;
+  let nonAsciiCount = 0;
+  for (const char of text) {
+    if (char.codePointAt(0)! <= 127) {
+      asciiCount++;
+    } else {
+      nonAsciiCount++;
+    }
+  }
+  return Math.ceil(asciiCount / 4) + nonAsciiCount;
+}
+
+export function estimateTokensForMessages(messages: Message[]): number {
+  let total = 0;
+  for (const message of messages) {
+    total += estimateTokensForMessage(message);
+  }
+  return total;
+}
+
+export function estimateTokensForTools(tools: readonly Tool[]): number {
+  let total = 0;
+  for (const tool of tools) {
+    total += estimateTokens(tool.name);
+    total += estimateTokens(tool.description);
+    total += estimateTokens(JSON.stringify(tool.parameters));
+  }
+  return total;
+}
+
+export function estimateTokensForMessage(message: Message): number {
+  let total = estimateTokens(message.role);
+  for (const part of message.content) {
+    total += estimateTokensForContentPart(part);
+  }
+  if (message.toolCalls !== undefined) {
+    for (const call of message.toolCalls) {
+      total += estimateTokens(call.function.name);
+      total += estimateTokens(JSON.stringify(call.function.arguments));
+    }
+  }
+  return total;
+}
+
+export function estimateTokensForContentPart(part: ContentPart): number {
+  if (part.type === 'text') {
+    return estimateTokens(part.text);
+  } else if (part.type === 'think') {
+    return estimateTokens(part.think);
+  }
+  return 0;
+}
diff --git a/packages/agent-core/src/utils/types.ts b/packages/agent-core/src/utils/types.ts
new file mode 100644
index 000000000..45a0d1c9d
--- /dev/null
+++ b/packages/agent-core/src/utils/types.ts
@@ -0,0 +1,13 @@
+export type Promisify<T> = [T] extends [Promise<any>] ? T : Promise<T>;
+export type PromisifyMethods<T> = {
+  [K in keyof T]: T[K] extends (...args: infer Args) => infer Return
+    ? (...args: Args) => Promisify<Return>
+    : never;
+};
+
+export type Promisable<T> = [T] extends [Promise<any>] ? T | Awaited<T> : T | Promise<T>;
+export type PromisableMethods<T> = {
+  [K in keyof T]: T[K] extends (...args: infer Args) => infer Return
+    ? (...args: Args) => Promisable<Return>
+    : never;
+};
diff --git a/packages/agent-core/src/utils/workdir-slug.ts b/packages/agent-core/src/utils/workdir-slug.ts
new file mode 100644
index 000000000..5f8da29a6
--- /dev/null
+++ b/packages/agent-core/src/utils/workdir-slug.ts
@@ -0,0 +1,11 @@
+const MAX_WORKDIR_SLUG_LENGTH = 40;
+
+export function slugifyWorkDirName(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9._-]+/g, '-')
+    .replaceAll(/^-+|-+$/g, '')
+    .slice(0, MAX_WORKDIR_SLUG_LENGTH)
+    .replaceAll(/^-+|-+$/g, '');
+  return slug === '' || slug === '.' || slug === '..' ? 'workspace' : slug;
+}
diff --git a/packages/agent-core/src/version.ts b/packages/agent-core/src/version.ts
new file mode 100644
index 000000000..5436e6c6f
--- /dev/null
+++ b/packages/agent-core/src/version.ts
@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export function getCoreVersion(): string {
+  try {
+    const pkgUrl = new URL('../package.json', import.meta.url);
+    const raw = readFileSync(fileURLToPath(pkgUrl), 'utf-8');
+    const pkg = JSON.parse(raw) as { version?: unknown };
+    return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
diff --git a/packages/agent-core/test/agent/background-manager.test.ts b/packages/agent-core/test/agent/background-manager.test.ts
new file mode 100644
index 000000000..882fb9016
--- /dev/null
+++ b/packages/agent-core/test/agent/background-manager.test.ts
@@ -0,0 +1,628 @@
+/**
+ * Covers: BackgroundManager (the agent-aware subclass).
+ *
+ * Confirms that BPM lifecycle transitions are translated into
+ * agent.emitEvent({ type: 'background.task.*' }) so SDK / TUI
+ * subscribers can react in real time without polling.
+ */
+
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import type { Writable } from 'node:stream';
+
+import type { KaosProcess } from '@moonshot-ai/kaos';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { BackgroundManager } from '../../src/agent/background';
+import type { AgentEvent } from '../../src/rpc/events';
+import { appendTaskOutput, writeTask } from '../../src/tools/background/persist';
+
+interface FakeAgent {
+  emitEvent: (event: AgentEvent) => void;
+  emittedEvents: AgentEvent[];
+  hooks?: { fireAndForgetTrigger: ReturnType<typeof vi.fn> };
+  turn: {
+    hasActiveTurn: boolean;
+    waitForCurrentTurn: () => Promise<void>;
+    steer: (...args: unknown[]) => number | null;
+  };
+  context: { appendUserMessage: (...args: unknown[]) => void };
+  records: { restoring: boolean; logRecord: (record: unknown) => void };
+  telemetry: { track: ReturnType<typeof vi.fn> };
+  background: BackgroundManager;
+}
+
+function makeAgent(options: { hooks?: FakeAgent['hooks'] } = {}): FakeAgent {
+  const emitted: AgentEvent[] = [];
+  const agent = {
+    emittedEvents: emitted,
+    emitEvent: (event: AgentEvent) => {
+      emitted.push(event);
+    },
+    hooks: options.hooks,
+    turn: {
+      hasActiveTurn: false,
+      waitForCurrentTurn: vi.fn(() => Promise.resolve()),
+      steer: vi.fn(() => 1),
+    },
+    context: { appendUserMessage: vi.fn() },
+    records: { restoring: false, logRecord: vi.fn() },
+    telemetry: { track: vi.fn() },
+  } as unknown as FakeAgent;
+  const manager = new BackgroundManager(agent as never);
+  agent.background = manager;
+  return agent;
+}
+
+function immediateProcess(exitCode: number): KaosProcess {
+  return {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 30000 + exitCode,
+    exitCode,
+    wait: vi.fn().mockResolvedValue(exitCode) as KaosProcess['wait'],
+    kill: vi.fn().mockResolvedValue(undefined) as KaosProcess['kill'],
+  };
+}
+
+function pendingProcess(): KaosProcess {
+  let resolveWait: (code: number) => void = () => {};
+  const waitPromise = new Promise<number>((res) => {
+    resolveWait = res;
+  });
+  let currentExitCode: number | null = null;
+  return {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 99999,
+    get exitCode(): number | null {
+      return currentExitCode;
+    },
+    wait: () => waitPromise,
+    kill: vi.fn(async () => {
+      if (currentExitCode === null) {
+        currentExitCode = 143;
+        resolveWait(143);
+      }
+    }) as unknown as KaosProcess['kill'],
+  };
+}
+
+describe('BackgroundManager — RPC event emission', () => {
+  let agent: FakeAgent;
+
+  beforeEach(() => {
+    agent = makeAgent();
+  });
+
+  afterEach(() => {
+    agent.background._reset();
+  });
+
+  it('emits background.task.started on register()', () => {
+    const taskId = agent.background.register(pendingProcess(), 'sleep 60', 'demo');
+
+    const started = agent.emittedEvents.filter((e) => e.type === 'background.task.started');
+    expect(started.length).toBe(1);
+    expect(started[0]!.info.taskId).toBe(taskId);
+    expect(started[0]!.info.status).toBe('running');
+    expect(agent.telemetry.track).toHaveBeenCalledWith('background_task_created', {
+      kind: 'bash',
+    });
+  });
+
+  it('emits background.task.started on registerAgentTask()', () => {
+    const taskId = agent.background.registerAgentTask(new Promise(() => {}), 'agent task');
+
+    const started = agent.emittedEvents.filter((e) => e.type === 'background.task.started');
+    expect(started.length).toBe(1);
+    expect(started[0]!.info.taskId).toBe(taskId);
+    expect(taskId).toMatch(/^agent-/);
+    expect(agent.telemetry.track).toHaveBeenCalledWith('background_task_created', {
+      kind: 'agent',
+    });
+  });
+
+  it('emits background.task.updated on awaiting_approval transitions', () => {
+    const taskId = agent.background.register(pendingProcess(), 'sleep', 'demo');
+    agent.emittedEvents.length = 0;
+
+    agent.background.markAwaitingApproval(taskId, 'needs approval');
+    agent.background.clearAwaitingApproval(taskId);
+
+    const updated = agent.emittedEvents.filter((e) => e.type === 'background.task.updated');
+    expect(updated.length).toBe(2);
+    expect(updated[0]!.info.status).toBe('awaiting_approval');
+    expect(updated[1]!.info.status).toBe('running');
+  });
+
+  it('emits background.task.terminated on natural exit', async () => {
+    agent.background.register(immediateProcess(0), 'echo', 'done');
+    await new Promise((r) => setTimeout(r, 20));
+
+    const terminated = agent.emittedEvents.filter((e) => e.type === 'background.task.terminated');
+    expect(terminated.length).toBe(1);
+    expect(terminated[0]!.info.status).toBe('completed');
+  });
+
+  it('tracks successful task completion with duration and no reason', async () => {
+    const taskId = agent.background.register(immediateProcess(0), 'echo ok', 'done');
+    agent.telemetry.track.mockClear();
+
+    await agent.background.waitForTerminal(taskId);
+
+    expect(agent.telemetry.track).toHaveBeenCalledWith(
+      'background_task_completed',
+      expect.objectContaining({
+        kind: 'bash',
+        success: true,
+        duration_s: expect.any(Number),
+      }),
+    );
+    expect(agent.telemetry.track.mock.calls[0]?.[1]).not.toHaveProperty('reason');
+  });
+
+  it('tracks failed task completion with reason=error', async () => {
+    const taskId = agent.background.register(immediateProcess(1), 'false', 'failed');
+    agent.telemetry.track.mockClear();
+
+    await agent.background.waitForTerminal(taskId);
+
+    expect(agent.telemetry.track).toHaveBeenCalledWith(
+      'background_task_completed',
+      expect.objectContaining({
+        kind: 'bash',
+        success: false,
+        reason: 'error',
+        duration_s: expect.any(Number),
+      }),
+    );
+  });
+
+  it('tracks timed-out agent tasks with reason=timeout', async () => {
+    const taskId = agent.background.registerAgentTask(new Promise(() => {}), 'slow agent', {
+      timeoutMs: 1,
+    });
+    agent.telemetry.track.mockClear();
+
+    await agent.background.waitForTerminal(taskId);
+
+    expect(agent.telemetry.track).toHaveBeenCalledWith(
+      'background_task_completed',
+      expect.objectContaining({
+        kind: 'agent',
+        success: false,
+        reason: 'timeout',
+        duration_s: expect.any(Number),
+      }),
+    );
+  });
+
+  it('emits background.task.terminated on stop()', async () => {
+    const taskId = agent.background.register(pendingProcess(), 'sleep 60', 'long');
+    agent.emittedEvents.length = 0;
+
+    await agent.background.stop(taskId, 'user');
+
+    const terminated = agent.emittedEvents.filter((e) => e.type === 'background.task.terminated');
+    expect(terminated.length).toBe(1);
+    expect(terminated[0]!.info.status).toBe('killed');
+  });
+
+  it('emits background.task.terminated when a restored task is marked lost', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-agent-reconcile-'));
+    try {
+      agent.background.attachSessionDir(sessionDir);
+      await writeTask(sessionDir, {
+        task_id: 'bash-orphan00',
+        command: 'sleep 60',
+        description: 'orphan task',
+        pid: 99999,
+        started_at: 1_700_000_000,
+        ended_at: null,
+        exit_code: null,
+        status: 'running',
+      });
+      agent.emittedEvents.length = 0;
+
+      await agent.background.loadFromDisk();
+      await agent.background.reconcile();
+
+      const terminated = agent.emittedEvents.filter(
+        (e) => e.type === 'background.task.terminated',
+      );
+      expect(terminated.length).toBe(1);
+      expect(terminated[0]!.info.taskId).toBe('bash-orphan00');
+      expect(terminated[0]!.info.status).toBe('lost');
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('steers completed agent task notifications into the turn flow', async () => {
+    const taskId = agent.background.registerAgentTask(
+      Promise.resolve({ result: 'final subagent summary' }),
+      'agent task',
+    );
+    await agent.background.waitForTerminal(taskId);
+
+    await vi.waitFor(() => {
+      expect(agent.turn.steer).toHaveBeenCalledTimes(1);
+    });
+    expect(agent.turn.waitForCurrentTurn).not.toHaveBeenCalled();
+    expect(agent.context.appendUserMessage).not.toHaveBeenCalled();
+
+    const [content, origin] = vi.mocked(agent.turn.steer).mock.calls[0]!;
+    expect(origin).toEqual({
+      kind: 'background_task',
+      taskId,
+      status: 'completed',
+      notificationId: `task:${taskId}:completed`,
+    });
+    expect((content as Array<{ text: string }>)[0]!.text).toContain(
+      'Background agent completed',
+    );
+    expect((content as Array<{ text: string }>)[0]!.text).toContain('final subagent summary');
+  });
+
+  it('steers completed bash task notifications into the turn flow', async () => {
+    const taskId = agent.background.register(immediateProcess(0), 'echo ok', 'shell task');
+
+    await agent.background.waitForTerminal(taskId);
+
+    await vi.waitFor(() => {
+      expect(agent.turn.steer).toHaveBeenCalledTimes(1);
+    });
+    expect(agent.turn.waitForCurrentTurn).not.toHaveBeenCalled();
+    expect(agent.context.appendUserMessage).not.toHaveBeenCalled();
+
+    const [content, origin] = vi.mocked(agent.turn.steer).mock.calls[0]!;
+    expect(origin).toEqual({
+      kind: 'background_task',
+      taskId,
+      status: 'completed',
+      notificationId: `task:${taskId}:completed`,
+    });
+    expect((content as Array<{ text: string }>)[0]!.text).toContain(
+      'Background task completed',
+    );
+    expect((content as Array<{ text: string }>)[0]!.text).toContain('shell task completed.');
+  });
+
+  it('steers stopped bash task notifications into the turn flow', async () => {
+    const taskId = agent.background.register(pendingProcess(), 'sleep 60', 'long shell task');
+
+    await agent.background.stop(taskId);
+
+    await vi.waitFor(() => {
+      expect(agent.turn.steer).toHaveBeenCalledTimes(1);
+    });
+    const [content, origin] = vi.mocked(agent.turn.steer).mock.calls[0]!;
+    expect(origin).toEqual({
+      kind: 'background_task',
+      taskId,
+      status: 'killed',
+      notificationId: `task:${taskId}:killed`,
+    });
+    expect((content as Array<{ text: string }>)[0]!.text).toContain('Background task killed');
+    expect((content as Array<{ text: string }>)[0]!.text).toContain('long shell task killed.');
+  });
+
+  it('queues background agent notifications without waiting for an active turn', async () => {
+    agent.turn.hasActiveTurn = true;
+    const taskId = agent.background.registerAgentTask(
+      Promise.resolve({ result: 'active turn summary' }),
+      'agent task',
+    );
+    await agent.background.waitForTerminal(taskId);
+
+    await vi.waitFor(() => {
+      expect(agent.turn.steer).toHaveBeenCalledTimes(1);
+    });
+    expect(agent.turn.waitForCurrentTurn).not.toHaveBeenCalled();
+    const [content, origin] = vi.mocked(agent.turn.steer).mock.calls[0]!;
+    expect(origin).toEqual({
+      kind: 'background_task',
+      taskId,
+      status: 'completed',
+      notificationId: `task:${taskId}:completed`,
+    });
+    expect((content as Array<{ text: string }>)[0]!.text).toContain('active turn summary');
+  });
+
+  it('replays restored terminal agent task notifications when they were not delivered', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-agent-replay-'));
+    try {
+      agent.background.attachSessionDir(sessionDir);
+      await writeTask(sessionDir, {
+        task_id: 'agent-done0000',
+        command: '[agent] restored task',
+        description: 'restored task',
+        pid: 0,
+        started_at: 1_700_000_000,
+        ended_at: 1_700_000_010,
+        exit_code: 0,
+        status: 'completed',
+      });
+      await appendTaskOutput(sessionDir, 'agent-done0000', 'restored subagent summary');
+
+      await agent.background.loadFromDisk();
+      const result = await agent.background.reconcile();
+
+      expect(result.lost).toEqual([]);
+      await vi.waitFor(() => {
+        expect(agent.context.appendUserMessage).toHaveBeenCalledTimes(1);
+      });
+      expect(agent.turn.steer).not.toHaveBeenCalled();
+      const [content, origin] = vi.mocked(agent.context.appendUserMessage).mock.calls[0]!;
+      expect(origin).toEqual({
+        kind: 'background_task',
+        taskId: 'agent-done0000',
+        status: 'completed',
+        notificationId: 'task:agent-done0000:completed',
+      });
+      expect((content as Array<{ text: string }>)[0]!.text).toContain(
+        'Background agent completed',
+      );
+      expect((content as Array<{ text: string }>)[0]!.text).toContain('restored subagent summary');
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('replays restored terminal bash task notifications when they were not delivered', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-bash-replay-'));
+    try {
+      agent.background.attachSessionDir(sessionDir);
+      await writeTask(sessionDir, {
+        task_id: 'bash-done0000',
+        command: 'echo done',
+        description: 'restored shell task',
+        pid: 12345,
+        started_at: 1_700_000_000,
+        ended_at: 1_700_000_010,
+        exit_code: 0,
+        status: 'completed',
+      });
+      await appendTaskOutput(sessionDir, 'bash-done0000', 'restored shell output');
+
+      await agent.background.loadFromDisk();
+      const result = await agent.background.reconcile();
+
+      expect(result.lost).toEqual([]);
+      await vi.waitFor(() => {
+        expect(agent.context.appendUserMessage).toHaveBeenCalledTimes(1);
+      });
+      expect(agent.turn.steer).not.toHaveBeenCalled();
+      const [content, origin] = vi.mocked(agent.context.appendUserMessage).mock.calls[0]!;
+      expect(origin).toEqual({
+        kind: 'background_task',
+        taskId: 'bash-done0000',
+        status: 'completed',
+        notificationId: 'task:bash-done0000:completed',
+      });
+      expect((content as Array<{ text: string }>)[0]!.text).toContain(
+        'Background task completed',
+      );
+      expect((content as Array<{ text: string }>)[0]!.text).toContain('restored shell output');
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('reads only a bounded output tail for restored bash task notifications', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-bash-tail-'));
+    try {
+      const taskId = 'bash-large000';
+      const largeOutput = `early-output-marker\n${'x'.repeat(8_000)}\nfinal output line`;
+      agent.background.attachSessionDir(sessionDir);
+      await writeTask(sessionDir, {
+        task_id: taskId,
+        command: 'generate large output',
+        description: 'large shell task',
+        pid: 12345,
+        started_at: 1_700_000_000,
+        ended_at: 1_700_000_010,
+        exit_code: 0,
+        status: 'completed',
+      });
+      await appendTaskOutput(sessionDir, taskId, largeOutput);
+      const readOutputSpy = vi.spyOn(agent.background, 'readOutput');
+      const snapshotSpy = vi.spyOn(agent.background, 'getOutputSnapshot');
+
+      await agent.background.loadFromDisk();
+      await agent.background.reconcile();
+
+      await vi.waitFor(() => {
+        expect(agent.context.appendUserMessage).toHaveBeenCalledTimes(1);
+      });
+      expect(readOutputSpy).not.toHaveBeenCalled();
+      expect(snapshotSpy).toHaveBeenCalledWith(taskId, expect.any(Number));
+      expect(snapshotSpy.mock.calls[0]![1]).toBeLessThan(largeOutput.length);
+      const [content] = vi.mocked(agent.context.appendUserMessage).mock.calls[0]!;
+      const text = (content as Array<{ text: string }>)[0]!.text;
+      expect(text).toContain('final output line');
+      expect(text).not.toContain('early-output-marker');
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('does not replay restored agent task notifications already marked delivered', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-agent-replay-'));
+    try {
+      const origin = {
+        kind: 'background_task',
+        taskId: 'agent-seen0000',
+        status: 'completed',
+        notificationId: 'task:agent-seen0000:completed',
+      } as const;
+      agent.background.markDeliveredNotification(origin);
+      agent.background.attachSessionDir(sessionDir);
+      await writeTask(sessionDir, {
+        task_id: 'agent-seen0000',
+        command: '[agent] already delivered',
+        description: 'already delivered',
+        pid: 0,
+        started_at: 1_700_000_000,
+        ended_at: 1_700_000_010,
+        exit_code: 0,
+        status: 'completed',
+      });
+      await appendTaskOutput(sessionDir, 'agent-seen0000', 'already delivered summary');
+
+      await agent.background.loadFromDisk();
+      await agent.background.reconcile();
+
+      expect(agent.turn.steer).not.toHaveBeenCalled();
+      expect(agent.context.appendUserMessage).not.toHaveBeenCalled();
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('does not double-notify newly lost restored agent tasks', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-agent-replay-'));
+    try {
+      agent.background.attachSessionDir(sessionDir);
+      await writeTask(sessionDir, {
+        task_id: 'agent-run00000',
+        command: '[agent] interrupted task',
+        description: 'interrupted task',
+        pid: 0,
+        started_at: 1_700_000_000,
+        ended_at: null,
+        exit_code: null,
+        status: 'running',
+      });
+
+      await agent.background.loadFromDisk();
+      const result = await agent.background.reconcile();
+
+      expect(result.lost).toEqual(['agent-run00000']);
+      await vi.waitFor(() => {
+        expect(agent.context.appendUserMessage).toHaveBeenCalledTimes(1);
+      });
+      expect(agent.turn.steer).not.toHaveBeenCalled();
+      const [content, origin] = vi.mocked(agent.context.appendUserMessage).mock.calls[0]!;
+      expect(origin).toEqual({
+        kind: 'background_task',
+        taskId: 'agent-run00000',
+        status: 'lost',
+        notificationId: 'task:agent-run00000:lost',
+      });
+      expect((content as Array<{ text: string }>)[0]!.text).toContain('Background agent lost');
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('fires a Notification hook when a background agent notification is delivered', async () => {
+    const fireAndForgetTrigger = vi.fn(() => Promise.resolve([]));
+    agent = makeAgent({ hooks: { fireAndForgetTrigger } });
+
+    const taskId = agent.background.registerAgentTask(
+      Promise.resolve({ result: 'final agent output' }),
+      'inspect repository',
+    );
+    await agent.background.wait(taskId);
+
+    await vi.waitFor(() => {
+      expect(agent.turn.steer).toHaveBeenCalled();
+      expect(fireAndForgetTrigger).toHaveBeenCalled();
+    });
+    expect(fireAndForgetTrigger).toHaveBeenCalledWith('Notification', {
+      matcherValue: 'task.completed',
+      inputData: {
+        sink: 'context',
+        notificationType: 'task.completed',
+        title: 'Background agent completed',
+        body: 'inspect repository completed.',
+        severity: 'info',
+        sourceKind: 'background_task',
+        sourceId: taskId,
+      },
+    });
+  });
+
+  it('does not let Notification hook failures interrupt background notification delivery', async () => {
+    const fireAndForgetTrigger = vi.fn(() => {
+      throw new Error('notification hook failed');
+    });
+    agent = makeAgent({ hooks: { fireAndForgetTrigger } });
+
+    const taskId = agent.background.registerAgentTask(
+      Promise.resolve({ result: 'final agent output' }),
+      'inspect repository',
+    );
+    await agent.background.wait(taskId);
+
+    await vi.waitFor(() => {
+      expect(agent.turn.steer).toHaveBeenCalled();
+      expect(fireAndForgetTrigger).toHaveBeenCalled();
+    });
+    expect(agent.turn.steer).toHaveBeenCalledWith(
+      [
+        {
+          type: 'text',
+          text: expect.stringContaining(`source_id="${taskId}"`),
+        },
+      ],
+      {
+        kind: 'background_task',
+        taskId,
+        status: 'completed',
+        notificationId: `task:${taskId}:completed`,
+      },
+    );
+  });
+
+  it('fires Notification hooks for bash background task notifications', async () => {
+    const fireAndForgetTrigger = vi.fn(() => Promise.resolve([]));
+    agent = makeAgent({ hooks: { fireAndForgetTrigger } });
+
+    const taskId = agent.background.register(immediateProcess(0), 'echo', 'done');
+    await agent.background.waitForTerminal(taskId);
+
+    await vi.waitFor(() => {
+      expect(agent.turn.steer).toHaveBeenCalled();
+      expect(fireAndForgetTrigger).toHaveBeenCalled();
+    });
+    expect(agent.context.appendUserMessage).not.toHaveBeenCalled();
+    expect(fireAndForgetTrigger).toHaveBeenCalledWith('Notification', {
+      matcherValue: 'task.completed',
+      inputData: {
+        sink: 'context',
+        notificationType: 'task.completed',
+        title: 'Background task completed',
+        body: 'done completed.',
+        severity: 'info',
+        sourceKind: 'background_task',
+        sourceId: taskId,
+      },
+    });
+  });
+
+  it('tracks stopped tasks as killed even without a stop reason', async () => {
+    const taskId = agent.background.register(pendingProcess(), 'sleep 60', 'long');
+    agent.telemetry.track.mockClear();
+
+    await agent.background.stop(taskId);
+
+    expect(agent.telemetry.track).toHaveBeenCalledWith(
+      'background_task_completed',
+      expect.objectContaining({
+        success: false,
+        reason: 'killed',
+      }),
+    );
+  });
+
+  // Note: the `records.restoring` guard is enforced inside `Agent.emitEvent`
+  // (see agent/index.ts). BackgroundManager unconditionally forwards
+  // lifecycle events to the agent; suppression is the agent's job.
+});
diff --git a/packages/agent-core/test/agent/basic.test.ts b/packages/agent-core/test/agent/basic.test.ts
new file mode 100644
index 000000000..0a3e4da1a
--- /dev/null
+++ b/packages/agent-core/test/agent/basic.test.ts
@@ -0,0 +1,138 @@
+import type { ToolCall } from '@moonshot-ai/kosong';
+import { expect, it } from 'vitest';
+
+import { createCommandKaos, testAgent } from './harness/agent';
+
+it('runs a text-only agent turn from prompt to completion', async () => {
+  const ctx = testAgent();
+  ctx.configure();
+
+  ctx.mockNextResponse({ type: 'think', think: '<think-1>' }, { type: 'text', text: '<text-1>' });
+  await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Hello' }] });
+
+  expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+    [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Hello" } ], "origin": { "kind": "user" }, "time": "<time>" }
+    [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+    [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Hello" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+    [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+    [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+    [emit] thinking.delta              { "turnId": 0, "delta": "<think-1>" }
+    [emit] assistant.delta             { "turnId": 0, "delta": "<text-1>" }
+    [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "think", "think": "<think-1>" } }, "time": "<time>" }
+    [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-3>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "<text-1>" } }, "time": "<time>" }
+    [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "usage": { "inputOther": 3, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+    [emit] turn.step.completed         { "turnId": 0, "step": 1, "stepId": "<uuid-1>", "usage": { "inputOther": 3, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+    [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 3, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+    [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 11, "maxContextTokens": 1000000, "contextUsage": 0.000011, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 3, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 3, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 3, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+    [emit] turn.ended                  { "turnId": 0, "reason": "completed" }
+  `);
+  expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+    system: <system-prompt>
+    tools: []
+    messages:
+      user: text "Hello"
+  `);
+  await ctx.expectResumeMatches();
+});
+
+it('forwards provider finish diagnostics on filtered steps', async () => {
+  const ctx = testAgent();
+  ctx.configure();
+
+  ctx.mockNextProviderResponse({
+    parts: [{ type: 'text', text: 'blocked' }],
+    finishReason: 'filtered',
+    rawFinishReason: 'content_filter',
+  });
+  await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Hello' }] });
+
+  await ctx.untilTurnEnd();
+
+  const wireStepEnd = ctx.allEvents.find(
+    (event) =>
+      event.type === '[wire]' &&
+      event.event === 'context.append_loop_event' &&
+      (event.args as { event?: { type?: string } }).event?.type === 'step.end',
+  );
+  const rpcStepEnd = ctx.allEvents.find(
+    (event) => event.type === '[rpc]' && event.event === 'turn.step.completed',
+  );
+
+  expect(wireStepEnd?.args).toMatchObject({
+    event: {
+      finishReason: 'filtered',
+      providerFinishReason: 'filtered',
+      rawFinishReason: 'content_filter',
+    },
+  });
+  expect(rpcStepEnd?.args).toMatchObject({
+    finishReason: 'filtered',
+    providerFinishReason: 'filtered',
+    rawFinishReason: 'content_filter',
+  });
+  await ctx.expectResumeMatches();
+});
+
+it('runs an agent turn through builtin tool approval and execution', async () => {
+  const bashCall: ToolCall = {
+    type: 'function',
+    id: 'call_bash',
+    function: {
+      name: 'Bash',
+      arguments: '{"command":"printf lookup-result","timeout":60}',
+    },
+  };
+  const ctx = testAgent({ kaos: createCommandKaos('lookup-result') });
+  ctx.configure({ tools: ['Bash'] });
+
+  ctx.mockNextResponse({ type: 'text', text: 'I will run that.' }, bashCall);
+  await ctx.rpc.prompt({
+    input: [{ type: 'text', text: 'Run a command that prints lookup-result' }],
+  });
+  expect(await ctx.untilApproval(true)).toMatchInlineSnapshot(`
+    [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Run a command that prints lookup-result" } ], "origin": { "kind": "user" }, "time": "<time>" }
+    [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+    [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Run a command that prints lookup-result" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+    [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+    [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+    [emit] assistant.delta             { "turnId": 0, "delta": "I will run that." }
+    [emit] tool.call.delta             { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "argumentsPart": "{\\"command\\":\\"printf lookup-result\\",\\"timeout\\":60}" }
+    [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "I will run that." } }, "time": "<time>" }
+    [emit] requestApproval             { "turnId": 0, "toolCallId": "call_bash", "toolName": "Bash", "action": "run command", "display": { "kind": "generic", "summary": "Approve Bash", "detail": { "command": "printf lookup-result", "timeout": 60 } } }
+  `);
+  expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+    system: <system-prompt>
+    tools: Bash
+    messages:
+      user: text "Run a command that prints lookup-result"
+  `);
+
+  ctx.mockNextResponse({ type: 'text', text: 'The command printed lookup-result.' });
+  expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+    [wire] permission.record_approval_result   { "turnId": 0, "toolCallId": "call_bash", "toolName": "Bash", "action": "run command", "result": { "decision": "approved", "selectedLabel": "approve" }, "time": "<time>" }
+    [wire] context.append_loop_event           { "event": { "type": "tool.call", "uuid": "call_bash", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf lookup-result", "timeout": 60 }, "description": "Running: printf lookup-result" }, "time": "<time>" }
+    [emit] tool.call.started                   { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf lookup-result", "timeout": 60 }, "description": "Running: printf lookup-result" }
+    [wire] context.append_loop_event           { "event": { "type": "tool.result", "parentUuid": "call_bash", "toolCallId": "call_bash", "result": { "output": "lookup-result" } }, "time": "<time>" }
+    [emit] tool.result                         { "turnId": 0, "toolCallId": "call_bash", "output": "lookup-result" }
+    [wire] context.append_loop_event           { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "usage": { "inputOther": 11, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }, "time": "<time>" }
+    [emit] turn.step.completed                 { "turnId": 0, "step": 1, "stepId": "<uuid-1>", "usage": { "inputOther": 11, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }
+    [wire] usage.record                        { "model": "mock-model", "usage": { "inputOther": 11, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+    [emit] agent.status.updated                { "model": "mock-model", "contextTokens": 33, "maxContextTokens": 1000000, "contextUsage": 0.000033, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 11, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 11, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 11, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+    [wire] context.append_loop_event           { "event": { "type": "step.begin", "uuid": "<uuid-3>", "turnId": "0", "step": 2 }, "time": "<time>" }
+    [emit] turn.step.started                   { "turnId": 0, "step": 2, "stepId": "<uuid-3>" }
+    [emit] assistant.delta                     { "turnId": 0, "delta": "The command printed lookup-result." }
+    [wire] context.append_loop_event           { "event": { "type": "content.part", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "stepUuid": "<uuid-3>", "part": { "type": "text", "text": "The command printed lookup-result." } }, "time": "<time>" }
+    [wire] context.append_loop_event           { "event": { "type": "step.end", "uuid": "<uuid-3>", "turnId": "0", "step": 2, "usage": { "inputOther": 38, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+    [emit] turn.step.completed                 { "turnId": 0, "step": 2, "stepId": "<uuid-3>", "usage": { "inputOther": 38, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+    [wire] usage.record                        { "model": "mock-model", "usage": { "inputOther": 38, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+    [emit] agent.status.updated                { "model": "mock-model", "contextTokens": 50, "maxContextTokens": 1000000, "contextUsage": 0.00005, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 49, "output": 34, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 49, "output": 34, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 49, "output": 34, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+    [emit] turn.ended                          { "turnId": 0, "reason": "completed" }
+  `);
+  expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+    messages:
+      <last>
+      assistant: text "I will run that."  calls call_bash:Bash { "command": "printf lookup-result", "timeout": 60 }
+      tool[call_bash]: text "lookup-result"
+  `);
+  await ctx.expectResumeMatches();
+});
diff --git a/packages/agent-core/test/agent/compaction.test.ts b/packages/agent-core/test/agent/compaction.test.ts
new file mode 100644
index 000000000..46a4f7cb5
--- /dev/null
+++ b/packages/agent-core/test/agent/compaction.test.ts
@@ -0,0 +1,1651 @@
+import { existsSync, mkdtempSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  APIConnectionError,
+  APIContextOverflowError,
+  APIStatusError,
+  UNKNOWN_CAPABILITY,
+  type Message,
+  type ToolCall,
+} from '@moonshot-ai/kosong';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { AgentConfig } from '../../src/agent';
+import { DefaultCompactionStrategy, type CompactionStrategy } from '../../src/agent/compaction';
+import { HookEngine, type HookEngineTriggerArgs } from '../../src/agent/hooks';
+import type { KimiConfig } from '../../src/config';
+import { ProviderManager } from '../../src/providers/provider-manager';
+import { recordingTelemetry, type TelemetryRecord } from '../fixtures/telemetry';
+import type { TestAgentContext } from './harness/agent';
+import { testAgent } from './harness/agent';
+
+type GenerateFn = NonNullable<AgentConfig['generate']>;
+
+const CATALOGUED_PROVIDER = {
+  type: 'kimi',
+  apiKey: 'test-key',
+  model: 'kimi-code',
+} as const;
+const CATALOGUED_MODEL_CAPABILITIES = {
+  image_in: true,
+  video_in: true,
+  audio_in: false,
+  thinking: true,
+  tool_use: true,
+  max_context_tokens: 256_000,
+} as const;
+
+describe('Agent compaction', () => {
+  it('keeps an oversized trailing user message as recent', () => {
+    const strategy = testCompactionStrategy();
+    const messages = [
+      textMessage('user', 'old user'),
+      textMessage('assistant', 'old assistant'),
+      textMessage('user', `pending user ${'x'.repeat(1_200)}`),
+    ];
+
+    expect(strategy.computeCompactCount(messages, 1_000)).toBe(2);
+  });
+
+  it('keeps consecutive trailing user messages as recent', () => {
+    const strategy = testCompactionStrategy();
+    const messages = [
+      textMessage('user', 'old user'),
+      textMessage('assistant', 'old assistant'),
+      textMessage('user', `pending user one ${'x'.repeat(1_200)}`),
+      textMessage('user', `pending user two ${'x'.repeat(1_200)}`),
+    ];
+
+    expect(strategy.computeCompactCount(messages, 1_000)).toBe(2);
+  });
+
+  it('does not keep an oversized completed exchange as recent', () => {
+    const strategy = testCompactionStrategy();
+    const messages = [
+      textMessage('user', 'old user'),
+      textMessage('assistant', 'old assistant'),
+      textMessage('user', 'recent user'),
+      textMessage('assistant', `recent assistant ${'x'.repeat(1_200)}`),
+    ];
+
+    expect(strategy.computeCompactCount(messages, 1_000)).toBe(messages.length);
+  });
+
+  it('reserves response context by default before the ratio threshold is reached', () => {
+    const strategy = new DefaultCompactionStrategy();
+
+    expect(strategy.shouldCompact(210_000, 256_000)).toBe(true);
+    expect(strategy.shouldBlock(210_000, 256_000)).toBe(true);
+  });
+
+  it('ignores reserved context when the reserve is not smaller than the model window', () => {
+    const strategy = new DefaultCompactionStrategy({
+      triggerRatio: 0.85,
+      blockRatio: 0.85,
+      reservedContextSize: 50_000,
+      maxCompactionPerTurn: 3,
+      maxRecentSteps: 3,
+      maxRecentUserMessages: Infinity,
+      maxRecentSizeRatio: 0.2,
+    });
+
+    expect(strategy.shouldCompact(1, 32_000)).toBe(false);
+    expect(strategy.shouldBlock(1, 32_000)).toBe(false);
+    expect(strategy.shouldCompact(28_000, 32_000)).toBe(true);
+    expect(strategy.shouldBlock(28_000, 32_000)).toBe(true);
+  });
+
+  it('runs manual compaction and applies the compacted context', async () => {
+    const records: TelemetryRecord[] = [];
+    const ctx = testAgent({ telemetry: recordingTelemetry(records) });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    appendExchange(ctx, 2, 'old user two', 'old assistant two', 40);
+    appendExchange(ctx, 3, 'recent user three', 'recent assistant three', 120);
+    const compacted = new Promise<void>((resolve) => {
+      ctx.emitter.once('context.apply_compaction', () => {
+        resolve();
+      });
+    });
+
+    ctx.mockNextResponse({ type: 'text', text: 'Compacted summary.' });
+    await ctx.rpc.beginCompaction({ instruction: 'Keep the important test facts.' });
+    await compacted;
+
+    expect(ctx.newEvents()).toMatchInlineSnapshot(`
+      [wire] context.append_message     { "message": { "role": "user", "content": [ { "type": "text", "text": "old user one" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_message     { "message": { "role": "user", "content": [ { "type": "text", "text": "old user two" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_message     { "message": { "role": "user", "content": [ { "type": "text", "text": "recent user three" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] full_compaction.begin      { "source": "manual", "instruction": "Keep the important test facts.", "time": "<time>" }
+      [emit] compaction.started         { "trigger": "manual", "instruction": "Keep the important test facts." }
+      [wire] usage.record               { "model": "kimi-code", "usage": { "inputOther": 480, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "session", "time": "<time>" }
+      [emit] agent.status.updated       { "model": "kimi-code", "contextTokens": 120, "maxContextTokens": 256000, "contextUsage": 0.00046875, "planMode": false, "permission": "manual", "usage": { "byModel": { "kimi-code": { "inputOther": 480, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 480, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] full_compaction.complete   { "summary": "Compacted summary.", "compactedCount": 4, "tokensBefore": 120, "tokensAfter": 20, "time": "<time>" }
+      [emit] compaction.completed       { "result": { "summary": "Compacted summary.", "compactedCount": 4, "tokensBefore": 120, "tokensAfter": 20 } }
+      [wire] context.apply_compaction   { "summary": "Compacted summary.", "compactedCount": 4, "tokensBefore": 120, "tokensAfter": 20, "time": "<time>" }
+      [emit] agent.status.updated       { "model": "kimi-code", "contextTokens": 20, "maxContextTokens": 256000, "contextUsage": 0.000078125, "planMode": false, "permission": "manual", "usage": { "byModel": { "kimi-code": { "inputOther": 480, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 480, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: []
+      messages:
+        user: text "old user one"
+        assistant: text "old assistant one"
+        user: text "old user two"
+        assistant: text "old assistant two"
+        user: text <compaction-instruction>
+    `);
+    expect(compactHistory(ctx)).toMatchInlineSnapshot(`
+      [
+        {
+          "role": "assistant",
+          "text": "Compacted summary.",
+        },
+        {
+          "role": "user",
+          "text": "recent user three",
+        },
+        {
+          "role": "assistant",
+          "text": "recent assistant three",
+        },
+      ]
+    `);
+    expect(ctx.agent.fullCompaction.compactedHistory).toMatchInlineSnapshot(`
+      [
+        {
+          "text": "--- message 1 role=user ---
+      text:
+        old user one
+
+      --- message 2 role=assistant ---
+      text:
+        old assistant one
+
+      --- message 3 role=user ---
+      text:
+        old user two
+
+      --- message 4 role=assistant ---
+      text:
+        old assistant two
+
+      --- message 5 role=user ---
+      text:
+        recent user three
+
+      --- message 6 role=assistant ---
+      text:
+        recent assistant three",
+        },
+      ]
+    `);
+    expect(records).toContainEqual({
+      event: 'compaction_finished',
+      properties: {
+        trigger_type: 'manual-with-prompt',
+        before_tokens: 120,
+        after_tokens: 20,
+        duration_ms: expect.any(Number),
+        compacted_count: 4,
+        retry_count: 0,
+        llm_input_tokens: 480,
+        llm_output_tokens: 8,
+      },
+    });
+    await ctx.expectResumeMatches();
+  });
+
+  it('projects the compacted prefix before sending the summary request', async () => {
+    const ctx = testAgent({ compactionStrategy: alwaysCompactOnce });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: { type: 'step.begin', uuid: 'empty-placeholder', turnId: '', step: 2 },
+    });
+    appendExchange(ctx, 3, 'old user two', 'old assistant two', 40);
+    const compacted = new Promise<void>((resolve) => {
+      ctx.emitter.once('context.apply_compaction', () => {
+        resolve();
+      });
+    });
+
+    ctx.mockNextResponse({ type: 'text', text: 'Compacted summary.' });
+    await ctx.rpc.beginCompaction({ instruction: 'Keep the important test facts.' });
+    await compacted;
+
+    const [compactionCall] = ctx.llmCalls;
+    expect(compactionCall?.history.map((message) => message.role)).toEqual([
+      'user',
+      'assistant',
+      'user',
+      'assistant',
+      'user',
+    ]);
+    expect(
+      compactionCall?.history.some(
+        (message) =>
+          message.role === 'assistant' &&
+          message.content.length === 0 &&
+          message.toolCalls.length === 0,
+      ),
+    ).toBe(false);
+  });
+
+  it('force-refreshes OAuth credentials on compaction 401 and falls back to login_required when replay 401', async () => {
+    const tokenCalls: Array<boolean | undefined> = [];
+    const authKeys: string[] = [];
+    const providerManager = createOAuthProviderManager(async (options) => {
+      tokenCalls.push(options?.force);
+      return options?.force === true ? 'forced-refresh-token' : 'fresh-token';
+    });
+    const generate: GenerateFn = async (
+      _provider,
+      _system,
+      _tools,
+      _history,
+      _callbacks,
+      options,
+    ) => {
+      authKeys.push(options?.auth?.apiKey ?? '<missing>');
+      if (authKeys.length <= 2) {
+        throw new APIStatusError(401, 'Unauthorized', 'req-compact-401');
+      }
+      return textResult('Recovered compacted summary.');
+    };
+    const ctx = testAgent({ providerManager, generate });
+    ctx.configure();
+    await ctx.rpc.setModel({ model: 'kimi-code' });
+    ctx.newEvents();
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    appendExchange(ctx, 2, 'recent user two', 'recent assistant two', 80);
+    const outcome = onceAny(ctx, ['context.apply_compaction', 'error']);
+
+    await ctx.rpc.beginCompaction({});
+
+    expect(await outcome).toBe('error');
+    expect(ctx.newEvents()).toContainEqual(
+      expect.objectContaining({
+        event: 'error',
+        args: expect.objectContaining({
+          code: 'auth.login_required',
+          details: expect.objectContaining({
+            statusCode: 401,
+            requestId: 'req-compact-401',
+          }),
+        }),
+      }),
+    );
+    expect(authKeys).toEqual(['fresh-token', 'forced-refresh-token']);
+    expect(tokenCalls).toEqual([undefined, undefined, true]);
+    expect(compactHistory(ctx)).toEqual([
+      { role: 'user', text: 'old user one' },
+      { role: 'assistant', text: 'old assistant one' },
+      { role: 'user', text: 'recent user two' },
+      { role: 'assistant', text: 'recent assistant two' },
+    ]);
+
+    const retryOutcome = onceAny(ctx, ['context.apply_compaction', 'error']);
+
+    await ctx.rpc.beginCompaction({});
+
+    expect(await retryOutcome).toBe('context.apply_compaction');
+    expect(authKeys).toEqual(['fresh-token', 'forced-refresh-token', 'fresh-token']);
+    expect(tokenCalls).toEqual([undefined, undefined, true, undefined]);
+    expect(compactHistory(ctx)).toEqual([
+      { role: 'assistant', text: 'Recovered compacted summary.' },
+      { role: 'user', text: 'recent user two' },
+      { role: 'assistant', text: 'recent assistant two' },
+    ]);
+    await ctx.expectResumeMatches();
+  });
+
+  it('fires PreCompact and PostCompact hooks from the compaction module', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'kimi-compact-hooks-'));
+    const hookLog = join(dir, 'hooks.jsonl');
+    const hookCommand = hookPayloadLoggerCommand(hookLog);
+    const ctx = testAgent({
+      hookEngine: new HookEngine(
+        [
+          { event: 'PreCompact', matcher: 'auto', command: hookCommand, timeout: 5 },
+          { event: 'PostCompact', matcher: 'auto', command: hookCommand, timeout: 5 },
+        ],
+        { cwd: dir, sessionId: 'session-hooks' },
+      ),
+    });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    appendExchange(ctx, 2, 'old user two', 'old assistant two', 40);
+    appendExchange(ctx, 3, 'recent user three', 'recent assistant three', 120);
+    const compacted = once(ctx, 'context.apply_compaction');
+
+    ctx.mockNextResponse({ type: 'text', text: 'Compacted summary.' });
+    ctx.agent.fullCompaction.begin({ source: 'auto', instruction: undefined });
+    await compacted;
+    await vi.waitFor(() => {
+      expect(readHookPayloads(hookLog).map((payload) => payload['hook_event_name'])).toEqual([
+        'PreCompact',
+        'PostCompact',
+      ]);
+    });
+
+    const [pre, post] = readHookPayloads(hookLog);
+    expect(pre).toMatchObject({
+      hook_event_name: 'PreCompact',
+      session_id: 'session-hooks',
+      cwd: dir,
+      trigger: 'auto',
+      token_count: 120,
+    });
+    expect(post).toMatchObject({
+      hook_event_name: 'PostCompact',
+      session_id: 'session-hooks',
+      cwd: dir,
+      trigger: 'auto',
+      estimated_token_count: ctx.agent.context.tokenCount,
+    });
+  });
+
+  it('cancels while waiting for a PreCompact hook', async () => {
+    let preCompactSignal: AbortSignal | undefined;
+    const trigger = vi.fn(async (_event: string, args?: HookEngineTriggerArgs) => {
+      preCompactSignal = args?.signal;
+      await new Promise<void>((resolve) => {
+        args?.signal?.addEventListener(
+          'abort',
+          () => {
+            resolve();
+          },
+          { once: true },
+        );
+      });
+      return [];
+    });
+    const ctx = testAgent({ hookEngine: { trigger } as unknown as HookEngine });
+
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    appendExchange(ctx, 2, 'recent user two', 'recent assistant two', 80);
+
+    ctx.agent.fullCompaction.begin({ source: 'manual', instruction: undefined });
+    await vi.waitFor(() => {
+      expect(preCompactSignal).toBeInstanceOf(AbortSignal);
+    });
+    const canceled = once(ctx, 'compaction.cancelled');
+    ctx.agent.fullCompaction.cancel();
+    await canceled;
+
+    expect(trigger).toHaveBeenCalledWith(
+      'PreCompact',
+      expect.objectContaining({
+        matcherValue: 'manual',
+        inputData: expect.objectContaining({ trigger: 'manual' }),
+      }),
+    );
+    expect(preCompactSignal?.aborted).toBe(true);
+    expect(ctx.llmCalls).toHaveLength(0);
+  });
+
+  it('reports compaction retry_count after a retryable generation failure recovers', async () => {
+    const records: TelemetryRecord[] = [];
+    let attempts = 0;
+    const generate: GenerateFn = async () => {
+      attempts += 1;
+      if (attempts === 1) {
+        throw new APIConnectionError('socket hang up');
+      }
+      return textResult('Recovered compacted summary.');
+    };
+    const ctx = testAgent({ generate, telemetry: recordingTelemetry(records) });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    appendExchange(ctx, 2, 'recent user two', 'recent assistant two', 80);
+    const compacted = once(ctx, 'context.apply_compaction');
+
+    await ctx.rpc.beginCompaction({});
+    await compacted;
+
+    expect(attempts).toBe(2);
+    expect(records).toContainEqual({
+      event: 'compaction_finished',
+      properties: expect.objectContaining({
+        trigger_type: 'manual',
+        before_tokens: 80,
+        retry_count: 1,
+      }),
+    });
+    await ctx.expectResumeMatches();
+  });
+
+  it('waits before retrying compaction generation after a retryable failure', async () => {
+    vi.useFakeTimers();
+    const firstAttemptFailed = deferred<void>();
+    let attempts = 0;
+    const generate: GenerateFn = async () => {
+      attempts += 1;
+      if (attempts === 1) {
+        firstAttemptFailed.resolve();
+        throw new APIConnectionError('socket hang up');
+      }
+      return textResult('Recovered compacted summary.');
+    };
+    const ctx = testAgent({ generate });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    appendExchange(ctx, 2, 'recent user two', 'recent assistant two', 80);
+    const compacted = once(ctx, 'context.apply_compaction');
+
+    await ctx.rpc.beginCompaction({});
+    await firstAttemptFailed.promise;
+    await vi.advanceTimersByTimeAsync(299);
+
+    expect(attempts).toBe(1);
+
+    await vi.advanceTimersByTimeAsync(10_000);
+    await compacted;
+
+    expect(attempts).toBe(2);
+    await ctx.expectResumeMatches();
+  });
+
+  it('cancels retry backoff without issuing another compaction request', async () => {
+    vi.useFakeTimers();
+    const firstAttemptFailed = deferred<void>();
+    let attempts = 0;
+    const generate: GenerateFn = async () => {
+      attempts += 1;
+      if (attempts === 1) {
+        firstAttemptFailed.resolve();
+      }
+      throw new APIConnectionError('socket hang up');
+    };
+    const ctx = testAgent({ generate });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    appendExchange(ctx, 2, 'recent user two', 'recent assistant two', 80);
+    const cancelled = once(ctx, 'compaction.cancelled');
+
+    await ctx.rpc.beginCompaction({});
+    await firstAttemptFailed.promise;
+
+    ctx.agent.fullCompaction.cancel();
+    await cancelled;
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    expect(attempts).toBe(1);
+    await ctx.expectResumeMatches();
+  });
+
+  it('cancels the compaction lifecycle when manual compaction generation fails', async () => {
+    const records: TelemetryRecord[] = [];
+    const generate: GenerateFn = async () => {
+      throw new Error('compaction exploded');
+    };
+    const ctx = testAgent({ generate, telemetry: recordingTelemetry(records) });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    appendExchange(ctx, 2, 'recent user two', 'recent assistant two', 80);
+    const failed = once(ctx, 'error');
+
+    await ctx.rpc.beginCompaction({});
+    await failed;
+
+    const events = ctx.newEvents();
+    expect(events).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ type: '[wire]', event: 'full_compaction.cancel' }),
+        expect.objectContaining({ type: '[rpc]', event: 'compaction.cancelled' }),
+        expect.objectContaining({ type: '[rpc]', event: 'error' }),
+      ]),
+    );
+    expect(eventIndex(events, 'compaction.cancelled')).toBeLessThan(eventIndex(events, 'error'));
+    expect(compactHistory(ctx)).toEqual([
+      { role: 'user', text: 'old user one' },
+      { role: 'assistant', text: 'old assistant one' },
+      { role: 'user', text: 'recent user two' },
+      { role: 'assistant', text: 'recent assistant two' },
+    ]);
+    expect(records).toContainEqual({
+      event: 'compaction_failed',
+      properties: {
+        trigger_type: 'manual',
+        before_tokens: 80,
+        duration_ms: expect.any(Number),
+        retry_count: 0,
+        error_type: 'Error',
+      },
+    });
+    expect(
+      records.find((record) => record.event === 'compaction_failed')?.properties,
+    ).not.toHaveProperty('after_tokens');
+    await ctx.expectResumeMatches();
+  });
+
+  it('reports compaction retry_count when retryable generation failures are exhausted', async () => {
+    const records: TelemetryRecord[] = [];
+    let attempts = 0;
+    const generate: GenerateFn = async () => {
+      attempts += 1;
+      throw new APIConnectionError('socket hang up');
+    };
+    const ctx = testAgent({ generate, telemetry: recordingTelemetry(records) });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    appendExchange(ctx, 2, 'recent user two', 'recent assistant two', 80);
+    const failed = once(ctx, 'error');
+
+    await ctx.rpc.beginCompaction({});
+    await failed;
+
+    expect(attempts).toBe(3);
+    expect(records).toContainEqual({
+      event: 'compaction_failed',
+      properties: {
+        trigger_type: 'manual',
+        before_tokens: 80,
+        duration_ms: expect.any(Number),
+        retry_count: 2,
+        error_type: 'APIConnectionError',
+      },
+    });
+    await ctx.expectResumeMatches();
+  });
+
+  it('renders rich compacted history without dropping non-text context', async () => {
+    const ctx = testAgent();
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendRichToolExchange(ctx);
+    const compacted = new Promise<void>((resolve) => {
+      ctx.emitter.once('context.apply_compaction', () => {
+        resolve();
+      });
+    });
+
+    ctx.mockNextResponse({ type: 'text', text: 'Rich summary.' });
+    await ctx.rpc.beginCompaction({});
+    await compacted;
+
+    expect(ctx.agent.fullCompaction.compactedHistory).toMatchInlineSnapshot(`
+      [
+        {
+          "text": "--- message 1 role=user ---
+      text:
+        inspect this image
+      image_url: ms://image-1 (id=image-1)
+
+      --- message 2 role=assistant ---
+      think:
+        checking metadata
+      text:
+        I will call Lookup.
+      tool calls:
+      - call_lookup: Lookup
+      arguments:
+        {
+          "query": "moon",
+          "limit": 2
+        }
+
+      --- message 3 role=tool toolCallId="call_lookup" ---
+      text:
+        lookup result
+      video_url: ms://video-1 (id=video-1)",
+        },
+      ]
+    `);
+    await ctx.expectResumeMatches();
+  });
+
+  it('keeps an unresolved tool exchange out of the compaction prompt', async () => {
+    const ctx = testAgent();
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    appendPartiallyResolvedParallelToolExchange(ctx);
+    const compacted = once(ctx, 'context.apply_compaction');
+
+    ctx.mockNextResponse({ type: 'text', text: 'Compacted before open tools.' });
+    await ctx.rpc.beginCompaction({ instruction: 'Keep stable facts.' });
+    await compacted;
+
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: []
+      messages:
+        user: text "old user one"
+        assistant: text "old assistant one"
+        user: text <compaction-instruction>
+    `);
+    expect(ctx.agent.context.history.map((message) => message.role)).toEqual([
+      'assistant',
+      'user',
+      'assistant',
+      'tool',
+    ]);
+    await ctx.expectResumeMatches();
+  });
+
+  it('keeps messages appended while compacting an unchanged prefix', async () => {
+    const ctx = testAgent();
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    appendExchange(ctx, 2, 'recent user two', 'recent assistant two', 80);
+    const compacted = once(ctx, 'context.apply_compaction');
+
+    ctx.mockNextResponse({ type: 'text', text: 'Compacted prefix.' });
+    await ctx.rpc.beginCompaction({});
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'new user while compacting' }]);
+    await compacted;
+
+    expect(ctx.newEvents()).toMatchInlineSnapshot(`
+      [wire] context.append_message     { "message": { "role": "user", "content": [ { "type": "text", "text": "old user one" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_message     { "message": { "role": "user", "content": [ { "type": "text", "text": "recent user two" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] full_compaction.begin      { "source": "manual", "time": "<time>" }
+      [emit] compaction.started         { "trigger": "manual" }
+      [wire] context.append_message     { "message": { "role": "user", "content": [ { "type": "text", "text": "new user while compacting" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] usage.record               { "model": "kimi-code", "usage": { "inputOther": 460, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "session", "time": "<time>" }
+      [emit] agent.status.updated       { "model": "kimi-code", "contextTokens": 80, "maxContextTokens": 256000, "contextUsage": 0.0003125, "planMode": false, "permission": "manual", "usage": { "byModel": { "kimi-code": { "inputOther": 460, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 460, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] full_compaction.complete   { "summary": "Compacted prefix.", "compactedCount": 2, "tokensBefore": 80, "tokensAfter": 18, "time": "<time>" }
+      [emit] compaction.completed       { "result": { "summary": "Compacted prefix.", "compactedCount": 2, "tokensBefore": 80, "tokensAfter": 18 } }
+      [wire] context.apply_compaction   { "summary": "Compacted prefix.", "compactedCount": 2, "tokensBefore": 80, "tokensAfter": 18, "time": "<time>" }
+      [emit] agent.status.updated       { "model": "kimi-code", "contextTokens": 18, "maxContextTokens": 256000, "contextUsage": 0.0000703125, "planMode": false, "permission": "manual", "usage": { "byModel": { "kimi-code": { "inputOther": 460, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 460, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: []
+      messages:
+        user: text "old user one"
+        assistant: text "old assistant one"
+        user: text <compaction-instruction>
+    `);
+    expect(compactHistory(ctx)).toMatchInlineSnapshot(`
+      [
+        {
+          "role": "assistant",
+          "text": "Compacted prefix.",
+        },
+        {
+          "role": "user",
+          "text": "recent user two",
+        },
+        {
+          "role": "assistant",
+          "text": "recent assistant two",
+        },
+        {
+          "role": "user",
+          "text": "new user while compacting",
+        },
+      ]
+    `);
+    await ctx.expectResumeMatches();
+  });
+
+  it('cancels when the compacted prefix changes before completion', async () => {
+    const ctx = testAgent();
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    appendExchange(ctx, 2, 'recent user two', 'recent assistant two', 80);
+    const canceled = once(ctx, 'full_compaction.cancel');
+
+    ctx.mockNextResponse({ type: 'text', text: 'Stale summary.' });
+    await ctx.rpc.beginCompaction({});
+    await ctx.rpc.clearContext({});
+    await canceled;
+
+    expect(ctx.newEvents()).toMatchInlineSnapshot(`
+      [wire] context.append_message   { "message": { "role": "user", "content": [ { "type": "text", "text": "old user one" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_message   { "message": { "role": "user", "content": [ { "type": "text", "text": "recent user two" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] full_compaction.begin    { "source": "manual", "time": "<time>" }
+      [emit] compaction.started       { "trigger": "manual" }
+      [wire] context.clear            { "time": "<time>" }
+      [emit] agent.status.updated     { "model": "kimi-code", "contextTokens": 0, "maxContextTokens": 256000, "contextUsage": 0, "planMode": false, "permission": "manual" }
+      [wire] usage.record             { "model": "kimi-code", "usage": { "inputOther": 460, "output": 7, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "session", "time": "<time>" }
+      [emit] agent.status.updated     { "model": "kimi-code", "contextTokens": 0, "maxContextTokens": 256000, "contextUsage": 0, "planMode": false, "permission": "manual", "usage": { "byModel": { "kimi-code": { "inputOther": 460, "output": 7, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 460, "output": 7, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] full_compaction.cancel   { "time": "<time>" }
+      [emit] compaction.cancelled     {}
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: []
+      messages:
+        user: text "old user one"
+        assistant: text "old assistant one"
+        user: text <compaction-instruction>
+    `);
+    expect(compactHistory(ctx)).toMatchInlineSnapshot(`[]`);
+    await ctx.expectResumeMatches();
+  });
+
+  it('blocks the turn until auto compaction finishes', async () => {
+    const records: TelemetryRecord[] = [];
+    const ctx = testAgent({ telemetry: recordingTelemetry(records) });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 100);
+    appendExchange(ctx, 2, 'old user two', 'old assistant two', 200);
+    appendExchange(ctx, 3, 'recent user three', 'recent assistant three', 950_000);
+
+    ctx.mockNextResponse({ type: 'text', text: 'Auto compacted summary.' });
+    ctx.mockNextResponse({ type: 'text', text: 'I can answer after compaction.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Answer after compacting' }] });
+
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "old user one" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "old user two" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "recent user three" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Answer after compacting" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Answer after compacting" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] full_compaction.begin       { "source": "auto", "time": "<time>" }
+      [emit] compaction.started          { "trigger": "auto" }
+      [emit] compaction.blocked          { "turnId": 0 }
+      [wire] usage.record                { "model": "kimi-code", "usage": { "inputOther": 487, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "session", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "kimi-code", "contextTokens": 950000, "maxContextTokens": 256000, "contextUsage": 3.7109375, "planMode": false, "permission": "manual", "usage": { "byModel": { "kimi-code": { "inputOther": 487, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 487, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] full_compaction.complete    { "summary": "Auto compacted summary.", "compactedCount": 6, "tokensBefore": 950000, "tokensAfter": 13, "time": "<time>" }
+      [emit] compaction.completed        { "result": { "summary": "Auto compacted summary.", "compactedCount": 6, "tokensBefore": 950000, "tokensAfter": 13 } }
+      [wire] context.apply_compaction    { "summary": "Auto compacted summary.", "compactedCount": 6, "tokensBefore": 950000, "tokensAfter": 13, "time": "<time>" }
+      [emit] agent.status.updated        { "model": "kimi-code", "contextTokens": 13, "maxContextTokens": 256000, "contextUsage": 0.00005078125, "planMode": false, "permission": "manual", "usage": { "byModel": { "kimi-code": { "inputOther": 487, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 487, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "I can answer after compaction." }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "I can answer after compaction." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "usage": { "inputOther": 16, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 0, "step": 1, "stepId": "<uuid-1>", "usage": { "inputOther": 16, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+      [wire] usage.record                { "model": "kimi-code", "usage": { "inputOther": 16, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "kimi-code", "contextTokens": 27, "maxContextTokens": 256000, "contextUsage": 0.00010546875, "planMode": false, "permission": "manual", "usage": { "byModel": { "kimi-code": { "inputOther": 503, "output": 20, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 503, "output": 20, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 16, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [emit] turn.ended                  { "turnId": 0, "reason": "completed" }
+    `);
+    expect(ctx.llmInputs()).toMatchInlineSnapshot(`
+      call 1:
+        system: <system-prompt>
+        tools: []
+        messages:
+          user: text "old user one"
+          assistant: text "old assistant one"
+          user: text "old user two"
+          assistant: text "old assistant two"
+          user: text "recent user three"
+          assistant: text "recent assistant three"
+          user: text <compaction-instruction>
+
+      call 2:
+        messages:
+          assistant: text "Auto compacted summary."
+          user: text "Answer after compacting"
+    `);
+    expect(records).toContainEqual({
+      event: 'compaction_finished',
+      properties: expect.objectContaining({
+        trigger_type: 'auto',
+        before_tokens: 950000,
+        after_tokens: 13,
+        compacted_count: 6,
+        retry_count: 0,
+      }),
+    });
+    await ctx.expectResumeMatches();
+  });
+
+  it('does not auto compact when an oversized first prompt has no compactable prefix', async () => {
+    const ctx = testAgent();
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: {
+        ...CATALOGUED_MODEL_CAPABILITIES,
+        max_context_tokens: 2_000,
+      },
+    });
+    const oversizedPrompt = `initial-pending-verbatim:${'x'.repeat(8_000)}`;
+
+    ctx.mockNextResponse({ type: 'text', text: 'I can answer the initial prompt.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: oversizedPrompt }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(eventIndex(events, 'compaction.started')).toBe(-1);
+    expect(ctx.llmCalls).toHaveLength(1);
+    expect(messageText(ctx.llmCalls[0]?.history.at(-1))).toBe(oversizedPrompt);
+    await ctx.expectResumeMatches();
+  });
+
+  it('cancels manual compaction without leaving compaction stuck when no prefix is compactable', async () => {
+    const ctx = testAgent();
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'only pending user' }]);
+    const canceled = once(ctx, 'compaction.cancelled');
+
+    await ctx.rpc.beginCompaction({});
+    await canceled;
+
+    expect(ctx.llmCalls).toHaveLength(0);
+
+    ctx.agent.context.clear();
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    appendExchange(ctx, 2, 'recent user two', 'recent assistant two', 80);
+    const compacted = once(ctx, 'context.apply_compaction');
+
+    ctx.mockNextResponse({ type: 'text', text: 'Compacted after no-op cancel.' });
+    await ctx.rpc.beginCompaction({});
+    await compacted;
+
+    expect(ctx.llmCalls).toHaveLength(1);
+    expect(compactHistory(ctx)).toEqual([
+      { role: 'assistant', text: 'Compacted after no-op cancel.' },
+      { role: 'user', text: 'recent user two' },
+      { role: 'assistant', text: 'recent assistant two' },
+    ]);
+    await ctx.expectResumeMatches();
+  });
+
+  it('does not auto compact small contexts when reserved size exceeds the model window', async () => {
+    const providerManager = new ProviderManager({
+      config: {
+        providers: {},
+        loopControl: {
+          reservedContextSize: 50_000,
+        },
+      },
+    });
+    const ctx = testAgent({ providerManager });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: {
+        ...CATALOGUED_MODEL_CAPABILITIES,
+        max_context_tokens: 32_000,
+      },
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 1_000);
+
+    ctx.mockNextResponse({ type: 'text', text: 'I can answer without reserved compaction.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'small prompt' }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(eventIndex(events, 'compaction.started')).toBe(-1);
+    expect(ctx.llmCalls).toHaveLength(1);
+    expect(ctx.llmCalls[0]?.history.map(messageText)).toContain('old assistant one');
+    expect(messageText(ctx.llmCalls[0]?.history.at(-1))).toBe('small prompt');
+    await ctx.expectResumeMatches();
+  });
+
+  it('triggers auto compaction when pending tokens cross the reserved threshold', async () => {
+    const providerManager = new ProviderManager({
+      config: {
+        providers: {},
+        loopControl: {
+          reservedContextSize: 500,
+        },
+      },
+    });
+    const ctx = testAgent({ providerManager });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: {
+        ...CATALOGUED_MODEL_CAPABILITIES,
+        max_context_tokens: 2_000,
+      },
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 1_400);
+
+    ctx.mockNextResponse({ type: 'text', text: 'Reserved compacted summary.' });
+    ctx.mockNextResponse({ type: 'text', text: 'I can answer after reserved compaction.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'x'.repeat(440) }] });
+    await ctx.untilTurnEnd();
+
+    expect(ctx.llmCalls).toHaveLength(2);
+    const [compactionCall, answerCall] = ctx.llmCalls;
+    expect(messageText(compactionCall?.history.at(-1))).toContain('<!-- Compression Priorities');
+    expect(answerCall?.history.map(messageText)).toContain('Reserved compacted summary.');
+    await ctx.expectResumeMatches();
+  });
+
+  it('keeps an oversized pending user prompt out of auto compaction', async () => {
+    const ctx = testAgent();
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: {
+        ...CATALOGUED_MODEL_CAPABILITIES,
+        max_context_tokens: 2_000,
+      },
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 1_650);
+    const oversizedPrompt = `keep-this-pending-verbatim:${'x'.repeat(1_800)}`;
+
+    ctx.mockNextResponse({ type: 'text', text: 'Oversized prompt summary.' });
+    ctx.mockNextResponse({ type: 'text', text: 'I can answer the oversized prompt.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: oversizedPrompt }] });
+    await ctx.untilTurnEnd();
+
+    expect(ctx.llmCalls).toHaveLength(2);
+    const [compactionCall, answerCall] = ctx.llmCalls;
+    const compactionTexts = compactionCall?.history.map(messageText) ?? [];
+    expect(compactionTexts.some((text) => text.includes('keep-this-pending-verbatim'))).toBe(false);
+    expect(compactionCall?.history.map((message) => message.role)).toEqual(['user', 'assistant', 'user']);
+    expect(answerCall?.history.map(messageText)).toContain('Oversized prompt summary.');
+    expect(messageText(answerCall?.history.at(-1))).toBe(oversizedPrompt);
+    await ctx.expectResumeMatches();
+  });
+
+  it('triggers auto compaction when pending tokens cross the ratio threshold', async () => {
+    const ctx = testAgent();
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: {
+        ...CATALOGUED_MODEL_CAPABILITIES,
+        max_context_tokens: 1_000_000,
+      },
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 840_000);
+    const pendingPrompt = `ratio-pending-verbatim:${'x'.repeat(60_000)}`;
+
+    ctx.mockNextResponse({ type: 'text', text: 'Ratio compacted summary.' });
+    ctx.mockNextResponse({ type: 'text', text: 'I can answer the ratio pending prompt.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: pendingPrompt }] });
+    await ctx.untilTurnEnd();
+
+    expect(ctx.llmCalls).toHaveLength(2);
+    const [compactionCall, answerCall] = ctx.llmCalls;
+    const compactionTexts = compactionCall?.history.map(messageText) ?? [];
+    expect(compactionTexts.some((text) => text.includes('ratio-pending-verbatim'))).toBe(false);
+    expect(compactionCall?.history.map((message) => message.role)).toEqual(['user', 'assistant', 'user']);
+    expect(answerCall?.history.map(messageText)).toContain('Ratio compacted summary.');
+    expect(messageText(answerCall?.history.at(-1))).toBe(pendingPrompt);
+
+    await ctx.expectResumeMatches();
+  });
+
+  it('compacts and retries when the provider reports context overflow', async () => {
+    let callCount = 0;
+    const inputs: string[][] = [];
+    const generate: GenerateFn = async (_provider, _system, _tools, history, callbacks) => {
+      callCount += 1;
+      inputs.push(inputHistorySnapshot(history));
+      if (callCount === 1) {
+        throw new APIContextOverflowError(400, 'Context length exceeded', 'req-context-overflow');
+      }
+      if (callCount === 2) {
+        return textResult('Overflow compacted summary.');
+      }
+      if (callCount === 3) {
+        await callbacks?.onMessagePart?.({
+          type: 'text',
+          text: 'Recovered after overflow compaction.',
+        });
+        return textResult('Recovered after overflow compaction.');
+      }
+      throw new Error(`Unexpected generate call ${String(callCount)}`);
+    };
+    const ctx = testAgent({ generate });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    ctx.newEvents();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Retry after provider overflow' }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(callCount).toBe(3);
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'compaction.started',
+        args: { trigger: 'auto' },
+      }),
+    );
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'context.apply_compaction',
+        args: expect.objectContaining({
+          summary: 'Overflow compacted summary.',
+          compactedCount: 2,
+        }),
+      }),
+    );
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: { turnId: 0, reason: 'completed' },
+      }),
+    );
+    expect(inputs).toMatchInlineSnapshot(`
+      [
+        [
+          "user: old user one",
+          "assistant: old assistant one",
+          "user: Retry after provider overflow",
+        ],
+        [
+          "user: old user one",
+          "assistant: old assistant one",
+          "user: <compaction-instruction>",
+        ],
+        [
+          "assistant: Overflow compacted summary.",
+          "user: Retry after provider overflow",
+        ],
+      ]
+    `);
+    await ctx.expectResumeMatches();
+  });
+
+  it('compacts provider overflow when model context size is unknown', async () => {
+    let callCount = 0;
+    const generate: GenerateFn = async (_provider, _system, _tools, history, callbacks) => {
+      callCount += 1;
+      if (callCount === 1) {
+        throw new APIContextOverflowError(400, 'Context length exceeded', 'req-unknown-context');
+      }
+      if (callCount === 2) {
+        return textResult('Unknown window compacted summary.');
+      }
+      if (callCount === 3) {
+        await callbacks?.onMessagePart?.({
+          type: 'text',
+          text: 'Recovered with unknown context size.',
+        });
+        return textResult('Recovered with unknown context size.');
+      }
+      throw new Error(`Unexpected generate call ${String(callCount)}`);
+    };
+    const ctx = testAgent({ generate });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: CATALOGUED_MODEL_CAPABILITIES,
+    });
+    const providerManager = ctx.agent.providerManager;
+    if (providerManager === undefined) throw new Error('Expected provider manager');
+    const resolveProviderConfig = providerManager.resolveProviderConfigForModel.bind(providerManager);
+    providerManager.resolveProviderConfigForModel = (model) => {
+      const resolved = resolveProviderConfig(model);
+      return resolved === undefined
+        ? undefined
+        : { ...resolved, modelCapabilities: UNKNOWN_CAPABILITY };
+    };
+    expect(ctx.agent.config.modelCapabilities.max_context_tokens).toBe(0);
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    ctx.newEvents();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Retry without known model window' }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(callCount).toBe(3);
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'compaction.started',
+        args: { trigger: 'auto' },
+      }),
+    );
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'context.apply_compaction',
+        args: expect.objectContaining({
+          summary: 'Unknown window compacted summary.',
+          compactedCount: 2,
+        }),
+      }),
+    );
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: { turnId: 0, reason: 'completed' },
+      }),
+    );
+  });
+
+  it('does not compact a prefix when the retained pending prompt already exceeds the model window', async () => {
+    let callCount = 0;
+    const inputs: string[][] = [];
+    const generate: GenerateFn = async (_provider, _system, _tools, history) => {
+      callCount += 1;
+      inputs.push(inputHistorySnapshot(history));
+      throw new APIContextOverflowError(400, 'Context length exceeded', 'req-oversized-pending');
+    };
+    const ctx = testAgent({ generate });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: {
+        ...CATALOGUED_MODEL_CAPABILITIES,
+        max_context_tokens: 2_000,
+      },
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 20);
+    const oversizedPrompt = `uncompactable-pending:${'x'.repeat(9_000)}`;
+    ctx.newEvents();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: oversizedPrompt }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(callCount).toBe(1);
+    expect(eventIndex(events, 'compaction.started')).toBe(-1);
+    expect(inputs).toHaveLength(1);
+    expect(inputs[0]?.at(-1)).toBe(`user: ${oversizedPrompt}`);
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: expect.objectContaining({ reason: 'failed' }),
+      }),
+    );
+    await ctx.expectResumeMatches();
+  });
+
+  it('ignores filtered assistant placeholders when checking the retained overflow suffix', async () => {
+    let callCount = 0;
+    const generate: GenerateFn = async (_provider, _system, _tools, history, callbacks) => {
+      callCount += 1;
+      if (callCount === 1) {
+        throw new APIContextOverflowError(
+          400,
+          'Context length exceeded',
+          'req-placeholder-boundary',
+        );
+      }
+      if (callCount === 2) {
+        return textResult('Placeholder compacted summary.');
+      }
+      if (callCount === 3) {
+        await callbacks?.onMessagePart?.({
+          type: 'text',
+          text: 'Recovered after ignoring the placeholder.',
+        });
+        return textResult('Recovered after ignoring the placeholder.');
+      }
+      throw new Error(`Unexpected generate call ${String(callCount)}`);
+    };
+    const ctx = testAgent({
+      generate,
+      compactionStrategy: overflowOnlyCompactionStrategy(),
+    });
+    ctx.configure({
+      provider: CATALOGUED_PROVIDER,
+      modelCapabilities: {
+        ...CATALOGUED_MODEL_CAPABILITIES,
+        max_context_tokens: 14,
+      },
+    });
+    appendExchange(ctx, 1, 'old user one', 'old assistant one', 1);
+    const promptThatFitsWithoutPlaceholder = 'x'.repeat(40);
+    ctx.newEvents();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: promptThatFitsWithoutPlaceholder }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(callCount).toBe(3);
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'compaction.started',
+        args: { trigger: 'auto' },
+      }),
+    );
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'context.apply_compaction',
+        args: expect.objectContaining({
+          summary: 'Placeholder compacted summary.',
+          compactedCount: 2,
+        }),
+      }),
+    );
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: { turnId: 0, reason: 'completed' },
+      }),
+    );
+  });
+
+  it('emits context.overflow and terminates the turn after too many auto compactions', async () => {
+    const ctx = testAgent({ compactionStrategy: alwaysCompactOnce });
+    ctx.configure();
+
+    ctx.mockNextResponse({ type: 'text', text: 'First compacted summary.' });
+    ctx.mockNextResponse({ type: 'text', text: 'I need a tool.' }, missingToolCall());
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Trigger repeated compaction' }] });
+
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Trigger repeated compaction" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Trigger repeated compaction" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] full_compaction.begin       { "source": "auto", "time": "<time>" }
+      [emit] compaction.started          { "trigger": "auto" }
+      [emit] compaction.blocked          { "turnId": 0 }
+      [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 456, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "session", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 0, "maxContextTokens": 1000000, "contextUsage": 0, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 456, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 456, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] full_compaction.complete    { "summary": "First compacted summary.", "compactedCount": 1, "tokensBefore": 0, "tokensAfter": 6, "time": "<time>" }
+      [emit] compaction.completed        { "result": { "summary": "First compacted summary.", "compactedCount": 1, "tokensBefore": 0, "tokensAfter": 6 } }
+      [wire] context.apply_compaction    { "summary": "First compacted summary.", "compactedCount": 1, "tokensBefore": 0, "tokensAfter": 6, "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 6, "maxContextTokens": 1000000, "contextUsage": 0.000006, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 456, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 456, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "I need a tool." }
+      [emit] tool.call.delta             { "turnId": 0, "toolCallId": "call_missing", "name": "MissingTool", "argumentsPart": "{}" }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "I need a tool." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "tool.call", "uuid": "call_missing", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "toolCallId": "call_missing", "name": "MissingTool", "args": {} }, "time": "<time>" }
+      [emit] tool.call.started           { "turnId": 0, "toolCallId": "call_missing", "name": "MissingTool", "args": {} }
+      [wire] context.append_loop_event   { "event": { "type": "tool.result", "parentUuid": "call_missing", "toolCallId": "call_missing", "result": { "output": "Tool \\"MissingTool\\" not found", "isError": true } }, "time": "<time>" }
+      [emit] tool.result                 { "turnId": 0, "toolCallId": "call_missing", "output": "Tool \\"MissingTool\\" not found", "isError": true }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "usage": { "inputOther": 9, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 0, "step": 1, "stepId": "<uuid-1>", "usage": { "inputOther": 9, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }
+      [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 9, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 20, "maxContextTokens": 1000000, "contextUsage": 0.00002, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 465, "output": 20, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 465, "output": 20, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 9, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [emit] turn.step.interrupted       { "turnId": 0, "step": 2, "reason": "error", "message": "Compaction limit exceeded (1)" }
+      [emit] turn.ended                  { "turnId": 0, "reason": "failed", "error": { "code": "context.overflow", "message": "Compaction limit exceeded (1)", "name": "KimiError", "details": { "maxCompactions": 1, "turnId": 0 }, "retryable": true } }
+    `);
+    expect(ctx.newEvents()).toMatchInlineSnapshot(
+      `[emit] error   { "code": "context.overflow", "message": "Compaction limit exceeded (1)", "name": "KimiError", "details": { "maxCompactions": 1, "turnId": 0 }, "retryable": true }`,
+    );
+    expect(ctx.llmInputs()).toMatchInlineSnapshot(`
+      call 1:
+        system: <system-prompt>
+        tools: []
+        messages:
+          user: text "Trigger repeated compaction"
+          user: text <compaction-instruction>
+
+      call 2:
+        messages:
+          assistant: text "First compacted summary."
+    `);
+    await ctx.expectResumeMatches();
+  });
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+function once(ctx: TestAgentContext, type: string): Promise<void> {
+  return new Promise((resolve) => {
+    ctx.emitter.once(type, () => {
+      resolve();
+    });
+  });
+}
+
+function onceAny(ctx: TestAgentContext, types: readonly string[]): Promise<string> {
+  return new Promise((resolve) => {
+    for (const type of types) {
+      ctx.emitter.once(type, () => {
+        resolve(type);
+      });
+    }
+  });
+}
+
+function deferred<T>() {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+}
+
+function eventIndex(events: ReturnType<TestAgentContext['newEvents']>, type: string): number {
+  return events.findIndex((event) => {
+    if (typeof event !== 'object' || event === null) return false;
+    return (event as { readonly event?: unknown }).event === type;
+  });
+}
+
+function createOAuthProviderManager(
+  getAccessToken: (options?: { readonly force?: boolean }) => Promise<string>,
+): ProviderManager {
+  const oauthConfig: KimiConfig = {
+    defaultModel: 'kimi-code',
+    providers: {
+      'managed:kimi-code': {
+        type: 'vertexai',
+        baseUrl: 'https://api.example/v1',
+        oauth: { storage: 'file', key: 'oauth/kimi-code' },
+      },
+    },
+    models: {
+      'kimi-code': {
+        provider: 'managed:kimi-code',
+        model: 'kimi-for-coding',
+        maxContextSize: 1_000_000,
+      },
+    },
+  };
+  return new ProviderManager({
+    config: oauthConfig,
+    resolveOAuthTokenProvider: () => ({ getAccessToken }),
+  });
+}
+
+function textResult(text: string): Awaited<ReturnType<GenerateFn>> {
+  return {
+    id: 'mock-compaction-oauth-retry',
+    message: {
+      role: 'assistant',
+      content: [{ type: 'text', text }],
+      toolCalls: [],
+    },
+    usage: {
+      inputOther: 1,
+      output: 1,
+      inputCacheRead: 0,
+      inputCacheCreation: 0,
+    },
+    finishReason: 'completed',
+    rawFinishReason: 'stop',
+  };
+}
+
+function appendExchange(
+  ctx: TestAgentContext,
+  step: number,
+  userText: string,
+  assistantText: string,
+  tokenTotal: number,
+) {
+  const stepUuid = `step-${String(step)}`;
+  ctx.agent.context.appendUserMessage([{ type: 'text', text: userText }]);
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: { type: 'step.begin', uuid: stepUuid, turnId: '', step },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'content.part',
+      uuid: `part-${String(step)}`,
+      turnId: '',
+      step,
+      stepUuid,
+      part: {
+        type: 'text',
+        text: assistantText,
+      },
+    },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'step.end',
+      uuid: stepUuid,
+      turnId: '',
+      step,
+      usage: {
+        inputOther: tokenTotal - 1,
+        output: 1,
+        inputCacheRead: 0,
+        inputCacheCreation: 0,
+      },
+      finishReason: 'end_turn',
+    },
+  });
+}
+
+const alwaysCompactOnce: CompactionStrategy = {
+  shouldCompact: () => true,
+  shouldBlock: () => true,
+  computeCompactCount: (messages: readonly Message[]) => messages.length,
+  checkAfterStep: true,
+  maxCompactionPerTurn: 1,
+};
+
+function missingToolCall(): ToolCall {
+  return {
+    type: 'function',
+    id: 'call_missing',
+    function: {
+      name: 'MissingTool',
+      arguments: '{}',
+    },
+  };
+}
+
+function compactHistory(ctx: TestAgentContext) {
+  return ctx.agent.context.history.map((message) => ({
+    role: message.role,
+    text: message.content.map((part) => (part.type === 'text' ? part.text : '')).join(''),
+  }));
+}
+
+function testCompactionStrategy(): DefaultCompactionStrategy {
+  return new DefaultCompactionStrategy({
+    triggerRatio: 0.85,
+    blockRatio: 0.85,
+    reservedContextSize: 0,
+    maxCompactionPerTurn: 3,
+    maxRecentSteps: 10,
+    maxRecentUserMessages: Infinity,
+    maxRecentSizeRatio: 0.2,
+  });
+}
+
+function overflowOnlyCompactionStrategy(): DefaultCompactionStrategy {
+  return new DefaultCompactionStrategy({
+    triggerRatio: Infinity,
+    blockRatio: Infinity,
+    reservedContextSize: 0,
+    maxCompactionPerTurn: 3,
+    maxRecentSteps: 3,
+    maxRecentUserMessages: Infinity,
+    maxRecentSizeRatio: 0.2,
+  });
+}
+
+function textMessage(role: 'user' | 'assistant', text: string): Message {
+  return {
+    role,
+    content: [{ type: 'text', text }],
+    toolCalls: [],
+  };
+}
+
+function messageText(message: Message | undefined): string {
+  return message?.content.map((part) => (part.type === 'text' ? part.text : '')).join('') ?? '';
+}
+
+function hookPayloadLoggerCommand(logPath: string): string {
+  const script = [
+    "const fs = require('node:fs');",
+    "let input = '';",
+    "process.stdin.on('data', (chunk) => { input += chunk; });",
+    "process.stdin.on('end', () => {",
+    `  fs.appendFileSync(${JSON.stringify(logPath)}, JSON.stringify(JSON.parse(input)) + '\\n');`,
+    '});',
+  ].join('');
+  return `node -e ${JSON.stringify(script)}`;
+}
+
+function readHookPayloads(logPath: string): Array<Record<string, unknown>> {
+  if (!existsSync(logPath)) return [];
+  const text = readFileSync(logPath, 'utf-8').trim();
+  if (text.length === 0) return [];
+  return text.split('\n').map((line) => JSON.parse(line) as Record<string, unknown>);
+}
+
+function inputHistorySnapshot(history: readonly Message[]): string[] {
+  return history.map((message) => {
+    const text = message.content
+      .map((part) => (part.type === 'text' ? normalizeInputText(part.text) : ''))
+      .join('');
+    return `${message.role}: ${text}`;
+  });
+}
+
+function normalizeInputText(text: string): string {
+  return text.includes('compact this conversation context') ? '<compaction-instruction>' : text;
+}
+
+function appendRichToolExchange(ctx: TestAgentContext) {
+  const stepUuid = 'rich-step';
+  ctx.agent.context.appendUserMessage([
+    { type: 'text', text: 'inspect this image' },
+    { type: 'image_url', imageUrl: { url: 'ms://image-1', id: 'image-1' } },
+  ]);
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: { type: 'step.begin', uuid: stepUuid, turnId: '', step: 1 },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'content.part',
+      uuid: 'rich-think',
+      turnId: '',
+      step: 1,
+      stepUuid,
+      part: {
+        type: 'think',
+        think: 'checking metadata',
+      },
+    },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'content.part',
+      uuid: 'rich-text',
+      turnId: '',
+      step: 1,
+      stepUuid,
+      part: {
+        type: 'text',
+        text: 'I will call Lookup.',
+      },
+    },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'tool.call',
+      uuid: 'rich-tool-call',
+      turnId: '',
+      step: 1,
+      stepUuid,
+      toolCallId: 'call_lookup',
+      name: 'Lookup',
+      args: {
+        query: 'moon',
+        limit: 2,
+      },
+    },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'step.end',
+      uuid: stepUuid,
+      turnId: '',
+      step: 1,
+      usage: {
+        inputOther: 50,
+        output: 10,
+        inputCacheRead: 0,
+        inputCacheCreation: 0,
+      },
+      finishReason: 'tool_use',
+    },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'tool.result',
+      parentUuid: 'rich-tool-call',
+      toolCallId: 'call_lookup',
+      result: {
+        output: [
+          { type: 'text', text: 'lookup result' },
+          { type: 'video_url', videoUrl: { url: 'ms://video-1', id: 'video-1' } },
+        ],
+      },
+    },
+  });
+}
+
+function appendPartiallyResolvedParallelToolExchange(ctx: TestAgentContext) {
+  const stepUuid = 'partial-tool-step';
+  ctx.agent.context.appendUserMessage([{ type: 'text', text: 'run both tools' }]);
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: { type: 'step.begin', uuid: stepUuid, turnId: '', step: 2 },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'tool.call',
+      uuid: 'call_open_one',
+      turnId: '',
+      step: 2,
+      stepUuid,
+      toolCallId: 'call_open_one',
+      name: 'LookupOne',
+      args: { query: 'one' },
+    },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'tool.call',
+      uuid: 'call_open_two',
+      turnId: '',
+      step: 2,
+      stepUuid,
+      toolCallId: 'call_open_two',
+      name: 'LookupTwo',
+      args: { query: 'two' },
+    },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'tool.result',
+      parentUuid: 'call_open_one',
+      toolCallId: 'call_open_one',
+      result: {
+        output: 'one result',
+      },
+    },
+  });
+}
diff --git a/packages/agent-core/test/agent/config-state.test.ts b/packages/agent-core/test/agent/config-state.test.ts
new file mode 100644
index 000000000..fd17f0869
--- /dev/null
+++ b/packages/agent-core/test/agent/config-state.test.ts
@@ -0,0 +1,122 @@
+import { UNKNOWN_CAPABILITY } from '@moonshot-ai/kosong';
+import { describe, expect, it } from 'vitest';
+
+import { ProviderManager } from '../../src/providers/provider-manager';
+import { testAgent } from './harness';
+
+describe('ConfigState model capabilities', () => {
+  it('computes provider and model capabilities from ProviderManager metadata', () => {
+    const ctx = testAgent({
+      providerManager: new ProviderManager({
+        config: {
+          providers: {
+            kimi: {
+              type: 'kimi',
+              apiKey: 'test-key',
+            },
+          },
+          models: {
+            'kimi-code/kimi-for-coding': {
+              provider: 'kimi',
+              model: 'kimi-for-coding',
+              maxContextSize: 1_000_000,
+              capabilities: ['image_in', 'video_in', 'thinking', 'tool_use'],
+            },
+          },
+        },
+      }),
+    });
+    const config = ctx.agent.config;
+
+    config.update({ modelAlias: 'kimi-code/kimi-for-coding' });
+
+    expect(config.model).toBe('kimi-code/kimi-for-coding');
+    expect(config.providerConfig.model).toBe('kimi-for-coding');
+    expect(config.modelCapabilities).toMatchObject({
+      image_in: true,
+      video_in: true,
+      audio_in: false,
+      thinking: true,
+      tool_use: true,
+      max_context_tokens: 1_000_000,
+    });
+  });
+
+  it('does not infer Kimi capabilities from the provider catalogue', () => {
+    const ctx = testAgent({
+      providerManager: new ProviderManager({
+        config: {
+          providers: {
+            kimi: {
+              type: 'kimi',
+              apiKey: 'test-key',
+            },
+          },
+          models: {
+            'kimi-code': {
+              provider: 'kimi',
+              model: 'kimi-code',
+              maxContextSize: 128_000,
+            },
+          },
+        },
+      }),
+    });
+    const config = ctx.agent.config;
+
+    config.update({ modelAlias: 'kimi-code' });
+
+    expect(config.modelCapabilities).toMatchObject({
+      image_in: false,
+      video_in: false,
+      audio_in: false,
+      max_context_tokens: 128_000,
+    });
+  });
+
+  it('clears the selected model when modelAlias is cleared', () => {
+    const ctx = testAgent();
+    ctx.configure();
+    const config = ctx.agent.config;
+
+    config.update({ modelAlias: undefined });
+
+    expect(() => config.model).toThrow('Model not set');
+    expect(config.data().provider).toBeUndefined();
+    expect(config.modelCapabilities).toEqual(UNKNOWN_CAPABILITY);
+  });
+
+  it('uses session id as a provider prompt cache hint without storing it on Agent', () => {
+    const ctx = testAgent({
+      sessionId: 'session-test',
+      providerManager: new ProviderManager({
+        config: {
+          providers: {
+            kimi: {
+              type: 'kimi',
+              apiKey: 'test-key',
+            },
+          },
+          models: {
+            'kimi-code': {
+              provider: 'kimi',
+              model: 'kimi-code',
+              maxContextSize: 128_000,
+            },
+          },
+        },
+      }),
+    });
+    const config = ctx.agent.config;
+
+    config.update({ modelAlias: 'kimi-code' });
+
+    expect(config.providerConfig).toMatchObject({
+      type: 'kimi',
+      generationKwargs: {
+        prompt_cache_key: 'session-test',
+      },
+    });
+    expect('sessionId' in ctx.agent).toBe(false);
+  });
+});
diff --git a/packages/agent-core/test/agent/config.test.ts b/packages/agent-core/test/agent/config.test.ts
new file mode 100644
index 000000000..d73a37aa0
--- /dev/null
+++ b/packages/agent-core/test/agent/config.test.ts
@@ -0,0 +1,210 @@
+import type { ModelCapability, ProviderConfig, ToolCall } from '@moonshot-ai/kosong';
+import { describe, expect, it } from 'vitest';
+
+import type { ResolvedAgentProfile } from '../../src/profile';
+import { createCommandKaos, testAgent } from './harness/agent';
+import { DEFAULT_TEST_SYSTEM_PROMPT } from './harness/snapshots';
+
+describe('Agent config', () => {
+  it('exposes provider, system prompt, thinking level, and model capability updates', async () => {
+    const ctx = testAgent();
+    const initialProvider: ProviderConfig = {
+      type: 'openai',
+      apiKey: 'sk-initial',
+      baseUrl: 'https://initial.example/v1',
+      model: 'gpt-initial',
+    };
+    const initialCapability: ModelCapability = {
+      image_in: true,
+      video_in: false,
+      audio_in: false,
+      thinking: false,
+      tool_use: true,
+      max_context_tokens: 128000,
+    };
+    ctx.configure({
+      provider: initialProvider,
+      modelCapabilities: initialCapability,
+    });
+
+    await expect(ctx.rpc.getConfig({})).resolves.toMatchObject({
+      provider: initialProvider,
+      systemPrompt: DEFAULT_TEST_SYSTEM_PROMPT,
+      thinkingLevel: 'off',
+      modelCapabilities: initialCapability,
+    });
+
+    const nextProvider: ProviderConfig = {
+      type: 'kimi',
+      apiKey: 'sk-next',
+      baseUrl: 'https://next.example/v1',
+      model: 'kimi-next',
+    };
+    const nextCapability: ModelCapability = {
+      image_in: true,
+      video_in: true,
+      audio_in: false,
+      thinking: true,
+      tool_use: true,
+      max_context_tokens: 262144,
+    };
+    ctx.configureRuntimeModel(nextProvider, nextCapability);
+    ctx.agent.config.update({
+      systemPrompt: 'Changed profile prompt.',
+      thinkingLevel: 'high',
+    });
+
+    await expect(ctx.rpc.getConfig({})).resolves.toMatchObject({
+      provider: nextProvider,
+      systemPrompt: 'Changed profile prompt.',
+      thinkingLevel: 'high',
+      modelCapabilities: nextCapability,
+    });
+    await ctx.expectResumeMatches();
+  });
+
+  it('useProfile emits the rendered system prompt and active tools', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+    const profile: ResolvedAgentProfile = {
+      name: 'test-profile',
+      systemPrompt: () => 'Profile system prompt.',
+      tools: ['Bash'],
+    };
+
+    ctx.agent.useProfile(profile);
+
+    expect(ctx.newEvents()).toMatchInlineSnapshot(`
+      [wire] config.update            { "profileName": "test-profile", "systemPrompt": "Profile system prompt.", "time": "<time>" }
+      [emit] agent.status.updated     { "model": "mock-model", "contextTokens": 0, "maxContextTokens": 1000000, "contextUsage": 0, "planMode": false, "permission": "manual" }
+      [wire] tools.set_active_tools   { "names": [ "Bash" ], "time": "<time>" }
+    `);
+    await ctx.expectResumeMatches();
+  });
+
+  it('config.update with cwd initializes builtin tools', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+
+    const tools = await ctx.rpc.getTools({});
+
+    expect(toolNames(tools)).toEqual(
+      expect.arrayContaining(['Bash', 'Read', 'Write', 'Edit', 'Grep', 'Glob']),
+    );
+    await ctx.expectResumeMatches();
+  });
+
+  it('keeps turn-start config for later steps and applies updates to the next turn', async () => {
+    const bashCall: ToolCall = {
+      type: 'function',
+      id: 'call_bash',
+      function: {
+        name: 'Bash',
+        arguments: '{"command":"printf original-result","timeout":60}',
+      },
+    };
+    const ctx = testAgent({ kaos: createCommandKaos('original-result') });
+    ctx.configure({ tools: ['Bash'] });
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will run Bash.' }, bashCall);
+    await ctx.rpc.prompt({
+      input: [{ type: 'text', text: 'Run Bash before config changes' }],
+    });
+    expect(await ctx.untilApproval(true)).toMatchInlineSnapshot(`
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Run Bash before config changes" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Run Bash before config changes" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "I will run Bash." }
+      [emit] tool.call.delta             { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "argumentsPart": "{\\"command\\":\\"printf original-result\\",\\"timeout\\":60}" }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "I will run Bash." } }, "time": "<time>" }
+      [emit] requestApproval             { "turnId": 0, "toolCallId": "call_bash", "toolName": "Bash", "action": "run command", "display": { "kind": "generic", "summary": "Approve Bash", "detail": { "command": "printf original-result", "timeout": 60 } } }
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: Bash
+      messages:
+        user: text "Run Bash before config changes"
+    `);
+
+    ctx.configureRuntimeModel({
+      type: 'kimi',
+      apiKey: 'test-key',
+      model: 'changed-model',
+    });
+    ctx.agent.config.update({ systemPrompt: 'Changed system prompt.' });
+    await ctx.rpc.setActiveTools({ names: [] });
+
+    ctx.mockNextResponse({ type: 'text', text: 'Still using the original turn config.' });
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] permission.record_approval_result   { "turnId": 0, "toolCallId": "call_bash", "toolName": "Bash", "action": "run command", "result": { "decision": "approved", "selectedLabel": "approve" }, "time": "<time>" }
+      [wire] config.update                       { "modelAlias": "changed-model", "time": "<time>" }
+      [emit] agent.status.updated                { "model": "changed-model", "contextTokens": 0, "maxContextTokens": 1000000, "contextUsage": 0, "planMode": false, "permission": "manual" }
+      [wire] config.update                       { "systemPrompt": "Changed system prompt.", "time": "<time>" }
+      [emit] agent.status.updated                { "model": "changed-model", "contextTokens": 0, "maxContextTokens": 1000000, "contextUsage": 0, "planMode": false, "permission": "manual" }
+      [wire] tools.set_active_tools              { "names": [], "time": "<time>" }
+      [wire] context.append_loop_event           { "event": { "type": "tool.call", "uuid": "call_bash", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf original-result", "timeout": 60 }, "description": "Running: printf original-result" }, "time": "<time>" }
+      [emit] tool.call.started                   { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf original-result", "timeout": 60 }, "description": "Running: printf original-result" }
+      [wire] context.append_loop_event           { "event": { "type": "tool.result", "parentUuid": "call_bash", "toolCallId": "call_bash", "result": { "output": "original-result" } }, "time": "<time>" }
+      [emit] tool.result                         { "turnId": 0, "toolCallId": "call_bash", "output": "original-result" }
+      [wire] context.append_loop_event           { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "usage": { "inputOther": 9, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }, "time": "<time>" }
+      [emit] turn.step.completed                 { "turnId": 0, "step": 1, "stepId": "<uuid-1>", "usage": { "inputOther": 9, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }
+      [wire] usage.record                        { "model": "mock-model", "usage": { "inputOther": 9, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated                { "model": "changed-model", "contextTokens": 32, "maxContextTokens": 1000000, "contextUsage": 0.000032, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 9, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 9, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 9, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] context.append_loop_event           { "event": { "type": "step.begin", "uuid": "<uuid-3>", "turnId": "0", "step": 2 }, "time": "<time>" }
+      [emit] turn.step.started                   { "turnId": 0, "step": 2, "stepId": "<uuid-3>" }
+      [emit] assistant.delta                     { "turnId": 0, "delta": "Still using the original turn config." }
+      [wire] context.append_loop_event           { "event": { "type": "content.part", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "stepUuid": "<uuid-3>", "part": { "type": "text", "text": "Still using the original turn config." } }, "time": "<time>" }
+      [wire] context.append_loop_event           { "event": { "type": "step.end", "uuid": "<uuid-3>", "turnId": "0", "step": 2, "usage": { "inputOther": 37, "output": 13, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+      [emit] turn.step.completed                 { "turnId": 0, "step": 2, "stepId": "<uuid-3>", "usage": { "inputOther": 37, "output": 13, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+      [wire] usage.record                        { "model": "mock-model", "usage": { "inputOther": 37, "output": 13, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated                { "model": "changed-model", "contextTokens": 50, "maxContextTokens": 1000000, "contextUsage": 0.00005, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 46, "output": 36, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 46, "output": 36, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 46, "output": 36, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [emit] turn.ended                          { "turnId": 0, "reason": "completed" }
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      messages:
+        <last>
+        assistant: text "I will run Bash."  calls call_bash:Bash { "command": "printf original-result", "timeout": 60 }
+        tool[call_bash]: text "original-result"
+    `);
+
+    ctx.mockNextResponse({ type: 'text', text: 'Now the changed config is active.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Start a fresh turn' }] });
+
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Start a fresh turn" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 1, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Start a fresh turn" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-5>", "turnId": "1", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 1, "step": 1, "stepId": "<uuid-5>" }
+      [emit] assistant.delta             { "turnId": 1, "delta": "Now the changed config is active." }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-6>", "turnId": "1", "step": 1, "stepUuid": "<uuid-5>", "part": { "type": "text", "text": "Now the changed config is active." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-5>", "turnId": "1", "step": 1, "usage": { "inputOther": 56, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 1, "step": 1, "stepId": "<uuid-5>", "usage": { "inputOther": 56, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+      [wire] usage.record                { "model": "changed-model", "usage": { "inputOther": 56, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "changed-model", "contextTokens": 68, "maxContextTokens": 1000000, "contextUsage": 0.000068, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 46, "output": 36, "inputCacheRead": 0, "inputCacheCreation": 0 }, "changed-model": { "inputOther": 56, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 102, "output": 48, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 56, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [emit] turn.ended                  { "turnId": 1, "reason": "completed" }
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: "Changed system prompt."
+      tools: []
+      messages:
+        <last>
+        assistant: text "Still using the original turn config."
+        user: text "Start a fresh turn"
+    `);
+    await ctx.expectResumeMatches();
+  });
+});
+
+function toolNames(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => {
+      if (item === null || typeof item !== 'object') return null;
+      const record = item as Record<string, unknown>;
+      return typeof record['name'] === 'string' ? record['name'] : null;
+    })
+    .filter((name): name is string => name !== null);
+}
diff --git a/packages/agent-core/test/agent/config/thinking.test.ts b/packages/agent-core/test/agent/config/thinking.test.ts
new file mode 100644
index 000000000..255bec915
--- /dev/null
+++ b/packages/agent-core/test/agent/config/thinking.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveThinkingEffort } from '../../../src/agent/config/thinking';
+
+describe('resolveThinkingEffort', () => {
+  describe('without explicit request', () => {
+    it('defaults to high when no config is provided', () => {
+      expect(resolveThinkingEffort(undefined, undefined)).toBe('high');
+    });
+
+    it('returns off when config mode is off', () => {
+      expect(resolveThinkingEffort(undefined, { mode: 'off' })).toBe('off');
+    });
+
+    it('returns high when config mode is on without explicit effort', () => {
+      expect(resolveThinkingEffort(undefined, { mode: 'on' })).toBe('high');
+    });
+
+    it('returns explicit effort when both mode=on and effort are set', () => {
+      expect(resolveThinkingEffort(undefined, { mode: 'on', effort: 'medium' })).toBe('medium');
+    });
+
+    it('uses effort even when mode is omitted', () => {
+      expect(resolveThinkingEffort(undefined, { effort: 'low' })).toBe('low');
+    });
+
+    it('returns off when mode is off even if effort is set', () => {
+      expect(resolveThinkingEffort(undefined, { mode: 'off', effort: 'high' })).toBe('off');
+    });
+  });
+
+  describe('with explicit request', () => {
+    it('returns off when request is "off" regardless of config', () => {
+      expect(resolveThinkingEffort('off', { mode: 'on', effort: 'medium' })).toBe('off');
+    });
+
+    it('returns config effort when request is "on" and config has effort', () => {
+      expect(resolveThinkingEffort('on', { effort: 'medium' })).toBe('medium');
+    });
+
+    it('returns high when request is "on" and config has no effort', () => {
+      expect(resolveThinkingEffort('on', undefined)).toBe('high');
+    });
+
+    it('returns explicit effort level when request is a level name', () => {
+      expect(resolveThinkingEffort('xhigh', undefined)).toBe('xhigh');
+    });
+
+    it('falls back to config effort when request is unknown', () => {
+      expect(resolveThinkingEffort('bogus', { effort: 'low' })).toBe('low');
+    });
+
+    it('falls back to default high when request is unknown and no config', () => {
+      expect(resolveThinkingEffort('bogus', undefined)).toBe('high');
+    });
+
+    it('normalizes case and whitespace', () => {
+      expect(resolveThinkingEffort('  Medium ', undefined)).toBe('medium');
+      expect(resolveThinkingEffort('OFF', { mode: 'on' })).toBe('off');
+    });
+  });
+
+  describe('default behavior', () => {
+    it('uses high as the concrete effort for the default-on state', () => {
+      expect(resolveThinkingEffort(undefined, undefined)).toBe('high');
+      expect(resolveThinkingEffort('on', undefined)).toBe('high');
+    });
+  });
+});
diff --git a/packages/agent-core/test/agent/context.test.ts b/packages/agent-core/test/agent/context.test.ts
new file mode 100644
index 000000000..bd5b8cc6f
--- /dev/null
+++ b/packages/agent-core/test/agent/context.test.ts
@@ -0,0 +1,758 @@
+import type { Message } from '@moonshot-ai/kosong';
+import { describe, expect, it } from 'vitest';
+
+import { sliceCompleteMessages } from '../../src/agent/context/complete-slice';
+import { renderNotificationXml } from '../../src/agent/context/notification-xml';
+import { project } from '../../src/agent/context/projector';
+import { estimateTokensForMessages } from '../../src/utils/tokens';
+import type { TestAgentContext } from './harness/agent';
+import { testAgent } from './harness/agent';
+
+describe('Agent context', () => {
+  it('stores prompt origins without leaking them to LLM projection', () => {
+    const ctx = testAgent();
+    ctx.configure();
+
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'hello' }]);
+    ctx.agent.context.appendSystemReminder('Remember this.', { kind: 'injection', variant: 'host' });
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: { type: 'step.begin', uuid: 'origin-step', turnId: '', step: 1 },
+    });
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: { type: 'step.end', uuid: 'origin-step', turnId: '', step: 1 },
+    });
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.result',
+        parentUuid: 'origin-tool',
+        toolCallId: 'call_origin',
+        result: { output: 'tool output' },
+      },
+    });
+
+    expect(ctx.agent.context.history.map(({ role, origin }) => ({ role, origin }))).toEqual([
+      { role: 'user', origin: { kind: 'user' } },
+      { role: 'user', origin: { kind: 'injection', variant: 'host' } },
+      { role: 'assistant', origin: undefined },
+      { role: 'tool', origin: undefined },
+    ]);
+    expect(ctx.agent.context.messages.some((message) => 'origin' in message)).toBe(false);
+  });
+
+  it('renders tool error and empty-output status as model-visible text', () => {
+    const ctx = testAgent();
+    ctx.configure();
+
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.result',
+        parentUuid: 'call_error',
+        toolCallId: 'call_error',
+        result: { output: 'permission denied', isError: true },
+      },
+    });
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.result',
+        parentUuid: 'call_empty',
+        toolCallId: 'call_empty',
+        result: { output: '' },
+      },
+    });
+
+    expect(ctx.agent.context.messages).toMatchObject([
+      {
+        role: 'tool',
+        content: [
+          { type: 'text', text: '<system>ERROR: Tool execution failed.</system>\npermission denied' },
+        ],
+        toolCallId: 'call_error',
+      },
+      {
+        role: 'tool',
+        content: [{ type: 'text', text: '<system>Tool output is empty.</system>' }],
+        toolCallId: 'call_empty',
+      },
+    ]);
+  });
+
+  it('keeps hook result transcript messages out of LLM projection', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'hooked input' }]);
+    ctx.agent.context.appendMessage({
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text: '<hook_result hook_event="UserPromptSubmit">\nhook response\n</hook_result>',
+        },
+      ],
+      toolCalls: [],
+      origin: { kind: 'hook_result', event: 'UserPromptSubmit' },
+    });
+    ctx.agent.context.appendMessage({
+      role: 'assistant',
+      content: [
+        {
+          type: 'text',
+          text: '<hook_result hook_event="UserPromptSubmit">\nblocked reason\n</hook_result>',
+        },
+      ],
+      toolCalls: [],
+      origin: { kind: 'hook_result', event: 'UserPromptSubmit', blocked: true },
+    });
+    ctx.agent.context.appendMessage({
+      role: 'user',
+      content: [{ type: 'text', text: 'continue from stop hook' }],
+      toolCalls: [],
+      origin: { kind: 'hook_result', event: 'Stop' },
+    });
+
+    expect(ctx.agent.context.history).toHaveLength(4);
+    expect(ctx.agent.context.messages).toEqual([
+      {
+        role: 'user',
+        content: [{ type: 'text', text: 'hooked input\n\ncontinue from stop hook' }],
+        toolCalls: [],
+      },
+    ]);
+    await ctx.expectResumeMatches();
+  });
+
+  it('keeps blocked UserPromptSubmit prompts out of LLM projection', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'blocked prompt' }]);
+    ctx.agent.context.markLastUserPromptBlocked('UserPromptSubmit');
+    ctx.agent.context.appendMessage({
+      role: 'assistant',
+      content: [
+        {
+          type: 'text',
+          text: '<hook_result hook_event="UserPromptSubmit">\nblocked reason\n</hook_result>',
+        },
+      ],
+      toolCalls: [],
+      origin: { kind: 'hook_result', event: 'UserPromptSubmit', blocked: true },
+    });
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'safe followup' }]);
+
+    expect(ctx.agent.context.history).toHaveLength(3);
+    expect(ctx.agent.context.messages).toEqual([
+      {
+        role: 'user',
+        content: [{ type: 'text', text: 'safe followup' }],
+        toolCalls: [],
+      },
+    ]);
+    await ctx.expectResumeMatches();
+  });
+
+  it('projects user, assistant, tool call, and tool result records into LLM history', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+    appendAssistantText(ctx, 1, 'earlier assistant');
+    appendToolExchange(ctx);
+
+    ctx.mockNextResponse({ type: 'text', text: 'done' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'continue' }] });
+
+    await ctx.untilTurnEnd();
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: []
+      messages:
+        user: text "user before step 1"
+        assistant: text "earlier assistant"
+        user: text "lookup something"
+        assistant: text "I will call Lookup."  calls call_lookup:Lookup { "query": "moon" }
+        tool[call_lookup]: text "lookup result"
+        user: text "continue"
+    `);
+    await ctx.expectResumeMatches();
+  });
+
+  it('keeps system reminders separate from real user prompts', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+    ctx.agent.context.appendSystemReminder('Remember the host note.', {
+      kind: 'injection',
+      variant: 'host',
+    });
+
+    ctx.mockNextResponse({ type: 'text', text: 'noted' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Real user prompt' }] });
+
+    await ctx.untilTurnEnd();
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: []
+      messages:
+        user: text "<system-reminder>\\nRemember the host note.\\n</system-reminder>"
+        user: text "Real user prompt"
+    `);
+  });
+
+  it('defers system reminders until pending tool results are recorded and resumed', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+    const stepUuid = 'skill-batch-step';
+
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'load a skill' }]);
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: { type: 'step.begin', uuid: stepUuid, turnId: '0', step: 1 },
+    });
+    for (const [toolCallId, name] of [
+      ['call_write', 'Write'],
+      ['call_skill', 'Skill'],
+    ] as const) {
+      ctx.dispatch({
+        type: 'context.append_loop_event',
+        event: {
+          type: 'tool.call',
+          uuid: toolCallId,
+          turnId: '0',
+          step: 1,
+          stepUuid,
+          toolCallId,
+          name,
+          args: {},
+        },
+      });
+    }
+
+    ctx.dispatch({
+      type: 'context.append_message',
+      message: {
+        role: 'user',
+        content: [{ type: 'text', text: '<system-reminder>\nskill body\n</system-reminder>' }],
+        toolCalls: [],
+        origin: {
+          kind: 'skill_activation',
+          activationId: 'act_skill',
+          skillName: 'demo',
+          trigger: 'model-tool',
+        },
+      },
+    });
+
+    expect(ctx.agent.context.history.map((message) => message.role)).toEqual(['user', 'assistant']);
+
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: {
+        type: 'step.end',
+        uuid: stepUuid,
+        turnId: '0',
+        step: 1,
+        finishReason: 'tool_use',
+      },
+    });
+    expect(ctx.agent.context.history.map((message) => message.role)).toEqual(['user', 'assistant']);
+
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.result',
+        parentUuid: 'call_write',
+        toolCallId: 'call_write',
+        result: { output: 'wrote file' },
+      },
+    });
+    expect(ctx.agent.context.history.map((message) => message.role)).toEqual([
+      'user',
+      'assistant',
+      'tool',
+    ]);
+
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.result',
+        parentUuid: 'call_skill',
+        toolCallId: 'call_skill',
+        result: { output: 'skill loaded' },
+      },
+    });
+
+    expect(ctx.agent.context.messages.map((message) => message.role)).toEqual([
+      'user',
+      'assistant',
+      'tool',
+      'tool',
+      'user',
+    ]);
+    expect(ctx.agent.context.messages[4]?.content).toEqual([
+      { type: 'text', text: '<system-reminder>\nskill body\n</system-reminder>' },
+    ]);
+    await ctx.expectResumeMatches();
+  });
+
+  it('preserves deferred reminders when compaction keeps a pending tool exchange', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'old prompt' }]);
+    appendPartiallyResolvedParallelToolExchange(ctx);
+
+    ctx.agent.context.appendSystemReminder('first reminder', {
+      kind: 'injection',
+      variant: 'host',
+    });
+    ctx.agent.context.applyCompaction({
+      summary: 'summary of old prompt',
+      compactedCount: 1,
+      tokensBefore: 100,
+      tokensAfter: 40,
+    });
+    ctx.agent.context.appendSystemReminder('second reminder', {
+      kind: 'injection',
+      variant: 'host',
+    });
+
+    expect(ctx.agent.context.messages.map((message) => message.role)).toEqual([
+      'assistant',
+      'user',
+      'assistant',
+      'tool',
+    ]);
+
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.result',
+        parentUuid: 'call_open_two',
+        toolCallId: 'call_open_two',
+        result: { output: 'two result' },
+      },
+    });
+
+    expect(ctx.agent.context.messages.map((message) => message.role)).toEqual([
+      'assistant',
+      'user',
+      'assistant',
+      'tool',
+      'tool',
+      'user',
+      'user',
+    ]);
+    expect(ctx.agent.context.messages[5]?.content).toEqual([
+      { type: 'text', text: '<system-reminder>\nfirst reminder\n</system-reminder>' },
+    ]);
+    expect(ctx.agent.context.messages[6]?.content).toEqual([
+      { type: 'text', text: '<system-reminder>\nsecond reminder\n</system-reminder>' },
+    ]);
+    await ctx.expectResumeMatches();
+  });
+
+  it('clears context before the next LLM request', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'stale user message' }]);
+    await ctx.rpc.clearContext({});
+
+    ctx.mockNextResponse({ type: 'text', text: 'fresh' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'fresh prompt' }] });
+
+    await ctx.untilTurnEnd();
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: []
+      messages:
+        user: text "fresh prompt"
+    `);
+    await ctx.expectResumeMatches();
+  });
+
+  it('uses compacted summary plus recent messages', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'old user message' }]);
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'recent user message' }]);
+    ctx.agent.context.applyCompaction({
+      summary: 'summary of old context',
+      compactedCount: 1,
+      tokensBefore: 100,
+      tokensAfter: 20,
+    });
+    expect(ctx.agent.context.history[0]?.origin).toEqual({ kind: 'compaction_summary' });
+
+    ctx.mockNextResponse({ type: 'text', text: 'after compaction' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'new prompt' }] });
+
+    await ctx.untilTurnEnd();
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: []
+      messages:
+        assistant: text "summary of old context"
+        user: text "recent user message\\n\\nnew prompt"
+    `);
+    await ctx.expectResumeMatches();
+  });
+
+  it('includes new user messages as pending until the next usage update', () => {
+    const ctx = testAgent();
+    ctx.configure();
+    appendAssistantTextWithUsage(ctx, 1, 'previous answer', 1_000);
+    expect(ctx.agent.context.tokenCountWithPending).toBe(1_000);
+
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'next user prompt'.repeat(20) }]);
+
+    const pendingMessages = ctx.agent.context.history.slice(-1);
+    expect(ctx.agent.context.tokenCountWithPending).toBe(
+      ctx.agent.context.tokenCount + estimateTokensForMessages([...pendingMessages]),
+    );
+  });
+
+  it('keeps tool results pending when step usage covers only through the assistant message', () => {
+    const ctx = testAgent();
+    ctx.configure();
+    const stepUuid = 'context-pending-tool-step';
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'lookup pending tokens' }]);
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: { type: 'step.begin', uuid: stepUuid, turnId: '0', step: 1 },
+    });
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.call',
+        uuid: 'call_pending_tokens',
+        turnId: '0',
+        step: 1,
+        stepUuid,
+        toolCallId: 'call_pending_tokens',
+        name: 'Lookup',
+        args: {},
+      },
+    });
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.result',
+        parentUuid: 'call_pending_tokens',
+        toolCallId: 'call_pending_tokens',
+        result: { output: 'large tool result '.repeat(50) },
+      },
+    });
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: {
+        type: 'step.end',
+        uuid: stepUuid,
+        turnId: '0',
+        step: 1,
+        usage: {
+          inputOther: 1_200,
+          output: 80,
+          inputCacheRead: 0,
+          inputCacheCreation: 0,
+        },
+        finishReason: 'tool_use',
+      },
+    });
+
+    const pendingMessages = ctx.agent.context.history.slice(-1);
+    expect(ctx.agent.context.tokenCount).toBe(1_280);
+    expect(ctx.agent.context.tokenCountWithPending).toBe(
+      1_280 + estimateTokensForMessages([...pendingMessages]),
+    );
+  });
+
+  it('normalizes message slice ends around tool exchanges', () => {
+    const messages: Message[] = [
+      userMessage('old prompt'),
+      assistantMessage('old answer'),
+      userMessage('run both tools'),
+      assistantToolCallMessage(['call_one', 'call_two']),
+      toolMessage('call_one', 'one result'),
+      toolMessage('call_two', 'two result'),
+      userMessage('recent prompt'),
+    ];
+
+    expect(sliceCompleteMessages(messages, 1)).toBe(1);
+    expect(sliceCompleteMessages(messages, 4)).toBe(2);
+    expect(sliceCompleteMessages(messages, 5)).toBe(2);
+    expect(sliceCompleteMessages(messages, 6)).toBe(6);
+    expect(sliceCompleteMessages(messages, 99)).toBe(7);
+
+    const incomplete = messages.slice(0, 5);
+    expect(sliceCompleteMessages(incomplete, 5)).toBe(2);
+  });
+});
+
+describe('Agent context notification projection', () => {
+  it('renders task notifications with escaped attributes and a bounded output tail', () => {
+    const tail = Array.from({ length: 25 }, (_, index) => `line ${String(index + 1)}`).join('\n');
+
+    const text = renderNotificationXml({
+      id: 'n_"1&2',
+      category: 'task',
+      type: 'task.done',
+      source_kind: 'background_task',
+      source_id: 'bg&1',
+      title: 'Task finished',
+      severity: 'info',
+      body: 'The task completed.',
+      tail_output: tail,
+    });
+
+    expect(text).toContain('id="n_&quot;1&amp;2"');
+    expect(text).toContain('source_id="bg&amp;1"');
+    expect(text).toContain('Title: Task finished');
+    expect(text).toContain('Severity: info');
+    expect(text).toContain('<task-notification>');
+    expect(text).not.toContain('line 5');
+    expect(text).toContain('line 6');
+    expect(text).toContain('line 25');
+    expect(text.trimEnd()).toMatch(/<\/notification>$/);
+  });
+
+  it('does not render task output blocks for non-task notifications', () => {
+    const text = renderNotificationXml({
+      id: '',
+      source_kind: 'host',
+      tail_output: 'should stay out of the XML',
+    });
+
+    expect(text).toContain('id="unknown"');
+    expect(text).toContain('category="unknown"');
+    expect(text).not.toContain('<task-notification>');
+    expect(text).not.toContain('should stay out of the XML');
+  });
+
+  it('keeps pending notification injections separate from real user prompts', () => {
+    const messages = project(
+      [userMessage('Actual user prompt')],
+      [
+        {
+          kind: 'pending_notification',
+          content: {
+            id: 'n_1',
+            category: 'task',
+            type: 'task.done',
+            source_kind: 'background_task',
+            source_id: 'bg_1',
+            title: 'Task done',
+            severity: 'info',
+            body: 'Background task finished.',
+          },
+        },
+      ],
+    );
+
+    expect(messages).toHaveLength(2);
+    expect(textOf(messages[0]!)).toMatch(/^<notification /);
+    expect(textOf(messages[0]!)).toContain('Task done');
+    expect(textOf(messages[1]!)).toBe('Actual user prompt');
+  });
+});
+
+function appendAssistantText(ctx: TestAgentContext, step: number, text: string) {
+  appendAssistantTextWithUsage(ctx, step, text);
+}
+
+function appendAssistantTextWithUsage(
+  ctx: TestAgentContext,
+  step: number,
+  text: string,
+  tokenTotal?: number,
+) {
+  const stepUuid = `context-step-${String(step)}`;
+  const usage =
+    tokenTotal === undefined
+      ? undefined
+      : {
+          inputOther: tokenTotal - 1,
+          output: 1,
+          inputCacheRead: 0,
+          inputCacheCreation: 0,
+        };
+  ctx.agent.context.appendUserMessage([{ type: 'text', text: `user before step ${String(step)}` }]);
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: { type: 'step.begin', uuid: stepUuid, turnId: '', step },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'content.part',
+      uuid: `context-part-${String(step)}`,
+      turnId: '',
+      step,
+      stepUuid,
+      part: {
+        type: 'text',
+        text,
+      },
+    },
+  });
+  ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: {
+        type: 'step.end',
+        uuid: stepUuid,
+        turnId: '',
+        step,
+        usage,
+        finishReason: 'end_turn',
+      },
+    });
+}
+
+function appendToolExchange(ctx: TestAgentContext) {
+  const stepUuid = 'context-tool-step';
+  ctx.agent.context.appendUserMessage([{ type: 'text', text: 'lookup something' }]);
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: { type: 'step.begin', uuid: stepUuid, turnId: '', step: 2 },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'content.part',
+      uuid: 'context-tool-part',
+      turnId: '',
+      step: 2,
+      stepUuid,
+      part: {
+        type: 'text',
+        text: 'I will call Lookup.',
+      },
+    },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'tool.call',
+      uuid: 'context-tool-call',
+      turnId: '',
+      step: 2,
+      stepUuid,
+      toolCallId: 'call_lookup',
+      name: 'Lookup',
+      args: {
+        query: 'moon',
+      },
+    },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'step.end',
+      uuid: stepUuid,
+      turnId: '',
+      step: 2,
+      finishReason: 'tool_use',
+    },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'tool.result',
+      parentUuid: 'context-tool-call',
+      toolCallId: 'call_lookup',
+      result: { output: 'lookup result' },
+    },
+  });
+}
+
+function appendPartiallyResolvedParallelToolExchange(ctx: TestAgentContext) {
+  const stepUuid = 'context-partial-tool-step';
+  ctx.agent.context.appendUserMessage([{ type: 'text', text: 'run both tools' }]);
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: { type: 'step.begin', uuid: stepUuid, turnId: '', step: 2 },
+  });
+  for (const [toolCallId, name] of [
+    ['call_open_one', 'LookupOne'],
+    ['call_open_two', 'LookupTwo'],
+  ] as const) {
+    ctx.dispatch({
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.call',
+        uuid: toolCallId,
+        turnId: '',
+        step: 2,
+        stepUuid,
+        toolCallId,
+        name,
+        args: {},
+      },
+    });
+  }
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'step.end',
+      uuid: stepUuid,
+      turnId: '',
+      step: 2,
+      finishReason: 'tool_use',
+    },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'tool.result',
+      parentUuid: 'call_open_one',
+      toolCallId: 'call_open_one',
+      result: { output: 'one result' },
+    },
+  });
+}
+
+function userMessage(text: string): Message {
+  return {
+    role: 'user',
+    content: [{ type: 'text', text }],
+    toolCalls: [],
+  };
+}
+
+function assistantMessage(text: string): Message {
+  return {
+    role: 'assistant',
+    content: [{ type: 'text', text }],
+    toolCalls: [],
+  };
+}
+
+function assistantToolCallMessage(ids: readonly string[]): Message {
+  return {
+    role: 'assistant',
+    content: [],
+    toolCalls: ids.map((id) => ({
+      type: 'function',
+      id,
+      function: { name: 'Lookup', arguments: '{}' },
+    })),
+  };
+}
+
+function toolMessage(toolCallId: string, text: string): Message {
+  return {
+    role: 'tool',
+    content: [{ type: 'text', text }],
+    toolCalls: [],
+    toolCallId,
+  };
+}
+
+function textOf(message: Message): string {
+  return message.content
+    .filter((part): part is { type: 'text'; text: string } => part.type === 'text')
+    .map((part) => part.text)
+    .join('');
+}
diff --git a/packages/agent-core/test/agent/file-system-record-persistence.test.ts b/packages/agent-core/test/agent/file-system-record-persistence.test.ts
new file mode 100644
index 000000000..723955ee3
--- /dev/null
+++ b/packages/agent-core/test/agent/file-system-record-persistence.test.ts
@@ -0,0 +1,119 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  AGENT_WIRE_PROTOCOL_VERSION,
+  FileSystemAgentRecordPersistence,
+  type AgentRecord,
+} from '../../src/agent/records';
+
+const cleanups: string[] = [];
+
+afterEach(async () => {
+  for (const dir of cleanups.splice(0)) {
+    await rm(dir, { recursive: true, force: true }).catch(() => {});
+  }
+});
+
+async function makeWirePath(): Promise<string> {
+  const dir = join(tmpdir(), `wire-jsonl-test-${randomBytes(6).toString('hex')}`);
+  await mkdir(dir, { recursive: true });
+  cleanups.push(dir);
+  return join(dir, 'wire.jsonl');
+}
+
+async function readLines(path: string): Promise<string[]> {
+  const raw = await readFile(path, 'utf8');
+  return raw.split('\n').filter((line) => line.length > 0);
+}
+
+describe('FileSystemAgentRecordPersistence', () => {
+  it('writes a metadata header on the first append', async () => {
+    const wirePath = await makeWirePath();
+    const persistence = new FileSystemAgentRecordPersistence(wirePath);
+
+    await persistence.append({
+      type: 'turn.prompt',
+      input: [{ type: 'text', text: 'hello' }],
+      origin: { kind: 'user' },
+    });
+    await persistence.close();
+
+    const lines = await readLines(wirePath);
+    expect(lines).toHaveLength(2);
+    const meta = JSON.parse(lines[0]!) as Record<string, unknown>;
+    expect(meta).toMatchObject({
+      type: 'metadata',
+      protocol_version: AGENT_WIRE_PROTOCOL_VERSION,
+    });
+    expect(typeof meta['created_at']).toBe('number');
+  });
+
+  it('does not re-emit a metadata header when the file already has content', async () => {
+    const wirePath = await makeWirePath();
+
+    const first = new FileSystemAgentRecordPersistence(wirePath);
+    await first.append({
+      type: 'turn.prompt',
+      input: [{ type: 'text', text: 'one' }],
+      origin: { kind: 'user' },
+    });
+    await first.close();
+
+    const second = new FileSystemAgentRecordPersistence(wirePath);
+    await second.append({
+      type: 'turn.prompt',
+      input: [{ type: 'text', text: 'two' }],
+      origin: { kind: 'user' },
+    });
+    await second.close();
+
+    const lines = await readLines(wirePath);
+    // 1 metadata + 2 turn.prompt records.
+    expect(lines).toHaveLength(3);
+    const metaLines = lines.filter((l) => l.includes('"type":"metadata"'));
+    expect(metaLines).toHaveLength(1);
+  });
+
+  it('filters the metadata header out of read() output', async () => {
+    const wirePath = await makeWirePath();
+    const persistence = new FileSystemAgentRecordPersistence(wirePath);
+    await persistence.append({
+      type: 'turn.prompt',
+      input: [{ type: 'text', text: 'hi' }],
+      origin: { kind: 'user' },
+    });
+    await persistence.close();
+
+    const reader = new FileSystemAgentRecordPersistence(wirePath);
+    const records: AgentRecord[] = [];
+    for await (const r of reader.read()) records.push(r);
+    expect(records).toHaveLength(1);
+    expect(records[0]!.type).toBe('turn.prompt');
+  });
+
+  it('rejects an append that resumes after close starts', async () => {
+    const wirePath = await makeWirePath();
+    const persistence = new FileSystemAgentRecordPersistence(wirePath);
+
+    const appendPromise = persistence.append({
+      type: 'turn.prompt',
+      input: [{ type: 'text', text: 'late' }],
+      origin: { kind: 'user' },
+    });
+    const closePromise = persistence.close();
+
+    await expect(appendPromise).rejects.toThrow(
+      'FileSystemAgentRecordPersistence: append on closed persistence',
+    );
+    await closePromise;
+
+    const lines = await readLines(wirePath);
+    expect(lines).toHaveLength(1);
+    expect(JSON.parse(lines[0]!)['type']).toBe('metadata');
+  });
+});
diff --git a/packages/agent-core/test/agent/harness/agent.ts b/packages/agent-core/test/agent/harness/agent.ts
new file mode 100644
index 000000000..3e57bb665
--- /dev/null
+++ b/packages/agent-core/test/agent/harness/agent.ts
@@ -0,0 +1,637 @@
+import { EventEmitter } from 'node:events';
+import { Readable, type Writable } from 'node:stream';
+
+import { createControlledPromise } from '@antfu/utils';
+import { localKaos, type Kaos, type KaosProcess } from '@moonshot-ai/kaos';
+import type { ModelCapability, ProviderConfig } from '@moonshot-ai/kosong';
+import { expect, vi } from 'vitest';
+
+import {
+  Agent,
+  type AgentConfig,
+  type AgentRecord,
+  type AgentRecordPersistence,
+} from '../../../src/agent';
+import type { CompactionStrategy } from '../../../src/agent/compaction';
+import type { ApprovalResponse } from '../../../src/agent/permission';
+import type { KimiConfig } from '../../../src/config';
+import type { ExecutableToolResult } from '../../../src/loop';
+import type { Logger } from '../../../src/logging';
+import { ProviderManager } from '../../../src/providers/provider-manager';
+import type { QuestionResult, RPCCallOptions, SDKAgentRPC } from '../../../src/rpc';
+import type { AgentAPI } from '../../../src/rpc/core-api';
+import type { RuntimeConfig } from '../../../src/runtime-types';
+import type { TelemetryClient } from '../../../src/telemetry';
+import type { Environment } from '../../../src/utils/environment';
+import type { PromisifyMethods } from '../../../src/utils/types';
+import { createFakeKaos } from '../../tools/fixtures/fake-kaos';
+import { createScriptedGenerate } from './scripted-generate';
+import {
+  DEFAULT_TEST_SYSTEM_PROMPT,
+  eventSnapshot,
+  type EventSnapshotEntry,
+  type RpcSnapshotEntry,
+  type WireSnapshotEntry,
+} from './snapshots';
+
+const TEST_OS_ENV: Environment = {
+  osKind: 'Linux',
+  osArch: 'x86_64',
+  osVersion: 'test',
+  shellName: 'bash',
+  shellPath: '/bin/bash',
+};
+
+const MOCK_PROVIDER = {
+  type: 'kimi',
+  apiKey: 'test-key',
+  model: 'mock-model',
+} as const;
+
+const RPC_RESPONSE = Symbol('rpcResponse');
+
+type RpcPromise<T> = Promise<T> & {
+  resolve(value: T): void;
+  reject(reason?: unknown): void;
+};
+
+type RpcLogEntry = RpcSnapshotEntry & {
+  readonly [RPC_RESPONSE]?: RpcPromise<unknown>;
+};
+
+type PromiseAgentAPI = PromisifyMethods<AgentAPI>;
+type GenerateFn = NonNullable<AgentConfig['generate']>;
+
+type TestToolResult = ExecutableToolResult & {
+  readonly content?: unknown;
+};
+
+interface ResumeStateSnapshot {
+  readonly background: ReturnType<Agent['background']['list']>;
+  readonly config: {
+    readonly cwd: string;
+    readonly provider: ProviderConfig | undefined;
+    readonly profileName: string | undefined;
+    readonly thinkingLevel: string;
+    readonly systemPrompt: string;
+  };
+  readonly context: ReturnType<Agent['context']['data']>;
+  readonly fullCompaction: Agent['fullCompaction']['compactedHistory'];
+  readonly permission: ReturnType<Agent['permission']['data']>;
+  readonly tools: ReturnType<Agent['tools']['data']>;
+  readonly toolStore: ReturnType<Agent['tools']['storeData']>;
+  readonly usage: ReturnType<Agent['usage']['data']>;
+}
+
+interface TestAgentOptions {
+  readonly kaos?: Kaos | undefined;
+  readonly runtime?: RuntimeConfig | undefined;
+  readonly compactionStrategy?: CompactionStrategy | undefined;
+  readonly generate?: GenerateFn | undefined;
+  readonly hookEngine?: AgentConfig['hookEngine'];
+  readonly type?: AgentConfig['type'];
+  readonly permission?: AgentConfig['permission'];
+  readonly providerManager?: ProviderManager;
+  readonly sessionId?: string;
+  readonly subagentHost?: AgentConfig['subagentHost'];
+  readonly onEvent?: ((event: AgentRecord) => AgentRecord | undefined) | undefined;
+  readonly persistence?: AgentRecordPersistence | undefined;
+  readonly telemetry?: TelemetryClient | undefined;
+  readonly log?: Logger;
+}
+
+interface ConfigureOptions {
+  readonly tools?: readonly string[] | undefined;
+  readonly provider?: ProviderConfig | undefined;
+  readonly modelCapabilities?: ModelCapability | undefined;
+}
+
+export type TestAgentContext = AgentTestContext;
+
+export function createCommandKaos(stdout: string): Kaos {
+  function createProcess(): KaosProcess {
+    return {
+      stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+      stdout: Readable.from([stdout]),
+      stderr: Readable.from(['']),
+      pid: 42,
+      exitCode: 0,
+      wait: vi.fn().mockResolvedValue(0),
+      kill: vi.fn().mockResolvedValue(undefined),
+    };
+  }
+
+  return createFakeKaos({
+    execWithEnv: vi.fn().mockImplementation(async () => createProcess()),
+    mkdir: vi.fn().mockResolvedValue(undefined),
+    writeText: vi.fn(async (_path: string, content: string) => content.length),
+  });
+}
+
+export function testAgent(options: TestAgentOptions = {}): AgentTestContext {
+  return new AgentTestContext(options);
+}
+
+export class AgentTestContext {
+  private readonly options: TestAgentOptions;
+  private readonly scriptedGenerate = createScriptedGenerate();
+  private readonly recordHistory: AgentRecord[] = [];
+  private suppressWireSnapshot = false;
+  private lastEventCount = 0;
+  private readonly uuidLabels = new Map<string, string>();
+
+  readonly emitter = new EventEmitter();
+  readonly allEvents: EventSnapshotEntry[] = [];
+  readonly agent: Agent;
+  readonly rpc: PromiseAgentAPI;
+  readonly llmCalls = this.scriptedGenerate.calls;
+  readonly lastLlmInput = this.scriptedGenerate.lastInput;
+  readonly llmInputs = this.scriptedGenerate.inputs;
+  readonly mockNextResponse = this.scriptedGenerate.mockNextResponse;
+  readonly mockNextProviderResponse = this.scriptedGenerate.mockNextProviderResponse;
+
+  constructor(options: TestAgentOptions = {}) {
+    this.options = options;
+    this.emitter.on('error', () => {});
+    const providerManager = options.providerManager ?? new ProviderManager({ config: emptyConfig() });
+
+    const runtime = options.runtime ?? {
+      kaos: options.kaos ?? localKaos,
+      osEnv: TEST_OS_ENV,
+    };
+    this.agent = new Agent({
+      runtime,
+      rpc: this.createRpcProxy(),
+      persistence:
+        options.persistence === undefined ? undefined : this.wrapPersistence(options.persistence),
+      generate: options.generate ?? this.scriptedGenerate.generate,
+      compactionStrategy: options.compactionStrategy,
+      providerManager,
+      sessionId: options.sessionId,
+      subagentHost: options.subagentHost,
+      type: options.type,
+      permission: options.permission,
+      hookEngine: options.hookEngine,
+      telemetry: options.telemetry,
+      log: options.log,
+    });
+    this.agent.records.onRecord = (event) => {
+      this.captureRecord(event);
+    };
+    this.rpc = this.createPromiseAgentApi(this.agent);
+  }
+
+  configure({
+    tools = [],
+    provider = MOCK_PROVIDER,
+    modelCapabilities,
+  }: ConfigureOptions = {}): void {
+    this.configureRuntimeModel(provider, modelCapabilities);
+    this.agent.config.update({
+      cwd: process.cwd(),
+      modelAlias: provider.model,
+      systemPrompt: DEFAULT_TEST_SYSTEM_PROMPT,
+      thinkingLevel: 'off',
+    });
+
+    if (tools.length > 0) {
+      void this.rpc.setActiveTools({ names: [...tools] });
+    }
+
+    this.lastEventCount = this.allEvents.length;
+  }
+
+  configureRuntimeModel(
+    provider: ProviderConfig,
+    modelCapabilities?: ModelCapability | undefined,
+  ): void {
+    this.agent.providerManager?.updateConfig(
+      configWithProvider(this.agent.providerManager.config, provider, modelCapabilities),
+    );
+    this.agent.config.update({ modelAlias: provider.model });
+  }
+
+  newEvents(): ReturnType<typeof eventSnapshot> {
+    const events = this.allEvents.slice(this.lastEventCount);
+    this.lastEventCount = this.allEvents.length;
+    return eventSnapshot(events, this.uuidLabels);
+  }
+
+  untilTurnEnd(): Promise<ReturnType<typeof eventSnapshot>> {
+    return this.takeUntilRpc('turn.ended').then(({ events }) => events);
+  }
+
+  untilApprovalRequest(): Promise<ReturnType<typeof eventSnapshot>> {
+    return this.takeUntilRpc('requestApproval').then(({ events }) => events);
+  }
+
+  async takeApprovalRequest(): Promise<{
+    events: ReturnType<typeof eventSnapshot>;
+    respond(response: ApprovalResponse): void;
+  }> {
+    const { event, events } = await this.takeUntilRpc('requestApproval');
+    return {
+      events,
+      respond: (response) => {
+        this.resolveRpcRequest(event, response);
+      },
+    };
+  }
+
+  async untilApproval(approved: boolean): Promise<ReturnType<typeof eventSnapshot>> {
+    const { event, events } = await this.takeUntilRpc('requestApproval');
+    this.resolveRpcRequest(event, {
+      decision: approved ? 'approved' : 'rejected',
+      selectedLabel: approved ? 'approve' : 'reject',
+    } satisfies ApprovalResponse);
+    return events;
+  }
+
+  untilQuestionRequest(): Promise<ReturnType<typeof eventSnapshot>> {
+    return this.takeUntilRpc('requestQuestion').then(({ events }) => events);
+  }
+
+  async untilQuestion(result: QuestionResult): Promise<ReturnType<typeof eventSnapshot>> {
+    const { event, events } = await this.takeUntilRpc('requestQuestion');
+    this.resolveRpcRequest(event, result);
+    return events;
+  }
+
+  async untilToolCall(result: TestToolResult): Promise<ReturnType<typeof eventSnapshot>> {
+    const { event, events } = await this.takeUntilRpc('toolCall');
+    this.resolveRpcRequest(event, result);
+    return events;
+  }
+
+  dispatch(event: AgentRecord): void {
+    this.suppressWireSnapshot = true;
+    try {
+      this.appendRecord(event);
+    } finally {
+      this.suppressWireSnapshot = false;
+    }
+  }
+
+  async expectResumeMatches(): Promise<void> {
+    const resumed = testAgent({
+      runtime: {
+        kaos: createResumeNoSideEffectKaos(),
+        osEnv: this.agent.runtime.osEnv,
+        urlFetcher: this.agent.runtime.urlFetcher,
+        webSearcher: this.agent.runtime.webSearcher,
+      },
+      providerManager: this.agent.providerManager,
+      generate: failOnResumeGenerate,
+      compactionStrategy: this.options.compactionStrategy,
+      persistence: new ReplayAgentPersistence(this.recordHistory),
+    });
+
+    await resumed.agent.resume();
+
+    // oxlint-disable-next-line jest/no-standalone-expect
+    expect(resumeStateSnapshot(resumed.agent)).toEqual(resumeStateSnapshot(this.agent));
+  }
+
+  private takeUntilRpc(method: string): Promise<{
+    event: RpcLogEntry;
+    events: ReturnType<typeof eventSnapshot>;
+  }> {
+    const ready = this.findRpcFromCursor(method);
+    if (ready !== undefined) return Promise.resolve(this.takeThrough(ready));
+
+    const promise = createControlledPromise<{
+      event: RpcLogEntry;
+      events: ReturnType<typeof eventSnapshot>;
+    }>();
+
+    const onEvent = () => {
+      const event = this.findRpcFromCursor(method);
+      if (event === undefined) return;
+      this.emitter.off('event', onEvent);
+      promise.resolve(this.takeThrough(event));
+    };
+    this.emitter.on('event', onEvent);
+
+    return promise;
+  }
+
+  private takeThrough(match: { event: RpcLogEntry; index: number }): {
+    event: RpcLogEntry;
+    events: ReturnType<typeof eventSnapshot>;
+  } {
+    const events = this.allEvents.slice(this.lastEventCount, match.index + 1);
+    this.lastEventCount = match.index + 1;
+    return {
+      event: match.event,
+      events: eventSnapshot(events, this.uuidLabels),
+    };
+  }
+
+  private findRpcFromCursor(method: string): { event: RpcLogEntry; index: number } | undefined {
+    const index = this.allEvents.findIndex((entry, eventIndex) => {
+      return eventIndex >= this.lastEventCount && entry.type === '[rpc]' && entry.event === method;
+    });
+    if (index === -1) return undefined;
+
+    const event = this.allEvents[index]!;
+    return { event: event as RpcLogEntry, index };
+  }
+
+  private recordWire(event: AgentRecord): WireSnapshotEntry {
+    const { type, ...args } = event;
+    const entry: WireSnapshotEntry = {
+      type: '[wire]',
+      event: type,
+      args,
+    };
+    this.allEvents.push(entry);
+    this.emitter.emit(type, entry);
+    this.emitter.emit('event', entry);
+    return entry;
+  }
+
+  private recordRpc(method: string, args: unknown, response?: RpcPromise<unknown>): RpcLogEntry {
+    const event: RpcLogEntry = {
+      type: '[rpc]',
+      event: method,
+      args,
+      ...(response !== undefined ? { [RPC_RESPONSE]: response } : {}),
+    };
+    this.allEvents.push(event);
+    this.emitter.emit(method, event);
+    this.emitter.emit('event', event);
+    return event;
+  }
+
+  private createRpcPromise<T>(signal?: AbortSignal): RpcPromise<T> {
+    const promise = createControlledPromise<T>() as RpcPromise<T>;
+    const abort = () => {
+      const error = new Error('Aborted');
+      error.name = 'AbortError';
+      promise.reject(error);
+    };
+    if (signal?.aborted) {
+      abort();
+    } else {
+      signal?.addEventListener('abort', abort, { once: true });
+    }
+    return promise;
+  }
+
+  private resolveRpcRequest(event: RpcLogEntry, result: unknown): void {
+    const response = event[RPC_RESPONSE];
+    if (response === undefined) {
+      throw new Error(`RPC ${event.event} does not have a pending response`);
+    }
+    response.resolve(result);
+  }
+
+  private createRpcProxy(): SDKAgentRPC {
+    return new Proxy(
+      {},
+      {
+        get: (_target, property) => {
+          if (typeof property !== 'string') return;
+          return (payload: unknown, options?: RPCCallOptions) => {
+            if (property === 'emitEvent') {
+              const event = payload;
+              if (!this.isRpcEvent(event)) {
+                throw new TypeError('rpc.emitEvent expected an event object');
+              }
+              const { type, ...eventPayload } = event;
+              this.recordRpc(type, eventPayload);
+              return;
+            }
+
+            const promise = this.createRpcPromise(options?.signal);
+            void promise.catch(() => {});
+            this.recordRpc(property, payload, promise);
+            options?.signal?.throwIfAborted();
+            return promise;
+          };
+        },
+      },
+    ) as SDKAgentRPC;
+  }
+
+  private isRpcEvent(value: unknown): value is { readonly type: string } {
+    return (
+      value !== null &&
+      typeof value === 'object' &&
+      typeof (value as { readonly type?: unknown }).type === 'string'
+    );
+  }
+
+  private appendRecord(event: AgentRecord): void {
+    const records = (
+      this.agent as unknown as {
+        records: {
+          logRecord(record: AgentRecord): void;
+          restore(record: AgentRecord): void;
+        };
+      }
+    ).records;
+    records.logRecord(event);
+    records.restore(event);
+  }
+
+  private wrapPersistence(persistence: AgentRecordPersistence): AgentRecordPersistence {
+    return {
+      read: () => this.readAndCapturePersistence(persistence),
+      append: (event) => persistence.append(event),
+      flush: () => persistence.flush(),
+      close: () => persistence.close(),
+    };
+  }
+
+  private async *readAndCapturePersistence(
+    persistence: AgentRecordPersistence,
+  ): AsyncIterable<AgentRecord> {
+    for await (const event of persistence.read()) {
+      this.recordHistory.push(cloneRecord(event));
+      yield event;
+    }
+  }
+
+  private captureRecord(event: AgentRecord): void {
+    const cloned = cloneRecord(event);
+    this.recordHistory.push(cloned);
+    if (this.suppressWireSnapshot) return;
+
+    this.recordWire(cloned);
+    const response = this.options.onEvent?.(cloned);
+    if (response !== undefined) {
+      this.dispatch(response);
+    }
+  }
+
+  private createPromiseAgentApi(agent: Agent): PromiseAgentAPI {
+    const target = agent.rpcMethods;
+    return new Proxy(target, {
+      get(proxyTarget, property, receiver) {
+        const value = Reflect.get(proxyTarget, property, receiver);
+        if (typeof value !== 'function') return value;
+        return (payload: unknown) => {
+          try {
+            return Promise.resolve(value.call(proxyTarget, payload));
+          } catch (error) {
+            return Promise.reject(error);
+          }
+        };
+      },
+    }) as unknown as PromiseAgentAPI;
+  }
+}
+
+class ReplayAgentPersistence implements AgentRecordPersistence {
+  constructor(private readonly events: readonly AgentRecord[]) {}
+
+  async *read(): AsyncIterable<AgentRecord> {
+    for (const event of this.events) {
+      yield cloneRecord(event);
+    }
+  }
+
+  async append(_event: AgentRecord): Promise<void> {
+    throw new Error('Resume replay unexpectedly appended a record');
+  }
+
+  async flush(): Promise<void> {}
+
+  async close(): Promise<void> {}
+}
+
+const failOnResumeGenerate: GenerateFn = async () => {
+  throw new Error('Resume replay unexpectedly called the LLM');
+};
+
+function createResumeNoSideEffectKaos(): Kaos {
+  const fail = (method: string): never => {
+    throw new Error(`Resume replay unexpectedly called kaos.${method}`);
+  };
+
+  return {
+    name: 'resume-no-side-effects',
+    pathClass: () => 'posix',
+    normpath: (p: string) => p,
+    gethome: () => '/home/test',
+    getcwd: () => '/workspace',
+    chdir: () => fail('chdir'),
+    stat: () => fail('stat'),
+    iterdir: () => fail('iterdir'),
+    glob: () => fail('glob'),
+    readBytes: () => fail('readBytes'),
+    readText: () => fail('readText'),
+    readLines: () => fail('readLines'),
+    writeBytes: () => fail('writeBytes'),
+    writeText: () => fail('writeText'),
+    mkdir: () => fail('mkdir'),
+    exec: () => fail('exec'),
+    execWithEnv: () => fail('execWithEnv'),
+  };
+}
+
+function resumeStateSnapshot(agent: Agent): ResumeStateSnapshot {
+  return {
+    background: agent.background.list(false),
+    config: configStateSnapshot(agent),
+    context: resumeContextSnapshot(agent),
+    fullCompaction: agent.fullCompaction.compactedHistory,
+    permission: agent.permission.data(),
+    tools: agent.tools.data(),
+    toolStore: agent.tools.storeData(),
+    usage: agent.usage.data(),
+  };
+}
+
+function resumeContextSnapshot(agent: Agent): ReturnType<Agent['context']['data']> {
+  const context = agent.context.data();
+  return {
+    ...context,
+    history: context.history.filter((message) => !isSystemReminderMessage(message)),
+  };
+}
+
+function isSystemReminderMessage(
+  message: ReturnType<Agent['context']['data']>['history'][number],
+): boolean {
+  if (message.role !== 'user') return false;
+  const text = message.content
+    .map((part) => (part.type === 'text' ? part.text : ''))
+    .join('')
+    .trimStart();
+  return text.startsWith('<system-reminder>');
+}
+
+function configStateSnapshot(agent: Agent): ResumeStateSnapshot['config'] {
+  let provider: ProviderConfig | undefined;
+  try {
+    provider = agent.config.providerConfig;
+  } catch {}
+
+  return {
+    cwd: agent.config.cwd,
+    provider,
+    profileName: agent.config.profileName,
+    thinkingLevel: agent.config.thinkingLevel,
+    systemPrompt: agent.config.systemPrompt,
+  };
+}
+
+function emptyConfig(): KimiConfig {
+  return configWithProvider({ providers: {} }, MOCK_PROVIDER, undefined);
+}
+
+function configWithProvider(
+  config: KimiConfig,
+  provider: ProviderConfig,
+  modelCapabilities: ModelCapability | undefined,
+): KimiConfig {
+  const providerName = 'test-provider';
+  const maxContextSize = modelCapabilities?.max_context_tokens;
+  return {
+    ...config,
+    providers: {
+      ...config.providers,
+      [providerName]: providerConfigForAlias(provider),
+    },
+    models: {
+      ...config.models,
+      [provider.model]: {
+        provider: providerName,
+        model: provider.model,
+        maxContextSize:
+          maxContextSize === undefined || maxContextSize <= 0 ? 1_000_000 : maxContextSize,
+        capabilities: capabilityNames(modelCapabilities),
+      },
+    },
+  };
+}
+
+function providerConfigForAlias(provider: ProviderConfig): KimiConfig['providers'][string] {
+  return {
+    type: provider.type,
+    apiKey: 'apiKey' in provider ? provider.apiKey : undefined,
+    baseUrl: 'baseUrl' in provider ? provider.baseUrl : undefined,
+  };
+}
+
+function capabilityNames(capabilities: ModelCapability | undefined): string[] {
+  if (capabilities === undefined) return [];
+  return [
+    capabilities.image_in ? 'image_in' : undefined,
+    capabilities.video_in ? 'video_in' : undefined,
+    capabilities.audio_in ? 'audio_in' : undefined,
+    capabilities.thinking ? 'thinking' : undefined,
+    capabilities.tool_use ? 'tool_use' : undefined,
+  ].filter((capability): capability is string => capability !== undefined);
+}
+
+function buildSkillPrompt(content: string, args: string | undefined): string {
+  if (args === undefined) return content;
+  return `${content}\n\nUser request:\n${args}`;
+}
+
+function cloneRecord(event: AgentRecord): AgentRecord {
+  return structuredClone(event);
+}
diff --git a/packages/agent-core/test/agent/harness/index.ts b/packages/agent-core/test/agent/harness/index.ts
new file mode 100644
index 000000000..fdb7682c9
--- /dev/null
+++ b/packages/agent-core/test/agent/harness/index.ts
@@ -0,0 +1,16 @@
+export { createCommandKaos, testAgent, type TestAgentContext } from './agent';
+export { createScriptedGenerate } from './scripted-generate';
+export {
+  DEFAULT_TEST_SYSTEM_PROMPT,
+  eventSnapshot,
+  generateInputSnapshot,
+  generateInputsSnapshot,
+  normalizeGenerateInput,
+  type EventSnapshot,
+  type EventSnapshotEntry,
+  type GenerateCall,
+  type GenerateInputSnapshot,
+  type GenerateInputsSnapshot,
+  type RpcSnapshotEntry,
+  type WireSnapshotEntry,
+} from './snapshots';
diff --git a/packages/agent-core/test/agent/harness/scripted-generate.ts b/packages/agent-core/test/agent/harness/scripted-generate.ts
new file mode 100644
index 000000000..00aa181bb
--- /dev/null
+++ b/packages/agent-core/test/agent/harness/scripted-generate.ts
@@ -0,0 +1,147 @@
+import {
+  isContentPart,
+  isToolCall,
+  type FinishReason,
+  type Message,
+  type StreamedMessagePart,
+} from '@moonshot-ai/kosong';
+
+import type { AgentConfig } from '../../../src/agent';
+import { estimateTokensForMessages } from '../../../src/utils/tokens';
+import {
+  generateInputSnapshot,
+  generateInputsSnapshot,
+  normalizeGenerateInput,
+  type GenerateCall,
+} from './snapshots';
+
+type GenerateFn = NonNullable<AgentConfig['generate']>;
+
+interface ScriptedResponse {
+  readonly parts: readonly StreamedMessagePart[];
+  readonly finishReason?: FinishReason | null | undefined;
+  readonly rawFinishReason?: string | null | undefined;
+}
+
+export function createScriptedGenerate() {
+  const calls: GenerateCall[] = [];
+  const responses: ScriptedResponse[] = [];
+  let assertedCallCount = 0;
+
+  function mockNextResponse(...response: StreamedMessagePart[]) {
+    responses.push({ parts: structuredClone(response) });
+  }
+
+  function mockNextProviderResponse(input: {
+    readonly parts?: readonly StreamedMessagePart[] | undefined;
+    readonly finishReason?: FinishReason | null | undefined;
+    readonly rawFinishReason?: string | null | undefined;
+  }) {
+    responses.push({
+      parts: structuredClone(input.parts ?? []),
+      ...(input.finishReason !== undefined ? { finishReason: input.finishReason } : {}),
+      ...(input.rawFinishReason !== undefined ? { rawFinishReason: input.rawFinishReason } : {}),
+    });
+  }
+
+  const generate: GenerateFn = async (_chat, systemPrompt, tools, history, callbacks, options) => {
+    options?.signal?.throwIfAborted();
+
+    const response = responses.shift();
+    if (response === undefined) {
+      throw new Error(`Unexpected generate call #${String(calls.length + 1)}`);
+    }
+
+    const input = normalizeGenerateInput({
+      systemPrompt,
+      tools: tools.map(({ name, description, parameters }) => ({
+        name,
+        description,
+        parameters,
+      })),
+      history: structuredClone(history),
+    });
+    calls.push(input);
+
+    const content = response.parts.filter((part) => isContentPart(part));
+    const toolCalls = response.parts.filter((part) => isToolCall(part));
+    const message: Message = {
+      role: 'assistant',
+      content: structuredClone(content),
+      toolCalls: structuredClone(toolCalls),
+    };
+
+    for (const part of response.parts) {
+      await callbacks?.onMessagePart?.(structuredClone(part));
+      options?.signal?.throwIfAborted();
+    }
+
+    const inferredFinishReason: FinishReason = toolCalls.length > 0 ? 'tool_calls' : 'completed';
+    const finishReason = response.finishReason ?? inferredFinishReason;
+    return {
+      id: `mock-${String(calls.length)}`,
+      message,
+      usage: {
+        inputOther: estimateTokensForMessages(normalizeMessagesForTokenEstimates(history)),
+        output: estimateTokensForMessages(normalizeMessagesForTokenEstimates([message])),
+        inputCacheRead: 0,
+        inputCacheCreation: 0,
+      },
+      finishReason,
+      rawFinishReason: response.rawFinishReason ?? defaultRawFinishReason(finishReason),
+    };
+  };
+
+  return {
+    generate,
+    calls,
+    lastInput() {
+      const pendingCount = calls.length - assertedCallCount;
+      if (pendingCount === 0) {
+        throw new Error('No unasserted LLM input. Call ctx.lastLlmInput() after an LLM call.');
+      }
+      if (pendingCount > 1) {
+        throw new Error(
+          `Expected one unasserted LLM input, but ${String(pendingCount)} were produced. ` +
+            'Call ctx.lastLlmInput() after each LLM call.',
+        );
+      }
+
+      assertedCallCount = calls.length;
+      return generateInputSnapshot(calls.at(-1)!, calls.at(-2));
+    },
+    inputs() {
+      const pendingCount = calls.length - assertedCallCount;
+      if (pendingCount === 0) {
+        throw new Error('No unasserted LLM inputs. Call ctx.llmInputs() after LLM calls.');
+      }
+
+      const pending = calls.slice(assertedCallCount);
+      const previous = calls[assertedCallCount - 1];
+      assertedCallCount = calls.length;
+      return generateInputsSnapshot(pending, previous);
+    },
+    mockNextResponse,
+    mockNextProviderResponse,
+  };
+}
+
+function normalizeMessagesForTokenEstimates(messages: Message[]): Message[] {
+  return messages.map((message) => ({
+    ...message,
+    content: message.content.map((part) =>
+      part.type === 'text'
+        ? {
+            ...part,
+            text: part.text.replaceAll(/^Plan file: .+$/gm, 'Plan file: <plan-file>'),
+          }
+        : part,
+    ),
+  }));
+}
+
+function defaultRawFinishReason(finishReason: FinishReason | null): string | null {
+  if (finishReason === null) return null;
+  if (finishReason === 'completed') return 'stop';
+  return finishReason;
+}
diff --git a/packages/agent-core/test/agent/harness/snapshots.ts b/packages/agent-core/test/agent/harness/snapshots.ts
new file mode 100644
index 000000000..e0ff13349
--- /dev/null
+++ b/packages/agent-core/test/agent/harness/snapshots.ts
@@ -0,0 +1,314 @@
+import type { Message, Tool as LLMTool } from '@moonshot-ai/kosong';
+import { expect } from 'vitest';
+
+const IS_EVENT_ARRAY = Symbol('isEventArray');
+const IS_GENERATE_INPUT_SNAPSHOT = Symbol('isGenerateInputSnapshot');
+const IS_GENERATE_INPUTS_SNAPSHOT = Symbol('isGenerateInputsSnapshot');
+
+export const DEFAULT_TEST_SYSTEM_PROMPT = 'You are a deterministic test agent.';
+
+export interface RpcSnapshotEntry {
+  readonly type: '[rpc]';
+  readonly event: string;
+  readonly args: unknown;
+}
+
+export interface WireSnapshotEntry {
+  readonly type: '[wire]';
+  readonly event: string;
+  readonly args: unknown;
+}
+
+export type EventSnapshotEntry = WireSnapshotEntry | RpcSnapshotEntry;
+
+export interface GenerateCall {
+  readonly systemPrompt: string;
+  readonly tools: Array<Pick<LLMTool, 'name' | 'description' | 'parameters'>>;
+  readonly history: Message[];
+}
+
+export type EventSnapshot = ReturnType<typeof eventSnapshot>;
+
+export interface GenerateInputSnapshot {
+  readonly [IS_GENERATE_INPUT_SNAPSHOT]: true;
+  readonly input: GenerateCall;
+  readonly previous: GenerateCall | undefined;
+}
+
+export interface GenerateInputsSnapshot {
+  readonly [IS_GENERATE_INPUTS_SNAPSHOT]: true;
+  readonly inputs: readonly GenerateCall[];
+  readonly previous: GenerateCall | undefined;
+}
+
+export function eventSnapshot(
+  events: readonly EventSnapshotEntry[],
+  uuidLabels: Map<string, string>,
+) {
+  const normalized = events.map((event) => normalizeValue(event, uuidLabels));
+  (normalized as unknown as Record<symbol, true>)[IS_EVENT_ARRAY] = true;
+  return normalized;
+}
+
+export function createEventSnapshotter() {
+  const uuidLabels = new Map<string, string>();
+
+  return (events: readonly EventSnapshotEntry[]): EventSnapshot =>
+    eventSnapshot(events, uuidLabels);
+}
+
+export function generateInputSnapshot(
+  input: GenerateCall,
+  previous: GenerateCall | undefined,
+): GenerateInputSnapshot {
+  return {
+    [IS_GENERATE_INPUT_SNAPSHOT]: true,
+    input,
+    previous,
+  };
+}
+
+export function generateInputsSnapshot(
+  inputs: readonly GenerateCall[],
+  previous: GenerateCall | undefined,
+): GenerateInputsSnapshot {
+  return {
+    [IS_GENERATE_INPUTS_SNAPSHOT]: true,
+    inputs,
+    previous,
+  };
+}
+
+export function normalizeGenerateInput(input: GenerateCall): GenerateCall {
+  return stripUndefined(input) as GenerateCall;
+}
+
+function stringifyCompact(obj: unknown) {
+  return JSON.stringify(obj, null, 1).replaceAll(/\n\s*/g, ' ').trim();
+}
+
+function hasSnapshotSymbol(val: unknown, symbol: symbol): boolean {
+  return (
+    val !== null && typeof val === 'object' && Boolean((val as Record<symbol, unknown>)[symbol])
+  );
+}
+
+expect.addSnapshotSerializer({
+  test(val) {
+    return hasSnapshotSymbol(val, IS_EVENT_ARRAY);
+  },
+  serialize(val) {
+    const events = val as Array<Record<string, unknown>>;
+    if (events.length === 0) return '[]';
+
+    const maxEventLength = Math.max(...events.map((event) => String(event['event']).length), 0) + 2;
+    return events
+      .map((v) => {
+        const prefix = v['type'] === '[rpc]' ? '[emit]' : '[wire]';
+        return `${prefix} ${String(v['event']).padEnd(maxEventLength, ' ')} ${stringifyCompact(v['args'])}`;
+      })
+      .join('\n');
+  },
+});
+
+expect.addSnapshotSerializer({
+  test(val) {
+    return hasSnapshotSymbol(val, IS_GENERATE_INPUT_SNAPSHOT);
+  },
+  serialize(val) {
+    const snapshot = val as GenerateInputSnapshot;
+    return formatGenerateInput(snapshot.input, snapshot.previous);
+  },
+});
+
+expect.addSnapshotSerializer({
+  test(val) {
+    return hasSnapshotSymbol(val, IS_GENERATE_INPUTS_SNAPSHOT);
+  },
+  serialize(val) {
+    const snapshot = val as GenerateInputsSnapshot;
+    let previous = snapshot.previous;
+    return snapshot.inputs
+      .map((input, index) => {
+        const formatted = formatGenerateInput(input, previous);
+        previous = input;
+        return `call ${String(index + 1)}:\n${indentLines(formatted)}`;
+      })
+      .join('\n\n');
+  },
+});
+
+function formatGenerateInput(input: GenerateCall, previous: GenerateCall | undefined): string {
+  const lines: string[] = [];
+
+  if (previous === undefined || previous.systemPrompt !== input.systemPrompt) {
+    lines.push(`system: ${formatSystemPrompt(input.systemPrompt)}`);
+  }
+
+  if (previous === undefined || !isDeepEqual(previous.tools, input.tools)) {
+    lines.push(`tools: ${formatToolNames(input.tools)}`);
+  }
+
+  lines.push('messages:');
+
+  if (previous !== undefined && isMessagePrefix(previous.history, input.history)) {
+    const addedMessages = input.history.slice(previous.history.length);
+    lines.push('  <last>');
+    if (addedMessages.length > 0) {
+      lines.push(...formatMessages(addedMessages));
+    }
+    return lines.join('\n');
+  }
+
+  lines.push(...formatMessages(input.history));
+  return lines.join('\n');
+}
+
+function indentLines(text: string): string {
+  return text
+    .split('\n')
+    .map((line) => `  ${line}`)
+    .join('\n');
+}
+
+function formatSystemPrompt(systemPrompt: string): string {
+  if (systemPrompt === DEFAULT_TEST_SYSTEM_PROMPT) return '<system-prompt>';
+  return JSON.stringify(systemPrompt);
+}
+
+function formatToolNames(tools: GenerateCall['tools']): string {
+  if (tools.length === 0) return '[]';
+  return tools.map((tool) => tool.name).join(', ');
+}
+
+function isMessagePrefix(previous: readonly Message[], input: readonly Message[]): boolean {
+  if (previous.length > input.length) return false;
+  return previous.every((message, index) => isDeepEqual(message, input[index]));
+}
+
+function formatMessages(messages: readonly Message[]): string[] {
+  if (messages.length === 0) return ['  []'];
+
+  return messages.map((message) => {
+    const role =
+      message.toolCallId === undefined ? message.role : `${message.role}[${message.toolCallId}]`;
+    const parts = [formatContent(message.content)];
+    if (message.toolCalls.length > 0) {
+      parts.push(`calls ${message.toolCalls.map((call) => formatToolCall(call)).join(', ')}`);
+    }
+    return `  ${role}: ${parts.join('  ')}`;
+  });
+}
+
+function formatContent(content: Message['content']): string {
+  if (content.length === 0) return '[]';
+
+  return content
+    .map((part) => {
+      if (part.type === 'text') return `text ${formatText(part.text)}`;
+      if (part.type === 'think') return `think ${JSON.stringify(part.think)}`;
+      return stringifyCompact(part);
+    })
+    .join(' + ');
+}
+
+function formatText(text: string): string {
+  if (isAutoModeEnterReminder(text)) {
+    return '<auto-mode-enter-reminder>';
+  }
+  if (isAutoModeExitReminder(text)) {
+    return '<auto-mode-exit-reminder>';
+  }
+  if (isPlanModeReminder(text)) {
+    return '<plan-mode-reminder>';
+  }
+  if (text.includes('<!-- Compression Priorities (in order) -->')) {
+    return '<compaction-instruction>';
+  }
+  return JSON.stringify(text);
+}
+
+function formatToolCall(call: Message['toolCalls'][number]): string {
+  return `${call.id}:${call.function.name} ${formatToolCallArguments(call.function.arguments)}`;
+}
+
+function formatToolCallArguments(args: string | null): string {
+  if (args === null) return 'null';
+
+  try {
+    return stringifyCompact(JSON.parse(args));
+  } catch {
+    return JSON.stringify(args);
+  }
+}
+
+function isDeepEqual(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function normalizeValue(value: unknown, uuidLabels: Map<string, string>): unknown {
+  if (typeof value === 'string') {
+    if (isAutoModeEnterReminder(value)) return '<auto-mode-enter-reminder>';
+    if (isAutoModeExitReminder(value)) return '<auto-mode-exit-reminder>';
+    if (isPlanModeReminder(value)) return '<plan-mode-reminder>';
+    if (!isUuid(value)) return value;
+    let label = uuidLabels.get(value);
+    if (label === undefined) {
+      label = `<uuid-${String(uuidLabels.size + 1)}>`;
+      uuidLabels.set(value, label);
+    }
+    return label;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeValue(item, uuidLabels));
+  }
+
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, nested]) => [
+        key,
+        key === 'time' && typeof nested === 'number'
+          ? '<time>'
+          : normalizeValue(nested, uuidLabels),
+      ]),
+    );
+  }
+
+  return value;
+}
+
+function stripUndefined(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => stripUndefined(item));
+  }
+
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, nested]) => nested !== undefined)
+        .map(([key, nested]) => [key, stripUndefined(nested)]),
+    );
+  }
+
+  return value;
+}
+
+function isUuid(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+
+function isPlanModeReminder(value: string): boolean {
+  return (
+    value.includes('Plan mode is active. You MUST NOT make any edits') &&
+    value.includes('Plan file:')
+  );
+}
+
+function isAutoModeEnterReminder(value: string): boolean {
+  return value.includes('Auto permission mode is active.');
+}
+
+function isAutoModeExitReminder(value: string): boolean {
+  return value.includes('Auto permission mode is no longer active.');
+}
diff --git a/packages/agent-core/test/agent/injection/manager.test.ts b/packages/agent-core/test/agent/injection/manager.test.ts
new file mode 100644
index 000000000..240030659
--- /dev/null
+++ b/packages/agent-core/test/agent/injection/manager.test.ts
@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'vitest';
+
+import { DynamicInjector } from '../../../src/agent/injection/injector';
+import { InjectionManager } from '../../../src/agent/injection/manager';
+import { testAgent } from '../harness/agent';
+
+class RecordingInjector extends DynamicInjector {
+  override readonly injectionVariant = 'recording_test';
+  compactionCalls = 0;
+  clearCalls = 0;
+
+  override onContextClear(): void {
+    this.clearCalls += 1;
+    super.onContextClear();
+  }
+
+  override onContextCompacted(compactedCount: number): void {
+    this.compactionCalls += 1;
+    super.onContextCompacted(compactedCount);
+  }
+
+  protected override getInjection(): string | undefined {
+    return undefined;
+  }
+}
+
+class BoomInjector extends DynamicInjector {
+  override readonly injectionVariant = 'boom_test';
+
+  override onContextCompacted(_compactedCount: number): void {
+    throw new Error('boom-compact');
+  }
+
+  protected override getInjection(): string | undefined {
+    return undefined;
+  }
+}
+
+function installInjectors(manager: InjectionManager, injectors: DynamicInjector[]): void {
+  (manager as unknown as { injectors: DynamicInjector[] }).injectors = injectors;
+}
+
+describe('InjectionManager.onContextCompacted', () => {
+  it('notifies every registered injector when compaction occurs', () => {
+    const ctx = testAgent();
+    ctx.configure();
+    const a = new RecordingInjector(ctx.agent);
+    const b = new RecordingInjector(ctx.agent);
+    installInjectors(ctx.agent.injection, [a, b]);
+
+    ctx.agent.injection.onContextCompacted(3);
+
+    expect(a.compactionCalls).toBe(1);
+    expect(b.compactionCalls).toBe(1);
+  });
+
+  it('isolates compaction hook failures so later injectors still receive the notification', () => {
+    const ctx = testAgent();
+    ctx.configure();
+    const recorder = new RecordingInjector(ctx.agent);
+    installInjectors(ctx.agent.injection, [new BoomInjector(ctx.agent), recorder]);
+
+    expect(() => {
+      ctx.agent.injection.onContextCompacted(2);
+    }).not.toThrow();
+    expect(recorder.compactionCalls).toBe(1);
+  });
+
+  it('continues notifying surviving injectors on later compactions', () => {
+    const ctx = testAgent();
+    ctx.configure();
+    const recorder = new RecordingInjector(ctx.agent);
+    installInjectors(ctx.agent.injection, [new BoomInjector(ctx.agent), recorder]);
+
+    expect(() => {
+      ctx.agent.injection.onContextCompacted(1);
+    }).not.toThrow();
+    expect(recorder.compactionCalls).toBe(1);
+
+    ctx.agent.injection.onContextCompacted(1);
+    expect(recorder.compactionCalls).toBe(2);
+  });
+
+  it('replays context lifecycle records through ContextMemory only once', () => {
+    const ctx = testAgent();
+    ctx.configure();
+    const recorder = new RecordingInjector(ctx.agent);
+    installInjectors(ctx.agent.injection, [recorder]);
+
+    ctx.agent.records.restore({ type: 'context.clear' });
+    ctx.agent.records.restore({
+      type: 'context.apply_compaction',
+      summary: 'Compacted summary.',
+      compactedCount: 2,
+      tokensBefore: 10,
+      tokensAfter: 4,
+    });
+
+    expect(recorder.clearCalls).toBe(1);
+    expect(recorder.compactionCalls).toBe(1);
+  });
+});
diff --git a/packages/agent-core/test/agent/injection/plan-mode.test.ts b/packages/agent-core/test/agent/injection/plan-mode.test.ts
new file mode 100644
index 000000000..cd6d68792
--- /dev/null
+++ b/packages/agent-core/test/agent/injection/plan-mode.test.ts
@@ -0,0 +1,150 @@
+import { describe, expect, it } from 'vitest';
+
+import type { Agent } from '../../../src/agent';
+import { PlanModeInjector } from '../../../src/agent/injection/plan-mode';
+
+interface PlanModeStub {
+  isActive: boolean;
+  planFilePath?: string | null;
+}
+
+function planAgent(stub: PlanModeStub): Agent {
+  const history: unknown[] = [];
+  return {
+    type: 'main',
+    planMode: {
+      get isActive() {
+        return stub.isActive;
+      },
+      get planFilePath() {
+        return stub.planFilePath ?? null;
+      },
+    },
+    context: {
+      history,
+      appendSystemReminder: (content: string) => {
+        history.push({ role: 'user', content: [{ type: 'text', text: content }] });
+      },
+    },
+  } as unknown as Agent;
+}
+
+function history(agent: Agent): Array<{ role: string; content?: ReadonlyArray<{ text?: string }> }> {
+  return agent.context.history as unknown as Array<{
+    role: string;
+    content?: ReadonlyArray<{ text?: string }>;
+  }>;
+}
+
+function lastReminder(agent: Agent): string {
+  const last = history(agent).findLast((message) => message.role === 'user');
+  return last?.content?.map((part) => part.text ?? '').join('') ?? '';
+}
+
+describe('PlanModeInjector content', () => {
+  it('injects the full reminder with the current plan file footer', async () => {
+    const agent = planAgent({ isActive: true, planFilePath: '/tmp/plan.md' });
+    const injector = new PlanModeInjector(agent);
+
+    await injector.inject();
+    const text = lastReminder(agent);
+
+    expect(text).toContain('Plan mode is active');
+    expect(text).toContain('current plan file');
+    expect(text).toContain('Write');
+    expect(text).toContain('Edit');
+    expect(text).toContain('ExitPlanMode');
+    expect(text).toContain('Plan file: /tmp/plan.md');
+  });
+
+  it('uses the inline reminder when no plan file path is available', async () => {
+    const agent = planAgent({ isActive: true, planFilePath: null });
+    const injector = new PlanModeInjector(agent);
+
+    await injector.inject();
+
+    const text = lastReminder(agent);
+    expect(text).toContain('Plan mode is active');
+    expect(text).toContain('Wait for the host to provide a plan file path');
+    expect(text).not.toContain('Plan file:');
+  });
+
+  it('injects the exit reminder when plan mode turns off after being active', async () => {
+    const stub: PlanModeStub = { isActive: true, planFilePath: '/tmp/plan.md' };
+    const agent = planAgent(stub);
+    const injector = new PlanModeInjector(agent);
+
+    await injector.inject();
+    stub.isActive = false;
+    await injector.inject();
+
+    expect(lastReminder(agent)).toContain('Plan mode is no longer active');
+  });
+
+  it('does not inject anything when plan mode is inactive from the start', async () => {
+    const agent = planAgent({ isActive: false });
+    const injector = new PlanModeInjector(agent);
+
+    await injector.inject();
+
+    expect(history(agent)).toHaveLength(0);
+  });
+});
+
+describe('PlanModeInjector cadence', () => {
+  it('skips reinjection before the assistant-turn threshold', async () => {
+    const agent = planAgent({ isActive: true, planFilePath: '/tmp/plan.md' });
+    const injector = new PlanModeInjector(agent);
+
+    await injector.inject();
+    const messages = history(agent);
+    messages.push({ role: 'assistant' });
+    await injector.inject();
+
+    expect(messages).toHaveLength(2);
+  });
+
+  it('injects the sparse reminder after the short assistant-turn threshold', async () => {
+    const agent = planAgent({ isActive: true, planFilePath: '/tmp/plan.md' });
+    const injector = new PlanModeInjector(agent);
+
+    await injector.inject();
+    const messages = history(agent);
+    messages.push({ role: 'assistant' }, { role: 'assistant' });
+    await injector.inject();
+
+    const text = lastReminder(agent);
+    expect(text).toContain('Plan mode still active');
+    expect(text).toContain('see full instructions earlier');
+    expect(text).toContain('Plan file: /tmp/plan.md');
+  });
+
+  it('refreshes the full reminder after the long assistant-turn threshold', async () => {
+    const agent = planAgent({ isActive: true, planFilePath: '/tmp/plan.md' });
+    const injector = new PlanModeInjector(agent);
+
+    await injector.inject();
+    const messages = history(agent);
+    for (let i = 0; i < 5; i += 1) {
+      messages.push({ role: 'assistant' });
+    }
+    await injector.inject();
+
+    const text = lastReminder(agent);
+    expect(text).toContain('Plan mode is active');
+    expect(text).not.toContain('Plan mode still active');
+  });
+
+  it('refreshes the full reminder if a user message appears after the last injection', async () => {
+    const agent = planAgent({ isActive: true, planFilePath: '/tmp/plan.md' });
+    const injector = new PlanModeInjector(agent);
+
+    await injector.inject();
+    history(agent).push({ role: 'user', content: [{ text: 'next task' }] });
+    await injector.inject();
+
+    const text = lastReminder(agent);
+    expect(text).toContain('Plan mode is active');
+    expect(text).not.toContain('Plan mode still active');
+  });
+});
diff --git a/packages/agent-core/test/agent/kosong-llm.test.ts b/packages/agent-core/test/agent/kosong-llm.test.ts
new file mode 100644
index 000000000..38130b929
--- /dev/null
+++ b/packages/agent-core/test/agent/kosong-llm.test.ts
@@ -0,0 +1,133 @@
+import {
+  emptyUsage,
+  type ChatProvider,
+  type StreamedMessagePart,
+  type ToolCall,
+} from '@moonshot-ai/kosong';
+import { describe, expect, it } from 'vitest';
+
+import { KosongLLM, type GenerateFn } from '../../src/agent/turn/kosong-llm';
+import type { ToolCallDelta } from '../../src/loop';
+
+const provider: ChatProvider = {
+  name: 'test',
+  modelName: 'test-model',
+  thinkingEffort: null,
+  async generate() {
+    throw new Error('generate should be injected by the test');
+  },
+  withThinking() {
+    return this;
+  },
+};
+
+describe('KosongLLM streaming tool-call deltas', () => {
+  it('maps indexed argument deltas back to the provider tool call id', async () => {
+    const deltas = await collectToolCallDeltas([
+      {
+        type: 'function',
+        id: 'call_bash',
+        function: { name: 'Bash', arguments: null },
+        _streamIndex: 0,
+      },
+      { type: 'tool_call_part', argumentsPart: '{"command"', index: 0 },
+      { type: 'tool_call_part', argumentsPart: ':"pwd"}', index: 0 },
+    ]);
+
+    expect(deltas).toEqual([
+      { toolCallId: 'call_bash', name: 'Bash' },
+      { toolCallId: 'call_bash', name: 'Bash', argumentsPart: '{"command"' },
+      { toolCallId: 'call_bash', name: 'Bash', argumentsPart: ':"pwd"}' },
+    ]);
+  });
+
+  it('buffers indexed argument deltas until the provider tool call id is known', async () => {
+    const deltas = await collectToolCallDeltas([
+      { type: 'tool_call_part', argumentsPart: '{"command"', index: 0 },
+      {
+        type: 'function',
+        id: 'call_bash',
+        function: { name: 'Bash', arguments: null },
+        _streamIndex: 0,
+      },
+      { type: 'tool_call_part', argumentsPart: ':"pwd"}', index: 0 },
+    ]);
+
+    expect(deltas).toEqual([
+      { toolCallId: 'call_bash', name: 'Bash' },
+      { toolCallId: 'call_bash', name: 'Bash', argumentsPart: '{"command"' },
+      { toolCallId: 'call_bash', name: 'Bash', argumentsPart: ':"pwd"}' },
+    ]);
+    expect(deltas.map((delta) => delta.toolCallId)).not.toContain('0');
+  });
+
+  it('uses the latest tool call identity for linear unindexed argument deltas', async () => {
+    const deltas = await collectToolCallDeltas([
+      {
+        type: 'function',
+        id: 'call_write',
+        function: { name: 'Write', arguments: null },
+      },
+      { type: 'tool_call_part', argumentsPart: '{"path"' },
+      { type: 'tool_call_part', argumentsPart: ':"a.txt"}' },
+    ]);
+
+    expect(deltas).toEqual([
+      { toolCallId: 'call_write', name: 'Write' },
+      { toolCallId: 'call_write', name: 'Write', argumentsPart: '{"path"' },
+      { toolCallId: 'call_write', name: 'Write', argumentsPart: ':"a.txt"}' },
+    ]);
+  });
+});
+
+async function collectToolCallDeltas(
+  parts: readonly StreamedMessagePart[],
+): Promise<ToolCallDelta[]> {
+  const deltas: ToolCallDelta[] = [];
+  const generate: GenerateFn = async (_provider, _systemPrompt, _tools, _history, callbacks) => {
+    for (const part of parts) {
+      await callbacks?.onMessagePart?.(part);
+    }
+    return {
+      id: 'response-1',
+      message: {
+        role: 'assistant',
+        content: [],
+        toolCalls: parts
+          .filter((part): part is ToolCall => isToolCall(part))
+          .map((toolCall) => stripStreamIndex(toolCall)),
+      },
+      usage: emptyUsage(),
+      finishReason: 'tool_calls',
+      rawFinishReason: 'tool_calls',
+    };
+  };
+  const llm = new KosongLLM({
+    provider,
+    modelName: 'test-model',
+    systemPrompt: 'system',
+    generate,
+  });
+
+  await llm.chat({
+    messages: [],
+    tools: [],
+    signal: new AbortController().signal,
+    onToolCallDelta: (delta) => deltas.push(delta),
+  });
+
+  return deltas;
+}
+
+function isToolCall(part: StreamedMessagePart): part is ToolCall {
+  return part.type === 'function';
+}
+
+function stripStreamIndex(toolCall: ToolCall): ToolCall {
+  return {
+    type: 'function',
+    id: toolCall.id,
+    function: { ...toolCall.function },
+    ...(toolCall.extras !== undefined ? { extras: toolCall.extras } : {}),
+  };
+}
diff --git a/packages/agent-core/test/agent/permission.test.ts b/packages/agent-core/test/agent/permission.test.ts
new file mode 100644
index 000000000..987e87b06
--- /dev/null
+++ b/packages/agent-core/test/agent/permission.test.ts
@@ -0,0 +1,1946 @@
+import type { Kaos } from '@moonshot-ai/kaos';
+import type { ToolCall } from '@moonshot-ai/kosong';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Agent } from '../../src/agent';
+import { PermissionModeInjector } from '../../src/agent/injection/permission-mode';
+import {
+  PermissionManager,
+  type ApprovalResponse,
+  type PermissionMode,
+  type PermissionRule,
+} from '../../src/agent/permission';
+import {
+  actionToRulePattern,
+  describeApprovalAction,
+} from '../../src/agent/permission/action-label';
+import { checkMatchingRules } from '../../src/agent/permission/check-rules';
+import { matchesRule } from '../../src/agent/permission/matches-rule';
+import { parsePattern } from '../../src/agent/permission/parse-pattern';
+import { createPlanPermissionPolicies } from '../../src/agent/permission/policies/plan';
+import type {
+  PermissionPolicy,
+  PermissionPolicyResult,
+} from '../../src/agent/permission/policy';
+import type { ToolExecutionHookContext } from '../../src/loop';
+import type { ToolInputDisplay } from '../../src/tools/display';
+import { createFakeKaos } from '../tools/fixtures/fake-kaos';
+import { createCommandKaos, testAgent } from './harness/agent';
+
+describe('Agent permission', () => {
+  it('auto mode bypasses approval for ordinary builtin tools', async () => {
+    const ctx = testAgent({ kaos: createCommandKaos('auto-output') });
+    ctx.configure({ tools: ['Bash'] });
+    await ctx.rpc.setPermission({ mode: 'auto' });
+
+    ctx.mockNextResponse({ type: 'text', text: 'Running without asking.' }, bashCall());
+    ctx.mockNextResponse({ type: 'text', text: 'The command printed auto-output.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Run Bash in auto mode' }] });
+
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] permission.set_mode         { "mode": "auto", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 0, "maxContextTokens": 1000000, "contextUsage": 0, "planMode": false, "permission": "auto" }
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Run Bash in auto mode" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Run Bash in auto mode" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "<auto-mode-enter-reminder>" } ], "toolCalls": [], "origin": { "kind": "injection", "variant": "permission_mode" } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "Running without asking." }
+      [emit] tool.call.delta             { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "argumentsPart": "{\\"command\\":\\"printf permission-output\\",\\"timeout\\":60}" }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "Running without asking." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "tool.call", "uuid": "call_bash", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf permission-output", "timeout": 60 }, "description": "Running: printf permission-output" }, "time": "<time>" }
+      [emit] tool.call.started           { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf permission-output", "timeout": 60 }, "description": "Running: printf permission-output" }
+      [wire] context.append_loop_event   { "event": { "type": "tool.result", "parentUuid": "call_bash", "toolCallId": "call_bash", "result": { "output": "auto-output" } }, "time": "<time>" }
+      [emit] tool.result                 { "turnId": 0, "toolCallId": "call_bash", "output": "auto-output" }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "usage": { "inputOther": 91, "output": 25, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 0, "step": 1, "stepId": "<uuid-1>", "usage": { "inputOther": 91, "output": 25, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }
+      [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 91, "output": 25, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 116, "maxContextTokens": 1000000, "contextUsage": 0.000116, "planMode": false, "permission": "auto", "usage": { "byModel": { "mock-model": { "inputOther": 91, "output": 25, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 91, "output": 25, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 91, "output": 25, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-3>", "turnId": "0", "step": 2 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 2, "stepId": "<uuid-3>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "The command printed auto-output." }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "stepUuid": "<uuid-3>", "part": { "type": "text", "text": "The command printed auto-output." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-3>", "turnId": "0", "step": 2, "usage": { "inputOther": 120, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 0, "step": 2, "stepId": "<uuid-3>", "usage": { "inputOther": 120, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+      [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 120, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 131, "maxContextTokens": 1000000, "contextUsage": 0.000131, "planMode": false, "permission": "auto", "usage": { "byModel": { "mock-model": { "inputOther": 211, "output": 36, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 211, "output": 36, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 211, "output": 36, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [emit] turn.ended                  { "turnId": 0, "reason": "completed" }
+    `);
+    expect(ctx.llmInputs()).toMatchInlineSnapshot(`
+      call 1:
+        system: <system-prompt>
+        tools: Bash
+        messages:
+          user: text "Run Bash in auto mode"
+          user: text <auto-mode-enter-reminder>
+
+      call 2:
+        messages:
+          <last>
+          assistant: text "Running without asking."  calls call_bash:Bash { "command": "printf permission-output", "timeout": 60 }
+          tool[call_bash]: text "auto-output"
+    `);
+    await ctx.expectResumeMatches();
+  });
+
+  it('yolo mode bypasses approval for ordinary builtin tools', async () => {
+    const ctx = testAgent({ kaos: createCommandKaos('yolo-output') });
+    ctx.configure({ tools: ['Bash'] });
+    await ctx.rpc.setPermission({ mode: 'yolo' });
+
+    ctx.mockNextResponse({ type: 'text', text: 'Running in yolo mode.' }, bashCall());
+    ctx.mockNextResponse({ type: 'text', text: 'The command printed yolo-output.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Run Bash in yolo mode' }] });
+
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] permission.set_mode         { "mode": "yolo", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 0, "maxContextTokens": 1000000, "contextUsage": 0, "planMode": false, "permission": "yolo" }
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Run Bash in yolo mode" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Run Bash in yolo mode" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "Running in yolo mode." }
+      [emit] tool.call.delta             { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "argumentsPart": "{\\"command\\":\\"printf permission-output\\",\\"timeout\\":60}" }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "Running in yolo mode." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "tool.call", "uuid": "call_bash", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf permission-output", "timeout": 60 }, "description": "Running: printf permission-output" }, "time": "<time>" }
+      [emit] tool.call.started           { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf permission-output", "timeout": 60 }, "description": "Running: printf permission-output" }
+      [wire] context.append_loop_event   { "event": { "type": "tool.result", "parentUuid": "call_bash", "toolCallId": "call_bash", "result": { "output": "yolo-output" } }, "time": "<time>" }
+      [emit] tool.result                 { "turnId": 0, "toolCallId": "call_bash", "output": "yolo-output" }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "usage": { "inputOther": 7, "output": 25, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 0, "step": 1, "stepId": "<uuid-1>", "usage": { "inputOther": 7, "output": 25, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }
+      [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 7, "output": 25, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 32, "maxContextTokens": 1000000, "contextUsage": 0.000032, "planMode": false, "permission": "yolo", "usage": { "byModel": { "mock-model": { "inputOther": 7, "output": 25, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 7, "output": 25, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 7, "output": 25, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-3>", "turnId": "0", "step": 2 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 2, "stepId": "<uuid-3>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "The command printed yolo-output." }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "stepUuid": "<uuid-3>", "part": { "type": "text", "text": "The command printed yolo-output." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-3>", "turnId": "0", "step": 2, "usage": { "inputOther": 36, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 0, "step": 2, "stepId": "<uuid-3>", "usage": { "inputOther": 36, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+      [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 36, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 47, "maxContextTokens": 1000000, "contextUsage": 0.000047, "planMode": false, "permission": "yolo", "usage": { "byModel": { "mock-model": { "inputOther": 43, "output": 36, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 43, "output": 36, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 43, "output": 36, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [emit] turn.ended                  { "turnId": 0, "reason": "completed" }
+    `);
+    expect(ctx.llmInputs()).toMatchInlineSnapshot(`
+      call 1:
+        system: <system-prompt>
+        tools: Bash
+        messages:
+          user: text "Run Bash in yolo mode"
+
+      call 2:
+        messages:
+          <last>
+          assistant: text "Running in yolo mode."  calls call_bash:Bash { "command": "printf permission-output", "timeout": 60 }
+          tool[call_bash]: text "yolo-output"
+    `);
+    await ctx.expectResumeMatches();
+  });
+  it('injects a reminder when leaving auto mode', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+    await ctx.rpc.setPermission({ mode: 'auto' });
+
+    ctx.mockNextResponse({ type: 'text', text: 'Auto turn done.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Use auto first' }] });
+    await ctx.untilTurnEnd();
+
+    await ctx.rpc.setPermission({ mode: 'manual' });
+    ctx.mockNextResponse({ type: 'text', text: 'Manual turn done.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Back to manual' }] });
+
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] permission.set_mode         { "mode": "manual", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 96, "maxContextTokens": 1000000, "contextUsage": 0.000096, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 89, "output": 7, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 89, "output": 7, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Back to manual" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 1, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Back to manual" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "<auto-mode-exit-reminder>" } ], "toolCalls": [], "origin": { "kind": "injection", "variant": "permission_mode" } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-3>", "turnId": "1", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 1, "step": 1, "stepId": "<uuid-3>" }
+      [emit] assistant.delta             { "turnId": 1, "delta": "Manual turn done." }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-4>", "turnId": "1", "step": 1, "stepUuid": "<uuid-3>", "part": { "type": "text", "text": "Manual turn done." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-3>", "turnId": "1", "step": 1, "usage": { "inputOther": 161, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 1, "step": 1, "stepId": "<uuid-3>", "usage": { "inputOther": 161, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+      [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 161, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 169, "maxContextTokens": 1000000, "contextUsage": 0.000169, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 250, "output": 15, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 250, "output": 15, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 161, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [emit] turn.ended                  { "turnId": 1, "reason": "completed" }
+    `);
+    expect(ctx.llmInputs()).toMatchInlineSnapshot(`
+      call 1:
+        system: <system-prompt>
+        tools: []
+        messages:
+          user: text "Use auto first"
+          user: text <auto-mode-enter-reminder>
+
+      call 2:
+        messages:
+          <last>
+          assistant: text "Auto turn done."
+          user: text "Back to manual"
+          user: text <auto-mode-exit-reminder>
+    `);
+    await ctx.expectResumeMatches();
+  });
+
+  it('does not execute rejected builtin tools and feeds the rejection back to the LLM', async () => {
+    const execWithEnv = vi.fn().mockRejectedValue(new Error('Bash should not execute'));
+    const bashCall: ToolCall = {
+      type: 'function',
+      id: 'call_bash',
+      function: {
+        name: 'Bash',
+        arguments: '{"command":"printf should-not-run","timeout":60}',
+      },
+    };
+    const ctx = testAgent({
+      kaos: createFakeKaos({ execWithEnv }),
+    });
+    ctx.configure({ tools: ['Bash'] });
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will try Bash.' }, bashCall);
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Try to run Bash' }] });
+    expect(await ctx.untilApproval(false)).toMatchInlineSnapshot(`
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Try to run Bash" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Try to run Bash" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "I will try Bash." }
+      [emit] tool.call.delta             { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "argumentsPart": "{\\"command\\":\\"printf should-not-run\\",\\"timeout\\":60}" }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "I will try Bash." } }, "time": "<time>" }
+      [emit] requestApproval             { "turnId": 0, "toolCallId": "call_bash", "toolName": "Bash", "action": "run command", "display": { "kind": "generic", "summary": "Approve Bash", "detail": { "command": "printf should-not-run", "timeout": 60 } } }
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: Bash
+      messages:
+        user: text "Try to run Bash"
+    `);
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will not run the command.' });
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] permission.record_approval_result   { "turnId": 0, "toolCallId": "call_bash", "toolName": "Bash", "action": "run command", "result": { "decision": "rejected", "selectedLabel": "reject" }, "time": "<time>" }
+      [wire] context.append_loop_event           { "event": { "type": "tool.call", "uuid": "call_bash", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf should-not-run", "timeout": 60 } }, "time": "<time>" }
+      [emit] tool.call.started                   { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf should-not-run", "timeout": 60 } }
+      [wire] context.append_loop_event           { "event": { "type": "tool.result", "parentUuid": "call_bash", "toolCallId": "call_bash", "result": { "output": "Tool \\"Bash\\" was not run because the user rejected the approval request.", "isError": true } }, "time": "<time>" }
+      [emit] tool.result                         { "turnId": 0, "toolCallId": "call_bash", "output": "Tool \\"Bash\\" was not run because the user rejected the approval request.", "isError": true }
+      [wire] context.append_loop_event           { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "usage": { "inputOther": 5, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }, "time": "<time>" }
+      [emit] turn.step.completed                 { "turnId": 0, "step": 1, "stepId": "<uuid-1>", "usage": { "inputOther": 5, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }
+      [wire] usage.record                        { "model": "mock-model", "usage": { "inputOther": 5, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated                { "model": "mock-model", "contextTokens": 27, "maxContextTokens": 1000000, "contextUsage": 0.000027, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 5, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 5, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 5, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] context.append_loop_event           { "event": { "type": "step.begin", "uuid": "<uuid-3>", "turnId": "0", "step": 2 }, "time": "<time>" }
+      [emit] turn.step.started                   { "turnId": 0, "step": 2, "stepId": "<uuid-3>" }
+      [emit] assistant.delta                     { "turnId": 0, "delta": "I will not run the command." }
+      [wire] context.append_loop_event           { "event": { "type": "content.part", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "stepUuid": "<uuid-3>", "part": { "type": "text", "text": "I will not run the command." } }, "time": "<time>" }
+      [wire] context.append_loop_event           { "event": { "type": "step.end", "uuid": "<uuid-3>", "turnId": "0", "step": 2, "usage": { "inputOther": 58, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+      [emit] turn.step.completed                 { "turnId": 0, "step": 2, "stepId": "<uuid-3>", "usage": { "inputOther": 58, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+      [wire] usage.record                        { "model": "mock-model", "usage": { "inputOther": 58, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated                { "model": "mock-model", "contextTokens": 68, "maxContextTokens": 1000000, "contextUsage": 0.000068, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 63, "output": 32, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 63, "output": 32, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 63, "output": 32, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [emit] turn.ended                          { "turnId": 0, "reason": "completed" }
+    `);
+    expect(execWithEnv).not.toHaveBeenCalled();
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      messages:
+        <last>
+        assistant: text "I will try Bash."  calls call_bash:Bash { "command": "printf should-not-run", "timeout": 60 }
+        tool[call_bash]: text "<system>ERROR: Tool execution failed.</system>\\nTool \\"Bash\\" was not run because the user rejected the approval request."
+    `);
+    await ctx.expectResumeMatches();
+  });
+});
+
+describe('Permission auto mode', () => {
+  it('tells the agent not to ask questions in auto mode', async () => {
+    const appendSystemReminder = vi.fn();
+    const agent = {
+      permission: { mode: 'auto' },
+      context: { history: [], appendSystemReminder },
+    } as unknown as Agent;
+    const injector = new PermissionModeInjector(agent);
+
+    await injector.inject();
+
+    expect(appendSystemReminder).toHaveBeenCalledWith(
+      expect.stringContaining('Do NOT call AskUserQuestion while auto mode is active'),
+      { kind: 'injection', variant: 'permission_mode' },
+    );
+  });
+
+  it('blocks AskUserQuestion in auto mode before execution', async () => {
+    const { manager, requestApproval } = makePermissionManager(async () => ({
+      decision: 'approved',
+    }));
+    manager.setMode('auto');
+
+    await expect(
+      manager.beforeToolCall(
+        hookContext({
+          id: 'call_question',
+          toolName: 'AskUserQuestion',
+          args: { questions: [] },
+        }),
+      ),
+    ).resolves.toMatchObject({
+      block: true,
+      reason: expect.stringContaining(
+        'AskUserQuestion is disabled while auto permission mode is active',
+      ),
+    });
+    expect(requestApproval).not.toHaveBeenCalled();
+  });
+
+  it('allows AskUserQuestion in yolo mode so it can reach question rpc', async () => {
+    const { manager, requestApproval } = makePermissionManager(async () => ({
+      decision: 'approved',
+    }));
+    manager.setMode('yolo');
+
+    await expect(
+      manager.beforeToolCall(
+        hookContext({
+          id: 'call_question',
+          toolName: 'AskUserQuestion',
+          args: { questions: [] },
+        }),
+      ),
+    ).resolves.toBeUndefined();
+    expect(requestApproval).not.toHaveBeenCalled();
+  });
+
+  it.each(['auto', 'yolo'] as const)('applies deny rules before %s mode bypass', async (mode) => {
+    const { manager, requestApproval } = makePermissionManager(async () => ({
+      decision: 'approved',
+    }));
+    manager.setMode(mode);
+    manager.rules.push({
+      decision: 'deny',
+      scope: 'user',
+      pattern: 'Bash',
+      reason: 'blocked by test',
+    });
+
+    await expect(manager.beforeToolCall(hookContext({ id: 'call_1' }))).resolves.toMatchObject({
+      block: true,
+      reason: 'Tool "Bash" was denied by permission rule. Reason: blocked by test',
+    });
+    expect(requestApproval).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['auto', 'afk'],
+    ['yolo', 'yolo'],
+  ] as const)('tracks %s mode bypass as approval_mode=%s', async (mode, approvalMode) => {
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(async () => ({
+      decision: 'approved',
+    }));
+    manager.setMode(mode);
+
+    await expect(manager.beforeToolCall(hookContext({ id: 'call_1' }))).resolves.toBeUndefined();
+
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(telemetryTrack).toHaveBeenCalledWith('tool_approved', {
+      tool_name: 'Bash',
+      approval_mode: approvalMode,
+    });
+  });
+
+  it('tracks plan-mode Bash bypass in auto mode as approval_mode=afk', async () => {
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({
+        decision: 'approved',
+      }),
+      { planModeActive: true },
+    );
+    manager.setMode('auto');
+
+    await expect(manager.beforeToolCall(hookContext({ id: 'call_plan_bash' }))).resolves.toBeUndefined();
+
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(telemetryTrack).toHaveBeenCalledWith('tool_approved', {
+      tool_name: 'Bash',
+      approval_mode: 'afk',
+    });
+  });
+
+  it.each(['auto', 'yolo'] as const)(
+    'does not track approval for default-allowed tools in %s mode',
+    async (mode) => {
+      const { manager, requestApproval, telemetryTrack } = makePermissionManager(async () => ({
+        decision: 'approved',
+      }));
+      manager.setMode(mode);
+
+      await expect(
+        manager.beforeToolCall(
+          hookContext({
+            id: 'call_read',
+            toolName: 'Read',
+            args: { path: '/workspace/notes.md' },
+          }),
+        ),
+      ).resolves.toBeUndefined();
+
+      expect(requestApproval).not.toHaveBeenCalled();
+      expect(telemetryTrack).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each([
+    ['Read', { path: '/tmp/notes.md' }, 'read'],
+    ['ReadMediaFile', { path: '/tmp/image.png' }, 'read'],
+    ['Write', { path: '/tmp/notes.md', content: 'x' }, 'write'],
+    ['Edit', { path: '/tmp/notes.md', old_string: 'a', new_string: 'b' }, 'edit'],
+    ['Grep', { pattern: 'TODO', path: '/tmp' }, 'grep'],
+  ] as const)(
+    'requests approval for %s outside the workspace in yolo mode',
+    async (toolName, args, operation) => {
+      const { manager, requestApproval } = makePermissionManager(async () => ({
+        decision: 'approved',
+      }));
+      manager.setMode('yolo');
+
+      await expect(
+        manager.beforeToolCall(hookContext({ id: `call_${toolName}`, toolName, args })),
+      ).resolves.toBeUndefined();
+
+      expect(requestApproval).toHaveBeenCalledWith(
+        expect.objectContaining({
+          toolName,
+          display: {
+            kind: 'file_io',
+            operation,
+            path: args.path,
+            detail: 'Outside workspace: /workspace',
+          },
+        }),
+        expect.any(Object),
+      );
+    },
+  );
+
+  it.each([
+    ['Read', { path: '/workspace/notes.md' }],
+    ['ReadMediaFile', { path: '/workspace/image.png' }],
+    ['Write', { path: '/workspace/notes.md', content: 'x' }],
+    ['Edit', { path: '/workspace/notes.md', old_string: 'a', new_string: 'b' }],
+    ['Grep', { pattern: 'TODO', path: '/workspace' }],
+  ] as const)(
+    'does not request approval for %s inside the workspace in yolo mode',
+    async (toolName, args) => {
+      const { manager, requestApproval } = makePermissionManager(async () => ({
+        decision: 'approved',
+      }));
+      manager.setMode('yolo');
+
+      await expect(
+        manager.beforeToolCall(hookContext({ id: `call_${toolName}`, toolName, args })),
+      ).resolves.toBeUndefined();
+
+      expect(requestApproval).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each(['manual', 'auto'] as const)(
+    'does not apply the outside-workspace yolo policy in %s mode',
+    async (mode) => {
+      const { manager, requestApproval } = makePermissionManager(async () => ({
+        decision: 'approved',
+      }));
+      manager.setMode(mode);
+
+      await expect(
+        manager.beforeToolCall(
+          hookContext({
+            id: `call_read_${mode}`,
+            toolName: 'Read',
+            args: { path: '/tmp/notes.md' },
+          }),
+        ),
+      ).resolves.toBeUndefined();
+
+      expect(requestApproval).not.toHaveBeenCalled();
+    },
+  );
+
+  it('keeps explicit deny rules higher priority than yolo outside-workspace approval', async () => {
+    const { manager, requestApproval } = makePermissionManager(async () => ({
+      decision: 'approved',
+    }));
+    manager.setMode('yolo');
+    manager.rules.push({
+      decision: 'deny',
+      scope: 'user',
+      pattern: 'Read',
+      reason: 'reads disabled',
+    });
+
+    await expect(
+      manager.beforeToolCall(
+        hookContext({
+          id: 'call_read_denied',
+          toolName: 'Read',
+          args: { path: '/tmp/notes.md' },
+        }),
+      ),
+    ).resolves.toMatchObject({
+      block: true,
+      reason: 'Tool "Read" was denied by permission rule. Reason: reads disabled',
+    });
+    expect(requestApproval).not.toHaveBeenCalled();
+  });
+
+  it('reuses approve-for-session for repeated outside-workspace reads in yolo mode', async () => {
+    const { manager, requestApproval } = makePermissionManager(async () => ({
+      decision: 'approved',
+      scope: 'session',
+      selectedLabel: 'Approve for this session',
+    }));
+    manager.setMode('yolo');
+    const call = () =>
+      manager.beforeToolCall(
+        hookContext({
+          id: 'call_read_session',
+          toolName: 'Read',
+          args: { path: '/tmp/notes.md' },
+        }),
+      );
+
+    await expect(call()).resolves.toBeUndefined();
+    await expect(call()).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+    expect(manager.data().rules).toContainEqual({
+      decision: 'allow',
+      scope: 'session-runtime',
+      pattern: 'Read',
+      reason: 'approve_for_session: read file',
+    });
+  });
+});
+
+describe('Permission policy chain', () => {
+  it('keeps plan-specific policies under the permission module plan namespace', () => {
+    expect(createPlanPermissionPolicies().map((policy) => policy.name)).toEqual([
+      'plan.enter-plan-mode',
+      'plan.exit-plan-mode',
+      'plan.mode-guard',
+    ]);
+  });
+
+  it('runs custom policies after deny rules and before generic approval', async () => {
+    const policy: PermissionPolicy = {
+      name: 'test.block-bash',
+      evaluate: vi.fn(async (): Promise<PermissionPolicyResult> => ({
+        kind: 'result',
+        result: {
+          block: true,
+          reason: 'blocked by custom policy',
+        },
+      })),
+    };
+    const { manager, requestApproval } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { policies: [policy] },
+    );
+
+    await expect(manager.beforeToolCall(hookContext({ id: 'call_policy' }))).resolves.toEqual({
+      block: true,
+      reason: 'blocked by custom policy',
+    });
+    expect(policy.evaluate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        agent: expect.any(Object),
+        mode: 'manual',
+        toolCallContext: expect.objectContaining({
+          toolCall: expect.objectContaining({ id: 'call_policy' }),
+        }),
+      }),
+    );
+    expect(requestApproval).not.toHaveBeenCalled();
+  });
+
+  it('keeps explicit deny rules higher priority than custom policies', async () => {
+    const policy: PermissionPolicy = {
+      name: 'test.allow-bash',
+      evaluate: vi.fn(async (): Promise<PermissionPolicyResult> => ({ kind: 'allow' })),
+    };
+    const { manager, requestApproval } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { policies: [policy] },
+    );
+    manager.rules.push({
+      decision: 'deny',
+      scope: 'user',
+      pattern: 'Bash',
+      reason: 'blocked before policy',
+    });
+
+    await expect(manager.beforeToolCall(hookContext({ id: 'call_deny' }))).resolves.toMatchObject({
+      block: true,
+      reason: 'Tool "Bash" was denied by permission rule. Reason: blocked before policy',
+    });
+    expect(policy.evaluate).not.toHaveBeenCalled();
+    expect(requestApproval).not.toHaveBeenCalled();
+  });
+});
+
+describe('Permission live derive', () => {
+  it('derives parent mode until the child records a local mode', () => {
+    const parent = makePermissionManager(async () => ({ decision: 'approved' }));
+    const child = makePermissionManager(async () => ({ decision: 'approved' }), {
+      parent: parent.manager,
+    });
+
+    expect(child.manager.mode).toBe('manual');
+    parent.manager.setMode('yolo');
+    expect(child.manager.mode).toBe('yolo');
+    expect(child.manager.data().mode).toBe('yolo');
+
+    child.manager.setMode('manual');
+    parent.manager.setMode('auto');
+    expect(child.manager.mode).toBe('manual');
+  });
+
+  it('uses child matching rules before parent rules', async () => {
+    const parent = makePermissionManager(async () => ({ decision: 'approved' }));
+    parent.manager.rules.push({
+      decision: 'deny',
+      scope: 'user',
+      pattern: 'Bash',
+      reason: 'parent deny',
+    });
+    const child = makePermissionManager(async () => ({ decision: 'approved' }), {
+      parent: parent.manager,
+    });
+    child.manager.rules.push({
+      decision: 'allow',
+      scope: 'session-runtime',
+      pattern: 'Bash',
+      reason: 'child allow',
+    });
+
+    await expect(child.manager.beforeToolCall(hookContext({ id: 'call_allow' }))).resolves
+      .toBeUndefined();
+    expect(child.requestApproval).not.toHaveBeenCalled();
+
+    const parentAllow = makePermissionManager(async () => ({ decision: 'approved' }));
+    parentAllow.manager.rules.push({
+      decision: 'allow',
+      scope: 'user',
+      pattern: 'Bash',
+      reason: 'parent allow',
+    });
+    const childDeny = makePermissionManager(async () => ({ decision: 'approved' }), {
+      parent: parentAllow.manager,
+    });
+    childDeny.manager.rules.push({
+      decision: 'deny',
+      scope: 'user',
+      pattern: 'Bash',
+      reason: 'child deny',
+    });
+
+    await expect(childDeny.manager.beforeToolCall(hookContext({ id: 'call_deny' }))).resolves
+      .toMatchObject({
+        block: true,
+        reason: 'Tool "Bash" was denied by permission rule. Reason: child deny',
+      });
+    expect(childDeny.requestApproval).not.toHaveBeenCalled();
+  });
+
+  it('falls back to parent rules and session approvals when no child rule matches', async () => {
+    const parent = makePermissionManager(async () => ({ decision: 'approved' }));
+    parent.manager.recordApprovalResult({
+      turnId: 0,
+      toolCallId: 'call_parent',
+      toolName: 'Bash',
+      action: 'run command',
+      result: {
+        decision: 'approved',
+        scope: 'session',
+        selectedLabel: 'Approve for this session',
+      },
+    });
+    const child = makePermissionManager(async () => ({ decision: 'approved' }), {
+      parent: parent.manager,
+    });
+
+    await expect(child.manager.beforeToolCall(hookContext({ id: 'call_child' }))).resolves
+      .toBeUndefined();
+
+    expect(child.requestApproval).not.toHaveBeenCalled();
+    expect(child.manager.rules).toEqual([]);
+    expect(child.manager.data().rules).toContainEqual(sessionAllowRule());
+  });
+
+  it('uses child local mode for inherited non-deny decisions', async () => {
+    const parent = makePermissionManager(async () => ({ decision: 'approved' }));
+    parent.manager.setMode('yolo');
+    const child = makePermissionManager(async () => ({ decision: 'approved' }), {
+      parent: parent.manager,
+    });
+
+    await expect(child.manager.beforeToolCall(hookContext({ id: 'call_inherited_yolo' }))).resolves
+      .toBeUndefined();
+    expect(child.requestApproval).not.toHaveBeenCalled();
+
+    child.manager.setMode('manual');
+    await expect(child.manager.beforeToolCall(hookContext({ id: 'call_local_manual' }))).resolves
+      .toBeUndefined();
+    expect(child.requestApproval).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('Plan mode Bash permission policy', () => {
+  it('uses ordinary Bash approval in manual plan mode', async () => {
+    const { manager, requestApproval } = makePlanPermissionManager({
+      mode: 'manual',
+      approval: { decision: 'approved' },
+    });
+
+    await expect(
+      manager.beforeToolCall(
+        hookContext({
+          id: 'call_plan_bash',
+          toolName: 'Bash',
+          args: { command: 'ls -la', timeout: 60 },
+        }),
+      ),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledWith(
+      {
+        turnId: 0,
+        toolCallId: 'call_plan_bash',
+        toolName: 'Bash',
+        action: 'run command',
+        display: {
+          kind: 'generic',
+          summary: 'Approve Bash',
+          detail: { command: 'ls -la', timeout: 60 },
+        },
+      },
+      { signal: expect.any(AbortSignal) },
+    );
+  });
+
+  it('reuses ordinary Bash approve-for-session in plan mode', async () => {
+    const { manager, requestApproval } = makePlanPermissionManager({
+      mode: 'manual',
+    });
+    manager.recordApprovalResult({
+      turnId: 0,
+      toolCallId: 'call_ordinary_bash',
+      toolName: 'Bash',
+      action: 'run command',
+      result: {
+        decision: 'approved',
+        scope: 'session',
+        selectedLabel: 'Approve for this session',
+      },
+    });
+
+    await expect(
+      manager.beforeToolCall(
+        hookContext({
+          id: 'call_plan_bash',
+          toolName: 'Bash',
+          args: { command: 'ls -la', timeout: 60 },
+        }),
+      ),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(manager.data().rules).toContainEqual(sessionAllowRule());
+  });
+
+  it.each(['yolo', 'auto'] as const)(
+    'defers Bash to ordinary %s permission behavior in plan mode',
+    async (mode) => {
+      const { manager, requestApproval } = makePlanPermissionManager({
+        mode,
+        approval: { decision: 'rejected' },
+      });
+
+      await expect(
+        manager.beforeToolCall(
+          hookContext({
+            id: 'call_plan_bash',
+            toolName: 'Bash',
+            args: { command: 'rm generated.txt', timeout: 60 },
+          }),
+        ),
+      ).resolves.toBeUndefined();
+
+      expect(requestApproval).not.toHaveBeenCalled();
+    },
+  );
+});
+
+describe('ExitPlanMode permission policy', () => {
+  const planOptions = [
+    { label: 'Approach A', description: 'Use the small change.' },
+    { label: 'Approach B', description: 'Use the complete refactor.' },
+  ];
+
+  it('allows ExitPlanMode directly in auto mode without requesting approval', async () => {
+    const { manager, requestApproval } = makePlanPermissionManager({
+      mode: 'auto',
+      plan: '# Auto Plan',
+    });
+
+    const result = await manager.beforeToolCall(
+      hookContext({ id: 'call_exit', toolName: 'ExitPlanMode', args: {} }),
+    );
+
+    expect(result).toBeUndefined();
+    expect(requestApproval).not.toHaveBeenCalled();
+  });
+
+  it('requests plan-review approval in yolo mode and returns selected option metadata', async () => {
+    const { manager, record, requestApproval } = makePlanPermissionManager({
+      mode: 'yolo',
+      plan: '# Plan\n\n- Step',
+      path: '/tmp/plan.md',
+      approval: { decision: 'approved', selectedLabel: 'Approach B' },
+    });
+
+    const result = await manager.beforeToolCall(
+      hookContext({
+        id: 'call_exit',
+        toolName: 'ExitPlanMode',
+        args: { options: planOptions },
+      }),
+    );
+
+    expect(requestApproval).toHaveBeenCalledWith(
+      {
+        turnId: 0,
+        toolCallId: 'call_exit',
+        toolName: 'ExitPlanMode',
+        action: 'Review plan and choose an option',
+        display: {
+          kind: 'plan_review',
+          plan: '# Plan\n\n- Step',
+          path: '/tmp/plan.md',
+          options: planOptions,
+        },
+      },
+      { signal: expect.any(AbortSignal) },
+    );
+    expect(record).toHaveBeenCalledWith({
+      type: 'permission.record_approval_result',
+      turnId: 0,
+      toolCallId: 'call_exit',
+      toolName: 'ExitPlanMode',
+      action: 'Review plan and choose an option',
+      result: { decision: 'approved', selectedLabel: 'Approach B' },
+    });
+    expect(result).toMatchObject({
+      executionMetadata: {
+        selectedOption: planOptions[1],
+      },
+    });
+  });
+
+  it('returns a synthetic stop-turn result when the user rejects the plan', async () => {
+    const { manager, exit } = makePlanPermissionManager({
+      mode: 'manual',
+      plan: '# Draft Plan',
+      approval: { decision: 'rejected', selectedLabel: 'Reject' },
+    });
+
+    const result = await manager.beforeToolCall(
+      hookContext({ id: 'call_exit', toolName: 'ExitPlanMode', args: {} }),
+    );
+
+    expect(exit).not.toHaveBeenCalled();
+    expect(result).toMatchObject({
+      syntheticResult: {
+        isError: true,
+        stopTurn: true,
+        output: 'Plan rejected by user. Plan mode remains active.',
+      },
+    });
+  });
+
+  it('keeps plan mode active when plan approval is cancelled', async () => {
+    const { manager, exit } = makePlanPermissionManager({
+      mode: 'manual',
+      plan: '# Draft Plan',
+      approval: { decision: 'cancelled', feedback: 'dismissed' },
+    });
+
+    const result = await manager.beforeToolCall(
+      hookContext({ id: 'call_exit', toolName: 'ExitPlanMode', args: {} }),
+    );
+
+    expect(exit).not.toHaveBeenCalled();
+    expect(result).toMatchObject({
+      syntheticResult: {
+        isError: false,
+        output: 'Plan approval dismissed. Plan mode remains active.',
+      },
+    });
+  });
+
+  it('keeps plan mode active when plan approval request fails', async () => {
+    const { manager, exit, record } = makePlanPermissionManager({
+      mode: 'manual',
+      plan: '# Draft Plan',
+      approvalError: new Error('approval transport closed'),
+    });
+
+    const result = await manager.beforeToolCall(
+      hookContext({ id: 'call_exit', toolName: 'ExitPlanMode', args: {} }),
+    );
+
+    expect(exit).not.toHaveBeenCalled();
+    expect(record).not.toHaveBeenCalled();
+    expect(result).toMatchObject({
+      syntheticResult: {
+        isError: true,
+        output: 'Plan approval failed: approval transport closed',
+      },
+    });
+  });
+
+  it('keeps plan mode active and returns revision feedback as a synthetic result', async () => {
+    const { manager, exit } = makePlanPermissionManager({
+      mode: 'manual',
+      plan: '# Draft Plan',
+      approval: {
+        decision: 'rejected',
+        selectedLabel: 'Revise',
+        feedback: 'Add verification.',
+      },
+    });
+
+    const result = await manager.beforeToolCall(
+      hookContext({ id: 'call_exit', toolName: 'ExitPlanMode', args: {} }),
+    );
+
+    expect(exit).not.toHaveBeenCalled();
+    expect(result).toMatchObject({
+      syntheticResult: {
+        isError: false,
+        output: expect.stringContaining('Add verification.'),
+      },
+    });
+  });
+});
+
+describe('Agent-local approve for session', () => {
+  it('turns approved session-scoped responses into an agent-local allow cache', async () => {
+    const { manager, record, requestApproval, telemetryTrack } = makePermissionManager(async () => ({
+      decision: 'approved',
+      scope: 'session',
+      selectedLabel: 'Approve for this session',
+    }));
+
+    await expect(manager.beforeToolCall(hookContext({ id: 'call_1' }))).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+    expect(telemetryTrack).toHaveBeenNthCalledWith(1, 'tool_approved', {
+      tool_name: 'Bash',
+      approval_mode: 'manual',
+      scope: 'session',
+    });
+    expect(record).toHaveBeenCalledWith({
+      type: 'permission.record_approval_result',
+      turnId: 0,
+      toolCallId: 'call_1',
+      toolName: 'Bash',
+      action: 'run command',
+      result: {
+        decision: 'approved',
+        scope: 'session',
+        selectedLabel: 'Approve for this session',
+      },
+    });
+    expect(manager.data().rules).toContainEqual({
+      decision: 'allow',
+      scope: 'session-runtime',
+      pattern: 'Bash',
+      reason: 'approve_for_session: run command',
+    });
+
+    await expect(
+      manager.beforeToolCall(
+        hookContext({
+          id: 'call_2',
+          args: { command: 'printf second', timeout: 60 },
+        }),
+      ),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+    expect(telemetryTrack).toHaveBeenNthCalledWith(2, 'tool_approved', {
+      tool_name: 'Bash',
+      approval_mode: 'auto_session',
+      scope: 'session',
+    });
+  });
+
+  it('keeps approved once responses one-shot', async () => {
+    const { manager, record, requestApproval } = makePermissionManager(async () => ({
+      decision: 'approved',
+    }));
+
+    await expect(manager.beforeToolCall(hookContext({ id: 'call_1' }))).resolves.toBeUndefined();
+    await expect(manager.beforeToolCall(hookContext({ id: 'call_2' }))).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(2);
+    expect(record).toHaveBeenCalledTimes(2);
+    expect(record).toHaveBeenNthCalledWith(1, {
+      type: 'permission.record_approval_result',
+      turnId: 0,
+      toolCallId: 'call_1',
+      toolName: 'Bash',
+      action: 'run command',
+      result: {
+        decision: 'approved',
+      },
+    });
+    expect(record).toHaveBeenNthCalledWith(2, {
+      type: 'permission.record_approval_result',
+      turnId: 0,
+      toolCallId: 'call_2',
+      toolName: 'Bash',
+      action: 'run command',
+      result: {
+        decision: 'approved',
+      },
+    });
+    expect(manager.data().rules).toEqual([]);
+  });
+
+  it('does not let session approval override an explicit deny rule', async () => {
+    const { manager, requestApproval } = makePermissionManager(async () => ({
+      decision: 'approved',
+    }));
+    manager.recordApprovalResult({
+      turnId: 0,
+      toolCallId: 'call_session',
+      toolName: 'Bash',
+      action: 'run command',
+      result: {
+        decision: 'approved',
+        scope: 'session',
+      },
+    });
+    manager.rules.push({
+      decision: 'deny',
+      scope: 'user',
+      pattern: 'Bash',
+      reason: 'blocked by test',
+    });
+
+    const result = await manager.beforeToolCall(hookContext({ id: 'call_1' }));
+
+    expect(result).toMatchObject({
+      block: true,
+      reason: 'Tool "Bash" was denied by permission rule. Reason: blocked by test',
+    });
+    expect(requestApproval).not.toHaveBeenCalled();
+  });
+
+  it('replays session approval wire events into agent permission state', () => {
+    const ctx = testAgent();
+    const rule = sessionAllowRule();
+
+    ctx.dispatch({
+      type: 'permission.record_approval_result',
+      turnId: 0,
+      toolCallId: 'call_replay',
+      toolName: 'Bash',
+      action: 'run command',
+      result: {
+        decision: 'approved',
+        scope: 'session',
+        selectedLabel: 'Approve for this session',
+      },
+    });
+
+    expect(ctx.agent.permission.data().rules).toContainEqual(rule);
+  });
+
+  it('replays one-shot approval wire events without adding session rules', () => {
+    const ctx = testAgent();
+    const record = {
+      turnId: 0,
+      toolCallId: 'call_replay',
+      toolName: 'Bash',
+      action: 'run command',
+      result: {
+        decision: 'approved',
+        selectedLabel: 'Approve once',
+      },
+    } as const;
+
+    const event = {
+      type: 'permission.record_approval_result',
+      ...record,
+    } as const;
+
+    ctx.dispatch(event);
+
+    expect(ctx.agent.replayBuilder.buildResult()).toContainEqual({
+      type: 'approval_result',
+      record: event,
+    });
+    expect(ctx.agent.permission.data().rules).toEqual([]);
+  });
+});
+
+describe('Approval telemetry', () => {
+  it('tracks cancelled approval requests with approval_mode=cancelled', async () => {
+    const { manager, telemetryTrack } = makePermissionManager(async () => ({
+      decision: 'cancelled',
+      feedback: 'request closed',
+    }));
+
+    await expect(manager.beforeToolCall(hookContext({ id: 'call_1' }))).resolves.toMatchObject({
+      block: true,
+      reason: expect.stringContaining('approval request was cancelled'),
+    });
+
+    expect(telemetryTrack).toHaveBeenCalledWith('tool_rejected', {
+      tool_name: 'Bash',
+      approval_mode: 'cancelled',
+      decision: 'cancelled',
+      has_feedback: true,
+    });
+  });
+});
+
+describe('Default git CWD Write/Edit permission', () => {
+  const DIR_MODE = 0o040_755;
+  const FILE_MODE = 0o100_644;
+  const SYMLINK_MODE = 0o120_777;
+
+  function statResult(mode: number): Awaited<ReturnType<Kaos['stat']>> {
+    return {
+      stMode: mode,
+      stIno: 1,
+      stDev: 1,
+      stNlink: 1,
+      stUid: 1000,
+      stGid: 1000,
+      stSize: 0,
+      stAtime: 0,
+      stMtime: 0,
+      stCtime: 0,
+    };
+  }
+
+  function notFound(path: string): Error {
+    return Object.assign(new Error(`ENOENT ${path}`), { code: 'ENOENT' });
+  }
+
+  function sshNotFound(path: string): Error {
+    const error = Object.assign(new Error(`No such file: ${path}`), { code: 2 });
+    error.name = 'KaosFileNotFoundError';
+    return error;
+  }
+
+  function gitKaos(options: {
+    readonly markerPath?: string | undefined;
+    readonly markerMode?: number | undefined;
+    readonly statModes?: Readonly<Record<string, number>> | undefined;
+    readonly readText?: Kaos['readText'] | undefined;
+    readonly missingError?: (path: string) => Error;
+  } = {}): { kaos: Kaos; stat: ReturnType<typeof vi.fn<Kaos['stat']>> } {
+    const markerPath = options.markerPath ?? '/workspace/.git';
+    const statModes: Readonly<Record<string, number>> = {
+      '/workspace': DIR_MODE,
+      '/workspace/src': DIR_MODE,
+      [markerPath]: options.markerMode ?? DIR_MODE,
+      ...options.statModes,
+    };
+    const stat = vi
+      .fn<Kaos['stat']>()
+      .mockImplementation(async (path) => {
+        const mode = statModes[path];
+        if (mode !== undefined) return statResult(mode);
+        throw options.missingError?.(path) ?? notFound(path);
+      });
+    return {
+      kaos: createFakeKaos({ stat, readText: options.readText }),
+      stat,
+    };
+  }
+
+  function nonGitKaos(): Kaos {
+    return createFakeKaos({
+      stat: vi.fn<Kaos['stat']>().mockRejectedValue(new Error('ENOENT')),
+    });
+  }
+
+  function writeHook(args: Record<string, unknown>, id = 'call_write'): ToolExecutionHookContext {
+    return hookContext({ id, toolName: 'Write', args });
+  }
+
+  function editHook(args: Record<string, unknown>, id = 'call_edit'): ToolExecutionHookContext {
+    return hookContext({ id, toolName: 'Edit', args });
+  }
+
+  it('still requests approval for Bash inside a git cwd in manual mode', async () => {
+    const { kaos } = gitKaos();
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+
+    await expect(manager.beforeToolCall(hookContext({ id: 'call_bash_git_cwd' }))).resolves
+      .toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledWith(
+      expect.objectContaining({
+        toolName: 'Bash',
+        action: 'run command',
+      }),
+      expect.any(Object),
+    );
+    expect(telemetryTrack).not.toHaveBeenCalledWith(
+      'tool_approved',
+      expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+    );
+  });
+
+  it('bypasses approval for Write to a relative path inside a git cwd', async () => {
+    const { kaos } = gitKaos();
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: 'src/a.ts', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(telemetryTrack).toHaveBeenCalledWith('tool_approved', {
+      tool_name: 'Write',
+      approval_mode: 'manual',
+      auto_reason: 'default_git_cwd_write',
+    });
+  });
+
+  it('bypasses approval for Edit on an absolute path inside the git cwd', async () => {
+    const { kaos } = gitKaos();
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+
+    await expect(
+      manager.beforeToolCall(
+        editHook({ path: '/workspace/src/a.ts', old_string: 'A', new_string: 'B' }),
+      ),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(telemetryTrack).toHaveBeenCalledWith('tool_approved', {
+      tool_name: 'Edit',
+      approval_mode: 'manual',
+      auto_reason: 'default_git_cwd_write',
+    });
+  });
+
+  it('still requests approval when cwd is not inside a git work tree', async () => {
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos: nonGitKaos() },
+    );
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: 'src/a.ts', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+    expect(telemetryTrack).not.toHaveBeenCalledWith(
+      'tool_approved',
+      expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+    );
+  });
+
+  it('still requests approval when a relative path escapes cwd via ..', async () => {
+    const { kaos } = gitKaos();
+    const { manager, requestApproval } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: '../outside.ts', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+  });
+
+  it('still requests approval for an absolute path outside the cwd', async () => {
+    const { kaos } = gitKaos();
+    const { manager, requestApproval } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: '/tmp/outside.ts', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+  });
+
+  it('still requests approval for a path inside the git root but outside the cwd', async () => {
+    const { kaos } = gitKaos({ markerPath: '/a/.git' });
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { cwd: '/a/b/c', kaos },
+    );
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: '/a/x.ts', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+    expect(telemetryTrack).not.toHaveBeenCalledWith(
+      'tool_approved',
+      expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+    );
+  });
+
+  it.each(['.git/config', '.git/hooks/pre-commit'])(
+    'still requests approval for git control file %s',
+    async (path) => {
+      const { kaos } = gitKaos();
+      const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+        async () => ({ decision: 'approved' }),
+        { kaos },
+      );
+
+      await expect(manager.beforeToolCall(writeHook({ path, content: 'x' }))).resolves
+        .toBeUndefined();
+
+      expect(requestApproval).toHaveBeenCalledTimes(1);
+      expect(telemetryTrack).not.toHaveBeenCalledWith(
+        'tool_approved',
+        expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+      );
+    },
+  );
+
+  it('still requests approval for case-variant git control files', async () => {
+    const { kaos } = gitKaos();
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: '.GIT/config', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+    expect(telemetryTrack).not.toHaveBeenCalledWith(
+      'tool_approved',
+      expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+    );
+  });
+
+  it('still requests approval for a linked-worktree gitdir inside cwd', async () => {
+    const { kaos } = gitKaos({
+      markerMode: FILE_MODE,
+      statModes: { '/workspace/.gitdir': DIR_MODE },
+      readText: vi.fn<Kaos['readText']>(async (path) => {
+        if (path === '/workspace/.git') return 'gitdir: .gitdir\n';
+        throw notFound(path);
+      }),
+    });
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: '/workspace/.gitdir/config', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+    expect(telemetryTrack).not.toHaveBeenCalledWith(
+      'tool_approved',
+      expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+    );
+  });
+
+  it('still requests approval when a parent path segment is a symlink', async () => {
+    const { kaos } = gitKaos({
+      statModes: { '/workspace/out': SYMLINK_MODE },
+    });
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: 'out/hosts', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+    expect(telemetryTrack).not.toHaveBeenCalledWith(
+      'tool_approved',
+      expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+    );
+  });
+
+  it('still requests approval when the target file is a symlink', async () => {
+    const { kaos } = gitKaos({
+      statModes: { '/workspace/link.txt': SYMLINK_MODE },
+    });
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: 'link.txt', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+    expect(telemetryTrack).not.toHaveBeenCalledWith(
+      'tool_approved',
+      expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+    );
+  });
+
+  it('still requests approval for a sensitive file inside the git cwd', async () => {
+    const { kaos } = gitKaos();
+    const { manager, requestApproval } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: '.env', content: 'SECRET=1' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+  });
+
+  it.each(['.ENV', '.Aws/credentials'])(
+    'still requests approval for case-variant sensitive file %s',
+    async (path) => {
+      const { kaos } = gitKaos({
+        statModes: path.includes('/') ? { '/workspace/.Aws': DIR_MODE } : {},
+      });
+      const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+        async () => ({ decision: 'approved' }),
+        { kaos },
+      );
+
+      await expect(manager.beforeToolCall(writeHook({ path, content: 'secret' }))).resolves
+        .toBeUndefined();
+
+      expect(requestApproval).toHaveBeenCalledTimes(1);
+      expect(telemetryTrack).not.toHaveBeenCalledWith(
+        'tool_approved',
+        expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+      );
+    },
+  );
+
+  it('bypasses approval for new files when SSH Kaos reports numeric no-such-file', async () => {
+    const { kaos } = gitKaos({ missingError: sshNotFound });
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: 'src/new.ts', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(telemetryTrack).toHaveBeenCalledWith('tool_approved', {
+      tool_name: 'Write',
+      approval_mode: 'manual',
+      auto_reason: 'default_git_cwd_write',
+    });
+  });
+
+  it('lets an explicit `ask` rule keep the approval prompt for Write', async () => {
+    const { kaos } = gitKaos();
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+    manager.rules.push({
+      decision: 'ask',
+      scope: 'user',
+      pattern: 'Write',
+      reason: 'user requested manual confirmation',
+    });
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: 'src/a.ts', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+    expect(telemetryTrack).not.toHaveBeenCalledWith(
+      'tool_approved',
+      expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+    );
+  });
+
+  it('lets an explicit `allow` rule take the original allow path without auto_reason telemetry', async () => {
+    const { kaos } = gitKaos();
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+    manager.rules.push({
+      decision: 'allow',
+      scope: 'user',
+      pattern: 'Write',
+    });
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: 'src/a.ts', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(telemetryTrack).not.toHaveBeenCalledWith(
+      'tool_approved',
+      expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+    );
+  });
+
+  it('keeps explicit `deny` rules higher priority than the bypass', async () => {
+    const { kaos } = gitKaos();
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+    manager.rules.push({
+      decision: 'deny',
+      scope: 'user',
+      pattern: 'Write',
+      reason: 'no writes here',
+    });
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: 'src/a.ts', content: 'x' })),
+    ).resolves.toMatchObject({
+      block: true,
+      reason: expect.stringContaining('no writes here'),
+    });
+
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(telemetryTrack).not.toHaveBeenCalledWith(
+      'tool_approved',
+      expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+    );
+  });
+
+  it('does not fire in auto mode — existing afk telemetry path takes over', async () => {
+    const { kaos } = gitKaos();
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+    manager.setMode('auto');
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: 'src/a.ts', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(telemetryTrack).toHaveBeenCalledWith('tool_approved', {
+      tool_name: 'Write',
+      approval_mode: 'afk',
+    });
+    expect(telemetryTrack).not.toHaveBeenCalledWith(
+      'tool_approved',
+      expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+    );
+  });
+
+  it('does not fire on Windows path semantics (Windows stMode unverified)', async () => {
+    const stat = vi
+      .fn<Kaos['stat']>()
+      .mockImplementation(async (path) =>
+        path === '/workspace/.git'
+          ? statResult(0o040_755)
+          : Promise.reject(new Error('ENOENT')),
+      );
+    const kaos = createFakeKaos({ stat, pathClass: () => 'win32' });
+    const { manager, requestApproval, telemetryTrack } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: 'src/a.ts', content: 'x' })),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).toHaveBeenCalledTimes(1);
+    expect(telemetryTrack).not.toHaveBeenCalledWith(
+      'tool_approved',
+      expect.objectContaining({ auto_reason: 'default_git_cwd_write' }),
+    );
+  });
+
+  it('caches the git marker check across repeated Write/Edit calls in the same cwd', async () => {
+    const { kaos, stat } = gitKaos();
+    const { manager, requestApproval } = makePermissionManager(
+      async () => ({ decision: 'approved' }),
+      { kaos },
+    );
+
+    await expect(
+      manager.beforeToolCall(writeHook({ path: 'src/a.ts', content: 'x' }, 'call_1')),
+    ).resolves.toBeUndefined();
+    await expect(
+      manager.beforeToolCall(editHook({ path: 'src/b.ts', old_string: 'A', new_string: 'B' }, 'call_2')),
+    ).resolves.toBeUndefined();
+
+    expect(requestApproval).not.toHaveBeenCalled();
+    const markerCalls = stat.mock.calls.filter(([path]) => path === '/workspace/.git');
+    expect(markerCalls).toHaveLength(1);
+  });
+});
+
+describe('Permission rule helpers', () => {
+  it('parses permission patterns used by rule matching', () => {
+    expect(parsePattern('Write')).toEqual({ toolName: 'Write' });
+    expect(parsePattern('Read(/etc/**)')).toEqual({
+      toolName: 'Read',
+      argPattern: '/etc/**',
+    });
+    expect(parsePattern('Edit(!./src/**)')).toEqual({
+      toolName: 'Edit',
+      argPattern: '!./src/**',
+    });
+    expect(parsePattern('  mcp__github__*  ')).toEqual({ toolName: 'mcp__github__*' });
+    expect(parsePattern('Read()')).toEqual({ toolName: 'Read' });
+    expect(() => parsePattern('Read(/etc/**')).toThrow(/missing closing paren/);
+    expect(() => parsePattern('')).toThrow(/empty string/);
+  });
+
+  it('matches rules against the tool-specific argument fields', () => {
+    expect(matchesRule(permissionRule('Bash(git *)'), 'Bash', { command: 'git status' })).toBe(
+      true,
+    );
+    expect(matchesRule(permissionRule('Bash(git *)'), 'Bash', { command: 'npm test' })).toBe(false);
+    expect(matchesRule(permissionRule('Read(/etc/**)'), 'Read', { path: '/etc/passwd' })).toBe(
+      true,
+    );
+    expect(
+      matchesRule(permissionRule('Edit(!./src/**)', 'deny'), 'Edit', { path: './tests/foo.ts' }),
+    ).toBe(true);
+    expect(
+      matchesRule(permissionRule('Edit(!./src/**)', 'deny'), 'Edit', { path: './src/foo.ts' }),
+    ).toBe(false);
+    expect(
+      matchesRule(permissionRule('Agent(review-*)'), 'Agent', { subagent_type: 'review-code' }),
+    ).toBe(true);
+    expect(matchesRule(permissionRule('mcp__github__*'), 'mcp__github__list_issues', {})).toBe(
+      true,
+    );
+    expect(matchesRule(permissionRule('Bash(git *)'), 'Bash', { command: 42 })).toBe(false);
+    expect(matchesRule(permissionRule('Bad(unclosed'), 'Bad', {})).toBe(false);
+  });
+
+  it('matches path rules against lexical variants of the same absolute file', () => {
+    const secret = '/workspace/project/secret.txt';
+    const rule = permissionRule(`Read(${secret})`, 'deny');
+
+    expect(matchesRule(rule, 'Read', { path: secret })).toBe(true);
+    expect(matchesRule(rule, 'Read', { path: '/workspace/project/./secret.txt' })).toBe(true);
+    expect(matchesRule(rule, 'Read', { path: '/workspace/project/tmp/../secret.txt' })).toBe(true);
+    expect(matchesRule(rule, 'Read', { path: '/workspace/project/SECRET.txt' })).toBe(true);
+    expect(
+      matchesRule(permissionRule(`Read(${secret})`, 'allow'), 'Read', {
+        path: '/workspace/project/SECRET.txt',
+      }),
+    ).toBe(false);
+  });
+
+  it('matches path rules against relative tool paths using the active cwd', () => {
+    expect(
+      checkMatchingRules(
+        [permissionRule('Read(/workspace/project/secret.txt)', 'deny')],
+        'Read',
+        { path: './secret.txt' },
+        'manual',
+        { cwd: '/workspace/project', pathClass: 'posix' },
+      ),
+    ).toMatchObject({ decision: 'deny' });
+  });
+
+  it('matches win32 path rules across separators, dot segments, and case variants', () => {
+    const secret = 'C:\\workspace\\project\\secret.txt';
+    const denyRule = permissionRule(`Read(${secret})`, 'deny');
+    const allowRule = permissionRule(`Read(${secret})`, 'allow');
+    const context = { pathClass: 'win32' as const };
+
+    expect(
+      matchesRule(denyRule, 'Read', { path: 'C:\\workspace\\project\\.\\secret.txt' }, context),
+    ).toBe(true);
+    expect(
+      matchesRule(
+        denyRule,
+        'Read',
+        { path: 'C:\\workspace\\project\\tmp\\..\\SECRET.txt' },
+        context,
+      ),
+    ).toBe(true);
+    expect(
+      matchesRule(denyRule, 'Read', { path: 'C:/workspace/project/secret.txt' }, context),
+    ).toBe(true);
+    expect(
+      matchesRule(denyRule, 'Read', { path: 'C:/workspace\\project/tmp\\..\\SECRET.txt' }, context),
+    ).toBe(true);
+    expect(
+      matchesRule(allowRule, 'Read', { path: 'C:\\workspace\\project\\SECRET.txt' }, context),
+    ).toBe(true);
+  });
+
+  it('matches win32 path rules against relative tool paths using the active cwd', () => {
+    expect(
+      checkMatchingRules(
+        [permissionRule('Read(C:\\workspace\\project\\secret.txt)', 'deny')],
+        'Read',
+        { path: '.\\SECRET.txt' },
+        'manual',
+        { cwd: 'C:\\workspace\\project', pathClass: 'win32' },
+      ),
+    ).toMatchObject({ decision: 'deny' });
+  });
+
+  it('applies explicit rule priority and mode overlay in order', () => {
+    expect(checkMatchingRules([], 'Write', { path: '/tmp/a' }, 'manual')).toBeUndefined();
+    expect(
+      checkMatchingRules(
+        [permissionRule('Write', 'allow')],
+        'Write',
+        { path: '/tmp/a' },
+        'manual',
+      ),
+    ).toMatchObject({
+      decision: 'allow',
+    });
+    expect(
+      checkMatchingRules(
+        [permissionRule('Write', 'allow'), permissionRule('Write', 'ask')],
+        'Write',
+        {},
+        'manual',
+      ),
+    ).toMatchObject({ decision: 'ask' });
+    expect(
+      checkMatchingRules(
+        [permissionRule('Write', 'allow'), permissionRule('Write', 'deny')],
+        'Write',
+        {},
+        'manual',
+      ),
+    ).toMatchObject({ decision: 'deny' });
+    expect(
+      checkMatchingRules([permissionRule('Write', 'ask')], 'Write', { path: '/tmp/a' }, 'yolo'),
+    ).toMatchObject({
+      decision: 'allow',
+    });
+    expect(
+      checkMatchingRules([permissionRule('Write', 'deny')], 'Write', { path: '/tmp/a' }, 'yolo'),
+    ).toMatchObject({
+      decision: 'deny',
+    });
+  });
+
+  it('derives approval action labels from display semantics and MCP names', () => {
+    expect(describeApprovalAction('Bash', {}, { kind: 'command', command: 'git status' })).toBe(
+      'run command',
+    );
+    expect(
+      describeApprovalAction('Write', {}, { kind: 'file_io', operation: 'write', path: 'x' }),
+    ).toBe('write file');
+    expect(
+      describeApprovalAction('ExitPlanMode', {}, { kind: 'plan_review', plan: '# Plan' }),
+    ).toBe('review plan');
+    expect(
+      describeApprovalAction(
+        'Agent',
+        {},
+        { kind: 'agent_call', agent_name: 'review', prompt: 'x' },
+      ),
+    ).toBe('spawn agent');
+    expect(describeApprovalAction('Skill', {}, { kind: 'skill_call', skill_name: 'commit' })).toBe(
+      'invoke skill',
+    );
+    expect(describeApprovalAction('mcp__files__get_files', {}, genericDisplay())).toBe(
+      'call MCP tool: files:get_files',
+    );
+    expect(actionToRulePattern('edit file outside of working directory', 'Edit')).toBe('Write');
+    expect(actionToRulePattern('run command in plan mode', 'Bash')).toBeUndefined();
+    expect(actionToRulePattern('call CustomTool', 'CustomTool')).toBe('CustomTool');
+  });
+});
+
+function bashCall(): ToolCall {
+  return {
+    type: 'function',
+    id: 'call_bash',
+    function: {
+      name: 'Bash',
+      arguments: '{"command":"printf permission-output","timeout":60}',
+    },
+  };
+}
+
+function makePermissionManager(
+  handleApproval: (request: unknown) => Promise<ApprovalResponse>,
+  options: {
+    readonly policies?: readonly PermissionPolicy[];
+    readonly parent?: PermissionManager | undefined;
+    readonly planModeActive?: boolean;
+    readonly kaos?: Kaos;
+    readonly cwd?: string;
+  } = {},
+): {
+  manager: PermissionManager;
+  record: ReturnType<typeof vi.fn>;
+  requestApproval: ReturnType<typeof vi.fn>;
+  telemetryTrack: ReturnType<typeof vi.fn>;
+} {
+  let manager!: PermissionManager;
+  const requestApproval = vi.fn(handleApproval);
+  const record = vi.fn();
+  const telemetryTrack = vi.fn();
+  const agent = {
+    type: 'main',
+    config: { cwd: options.cwd ?? '/workspace' },
+    runtime: { kaos: options.kaos ?? createFakeKaos() },
+    emitStatusUpdated: vi.fn(),
+    records: { logRecord: record },
+    replayBuilder: { push: vi.fn() },
+    rpc: { requestApproval },
+    telemetry: { track: telemetryTrack },
+    planMode: {
+      get isActive() {
+        return options.planModeActive ?? false;
+      },
+      get planFilePath() {
+        return null;
+      },
+      data: vi.fn(async () => null),
+      exit: vi.fn(),
+    },
+  } as unknown as Agent;
+  manager = new PermissionManager(agent, options);
+  return { manager, record, requestApproval, telemetryTrack };
+}
+
+function makePlanPermissionManager(input: {
+  readonly mode: PermissionMode;
+  readonly plan?: string | null | undefined;
+  readonly path?: string | undefined;
+  readonly approval?: ApprovalResponse | undefined;
+  readonly approvalError?: Error | undefined;
+}): {
+  manager: PermissionManager;
+  record: ReturnType<typeof vi.fn>;
+  requestApproval: ReturnType<typeof vi.fn>;
+  exit: ReturnType<typeof vi.fn>;
+} {
+  const requestApproval = vi.fn(async () => {
+    if (input.approvalError !== undefined) throw input.approvalError;
+    return input.approval ?? { decision: 'approved' };
+  });
+  const record = vi.fn();
+  const exit = vi.fn();
+  const path = input.path ?? '/tmp/plan.md';
+  const agent = {
+    type: 'main',
+    config: { cwd: '/workspace' },
+    runtime: { kaos: createFakeKaos() },
+    emitStatusUpdated: vi.fn(),
+    records: { logRecord: record },
+    replayBuilder: { push: vi.fn() },
+    rpc: { requestApproval },
+    log: { warn: vi.fn(), error: vi.fn(), info: vi.fn(), debug: vi.fn() },
+    telemetry: { track: vi.fn() },
+    planMode: {
+      get isActive() {
+        return true;
+      },
+      get planFilePath() {
+        return path;
+      },
+      data: vi.fn(async () => {
+        if (input.plan === null) return null;
+        return {
+          content: input.plan ?? '# Plan',
+          path,
+        };
+      }),
+      exit,
+    },
+  } as unknown as Agent;
+  const manager = new PermissionManager(agent);
+  manager.mode = input.mode;
+  return { manager, record, requestApproval, exit };
+}
+
+function hookContext(input: {
+  readonly id: string;
+  readonly toolName?: string | undefined;
+  readonly args?: Record<string, unknown> | undefined;
+}): ToolExecutionHookContext {
+  const toolName = input.toolName ?? 'Bash';
+  const args = input.args ?? { command: 'printf first', timeout: 60 };
+  const toolCall: ToolCall = {
+    type: 'function',
+    id: input.id,
+    function: {
+      name: toolName,
+      arguments: JSON.stringify(args),
+    },
+  };
+  return {
+    turnId: '0',
+    stepNumber: 1,
+    signal: new AbortController().signal,
+    llm: {} as ToolExecutionHookContext['llm'],
+    toolCall,
+    args,
+  };
+}
+
+function sessionAllowRule(): PermissionRule {
+  return {
+    decision: 'allow',
+    scope: 'session-runtime',
+    pattern: 'Bash',
+    reason: 'approve_for_session: run command',
+  };
+}
+
+function permissionRule(
+  pattern: string,
+  decision: PermissionRule['decision'] = 'allow',
+): PermissionRule {
+  return {
+    decision,
+    scope: 'turn-override',
+    pattern,
+  };
+}
+
+function genericDisplay(): ToolInputDisplay {
+  return { kind: 'generic', summary: 'Approve tool', detail: {} };
+}
diff --git a/packages/agent-core/test/agent/plan.test.ts b/packages/agent-core/test/agent/plan.test.ts
new file mode 100644
index 000000000..a92ba61af
--- /dev/null
+++ b/packages/agent-core/test/agent/plan.test.ts
@@ -0,0 +1,673 @@
+import type { ToolCall } from '@moonshot-ai/kosong';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createFakeKaos } from '../tools/fixtures/fake-kaos';
+import { createCommandKaos, testAgent } from './harness/agent';
+
+function createPlanKaos(overrides: Parameters<typeof createFakeKaos>[0] = {}) {
+  return createFakeKaos({
+    mkdir: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  });
+}
+
+describe('manual plan entry', () => {
+  it('keeps permission gating out of the PlanMode state object', () => {
+    const ctx = testAgent();
+
+    expect('beforeToolCall' in ctx.agent.planMode).toBe(false);
+  });
+
+  it('enters plan mode without starting a model turn and prepares the plan directory', async () => {
+    const mkdir = vi.fn().mockResolvedValue(undefined);
+    const writeText = vi.fn().mockResolvedValue(0);
+    const ctx = testAgent({
+      kaos: createFakeKaos({ mkdir, writeText }),
+    });
+
+    await ctx.rpc.enterPlan({});
+    await delay(10);
+
+    expect(ctx.agent.planMode.isActive).toBe(true);
+    expect(ctx.agent.planMode.planFilePath).toMatch(/\.md$/);
+    expect(mkdir).toHaveBeenCalledWith('/workspace/plan', { parents: true, existOk: true });
+    expect(writeText).not.toHaveBeenCalled();
+    expect(ctx.allEvents.some((event) => event.event === 'turn.started')).toBe(false);
+    expect(ctx.llmCalls).toHaveLength(0);
+  });
+
+  it('derives the no-homedir plan path from cwd on enter and restore', async () => {
+    const ctx = testAgent({
+      kaos: createPlanKaos({
+        writeText: vi.fn(async (_path: string, content: string) => content.length),
+      }),
+    });
+    await ctx.agent.planMode.enter('stable-plan');
+
+    const livePath = ctx.agent.planMode.planFilePath;
+    if (livePath === null) throw new Error('expected active plan path');
+    expect(livePath).toBe('/workspace/plan/stable-plan.md');
+
+    const enterRecord = ctx.allEvents.find(
+      (event) => event.type === '[wire]' && event.event === 'plan_mode.enter',
+    );
+    expect(enterRecord?.args).toEqual({
+      id: 'stable-plan',
+      time: expect.any(Number),
+    });
+
+    const resumed = testAgent({ kaos: createFakeKaos() });
+    resumed.dispatch({
+      type: 'plan_mode.enter',
+      id: 'stable-plan',
+    });
+
+    expect(resumed.agent.planMode.planFilePath).toBe(livePath);
+  });
+
+  it('enters plan mode through the EnterPlanMode tool and reminds the next step', async () => {
+    const enterPlanModeCall: ToolCall = {
+      type: 'function',
+      id: 'call_enter_plan',
+      function: {
+        name: 'EnterPlanMode',
+        arguments: '{}',
+      },
+    };
+    const ctx = testAgent({
+      kaos: createPlanKaos({
+        writeText: vi.fn(async (_path: string, content: string) => content.length),
+      }),
+    });
+    ctx.configure({ tools: ['EnterPlanMode'] });
+    await ctx.rpc.setPermission({ mode: 'yolo' });
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will enter plan mode.' }, enterPlanModeCall);
+    ctx.mockNextResponse({ type: 'text', text: 'Plan mode is active now.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Plan first' }] });
+
+    await ctx.untilTurnEnd();
+    await delay(10);
+    expect(ctx.agent.planMode.isActive).toBe(true);
+    expect(ctx.llmCalls).toHaveLength(2);
+    expect(toolResultText(ctx.llmCalls[1]!.history)).toContain('Plan mode is now active');
+    await ctx.expectResumeMatches();
+  });
+});
+
+describe('plan clear', () => {
+  it('empties the current plan file without leaving plan mode', async () => {
+    const files = new Map<string, string>();
+    const mkdir = vi.fn().mockResolvedValue(undefined);
+    const readText = vi.fn(async (path: string) => files.get(path) ?? '');
+    const writeText = vi.fn(async (path: string, content: string) => {
+      files.set(path, content);
+      return content.length;
+    });
+
+    const ctx = testAgent({
+      kaos: createPlanKaos({ mkdir, readText, writeText }),
+    });
+    await ctx.agent.planMode.enter('test-plan', false);
+
+    const planPath = ctx.agent.planMode.planFilePath;
+    if (planPath === null) throw new Error('expected active plan path');
+    files.set(planPath, '# Plan\n\n- Step 1');
+
+    await ctx.rpc.clearPlan({});
+
+    expect(writeText).toHaveBeenCalledWith(planPath, '');
+    expect(files.get(planPath)).toBe('');
+    expect(ctx.agent.planMode.isActive).toBe(true);
+    expect(ctx.agent.planMode.planFilePath).toBe(planPath);
+    await expect(ctx.rpc.getPlan({})).resolves.toMatchObject({
+      id: 'test-plan',
+      content: '',
+      path: planPath,
+    });
+    await ctx.expectResumeMatches();
+  });
+});
+
+describe('plan exit tool', () => {
+  it('reads the current plan file and exits plan mode directly in auto mode', async () => {
+    const files = new Map<string, string>();
+    const readText = vi.fn(async (path: string) => files.get(path) ?? '');
+    const ctx = testAgent({
+      kaos: createPlanKaos({ readText }),
+    });
+    ctx.configure({ tools: ['ExitPlanMode'] });
+    await ctx.rpc.setPermission({ mode: 'auto' });
+    await ctx.agent.planMode.enter('test-plan', false);
+
+    const planPath = ctx.agent.planMode.planFilePath;
+    if (planPath === null) throw new Error('expected active plan path');
+    files.set(planPath, '# Plan\n\n- Inspect\n- Change\n- Verify');
+
+    const exitPlanModeCall: ToolCall = {
+      type: 'function',
+      id: 'call_exit_plan',
+      function: {
+        name: 'ExitPlanMode',
+        arguments: '{}',
+      },
+    };
+    ctx.mockNextResponse({ type: 'text', text: 'I will present the plan.' }, exitPlanModeCall);
+    ctx.mockNextResponse({ type: 'text', text: 'I can execute after approval.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Show the plan' }] });
+
+    await ctx.untilTurnEnd();
+    expect(
+      ctx.allEvents.some((event) => event.type === '[rpc]' && event.event === 'requestApproval'),
+    ).toBe(false);
+    expect(readText).toHaveBeenCalledWith(planPath);
+    expect(ctx.agent.planMode.isActive).toBe(false);
+    const llmInput = ctx.llmCalls[1]!;
+    expect(toolResultText(llmInput.history)).toContain('Plan mode deactivated');
+    expect(toolResultText(llmInput.history)).toContain('# Plan');
+    await ctx.expectResumeMatches();
+  });
+
+  it('stops the turn and stays in plan mode when the user rejects the plan', async () => {
+    const files = new Map<string, string>();
+    const readText = vi.fn(async (path: string) => files.get(path) ?? '');
+    const ctx = testAgent({
+      kaos: createPlanKaos({ readText }),
+    });
+    ctx.configure({ tools: ['ExitPlanMode'] });
+    await ctx.rpc.setPermission({ mode: 'manual' });
+    await ctx.agent.planMode.enter('reject-plan', false);
+
+    const planPath = ctx.agent.planMode.planFilePath;
+    if (planPath === null) throw new Error('expected active plan path');
+    files.set(planPath, '# Plan\n\n- Inspect\n- Change\n- Verify');
+
+    const exitPlanModeCall: ToolCall = {
+      type: 'function',
+      id: 'call_exit_reject',
+      function: {
+        name: 'ExitPlanMode',
+        arguments: '{}',
+      },
+    };
+    ctx.mockNextResponse({ type: 'text', text: 'I will present the plan.' }, exitPlanModeCall);
+    ctx.mockNextResponse({ type: 'text', text: 'This response must not be requested.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Show the plan' }] });
+
+    const approval = await ctx.takeApprovalRequest();
+    approval.respond({ decision: 'rejected', selectedLabel: 'Reject' });
+
+    await ctx.untilTurnEnd();
+    expect(readText).toHaveBeenCalledWith(planPath);
+    expect(ctx.agent.planMode.isActive).toBe(true);
+    expect(ctx.llmCalls).toHaveLength(1);
+    expect(toolResultText(ctx.agent.context.history)).toContain('Plan rejected by user');
+    await ctx.expectResumeMatches();
+  });
+
+  it('does not execute later tool calls in the same batch after plan rejection', async () => {
+    const files = new Map<string, string>();
+    const readText = vi.fn(async (path: string) => files.get(path) ?? '');
+    const execWithEnv = vi.fn(() => {
+      throw new Error('Bash should not execute after plan rejection');
+    });
+    const ctx = testAgent({
+      kaos: createPlanKaos({ readText, execWithEnv }),
+    });
+    ctx.configure({ tools: ['ExitPlanMode', 'Bash'] });
+    await ctx.rpc.setPermission({ mode: 'yolo' });
+    await ctx.agent.planMode.enter('reject-and-exit-plan', false);
+
+    const planPath = ctx.agent.planMode.planFilePath;
+    if (planPath === null) throw new Error('expected active plan path');
+    files.set(planPath, '# Plan\n\n- Inspect\n- Change\n- Verify');
+
+    const exitPlanModeCall: ToolCall = {
+      type: 'function',
+      id: 'call_exit_reject_and_exit',
+      function: {
+        name: 'ExitPlanMode',
+        arguments: '{}',
+      },
+    };
+    const bashCall: ToolCall = {
+      type: 'function',
+      id: 'call_bash_after_reject',
+      function: {
+        name: 'Bash',
+        arguments: '{"command":"touch should-not-run","timeout":60}',
+      },
+    };
+    ctx.mockNextResponse(
+      { type: 'text', text: 'I will present the plan and then run a command.' },
+      exitPlanModeCall,
+      bashCall,
+    );
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Show the plan' }] });
+
+    const approval = await ctx.takeApprovalRequest();
+    approval.respond({ decision: 'rejected', selectedLabel: 'Reject' });
+
+    await ctx.untilTurnEnd();
+    expect(ctx.agent.planMode.isActive).toBe(true);
+    expect(execWithEnv).not.toHaveBeenCalled();
+    expect(ctx.llmCalls).toHaveLength(1);
+    expect(toolResultText(ctx.agent.context.history)).toContain('Plan rejected by user');
+    expect(toolResultText(ctx.agent.context.history)).toContain(
+      'Tool skipped because a previous tool call stopped the turn.',
+    );
+    await ctx.expectResumeMatches();
+  });
+
+  it('refuses to exit when the current plan file is empty', async () => {
+    const readText = vi.fn(async () => '');
+    const ctx = testAgent({
+      kaos: createPlanKaos({ readText }),
+    });
+    ctx.configure({ tools: ['ExitPlanMode'] });
+    await ctx.rpc.setPermission({ mode: 'yolo' });
+    await ctx.agent.planMode.enter('empty-plan', false);
+
+    const exitPlanModeCall: ToolCall = {
+      type: 'function',
+      id: 'call_exit_empty_plan',
+      function: {
+        name: 'ExitPlanMode',
+        arguments: '{}',
+      },
+    };
+    ctx.mockNextResponse(
+      { type: 'text', text: 'I will present the empty plan.' },
+      exitPlanModeCall,
+    );
+    ctx.mockNextResponse({ type: 'text', text: 'I need to write the plan first.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Show an empty plan' }] });
+
+    await ctx.untilTurnEnd();
+    expect(ctx.agent.planMode.isActive).toBe(true);
+    expect(toolResultText(ctx.llmCalls[1]!.history)).toContain('No plan file found');
+    await ctx.expectResumeMatches();
+  });
+});
+
+describe('plan exit tool options', () => {
+  it('keeps options for approval when an option omits the optional description', async () => {
+    const files = new Map<string, string>();
+    const readText = vi.fn(async (path: string) => files.get(path) ?? '');
+    const ctx = testAgent({
+      kaos: createPlanKaos({ readText }),
+    });
+    ctx.configure({ tools: ['ExitPlanMode'] });
+    await ctx.rpc.setPermission({ mode: 'manual' });
+    await ctx.agent.planMode.enter('options-plan', false);
+
+    const planPath = ctx.agent.planMode.planFilePath;
+    if (planPath === null) throw new Error('expected active plan path');
+    files.set(planPath, '# Plan\n\n- Inspect\n- Change\n- Verify');
+
+    const exitPlanModeCall: ToolCall = {
+      type: 'function',
+      id: 'call_exit_options',
+      function: {
+        name: 'ExitPlanMode',
+        // The second option omits `description` — valid input after the
+        // schema relaxation. The approval policy must still surface both.
+        arguments: JSON.stringify({
+          options: [
+            { label: 'Approach A', description: 'Smaller refactor.' },
+            { label: 'Approach B' },
+          ],
+        }),
+      },
+    };
+    ctx.mockNextResponse({ type: 'text', text: 'I will present the plan.' }, exitPlanModeCall);
+    ctx.mockNextResponse({ type: 'text', text: 'I can execute after approval.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Show the plan' }] });
+
+    const approval = await ctx.takeApprovalRequest();
+    const rpcArgs = (
+      ctx.allEvents.find(
+        (event) => event.type === '[rpc]' && event.event === 'requestApproval',
+      ) as { args: { action?: string; display?: { options?: readonly unknown[] } } } | undefined
+    )?.args;
+
+    expect(rpcArgs?.action).toBe('Review plan and choose an option');
+    expect(rpcArgs?.display?.options).toHaveLength(2);
+
+    approval.respond({ decision: 'approved', selectedLabel: 'Approach A' });
+    await ctx.untilTurnEnd();
+  });
+});
+
+describe('plan allows safe tool flow', () => {
+  it.each(['Write', 'Edit'] as const)(
+    'runs %s on the active plan file without approval in manual mode',
+    async (toolName) => {
+      const files = new Map<string, string>();
+      const readText = vi.fn(async (path: string) => files.get(path) ?? '');
+      const writeText = vi.fn(async (path: string, content: string) => {
+        files.set(path, content);
+        return content.length;
+      });
+      const ctx = testAgent({
+        kaos: createPlanKaos({ readText, writeText }),
+      });
+      ctx.configure({ tools: [toolName] });
+      await ctx.agent.planMode.enter('test-plan', false);
+
+      const planPath = ctx.agent.planMode.planFilePath;
+      if (planPath === null) throw new Error('expected active plan path');
+      files.set(planPath, '# Plan\n\n- Draft');
+
+      const expectedContent =
+        toolName === 'Write' ? '# Plan\n\n- Inspect\n- Verify' : '# Plan\n\n- Draft\n- Verify';
+      const args =
+        toolName === 'Write'
+          ? { path: planPath, content: expectedContent }
+          : { path: planPath, old_string: '- Draft', new_string: '- Draft\n- Verify' };
+      const writePlanCall: ToolCall = {
+        type: 'function',
+        id: `call_${toolName.toLowerCase()}_plan`,
+        function: {
+          name: toolName,
+          arguments: JSON.stringify(args),
+        },
+      };
+
+      ctx.mockNextResponse({ type: 'text', text: 'I will update the plan file.' }, writePlanCall);
+      ctx.mockNextResponse({ type: 'text', text: 'Plan file updated.' });
+      await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Update the plan file' }] });
+
+      await ctx.untilTurnEnd();
+
+      expect(files.get(planPath)).toBe(expectedContent);
+      expect(writeText).toHaveBeenCalledWith(planPath, expectedContent);
+      expect(
+        ctx.allEvents.some((event) => event.type === '[rpc]' && event.event === 'requestApproval'),
+      ).toBe(false);
+      await ctx.expectResumeMatches();
+    },
+  );
+
+  it('keeps explicit deny rules above active plan file writes', async () => {
+    const files = new Map<string, string>();
+    const writeText = vi.fn(async (path: string, content: string) => {
+      files.set(path, content);
+      return content.length;
+    });
+    const ctx = testAgent({
+      kaos: createPlanKaos({ writeText }),
+    });
+    ctx.configure({ tools: ['Write'] });
+    ctx.agent.permission.rules.push({
+      decision: 'deny',
+      scope: 'user',
+      pattern: 'Write',
+      reason: 'blocked by test',
+    });
+    await ctx.agent.planMode.enter('test-plan', false);
+
+    const planPath = ctx.agent.planMode.planFilePath;
+    if (planPath === null) throw new Error('expected active plan path');
+    const content = '# Plan\n\n- Inspect\n- Verify';
+    const writePlanCall: ToolCall = {
+      type: 'function',
+      id: 'call_write_plan_with_deny',
+      function: {
+        name: 'Write',
+        arguments: JSON.stringify({ path: planPath, content }),
+      },
+    };
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will update the plan file.' }, writePlanCall);
+    ctx.mockNextResponse({ type: 'text', text: 'Plan file updated.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Update the plan file' }] });
+
+    await ctx.untilTurnEnd();
+
+    expect(files.get(planPath)).toBeUndefined();
+    expect(writeText).not.toHaveBeenCalled();
+    expect(toolResultText(ctx.agent.context.history)).toContain(
+      'Tool "Write" was denied by permission rule. Reason: blocked by test',
+    );
+    expect(
+      ctx.allEvents.some((event) => event.type === '[rpc]' && event.event === 'requestApproval'),
+    ).toBe(false);
+  });
+
+  it('allows read-only Bash to continue through permission and execution', async () => {
+    const bashCall: ToolCall = {
+      type: 'function',
+      id: 'call_bash',
+      function: {
+        name: 'Bash',
+        arguments: '{"command":"printf plan-safe","timeout":60}',
+      },
+    };
+    const ctx = testAgent({ kaos: createCommandKaos('plan-safe') });
+    ctx.configure({ tools: ['Bash'] });
+    await ctx.rpc.setPermission({ mode: 'yolo' });
+    await ctx.agent.planMode.enter('test-plan', false);
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will inspect safely.' }, bashCall);
+    ctx.mockNextResponse({ type: 'text', text: 'The safe command printed plan-safe.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Inspect without mutating files' }] });
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] permission.set_mode         { "mode": "yolo", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 0, "maxContextTokens": 1000000, "contextUsage": 0, "planMode": false, "permission": "yolo" }
+      [wire] plan_mode.enter             { "id": "test-plan", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 0, "maxContextTokens": 1000000, "contextUsage": 0, "planMode": true, "permission": "yolo" }
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Inspect without mutating files" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Inspect without mutating files" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "<plan-mode-reminder>" } ], "toolCalls": [], "origin": { "kind": "injection", "variant": "plan_mode" } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "I will inspect safely." }
+      [emit] tool.call.delta             { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "argumentsPart": "{\\"command\\":\\"printf plan-safe\\",\\"timeout\\":60}" }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "I will inspect safely." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "tool.call", "uuid": "call_bash", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf plan-safe", "timeout": 60 }, "description": "Running: printf plan-safe" }, "time": "<time>" }
+      [emit] tool.call.started           { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf plan-safe", "timeout": 60 }, "description": "Running: printf plan-safe" }
+      [wire] context.append_loop_event   { "event": { "type": "tool.result", "parentUuid": "call_bash", "toolCallId": "call_bash", "result": { "output": "plan-safe" } }, "time": "<time>" }
+      [emit] tool.result                 { "turnId": 0, "toolCallId": "call_bash", "output": "plan-safe" }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "usage": { "inputOther": 536, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 0, "step": 1, "stepId": "<uuid-1>", "usage": { "inputOther": 536, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }
+      [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 536, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 559, "maxContextTokens": 1000000, "contextUsage": 0.000559, "planMode": true, "permission": "yolo", "usage": { "byModel": { "mock-model": { "inputOther": 536, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 536, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 536, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-3>", "turnId": "0", "step": 2 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 2, "stepId": "<uuid-3>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "The safe command printed plan-safe." }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "stepUuid": "<uuid-3>", "part": { "type": "text", "text": "The safe command printed plan-safe." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-3>", "turnId": "0", "step": 2, "usage": { "inputOther": 563, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 0, "step": 2, "stepId": "<uuid-3>", "usage": { "inputOther": 563, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+      [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 563, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 575, "maxContextTokens": 1000000, "contextUsage": 0.000575, "planMode": true, "permission": "yolo", "usage": { "byModel": { "mock-model": { "inputOther": 1099, "output": 35, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 1099, "output": 35, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 1099, "output": 35, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [emit] turn.ended                  { "turnId": 0, "reason": "completed" }
+    `);
+    await ctx.expectResumeMatches();
+  });
+});
+
+describe('plan mode Bash ordinary permission behavior', () => {
+  it('allows Bash through ordinary yolo permission behavior', async () => {
+    const bashCall: ToolCall = {
+      type: 'function',
+      id: 'call_bash',
+      function: {
+        name: 'Bash',
+        arguments: '{"command":"rm forbidden.txt","timeout":60}',
+      },
+    };
+    const ctx = testAgent({ kaos: createCommandKaos('removed') });
+    ctx.configure({ tools: ['Bash'] });
+    await ctx.rpc.setPermission({ mode: 'yolo' });
+    await ctx.agent.planMode.enter('test-plan', false);
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will mutate a file.' }, bashCall);
+    ctx.mockNextResponse({ type: 'text', text: 'The command completed.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Remove forbidden.txt' }] });
+
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] permission.set_mode         { "mode": "yolo", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 0, "maxContextTokens": 1000000, "contextUsage": 0, "planMode": false, "permission": "yolo" }
+      [wire] plan_mode.enter             { "id": "test-plan", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 0, "maxContextTokens": 1000000, "contextUsage": 0, "planMode": true, "permission": "yolo" }
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Remove forbidden.txt" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Remove forbidden.txt" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "<plan-mode-reminder>" } ], "toolCalls": [], "origin": { "kind": "injection", "variant": "plan_mode" } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "I will mutate a file." }
+      [emit] tool.call.delta             { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "argumentsPart": "{\\"command\\":\\"rm forbidden.txt\\",\\"timeout\\":60}" }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "I will mutate a file." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "tool.call", "uuid": "call_bash", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "toolCallId": "call_bash", "name": "Bash", "args": { "command": "rm forbidden.txt", "timeout": 60 }, "description": "Running: rm forbidden.txt" }, "time": "<time>" }
+      [emit] tool.call.started           { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "args": { "command": "rm forbidden.txt", "timeout": 60 }, "description": "Running: rm forbidden.txt" }
+      [wire] context.append_loop_event   { "event": { "type": "tool.result", "parentUuid": "call_bash", "toolCallId": "call_bash", "result": { "output": "removed" } }, "time": "<time>" }
+      [emit] tool.result                 { "turnId": 0, "toolCallId": "call_bash", "output": "removed" }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "usage": { "inputOther": 533, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 0, "step": 1, "stepId": "<uuid-1>", "usage": { "inputOther": 533, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }
+      [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 533, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 556, "maxContextTokens": 1000000, "contextUsage": 0.000556, "planMode": true, "permission": "yolo", "usage": { "byModel": { "mock-model": { "inputOther": 533, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 533, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 533, "output": 23, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-3>", "turnId": "0", "step": 2 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 2, "stepId": "<uuid-3>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "The command completed." }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "stepUuid": "<uuid-3>", "part": { "type": "text", "text": "The command completed." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-3>", "turnId": "0", "step": 2, "usage": { "inputOther": 559, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 0, "step": 2, "stepId": "<uuid-3>", "usage": { "inputOther": 559, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+      [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 559, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 568, "maxContextTokens": 1000000, "contextUsage": 0.000568, "planMode": true, "permission": "yolo", "usage": { "byModel": { "mock-model": { "inputOther": 1092, "output": 32, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 1092, "output": 32, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 1092, "output": 32, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [emit] turn.ended                  { "turnId": 0, "reason": "completed" }
+    `);
+    expect(toolResultText(ctx.agent.context.history)).toContain('removed');
+    await ctx.expectResumeMatches();
+  });
+});
+
+describe('plan mode injection cadence', () => {
+  it('dedupes immediate repeats and emits sparse reminders after assistant turns', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+    await ctx.agent.planMode.enter('test-plan', false);
+
+    await ctx.agent.injection.inject();
+    const afterFull = ctx.agent.context.history.length;
+    expect(lastUserText(ctx.agent.context.history)).toContain('Plan mode is active');
+    expect(lastUserText(ctx.agent.context.history)).toContain('Plan file:');
+
+    await ctx.agent.injection.inject();
+    expect(ctx.agent.context.history).toHaveLength(afterFull);
+
+    appendAssistantTurn(ctx, 1, 'assistant one');
+    appendAssistantTurn(ctx, 2, 'assistant two');
+    await ctx.agent.injection.inject();
+
+    expect(lastUserText(ctx.agent.context.history)).toContain('Plan mode still active');
+    expect(lastUserText(ctx.agent.context.history)).toContain('Plan file:');
+    await ctx.expectResumeMatches();
+  });
+
+  it('emits a reentry reminder when restored plan mode already has plan content', async () => {
+    const ctx = testAgent({
+      kaos: createFakeKaos({
+        readText: vi.fn(async () => '# Existing Plan\n\n- Keep this context'),
+      }),
+    });
+    ctx.configure();
+    ctx.dispatch({
+      type: 'plan_mode.enter',
+      id: 'restored-plan',
+    });
+
+    await ctx.agent.injection.inject();
+
+    expect(lastUserText(ctx.agent.context.history)).toContain('Re-entering Plan Mode');
+    expect(lastUserText(ctx.agent.context.history)).toContain('Read the existing plan file');
+    await ctx.expectResumeMatches();
+  });
+
+  it('emits one exit reminder after leaving plan mode', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+    await ctx.agent.planMode.enter('test-plan', false);
+    await ctx.agent.injection.inject();
+
+    ctx.agent.planMode.exit();
+    await ctx.agent.injection.inject();
+    const afterExit = ctx.agent.context.history.length;
+    expect(lastUserText(ctx.agent.context.history)).toContain('Plan mode is no longer active');
+
+    await ctx.agent.injection.inject();
+    expect(ctx.agent.context.history).toHaveLength(afterExit);
+    await ctx.expectResumeMatches();
+  });
+});
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function appendAssistantTurn(ctx: ReturnType<typeof testAgent>, step: number, text: string): void {
+  const stepUuid = `plan-injection-step-${String(step)}`;
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: { type: 'step.begin', uuid: stepUuid, turnId: '', step },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'content.part',
+      uuid: `plan-injection-part-${String(step)}`,
+      turnId: '',
+      step,
+      stepUuid,
+      part: { type: 'text', text },
+    },
+  });
+  ctx.dispatch({
+    type: 'context.append_loop_event',
+    event: {
+      type: 'step.end',
+      uuid: stepUuid,
+      turnId: '',
+      step,
+      finishReason: 'end_turn',
+    },
+  });
+}
+
+function lastUserText(history: readonly { role: string; content: readonly unknown[] }[]): string {
+  const message = history.findLast((item) => item.role === 'user');
+  if (message === undefined) return '';
+  return message.content
+    .map((part) => {
+      if (
+        part !== null &&
+        typeof part === 'object' &&
+        (part as { type?: unknown }).type === 'text'
+      ) {
+        const text = (part as { text?: unknown }).text;
+        return typeof text === 'string' ? text : '';
+      }
+      return '';
+    })
+    .join('');
+}
+
+function toolResultText(history: readonly { role: string; content: readonly unknown[] }[]): string {
+  return history
+    .filter((message) => message.role === 'tool')
+    .flatMap((message) => message.content)
+    .map((part) => {
+      if (
+        part !== null &&
+        typeof part === 'object' &&
+        (part as { type?: unknown }).type === 'text'
+      ) {
+        const text = (part as { text?: unknown }).text;
+        return typeof text === 'string' ? text : '';
+      }
+      return '';
+    })
+    .join('\n');
+}
diff --git a/packages/agent-core/test/agent/question.test.ts b/packages/agent-core/test/agent/question.test.ts
new file mode 100644
index 000000000..8ad46776d
--- /dev/null
+++ b/packages/agent-core/test/agent/question.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+
+import { testAgent } from './harness/agent';
+
+describe('Agent question', () => {
+  it('roundtrips a question request through wire rpc', async () => {
+    const ctx = testAgent();
+
+    const resultPromise = ctx.agent.rpc.requestQuestion(
+      {
+        questions: [
+          {
+            question: 'Pick one',
+            options: [{ label: 'Yes' }, { label: 'No' }],
+          },
+        ],
+      },
+      { signal: new AbortController().signal },
+    );
+
+    expect(await ctx.untilQuestion({ Yes: true })).toMatchInlineSnapshot(
+      `[emit] requestQuestion   { "questions": [ { "question": "Pick one", "options": [ { "label": "Yes" }, { "label": "No" } ] } ] }`,
+    );
+
+    await expect(resultPromise).resolves.toEqual({ Yes: true });
+    await ctx.expectResumeMatches();
+  });
+
+  it('sends multiple questions in one request', async () => {
+    const ctx = testAgent();
+
+    const resultPromise = ctx.agent.rpc.requestQuestion(
+      {
+        questions: [
+          {
+            question: 'Pick one',
+            options: [{ label: 'Yes' }, { label: 'No' }],
+          },
+          {
+            question: 'Pick storage',
+            options: [{ label: 'Postgres' }, { label: 'SQLite' }],
+          },
+        ],
+      },
+      { signal: new AbortController().signal },
+    );
+
+    expect(
+      await ctx.untilQuestion({ Yes: true, 'Pick storage': 'Postgres' }),
+    ).toMatchInlineSnapshot(
+      `[emit] requestQuestion   { "questions": [ { "question": "Pick one", "options": [ { "label": "Yes" }, { "label": "No" } ] }, { "question": "Pick storage", "options": [ { "label": "Postgres" }, { "label": "SQLite" } ] } ] }`,
+    );
+
+    await expect(resultPromise).resolves.toEqual({ Yes: true, 'Pick storage': 'Postgres' });
+    await ctx.expectResumeMatches();
+  });
+});
diff --git a/packages/agent-core/test/agent/resume.test.ts b/packages/agent-core/test/agent/resume.test.ts
new file mode 100644
index 000000000..c75a283fc
--- /dev/null
+++ b/packages/agent-core/test/agent/resume.test.ts
@@ -0,0 +1,543 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import type { AgentRecord, AgentRecordPersistence } from '../../src/agent';
+import { appendTaskOutput, writeTask } from '../../src/tools/background/persist';
+import { createFakeKaos } from '../tools/fixtures/fake-kaos';
+import { testAgent } from './harness/agent';
+import { DEFAULT_TEST_SYSTEM_PROMPT } from './harness/snapshots';
+
+const MOCK_PROVIDER = {
+  type: 'kimi',
+  apiKey: 'test-key',
+  model: 'mock-model',
+} as const;
+
+describe('Agent resume', () => {
+  it('replays persisted records without restarting turns, compactions, plan turns, or tools', async () => {
+    const persistence = new RecordingAgentPersistence(resumeHistory());
+    const execWithEnv = vi.fn().mockRejectedValue(new Error('Bash should not execute on resume'));
+    const ctx = testAgent({
+      kaos: createFakeKaos({ execWithEnv }),
+      persistence,
+    });
+
+    await ctx.agent.resume();
+
+    expect(ctx.agent.planMode.isActive).toBe(true);
+    expect(ctx.agent.planMode.planFilePath).toContain('resume-plan');
+    expect(ctx.newEvents()).toMatchInlineSnapshot(`[]`);
+    expect(ctx.llmCalls).toHaveLength(0);
+    expect(execWithEnv).not.toHaveBeenCalled();
+    expect(persistence.appended).toEqual([]);
+    await ctx.expectResumeMatches();
+
+    ctx.mockNextResponse({ type: 'text', text: 'Fresh response after resume.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Fresh prompt after resume' }] });
+    await ctx.untilTurnEnd();
+
+    expect(findRpcEvent(ctx.allEvents, 'turn.started')?.args).toMatchObject({
+      turnId: 1,
+    });
+    expect(findRpcEvent(ctx.allEvents, 'turn.ended')?.args).toMatchObject({
+      turnId: 1,
+      reason: 'completed',
+    });
+    expect(findRpcEvent(ctx.allEvents, 'error')).toBeUndefined();
+    expect(execWithEnv).not.toHaveBeenCalled();
+    expect(ctx.llmInputs()).toMatchInlineSnapshot(`
+      call 1:
+        system: <system-prompt>
+        tools: Bash
+        messages:
+          assistant: text "Historical compacted summary."
+          user: text "Fresh prompt after resume"
+          user: text <plan-mode-reminder>
+    `);
+  });
+
+  it('replays inline skill reminders after pending tool results before the next prompt', async () => {
+    const persistence = new RecordingAgentPersistence(resumeDeferredSystemReminderHistory());
+    const ctx = testAgent({ persistence });
+
+    await ctx.agent.resume();
+
+    expect(ctx.agent.context.messages.map((message) => message.role)).toEqual([
+      'user',
+      'assistant',
+      'tool',
+      'tool',
+      'user',
+    ]);
+    expect(ctx.agent.context.messages[4]?.content).toEqual([
+      {
+        type: 'text',
+        text: '<system-reminder>\nresume skill body\n</system-reminder>',
+      },
+    ]);
+
+    ctx.mockNextResponse({ type: 'text', text: 'Fresh response after deferred resume.' });
+    await ctx.rpc.prompt({
+      input: [{ type: 'text', text: 'Fresh prompt after deferred resume' }],
+    });
+    await ctx.untilTurnEnd();
+
+    expect(ctx.llmInputs()).toMatchInlineSnapshot(`
+      call 1:
+        system: <system-prompt>
+        tools: []
+        messages:
+          user: text "Historical prompt before skill"
+          assistant: []  calls call_resume_write:Write { "path": "result.txt" }, call_resume_skill:Skill { "skill": "review" }
+          tool[call_resume_write]: text "wrote file"
+          tool[call_resume_skill]: text "skill loaded"
+          user: text "<system-reminder>\\nresume skill body\\n</system-reminder>"
+          user: text "Fresh prompt after deferred resume"
+    `);
+    await ctx.expectResumeMatches();
+  });
+
+  it('restores tool store state from persisted records', async () => {
+    const persistence = new RecordingAgentPersistence([
+      {
+        type: 'tools.update_store',
+        key: 'todo',
+        value: [
+          { title: 'Inspect resume snapshot', status: 'done' },
+          { title: 'Hydrate TUI todo panel', status: 'in_progress' },
+        ],
+      },
+    ]);
+    const ctx = testAgent({ persistence });
+
+    await ctx.agent.resume();
+
+    expect(ctx.agent.tools.storeData()).toEqual({
+      todo: [
+        { title: 'Inspect resume snapshot', status: 'done' },
+        { title: 'Hydrate TUI todo panel', status: 'in_progress' },
+      ],
+    });
+    await ctx.expectResumeMatches();
+  });
+
+  it('keeps delivered background notifications indexed after compaction replay', async () => {
+    const origin = {
+      kind: 'background_task',
+      taskId: 'agent-seen0000',
+      status: 'completed',
+      notificationId: 'task:agent-seen0000:completed',
+    } as const;
+    const persistence = new RecordingAgentPersistence([
+      {
+        type: 'context.append_message',
+        message: {
+          role: 'user',
+          content: [{ type: 'text', text: 'already delivered background notification' }],
+          toolCalls: [],
+          origin,
+        },
+      },
+      {
+        type: 'context.apply_compaction',
+        summary: 'Compacted delivered notification.',
+        compactedCount: 1,
+        tokensBefore: 10,
+        tokensAfter: 3,
+      },
+    ]);
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-resume-delivered-'));
+    try {
+      const ctx = testAgent({ persistence });
+      ctx.agent.background.attachSessionDir(sessionDir);
+      await writeTask(sessionDir, {
+        task_id: 'agent-seen0000',
+        command: '[agent] already delivered',
+        description: 'already delivered',
+        pid: 0,
+        started_at: 1_700_000_000,
+        ended_at: 1_700_000_010,
+        exit_code: 0,
+        status: 'completed',
+      });
+      await appendTaskOutput(sessionDir, 'agent-seen0000', 'already delivered summary');
+      const steer = vi.spyOn(ctx.agent.turn, 'steer');
+
+      await ctx.agent.resume();
+      expect(
+        ctx.agent.context.history.some((message) => message.origin?.kind === 'background_task'),
+      ).toBe(false);
+
+      await ctx.agent.background.loadFromDisk();
+      await ctx.agent.background.reconcile();
+
+      expect(steer).not.toHaveBeenCalled();
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('persists undelivered restored background notifications during resume', async () => {
+    const persistence = new RecordingAgentPersistence([
+      {
+        type: 'turn.prompt',
+        input: [{ type: 'text', text: 'Historical prompt' }],
+        origin: { kind: 'user' },
+      },
+    ]);
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-resume-undelivered-'));
+    try {
+      const ctx = testAgent({ persistence });
+      ctx.agent.background.attachSessionDir(sessionDir);
+      await writeTask(sessionDir, {
+        task_id: 'agent-new00000',
+        command: '[agent] newly delivered',
+        description: 'newly delivered',
+        pid: 0,
+        started_at: 1_700_000_000,
+        ended_at: 1_700_000_010,
+        exit_code: 0,
+        status: 'completed',
+      });
+      await appendTaskOutput(sessionDir, 'agent-new00000', 'newly delivered summary');
+      const steer = vi.spyOn(ctx.agent.turn, 'steer');
+
+      await ctx.agent.resume();
+
+      expect(steer).not.toHaveBeenCalled();
+      expect(
+        ctx.agent.context.history.some(
+          (message) =>
+            message.origin?.kind === 'background_task' &&
+            message.origin.taskId === 'agent-new00000',
+        ),
+      ).toBe(true);
+      expect(persistence.appended).toContainEqual(
+        expect.objectContaining({
+          type: 'context.append_message',
+          message: expect.objectContaining({
+            origin: {
+              kind: 'background_task',
+              taskId: 'agent-new00000',
+              status: 'completed',
+              notificationId: 'task:agent-new00000:completed',
+            },
+          }),
+        }),
+      );
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('preserves failed tool result state in replay messages', async () => {
+    const persistence = new RecordingAgentPersistence([
+      {
+        type: 'context.append_loop_event',
+        event: {
+          type: 'step.begin',
+          uuid: 'failed-step',
+          turnId: '0',
+          step: 1,
+        },
+      },
+      {
+        type: 'context.append_loop_event',
+        event: {
+          type: 'tool.call',
+          uuid: 'failed-call',
+          turnId: '0',
+          step: 1,
+          stepUuid: 'failed-step',
+          toolCallId: 'call_failed_bash',
+          name: 'Bash',
+          args: { command: 'false' },
+        },
+      },
+      {
+        type: 'context.append_loop_event',
+        event: {
+          type: 'tool.result',
+          parentUuid: 'failed-call',
+          toolCallId: 'call_failed_bash',
+          result: { output: 'failed', isError: true },
+        },
+      },
+    ]);
+    const ctx = testAgent({ persistence });
+
+    await ctx.agent.resume();
+
+    expect(ctx.agent.replayBuilder.buildResult()).toContainEqual({
+      type: 'message',
+      message: expect.objectContaining({
+        role: 'tool',
+        toolCallId: 'call_failed_bash',
+        isError: true,
+      }),
+    });
+  });
+});
+
+class RecordingAgentPersistence implements AgentRecordPersistence {
+  readonly appended: AgentRecord[] = [];
+
+  constructor(private readonly events: readonly AgentRecord[]) {}
+
+  async *read(): AsyncIterable<AgentRecord> {
+    for (const event of this.events) {
+      yield event;
+    }
+  }
+
+  async append(input: AgentRecord): Promise<void> {
+    this.appended.push(input);
+  }
+
+  async flush(): Promise<void> {}
+
+  async close(): Promise<void> {}
+}
+
+function resumeHistory(): AgentRecord[] {
+  return [
+    {
+      type: 'config.update',
+      cwd: process.cwd(),
+      modelAlias: MOCK_PROVIDER.model,
+      systemPrompt: DEFAULT_TEST_SYSTEM_PROMPT,
+      thinkingLevel: 'off',
+    },
+    {
+      type: 'tools.set_active_tools',
+      names: ['Bash'],
+    },
+    {
+      type: 'permission.set_mode',
+      mode: 'yolo',
+    },
+    {
+      type: 'turn.prompt',
+      input: [{ type: 'text', text: 'Historical prompt' }],
+      origin: { kind: 'user' },
+    },
+    {
+      type: 'context.append_message',
+      message: {
+        role: 'user',
+        content: [{ type: 'text', text: 'Historical prompt' }],
+        toolCalls: [],
+        origin: { kind: 'user' },
+      },
+    },
+    {
+      type: 'context.append_loop_event',
+      event: {
+        type: 'step.begin',
+        uuid: 'resume-step',
+        turnId: '0',
+        step: 1,
+      },
+    },
+    {
+      type: 'context.append_loop_event',
+      event: {
+        type: 'content.part',
+        uuid: 'resume-content',
+        turnId: '0',
+        step: 1,
+        stepUuid: 'resume-step',
+        part: { type: 'text', text: 'Historical assistant text.' },
+      },
+    },
+    {
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.call',
+        uuid: 'resume-tool-call',
+        turnId: '0',
+        step: 1,
+        stepUuid: 'resume-step',
+        toolCallId: 'call_resume_bash',
+        name: 'Bash',
+        args: { command: 'printf should-not-rerun', timeout: 60 },
+      },
+    },
+    {
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.result',
+        parentUuid: 'resume-tool-call',
+        toolCallId: 'call_resume_bash',
+        result: { output: 'already ran' },
+      },
+    },
+    {
+      type: 'context.append_loop_event',
+      event: {
+        type: 'step.end',
+        uuid: 'resume-step',
+        turnId: '0',
+        step: 1,
+        usage: {
+          inputOther: 10,
+          output: 2,
+          inputCacheRead: 0,
+          inputCacheCreation: 0,
+        },
+        finishReason: 'tool_use',
+      },
+    },
+    {
+      type: 'usage.record',
+      model: 'mock-model',
+      usage: {
+        inputOther: 10,
+        output: 2,
+        inputCacheRead: 0,
+        inputCacheCreation: 0,
+      },
+    },
+    {
+      type: 'full_compaction.begin',
+      source: 'auto',
+    },
+    {
+      type: 'full_compaction.complete',
+      summary: 'Historical compacted summary.',
+      compactedCount: 3,
+      tokensBefore: 12,
+      tokensAfter: 4,
+    },
+    {
+      type: 'context.apply_compaction',
+      summary: 'Historical compacted summary.',
+      compactedCount: 3,
+      tokensBefore: 12,
+      tokensAfter: 4,
+    },
+    {
+      type: 'plan_mode.enter',
+      id: 'resume-plan',
+    },
+  ];
+}
+
+function resumeDeferredSystemReminderHistory(): AgentRecord[] {
+  return [
+    {
+      type: 'config.update',
+      cwd: process.cwd(),
+      modelAlias: MOCK_PROVIDER.model,
+      systemPrompt: DEFAULT_TEST_SYSTEM_PROMPT,
+      thinkingLevel: 'off',
+    },
+    {
+      type: 'context.append_message',
+      message: {
+        role: 'user',
+        content: [{ type: 'text', text: 'Historical prompt before skill' }],
+        toolCalls: [],
+        origin: { kind: 'user' },
+      },
+    },
+    {
+      type: 'context.append_loop_event',
+      event: {
+        type: 'step.begin',
+        uuid: 'resume-skill-step',
+        turnId: '0',
+        step: 1,
+      },
+    },
+    {
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.call',
+        uuid: 'call_resume_write',
+        turnId: '0',
+        step: 1,
+        stepUuid: 'resume-skill-step',
+        toolCallId: 'call_resume_write',
+        name: 'Write',
+        args: { path: 'result.txt' },
+      },
+    },
+    {
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.call',
+        uuid: 'call_resume_skill',
+        turnId: '0',
+        step: 1,
+        stepUuid: 'resume-skill-step',
+        toolCallId: 'call_resume_skill',
+        name: 'Skill',
+        args: { skill: 'review' },
+      },
+    },
+    {
+      type: 'context.append_message',
+      message: {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: '<system-reminder>\nresume skill body\n</system-reminder>',
+          },
+        ],
+        toolCalls: [],
+        origin: {
+          kind: 'skill_activation',
+          activationId: 'act_resume_skill',
+          skillName: 'review',
+          trigger: 'model-tool',
+        },
+      },
+    },
+    {
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.result',
+        parentUuid: 'call_resume_write',
+        toolCallId: 'call_resume_write',
+        result: { output: 'wrote file' },
+      },
+    },
+    {
+      type: 'context.append_loop_event',
+      event: {
+        type: 'tool.result',
+        parentUuid: 'call_resume_skill',
+        toolCallId: 'call_resume_skill',
+        result: { output: 'skill loaded' },
+      },
+    },
+    {
+      type: 'context.append_loop_event',
+      event: {
+        type: 'step.end',
+        uuid: 'resume-skill-step',
+        turnId: '0',
+        step: 1,
+        usage: {
+          inputOther: 10,
+          output: 2,
+          inputCacheRead: 0,
+          inputCacheCreation: 0,
+        },
+        finishReason: 'tool_use',
+      },
+    },
+  ];
+}
+
+function findRpcEvent(
+  ctxEvents: readonly { type: string; event: string; args: unknown }[],
+  event: string,
+) {
+  return ctxEvents.find((entry) => entry.type === '[rpc]' && entry.event === event);
+}
diff --git a/packages/agent-core/test/agent/skill-tool-manager.test.ts b/packages/agent-core/test/agent/skill-tool-manager.test.ts
new file mode 100644
index 000000000..7fadfff16
--- /dev/null
+++ b/packages/agent-core/test/agent/skill-tool-manager.test.ts
@@ -0,0 +1,216 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { localKaos } from '@moonshot-ai/kaos';
+import { describe, expect, it, vi } from 'vitest';
+
+import { Agent } from '../../src/agent';
+import { ProviderManager } from '../../src/providers/provider-manager';
+import type { ApprovalResponse, SDKAgentRPC, SDKSessionRPC } from '../../src/rpc';
+import { Session } from '../../src/session';
+import { SkillRegistry, type SkillDefinition } from '../../src/skill';
+import { SkillTool } from '../../src/tools/builtin/collaboration/skill-tool';
+import type { Environment } from '../../src/utils/environment';
+import { executeTool } from '../tools/fixtures/execute-tool';
+
+const TEST_OS_ENV: Environment = {
+  osKind: 'Linux',
+  osArch: 'x86_64',
+  osVersion: 'test',
+  shellName: 'bash',
+  shellPath: '/bin/bash',
+};
+
+const MOCK_PROVIDER = {
+  type: 'kimi',
+  apiKey: 'test-key',
+  model: 'mock-model',
+} as const;
+
+function makeSkill(name: string, metadata: SkillDefinition['metadata'] = {}): SkillDefinition {
+  return {
+    name,
+    description: `desc for ${name}`,
+    path: `/skills/${name}/SKILL.md`,
+    dir: `/skills/${name}`,
+    content: `body of ${name}`,
+    metadata,
+    source: 'user',
+  };
+}
+
+function makeAgent(skills?: SkillRegistry): Agent {
+  const rpc = {
+    emitEvent: vi.fn(),
+    requestApproval: vi.fn(),
+    requestQuestion: vi.fn(),
+    toolCall: vi.fn(),
+  } as unknown as SDKAgentRPC;
+  const agent = new Agent({
+    runtime: {
+      kaos: localKaos,
+      osEnv: TEST_OS_ENV,
+    },
+    rpc,
+    skills,
+    providerManager: testProviderManager(),
+  });
+  agent.config.update({
+    cwd: process.cwd(),
+    modelAlias: MOCK_PROVIDER.model,
+  });
+  agent.tools.initializeBuiltinTools();
+  agent.tools.setActiveTools(['Skill']);
+  return agent;
+}
+
+function runtime() {
+  return {
+    kaos: localKaos,
+    osEnv: TEST_OS_ENV,
+  };
+}
+
+function sessionRpc(): SDKSessionRPC {
+  return {
+    emitEvent: vi.fn(),
+    requestApproval: vi.fn(async (): Promise<ApprovalResponse> => ({ decision: 'rejected' })),
+    requestQuestion: vi.fn(async () => null),
+    toolCall: vi.fn(async () => ({ output: '' })),
+  } as unknown as SDKSessionRPC;
+}
+
+function testProviderManager(): ProviderManager {
+  return new ProviderManager({
+    config: {
+      providers: {
+        test: {
+          type: MOCK_PROVIDER.type,
+          apiKey: MOCK_PROVIDER.apiKey,
+        },
+      },
+      models: {
+        [MOCK_PROVIDER.model]: {
+          provider: 'test',
+          model: MOCK_PROVIDER.model,
+          maxContextSize: 1_000_000,
+        },
+      },
+    },
+  });
+}
+
+describe('ToolManager SkillTool registration', () => {
+  it('does not expose Skill when the agent has no skill registry', () => {
+    const agent = makeAgent();
+
+    expect(agent.tools.data().find((tool) => tool.name === 'Skill')).toBeUndefined();
+    expect(agent.tools.loopTools.find((tool) => tool.name === 'Skill')).toBeUndefined();
+  });
+
+  it('does not expose Skill when there are no model-invocable skills', () => {
+    const skills = new SkillRegistry();
+    skills.register(makeSkill('private', { disableModelInvocation: true }));
+
+    const agent = makeAgent(skills);
+
+    expect(agent.tools.data().find((tool) => tool.name === 'Skill')).toBeUndefined();
+    expect(agent.tools.loopTools.find((tool) => tool.name === 'Skill')).toBeUndefined();
+  });
+
+  it('exposes Skill when at least one inline skill is model-invocable', () => {
+    const skills = new SkillRegistry();
+    skills.register(makeSkill('review'));
+    skills.register(makeSkill('flow-only', { type: 'flow' }));
+
+    const agent = makeAgent(skills);
+    const skillInfo = agent.tools.data().find((tool) => tool.name === 'Skill');
+    const skillTool = agent.tools.loopTools.find((tool) => tool.name === 'Skill');
+
+    expect(skillInfo).toMatchObject({ name: 'Skill', active: true, source: 'builtin' });
+    expect(skillTool).toBeInstanceOf(SkillTool);
+  });
+
+  it('persists model-invoked inline skill reminders through agent wire', async () => {
+    const skills = new SkillRegistry();
+    skills.register(makeSkill('review'));
+    const agent = makeAgent(skills);
+    const skillTool = agent.tools.loopTools.find((tool) => tool.name === 'Skill');
+    if (!(skillTool instanceof SkillTool)) {
+      throw new Error('Expected SkillTool to be active');
+    }
+
+    const result = await executeTool(skillTool, {
+      turnId: '0',
+      toolCallId: 'call_skill',
+      args: { skill: 'review' },
+      signal: new AbortController().signal,
+    });
+
+    expect(result.output).toContain('loaded inline');
+    expect(
+      agent.records.snapshot().find((record) => record.type === 'context.append_message'),
+    ).toMatchObject({
+      type: 'context.append_message',
+      message: {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: '<system-reminder>\n<kimi-skill-loaded name="review" args="">\nbody of review\n</kimi-skill-loaded>\n</system-reminder>',
+          },
+        ],
+        origin: {
+          kind: 'skill_activation',
+          skillName: 'review',
+          trigger: 'model-tool',
+        },
+      },
+    });
+    expect(agent.context.history.at(-1)).toMatchObject({
+      role: 'user',
+      origin: {
+        kind: 'skill_activation',
+        skillName: 'review',
+      },
+    });
+  });
+
+  it('exposes session skills after the main agent is created', async () => {
+    const tmp = await mkdtemp(join(tmpdir(), 'kimi-core-skill-tool-refresh-'));
+    try {
+      const homeDir = join(tmp, 'home');
+      const workDir = join(tmp, 'work');
+      const skillDir = join(workDir, '.kimi-code', 'skills', 'review');
+      await mkdir(skillDir, { recursive: true });
+      await writeFile(
+        join(skillDir, 'SKILL.md'),
+        ['---', 'name: review', 'description: Review code', '---', '', 'Review body.'].join('\n'),
+      );
+
+      const session = new Session({
+        id: 'test-skill-tool',
+        runtime: runtime(),
+        homedir: homeDir,
+        cwd: workDir,
+        rpc: sessionRpc(),
+        providerManager: testProviderManager(),
+      });
+      const mainAgent = await session.createMain();
+      mainAgent.config.update({
+        cwd: workDir,
+        modelAlias: MOCK_PROVIDER.model,
+      });
+      mainAgent.tools.initializeBuiltinTools();
+      mainAgent.tools.setActiveTools(['Skill']);
+
+      expect(mainAgent.tools.loopTools.find((tool) => tool.name === 'Skill')).toBeInstanceOf(
+        SkillTool,
+      );
+      await session.flushMetadata();
+    } finally {
+      await rm(tmp, { recursive: true, force: true, maxRetries: 3, retryDelay: 10 });
+    }
+  });
+});
diff --git a/packages/agent-core/test/agent/tool.test.ts b/packages/agent-core/test/agent/tool.test.ts
new file mode 100644
index 000000000..542f66653
--- /dev/null
+++ b/packages/agent-core/test/agent/tool.test.ts
@@ -0,0 +1,404 @@
+import type { ToolCall } from '@moonshot-ai/kosong';
+import { describe, expect, it, vi } from 'vitest';
+
+import { HookEngine } from '../../src/agent/hooks';
+import type { SessionSubagentHost } from '../../src/session/subagent-host';
+import { createFakeKaos } from '../tools/fixtures/fake-kaos';
+import { createCommandKaos, testAgent } from './harness/agent';
+import { executeTool } from '../tools/fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+describe('Agent tools', () => {
+  it('blocks tools through PreToolUse before permission and emits PostToolUseFailure', async () => {
+    const execWithEnv = vi.fn().mockRejectedValue(new Error('Bash should not execute'));
+    const triggered: Array<[string, string, number]> = [];
+    const hookEngine = new HookEngine(
+      [
+        {
+          event: 'PreToolUse',
+          matcher: 'Bash',
+          command: "echo 'blocked by PreToolUse' >&2; exit 2",
+        },
+        {
+          event: 'PostToolUseFailure',
+          matcher: 'Bash',
+          command: 'exit 0',
+        },
+      ],
+      {
+        onTriggered: (event, target, count) => {
+          triggered.push([event, target, count]);
+        },
+      },
+    );
+    const ctx = testAgent({
+      kaos: createFakeKaos({ execWithEnv }),
+      hookEngine,
+    });
+    ctx.configure({ tools: ['Bash'] });
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will run Bash.' }, bashCall());
+    ctx.mockNextResponse({ type: 'text', text: 'The hook blocked Bash.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Try Bash' }] });
+
+    await ctx.untilTurnEnd();
+
+    expect(execWithEnv).not.toHaveBeenCalled();
+    expect(triggered).toEqual([
+      ['PreToolUse', 'Bash', 1],
+      ['PostToolUseFailure', 'Bash', 1],
+    ]);
+    expect(JSON.stringify(ctx.agent.context.data().history)).toContain('blocked by PreToolUse');
+  });
+
+  it('emits PostToolUse after successful tools', async () => {
+    const triggered: Array<[string, string, number]> = [];
+    const hookEngine = new HookEngine(
+      [
+        {
+          event: 'PostToolUse',
+          matcher: 'Bash',
+          command: 'exit 0',
+        },
+      ],
+      {
+        onTriggered: (event, target, count) => {
+          triggered.push([event, target, count]);
+        },
+      },
+    );
+    const ctx = testAgent({
+      kaos: createCommandKaos('ok'),
+      hookEngine,
+    });
+    ctx.configure({ tools: ['Bash'] });
+    await ctx.rpc.setPermission({ mode: 'auto' });
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will run Bash.' }, bashCall());
+    ctx.mockNextResponse({ type: 'text', text: 'Bash returned ok.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Run Bash' }] });
+
+    await ctx.untilTurnEnd();
+
+    expect(triggered).toEqual([['PostToolUse', 'Bash', 1]]);
+  });
+
+  it('uses builtin descriptions on tool call start events', async () => {
+    const ctx = testAgent({
+      kaos: createCommandKaos('ok'),
+    });
+    ctx.configure({ tools: ['Bash'] });
+    await ctx.rpc.setPermission({ mode: 'yolo' });
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will run Bash.' }, bashCall());
+    ctx.mockNextResponse({ type: 'text', text: 'Bash returned ok.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Run Bash' }] });
+    await ctx.untilTurnEnd();
+
+    const started = ctx.allEvents.find(
+      (event) => event.type === '[rpc]' && event.event === 'tool.call.started',
+    );
+    expect(started?.args).toMatchObject({
+      description: 'Running: printf hook-output',
+    });
+  });
+
+  it('continues after a foreground Agent tool returns a max_tokens failure', async () => {
+    const subagentHost = {
+      spawn: vi.fn().mockResolvedValue({
+        agentId: 'agent-child',
+        profileName: 'coder',
+        resumed: false,
+        completion: Promise.reject(
+          new Error('Subagent turn failed before completing its final summary: reason=max_tokens.'),
+        ),
+      }),
+      resume: vi.fn(),
+    } as unknown as SessionSubagentHost;
+    const ctx = testAgent({ subagentHost });
+    ctx.configure({ tools: ['Agent'] });
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will ask a subagent.' }, agentCall());
+    ctx.mockNextResponse({
+      type: 'text',
+      text: 'The subagent failed with reason=max_tokens, so I will continue in the parent turn.',
+    });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Delegate and recover' }] });
+    await ctx.untilTurnEnd();
+
+    expect(subagentHost.spawn).toHaveBeenCalledWith(
+      'coder',
+      expect.objectContaining({
+        parentToolCallId: 'call_agent',
+        prompt: 'Investigate deeply',
+        description: 'Investigate deeply',
+        runInBackground: false,
+      }),
+    );
+    expect(ctx.llmCalls).toHaveLength(2);
+    expect(ctx.allEvents).toContainEqual(
+      expect.objectContaining({
+        type: '[rpc]',
+        event: 'tool.result',
+        args: expect.objectContaining({
+          toolCallId: 'call_agent',
+          isError: true,
+          output: expect.stringContaining('reason=max_tokens'),
+        }),
+      }),
+    );
+    expect(JSON.stringify(ctx.llmCalls[1]?.history)).toContain('reason=max_tokens');
+  });
+
+  it('passes text from content-part error outputs to PostToolUseFailure hooks', async () => {
+    const lookupCall: ToolCall = {
+      type: 'function',
+      id: 'call_lookup',
+      function: {
+        name: 'Lookup',
+        arguments: '{"query":"moon"}',
+      },
+    };
+    const resolved: Array<[string, string, string]> = [];
+    const hookEngine = new HookEngine(
+      [
+        {
+          event: 'PostToolUseFailure',
+          matcher: 'Lookup',
+          command: hookErrorMessageAssertCommand('rich failure text'),
+        },
+      ],
+      {
+        onResolved: (event, target, action) => {
+          resolved.push([event, target, action]);
+        },
+      },
+    );
+    const ctx = testAgent({ hookEngine });
+    ctx.configure();
+    await ctx.rpc.setPermission({ mode: 'auto' });
+    await ctx.rpc.registerTool({
+      name: 'Lookup',
+      description: 'Look up a short test value.',
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string' },
+        },
+        required: ['query'],
+        additionalProperties: false,
+      },
+    });
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will look it up.' }, lookupCall);
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Look up moon' }] });
+    await ctx.untilToolCall({
+      isError: true,
+      output: [{ type: 'text', text: 'rich failure text' }],
+    });
+
+    ctx.mockNextResponse({ type: 'text', text: 'The lookup failed.' });
+    await ctx.untilTurnEnd();
+
+    await vi.waitFor(() => {
+      expect(resolved).toEqual([['PostToolUseFailure', 'Lookup', 'allow']]);
+    });
+  });
+
+  it('uses the active builtin tool set as the LLM visible tools', async () => {
+    const ctx = testAgent();
+    ctx.configure({ tools: ['Write', 'Bash'] });
+
+    ctx.mockNextResponse({ type: 'text', text: 'ready' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Which tools are active?' }] });
+
+    await ctx.untilTurnEnd();
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: Bash, Write
+      messages:
+        user: text "Which tools are active?"
+    `);
+    await ctx.expectResumeMatches();
+  });
+
+  it('disables Bash background mode unless task management tools are active', async () => {
+    const ctx = testAgent();
+    ctx.configure({ tools: ['Bash'] });
+
+    const bashOnly = ctx.agent.tools.loopTools.find((tool) => tool.name === 'Bash');
+    expect(bashOnly).toBeDefined();
+    expect(bashOnly!.description).toContain('Background execution is disabled for this agent.');
+    expect(bashOnly!.description).not.toContain('the command will be started as a background task');
+    await expect(
+      executeTool(bashOnly!, {
+        turnId: '0',
+        toolCallId: 'call_bash',
+        args: { command: 'sleep 10', run_in_background: true, description: 'watch' },
+        signal,
+      }),
+    ).resolves.toMatchObject({
+      isError: true,
+      output:
+        'Background execution is not available for this agent because TaskOutput and TaskStop are not enabled.',
+    });
+
+    ctx.agent.tools.setActiveTools(['Bash', 'TaskList', 'TaskOutput', 'TaskStop']);
+
+    const managedBash = ctx.agent.tools.loopTools.find((tool) => tool.name === 'Bash');
+    expect(managedBash).toBeDefined();
+    expect(managedBash!.description).toContain('run_in_background=true');
+  });
+
+  it('routes registered user tools through tool.call request/response', async () => {
+    const lookupCall: ToolCall = {
+      type: 'function',
+      id: 'call_lookup',
+      function: {
+        name: 'Lookup',
+        arguments: '{"query":"moon"}',
+      },
+    };
+    const ctx = testAgent();
+    ctx.configure();
+    await ctx.rpc.setPermission({ mode: 'auto' });
+    await ctx.rpc.registerTool({
+      name: 'Lookup',
+      description: 'Look up a short test value.',
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string' },
+        },
+        required: ['query'],
+        additionalProperties: false,
+      },
+    });
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will look it up.' }, lookupCall);
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Look up moon' }] });
+    expect(
+      await ctx.untilToolCall({
+        content: 'moon-result',
+        output: 'moon-result',
+      }),
+    ).toMatchInlineSnapshot(`
+      [wire] permission.set_mode         { "mode": "auto", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 0, "maxContextTokens": 1000000, "contextUsage": 0, "planMode": false, "permission": "auto" }
+      [wire] tools.register_user_tool    { "name": "Lookup", "description": "Look up a short test value.", "parameters": { "type": "object", "properties": { "query": { "type": "string" } }, "required": [ "query" ], "additionalProperties": false }, "time": "<time>" }
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Look up moon" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Look up moon" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "<auto-mode-enter-reminder>" } ], "toolCalls": [], "origin": { "kind": "injection", "variant": "permission_mode" } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "I will look it up." }
+      [emit] tool.call.delta             { "turnId": 0, "toolCallId": "call_lookup", "name": "Lookup", "argumentsPart": "{\\"query\\":\\"moon\\"}" }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "I will look it up." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "tool.call", "uuid": "call_lookup", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "toolCallId": "call_lookup", "name": "Lookup", "args": { "query": "moon" } }, "time": "<time>" }
+      [emit] tool.call.started           { "turnId": 0, "toolCallId": "call_lookup", "name": "Lookup", "args": { "query": "moon" } }
+      [emit] toolCall                    { "turnId": 0, "toolCallId": "call_lookup", "args": { "query": "moon" } }
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: Lookup
+      messages:
+        user: text "Look up moon"
+        user: text <auto-mode-enter-reminder>
+    `);
+
+    ctx.mockNextResponse({ type: 'text', text: 'The lookup result is moon-result.' });
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] context.append_loop_event   { "event": { "type": "tool.result", "parentUuid": "call_lookup", "toolCallId": "call_lookup", "result": { "output": "moon-result" } }, "time": "<time>" }
+      [emit] tool.result                 { "turnId": 0, "toolCallId": "call_lookup", "output": "moon-result" }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "usage": { "inputOther": 88, "output": 16, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 0, "step": 1, "stepId": "<uuid-1>", "usage": { "inputOther": 88, "output": 16, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }
+      [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 88, "output": 16, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 104, "maxContextTokens": 1000000, "contextUsage": 0.000104, "planMode": false, "permission": "auto", "usage": { "byModel": { "mock-model": { "inputOther": 88, "output": 16, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 88, "output": 16, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 88, "output": 16, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-3>", "turnId": "0", "step": 2 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 2, "stepId": "<uuid-3>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "The lookup result is moon-result." }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "stepUuid": "<uuid-3>", "part": { "type": "text", "text": "The lookup result is moon-result." } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-3>", "turnId": "0", "step": 2, "usage": { "inputOther": 108, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+      [emit] turn.step.completed         { "turnId": 0, "step": 2, "stepId": "<uuid-3>", "usage": { "inputOther": 108, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+      [wire] usage.record                { "model": "mock-model", "usage": { "inputOther": 108, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated        { "model": "mock-model", "contextTokens": 120, "maxContextTokens": 1000000, "contextUsage": 0.00012, "planMode": false, "permission": "auto", "usage": { "byModel": { "mock-model": { "inputOther": 196, "output": 28, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 196, "output": 28, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 196, "output": 28, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [emit] turn.ended                  { "turnId": 0, "reason": "completed" }
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      messages:
+        <last>
+        assistant: text "I will look it up."  calls call_lookup:Lookup { "query": "moon" }
+        tool[call_lookup]: text "moon-result"
+    `);
+
+    await ctx.rpc.unregisterTool({ name: 'Lookup' });
+    ctx.mockNextResponse({ type: 'text', text: 'No lookup tool is available.' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Can you still use Lookup?' }] });
+
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] tools.unregister_user_tool   { "name": "Lookup", "time": "<time>" }
+      [wire] turn.prompt                  { "input": [ { "type": "text", "text": "Can you still use Lookup?" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                 { "turnId": 1, "origin": { "kind": "user" } }
+      [wire] context.append_message       { "message": { "role": "user", "content": [ { "type": "text", "text": "Can you still use Lookup?" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_loop_event    { "event": { "type": "step.begin", "uuid": "<uuid-5>", "turnId": "1", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started            { "turnId": 1, "step": 1, "stepId": "<uuid-5>" }
+      [emit] assistant.delta              { "turnId": 1, "delta": "No lookup tool is available." }
+      [wire] context.append_loop_event    { "event": { "type": "content.part", "uuid": "<uuid-6>", "turnId": "1", "step": 1, "stepUuid": "<uuid-5>", "part": { "type": "text", "text": "No lookup tool is available." } }, "time": "<time>" }
+      [wire] context.append_loop_event    { "event": { "type": "step.end", "uuid": "<uuid-5>", "turnId": "1", "step": 1, "usage": { "inputOther": 128, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+      [emit] turn.step.completed          { "turnId": 1, "step": 1, "stepId": "<uuid-5>", "usage": { "inputOther": 128, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+      [wire] usage.record                 { "model": "mock-model", "usage": { "inputOther": 128, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated         { "model": "mock-model", "contextTokens": 138, "maxContextTokens": 1000000, "contextUsage": 0.000138, "planMode": false, "permission": "auto", "usage": { "byModel": { "mock-model": { "inputOther": 324, "output": 38, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 324, "output": 38, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 128, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [emit] turn.ended                   { "turnId": 1, "reason": "completed" }
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      tools: []
+      messages:
+        <last>
+        assistant: text "The lookup result is moon-result."
+        user: text "Can you still use Lookup?"
+    `);
+    await ctx.expectResumeMatches();
+  });
+});
+
+function bashCall(): ToolCall {
+  return {
+    type: 'function',
+    id: 'call_bash',
+    function: {
+      name: 'Bash',
+      arguments: '{"command":"printf hook-output","timeout":60}',
+    },
+  };
+}
+
+function agentCall(): ToolCall {
+  return {
+    type: 'function',
+    id: 'call_agent',
+    function: {
+      name: 'Agent',
+      arguments: JSON.stringify({
+        prompt: 'Investigate deeply',
+        description: 'Investigate deeply',
+        subagent_type: 'coder',
+      }),
+    },
+  };
+}
+
+function hookErrorMessageAssertCommand(expected: string): string {
+  const script = [
+    "let input = '';",
+    "process.stdin.on('data', (chunk) => { input += chunk; });",
+    "process.stdin.on('end', () => {",
+    '  const payload = JSON.parse(input);',
+    `  if (payload.error?.message === ${JSON.stringify(expected)}) process.exit(0);`,
+    "  console.error(payload.error?.message ?? '<missing>');",
+    '  process.exit(2);',
+    '});',
+  ].join('');
+  return `node -e ${JSON.stringify(script)}`;
+}
diff --git a/packages/agent-core/test/agent/turn.test.ts b/packages/agent-core/test/agent/turn.test.ts
new file mode 100644
index 000000000..f201b082f
--- /dev/null
+++ b/packages/agent-core/test/agent/turn.test.ts
@@ -0,0 +1,1508 @@
+import { existsSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import type { Kaos } from '@moonshot-ai/kaos';
+import {
+  APIConnectionError,
+  APIEmptyResponseError,
+  APIStatusError,
+  APITimeoutError,
+  type ChatProvider,
+  type ModelCapability,
+  type ToolCall,
+} from '@moonshot-ai/kosong';
+import { describe, expect, it, vi } from 'vitest';
+
+import { HookEngine } from '../../src/agent/hooks';
+import type { AgentConfig } from '../../src/agent';
+import type { KimiConfig } from '../../src/config';
+import type { Logger, LogPayload } from '../../src/logging';
+import { ProviderManager } from '../../src/providers/provider-manager';
+import {
+  estimateTokens,
+  estimateTokensForMessages,
+  estimateTokensForTools,
+} from '../../src/utils/tokens';
+import { recordingTelemetry, type TelemetryRecord } from '../fixtures/telemetry';
+import { createFakeKaos } from '../tools/fixtures/fake-kaos';
+import { createCommandKaos, testAgent } from './harness/agent';
+import { executeTool } from '../tools/fixtures/execute-tool';
+
+type GenerateFn = NonNullable<AgentConfig['generate']>;
+
+interface CapturedLogEntry {
+  readonly level: 'error' | 'warn' | 'info' | 'debug';
+  readonly message: string;
+  readonly payload: LogPayload | undefined;
+}
+
+function captureLogs(): { logger: Logger; entries: CapturedLogEntry[] } {
+  const entries: CapturedLogEntry[] = [];
+  const capture =
+    (level: CapturedLogEntry['level']) => (message: string, payload?: LogPayload) => {
+      entries.push({ level, message, payload });
+    };
+  const logger: Logger = {
+    error: capture('error'),
+    warn: capture('warn'),
+    info: capture('info'),
+    debug: capture('debug'),
+    createChild: () => logger,
+  };
+  return { logger, entries };
+}
+
+describe('Agent turn flow', () => {
+  it('tracks turn_started and turn_interrupted telemetry', async () => {
+    const records: TelemetryRecord[] = [];
+    const ctx = testAgent({ telemetry: recordingTelemetry(records) });
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Hello without login' }] });
+    await ctx.untilTurnEnd();
+
+    expect(records).toContainEqual({
+      event: 'turn_started',
+      properties: { mode: 'agent' },
+    });
+    expect(records).toContainEqual({
+      event: 'turn_interrupted',
+      properties: { mode: 'agent', at_step: 0 },
+    });
+  });
+
+  it('tracks duplicate tool-call detection telemetry', async () => {
+    const records: TelemetryRecord[] = [];
+    const ctx = testAgent({
+      kaos: createCommandKaos('dup'),
+      telemetry: recordingTelemetry(records),
+    });
+    ctx.configure({ tools: ['Bash'] });
+    await ctx.rpc.setPermission({ mode: 'yolo' });
+    records.length = 0;
+
+    ctx.mockNextResponse(
+      bashCallWithId('call_dup_1', 'printf dup'),
+      bashCallWithId('call_dup_2', 'printf dup'),
+    );
+    ctx.mockNextResponse({ type: 'text', text: 'done' });
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Run duplicates' }] });
+    await ctx.untilTurnEnd();
+
+    expect(records).toContainEqual({
+      event: 'tool_call_dedup_detected',
+      properties: {
+        turn_id: 0,
+        step_no: 1,
+        tool_name: 'Bash',
+        dup_type: 'same_step',
+        args_hash: expect.any(String),
+      },
+    });
+    expect(records).toContainEqual({
+      event: 'hook_triggered',
+      properties: {
+        event_type: 'PreToolUse',
+        action: 'allow',
+      },
+    });
+  });
+
+  it('tracks cross-step duplicate tool-call detection telemetry', async () => {
+    const records: TelemetryRecord[] = [];
+    const ctx = testAgent({
+      kaos: createCommandKaos('dup'),
+      telemetry: recordingTelemetry(records),
+    });
+    ctx.configure({ tools: ['Bash'] });
+    await ctx.rpc.setPermission({ mode: 'yolo' });
+    records.length = 0;
+
+    ctx.mockNextResponse(bashCallWithId('call_dup_1', 'printf dup'));
+    ctx.mockNextResponse(bashCallWithId('call_dup_2', 'printf dup'));
+    ctx.mockNextResponse({ type: 'text', text: 'done' });
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Run duplicates across steps' }] });
+    await ctx.untilTurnEnd();
+
+    expect(records).toContainEqual({
+      event: 'tool_call_dedup_detected',
+      properties: {
+        turn_id: 0,
+        step_no: 2,
+        tool_name: 'Bash',
+        dup_type: 'cross_step',
+        args_hash: expect.any(String),
+      },
+    });
+    expect(records).toContainEqual({
+      event: 'tool_call',
+      properties: expect.objectContaining({
+        tool_name: 'Bash',
+        outcome: 'success',
+        dup_type: 'cross_step',
+        duration_ms: expect.any(Number),
+      }),
+    });
+  });
+
+  it('fires PostToolUse for same-step dups with the original real output, not the dedup placeholder', async () => {
+    // Hook command asserts the dup's PostToolUse payload carries the real
+    // stdout ('dup'), not the placeholder ('').
+    const assertScript = [
+      "let input = '';",
+      "process.stdin.on('data', (chunk) => { input += chunk; });",
+      "process.stdin.on('end', () => {",
+      '  const payload = JSON.parse(input);',
+      "  if (typeof payload.tool_output === 'string' && payload.tool_output.includes('dup')) process.exit(0);",
+      "  console.error('bad tool_output: ' + JSON.stringify(payload.tool_output));",
+      '  process.exit(2);',
+      '});',
+    ].join('');
+    const resolved: Array<[string, string, string]> = [];
+    const hookEngine = new HookEngine(
+      [
+        {
+          event: 'PostToolUse',
+          matcher: 'Bash',
+          command: `node -e ${JSON.stringify(assertScript)}`,
+        },
+      ],
+      {
+        onResolved: (event, target, action) => {
+          resolved.push([event, target, action]);
+        },
+      },
+    );
+    const ctx = testAgent({ kaos: createCommandKaos('dup'), hookEngine });
+    ctx.configure({ tools: ['Bash'] });
+    await ctx.rpc.setPermission({ mode: 'yolo' });
+
+    ctx.mockNextResponse(
+      bashCallWithId('call_dup_1', 'printf dup'),
+      bashCallWithId('call_dup_2', 'printf dup'),
+    );
+    ctx.mockNextResponse({ type: 'text', text: 'done' });
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Run duplicates' }] });
+    await ctx.untilTurnEnd();
+
+    await vi.waitFor(() => {
+      expect(resolved).toEqual([
+        ['PostToolUse', 'Bash', 'allow'],
+        ['PostToolUse', 'Bash', 'allow'],
+      ]);
+    });
+  });
+
+  it('tracks failed tool-call telemetry with error taxonomy', async () => {
+    const records: TelemetryRecord[] = [];
+    const ctx = testAgent({ telemetry: recordingTelemetry(records) });
+    ctx.configure();
+    records.length = 0;
+
+    ctx.mockNextResponse({
+      type: 'function',
+      id: 'call_missing',
+      function: {
+        name: 'MissingTool',
+        arguments: '{}',
+      },
+    });
+    ctx.mockNextResponse({ type: 'text', text: 'done' });
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Call a missing tool' }] });
+    await ctx.untilTurnEnd();
+
+    expect(records).toContainEqual({
+      event: 'tool_call',
+      properties: expect.objectContaining({
+        tool_name: 'MissingTool',
+        outcome: 'error',
+        dup_type: 'normal',
+        error_type: 'ToolNotFound',
+        duration_ms: expect.any(Number),
+      }),
+    });
+  });
+
+  it('emits a failed turn and error when generation fails', async () => {
+    const ctx = testAgent();
+    ctx.configure();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Trigger generate failure' }] });
+
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Trigger generate failure" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Trigger generate failure" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+      [emit] turn.step.interrupted       { "turnId": 0, "step": 1, "reason": "error", "message": "Unexpected generate call #1" }
+      [emit] turn.ended                  { "turnId": 0, "reason": "failed", "error": { "code": "internal", "message": "Unexpected generate call #1", "name": "Error", "retryable": false, "details": { "turnId": 0 } } }
+    `);
+    expect(ctx.newEvents()).toMatchInlineSnapshot(
+      `[emit] error   { "code": "internal", "message": "Unexpected generate call #1", "name": "Error", "retryable": false, "details": { "turnId": 0 } }`,
+    );
+    await ctx.expectResumeMatches();
+  });
+
+  it('emits a friendly model.not_configured error when no model is configured', async () => {
+    const ctx = testAgent();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Hello without login' }] });
+
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] turn.prompt              { "input": [ { "type": "text", "text": "Hello without login" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started             { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message   { "message": { "role": "user", "content": [ { "type": "text", "text": "Hello without login" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [emit] turn.ended               { "turnId": 0, "reason": "failed", "error": { "code": "model.not_configured", "message": "LLM not set, send \\"/login\\" to login", "name": "Error", "retryable": false, "details": { "turnId": 0 } } }
+    `);
+    expect(ctx.newEvents()).toMatchInlineSnapshot(
+      `[emit] error   { "code": "model.not_configured", "message": "LLM not set, send \\"/login\\" to login", "name": "Error", "retryable": false, "details": { "turnId": 0 } }`,
+    );
+  });
+
+  it('continues the turn after showing UserPromptSubmit hook output without injecting it', async () => {
+    const hookEngine = new HookEngine([
+      {
+        event: 'UserPromptSubmit',
+        matcher: 'hooked input',
+        command:
+          'node -e "let s=\\"\\";process.stdin.on(\\"data\\",d=>s+=d);process.stdin.on(\\"end\\",()=>{const o=JSON.parse(s);if(Array.isArray(o.prompt)&&o.prompt[0]?.text===\\"hooked input\\"){process.stdout.write(\\"hook response 1\\");process.exit(0);}console.error(\\"bad prompt\\");process.exit(1);})"',
+      },
+      {
+        event: 'UserPromptSubmit',
+        matcher: 'hooked input',
+        command: "echo 'hook response 2'",
+      },
+    ]);
+    const ctx = testAgent({ hookEngine });
+    ctx.configure();
+    ctx.mockNextResponse({ type: 'text', text: 'model saw original prompt only' });
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'hooked input' }] });
+    const events = await ctx.untilTurnEnd();
+
+    const hookResult =
+      '<hook_result hook_event="UserPromptSubmit">\nhook response 1\n</hook_result>\n<hook_result hook_event="UserPromptSubmit">\nhook response 2\n</hook_result>';
+    expect(ctx.llmCalls).toHaveLength(1);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: []
+      messages:
+        user: text "hooked input"
+    `);
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'hook.result',
+        args: expect.objectContaining({
+          hookEvent: 'UserPromptSubmit',
+          content: 'hook response 1\n\nhook response 2',
+        }),
+      }),
+    );
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'assistant.delta',
+        args: expect.objectContaining({ delta: 'model saw original prompt only' }),
+      }),
+    );
+    expect(ctx.agent.context.data().history).toEqual([
+      {
+        role: 'user',
+        content: [{ type: 'text', text: 'hooked input' }],
+        toolCalls: [],
+        origin: { kind: 'user' },
+      },
+      {
+        role: 'user',
+        content: [{ type: 'text', text: hookResult }],
+        toolCalls: [],
+        origin: { kind: 'hook_result', event: 'UserPromptSubmit' },
+      },
+      {
+        role: 'assistant',
+        content: [{ type: 'text', text: 'model saw original prompt only' }],
+        toolCalls: [],
+      },
+    ]);
+  });
+
+  it('shows structured UserPromptSubmit stdout without injecting it', async () => {
+    const hookEngine = new HookEngine([
+      {
+        event: 'UserPromptSubmit',
+        matcher: 'hooked input',
+        command: "echo '{}'",
+      },
+      {
+        event: 'UserPromptSubmit',
+        matcher: 'hooked input',
+        command: 'echo \'{"hookSpecificOutput":{}}\'',
+      },
+    ]);
+    const ctx = testAgent({ hookEngine });
+    ctx.configure();
+    ctx.mockNextResponse({ type: 'text', text: 'model saw original prompt only' });
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'hooked input' }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(ctx.llmCalls).toHaveLength(1);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: []
+      messages:
+        user: text "hooked input"
+    `);
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'hook.result',
+        args: expect.objectContaining({
+          hookEvent: 'UserPromptSubmit',
+          content: '{}\n\n{"hookSpecificOutput":{}}',
+        }),
+      }),
+    );
+    expect(ctx.agent.context.data().history).toEqual([
+      {
+        role: 'user',
+        content: [{ type: 'text', text: 'hooked input' }],
+        toolCalls: [],
+        origin: { kind: 'user' },
+      },
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: '<hook_result hook_event="UserPromptSubmit">\n{}\n</hook_result>\n<hook_result hook_event="UserPromptSubmit">\n{"hookSpecificOutput":{}}\n</hook_result>',
+          },
+        ],
+        toolCalls: [],
+        origin: { kind: 'hook_result', event: 'UserPromptSubmit' },
+      },
+      {
+        role: 'assistant',
+        content: [{ type: 'text', text: 'model saw original prompt only' }],
+        toolCalls: [],
+      },
+    ]);
+  });
+
+  it('stops the turn when a UserPromptSubmit hook blocks', async () => {
+    const hookEngine = new HookEngine([
+      {
+        event: 'UserPromptSubmit',
+        matcher: 'bad words',
+        command: "echo 'no profanity' >&2; exit 2",
+      },
+    ]);
+    const ctx = testAgent({ hookEngine });
+    ctx.configure();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'bad words here' }] });
+    const events = await ctx.untilTurnEnd();
+
+    const hookResult = '<hook_result hook_event="UserPromptSubmit">\nno profanity\n</hook_result>';
+    expect(ctx.llmCalls).toHaveLength(0);
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'hook.result',
+        args: expect.objectContaining({
+          hookEvent: 'UserPromptSubmit',
+          content: 'no profanity',
+          blocked: true,
+        }),
+      }),
+    );
+    expect(ctx.agent.context.data().history).toEqual([
+      {
+        role: 'user',
+        content: [{ type: 'text', text: 'bad words here' }],
+        toolCalls: [],
+        origin: { kind: 'user', blockedByHook: 'UserPromptSubmit' },
+      },
+      {
+        role: 'assistant',
+        content: [{ type: 'text', text: hookResult }],
+        toolCalls: [],
+        origin: { kind: 'hook_result', event: 'UserPromptSubmit', blocked: true },
+      },
+    ]);
+
+    ctx.mockNextResponse({ type: 'text', text: 'safe answer' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'safe followup' }] });
+    await ctx.untilTurnEnd();
+
+    expect(ctx.llmCalls).toHaveLength(1);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: []
+      messages:
+        user: text "safe followup"
+    `);
+  });
+
+  it('cancels while waiting for a UserPromptSubmit hook without appending stale output', async () => {
+    const hookEngine = new HookEngine([
+      {
+        event: 'UserPromptSubmit',
+        command: 'node -e "setTimeout(() => process.stdout.write(\\"late hook\\"), 250)"',
+        timeout: 5,
+      },
+    ]);
+    const ctx = testAgent({ hookEngine });
+    ctx.configure();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'hook will sleep' }] });
+    await ctx.rpc.cancel({ turnId: 0 });
+    const events = await ctx.untilTurnEnd();
+
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: expect.objectContaining({ reason: 'cancelled' }),
+      }),
+    );
+    expect(events).not.toContainEqual(
+      expect.objectContaining({
+        event: 'assistant.delta',
+        args: expect.objectContaining({ delta: expect.stringContaining('late hook') }),
+      }),
+    );
+    expect(ctx.agent.context.data().history).toEqual([
+      {
+        role: 'user',
+        content: [{ type: 'text', text: 'hook will sleep' }],
+        toolCalls: [],
+        origin: { kind: 'user' },
+      },
+    ]);
+  });
+
+  it('uses a Stop hook block reason as a one-shot turn continuation', async () => {
+    const hookEngine = new HookEngine([
+      {
+        event: 'Stop',
+        command: "echo 'continue from hook' >&2; exit 2",
+      },
+    ]);
+    const ctx = testAgent({ hookEngine });
+    ctx.configure();
+    ctx.mockNextResponse({ type: 'text', text: 'First answer.' });
+    ctx.mockNextResponse({ type: 'text', text: 'Second answer.' });
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'hello' }] });
+    await ctx.untilTurnEnd();
+
+    expect(ctx.llmCalls).toHaveLength(2);
+    const stopHookMessage = {
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text: 'continue from hook',
+        },
+      ],
+      toolCalls: [],
+      origin: { kind: 'system_trigger', name: 'stop_hook' },
+    };
+    const llmStopHookMessage = {
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text: 'continue from hook',
+        },
+      ],
+      toolCalls: [],
+    };
+    expect(JSON.stringify(ctx.agent.context.data().history)).toContain('continue from hook');
+    expect(ctx.agent.context.data().history).toContainEqual(stopHookMessage);
+    expect(ctx.llmCalls[1]?.history).toContainEqual(llmStopHookMessage);
+    expect(JSON.stringify(ctx.agent.context.data().history)).toContain('Second answer.');
+  });
+
+  it('cancels while waiting for a Stop hook', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'kimi-stop-hook-'));
+    const marker = join(dir, 'started');
+    const script = [
+      "const fs=require('node:fs');",
+      `fs.writeFileSync(${JSON.stringify(marker)}, 'started');`,
+      "setTimeout(() => process.stderr.write('late stop hook'), 250);",
+    ].join('');
+    const hookEngine = new HookEngine([
+      {
+        event: 'Stop',
+        command: `node -e ${JSON.stringify(script)}`,
+        timeout: 5,
+      },
+    ]);
+    const ctx = testAgent({ hookEngine });
+    ctx.configure();
+    ctx.mockNextResponse({ type: 'text', text: 'Answer before stop hook.' });
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'hello' }] });
+    await waitForFile(marker);
+    await ctx.rpc.cancel({ turnId: 0 });
+    const events = await ctx.untilTurnEnd();
+
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: expect.objectContaining({ reason: 'cancelled' }),
+      }),
+    );
+    expect(ctx.llmCalls).toHaveLength(1);
+    expect(JSON.stringify(ctx.agent.context.data().history)).not.toContain('late stop hook');
+  });
+
+  it('cancels while waiting for a PreToolUse hook before permission fallback', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'kimi-pre-tool-hook-'));
+    const marker = join(dir, 'started');
+    const script = [
+      "const fs=require('node:fs');",
+      `fs.writeFileSync(${JSON.stringify(marker)}, 'started');`,
+      "setTimeout(() => process.stdout.write('late pre tool hook'), 250);",
+    ].join('');
+    const execWithEnv = vi.fn().mockRejectedValue(new Error('Bash should not execute'));
+    const hookEngine = new HookEngine([
+      {
+        event: 'PreToolUse',
+        matcher: 'Bash',
+        command: `node -e ${JSON.stringify(script)}`,
+        timeout: 5,
+      },
+    ]);
+    const ctx = testAgent({
+      kaos: createFakeKaos({ execWithEnv }),
+      hookEngine,
+    });
+    const beforeToolCall = vi.spyOn(ctx.agent.permission, 'beforeToolCall');
+    ctx.configure({ tools: ['Bash'] });
+    await ctx.rpc.setPermission({ mode: 'auto' });
+    ctx.newEvents();
+    ctx.mockNextResponse({ type: 'text', text: 'I will run Bash.' }, bashCall());
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Run Bash while hook sleeps' }] });
+    await waitForFile(marker);
+    await ctx.rpc.cancel({ turnId: 0 });
+    const events = await ctx.untilTurnEnd();
+
+    expect(beforeToolCall).not.toHaveBeenCalled();
+    expect(execWithEnv).not.toHaveBeenCalled();
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: expect.objectContaining({ reason: 'cancelled' }),
+      }),
+    );
+    expect(JSON.stringify(ctx.agent.context.data().history)).not.toContain('late pre tool hook');
+  });
+
+  it('fires StopFailure when a turn fails', async () => {
+    const triggered: Array<[string, string, number]> = [];
+    const hookEngine = new HookEngine(
+      [
+        {
+          event: 'StopFailure',
+          matcher: 'Error',
+          command: 'exit 0',
+        },
+      ],
+      {
+        onTriggered: (event, target, count) => {
+          triggered.push([event, target, count]);
+        },
+      },
+    );
+    const ctx = testAgent({ hookEngine });
+    ctx.configure();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Trigger generate failure' }] });
+    await ctx.untilTurnEnd();
+
+    expect(triggered).toEqual([['StopFailure', 'Error', 1]]);
+  });
+
+  it('resolves the latest request-scoped OAuth auth before each generation', async () => {
+    const tokenCalls: Array<boolean | undefined> = [];
+    const authKeys: string[] = [];
+    const tokens = ['initial-oauth-token', 'first-turn-token', 'second-turn-token'];
+    const providerManager = createOAuthProviderManager(async (options) => {
+      tokenCalls.push(options?.force);
+      const token = tokens.shift();
+      if (token === undefined) throw new Error('unexpected token request');
+      return token;
+    });
+    const generate: GenerateFn = async (
+      _provider,
+      _system,
+      _tools,
+      _history,
+      callbacks,
+      options,
+    ) => {
+      const apiKey = options?.auth?.apiKey ?? '<missing>';
+      authKeys.push(apiKey);
+      const text = `Generated with ${apiKey}`;
+      await callbacks?.onMessagePart?.({ type: 'text', text });
+      return textResult(text);
+    };
+    const ctx = testAgent({ providerManager, generate });
+    ctx.configure();
+    await ctx.rpc.setModel({ model: 'kimi-code' });
+    ctx.newEvents();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'hello' }] });
+    const firstEvents = await ctx.untilTurnEnd();
+    ctx.newEvents();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'hello again' }] });
+    const secondEvents = await ctx.untilTurnEnd();
+
+    expect(authKeys).toEqual(['first-turn-token', 'second-turn-token']);
+    expect(tokenCalls).toEqual([undefined, undefined, undefined]);
+    expect(firstEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'assistant.delta',
+        args: { turnId: 0, delta: 'Generated with first-turn-token' },
+      }),
+    );
+    expect(secondEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'assistant.delta',
+        args: { turnId: 1, delta: 'Generated with second-turn-token' },
+      }),
+    );
+    expect(firstEvents).not.toContainEqual(
+      expect.objectContaining({ event: 'turn.step.interrupted' }),
+    );
+    expect(secondEvents).not.toContainEqual(
+      expect.objectContaining({ event: 'turn.step.interrupted' }),
+    );
+  });
+
+  it('logs LLM request metadata without message bodies', async () => {
+    const { logger, entries } = captureLogs();
+    const ctx = testAgent({ log: logger });
+    ctx.configure();
+    ctx.mockNextResponse({ type: 'text', text: 'done' });
+
+    await ctx.rpc.prompt({
+      input: [{ type: 'text', text: 'secret prompt body should stay out of logs' }],
+    });
+    await ctx.untilTurnEnd();
+
+    const configLogs = entries.filter((entry) => entry.message === 'llm config');
+    expect(configLogs).toHaveLength(1);
+    const configPayload = configLogs[0]?.payload as Record<string, unknown>;
+    expect(configPayload).toMatchObject({
+      turnId: '0',
+      step: 1,
+      provider: 'kimi',
+      model: 'mock-model',
+      modelAlias: 'mock-model',
+      toolCount: 0,
+    });
+    expect(configPayload['systemPromptChars']).toEqual(expect.any(Number));
+
+    const requestLogs = entries.filter((entry) => entry.message === 'llm request');
+    expect(requestLogs).toHaveLength(1);
+    const payload = requestLogs[0]?.payload as Record<string, unknown>;
+    expect(payload).toMatchObject({
+      turnId: '0',
+      step: 1,
+      messageCount: 1,
+      toolCallCount: 0,
+    });
+    expect(payload['estimatedInputTokens']).toEqual(expect.any(Number));
+    expect(payload).not.toHaveProperty('attempt');
+    expect(payload).not.toHaveProperty('maxAttempts');
+    expect(payload).not.toHaveProperty('stepUuid');
+    expect(payload).not.toHaveProperty('model');
+    expect(payload).not.toHaveProperty('provider');
+    expect(payload).not.toHaveProperty('modelAlias');
+    expect(payload).not.toHaveProperty('thinkingEffort');
+    expect(payload).not.toHaveProperty('systemPromptChars');
+    expect(payload).not.toHaveProperty('partialMessageCount');
+    expect(payload).not.toHaveProperty('toolCount');
+    expect(payload).not.toHaveProperty('systemPromptHash');
+    expect(payload).not.toHaveProperty('toolsHash');
+    expect(payload).not.toHaveProperty('messageRoles');
+    expect(payload).not.toHaveProperty('contentPartTypes');
+    expect(payload).not.toHaveProperty('toolNames');
+    expect(payload).not.toHaveProperty('history');
+    expect(payload).not.toHaveProperty('systemPrompt');
+    expect(JSON.stringify(entries)).not.toContain('secret prompt body should stay out of logs');
+  });
+
+  it('does not repeat unchanged LLM config metadata', async () => {
+    const { logger, entries } = captureLogs();
+    const ctx = testAgent({ log: logger });
+    ctx.configure();
+
+    ctx.mockNextResponse({ type: 'text', text: 'first' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'first prompt' }] });
+    await ctx.untilTurnEnd();
+
+    ctx.mockNextResponse({ type: 'text', text: 'second' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'second prompt' }] });
+    await ctx.untilTurnEnd();
+
+    expect(entries.filter((entry) => entry.message === 'llm config')).toHaveLength(1);
+    expect(entries.filter((entry) => entry.message === 'llm request')).toHaveLength(2);
+  });
+
+  it('logs changed LLM config when same-size system prompt content changes', async () => {
+    const { logger, entries } = captureLogs();
+    const ctx = testAgent({ log: logger });
+    ctx.configure();
+
+    ctx.agent.config.update({ systemPrompt: 'alpha' });
+    ctx.mockNextResponse({ type: 'text', text: 'first' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'first prompt' }] });
+    await ctx.untilTurnEnd();
+
+    ctx.agent.config.update({ systemPrompt: 'bravo' });
+    ctx.mockNextResponse({ type: 'text', text: 'second' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'second prompt' }] });
+    await ctx.untilTurnEnd();
+
+    const configPayloads = entries
+      .filter((entry) => entry.message === 'llm config')
+      .map((entry) => entry.payload as Record<string, unknown>);
+    expect(configPayloads).toHaveLength(2);
+    expect(configPayloads.map((payload) => payload['systemPromptChars'])).toEqual([5, 5]);
+    for (const payload of configPayloads) {
+      expect(payload).not.toHaveProperty('systemPromptHash');
+      expect(payload).not.toHaveProperty('toolsHash');
+    }
+  });
+
+  it('includes tool schemas in estimated LLM request tokens', async () => {
+    const { logger, entries } = captureLogs();
+    const ctx = testAgent({ log: logger });
+    ctx.configure();
+    await ctx.rpc.setActiveTools({ names: ['Bash'] });
+    ctx.mockNextResponse({ type: 'text', text: 'done' });
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'use bash' }] });
+    await ctx.untilTurnEnd();
+
+    const input = ctx.llmCalls[0];
+    expect(input?.tools.length).toBeGreaterThan(0);
+    const expectedTokens =
+      estimateTokens(input!.systemPrompt) +
+      estimateTokensForMessages(input!.history) +
+      estimateTokensForTools(input!.tools);
+    const requestPayload = entries.find((entry) => entry.message === 'llm request')?.payload as
+      | Record<string, unknown>
+      | undefined;
+    expect(requestPayload?.['estimatedInputTokens']).toBe(expectedTokens);
+  });
+
+  it('classifies OAuth resolver failures as auth errors', async () => {
+    const tokenCalls: Array<boolean | undefined> = [];
+    const tokens = ['initial-oauth-token'];
+    const providerManager = createOAuthProviderManager(async (options) => {
+      tokenCalls.push(options?.force);
+      const token = tokens.shift();
+      if (token === undefined) throw new Error('refresh token expired');
+      return token;
+    });
+    const generate = vi.fn<GenerateFn>();
+    const ctx = testAgent({ providerManager, generate });
+    ctx.configure();
+    await ctx.rpc.setModel({ model: 'kimi-code' });
+    ctx.newEvents();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'hello after token expiry' }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(tokenCalls).toEqual([undefined, undefined]);
+    expect(generate).not.toHaveBeenCalled();
+    expect(events).not.toContainEqual(expect.objectContaining({ event: 'assistant.delta' }));
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: expect.objectContaining({
+          reason: 'failed',
+          error: expect.objectContaining({
+            code: 'auth.login_required',
+          }),
+        }),
+      }),
+    );
+  });
+
+  it('honors configured maxStepsPerTurn in agent turns', async () => {
+    const providerManager = new ProviderManager({
+      config: {
+        providers: {},
+        loopControl: {
+          maxStepsPerTurn: 1,
+        },
+      },
+    });
+    const ctx = testAgent({
+      providerManager,
+      kaos: createCommandKaos('loop-output'),
+    });
+    ctx.configure({ tools: ['Bash'] });
+    await ctx.rpc.setPermission({ mode: 'yolo' });
+    ctx.newEvents();
+
+    const bashCall: ToolCall = {
+      id: 'call_bash',
+      type: 'function',
+      function: {
+        name: 'Bash',
+        arguments: '{"command":"printf loop-output","timeout":60}',
+      },
+    };
+    ctx.mockNextResponse(bashCall);
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Run a command once' }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(ctx.llmCalls).toHaveLength(1);
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: expect.objectContaining({
+          reason: 'failed',
+          error: expect.objectContaining({
+            code: 'loop.max_steps_exceeded',
+            details: expect.objectContaining({
+              maxSteps: 1,
+            }),
+          }),
+        }),
+      }),
+    );
+  });
+
+  it('force-refreshes OAuth credentials and replays the request on 401', async () => {
+    const tokenCalls: Array<boolean | undefined> = [];
+    const authKeys: string[] = [];
+    const providerManager = createOAuthProviderManager(async (options) => {
+      tokenCalls.push(options?.force);
+      return options?.force === true ? 'forced-refresh-token' : 'fresh-token';
+    });
+    const generate: GenerateFn = async (
+      _provider,
+      _system,
+      _tools,
+      _history,
+      callbacks,
+      options,
+    ) => {
+      const apiKey = options?.auth?.apiKey ?? '<missing>';
+      authKeys.push(apiKey);
+      if (authKeys.length === 1) throw new APIStatusError(401, 'Unauthorized', 'req-401');
+      const text = `Generated with ${apiKey}`;
+      await callbacks?.onMessagePart?.({ type: 'text', text });
+      return textResult(text);
+    };
+    const ctx = testAgent({ providerManager, generate });
+    ctx.configure();
+    await ctx.rpc.setModel({ model: 'kimi-code' });
+    ctx.newEvents();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'hello after token expiry' }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(authKeys).toEqual(['fresh-token', 'forced-refresh-token']);
+    expect(tokenCalls).toEqual([undefined, undefined, true]);
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'assistant.delta',
+        args: { turnId: 0, delta: 'Generated with forced-refresh-token' },
+      }),
+    );
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: expect.objectContaining({ reason: 'completed' }),
+      }),
+    );
+  });
+
+  it('falls back to login_required when force-refresh and replay both 401', async () => {
+    const tokenCalls: Array<boolean | undefined> = [];
+    const authKeys: string[] = [];
+    const providerManager = createOAuthProviderManager(
+      async (options) => {
+        tokenCalls.push(options?.force);
+        return options?.force === true ? 'forced-refresh-token' : 'fresh-token';
+      },
+      ['image_in', 'video_in', 'tool_use'],
+    );
+    const generate: GenerateFn = async (
+      _provider,
+      _system,
+      _tools,
+      _history,
+      _callbacks,
+      options,
+    ) => {
+      authKeys.push(options?.auth?.apiKey ?? '<missing>');
+      throw new APIStatusError(401, 'Unauthorized', 'req-401');
+    };
+    const ctx = testAgent({ providerManager, generate });
+    ctx.configure();
+    await ctx.rpc.setModel({ model: 'kimi-code' });
+    ctx.newEvents();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'hello' }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(authKeys).toEqual(['fresh-token', 'forced-refresh-token']);
+    expect(tokenCalls).toEqual([undefined, undefined, true]);
+    expect(events).not.toContainEqual(expect.objectContaining({ event: 'assistant.delta' }));
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: expect.objectContaining({
+          reason: 'failed',
+          error: expect.objectContaining({
+            code: 'auth.login_required',
+            details: expect.objectContaining({
+              statusCode: 401,
+              requestId: 'req-401',
+            }),
+          }),
+        }),
+      }),
+    );
+  });
+
+  it('keeps non-OAuth provider 401 as provider auth error', async () => {
+    const generate: GenerateFn = async () => {
+      throw new APIStatusError(401, 'Unauthorized', 'req-api-key-401');
+    };
+    const ctx = testAgent({ generate });
+    ctx.configure();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'hello' }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: expect.objectContaining({
+          reason: 'failed',
+          error: expect.objectContaining({
+            code: 'provider.auth_error',
+            details: expect.objectContaining({
+              statusCode: 401,
+              requestId: 'req-api-key-401',
+            }),
+          }),
+        }),
+      }),
+    );
+  });
+
+  it.each<ApiErrorTelemetryCase>([
+    {
+      name: '429 status',
+      createError: () => new APIStatusError(429, 'Rate limited', 'req-429'),
+      errorType: 'rate_limit',
+      statusCode: 429,
+    },
+    {
+      name: '401 status',
+      createError: () => new APIStatusError(401, 'Unauthorized', 'req-401'),
+      errorType: 'auth',
+      statusCode: 401,
+    },
+    {
+      name: '403 status',
+      createError: () => new APIStatusError(403, 'Forbidden', 'req-403'),
+      errorType: 'auth',
+      statusCode: 403,
+    },
+    {
+      name: '500 status',
+      createError: () => new APIStatusError(500, 'Internal server error', 'req-500'),
+      errorType: '5xx_server',
+      statusCode: 500,
+    },
+    {
+      name: '400 status',
+      createError: () => new APIStatusError(400, 'Bad request', 'req-400'),
+      errorType: '4xx_client',
+      statusCode: 400,
+    },
+    {
+      name: 'context overflow status',
+      createError: () => new APIStatusError(422, 'Maximum context window exceeded', 'req-422'),
+      errorType: 'context_overflow',
+      statusCode: 422,
+    },
+    {
+      name: 'connection error',
+      createError: () => new APIConnectionError('socket hang up'),
+      errorType: 'network',
+    },
+    {
+      name: 'timeout error',
+      createError: () => new APITimeoutError('request timed out'),
+      errorType: 'timeout',
+    },
+    {
+      name: 'empty response error',
+      createError: () => new APIEmptyResponseError('empty response'),
+      errorType: 'empty_response',
+    },
+    {
+      name: 'generic step error',
+      createError: () => new Error('unexpected step failure'),
+      errorType: 'other',
+    },
+  ])('tracks api_error telemetry for $name', async ({ createError, errorType, statusCode }) => {
+    const records: TelemetryRecord[] = [];
+    const generate: GenerateFn = async () => {
+      throw createError();
+    };
+    const ctx = testAgent({
+      generate,
+      providerManager: createSingleAttemptProviderManager(),
+      telemetry: recordingTelemetry(records),
+    });
+    ctx.configure();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'trigger provider error' }] });
+    await ctx.untilTurnEnd();
+
+    const expectedProperties: Record<string, unknown> = {
+      error_type: errorType,
+      model: 'mock-model',
+      retryable: expect.any(Boolean),
+      duration_ms: expect.any(Number),
+    };
+    if (statusCode !== undefined) {
+      expectedProperties['status_code'] = statusCode;
+    }
+
+    const record = records.find((candidate) => candidate.event === 'api_error');
+    expect(record).toEqual({
+      event: 'api_error',
+      properties: expect.objectContaining(expectedProperties),
+    });
+    if (statusCode === undefined) {
+      expect(record?.properties).not.toHaveProperty('status_code');
+    }
+  });
+
+  it('keeps transient retry handling with request-scoped OAuth auth', async () => {
+    const { logger, entries } = captureLogs();
+    const authKeys: string[] = [];
+    const providerManager = createOAuthProviderManager(async () => 'fresh-token');
+    const generate: GenerateFn = async (
+      _provider,
+      _system,
+      _tools,
+      _history,
+      callbacks,
+      options,
+    ) => {
+      authKeys.push(options?.auth?.apiKey ?? '<missing>');
+      if (authKeys.length === 1) {
+        throw new APIConnectionError('socket hang up');
+      }
+      await callbacks?.onMessagePart?.({ type: 'text', text: 'Recovered after retry' });
+      return textResult('Recovered after retry');
+    };
+    const ctx = testAgent({ providerManager, generate, log: logger });
+    ctx.configure();
+    await ctx.rpc.setModel({ model: 'kimi-code' });
+    ctx.newEvents();
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'hello' }] });
+    const events = await ctx.untilTurnEnd();
+
+    expect(authKeys).toEqual(['fresh-token', 'fresh-token']);
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.step.retrying',
+        args: expect.objectContaining({
+          failedAttempt: 1,
+          nextAttempt: 2,
+          errorName: 'APIConnectionError',
+        }),
+      }),
+    );
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'assistant.delta',
+        args: { turnId: 0, delta: 'Recovered after retry' },
+      }),
+    );
+    const requestLogs = entries.filter((entry) => entry.message === 'llm request');
+    expect(requestLogs.map((entry) => entry.payload)).toEqual([
+      expect.not.objectContaining({ attempt: expect.any(Number), maxAttempts: expect.any(Number) }),
+      expect.objectContaining({ attempt: 2, maxAttempts: 3 }),
+    ]);
+  });
+
+  it('force-refreshes OAuth credentials on video upload 401 and falls back to login_required when replay 401', async () => {
+    const tokenCalls: Array<boolean | undefined> = [];
+    const authKeys: string[] = [];
+    const providerManager = createOAuthProviderManager(
+      async (options) => {
+        tokenCalls.push(options?.force);
+        return options?.force === true ? 'forced-refresh-token' : 'fresh-token';
+      },
+      ['image_in', 'video_in', 'tool_use'],
+    );
+    const provider = {
+      uploadVideo: vi.fn().mockImplementation(async (_input, options) => {
+        authKeys.push(options?.auth?.apiKey ?? '<missing>');
+        throw new APIStatusError(401, 'Unauthorized', 'req-upload-401');
+      }),
+    } as unknown as ChatProvider;
+    const ctx = testAgent({
+      kaos: createVideoKaos(),
+      providerManager,
+    });
+    ctx.agent.config.update({
+      cwd: process.cwd(),
+      modelAlias: 'kimi-code',
+      systemPrompt: 'test system prompt',
+      thinkingLevel: 'off',
+    });
+    Object.defineProperty(ctx.agent.config, 'provider', {
+      configurable: true,
+      get: () => provider,
+    });
+    ctx.agent.tools.initializeBuiltinTools();
+    ctx.agent.tools.setActiveTools(['ReadMediaFile']);
+
+    const tool = ctx.agent.tools.loopTools.find((candidate) => candidate.name === 'ReadMediaFile');
+    if (tool === undefined) throw new Error('ReadMediaFile tool was not initialized');
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'call_media',
+      args: { path: '/workspace/sample.mp4' },
+      signal: new AbortController().signal,
+    });
+
+    expect(result.isError).toBe(true);
+    expect(authKeys).toEqual(['fresh-token', 'forced-refresh-token']);
+    expect(tokenCalls).toEqual([undefined, true]);
+    expect(result.output).toContain('OAuth provider credentials were rejected');
+    expect(result.output).toContain('Send /login to login');
+  });
+
+  it('cancels an active turn', async () => {
+    const records: TelemetryRecord[] = [];
+    const ctx = testAgent({
+      kaos: createCommandKaos('should-not-run'),
+      telemetry: recordingTelemetry(records),
+    });
+    ctx.configure({ tools: ['Bash'] });
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will run Bash.' }, bashCall());
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Run a command' }] });
+
+    expect(await ctx.untilApprovalRequest()).toMatchInlineSnapshot(`
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Run a command" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Run a command" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "I will run Bash." }
+      [emit] tool.call.delta             { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "argumentsPart": "{\\"command\\":\\"printf should-not-run\\",\\"timeout\\":60}" }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "I will run Bash." } }, "time": "<time>" }
+      [emit] requestApproval             { "turnId": 0, "toolCallId": "call_bash", "toolName": "Bash", "action": "run command", "display": { "kind": "generic", "summary": "Approve Bash", "detail": { "command": "printf should-not-run", "timeout": 60 } } }
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: Bash
+      messages:
+        user: text "Run a command"
+    `);
+    records.length = 0;
+    await ctx.rpc.cancel({ turnId: 0 });
+    expect(records).toContainEqual({
+      event: 'cancel',
+      properties: { from: 'streaming' },
+    });
+
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] turn.cancel                 { "turnId": 0, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "tool.call", "uuid": "call_bash", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf should-not-run", "timeout": 60 } }, "time": "<time>" }
+      [emit] tool.call.started           { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf should-not-run", "timeout": 60 } }
+      [wire] context.append_loop_event   { "event": { "type": "tool.result", "parentUuid": "call_bash", "toolCallId": "call_bash", "result": { "output": "Tool \\"Bash\\" was aborted during prepareToolExecution hook", "isError": true } }, "time": "<time>" }
+      [emit] tool.result                 { "turnId": 0, "toolCallId": "call_bash", "output": "Tool \\"Bash\\" was aborted during prepareToolExecution hook", "isError": true }
+      [emit] turn.step.interrupted       { "turnId": 0, "step": 1, "reason": "aborted" }
+      [emit] turn.ended                  { "turnId": 0, "reason": "cancelled" }
+    `);
+    expect(records).toContainEqual({
+      event: 'tool_call',
+      properties: expect.objectContaining({
+        tool_name: 'Bash',
+        outcome: 'cancelled',
+        dup_type: 'normal',
+        duration_ms: expect.any(Number),
+      }),
+    });
+    await ctx.expectResumeMatches();
+  });
+
+  it('buffers steer input and includes it in the same turn after approval', async () => {
+    const bashCall: ToolCall = {
+      type: 'function',
+      id: 'call_bash',
+      function: {
+        name: 'Bash',
+        arguments: '{"command":"printf approved","timeout":60}',
+      },
+    };
+    const ctx = testAgent({
+      kaos: createCommandKaos('approved'),
+    });
+    ctx.configure({ tools: ['Bash'] });
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will ask first.' }, bashCall);
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Run Bash, then listen' }] });
+
+    const approval = await ctx.takeApprovalRequest();
+    expect(approval.events).toMatchInlineSnapshot(`
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Run Bash, then listen" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Run Bash, then listen" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "I will ask first." }
+      [emit] tool.call.delta             { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "argumentsPart": "{\\"command\\":\\"printf approved\\",\\"timeout\\":60}" }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "I will ask first." } }, "time": "<time>" }
+      [emit] requestApproval             { "turnId": 0, "toolCallId": "call_bash", "toolName": "Bash", "action": "run command", "display": { "kind": "generic", "summary": "Approve Bash", "detail": { "command": "printf approved", "timeout": 60 } } }
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: Bash
+      messages:
+        user: text "Run Bash, then listen"
+    `);
+    expect(ctx.llmCalls).toHaveLength(1);
+
+    await ctx.rpc.steer({ input: [{ type: 'text', text: 'Also mention the steer.' }] });
+    expect(ctx.llmCalls).toHaveLength(1);
+    expect(ctx.newEvents()).toMatchInlineSnapshot(`[wire] turn.steer   { "input": [ { "type": "text", "text": "Also mention the steer." } ], "origin": { "kind": "user" }, "time": "<time>" }`);
+
+    ctx.mockNextResponse({ type: 'text', text: 'Approved, and I saw the steer.' });
+    approval.respond({
+      decision: 'approved',
+      selectedLabel: 'approve',
+    });
+
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] permission.record_approval_result   { "turnId": 0, "toolCallId": "call_bash", "toolName": "Bash", "action": "run command", "result": { "decision": "approved", "selectedLabel": "approve" }, "time": "<time>" }
+      [wire] context.append_loop_event           { "event": { "type": "tool.call", "uuid": "call_bash", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf approved", "timeout": 60 }, "description": "Running: printf approved" }, "time": "<time>" }
+      [emit] tool.call.started                   { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf approved", "timeout": 60 }, "description": "Running: printf approved" }
+      [wire] context.append_loop_event           { "event": { "type": "tool.result", "parentUuid": "call_bash", "toolCallId": "call_bash", "result": { "output": "approved" } }, "time": "<time>" }
+      [emit] tool.result                         { "turnId": 0, "toolCallId": "call_bash", "output": "approved" }
+      [wire] context.append_loop_event           { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "usage": { "inputOther": 7, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }, "time": "<time>" }
+      [emit] turn.step.completed                 { "turnId": 0, "step": 1, "stepId": "<uuid-1>", "usage": { "inputOther": 7, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }
+      [wire] usage.record                        { "model": "mock-model", "usage": { "inputOther": 7, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated                { "model": "mock-model", "contextTokens": 29, "maxContextTokens": 1000000, "contextUsage": 0.000029, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 7, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 7, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 7, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] context.append_message              { "message": { "role": "user", "content": [ { "type": "text", "text": "Also mention the steer." } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_loop_event           { "event": { "type": "step.begin", "uuid": "<uuid-3>", "turnId": "0", "step": 2 }, "time": "<time>" }
+      [emit] turn.step.started                   { "turnId": 0, "step": 2, "stepId": "<uuid-3>" }
+      [emit] assistant.delta                     { "turnId": 0, "delta": "Approved, and I saw the steer." }
+      [wire] context.append_loop_event           { "event": { "type": "content.part", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "stepUuid": "<uuid-3>", "part": { "type": "text", "text": "Approved, and I saw the steer." } }, "time": "<time>" }
+      [wire] context.append_loop_event           { "event": { "type": "step.end", "uuid": "<uuid-3>", "turnId": "0", "step": 2, "usage": { "inputOther": 39, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+      [emit] turn.step.completed                 { "turnId": 0, "step": 2, "stepId": "<uuid-3>", "usage": { "inputOther": 39, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+      [wire] usage.record                        { "model": "mock-model", "usage": { "inputOther": 39, "output": 11, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated                { "model": "mock-model", "contextTokens": 50, "maxContextTokens": 1000000, "contextUsage": 0.00005, "planMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 46, "output": 33, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 46, "output": 33, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 46, "output": 33, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [emit] turn.ended                          { "turnId": 0, "reason": "completed" }
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      messages:
+        <last>
+        assistant: text "I will ask first."  calls call_bash:Bash { "command": "printf approved", "timeout": 60 }
+        tool[call_bash]: text "approved"
+        user: text "Also mention the steer."
+    `);
+    expect(ctx.llmCalls).toHaveLength(2);
+    await ctx.expectResumeMatches();
+  });
+
+  it('rejects a non-steer prompt while a turn is active', async () => {
+    const ctx = testAgent({ kaos: createCommandKaos('should-not-run') });
+    ctx.configure({ tools: ['Bash'] });
+
+    ctx.mockNextResponse({ type: 'text', text: 'I will wait for approval.' }, bashCall());
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Start the active turn' }] });
+
+    expect(await ctx.untilApprovalRequest()).toMatchInlineSnapshot(`
+      [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Start the active turn" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" } }
+      [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Start the active turn" } ], "toolCalls": [], "origin": { "kind": "user" } }, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "step.begin", "uuid": "<uuid-1>", "turnId": "0", "step": 1 }, "time": "<time>" }
+      [emit] turn.step.started           { "turnId": 0, "step": 1, "stepId": "<uuid-1>" }
+      [emit] assistant.delta             { "turnId": 0, "delta": "I will wait for approval." }
+      [emit] tool.call.delta             { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "argumentsPart": "{\\"command\\":\\"printf should-not-run\\",\\"timeout\\":60}" }
+      [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "I will wait for approval." } }, "time": "<time>" }
+      [emit] requestApproval             { "turnId": 0, "toolCallId": "call_bash", "toolName": "Bash", "action": "run command", "display": { "kind": "generic", "summary": "Approve Bash", "detail": { "command": "printf should-not-run", "timeout": 60 } } }
+    `);
+    expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
+      system: <system-prompt>
+      tools: Bash
+      messages:
+        user: text "Start the active turn"
+    `);
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'This should not start a new turn' }] });
+
+    expect(ctx.newEvents()).toMatchInlineSnapshot(`
+      [wire] turn.prompt   { "input": [ { "type": "text", "text": "This should not start a new turn" } ], "origin": { "kind": "user" }, "time": "<time>" }
+      [emit] error         { "code": "turn.agent_busy", "message": "Cannot launch a new turn while another turn (ID 0) is active", "details": { "turnId": 0 }, "retryable": true }
+    `);
+    await ctx.rpc.cancel({ turnId: 0 });
+    expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] turn.cancel                 { "turnId": 0, "time": "<time>" }
+      [wire] context.append_loop_event   { "event": { "type": "tool.call", "uuid": "call_bash", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf should-not-run", "timeout": 60 } }, "time": "<time>" }
+      [emit] tool.call.started           { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf should-not-run", "timeout": 60 } }
+      [wire] context.append_loop_event   { "event": { "type": "tool.result", "parentUuid": "call_bash", "toolCallId": "call_bash", "result": { "output": "Tool \\"Bash\\" was aborted during prepareToolExecution hook", "isError": true } }, "time": "<time>" }
+      [emit] tool.result                 { "turnId": 0, "toolCallId": "call_bash", "output": "Tool \\"Bash\\" was aborted during prepareToolExecution hook", "isError": true }
+      [emit] turn.step.interrupted       { "turnId": 0, "step": 1, "reason": "aborted" }
+      [emit] turn.ended                  { "turnId": 0, "reason": "cancelled" }
+    `);
+    await ctx.expectResumeMatches();
+  });
+});
+
+function bashCall(): ToolCall {
+  return bashCallWithId('call_bash', 'printf should-not-run');
+}
+
+function bashCallWithId(id: string, command: string): ToolCall {
+  return {
+    type: 'function',
+    id,
+    function: {
+      name: 'Bash',
+      arguments: JSON.stringify({ command, timeout: 60 }),
+    },
+  };
+}
+
+interface ApiErrorTelemetryCase {
+  readonly name: string;
+  readonly createError: () => Error;
+  readonly errorType: string;
+  readonly statusCode?: number;
+}
+
+function createSingleAttemptProviderManager(): ProviderManager {
+  return new ProviderManager({
+    config: {
+      providers: {},
+      loopControl: {
+        maxRetriesPerStep: 1,
+      },
+    },
+  });
+}
+
+const MP4_HEADER = Buffer.concat([
+  Buffer.from([0x00, 0x00, 0x00, 0x18]),
+  Buffer.from('ftyp'),
+  Buffer.from('mp42'),
+  Buffer.from([0x00, 0x00, 0x00, 0x00]),
+  Buffer.from('mp42isom'),
+]);
+
+const DEFAULT_MEDIA_STAT = {
+  stMode: 0o100644,
+  stIno: 0,
+  stDev: 0,
+  stNlink: 1,
+  stUid: 0,
+  stGid: 0,
+  stSize: MP4_HEADER.length,
+  stAtime: 0,
+  stMtime: 0,
+  stCtime: 0,
+};
+
+function createVideoKaos(): Kaos {
+  return createFakeKaos({
+    stat: vi.fn<Kaos['stat']>().mockResolvedValue(DEFAULT_MEDIA_STAT),
+    readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(MP4_HEADER),
+  });
+}
+
+async function waitForFile(path: string): Promise<void> {
+  for (let i = 0; i < 100; i++) {
+    if (existsSync(path)) return;
+    await delay(10);
+  }
+  throw new Error(`Timed out waiting for ${path}`);
+}
+
+function mediaCapabilities(): ModelCapability {
+  return {
+    image_in: true,
+    video_in: true,
+    audio_in: false,
+    thinking: false,
+    tool_use: true,
+    max_context_tokens: 1_000_000,
+  };
+}
+
+function createOAuthProviderManager(
+  getAccessToken: (options?: { readonly force?: boolean }) => Promise<string>,
+  capabilities?: readonly string[] | undefined,
+): ProviderManager {
+  const oauthConfig: KimiConfig = {
+    defaultModel: 'kimi-code',
+    providers: {
+      'managed:kimi-code': {
+        type: 'vertexai',
+        baseUrl: 'https://api.example/v1',
+        oauth: { storage: 'file', key: 'oauth/kimi-code' },
+      },
+    },
+    models: {
+      'kimi-code': {
+        provider: 'managed:kimi-code',
+        model: 'kimi-for-coding',
+        maxContextSize: 1_000_000,
+        capabilities: capabilities === undefined ? undefined : [...capabilities],
+      },
+    },
+  };
+  return new ProviderManager({
+    config: oauthConfig,
+    resolveOAuthTokenProvider: vi.fn(() => ({ getAccessToken })),
+  });
+}
+
+function textResult(text: string): Awaited<ReturnType<GenerateFn>> {
+  return {
+    id: 'mock-oauth-retry',
+    message: {
+      role: 'assistant',
+      content: [{ type: 'text', text }],
+      toolCalls: [],
+    },
+    usage: {
+      inputOther: 1,
+      output: 1,
+      inputCacheRead: 0,
+      inputCacheCreation: 0,
+    },
+    finishReason: 'completed',
+    rawFinishReason: 'stop',
+  };
+}
diff --git a/packages/agent-core/test/agent/turn/tool-dedup.test.ts b/packages/agent-core/test/agent/turn/tool-dedup.test.ts
new file mode 100644
index 000000000..964f0e4b0
--- /dev/null
+++ b/packages/agent-core/test/agent/turn/tool-dedup.test.ts
@@ -0,0 +1,290 @@
+import { describe, expect, it } from 'vitest';
+
+import type { ExecutableToolResult } from '../../../src/loop/types';
+import { ToolCallDeduplicator, __testing } from '../../../src/agent/turn/tool-dedup';
+
+const { REMINDER_TEXT, CROSS_STEP_DEDUP_TRIGGER_COUNT } = __testing;
+
+function okResult(text: string): ExecutableToolResult {
+  return { output: text };
+}
+
+function errResult(text: string): ExecutableToolResult {
+  return { output: text, isError: true };
+}
+
+/**
+ * Drives one full lifecycle for a single (original) tool call:
+ * beginStep is the caller's responsibility — this only handles checkSameStep
+ * + finalizeResult for the original (first-occurrence) call.
+ */
+async function runOriginal(
+  deduper: ToolCallDeduplicator,
+  callId: string,
+  tool: string,
+  args: unknown,
+  result: ExecutableToolResult,
+): Promise<ExecutableToolResult> {
+  const cached = deduper.checkSameStep(callId, tool, args);
+  expect(cached).toBeNull();
+  return deduper.finalizeResult(callId, tool, args, result);
+}
+
+describe('ToolCallDeduplicator', () => {
+  describe('same-step dedup', () => {
+    it('returns a placeholder synchronously and resolves to the real result on finalize', async () => {
+      const dedup = new ToolCallDeduplicator();
+      dedup.beginStep();
+      const original = await runOriginal(dedup, 'c1', 'Read', { path: '/a' }, okResult('FILE_A'));
+      const cached = dedup.checkSameStep('c2', 'Read', { path: '/a' });
+      // Same-step dup gets a synthetic placeholder (non-error, empty string).
+      expect(cached).not.toBeNull();
+      expect(cached!.isError).toBeUndefined();
+      // Finalize substitutes the original's real result.
+      const finalDup = await dedup.finalizeResult('c2', 'Read', { path: '/a' }, cached!);
+      expect(finalDup).toEqual(original);
+    });
+
+    it('propagates error results to same-step dups', async () => {
+      const dedup = new ToolCallDeduplicator();
+      dedup.beginStep();
+      await runOriginal(dedup, 'c1', 'Bash', { cmd: 'x' }, errResult('boom'));
+      const cached = dedup.checkSameStep('c2', 'Bash', { cmd: 'x' });
+      expect(cached).not.toBeNull();
+      const finalDup = await dedup.finalizeResult('c2', 'Bash', { cmd: 'x' }, cached!);
+      expect(finalDup).toEqual(errResult('boom'));
+    });
+
+    it('finalizes original before dup (provider order)', async () => {
+      // The loop guarantees finalize runs in provider order, so by the time a
+      // dup's finalize runs, the original's deferred is already resolved.
+      const dedup = new ToolCallDeduplicator();
+      dedup.beginStep();
+      const origCached = dedup.checkSameStep('c1', 'Read', { path: '/a' });
+      expect(origCached).toBeNull();
+      const dupCached = dedup.checkSameStep('c2', 'Read', { path: '/a' });
+      expect(dupCached).not.toBeNull();
+      // Finalize in provider order: c1 first, then c2.
+      const origFinal = await dedup.finalizeResult('c1', 'Read', { path: '/a' }, okResult('A'));
+      const dupFinal = await dedup.finalizeResult('c2', 'Read', { path: '/a' }, dupCached!);
+      expect(origFinal).toEqual(okResult('A'));
+      expect(dupFinal).toEqual(okResult('A'));
+    });
+  });
+
+  describe('cross-step streak', () => {
+    it(`does not inject reminder below ${String(CROSS_STEP_DEDUP_TRIGGER_COUNT)} consecutive`, async () => {
+      const dedup = new ToolCallDeduplicator();
+      let last: ExecutableToolResult | undefined;
+      for (let i = 0; i < CROSS_STEP_DEDUP_TRIGGER_COUNT - 1; i += 1) {
+        dedup.beginStep();
+        last = await runOriginal(dedup, `c${String(i)}`, 'Read', { p: 1 }, okResult('R'));
+        dedup.endStep();
+      }
+      expect(typeof last!.output).toBe('string');
+      expect(last!.output as string).not.toContain('<system-reminder>');
+    });
+
+    it(`injects reminder at exactly ${String(CROSS_STEP_DEDUP_TRIGGER_COUNT)} consecutive`, async () => {
+      const dedup = new ToolCallDeduplicator();
+      let last: ExecutableToolResult | undefined;
+      for (let i = 0; i < CROSS_STEP_DEDUP_TRIGGER_COUNT; i += 1) {
+        dedup.beginStep();
+        last = await runOriginal(dedup, `c${String(i)}`, 'Read', { p: 1 }, okResult('R'));
+        dedup.endStep();
+      }
+      expect(last!.output as string).toContain('<system-reminder>');
+      expect(last!.output as string).toContain('repeating the exact same tool call');
+    });
+
+    it('resets streak when a different call is interleaved', async () => {
+      const dedup = new ToolCallDeduplicator();
+      // 6× Read({p:1}) — should NOT trigger yet
+      for (let i = 0; i < 6; i += 1) {
+        dedup.beginStep();
+        await runOriginal(dedup, `a${String(i)}`, 'Read', { p: 1 }, okResult('R'));
+        dedup.endStep();
+      }
+      // 1× Read({p:2}) interrupts the streak
+      dedup.beginStep();
+      await runOriginal(dedup, 'b1', 'Read', { p: 2 }, okResult('R'));
+      dedup.endStep();
+      // Back to Read({p:1}); streak restarts → 1 occurrence, no reminder
+      dedup.beginStep();
+      const last = await runOriginal(dedup, 'c1', 'Read', { p: 1 }, okResult('R'));
+      dedup.endStep();
+      expect(last.output as string).not.toContain('<system-reminder>');
+    });
+
+    it('same-step dups inherit the reminder when streak triggers on original', async () => {
+      const dedup = new ToolCallDeduplicator();
+      // Build streak up to N-1 across previous steps.
+      for (let i = 0; i < CROSS_STEP_DEDUP_TRIGGER_COUNT - 1; i += 1) {
+        dedup.beginStep();
+        await runOriginal(dedup, `p${String(i)}`, 'Read', { p: 1 }, okResult('R'));
+        dedup.endStep();
+      }
+      // Next step: same call appears twice. First is the original (triggers reminder),
+      // second is a same-step dup that should inherit it.
+      dedup.beginStep();
+      const original = await runOriginal(
+        dedup,
+        'orig',
+        'Read',
+        { p: 1 },
+        okResult('R'),
+      );
+      const dupCached = dedup.checkSameStep('dup', 'Read', { p: 1 });
+      expect(dupCached).not.toBeNull();
+      const finalDup = await dedup.finalizeResult('dup', 'Read', { p: 1 }, dupCached!);
+      dedup.endStep();
+
+      expect(original.output as string).toContain('<system-reminder>');
+      expect(finalDup.output as string).toContain('<system-reminder>');
+    });
+
+    it('same-step spam alone does not trigger reminder', async () => {
+      const dedup = new ToolCallDeduplicator();
+      // 7 occurrences of the same call within a single step, but no prior
+      // streak — the trigger is about sustained behaviour across steps, not
+      // intra-step spam. Same-step dedup already short-circuits execution.
+      dedup.beginStep();
+      const cached = dedup.checkSameStep('orig', 'Read', { p: 1 });
+      expect(cached).toBeNull();
+      for (let i = 0; i < CROSS_STEP_DEDUP_TRIGGER_COUNT - 1; i += 1) {
+        dedup.checkSameStep(`dup${String(i)}`, 'Read', { p: 1 });
+      }
+      const final = await dedup.finalizeResult('orig', 'Read', { p: 1 }, okResult('R'));
+      expect(final.output as string).not.toContain('<system-reminder>');
+    });
+  });
+
+  describe('reminder injection into ContentPart[] outputs', () => {
+    it('appends to a trailing text part', async () => {
+      const dedup = new ToolCallDeduplicator();
+      const arrayResult: ExecutableToolResult = {
+        output: [{ type: 'text', text: 'hello' }],
+      };
+      // Force streak = trigger by running N-1 prior steps then this one.
+      for (let i = 0; i < CROSS_STEP_DEDUP_TRIGGER_COUNT - 1; i += 1) {
+        dedup.beginStep();
+        await runOriginal(dedup, `p${String(i)}`, 'X', {}, okResult('R'));
+        dedup.endStep();
+      }
+      dedup.beginStep();
+      const final = await runOriginal(dedup, 'final', 'X', {}, arrayResult);
+      dedup.endStep();
+      const arr = final.output as Array<{ type: string; text: string }>;
+      expect(arr).toHaveLength(1);
+      expect(arr[0]!.type).toBe('text');
+      expect(arr[0]!.text).toBe('hello' + REMINDER_TEXT);
+    });
+
+    it('pushes a new text part when trailing part is non-text', async () => {
+      const dedup = new ToolCallDeduplicator();
+      const arrayResult: ExecutableToolResult = {
+        output: [{ type: 'image_url', imageUrl: { url: 'data:foo' } }],
+      };
+      for (let i = 0; i < CROSS_STEP_DEDUP_TRIGGER_COUNT - 1; i += 1) {
+        dedup.beginStep();
+        await runOriginal(dedup, `p${String(i)}`, 'X', {}, okResult('R'));
+        dedup.endStep();
+      }
+      dedup.beginStep();
+      const final = await runOriginal(dedup, 'final', 'X', {}, arrayResult);
+      dedup.endStep();
+      const arr = final.output as Array<{ type: string; text?: string }>;
+      expect(arr).toHaveLength(2);
+      expect(arr[0]!.type).toBe('image_url');
+      expect(arr[1]!.type).toBe('text');
+      expect(arr[1]!.text).toBe(REMINDER_TEXT);
+    });
+
+    it('preserves isError flag when injecting reminder', async () => {
+      const dedup = new ToolCallDeduplicator();
+      for (let i = 0; i < CROSS_STEP_DEDUP_TRIGGER_COUNT - 1; i += 1) {
+        dedup.beginStep();
+        await runOriginal(dedup, `p${String(i)}`, 'X', {}, errResult('boom'));
+        dedup.endStep();
+      }
+      dedup.beginStep();
+      const final = await runOriginal(dedup, 'final', 'X', {}, errResult('boom'));
+      dedup.endStep();
+      expect(final.isError).toBe(true);
+      expect(final.output as string).toContain('<system-reminder>');
+    });
+  });
+
+  describe('key canonicalization', () => {
+    it('treats argument objects with different key order as the same call', async () => {
+      const dedup = new ToolCallDeduplicator();
+      dedup.beginStep();
+      await runOriginal(dedup, 'c1', 'Read', { a: 1, b: 2 }, okResult('SAME'));
+      const cached = dedup.checkSameStep('c2', 'Read', { b: 2, a: 1 });
+      expect(cached).not.toBeNull();
+      const finalDup = await dedup.finalizeResult('c2', 'Read', { b: 2, a: 1 }, cached!);
+      expect(finalDup).toEqual(okResult('SAME'));
+    });
+  });
+
+  describe('arg rewrite between checkSameStep and finalize', () => {
+    it('resolves the dup deferred even when the original call args are rewritten before finalize', async () => {
+      // Models the loop contract: prepareToolExecution may return
+      // {updatedArgs}, in which case finalizeToolResult sees the rewritten
+      // args. The dedup key registered at checkSameStep time uses the
+      // LLM-issued args; the deferred must be resolved under that same key.
+      const dedup = new ToolCallDeduplicator();
+      dedup.beginStep();
+      const c1 = dedup.checkSameStep('c1', 'Read', { path: '/a' });
+      expect(c1).toBeNull();
+      const c2 = dedup.checkSameStep('c2', 'Read', { path: '/a' });
+      expect(c2).not.toBeNull();
+
+      // Original finalize is called with REWRITTEN args (simulates a hook
+      // returning updatedArgs).
+      const finalC1 = await dedup.finalizeResult(
+        'c1',
+        'Read',
+        { path: '/REWRITTEN' },
+        okResult('A'),
+      );
+      // Dup's finalize must not hang — it should resolve via the deferred
+      // registered under the original-args key.
+      const finalC2 = await Promise.race([
+        dedup.finalizeResult('c2', 'Read', { path: '/a' }, c2!),
+        new Promise<ExecutableToolResult>((_, reject) => {
+          setTimeout(() => {
+            reject(new Error('dup finalize hung — deferred was never resolved'));
+          }, 500);
+        }),
+      ]);
+      expect(finalC1).toEqual(okResult('A'));
+      expect(finalC2).toEqual(okResult('A'));
+    });
+  });
+
+  describe('beginStep cleanup', () => {
+    it('resolves leaked deferreds from a prior aborted step with an error result', async () => {
+      const dedup = new ToolCallDeduplicator();
+      dedup.beginStep();
+      // Register an original but never finalize it (simulates abort mid-step).
+      const orig = dedup.checkSameStep('leaked', 'Read', { p: 1 });
+      expect(orig).toBeNull();
+      // Register a dup that captures the leaked deferred.
+      const dupCached = dedup.checkSameStep('dup', 'Read', { p: 1 });
+      expect(dupCached).not.toBeNull();
+
+      // Next step begins — the leaked deferred should resolve so an awaiter
+      // doesn't hang. (In production the dup's finalize would have already
+      // happened before beginStep, but defensively resolving leaked deferreds
+      // protects against any ordering bug.)
+      dedup.beginStep();
+      // Finalize the dup that captured the leaked deferred. Since we cleared
+      // syntheticCallIds in beginStep, this is no longer tracked — it just
+      // returns the placeholder it was passed. The leaked deferred has been
+      // resolved with an error result but nothing is awaiting it now.
+      const finalDup = await dedup.finalizeResult('dup', 'Read', { p: 1 }, dupCached!);
+      expect(finalDup).toEqual(dupCached);
+    });
+  });
+});
diff --git a/packages/agent-core/test/agent/usage.test.ts b/packages/agent-core/test/agent/usage.test.ts
new file mode 100644
index 000000000..c21757ae6
--- /dev/null
+++ b/packages/agent-core/test/agent/usage.test.ts
@@ -0,0 +1,140 @@
+import { describe, expect, it } from 'vitest';
+
+import { UsageRecorder } from '../../src/agent/usage';
+
+describe('Agent usage', () => {
+  it('accumulates usage by model', () => {
+    const usage = new UsageRecorder();
+
+    usage.record('model-a', {
+      inputOther: 1,
+      output: 2,
+      inputCacheRead: 3,
+      inputCacheCreation: 4,
+    });
+    usage.record('model-a', {
+      inputOther: 10,
+      output: 20,
+      inputCacheRead: 30,
+      inputCacheCreation: 40,
+    });
+    usage.record('model-b', {
+      inputOther: 100,
+      output: 200,
+      inputCacheRead: 300,
+      inputCacheCreation: 400,
+    });
+
+    expect(usage.data()).toEqual({
+      byModel: {
+        'model-a': {
+          inputOther: 11,
+          output: 22,
+          inputCacheRead: 33,
+          inputCacheCreation: 44,
+        },
+        'model-b': {
+          inputOther: 100,
+          output: 200,
+          inputCacheRead: 300,
+          inputCacheCreation: 400,
+        },
+      },
+      total: {
+        inputOther: 111,
+        output: 222,
+        inputCacheRead: 333,
+        inputCacheCreation: 444,
+      },
+      currentTurn: undefined,
+    });
+  });
+
+  it('tracks current turn usage separately from session totals', () => {
+    const usage = new UsageRecorder();
+
+    usage.record('model-a', {
+      inputOther: 1,
+      output: 2,
+      inputCacheRead: 3,
+      inputCacheCreation: 4,
+    });
+    usage.beginTurn();
+    usage.record(
+      'model-a',
+      {
+        inputOther: 10,
+        output: 20,
+        inputCacheRead: 30,
+        inputCacheCreation: 40,
+      },
+      'turn',
+    );
+    usage.record(
+      'model-b',
+      {
+        inputOther: 100,
+        output: 200,
+        inputCacheRead: 300,
+        inputCacheCreation: 400,
+      },
+      'turn',
+    );
+
+    expect(usage.data()).toMatchObject({
+      total: {
+        inputOther: 111,
+        output: 222,
+        inputCacheRead: 333,
+        inputCacheCreation: 444,
+      },
+      currentTurn: {
+        inputOther: 110,
+        output: 220,
+        inputCacheRead: 330,
+        inputCacheCreation: 440,
+      },
+    });
+
+    usage.endTurn();
+
+    expect(usage.data().currentTurn).toBeUndefined();
+  });
+
+  it('returns immutable status snapshots', () => {
+    const usage = new UsageRecorder();
+
+    usage.record('model-a', {
+      inputOther: 1,
+      output: 2,
+      inputCacheRead: 3,
+      inputCacheCreation: 4,
+    });
+    const snapshot = usage.data();
+
+    usage.record('model-a', {
+      inputOther: 10,
+      output: 20,
+      inputCacheRead: 30,
+      inputCacheCreation: 40,
+    });
+
+    expect(snapshot).toEqual({
+      byModel: {
+        'model-a': {
+          inputOther: 1,
+          output: 2,
+          inputCacheRead: 3,
+          inputCacheCreation: 4,
+        },
+      },
+      total: {
+        inputOther: 1,
+        output: 2,
+        inputCacheRead: 3,
+        inputCacheCreation: 4,
+      },
+      currentTurn: undefined,
+    });
+  });
+});
diff --git a/packages/agent-core/test/config/configs.test.ts b/packages/agent-core/test/config/configs.test.ts
new file mode 100644
index 000000000..7d118cbe4
--- /dev/null
+++ b/packages/agent-core/test/config/configs.test.ts
@@ -0,0 +1,538 @@
+import { mkdtempSync } from 'node:fs';
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { ErrorCodes, KimiError } from '../../src/errors';
+import {
+  KimiConfigSchema,
+  ensureConfigFile,
+  mergeConfigPatch,
+  parseConfigString,
+  parseBooleanEnv,
+  readConfigFile,
+  resolveConfigPath,
+  resolveConfigValue,
+  resolveKimiHome,
+  validateConfig,
+  writeConfigFile,
+} from '../../src/config';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+function makeTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'kimi-core-config-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function expectKimiErrorCode(fn: () => unknown, code: string): void {
+  try {
+    fn();
+  } catch (error) {
+    expect(error).toBeInstanceOf(KimiError);
+    expect((error as KimiError).code).toBe(code);
+    return;
+  }
+  throw new Error('expected function to throw');
+}
+
+const COMPLETE_TOML = `
+default_model = "kimi-code/kimi-for-coding"
+default_thinking = true
+default_permission_mode = "auto"
+default_plan_mode = false
+merge_all_available_skills = true
+extra_skill_dirs = ["~/team-skills", ".agents/team-skills"]
+telemetry = false
+theme = "dark"
+
+[providers."managed:kimi-code"]
+type = "kimi"
+base_url = "https://api.kimi.com/coding/v1"
+api_key = "sk-file"
+custom_headers = { "X-Test" = "1" }
+
+[providers."managed:kimi-code".env]
+GOOGLE_CLOUD_PROJECT = "project-1"
+
+[models."kimi-code/kimi-for-coding"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+max_context_size = 262144
+capabilities = ["image_in", "thinking", "video_in"]
+display_name = "Kimi for Coding"
+
+[thinking]
+mode = "auto"
+effort = "medium"
+
+[permission]
+mode = "manual"
+
+[[permission.rules]]
+decision = "deny"
+scope = "user"
+pattern = "Bash(rm *)"
+reason = "no rm"
+
+[[permission.allow]]
+tool = "Read"
+match = "src/**"
+reason = "read src"
+
+[loop_control]
+max_steps_per_run = 42
+max_retries_per_step = 3
+reserved_context_size = 50000
+compaction_trigger_ratio = 0.85
+
+[background]
+max_running_tasks = 4
+keep_alive_on_exit = false
+kill_grace_period_ms = 2000
+agent_task_timeout_s = 900
+print_wait_ceiling_s = 3600
+
+[[hooks]]
+event = "PreToolUse"
+matcher = "Shell"
+command = "echo pre"
+timeout = 5
+
+[[hooks]]
+event = "Stop"
+command = "echo stop"
+
+[services.moonshot_search]
+base_url = "https://api.kimi.com/coding/v1/search"
+api_key = "sk-search"
+custom_headers = { "X-Search" = "1" }
+
+[services.moonshot_fetch]
+base_url = "https://api.kimi.com/coding/v1/fetch"
+api_key = "sk-fetch"
+
+[notifications]
+claim_stale_after_ms = 15000
+`;
+
+describe('harness config TOML loader', () => {
+  it('parses the current config.toml shape through explicit field mappings', () => {
+    const config = parseConfigString(COMPLETE_TOML, 'config.toml');
+
+    expect(config.defaultModel).toBe('kimi-code/kimi-for-coding');
+    expect(config.defaultThinking).toBe(true);
+    expect(config.defaultPermissionMode).toBe('auto');
+    expect(config.defaultPlanMode).toBe(false);
+    expect(config.mergeAllAvailableSkills).toBe(true);
+    expect(config.extraSkillDirs).toEqual(['~/team-skills', '.agents/team-skills']);
+    expect(config.telemetry).toBe(false);
+    expect(config.providers['managed:kimi-code']).toMatchObject({
+      type: 'kimi',
+      baseUrl: 'https://api.kimi.com/coding/v1',
+      apiKey: 'sk-file',
+      env: { GOOGLE_CLOUD_PROJECT: 'project-1' },
+      customHeaders: { 'X-Test': '1' },
+    });
+    expect(config.models?.['kimi-code/kimi-for-coding']).toMatchObject({
+      provider: 'managed:kimi-code',
+      model: 'kimi-for-coding',
+      maxContextSize: 262144,
+      capabilities: ['image_in', 'thinking', 'video_in'],
+      displayName: 'Kimi for Coding',
+    });
+    expect(config.thinking).toEqual({ mode: 'auto', effort: 'medium' });
+    expect(config.permission).toEqual({
+      rules: [
+        {
+          decision: 'deny',
+          scope: 'user',
+          pattern: 'Bash(rm *)',
+          reason: 'no rm',
+        },
+        {
+          decision: 'allow',
+          scope: 'user',
+          pattern: 'Read(src/**)',
+          reason: 'read src',
+        },
+      ],
+    });
+    expect(config.loopControl).toMatchObject({
+      maxStepsPerTurn: 42,
+      maxRetriesPerStep: 3,
+      reservedContextSize: 50000,
+      compactionTriggerRatio: 0.85,
+    });
+    expect(config.background?.agentTaskTimeoutS).toBe(900);
+    expect(config.hooks).toEqual([
+      {
+        event: 'PreToolUse',
+        matcher: 'Shell',
+        command: 'echo pre',
+        timeout: 5,
+      },
+      {
+        event: 'Stop',
+        command: 'echo stop',
+      },
+    ]);
+    expect(config.services?.moonshotSearch?.customHeaders).toEqual({ 'X-Search': '1' });
+    expect(config.services?.moonshotFetch?.apiKey).toBe('sk-fetch');
+
+    expect('theme' in config).toBe(false);
+    expect(config.raw?.['theme']).toBe('dark');
+    expect(config.raw?.['notifications']).toEqual({ claim_stale_after_ms: 15000 });
+  });
+
+  it('loads defaults for absent files and writes typed fields without dropping raw sections', async () => {
+    const dir = makeTempDir();
+    const configPath = join(dir, 'config.toml');
+
+    expect(readConfigFile(configPath)).toEqual({ providers: {} });
+
+    const config = parseConfigString(COMPLETE_TOML, configPath);
+    const loopControl = config.loopControl;
+    expect(loopControl).toBeDefined();
+    await writeConfigFile(configPath, {
+      ...config,
+      defaultModel: 'kimi-code/kimi-for-coding',
+      loopControl: {
+        ...loopControl!,
+        maxStepsPerTurn: 7,
+      },
+    });
+
+    const text = await readFile(configPath, 'utf-8');
+    expect(text).toContain('default_model = "kimi-code/kimi-for-coding"');
+    expect(text).toContain('default_permission_mode = "auto"');
+    expect(text).toContain('extra_skill_dirs = [ "~/team-skills", ".agents/team-skills" ]');
+    expect(text).toContain('telemetry = false');
+    expect(text).not.toContain('default_yolo');
+    expect(text).toContain('[[permission.rules]]');
+    expect(text).toContain('pattern = "Bash(rm *)"');
+    expect(text).toContain('pattern = "Read(src/**)"');
+    expect(text).not.toContain('[[permission.allow]]');
+    expect(text).toContain('max_steps_per_turn = 7');
+    expect(text).toContain('GOOGLE_CLOUD_PROJECT = "project-1"');
+    expect(text).toContain('theme = "dark"');
+    expect(text).toContain('claim_stale_after_ms = 15000');
+    expect(text).toContain('[[hooks]]');
+    expect(text).toContain('event = "PreToolUse"');
+    expect(text).toContain('command = "echo pre"');
+
+    const reloaded = readConfigFile(configPath);
+    expect(reloaded.loopControl?.maxStepsPerTurn).toBe(7);
+    expect(reloaded.hooks?.[0]?.event).toBe('PreToolUse');
+    expect(reloaded.raw?.['theme']).toBe('dark');
+  });
+
+  it('creates a parseable default config scaffold without changing runtime defaults', async () => {
+    const dir = makeTempDir();
+    const configPath = join(dir, 'config.toml');
+
+    await ensureConfigFile(configPath);
+
+    const text = await readFile(configPath, 'utf-8');
+    expect(text).toContain('Runtime settings for Kimi Code.');
+    expect(text).not.toMatch(/^default_thinking =/m);
+    expect(text).not.toMatch(/^default_model =/m);
+
+    const config = readConfigFile(configPath);
+    expect(config.providers).toEqual({});
+    expect(config.defaultModel).toBeUndefined();
+    expect(config.defaultThinking).toBeUndefined();
+  });
+
+  it('does not overwrite an existing config file', async () => {
+    const dir = makeTempDir();
+    const configPath = join(dir, 'config.toml');
+    const existing = 'default_model = "custom"\n';
+    await writeFile(configPath, existing, 'utf-8');
+
+    await ensureConfigFile(configPath);
+
+    await expect(readFile(configPath, 'utf-8')).resolves.toBe(existing);
+  });
+
+  it('drops deprecated default_yolo when rewriting config files', async () => {
+    const dir = makeTempDir();
+    const configPath = join(dir, 'config.toml');
+    const config = parseConfigString('default_yolo = true\n', configPath);
+
+    expect(config.defaultPermissionMode).toBeUndefined();
+
+    await writeConfigFile(configPath, config);
+
+    const text = await readFile(configPath, 'utf-8');
+    expect(text).not.toContain('default_yolo');
+    expect(text).not.toContain('default_permission_mode');
+  });
+
+  it('rejects invalid TOML and invalid schema with KimiError(config.invalid)', () => {
+    expectKimiErrorCode(
+      () => parseConfigString('[[[', 'broken.toml'),
+      ErrorCodes.CONFIG_INVALID,
+    );
+    expectKimiErrorCode(
+      () =>
+        parseConfigString(
+          `
+[providers.bad]
+type = "not-a-provider"
+`,
+          'broken.toml',
+        ),
+      ErrorCodes.CONFIG_INVALID,
+    );
+    expectKimiErrorCode(
+      () =>
+        parseConfigString(
+          `
+[[permission.rules]]
+decision = "deny"
+pattern = "Bash(rm *"
+`,
+          'broken.toml',
+        ),
+      ErrorCodes.CONFIG_INVALID,
+    );
+  });
+
+  it('parses hooks config from TOML arrays of tables', () => {
+    const config = parseConfigString(
+      `
+[[hooks]]
+event = "PreToolUse"
+matcher = "Shell"
+command = "echo hi"
+timeout = 5
+`,
+      'hooks.toml',
+    );
+
+    expect(config.hooks).toEqual([
+      {
+        event: 'PreToolUse',
+        matcher: 'Shell',
+        command: 'echo hi',
+        timeout: 5,
+      },
+    ]);
+  });
+
+  it('rejects invalid hooks config', () => {
+    expectKimiErrorCode(
+      () =>
+        parseConfigString(
+          `
+hooks = [{ type = "pre-tool-call", command = "echo hi" }]
+`,
+          'hooks.toml',
+        ),
+      ErrorCodes.CONFIG_INVALID,
+    );
+  });
+});
+
+describe('harness config schema and patch merge', () => {
+  it('accepts the empty public config and requires model context size in full configs', () => {
+    expect(KimiConfigSchema.parse({})).toEqual({ providers: {} });
+    expect(() =>
+      validateConfig({
+        providers: {
+          local: { type: 'openai', apiKey: 'sk-test' },
+        },
+        models: {
+          broken: { provider: 'local', model: 'gpt-test' },
+        },
+      }),
+    ).toThrow(/max_context_size/);
+  });
+
+  it('deep-merges validated patches while preserving existing typed and raw data', () => {
+    const base = parseConfigString(COMPLETE_TOML);
+    const merged = mergeConfigPatch(base, {
+      providers: {
+        'managed:kimi-code': {
+          apiKey: 'sk-patched',
+          baseUrl: undefined,
+        },
+      },
+      models: {
+        'kimi-code/kimi-for-coding': {
+          capabilities: ['tool_use'],
+        },
+      },
+      thinking: {
+        effort: 'high',
+      },
+    });
+
+    expect(merged.providers['managed:kimi-code']).toMatchObject({
+      type: 'kimi',
+      baseUrl: 'https://api.kimi.com/coding/v1',
+      apiKey: 'sk-patched',
+      env: { GOOGLE_CLOUD_PROJECT: 'project-1' },
+    });
+    expect(merged.models?.['kimi-code/kimi-for-coding']).toMatchObject({
+      provider: 'managed:kimi-code',
+      model: 'kimi-for-coding',
+      maxContextSize: 262144,
+      capabilities: ['tool_use'],
+    });
+    expect(merged.thinking).toEqual({ mode: 'auto', effort: 'high' });
+    expect(merged.hooks).toEqual(base.hooks);
+    expect(merged.raw?.['theme']).toBe('dark');
+  });
+
+  it('rejects unknown fields in config patches', () => {
+    expectKimiErrorCode(
+      () => mergeConfigPatch({ providers: {} }, { theme: 'dark' } as never),
+      ErrorCodes.CONFIG_INVALID,
+    );
+  });
+
+  it('replaces hooks arrays in config patches', () => {
+    const base = parseConfigString(COMPLETE_TOML);
+    const merged = mergeConfigPatch(base, {
+      hooks: [{ event: 'Notification', matcher: 'task_completed', command: 'echo notified' }],
+    });
+
+    expect(merged.hooks).toEqual([
+      { event: 'Notification', matcher: 'task_completed', command: 'echo notified' },
+    ]);
+  });
+
+  it('accepts maxOutputSize on a model alias and round-trips it', () => {
+    const parsed = KimiConfigSchema.parse({
+      providers: { local: { type: 'anthropic', apiKey: 'sk-test' } },
+      models: {
+        opus: {
+          provider: 'local',
+          model: 'claude-opus-4-7',
+          maxContextSize: 200000,
+          maxOutputSize: 32000,
+        },
+      },
+    });
+    expect(parsed.models?.['opus']).toMatchObject({
+      maxContextSize: 200000,
+      maxOutputSize: 32000,
+    });
+  });
+
+  it('leaves maxOutputSize undefined when omitted', () => {
+    const parsed = KimiConfigSchema.parse({
+      providers: { local: { type: 'anthropic', apiKey: 'sk-test' } },
+      models: {
+        opus: {
+          provider: 'local',
+          model: 'claude-opus-4-7',
+          maxContextSize: 200000,
+        },
+      },
+    });
+    expect(parsed.models?.['opus']?.maxOutputSize).toBeUndefined();
+  });
+
+  it('rejects maxOutputSize <= 0', () => {
+    expect(() =>
+      KimiConfigSchema.parse({
+        providers: { local: { type: 'anthropic', apiKey: 'sk-test' } },
+        models: {
+          opus: {
+            provider: 'local',
+            model: 'claude-opus-4-7',
+            maxContextSize: 200000,
+            maxOutputSize: 0,
+          },
+        },
+      }),
+    ).toThrow();
+  });
+});
+
+describe('config path env override', () => {
+  it('uses KIMI_CODE_HOME when no explicit homeDir is supplied', () => {
+    const saved = process.env['KIMI_CODE_HOME'];
+    try {
+      process.env['KIMI_CODE_HOME'] = '/tmp/kimi-from-env';
+
+      expect(resolveKimiHome()).toBe('/tmp/kimi-from-env');
+      expect(resolveKimiHome('/tmp/kimi-explicit')).toBe('/tmp/kimi-explicit');
+      expect(resolveConfigPath({})).toBe('/tmp/kimi-from-env/config.toml');
+      expect(resolveConfigPath({ configPath: '/tmp/custom.toml' })).toBe('/tmp/custom.toml');
+    } finally {
+      if (saved === undefined) delete process.env['KIMI_CODE_HOME'];
+      else process.env['KIMI_CODE_HOME'] = saved;
+    }
+  });
+});
+
+describe('config value env override helpers', () => {
+  it('parses boolean env values', () => {
+    expect(parseBooleanEnv('1')).toBe(true);
+    expect(parseBooleanEnv(' true ')).toBe(true);
+    expect(parseBooleanEnv('yes')).toBe(true);
+    expect(parseBooleanEnv('on')).toBe(true);
+    expect(parseBooleanEnv('0')).toBe(false);
+    expect(parseBooleanEnv(' false ')).toBe(false);
+    expect(parseBooleanEnv('no')).toBe(false);
+    expect(parseBooleanEnv('off')).toBe(false);
+    expect(parseBooleanEnv('')).toBeUndefined();
+    expect(parseBooleanEnv('maybe')).toBeUndefined();
+  });
+
+  it('resolves env before config before default', () => {
+    expect(
+      resolveConfigValue({
+        env: { KIMI_TEST_FLAG: '0' },
+        envKey: 'KIMI_TEST_FLAG',
+        configValue: true,
+        defaultValue: true,
+        parseEnv: parseBooleanEnv,
+      }),
+    ).toBe(false);
+
+    expect(
+      resolveConfigValue({
+        env: {},
+        envKey: 'KIMI_TEST_FLAG',
+        configValue: false,
+        defaultValue: true,
+        parseEnv: parseBooleanEnv,
+      }),
+    ).toBe(false);
+
+    expect(
+      resolveConfigValue({
+        env: {},
+        envKey: 'KIMI_TEST_FLAG',
+        defaultValue: true,
+        parseEnv: parseBooleanEnv,
+      }),
+    ).toBe(true);
+  });
+
+  it('ignores invalid env values', () => {
+    expect(
+      resolveConfigValue({
+        env: { KIMI_TEST_FLAG: 'invalid' },
+        envKey: 'KIMI_TEST_FLAG',
+        configValue: false,
+        defaultValue: true,
+        parseEnv: parseBooleanEnv,
+      }),
+    ).toBe(false);
+  });
+});
diff --git a/packages/agent-core/test/fixtures/telemetry.ts b/packages/agent-core/test/fixtures/telemetry.ts
new file mode 100644
index 000000000..cad735565
--- /dev/null
+++ b/packages/agent-core/test/fixtures/telemetry.ts
@@ -0,0 +1,32 @@
+import type { TelemetryClient, TelemetryProperties } from '../../src/telemetry';
+
+export interface TelemetryRecord {
+  readonly event: string;
+  readonly properties?: TelemetryProperties;
+}
+
+export interface TelemetryContextRecord extends TelemetryRecord {
+  readonly sessionId: string | null;
+}
+
+export function recordingTelemetry(records: TelemetryRecord[]): TelemetryClient {
+  return {
+    track: (event, properties) => {
+      records.push({ event, properties });
+    },
+    withContext: () => recordingTelemetry(records),
+  };
+}
+
+export function recordingContextTelemetry(records: TelemetryContextRecord[]): TelemetryClient {
+  return {
+    track: (event, properties) => {
+      records.push({ event, sessionId: null, properties });
+    },
+    withContext: (patch) => ({
+      track: (event, properties) => {
+        records.push({ event, sessionId: patch.sessionId ?? null, properties });
+      },
+    }),
+  };
+}
diff --git a/packages/agent-core/test/harness/model-alias-session.test.ts b/packages/agent-core/test/harness/model-alias-session.test.ts
new file mode 100644
index 000000000..1113937d3
--- /dev/null
+++ b/packages/agent-core/test/harness/model-alias-session.test.ts
@@ -0,0 +1,412 @@
+import { mkdtemp, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createRPC,
+  KimiCore,
+  type CoreAPI,
+  type SDKAPI,
+  type TelemetryClient,
+} from '../../src';
+import {
+  recordingContextTelemetry,
+  type TelemetryContextRecord,
+} from '../fixtures/telemetry';
+
+const CONFIG = `
+default_model = "kimi-code/kimi-for-coding"
+
+[providers."managed:kimi-code"]
+type = "kimi"
+api_key = "test-key"
+base_url = "https://api.example/v1"
+
+[models."kimi-code/kimi-for-coding"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+max_context_size = 1000000
+`;
+
+describe('HarnessAPI session model aliases', () => {
+  let tmp: string;
+  let homeDir: string;
+  let workDir: string;
+  let configPath: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), 'kimi-model-alias-'));
+    homeDir = join(tmp, 'home');
+    workDir = join(tmp, 'work');
+    configPath = join(tmp, 'config.toml');
+    await mkdir(workDir, { recursive: true });
+    await writeFile(configPath, CONFIG);
+  });
+
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('keeps the configured alias separate from the provider model across create, setModel, and resume', async () => {
+    const rpc = await createTestRpc();
+    const created = await rpc.createSession({
+      workDir,
+      model: 'kimi-code/kimi-for-coding',
+    });
+
+    expect(await rpc.getModel({ sessionId: created.id, agentId: 'main' })).toBe(
+      'kimi-code/kimi-for-coding',
+    );
+
+    const config = await rpc.getConfig({ sessionId: created.id, agentId: 'main' });
+    expect(config.modelAlias).toBe('kimi-code/kimi-for-coding');
+    expect(config.provider?.model).toBe('kimi-for-coding');
+    expect(config.modelCapabilities?.max_context_tokens).toBe(1_000_000);
+
+    await rpc.setModel({
+      sessionId: created.id,
+      agentId: 'main',
+      model: 'kimi-code/kimi-for-coding',
+    });
+
+    const freshRpc = await createTestRpc();
+    await freshRpc.resumeSession({ sessionId: created.id });
+
+    expect(await freshRpc.getModel({ sessionId: created.id, agentId: 'main' })).toBe(
+      'kimi-code/kimi-for-coding',
+    );
+  });
+
+  it('re-bootstraps profile and model when resuming a session whose wire has no config.update', async () => {
+    // A migrated session ships a wire.jsonl with only `metadata` and message
+    // records — none of the `config.update` / `tools.set_active_tools`
+    // bootstrap events a natively-created session writes. Resuming it must
+    // still yield a usable agent (model + system prompt), not an empty config.
+    const rpc = await createTestRpc();
+    const created = await rpc.createSession({
+      workDir,
+      model: 'kimi-code/kimi-for-coding',
+    });
+    await rpc.closeSession({ sessionId: created.id });
+
+    const wirePath = await findWireFile(homeDir);
+    const kept = (await readFile(wirePath, 'utf-8'))
+      .split('\n')
+      .filter((line) => line.trim().length > 0)
+      .filter((line) => {
+        const type = (JSON.parse(line) as { type?: string }).type;
+        return type !== 'config.update' && type !== 'tools.set_active_tools';
+      });
+    await writeFile(wirePath, `${kept.join('\n')}\n`);
+
+    const freshRpc = await createTestRpc();
+    await freshRpc.resumeSession({ sessionId: created.id });
+
+    expect(await freshRpc.getModel({ sessionId: created.id, agentId: 'main' })).toBe(
+      'kimi-code/kimi-for-coding',
+    );
+    const config = await freshRpc.getConfig({ sessionId: created.id, agentId: 'main' });
+    expect(config.modelAlias).toBe('kimi-code/kimi-for-coding');
+    expect(config.systemPrompt.length).toBeGreaterThan(0);
+  });
+
+  it('applies RPC config updates to later agent model changes', async () => {
+    const rpc = await createTestRpc();
+    const created = await rpc.createSession({
+      workDir,
+      model: 'kimi-code/kimi-for-coding',
+    });
+
+    const updatedConfig = await rpc.setKimiConfig({
+      defaultModel: 'gpt-alias',
+      providers: {
+        openai: {
+          type: 'openai',
+          apiKey: 'sk-openai',
+          baseUrl: 'https://openai.example/v1',
+        },
+      },
+      models: {
+        'gpt-alias': {
+          provider: 'openai',
+          model: 'gpt-runtime',
+          maxContextSize: 200000,
+          capabilities: ['tool_use'],
+        },
+      },
+    });
+    expect(updatedConfig.defaultModel).toBe('gpt-alias');
+
+    await expect(
+      rpc.setModel({
+        sessionId: created.id,
+        agentId: 'main',
+        model: 'gpt-alias',
+      }),
+    ).resolves.toEqual({
+      model: 'gpt-alias',
+      providerName: 'openai',
+    });
+
+    const config = await rpc.getConfig({ sessionId: created.id, agentId: 'main' });
+    expect(config.modelAlias).toBe('gpt-alias');
+    expect(config.provider).toMatchObject({
+      type: 'openai',
+      model: 'gpt-runtime',
+      apiKey: 'sk-openai',
+      baseUrl: 'https://openai.example/v1',
+    });
+    expect(config.modelCapabilities).toMatchObject({
+      tool_use: true,
+      max_context_tokens: 200000,
+    });
+  });
+
+  it('can create an unconfigured session when no model is selected', async () => {
+    await writeFile(configPath, '');
+    const rpc = await createTestRpc();
+
+    const created = await rpc.createSession({ workDir });
+
+    expect(created.id.startsWith('session_')).toBe(true);
+    expect(await rpc.getModel({ sessionId: created.id, agentId: 'main' })).toBe('');
+  });
+
+  it('loads configured permission rules into created and resumed sessions', async () => {
+    await writeFile(
+      configPath,
+      `${CONFIG}
+
+[[permission.deny]]
+tool = "Bash"
+match = "rm *"
+reason = "no rm"
+`,
+    );
+    const rpc = await createTestRpc();
+    const created = await rpc.createSession({ workDir });
+
+    await expect(rpc.getPermission({ sessionId: created.id, agentId: 'main' })).resolves.toEqual({
+      mode: 'manual',
+      rules: [
+        {
+          decision: 'deny',
+          scope: 'user',
+          pattern: 'Bash(rm *)',
+          reason: 'no rm',
+        },
+      ],
+    });
+
+    const freshRpc = await createTestRpc();
+    await freshRpc.resumeSession({ sessionId: created.id });
+    await expect(
+      freshRpc.getPermission({ sessionId: created.id, agentId: 'main' }),
+    ).resolves.toEqual({
+      mode: 'manual',
+      rules: [
+        {
+          decision: 'deny',
+          scope: 'user',
+          pattern: 'Bash(rm *)',
+          reason: 'no rm',
+        },
+      ],
+    });
+  });
+
+  it('uses configured default permission mode for fresh sessions', async () => {
+    await writeFile(
+      configPath,
+      CONFIG.replace(
+        'default_model = "kimi-code/kimi-for-coding"',
+        'default_model = "kimi-code/kimi-for-coding"\ndefault_permission_mode = "auto"',
+      ),
+    );
+    const rpc = await createTestRpc();
+    const created = await rpc.createSession({ workDir });
+
+    await expect(rpc.getPermission({ sessionId: created.id, agentId: 'main' })).resolves.toEqual({
+      mode: 'auto',
+      rules: [],
+    });
+
+    const explicit = await rpc.createSession({ workDir, permission: 'manual' });
+    await expect(rpc.getPermission({ sessionId: explicit.id, agentId: 'main' })).resolves.toEqual({
+      mode: 'manual',
+      rules: [],
+    });
+  });
+
+  it('does not expose raw provider switching through the core RPC surface', async () => {
+    const rpc = (await createTestRpc()) as unknown as Record<string, unknown>;
+
+    expect(rpc['setProvider']).toBeUndefined();
+  });
+
+  it('exposes the core package version as read-only metadata', async () => {
+    const rpc = await createTestRpc();
+    const pkg = JSON.parse(
+      await readFile(new URL('../../package.json', import.meta.url), 'utf-8'),
+    ) as { version: string };
+
+    await expect(rpc.getCoreInfo({})).resolves.toEqual({
+      version: pkg.version,
+    });
+    expect((rpc as unknown as Record<string, unknown>)['setVersion']).toBeUndefined();
+  });
+
+  it('clears a resumed model that no longer resolves and has no valid fallback', async () => {
+    const rpc = await createTestRpc();
+    const created = await rpc.createSession({ workDir, model: 'kimi-code/kimi-for-coding' });
+    await rpc.closeSession({ sessionId: created.id });
+
+    // The config now has no models and no default model — the alias replayed
+    // from the session is invalid and there is no fallback to resolve.
+    await writeFile(configPath, '');
+
+    const freshRpc = await createTestRpc();
+    await freshRpc.resumeSession({ sessionId: created.id });
+
+    // The stale alias must be cleared, not left selected — a phantom model
+    // would fail on the next prompt instead of surfacing the no-model state.
+    expect(await freshRpc.getModel({ sessionId: created.id, agentId: 'main' })).toBe('');
+  });
+
+  it('surfaces a config error when a resumed model is configured but unresolvable', async () => {
+    const rpc = await createTestRpc();
+    const created = await rpc.createSession({ workDir, model: 'kimi-code/kimi-for-coding' });
+    await rpc.closeSession({ sessionId: created.id });
+
+    // The model alias is still in config, but it now references a provider
+    // that does not exist. That is an actionable config error — resume must
+    // surface it, not silently fall back to another model or clear it.
+    await writeFile(
+      configPath,
+      `
+default_model = "kimi-code/kimi-for-coding"
+
+[providers."managed:kimi-code"]
+type = "kimi"
+api_key = "test-key"
+base_url = "https://api.example/v1"
+
+[models."kimi-code/kimi-for-coding"]
+provider = "ghost-provider"
+model = "kimi-for-coding"
+max_context_size = 1000000
+`,
+    );
+
+    const freshRpc = await createTestRpc();
+    await expect(freshRpc.resumeSession({ sessionId: created.id })).rejects.toThrow();
+  });
+
+  it('scopes agent telemetry events to the owning session', async () => {
+    const createRecords: TelemetryContextRecord[] = [];
+    const createRpc = await createTestRpc({ telemetry: recordingContextTelemetry(createRecords) });
+    const created = await createRpc.createSession({
+      workDir,
+      model: 'kimi-code/kimi-for-coding',
+    });
+
+    await createRpc.setPermission({ sessionId: created.id, agentId: 'main', mode: 'yolo' });
+
+    expect(createRecords).toContainEqual({
+      event: 'yolo_toggle',
+      sessionId: created.id,
+      properties: { enabled: true },
+    });
+
+    await createRpc.setPermission({ sessionId: created.id, agentId: 'main', mode: 'auto' });
+
+    expect(createRecords).toContainEqual({
+      event: 'afk_toggle',
+      sessionId: created.id,
+      properties: { enabled: true },
+    });
+
+    await createRpc.setKimiConfig({
+      defaultModel: 'gpt-alias',
+      providers: {
+        openai: {
+          type: 'openai',
+          apiKey: 'sk-openai',
+          baseUrl: 'https://openai.example/v1',
+        },
+      },
+      models: {
+        'gpt-alias': {
+          provider: 'openai',
+          model: 'gpt-runtime',
+          maxContextSize: 200000,
+        },
+      },
+    });
+    await createRpc.setModel({
+      sessionId: created.id,
+      agentId: 'main',
+      model: 'gpt-alias',
+    });
+
+    expect(createRecords).toContainEqual({
+      event: 'model_switch',
+      sessionId: created.id,
+      properties: { model: 'gpt-alias' },
+    });
+
+    const resumeRecords: TelemetryContextRecord[] = [];
+    const resumeRpc = await createTestRpc({ telemetry: recordingContextTelemetry(resumeRecords) });
+    await resumeRpc.resumeSession({ sessionId: created.id });
+    await resumeRpc.setThinking({ sessionId: created.id, agentId: 'main', level: 'off' });
+
+    expect(resumeRecords).toContainEqual({
+      event: 'thinking_toggle',
+      sessionId: created.id,
+      properties: { enabled: false },
+    });
+  });
+
+  it('tracks session_load_failed with the attempted session context', async () => {
+    const rpc = await createTestRpc();
+    const created = await rpc.createSession({ workDir });
+    await writeFile(join(created.sessionDir, 'state.json'), '{bad json', 'utf-8');
+
+    const records: TelemetryContextRecord[] = [];
+    const freshRpc = await createTestRpc({ telemetry: recordingContextTelemetry(records) });
+
+    await expect(freshRpc.resumeSession({ sessionId: created.id })).rejects.toThrow();
+    expect(records).toContainEqual({
+      event: 'session_load_failed',
+      sessionId: created.id,
+      properties: { reason: 'SyntaxError' },
+    });
+  });
+
+  async function findWireFile(root: string): Promise<string> {
+    const suffix = join('agents', 'main', 'wire.jsonl');
+    const entries = await readdir(root, { recursive: true });
+    const match = entries.find((entry) => entry.endsWith(suffix));
+    if (match === undefined) {
+      throw new Error('wire.jsonl not found under session home');
+    }
+    return join(root, match);
+  }
+
+  async function createTestRpc(options: { readonly telemetry?: TelemetryClient } = {}) {
+    const [coreRpc, sdkRpc] = createRPC<CoreAPI, SDKAPI>();
+    void new KimiCore(coreRpc, {
+      homeDir,
+      configPath,
+      telemetry: options.telemetry,
+    });
+    return sdkRpc({
+      emitEvent: vi.fn(),
+      requestApproval: vi.fn(async () => ({ decision: 'rejected' as const })),
+      requestQuestion: vi.fn(async () => null),
+      toolCall: vi.fn(async () => ({ output: '' })),
+    });
+  }
+});
diff --git a/packages/agent-core/test/harness/plan-mode-session.test.ts b/packages/agent-core/test/harness/plan-mode-session.test.ts
new file mode 100644
index 000000000..bbd578555
--- /dev/null
+++ b/packages/agent-core/test/harness/plan-mode-session.test.ts
@@ -0,0 +1,99 @@
+import { mkdtemp, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createRPC, KimiCore, type CoreAPI, type SDKAPI } from '../../src';
+
+const BASE_CONFIG = `
+default_model = "kimi-code/kimi-for-coding"
+
+[providers."managed:kimi-code"]
+type = "kimi"
+api_key = "test-key"
+base_url = "https://api.example/v1"
+
+[models."kimi-code/kimi-for-coding"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+max_context_size = 1000000
+`;
+
+describe('plan-mode bootstrap from config.defaultPlanMode', () => {
+  let tmp: string;
+  let homeDir: string;
+  let workDir: string;
+  let configPath: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), 'kimi-plan-mode-'));
+    homeDir = join(tmp, 'home');
+    workDir = join(tmp, 'work');
+    configPath = join(tmp, 'config.toml');
+    await mkdir(workDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('activates plan mode on a new session when config.defaultPlanMode is true', async () => {
+    await writeFile(configPath, `default_plan_mode = true\n${BASE_CONFIG}`);
+    const rpc = await createTestRpc();
+    const created = await rpc.createSession({ workDir });
+    await rpc.closeSession({ sessionId: created.id });
+
+    expect(await countPlanModeEnters()).toBe(1);
+  });
+
+  it('leaves plan mode inactive when config.defaultPlanMode is absent', async () => {
+    await writeFile(configPath, BASE_CONFIG);
+    const rpc = await createTestRpc();
+    const created = await rpc.createSession({ workDir });
+    await rpc.closeSession({ sessionId: created.id });
+
+    expect(await countPlanModeEnters()).toBe(0);
+  });
+
+  it('does not apply config.defaultPlanMode when resuming an existing session', async () => {
+    await writeFile(configPath, BASE_CONFIG);
+    const rpc = await createTestRpc();
+    const created = await rpc.createSession({ workDir });
+    await rpc.closeSession({ sessionId: created.id });
+
+    // Turning the default on after the session already exists must not
+    // retroactively push a resumed session into plan mode.
+    await writeFile(configPath, `default_plan_mode = true\n${BASE_CONFIG}`);
+    const freshRpc = await createTestRpc();
+    await freshRpc.resumeSession({ sessionId: created.id });
+    await freshRpc.closeSession({ sessionId: created.id });
+
+    expect(await countPlanModeEnters()).toBe(0);
+  });
+
+  async function countPlanModeEnters(): Promise<number> {
+    const suffix = join('agents', 'main', 'wire.jsonl');
+    const entries = await readdir(homeDir, { recursive: true });
+    const match = entries.find((entry) => entry.endsWith(suffix));
+    if (match === undefined) {
+      throw new Error('wire.jsonl not found under session home');
+    }
+    const lines = (await readFile(join(homeDir, match), 'utf-8'))
+      .split('\n')
+      .filter((line) => line.trim().length > 0);
+    return lines.filter((line) => (JSON.parse(line) as { type?: string }).type === 'plan_mode.enter')
+      .length;
+  }
+
+  async function createTestRpc() {
+    const [coreRpc, sdkRpc] = createRPC<CoreAPI, SDKAPI>();
+    void new KimiCore(coreRpc, { homeDir, configPath });
+    return sdkRpc({
+      emitEvent: vi.fn(),
+      requestApproval: vi.fn(async () => ({ decision: 'rejected' as const })),
+      requestQuestion: vi.fn(async () => null),
+      toolCall: vi.fn(async () => ({ output: '' })),
+    });
+  }
+});
diff --git a/packages/agent-core/test/harness/runtime-provider.test.ts b/packages/agent-core/test/harness/runtime-provider.test.ts
new file mode 100644
index 000000000..31264e800
--- /dev/null
+++ b/packages/agent-core/test/harness/runtime-provider.test.ts
@@ -0,0 +1,610 @@
+import { describe, expect, it } from 'vitest';
+
+import type { KimiConfig } from '../../src/config';
+import { KimiError } from '../../src/errors';
+import { resolveRuntimeProvider } from '../../src/providers/runtime-provider';
+import { ProviderManager } from '../../src/providers/provider-manager';
+
+const BASE_CONFIG: KimiConfig = {
+  defaultModel: 'kimi-code/kimi-for-coding',
+  providers: {
+    'managed:kimi-code': {
+      type: 'kimi',
+      apiKey: 'test-key',
+      baseUrl: 'https://api.example/v1',
+    },
+  },
+  models: {
+    'kimi-code/kimi-for-coding': {
+      provider: 'managed:kimi-code',
+      model: 'kimi-for-coding',
+      maxContextSize: 1_000_000,
+      capabilities: ['thinking', 'image_in', 'video_in', 'tool_use'],
+    },
+  },
+};
+
+const TEST_KIMI_HEADERS = {
+  'User-Agent': 'kimi-code-cli/0.0.0-test',
+  'X-Msh-Platform': 'kimi-code-cli',
+  'X-Msh-Version': '0.0.0-test',
+};
+
+describe('resolveRuntimeProvider model metadata', () => {
+  it('uses config model metadata as the source of truth', () => {
+    const resolved = resolveRuntimeProvider({
+      config: BASE_CONFIG,
+    });
+
+    expect(resolved.modelCapabilities).toMatchObject({
+      image_in: true,
+      video_in: true,
+      thinking: true,
+      tool_use: true,
+      max_context_tokens: 1_000_000,
+    });
+    expect(resolved.modelName).toBe('kimi-code/kimi-for-coding');
+    expect(resolved.provider.model).toBe('kimi-for-coding');
+  });
+
+  it('resolves requested aliases to the configured provider and provider model', () => {
+    const resolved = resolveRuntimeProvider({
+      config: {
+        ...BASE_CONFIG,
+        providers: {
+          ...BASE_CONFIG.providers,
+          openai: {
+            type: 'openai',
+            apiKey: 'sk-openai',
+            baseUrl: 'https://openai.example/v1',
+          },
+        },
+        models: {
+          ...BASE_CONFIG.models!,
+          'gpt-alias': {
+            provider: 'openai',
+            model: 'gpt-runtime',
+            maxContextSize: 200000,
+            capabilities: ['tool_use'],
+          },
+        },
+      },
+      model: 'gpt-alias',
+    });
+
+    expect(resolved.providerName).toBe('openai');
+    expect(resolved.modelName).toBe('gpt-alias');
+    expect(resolved.provider).toMatchObject({
+      type: 'openai',
+      model: 'gpt-runtime',
+      apiKey: 'sk-openai',
+      baseUrl: 'https://openai.example/v1',
+    });
+    expect(resolved.modelCapabilities).toMatchObject({
+      tool_use: true,
+      max_context_tokens: 200000,
+    });
+  });
+
+  it('uses config Kimi capabilities without requiring an api key during OAuth setup', () => {
+    const resolved = resolveRuntimeProvider({
+      config: {
+        ...BASE_CONFIG,
+        providers: {
+          'managed:kimi-code': {
+            type: 'kimi',
+            apiKey: '',
+            baseUrl: 'https://api.example/v1',
+            oauth: { storage: 'file', key: 'oauth/kimi-code' },
+          },
+        },
+      },
+    });
+
+    expect(resolved.modelCapabilities).toMatchObject({
+      image_in: true,
+      video_in: true,
+      thinking: true,
+      tool_use: true,
+      max_context_tokens: 1_000_000,
+    });
+  });
+
+  it('does not infer Kimi capabilities from the provider model name', () => {
+    const resolved = resolveRuntimeProvider({
+      config: {
+        ...BASE_CONFIG,
+        models: {
+          'kimi-code/kimi-for-coding': {
+            provider: 'managed:kimi-code',
+            model: 'kimi-for-coding',
+            maxContextSize: 1_000_000,
+          },
+        },
+      },
+    });
+
+    expect(resolved.modelCapabilities).toMatchObject({
+      image_in: false,
+      video_in: false,
+      thinking: false,
+      tool_use: false,
+      max_context_tokens: 1_000_000,
+    });
+  });
+
+  it('rejects provider model names that are not configured aliases', () => {
+    expect(() =>
+      resolveRuntimeProvider({
+        config: BASE_CONFIG,
+        model: 'kimi-for-coding',
+      }),
+    ).toThrow(/not configured in config.toml/);
+  });
+
+  it('throws when no model is selected', () => {
+    expect(() =>
+      resolveRuntimeProvider({
+        config: {
+          providers: {},
+        },
+      }),
+    ).toThrow(/No model is selected/);
+  });
+
+  it('throws when the selected model is not configured as an alias', () => {
+    expect(() =>
+      resolveRuntimeProvider({
+        config: BASE_CONFIG,
+        model: 'kimi-code',
+      }),
+    ).toThrow(KimiError);
+  });
+
+  it('throws when the selected provider has neither apiKey nor oauth configured', () => {
+    expect(() =>
+      resolveRuntimeProvider({
+        config: {
+          ...BASE_CONFIG,
+          providers: {
+            'managed:kimi-code': {
+              type: 'kimi',
+              baseUrl: 'https://api.example/v1',
+            },
+          },
+        },
+      }),
+    ).toThrow(/no credentials configured/i);
+  });
+
+  it('throws when apiKey is an empty string and no oauth is configured', () => {
+    expect(() =>
+      resolveRuntimeProvider({
+        config: {
+          ...BASE_CONFIG,
+          providers: {
+            'managed:kimi-code': {
+              type: 'kimi',
+              apiKey: '',
+              baseUrl: 'https://api.example/v1',
+            },
+          },
+        },
+      }),
+    ).toThrow(/no credentials configured/i);
+  });
+
+  it('allows vertexai providers without an apiKey', () => {
+    const resolved = resolveRuntimeProvider({
+      config: {
+        defaultModel: 'gemini',
+        providers: {
+          vertex: {
+            type: 'vertexai',
+          },
+        },
+        models: {
+          gemini: {
+            provider: 'vertex',
+            model: 'gemini-1.5-pro',
+            maxContextSize: 1_000_000,
+          },
+        },
+      },
+    });
+
+    expect(resolved.provider).toMatchObject({ type: 'vertexai' });
+  });
+
+  it('throws when the selected model alias has no maxContextSize', () => {
+    const config = {
+      ...BASE_CONFIG,
+      models: {
+        broken: {
+          provider: 'managed:kimi-code',
+          model: 'kimi-for-coding',
+          capabilities: ['thinking'],
+        },
+      },
+    } as unknown as KimiConfig;
+
+    expect(() =>
+      resolveRuntimeProvider({
+        config,
+        model: 'broken',
+      }),
+    ).toThrow(/max_context_size/);
+  });
+});
+
+describe('resolveRuntimeProvider maxOutputSize forwarding', () => {
+  it('forwards alias.maxOutputSize to the anthropic provider config as defaultMaxTokens', () => {
+    const resolved = resolveRuntimeProvider({
+      config: {
+        ...BASE_CONFIG,
+        providers: {
+          ...BASE_CONFIG.providers,
+          anthropic: { type: 'anthropic', apiKey: 'sk-anthropic' },
+        },
+        models: {
+          ...BASE_CONFIG.models!,
+          'opus-alias': {
+            provider: 'anthropic',
+            model: 'claude-opus-4-7',
+            maxContextSize: 200000,
+            maxOutputSize: 24000,
+          },
+        },
+      },
+      model: 'opus-alias',
+    });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'anthropic',
+      model: 'claude-opus-4-7',
+      defaultMaxTokens: 24000,
+    });
+  });
+
+  it('omits defaultMaxTokens when alias.maxOutputSize is unset', () => {
+    const resolved = resolveRuntimeProvider({
+      config: {
+        ...BASE_CONFIG,
+        providers: {
+          ...BASE_CONFIG.providers,
+          anthropic: { type: 'anthropic', apiKey: 'sk-anthropic' },
+        },
+        models: {
+          ...BASE_CONFIG.models!,
+          'opus-alias': {
+            provider: 'anthropic',
+            model: 'claude-opus-4-7',
+            maxContextSize: 200000,
+          },
+        },
+      },
+      model: 'opus-alias',
+    });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'anthropic',
+      model: 'claude-opus-4-7',
+    });
+    expect('defaultMaxTokens' in resolved.provider).toBe(false);
+  });
+});
+
+describe('resolveRuntimeProvider Kimi request headers', () => {
+  it('does not set defaultHeaders when no kimiRequestHeaders or customHeaders exist', () => {
+    const resolved = resolveRuntimeProvider({ config: BASE_CONFIG });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'kimi',
+      model: 'kimi-for-coding',
+    });
+    expect('defaultHeaders' in resolved.provider).toBe(false);
+  });
+
+  it('uses only customHeaders when kimiRequestHeaders are missing', () => {
+    const resolved = resolveRuntimeProvider({
+      config: {
+        ...BASE_CONFIG,
+        providers: {
+          'managed:kimi-code': {
+            type: 'kimi',
+            apiKey: 'test-key',
+            baseUrl: 'https://api.example/v1',
+            customHeaders: {
+              'User-Agent': 'Custom/1',
+            },
+          },
+        },
+      },
+    });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'kimi',
+      defaultHeaders: {
+        'User-Agent': 'Custom/1',
+      },
+    });
+  });
+
+  it('passes kimiRequestHeaders through to Kimi provider defaultHeaders', () => {
+    const resolved = resolveRuntimeProvider({
+      config: BASE_CONFIG,
+      kimiRequestHeaders: TEST_KIMI_HEADERS,
+    });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'kimi',
+      defaultHeaders: TEST_KIMI_HEADERS,
+    });
+  });
+
+  it('passes the prompt cache key to Kimi generation kwargs', () => {
+    const resolved = resolveRuntimeProvider({
+      config: BASE_CONFIG,
+      promptCacheKey: 'session-test',
+    });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'kimi',
+      generationKwargs: {
+        prompt_cache_key: 'session-test',
+      },
+    });
+  });
+
+  it('lets provider customHeaders override kimiRequestHeaders', () => {
+    const resolved = resolveRuntimeProvider({
+      config: {
+        ...BASE_CONFIG,
+        providers: {
+          'managed:kimi-code': {
+            type: 'kimi',
+            apiKey: 'test-key',
+            baseUrl: 'https://api.example/v1',
+            customHeaders: {
+              'User-Agent': 'Custom/1',
+              'X-Msh-Version': 'override-version',
+            },
+          },
+        },
+      },
+      kimiRequestHeaders: TEST_KIMI_HEADERS,
+    });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'kimi',
+      defaultHeaders: {
+        'User-Agent': 'Custom/1',
+        'X-Msh-Platform': 'kimi-code-cli',
+        'X-Msh-Version': 'override-version',
+      },
+    });
+  });
+
+  it('does not apply kimiRequestHeaders to non-Kimi providers', () => {
+    const resolved = resolveRuntimeProvider({
+      config: {
+        defaultModel: 'gpt-alias',
+        providers: {
+          openai: {
+            type: 'openai',
+            apiKey: 'sk-openai',
+          },
+        },
+        models: {
+          'gpt-alias': {
+            provider: 'openai',
+            model: 'gpt-runtime',
+            maxContextSize: 200000,
+          },
+        },
+      },
+      kimiRequestHeaders: TEST_KIMI_HEADERS,
+      promptCacheKey: 'session-test',
+    });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'openai',
+      model: 'gpt-runtime',
+      apiKey: 'sk-openai',
+    });
+    expect('defaultHeaders' in resolved.provider).toBe(false);
+    expect('generationKwargs' in resolved.provider).toBe(false);
+  });
+});
+
+describe('resolveRuntimeProvider customHeaders propagation', () => {
+  it('forwards customHeaders to an anthropic provider', () => {
+    const resolved = resolveRuntimeProvider({
+      config: {
+        defaultModel: 'claude-alias',
+        providers: {
+          anthropic: {
+            type: 'anthropic',
+            apiKey: 'sk-anthropic',
+            customHeaders: { 'X-Custom': 'value' },
+          },
+        },
+        models: {
+          'claude-alias': { provider: 'anthropic', model: 'claude-runtime', maxContextSize: 200000 },
+        },
+      },
+    });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'anthropic',
+      defaultHeaders: { 'X-Custom': 'value' },
+    });
+  });
+
+  it('forwards customHeaders to an openai provider', () => {
+    const resolved = resolveRuntimeProvider({
+      config: {
+        defaultModel: 'gpt-alias',
+        providers: {
+          openai: {
+            type: 'openai',
+            apiKey: 'sk-openai',
+            customHeaders: { 'X-Custom': 'value' },
+          },
+        },
+        models: {
+          'gpt-alias': { provider: 'openai', model: 'gpt-runtime', maxContextSize: 200000 },
+        },
+      },
+    });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'openai',
+      defaultHeaders: { 'X-Custom': 'value' },
+    });
+  });
+
+  it('forwards customHeaders to an openai_responses provider', () => {
+    const resolved = resolveRuntimeProvider({
+      config: {
+        defaultModel: 'resp-alias',
+        providers: {
+          openai_responses: {
+            type: 'openai_responses',
+            apiKey: 'sk-openai',
+            customHeaders: { 'X-Custom': 'value' },
+          },
+        },
+        models: {
+          'resp-alias': {
+            provider: 'openai_responses',
+            model: 'gpt-runtime',
+            maxContextSize: 200000,
+          },
+        },
+      },
+    });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'openai_responses',
+      defaultHeaders: { 'X-Custom': 'value' },
+    });
+  });
+
+  it('keeps customHeaders isolated between resolved provider instances', () => {
+    const config: KimiConfig = {
+      defaultModel: 'gpt-alias',
+      providers: {
+        openai: {
+          type: 'openai',
+          apiKey: 'sk-openai',
+          customHeaders: { 'X-Custom': 'original' },
+        },
+      },
+      models: {
+        'gpt-alias': { provider: 'openai', model: 'gpt-runtime', maxContextSize: 200000 },
+      },
+    };
+
+    const first = resolveRuntimeProvider({ config });
+    const second = resolveRuntimeProvider({ config });
+    const firstHeaders = (first.provider as { defaultHeaders?: Record<string, string> })
+      .defaultHeaders;
+    expect(firstHeaders).toEqual({ 'X-Custom': 'original' });
+
+    firstHeaders!['X-Custom'] = 'mutated';
+
+    expect(
+      (second.provider as { defaultHeaders?: Record<string, string> }).defaultHeaders,
+    ).toEqual({ 'X-Custom': 'original' });
+    expect(config.providers['openai']?.customHeaders).toEqual({ 'X-Custom': 'original' });
+  });
+});
+
+describe('ProviderManager prompt cache key', () => {
+  it('applies a prompt cache key to Kimi providers', () => {
+    const manager = new ProviderManager({ config: BASE_CONFIG }).withPromptCacheKey(
+      'session-test',
+    );
+    const resolved = manager.resolveProviderConfigForModel('kimi-code/kimi-for-coding');
+
+    expect(resolved?.provider).toMatchObject({
+      type: 'kimi',
+      generationKwargs: {
+        prompt_cache_key: 'session-test',
+      },
+    });
+  });
+
+  it('does not add generation kwargs to non-Kimi providers', () => {
+    const manager = new ProviderManager({
+      config: {
+        defaultModel: 'gpt-alias',
+        providers: {
+          openai: {
+            type: 'openai',
+            apiKey: 'sk-openai',
+          },
+        },
+        models: {
+          'gpt-alias': {
+            provider: 'openai',
+            model: 'gpt-runtime',
+            maxContextSize: 200000,
+          },
+        },
+      },
+    }).withPromptCacheKey('session-test');
+    const resolved = manager.resolveProviderConfigForModel('gpt-alias');
+
+    expect(resolved?.provider).toMatchObject({
+      type: 'openai',
+      model: 'gpt-runtime',
+    });
+    expect('generationKwargs' in resolved!.provider).toBe(false);
+  });
+
+  it('keeps derived managers on the latest shared config', () => {
+    const manager = new ProviderManager({ config: { providers: {} } });
+    const derived = manager.withPromptCacheKey('session-test');
+
+    manager.updateConfig(BASE_CONFIG);
+
+    const resolved = derived.resolveProviderConfigForModel(undefined);
+    expect(resolved?.provider).toMatchObject({
+      type: 'kimi',
+      generationKwargs: {
+        prompt_cache_key: 'session-test',
+      },
+    });
+  });
+});
+
+describe('ProviderManager thinking level', () => {
+  it('normalizes requested thinking into a concrete effort', () => {
+    const manager = new ProviderManager({
+      config: {
+        providers: {},
+        thinking: { effort: 'medium', mode: 'auto' },
+      },
+    });
+    expect(manager.resolveThinkingLevel('on')).toBe('medium');
+    expect(manager.resolveThinkingLevel('off')).toBe('off');
+    expect(manager.resolveThinkingLevel('low')).toBe('low');
+    expect(manager.resolveThinkingLevel()).toBe('medium');
+
+    const managerWithoutEffort = new ProviderManager({
+      config: { providers: {}, thinking: { mode: 'auto' } },
+    });
+    expect(managerWithoutEffort.resolveThinkingLevel('on')).toBe('high');
+    expect(managerWithoutEffort.resolveThinkingLevel()).toBe('high');
+
+    const managerOffByDefault = new ProviderManager({
+      config: { providers: {}, thinking: { mode: 'off' } },
+    });
+    expect(managerOffByDefault.resolveThinkingLevel()).toBe('off');
+
+    const managerWithoutThinking = new ProviderManager({ config: { providers: {} } });
+    expect(managerWithoutThinking.resolveThinkingLevel()).toBe('high');
+  });
+});
diff --git a/packages/agent-core/test/harness/runtime.test.ts b/packages/agent-core/test/harness/runtime.test.ts
new file mode 100644
index 000000000..2e272bb90
--- /dev/null
+++ b/packages/agent-core/test/harness/runtime.test.ts
@@ -0,0 +1,89 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createRPC,
+  KimiCore,
+  type ApprovalResponse,
+  type CoreAPI,
+  type SDKAPI,
+} from '../../src';
+import type { OAuthTokenProviderResolver } from '../../src/providers/runtime-provider';
+
+describe('KimiCore runtime config', () => {
+  let tmp: string;
+
+  afterEach(async () => {
+    if (tmp !== undefined) {
+      await rm(tmp, { recursive: true, force: true });
+    }
+    vi.unstubAllGlobals();
+  });
+
+  it('uses the shared OAuth resolver for Moonshot service tokens', async () => {
+    tmp = await mkdtemp(join(tmpdir(), 'kimi-core-runtime-'));
+    const homeDir = join(tmp, 'home');
+    const workDir = join(tmp, 'work');
+    await mkdir(homeDir, { recursive: true });
+    await mkdir(workDir, { recursive: true });
+    await writeFile(
+      join(homeDir, 'config.toml'),
+      `
+[services.moonshot_search]
+base_url = "https://search.example/v1"
+oauth = { storage = "file", key = "oauth/custom-kimi-code" }
+custom_headers = { "X-Test" = "1" }
+`,
+    );
+
+    const getAccessToken = vi.fn().mockResolvedValue('service-token');
+    const resolveOAuthTokenProvider = vi.fn<OAuthTokenProviderResolver>(() => ({
+      getAccessToken,
+    }));
+    const fetchImpl = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ search_results: [] }), {
+        status: 200,
+      }),
+    );
+    vi.stubGlobal('fetch', fetchImpl);
+
+    const [coreRpc, sdkRpc] = createRPC<CoreAPI, SDKAPI>();
+    const core = new KimiCore(coreRpc, {
+      homeDir,
+      kimiRequestHeaders: {
+        'User-Agent': 'kimi-code-cli/0.0.0-test',
+        'X-Msh-Version': '0.0.0-test',
+      },
+      resolveOAuthTokenProvider,
+    });
+    const rpc = await sdkRpc({
+      emitEvent: vi.fn(),
+      requestApproval: vi.fn(async (): Promise<ApprovalResponse> => ({ decision: 'rejected' })),
+      requestQuestion: vi.fn(async () => null),
+      toolCall: vi.fn(async () => ({ output: '' })),
+    });
+
+    const created = await rpc.createSession({ id: 'ses_runtime_service_oauth', workDir });
+    const session = core.sessions.get(created.id);
+
+    expect(resolveOAuthTokenProvider).toHaveBeenCalledWith('managed:kimi-code', {
+      storage: 'file',
+      key: 'oauth/custom-kimi-code',
+    });
+    expect(session?.config.runtime.webSearcher).toBeDefined();
+
+    await session!.config.runtime.webSearcher!.search('kimi');
+
+    expect(getAccessToken).toHaveBeenCalledWith();
+    const init = fetchImpl.mock.calls[0]?.[1] as RequestInit;
+    expect(init.headers).toMatchObject({
+      Authorization: 'Bearer service-token',
+      'User-Agent': 'kimi-code-cli/0.0.0-test',
+      'X-Msh-Version': '0.0.0-test',
+      'X-Test': '1',
+    });
+  });
+});
diff --git a/packages/agent-core/test/harness/skill-session.test.ts b/packages/agent-core/test/harness/skill-session.test.ts
new file mode 100644
index 000000000..8cb0c1612
--- /dev/null
+++ b/packages/agent-core/test/harness/skill-session.test.ts
@@ -0,0 +1,556 @@
+import { mkdtemp, mkdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createRPC,
+  KimiCore,
+  type ApprovalResponse,
+  type CoreAPI,
+  type CoreRPC,
+  type Event,
+  type SDKAPI,
+  type TelemetryClient,
+} from '../../src';
+import {
+  recordingContextTelemetry,
+  type TelemetryContextRecord,
+} from '../fixtures/telemetry';
+
+describe('HarnessAPI session skills', () => {
+  let tmp: string;
+  let homeDir: string;
+  let workDir: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), 'kimi-core-skills-'));
+    homeDir = join(tmp, 'home');
+    workDir = join(tmp, 'work');
+    await mkdir(workDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+    vi.unstubAllEnvs();
+  });
+
+  it('lists session skills without exposing content', async () => {
+    await writeSkill('phase-one-review', [
+      '---',
+      'name: phase-one-review',
+      'description: Review code',
+      'disable_model_invocation: true',
+      '---',
+      '',
+      'Review the requested file.',
+    ]);
+    const { rpc } = await createTestRpc();
+    const created = await rpc.createSession({ id: 'ses_skill_list', workDir });
+
+    const skills = await rpc.listSkills({ sessionId: created.id });
+    const listed = skills.find((skill) => skill.name === 'phase-one-review');
+
+    expect(listed).toMatchObject({
+      name: 'phase-one-review',
+      description: 'Review code',
+      source: 'project',
+      disableModelInvocation: true,
+    });
+    expect(listed?.path.endsWith('/.kimi-code/skills/phase-one-review/SKILL.md')).toBe(true);
+    expect(JSON.stringify(skills)).not.toContain('Review the requested file.');
+  });
+
+  it('uses the first body line when a flat skill description is missing', async () => {
+    await writeFlatSkill('body-described', [
+      '',
+      '  First useful line that describes it.  ',
+      '',
+      'Full instructions stay private.',
+    ]);
+    const { rpc } = await createTestRpc();
+    const created = await rpc.createSession({ id: 'ses_skill_description_fallback', workDir });
+
+    const skills = await rpc.listSkills({ sessionId: created.id });
+    const listed = skills.find((skill) => skill.name === 'body-described');
+
+    expect(listed).toMatchObject({
+      name: 'body-described',
+      description: 'First useful line that describes it.',
+      source: 'project',
+    });
+    expect(JSON.stringify(skills)).not.toContain('Full instructions stay private.');
+  });
+
+  it('lists bundled built-in skills by default', async () => {
+    const { rpc } = await createTestRpc();
+    const created = await rpc.createSession({ id: 'ses_builtin_skill_list', workDir });
+
+    const skills = await rpc.listSkills({ sessionId: created.id });
+    const listed = skills.find((skill) => skill.name === 'mcp-config');
+
+    expect(listed).toMatchObject({
+      name: 'mcp-config',
+      description: 'Configure MCP servers and handle MCP OAuth login.',
+      source: 'builtin',
+    });
+    expect(listed?.path).toBe('builtin://mcp-config');
+    expect(JSON.stringify(skills)).not.toContain('Your tool list contains one synthetic tool');
+  });
+
+  it('uses the explicit core home as user skill home instead of the process home', async () => {
+    const processHome = join(tmp, 'process-home');
+    vi.stubEnv('HOME', processHome);
+    await writeUserSkill(processHome, 'real-home-only', 'Real home skill');
+    await writeUserSkill(homeDir, 'sandbox-only', 'Sandbox skill');
+    const { rpc } = await createTestRpc();
+    const created = await rpc.createSession({ id: 'ses_skill_sandbox_home', workDir });
+
+    const names = new Set((await rpc.listSkills({ sessionId: created.id })).map((skill) => skill.name));
+
+    expect(names.has('sandbox-only')).toBe(true);
+    expect(names.has('real-home-only')).toBe(false);
+  });
+
+  it('uses KIMI_CODE_HOME as user skill home when core home comes from env', async () => {
+    const processHome = join(tmp, 'env-process-home');
+    vi.stubEnv('HOME', processHome);
+    vi.stubEnv('KIMI_CODE_HOME', homeDir);
+    await writeUserSkill(processHome, 'env-real-home-only', 'Env real home skill');
+    await writeUserSkill(homeDir, 'env-sandbox-only', 'Env sandbox skill');
+    const { rpc } = await createTestRpc({});
+    const created = await rpc.createSession({ id: 'ses_skill_env_home', workDir });
+
+    const names = new Set((await rpc.listSkills({ sessionId: created.id })).map((skill) => skill.name));
+
+    expect(names.has('env-sandbox-only')).toBe(true);
+    expect(names.has('env-real-home-only')).toBe(false);
+  });
+
+  it('activates an inline skill through core and records display origin metadata', async () => {
+    await writeSkill('phase-one-review', [
+      '---',
+      'name: phase-one-review',
+      'description: Review code',
+      'disable_model_invocation: true',
+      '---',
+      '',
+      'Review the requested file.',
+    ]);
+    const telemetryRecords: TelemetryContextRecord[] = [];
+    const { core, events, rpc } = await createTestRpc({
+      homeDir,
+      telemetry: recordingContextTelemetry(telemetryRecords),
+    });
+    const created = await rpc.createSession({ id: 'ses_skill_activate', workDir });
+
+    await rpc.activateSkill({
+      sessionId: created.id,
+      agentId: 'main',
+      name: 'phase-one-review',
+      args: 'src/app.ts',
+    });
+    await waitForEvent(events, (event) => event.type === 'skill.activated');
+    await core.sessions.get(created.id)?.flushMetadata();
+
+    const skillEvent = events.find((event) => event.type === 'skill.activated');
+    expect(skillEvent).toMatchObject({
+      type: 'skill.activated',
+      agentId: 'main',
+      sessionId: created.id,
+      skillName: 'phase-one-review',
+      skillArgs: 'src/app.ts',
+      trigger: 'user-slash',
+      skillSource: 'project',
+    });
+    expect(JSON.stringify(skillEvent)).not.toContain('Review the requested file.');
+    expect(telemetryRecords).toContainEqual({
+      event: 'skill_invoked',
+      sessionId: created.id,
+      properties: {
+        skill_name: 'phase-one-review',
+        trigger: 'user-slash',
+      },
+    });
+    expect(telemetryRecords.some((record) => record.event === 'flow_invoked')).toBe(false);
+
+    const skillIndex = events.findIndex((event) => event.type === 'skill.activated');
+    const turnIndex = events.findIndex((event) => event.type === 'turn.started');
+    expect(skillIndex).toBeGreaterThanOrEqual(0);
+    expect(turnIndex).toBeGreaterThan(skillIndex);
+
+    const records = await readMainWire(created.sessionDir);
+    const prompt = records.find((record) => record['type'] === 'turn.prompt');
+    const userMessage = records.find((record) => record['type'] === 'context.append_message');
+    const expectedPrompt = 'Review the requested file.\n\nARGUMENTS: src/app.ts';
+    expect(prompt).toMatchObject({
+      type: 'turn.prompt',
+      input: [{ type: 'text', text: expectedPrompt }],
+      origin: {
+        kind: 'skill_activation',
+        skillName: 'phase-one-review',
+        skillArgs: 'src/app.ts',
+        trigger: 'user-slash',
+        skillSource: 'project',
+      },
+    });
+    expect(userMessage).toMatchObject({
+      type: 'context.append_message',
+      message: {
+        role: 'user',
+        content: [{ type: 'text', text: expectedPrompt }],
+        origin: {
+          kind: 'skill_activation',
+          skillName: 'phase-one-review',
+          skillArgs: 'src/app.ts',
+          trigger: 'user-slash',
+          skillSource: 'project',
+        },
+      },
+    });
+    expect(
+      (prompt as { origin?: { activationId?: string } } | undefined)?.origin?.activationId,
+    ).toBe((skillEvent as { activationId?: string } | undefined)?.activationId);
+    expect((skillEvent as { activationId?: string } | undefined)?.activationId).toBe(
+      (userMessage as { message?: { origin?: { activationId?: string } } } | undefined)?.message
+        ?.origin?.activationId,
+    );
+
+    const context = await rpc.getContext({ sessionId: created.id, agentId: 'main' });
+    expect(context.history.at(0)).toMatchObject({
+      role: 'user',
+      content: [{ type: 'text', text: expectedPrompt }],
+      toolCalls: [],
+      origin: {
+        kind: 'skill_activation',
+        skillName: 'phase-one-review',
+        skillArgs: 'src/app.ts',
+        trigger: 'user-slash',
+        skillSource: 'project',
+      },
+    });
+  });
+
+  it('expands skill body placeholders on user slash activation', async () => {
+    await writeSkill('templated-review', [
+      '---',
+      'name: templated-review',
+      'description: Review with template variables',
+      'arguments:',
+      '  - target',
+      '  - mode',
+      '---',
+      '',
+      'Target: $target',
+      'Mode: $mode',
+      'Raw: $ARGUMENTS',
+      'Dir: ${KIMI_SKILL_DIR}',
+      'Session: ${KIMI_SESSION_ID}',
+    ]);
+    const { core, rpc } = await createTestRpc({ homeDir });
+    const created = await rpc.createSession({ id: 'ses_skill_template', workDir });
+
+    await rpc.activateSkill({
+      sessionId: created.id,
+      agentId: 'main',
+      name: 'templated-review',
+      args: '"src/app.ts" careful',
+    });
+    await core.sessions.get(created.id)?.flushMetadata();
+
+    const records = await readMainWire(created.sessionDir);
+    const prompt = records.find((record) => record['type'] === 'turn.prompt');
+    const skillDir = await realpath(join(workDir, '.kimi-code', 'skills', 'templated-review'));
+    const expectedPrompt = [
+      'Target: src/app.ts',
+      'Mode: careful',
+      'Raw: "src/app.ts" careful',
+      `Dir: ${skillDir}`,
+      'Session: ses_skill_template',
+    ].join('\n');
+    expect(prompt).toMatchObject({
+      type: 'turn.prompt',
+      input: [{ type: 'text', text: expectedPrompt }],
+      origin: {
+        kind: 'skill_activation',
+        skillName: 'templated-review',
+        skillArgs: '"src/app.ts" careful',
+      },
+    });
+    expect(JSON.stringify(prompt)).not.toContain('ARGUMENTS:');
+  });
+
+  it('records legacy flow telemetry when activating a flow skill', async () => {
+    await writeSkill('review-flow', [
+      '---',
+      'name: review-flow',
+      'description: Review flow',
+      'type: flow',
+      '---',
+      '',
+      'Review the requested file as a flow.',
+    ]);
+    const telemetryRecords: TelemetryContextRecord[] = [];
+    const { events, rpc } = await createTestRpc({
+      homeDir,
+      telemetry: recordingContextTelemetry(telemetryRecords),
+    });
+    const created = await rpc.createSession({ id: 'ses_flow_skill_activate', workDir });
+
+    await rpc.activateSkill({
+      sessionId: created.id,
+      agentId: 'main',
+      name: 'review-flow',
+    });
+    await waitForEvent(events, (event) => event.type === 'skill.activated');
+
+    expect(telemetryRecords).toContainEqual({
+      event: 'skill_invoked',
+      sessionId: created.id,
+      properties: {
+        skill_name: 'review-flow',
+        trigger: 'user-slash',
+      },
+    });
+    expect(telemetryRecords).toContainEqual({
+      event: 'flow_invoked',
+      sessionId: created.id,
+      properties: {
+        flow_name: 'review-flow',
+      },
+    });
+  });
+
+  it('does not re-emit skill activation live events on resume', async () => {
+    await writeSkill('phase-one-review', [
+      '---',
+      'name: phase-one-review',
+      'description: Review code',
+      '---',
+      '',
+      'Review the requested file.',
+    ]);
+    const first = await createTestRpc();
+    const created = await first.rpc.createSession({ id: 'ses_skill_resume', workDir });
+    await first.rpc.activateSkill({
+      sessionId: created.id,
+      agentId: 'main',
+      name: 'phase-one-review',
+      args: 'src/app.ts',
+    });
+    await waitForEvent(first.events, (event) => event.type === 'skill.activated');
+    await first.core.sessions.get(created.id)?.flushMetadata();
+
+    const second = await createTestRpc();
+    const resumed = await second.rpc.resumeSession({ sessionId: created.id });
+
+    expect(second.events.some((event) => event.type === 'skill.activated')).toBe(false);
+    const context = await second.rpc.getContext({ sessionId: created.id, agentId: 'main' });
+    expect(context.history).toMatchObject([
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: 'Review the requested file.\n\nARGUMENTS: src/app.ts',
+          },
+        ],
+        origin: {
+          kind: 'skill_activation',
+          skillName: 'phase-one-review',
+          skillArgs: 'src/app.ts',
+          trigger: 'user-slash',
+          skillSource: 'project',
+        },
+      },
+    ]);
+    const replay = resumed.agents['main']?.replay ?? [];
+    expect(replay).toContainEqual(
+      expect.objectContaining({
+        type: 'message',
+        message: expect.objectContaining({
+          origin: expect.objectContaining({
+            kind: 'skill_activation',
+            skillName: 'phase-one-review',
+          }),
+        }),
+      }),
+    );
+    expect(replay).not.toContainEqual(
+      expect.objectContaining({
+        type: 'turn.prompt',
+        origin: expect.objectContaining({ kind: 'skill_activation' }),
+      }),
+    );
+  });
+
+  it('registers builtin mcp-config skill, hides it from the model, and activates it via slash', async () => {
+    const { core, events, rpc } = await createTestRpc();
+    const created = await rpc.createSession({ id: 'ses_skill_builtin', workDir });
+
+    const skills = await rpc.listSkills({ sessionId: created.id });
+    const builtin = skills.find((skill) => skill.name === 'mcp-config');
+    expect(builtin).toMatchObject({
+      name: 'mcp-config',
+      source: 'builtin',
+      disableModelInvocation: true,
+    });
+
+    const session = core.sessions.get(created.id);
+    expect(session).toBeDefined();
+    const invocable = session!.skills.listInvocableSkills();
+    expect(invocable.some((skill) => skill.name === 'mcp-config')).toBe(false);
+    expect(session!.skills.getModelSkillListing()).not.toContain('mcp-config');
+
+    await rpc.activateSkill({
+      sessionId: created.id,
+      agentId: 'main',
+      name: 'mcp-config',
+    });
+    const activated = await waitForEvent(events, (event) => event.type === 'skill.activated');
+    expect(activated).toMatchObject({
+      type: 'skill.activated',
+      skillName: 'mcp-config',
+      trigger: 'user-slash',
+      skillSource: 'builtin',
+    });
+
+    await session?.flushMetadata();
+    const records = await readMainWire(created.sessionDir);
+    const prompt = records.find((record) => record['type'] === 'turn.prompt');
+    expect(prompt).toMatchObject({
+      type: 'turn.prompt',
+      origin: {
+        kind: 'skill_activation',
+        skillName: 'mcp-config',
+        skillSource: 'builtin',
+      },
+    });
+    const promptInput = (prompt as { input?: ReadonlyArray<{ text?: string }> } | undefined)?.input;
+    expect(promptInput?.[0]?.text).toContain('Interactive MCP server configuration');
+    expect(promptInput?.[0]?.text).toContain('AskUserQuestion');
+  });
+
+  it('lets a user-supplied skill override the builtin of the same name', async () => {
+    await writeSkill('mcp-config', [
+      '---',
+      'name: mcp-config',
+      'description: Project-local override',
+      '---',
+      '',
+      'Local override body.',
+    ]);
+    const { rpc } = await createTestRpc();
+    const created = await rpc.createSession({ id: 'ses_skill_builtin_override', workDir });
+
+    const skills = await rpc.listSkills({ sessionId: created.id });
+    const listed = skills.find((skill) => skill.name === 'mcp-config');
+    expect(listed).toMatchObject({
+      name: 'mcp-config',
+      source: 'project',
+      description: 'Project-local override',
+    });
+  });
+
+  it('rejects missing and non-inline skills with structured errors', async () => {
+    const { core, rpc } = await createTestRpc();
+    const created = await rpc.createSession({ id: 'ses_skill_errors', workDir });
+
+    await expect(
+      rpc.activateSkill({ sessionId: created.id, agentId: 'main', name: 'missing' }),
+    ).rejects.toMatchObject({
+      name: 'KimiError',
+      code: 'skill.not_found',
+    });
+
+    const session = core.sessions.get(created.id);
+    session?.skills.registerBuiltinSkill({
+      name: 'forked',
+      description: 'Forked skill',
+      path: '/skills/forked/SKILL.md',
+      dir: '/skills/forked',
+      content: 'fork body',
+      metadata: { type: 'fork' },
+      source: 'builtin',
+    });
+
+    await expect(
+      rpc.activateSkill({ sessionId: created.id, agentId: 'main', name: 'forked' }),
+    ).rejects.toMatchObject({
+      name: 'KimiError',
+      code: 'skill.type_unsupported',
+    });
+  });
+
+  async function writeSkill(name: string, lines: readonly string[]): Promise<void> {
+    const dir = join(workDir, '.kimi-code', 'skills', name);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'SKILL.md'), lines.join('\n'));
+  }
+
+  async function writeUserSkill(userHomeDir: string, name: string, description: string): Promise<void> {
+    const dir = join(userHomeDir, '.kimi-code', 'skills', name);
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      join(dir, 'SKILL.md'),
+      ['---', `name: ${name}`, `description: ${description}`, '---', '', `${description}.`].join(
+        '\n',
+      ),
+    );
+  }
+
+  async function writeFlatSkill(name: string, lines: readonly string[]): Promise<void> {
+    const dir = join(workDir, '.kimi-code', 'skills');
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, `${name}.md`), lines.join('\n'));
+  }
+
+  async function createTestRpc(options?: {
+    readonly homeDir?: string;
+    readonly telemetry?: TelemetryClient;
+  }): Promise<{
+    core: KimiCore;
+    events: Event[];
+    rpc: CoreRPC;
+  }> {
+    const [coreRpc, sdkRpc] = createRPC<CoreAPI, SDKAPI>();
+    const events: Event[] = [];
+    const configuredHomeDir = options === undefined ? homeDir : options.homeDir;
+    const core = new KimiCore(
+      coreRpc,
+      { homeDir: configuredHomeDir, telemetry: options?.telemetry },
+    );
+    const rpc = await sdkRpc({
+      emitEvent: (event) => {
+        events.push(event);
+      },
+      requestApproval: vi.fn(async (): Promise<ApprovalResponse> => ({ decision: 'rejected' })),
+      requestQuestion: vi.fn(async () => null),
+      toolCall: vi.fn(async () => ({ output: '' })),
+    });
+    return { core, events, rpc };
+  }
+});
+
+async function waitForEvent(
+  events: readonly Event[],
+  predicate: (event: Event) => boolean,
+): Promise<Event> {
+  const deadline = Date.now() + 1_000;
+  while (Date.now() < deadline) {
+    const event = events.find(predicate);
+    if (event !== undefined) return event;
+    await delay(10);
+  }
+  throw new Error('Timed out waiting for event');
+}
+
+async function readMainWire(sessionDir: string): Promise<Array<Record<string, unknown>>> {
+  const raw = await readFile(join(sessionDir, 'agents', 'main', 'wire.jsonl'), 'utf-8');
+  return raw
+    .split('\n')
+    .filter((line) => line.length > 0)
+    .map((line) => JSON.parse(line) as Record<string, unknown>);
+}
diff --git a/packages/agent-core/test/hooks/engine.test.ts b/packages/agent-core/test/hooks/engine.test.ts
new file mode 100644
index 000000000..66896c394
--- /dev/null
+++ b/packages/agent-core/test/hooks/engine.test.ts
@@ -0,0 +1,352 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ContentPart } from '@moonshot-ai/kosong';
+
+// Dynamic-import contract: locks the public shape of the future HookEngine
+// without forcing TS module resolution to find a file that doesn't exist yet.
+const ENGINE_MODULE = '../../src/agent/hooks/engine' as string;
+
+type HookDef = {
+  event: string;
+  matcher?: string;
+  command: string;
+  timeout?: number;
+};
+
+interface HookResult {
+  action: 'allow' | 'block';
+  reason?: string;
+  stdout?: string;
+  stderr?: string;
+  timedOut?: boolean;
+}
+
+interface HookBlockDecision {
+  block: true;
+  reason?: string;
+}
+
+type HookMatcherValue = string | readonly ContentPart[];
+
+interface HookEngineCtor {
+  new (
+    hooks: HookDef[],
+    options?: {
+      cwd?: string;
+      sessionId?: string;
+      onTriggered?: (event: string, target: string, count: number) => void;
+      onResolved?: (
+        event: string,
+        target: string,
+        action: string,
+        reason: string | undefined,
+        durationMs: number,
+      ) => void;
+    },
+  ): {
+    trigger: (
+      event: string,
+      args?: {
+        matcherValue?: HookMatcherValue;
+        inputData?: Record<string, unknown>;
+        signal?: AbortSignal;
+      },
+    ) => Promise<HookResult[]>;
+    triggerBlock: (
+      event: string,
+      args?: {
+        matcherValue?: HookMatcherValue;
+        inputData?: Record<string, unknown>;
+        signal?: AbortSignal;
+      },
+    ) => Promise<HookBlockDecision | undefined>;
+    fireAndForgetTrigger: (
+      event: string,
+      args?: {
+        matcherValue?: HookMatcherValue;
+        inputData?: Record<string, unknown>;
+        signal?: AbortSignal;
+      },
+    ) => Promise<HookResult[]>;
+    summary: Record<string, number>;
+  };
+}
+
+interface EngineModule {
+  HookEngine: HookEngineCtor;
+}
+
+async function importEngine(): Promise<EngineModule> {
+  return (await import(ENGINE_MODULE)) as EngineModule;
+}
+
+describe('HookEngine', () => {
+  it('fires a PreToolUse hook whose matcher regex matches the matcher value', async () => {
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine([
+      { event: 'PreToolUse', matcher: 'Shell|WriteFile', command: 'exit 0', timeout: 5 },
+      { event: 'PreToolUse', matcher: 'ReadFile', command: 'exit 2', timeout: 5 },
+      { event: 'Stop', matcher: '', command: 'echo done', timeout: 5 },
+    ]);
+    const results = await engine.trigger('PreToolUse', {
+      matcherValue: 'Shell',
+      inputData: { toolName: 'Shell' },
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0]?.action).toBe('allow');
+  });
+
+  it('returns no results when no hook matcher matches the matcher value', async () => {
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine([
+      { event: 'PreToolUse', matcher: 'Shell|WriteFile', command: 'exit 0', timeout: 5 },
+      { event: 'PreToolUse', matcher: 'ReadFile', command: 'exit 2', timeout: 5 },
+    ]);
+    const results = await engine.trigger('PreToolUse', {
+      matcherValue: 'Grep',
+      inputData: {},
+    });
+    expect(results).toHaveLength(0);
+  });
+
+  it('maps exit code 2 to a block action', async () => {
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine([
+      { event: 'PreToolUse', matcher: 'ReadFile', command: 'exit 2', timeout: 5 },
+    ]);
+    const results = await engine.trigger('PreToolUse', {
+      matcherValue: 'ReadFile',
+      inputData: {},
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0]?.action).toBe('block');
+  });
+
+  it('exposes a triggerBlock helper for block decisions', async () => {
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine([
+      {
+        event: 'PreToolUse',
+        matcher: 'ReadFile',
+        command: "echo 'blocked' >&2; exit 2",
+        timeout: 5,
+      },
+    ]);
+
+    await expect(
+      engine.triggerBlock('PreToolUse', {
+        matcherValue: 'ReadFile',
+        inputData: {},
+      }),
+    ).resolves.toEqual({ block: true, reason: 'blocked' });
+  });
+
+  it('fills a default triggerBlock reason when the hook result has none', async () => {
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine([
+      { event: 'PreToolUse', matcher: 'ReadFile', command: 'exit 2', timeout: 5 },
+    ]);
+
+    await expect(
+      engine.triggerBlock('PreToolUse', {
+        matcherValue: 'ReadFile',
+        inputData: {},
+      }),
+    ).resolves.toEqual({ block: true, reason: 'Blocked by PreToolUse hook' });
+  });
+
+  it('aborts a running hook when the trigger signal aborts', async () => {
+    const { HookEngine } = await importEngine();
+    const abortController = new AbortController();
+    const engine = new HookEngine([
+      {
+        event: 'PreToolUse',
+        matcher: 'Shell',
+        command: 'node -e "setTimeout(() => {}, 10000)"',
+        timeout: 5,
+      },
+    ]);
+    const startedAt = Date.now();
+    setTimeout(() => {
+      abortController.abort();
+    }, 50);
+
+    const results = await engine.trigger('PreToolUse', {
+      matcherValue: 'Shell',
+      inputData: {},
+      signal: abortController.signal,
+    });
+
+    expect(Date.now() - startedAt).toBeLessThan(1000);
+    expect(results).toHaveLength(1);
+    expect(results[0]?.action).toBe('allow');
+    expect(results[0]?.timedOut).toBeUndefined();
+  });
+
+  it('serializes camelCase inputData as snake_case for hook stdin', async () => {
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine([
+      {
+        event: 'PreToolUse',
+        matcher: 'Shell',
+        command:
+          'node -e "let s=\\"\\";process.stdin.on(\\"data\\",d=>s+=d);process.stdin.on(\\"end\\",()=>{const o=JSON.parse(s);process.stdout.write(o.tool_name+\\" \\"+o.tool_call_id);})"',
+        timeout: 5,
+      },
+    ]);
+
+    const results = await engine.trigger('PreToolUse', {
+      matcherValue: 'Shell',
+      inputData: { toolName: 'Shell', toolCallId: 'call_1' },
+    });
+
+    expect(results[0]?.stdout?.trim()).toBe('Shell call_1');
+  });
+
+  it('adds sessionId, cwd, and hookEventName from engine context', async () => {
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine(
+      [
+        {
+          event: 'SessionStart',
+          command:
+            'node -e "let s=\\"\\";process.stdin.on(\\"data\\",d=>s+=d);process.stdin.on(\\"end\\",()=>{const o=JSON.parse(s);process.stdout.write(o.hook_event_name+\\" \\"+o.session_id+\\" \\"+o.cwd);})"',
+          timeout: 5,
+        },
+      ],
+      {
+        sessionId: 'ses_123',
+        cwd: '/tmp',
+      },
+    );
+
+    const results = await engine.trigger('SessionStart');
+
+    expect(results[0]?.stdout?.trim()).toBe('SessionStart ses_123 /tmp');
+  });
+
+  it('treats an empty matcher string as a catch-all for any matcher value', async () => {
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine([
+      { event: 'Stop', matcher: '', command: 'echo done', timeout: 5 },
+    ]);
+    const results = await engine.trigger('Stop', {
+      matcherValue: 'anything',
+      inputData: {},
+    });
+    expect(results).toHaveLength(1);
+  });
+
+  it('matches ContentPart matcher values against their text content', async () => {
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine([
+      { event: 'UserPromptSubmit', matcher: 'hello world', command: 'exit 0', timeout: 5 },
+    ]);
+    const results = await engine.trigger('UserPromptSubmit', {
+      matcherValue: [
+        { type: 'text', text: 'hello' },
+        { type: 'image_url', imageUrl: { url: 'file:///tmp/a.png' } },
+        { type: 'text', text: 'world' },
+      ],
+      inputData: {},
+    });
+    expect(results).toHaveLength(1);
+  });
+
+  it('returns no results for events that have no registered hooks', async () => {
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine([
+      { event: 'PreToolUse', matcher: 'Shell', command: 'exit 0', timeout: 5 },
+    ]);
+    const results = await engine.trigger('UserPromptSubmit', {
+      matcherValue: '',
+      inputData: {},
+    });
+    expect(results).toHaveLength(0);
+  });
+
+  it('dedupes hooks with identical command strings so they only fire once', async () => {
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine([
+      { event: 'Stop', command: 'echo once', timeout: 5 },
+      { event: 'Stop', command: 'echo once', timeout: 5 },
+    ]);
+    const results = await engine.trigger('Stop', { inputData: {} });
+    expect(results).toHaveLength(1);
+  });
+
+  it('silently skips hooks whose matcher is not a valid regex', async () => {
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine([
+      { event: 'PreToolUse', matcher: '[invalid', command: 'exit 0', timeout: 5 },
+    ]);
+    const results = await engine.trigger('PreToolUse', {
+      matcherValue: 'Shell',
+      inputData: {},
+    });
+    expect(results).toHaveLength(0);
+  });
+
+  it('fails open when trigger input preparation throws', async () => {
+    const { HookEngine } = await importEngine();
+    const inputData = {};
+    Object.defineProperty(inputData, 'broken', {
+      enumerable: true,
+      get() {
+        throw new Error('broken input');
+      },
+    });
+    const engine = new HookEngine([{ event: 'PreToolUse', command: 'echo should-not-run' }]);
+
+    await expect(
+      engine.trigger('PreToolUse', {
+        matcherValue: 'Bash',
+        inputData,
+      }),
+    ).resolves.toEqual([]);
+    await expect(
+      engine.triggerBlock('PreToolUse', {
+        matcherValue: 'Bash',
+        inputData,
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it('fails open when fireAndForgetTrigger sees a synchronous trigger error', async () => {
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine([]);
+    vi.spyOn(engine, 'trigger').mockImplementation(() => {
+        throw new Error('trigger failed');
+    });
+
+    await expect(engine.fireAndForgetTrigger('Notification')).resolves.toEqual([]);
+  });
+
+  it('preserves a PreToolUse block result even when telemetry throws (no fail-open)', async () => {
+    // Safety-critical: a telemetry failure MUST NOT silently bypass a block.
+    const telemetry = await import('../../src/utils/telemetry' as string).catch(() => null);
+    const { HookEngine } = await importEngine();
+    const engine = new HookEngine([
+      { event: 'PreToolUse', matcher: 'ReadFile', command: 'exit 2', timeout: 5 },
+    ]);
+
+    const spy =
+      telemetry && typeof (telemetry as { track?: unknown }).track === 'function'
+        ? vi
+            .spyOn(telemetry as { track: (...args: unknown[]) => unknown }, 'track')
+            .mockImplementation(() => {
+              throw new Error('telemetry broken');
+            })
+        : null;
+
+    try {
+      const results = await engine.trigger('PreToolUse', {
+        matcherValue: 'ReadFile',
+        inputData: {},
+      });
+      expect(results).toHaveLength(1);
+      expect(results[0]?.action).toBe('block');
+    } finally {
+      spy?.mockRestore();
+    }
+  });
+});
diff --git a/packages/agent-core/test/hooks/integration.test.ts b/packages/agent-core/test/hooks/integration.test.ts
new file mode 100644
index 000000000..365dd879e
--- /dev/null
+++ b/packages/agent-core/test/hooks/integration.test.ts
@@ -0,0 +1,339 @@
+import { mkdtempSync, writeFileSync, chmodSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type { ContentPart } from '@moonshot-ai/kosong';
+import { describe, expect, it } from 'vitest';
+
+// Dynamic-import contract: locks the Agent <-> HookEngine integration shape
+// (engine ctor, trigger surface, summary, wire callbacks, event helpers,
+// config round-trip) before the implementation lands.
+const ENGINE_MODULE = '../../src/agent/hooks/engine' as string;
+const CONFIG_MODULE = '../../src/config' as string;
+
+type HookDef = {
+  event: string;
+  matcher?: string;
+  command: string;
+  timeout?: number;
+};
+
+interface HookResult {
+  action: 'allow' | 'block';
+  reason?: string;
+  stdout?: string;
+  stderr?: string;
+}
+
+type HookMatcherValue = string | readonly ContentPart[];
+
+interface HookEngineInstance {
+  trigger: (
+    event: string,
+    args?: { matcherValue?: HookMatcherValue; inputData?: Record<string, unknown> },
+  ) => Promise<HookResult[]>;
+  summary: Record<string, number>;
+}
+
+interface HookEngineCtor {
+  new (
+    hooks: HookDef[],
+    options?: {
+      cwd?: string;
+      onTriggered?: (event: string, target: string, count: number) => void;
+      onResolved?: (
+        event: string,
+        target: string,
+        action: string,
+        reason: string | undefined,
+        durationMs: number,
+      ) => void;
+    },
+  ): HookEngineInstance;
+}
+
+async function importEngine(): Promise<HookEngineCtor> {
+  const mod = (await import(ENGINE_MODULE)) as { HookEngine: HookEngineCtor };
+  return mod.HookEngine;
+}
+
+describe('HookEngine integration', () => {
+  it('blocks a dangerous Shell command and allows a safe one via a PreToolUse script hook', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'kimi-hooks-int-'));
+    const script = join(dir, 'block-rm.sh');
+    // Use node for the body to keep the test runtime-agnostic.
+    writeFileSync(
+      script,
+      [
+        '#!/bin/bash',
+        'CMD=$(node -e "let s=\\"\\";process.stdin.on(\\"data\\",d=>s+=d);process.stdin.on(\\"end\\",()=>{try{const o=JSON.parse(s);process.stdout.write((o.tool_input&&o.tool_input.command)||\\"\\");}catch(e){}})")',
+        'if echo "$CMD" | grep -q "rm -rf"; then echo "Blocked: rm -rf" >&2; exit 2; fi',
+        'exit 0',
+        '',
+      ].join('\n'),
+      'utf-8',
+    );
+    chmodSync(script, 0o755);
+
+    const HookEngine = await importEngine();
+    const engine = new HookEngine(
+      [{ event: 'PreToolUse', matcher: 'Shell', command: script, timeout: 5 }],
+      { cwd: dir },
+    );
+
+    const safe = await engine.trigger('PreToolUse', {
+      matcherValue: 'Shell',
+      inputData: { tool_name: 'Shell', tool_input: { command: 'ls -la' } },
+    });
+    expect(safe.every((r) => r.action === 'allow')).toBe(true);
+
+    const dangerous = await engine.trigger('PreToolUse', {
+      matcherValue: 'Shell',
+      inputData: { tool_name: 'Shell', tool_input: { command: 'rm -rf /' } },
+    });
+    expect(dangerous.some((r) => r.action === 'block')).toBe(true);
+    expect(dangerous[0]?.reason).toContain('rm -rf');
+  });
+
+  it('honors a Stop hook returning permissionDecision=deny by producing a block result with reason', async () => {
+    const HookEngine = await importEngine();
+    const engine = new HookEngine([
+      {
+        event: 'Stop',
+        command:
+          'echo \'{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"tests not written"}}\'',
+        timeout: 5,
+      },
+    ]);
+    const results = await engine.trigger('Stop', { inputData: { stop_hook_active: false } });
+    expect(results).toHaveLength(1);
+    expect(results[0]?.action).toBe('block');
+    expect(results[0]?.reason).toContain('tests not written');
+  });
+
+  it('fires a Notification hook only when its matcher equals the notification matcher value', async () => {
+    const HookEngine = await importEngine();
+    const engine = new HookEngine([
+      { event: 'Notification', matcher: 'task_completed', command: 'echo notified', timeout: 5 },
+      { event: 'Notification', matcher: 'other_type', command: 'echo other', timeout: 5 },
+    ]);
+    const results = await engine.trigger('Notification', {
+      matcherValue: 'task_completed',
+      inputData: { notification_type: 'task_completed', title: 'Done' },
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0]?.stdout?.trim()).toBe('notified');
+  });
+
+  it('runs multiple hooks for the same event in parallel and collects every result', async () => {
+    const HookEngine = await importEngine();
+    const engine = new HookEngine([
+      { event: 'PostToolUse', matcher: 'WriteFile', command: 'echo hook1', timeout: 5 },
+      { event: 'PostToolUse', matcher: 'WriteFile', command: 'echo hook2', timeout: 5 },
+    ]);
+    const results = await engine.trigger('PostToolUse', {
+      matcherValue: 'WriteFile',
+      inputData: { tool_name: 'WriteFile' },
+    });
+    expect(results).toHaveLength(2);
+    const outputs = new Set(results.map((r) => r.stdout?.trim()));
+    expect(outputs).toEqual(new Set(['hook1', 'hook2']));
+  });
+
+  it('round-trips hook definitions through the TOML config loader', async () => {
+    const config = (await import(CONFIG_MODULE)) as {
+      parseConfigString: (text: string, source?: string) => { hooks?: HookDef[] };
+    };
+    const toml = `
+[[hooks]]
+event = "PreToolUse"
+matcher = "Shell"
+command = "echo ok"
+
+[[hooks]]
+event = "Notification"
+matcher = "permission_prompt"
+command = "notify-send Kimi"
+timeout = 5
+`;
+    const parsed = config.parseConfigString(toml, 'hooks.toml');
+    expect(parsed.hooks).toHaveLength(2);
+    expect(parsed.hooks?.[0]?.event).toBe('PreToolUse');
+    expect(parsed.hooks?.[1]?.event).toBe('Notification');
+    expect(parsed.hooks?.[1]?.timeout).toBe(5);
+  });
+
+  it('exposes a summary map of event name to registered hook count', async () => {
+    const HookEngine = await importEngine();
+    const engine = new HookEngine([
+      { event: 'PreToolUse', matcher: 'Shell', command: 'echo 1' },
+      { event: 'PreToolUse', matcher: 'WriteFile', command: 'echo 2' },
+      { event: 'Stop', command: 'echo 3' },
+    ]);
+    expect(engine.summary).toEqual({ PreToolUse: 2, Stop: 1 });
+  });
+
+  it('feeds the SessionStart source field through stdin and filters by the startup matcher', async () => {
+    const HookEngine = await importEngine();
+    const engine = new HookEngine([
+      {
+        event: 'SessionStart',
+        matcher: 'startup',
+        command:
+          'node -e "let s=\\"\\";process.stdin.on(\\"data\\",d=>s+=d);process.stdin.on(\\"end\\",()=>{const o=JSON.parse(s);process.stdout.write(o.source||\\"\\");})"',
+        timeout: 5,
+      },
+    ]);
+
+    const matched = await engine.trigger('SessionStart', {
+      matcherValue: 'startup',
+      inputData: { sessionId: 'test-123', cwd: '/tmp', source: 'startup' },
+    });
+    expect(matched).toHaveLength(1);
+    expect(matched[0]?.stdout?.trim()).toBe('startup');
+
+    const unmatched = await engine.trigger('SessionStart', {
+      matcherValue: 'resume',
+      inputData: { sessionId: 'test-123', cwd: '/tmp', source: 'resume' },
+    });
+    expect(unmatched).toHaveLength(0);
+  });
+
+  it('fires a PostToolUseFailure hook with the tool error in the payload', async () => {
+    const HookEngine = await importEngine();
+    const engine = new HookEngine([
+      {
+        event: 'PostToolUseFailure',
+        matcher: 'Shell',
+        command: 'echo failure_caught',
+        timeout: 5,
+      },
+    ]);
+    const results = await engine.trigger('PostToolUseFailure', {
+      matcherValue: 'Shell',
+      inputData: { tool_name: 'Shell', tool_input: {}, error: 'command not found' },
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0]?.action).toBe('allow');
+    expect(results[0]?.stdout).toContain('failure_caught');
+  });
+
+  it('blocks a UserPromptSubmit prompt when the hook exits 2 and returns the reason to the user', async () => {
+    const HookEngine = await importEngine();
+    const engine = new HookEngine([
+      {
+        event: 'UserPromptSubmit',
+        command: "echo 'no profanity' >&2; exit 2",
+        timeout: 5,
+      },
+    ]);
+    const results = await engine.trigger('UserPromptSubmit', {
+      inputData: { prompt: 'bad words here' },
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0]?.action).toBe('block');
+    expect(results[0]?.reason).toContain('no profanity');
+  });
+
+  it('fires a StopFailure hook on chat provider errors with the error_type field present', async () => {
+    const HookEngine = await importEngine();
+    const engine = new HookEngine([
+      { event: 'StopFailure', command: 'echo error_logged', timeout: 5 },
+    ]);
+    const results = await engine.trigger('StopFailure', {
+      inputData: { error_type: 'ChatProviderError', error_message: 'rate limited' },
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0]?.stdout).toContain('error_logged');
+  });
+
+  it('fires a SessionEnd hook only for the matching reason matcher', async () => {
+    const HookEngine = await importEngine();
+    const engine = new HookEngine([
+      { event: 'SessionEnd', matcher: 'exit', command: 'echo goodbye', timeout: 5 },
+    ]);
+
+    const matched = await engine.trigger('SessionEnd', {
+      matcherValue: 'exit',
+      inputData: { session_id: 's1', reason: 'exit' },
+    });
+    expect(matched).toHaveLength(1);
+
+    const unmatched = await engine.trigger('SessionEnd', {
+      matcherValue: 'clear',
+      inputData: { session_id: 's1', reason: 'clear' },
+    });
+    expect(unmatched).toHaveLength(0);
+  });
+
+  it('fires a SubagentStart hook with the agent_name payload field', async () => {
+    const HookEngine = await importEngine();
+    const engine = new HookEngine([
+      {
+        event: 'SubagentStart',
+        matcher: 'coder',
+        command: 'echo agent_starting',
+        timeout: 5,
+      },
+    ]);
+    const results = await engine.trigger('SubagentStart', {
+      matcherValue: 'coder',
+      inputData: { agent_name: 'coder', prompt: 'Fix the bug' },
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0]?.stdout).toContain('agent_starting');
+  });
+
+  it('fires a SubagentStop hook on subagent completion', async () => {
+    const HookEngine = await importEngine();
+    const engine = new HookEngine([
+      { event: 'SubagentStop', matcher: 'coder', command: 'echo agent_done', timeout: 5 },
+    ]);
+    const results = await engine.trigger('SubagentStop', {
+      matcherValue: 'coder',
+      inputData: { agent_name: 'coder', response: 'Bug fixed' },
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0]?.stdout).toContain('agent_done');
+  });
+
+  it('fires PreCompact and PostCompact hooks around compaction with trigger and token payloads', async () => {
+    const HookEngine = await importEngine();
+    const engine = new HookEngine([
+      { event: 'PreCompact', matcher: 'auto', command: 'echo pre_compact', timeout: 5 },
+      { event: 'PostCompact', matcher: 'auto', command: 'echo post_compact', timeout: 5 },
+    ]);
+
+    const pre = await engine.trigger('PreCompact', {
+      matcherValue: 'auto',
+      inputData: { trigger: 'auto', token_count: 150000 },
+    });
+    expect(pre).toHaveLength(1);
+    expect(pre[0]?.stdout).toContain('pre_compact');
+
+    const post = await engine.trigger('PostCompact', {
+      matcherValue: 'auto',
+      inputData: { trigger: 'auto', estimated_token_count: 50000 },
+    });
+    expect(post).toHaveLength(1);
+    expect(post[0]?.stdout).toContain('post_compact');
+  });
+
+  it('invokes onTriggered with (event,target,count) and onResolved with (event,target,action)', async () => {
+    const HookEngine = await importEngine();
+    const triggered: Array<[string, string, number]> = [];
+    const resolved: Array<[string, string, string]> = [];
+    const engine = new HookEngine(
+      [{ event: 'PreToolUse', matcher: 'Shell', command: 'exit 0', timeout: 5 }],
+      {
+        onTriggered: (e, t, c) => triggered.push([e, t, c]),
+        onResolved: (e, t, a) => resolved.push([e, t, a]),
+      },
+    );
+
+    await engine.trigger('PreToolUse', { matcherValue: 'Shell', inputData: {} });
+
+    expect(triggered).toEqual([['PreToolUse', 'Shell', 1]]);
+    expect(resolved).toEqual([['PreToolUse', 'Shell', 'allow']]);
+  });
+});
diff --git a/packages/agent-core/test/hooks/runner.test.ts b/packages/agent-core/test/hooks/runner.test.ts
new file mode 100644
index 000000000..1e447839e
--- /dev/null
+++ b/packages/agent-core/test/hooks/runner.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+
+const RUNNER_MODULE = '../../src/agent/hooks/runner' as string;
+
+interface HookResult {
+  action: 'allow' | 'block';
+  message?: string;
+  reason?: string;
+  stdout?: string;
+  stderr?: string;
+  timedOut?: boolean;
+  structuredOutput?: boolean;
+}
+
+type RunHook = (
+  command: string,
+  input: Record<string, unknown>,
+  options: { timeout: number; cwd?: string },
+) => Promise<HookResult>;
+
+async function importRunHook(): Promise<RunHook> {
+  const mod = (await import(RUNNER_MODULE)) as { runHook: RunHook };
+  return mod.runHook;
+}
+
+describe('runHook process runner', () => {
+  it('returns allow when the hook exits 0 and captures stdout', async () => {
+    const runHook = await importRunHook();
+    const result = await runHook('echo ok', { tool_name: 'Shell' }, { timeout: 5 });
+    expect(result.action).toBe('allow');
+    expect(result.stdout?.trim()).toBe('ok');
+  });
+
+  it('parses stdout JSON message into a hook result message', async () => {
+    const runHook = await importRunHook();
+    const result = await runHook('echo \'{"message":"hook says hi"}\'', {}, { timeout: 5 });
+    expect(result.action).toBe('allow');
+    expect(result.message).toBe('hook says hi');
+    expect(result.structuredOutput).toBe(true);
+  });
+
+  it('marks structured stdout JSON without message as empty hook output', async () => {
+    const runHook = await importRunHook();
+
+    const emptyObject = await runHook("echo '{}'", {}, { timeout: 5 });
+    expect(emptyObject.action).toBe('allow');
+    expect(emptyObject.message).toBeUndefined();
+    expect(emptyObject.structuredOutput).toBe(true);
+
+    const emptyHookSpecificOutput = await runHook(
+      'echo \'{"hookSpecificOutput":{}}\'',
+      {},
+      { timeout: 5 },
+    );
+    expect(emptyHookSpecificOutput.action).toBe('allow');
+    expect(emptyHookSpecificOutput.message).toBeUndefined();
+    expect(emptyHookSpecificOutput.structuredOutput).toBe(true);
+  });
+
+  it('returns block when the hook exits 2 and captures stderr as the reason', async () => {
+    const runHook = await importRunHook();
+    const result = await runHook(
+      "echo 'blocked' >&2; exit 2",
+      { tool_name: 'Shell' },
+      { timeout: 5 },
+    );
+    expect(result.action).toBe('block');
+    expect(result.reason).toContain('blocked');
+  });
+
+  it('returns allow on non-zero, non-2 exit codes (e.g. exit 1)', async () => {
+    const runHook = await importRunHook();
+    const result = await runHook('exit 1', { tool_name: 'Shell' }, { timeout: 5 });
+    expect(result.action).toBe('allow');
+  });
+
+  it('returns allow with timedOut=true when the command exceeds the timeout', async () => {
+    const runHook = await importRunHook();
+    const result = await runHook('sleep 10', { tool_name: 'Shell' }, { timeout: 1 });
+    expect(result.action).toBe('allow');
+    expect(result.timedOut).toBe(true);
+  });
+
+  it('parses stdout JSON permissionDecision=deny into a block result with the supplied reason', async () => {
+    const runHook = await importRunHook();
+    const cmd =
+      'echo \'{"hookSpecificOutput": {"permissionDecision": "deny", "permissionDecisionReason": "use rg"}}\'';
+    const result = await runHook(cmd, { tool_name: 'Bash' }, { timeout: 5 });
+    expect(result.action).toBe('block');
+    expect(result.reason).toBe('use rg');
+  });
+
+  it('writes the input payload to the hook process stdin as JSON', async () => {
+    const runHook = await importRunHook();
+    const cmd =
+      'node -e "let s=\\"\\";process.stdin.on(\\"data\\",d=>s+=d);process.stdin.on(\\"end\\",()=>{const o=JSON.parse(s);process.stdout.write(o.tool_name);})"';
+    const result = await runHook(cmd, { tool_name: 'WriteFile' }, { timeout: 5 });
+    expect(result.stdout?.trim()).toBe('WriteFile');
+  });
+});
diff --git a/packages/agent-core/test/logging/formatter.test.ts b/packages/agent-core/test/logging/formatter.test.ts
new file mode 100644
index 000000000..401b7567e
--- /dev/null
+++ b/packages/agent-core/test/logging/formatter.test.ts
@@ -0,0 +1,231 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  CTX_VALUE_MAX_CHARS,
+  ENTRY_MAX_BYTES,
+  MSG_MAX_CHARS,
+  STACK_MAX_BYTES,
+  extractError,
+  formatEntry,
+  redactCtx,
+} from '#/logging/formatter';
+import type { LogEntry } from '#/logging/types';
+
+const FIXED_TIME = Date.UTC(2026, 4, 19, 10, 12, 30, 123);
+
+function baseEntry(overrides: Partial<LogEntry> = {}): LogEntry {
+  return {
+    t: FIXED_TIME,
+    level: 'info',
+    msg: 'diagnostic event',
+    ...overrides,
+  };
+}
+
+describe('formatter — logfmt rendering', () => {
+  it('renders timestamp, level, msg without ctx', () => {
+    const { text } = formatEntry(baseEntry());
+    expect(text).toBe('2026-05-19T10:12:30.123Z INFO  diagnostic event');
+  });
+
+  it('renders ctx as k=v pairs', () => {
+    const { text } = formatEntry(
+      baseEntry({ ctx: { sessionId: 'ses_abc', workDir: '/repo' } }),
+    );
+    expect(text).toContain('sessionId=ses_abc');
+    expect(text).toContain('workDir=/repo');
+  });
+
+  it('omits selected ctx keys', () => {
+    const { text } = formatEntry(
+      baseEntry({ ctx: { sessionId: 'ses_abc', workDir: '/repo' } }),
+      { omitContextKeys: ['sessionId'] },
+    );
+    expect(text).not.toContain('sessionId=ses_abc');
+    expect(text).toContain('workDir=/repo');
+  });
+
+  it('quotes ctx values that contain spaces or special chars', () => {
+    const { text } = formatEntry(baseEntry({ ctx: { path: '/Users/foo bar/x' } }));
+    expect(text).toContain('path="/Users/foo bar/x"');
+  });
+
+  it('renders all level labels at fixed width', () => {
+    for (const level of ['error', 'warn', 'info', 'debug'] as const) {
+      const { text } = formatEntry(baseEntry({ level }));
+      const label = level === 'error' ? 'ERROR' : level === 'warn' ? 'WARN ' : level === 'info' ? 'INFO ' : 'DEBUG';
+      expect(text).toContain(` ${label} `);
+    }
+  });
+
+  it('does not include ANSI when ansi=false', () => {
+    const { text } = formatEntry(baseEntry({ level: 'error' }), { ansi: false });
+    expect(text).not.toMatch(/\[/);
+  });
+
+  it('includes ANSI when ansi=true', () => {
+    const { text } = formatEntry(baseEntry({ level: 'error' }), { ansi: true });
+    expect(text).toMatch(/\[31m/);
+    expect(text).toMatch(/\[0m/);
+  });
+});
+
+describe('formatter — error extraction', () => {
+  it('attaches stack as indented multi-line block', () => {
+    const err = new Error('boom');
+    err.stack = 'Error: boom\n    at fn (file.ts:1:1)';
+    const ext = extractError(err);
+    const { text } = formatEntry(baseEntry({ level: 'error', msg: 'failure', error: { message: ext.message, stack: ext.stack ?? '' } }));
+    expect(text).toMatch(/\n  Error: boom\n {4}at fn/);
+  });
+
+  it('falls back to message-only line when no stack', () => {
+    const { text } = formatEntry(baseEntry({ level: 'error', error: { message: 'no stack' } }));
+    expect(text).toMatch(/\n  Error: no stack$/);
+  });
+
+  it('redacts secrets in error stack and message lines', () => {
+    const { text: stackText } = formatEntry(
+      baseEntry({
+        level: 'error',
+        error: {
+          message: 'failed',
+          stack:
+            'Error: request failed token=abc123\nAuthorization: Bearer secret-token\ncookie: sid=secret-cookie',
+        },
+      }),
+    );
+    expect(stackText).toContain('token=[REDACTED]');
+    expect(stackText).toContain('Authorization: Bearer [REDACTED]');
+    expect(stackText).toContain('cookie: [REDACTED]');
+    expect(stackText).not.toContain('abc123');
+    expect(stackText).not.toContain('secret-token');
+    expect(stackText).not.toContain('secret-cookie');
+
+    const { text: messageText } = formatEntry(
+      baseEntry({ level: 'error', error: { message: 'failed access_token=abc123' } }),
+    );
+    expect(messageText).toContain('access_token=[REDACTED]');
+    expect(messageText).not.toContain('abc123');
+  });
+
+  it('clips stack to STACK_MAX_BYTES with truncation marker', () => {
+    const longStack = 'Error: x\n' + '    at frame()\n'.repeat(1000);
+    const { text } = formatEntry(baseEntry({ error: { message: 'x', stack: longStack } }));
+    expect(text).toContain('…truncated');
+    expect(Buffer.byteLength(text, 'utf-8')).toBeLessThan(STACK_MAX_BYTES + 4096);
+  });
+});
+
+describe('formatter — limits', () => {
+  it('truncates msg over MSG_MAX_CHARS with ellipsis', () => {
+    const longMsg = 'x'.repeat(MSG_MAX_CHARS + 50);
+    const { text } = formatEntry(baseEntry({ msg: longMsg }));
+    expect(text).toContain('…');
+  });
+
+  it('truncates a single ctx value over CTX_VALUE_MAX_CHARS', () => {
+    const big = 'y'.repeat(CTX_VALUE_MAX_CHARS + 50);
+    const { text } = formatEntry(baseEntry({ ctx: { huge: big } }));
+    expect(text).toMatch(/huge="?y{300,}…/);
+  });
+
+  it('byte-slices the rendered head when entry exceeds ENTRY_MAX_BYTES', () => {
+    const ctx: Record<string, unknown> = {};
+    for (let i = 0; i < 1000; i++) ctx[`k${i}`] = 'v'.repeat(50);
+    const { text } = formatEntry(baseEntry({ ctx, msg: 'x'.repeat(MSG_MAX_CHARS) }));
+    const head = text.split('\n')[0] ?? '';
+    expect(Buffer.byteLength(head, 'utf-8')).toBeLessThanOrEqual(ENTRY_MAX_BYTES);
+    expect(text).toContain('…truncated');
+  });
+});
+
+describe('formatter — auto-redact', () => {
+  it('redacts top-level sensitive keys', () => {
+    const out = redactCtx({
+      token: 'abc',
+      apiKey: 'def',
+      cookie: 'ghi',
+      password: 'jkl',
+      user: 'x',
+    });
+    expect(out['token']).toBe('[REDACTED]');
+    expect(out['apiKey']).toBe('[REDACTED]');
+    expect(out['cookie']).toBe('[REDACTED]');
+    expect(out['password']).toBe('[REDACTED]');
+    expect(out['user']).toBe('x');
+  });
+
+  it('redacts case- and separator-normalized keys', () => {
+    const out = redactCtx({
+      API_KEY: '1',
+      access_token: '2',
+      'Refresh-Token': '3',
+      Authorization: '4',
+      client_secret: '5',
+      api_secret: '6',
+    });
+    expect(out['API_KEY']).toBe('[REDACTED]');
+    expect(out['access_token']).toBe('[REDACTED]');
+    expect(out['Refresh-Token']).toBe('[REDACTED]');
+    expect(out['Authorization']).toBe('[REDACTED]');
+    expect(out['client_secret']).toBe('[REDACTED]');
+    expect(out['api_secret']).toBe('[REDACTED]');
+  });
+
+  it('redacts common secret assignments inside raw string values', () => {
+    const { text } = formatEntry(
+      baseEntry({
+        ctx: {
+          stderrTail:
+            'Authorization: Bearer abc123\napi_key=def456\ncookie: session=ghi789',
+        },
+      }),
+    );
+    expect(text).toContain('Authorization: Bearer [REDACTED]');
+    expect(text).toContain('api_key=[REDACTED]');
+    expect(text).toContain('cookie: [REDACTED]');
+    expect(text).not.toContain('abc123');
+    expect(text).not.toContain('def456');
+    expect(text).not.toContain('ghi789');
+  });
+
+  it('recurses into nested objects', () => {
+    const out = redactCtx({ headers: { Authorization: 'Bearer xxx', 'X-Trace': '1' } });
+    const headers = out['headers'] as Record<string, unknown>;
+    expect(headers['Authorization']).toBe('[REDACTED]');
+    expect(headers['X-Trace']).toBe('1');
+  });
+
+  it('recurses into arrays of objects', () => {
+    const out = redactCtx({ tokens: [{ token: 'a' }, { token: 'b' }] });
+    const tokens = out['tokens'] as Array<Record<string, unknown>>;
+    expect(tokens[0]?.['token']).toBe('[REDACTED]');
+    expect(tokens[1]?.['token']).toBe('[REDACTED]');
+  });
+
+  it('collapses cycles to [REDACTED:cycle]', () => {
+    const a: Record<string, unknown> = { name: 'a' };
+    a['self'] = a;
+    const out = redactCtx({ a });
+    const wrap = out['a'] as Record<string, unknown>;
+    expect(wrap['self']).toBe('[REDACTED:cycle]');
+  });
+
+  it('collapses deep nesting to [REDACTED:depth]', () => {
+    let leaf: Record<string, unknown> = { n: 'leaf' };
+    for (let i = 0; i < 20; i++) leaf = { down: leaf };
+    const out = redactCtx({ chain: leaf });
+    const json = JSON.stringify(out);
+    expect(json).toContain('[REDACTED:depth]');
+  });
+});
+
+describe('extractError', () => {
+  it('captures message and stack', () => {
+    const e = new Error('boom');
+    const result = extractError(e);
+    expect(result.message).toBe('boom');
+    expect(result.stack).toMatch(/Error: boom/);
+  });
+});
diff --git a/packages/agent-core/test/logging/logger.test.ts b/packages/agent-core/test/logging/logger.test.ts
new file mode 100644
index 000000000..4ef8a33d6
--- /dev/null
+++ b/packages/agent-core/test/logging/logger.test.ts
@@ -0,0 +1,459 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  __resetRootLoggerForTest,
+  getRootLogger,
+  log,
+  redact,
+  resolveGlobalLogPath,
+} from '#/logging/logger';
+
+let homeDir: string;
+
+beforeEach(async () => {
+  await __resetRootLoggerForTest();
+  homeDir = await mkdtemp(join(tmpdir(), 'logger-test-'));
+});
+
+afterEach(async () => {
+  await __resetRootLoggerForTest();
+  await rm(homeDir, { recursive: true, force: true });
+});
+
+function defaultConfig(level: 'info' | 'debug' | 'warn' | 'error' | 'off' = 'info') {
+  return {
+    level,
+    globalLogPath: resolveGlobalLogPath(homeDir),
+    globalMaxBytes: 1_000_000,
+    globalFiles: 3,
+    sessionMaxBytes: 500_000,
+    sessionFiles: 2,
+  } as const;
+}
+
+async function readGlobal(): Promise<string> {
+  return readGlobalAt(homeDir);
+}
+
+async function readGlobalAt(dir: string): Promise<string> {
+  try {
+    return await readFile(resolveGlobalLogPath(dir), 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+describe('log — pre-configure noop', () => {
+  it('silently swallows calls before configure', async () => {
+    expect(() => {
+      log.info('before configure');
+    }).not.toThrow();
+    expect(await readGlobal()).toBe('');
+  });
+
+  it('the same `log` import routes to sink after configure (late-binding)', async () => {
+    log.info('pre-config'); // dropped
+    await getRootLogger().configure(defaultConfig());
+    log.info('post-config');
+    await getRootLogger().flush();
+    const text = await readGlobal();
+    expect(text).not.toContain('pre-config');
+    expect(text).toContain('post-config');
+  });
+});
+
+describe('configure idempotency', () => {
+  it('second configure with deep-equal config is a no-op', async () => {
+    await getRootLogger().configure(defaultConfig());
+    log.info('one');
+    await getRootLogger().flush();
+    await getRootLogger().configure(defaultConfig());
+    log.info('two');
+    await getRootLogger().flush();
+    const text = await readGlobal();
+    expect(text).toContain('one');
+    expect(text).toContain('two');
+  });
+
+  it('does not throw on multiple harness-like configure cycles', async () => {
+    for (let i = 0; i < 3; i++) {
+      await getRootLogger().configure(defaultConfig());
+    }
+    expect(getRootLogger().isConfigured()).toBe(true);
+  });
+
+  it('reconfigures the global sink when config changes', async () => {
+    await getRootLogger().configure(defaultConfig('info'));
+    const nextHomeDir = await mkdtemp(join(tmpdir(), 'logger-next-home-'));
+    try {
+      await getRootLogger().configure({
+        ...defaultConfig('debug'),
+        globalLogPath: resolveGlobalLogPath(nextHomeDir),
+      });
+      log.debug('after-reconfigure');
+      await getRootLogger().flushGlobal();
+      expect(await readGlobal()).not.toContain('after-reconfigure');
+      expect(await readGlobalAt(nextHomeDir)).toContain('after-reconfigure');
+    } finally {
+      await rm(nextHomeDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('level filtering', () => {
+  it('drops entries below configured level', async () => {
+    await getRootLogger().configure(defaultConfig('warn'));
+    log.info('info-line');
+    log.warn('warn-line');
+    log.error('error-line');
+    await getRootLogger().flush();
+    const text = await readGlobal();
+    expect(text).not.toContain('info-line');
+    expect(text).toContain('warn-line');
+    expect(text).toContain('error-line');
+  });
+
+  it('off level disables all output', async () => {
+    await getRootLogger().configure(defaultConfig('off'));
+    log.error('should-not-write');
+    await getRootLogger().flush();
+    expect(await readGlobal()).toBe('');
+  });
+});
+
+describe('payload shapes', () => {
+  it('accepts Error directly (no manual wrap needed)', async () => {
+    await getRootLogger().configure(defaultConfig());
+    const err = new Error('boom');
+    log.error('provider failed', err);
+    await getRootLogger().flush();
+    const text = await readGlobal();
+    expect(text).toContain('provider failed');
+    expect(text).toMatch(/Error: boom/);
+  });
+
+  it('accepts plain object as ctx', async () => {
+    await getRootLogger().configure(defaultConfig());
+    log.info('hello', { sessionId: 'ses_x', model: 'kimi-k2' });
+    await getRootLogger().flush();
+    const text = await readGlobal();
+    expect(text).toContain('sessionId=ses_x');
+    expect(text).toContain('model=kimi-k2');
+  });
+
+  it('bunyan-style: ctx with `error: Error` field hoists stack out', async () => {
+    await getRootLogger().configure(defaultConfig());
+    const err = new Error('persist failed');
+    log.error('wire persist failed', { agentHomedir: '/tmp/a', error: err });
+    await getRootLogger().flush();
+    const text = await readGlobal();
+    expect(text).toContain('agentHomedir=/tmp/a');
+    expect(text).toMatch(/Error: persist failed/);
+  });
+
+  it('coerces primitive payload into a reason field', async () => {
+    await getRootLogger().configure(defaultConfig());
+    log.warn('weird path', 'oh no');
+    await getRootLogger().flush();
+    const text = await readGlobal();
+    expect(text).toContain('reason="oh no"');
+  });
+
+  it('accepts a `catch (e: unknown)` binding without wrapping', async () => {
+    await getRootLogger().configure(defaultConfig());
+    try {
+      throw new Error('caught');
+    } catch (error) {
+      log.error('caught it', error);
+    }
+    await getRootLogger().flush();
+    const text = await readGlobal();
+    expect(text).toMatch(/Error: caught/);
+  });
+
+  it('does not let throwing payload accessors escape into caller flow', async () => {
+    await getRootLogger().configure(defaultConfig());
+    const payload = new Proxy(
+      {},
+      {
+        get() {
+          throw new Error('getter boom');
+        },
+        ownKeys() {
+          return ['error'];
+        },
+        getOwnPropertyDescriptor() {
+          return { configurable: true, enumerable: true };
+        },
+      },
+    );
+
+    expect(() => {
+      log.warn('proxy payload', payload);
+    }).not.toThrow();
+    await getRootLogger().flush();
+    expect(await readGlobal()).not.toContain('proxy payload');
+  });
+});
+
+describe('createChild', () => {
+  it('binds ctx that travels with every entry', async () => {
+    await getRootLogger().configure(defaultConfig());
+    const sessionLog = log.createChild({ sessionId: 'ses_a', model: 'kimi-k2' });
+    sessionLog.info('first');
+    sessionLog.warn('second', { extra: 'x' });
+    await getRootLogger().flush();
+    const text = await readGlobal();
+    expect(text).toMatch(/first.*sessionId=ses_a.*model=kimi-k2/);
+    expect(text).toMatch(/second.*extra=x.*sessionId=ses_a/);
+  });
+
+  it('chains: parent ctx + child ctx + call ctx all merged', async () => {
+    await getRootLogger().configure(defaultConfig());
+    const sessionLog = log.createChild({ sessionId: 'ses_a' });
+    const agentLog = sessionLog.createChild({ agentId: 'main' });
+    agentLog.info('turn started', { turnId: 7 });
+    await getRootLogger().flush();
+    const text = await readGlobal();
+    expect(text).toContain('sessionId=ses_a');
+    expect(text).toContain('agentId=main');
+    expect(text).toContain('turnId=7');
+  });
+
+  it('bound ctx overrides call-site ctx (cannot accidentally overwrite ownership)', async () => {
+    await getRootLogger().configure(defaultConfig());
+    const sessionLog = log.createChild({ sessionId: 'ses_a' });
+    sessionLog.info('msg', { sessionId: 'ses_FAKE', extra: 'k' });
+    await getRootLogger().flush();
+    const text = await readGlobal();
+    expect(text).toContain('sessionId=ses_a');
+    expect(text).not.toContain('ses_FAKE');
+    expect(text).toContain('extra=k');
+  });
+});
+
+describe('session routing', () => {
+  it('writes sessionId-tagged entries to both global and session sink', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'logger-session-'));
+    try {
+      await getRootLogger().configure(defaultConfig());
+      const handle = getRootLogger().attachSession({ sessionId: 'ses_abc', sessionDir });
+      const sessionLog = log.createChild({ sessionId: 'ses_abc' });
+      sessionLog.info('hello');
+      await handle.flush();
+      await getRootLogger().flush();
+      const global = await readGlobal();
+      const session = await readFile(join(sessionDir, 'logs', 'kimi-code.log'), 'utf-8');
+      expect(global).toContain('hello');
+      expect(session).toContain('hello');
+      await handle.close();
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('prints sessionId once on llm config but omits stable main-agent fields from session llm request lines', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'logger-session-'));
+    try {
+      await getRootLogger().configure(defaultConfig());
+      const handle = getRootLogger().attachSession({ sessionId: 'ses_abc', sessionDir });
+      const sessionLog = handle.logger.createChild({ agentId: 'main' });
+      sessionLog.info('llm config', { model: 'kimi-k2' });
+      sessionLog.info('llm request', { turn: 0, step: 1 });
+      await handle.flush();
+      await getRootLogger().flush();
+
+      const global = await readGlobal();
+      expect(global).toMatch(/llm config.*sessionId=ses_abc/);
+      expect(global).toMatch(/llm request.*sessionId=ses_abc/);
+
+      const session = await readFile(join(sessionDir, 'logs', 'kimi-code.log'), 'utf-8');
+      expect(session).toMatch(/llm config.*sessionId=ses_abc/);
+      expect(session).toMatch(/llm request(?!.*sessionId=ses_abc)/);
+      expect(session).toMatch(/llm request(?!.*agentId=main)/);
+      await handle.close();
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('keeps subagent ids on session llm request lines', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'logger-session-'));
+    try {
+      await getRootLogger().configure(defaultConfig());
+      const handle = getRootLogger().attachSession({ sessionId: 'ses_abc', sessionDir });
+      const sessionLog = handle.logger.createChild({ agentId: 'agent-0' });
+      sessionLog.info('llm request', { turn: 0, step: 1 });
+      await handle.flush();
+      await getRootLogger().flush();
+
+      const session = await readFile(join(sessionDir, 'logs', 'kimi-code.log'), 'utf-8');
+      expect(session).toMatch(/llm request.*agentId=agent-0/);
+      expect(session).toMatch(/llm request(?!.*sessionId=ses_abc)/);
+      await handle.close();
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('writes entries without sessionId only to global (not broadcast)', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'logger-session-'));
+    try {
+      await getRootLogger().configure(defaultConfig());
+      const handle = getRootLogger().attachSession({ sessionId: 'ses_abc', sessionDir });
+      log.info('bootstrap event');
+      await getRootLogger().flush();
+      await handle.flush();
+      const global = await readGlobal();
+      expect(global).toContain('bootstrap event');
+      let sessionText = '';
+      try {
+        sessionText = await readFile(join(sessionDir, 'logs', 'kimi-code.log'), 'utf-8');
+      } catch {}
+      expect(sessionText).not.toContain('bootstrap event');
+      await handle.close();
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('keeps same-id sessions in different directories isolated', async () => {
+    const firstDir = await mkdtemp(join(tmpdir(), 'logger-session-a-'));
+    const secondDir = await mkdtemp(join(tmpdir(), 'logger-session-b-'));
+    try {
+      await getRootLogger().configure(defaultConfig());
+      const first = getRootLogger().attachSession({ sessionId: 'ses_same', sessionDir: firstDir });
+      const second = getRootLogger().attachSession({
+        sessionId: 'ses_same',
+        sessionDir: secondDir,
+      });
+
+      first.logger.info('first only');
+      second.logger.info('second only');
+      log.info('ambiguous session id', { sessionId: 'ses_same' });
+      await getRootLogger().flush();
+
+      const firstText = await readFile(join(firstDir, 'logs', 'kimi-code.log'), 'utf-8');
+      const secondText = await readFile(join(secondDir, 'logs', 'kimi-code.log'), 'utf-8');
+      expect(firstText).toContain('first only');
+      expect(firstText).not.toContain('second only');
+      expect(firstText).not.toContain('ambiguous session id');
+      expect(secondText).toContain('second only');
+      expect(secondText).not.toContain('first only');
+      expect(secondText).not.toContain('ambiguous session id');
+
+      const global = await readGlobal();
+      expect(global).toContain('first only');
+      expect(global).toContain('second only');
+      expect(global).toContain('ambiguous session id');
+
+      await first.close();
+      await second.close();
+    } finally {
+      await rm(firstDir, { recursive: true, force: true });
+      await rm(secondDir, { recursive: true, force: true });
+    }
+  });
+
+  it('keeps a reused same-directory session sink open until every handle closes', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'logger-session-shared-'));
+    try {
+      await getRootLogger().configure(defaultConfig());
+      const first = getRootLogger().attachSession({ sessionId: 'ses_shared', sessionDir });
+      const second = getRootLogger().attachSession({ sessionId: 'ses_shared', sessionDir });
+
+      await first.close();
+      await first.close();
+
+      second.logger.info('still routes after first close');
+      await second.flush();
+
+      const text = await readFile(join(sessionDir, 'logs', 'kimi-code.log'), 'utf-8');
+      expect(text).toContain('still routes after first close');
+      await second.close();
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('does not let a closing handle remove a replacement session sink', async () => {
+    const firstDir = await mkdtemp(join(tmpdir(), 'logger-session-old-'));
+    const secondDir = await mkdtemp(join(tmpdir(), 'logger-session-new-'));
+    try {
+      await getRootLogger().configure(defaultConfig());
+      const first = getRootLogger().attachSession({
+        sessionId: 'ses_replace',
+        sessionDir: firstDir,
+      });
+
+      const closing = first.close();
+      const second = getRootLogger().attachSession({
+        sessionId: 'ses_replace',
+        sessionDir: secondDir,
+      });
+      await closing;
+
+      second.logger.info('replacement still routes');
+      await second.flush();
+
+      const secondText = await readFile(join(secondDir, 'logs', 'kimi-code.log'), 'utf-8');
+      expect(secondText).toContain('replacement still routes');
+      await second.close();
+    } finally {
+      await rm(firstDir, { recursive: true, force: true });
+      await rm(secondDir, { recursive: true, force: true });
+    }
+  });
+
+  it('waits for a closing session sink when flushing by session id', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'logger-session-closing-'));
+    try {
+      await getRootLogger().configure(defaultConfig());
+      const handle = getRootLogger().attachSession({ sessionId: 'ses_closing', sessionDir });
+      handle.logger.info('close flush marker');
+
+      const closing = handle.close();
+      await expect(getRootLogger().flushSession('ses_closing')).resolves.toBe(true);
+      await closing;
+
+      const text = await readFile(join(sessionDir, 'logs', 'kimi-code.log'), 'utf-8');
+      expect(text).toContain('close flush marker');
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('redact helper', () => {
+  it('returns same shape with sensitive fields replaced', () => {
+    const out = redact({ user: 'x', token: 'abc', nested: { apiKey: '1' } });
+    expect(out.user).toBe('x');
+    expect(out.token).toBe('[REDACTED]');
+    expect(out.nested.apiKey).toBe('[REDACTED]');
+  });
+
+  it('passes primitives through unchanged', () => {
+    expect(redact(42)).toBe(42);
+    expect(redact('hi')).toBe('hi');
+    expect(redact(null)).toBe(null);
+  });
+
+  it('processes arrays', () => {
+    const out = redact([{ token: '1' }, { apiKey: '2' }]);
+    expect(out[0]?.token).toBe('[REDACTED]');
+    expect(out[1]?.apiKey).toBe('[REDACTED]');
+  });
+
+  it('handles cyclic arrays without recursing forever', () => {
+    const input: unknown[] = [];
+    input.push(input);
+
+    const out = redact(input);
+
+    expect(out[0]).toBe('[REDACTED:cycle]');
+  });
+});
diff --git a/packages/agent-core/test/logging/sinks.test.ts b/packages/agent-core/test/logging/sinks.test.ts
new file mode 100644
index 000000000..bb7a24b74
--- /dev/null
+++ b/packages/agent-core/test/logging/sinks.test.ts
@@ -0,0 +1,156 @@
+import { mkdtemp, readFile, readdir, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { PENDING_MAX, RotatingFileSink } from '#/logging/sinks';
+
+let workDir: string;
+
+beforeEach(async () => {
+  workDir = await mkdtemp(join(tmpdir(), 'logger-sinks-'));
+});
+
+afterEach(async () => {
+  await rm(workDir, { recursive: true, force: true });
+});
+
+async function listLogs(dir: string): Promise<string[]> {
+  return (await readdir(dir)).toSorted();
+}
+
+describe('RotatingFileSink', () => {
+  it('writes single line to active file', async () => {
+    const sink = new RotatingFileSink({
+      path: join(workDir, 'app.log'),
+      maxBytes: 1024,
+      files: 3,
+    });
+    sink.enqueue('hello\n');
+    await sink.flush();
+    const text = await readFile(join(workDir, 'app.log'), 'utf-8');
+    expect(text).toBe('hello\n');
+  });
+
+  it('rotates when active file exceeds maxBytes', async () => {
+    const path = join(workDir, 'app.log');
+    const sink = new RotatingFileSink({ path, maxBytes: 64, files: 3 });
+    for (let i = 0; i < 20; i++) {
+      sink.enqueue(`line${i} ${'x'.repeat(20)}\n`);
+      await sink.flush();
+    }
+    const files = await listLogs(workDir);
+    expect(files).toContain('app.log');
+    expect(files).toContain('app.log.1');
+  });
+
+  it('evicts oldest archive after files=N rolls', async () => {
+    const path = join(workDir, 'app.log');
+    const sink = new RotatingFileSink({ path, maxBytes: 32, files: 2 });
+    for (let i = 0; i < 50; i++) {
+      sink.enqueue(`${i.toString().padStart(3, '0')} ${'x'.repeat(30)}\n`);
+      await sink.flush();
+    }
+    // Final write to ensure active file exists post-rotation
+    sink.enqueue('final\n');
+    await sink.flush();
+    const files = await listLogs(workDir);
+    expect(files).toEqual(expect.arrayContaining(['app.log']));
+    // files = 2 → active + at most 1 archive; no app.log.2 or higher
+    expect(files.some((f) => /^app\.log\.[2-9]$/.test(f))).toBe(false);
+  });
+
+  it('rotates a large pending batch instead of writing it as one oversized file', async () => {
+    const path = join(workDir, 'app.log');
+    const maxBytes = 128;
+    const sink = new RotatingFileSink({ path, maxBytes, files: 3 });
+    for (let i = 0; i < 24; i++) {
+      sink.enqueue(`line${i.toString().padStart(2, '0')} ${'x'.repeat(24)}\n`);
+    }
+
+    await sink.flush();
+
+    const files = await listLogs(workDir);
+    expect(files).toContain('app.log.1');
+    for (const file of files) {
+      expect((await stat(join(workDir, file))).size).toBeLessThanOrEqual(maxBytes);
+    }
+  });
+
+  it('drops oldest when pending overflows', async () => {
+    const path = join(workDir, 'app.log');
+    const sink = new RotatingFileSink({ path, maxBytes: 1_000_000, files: 2 });
+    const over = PENDING_MAX + 500;
+    for (let i = 0; i < over; i++) {
+      sink.enqueue(`line${i}\n`);
+    }
+    await sink.flush();
+    const text = await readFile(path, 'utf-8');
+    expect(text).toMatch(/\.\.\. dropped \d+ entries \.\.\./);
+    // First lines (oldest) should be gone
+    expect(text).not.toContain('line0\n');
+    // Latest should be present
+    expect(text).toContain(`line${over - 1}\n`);
+  });
+
+  it('does not throw when fs write fails; emits stderr notice', async () => {
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    // Force failure by passing an invalid path char on POSIX
+    const badSink = new RotatingFileSink({
+      path: '\0/invalid/path',
+      maxBytes: 1024,
+      files: 2,
+    });
+    badSink.enqueue('x\n');
+    expect(await badSink.flush()).toBe(false);
+    expect(
+      stderrSpy.mock.calls.some((c) => String(c[0]).includes('[logger] write failed')),
+    ).toBe(true);
+    stderrSpy.mockRestore();
+  });
+
+  it('keeps restored pending bounded after repeated write failures', async () => {
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const badSink = new RotatingFileSink({
+      path: '\0/invalid/path',
+      maxBytes: 1024,
+      files: 2,
+    });
+    try {
+      for (let round = 0; round < 3; round++) {
+        for (let i = 0; i < PENDING_MAX + 25; i++) {
+          badSink.enqueue(`round${round}-line${i}\n`);
+        }
+        expect(await badSink.flush()).toBe(false);
+      }
+      const pending = (badSink as unknown as { pending: readonly string[] }).pending;
+      expect(pending.length).toBeLessThanOrEqual(PENDING_MAX);
+    } finally {
+      stderrSpy.mockRestore();
+    }
+  });
+
+  it('returns true when flush writes successfully', async () => {
+    const path = join(workDir, 'app.log');
+    const sink = new RotatingFileSink({ path, maxBytes: 1024, files: 2 });
+    sink.enqueue('ok\n');
+    expect(await sink.flush()).toBe(true);
+  });
+
+  it('serializes concurrent writes without interleaving lines', async () => {
+    const path = join(workDir, 'app.log');
+    const sink = new RotatingFileSink({ path, maxBytes: 10_000_000, files: 2 });
+    const N = 500;
+    for (let i = 0; i < N; i++) {
+      sink.enqueue(`line${i.toString().padStart(4, '0')}\n`);
+    }
+    await sink.flush();
+    const text = await readFile(path, 'utf-8');
+    const lines = text.split('\n').filter((l) => l.length > 0);
+    expect(lines.length).toBe(N);
+    for (const line of lines) {
+      expect(line).toMatch(/^line\d{4}$/);
+    }
+  });
+});
diff --git a/packages/agent-core/test/loop/abort.e2e.test.ts b/packages/agent-core/test/loop/abort.e2e.test.ts
new file mode 100644
index 000000000..4ec8a967e
--- /dev/null
+++ b/packages/agent-core/test/loop/abort.e2e.test.ts
@@ -0,0 +1,253 @@
+/**
+ * Abort behaviour at each safe point.
+ *
+ * The loop's contract is that an externally-aborted turn never throws to the
+ * caller and never loses already-recorded usage. The matrix here covers
+ * abort triggered at every observable boundary: before the loop, during
+ * the LLM call, during tool execution, between steps, and during a hook.
+ */
+
+import { inputTotal } from '@moonshot-ai/kosong';
+import { describe, expect, it } from 'vitest';
+
+import type { LLMChatResponse, LoopHooks } from '../../src/loop/index';
+import { makeEndTurnResponse, makeToolCall, makeToolUseResponse } from './fixtures/fake-llm';
+import { runTurn } from './fixtures/helpers';
+import { EchoTool, GatedTool, markReadAnyFileAccesses, SlowTool } from './fixtures/tools';
+
+function waitOneMacrotask(): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, 0);
+  });
+}
+
+describe('runTurn — abort handling', () => {
+  it('returns aborted without throwing when signal is already aborted on entry', async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    const { result, llm, sink, context } = await runTurn({
+      responses: [makeEndTurnResponse('never executed')],
+      signal: controller.signal,
+    });
+
+    expect(result.stopReason).toBe('aborted');
+    expect(result.steps).toBe(0);
+    // LLM was never called and no transcript envelope opened
+    expect(llm.callCount).toBe(0);
+    expect(context.stepBegins().length).toBe(0);
+    // turn.interrupted{aborted} is emitted
+    const interrupted = sink.byType('turn.interrupted');
+    expect(interrupted.length).toBe(1);
+    expect(interrupted[0]?.reason).toBe('aborted');
+    expect(interrupted[0]?.attemptedSteps).toBe(0);
+    expect(interrupted[0]?.activeStep).toBeUndefined();
+    // No step.begin / step.end ever fired
+    expect(sink.count('step.begin')).toBe(0);
+    expect(sink.count('step.end')).toBe(0);
+  });
+
+  it('returns aborted when the LLM call itself observes the signal', async () => {
+    const controller = new AbortController();
+    const { result, sink, llm } = await runTurn({
+      responses: [makeEndTurnResponse('not returned')],
+      signal: controller.signal,
+      llmAbortOnIndex: { index: 0, controller },
+    });
+
+    expect(result.stopReason).toBe('aborted');
+    expect(llm.callCount).toBe(1);
+    expect(sink.byType('turn.interrupted')[0]?.reason).toBe('aborted');
+  });
+
+  it('preserves usage already recorded by an earlier step when later steps abort', async () => {
+    const slow = new SlowTool();
+    const controller = new AbortController();
+
+    // Scenario: step 1 records usage for an end-of-step we never reach (the
+    // LLM returns first), step 2 hangs in the slow tool until we abort.
+    const responses: LLMChatResponse[] = [
+      makeToolUseResponse([makeToolCall('echo', { text: 'first' }, 'tc-1')], {
+        inputOther: 100,
+        output: 50,
+      }),
+      makeToolUseResponse([makeToolCall('slow', {}, 'tc-2')], {
+        inputOther: 7,
+        output: 11,
+      }),
+      // Never reached
+      makeEndTurnResponse('unreachable'),
+    ];
+
+    const echo = new EchoTool();
+    const turnPromise = runTurn({
+      tools: [echo, slow],
+      responses,
+      signal: controller.signal,
+    });
+
+    // Wait for the slow tool to start, then abort.
+    await slow.started.promise;
+    controller.abort();
+
+    const { result, sink } = await turnPromise;
+    expect(result.stopReason).toBe('aborted');
+    // Step 1 fully recorded its usage; step 2 also recorded its LLM
+    // usage immediately after the chat call, before the tool aborted.
+    expect(inputTotal(result.usage)).toBe(100 + 7);
+    expect(result.usage.output).toBe(50 + 11);
+    expect(sink.byType('turn.interrupted').map((e) => e.reason)).toContain('aborted');
+  });
+
+  it('aborts cleanly when triggered inside a beforeStep hook', async () => {
+    const controller = new AbortController();
+    const hooks: LoopHooks = {
+      beforeStep: async () => {
+        controller.abort();
+        const err = new Error('aborted from hook');
+        err.name = 'AbortError';
+        throw err;
+      },
+    };
+
+    const { result, sink, llm, context } = await runTurn({
+      hooks,
+      responses: [makeEndTurnResponse('never')],
+      signal: controller.signal,
+    });
+
+    expect(result.stopReason).toBe('aborted');
+    expect(llm.callCount).toBe(0);
+    expect(context.stepBegins().length).toBe(0);
+    expect(sink.byType('turn.interrupted')[0]?.reason).toBe('aborted');
+  });
+
+  it('aborts cleanly when triggered inside a prepareToolExecution hook', async () => {
+    const controller = new AbortController();
+    const echo = new EchoTool();
+    const hooks: LoopHooks = {
+      prepareToolExecution: async () => {
+        controller.abort();
+        const err = new Error('aborted from prepareToolExecution');
+        err.name = 'AbortError';
+        throw err;
+      },
+    };
+
+    const { result, sink } = await runTurn({
+      hooks,
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'hi' }, 'tc-1')]),
+        makeEndTurnResponse('never'),
+      ],
+      signal: controller.signal,
+    });
+
+    expect(result.stopReason).toBe('aborted');
+    // tool.execute must not have been invoked
+    expect(echo.calls.length).toBe(0);
+    expect(sink.byType('turn.interrupted')[0]?.reason).toBe('aborted');
+  });
+
+  it('does NOT crash when an aborted turn still has work to drain', async () => {
+    // A SlowTool waits forever; we abort while it's running. The loop must
+    // settle gracefully and emit a single turn.interrupted.
+    const slow = new SlowTool();
+    const controller = new AbortController();
+
+    const turnPromise = runTurn({
+      tools: [slow],
+      responses: [
+        makeToolUseResponse([makeToolCall('slow', {}, 'tc-1')]),
+        makeEndTurnResponse('unreachable'),
+      ],
+      signal: controller.signal,
+    });
+
+    await slow.started.promise;
+    controller.abort();
+    const { result, sink } = await turnPromise;
+
+    expect(result.stopReason).toBe('aborted');
+    // Exactly one turn.interrupted record
+    expect(sink.byType('turn.interrupted').length).toBe(1);
+  });
+
+  it('does not start a queued conflicting tool after abort', async () => {
+    const gated = new GatedTool('gated');
+    const echo = new EchoTool();
+    const controller = new AbortController();
+
+    const turnPromise = runTurn({
+      tools: [gated, echo],
+      responses: [
+        makeToolUseResponse([
+          makeToolCall('gated', {}, 'tc-gated'),
+          makeToolCall('echo', { text: 'late mutation' }, 'tc-echo'),
+        ]),
+        makeEndTurnResponse('unreachable'),
+      ],
+      signal: controller.signal,
+    });
+
+    await gated.started;
+    await waitOneMacrotask();
+    expect(echo.calls.length).toBe(0);
+
+    controller.abort();
+    gated.release();
+    const { result, sink } = await turnPromise;
+
+    expect(result.stopReason).toBe('aborted');
+    expect(echo.calls.length).toBe(0);
+    expect(sink.byType('tool.call').map((e) => e.toolCallId)).toEqual(['tc-gated', 'tc-echo']);
+    const results = sink.byType('tool.result');
+    expect(results.map((e) => e.toolCallId)).toEqual(['tc-gated', 'tc-echo']);
+    const echoResult = results.find((event) => event.toolCallId === 'tc-echo');
+    expect(echoResult?.result).toEqual({
+      output: 'Tool "echo" was aborted',
+      isError: true,
+    });
+  });
+
+  it('every tool.call still has a matching tool.result when aborted mid-batch', async () => {
+    // Transcript-balance contract: even when the turn is aborted while
+    // multiple tool tasks are running, every dispatched tool.call must be
+    // followed by a tool.result for the same toolCallId. Without this,
+    // the next turn's messages would carry orphan tool.calls and the
+    // provider API would reject the conversation.
+    const slow = markReadAnyFileAccesses(new SlowTool());
+    const controller = new AbortController();
+
+    const turnPromise = runTurn({
+      tools: [slow],
+      responses: [
+        makeToolUseResponse([
+          makeToolCall('slow', {}, 'tc-1'),
+          makeToolCall('slow', {}, 'tc-2'),
+          makeToolCall('slow', {}, 'tc-3'),
+        ]),
+        makeEndTurnResponse('unreachable'),
+      ],
+      signal: controller.signal,
+    });
+
+    await slow.started.promise;
+    controller.abort();
+    const { result, sink } = await turnPromise;
+
+    expect(result.stopReason).toBe('aborted');
+
+    const callIds = sink
+      .byType('tool.call')
+      .map((e) => e.toolCallId)
+      .toSorted();
+    const resultIds = sink
+      .byType('tool.result')
+      .map((e) => e.toolCallId)
+      .toSorted();
+    expect(callIds).toEqual(['tc-1', 'tc-2', 'tc-3']);
+    expect(resultIds).toEqual(callIds);
+  });
+});
diff --git a/packages/agent-core/test/loop/api-shape.e2e.test.ts b/packages/agent-core/test/loop/api-shape.e2e.test.ts
new file mode 100644
index 000000000..49b6c14a5
--- /dev/null
+++ b/packages/agent-core/test/loop/api-shape.e2e.test.ts
@@ -0,0 +1,589 @@
+/**
+ * Type-level lock on the loop's public surface.
+ *
+ * The point is to make refactors that *unintentionally* widen / narrow /
+ * remove a public type a compile error rather than a quiet binary
+ * regression. Real behavioural assertions live in the other e2e files;
+ * this file is the structural complement to them.
+ *
+ * Type checks live inside a never-called function body so they run during
+ * compile (`tsc --noEmit`) but cost nothing at runtime. A single trivial
+ * `it` keeps Vitest happy.
+ */
+
+import type { ContentPart, ModelCapability, TokenUsage } from '@moonshot-ai/kosong';
+import { describe, expect, it } from 'vitest';
+
+import { createLoopEventDispatcher, runTurn, ToolAccesses } from '../../src/loop/index';
+import type {
+  AfterStepHook,
+  BeforeStepResult,
+  BeforeStepHook,
+  ExecutableTool,
+  LLM,
+  LLMChatParams,
+  LLMChatResponse,
+  RunTurnInput,
+  ShouldContinueAfterStopHook,
+  ShouldContinueAfterStopResult,
+  LoopRecordedEvent,
+  LoopLiveOnlyEvent,
+  LoopEvent,
+  LoopHooks,
+  LoopInterruptReason,
+  LoopLiveEventEmitter,
+  LoopMessageBuilder,
+  LoopEventDispatcher,
+  LoopAfterStepContext,
+  LoopStepHookContext,
+  LoopTextDeltaEvent,
+  LoopThinkingDeltaEvent,
+  LoopToolCallDeltaEvent,
+  LoopContentPartEvent,
+  LoopStepBeginEvent,
+  LoopStepEndEvent,
+  LoopToolCallEvent,
+  LoopToolProgressEvent,
+  LoopToolResultEvent,
+  LoopTurnInterruptedEvent,
+  LoopStepStopReason,
+  LoopStoppedStepContext,
+  LoopTerminalStepStopReason,
+  LoopTurnStopReason,
+  StopReason,
+  ToolCallDelta,
+  ToolCall,
+  ExecutableToolContext,
+  ToolExecutionHookContext,
+  PrepareToolExecutionHook,
+  PrepareToolExecutionResult,
+  ExecutableToolResult,
+  FinalizeToolResultContext,
+  FinalizeToolResultHook,
+  TurnResult,
+} from '../../src/loop/index';
+
+// Compile-time fixtures (never executed).
+
+declare const _llm: LLM;
+declare const _buildMessages: LoopMessageBuilder;
+declare const _appendTranscriptRecord: (record: LoopRecordedEvent) => Promise<void>;
+declare const _emit: LoopLiveEventEmitter;
+declare const _dispatchEvent: LoopEventDispatcher;
+declare const _signal: AbortSignal;
+declare const _hooks: LoopHooks;
+
+function _typeOnlyChecks(): void {
+  // RunTurnInput names every external capability explicitly, using
+  // function-shaped dependencies when the capability has exactly one method.
+  const input: RunTurnInput = {
+    turnId: 't1',
+    signal: _signal,
+    llm: _llm,
+    buildMessages: _buildMessages,
+    dispatchEvent: _dispatchEvent,
+    tools: [],
+    hooks: _hooks,
+    maxSteps: 2,
+  };
+  void runTurn(input);
+
+  // Minimal input: tools / hooks / maxSteps are optional.
+  const minimalInput: RunTurnInput = {
+    turnId: 't1',
+    signal: _signal,
+    llm: _llm,
+    buildMessages: _buildMessages,
+    dispatchEvent: _dispatchEvent,
+  };
+  void minimalInput;
+
+  const createdEventDispatcher = createLoopEventDispatcher({
+    appendTranscriptRecord: _appendTranscriptRecord,
+    emitLiveEvent: _emit,
+  });
+  void createdEventDispatcher;
+
+  const chatParams: LLMChatParams = {
+    messages: [],
+    tools: [],
+    signal: _signal,
+    onTextDelta: (_delta: string) => {},
+    onThinkDelta: (_delta: string) => {},
+    onToolCallDelta: (_delta) => {},
+    onTextPart: async (_part) => {
+      const text: string = _part.text;
+      void text;
+    },
+    onThinkPart: async (_part) => {
+      const thinking: string = _part.think;
+      void thinking;
+    },
+  };
+  void chatParams;
+  const _badChatParamsDelta: LLMChatParams = {
+    messages: [],
+    tools: [],
+    signal: _signal,
+    // @ts-expect-error — text deltas use `onTextDelta`, not `onDelta`.
+    onDelta: (_delta: string) => {},
+  };
+  void _badChatParamsDelta;
+  const _badChatParamsAtomic: LLMChatParams = {
+    messages: [],
+    tools: [],
+    signal: _signal,
+    // @ts-expect-error — completed parts use `onTextPart` / `onThinkPart`.
+    onAtomicPart: async (_part: unknown) => {},
+  };
+  void _badChatParamsAtomic;
+  const _badChatParamsContentPart: LLMChatParams = {
+    messages: [],
+    tools: [],
+    signal: _signal,
+    // @ts-expect-error — text and thinking parts are split by type.
+    onContentPart: async (_part: unknown) => {},
+  };
+  void _badChatParamsContentPart;
+
+  const chatResponse: LLMChatResponse = {
+    toolCalls: [],
+    providerFinishReason: 'filtered',
+    rawFinishReason: 'content_filter',
+    usage: {} as TokenUsage,
+  };
+  void chatResponse;
+  const _badChatResponseStopReason: LLMChatResponse = {
+    toolCalls: [],
+    usage: {} as TokenUsage,
+    // @ts-expect-error - LLM responses expose provider diagnostics; the loop derives stopReason.
+    stopReason: 'end_turn',
+  };
+  void _badChatResponseStopReason;
+
+  // @ts-expect-error — old context/config shape is no longer accepted.
+  const _badOldInput: RunTurnInput = { ...input, context: {}, config: {} };
+  void _badOldInput;
+
+  // @ts-expect-error — old grouped turn shape is no longer accepted.
+  const _badGroupedTurn: RunTurnInput = { ...input, turn: { id: 't1', signal: _signal } };
+  void _badGroupedTurn;
+
+  // @ts-expect-error — old events array shape is no longer accepted.
+  const _badEvents: RunTurnInput = { ...input, events: [_emit] };
+  void _badEvents;
+
+  const _badAppendTranscript: RunTurnInput = {
+    ...input,
+    // @ts-expect-error — transcript append is now attached to LoopEventDispatcher.
+    appendTranscriptRecord: _appendTranscriptRecord,
+  };
+  void _badAppendTranscript;
+
+  // @ts-expect-error — old emit field is no longer accepted.
+  const _badEmit: RunTurnInput = { ...input, emit: _emit };
+  void _badEmit;
+
+  // @ts-expect-error — live emit is now attached to LoopEventDispatcher.
+  const _badEmitLiveEvent: RunTurnInput = { ...input, emitLiveEvent: _emit };
+  void _badEmitLiveEvent;
+
+  // @ts-expect-error — old limits wrapper is no longer accepted.
+  const _badLimits: RunTurnInput = { ...input, limits: { maxSteps: 2 } };
+  void _badLimits;
+
+  // Messages are built directly; system prompt belongs to LLM.
+  const buildMessages: LoopMessageBuilder = () => [];
+  void buildMessages;
+
+  // @ts-expect-error — old prompt object wrapper is no longer accepted.
+  const _badMessages: LoopMessageBuilder = { buildMessages };
+  void _badMessages;
+
+  // Transcript is one append-only recorded event function.
+  const appendTranscriptRecord = async (_record: LoopRecordedEvent): Promise<void> => {};
+  void appendTranscriptRecord;
+
+  const _badTranscript: (record: LoopRecordedEvent) => Promise<void> = {
+    // @ts-expect-error — transcript append is a function, not an object wrapper.
+    append: async () => {},
+  };
+  void _badTranscript;
+
+  const emit: LoopLiveEventEmitter = (_event: LoopEvent) => {};
+  void emit;
+
+  const stepBeginRecord: LoopStepBeginEvent = {
+    type: 'step.begin',
+    uuid: 's1',
+    turnId: 't1',
+    step: 1,
+  };
+  const stepEndRecord: LoopStepEndEvent = {
+    type: 'step.end',
+    uuid: 's1',
+    turnId: 't1',
+    step: 1,
+    finishReason: 'filtered',
+    providerFinishReason: 'filtered',
+    rawFinishReason: 'content_filter',
+  };
+  const contentPartRecord: LoopContentPartEvent = {
+    type: 'content.part',
+    uuid: 'c1',
+    turnId: 't1',
+    step: 1,
+    stepUuid: 's1',
+    part: { type: 'text', text: 'hi' },
+  };
+  const toolCallRecord: LoopToolCallEvent = {
+    type: 'tool.call',
+    uuid: 'tc1',
+    turnId: 't1',
+    step: 1,
+    stepUuid: 's1',
+    toolCallId: 'tc1',
+    name: 'echo',
+    args: {},
+  };
+  const toolResultRecord: LoopToolResultEvent = {
+    type: 'tool.result',
+    parentUuid: 'tc1',
+    toolCallId: 'tc1',
+    result: { output: 'ok' },
+  };
+  const _records: LoopRecordedEvent[] = [
+    stepBeginRecord,
+    stepEndRecord,
+    contentPartRecord,
+    toolCallRecord,
+    toolResultRecord,
+  ];
+  void _records;
+
+  // Hook contexts receive the LLM directly and no prompt/transcript object.
+  const stepHookContext: LoopStepHookContext = {
+    turnId: 't1',
+    stepNumber: 1,
+    signal: _signal,
+    llm: _llm,
+  };
+  void stepHookContext;
+
+  const _badStepHookContext: LoopStepHookContext = {
+    turnId: 't1',
+    stepNumber: 1,
+    signal: _signal,
+    llm: _llm,
+    // @ts-expect-error — hooks receive `llm`, not a separate modelName field.
+    modelName: 'model',
+  };
+  void _badStepHookContext;
+
+  const afterStepContext: LoopAfterStepContext = {
+    ...stepHookContext,
+    usage: {} as TokenUsage,
+    stopReason: 'tool_use',
+  };
+  void afterStepContext;
+
+  const stoppedStepContext: LoopStoppedStepContext = {
+    ...stepHookContext,
+    usage: {} as TokenUsage,
+    stopReason: 'filtered',
+  };
+  void stoppedStepContext;
+
+  const toolCallHookContext: ToolExecutionHookContext = {
+    ...stepHookContext,
+    toolCall: { type: 'function', id: 'tc1', function: { name: 'echo', arguments: '{}' } },
+    args: {},
+  };
+  void toolCallHookContext;
+
+  const _badToolExecutionHookContext: ToolExecutionHookContext = {
+    ...stepHookContext,
+    toolCall: { type: 'function', id: 'tc1', function: { name: 'echo', arguments: '{}' } },
+    // @ts-expect-error — tool hooks receive `args`, not the old `input` field.
+    input: {},
+  };
+  void _badToolExecutionHookContext;
+
+  const _badHookContext: ToolExecutionHookContext = {
+    ...toolCallHookContext,
+    // @ts-expect-error — hooks no longer receive the old big context reader.
+    context: buildMessages,
+  };
+  void _badHookContext;
+
+  // @ts-expect-error — old sink property is no longer accepted.
+  const _badInput: RunTurnInput = { ...input, sinks: _emit };
+  void _badInput;
+
+  // LoopHooks members are all optional.
+  const allHooks: LoopHooks = {
+    beforeStep: undefined,
+    afterStep: undefined,
+    prepareToolExecution: undefined,
+    finalizeToolResult: undefined,
+    shouldContinueAfterStop: undefined,
+  };
+  void allHooks;
+
+  // Step stop reasons include provider-visible terminal states and `tool_use`
+  // as an intermediate loop-control state.
+  const _validStepStops: LoopStepStopReason[] = [
+    'end_turn',
+    'max_tokens',
+    'tool_use',
+    'filtered',
+    'paused',
+    'unknown',
+  ];
+  void _validStepStops;
+
+  const _validTerminalStepStops: LoopTerminalStepStopReason[] = [
+    'end_turn',
+    'max_tokens',
+    'filtered',
+    'paused',
+    'unknown',
+  ];
+  void _validTerminalStepStops;
+
+  // Turn stop reasons exclude `tool_use` because a completed turn never returns
+  // while tools are still pending.
+  const _validTurnStops: LoopTurnStopReason[] = [
+    'end_turn',
+    'max_tokens',
+    'filtered',
+    'paused',
+    'unknown',
+    'aborted',
+  ];
+  void _validTurnStops;
+
+  const _deprecatedStopAlias: StopReason[] = [
+    'end_turn',
+    'max_tokens',
+    'tool_use',
+    'filtered',
+    'paused',
+    'unknown',
+    'aborted',
+  ];
+  void _deprecatedStopAlias;
+
+  // @ts-expect-error - stop reasons that flow through throws are not in the union
+  const _badStop1: LoopTurnStopReason = 'error';
+  void _badStop1;
+  // @ts-expect-error - max_steps is represented by a thrown KimiError, not StopReason.
+  const _badStop2: LoopTurnStopReason = 'max_steps';
+  void _badStop2;
+  // @ts-expect-error - tool_use is step-local and cannot be a final turn result.
+  const _badStop3: LoopTurnStopReason = 'tool_use';
+  void _badStop3;
+
+  // Capability metadata reuses Kosong's provider-facing shape.
+  const capability: ModelCapability = {
+    image_in: false,
+    video_in: false,
+    audio_in: false,
+    thinking: false,
+    tool_use: true,
+    max_context_tokens: 200000,
+  };
+  const _llmCapability: ModelCapability | undefined = _llm.capability;
+  void capability;
+  void _llmCapability;
+
+  // ToolCall reuses Kosong's provider-facing function-call shape.
+  const toolCall: ToolCall = {
+    type: 'function',
+    id: 'tc1',
+    function: { name: 'echo', arguments: '{"text":"hi"}' },
+  };
+  void toolCall;
+  const _badToolCall: ToolCall = {
+    // @ts-expect-error — the loop no longer owns a parsed `{ name, args }` tool-call shape.
+    name: 'echo',
+    args: {},
+  };
+  void _badToolCall;
+
+  const toolResultContent: ContentPart[] = [
+    { type: 'text', text: 'see image:' },
+    { type: 'image_url', imageUrl: { url: 'data:image/png;base64,AAAA' } },
+  ];
+  const structuredToolResult: ExecutableToolResult = { output: toolResultContent };
+  void structuredToolResult;
+
+  const executeContext: ExecutableToolContext = {
+    turnId: 't1',
+    toolCallId: 'tc1',
+    signal: _signal,
+  };
+  void executeContext;
+  const _badExecuteContext: ExecutableToolContext = {
+    turnId: 't1',
+    toolCallId: 'tc1',
+    signal: _signal,
+    // @ts-expect-error — args are captured by resolveExecution(input), not passed in execute context.
+    args: {},
+  };
+  void _badExecuteContext;
+
+  // ExecutableTool is one object: Kosong's model-visible definition plus resolveExecution().
+  const _tool: ExecutableTool = {
+    name: 'x',
+    description: 'x',
+    parameters: { type: 'object' },
+    resolveExecution: () => ({
+      execute: async (_ctx: ExecutableToolContext) => ({ output: 'ok' }),
+    }),
+  };
+  void _tool;
+  const _describableTool: ExecutableTool<{ text: string }> = {
+    name: 'x',
+    description: 'x',
+    parameters: { type: 'object' },
+    resolveExecution: (args) => ({
+      accesses: ToolAccesses.none(),
+      description: `Running ${args.text}`,
+      execute: async (_ctx: ExecutableToolContext) => ({ output: 'ok' }),
+    }),
+  };
+  void _describableTool;
+  const _badTool: ExecutableTool = {
+    name: 'x',
+    description: 'x',
+    parameters: { type: 'object' },
+    resolveExecution: () => ({
+      execute: async (_ctx: ExecutableToolContext) => ({ output: 'ok' }),
+    }),
+    // @ts-expect-error — there is no second Zod schema source on ExecutableTool.
+    inputSchema: {},
+  };
+  void _badTool;
+
+  // Hook function aliases name the phase boundary; LoopHooks stays readable.
+  const beforeStepHook: BeforeStepHook = async (ctx) => {
+    const llm: LLM = ctx.llm;
+    void llm;
+    const result: BeforeStepResult = { block: false };
+    return result;
+  };
+  const afterStepHook: AfterStepHook = async (ctx) => {
+    const usage: TokenUsage = ctx.usage;
+    void usage;
+  };
+  const prepareToolExecutionHook: PrepareToolExecutionHook = async (ctx) => ({
+    updatedArgs: ctx.args,
+  });
+  const finalizeToolResultHook: FinalizeToolResultHook = async (ctx) => ctx.result;
+  const shouldContinueAfterStopHook: ShouldContinueAfterStopHook = async (ctx) => ({
+    continue: ctx.stopReason === 'max_tokens',
+  });
+  const shouldContinueAfterStopResult: ShouldContinueAfterStopResult = { continue: false };
+  void shouldContinueAfterStopResult;
+  const hookShapes: LoopHooks = {
+    beforeStep: beforeStepHook,
+    afterStep: afterStepHook,
+    prepareToolExecution: prepareToolExecutionHook,
+    finalizeToolResult: finalizeToolResultHook,
+    shouldContinueAfterStop: shouldContinueAfterStopHook,
+  };
+  void hookShapes;
+
+  // LoopEvent is a closed union with the documented variants.
+  const _evs: LoopEvent[] = [
+    { type: 'step.begin', uuid: 's1', turnId: 't1', step: 1 },
+    { type: 'step.end', uuid: 's1', turnId: 't1', step: 1 },
+    {
+      type: 'content.part',
+      uuid: 'c1',
+      turnId: 't1',
+      step: 1,
+      stepUuid: 's1',
+      part: { type: 'text', text: '' },
+    },
+    { type: 'turn.interrupted', attemptedSteps: 1, activeStep: 1, reason: 'aborted' },
+    { type: 'text.delta', delta: '' },
+    { type: 'thinking.delta', delta: '' },
+    { type: 'tool.call.delta', toolCallId: 'a' },
+    {
+      type: 'tool.call',
+      uuid: 'a',
+      turnId: 't1',
+      step: 1,
+      stepUuid: 's1',
+      toolCallId: 'a',
+      name: 'x',
+      args: {},
+    },
+    { type: 'tool.progress', toolCallId: 'a', update: { kind: 'stdout' } },
+    { type: 'tool.result', parentUuid: 'a', toolCallId: 'a', result: { output: '' } },
+  ];
+  void _evs;
+
+  // All recorded events are also live events, including completed content parts.
+  const _contentPartLiveEvent: LoopEvent = _evs[2] as LoopEvent;
+  void _contentPartLiveEvent;
+
+  // TurnResult fields
+  const _tr: TurnResult = { stopReason: 'end_turn', steps: 1, usage: {} as TokenUsage };
+  void _tr;
+
+  // Cross-reference all named exports just to keep this list in sync
+  // with the barrel — adding a new public type without referencing it
+  // here will not break anything, but removing one breaks compile.
+  type _Exports =
+    | AfterStepHook
+    | BeforeStepResult
+    | BeforeStepHook
+    | LLMChatParams
+    | LLMChatResponse
+    | ShouldContinueAfterStopHook
+    | ShouldContinueAfterStopResult
+    | LoopContentPartEvent
+    | LoopRecordedEvent
+    | LoopLiveOnlyEvent
+    | LoopEvent
+    | LoopLiveEventEmitter
+    | LoopInterruptReason
+    | LoopMessageBuilder
+    | LoopEventDispatcher
+    | LoopAfterStepContext
+    | LoopStepHookContext
+    | LoopStoppedStepContext
+    | LoopTerminalStepStopReason
+    | LoopStepStopReason
+    | LoopTurnStopReason
+    | LoopStepBeginEvent
+    | LoopStepEndEvent
+    | LoopTextDeltaEvent
+    | LoopThinkingDeltaEvent
+    | LoopToolCallDeltaEvent
+    | LoopToolCallEvent
+    | LoopToolProgressEvent
+    | LoopToolResultEvent
+    | LoopTurnInterruptedEvent
+    | ToolCallDelta
+    | ToolCall
+    | ToolExecutionHookContext
+    | PrepareToolExecutionHook
+    | PrepareToolExecutionResult
+    | FinalizeToolResultContext
+    | FinalizeToolResultHook
+    | TurnResult;
+  const _e: _Exports | undefined = undefined;
+  void _e;
+}
+void _typeOnlyChecks;
+
+describe('loop public API shape', () => {
+  it('barrel exports the runtime entry points', () => {
+    expect(typeof runTurn).toBe('function');
+    expect(typeof createLoopEventDispatcher).toBe('function');
+  });
+});
diff --git a/packages/agent-core/test/loop/error-paths.e2e.test.ts b/packages/agent-core/test/loop/error-paths.e2e.test.ts
new file mode 100644
index 000000000..5a3fb2a38
--- /dev/null
+++ b/packages/agent-core/test/loop/error-paths.e2e.test.ts
@@ -0,0 +1,183 @@
+/**
+ * Error propagation contract.
+ *
+ * The loop never returns `'error'` or `'max_steps'` as a stopReason — those
+ * states surface only by throwing. AbortError-shaped exceptions converge
+ * to `stopReason='aborted'` and never throw to the caller. Every throw
+ * is preceded by exactly one `turn.interrupted` event whose `reason`
+ * names the cause.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { ErrorCodes, KimiError } from '../../src/errors';
+import type { Logger, LogPayload } from '../../src/logging';
+import type { LoopHooks } from '../../src/loop/index';
+import { makeEndTurnResponse, makeToolCall, makeToolUseResponse } from './fixtures/fake-llm';
+import { runTurn, runTurnExpectingThrow } from './fixtures/helpers';
+import { EchoTool } from './fixtures/tools';
+
+interface CapturedLogEntry {
+  readonly level: 'error' | 'warn' | 'info' | 'debug';
+  readonly message: string;
+  readonly payload?: LogPayload;
+}
+
+describe('runTurn — error paths', () => {
+  it('rethrows non-abort LLM errors with turn.interrupted{reason:"error"}', async () => {
+    const llmError = new Error('upstream blew up');
+    const { error, sink, context } = await runTurnExpectingThrow({
+      responses: [makeEndTurnResponse('never')], // ignored: throw fires first
+      llmThrowOnIndex: { index: 0, error: llmError },
+    });
+
+    expect(error).toBe(llmError);
+    const interrupted = sink.byType('turn.interrupted');
+    expect(interrupted.length).toBe(1);
+    expect(interrupted[0]?.reason).toBe('error');
+    expect(interrupted[0]?.attemptedSteps).toBe(1);
+    expect(interrupted[0]?.activeStep).toBe(1);
+    // step.begin was opened but step.end was NOT
+    expect(context.stepBegins().length).toBe(1);
+    expect(context.stepEnds().length).toBe(0);
+  });
+
+  it('logs non-abort LLM request failures without request payloads or stacks', async () => {
+    const llmError = new Error('upstream blew up');
+    const { logger, entries } = captureLogs();
+    const { error } = await runTurnExpectingThrow({
+      responses: [makeEndTurnResponse('never')],
+      llmThrowOnIndex: { index: 0, error: llmError },
+      log: logger,
+    });
+
+    expect(error).toBe(llmError);
+    expect(entries).toEqual([
+      {
+        level: 'warn',
+        message: 'llm request failed',
+        payload: {
+          turnId: 'turn-1',
+          step: 1,
+          attempt: 1,
+          maxAttempts: 3,
+          model: 'fake-model',
+          errorName: 'Error',
+          errorMessage: 'upstream blew up',
+        },
+      },
+    ]);
+  });
+
+  it('does not log aborted LLM requests as failures', async () => {
+    const controller = new AbortController();
+    const { logger, entries } = captureLogs();
+    const { result } = await runTurn({
+      responses: [makeEndTurnResponse('never')],
+      llmAbortOnIndex: { index: 0, controller },
+      signal: controller.signal,
+      log: logger,
+    });
+
+    expect(result.stopReason).toBe('aborted');
+    expect(entries).toEqual([]);
+  });
+
+  it('throws KimiError(loop.max_steps_exceeded) with turn.interrupted{reason:"max_steps"} before the throw', async () => {
+    const echo = new EchoTool();
+    const { error, sink } = await runTurnExpectingThrow({
+      maxSteps: 2,
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: '1' }, 'a')]),
+        makeToolUseResponse([makeToolCall('echo', { text: '2' }, 'b')]),
+        // never reached
+      ],
+    });
+
+    expect(error).toBeInstanceOf(KimiError);
+    expect((error as KimiError).code).toBe(ErrorCodes.LOOP_MAX_STEPS_EXCEEDED);
+    const interrupted = sink.byType('turn.interrupted');
+    expect(interrupted.map((e) => e.reason)).toEqual(['max_steps']);
+    expect(interrupted[0]?.attemptedSteps).toBe(2);
+    expect(interrupted[0]?.activeStep).toBeUndefined();
+  });
+
+  it('rethrows non-abort hook errors via the same path', async () => {
+    const hookError = new Error('hook crashed');
+    const hooks: LoopHooks = {
+      beforeStep: async () => {
+        throw hookError;
+      },
+    };
+    const { error, sink } = await runTurnExpectingThrow({
+      hooks,
+      responses: [makeEndTurnResponse('never')],
+    });
+
+    expect(error).toBe(hookError);
+    const interrupted = sink.byType('turn.interrupted');
+    expect(interrupted.length).toBe(1);
+    expect(interrupted[0]?.reason).toBe('error');
+  });
+
+  it('AbortError thrown by a hook converges to stopReason="aborted" (no throw)', async () => {
+    const controller = new AbortController();
+    const hooks: LoopHooks = {
+      beforeStep: async () => {
+        controller.abort();
+        const err = new Error('aborted');
+        err.name = 'AbortError';
+        throw err;
+      },
+    };
+    const { result, sink } = await runTurn({
+      hooks,
+      responses: [makeEndTurnResponse('never')],
+      signal: controller.signal,
+    });
+    expect(result.stopReason).toBe('aborted');
+    const interrupted = sink.byType('turn.interrupted');
+    expect(interrupted.length).toBe(1);
+    expect(interrupted[0]?.reason).toBe('aborted');
+  });
+
+  it('emits turn.interrupted exactly once per failure (no duplicate emits)', async () => {
+    const { sink } = await runTurnExpectingThrow({
+      responses: [makeEndTurnResponse('never')],
+      llmThrowOnIndex: { index: 0, error: new Error('once') },
+    });
+    expect(sink.byType('turn.interrupted').length).toBe(1);
+  });
+
+  it('does NOT emit step.end when a step throws before sealing', async () => {
+    const { sink } = await runTurnExpectingThrow({
+      responses: [makeEndTurnResponse('never')],
+      llmThrowOnIndex: { index: 0, error: new Error('boom') },
+    });
+    // step.begin fires, step.end does not, turn.interrupted takes its place
+    expect(sink.count('step.begin')).toBe(1);
+    expect(sink.count('step.end')).toBe(0);
+    expect(sink.count('turn.interrupted')).toBe(1);
+  });
+});
+
+function captureLogs(): { readonly logger: Logger; readonly entries: CapturedLogEntry[] } {
+  const entries: CapturedLogEntry[] = [];
+  const logger: Logger = {
+    error: (message, payload) => {
+      entries.push({ level: 'error', message, payload });
+    },
+    warn: (message, payload) => {
+      entries.push({ level: 'warn', message, payload });
+    },
+    info: (message, payload) => {
+      entries.push({ level: 'info', message, payload });
+    },
+    debug: (message, payload) => {
+      entries.push({ level: 'debug', message, payload });
+    },
+    createChild: () => logger,
+  };
+  return { logger, entries };
+}
diff --git a/packages/agent-core/test/loop/events.e2e.test.ts b/packages/agent-core/test/loop/events.e2e.test.ts
new file mode 100644
index 000000000..9f82d4f12
--- /dev/null
+++ b/packages/agent-core/test/loop/events.e2e.test.ts
@@ -0,0 +1,176 @@
+/**
+ * LoopEventDispatcher live event contract — fire-and-forget listener errors must
+ * never reach the loop.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import type { LoopEvent, LoopLiveEventEmitter } from '../../src/loop/index';
+import { CollectingSink } from './fixtures/collecting-sink';
+import { makeEndTurnResponse, makeToolCall, makeToolUseResponse } from './fixtures/fake-llm';
+import { runTurn } from './fixtures/helpers';
+import { EchoTool, markReadAnyFileAccesses, ProgressTool } from './fixtures/tools';
+
+describe('runTurn — LoopEventDispatcher live event containment', () => {
+  it('contains synchronous emit() throws', async () => {
+    const sink = new CollectingSink({ errorMode: { kind: 'sync-throw' } });
+    const { result } = await runTurn({
+      emitLiveEvent: sink.emit,
+      responses: [makeEndTurnResponse('ok')],
+    });
+    // The loop still completes the turn.
+    expect(result.stopReason).toBe('end_turn');
+  });
+
+  it('contains async-rejected emit() returns', async () => {
+    const sink = new CollectingSink({ errorMode: { kind: 'async-reject' } });
+    const { result } = await runTurn({
+      emitLiveEvent: sink.emit,
+      responses: [makeEndTurnResponse('ok')],
+    });
+    expect(result.stopReason).toBe('end_turn');
+    // Each emit is recorded even though the listener returned a rejected
+    // promise; LoopEventDispatcher attaches a terminal catch.
+    expect(sink.events.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('survives a sink that throws on EVERY emit across a full multi-step turn', async () => {
+    const sink = new CollectingSink({ errorMode: { kind: 'every-call-throws' } });
+    const echo = new EchoTool();
+    const progress = new ProgressTool();
+    const { result, context } = await runTurn({
+      emitLiveEvent: sink.emit,
+      tools: [echo, progress],
+      responses: [
+        makeToolUseResponse([
+          makeToolCall('echo', { text: '1' }, 'a'),
+          makeToolCall('progress', {}, 'b'),
+        ]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    // Despite every emit throwing, the turn still converges and writes
+    // its transcript records.
+    expect(result.stopReason).toBe('end_turn');
+    expect(context.stepBegins().length).toBe(2);
+    expect(context.stepEnds().length).toBe(2);
+    // The tool was still executed
+    expect(echo.calls.length).toBe(1);
+    expect(progress.calls.length).toBe(1);
+  });
+
+  it('allows host-owned fan-out through a single emitter function', async () => {
+    const a = new CollectingSink({ id: 'a' });
+    const b = new CollectingSink({ id: 'b' });
+    const { result } = await runTurn({
+      emitLiveEvent: (event) => {
+        a.emit(event);
+        b.emit(event);
+      },
+      responses: [makeEndTurnResponse('ok')],
+    });
+    expect(result.stopReason).toBe('end_turn');
+    expect(a.typesIn()).toEqual(b.typesIn());
+    expect(a.events.length).toBeGreaterThan(0);
+  });
+
+  it('a misbehaving sink does not starve the others', async () => {
+    const broken = new CollectingSink({
+      id: 'broken',
+      errorMode: { kind: 'every-call-throws' },
+    });
+    const good = new CollectingSink({ id: 'good' });
+    const { result } = await runTurn({
+      emitLiveEvent: (event) => {
+        try {
+          broken.emit(event);
+        } catch {
+          // host-owned fan-out contains individual listener failure
+        }
+        good.emit(event);
+      },
+      responses: [makeEndTurnResponse('ok')],
+    });
+    expect(result.stopReason).toBe('end_turn');
+    // Good sink received the events; ordering matches the documented set.
+    expect(good.count('step.begin')).toBe(1);
+    expect(good.count('step.end')).toBe(1);
+  });
+
+  it('emits a documented full event sequence for one tool-bearing turn', async () => {
+    const echo = markReadAnyFileAccesses(new EchoTool());
+    const progress = markReadAnyFileAccesses(
+      new ProgressTool([{ kind: 'progress', percent: 50 }]),
+    );
+    const { sink } = await runTurn({
+      tools: [echo, progress],
+      responses: [
+        makeToolUseResponse([
+          makeToolCall('echo', { text: 'hi' }, 'tc-1'),
+          makeToolCall('progress', {}, 'tc-2'),
+        ]),
+        makeEndTurnResponse('done', { inputOther: 1, output: 1 }),
+      ],
+    });
+
+    const types = sink.typesIn();
+    // Required milestones in order
+    const order: LoopEvent['type'][] = [
+      'step.begin',
+      'tool.call',
+      'tool.call',
+      'tool.result',
+      'tool.result',
+      'step.end',
+      'step.begin',
+      'step.end',
+    ];
+    // Every required type appears in the right relative order
+    let fromIdx = 0;
+    for (const expected of order) {
+      const found = types.indexOf(expected, fromIdx);
+      expect(
+        found,
+        `missing ${expected} starting at ${String(fromIdx)} of [${types.join(',')}]`,
+      ).toBeGreaterThanOrEqual(fromIdx);
+      fromIdx = found + 1;
+    }
+    // tool.progress fired between tool.call and tool.result
+    expect(sink.byType('tool.progress').length).toBe(1);
+  });
+
+  it('LoopEvent payload carries the documented fields', async () => {
+    const echo = new EchoTool();
+    const { sink } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'hi' }, 'tc-99')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    const tc = sink.byType('tool.call')[0];
+    expect(tc).toBeDefined();
+    expect(tc?.toolCallId).toBe('tc-99');
+    expect(tc?.name).toBe('echo');
+    expect(tc?.args).toEqual({ text: 'hi' });
+    const tr = sink.byType('tool.result')[0];
+    expect(tr?.toolCallId).toBe('tc-99');
+    expect(typeof tr?.result.output).toBe('string');
+  });
+
+  it('accepts a custom emitter function', async () => {
+    class StrictCollector {
+      readonly events: LoopEvent[] = [];
+      readonly emit: LoopLiveEventEmitter = (event) => {
+        this.events.push(event);
+      };
+    }
+    const custom = new StrictCollector();
+    const { result } = await runTurn({
+      emitLiveEvent: custom.emit,
+      responses: [makeEndTurnResponse('ok')],
+    });
+    expect(result.stopReason).toBe('end_turn');
+    expect(custom.events.length).toBeGreaterThan(0);
+  });
+});
diff --git a/packages/agent-core/test/loop/fixtures/collecting-sink.ts b/packages/agent-core/test/loop/fixtures/collecting-sink.ts
new file mode 100644
index 000000000..8b4c59b80
--- /dev/null
+++ b/packages/agent-core/test/loop/fixtures/collecting-sink.ts
@@ -0,0 +1,82 @@
+import type { LoopEvent, LoopLiveEventEmitter } from '../../../src/loop/index';
+
+export type SinkErrorMode =
+  | { kind: 'none' }
+  | { kind: 'sync-throw'; onlyAt?: number }
+  | { kind: 'async-reject'; onlyAt?: number }
+  | { kind: 'every-call-throws' };
+
+export interface CollectingSinkOptions {
+  readonly errorMode?: SinkErrorMode | undefined;
+  readonly id?: string | undefined;
+}
+
+/**
+ * Records every event into `events` and supports several injected error
+ * modes so tests can assert the loop's listener-failure containment.
+ *
+ * `LoopLiveEventEmitter` is typed `void`, but LoopEventDispatcher also defends
+ * against thenable returns (async listeners). We keep the declared
+ * signature `void` and use a runtime cast for the async-reject mode so
+ * we exercise the production code path without violating types at the
+ * call site.
+ */
+export class CollectingSink {
+  readonly events: LoopEvent[] = [];
+  readonly id: string;
+  private mode: SinkErrorMode;
+  private callCount = 0;
+
+  constructor(opts: CollectingSinkOptions = {}) {
+    this.mode = opts.errorMode ?? { kind: 'none' };
+    this.id = opts.id ?? 'sink';
+  }
+
+  readonly emit: LoopLiveEventEmitter = (event) => {
+    const callIndex = this.callCount;
+    this.callCount += 1;
+
+    if (this.mode.kind === 'every-call-throws') {
+      this.events.push(event);
+      throw new Error(`sink ${this.id} fails on every emit`);
+    }
+
+    if (
+      this.mode.kind === 'sync-throw' &&
+      (this.mode.onlyAt === undefined || this.mode.onlyAt === callIndex)
+    ) {
+      throw new Error(`sink ${this.id} sync throw at call ${String(callIndex)}`);
+    }
+
+    if (
+      this.mode.kind === 'async-reject' &&
+      (this.mode.onlyAt === undefined || this.mode.onlyAt === callIndex)
+    ) {
+      // Structurally the function returns a rejected promise instead of
+      // void; LoopEventDispatcher must contain it.
+      const rejected = Promise.reject(
+        new Error(`sink ${this.id} async reject at call ${String(callIndex)}`),
+      );
+      this.events.push(event);
+      return rejected as unknown as void;
+    }
+
+    this.events.push(event);
+  };
+
+  setErrorMode(mode: SinkErrorMode): void {
+    this.mode = mode;
+  }
+
+  typesIn(): LoopEvent['type'][] {
+    return this.events.map((e) => e.type);
+  }
+
+  count(type: LoopEvent['type']): number {
+    return this.events.filter((e) => e.type === type).length;
+  }
+
+  byType<T extends LoopEvent['type']>(type: T): Extract<LoopEvent, { type: T }>[] {
+    return this.events.filter((e): e is Extract<LoopEvent, { type: T }> => e.type === type);
+  }
+}
diff --git a/packages/agent-core/test/loop/fixtures/fake-llm.ts b/packages/agent-core/test/loop/fixtures/fake-llm.ts
new file mode 100644
index 000000000..f346ff57e
--- /dev/null
+++ b/packages/agent-core/test/loop/fixtures/fake-llm.ts
@@ -0,0 +1,207 @@
+import {
+  emptyUsage,
+  type FinishReason,
+  type ModelCapability,
+  type TextPart,
+  type ThinkPart,
+  type TokenUsage,
+} from '@moonshot-ai/kosong';
+
+import type {
+  LLM,
+  LLMChatParams,
+  LLMChatResponse,
+  LoopStepStopReason,
+  ToolCall,
+} from '../../../src/loop/index';
+
+export type FakeOutputPart = TextPart | ThinkPart;
+
+export interface FakeLLMResponse extends LLMChatResponse {
+  readonly contentParts?: readonly FakeOutputPart[] | undefined;
+}
+
+export interface FakeLLMOptions {
+  readonly responses: readonly FakeLLMResponse[];
+  readonly throwOnIndex?: { readonly index: number; readonly error: unknown } | undefined;
+  readonly abortOnIndex?:
+    | { readonly index: number; readonly controller: AbortController }
+    | undefined;
+  readonly delayMs?: number | undefined;
+  readonly modelName?: string | undefined;
+  readonly capability?: ModelCapability | undefined;
+  readonly systemPrompt?: string | undefined;
+}
+
+export class FakeLLM implements LLM {
+  readonly systemPrompt: string;
+  readonly modelName: string;
+  readonly capability?: ModelCapability | undefined;
+
+  readonly calls: LLMChatParams[] = [];
+
+  private index = 0;
+  private readonly responses: readonly FakeLLMResponse[];
+  private readonly throwOnIndex: FakeLLMOptions['throwOnIndex'];
+  private readonly abortOnIndex: FakeLLMOptions['abortOnIndex'];
+  private readonly delayMs: number;
+
+  constructor(opts: FakeLLMOptions) {
+    this.systemPrompt = opts.systemPrompt ?? 'fake system prompt';
+    this.modelName = opts.modelName ?? 'fake-model';
+    this.capability = opts.capability;
+    this.responses = opts.responses;
+    this.throwOnIndex = opts.throwOnIndex;
+    this.abortOnIndex = opts.abortOnIndex;
+    this.delayMs = opts.delayMs ?? 0;
+  }
+
+  async chat(params: LLMChatParams): Promise<LLMChatResponse> {
+    this.calls.push(params);
+    const current = this.index;
+    this.index += 1;
+
+    if (this.delayMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, this.delayMs));
+    }
+
+    if (this.abortOnIndex !== undefined && this.abortOnIndex.index === current) {
+      this.abortOnIndex.controller.abort();
+    }
+
+    if (params.signal.aborted) {
+      const err = new Error('aborted');
+      err.name = 'AbortError';
+      throw err;
+    }
+
+    if (this.throwOnIndex !== undefined && this.throwOnIndex.index === current) {
+      throw this.throwOnIndex.error;
+    }
+
+    if (current >= this.responses.length) {
+      throw new Error(`FakeLLM ran out of responses at call ${String(current + 1)}`);
+    }
+
+    const response = this.responses[current];
+    if (response === undefined) {
+      throw new Error(`FakeLLM: missing response at index ${String(current)}`);
+    }
+
+    for (const part of response.contentParts ?? []) {
+      if (part.type === 'text') {
+        await params.onTextPart?.(part);
+      } else {
+        await params.onThinkPart?.(part);
+      }
+    }
+
+    return response;
+  }
+
+  get callCount(): number {
+    return this.calls.length;
+  }
+}
+
+export function makeTextParts(text: string): FakeOutputPart[] {
+  return text.length > 0 ? [{ type: 'text', text }] : [];
+}
+
+export function makeThinkingParts(
+  thinking: string,
+  text = '',
+  signature?: string,
+): FakeOutputPart[] {
+  const parts: FakeOutputPart[] =
+    signature !== undefined
+      ? [{ type: 'think', think: thinking, encrypted: signature }]
+      : [{ type: 'think', think: thinking }];
+  if (text.length > 0) parts.push({ type: 'text', text });
+  return parts;
+}
+
+export function makeEndTurnResponse(
+  text: string,
+  usage: Partial<TokenUsage> = {},
+): FakeLLMResponse {
+  return {
+    toolCalls: [],
+    providerFinishReason: 'completed',
+    usage: zeroUsage(usage),
+    contentParts: makeTextParts(text),
+  };
+}
+
+export function makeMaxTokensResponse(
+  text: string,
+  usage: Partial<TokenUsage> = {},
+): FakeLLMResponse {
+  return {
+    toolCalls: [],
+    providerFinishReason: 'truncated',
+    usage: zeroUsage(usage),
+    contentParts: makeTextParts(text),
+  };
+}
+
+export function makeToolUseResponse(
+  toolCalls: ToolCall[],
+  usage: Partial<TokenUsage> = {},
+): FakeLLMResponse {
+  return {
+    toolCalls,
+    providerFinishReason: 'tool_calls',
+    usage: zeroUsage(usage),
+  };
+}
+
+export function makeResponse(
+  contentParts: readonly FakeOutputPart[],
+  toolCalls: ToolCall[],
+  stopReason: LoopStepStopReason,
+  usage: Partial<TokenUsage> = {},
+): FakeLLMResponse {
+  return {
+    contentParts,
+    toolCalls,
+    providerFinishReason: providerFinishReasonForStopReason(stopReason),
+    usage: zeroUsage(usage),
+  };
+}
+
+function providerFinishReasonForStopReason(reason: LoopStepStopReason): FinishReason {
+  switch (reason) {
+    case 'end_turn':
+      return 'completed';
+    case 'tool_use':
+      return 'tool_calls';
+    case 'max_tokens':
+      return 'truncated';
+    case 'filtered':
+      return 'filtered';
+    case 'paused':
+      return 'paused';
+    case 'unknown':
+      return 'other';
+    default: {
+      const _exhaustive: never = reason;
+      return _exhaustive;
+    }
+  }
+}
+
+export function zeroUsage(partial: Partial<TokenUsage> = {}): TokenUsage {
+  return { ...emptyUsage(), ...partial };
+}
+
+export function makeToolCall(name: string, args: unknown, id?: string): ToolCall {
+  return {
+    type: 'function',
+    id: id ?? `call_${Math.random().toString(36).slice(2, 10)}`,
+    function: {
+      name,
+      arguments: JSON.stringify(args),
+    },
+  };
+}
diff --git a/packages/agent-core/test/loop/fixtures/helpers.ts b/packages/agent-core/test/loop/fixtures/helpers.ts
new file mode 100644
index 000000000..ce08e3a44
--- /dev/null
+++ b/packages/agent-core/test/loop/fixtures/helpers.ts
@@ -0,0 +1,141 @@
+import type {
+  ExecutableTool,
+  RunTurnInput,
+  LoopHooks,
+  LoopLiveEventEmitter,
+  TurnResult,
+} from '../../../src/loop/index';
+import type { Logger } from '../../../src/logging';
+import { createLoopEventDispatcher, runTurn as runTurnImpl } from '../../../src/loop/index';
+import { CollectingSink, type SinkErrorMode } from './collecting-sink';
+import { FakeLLM, type FakeLLMResponse } from './fake-llm';
+import { RecordingContext, type RecordingContextOptions } from './recording-context';
+
+export interface RunTurnOptions {
+  readonly responses: readonly FakeLLMResponse[];
+  readonly tools?: readonly ExecutableTool[] | undefined;
+  readonly hooks?: LoopHooks | undefined;
+  readonly log?: Logger | undefined;
+  readonly maxSteps?: number | undefined;
+  readonly turnId?: string | undefined;
+  readonly signal?: AbortSignal | undefined;
+  readonly emitLiveEvent?: LoopLiveEventEmitter | undefined;
+  readonly llmThrowOnIndex?: { index: number; error: unknown } | undefined;
+  readonly llmAbortOnIndex?: { index: number; controller: AbortController } | undefined;
+  readonly llmDelayMs?: number | undefined;
+  readonly systemPrompt?: string | undefined;
+  readonly contextOptions?: RecordingContextOptions | undefined;
+  readonly sinkErrorMode?: SinkErrorMode | undefined;
+}
+
+export interface RunTurnResult {
+  readonly result: TurnResult;
+  readonly llm: FakeLLM;
+  readonly context: RecordingContext;
+  readonly sink: CollectingSink;
+}
+
+/**
+ * Run one turn end-to-end with sensible defaults. Returns the turn result
+ * plus the fixture instances so tests can assert against them.
+ */
+export async function runTurn(opts: RunTurnOptions): Promise<RunTurnResult> {
+  const llm = new FakeLLM({
+    responses: opts.responses,
+    throwOnIndex: opts.llmThrowOnIndex,
+    abortOnIndex: opts.llmAbortOnIndex,
+    delayMs: opts.llmDelayMs,
+    systemPrompt: opts.systemPrompt,
+  });
+  const context = new RecordingContext(opts.contextOptions ?? {});
+  const fallback = new CollectingSink({ errorMode: opts.sinkErrorMode });
+  const sink = fallback;
+  const input: RunTurnInput = {
+    turnId: opts.turnId ?? 'turn-1',
+    signal: opts.signal ?? new AbortController().signal,
+    llm,
+    buildMessages: context.buildMessages,
+    dispatchEvent: createLoopEventDispatcher({
+      appendTranscriptRecord: context.appendTranscriptRecord,
+      emitLiveEvent: opts.emitLiveEvent ?? fallback.emit,
+    }),
+    tools: opts.tools,
+    hooks: opts.hooks,
+    log: opts.log,
+    maxSteps: opts.maxSteps,
+  };
+  const result = await runTurnImpl(input);
+  return { result, llm, context, sink };
+}
+
+/**
+ * Run a turn that's expected to throw, returning the captured error.
+ * Throws if the turn returns normally.
+ */
+export async function runTurnExpectingThrow(opts: RunTurnOptions): Promise<{
+  error: unknown;
+  llm: FakeLLM;
+  context: RecordingContext;
+  sink: CollectingSink;
+}> {
+  const llm = new FakeLLM({
+    responses: opts.responses,
+    throwOnIndex: opts.llmThrowOnIndex,
+    abortOnIndex: opts.llmAbortOnIndex,
+    delayMs: opts.llmDelayMs,
+    systemPrompt: opts.systemPrompt,
+  });
+  const context = new RecordingContext(opts.contextOptions ?? {});
+  const fallback = new CollectingSink({ errorMode: opts.sinkErrorMode });
+  const sink = fallback;
+  const input: RunTurnInput = {
+    turnId: opts.turnId ?? 'turn-1',
+    signal: opts.signal ?? new AbortController().signal,
+    llm,
+    buildMessages: context.buildMessages,
+    dispatchEvent: createLoopEventDispatcher({
+      appendTranscriptRecord: context.appendTranscriptRecord,
+      emitLiveEvent: opts.emitLiveEvent ?? fallback.emit,
+    }),
+    tools: opts.tools,
+    hooks: opts.hooks,
+    log: opts.log,
+    maxSteps: opts.maxSteps,
+  };
+  try {
+    await runTurnImpl(input);
+  } catch (error) {
+    return { error, llm, context, sink };
+  }
+  throw new Error('runTurnExpectingThrow: expected throw, got resolution');
+}
+
+/**
+ * Find the index of a kind in `recording.kinds()`, throwing a clear
+ * error if it's missing. Helpful for adjacency-pair assertions.
+ */
+export function indexOfKind(kinds: readonly string[], kind: string, fromIndex = 0): number {
+  for (let i = fromIndex; i < kinds.length; i += 1) {
+    if (kinds[i] === kind) return i;
+  }
+  throw new Error(`indexOfKind: missing "${kind}" in [${kinds.join(',')}]`);
+}
+
+/**
+ * Assert that one kind appears immediately before another (for ordering
+ * assertions that aren't full-sequence snapshots).
+ */
+export function assertImmediatelyBefore(
+  kinds: readonly string[],
+  earlier: string,
+  later: string,
+): void {
+  const i = indexOfKind(kinds, earlier);
+  if (kinds[i + 1] !== later) {
+    throw new Error(
+      `expected "${earlier}" to be immediately followed by "${later}", got "${
+        kinds[i + 1] ?? '<end>'
+      }". full: [${kinds.join(',')}]`,
+    );
+  }
+}
diff --git a/packages/agent-core/test/loop/fixtures/recording-context.ts b/packages/agent-core/test/loop/fixtures/recording-context.ts
new file mode 100644
index 000000000..c6eb6dd3e
--- /dev/null
+++ b/packages/agent-core/test/loop/fixtures/recording-context.ts
@@ -0,0 +1,99 @@
+import type { Message } from '@moonshot-ai/kosong';
+
+import type {
+  LoopContentPartEvent,
+  LoopMessageBuilder,
+  LoopRecordedEvent,
+  LoopStepBeginEvent,
+  LoopStepEndEvent,
+  LoopToolCallEvent,
+  LoopToolResultEvent,
+} from '../../../src/loop/index';
+
+export type AppendCall =
+  | { kind: 'appendStepBegin'; input: LoopStepBeginEvent }
+  | { kind: 'appendStepEnd'; input: LoopStepEndEvent }
+  | { kind: 'appendContentPart'; input: LoopContentPartEvent }
+  | { kind: 'appendToolCall'; input: LoopToolCallEvent }
+  | { kind: 'appendToolResult'; input: LoopToolResultEvent };
+
+export interface RecordingContextOptions {
+  readonly messages?: Message[] | undefined;
+}
+
+/**
+ * Test helper that exposes `buildMessages` and `appendTranscriptRecord` methods
+ * matching the loop's function-shaped input fields.
+ */
+export class RecordingContext {
+  readonly calls: AppendCall[] = [];
+  readonly buildMessagesCalls: number[] = [];
+
+  private _messages: Message[];
+
+  constructor(opts: RecordingContextOptions = {}) {
+    this._messages = opts.messages ?? [];
+  }
+
+  readonly buildMessages: LoopMessageBuilder = () => {
+    this.buildMessagesCalls.push(this.calls.length);
+    return this._messages;
+  };
+
+  setPromptMessages(messages: Message[]): void {
+    this._messages = messages;
+  }
+
+  readonly appendTranscriptRecord = async (record: LoopRecordedEvent): Promise<void> => {
+    switch (record.type) {
+      case 'step.begin': {
+        this.calls.push({ kind: 'appendStepBegin', input: record });
+        return;
+      }
+      case 'step.end': {
+        this.calls.push({ kind: 'appendStepEnd', input: record });
+        return;
+      }
+      case 'content.part': {
+        this.calls.push({ kind: 'appendContentPart', input: record });
+        return;
+      }
+      case 'tool.call': {
+        this.calls.push({ kind: 'appendToolCall', input: record });
+        return;
+      }
+      case 'tool.result':
+        this.calls.push({ kind: 'appendToolResult', input: record });
+    }
+  };
+
+  // Convenience filters
+
+  kinds(): AppendCall['kind'][] {
+    return this.calls.map((c) => c.kind);
+  }
+
+  ofKind<K extends AppendCall['kind']>(kind: K): Extract<AppendCall, { kind: K }>[] {
+    return this.calls.filter((c): c is Extract<AppendCall, { kind: K }> => c.kind === kind);
+  }
+
+  stepBegins(): LoopStepBeginEvent[] {
+    return this.ofKind('appendStepBegin').map((c) => c.input);
+  }
+
+  stepEnds(): LoopStepEndEvent[] {
+    return this.ofKind('appendStepEnd').map((c) => c.input);
+  }
+
+  contentParts(): LoopContentPartEvent[] {
+    return this.ofKind('appendContentPart').map((c) => c.input);
+  }
+
+  toolCalls(): LoopToolCallEvent[] {
+    return this.ofKind('appendToolCall').map((c) => c.input);
+  }
+
+  toolResults(): LoopToolResultEvent[] {
+    return this.ofKind('appendToolResult').map((c) => c.input);
+  }
+}
diff --git a/packages/agent-core/test/loop/fixtures/tools.ts b/packages/agent-core/test/loop/fixtures/tools.ts
new file mode 100644
index 000000000..34cf5446b
--- /dev/null
+++ b/packages/agent-core/test/loop/fixtures/tools.ts
@@ -0,0 +1,299 @@
+import { ToolAccesses } from '../../../src/loop/index';
+import type {
+  ExecutableTool,
+  ExecutableToolResult,
+  ToolExecution,
+  ToolUpdate,
+} from '../../../src/loop/index';
+
+const RECORD_PARAMETERS: Record<string, unknown> = {
+  type: 'object',
+  additionalProperties: true,
+};
+
+const TEXT_PARAMETERS: Record<string, unknown> = {
+  type: 'object',
+  properties: { text: { type: 'string' } },
+  required: ['text'],
+  additionalProperties: false,
+};
+
+const STRICT_PARAMETERS: Record<string, unknown> = {
+  type: 'object',
+  properties: { value: { type: 'number' } },
+  required: ['value'],
+  additionalProperties: false,
+};
+
+export interface RecordedToolCall<Input> {
+  readonly id: string;
+  readonly args: Input;
+  readonly turnId: string;
+}
+
+export function markReadAnyFileAccesses<T extends ExecutableTool>(tool: T): T {
+  const resolveExecution = tool.resolveExecution.bind(tool);
+  tool.resolveExecution = ((input: unknown) => {
+    const execution = resolveExecution(input);
+    return { ...execution, accesses: ToolAccesses.readAnyFile() };
+  }) as T['resolveExecution'];
+  return tool;
+}
+
+export interface EchoInput {
+  text: string;
+}
+
+export class EchoTool implements ExecutableTool<EchoInput> {
+  readonly name = 'echo';
+  readonly description = 'Return the input text unchanged.';
+  readonly parameters = TEXT_PARAMETERS;
+  readonly calls: RecordedToolCall<EchoInput>[] = [];
+
+  resolveExecution(args: EchoInput): ToolExecution {
+    return {
+      execute: async (ctx): Promise<ExecutableToolResult> => {
+        this.calls.push({
+          id: ctx.toolCallId,
+          args,
+          turnId: ctx.turnId,
+        });
+        return { output: args.text };
+      },
+    };
+  }
+}
+
+export type FailingInput = Record<string, unknown>;
+
+export class FailingTool implements ExecutableTool<FailingInput> {
+  readonly name = 'fail';
+  readonly description = 'Always throws.';
+  readonly parameters = RECORD_PARAMETERS;
+  readonly calls: RecordedToolCall<FailingInput>[] = [];
+  readonly errorMessage: string;
+
+  constructor(errorMessage = 'tool blew up') {
+    this.errorMessage = errorMessage;
+  }
+
+  resolveExecution(args: FailingInput): ToolExecution {
+    return {
+      execute: async (ctx): Promise<ExecutableToolResult> => {
+        this.calls.push({
+          id: ctx.toolCallId,
+          args,
+          turnId: ctx.turnId,
+        });
+        throw new Error(this.errorMessage);
+      },
+    };
+  }
+}
+
+export type SlowInput = Record<string, unknown>;
+
+/**
+ * Awaits the abort signal forever. Useful for asserting abort propagation
+ * during tool execution. Throws an AbortError once aborted.
+ */
+export class SlowTool implements ExecutableTool<SlowInput> {
+  readonly name = 'slow';
+  readonly description = 'Blocks until aborted.';
+  readonly parameters = RECORD_PARAMETERS;
+  readonly calls: RecordedToolCall<SlowInput>[] = [];
+  readonly started: { resolve: () => void; promise: Promise<void> };
+
+  constructor() {
+    let resolveStart: () => void = () => {};
+    const startedPromise = new Promise<void>((resolve) => {
+      resolveStart = resolve;
+    });
+    this.started = { resolve: resolveStart, promise: startedPromise };
+  }
+
+  resolveExecution(args: SlowInput): ToolExecution {
+    return {
+      execute: async (ctx): Promise<ExecutableToolResult> => {
+        this.calls.push({
+          id: ctx.toolCallId,
+          args,
+          turnId: ctx.turnId,
+        });
+        this.started.resolve();
+        return new Promise<ExecutableToolResult>((_resolve, reject) => {
+          const onAbort = (): void => {
+            ctx.signal.removeEventListener('abort', onAbort);
+            const err = new Error('slow tool cancelled');
+            err.name = 'AbortError';
+            reject(err);
+          };
+          if (ctx.signal.aborted) {
+            onAbort();
+            return;
+          }
+          ctx.signal.addEventListener('abort', onAbort);
+        });
+      },
+    };
+  }
+}
+
+/**
+ * Ignores abort signals entirely. Combined with the loop's grace timeout this
+ * exercises the "tool refuses to cancel" code path. The promise never
+ * settles on its own.
+ */
+export class HangingTool implements ExecutableTool<Record<string, unknown>> {
+  readonly name = 'hang';
+  readonly description = 'Never settles, ignores abort.';
+  readonly parameters = RECORD_PARAMETERS;
+  readonly calls: RecordedToolCall<Record<string, unknown>>[] = [];
+
+  resolveExecution(args: Record<string, unknown>): ToolExecution {
+    return {
+      execute: async (ctx): Promise<ExecutableToolResult> => {
+        this.calls.push({
+          id: ctx.toolCallId,
+          args,
+          turnId: ctx.turnId,
+        });
+        return new Promise<ExecutableToolResult>(() => {
+          // never resolve, never reject
+        });
+      },
+    };
+  }
+}
+
+export type ProgressInput = Record<string, unknown>;
+
+export class ProgressTool implements ExecutableTool<ProgressInput> {
+  readonly name = 'progress';
+  readonly description = 'Streams a few progress updates before returning.';
+  readonly parameters = RECORD_PARAMETERS;
+  readonly calls: RecordedToolCall<ProgressInput>[] = [];
+  readonly updates: ToolUpdate[];
+
+  constructor(
+    updates: ToolUpdate[] = [
+      { kind: 'stdout', text: 'working...' },
+      { kind: 'progress', percent: 50 },
+    ],
+  ) {
+    this.updates = updates;
+  }
+
+  resolveExecution(args: ProgressInput): ToolExecution {
+    return {
+      execute: async (ctx): Promise<ExecutableToolResult> => {
+        this.calls.push({
+          id: ctx.toolCallId,
+          args,
+          turnId: ctx.turnId,
+        });
+        for (const update of this.updates) ctx.onUpdate?.(update);
+        return { output: 'done' };
+      },
+    };
+  }
+}
+
+export interface StrictInput {
+  value: number;
+}
+
+export class StrictArgsTool implements ExecutableTool<StrictInput> {
+  readonly name = 'strict';
+  readonly description = 'Requires { value: number }.';
+  readonly parameters = STRICT_PARAMETERS;
+  readonly calls: RecordedToolCall<StrictInput>[] = [];
+
+  resolveExecution(args: StrictInput): ToolExecution {
+    return {
+      execute: async (ctx): Promise<ExecutableToolResult> => {
+        this.calls.push({
+          id: ctx.toolCallId,
+          args,
+          turnId: ctx.turnId,
+        });
+        return { output: `value=${String(args.value)}` };
+      },
+    };
+  }
+}
+
+/**
+ * A tool whose result is a content-block array. Useful for exercising
+ * media-aware tool-result persistence in the loop.
+ */
+export class ContentBlocksTool implements ExecutableTool<Record<string, unknown>> {
+  readonly name = 'blocks';
+  readonly description = 'Returns a structured ExecutableToolResult.';
+  readonly parameters = RECORD_PARAMETERS;
+  readonly calls: RecordedToolCall<Record<string, unknown>>[] = [];
+  readonly result: ExecutableToolResult;
+
+  constructor(result: ExecutableToolResult) {
+    this.result = result;
+  }
+
+  resolveExecution(args: Record<string, unknown>): ToolExecution {
+    return {
+      execute: async (ctx): Promise<ExecutableToolResult> => {
+        this.calls.push({
+          id: ctx.toolCallId,
+          args,
+          turnId: ctx.turnId,
+        });
+        return this.result;
+      },
+    };
+  }
+}
+
+/**
+ * A tool that signals when its execute starts and resolves only after
+ * `release()` is called. Useful for orchestrating concurrent execution
+ * tests deterministically.
+ */
+export class GatedTool implements ExecutableTool<Record<string, unknown>> {
+  readonly name: string;
+  readonly description = 'Waits for an external release signal.';
+  readonly parameters = RECORD_PARAMETERS;
+  readonly calls: RecordedToolCall<Record<string, unknown>>[] = [];
+  readonly started: Promise<void>;
+
+  private resolveStarted: () => void = () => {};
+  private gate: Promise<void>;
+  private resolveGate: () => void = () => {};
+
+  constructor(name = 'gated') {
+    this.name = name;
+    this.started = new Promise<void>((resolve) => {
+      this.resolveStarted = resolve;
+    });
+    this.gate = new Promise<void>((resolve) => {
+      this.resolveGate = resolve;
+    });
+  }
+
+  release(): void {
+    this.resolveGate();
+  }
+
+  resolveExecution(args: Record<string, unknown>): ToolExecution {
+    return {
+      execute: async (ctx): Promise<ExecutableToolResult> => {
+        this.calls.push({
+          id: ctx.toolCallId,
+          args,
+          turnId: ctx.turnId,
+        });
+        this.resolveStarted();
+        await this.gate;
+        return { output: `${this.name} done` };
+      },
+    };
+  }
+}
diff --git a/packages/agent-core/test/loop/hooks.e2e.test.ts b/packages/agent-core/test/loop/hooks.e2e.test.ts
new file mode 100644
index 000000000..dd07e3a34
--- /dev/null
+++ b/packages/agent-core/test/loop/hooks.e2e.test.ts
@@ -0,0 +1,492 @@
+/**
+ * LoopHooks contract — every phase hook is observed and asserted by its
+ * publicly visible effect (events, transcript writes, TurnResult), not
+ * by inspecting the loop's call graph.
+ */
+
+import { inputTotal } from '@moonshot-ai/kosong';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { LoopHooks, ExecutableToolResult, ToolExecution } from '../../src/loop/index';
+import { PathSecurityError } from '../../src/tools/policies/path-access';
+import { makeEndTurnResponse, makeToolCall, makeToolUseResponse } from './fixtures/fake-llm';
+import { runTurn, runTurnExpectingThrow } from './fixtures/helpers';
+import { EchoTool, FailingTool, type EchoInput } from './fixtures/tools';
+
+function expectTextOutput(output: unknown): string {
+  expect(typeof output).toBe('string');
+  return output as string;
+}
+
+describe('runTurn — beforeStep hook', () => {
+  it('passes through when the hook returns undefined', async () => {
+    let calls = 0;
+    const hooks: LoopHooks = {
+      beforeStep: async () => {
+        calls += 1;
+      },
+    };
+    const { result } = await runTurn({
+      hooks,
+      responses: [makeEndTurnResponse('ok')],
+    });
+    expect(result.stopReason).toBe('end_turn');
+    expect(calls).toBe(1);
+  });
+
+  it('throws and prevents the LLM call when the hook blocks', async () => {
+    const hooks: LoopHooks = {
+      beforeStep: async () => ({ block: true, reason: 'policy says no' }),
+    };
+    const { error, llm, context, sink } = await runTurnExpectingThrow({
+      hooks,
+      responses: [makeEndTurnResponse('never')],
+    });
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toBe('policy says no');
+    expect(llm.callCount).toBe(0);
+    expect(context.stepBegins().length).toBe(0);
+    // turn.interrupted{reason:'error'} fires before the throw
+    const interrupted = sink.byType('turn.interrupted');
+    expect(interrupted[0]?.reason).toBe('error');
+  });
+
+  it('rethrows non-abort hook exceptions as loop errors', async () => {
+    const hooks: LoopHooks = {
+      beforeStep: async () => {
+        throw new Error('hook crashed');
+      },
+    };
+    const { error, llm } = await runTurnExpectingThrow({
+      hooks,
+      responses: [makeEndTurnResponse('never')],
+    });
+    expect((error as Error).message).toBe('hook crashed');
+    expect(llm.callCount).toBe(0);
+  });
+
+  it('receives turnId, stepNumber, signal, and LLM', async () => {
+    const ctxs: Array<{
+      turnId: string;
+      stepNumber: number;
+      signal: AbortSignal;
+      modelName: string;
+      chat: unknown;
+    }> = [];
+    const hooks: LoopHooks = {
+      beforeStep: async (ctx) => {
+        ctxs.push({
+          turnId: ctx.turnId,
+          stepNumber: ctx.stepNumber,
+          signal: ctx.signal,
+          modelName: ctx.llm.modelName,
+          chat: ctx.llm.chat,
+        });
+      },
+    };
+    await runTurn({
+      hooks,
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: '1' }, 'a')]),
+        makeEndTurnResponse('done'),
+      ],
+      tools: [new EchoTool()],
+      turnId: 'turn-foo',
+    });
+    expect(ctxs).toEqual([
+      {
+        turnId: 'turn-foo',
+        stepNumber: 1,
+        signal: expect.any(AbortSignal) as AbortSignal,
+        modelName: 'fake-model',
+        chat: expect.any(Function) as unknown,
+      },
+      {
+        turnId: 'turn-foo',
+        stepNumber: 2,
+        signal: expect.any(AbortSignal) as AbortSignal,
+        modelName: 'fake-model',
+        chat: expect.any(Function) as unknown,
+      },
+    ]);
+  });
+});
+
+describe('runTurn — afterStep hook', () => {
+  it('runs after step.end and observes the step result', async () => {
+    const captured: Array<{
+      stopReason: string;
+      stepNumber: number;
+      usageInput: number;
+      usageOutput: number;
+    }> = [];
+    const hooks: LoopHooks = {
+      afterStep: async (ctx) => {
+        captured.push({
+          stopReason: ctx.stopReason,
+          stepNumber: ctx.stepNumber,
+          usageInput: inputTotal(ctx.usage),
+          usageOutput: ctx.usage.output,
+        });
+      },
+    };
+    const { sink } = await runTurn({
+      hooks,
+      responses: [makeEndTurnResponse('ok', { inputOther: 1, output: 2 })],
+    });
+    expect(captured).toEqual([
+      {
+        stopReason: 'end_turn',
+        stepNumber: 1,
+        usageInput: 1,
+        usageOutput: 2,
+      },
+    ]);
+    // step.end has fired
+    expect(sink.count('step.end')).toBe(1);
+  });
+
+  it('errors thrown by afterStep are swallowed (turn still completes)', async () => {
+    const afterStep = vi.fn(async () => {
+      throw new Error('observer crashed');
+    });
+    const { result } = await runTurn({
+      hooks: { afterStep },
+      responses: [makeEndTurnResponse('ok')],
+    });
+    expect(result.stopReason).toBe('end_turn');
+    expect(afterStep).toHaveBeenCalled();
+  });
+});
+
+describe('runTurn — prepareToolExecution hook', () => {
+  it('block:true records an error result without invoking execute', async () => {
+    const echo = new EchoTool();
+    const hooks: LoopHooks = {
+      prepareToolExecution: async () => ({ block: true, reason: 'forbidden' }),
+    };
+    const { sink, context } = await runTurn({
+      hooks,
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'hi' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    expect(echo.calls.length).toBe(0);
+    const result = sink.byType('tool.result')[0];
+    expect(result?.result.isError).toBe(true);
+    expect(result?.result.output).toContain('forbidden');
+    expect(context.toolResults()[0]?.result.isError).toBe(true);
+  });
+
+  it('updatedArgs rewrites the args passed to execute', async () => {
+    const echo = new EchoTool();
+    const hooks: LoopHooks = {
+      prepareToolExecution: async () => ({ updatedArgs: { text: 'rewritten' } }),
+    };
+    const { sink, context } = await runTurn({
+      hooks,
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'original' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    expect(echo.calls.length).toBe(1);
+    expect(echo.calls[0]?.args).toEqual({ text: 'rewritten' });
+    expect(sink.byType('tool.call')[0]?.args).toEqual({ text: 'rewritten' });
+    expect(context.toolCalls()[0]?.args).toEqual({ text: 'rewritten' });
+  });
+
+  it('revalidates updatedArgs before execute', async () => {
+    const echo = new EchoTool();
+    const hooks: LoopHooks = {
+      prepareToolExecution: async () => ({ updatedArgs: { text: 123 } }),
+    };
+    const { sink, context } = await runTurn({
+      hooks,
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'original' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    expect(echo.calls.length).toBe(0);
+    expect(sink.byType('tool.result')[0]?.result.isError).toBe(true);
+    expect(sink.byType('tool.result')[0]?.result.output).toContain(
+      'after prepareToolExecution hook',
+    );
+    expect(context.toolResults()[0]?.result.isError).toBe(true);
+  });
+
+  it('hook throws non-abort -> records an error result, execute not called', async () => {
+    const echo = new EchoTool();
+    const hooks: LoopHooks = {
+      prepareToolExecution: async () => {
+        throw new Error('prepareToolExecution crashed');
+      },
+    };
+    const { sink, result } = await runTurn({
+      hooks,
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'hi' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    expect(echo.calls.length).toBe(0);
+    const tr = sink.byType('tool.result')[0];
+    expect(tr?.result.isError).toBe(true);
+    expect(expectTextOutput(tr?.result.output).toLowerCase()).toContain('preparetoolexecution');
+    // The turn still converges
+    expect(result.stopReason).toBe('end_turn');
+  });
+});
+
+class DescribedEchoTool extends EchoTool {
+  override resolveExecution(args: EchoInput) {
+    const execution = super.resolveExecution(args);
+    return { ...execution, description: `Echoing ${args.text}` };
+  }
+}
+
+class CrashingDescriptionEchoTool extends EchoTool {
+  override resolveExecution(_args: EchoInput): ToolExecution {
+    throw new Error('description crashed');
+  }
+}
+
+class PathSecurityEchoTool extends EchoTool {
+  override resolveExecution(_args: EchoInput): ToolExecution {
+    throw new PathSecurityError(
+      'PATH_OUTSIDE_WORKSPACE',
+      '../secret.txt',
+      '/secret.txt',
+      'path policy denied',
+    );
+  }
+}
+
+class ErrorExecutionEchoTool extends EchoTool {
+  override resolveExecution(_args: EchoInput): ToolExecution {
+    return { isError: true, output: 'resolved error' };
+  }
+}
+
+describe('runTurn — tool-call display fields', () => {
+  it('writes resolveExecution description onto appendToolCall after prepared args are known', async () => {
+    const echo = new DescribedEchoTool();
+    const hooks: LoopHooks = {
+      prepareToolExecution: async () => ({ updatedArgs: { text: 'rewritten' } }),
+    };
+    const { context } = await runTurn({
+      hooks,
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'hi' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    const tcRow = context.toolCalls()[0];
+    expect(tcRow?.description).toBe('Echoing rewritten');
+  });
+
+  it('resolveExecution failures record a tool error without running execute', async () => {
+    const echo = new CrashingDescriptionEchoTool();
+    const { context } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'hi' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    expect(echo.calls.length).toBe(0);
+    expect(context.toolResults()[0]?.result.isError).toBe(true);
+    expect(context.toolResults()[0]?.result.output).toContain('failed to resolve execution');
+  });
+
+  it('resolveExecution path security failures use the policy message directly', async () => {
+    const echo = new PathSecurityEchoTool();
+    const { context } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'hi' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    expect(echo.calls.length).toBe(0);
+    expect(context.toolResults()[0]?.result).toEqual({
+      isError: true,
+      output: 'path policy denied',
+    });
+  });
+
+  it('resolveExecution error result records a tool error without running execute', async () => {
+    const echo = new ErrorExecutionEchoTool();
+    const { context } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'hi' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    expect(echo.calls.length).toBe(0);
+    expect(context.toolResults()[0]?.result).toEqual({
+      isError: true,
+      output: 'resolved error',
+    });
+  });
+});
+
+describe('runTurn — finalizeToolResult hook', () => {
+  it('returned result replaces the tool result before persistence', async () => {
+    const echo = new EchoTool();
+    const override: ExecutableToolResult = { output: 'redacted' };
+    const hooks: LoopHooks = {
+      finalizeToolResult: async () => override,
+    };
+    const { context, sink } = await runTurn({
+      hooks,
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'secret' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    expect(echo.calls.length).toBe(1);
+    expect(context.toolResults()[0]?.result.output).toBe('redacted');
+    expect(sink.byType('tool.result')[0]?.result.output).toBe('redacted');
+  });
+
+  it('hook throw on success records an error result and never persists raw output', async () => {
+    const echo = new EchoTool();
+    const hooks: LoopHooks = {
+      finalizeToolResult: async () => {
+        throw new Error('finalizeToolResult crashed');
+      },
+    };
+    const { context, sink } = await runTurn({
+      hooks,
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'secret' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    const persisted = context.toolResults()[0]?.result;
+    expect(persisted?.isError).toBe(true);
+    // Output never leaks the original tool content
+    expect(persisted?.output).not.toContain('secret');
+    // Live event also marked as error
+    expect(sink.byType('tool.result')[0]?.result.isError).toBe(true);
+  });
+
+  it('execute failure passes the error result through finalizeToolResult', async () => {
+    const fail = new FailingTool('execute crashed');
+    let finalizeToolResultCalls = 0;
+    const hooks: LoopHooks = {
+      finalizeToolResult: async (ctx) => {
+        finalizeToolResultCalls += 1;
+        return ctx.result;
+      },
+    };
+    const { sink } = await runTurn({
+      hooks,
+      tools: [fail],
+      responses: [
+        makeToolUseResponse([makeToolCall('fail', {}, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    expect(finalizeToolResultCalls).toBe(1);
+    const tr = sink.byType('tool.result')[0];
+    expect(tr?.result.isError).toBe(true);
+  });
+
+  it('preflight errors pass through finalizeToolResult before persistence', async () => {
+    let finalizeToolResultCalls = 0;
+    const hooks: LoopHooks = {
+      finalizeToolResult: async (ctx) => {
+        finalizeToolResultCalls += 1;
+        const output = expectTextOutput(ctx.result.output);
+        return {
+          output: `finalized: ${output}`,
+          isError: ctx.result.isError,
+        };
+      },
+    };
+    const { sink, context } = await runTurn({
+      hooks,
+      tools: [],
+      responses: [
+        makeToolUseResponse([makeToolCall('ghost', { x: 1 }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    expect(finalizeToolResultCalls).toBe(1);
+    expect(context.toolResults()[0]?.result.output).toContain('finalized:');
+    expect(sink.byType('tool.result')[0]?.result.output).toContain('finalized:');
+  });
+});
+
+describe('runTurn — shouldContinueAfterStop hook', () => {
+  it('continue:false breaks the turn at end_turn (default behaviour)', async () => {
+    const shouldContinueAfterStop = vi.fn(async () => ({ continue: false }));
+    const { result } = await runTurn({
+      hooks: { shouldContinueAfterStop },
+      responses: [makeEndTurnResponse('ok')],
+    });
+    expect(result.stopReason).toBe('end_turn');
+    expect(shouldContinueAfterStop).toHaveBeenCalledTimes(1);
+  });
+
+  it('continue:true allows another step after a non-tool stopReason', async () => {
+    const shouldContinueAfterStop = vi
+      .fn()
+      .mockResolvedValueOnce({ continue: true })
+      .mockResolvedValueOnce({ continue: false });
+    const { result, llm } = await runTurn({
+      hooks: { shouldContinueAfterStop },
+      responses: [
+        makeEndTurnResponse('first', { inputOther: 1, output: 1 }),
+        makeEndTurnResponse('second', { inputOther: 2, output: 2 }),
+      ],
+    });
+    expect(llm.callCount).toBe(2);
+    expect(result.steps).toBe(2);
+    expect(result.stopReason).toBe('end_turn');
+  });
+
+  it('returning undefined breaks the turn (default)', async () => {
+    let calls = 0;
+    const hooks: LoopHooks = {
+      shouldContinueAfterStop: async () => {
+        calls += 1;
+      },
+    };
+    const { result } = await runTurn({
+      hooks,
+      responses: [makeEndTurnResponse('ok')],
+    });
+    expect(result.stopReason).toBe('end_turn');
+    expect(calls).toBe(1);
+  });
+
+  it('is NOT consulted between tool_use steps', async () => {
+    const shouldContinueAfterStop = vi.fn(async () => ({ continue: false }));
+    const echo = new EchoTool();
+    await runTurn({
+      hooks: { shouldContinueAfterStop },
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: '1' }, 'a')]),
+        makeToolUseResponse([makeToolCall('echo', { text: '2' }, 'b')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    // Hook is only consulted at the final non-tool step
+    expect(shouldContinueAfterStop).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/agent-core/test/loop/streaming.e2e.test.ts b/packages/agent-core/test/loop/streaming.e2e.test.ts
new file mode 100644
index 000000000..d2bea7267
--- /dev/null
+++ b/packages/agent-core/test/loop/streaming.e2e.test.ts
@@ -0,0 +1,200 @@
+/**
+ * Streaming callbacks — provider deltas are translated into LoopEvents
+ * and completed text / thinking parts are persisted via appendContentPart in order.
+ *
+ * The fixture (`FakeLLM`) cooperates by invoking the streaming callbacks
+ * during `chat()`, mirroring how a real provider adapter would. Tests
+ * here drive `runTurn` and assert against the observed events / WAL
+ * writes only.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import type { LLM, LLMChatParams, LLMChatResponse } from '../../src/loop/index';
+import { createLoopEventDispatcher, runTurn } from '../../src/loop/index';
+import { CollectingSink } from './fixtures/collecting-sink';
+import { makeEndTurnResponse, zeroUsage } from './fixtures/fake-llm';
+import { RecordingContext } from './fixtures/recording-context';
+
+/**
+ * A custom LLM that exposes onTextDelta / onThinkDelta / onToolCallDelta /
+ * onTextPart / onThinkPart so each test can decide what the provider emits.
+ */
+class StreamingLLM implements LLM {
+  readonly systemPrompt = 'streaming system prompt';
+  readonly modelName = 'streaming';
+
+  readonly responseProvider: (params: LLMChatParams) => Promise<LLMChatResponse>;
+
+  constructor(provider: (params: LLMChatParams) => Promise<LLMChatResponse>) {
+    this.responseProvider = provider;
+  }
+
+  async chat(params: LLMChatParams): Promise<LLMChatResponse> {
+    return this.responseProvider(params);
+  }
+}
+
+async function runWithLLM(llm: LLM): Promise<{
+  sink: CollectingSink;
+  context: RecordingContext;
+}> {
+  const sink = new CollectingSink();
+  const context = new RecordingContext();
+  await runTurn({
+    turnId: 'turn-1',
+    signal: new AbortController().signal,
+    llm,
+    buildMessages: context.buildMessages,
+    dispatchEvent: createLoopEventDispatcher({
+      appendTranscriptRecord: context.appendTranscriptRecord,
+      emitLiveEvent: sink.emit,
+    }),
+  });
+  return { sink, context };
+}
+
+describe('runTurn — streaming callbacks', () => {
+  it('routes onTextDelta into text.delta events', async () => {
+    const llm = new StreamingLLM(async (params) => {
+      params.onTextDelta?.('hel');
+      params.onTextDelta?.('lo');
+      return {
+        toolCalls: [],
+        providerFinishReason: 'completed',
+        usage: zeroUsage(),
+      };
+    });
+    const { sink } = await runWithLLM(llm);
+    const deltas = sink.byType('text.delta').map((e) => e.delta);
+    expect(deltas).toEqual(['hel', 'lo']);
+  });
+
+  it('routes onThinkDelta into thinking.delta events', async () => {
+    const llm = new StreamingLLM(async (params) => {
+      params.onThinkDelta?.('think...');
+      params.onThinkDelta?.('more');
+      return makeEndTurnResponse('done');
+    });
+    const { sink } = await runWithLLM(llm);
+    const thinks = sink.byType('thinking.delta').map((e) => e.delta);
+    expect(thinks).toEqual(['think...', 'more']);
+  });
+
+  it('routes onToolCallDelta into tool.call.delta events', async () => {
+    const llm = new StreamingLLM(async (params) => {
+      params.onToolCallDelta?.({
+        toolCallId: 'tc-1',
+        name: 'echo',
+        argumentsPart: '{"text":',
+      });
+      params.onToolCallDelta?.({
+        toolCallId: 'tc-1',
+        argumentsPart: '"hi"}',
+      });
+      return makeEndTurnResponse('done');
+    });
+    const { sink } = await runWithLLM(llm);
+    const deltas = sink.byType('tool.call.delta');
+    expect(deltas.length).toBe(2);
+    expect(deltas[0]?.toolCallId).toBe('tc-1');
+    expect(deltas[0]?.name).toBe('echo');
+    expect(deltas[0]?.argumentsPart).toBe('{"text":');
+    expect(deltas[1]?.argumentsPart).toBe('"hi"}');
+  });
+
+  it('routes onTextPart into appendContentPart{type:"text"}', async () => {
+    const llm = new StreamingLLM(async (params) => {
+      await params.onTextPart?.({
+        type: 'text',
+        text: 'first paragraph',
+      });
+      await params.onTextPart?.({
+        type: 'text',
+        text: 'second paragraph',
+      });
+      return makeEndTurnResponse('done');
+    });
+    const { context, sink } = await runWithLLM(llm);
+    const cps = context.contentParts();
+    expect(cps.length).toBe(2);
+    expect(cps[0]?.part).toEqual({ type: 'text', text: 'first paragraph' });
+    expect(cps[1]?.part).toEqual({ type: 'text', text: 'second paragraph' });
+    expect(sink.byType('content.part').map((e) => e.part)).toEqual([
+      { type: 'text', text: 'first paragraph' },
+      { type: 'text', text: 'second paragraph' },
+    ]);
+    // stepUuid is consistent across the part appends and the step envelope
+    const stepBeginUuid = context.stepBegins()[0]?.uuid;
+    expect(stepBeginUuid).toBeDefined();
+    expect(cps.every((c) => c.stepUuid === stepBeginUuid)).toBe(true);
+  });
+
+  it('routes onThinkPart into appendContentPart{type:"think"} preserving encrypted', async () => {
+    const llm = new StreamingLLM(async (params) => {
+      await params.onThinkPart?.({
+        type: 'think',
+        think: 'reasoning',
+        encrypted: 'sig-abc',
+      });
+      await params.onThinkPart?.({
+        type: 'think',
+        think: 'plain reasoning',
+      });
+      return makeEndTurnResponse('done');
+    });
+    const { context } = await runWithLLM(llm);
+    const cps = context.contentParts();
+    expect(cps.length).toBe(2);
+    expect(cps[0]?.part).toEqual({
+      type: 'think',
+      think: 'reasoning',
+      encrypted: 'sig-abc',
+    });
+    expect(cps[1]?.part).toEqual({ type: 'think', think: 'plain reasoning' });
+  });
+
+  it('preserves the order of mixed content parts as they fire', async () => {
+    const llm = new StreamingLLM(async (params) => {
+      await params.onThinkPart?.({
+        type: 'think',
+        think: 'first',
+      });
+      await params.onTextPart?.({
+        type: 'text',
+        text: 'middle',
+      });
+      await params.onThinkPart?.({
+        type: 'think',
+        think: 'last',
+      });
+      return makeEndTurnResponse('done');
+    });
+    const { context } = await runWithLLM(llm);
+    const kinds = context.contentParts().map((c) => c.part.type);
+    expect(kinds).toEqual(['think', 'text', 'think']);
+  });
+
+  it('all completed content parts are persisted before step.end fires', async () => {
+    // Use the chat() result's onTextPart to fan out two content parts,
+    // then assert step.end falls AFTER both appendContentPart calls in
+    // the recorded context call sequence.
+    const llm = new StreamingLLM(async (params) => {
+      await params.onTextPart?.({
+        type: 'text',
+        text: 'a',
+      });
+      await params.onTextPart?.({
+        type: 'text',
+        text: 'b',
+      });
+      return makeEndTurnResponse('a b');
+    });
+    const { context } = await runWithLLM(llm);
+    const seq = context.kinds();
+    const lastContent = seq.lastIndexOf('appendContentPart');
+    const stepEnd = seq.indexOf('appendStepEnd');
+    expect(lastContent).toBeGreaterThanOrEqual(0);
+    expect(stepEnd).toBeGreaterThan(lastContent);
+  });
+});
diff --git a/packages/agent-core/test/loop/tool-call.e2e.test.ts b/packages/agent-core/test/loop/tool-call.e2e.test.ts
new file mode 100644
index 000000000..2a21de3e1
--- /dev/null
+++ b/packages/agent-core/test/loop/tool-call.e2e.test.ts
@@ -0,0 +1,633 @@
+/**
+ * Tool-call invariants observed end-to-end.
+ *
+ * The loop promises that every provider tool_call produces exactly one
+ * matching tool.result event/record, even on
+ * the rejected/error paths (tool not found, schema rejected, LLM-marked args
+ * error, execute throws). It also runs non-conflicting tool tasks in parallel
+ * while dispatching terminal events in provider order.
+ */
+
+import type { ContentPart } from '@moonshot-ai/kosong';
+import { describe, expect, it } from 'vitest';
+
+import { ToolAccesses } from '../../src/loop';
+import type { Logger } from '../../src/logging';
+import type { ExecutableTool, ExecutableToolResult, LoopHooks, ToolExecution } from '../../src/loop';
+import { PathSecurityError } from '../../src/tools/policies/path-access';
+import {
+  makeEndTurnResponse,
+  makeResponse,
+  makeTextParts,
+  makeToolCall,
+  makeToolUseResponse,
+} from './fixtures/fake-llm';
+import { runTurn } from './fixtures/helpers';
+import {
+  ContentBlocksTool,
+  EchoTool,
+  FailingTool,
+  GatedTool,
+  markReadAnyFileAccesses,
+  ProgressTool,
+  StrictArgsTool,
+} from './fixtures/tools';
+
+function expectTextOutput(output: unknown): string {
+  expect(typeof output).toBe('string');
+  return output as string;
+}
+
+async function contentBlockOutput(output: ContentPart[]): Promise<ContentPart[]> {
+  const blocks = new ContentBlocksTool({ output });
+  const { context } = await runTurn({
+    tools: [blocks],
+    responses: [
+      makeToolUseResponse([makeToolCall('blocks', {}, 'tc-1')]),
+      makeEndTurnResponse('done'),
+    ],
+  });
+  const payload = context.toolResults()[0]?.result;
+  expect(Array.isArray(payload?.output)).toBe(true);
+  return payload?.output as ContentPart[];
+}
+
+function waitOneMacrotask(): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, 0);
+  });
+}
+
+function makeTestLogger(): {
+  readonly log: Logger;
+  readonly entries: Array<{ readonly level: string; readonly message: string; readonly payload: unknown }>;
+} {
+  const entries: Array<{ readonly level: string; readonly message: string; readonly payload: unknown }> = [];
+  const log: Logger = {
+    error: (message, payload) => entries.push({ level: 'error', message, payload }),
+    warn: (message, payload) => entries.push({ level: 'warn', message, payload }),
+    info: (message, payload) => entries.push({ level: 'info', message, payload }),
+    debug: (message, payload) => entries.push({ level: 'debug', message, payload }),
+    createChild: () => log,
+  };
+  return { log, entries };
+}
+
+describe('runTurn — tool-call behaviour', () => {
+  it('routes a successful tool call through execute and emits paired events', async () => {
+    const echo = new EchoTool();
+    const { sink, context } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'hi' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    expect(echo.calls.length).toBe(1);
+    expect(echo.calls[0]?.id).toBe('tc-1');
+    // tool.call and tool.result are paired
+    expect(sink.byType('tool.call').map((e) => e.toolCallId)).toEqual(['tc-1']);
+    expect(sink.byType('tool.result').map((e) => e.toolCallId)).toEqual(['tc-1']);
+    // appendToolResult was called with the tool's content as output
+    const trs = context.toolResults();
+    expect(trs.length).toBe(1);
+    expect(trs[0]?.toolCallId).toBe('tc-1');
+    expect(trs[0]?.result.output).toBe('hi');
+    expect(trs[0]?.result.isError).toBeUndefined();
+  });
+
+  it('passes toolCallId / turnId / args through to Tool.execute', async () => {
+    const echo = new EchoTool();
+    await runTurn({
+      tools: [echo],
+      turnId: 'turn-XYZ',
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'inputs' }, 'tc-99')]),
+        makeEndTurnResponse('ok'),
+      ],
+    });
+    expect(echo.calls[0]).toMatchObject({
+      id: 'tc-99',
+      turnId: 'turn-XYZ',
+      args: { text: 'inputs' },
+    });
+  });
+
+  it('records an error tool.result when the tool name is unknown', async () => {
+    const { sink, context } = await runTurn({
+      tools: [], // no tools at all
+      responses: [
+        makeToolUseResponse([makeToolCall('ghost', { x: 1 }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    expect(sink.byType('tool.call').length).toBe(1);
+    const results = sink.byType('tool.result');
+    expect(results.length).toBe(1);
+    expect(results[0]?.result.isError).toBe(true);
+    expect(expectTextOutput(results[0]?.result.output).toLowerCase()).toContain('not found');
+    // Rejected path also writes the tool.call and tool.result records
+    const tcRow = context.toolCalls();
+    const trRow = context.toolResults();
+    expect(tcRow.length).toBe(1);
+    expect(trRow.length).toBe(1);
+    expect(trRow[0]?.result.isError).toBe(true);
+  });
+
+  it('records an error tool.result when args fail tool parameter validation', async () => {
+    const strict = new StrictArgsTool();
+    const { sink } = await runTurn({
+      tools: [strict],
+      responses: [
+        makeToolUseResponse([makeToolCall('strict', { value: 'NOT_A_NUMBER' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    expect(strict.calls.length).toBe(0); // execute was NOT called
+    const results = sink.byType('tool.result');
+    expect(results.length).toBe(1);
+    expect(results[0]?.result.isError).toBe(true);
+    expect(expectTextOutput(results[0]?.result.output).toLowerCase()).toContain('invalid args');
+  });
+
+  it('records an error tool.result when LLM-side args parsing already failed', async () => {
+    const echo = new EchoTool();
+    const { sink } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([
+          {
+            type: 'function',
+            id: 'tc-1',
+            function: {
+              name: 'echo',
+              arguments: '{',
+            },
+          },
+        ]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    expect(echo.calls.length).toBe(0);
+    const results = sink.byType('tool.result');
+    expect(results.length).toBe(1);
+    expect(results[0]?.result.isError).toBe(true);
+    expect(results[0]?.result.output).toContain('malformed JSON in arguments');
+  });
+
+  it('captures tool execution failures as error results', async () => {
+    const fail = new FailingTool('boom');
+    const { sink, context } = await runTurn({
+      tools: [fail],
+      responses: [
+        makeToolUseResponse([makeToolCall('fail', {}, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    expect(fail.calls.length).toBe(1);
+    const results = sink.byType('tool.result');
+    expect(results[0]?.result.isError).toBe(true);
+    expect(expectTextOutput(results[0]?.result.output).toLowerCase()).toContain('boom');
+    expect(context.toolResults()[0]?.result.isError).toBe(true);
+  });
+
+  it('logs thrown tool execution failures for diagnostics', async () => {
+    const fail = new FailingTool('boom');
+    const { log, entries } = makeTestLogger();
+    await runTurn({
+      tools: [fail],
+      log,
+      responses: [
+        makeToolUseResponse([makeToolCall('fail', {}, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    expect(entries).toContainEqual(
+      expect.objectContaining({
+        level: 'warn',
+        message: 'tool execution failed',
+        payload: expect.objectContaining({
+          toolName: 'fail',
+          toolCallId: 'tc-1',
+          error: expect.any(Error),
+        }),
+      }),
+    );
+  });
+
+  it('does not duplicate prepare hook failures in the diagnostic log', async () => {
+    const echo = new EchoTool();
+    const { log, entries } = makeTestLogger();
+    await runTurn({
+      tools: [echo],
+      log,
+      hooks: {
+        prepareToolExecution: async () => {
+          throw new Error('hook exploded');
+        },
+      },
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'hi' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    expect(entries).not.toContainEqual(
+      expect.objectContaining({ message: 'prepareToolExecution hook failed' }),
+    );
+  });
+
+  it('does not log path security setup failures already covered by tool.result', async () => {
+    const tool = new PathSecurityTool();
+    const { log, entries } = makeTestLogger();
+    const { sink } = await runTurn({
+      tools: [tool],
+      log,
+      responses: [
+        makeToolUseResponse([makeToolCall('path-secure', {}, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    expect(sink.byType('tool.result')[0]?.result.isError).toBe(true);
+    expect(entries).not.toContainEqual(
+      expect.objectContaining({ message: 'tool execution setup failed' }),
+    );
+  });
+
+  it('forwards onUpdate calls as tool.progress events', async () => {
+    const progress = new ProgressTool([
+      { kind: 'stdout', text: 'a' },
+      { kind: 'progress', percent: 25 },
+      { kind: 'progress', percent: 75 },
+    ]);
+    const { sink } = await runTurn({
+      tools: [progress],
+      responses: [
+        makeToolUseResponse([makeToolCall('progress', {}, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    const progressEvents = sink.byType('tool.progress');
+    expect(progressEvents.length).toBe(3);
+    expect(progressEvents.every((e) => e.toolCallId === 'tc-1')).toBe(true);
+    expect(progressEvents.map((e) => e.update.kind)).toEqual(['stdout', 'progress', 'progress']);
+  });
+
+  it('runs multiple tool calls in the same step (transcripts in provider order)', async () => {
+    const echo = new EchoTool();
+    const { sink, context } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([
+          makeToolCall('echo', { text: 'a' }, 'tc-1'),
+          makeToolCall('echo', { text: 'b' }, 'tc-2'),
+          makeToolCall('echo', { text: 'c' }, 'tc-3'),
+        ]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    expect(echo.calls.map((c) => c.id)).toEqual(['tc-1', 'tc-2', 'tc-3']);
+    // tool.result is dispatched in provider order regardless of
+    // execute completion order
+    expect(context.toolResults().map((r) => r.toolCallId)).toEqual(['tc-1', 'tc-2', 'tc-3']);
+    expect(sink.byType('tool.call').map((e) => e.toolCallId)).toEqual(['tc-1', 'tc-2', 'tc-3']);
+  });
+
+  it('executes non-conflicting tool tasks concurrently (causal order, not wall-clock)', async () => {
+    // Two GatedTools start, each blocks until released. If the loop executed
+    // them serially we could not have both `started` promises resolve
+    // before releasing either.
+    const a = markReadAnyFileAccesses(new GatedTool('gated-a'));
+    const b = markReadAnyFileAccesses(new GatedTool('gated-b'));
+
+    const turnPromise = runTurn({
+      tools: [a, b],
+      responses: [
+        makeToolUseResponse([
+          makeToolCall('gated-a', {}, 'tc-a'),
+          makeToolCall('gated-b', {}, 'tc-b'),
+        ]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    // Both tools must enter plan execution before either releases.
+    await Promise.all([a.started, b.started]);
+    // Release in reverse provider order.
+    b.release();
+    a.release();
+
+    const { context, sink } = await turnPromise;
+    // Despite execute completing in reverse order, tool.result records
+    // are written in provider order.
+    expect(context.toolResults().map((r) => r.toolCallId)).toEqual(['tc-a', 'tc-b']);
+    // Each tool emitted its tool.call and tool.result.
+    expect(
+      sink
+        .byType('tool.call')
+        .map((e) => e.toolCallId)
+        .toSorted(),
+    ).toEqual(['tc-a', 'tc-b'].toSorted());
+    expect(
+      sink
+        .byType('tool.result')
+        .map((e) => e.toolCallId)
+        .toSorted(),
+    ).toEqual(['tc-a', 'tc-b'].toSorted());
+  });
+
+  it('serializes tool tasks with default accesses', async () => {
+    const a = new GatedTool('gated-a');
+    const b = new GatedTool('gated-b');
+
+    const turnPromise = runTurn({
+      tools: [a, b],
+      responses: [
+        makeToolUseResponse([
+          makeToolCall('gated-a', {}, 'tc-a'),
+          makeToolCall('gated-b', {}, 'tc-b'),
+        ]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    await a.started;
+    await expect(
+      Promise.race([b.started.then(() => true), waitOneMacrotask().then(() => false)]),
+    ).resolves.toBe(false);
+
+    a.release();
+    await b.started;
+    b.release();
+
+    const { context } = await turnPromise;
+    expect(context.toolResults().map((r) => r.toolCallId)).toEqual(['tc-a', 'tc-b']);
+  });
+
+  it('computes resource accesses after prepareToolExecution updates args', async () => {
+    const tool = new PathLockedGatedTool();
+    const hooks: LoopHooks = {
+      prepareToolExecution: async ({ toolCall }) =>
+        toolCall.id === 'tc-b' ? { updatedArgs: { path: '/repo/a.ts' } } : undefined,
+    };
+
+    const turnPromise = runTurn({
+      tools: [tool],
+      hooks,
+      responses: [
+        makeToolUseResponse([
+          makeToolCall('path-gated', { path: '/repo/a.ts' }, 'tc-a'),
+          makeToolCall('path-gated', { path: '/repo/b.ts' }, 'tc-b'),
+        ]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    await tool.waitForStartedCount(1);
+    await waitOneMacrotask();
+    expect(tool.startedIds).toEqual(['tc-a']);
+
+    tool.release('tc-a');
+    await tool.waitForStartedCount(2);
+    expect(tool.startedIds).toEqual(['tc-a', 'tc-b']);
+
+    tool.release('tc-b');
+    const { context } = await turnPromise;
+    expect(context.toolResults().map((r) => r.toolCallId)).toEqual(['tc-a', 'tc-b']);
+    expect(tool.calls.map((call) => call.args.path)).toEqual(['/repo/a.ts', '/repo/a.ts']);
+  });
+
+  it('starts later independent tool tasks behind an earlier queued conflict', async () => {
+    const tool = new PathLockedGatedTool();
+
+    const turnPromise = runTurn({
+      tools: [tool],
+      responses: [
+        makeToolUseResponse([
+          makeToolCall('path-gated', { path: '/repo/a.ts' }, 'tc-a-1'),
+          makeToolCall('path-gated', { path: '/repo/a.ts' }, 'tc-a-2'),
+          makeToolCall('path-gated', { path: '/repo/b.ts' }, 'tc-b'),
+        ]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    await tool.waitForStartedCount(2);
+    await waitOneMacrotask();
+    expect(tool.startedIds).toEqual(['tc-a-1', 'tc-b']);
+
+    tool.release('tc-b');
+    await waitOneMacrotask();
+    expect(tool.startedIds).toEqual(['tc-a-1', 'tc-b']);
+
+    tool.release('tc-a-1');
+    await tool.waitForStartedCount(3);
+    expect(tool.startedIds).toEqual(['tc-a-1', 'tc-b', 'tc-a-2']);
+
+    tool.release('tc-a-2');
+    const { context } = await turnPromise;
+    expect(context.toolResults().map((r) => r.toolCallId)).toEqual(['tc-a-1', 'tc-a-2', 'tc-b']);
+  });
+
+  it('preserves structured ExecutableToolResult output on transcript and live result event', async () => {
+    const blocks = new ContentBlocksTool({
+      output: [
+        { type: 'text', text: 'see image:' },
+        {
+          type: 'image_url',
+          imageUrl: { url: 'data:image/png;base64,AAAA' },
+        },
+      ],
+    });
+    const { context, sink } = await runTurn({
+      tools: [blocks],
+      responses: [
+        makeToolUseResponse([makeToolCall('blocks', {}, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    const payload = context.toolResults()[0]?.result;
+    expect(payload).toBeDefined();
+    // Media-bearing results are kept as a content-part array, not collapsed.
+    expect(Array.isArray(payload?.output)).toBe(true);
+    if (Array.isArray(payload?.output)) {
+      const types = payload.output.map((p) => (p as { type: string }).type);
+      expect(types).toContain('text');
+      expect(types).toContain('image_url');
+    }
+    const eventOutput = sink.byType('tool.result')[0]?.result.output;
+    expect(Array.isArray(eventOutput)).toBe(true);
+  });
+
+  it('preserves media-only image output with a text companion', async () => {
+    const image: ContentPart = {
+      type: 'image_url',
+      imageUrl: { url: 'https://example.com/image.jpg' },
+    };
+
+    const output = await contentBlockOutput([image]);
+
+    expect(output[0]).toMatchObject({
+      type: 'text',
+      text: 'Tool returned non-text content.',
+    });
+    expect(output.some((part) => part.type === 'image_url')).toBe(true);
+  });
+
+  it('preserves a list of only image ContentParts', async () => {
+    const img1: ContentPart = {
+      type: 'image_url',
+      imageUrl: { url: 'data:image/png;base64,abc' },
+    };
+    const img2: ContentPart = {
+      type: 'image_url',
+      imageUrl: { url: 'data:image/png;base64,def' },
+    };
+
+    const output = await contentBlockOutput([img1, img2]);
+
+    expect(output.filter((part) => part.type === 'image_url').length).toBe(2);
+  });
+
+  it('preserves an audio-only output', async () => {
+    const audio: ContentPart = {
+      type: 'audio_url',
+      audioUrl: { url: 'data:audio/mp3;base64,abc' },
+    };
+
+    const output = await contentBlockOutput([audio]);
+
+    expect(output.some((part) => part.type === 'audio_url')).toBe(true);
+  });
+
+  it('preserves an image when the tool emits a single image and no text channel exists', async () => {
+    const image: ContentPart = {
+      type: 'image_url',
+      imageUrl: { url: 'https://example.com/img.jpg' },
+    };
+
+    const output = await contentBlockOutput([image]);
+
+    expect(output.find((part) => part.type === 'image_url')).toBeDefined();
+  });
+
+  it('every tool.call event has a matching tool.result event (mixed batch)', async () => {
+    const echo = new EchoTool();
+    const fail = new FailingTool();
+    const strict = new StrictArgsTool();
+    const { sink } = await runTurn({
+      tools: [echo, fail, strict],
+      responses: [
+        makeResponse(
+          makeTextParts(''),
+          [
+            makeToolCall('echo', { text: 'ok' }, 'tc-good'),
+            makeToolCall('fail', {}, 'tc-fail'),
+            makeToolCall('strict', { value: 'oops' }, 'tc-bad-args'),
+            makeToolCall('ghost', {}, 'tc-missing'),
+          ],
+          'tool_use',
+        ),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    const callIds = sink
+      .byType('tool.call')
+      .map((e) => e.toolCallId)
+      .toSorted();
+    const resultIds = sink
+      .byType('tool.result')
+      .map((e) => e.toolCallId)
+      .toSorted();
+    expect(callIds).toEqual(['tc-bad-args', 'tc-fail', 'tc-good', 'tc-missing']);
+    expect(resultIds).toEqual(callIds);
+  });
+});
+
+interface PathLockedInput {
+  readonly path: string;
+}
+
+class PathLockedGatedTool implements ExecutableTool<PathLockedInput> {
+  readonly name = 'path-gated';
+  readonly description = 'Waits behind a path-scoped write lock.';
+  readonly parameters: Record<string, unknown> = {
+    type: 'object',
+    properties: { path: { type: 'string' } },
+    required: ['path'],
+    additionalProperties: false,
+  };
+  readonly calls: Array<{ readonly id: string; readonly args: PathLockedInput }> = [];
+  readonly startedIds: string[] = [];
+
+  private readonly gateResolvers = new Map<string, () => void>();
+  private readonly startedWaiters: Array<{ readonly count: number; readonly resolve: () => void }> =
+    [];
+
+  resolveExecution(input: PathLockedInput): ToolExecution {
+    return {
+      accesses: ToolAccesses.writeFile(input.path),
+      execute: async (ctx): Promise<ExecutableToolResult> => {
+        this.calls.push({
+          id: ctx.toolCallId,
+          args: input,
+        });
+        this.startedIds.push(ctx.toolCallId);
+        this.resolveStartedWaiters();
+
+        await new Promise<void>((resolve) => {
+          this.gateResolvers.set(ctx.toolCallId, resolve);
+        });
+        return { output: `${input.path} done` };
+      },
+    };
+  }
+
+  release(toolCallId: string): void {
+    this.gateResolvers.get(toolCallId)?.();
+  }
+
+  waitForStartedCount(count: number): Promise<void> {
+    if (this.startedIds.length >= count) return Promise.resolve();
+    return new Promise((resolve) => {
+      this.startedWaiters.push({ count, resolve });
+    });
+  }
+
+  private resolveStartedWaiters(): void {
+    for (let i = this.startedWaiters.length - 1; i >= 0; i--) {
+      const waiter = this.startedWaiters[i];
+      if (waiter !== undefined && this.startedIds.length >= waiter.count) {
+        this.startedWaiters.splice(i, 1);
+        waiter.resolve();
+      }
+    }
+  }
+}
+
+class PathSecurityTool implements ExecutableTool<Record<string, unknown>> {
+  readonly name = 'path-secure';
+  readonly description = 'Fails path checks during setup.';
+  readonly parameters: Record<string, unknown> = {
+    type: 'object',
+    additionalProperties: true,
+  };
+
+  resolveExecution(): ToolExecution {
+    throw new PathSecurityError(
+      'PATH_OUTSIDE_WORKSPACE',
+      '../secret',
+      '/secret',
+      'Path is outside workspace.',
+    );
+  }
+}
diff --git a/packages/agent-core/test/loop/tool-scheduler.test.ts b/packages/agent-core/test/loop/tool-scheduler.test.ts
new file mode 100644
index 000000000..af66da0c8
--- /dev/null
+++ b/packages/agent-core/test/loop/tool-scheduler.test.ts
@@ -0,0 +1,328 @@
+import { describe, expect, it } from 'vitest';
+
+import { ToolAccesses } from '../../src/loop';
+import { ToolScheduler, type ToolCallTask } from '../../src/loop/tool-scheduler';
+
+describe('ToolScheduler', () => {
+  it('starts read accesses on the same path concurrently', async () => {
+    const started: string[] = [];
+    const drained: string[] = [];
+    const scheduler = makeScheduler(drained);
+    const first = makeControlledTask('first', readPath('/repo/a.ts'), started);
+    const second = makeControlledTask('second', readPath('/repo/a.ts'), started);
+
+    scheduler.add(first.task);
+    scheduler.add(second.task);
+
+    expect(started).toEqual(['first', 'second']);
+    second.resolve();
+    first.resolve();
+    await scheduler.collectResults();
+    expect(drained).toEqual(['first', 'second']);
+  });
+
+  it('waits when read and write accesses intersect', async () => {
+    const started: string[] = [];
+    const drained: string[] = [];
+    const scheduler = makeScheduler(drained);
+    const writer = makeControlledTask('writer', writePath('/repo/a.ts'), started);
+    const reader = makeControlledTask('reader', readPath('/repo/a.ts'), started);
+
+    scheduler.add(writer.task);
+    scheduler.add(reader.task);
+    await waitOneMacrotask();
+
+    expect(started).toEqual(['writer']);
+    writer.resolve();
+    await waitOneMacrotask();
+    expect(started).toEqual(['writer', 'reader']);
+
+    reader.resolve();
+    await scheduler.collectResults();
+    expect(drained).toEqual(['writer', 'reader']);
+  });
+
+  it('serializes write accesses on the same path', async () => {
+    const started: string[] = [];
+    const drained: string[] = [];
+    const scheduler = makeScheduler(drained);
+    const firstWriter = makeControlledTask('first-writer', writePath('/repo/a.ts'), started);
+    const secondWriter = makeControlledTask('second-writer', writePath('/repo/a.ts'), started);
+
+    scheduler.add(firstWriter.task);
+    scheduler.add(secondWriter.task);
+    await waitOneMacrotask();
+
+    expect(started).toEqual(['first-writer']);
+    firstWriter.resolve();
+    await waitOneMacrotask();
+    expect(started).toEqual(['first-writer', 'second-writer']);
+
+    secondWriter.resolve();
+    await scheduler.collectResults();
+    expect(drained).toEqual(['first-writer', 'second-writer']);
+  });
+
+  it('serializes path accesses that differ only by case', async () => {
+    const started: string[] = [];
+    const drained: string[] = [];
+    const scheduler = makeScheduler(drained);
+    const writer = makeControlledTask('writer', writePath('C:\\Repo\\a.ts'), started);
+    const reader = makeControlledTask('reader', readPath('c:/repo/A.ts'), started);
+
+    scheduler.add(writer.task);
+    scheduler.add(reader.task);
+    await waitOneMacrotask();
+
+    expect(started).toEqual(['writer']);
+    writer.resolve();
+    await waitOneMacrotask();
+    expect(started).toEqual(['writer', 'reader']);
+
+    reader.resolve();
+    await scheduler.collectResults();
+    expect(drained).toEqual(['writer', 'reader']);
+  });
+
+  it('does not block non-intersecting path accesses', async () => {
+    const started: string[] = [];
+    const drained: string[] = [];
+    const scheduler = makeScheduler(drained);
+    const writer = makeControlledTask('writer', writePath('/repo/a.ts'), started);
+    const reader = makeControlledTask('reader', readPath('/repo/b.ts'), started);
+
+    scheduler.add(writer.task);
+    scheduler.add(reader.task);
+
+    expect(started).toEqual(['writer', 'reader']);
+    reader.resolve();
+    writer.resolve();
+    await scheduler.collectResults();
+    expect(drained).toEqual(['writer', 'reader']);
+  });
+
+  it('treats recursive path accesses as covering descendants', async () => {
+    const started: string[] = [];
+    const drained: string[] = [];
+    const scheduler = makeScheduler(drained);
+    const treeReader = makeControlledTask('tree-reader', readTree('/repo/src'), started);
+    const childWriter = makeControlledTask('child-writer', writePath('/repo/src/a.ts'), started);
+
+    scheduler.add(treeReader.task);
+    scheduler.add(childWriter.task);
+    await waitOneMacrotask();
+
+    expect(started).toEqual(['tree-reader']);
+    treeReader.resolve();
+    await waitOneMacrotask();
+    expect(started).toEqual(['tree-reader', 'child-writer']);
+
+    childWriter.resolve();
+    await scheduler.collectResults();
+    expect(drained).toEqual(['tree-reader', 'child-writer']);
+  });
+
+  it('treats pathless file access as covering the file namespace', async () => {
+    const started: string[] = [];
+    const drained: string[] = [];
+    const scheduler = makeScheduler(drained);
+    const writer = makeControlledTask('writer', ToolAccesses.writeAnyFile(), started);
+    const reader = makeControlledTask('reader', readPath('/repo/a.ts'), started);
+
+    scheduler.add(writer.task);
+    scheduler.add(reader.task);
+    await waitOneMacrotask();
+
+    expect(started).toEqual(['writer']);
+    writer.resolve();
+    await waitOneMacrotask();
+    expect(started).toEqual(['writer', 'reader']);
+
+    reader.resolve();
+    await scheduler.collectResults();
+    expect(drained).toEqual(['writer', 'reader']);
+  });
+
+  it('releases conflicting accesses when a task result rejects', async () => {
+    const started: string[] = [];
+    const drained: string[] = [];
+    const scheduler = makeScheduler(drained);
+    const writer = makeControlledTask('writer', writePath('/repo/a.ts'), started);
+    const reader = makeControlledTask('reader', readPath('/repo/a.ts'), started);
+
+    scheduler.add(writer.task);
+    scheduler.add(reader.task);
+    await waitOneMacrotask();
+
+    expect(started).toEqual(['writer']);
+    writer.reject(new Error('boom'));
+    await waitOneMacrotask();
+    expect(started).toEqual(['writer', 'reader']);
+
+    reader.resolve();
+    await scheduler.allSettled();
+  });
+
+  it('starts later independent accesses while an earlier task is queued', async () => {
+    const started: string[] = [];
+    const drained: string[] = [];
+    const scheduler = makeScheduler(drained);
+    const firstWriter = makeControlledTask('first-writer', writePath('/repo/a.ts'), started);
+    const secondWriter = makeControlledTask('second-writer', writePath('/repo/a.ts'), started);
+    const reader = makeControlledTask('reader', readPath('/repo/b.ts'), started);
+
+    scheduler.add(firstWriter.task);
+    scheduler.add(secondWriter.task);
+    scheduler.add(reader.task);
+    await waitOneMacrotask();
+
+    expect(started).toEqual(['first-writer', 'reader']);
+
+    reader.resolve();
+    firstWriter.resolve();
+    await waitOneMacrotask();
+    expect(started).toEqual(['first-writer', 'reader', 'second-writer']);
+
+    secondWriter.resolve();
+    await scheduler.collectResults();
+    expect(drained).toEqual(['first-writer', 'second-writer', 'reader']);
+  });
+
+  it('does not start later tasks that conflict with queued accesses', async () => {
+    const started: string[] = [];
+    const drained: string[] = [];
+    const scheduler = makeScheduler(drained);
+    const writer = makeControlledTask('writer', writePath('/repo/a.ts'), started);
+    const exclusive = makeControlledTask('exclusive', ToolAccesses.all(), started);
+    const reader = makeControlledTask('reader', readPath('/repo/b.ts'), started);
+
+    scheduler.add(writer.task);
+    scheduler.add(exclusive.task);
+    scheduler.add(reader.task);
+    await waitOneMacrotask();
+
+    expect(started).toEqual(['writer']);
+
+    writer.resolve();
+    await waitOneMacrotask();
+    expect(started).toEqual(['writer', 'exclusive']);
+
+    exclusive.resolve();
+    await waitOneMacrotask();
+    expect(started).toEqual(['writer', 'exclusive', 'reader']);
+
+    reader.resolve();
+    await scheduler.collectResults();
+    expect(drained).toEqual(['writer', 'exclusive', 'reader']);
+  });
+
+  it('serializes all-resource access against read-any-file access', async () => {
+    const started: string[] = [];
+    const drained: string[] = [];
+    const scheduler = makeScheduler(drained);
+    const reader = makeControlledTask('reader', ToolAccesses.readAnyFile(), started);
+    const exclusive = makeControlledTask('exclusive', ToolAccesses.all(), started);
+
+    scheduler.add(reader.task);
+    scheduler.add(exclusive.task);
+    await waitOneMacrotask();
+
+    expect(started).toEqual(['reader']);
+    reader.resolve();
+    await waitOneMacrotask();
+    expect(started).toEqual(['reader', 'exclusive']);
+
+    exclusive.resolve();
+    await scheduler.collectResults();
+    expect(drained).toEqual(['reader', 'exclusive']);
+  });
+
+  it('dispatches submitted results in provider order', async () => {
+    const started: string[] = [];
+    const drained: string[] = [];
+    const scheduler = makeScheduler(drained);
+    const first = makeControlledTask('first', ToolAccesses.none(), started);
+    const second = makeControlledTask('second', ToolAccesses.none(), started);
+
+    scheduler.add(first.task);
+    scheduler.add(second.task);
+    second.resolve();
+    first.resolve();
+    await scheduler.collectResults();
+
+    expect(drained).toEqual(['first', 'second']);
+  });
+});
+
+interface ControlledTask {
+  readonly task: ToolCallTask<string>;
+  readonly resolve: () => void;
+  readonly reject: (error: unknown) => void;
+}
+
+function makeScheduler(drained: string[]): {
+  readonly add: (task: ToolCallTask<string>) => void;
+  readonly collectResults: () => Promise<void>;
+  readonly allSettled: () => Promise<void>;
+} {
+  const scheduler = new ToolScheduler<string>();
+  const results: Array<Promise<string>> = [];
+  return {
+    add: (task) => {
+      results.push(scheduler.add(task));
+    },
+    collectResults: async () => {
+      for (const task of results) {
+        drained.push(await task);
+      }
+    },
+    allSettled: async () => {
+      await Promise.allSettled(results);
+    },
+  };
+}
+
+function makeControlledTask(
+  name: string,
+  accesses: ToolAccesses,
+  startedNames: string[],
+): ControlledTask {
+  let resolveResult: (value: string) => void = () => {};
+  let rejectResult: (error: unknown) => void = () => {};
+  const result = new Promise<string>((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  });
+
+  return {
+    task: {
+      accesses,
+      start: async () => {
+        startedNames.push(name);
+        return { result };
+      },
+    },
+    resolve: () => {
+      resolveResult(name);
+    },
+    reject: (error) => {
+      rejectResult(error);
+    },
+  };
+}
+
+function readPath(path: string): ToolAccesses {
+  return ToolAccesses.readFile(path);
+}
+
+function readTree(path: string): ToolAccesses {
+  return ToolAccesses.readTree(path);
+}
+
+function writePath(path: string): ToolAccesses {
+  return ToolAccesses.writeFile(path);
+}
+
+async function waitOneMacrotask(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
diff --git a/packages/agent-core/test/loop/transcript.e2e.test.ts b/packages/agent-core/test/loop/transcript.e2e.test.ts
new file mode 100644
index 000000000..74e18fc05
--- /dev/null
+++ b/packages/agent-core/test/loop/transcript.e2e.test.ts
@@ -0,0 +1,221 @@
+/**
+ * Transcript append (WAL) invariants.
+ *
+ * The loop writes a step envelope and tool-call records in a deterministic
+ * order. We assert the ordering with adjacency / before-after pairs
+ * rather than full-sequence snapshots so future internal refactors that
+ * insert harmless writes do not falsely trip the suite.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  makeEndTurnResponse,
+  makeResponse,
+  makeTextParts,
+  makeToolCall,
+  makeToolUseResponse,
+} from './fixtures/fake-llm';
+import { runTurn } from './fixtures/helpers';
+import { EchoTool, SlowTool } from './fixtures/tools';
+
+describe('runTurn — transcript writes', () => {
+  it('opens and closes one step envelope per step', async () => {
+    const echo = new EchoTool();
+    const { context } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'a' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    expect(context.stepBegins().length).toBe(2);
+    expect(context.stepEnds().length).toBe(2);
+    expect(context.stepBegins().map((s) => s.step)).toEqual([1, 2]);
+    expect(context.stepEnds().map((s) => s.step)).toEqual([1, 2]);
+  });
+
+  it('uses a consistent stepUuid across begin/end and child records of the same step', async () => {
+    const echo = new EchoTool();
+    const { context } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'a' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    const begins = context.stepBegins();
+    const ends = context.stepEnds();
+    const tcRows = context.toolCalls();
+    expect(begins[0]?.uuid).toBe(ends[0]?.uuid);
+    expect(begins[1]?.uuid).toBe(ends[1]?.uuid);
+    // tool.call record was written under step 1's uuid
+    expect(tcRows[0]?.stepUuid).toBe(begins[0]?.uuid);
+    // turnId propagates onto every record
+    const turnIds = new Set([
+      ...begins.map((b) => b.turnId),
+      ...ends.map((e) => e.turnId),
+      ...tcRows.map((t) => t.turnId),
+    ]);
+    expect(turnIds.size).toBe(1);
+    expect([...turnIds][0]).toBe('turn-1');
+  });
+
+  it('links tool.result records back to their tool.call via parentUuid', async () => {
+    const echo = new EchoTool();
+    const { context } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([
+          makeToolCall('echo', { text: 'a' }, 'tc-A'),
+          makeToolCall('echo', { text: 'b' }, 'tc-B'),
+        ]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    const tcRows = context.toolCalls();
+    const trRows = context.toolResults();
+    expect(tcRows.length).toBe(2);
+    expect(trRows.length).toBe(2);
+    // parentUuid of tool.result A == uuid of tool.call A
+    const tcByCallId = new Map(tcRows.map((r) => [r.toolCallId, r.uuid]));
+    expect(trRows[0]?.parentUuid).toBe(tcByCallId.get('tc-A'));
+    expect(trRows[1]?.parentUuid).toBe(tcByCallId.get('tc-B'));
+  });
+
+  it('appendStepEnd carries TokenUsage including cache fields', async () => {
+    const { context } = await runTurn({
+      responses: [
+        makeEndTurnResponse('ok', {
+          inputOther: 4,
+          output: 22,
+          inputCacheRead: 3,
+          inputCacheCreation: 4,
+        }),
+      ],
+    });
+    const end = context.stepEnds()[0];
+    expect(end?.usage).toEqual({
+      inputOther: 4,
+      output: 22,
+      inputCacheRead: 3,
+      inputCacheCreation: 4,
+    });
+    expect(end?.finishReason).toBe('end_turn');
+  });
+
+  it('normalises missing cache fields in appendStepEnd.usage', async () => {
+    const { context } = await runTurn({
+      responses: [makeEndTurnResponse('ok', { inputOther: 7, output: 5 })],
+    });
+    const end = context.stepEnds()[0];
+    expect(end?.usage?.inputOther).toBe(7);
+    expect(end?.usage?.output).toBe(5);
+    expect(end?.usage?.inputCacheRead).toBe(0);
+    expect(end?.usage?.inputCacheCreation).toBe(0);
+  });
+
+  it('does NOT call appendStepEnd when the step is interrupted by abort', async () => {
+    const slow = new SlowTool();
+    const controller = new AbortController();
+
+    const turnPromise = runTurn({
+      tools: [slow],
+      responses: [
+        makeToolUseResponse([makeToolCall('slow', {}, 'tc-1')]),
+        makeEndTurnResponse('unreachable'),
+      ],
+      signal: controller.signal,
+    });
+
+    await slow.started.promise;
+    controller.abort();
+    const { context } = await turnPromise;
+
+    // Step 1 was opened with appendStepBegin, but appendStepEnd was NOT
+    // called because the step aborted mid-tool. Replay treats the missing
+    // step.end as the interruption signal.
+    const begins = context.stepBegins();
+    const ends = context.stepEnds();
+    expect(begins.length).toBeGreaterThanOrEqual(1);
+    expect(ends.length).toBe(0);
+  });
+
+  it('writes appendStepBegin BEFORE llm.chat is called (envelope opens first)', async () => {
+    // Ordering captured as adjacency: the first append in the recorded
+    // calls is appendStepBegin; appendStepEnd appears after the tool
+    // result records for the same step.
+    const echo = new EchoTool();
+    const { context } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'a' }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    const kinds = context.kinds();
+    // First write of the turn is a step.begin
+    expect(kinds[0]).toBe('appendStepBegin');
+    // Within step 1, tool.call and tool.result land between begin and end
+    const begin1 = kinds.indexOf('appendStepBegin');
+    const end1 = kinds.indexOf('appendStepEnd', begin1);
+    const tc1 = kinds.indexOf('appendToolCall', begin1);
+    const tr1 = kinds.indexOf('appendToolResult', begin1);
+    expect(begin1).toBeLessThan(tc1);
+    expect(tc1).toBeLessThan(end1);
+    expect(begin1).toBeLessThan(tr1);
+    expect(tr1).toBeLessThan(end1);
+  });
+
+  it('writes appendToolCall BEFORE the tool actually executes', async () => {
+    // The rejected path also satisfies this ordering: the tool.call record
+    // exists even when there's nothing to execute. We verify with a
+    // missing tool so no tool is ever invoked.
+    const { context } = await runTurn({
+      tools: [],
+      responses: [
+        makeToolUseResponse([makeToolCall('ghost', { x: 1 }, 'tc-1')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    const kinds = context.kinds();
+    const tc = kinds.indexOf('appendToolCall');
+    const tr = kinds.indexOf('appendToolResult');
+    expect(tc).toBeGreaterThanOrEqual(0);
+    expect(tr).toBeGreaterThan(tc);
+  });
+
+  it('writes only one tool.call record per provider tool_call (no duplicate records)', async () => {
+    const echo = new EchoTool();
+    const { context } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeResponse(
+          makeTextParts(''),
+          [
+            makeToolCall('echo', { text: 'a' }, 'tc-1'),
+            makeToolCall('echo', { text: 'b' }, 'tc-2'),
+          ],
+          'tool_use',
+        ),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    expect(context.toolCalls().length).toBe(2);
+    expect(context.toolResults().length).toBe(2);
+  });
+
+  it('reuses the provider tool_call.id as the transcript record uuid', async () => {
+    const echo = new EchoTool();
+    const { context } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'x' }, 'tc-deadbeef')]),
+        makeEndTurnResponse('done'),
+      ],
+    });
+    const record = context.toolCalls()[0];
+    expect(record?.uuid).toBe('tc-deadbeef');
+    expect(record?.toolCallId).toBe('tc-deadbeef');
+  });
+});
diff --git a/packages/agent-core/test/loop/turn-lifecycle.e2e.test.ts b/packages/agent-core/test/loop/turn-lifecycle.e2e.test.ts
new file mode 100644
index 000000000..48e275dfa
--- /dev/null
+++ b/packages/agent-core/test/loop/turn-lifecycle.e2e.test.ts
@@ -0,0 +1,227 @@
+/**
+ * Turn-level lifecycle invariants of `runTurn`.
+ *
+ * These tests treat the loop as a black box: they drive `runTurn` only
+ * through its public input contract and assert against the public output
+ * (`TurnResult`, `LoopEvent`s, transcript writes, `Tool.execute`
+ * calls). Internal modules / classes / file layout are intentionally not
+ * referenced.
+ */
+
+import { inputTotal } from '@moonshot-ai/kosong';
+import { describe, expect, it } from 'vitest';
+
+import { ErrorCodes, KimiError } from '../../src/errors';
+import {
+  makeEndTurnResponse,
+  makeMaxTokensResponse,
+  makeResponse,
+  makeTextParts,
+  makeToolCall,
+  makeToolUseResponse,
+} from './fixtures/fake-llm';
+import { runTurn, runTurnExpectingThrow } from './fixtures/helpers';
+import { EchoTool } from './fixtures/tools';
+
+describe('runTurn — turn lifecycle', () => {
+  it('returns end_turn after a single non-tool step', async () => {
+    const { result, llm, sink } = await runTurn({
+      responses: [makeEndTurnResponse('hello', { inputOther: 5, output: 7 })],
+    });
+
+    expect(result.stopReason).toBe('end_turn');
+    expect(result.steps).toBe(1);
+    expect(inputTotal(result.usage)).toBe(5);
+    expect(result.usage.output).toBe(7);
+    expect(llm.callCount).toBe(1);
+    // step.begin and step.end at minimum, in that order
+    expect(sink.count('step.begin')).toBe(1);
+    expect(sink.count('step.end')).toBe(1);
+    const types = sink.typesIn();
+    expect(types.indexOf('step.begin')).toBeLessThan(types.indexOf('step.end'));
+  });
+
+  it('continues across tool_use steps until end_turn', async () => {
+    const echo = new EchoTool();
+    const { result, llm, sink, context } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'hi' }, 'tc-1')], {
+          inputOther: 1,
+          output: 2,
+        }),
+        makeToolUseResponse([makeToolCall('echo', { text: 'again' }, 'tc-2')], {
+          inputOther: 3,
+          output: 4,
+        }),
+        makeEndTurnResponse('done', { inputOther: 5, output: 6 }),
+      ],
+    });
+
+    expect(result.stopReason).toBe('end_turn');
+    expect(result.steps).toBe(3);
+    expect(inputTotal(result.usage)).toBe(1 + 3 + 5);
+    expect(result.usage.output).toBe(2 + 4 + 6);
+    expect(llm.callCount).toBe(3);
+    expect(echo.calls.map((c) => c.id)).toEqual(['tc-1', 'tc-2']);
+    // Three step envelopes were recorded
+    expect(context.stepBegins().map((s) => s.step)).toEqual([1, 2, 3]);
+    expect(context.stepEnds().map((s) => s.step)).toEqual([1, 2, 3]);
+    // tool_use never escapes as the final stopReason
+    expect(sink.byType('step.end').length).toBe(3);
+  });
+
+  it('returns max_tokens when the LLM signals it', async () => {
+    const { result, sink } = await runTurn({
+      responses: [makeMaxTokensResponse('partial...', { inputOther: 10, output: 20 })],
+    });
+
+    expect(result.stopReason).toBe('max_tokens');
+    expect(result.steps).toBe(1);
+    expect(result.usage).toEqual({
+      inputOther: 10,
+      output: 20,
+      inputCacheRead: 0,
+      inputCacheCreation: 0,
+    });
+    expect(sink.count('turn.interrupted')).toBe(0);
+  });
+
+  it('preserves provider terminal diagnostics when no tool calls are present', async () => {
+    const { result, sink } = await runTurn({
+      responses: [
+        {
+          ...makeResponse(makeTextParts('blocked'), [], 'filtered'),
+          rawFinishReason: 'content_filter',
+        },
+      ],
+    });
+
+    const stepEnd = sink.byType('step.end')[0];
+    expect(result.stopReason).toBe('filtered');
+    expect(stepEnd?.finishReason).toBe('filtered');
+    expect(stepEnd?.providerFinishReason).toBe('filtered');
+    expect(stepEnd?.rawFinishReason).toBe('content_filter');
+  });
+
+  it('treats provider tool_calls without tool call structure as unknown', async () => {
+    const { result } = await runTurn({
+      responses: [makeResponse(makeTextParts('done'), [], 'tool_use')],
+    });
+
+    expect(result.stopReason).toBe('unknown');
+  });
+
+  it('derives tool_use from tool call structure when provider reports completed', async () => {
+    const echo = new EchoTool();
+    const { result, llm } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeResponse([], [makeToolCall('echo', { text: 'hi' }, 'tc-completed')], 'end_turn'),
+        makeEndTurnResponse('done'),
+      ],
+    });
+
+    expect(result.stopReason).toBe('end_turn');
+    expect(llm.callCount).toBe(2);
+    expect(echo.calls.map((c) => c.id)).toEqual(['tc-completed']);
+  });
+
+  it('does not execute tool calls when provider reports a terminal diagnostic', async () => {
+    const echo = new EchoTool();
+    const { result, sink } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeResponse(
+          makeTextParts('blocked'),
+          [makeToolCall('echo', { text: 'should-not-run' }, 'tc-filtered')],
+          'filtered',
+        ),
+      ],
+    });
+
+    expect(result.stopReason).toBe('filtered');
+    expect(echo.calls).toEqual([]);
+    expect(sink.count('tool.call')).toBe(0);
+    expect(sink.count('tool.result')).toBe(0);
+  });
+
+  it('throws KimiError(loop.max_steps_exceeded) when steps reach maxSteps', async () => {
+    const echo = new EchoTool();
+    const { error, sink } = await runTurnExpectingThrow({
+      maxSteps: 2,
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: '1' }, 'a')]),
+        makeToolUseResponse([makeToolCall('echo', { text: '2' }, 'b')]),
+        // The loop throws before requesting a third step.
+      ],
+    });
+
+    expect(error).toBeInstanceOf(KimiError);
+    expect((error as KimiError).code).toBe(ErrorCodes.LOOP_MAX_STEPS_EXCEEDED);
+    expect((error as KimiError).details).toEqual({ maxSteps: 2 });
+    // turn.interrupted{reason:'max_steps'} is emitted before the throw
+    const interruptedTypes = sink.byType('turn.interrupted').map((e) => e.reason);
+    expect(interruptedTypes).toContain('max_steps');
+  });
+
+  it('throws immediately when maxSteps=0 (boundary)', async () => {
+    const { error, sink, llm, context } = await runTurnExpectingThrow({
+      maxSteps: 0,
+      responses: [makeEndTurnResponse('never reached')],
+    });
+
+    expect(error).toBeInstanceOf(KimiError);
+    expect((error as KimiError).code).toBe(ErrorCodes.LOOP_MAX_STEPS_EXCEEDED);
+    expect(llm.callCount).toBe(0);
+    // No step envelope was opened
+    expect(context.stepBegins().length).toBe(0);
+    expect(context.stepEnds().length).toBe(0);
+    expect(sink.count('step.begin')).toBe(0);
+    // turn.interrupted is still emitted without pretending a step started.
+    const interrupted = sink.byType('turn.interrupted');
+    expect(interrupted.length).toBe(1);
+    expect(interrupted[0]?.reason).toBe('max_steps');
+    expect(interrupted[0]?.attemptedSteps).toBe(0);
+    expect(interrupted[0]?.activeStep).toBeUndefined();
+  });
+
+  it('uses a generous default maxSteps when omitted', async () => {
+    // We don't want to actually exhaust the default; just prove that a
+    // single end_turn step under no explicit limit succeeds. The exact
+    // numeric default is an implementation detail, but it must allow at
+    // least one step.
+    const { result } = await runTurn({
+      responses: [makeEndTurnResponse('ok')],
+    });
+    expect(result.stopReason).toBe('end_turn');
+    expect(result.steps).toBe(1);
+  });
+
+  it('aggregates usage across steps including cache fields', async () => {
+    const echo = new EchoTool();
+    const { result } = await runTurn({
+      tools: [echo],
+      responses: [
+        makeToolUseResponse([makeToolCall('echo', { text: 'a' })], {
+          inputOther: 70,
+          output: 50,
+          inputCacheRead: 10,
+          inputCacheCreation: 20,
+        }),
+        makeEndTurnResponse('done', {
+          inputOther: 4,
+          output: 3,
+          inputCacheRead: 1,
+          inputCacheCreation: 2,
+        }),
+      ],
+    });
+
+    expect(inputTotal(result.usage)).toBe(107);
+    expect(result.usage.output).toBe(53);
+    expect(result.usage.inputCacheRead).toBe(11);
+    expect(result.usage.inputCacheCreation).toBe(22);
+  });
+});
diff --git a/packages/agent-core/test/mcp/auth-tool.test.ts b/packages/agent-core/test/mcp/auth-tool.test.ts
new file mode 100644
index 000000000..0025a4ab3
--- /dev/null
+++ b/packages/agent-core/test/mcp/auth-tool.test.ts
@@ -0,0 +1,143 @@
+import { describe, expect, it } from 'vitest';
+
+import type { ToolUpdate } from '../../src/loop';
+import { createMcpAuthTool } from '../../src/mcp/auth-tool';
+import {
+  AlreadyAuthorizedError,
+  type BeginAuthorizationResult,
+  type McpOAuthService,
+} from '../../src/mcp/oauth';
+import { MCP_OAUTH_AUTHORIZATION_URL_TOOL_UPDATE } from '../../src/rpc/events';
+import { executeTool } from '../tools/fixtures/execute-tool';
+
+function fakeOAuthService(
+  begin: (
+    serverName: string,
+    serverUrl: string | URL,
+  ) => Promise<BeginAuthorizationResult> | BeginAuthorizationResult,
+): McpOAuthService {
+  return {
+    beginAuthorization: async (serverName: string, serverUrl: string | URL) =>
+      begin(serverName, serverUrl),
+  } as unknown as McpOAuthService;
+}
+
+function runTool(opts: {
+  oauthService: McpOAuthService;
+  reconnect: (signal?: AbortSignal) => Promise<void>;
+  signal?: AbortSignal;
+}) {
+  const tool = createMcpAuthTool({
+    serverName: 'notion',
+    serverUrl: 'https://example.com/mcp',
+    oauthService: opts.oauthService,
+    reconnect: opts.reconnect,
+    timeoutMs: 100,
+  });
+  const controller = new AbortController();
+  const signal = opts.signal ?? controller.signal;
+  const updates: ToolUpdate[] = [];
+  const result = executeTool(tool, {
+    turnId: 't',
+    toolCallId: 'tc',
+    args: {},
+    signal,
+    onUpdate: (u) => updates.push(u),
+  });
+  return { result, controller, updates, tool };
+}
+
+describe('createMcpAuthTool', () => {
+  it('returns the authorization URL via status updates and final output on success', async () => {
+    let reconnectCalls = 0;
+    const oauthService = fakeOAuthService(async () => ({
+      authorizationUrl: new URL('https://example.com/authorize?state=abc'),
+      complete: async () => undefined,
+      cancel: async () => undefined,
+    }));
+    const { result, updates } = runTool({
+      oauthService,
+      reconnect: async () => {
+        reconnectCalls += 1;
+      },
+    });
+    const final = await result;
+    expect(final.isError).toBeUndefined();
+    expect(final.output).toMatch(/authenticated successfully/);
+    expect(reconnectCalls).toBe(1);
+    expect(updates.some((u) => u.text?.includes('https://example.com/authorize'))).toBe(true);
+    expect(updates).toContainEqual({
+      kind: 'custom',
+      customKind: MCP_OAUTH_AUTHORIZATION_URL_TOOL_UPDATE,
+      customData: {
+        serverName: 'notion',
+        authorizationUrl: 'https://example.com/authorize?state=abc',
+      },
+    });
+  });
+
+  it('falls through to reconnect when the provider reports already-authorized', async () => {
+    let reconnectCalls = 0;
+    const oauthService = fakeOAuthService(async () => {
+      throw new AlreadyAuthorizedError('notion');
+    });
+    const { result } = runTool({
+      oauthService,
+      reconnect: async () => {
+        reconnectCalls += 1;
+      },
+    });
+    const final = await result;
+    expect(final.isError).toBeUndefined();
+    expect(final.output).toMatch(/already had valid OAuth credentials/);
+    expect(reconnectCalls).toBe(1);
+  });
+
+  it('returns isError when beginAuthorization fails outright', async () => {
+    const oauthService = fakeOAuthService(async () => {
+      throw new Error('DCR unsupported');
+    });
+    const { result } = runTool({
+      oauthService,
+      reconnect: async () => undefined,
+    });
+    const final = await result;
+    expect(final.isError).toBe(true);
+    expect(final.output).toMatch(/DCR unsupported/);
+  });
+
+  it('returns isError and surfaces the URL when complete() rejects', async () => {
+    const oauthService = fakeOAuthService(async () => ({
+      authorizationUrl: new URL('https://example.com/authorize?state=abc'),
+      complete: async () => {
+        throw new Error('OAuth callback timed out');
+      },
+      cancel: async () => undefined,
+    }));
+    const { result } = runTool({
+      oauthService,
+      reconnect: async () => undefined,
+    });
+    const final = await result;
+    expect(final.isError).toBe(true);
+    expect(final.output).toMatch(/timed out/);
+    expect(final.output).toMatch(/https:\/\/example\.com\/authorize/);
+  });
+
+  it('returns isError when reconnect after success fails', async () => {
+    const oauthService = fakeOAuthService(async () => ({
+      authorizationUrl: new URL('https://example.com/authorize?state=abc'),
+      complete: async () => undefined,
+      cancel: async () => undefined,
+    }));
+    const { result } = runTool({
+      oauthService,
+      reconnect: async () => {
+        throw new Error('reconnect failed');
+      },
+    });
+    const final = await result;
+    expect(final.isError).toBe(true);
+    expect(final.output).toMatch(/reconnect failed/);
+  });
+});
diff --git a/packages/agent-core/test/mcp/client-http.test.ts b/packages/agent-core/test/mcp/client-http.test.ts
new file mode 100644
index 000000000..8ec1d3cac
--- /dev/null
+++ b/packages/agent-core/test/mcp/client-http.test.ts
@@ -0,0 +1,271 @@
+import { randomUUID } from 'node:crypto';
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { afterEach, describe, expect, it } from 'vitest';
+import { z } from 'zod';
+
+import { ErrorCodes, KimiError } from '../../src/errors';
+import {
+  buildMcpHttpHeaders,
+  HttpMcpClient,
+  isTerminalTransportError,
+} from '../../src/mcp/client-http';
+
+const cleanups: Array<() => Promise<void> | void> = [];
+
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0)) {
+    await cleanup();
+  }
+});
+
+function expectConfigInvalid(fn: () => unknown): void {
+  try {
+    fn();
+  } catch (error) {
+    expect(error).toBeInstanceOf(KimiError);
+    expect((error as KimiError).code).toBe(ErrorCodes.CONFIG_INVALID);
+    return;
+  }
+  throw new Error('expected function to throw');
+}
+
+describe('buildMcpHttpHeaders', () => {
+  it('returns undefined when no headers and no bearer are configured', () => {
+    expect(
+      buildMcpHttpHeaders({ transport: 'http', url: 'https://x' }, () => undefined),
+    ).toBeUndefined();
+  });
+
+  it('passes through configured static headers', () => {
+    expect(
+      buildMcpHttpHeaders(
+        { transport: 'http', url: 'https://x', headers: { 'X-Tenant': 'kimi' } },
+        () => undefined,
+      ),
+    ).toEqual({ 'X-Tenant': 'kimi' });
+  });
+
+  it('injects Authorization Bearer when env lookup yields a token', () => {
+    expect(
+      buildMcpHttpHeaders(
+        { transport: 'http', url: 'https://x', bearerTokenEnvVar: 'TOK' },
+        (name) => (name === 'TOK' ? 'secret' : undefined),
+      ),
+    ).toEqual({ Authorization: 'Bearer secret' });
+  });
+
+  it('throws KimiError(config.invalid) when a configured bearer token env var is empty or missing', () => {
+    expectConfigInvalid(() =>
+      buildMcpHttpHeaders(
+        { transport: 'http', url: 'https://x', bearerTokenEnvVar: 'MISSING' },
+        () => undefined,
+      ),
+    );
+    expect(() =>
+      buildMcpHttpHeaders(
+        { transport: 'http', url: 'https://x', bearerTokenEnvVar: 'MISSING' },
+        () => undefined,
+      ),
+    ).toThrow(/"MISSING" is not set or is empty/);
+    expectConfigInvalid(() =>
+      buildMcpHttpHeaders(
+        { transport: 'http', url: 'https://x', bearerTokenEnvVar: 'EMPTY' },
+        () => '',
+      ),
+    );
+    expect(() =>
+      buildMcpHttpHeaders(
+        { transport: 'http', url: 'https://x', bearerTokenEnvVar: 'EMPTY' },
+        () => '',
+      ),
+    ).toThrow(/"EMPTY" is not set or is empty/);
+  });
+
+  it('merges bearer over the same Authorization key from static headers', () => {
+    expect(
+      buildMcpHttpHeaders(
+        {
+          transport: 'http',
+          url: 'https://x',
+          headers: { Authorization: 'Bearer stale', 'X-Trace': '1' },
+          bearerTokenEnvVar: 'TOK',
+        },
+        () => 'fresh',
+      ),
+    ).toEqual({ Authorization: 'Bearer fresh', 'X-Trace': '1' });
+  });
+
+  it('flags errors the SDK uses to signal a dead HTTP transport as terminal', () => {
+    const unauthorized = new Error('Unauthorized');
+    unauthorized.name = 'UnauthorizedError';
+    expect(isTerminalTransportError(unauthorized)).toBe(true);
+    expect(isTerminalTransportError(new Error('Maximum reconnection attempts (3) exceeded.'))).toBe(
+      true,
+    );
+  });
+
+  it('does not flag transient SDK errors as terminal', () => {
+    expect(isTerminalTransportError(new Error('SSE stream disconnected: ECONNRESET'))).toBe(false);
+    expect(isTerminalTransportError(new Error('fetch failed'))).toBe(false);
+    expect(isTerminalTransportError(new Error('Connection closed'))).toBe(false);
+  });
+
+  it('strips case-variant authorization headers before injecting the bearer', () => {
+    expect(
+      buildMcpHttpHeaders(
+        {
+          transport: 'http',
+          url: 'https://x',
+          headers: { authorization: 'Bearer stale', AUTHORIZATION: 'Bearer older', 'X-Trace': '1' },
+          bearerTokenEnvVar: 'TOK',
+        },
+        () => 'fresh',
+      ),
+    ).toEqual({ Authorization: 'Bearer fresh', 'X-Trace': '1' });
+  });
+});
+
+async function startInProcessHttpMcpServer(opts?: {
+  authToken?: string;
+}): Promise<{ url: string; close: () => Promise<void> }> {
+  const mcpServer = new McpServer({ name: 'mock-http', version: '0.0.1' });
+  mcpServer.registerTool(
+    'echo',
+    { description: 'Echoes text', inputSchema: { text: z.string() } },
+    ({ text }) => ({ content: [{ type: 'text', text }] }),
+  );
+
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => randomUUID(),
+  });
+  await mcpServer.connect(transport);
+
+  const httpServer: Server = createServer((req, res) => {
+    if (opts?.authToken !== undefined) {
+      const auth = req.headers['authorization'];
+      if (auth !== `Bearer ${opts.authToken}`) {
+        res.writeHead(401, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: 'unauthorized' }));
+        return;
+      }
+    }
+    void transport.handleRequest(req, res);
+  });
+
+  await new Promise<void>((resolve) => {
+    httpServer.listen(0, '127.0.0.1', resolve);
+  });
+  const port = (httpServer.address() as AddressInfo).port;
+
+  return {
+    url: `http://127.0.0.1:${port}/mcp`,
+    async close() {
+      await new Promise<void>((resolve, reject) => {
+        httpServer.close((err) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve();
+        });
+      });
+    },
+  };
+}
+
+describe('HttpMcpClient', () => {
+  it('connects, lists tools, and round-trips a call over real HTTP', async () => {
+    const server = await startInProcessHttpMcpServer();
+    cleanups.push(server.close);
+
+    const client = new HttpMcpClient({ transport: 'http', url: server.url });
+    try {
+      await client.connect();
+      const tools = await client.listTools();
+      expect(tools.map((t) => t.name)).toEqual(['echo']);
+
+      const result = await client.callTool('echo', { text: 'hello http' });
+      expect(result.isError).toBe(false);
+      expect(result.content).toEqual([{ type: 'text', text: 'hello http' }]);
+    } finally {
+      await client.close();
+    }
+  }, 15000);
+
+  it('flips to unexpected-close when the SDK signals a terminal transport error', async () => {
+    const server = await startInProcessHttpMcpServer();
+    cleanups.push(server.close);
+
+    const client = new HttpMcpClient({ transport: 'http', url: server.url });
+    const closes: Array<{ error?: string }> = [];
+    client.onUnexpectedClose((reason) => {
+      closes.push({ error: reason.error?.message });
+    });
+    try {
+      await client.connect();
+      // The SDK normally calls `Client.onerror` from its own retry loop
+      // (e.g. "Maximum reconnection attempts (3) exceeded.") — there is no
+      // matching `onclose` for HTTP. Simulate that path directly to exercise
+      // the terminal-error branch without rigging an SSE reconnect storm.
+      const internal = (client as unknown as {
+        client: { onerror?: (error: Error) => void };
+      }).client;
+      internal.onerror?.(new Error('Maximum reconnection attempts (3) exceeded.'));
+      // Listener may fire in a later microtask; give it a chance.
+      await new Promise((r) => setTimeout(r, 25));
+      expect(closes).toHaveLength(1);
+      expect(closes[0]?.error).toContain('Maximum reconnection attempts');
+    } finally {
+      await client.close();
+    }
+  }, 15000);
+
+  it('ignores transient SDK errors that the transport recovers from', async () => {
+    const server = await startInProcessHttpMcpServer();
+    cleanups.push(server.close);
+
+    const client = new HttpMcpClient({ transport: 'http', url: server.url });
+    const closes: number[] = [];
+    client.onUnexpectedClose(() => closes.push(Date.now()));
+    try {
+      await client.connect();
+      const internal = (client as unknown as {
+        client: { onerror?: (error: Error) => void };
+      }).client;
+      // SSE flap that the SDK will retry on its own — should NOT flip the
+      // entry to failed; otherwise a brief network blip would tear down every
+      // HTTP MCP connection.
+      internal.onerror?.(new Error('SSE stream disconnected: ECONNRESET'));
+      internal.onerror?.(new Error('fetch failed'));
+      await new Promise((r) => setTimeout(r, 25));
+      expect(closes).toEqual([]);
+    } finally {
+      await client.close();
+    }
+  }, 15000);
+
+  it('forwards bearer token from envLookup', async () => {
+    const server = await startInProcessHttpMcpServer({ authToken: 'good-token' });
+    cleanups.push(server.close);
+
+    const client = new HttpMcpClient(
+      {
+        transport: 'http',
+        url: server.url,
+        bearerTokenEnvVar: 'EXAMPLE_TOKEN',
+      },
+      { envLookup: (name) => (name === 'EXAMPLE_TOKEN' ? 'good-token' : undefined) },
+    );
+    try {
+      await client.connect();
+      const tools = await client.listTools();
+      expect(tools.map((t) => t.name)).toEqual(['echo']);
+    } finally {
+      await client.close();
+    }
+  }, 15000);
+});
diff --git a/packages/agent-core/test/mcp/client-stdio.test.ts b/packages/agent-core/test/mcp/client-stdio.test.ts
new file mode 100644
index 000000000..854c4644a
--- /dev/null
+++ b/packages/agent-core/test/mcp/client-stdio.test.ts
@@ -0,0 +1,248 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import { KimiError } from '../../src/errors';
+import { StdioMcpClient } from '../../src/mcp/client-stdio';
+
+const here = import.meta.dirname;
+const fixture = join(here, 'fixtures', 'mock-stdio-server.mjs');
+const stderrThenExitFixture = join(here, 'fixtures', 'stderr-then-exit-stdio-server.mjs');
+const crashAfterConnectFixture = join(here, 'fixtures', 'crash-after-connect-stdio-server.mjs');
+
+describe('StdioMcpClient', () => {
+  it('rejects unsupported executor at construction time', () => {
+    expect(
+      () =>
+        new StdioMcpClient({
+          transport: 'stdio',
+          command: 'true',
+          executor: 'kaos',
+        }),
+    ).toThrow(
+      expect.objectContaining({ name: 'KimiError', code: 'not_implemented' }) as unknown as Error,
+    );
+    // Sanity-check the error class identity too.
+    let thrown: unknown;
+    try {
+      const client = new StdioMcpClient({ transport: 'stdio', command: 'true', executor: 'kaos' });
+      void client;
+    } catch (error) {
+      thrown = error;
+    }
+    expect(thrown).toBeInstanceOf(KimiError);
+  });
+
+  it('connects, lists tools, and round-trips a text result', async () => {
+    const client = new StdioMcpClient({
+      transport: 'stdio',
+      command: process.execPath,
+      args: [fixture],
+    });
+    try {
+      await client.connect();
+      const tools = await client.listTools();
+      expect(tools.map((t) => t.name).toSorted()).toEqual(['boom', 'echo', 'read_env']);
+      const echo = tools.find((t) => t.name === 'echo');
+      expect(echo?.description).toBe('Echoes input text');
+      expect(echo?.inputSchema).toMatchObject({ type: 'object' });
+
+      const result = await client.callTool('echo', { text: 'hello mcp' });
+      expect(result.isError).toBe(false);
+      expect(result.content).toEqual([{ type: 'text', text: 'hello mcp' }]);
+    } finally {
+      await client.close();
+    }
+  }, 15000);
+
+  it('propagates server-reported isError', async () => {
+    const client = new StdioMcpClient({
+      transport: 'stdio',
+      command: process.execPath,
+      args: [fixture],
+    });
+    try {
+      await client.connect();
+      const result = await client.callTool('boom', {});
+      expect(result.isError).toBe(true);
+      expect(result.content[0]).toEqual({ type: 'text', text: 'boom!' });
+    } finally {
+      await client.close();
+    }
+  }, 15000);
+
+  it('forwards configured env to the spawned server', async () => {
+    const client = new StdioMcpClient({
+      transport: 'stdio',
+      command: process.execPath,
+      args: [fixture],
+      env: { KIMI_TEST_ENV: 'forwarded-value' },
+    });
+    try {
+      await client.connect();
+      const result = await client.callTool('read_env', { name: 'KIMI_TEST_ENV' });
+      expect(result.content).toEqual([{ type: 'text', text: 'forwarded-value' }]);
+    } finally {
+      await client.close();
+    }
+  }, 15000);
+
+  it('inherits parent process env so PATH/HOME survive; config.env overrides on conflict', async () => {
+    const parentOnly = `KIMI_TEST_PARENT_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    const shared = `KIMI_TEST_SHARED_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    process.env[parentOnly] = 'from-parent';
+    process.env[shared] = 'from-parent';
+    const client = new StdioMcpClient({
+      transport: 'stdio',
+      command: process.execPath,
+      args: [fixture],
+      env: { [shared]: 'from-config' },
+    });
+    try {
+      await client.connect();
+      const inherited = await client.callTool('read_env', { name: parentOnly });
+      expect(inherited.content).toEqual([{ type: 'text', text: 'from-parent' }]);
+      const overridden = await client.callTool('read_env', { name: shared });
+      expect(overridden.content).toEqual([{ type: 'text', text: 'from-config' }]);
+    } finally {
+      delete process.env[parentOnly];
+      delete process.env[shared];
+      await client.close();
+    }
+  }, 15000);
+
+  it('captures recent stderr into a snapshot the manager can attach to errors', async () => {
+    const banner = `kimi-test-stderr-${Date.now()}`;
+    const client = new StdioMcpClient({
+      transport: 'stdio',
+      command: process.execPath,
+      args: [stderrThenExitFixture],
+      env: { KIMI_TEST_MCP_STDERR: banner },
+    });
+    try {
+      await expect(client.connect()).rejects.toThrow();
+      // Even when connect fails, the buffered stderr must be retrievable so
+      // higher layers can include it in the user-facing error message.
+      expect(client.stderrSnapshot()).toContain(banner);
+    } finally {
+      await client.close();
+    }
+  }, 15000);
+
+  it('keeps the stderr buffer bounded so noisy servers cannot exhaust memory', async () => {
+    const client = new StdioMcpClient({
+      transport: 'stdio',
+      command: process.execPath,
+      args: [fixture],
+    });
+    try {
+      await client.connect();
+      // Confirm the buffer cap is documented and finite (4 KB is plenty for a
+      // useful tail). The exact value is an implementation detail but
+      // exposing it for tests prevents unbounded growth from regressing.
+      expect(StdioMcpClient.stderrBufferCapacity).toBeLessThanOrEqual(16 * 1024);
+      expect(StdioMcpClient.stderrBufferCapacity).toBeGreaterThanOrEqual(1024);
+    } finally {
+      await client.close();
+    }
+  }, 15000);
+
+  it('notifies an unexpected-close listener when the child exits after connect', async () => {
+    const banner = `kimi-test-crash-${Date.now()}`;
+    const client = new StdioMcpClient({
+      transport: 'stdio',
+      command: process.execPath,
+      args: [crashAfterConnectFixture],
+      env: { KIMI_TEST_MCP_EXIT_AFTER_MS: '50', KIMI_TEST_MCP_STDERR: banner },
+    });
+    const closes: Array<{ stderr?: string; error?: string }> = [];
+    client.onUnexpectedClose((reason) => {
+      closes.push({ stderr: reason.stderr, error: reason.error?.message });
+    });
+    try {
+      await client.connect();
+      // Wait for the child to exit and onclose to fire.
+      for (let i = 0; i < 100; i++) {
+        if (closes.length > 0) break;
+        await new Promise((r) => setTimeout(r, 25));
+      }
+      expect(closes).toHaveLength(1);
+      expect(closes[0]?.stderr ?? '').toContain(banner);
+    } finally {
+      await client.close();
+    }
+  }, 15000);
+
+  it('buffers an early close and replays it on listener registration', async () => {
+    const banner = `kimi-test-early-${Date.now()}`;
+    const client = new StdioMcpClient({
+      transport: 'stdio',
+      command: process.execPath,
+      args: [crashAfterConnectFixture],
+      env: { KIMI_TEST_MCP_STDERR: banner, KIMI_TEST_MCP_EXIT_CODE: '0' },
+    });
+    try {
+      await client.connect();
+      // Drive the child to exit AFTER a successful tool response. The fixture
+      // schedules `process.exit` via setImmediate so the reply is fully
+      // flushed before the pipe closes; this exercises the post-handshake
+      // disconnect path with no startup-timing race.
+      const reply = await client.callTool('exit_after_reply', {});
+      expect(reply.isError).toBe(false);
+      // Wait deterministically for the child to actually exit. The fixture
+      // writes `banner\n` to stderr sync-before `process.exit`, so observing
+      // the banner is proof the exit syscall has been issued.
+      const exitDeadline = Date.now() + 5000;
+      while (Date.now() < exitDeadline && !client.stderrSnapshot().includes(banner)) {
+        await new Promise((r) => setTimeout(r, 5));
+      }
+      expect(client.stderrSnapshot()).toContain(banner);
+      // Drain probe: send a fresh request that the dead transport must
+      // reject. Once it does, we know the SDK has processed `_onclose`,
+      // which means our hook has already populated `pendingUnexpectedClose`.
+      // This is what gives us a buffer to replay — registering the listener
+      // first would intercept the close as a live fire instead.
+      const drainDeadline = Date.now() + 5000;
+      let transportConfirmedDead = false;
+      while (Date.now() < drainDeadline) {
+        try {
+          await client.callTool('echo', { text: 'probe' });
+        } catch {
+          transportConfirmedDead = true;
+          break;
+        }
+        await new Promise((r) => setTimeout(r, 10));
+      }
+      expect(transportConfirmedDead).toBe(true);
+      // `pendingUnexpectedClose` is set; registering the listener must
+      // invoke it synchronously inside the call.
+      let received: { stderr?: string } | undefined;
+      let syncedOnRegister = false;
+      client.onUnexpectedClose((reason) => {
+        syncedOnRegister = true;
+        received = { stderr: reason.stderr };
+      });
+      expect(syncedOnRegister).toBe(true);
+      expect(received?.stderr ?? '').toContain(banner);
+    } finally {
+      await client.close();
+    }
+  }, 15000);
+
+  it('does not fire unexpected-close when the caller closes the client itself', async () => {
+    const client = new StdioMcpClient({
+      transport: 'stdio',
+      command: process.execPath,
+      args: [fixture],
+    });
+    const closes: number[] = [];
+    client.onUnexpectedClose(() => closes.push(Date.now()));
+    await client.connect();
+    await client.close();
+    // Give any pending onclose listener a chance to fire so we are sure it is
+    // suppressed and not merely racing.
+    await new Promise((r) => setTimeout(r, 100));
+    expect(closes).toEqual([]);
+  }, 15000);
+});
diff --git a/packages/agent-core/test/mcp/config-loader.test.ts b/packages/agent-core/test/mcp/config-loader.test.ts
new file mode 100644
index 000000000..558d1ac92
--- /dev/null
+++ b/packages/agent-core/test/mcp/config-loader.test.ts
@@ -0,0 +1,167 @@
+import { mkdtempSync } from 'node:fs';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { ErrorCodes, KimiError } from '../../src/errors';
+import { loadMcpServers, resolveMcpJsonPaths } from '../../src/mcp/config-loader';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+function makeTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'kimi-mcp-loader-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+async function writeJson(path: string, value: unknown): Promise<void> {
+  await mkdir(join(path, '..'), { recursive: true });
+  await writeFile(path, JSON.stringify(value), 'utf-8');
+}
+
+describe('resolveMcpJsonPaths', () => {
+  it('returns the canonical user and project paths', () => {
+    const paths = resolveMcpJsonPaths({ cwd: '/work/proj', homeDir: '/home/user/.kimi-code' });
+    expect(paths.user).toBe('/home/user/.kimi-code/mcp.json');
+    expect(paths.project).toBe('/work/proj/.kimi-code/mcp.json');
+  });
+});
+
+describe('loadMcpServers', () => {
+  it('returns an empty map when no files exist', async () => {
+    const home = makeTempDir();
+    const cwd = makeTempDir();
+    const servers = await loadMcpServers({ cwd, homeDir: home });
+    expect(servers).toEqual({});
+  });
+
+  it('treats empty JSON files as empty maps', async () => {
+    const home = makeTempDir();
+    const cwd = makeTempDir();
+    await writeFile(join(home, 'mcp.json'), '   \n');
+    const servers = await loadMcpServers({ cwd, homeDir: home });
+    expect(servers).toEqual({});
+  });
+
+  it('merges project-local mcp.json with user-global, project overriding on conflict', async () => {
+    const home = makeTempDir();
+    const cwd = makeTempDir();
+
+    await writeJson(join(home, 'mcp.json'), {
+      mcpServers: {
+        shared: { transport: 'stdio', command: 'shared-user' },
+        userOnly: { transport: 'stdio', command: 'user-only' },
+      },
+    });
+    await writeJson(join(cwd, '.kimi-code', 'mcp.json'), {
+      mcpServers: {
+        shared: { transport: 'stdio', command: 'shared-project' },
+        local: { transport: 'http', url: 'http://localhost:8080/mcp' },
+      },
+    });
+
+    const servers = await loadMcpServers({ cwd, homeDir: home });
+
+    expect(Object.keys(servers).toSorted()).toEqual(['local', 'shared', 'userOnly']);
+    expect(servers['shared']).toEqual({
+      transport: 'stdio',
+      command: 'shared-project',
+    });
+    expect(servers['userOnly']).toEqual({
+      transport: 'stdio',
+      command: 'user-only',
+    });
+    expect(servers['local']).toEqual({
+      transport: 'http',
+      url: 'http://localhost:8080/mcp',
+    });
+  });
+
+  it('throws KimiError(config.invalid) on invalid JSON', async () => {
+    const home = makeTempDir();
+    const cwd = makeTempDir();
+    await writeFile(join(home, 'mcp.json'), '{not json}', 'utf-8');
+    await expect(loadMcpServers({ cwd, homeDir: home })).rejects.toBeInstanceOf(KimiError);
+    await expect(loadMcpServers({ cwd, homeDir: home })).rejects.toMatchObject({
+      code: ErrorCodes.CONFIG_INVALID,
+    });
+  });
+
+  it('throws KimiError(config.invalid) on schema violation (unknown transport)', async () => {
+    const home = makeTempDir();
+    const cwd = makeTempDir();
+    await writeJson(join(home, 'mcp.json'), {
+      mcpServers: { bad: { transport: 'sse', url: 'https://x' } },
+    });
+    await expect(loadMcpServers({ cwd, homeDir: home })).rejects.toMatchObject({
+      code: ErrorCodes.CONFIG_INVALID,
+    });
+  });
+
+  it('throws KimiError(config.invalid) on schema violation (missing required field)', async () => {
+    const home = makeTempDir();
+    const cwd = makeTempDir();
+    await writeJson(join(home, 'mcp.json'), {
+      mcpServers: { bad: { transport: 'stdio' } },
+    });
+    await expect(loadMcpServers({ cwd, homeDir: home })).rejects.toMatchObject({
+      code: ErrorCodes.CONFIG_INVALID,
+    });
+  });
+
+  it('infers transport=stdio when an entry omits transport but has command', async () => {
+    const home = makeTempDir();
+    const cwd = makeTempDir();
+    await writeJson(join(home, 'mcp.json'), {
+      mcpServers: {
+        gh: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] },
+      },
+    });
+    const servers = await loadMcpServers({ cwd, homeDir: home });
+    expect(servers['gh']).toEqual({
+      transport: 'stdio',
+      command: 'npx',
+      args: ['-y', '@modelcontextprotocol/server-github'],
+    });
+  });
+
+  it('infers transport=http when an entry omits transport but has url', async () => {
+    const home = makeTempDir();
+    const cwd = makeTempDir();
+    await writeJson(join(home, 'mcp.json'), {
+      mcpServers: {
+        remote: { url: 'https://mcp.example.com/sse' },
+      },
+    });
+    const servers = await loadMcpServers({ cwd, homeDir: home });
+    expect(servers['remote']).toEqual({
+      transport: 'http',
+      url: 'https://mcp.example.com/sse',
+    });
+  });
+
+  it('honors KIMI_CODE_HOME env var when homeDir is not supplied', async () => {
+    const home = makeTempDir();
+    const cwd = makeTempDir();
+    await writeJson(join(home, 'mcp.json'), {
+      mcpServers: { from_env: { transport: 'stdio', command: 'env-cmd' } },
+    });
+    const saved = process.env['KIMI_CODE_HOME'];
+    process.env['KIMI_CODE_HOME'] = home;
+    try {
+      const servers = await loadMcpServers({ cwd });
+      expect(servers['from_env']).toEqual({ transport: 'stdio', command: 'env-cmd' });
+    } finally {
+      if (saved === undefined) delete process.env['KIMI_CODE_HOME'];
+      else process.env['KIMI_CODE_HOME'] = saved;
+    }
+  });
+});
diff --git a/packages/agent-core/test/mcp/connection-manager.test.ts b/packages/agent-core/test/mcp/connection-manager.test.ts
new file mode 100644
index 000000000..7e77b41b2
--- /dev/null
+++ b/packages/agent-core/test/mcp/connection-manager.test.ts
@@ -0,0 +1,898 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { localKaos } from '@moonshot-ai/kaos';
+import type { ProviderConfig } from '@moonshot-ai/kosong';
+import { describe, expect, it } from 'vitest';
+
+import { randomUUID } from 'node:crypto';
+import { createServer as createHttpServer, type Server as HttpServer } from 'node:http';
+import type { AddressInfo as HttpAddress } from 'node:net';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type {
+  OAuthClientInformationFull,
+  OAuthTokens,
+} from '@modelcontextprotocol/sdk/shared/auth.js';
+import { z } from 'zod';
+
+import { KimiError } from '../../src/errors';
+import { ProviderManager } from '../../src/providers/provider-manager';
+import { McpConnectionManager, type McpServerEntry } from '../../src/mcp/connection-manager';
+import { JsonFileStore, McpOAuthService } from '../../src/mcp/oauth';
+import type { AgentEvent, SDKSessionRPC } from '../../src/rpc';
+import { Session } from '../../src/session';
+import { SessionAPIImpl } from '../../src/session/rpc';
+import { detectEnvironmentFromNode } from '../../src/utils/environment';
+import { createScriptedGenerate } from '../agent/harness';
+
+const here = import.meta.dirname;
+const stdioFixture = join(here, 'fixtures', 'mock-stdio-server.mjs');
+const slowStdioFixture = join(here, 'fixtures', 'slow-stdio-server.mjs');
+const crashAfterConnectFixture = join(here, 'fixtures', 'crash-after-connect-stdio-server.mjs');
+const stderrThenExitFixture = join(here, 'fixtures', 'stderr-then-exit-stdio-server.mjs');
+const MOCK_PROVIDER: ProviderConfig = {
+  type: 'kimi',
+  apiKey: 'test-key',
+  model: 'mock-model',
+};
+type SessionRpcEvent = AgentEvent & { readonly agentId: string };
+
+function stdioConfig(args: string[] = [stdioFixture]) {
+  return {
+    transport: 'stdio' as const,
+    command: process.execPath,
+    args,
+  };
+}
+
+function sessionRpc(options: {
+  readonly events?: SessionRpcEvent[] | undefined;
+  readonly onEvent?: ((event: SessionRpcEvent) => void) | undefined;
+} = {}): SDKSessionRPC {
+  return {
+    emitEvent: async (event: SessionRpcEvent) => {
+      options.events?.push(event);
+      options.onEvent?.(event);
+    },
+    requestApproval: async () => ({ decision: 'rejected' }),
+    requestQuestion: async () => null,
+    toolCall: async () => ({ output: '' }),
+  } as unknown as SDKSessionRPC;
+}
+
+describe('McpConnectionManager', () => {
+  it('connects servers in parallel and exposes connected entries with their tool count', async () => {
+    const cm = new McpConnectionManager();
+    try {
+      await cm.connectAll({ alpha: stdioConfig(), beta: stdioConfig() });
+      const entries = cm.list();
+      expect(entries.map((e) => e.name).toSorted()).toEqual(['alpha', 'beta']);
+      for (const entry of entries) {
+        expect(entry.status).toBe('connected');
+        expect(entry.toolCount).toBe(3);
+        expect(entry.transport).toBe('stdio');
+      }
+    } finally {
+      await cm.shutdown();
+    }
+  }, 20000);
+
+  it('isolates failures: a bad server is marked failed without blocking the rest', async () => {
+    const cm = new McpConnectionManager();
+    try {
+      await cm.connectAll({
+        good: stdioConfig(),
+        bad: { transport: 'stdio', command: '/this/path/does/not/exist/anywhere' },
+      });
+      const good = cm.get('good');
+      const bad = cm.get('bad');
+      expect(good?.status).toBe('connected');
+      expect(bad?.status).toBe('failed');
+      expect(bad?.error).toBeDefined();
+    } finally {
+      await cm.shutdown();
+    }
+  }, 20000);
+
+  it('marks HTTP servers failed when configured bearer token env var is missing', async () => {
+    const cm = new McpConnectionManager({ envLookup: () => undefined });
+    try {
+      await cm.connectAll({
+        remote: {
+          transport: 'http',
+          url: 'https://example.invalid/mcp',
+          bearerTokenEnvVar: 'REMOTE_MCP_TOKEN',
+        },
+      });
+      const entry = cm.get('remote');
+      expect(entry?.status).toBe('failed');
+      expect(entry?.error).toContain('"REMOTE_MCP_TOKEN" is not set or is empty');
+    } finally {
+      await cm.shutdown();
+    }
+  });
+
+  it('marks disabled servers without attempting a connection', async () => {
+    const cm = new McpConnectionManager();
+    try {
+      await cm.connectAll({
+        off: { ...stdioConfig(), enabled: false },
+      });
+      const entry = cm.get('off');
+      expect(entry?.status).toBe('disabled');
+      expect(entry?.toolCount).toBe(0);
+    } finally {
+      await cm.shutdown();
+    }
+  });
+
+  it('applies enabledTools / disabledTools filters to the resolved tool set', async () => {
+    const cm = new McpConnectionManager();
+    try {
+      await cm.connectAll({
+        filtered: { ...stdioConfig(), enabledTools: ['echo'], disabledTools: ['boom'] },
+      });
+      const resolved = cm.resolved('filtered');
+      expect(resolved).toBeDefined();
+      expect([...(resolved?.enabledNames ?? [])]).toEqual(['echo']);
+      const entry = cm.get('filtered');
+      expect(entry?.toolCount).toBe(1);
+    } finally {
+      await cm.shutdown();
+    }
+  }, 15000);
+
+  it('emits status transitions in order (pending → connected) per server', async () => {
+    const cm = new McpConnectionManager();
+    const seen: Array<{ name: string; status: McpServerEntry['status'] }> = [];
+    cm.onStatusChange((e) => seen.push({ name: e.name, status: e.status }));
+    try {
+      await cm.connectAll({ alpha: stdioConfig() });
+      const statuses = seen.filter((s) => s.name === 'alpha').map((s) => s.status);
+      expect(statuses).toEqual(['pending', 'connected']);
+    } finally {
+      await cm.shutdown();
+    }
+  }, 15000);
+
+  it('reconnect cycles a failed server back through pending and into connected when fixed', async () => {
+    const cm = new McpConnectionManager();
+    try {
+      // First, set up with bad config to land in `failed`.
+      await cm.connectAll({
+        flaky: { transport: 'stdio', command: '/no/such/binary' },
+      });
+      expect(cm.get('flaky')?.status).toBe('failed');
+
+      // Patch the entry's internal config to point at the real fixture by
+      // re-registering through the manager. There is no public `update`
+      // method; reconnect uses the original config stored at connectAll
+      // time, so we re-run connectAll with the corrected entry.
+      await cm.shutdown();
+
+      await cm.connectAll({ flaky: stdioConfig() });
+      await cm.reconnect('flaky');
+      expect(cm.get('flaky')?.status).toBe('connected');
+    } finally {
+      await cm.shutdown();
+    }
+  }, 20000);
+
+  it('does not let stale in-flight startup failures overwrite a reconnect attempt', async () => {
+    const cm = new McpConnectionManager();
+    const seen: Array<{ name: string; status: McpServerEntry['status'] }> = [];
+    cm.onStatusChange((entry) => {
+      seen.push({ name: entry.name, status: entry.status });
+    });
+    const delayedMockServer = `setTimeout(() => import(${JSON.stringify(pathToFileURL(stdioFixture).href)}), 250)`;
+
+    const connect = cm.connectAll({
+      slow: {
+        transport: 'stdio',
+        command: process.execPath,
+        args: ['-e', delayedMockServer],
+        startupTimeoutMs: 2_000,
+      },
+    });
+
+    try {
+      await sleep(50);
+      await cm.reconnect('slow');
+      await connect;
+
+      expect(cm.get('slow')).toMatchObject({
+        status: 'connected',
+        toolCount: 3,
+      });
+      expect(seen.filter((event) => event.name === 'slow').map((event) => event.status)).toEqual([
+        'pending',
+        'pending',
+        'connected',
+      ]);
+    } finally {
+      await cm.shutdown();
+      await Promise.race([connect.catch(() => {}), sleep(1_000)]);
+    }
+  }, 7000);
+
+  it('reconnect throws a coded KimiError when the server name is unknown', async () => {
+    const cm = new McpConnectionManager();
+    try {
+      await expect(cm.reconnect('nope')).rejects.toBeInstanceOf(KimiError);
+      await expect(cm.reconnect('nope')).rejects.toMatchObject({ code: 'mcp.server_not_found' });
+    } finally {
+      await cm.shutdown();
+    }
+  });
+
+  it('reconnect rejects disabled servers without connecting them', async () => {
+    const cm = new McpConnectionManager();
+    try {
+      await cm.connectAll({
+        off: { ...stdioConfig(), enabled: false },
+      });
+
+      const reconnect = cm.reconnect('off');
+      await expect(reconnect).rejects.toBeInstanceOf(KimiError);
+      await expect(reconnect).rejects.toMatchObject({ code: 'mcp.server_disabled' });
+      expect(cm.get('off')).toMatchObject({
+        status: 'disabled',
+        toolCount: 0,
+      });
+    } finally {
+      await cm.shutdown();
+    }
+  });
+
+  it('shutdown clears entries and is idempotent', async () => {
+    const cm = new McpConnectionManager();
+    await cm.connectAll({ alpha: stdioConfig() });
+    expect(cm.list().length).toBe(1);
+    await cm.shutdown();
+    expect(cm.list().length).toBe(0);
+    // Second call must not throw.
+    await cm.shutdown();
+  }, 15000);
+
+  it('shutdown cancels in-flight startup without late status updates', async () => {
+    const cm = new McpConnectionManager();
+    const hangingListFixture = join(here, 'fixtures', 'hanging-list-stdio-server.mjs');
+    const seen: Array<{ name: string; status: McpServerEntry['status'] }> = [];
+    cm.onStatusChange((entry) => {
+      seen.push({ name: entry.name, status: entry.status });
+    });
+
+    const connectPromise = cm.connectAll({
+      slowList: {
+        transport: 'stdio',
+        command: process.execPath,
+        args: [hangingListFixture],
+        startupTimeoutMs: 5_000,
+      },
+    });
+
+    await sleep(50);
+    await cm.shutdown();
+
+    const result = await Promise.race([
+      connectPromise.then(() => 'resolved' as const),
+      sleep(1_000).then(() => 'hung' as const),
+    ]);
+    expect(result).toBe('resolved');
+    expect(cm.list()).toEqual([]);
+    expect(seen).toEqual([{ name: 'slowList', status: 'pending' }]);
+  }, 2000);
+
+  it('honors startupTimeoutMs by marking slow servers failed', async () => {
+    const cm = new McpConnectionManager();
+    try {
+      // The stub.mjs fixture below sleeps before doing the handshake, so a
+      // very small startupTimeoutMs should fire before connect() returns.
+      const slowFixture = join(here, 'fixtures', 'slow-stdio-server.mjs');
+      await cm.connectAll({
+        slow: {
+          transport: 'stdio',
+          command: process.execPath,
+          args: [slowFixture],
+          startupTimeoutMs: 100,
+        },
+      });
+      const entry = cm.get('slow');
+      expect(entry?.status).toBe('failed');
+      expect(entry?.error?.toLowerCase()).toContain('timed out');
+    } finally {
+      await cm.shutdown();
+    }
+  }, 15000);
+
+  it('honors startupTimeoutMs while discovering tools', async () => {
+    const cm = new McpConnectionManager();
+    const hangingListFixture = join(here, 'fixtures', 'hanging-list-stdio-server.mjs');
+    const connectPromise = cm.connectAll({
+      slowList: {
+        transport: 'stdio',
+        command: process.execPath,
+        args: [hangingListFixture],
+        startupTimeoutMs: 100,
+      },
+    });
+    try {
+      const result = await Promise.race([
+        connectPromise.then(() => 'resolved' as const),
+        sleep(1_000).then(() => 'hung' as const),
+      ]);
+      expect(result).toBe('resolved');
+
+      const entry = cm.get('slowList');
+      expect(entry?.status).toBe('failed');
+      expect(entry?.error?.toLowerCase()).toContain('timed out');
+    } finally {
+      await cm.shutdown();
+      await Promise.race([connectPromise.catch(() => {}), sleep(1_000)]);
+    }
+  }, 7000);
+
+  it('flips HTTP servers into needs-auth when the server returns 401 and no static token is set', async () => {
+    const server: HttpServer = createHttpServer((_req, res) => {
+      res.writeHead(401, {
+        'content-type': 'application/json',
+        'www-authenticate': 'Bearer realm="mcp", resource_metadata="http://x/.well-known/oauth-protected-resource"',
+      });
+      res.end(JSON.stringify({ error: 'unauthorized' }));
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const port = (server.address() as HttpAddress).port;
+    const storeDir = await mkdtemp(join(tmpdir(), 'kimi-mcp-oauth-cm-'));
+    const oauthService = new McpOAuthService({ store: new JsonFileStore(storeDir) });
+    const cm = new McpConnectionManager({ oauthService });
+    try {
+      await cm.connectAll({
+        gated: {
+          transport: 'http',
+          url: `http://127.0.0.1:${port}/mcp`,
+          startupTimeoutMs: 5_000,
+        },
+      });
+      const entry = cm.get('gated');
+      expect(entry?.status).toBe('needs-auth');
+      expect(entry?.error).toContain('run /mcp-config login gated');
+      expect(entry?.toolCount).toBe(0);
+    } finally {
+      await cm.shutdown();
+      await new Promise<void>((resolve, reject) => {
+        server.close((err) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve();
+        });
+      });
+      await rm(storeDir, { recursive: true, force: true });
+    }
+  }, 15000);
+
+  it('flips cached OAuth credentials that require reauth into needs-auth', async () => {
+    const server: HttpServer = createHttpServer((req, res) => {
+      if (req.url === '/token') {
+        res.writeHead(400, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: 'invalid_grant' }));
+        return;
+      }
+      res.writeHead(401, {
+        'content-type': 'application/json',
+        'www-authenticate': 'Bearer realm="mcp"',
+      });
+      res.end(JSON.stringify({ error: 'unauthorized' }));
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const port = (server.address() as HttpAddress).port;
+    const serverUrl = `http://127.0.0.1:${port}/mcp`;
+    const authServerUrl = `http://127.0.0.1:${port}`;
+    const storeDir = await mkdtemp(join(tmpdir(), 'kimi-mcp-oauth-cached-'));
+    const oauthService = new McpOAuthService({ store: new JsonFileStore(storeDir) });
+    const provider = oauthService.getProvider('notion', serverUrl);
+    provider.saveDiscoveryState({
+      authorizationServerUrl: authServerUrl,
+      authorizationServerMetadata: {
+        issuer: authServerUrl,
+        authorization_endpoint: `${authServerUrl}/authorize`,
+        token_endpoint: `${authServerUrl}/token`,
+        response_types_supported: ['code'],
+        grant_types_supported: ['authorization_code', 'refresh_token'],
+        token_endpoint_auth_methods_supported: ['none'],
+      },
+    });
+    provider.saveClientInformation({
+      client_id: 'cached-client',
+      redirect_uris: ['http://127.0.0.1:45678/callback'],
+      token_endpoint_auth_method: 'none',
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+    } satisfies OAuthClientInformationFull);
+    provider.saveTokens({
+      access_token: 'stale-access-token',
+      refresh_token: 'stale-refresh-token',
+      token_type: 'Bearer',
+    } satisfies OAuthTokens);
+
+    const cm = new McpConnectionManager({ oauthService });
+    try {
+      await cm.connectAll({
+        notion: {
+          transport: 'http',
+          url: serverUrl,
+          startupTimeoutMs: 5_000,
+        },
+      });
+      const entry = cm.get('notion');
+      expect(entry).toMatchObject({
+        status: 'needs-auth',
+        error: expect.stringContaining('run /mcp-config login notion'),
+      });
+      expect(entry?.error).not.toContain('redirectUrl must be set');
+    } finally {
+      await cm.shutdown();
+      await new Promise<void>((resolve, reject) => {
+        server.close((err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+      await rm(storeDir, { recursive: true, force: true });
+    }
+  }, 15000);
+
+  it('marks HTTP 401 as failed (not needs-auth) when no OAuth service is configured', async () => {
+    const server: HttpServer = createHttpServer((_req, res) => {
+      res.writeHead(401).end('nope');
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const port = (server.address() as HttpAddress).port;
+    const cm = new McpConnectionManager();
+    try {
+      await cm.connectAll({
+        gated: {
+          transport: 'http',
+          url: `http://127.0.0.1:${port}/mcp`,
+          startupTimeoutMs: 5_000,
+        },
+      });
+      expect(cm.get('gated')?.status).toBe('failed');
+    } finally {
+      await cm.shutdown();
+      await new Promise<void>((resolve, reject) => {
+        server.close((err) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve();
+        });
+      });
+    }
+  }, 15000);
+
+  it('flips connected stdio servers to failed when the child exits unexpectedly', async () => {
+    const cm = new McpConnectionManager();
+    const seen: Array<{ name: string; status: McpServerEntry['status'] }> = [];
+    cm.onStatusChange((e) => seen.push({ name: e.name, status: e.status }));
+    try {
+      await cm.connectAll({
+        crashy: {
+          transport: 'stdio',
+          command: process.execPath,
+          args: [crashAfterConnectFixture],
+          env: { KIMI_TEST_MCP_EXIT_AFTER_MS: '50', KIMI_TEST_MCP_STDERR: 'fatal: out of memory' },
+          startupTimeoutMs: 4_000,
+        },
+      });
+      expect(cm.get('crashy')?.status).toBe('connected');
+
+      // Wait for the child to die and the manager to notice via onclose.
+      for (let i = 0; i < 100; i++) {
+        if (cm.get('crashy')?.status === 'failed') break;
+        await sleep(50);
+      }
+      const entry = cm.get('crashy');
+      expect(entry?.status).toBe('failed');
+      expect(entry?.toolCount).toBe(0);
+      expect(entry?.error).toBeDefined();
+      expect(entry?.error?.toLowerCase()).toContain('closed');
+      // stderr tail should appear in the error so users can debug.
+      expect(entry?.error).toContain('fatal: out of memory');
+      // Status events should include the new failed transition.
+      const statuses = seen.filter((s) => s.name === 'crashy').map((s) => s.status);
+      expect(statuses).toEqual(['pending', 'connected', 'failed']);
+    } finally {
+      await cm.shutdown();
+    }
+  }, 10000);
+
+  it('includes captured stderr in the error when stdio connect fails before handshake', async () => {
+    const cm = new McpConnectionManager();
+    try {
+      await cm.connectAll({
+        nope: {
+          transport: 'stdio',
+          command: process.execPath,
+          args: [stderrThenExitFixture],
+          env: { KIMI_TEST_MCP_STDERR: 'fatal: missing API token KIMI_X' },
+          startupTimeoutMs: 4_000,
+        },
+      });
+      const entry = cm.get('nope');
+      expect(entry?.status).toBe('failed');
+      expect(entry?.error).toContain('fatal: missing API token KIMI_X');
+    } finally {
+      await cm.shutdown();
+    }
+  }, 10000);
+
+  it('does not flip to failed when the manager intentionally closes the client', async () => {
+    const cm = new McpConnectionManager();
+    const seen: Array<{ name: string; status: McpServerEntry['status'] }> = [];
+    cm.onStatusChange((e) => seen.push({ name: e.name, status: e.status }));
+    try {
+      await cm.connectAll({ alpha: stdioConfig() });
+      expect(cm.get('alpha')?.status).toBe('connected');
+      await cm.shutdown();
+      // Give any stray onclose handlers a chance to fire.
+      await sleep(100);
+      // After shutdown the entry is gone; no extra `failed` event must be
+      // emitted from the intentional close path.
+      const statuses = seen.filter((s) => s.name === 'alpha').map((s) => s.status);
+      expect(statuses).toEqual(['pending', 'connected']);
+    } finally {
+      await cm.shutdown();
+    }
+  }, 10000);
+
+  it('flips connected HTTP servers to failed when the SDK reports a terminal transport error', async () => {
+    // Use the SDK's own in-process HTTP server so the connect succeeds; once
+    // the entry is `connected`, simulate the SDK calling Client.onerror with
+    // the reconnect-exhausted message (the path streamable-http uses to
+    // report a dead transport — there is no `onclose` for that case).
+    const mcpServer = new McpServer({ name: 'cm-terminal', version: '0.0.1' });
+    mcpServer.registerTool(
+      'echo',
+      { description: 'Echoes text', inputSchema: { text: z.string() } },
+      ({ text }) => ({ content: [{ type: 'text', text }] }),
+    );
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+    });
+    await mcpServer.connect(transport);
+    const httpServer = createHttpServer((req, res) => {
+      void transport.handleRequest(req, res);
+    });
+    await new Promise<void>((resolve) => httpServer.listen(0, '127.0.0.1', resolve));
+    const port = (httpServer.address() as HttpAddress).port;
+
+    const cm = new McpConnectionManager();
+    const seen: Array<{ name: string; status: McpServerEntry['status'] }> = [];
+    cm.onStatusChange((e) => seen.push({ name: e.name, status: e.status }));
+    try {
+      await cm.connectAll({
+        remote: {
+          transport: 'http',
+          url: `http://127.0.0.1:${port}/mcp`,
+          startupTimeoutMs: 5_000,
+        },
+      });
+      expect(cm.get('remote')?.status).toBe('connected');
+
+      // Reach into the live client to invoke the same hook the SDK uses.
+      const internalClient = (cm as unknown as {
+        entries: Map<string, { client?: { client: { onerror?: (e: Error) => void } } }>;
+      }).entries.get('remote')?.client?.client;
+      internalClient?.onerror?.(new Error('Maximum reconnection attempts (3) exceeded.'));
+
+      // Listener fires asynchronously through our wrapper; allow microtasks.
+      for (let i = 0; i < 50; i++) {
+        if (cm.get('remote')?.status === 'failed') break;
+        await sleep(25);
+      }
+      const entry = cm.get('remote');
+      expect(entry?.status).toBe('failed');
+      expect(entry?.toolCount).toBe(0);
+      expect(entry?.error).toContain('Maximum reconnection attempts');
+      const statuses = seen.filter((s) => s.name === 'remote').map((s) => s.status);
+      expect(statuses).toEqual(['pending', 'connected', 'failed']);
+    } finally {
+      await cm.shutdown();
+      await new Promise<void>((resolve, reject) => {
+        httpServer.close((err) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve();
+        });
+      });
+    }
+  }, 15000);
+
+  it('marks HTTP 401 as failed (not needs-auth) when the user pinned static headers', async () => {
+    const server: HttpServer = createHttpServer((_req, res) => {
+      res.writeHead(401).end('nope');
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const port = (server.address() as HttpAddress).port;
+    const storeDir = await mkdtemp(join(tmpdir(), 'kimi-mcp-oauth-cm-'));
+    const oauthService = new McpOAuthService({ store: new JsonFileStore(storeDir) });
+    const cm = new McpConnectionManager({ oauthService });
+    try {
+      await cm.connectAll({
+        keyed: {
+          transport: 'http',
+          url: `http://127.0.0.1:${port}/mcp`,
+          headers: { 'X-API-Key': 'wrong' },
+          startupTimeoutMs: 5_000,
+        },
+      });
+      expect(cm.get('keyed')?.status).toBe('failed');
+    } finally {
+      await cm.shutdown();
+      await new Promise<void>((resolve, reject) => {
+        server.close((err) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve();
+        });
+      });
+      await rm(storeDir, { recursive: true, force: true });
+    }
+  }, 15000);
+});
+
+describe('Session MCP startup', () => {
+  it('stores default MCP OAuth credentials under the configured Kimi home', async () => {
+    const tmp = await mkdtemp(join(tmpdir(), 'kimi-session-mcp-oauth-home-'));
+    const processHome = join(tmp, 'process-home');
+    const kimiHome = join(tmp, 'kimi-home');
+    const oldHome = process.env['HOME'];
+    process.env['HOME'] = processHome;
+
+    const session = new Session({
+      id: 'test-mcp-oauth',
+      runtime: {
+        kaos: localKaos,
+        osEnv: await detectEnvironmentFromNode(),
+      },
+      homedir: join(tmp, 'session'),
+      kimiHomeDir: kimiHome,
+      cwd: tmp,
+      rpc: sessionRpc(),
+    });
+
+    try {
+      const oauthService = session.mcp.oauthService;
+      if (oauthService === undefined) {
+        throw new Error('Expected session MCP manager to own an OAuth service');
+      }
+      const provider = oauthService.getProvider('gated', 'https://example.com/mcp');
+      provider.saveTokens({
+        access_token: 'session-token',
+        token_type: 'Bearer',
+      } satisfies OAuthTokens);
+
+      await expect(
+        readFile(
+          join(kimiHome, 'credentials', 'mcp', `${provider.storeKey}-tokens.json`),
+          'utf-8',
+        ),
+      ).resolves.toContain('session-token');
+      await expect(
+        readFile(
+          join(processHome, '.kimi-code', 'credentials', 'mcp', `${provider.storeKey}-tokens.json`),
+          'utf-8',
+        ),
+      ).rejects.toMatchObject({ code: 'ENOENT' });
+    } finally {
+      await session.close();
+      if (oldHome === undefined) delete process.env['HOME'];
+      else process.env['HOME'] = oldHome;
+      await rm(tmp, { recursive: true, force: true, maxRetries: 3, retryDelay: 10 });
+    }
+  });
+
+  it('does not block main agent creation on slow MCP startup', async () => {
+    const tmp = await mkdtemp(join(tmpdir(), 'kimi-session-mcp-startup-'));
+    const session = new Session({
+      id: 'test-mcp-slow',
+      runtime: {
+        kaos: localKaos,
+        osEnv: await detectEnvironmentFromNode(),
+      },
+      homedir: join(tmp, 'session'),
+      cwd: tmp,
+      rpc: sessionRpc(),
+      mcpConfig: {
+        servers: {
+          slow: {
+            transport: 'stdio',
+            command: process.execPath,
+            args: [slowStdioFixture],
+            startupTimeoutMs: 2_000,
+          },
+        },
+      },
+    });
+
+    const create = session.createMain();
+    try {
+      const result = await Promise.race([
+        create.then(() => 'resolved' as const),
+        sleep(1_000).then(() => 'blocked' as const),
+      ]);
+      expect(result).toBe('resolved');
+    } finally {
+      await session.close();
+      await Promise.race([create.catch(() => {}), sleep(1_000)]);
+      await rm(tmp, { recursive: true, force: true, maxRetries: 3, retryDelay: 10 });
+    }
+  }, 7000);
+
+  it('waits for initial MCP startup before the first prompt reaches the model', async () => {
+    const tmp = await mkdtemp(join(tmpdir(), 'kimi-session-mcp-prompt-'));
+    const events: SessionRpcEvent[] = [];
+    let resolveTurnEnded!: () => void;
+    const turnEnded = new Promise<void>((resolve) => {
+      resolveTurnEnded = resolve;
+    });
+    const scripted = createScriptedGenerate();
+    scripted.mockNextResponse({ type: 'text', text: 'ready' });
+    const session = new Session({
+      id: 'test-mcp-turn-ended',
+      runtime: {
+        kaos: localKaos,
+        osEnv: await detectEnvironmentFromNode(),
+      },
+      homedir: join(tmp, 'session'),
+      cwd: tmp,
+      rpc: sessionRpc({
+        events,
+        onEvent: (event) => {
+          if (event.type === 'turn.ended') resolveTurnEnded();
+        },
+      }),
+      providerManager: testProviderManager(),
+      mcpConfig: {
+        servers: {
+          slow: {
+            transport: 'stdio',
+            command: process.execPath,
+            args: [stdioFixture],
+            env: { KIMI_TEST_MCP_START_DELAY_MS: '250' },
+            startupTimeoutMs: 2_000,
+          },
+        },
+      },
+    });
+
+    try {
+      const { agent } = await session.createAgent({
+        type: 'main',
+        generate: scripted.generate,
+      });
+      agent.config.update({
+        cwd: tmp,
+        modelAlias: 'mock-model',
+        systemPrompt: 'test system prompt',
+        thinkingLevel: 'off',
+      });
+      // This bare agent gets no profile, so grant MCP access explicitly.
+      agent.tools.setActiveTools(['mcp__*']);
+
+      await new SessionAPIImpl(session).prompt({
+        agentId: 'main',
+        input: [{ type: 'text', text: 'hello' }],
+      });
+      await sleep(100);
+
+      expect(events.some((event) => event.type === 'turn.started')).toBe(true);
+      expect(events.some((event) => event.type === 'turn.step.started')).toBe(false);
+      expect(scripted.calls).toHaveLength(0);
+
+      await Promise.race([
+        turnEnded,
+        sleep(1_000).then(() => {
+          throw new Error('Timed out waiting for turn.ended');
+        }),
+      ]);
+
+      expect(scripted.calls).toHaveLength(1);
+      const toolNames = scripted.calls[0]!.tools.map((tool) => tool.name);
+      expect(toolNames).toContain('mcp__slow__echo');
+    } finally {
+      await session.close();
+      await rm(tmp, { recursive: true, force: true, maxRetries: 3, retryDelay: 10 });
+    }
+  }, 7000);
+
+  it('emits tool.list.updated(mcp.disconnected) when reconnect drops the live tools', async () => {
+    const tmp = await mkdtemp(join(tmpdir(), 'kimi-session-mcp-reconnect-'));
+    const events: SessionRpcEvent[] = [];
+    const session = new Session({
+      id: 'test-mcp-mixed',
+      runtime: {
+        kaos: localKaos,
+        osEnv: await detectEnvironmentFromNode(),
+      },
+      homedir: join(tmp, 'session'),
+      cwd: tmp,
+      rpc: sessionRpc({ events }),
+      mcpConfig: {
+        servers: {
+          good: {
+            transport: 'stdio',
+            command: process.execPath,
+            args: [stdioFixture],
+            startupTimeoutMs: 4_000,
+          },
+        },
+      },
+    });
+
+    try {
+      await session.createMain();
+      // Wait until the initial connect has registered tools.
+      for (let i = 0; i < 50; i++) {
+        const connected = events.some(
+          (e) => e.type === 'tool.list.updated' && e.reason === 'mcp.connected',
+        );
+        if (connected) break;
+        await sleep(50);
+      }
+      const initialConnected = events.filter(
+        (e) => e.type === 'tool.list.updated' && e.reason === 'mcp.connected',
+      ).length;
+      expect(initialConnected).toBeGreaterThanOrEqual(1);
+
+      events.length = 0;
+      await session.mcp.reconnect('good');
+      // The reconnect cycle: pending (tools cleared) → connected (tools back).
+      // Both transitions must surface as tool.list.updated so SDK consumers
+      // watching that event don't see stale tools mid-cycle.
+      const disconnects = events.filter(
+        (e) => e.type === 'tool.list.updated' && e.reason === 'mcp.disconnected',
+      );
+      const connects = events.filter(
+        (e) => e.type === 'tool.list.updated' && e.reason === 'mcp.connected',
+      );
+      expect(disconnects.length).toBeGreaterThanOrEqual(1);
+      expect(connects.length).toBeGreaterThanOrEqual(1);
+    } finally {
+      await session.close();
+      await rm(tmp, { recursive: true, force: true, maxRetries: 3, retryDelay: 10 });
+    }
+  }, 10_000);
+});
+
+function testProviderManager(): ProviderManager {
+  return new ProviderManager({
+    config: {
+      providers: {
+        test: {
+          type: MOCK_PROVIDER.type,
+          apiKey: MOCK_PROVIDER.apiKey,
+        },
+      },
+      models: {
+        [MOCK_PROVIDER.model]: {
+          provider: 'test',
+          model: MOCK_PROVIDER.model,
+          maxContextSize: 1_000_000,
+        },
+      },
+    },
+  });
+}
diff --git a/packages/agent-core/test/mcp/fixtures/crash-after-connect-stdio-server.mjs b/packages/agent-core/test/mcp/fixtures/crash-after-connect-stdio-server.mjs
new file mode 100644
index 000000000..880cdea38
--- /dev/null
+++ b/packages/agent-core/test/mcp/fixtures/crash-after-connect-stdio-server.mjs
@@ -0,0 +1,53 @@
+// Simulates an MCP stdio server that connects normally and then exits a short
+// time later, without going through the protocol shutdown handshake. Used to
+// drive the "transport disconnected after connect" path in
+// McpConnectionManager.
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const server = new McpServer({ name: 'crash-after-connect', version: '0.0.1' });
+
+const exitCode = Number.parseInt(process.env['KIMI_TEST_MCP_EXIT_CODE'] ?? '1', 10);
+const stderrBanner = process.env['KIMI_TEST_MCP_STDERR'];
+
+function exitWithBanner() {
+  if (stderrBanner !== undefined) {
+    process.stderr.write(`${stderrBanner}\n`);
+  }
+  process.exit(exitCode);
+}
+
+server.registerTool(
+  'echo',
+  {
+    description: 'Echoes input text',
+    inputSchema: { text: z.string() },
+  },
+  ({ text }) => ({
+    content: [{ type: 'text', text }],
+  }),
+);
+
+// Returns a normal reply, then exits on the next macrotask so the response is
+// fully flushed to stdout before the pipe closes. Lets a test deterministically
+// trigger "post-handshake disconnect" without racing against startup timing.
+server.registerTool(
+  'exit_after_reply',
+  {
+    description: 'Replies, then exits the process',
+    inputSchema: {},
+  },
+  () => {
+    setImmediate(exitWithBanner);
+    return { content: [{ type: 'text', text: 'bye' }] };
+  },
+);
+
+await server.connect(new StdioServerTransport());
+
+const exitAfterMsRaw = process.env['KIMI_TEST_MCP_EXIT_AFTER_MS'];
+if (exitAfterMsRaw !== undefined) {
+  setTimeout(exitWithBanner, Number.parseInt(exitAfterMsRaw, 10));
+}
diff --git a/packages/agent-core/test/mcp/fixtures/hanging-list-stdio-server.mjs b/packages/agent-core/test/mcp/fixtures/hanging-list-stdio-server.mjs
new file mode 100644
index 000000000..cc7f6e1ef
--- /dev/null
+++ b/packages/agent-core/test/mcp/fixtures/hanging-list-stdio-server.mjs
@@ -0,0 +1,38 @@
+// Completes the MCP initialize handshake, then leaves tools/list pending.
+
+import { createInterface } from 'node:readline';
+
+const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+for await (const line of lines) {
+  const message = JSON.parse(line);
+
+  if (message.method === 'initialize' && message.id !== undefined) {
+    send({
+      jsonrpc: '2.0',
+      id: message.id,
+      result: {
+        protocolVersion: message.params?.protocolVersion ?? '2025-11-25',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'hanging-list-stdio', version: '0.0.1' },
+      },
+    });
+    continue;
+  }
+
+  if (message.method === 'tools/list') {
+    continue;
+  }
+
+  if (message.id !== undefined) {
+    send({
+      jsonrpc: '2.0',
+      id: message.id,
+      error: { code: -32601, message: `Unsupported method: ${message.method}` },
+    });
+  }
+}
diff --git a/packages/agent-core/test/mcp/fixtures/mock-stdio-server.mjs b/packages/agent-core/test/mcp/fixtures/mock-stdio-server.mjs
new file mode 100644
index 000000000..24bbfd328
--- /dev/null
+++ b/packages/agent-core/test/mcp/fixtures/mock-stdio-server.mjs
@@ -0,0 +1,55 @@
+// Minimal MCP stdio server fixture for StdioMcpClient tests.
+// Exposes:
+//   - echo(text: string) -> text content
+//   - boom() -> isError: true
+//   - read_env(name: string) -> the value of process.env[name] (used to assert
+//     that StdioClientTransport `env` is honoured)
+
+import { setTimeout as sleep } from 'node:timers/promises';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const delayMs = Number.parseInt(process.env['KIMI_TEST_MCP_START_DELAY_MS'] ?? '0', 10);
+if (delayMs > 0) {
+  await sleep(delayMs);
+}
+
+const server = new McpServer({ name: 'mock-stdio', version: '0.0.1' });
+
+server.registerTool(
+  'echo',
+  {
+    description: 'Echoes input text',
+    inputSchema: { text: z.string() },
+  },
+  ({ text }) => ({
+    content: [{ type: 'text', text }],
+  }),
+);
+
+server.registerTool(
+  'boom',
+  {
+    description: 'Always returns an error result',
+    inputSchema: {},
+  },
+  () => ({
+    content: [{ type: 'text', text: 'boom!' }],
+    isError: true,
+  }),
+);
+
+server.registerTool(
+  'read_env',
+  {
+    description: 'Returns the value of process.env[name], or empty string',
+    inputSchema: { name: z.string() },
+  },
+  ({ name }) => ({
+    content: [{ type: 'text', text: process.env[name] ?? '' }],
+  }),
+);
+
+await server.connect(new StdioServerTransport());
diff --git a/packages/agent-core/test/mcp/fixtures/slow-stdio-server.mjs b/packages/agent-core/test/mcp/fixtures/slow-stdio-server.mjs
new file mode 100644
index 000000000..915a7ac61
--- /dev/null
+++ b/packages/agent-core/test/mcp/fixtures/slow-stdio-server.mjs
@@ -0,0 +1,26 @@
+// Simulates a slow-starting MCP server: sleeps before completing the
+// initialize handshake so startupTimeoutMs in McpConnectionManager fires.
+
+import { setTimeout as sleep } from 'node:timers/promises';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const delayMs = Number.parseInt(process.env['KIMI_TEST_MCP_START_DELAY_MS'] ?? '2000', 10);
+await sleep(delayMs);
+
+const server = new McpServer({ name: 'slow-stdio', version: '0.0.1' });
+
+server.registerTool(
+  'echo',
+  {
+    description: 'Echoes input text',
+    inputSchema: { text: z.string() },
+  },
+  ({ text }) => ({
+    content: [{ type: 'text', text }],
+  }),
+);
+
+await server.connect(new StdioServerTransport());
diff --git a/packages/agent-core/test/mcp/fixtures/stderr-then-exit-stdio-server.mjs b/packages/agent-core/test/mcp/fixtures/stderr-then-exit-stdio-server.mjs
new file mode 100644
index 000000000..3531ce193
--- /dev/null
+++ b/packages/agent-core/test/mcp/fixtures/stderr-then-exit-stdio-server.mjs
@@ -0,0 +1,7 @@
+// Simulates a misconfigured MCP stdio server: writes a banner to stderr, then
+// exits before completing the protocol handshake. Used to verify that
+// StdioMcpClient captures stderr and surfaces it on connect failure.
+
+const banner = process.env['KIMI_TEST_MCP_STDERR'] ?? 'fatal: missing API token';
+process.stderr.write(`${banner}\n`);
+process.exit(2);
diff --git a/packages/agent-core/test/mcp/oauth-store.test.ts b/packages/agent-core/test/mcp/oauth-store.test.ts
new file mode 100644
index 000000000..38dbc3388
--- /dev/null
+++ b/packages/agent-core/test/mcp/oauth-store.test.ts
@@ -0,0 +1,155 @@
+import { mkdtemp, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import type { OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+import { McpOAuthClientProvider, McpOAuthService } from '../../src/mcp/oauth';
+import { JsonFileStore, sanitizeStoreKey } from '../../src/mcp/oauth/store';
+
+describe('sanitizeStoreKey', () => {
+  it('strips path traversal segments', () => {
+    expect(sanitizeStoreKey('../../etc/passwd')).toBe('passwd');
+    expect(sanitizeStoreKey('a/b/c')).toBe('c');
+  });
+
+  it('replaces unsafe characters with underscores and collapses runs', () => {
+    expect(sanitizeStoreKey('My Server!Name')).toBe('My_Server_Name');
+  });
+
+  it('rejects names that collapse to empty', () => {
+    expect(() => sanitizeStoreKey('')).toThrow(/Invalid/);
+  });
+
+  it('rewrites a leading dot into a safe underscore-prefixed name', () => {
+    expect(sanitizeStoreKey('.dot')).toBe('_dot');
+  });
+});
+
+describe('JsonFileStore', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'kimi-mcp-oauth-store-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('round-trips JSON data via the named file', () => {
+    const store = new JsonFileStore(dir);
+    store.write('foo.json', { hello: 'world' });
+    expect(store.read('foo.json')).toEqual({ hello: 'world' });
+  });
+
+  it('returns undefined when a file is missing or unreadable JSON', () => {
+    const store = new JsonFileStore(dir);
+    expect(store.read('missing.json')).toBeUndefined();
+  });
+
+  it('writes files with 0600 permissions on POSIX', async () => {
+    if (process.platform === 'win32') return; // file modes unreliable on Windows
+    const store = new JsonFileStore(dir);
+    store.write('secret.json', { token: 'abc' });
+    const info = await stat(join(dir, 'secret.json'));
+    expect(info.mode & 0o777).toBe(0o600);
+  });
+
+  it('removes existing files without throwing on already-missing files', () => {
+    const store = new JsonFileStore(dir);
+    store.write('keep.json', { a: 1 });
+    expect(store.read('keep.json')).toEqual({ a: 1 });
+    store.remove('keep.json');
+    expect(store.read('keep.json')).toBeUndefined();
+    store.remove('keep.json'); // no throw
+  });
+});
+
+describe('MCP OAuth credential identity', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'kimi-mcp-oauth-identity-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('isolates tokens for the same server name on different URLs', () => {
+    const store = new JsonFileStore(dir);
+    const first = new McpOAuthClientProvider({
+      serverName: 'linear',
+      serverUrl: 'https://first.example.com/mcp',
+      store,
+    });
+    const second = new McpOAuthClientProvider({
+      serverName: 'linear',
+      serverUrl: 'https://second.example.com/mcp',
+      store,
+    });
+
+    first.saveTokens(token('first-token'));
+    second.saveTokens(token('second-token'));
+
+    expect(first.storeKey).not.toBe(second.storeKey);
+    expect(first.tokens()?.access_token).toBe('first-token');
+    expect(second.tokens()?.access_token).toBe('second-token');
+  });
+
+  it('isolates tokens when distinct server names sanitize to the same prefix', () => {
+    const store = new JsonFileStore(dir);
+    const first = new McpOAuthClientProvider({
+      serverName: 'team mcp',
+      serverUrl: 'https://same.example.com/mcp',
+      store,
+    });
+    const second = new McpOAuthClientProvider({
+      serverName: 'team!mcp',
+      serverUrl: 'https://same.example.com/mcp',
+      store,
+    });
+
+    first.saveTokens(token('space-token'));
+    second.saveTokens(token('bang-token'));
+
+    expect(first.storeKey).not.toBe(second.storeKey);
+    expect(first.tokens()?.access_token).toBe('space-token');
+    expect(second.tokens()?.access_token).toBe('bang-token');
+  });
+
+  it('scopes hasTokens to the server URL, not just the configured name', () => {
+    const service = new McpOAuthService({ store: new JsonFileStore(dir) });
+    service
+      .getProvider('linear', 'https://first.example.com/mcp')
+      .saveTokens(token('first-token'));
+
+    expect(service.hasTokens('linear', 'https://first.example.com/mcp')).toBe(true);
+    expect(service.hasTokens('linear', 'https://second.example.com/mcp')).toBe(false);
+  });
+
+  it('uses stored client redirect URI when no active OAuth callback is running', () => {
+    const provider = new McpOAuthClientProvider({
+      serverName: 'notion',
+      serverUrl: 'https://mcp.notion.com/mcp',
+      store: new JsonFileStore(dir),
+    });
+    provider.saveClientInformation({
+      client_id: 'cached-client',
+      redirect_uris: ['http://127.0.0.1:45678/callback'],
+      token_endpoint_auth_method: 'none',
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+    });
+
+    expect(provider.redirectUrl).toBe('http://127.0.0.1:45678/callback');
+    expect(provider.clientMetadata.redirect_uris).toEqual(['http://127.0.0.1:45678/callback']);
+  });
+});
+
+function token(accessToken: string): OAuthTokens {
+  return {
+    access_token: accessToken,
+    token_type: 'Bearer',
+  };
+}
diff --git a/packages/agent-core/test/mcp/output.test.ts b/packages/agent-core/test/mcp/output.test.ts
new file mode 100644
index 000000000..3fece7048
--- /dev/null
+++ b/packages/agent-core/test/mcp/output.test.ts
@@ -0,0 +1,324 @@
+import { ContentBlockSchema } from '@modelcontextprotocol/sdk/types.js';
+import type { ContentPart } from '@moonshot-ai/kosong';
+import { describe, expect, test } from 'vitest';
+
+import { convertMCPContentBlock, mcpResultToExecutableOutput } from '../../src/mcp/output';
+import type { MCPContentBlock, MCPToolResult } from '../../src/mcp/types';
+
+const MCP_OUTPUT_TRUNCATED_TEXT =
+  '\n\n[Output truncated: exceeded 100000 character limit. ' +
+  'Use pagination or more specific queries to get remaining content.]';
+
+/**
+ * Assert a test fixture matches the MCP SDK's ContentBlock schema. This
+ * guards against fixtures that drift from the real protocol shape — exactly
+ * the failure mode that previously hid the EmbeddedResource bug.
+ */
+function assertValidMcpBlock<T extends MCPContentBlock>(block: T): T {
+  const parsed = ContentBlockSchema.safeParse(block);
+  if (!parsed.success) {
+    throw new Error(`fixture is not a valid MCP ContentBlock: ${parsed.error.message}`);
+  }
+  return block;
+}
+
+describe('convertMCPContentBlock', () => {
+  test('converts text block to TextPart', () => {
+    const block: MCPContentBlock = { type: 'text', text: 'hello' };
+    expect(convertMCPContentBlock(block)).toEqual({ type: 'text', text: 'hello' });
+  });
+
+  test('converts image block with mimeType to image data URI', () => {
+    const block: MCPContentBlock = { type: 'image', data: 'AAA', mimeType: 'image/jpeg' };
+    expect(convertMCPContentBlock(block)).toEqual({
+      type: 'image_url',
+      imageUrl: { url: 'data:image/jpeg;base64,AAA' },
+    });
+  });
+
+  test('image block without mimeType defaults to image/png', () => {
+    const block: MCPContentBlock = { type: 'image', data: 'AAA' };
+    expect(convertMCPContentBlock(block)).toEqual({
+      type: 'image_url',
+      imageUrl: { url: 'data:image/png;base64,AAA' },
+    });
+  });
+
+  test('converts audio block to AudioURLPart with audio/mpeg default', () => {
+    const block: MCPContentBlock = { type: 'audio', data: 'BBB' };
+    expect(convertMCPContentBlock(block)).toEqual({
+      type: 'audio_url',
+      audioUrl: { url: 'data:audio/mpeg;base64,BBB' },
+    });
+  });
+
+  test('converts audio block with custom mimeType', () => {
+    const block: MCPContentBlock = { type: 'audio', data: 'BBB', mimeType: 'audio/wav' };
+    expect(convertMCPContentBlock(block)).toEqual({
+      type: 'audio_url',
+      audioUrl: { url: 'data:audio/wav;base64,BBB' },
+    });
+  });
+
+  test('converts text EmbeddedResource to TextPart', () => {
+    const block = assertValidMcpBlock({
+      type: 'resource',
+      resource: {
+        uri: 'file:///project/src/main.rs',
+        mimeType: 'text/x-rust',
+        text: 'fn main() {}',
+      },
+    });
+    expect(convertMCPContentBlock(block)).toEqual({ type: 'text', text: 'fn main() {}' });
+  });
+
+  test('text EmbeddedResource preserves text regardless of mimeType', () => {
+    const block = assertValidMcpBlock({
+      type: 'resource',
+      resource: { uri: 'file:///x.json', mimeType: 'application/json', text: '{"a":1}' },
+    });
+    expect(convertMCPContentBlock(block)).toEqual({ type: 'text', text: '{"a":1}' });
+  });
+
+  test('converts blob EmbeddedResource with image/* mimeType to ImageURLPart', () => {
+    const block = assertValidMcpBlock({
+      type: 'resource',
+      resource: { uri: 'file:///pic.webp', mimeType: 'image/webp', blob: 'III' },
+    });
+    expect(convertMCPContentBlock(block)).toEqual({
+      type: 'image_url',
+      imageUrl: { url: 'data:image/webp;base64,III' },
+    });
+  });
+
+  test('converts blob EmbeddedResource with audio/* mimeType to AudioURLPart', () => {
+    const block = assertValidMcpBlock({
+      type: 'resource',
+      resource: { uri: 'file:///clip.wav', mimeType: 'audio/wav', blob: 'AUD' },
+    });
+    expect(convertMCPContentBlock(block)).toEqual({
+      type: 'audio_url',
+      audioUrl: { url: 'data:audio/wav;base64,AUD' },
+    });
+  });
+
+  test('converts blob EmbeddedResource with video/* mimeType to VideoURLPart', () => {
+    const block = assertValidMcpBlock({
+      type: 'resource',
+      resource: { uri: 'file:///clip.mp4', mimeType: 'video/mp4', blob: 'VID' },
+    });
+    expect(convertMCPContentBlock(block)).toEqual({
+      type: 'video_url',
+      videoUrl: { url: 'data:video/mp4;base64,VID' },
+    });
+  });
+
+  test('returns null for blob EmbeddedResource with unsupported mimeType', () => {
+    const block = assertValidMcpBlock({
+      type: 'resource',
+      resource: { uri: 'file:///doc.pdf', mimeType: 'application/pdf', blob: 'XXX' },
+    });
+    expect(convertMCPContentBlock(block)).toBeNull();
+  });
+
+  test('blob EmbeddedResource defaults to application/octet-stream and returns null', () => {
+    const block = assertValidMcpBlock({
+      type: 'resource',
+      resource: { uri: 'file:///unknown', blob: 'XXX' },
+    });
+    expect(convertMCPContentBlock(block)).toBeNull();
+  });
+
+  test('returns null for resource block missing resource field', () => {
+    // Spec-illegal shape — guards the runtime branch, so skip schema validation.
+    const block = { type: 'resource' } as MCPContentBlock;
+    expect(convertMCPContentBlock(block)).toBeNull();
+  });
+
+  test('converts resource_link with image/* mimeType to ImageURLPart with URL', () => {
+    const block = assertValidMcpBlock({
+      type: 'resource_link',
+      name: 'img.png',
+      uri: 'https://example.com/img.png',
+      mimeType: 'image/png',
+    });
+    expect(convertMCPContentBlock(block)).toEqual({
+      type: 'image_url',
+      imageUrl: { url: 'https://example.com/img.png' },
+    });
+  });
+
+  test('converts resource_link with audio/* mimeType to AudioURLPart with URL', () => {
+    const block = assertValidMcpBlock({
+      type: 'resource_link',
+      name: 'audio.mp3',
+      uri: 'https://example.com/audio.mp3',
+      mimeType: 'audio/mpeg',
+    });
+    expect(convertMCPContentBlock(block)).toEqual({
+      type: 'audio_url',
+      audioUrl: { url: 'https://example.com/audio.mp3' },
+    });
+  });
+
+  test('converts resource_link with video/* mimeType to VideoURLPart with URL', () => {
+    const block = assertValidMcpBlock({
+      type: 'resource_link',
+      name: 'video.mp4',
+      uri: 'https://example.com/video.mp4',
+      mimeType: 'video/mp4',
+    });
+    expect(convertMCPContentBlock(block)).toEqual({
+      type: 'video_url',
+      videoUrl: { url: 'https://example.com/video.mp4' },
+    });
+  });
+
+  test('returns null for resource_link with unsupported mimeType', () => {
+    const block = assertValidMcpBlock({
+      type: 'resource_link',
+      name: 'file.bin',
+      uri: 'https://example.com/file.bin',
+      mimeType: 'application/octet-stream',
+    });
+    expect(convertMCPContentBlock(block)).toBeNull();
+  });
+
+  test('returns null for unknown block type', () => {
+    const block: MCPContentBlock = { type: 'fancy_new_type', text: 'whatever' };
+    expect(convertMCPContentBlock(block)).toBeNull();
+  });
+
+  test('returns null for text block missing text field', () => {
+    const block: MCPContentBlock = { type: 'text' };
+    expect(convertMCPContentBlock(block)).toBeNull();
+  });
+
+  test('returns null for image block missing data field', () => {
+    const block: MCPContentBlock = { type: 'image', mimeType: 'image/png' };
+    expect(convertMCPContentBlock(block)).toBeNull();
+  });
+});
+
+describe('mcpResultToExecutableOutput', () => {
+  function result(content: MCPContentBlock[], isError = false): MCPToolResult {
+    return { content, isError };
+  }
+
+  test('collapses a single text part into a plain string', () => {
+    const out = mcpResultToExecutableOutput(result([{ type: 'text', text: 'hello' }]), 'mcp__s__t');
+    expect(out).toEqual({ output: 'hello', isError: false });
+  });
+
+  test('propagates isError=true on the success-shape return', () => {
+    const out = mcpResultToExecutableOutput(
+      result([{ type: 'text', text: 'oops' }], true),
+      'mcp__s__t',
+    );
+    expect(out).toEqual({ output: 'oops', isError: true });
+  });
+
+  test('returns an empty string when the content array is empty', () => {
+    const out = mcpResultToExecutableOutput(result([]), 'mcp__s__t');
+    // No parts survive; collapseSingleText has nothing to collapse so the
+    // ContentPart[] branch wins. An empty array is the model-visible signal
+    // that the tool returned no content.
+    expect(out).toEqual({ output: [], isError: false });
+  });
+
+  test('drops unconvertible blocks and keeps the rest', () => {
+    const out = mcpResultToExecutableOutput(
+      result([
+        { type: 'text', text: 'kept' },
+        { type: 'fancy_new_type', text: 'dropped' },
+      ]),
+      'mcp__s__t',
+    );
+    expect(out).toEqual({ output: 'kept', isError: false });
+  });
+
+  test('wraps media-only output in mcp_tool_result tags using the qualified name', () => {
+    const out = mcpResultToExecutableOutput(
+      result([{ type: 'image', data: 'AAA', mimeType: 'image/png' }]),
+      'mcp__github__create_pr',
+    );
+    expect(out.isError).toBe(false);
+    expect(out.output).toEqual([
+      { type: 'text', text: '<mcp_tool_result name="mcp__github__create_pr">' },
+      { type: 'image_url', imageUrl: { url: 'data:image/png;base64,AAA' } },
+      { type: 'text', text: '</mcp_tool_result>' },
+    ]);
+  });
+
+  test('does NOT wrap when a non-empty text part accompanies the media', () => {
+    const out = mcpResultToExecutableOutput(
+      result([
+        { type: 'text', text: 'caption' },
+        { type: 'image', data: 'AAA', mimeType: 'image/png' },
+      ]),
+      'mcp__s__t',
+    );
+    expect(out.output).toEqual([
+      { type: 'text', text: 'caption' },
+      { type: 'image_url', imageUrl: { url: 'data:image/png;base64,AAA' } },
+    ]);
+  });
+
+  test('an empty-text companion still triggers the wrap', () => {
+    const out = mcpResultToExecutableOutput(
+      result([
+        { type: 'text', text: '' },
+        { type: 'image', data: 'AAA', mimeType: 'image/png' },
+      ]),
+      'mcp__s__t',
+    );
+    const parts = out.output as ContentPart[];
+    expect(parts[0]).toEqual({ type: 'text', text: '<mcp_tool_result name="mcp__s__t">' });
+    expect(parts.at(-1)).toEqual({ type: 'text', text: '</mcp_tool_result>' });
+  });
+
+  test('truncates oversized text and merges the notice into the surviving text part', () => {
+    const out = mcpResultToExecutableOutput(
+      result([{ type: 'text', text: 'x'.repeat(100_001) }]),
+      'mcp__s__t',
+    );
+    // The notice merges into the single text part so collapseSingleText still
+    // emits a plain string — the very common "single oversized text" case.
+    expect(out.output).toBe('x'.repeat(100_000) + MCP_OUTPUT_TRUNCATED_TEXT);
+  });
+
+  test('drops oversized binary parts in favor of a per-part notice without touching the text budget', () => {
+    // 14 MiB base64 ≈ 10.5 MiB raw — just above the 10 MiB per-part cap.
+    const huge = 'x'.repeat(14 * 1024 * 1024);
+    const out = mcpResultToExecutableOutput(
+      result([{ type: 'image', data: huge, mimeType: 'image/png' }]),
+      'mcp__s__big',
+    );
+    const parts = out.output as ContentPart[];
+    expect(parts).toHaveLength(3);
+    expect(parts[0]).toEqual({ type: 'text', text: '<mcp_tool_result name="mcp__s__big">' });
+    expect(parts[1]?.type).toBe('text');
+    expect((parts[1] as { text: string }).text).toContain('image_url dropped');
+    expect((parts[1] as { text: string }).text).toContain('10 MB per-part limit');
+    expect(parts[2]).toEqual({ type: 'text', text: '</mcp_tool_result>' });
+    // The text-budget marker must NOT appear — only the binary part was dropped.
+    const joined = parts.map((p) => (p.type === 'text' ? p.text : '')).join('');
+    expect(joined).not.toContain('Output truncated');
+  });
+
+  test('binary part within the per-part cap survives intact alongside oversized text', () => {
+    const out = mcpResultToExecutableOutput(
+      result([
+        { type: 'text', text: 'A'.repeat(100_000) },
+        { type: 'image', data: 'B'.repeat(500_000), mimeType: 'image/png' },
+      ]),
+      'mcp__s__t',
+    );
+    // Text fills the entire budget; image still rides through; no truncation
+    // marker (text was exactly 100K, not over).
+    expect(out.output).toEqual([
+      { type: 'text', text: 'A'.repeat(100_000) },
+      { type: 'image_url', imageUrl: { url: 'data:image/png;base64,' + 'B'.repeat(500_000) } },
+    ]);
+  });
+});
diff --git a/packages/agent-core/test/mcp/tool-manager-mcp.test.ts b/packages/agent-core/test/mcp/tool-manager-mcp.test.ts
new file mode 100644
index 000000000..58d26523a
--- /dev/null
+++ b/packages/agent-core/test/mcp/tool-manager-mcp.test.ts
@@ -0,0 +1,610 @@
+import type { ContentPart, Tool } from '@moonshot-ai/kosong';
+import { describe, expect, it } from 'vitest';
+
+import type { Agent } from '../../src/agent';
+import { ToolManager } from '../../src/agent/tool';
+import type { MCPClient } from '../../src/mcp/types';
+import { testAgent } from '../agent/harness/agent';
+import { executeTool } from '../tools/fixtures/execute-tool';
+
+const MCP_OUTPUT_TRUNCATED_TEXT =
+  '\n\n[Output truncated: exceeded 100000 character limit. ' +
+  'Use pagination or more specific queries to get remaining content.]';
+
+function fakeAgent(calls: unknown[] = []): Agent {
+  return {
+    records: {
+      logRecord(record: unknown) {
+        calls.push(record);
+      },
+    },
+    config: {
+      data: () => ({ provider: undefined }),
+    },
+  } as unknown as Agent;
+}
+
+function fakeClient(): MCPClient {
+  return {
+    async listTools() {
+      return [
+        {
+          name: 'echo',
+          description: 'Echoes back',
+          inputSchema: {
+            type: 'object',
+            properties: { text: { type: 'string' } },
+            required: ['text'],
+          },
+        },
+        {
+          name: 'noop',
+          description: 'Does nothing',
+          inputSchema: { type: 'object', properties: {} },
+        },
+      ];
+    },
+    async callTool(name, args) {
+      if (name === 'echo') {
+        return { content: [{ type: 'text', text: String(args['text']) }], isError: false };
+      }
+      return { content: [{ type: 'text', text: 'ok' }], isError: false };
+    },
+  };
+}
+
+// Mirrors `connection-manager.connectAndDiscoverTools` — projects an MCP
+// client's `listTools()` output into the kosong `Tool` shape that
+// `ToolManager.registerMcpServer` expects. Tests can hand the same client into
+// `registerMcpServer` so the wrapped `execute` flow hits a real `callTool`.
+async function discoverTools(client: MCPClient): Promise<Tool[]> {
+  const defs = await client.listTools();
+  return defs.map((d) => ({
+    name: d.name,
+    description: d.description,
+    parameters: d.inputSchema as Record<string, unknown>,
+  }));
+}
+
+describe('ToolManager MCP integration', () => {
+  it('registers MCP tools under qualified names with source=mcp', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    const client = fakeClient();
+    tm.registerMcpServer('local server', client, await discoverTools(client));
+
+    const infos = [...tm.toolInfos()].filter((i) => i.source === 'mcp');
+    expect(infos.map((i) => i.name).toSorted()).toEqual([
+      'mcp__local_server__echo',
+      'mcp__local_server__noop',
+    ]);
+    for (const info of infos) {
+      expect(info.active).toBe(true);
+    }
+
+    const loop = tm.loopTools.map((t) => t.name);
+    expect(loop).toContain('mcp__local_server__echo');
+    expect(loop).toContain('mcp__local_server__noop');
+  });
+
+  it('respects enabledTools filter when registering', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    const client = fakeClient();
+    tm.registerMcpServer('s', client, await discoverTools(client), new Set(['echo']));
+
+    const mcpNames = [...tm.toolInfos()].filter((i) => i.source === 'mcp').map((i) => i.name);
+    expect(mcpNames).toEqual(['mcp__s__echo']);
+  });
+
+  it('unregisterMcpServer removes every tool the server contributed', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    const client = fakeClient();
+
+    const before = tm.registerMcpServer('s', client, await discoverTools(client));
+    expect(before.registered.length).toBe(2);
+    expect(before.collisions).toEqual([]);
+    expect(tm.loopTools.length).toBe(2);
+
+    expect(tm.unregisterMcpServer('s')).toBe(true);
+    expect([...tm.toolInfos()].filter((i) => i.source === 'mcp')).toEqual([]);
+    expect(tm.loopTools).toEqual([]);
+    expect(tm.unregisterMcpServer('s')).toBe(false);
+  });
+
+  it('reports same-server qualified-name collisions and keeps only the first tool', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    const colliding: MCPClient = {
+      async listTools() {
+        return [
+          { name: 'a b', description: 'first', inputSchema: { type: 'object', properties: {} } },
+          {
+            name: 'a__b',
+            description: 'collides after collapse',
+            inputSchema: { type: 'object', properties: {} },
+          },
+        ];
+      },
+      async callTool() {
+        return { content: [{ type: 'text', text: 'ok' }], isError: false };
+      },
+    };
+    const result = tm.registerMcpServer('srv', colliding, await discoverTools(colliding));
+
+    expect(result.registered).toEqual(['mcp__srv__a_b']);
+    expect(result.collisions).toEqual([
+      {
+        qualified: 'mcp__srv__a_b',
+        toolName: 'a__b',
+        collidesWith: { kind: 'same_server', toolName: 'a b' },
+      },
+    ]);
+    const mcpNames = [...tm.toolInfos()].filter((i) => i.source === 'mcp').map((i) => i.name);
+    expect(mcpNames).toEqual(['mcp__srv__a_b']);
+  });
+
+  it('reports cross-server collisions instead of silently overwriting another server tool', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    const firstClient: MCPClient = {
+      async listTools() {
+        return [
+          { name: 'shared', description: 'first', inputSchema: { type: 'object', properties: {} } },
+        ];
+      },
+      async callTool() {
+        return { content: [{ type: 'text', text: 'first' }], isError: false };
+      },
+    };
+    const secondClient: MCPClient = {
+      async listTools() {
+        return [
+          {
+            name: 'shared',
+            description: 'second',
+            inputSchema: { type: 'object', properties: {} },
+          },
+        ];
+      },
+      async callTool() {
+        return { content: [{ type: 'text', text: 'second' }], isError: false };
+      },
+    };
+
+    // Both servers collapse to the same sanitized form ("srv_a"), so the
+    // qualified name `mcp__srv_a__shared` is contested between them.
+    tm.registerMcpServer('srv a', firstClient, await discoverTools(firstClient));
+    const result = tm.registerMcpServer('srv__a', secondClient, await discoverTools(secondClient));
+
+    expect(result.registered).toEqual([]);
+    expect(result.collisions).toEqual([
+      {
+        qualified: 'mcp__srv_a__shared',
+        toolName: 'shared',
+        collidesWith: { kind: 'other_server', serverName: 'srv a' },
+      },
+    ]);
+    // First server's tool still wins and stays callable.
+    expect(tm.loopTools.map((t) => t.name)).toEqual(['mcp__srv_a__shared']);
+  });
+
+  it('re-registering the same server replaces its previous tool set', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    const firstClient = fakeClient();
+    const secondClient: MCPClient = {
+      async listTools() {
+        return [
+          {
+            name: 'only',
+            description: 'Sole tool',
+            inputSchema: { type: 'object', properties: {} },
+          },
+        ];
+      },
+      async callTool() {
+        return { content: [], isError: false };
+      },
+    };
+
+    tm.registerMcpServer('s', firstClient, await discoverTools(firstClient));
+    tm.registerMcpServer('s', secondClient, await discoverTools(secondClient));
+
+    const mcpNames = [...tm.toolInfos()].filter((i) => i.source === 'mcp').map((i) => i.name);
+    expect(mcpNames).toEqual(['mcp__s__only']);
+  });
+
+  it('does not write set_active_tools records when registering an MCP server', async () => {
+    const calls: unknown[] = [];
+    const tm = new ToolManager(fakeAgent(calls));
+    const client = fakeClient();
+    tm.registerMcpServer('s', client, await discoverTools(client));
+
+    // MCP tools live in mcpTools map, separate from enabledTools, so
+    // registering an MCP server does not mutate enabledTools and does not
+    // emit a set_active_tools record. This is what keeps wire.jsonl free of
+    // synthetic mutations on session resume.
+    expect(calls).not.toContainEqual(
+      expect.objectContaining({ type: 'tools.set_active_tools' }),
+    );
+    expect(calls).not.toContainEqual(
+      expect.objectContaining({ type: 'tools.register_mcp_server' }),
+    );
+  });
+
+  it('re-enables all registered MCP tools when re-registering a server', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    const firstClient = fakeClient();
+    const secondClient = fakeClient();
+
+    tm.registerMcpServer('s', firstClient, await discoverTools(firstClient));
+    tm.unregisterMcpServer('s');
+    expect(tm.loopTools).toEqual([]);
+    tm.registerMcpServer('s', secondClient, await discoverTools(secondClient));
+
+    const mcpInfos = [...tm.toolInfos()]
+      .filter((i) => i.source === 'mcp')
+      .map((i) => ({ name: i.name, active: i.active }));
+    expect(mcpInfos).toEqual([
+      { name: 'mcp__s__echo', active: true },
+      { name: 'mcp__s__noop', active: true },
+    ]);
+    expect(tm.loopTools.map((t) => t.name)).toEqual(['mcp__s__echo', 'mcp__s__noop']);
+  });
+
+  it('executing a wrapped MCP tool dispatches to client.callTool', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    const client = fakeClient();
+    tm.registerMcpServer('s', client, await discoverTools(client));
+    const echo = tm.loopTools.find((t) => t.name === 'mcp__s__echo');
+    expect(echo).toBeDefined();
+
+    const result = await executeTool(echo!, {
+      turnId: '1',
+      toolCallId: 'tc-1',
+      args: { text: 'hello world' },
+      signal: new AbortController().signal,
+    });
+    expect(result.isError).toBe(false);
+    expect(result.output).toBe('hello world');
+  });
+
+  it('truncates oversized MCP text output with a clear notice', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    const client: MCPClient = {
+      async listTools() {
+        return [
+          {
+            name: 'big',
+            description: 'Returns a huge text',
+            inputSchema: { type: 'object', properties: {} },
+          },
+        ];
+      },
+      async callTool() {
+        return {
+          content: [{ type: 'text', text: 'x'.repeat(100_001) }],
+          isError: false,
+        };
+      },
+    };
+    tm.registerMcpServer('s', client, await discoverTools(client));
+    const big = tm.loopTools.find((t) => t.name === 'mcp__s__big');
+
+    const result = await executeTool(big!, {
+      turnId: '1',
+      toolCallId: 'tc-big-text',
+      args: {},
+      signal: new AbortController().signal,
+    });
+
+    // applyOutputLimits slices to the budget and merges the truncation
+    // notice into the last text part so the single-text case still collapses
+    // to a plain string.
+    expect(result.isError).toBe(false);
+    expect(result.output).toBe('x'.repeat(100_000) + MCP_OUTPUT_TRUNCATED_TEXT);
+  });
+
+  it('wraps modestly-sized MCP image output in mcp_tool_result companions', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    const client: MCPClient = {
+      async listTools() {
+        return [
+          {
+            name: 'snap',
+            description: 'Returns a small image',
+            inputSchema: { type: 'object', properties: {} },
+          },
+        ];
+      },
+      async callTool() {
+        return {
+          content: [{ type: 'image', data: 'x'.repeat(100_000), mimeType: 'image/png' }],
+          isError: false,
+        };
+      },
+    };
+    tm.registerMcpServer('s', client, await discoverTools(client));
+    const snap = tm.loopTools.find((t) => t.name === 'mcp__s__snap');
+
+    const result = await executeTool(snap!, {
+      turnId: '1',
+      toolCallId: 'tc-small-image',
+      args: {},
+      signal: new AbortController().signal,
+    });
+
+    expect(result.isError).toBe(false);
+    expect(Array.isArray(result.output)).toBe(true);
+    const parts = result.output as ContentPart[];
+    // mcpResultToExecutableOutput wraps media-only output in text companions
+    // tagged with the qualified tool name; the image_url itself is preserved
+    // intact (~75 KiB raw, well below the 10 MiB per-part cap).
+    expect(parts).toEqual([
+      { type: 'text', text: '<mcp_tool_result name="mcp__s__snap">' },
+      {
+        type: 'image_url',
+        imageUrl: { url: 'data:image/png;base64,' + 'x'.repeat(100_000) },
+      },
+      { type: 'text', text: '</mcp_tool_result>' },
+    ]);
+  });
+
+  it('drops MCP binary parts exceeding the per-part byte cap and substitutes a notice', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    // 14 MiB base64 ≈ 10.5 MiB raw — just above the 10 MiB per-part cap.
+    const huge = 'x'.repeat(14 * 1024 * 1024);
+    const client: MCPClient = {
+      async listTools() {
+        return [
+          {
+            name: 'huge_img',
+            description: 'Returns an oversized image',
+            inputSchema: { type: 'object', properties: {} },
+          },
+        ];
+      },
+      async callTool() {
+        return {
+          content: [{ type: 'image', data: huge, mimeType: 'image/png' }],
+          isError: false,
+        };
+      },
+    };
+    tm.registerMcpServer('s', client, await discoverTools(client));
+    const tool = tm.loopTools.find((t) => t.name === 'mcp__s__huge_img');
+
+    const result = await executeTool(tool!, {
+      turnId: '1',
+      toolCallId: 'tc-huge-image',
+      args: {},
+      signal: new AbortController().signal,
+    });
+
+    expect(result.isError).toBe(false);
+    expect(Array.isArray(result.output)).toBe(true);
+    const parts = result.output as ContentPart[];
+    // applyOutputLimits swaps the oversized image for a per-part notice
+    // inside the mcp_tool_result envelope: [open tag, dropped notice, close tag].
+    expect(parts).toHaveLength(3);
+    expect(parts[0]).toEqual({
+      type: 'text',
+      text: '<mcp_tool_result name="mcp__s__huge_img">',
+    });
+    expect(parts[1]?.type).toBe('text');
+    expect((parts[1] as { text: string }).text).toContain('image_url dropped');
+    expect((parts[1] as { text: string }).text).toContain('10 MB per-part limit');
+    expect(parts[2]).toEqual({ type: 'text', text: '</mcp_tool_result>' });
+    // The notice replaces the binary part; the *text* truncation marker must
+    // not fire because the text character budget was never touched.
+    const joined = parts
+      .map((p) => (p.type === 'text' ? p.text : ''))
+      .join('');
+    expect(joined).not.toContain('Output truncated');
+  });
+
+  it('large MCP image does not consume the text character budget', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    const client: MCPClient = {
+      async listTools() {
+        return [
+          {
+            name: 'mixed',
+            description: 'Returns text plus an image',
+            inputSchema: { type: 'object', properties: {} },
+          },
+        ];
+      },
+      async callTool() {
+        return {
+          content: [
+            { type: 'text', text: 'A'.repeat(100_000) },
+            { type: 'image', data: 'B'.repeat(500_000), mimeType: 'image/png' },
+          ],
+          isError: false,
+        };
+      },
+    };
+    tm.registerMcpServer('s', client, await discoverTools(client));
+    const tool = tm.loopTools.find((t) => t.name === 'mcp__s__mixed');
+
+    const result = await executeTool(tool!, {
+      turnId: '1',
+      toolCallId: 'tc-text-plus-image',
+      args: {},
+      signal: new AbortController().signal,
+    });
+
+    expect(result.isError).toBe(false);
+    expect(Array.isArray(result.output)).toBe(true);
+    const parts = result.output as ContentPart[];
+    // Text fills the whole 100k budget; image must still survive intact and
+    // the trailing truncation marker must not appear (text was not cut off).
+    expect(parts).toEqual([
+      { type: 'text', text: 'A'.repeat(100_000) },
+      {
+        type: 'image_url',
+        imageUrl: { url: 'data:image/png;base64,' + 'B'.repeat(500_000) },
+      },
+    ]);
+  });
+
+  it('oversized binary part does not affect neighboring small binary parts', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    const huge = 'x'.repeat(14 * 1024 * 1024);
+    const client: MCPClient = {
+      async listTools() {
+        return [
+          {
+            name: 'mixed',
+            description: 'Returns an oversized image plus a small audio clip',
+            inputSchema: { type: 'object', properties: {} },
+          },
+        ];
+      },
+      async callTool() {
+        return {
+          content: [
+            { type: 'image', data: huge, mimeType: 'image/png' },
+            { type: 'audio', data: 'A'.repeat(1000), mimeType: 'audio/mpeg' },
+          ],
+          isError: false,
+        };
+      },
+    };
+    tm.registerMcpServer('s', client, await discoverTools(client));
+    const tool = tm.loopTools.find((t) => t.name === 'mcp__s__mixed');
+
+    const result = await executeTool(tool!, {
+      turnId: '1',
+      toolCallId: 'tc-mixed-binary',
+      args: {},
+      signal: new AbortController().signal,
+    });
+
+    expect(result.isError).toBe(false);
+    expect(Array.isArray(result.output)).toBe(true);
+    const parts = result.output as ContentPart[];
+    // Inside the mcp_tool_result envelope: [open tag, dropped image notice,
+    // surviving audio, close tag]. The audio survives because each binary
+    // part is measured against its own byte cap independently.
+    expect(parts).toHaveLength(4);
+    expect(parts[0]).toEqual({ type: 'text', text: '<mcp_tool_result name="mcp__s__mixed">' });
+    expect(parts[1]?.type).toBe('text');
+    expect((parts[1] as { text: string }).text).toContain('image_url dropped');
+    expect(parts[2]).toEqual({
+      type: 'audio_url',
+      audioUrl: { url: 'data:audio/mpeg;base64,' + 'A'.repeat(1000) },
+    });
+    expect(parts[3]).toEqual({ type: 'text', text: '</mcp_tool_result>' });
+  });
+
+  it('forwards the execution AbortSignal through the wrapped MCP tool', async () => {
+    const tm = new ToolManager(fakeAgent());
+    tm.setActiveTools(['mcp__*']);
+    let receivedSignal: AbortSignal | undefined;
+    const client: MCPClient = {
+      async listTools() {
+        return [
+          {
+            name: 'echo',
+            description: 'Echoes back',
+            inputSchema: {
+              type: 'object',
+              properties: { text: { type: 'string' } },
+              required: ['text'],
+            },
+          },
+        ];
+      },
+      async callTool(_name, args, signal) {
+        receivedSignal = signal;
+        return { content: [{ type: 'text', text: String(args['text']) }], isError: false };
+      },
+    };
+    tm.registerMcpServer('s', client, await discoverTools(client));
+    const echo = tm.loopTools.find((t) => t.name === 'mcp__s__echo');
+
+    const controller = new AbortController();
+    await executeTool(echo!, {
+      turnId: '1',
+      toolCallId: 'tc-signal',
+      args: { text: 'hi' },
+      signal: controller.signal,
+    });
+
+    expect(receivedSignal).toBe(controller.signal);
+  });
+
+  it('gates MCP tools by the active profile', async () => {
+    const ctx = testAgent();
+    const tm = ctx.agent.tools;
+    const client = fakeClient();
+    tm.registerMcpServer('local', client, await discoverTools(client));
+
+    // A profile without any MCP pattern hides every MCP tool: they stay
+    // registered (and visible in toolInfos) but inactive and out of the loop.
+    ctx.agent.useProfile({
+      name: 'no-mcp',
+      systemPrompt: () => 'sys',
+      tools: ['Read'],
+    });
+    expect(
+      [...tm.toolInfos()]
+        .filter((i) => i.source === 'mcp')
+        .map((i) => ({ name: i.name, active: i.active })),
+    ).toEqual([
+      { name: 'mcp__local__echo', active: false },
+      { name: 'mcp__local__noop', active: false },
+    ]);
+    expect(tm.loopTools.some((t) => t.name.startsWith('mcp__'))).toBe(false);
+
+    // Adding `mcp__*` to the profile exposes them again.
+    ctx.agent.useProfile({
+      name: 'with-mcp',
+      systemPrompt: () => 'sys',
+      tools: ['Read', 'mcp__*'],
+    });
+    expect(
+      [...tm.toolInfos()]
+        .filter((i) => i.source === 'mcp')
+        .map((i) => ({ name: i.name, active: i.active })),
+    ).toEqual([
+      { name: 'mcp__local__echo', active: true },
+      { name: 'mcp__local__noop', active: true },
+    ]);
+    expect(tm.loopTools.map((t) => t.name)).toContain('mcp__local__echo');
+  });
+
+  it('a server-scoped MCP glob exposes only that server', async () => {
+    const tm = new ToolManager(fakeAgent());
+    const githubClient = fakeClient();
+    const slackClient = fakeClient();
+    tm.registerMcpServer('github', githubClient, await discoverTools(githubClient));
+    tm.registerMcpServer('slack', slackClient, await discoverTools(slackClient));
+    tm.setActiveTools(['mcp__github__*']);
+
+    expect(tm.loopTools.map((t) => t.name).toSorted()).toEqual([
+      'mcp__github__echo',
+      'mcp__github__noop',
+    ]);
+  });
+
+  it('an exact MCP tool name exposes only that tool', async () => {
+    const tm = new ToolManager(fakeAgent());
+    const client = fakeClient();
+    tm.registerMcpServer('s', client, await discoverTools(client));
+    tm.setActiveTools(['mcp__s__echo']);
+
+    expect(tm.loopTools.map((t) => t.name)).toEqual(['mcp__s__echo']);
+  });
+});
diff --git a/packages/agent-core/test/mcp/tool-naming.test.ts b/packages/agent-core/test/mcp/tool-naming.test.ts
new file mode 100644
index 000000000..7c26b8855
--- /dev/null
+++ b/packages/agent-core/test/mcp/tool-naming.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+
+import { isMcpToolName, qualifyMcpToolName, sanitizeMcpNamePart } from '../../src/mcp/tool-naming';
+
+describe('sanitizeMcpNamePart', () => {
+  it('passes alphanumeric, underscore, and dash through unchanged', () => {
+    expect(sanitizeMcpNamePart('github_v2-alpha')).toBe('github_v2-alpha');
+  });
+
+  it('replaces unsafe characters with underscores', () => {
+    expect(sanitizeMcpNamePart('My Search/Tool!')).toBe('My_Search_Tool_');
+    expect(sanitizeMcpNamePart('@scope/pkg.tool')).toBe('_scope_pkg_tool');
+  });
+
+  it('collapses runs of underscores (including pre-existing __) into a single _', () => {
+    // Pre-existing __ — keeping the separator out of either name half is what
+    // lets decoders split unambiguously on the first __ in the qualified name.
+    expect(sanitizeMcpNamePart('my__server')).toBe('my_server');
+    // A run of unsafe characters also collapses.
+    expect(sanitizeMcpNamePart('a   b')).toBe('a_b');
+    expect(sanitizeMcpNamePart('list..__issues')).toBe('list_issues');
+  });
+});
+
+describe('qualifyMcpToolName', () => {
+  it('joins prefix, sanitized server, and sanitized tool with double underscores', () => {
+    expect(qualifyMcpToolName('github', 'list_issues')).toBe('mcp__github__list_issues');
+    expect(qualifyMcpToolName('My Search', 'do.thing')).toBe('mcp__My_Search__do_thing');
+  });
+
+  it('keeps the server / tool boundary unambiguous when either half contained __', () => {
+    // Without the collapse step, `my__server` + `foo` would produce
+    // `mcp__my__server__foo` and a left-to-right decoder would think
+    // server=my, tool=server__foo. With the collapse, the qualified name
+    // contains exactly one `__` after the prefix and decoders cannot misread.
+    expect(qualifyMcpToolName('my__server', 'foo')).toBe('mcp__my_server__foo');
+    expect(qualifyMcpToolName('gh', 'list__issues')).toBe('mcp__gh__list_issues');
+  });
+
+  it('produces a length-capped name with a stable hash suffix when too long', () => {
+    const server = 'a'.repeat(40);
+    const tool = 'b'.repeat(40);
+    const name = qualifyMcpToolName(server, tool);
+    expect(name.length).toBeLessThanOrEqual(64);
+    expect(name.startsWith('mcp__')).toBe(true);
+    // Same input → same output (stable hash).
+    expect(qualifyMcpToolName(server, tool)).toBe(name);
+  });
+
+  it('differentiates servers when the tail is hashed', () => {
+    const tool = 'x'.repeat(40);
+    expect(qualifyMcpToolName('a'.repeat(40), tool)).not.toBe(
+      qualifyMcpToolName('b'.repeat(40), tool),
+    );
+  });
+});
+
+describe('isMcpToolName', () => {
+  it('detects qualified MCP tool names', () => {
+    expect(isMcpToolName('mcp__github__list')).toBe(true);
+    expect(isMcpToolName('Read')).toBe(false);
+    expect(isMcpToolName('mcp_one_underscore__no')).toBe(false);
+  });
+});
diff --git a/packages/agent-core/test/profile/agent-profile-loader.test.ts b/packages/agent-core/test/profile/agent-profile-loader.test.ts
new file mode 100644
index 000000000..963af54ea
--- /dev/null
+++ b/packages/agent-core/test/profile/agent-profile-loader.test.ts
@@ -0,0 +1,245 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  DEFAULT_AGENT_PROFILES,
+  loadAgentProfilesFromDir,
+  loadAgentProfilesFromSources,
+  resolveAgentProfiles,
+  type SystemPromptContext,
+} from '../../src/profile';
+import { SkillRegistry, type SkillDefinition } from '../../src/skill';
+
+let workDir: string;
+
+const promptContext: SystemPromptContext = {
+  osEnv: {
+    osKind: 'macOS',
+    osArch: 'arm64',
+    osVersion: '0',
+    shellName: 'bash',
+    shellPath: '/bin/bash',
+  },
+  cwd: '/workspace',
+  now: '2026-05-09T00:00:00.000Z',
+  cwdListing: 'README.md',
+  agentsMd: 'Project instructions.',
+  skills: 'Available test skills.',
+};
+
+beforeEach(async () => {
+  workDir = await mkdtemp(join(tmpdir(), 'kimi-agent-profile-'));
+});
+
+afterEach(async () => {
+  await rm(workDir, { recursive: true, force: true });
+});
+
+describe('agent profile loader', () => {
+  it('loads YAML profiles, inherits templates, and renders with runtime context', async () => {
+    const systemPath = await write(
+      'system.md',
+      [
+        'os={{ KIMI_OS }}',
+        'cwd={{ KIMI_WORK_DIR }}',
+        'listing={{ KIMI_WORK_DIR_LS }}',
+        'agents={{ KIMI_AGENTS_MD }}',
+        'skills={{ KIMI_SKILLS }}',
+        'parent={{ parentOnly }}',
+        'child={{ childOnly }}',
+        'role={{ ROLE_ADDITIONAL }}',
+        '{% if KIMI_OS == "macOS" %}nunjucks-ok{% endif %}',
+      ].join('\n'),
+    );
+    await write(
+      'agent.yaml',
+      `
+name: agent
+description: Parent agent
+systemPromptPath: ./${fileName(systemPath)}
+promptVars:
+  parentOnly: parent-value
+  roleAdditional: parent-role
+tools:
+  - Read
+subagents:
+  shared:
+    description: Shared parent subagent
+  coder:
+    description: Coder child subagent
+`,
+    );
+    await write(
+      'coder.yaml',
+      `
+extends: agent
+name: coder
+promptVars:
+  childOnly: child-value
+  roleAdditional: child-role
+tools:
+  - Bash
+`,
+    );
+    await write(
+      'shared.yaml',
+      `
+name: shared
+systemPromptTemplate: shared prompt
+tools:
+  - Read
+`,
+    );
+
+    const profiles = await loadAgentProfilesFromDir([
+      join(workDir, 'agent.yaml'),
+      join(workDir, 'coder.yaml'),
+      join(workDir, 'shared.yaml'),
+      join(workDir, 'missing.yaml'),
+    ]);
+    const coderPrompt = profiles['coder']?.systemPrompt(promptContext);
+
+    expect(profiles['coder']?.description).toBe('Coder child subagent');
+    expect(profiles['coder']?.tools).toEqual(['Bash']);
+    expect(profiles['agent']?.subagents?.['shared']).toBe(profiles['shared']);
+    expect(profiles['agent']?.subagents?.['coder']).toBe(profiles['coder']);
+    expect(profiles['coder']?.subagents).toBeUndefined();
+    expect(profiles['shared']?.description).toBe('Shared parent subagent');
+    expect(coderPrompt).toContain('os=macOS');
+    expect(coderPrompt).toContain('cwd=/workspace');
+    expect(coderPrompt).toContain('listing=README.md');
+    expect(coderPrompt).toContain('agents=Project instructions.');
+    expect(coderPrompt).toContain('skills=Available test skills.');
+    expect(coderPrompt).toContain('parent=parent-value');
+    expect(coderPrompt).toContain('child=child-value');
+    expect(coderPrompt).toContain('role=child-role');
+    expect(coderPrompt).toContain('nunjucks-ok');
+    expect(coderPrompt).not.toContain('{{ ROLE_ADDITIONAL }}');
+  });
+
+  it('reports invalid profile graphs without relying on loader internals', () => {
+    expect(() =>
+      resolveAgentProfiles([
+        {
+          name: 'agent',
+          subagents: {
+            missing: { description: 'Missing subagent' },
+          },
+        },
+      ]),
+    ).toThrow(/declares subagent "missing"/);
+
+    expect(() => resolveAgentProfiles([{ name: 'agent' }, { name: 'agent' }])).toThrow(
+      /Duplicate agent profile name: "agent"/,
+    );
+
+    expect(() =>
+      resolveAgentProfiles([
+        { name: 'agent', extends: 'coder' },
+        { name: 'coder', extends: 'agent' },
+      ]),
+    ).toThrow(/agent -> coder -> agent/);
+  });
+
+  it('fails loudly when an embedded system prompt source is missing', () => {
+    expect(() =>
+      loadAgentProfilesFromSources(['profile/default/agent.yaml'], {
+        'profile/default/agent.yaml': 'name: agent\nsystemPromptPath: ./missing.md\n',
+      }),
+    ).toThrow(/Embedded agent profile source missing: profile\/default\/missing\.md/);
+  });
+});
+
+describe('default agent profiles', () => {
+  it('links bundled subagents and keeps role-specific tool sets observable', () => {
+    expect(DEFAULT_AGENT_PROFILES['agent']?.subagents?.['coder']).toBe(
+      DEFAULT_AGENT_PROFILES['coder'],
+    );
+    expect(DEFAULT_AGENT_PROFILES['agent']?.subagents?.['explore']).toBe(
+      DEFAULT_AGENT_PROFILES['explore'],
+    );
+    expect(DEFAULT_AGENT_PROFILES['agent']?.subagents?.['plan']).toBe(
+      DEFAULT_AGENT_PROFILES['plan'],
+    );
+
+    expect(DEFAULT_AGENT_PROFILES['agent']?.tools).toEqual(
+      expect.arrayContaining([
+        'Read',
+        'Write',
+        'Edit',
+        'Bash',
+        'Agent',
+        'Skill',
+        'TaskList',
+        'TaskOutput',
+        'TaskStop',
+      ]),
+    );
+    expect(DEFAULT_AGENT_PROFILES['coder']?.tools).toEqual(
+      expect.arrayContaining(['Read', 'Write', 'Edit', 'Bash']),
+    );
+    expect(DEFAULT_AGENT_PROFILES['explore']?.tools).not.toContain('Write');
+    expect(DEFAULT_AGENT_PROFILES['plan']?.tools).not.toContain('Bash');
+  });
+
+  it('renders the model-invocable skill listing for bundled prompts', () => {
+    const skills = new SkillRegistry();
+    skills.register(skill('review', { whenToUse: 'When code review is requested.' }));
+    skills.register(skill('private', { disableModelInvocation: true }));
+    skills.register(skill('flow-only', { type: 'flow' }));
+
+    const prompt = DEFAULT_AGENT_PROFILES['agent']?.systemPrompt({
+      ...promptContext,
+      skills,
+    });
+
+    expect(prompt).toContain('Current available skills:');
+    expect(prompt).toContain('- review:');
+    expect(prompt).toContain('When to use: When code review is requested.');
+    expect(prompt).not.toContain('private');
+    expect(prompt).not.toContain('flow-only');
+    expect(prompt).not.toContain('body of review');
+  });
+
+  it('renders the bundled default prompt from the current runtime context', () => {
+    const first = DEFAULT_AGENT_PROFILES['agent']?.systemPrompt({
+      ...promptContext,
+      cwd: '/workspace/one',
+    });
+    const second = DEFAULT_AGENT_PROFILES['agent']?.systemPrompt({
+      ...promptContext,
+      cwd: '/workspace/two',
+    });
+
+    expect(first).toContain('You are Kimi Code CLI');
+    expect(first).toContain('Available skills');
+    expect(first).toContain('/workspace/one');
+    expect(second).toContain('/workspace/two');
+    expect(second).not.toContain('/workspace/one');
+  });
+});
+
+async function write(fileName: string, content: string): Promise<string> {
+  const filePath = join(workDir, fileName);
+  await writeFile(filePath, content.trimStart(), 'utf-8');
+  return filePath;
+}
+
+function fileName(filePath: string): string {
+  return filePath.slice(workDir.length + 1);
+}
+
+function skill(name: string, metadata: SkillDefinition['metadata'] = {}): SkillDefinition {
+  return {
+    name,
+    description: `desc for ${name}`,
+    path: `/skills/${name}/SKILL.md`,
+    dir: `/skills/${name}`,
+    content: `body of ${name}`,
+    metadata,
+    source: 'user',
+  };
+}
diff --git a/packages/agent-core/test/profile/context.test.ts b/packages/agent-core/test/profile/context.test.ts
new file mode 100644
index 000000000..e7449969c
--- /dev/null
+++ b/packages/agent-core/test/profile/context.test.ts
@@ -0,0 +1,68 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { localKaos } from '@moonshot-ai/kaos';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { loadAgentsMd } from '../../src/profile/context';
+
+let homeDir: string;
+let workDir: string;
+
+beforeEach(async () => {
+  homeDir = await mkdtemp(join(tmpdir(), 'kimi-agents-home-'));
+  workDir = await mkdtemp(join(tmpdir(), 'kimi-agents-work-'));
+  vi.spyOn(localKaos, 'gethome').mockReturnValue(homeDir);
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await rm(homeDir, { recursive: true, force: true });
+  await rm(workDir, { recursive: true, force: true });
+});
+
+describe('loadAgentsMd user-level discovery', () => {
+  it('loads user-level branded and generic files before project-level', async () => {
+    await mkdir(join(homeDir, '.kimi-code'), { recursive: true });
+    await writeFile(join(homeDir, '.kimi-code', 'AGENTS.md'), 'user branded', 'utf-8');
+    await mkdir(join(homeDir, '.agents'), { recursive: true });
+    await writeFile(join(homeDir, '.agents', 'AGENTS.md'), 'user generic', 'utf-8');
+    await writeFile(join(workDir, 'AGENTS.md'), 'project instructions', 'utf-8');
+
+    const result = await loadAgentsMd(localKaos, workDir);
+
+    expect(result).toContain('user branded');
+    expect(result).toContain('user generic');
+    expect(result).toContain('project instructions');
+    expect(result.indexOf('user branded')).toBeLessThan(result.indexOf('user generic'));
+    expect(result.indexOf('user generic')).toBeLessThan(result.indexOf('project instructions'));
+  });
+
+  it('loads generic user-level .agents/AGENTS.md', async () => {
+    await mkdir(join(homeDir, '.agents'), { recursive: true });
+    await writeFile(join(homeDir, '.agents', 'AGENTS.md'), 'dot-agents generic', 'utf-8');
+
+    const result = await loadAgentsMd(localKaos, workDir);
+
+    expect(result).toContain('dot-agents generic');
+  });
+
+  it('falls back to project-level only when no user-level files exist', async () => {
+    await writeFile(join(workDir, 'AGENTS.md'), 'project only', 'utf-8');
+
+    const result = await loadAgentsMd(localKaos, workDir);
+
+    expect(result).toContain('project only');
+    expect(result).not.toContain(homeDir);
+  });
+
+  it('does not load the same file twice when the work dir is the home dir', async () => {
+    await mkdir(join(homeDir, '.kimi-code'), { recursive: true });
+    await writeFile(join(homeDir, '.kimi-code', 'AGENTS.md'), 'home branded', 'utf-8');
+
+    const result = await loadAgentsMd(localKaos, homeDir);
+
+    expect(result.split('home branded').length - 1).toBe(1);
+  });
+});
diff --git a/packages/agent-core/test/profile/default-agent-profiles.test.ts b/packages/agent-core/test/profile/default-agent-profiles.test.ts
new file mode 100644
index 000000000..469897086
--- /dev/null
+++ b/packages/agent-core/test/profile/default-agent-profiles.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+
+import { DEFAULT_AGENT_PROFILES, loadAgentProfilesFromSources } from '../../src/profile';
+
+const promptContext = {
+  osEnv: {
+    osKind: 'macOS',
+    osArch: 'arm64',
+    osVersion: '0',
+    shellName: 'bash',
+    shellPath: '/bin/bash',
+  },
+  cwd: '/workspace',
+  now: '2026-05-09T00:00:00.000Z',
+} as const;
+
+describe('default agent profiles', () => {
+  it('loads the bundled default system prompt from embedded sources', () => {
+    const prompt = DEFAULT_AGENT_PROFILES['agent']?.systemPrompt(promptContext);
+
+    expect(prompt).toContain('You are Kimi Code CLI');
+    expect(prompt).toContain('Available skills');
+    expect(prompt).toContain('/workspace');
+  });
+
+  it('fails loudly when an embedded system prompt source is missing', () => {
+    expect(() =>
+      loadAgentProfilesFromSources(['profile/default/agent.yaml'], {
+        'profile/default/agent.yaml': 'name: agent\nsystemPromptPath: ./missing.md\n',
+      }),
+    ).toThrow(/Embedded agent profile source missing: profile\/default\/missing\.md/);
+  });
+});
diff --git a/packages/agent-core/test/prompt-placeholders.test.ts b/packages/agent-core/test/prompt-placeholders.test.ts
new file mode 100644
index 000000000..dcfe13d81
--- /dev/null
+++ b/packages/agent-core/test/prompt-placeholders.test.ts
@@ -0,0 +1,76 @@
+import { globSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Guard against unrendered template placeholders reaching the model.
+ *
+ * Prompt `.md` files fall into two groups:
+ *   - **Templated** — rendered at runtime through `renderPrompt` (nunjucks).
+ *     They are expected to contain `{{ }}` / `{% %}`.
+ *   - **Static** — imported as raw strings and used verbatim. They must NOT
+ *     contain template syntax: a stray `{{ var }}` in a static file would be
+ *     sent to the model literally, since nothing renders it.
+ *
+ * This test pins that split. Adding a `{{ }}` to a static file (or forgetting
+ * to route it through `renderPrompt`) fails here instead of leaking silently.
+ */
+
+const SRC = join(import.meta.dirname, '..', 'src');
+
+// `.md` files rendered through `renderPrompt`. Keep in sync when a new
+// templated prompt file is introduced.
+const TEMPLATED = new Set([
+  'profile/default/system.md',
+  'agent/compaction/compaction-instruction.md',
+  'tools/builtin/file/read.md',
+  'tools/builtin/file/read-media.md',
+  'tools/builtin/shell/bash.md',
+  'tools/builtin/collaboration/skill-tool.md',
+]);
+
+const mdFiles = globSync('**/*.md', { cwd: SRC })
+  .map((file) => file.split('\\').join('/'))
+  .filter((file) => !file.endsWith('README.md'));
+
+describe('prompt placeholders', () => {
+  it('discovers prompt .md files', () => {
+    expect(mdFiles.length).toBeGreaterThan(0);
+  });
+
+  it('static .md files contain no unrendered template syntax', () => {
+    for (const file of mdFiles) {
+      if (TEMPLATED.has(file)) continue;
+      const content = readFileSync(join(SRC, file), 'utf-8');
+      expect(
+        /\{\{|\{%|\$\{/.test(content),
+        `${file} is imported as raw text; it must not contain {{ }} / {% %} / \${ } ` +
+          'or it would reach the model unrendered (route it through renderPrompt instead).',
+      ).toBe(false);
+    }
+  });
+
+  it('templated .md files use {{ }} syntax, not legacy ${ }', () => {
+    for (const file of mdFiles) {
+      if (!TEMPLATED.has(file)) continue;
+      const content = readFileSync(join(SRC, file), 'utf-8');
+      expect(content.includes('${'), `${file} must use {{ }} placeholders, not legacy \${ }`).toBe(
+        false,
+      );
+    }
+  });
+
+  // Closes the whitelist loop: a file wrongly added to TEMPLATED would have its
+  // own `{{ }}` skipped by the static-file check above and leak unrendered.
+  it('every TEMPLATED entry exists and actually uses template syntax', () => {
+    for (const file of TEMPLATED) {
+      // readFileSync throws on a wrong path — pins the whitelist to real files.
+      const content = readFileSync(join(SRC, file), 'utf-8');
+      expect(
+        /\{\{|\{%/.test(content),
+        `${file} is whitelisted as templated but has no {{ }} / {% %} — it must not be in TEMPLATED.`,
+      ).toBe(true);
+    }
+  });
+});
diff --git a/packages/agent-core/test/rpc/create-rpc.test.ts b/packages/agent-core/test/rpc/create-rpc.test.ts
new file mode 100644
index 000000000..3e8accccf
--- /dev/null
+++ b/packages/agent-core/test/rpc/create-rpc.test.ts
@@ -0,0 +1,203 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { ErrorCodes, KimiError } from '../../src/errors';
+import { createRPC } from '../../src/rpc';
+
+interface CoreSide {
+  getConfig(payload: { sessionId: string }): { model: string };
+}
+
+interface HostSide {
+  emitEvent(event: { type: string; payload: { value: number } }): void;
+  requestApproval(request: { requestId: string; toolName: string }): Promise<{ decision: string }>;
+  fail(request: { code: string }): Promise<void>;
+}
+
+describe('createRPC', () => {
+  it('routes request and response payloads across both sides', async () => {
+    const [connectCore, connectHost] = createRPC<CoreSide, HostSide>();
+    const hostImpl = {
+      emitEvent: vi.fn(),
+      requestApproval: vi.fn(async (request: { requestId: string; toolName: string }) => ({
+        decision: `approved:${request.toolName}`,
+      })),
+      fail: vi.fn(async () => {}),
+    };
+
+    const hostProxyPromise = connectCore({
+      getConfig: ({ sessionId }) => ({ model: `model-for:${sessionId}` }),
+    });
+    const coreProxy = await connectHost(hostImpl);
+    const hostProxy = await hostProxyPromise;
+
+    await hostProxy.emitEvent({ type: 'agent.status.updated', payload: { value: 1 } });
+    await expect(
+      hostProxy.requestApproval({ requestId: 'approval-1', toolName: 'Bash' }),
+    ).resolves.toEqual({ decision: 'approved:Bash' });
+    await expect(coreProxy.getConfig({ sessionId: 'session-1' })).resolves.toEqual({
+      model: 'model-for:session-1',
+    });
+    expect(hostImpl.emitEvent).toHaveBeenCalledWith({
+      type: 'agent.status.updated',
+      payload: { value: 1 },
+    });
+  });
+
+  it('binds prototype methods and rehydrates plain remote errors as KimiError(internal)', async () => {
+    class HostImpl implements HostSide {
+      readonly approvals: string[] = [];
+
+      emitEvent(_event: { type: string; payload: { value: number } }): void {}
+
+      async requestApproval(request: { requestId: string; toolName: string }) {
+        this.approvals.push(request.requestId);
+        return { decision: 'approved' };
+      }
+
+      async fail(request: { code: string }): Promise<void> {
+        throw new Error(`host failed:${request.code}`);
+      }
+    }
+
+    const hostImpl = new HostImpl();
+    const [connectCore, connectHost] = createRPC<CoreSide, HostSide>();
+    const hostProxyPromise = connectCore({
+      getConfig: ({ sessionId }) => ({ model: sessionId }),
+    });
+    await connectHost(hostImpl);
+    const hostProxy = await hostProxyPromise;
+
+    await expect(
+      hostProxy.requestApproval({ requestId: 'approval-2', toolName: 'Bash' }),
+    ).resolves.toEqual({ decision: 'approved' });
+
+    await expect(hostProxy.fail({ code: 'boom' })).rejects.toMatchObject({
+      message: 'host failed:boom',
+      code: ErrorCodes.INTERNAL,
+    });
+    await expect(hostProxy.fail({ code: 'boom' })).rejects.toBeInstanceOf(KimiError);
+    expect(hostImpl.approvals).toEqual(['approval-2']);
+  });
+
+  it('passes a thrown KimiError across the wire preserving code and details', async () => {
+    interface CallerSide {}
+    interface RemoteSide {
+      prompt(payload: { input: string }): Promise<void>;
+    }
+    const [connectCaller, connectRemote] = createRPC<CallerSide, RemoteSide>();
+    const remoteProxyPromise = connectCaller({});
+    await connectRemote({
+      async prompt(payload) {
+        if (payload.input === '') {
+          throw new KimiError(ErrorCodes.REQUEST_PROMPT_INPUT_EMPTY, 'Prompt input cannot be empty', {
+            details: { hint: 'pass at least one content part' },
+            cause: new Error('local diagnostic — must not cross'),
+          });
+        }
+      },
+    });
+    const remoteProxy = await remoteProxyPromise;
+
+    const received = await remoteProxy.prompt({ input: '' }).then(
+      () => {
+        throw new Error('expected prompt() to reject');
+      },
+      (error: unknown) => error,
+    );
+
+    expect(received).toBeInstanceOf(KimiError);
+    const error = received as KimiError;
+    expect(error.code).toBe(ErrorCodes.REQUEST_PROMPT_INPUT_EMPTY);
+    expect(error.message).toBe('Prompt input cannot be empty');
+    expect(error.details).toEqual({ hint: 'pass at least one content part' });
+    expect(error.cause).toBeUndefined();
+  });
+
+  it('serializes remote error details through JSON semantics before crossing the wire', async () => {
+    interface RemoteSide {
+      fail(payload: {}): Promise<void>;
+    }
+    const [connectCaller, connectRemote] = createRPC<{}, RemoteSide>();
+    const remoteProxyPromise = connectCaller({});
+    await connectRemote({
+      async fail() {
+        const details: Record<string, unknown> = {
+          nested: { ok: true },
+          at: new Date('2026-05-18T00:00:00.000Z'),
+          dropped: undefined,
+          notFinite: Number.NaN,
+          cause: new Error('detail failed'),
+        };
+        throw new KimiError(ErrorCodes.INTERNAL, 'Remote failed', {
+          details,
+        });
+      },
+    });
+    const remoteProxy = await remoteProxyPromise;
+
+    const received = await remoteProxy.fail({}).then(
+      () => {
+        throw new Error('expected fail() to reject');
+      },
+      (error: unknown) => error,
+    );
+
+    expect(received).toBeInstanceOf(KimiError);
+    const error = received as KimiError;
+    expect(error.details).toEqual({
+      nested: { ok: true },
+      at: '2026-05-18T00:00:00.000Z',
+      notFinite: null,
+      cause: {},
+    });
+  });
+
+  it('rehydrates provider.* codes as KimiError', async () => {
+    interface RemoteSide {
+      callProvider(payload: { kind: string }): Promise<void>;
+    }
+    const [connectCaller, connectRemote] = createRPC<{}, RemoteSide>();
+    const remoteProxyPromise = connectCaller({});
+    await connectRemote({
+      async callProvider() {
+        throw new KimiError(ErrorCodes.PROVIDER_RATE_LIMIT, 'Upstream rate limit', {
+          details: { retryAfterMs: 1000 },
+        });
+      },
+    });
+    const remoteProxy = await remoteProxyPromise;
+
+    const received = await remoteProxy.callProvider({ kind: 'chat' }).then(
+      () => {
+        throw new Error('expected callProvider() to reject');
+      },
+      (error: unknown) => error,
+    );
+
+    expect(received).toBeInstanceOf(KimiError);
+    const error = received as KimiError;
+    expect(error.code).toBe(ErrorCodes.PROVIDER_RATE_LIMIT);
+    expect(error.details).toEqual({ retryAfterMs: 1000 });
+  });
+
+  it('collapses non-Error throws to KimiError(internal)', async () => {
+    interface RemoteSide {
+      misbehave(payload: {}): Promise<void>;
+    }
+    const [connectCaller, connectRemote] = createRPC<{}, RemoteSide>();
+    const remoteProxyPromise = connectCaller({});
+    await connectRemote({
+      async misbehave() {
+        // oxlint-disable-next-line no-throw-literal, @typescript-eslint/only-throw-error
+        throw 'not an error object';
+      },
+    });
+    const remoteProxy = await remoteProxyPromise;
+
+    await expect(remoteProxy.misbehave({})).rejects.toMatchObject({
+      code: ErrorCodes.INTERNAL,
+      message: 'not an error object',
+    });
+    await expect(remoteProxy.misbehave({})).rejects.toBeInstanceOf(KimiError);
+  });
+});
diff --git a/packages/agent-core/test/session/git-context.test.ts b/packages/agent-core/test/session/git-context.test.ts
new file mode 100644
index 000000000..62cdc4350
--- /dev/null
+++ b/packages/agent-core/test/session/git-context.test.ts
@@ -0,0 +1,178 @@
+import { Readable } from 'node:stream';
+
+import type { Kaos, KaosProcess } from '@moonshot-ai/kaos';
+import { describe, expect, it, vi } from 'vitest';
+
+import { collectGitContext, parseProjectName, sanitizeRemoteUrl } from '../../src/session/git-context';
+import { createFakeKaos } from '../tools/fixtures/fake-kaos';
+
+function fakeProcess(stdout: string, exitCode = 0): KaosProcess {
+  return {
+    stdin: { write: () => true, end: () => {} } as never,
+    stdout: Readable.from([stdout]),
+    stderr: Readable.from(['']),
+    pid: 1,
+    exitCode,
+    wait: async () => exitCode,
+    kill: async () => {},
+  };
+}
+
+/** Scripted git output keyed by the git subcommand (`args[3]`). */
+type GitScript = Record<string, { stdout: string; exitCode?: number }>;
+
+function gitKaos(script: GitScript): Kaos {
+  return createFakeKaos({
+    exec: async (...args: string[]): Promise<KaosProcess> => {
+      const subcommand = args[3] ?? '';
+      const scripted = script[subcommand];
+      if (scripted === undefined) return fakeProcess('', 1);
+      return fakeProcess(scripted.stdout, scripted.exitCode ?? 0);
+    },
+  });
+}
+
+describe('collectGitContext', () => {
+  it('returns an empty string when the directory is not a git repository', async () => {
+    const kaos = gitKaos({ 'rev-parse': { stdout: '', exitCode: 1 } });
+    expect(await collectGitContext(kaos, '/project')).toBe('');
+  });
+
+  it('builds a git-context block with all sections', async () => {
+    const kaos = gitKaos({
+      'rev-parse': { stdout: 'true' },
+      remote: { stdout: 'https://github.com/acme/widgets.git' },
+      branch: { stdout: 'main' },
+      status: { stdout: ' M src/a.ts\n?? src/b.ts' },
+      log: { stdout: 'abc123 first commit\ndef456 second commit' },
+    });
+
+    const block = await collectGitContext(kaos, '/project');
+
+    expect(block.startsWith('<git-context>\n')).toBe(true);
+    expect(block.endsWith('\n</git-context>')).toBe(true);
+    expect(block).toContain('Working directory: /project');
+    expect(block).toContain('Remote: https://github.com/acme/widgets.git');
+    expect(block).toContain('Project: acme/widgets');
+    expect(block).toContain('Branch: main');
+    expect(block).toContain('Dirty files (2):');
+    expect(block).toContain('  ?? src/b.ts');
+    expect(block).toContain('Recent commits:');
+    expect(block).toContain('  abc123 first commit');
+  });
+
+  it('caps dirty files at 20 and reports the remainder', async () => {
+    const dirty = Array.from({ length: 25 }, (_, i) => ` M src/f${String(i)}.ts`).join('\n');
+    const kaos = gitKaos({
+      'rev-parse': { stdout: 'true' },
+      status: { stdout: dirty },
+    });
+
+    const block = await collectGitContext(kaos, '/project');
+
+    expect(block).toContain('Dirty files (25):');
+    expect(block).toContain('  ... and 5 more');
+  });
+
+  it('returns an empty string when only the working directory is known', async () => {
+    const kaos = gitKaos({ 'rev-parse': { stdout: 'true' } });
+    expect(await collectGitContext(kaos, '/project')).toBe('');
+  });
+
+  it('omits both Remote and Project for a disallowed remote host', async () => {
+    const kaos = gitKaos({
+      'rev-parse': { stdout: 'true' },
+      remote: { stdout: 'git@internal.corp:secret/repo.git' },
+      branch: { stdout: 'main' },
+    });
+
+    const block = await collectGitContext(kaos, '/project');
+
+    expect(block).not.toContain('Remote:');
+    expect(block).not.toContain('Project:');
+    expect(block).not.toContain('secret/repo');
+    expect(block).toContain('Branch: main');
+  });
+
+  it('treats a hanging git command as a failure (timeout)', async () => {
+    vi.useFakeTimers();
+    try {
+      const kaos = createFakeKaos({
+        exec: async (): Promise<KaosProcess> => {
+          let release: (code: number) => void = () => {};
+          const exited = new Promise<number>((resolve) => {
+            release = resolve;
+          });
+          return {
+            stdin: { write: () => true, end: () => {} } as never,
+            stdout: Readable.from(['']),
+            stderr: Readable.from(['']),
+            pid: 1,
+            exitCode: null,
+            wait: () => exited,
+            // A real process exits once it receives SIGKILL.
+            kill: async () => {
+              release(137);
+            },
+          };
+        },
+      });
+
+      const promise = collectGitContext(kaos, '/project');
+      await vi.advanceTimersByTimeAsync(6_000);
+      expect(await promise).toBe('');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe('sanitizeRemoteUrl', () => {
+  it('strips credentials from an allowed HTTPS host', () => {
+    expect(sanitizeRemoteUrl('https://user:pass@github.com/acme/widgets.git')).toBe(
+      'https://github.com/acme/widgets.git',
+    );
+  });
+
+  it('passes through an allowed SSH host', () => {
+    expect(sanitizeRemoteUrl('git@github.com:acme/widgets.git')).toBe(
+      'git@github.com:acme/widgets.git',
+    );
+  });
+
+  it('rejects an unrecognized HTTPS host', () => {
+    expect(sanitizeRemoteUrl('https://internal.corp/acme/widgets.git')).toBeNull();
+  });
+
+  it('rejects an unrecognized SSH host', () => {
+    expect(sanitizeRemoteUrl('git@internal.corp:acme/widgets.git')).toBeNull();
+  });
+
+  it('passes through the SourceHut git host', () => {
+    expect(sanitizeRemoteUrl('git@git.sr.ht:~user/repo')).toBe('git@git.sr.ht:~user/repo');
+  });
+});
+
+describe('parseProjectName', () => {
+  it('extracts owner/repo from an SSH URL', () => {
+    expect(parseProjectName('git@github.com:acme/widgets.git')).toBe('acme/widgets');
+  });
+
+  it('extracts owner/repo from an HTTPS URL', () => {
+    expect(parseProjectName('https://github.com/acme/widgets.git')).toBe('acme/widgets');
+  });
+
+  it('extracts owner/repo from an HTTPS URL without a .git suffix', () => {
+    expect(parseProjectName('https://gitee.com/acme/widgets')).toBe('acme/widgets');
+  });
+
+  it('keeps the full namespace for nested GitLab groups (HTTPS)', () => {
+    expect(parseProjectName('https://gitlab.com/group/subgroup/repo.git')).toBe(
+      'group/subgroup/repo',
+    );
+  });
+
+  it('keeps the full namespace for nested GitLab groups (SSH)', () => {
+    expect(parseProjectName('git@gitlab.com:group/subgroup/repo.git')).toBe('group/subgroup/repo');
+  });
+});
diff --git a/packages/agent-core/test/session/init.test.ts b/packages/agent-core/test/session/init.test.ts
new file mode 100644
index 000000000..8320daf43
--- /dev/null
+++ b/packages/agent-core/test/session/init.test.ts
@@ -0,0 +1,229 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { localKaos } from '@moonshot-ai/kaos';
+import type { ProviderConfig } from '@moonshot-ai/kosong';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { ProviderManager } from '../../src/providers/provider-manager';
+import type { ResolvedAgentProfile } from '../../src/profile';
+import type { SDKSessionRPC } from '../../src/rpc';
+import { Session } from '../../src/session';
+import { SessionAPIImpl } from '../../src/session/rpc';
+import { createScriptedGenerate } from '../agent/harness/scripted-generate';
+import { recordingTelemetry, type TelemetryRecord } from '../fixtures/telemetry';
+
+const MOCK_PROVIDER = {
+  type: 'kimi',
+  apiKey: 'test-key',
+  model: 'mock-model',
+} as const satisfies ProviderConfig;
+
+const OS_ENV = {
+  osKind: 'Linux',
+  osArch: 'arm64',
+  osVersion: 'test',
+  shellPath: '/bin/bash',
+  shellName: 'bash',
+} as const;
+
+const here = import.meta.dirname;
+const mcpStdioFixture = join(here, '..', 'mcp', 'fixtures', 'mock-stdio-server.mjs');
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+describe('Session.init', () => {
+  it('runs an isolated system-trigger turn and records the latest AGENTS as a system reminder', async () => {
+    const workDir = await makeTempDir();
+    const sessionDir = await makeTempDir();
+    await mkdir(join(workDir, '.git'));
+    await writeFile(join(workDir, 'AGENTS.md'), 'latest project instructions', 'utf-8');
+
+    const events: Array<Record<string, unknown>> = [];
+    const scripted = createScriptedGenerate();
+    const session = new Session({
+      id: 'test-init',
+      runtime: { kaos: localKaos, osEnv: OS_ENV },
+      homedir: sessionDir,
+      cwd: workDir,
+      rpc: createSessionRpc(events),
+      skills: { explicitDirs: [join(workDir, 'missing-skills')] },
+      providerManager: testProviderManager(),
+    });
+    const { agent: mainAgent } = await session.createAgent(
+      { type: 'main', generate: scripted.generate },
+      testProfile(),
+    );
+    mainAgent.config.update({
+      modelAlias: 'mock-model',
+      thinkingLevel: 'off',
+    });
+    mainAgent.tools.setActiveTools([]);
+    events.length = 0;
+    scripted.mockNextResponse({
+      type: 'text',
+      text: 'Explored the project structure, identified the build and test commands, mapped the module layout, and wrote a comprehensive summary into AGENTS.md covering architecture, conventions, and the developer workflow for future agents.',
+    });
+
+    await session.generateAgentsMd();
+
+    expect(session.agents.size).toBe(2);
+    expect(session.agents.get('main')).toBe(mainAgent);
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: 'subagent.spawned',
+        agentId: 'main',
+        subagentId: 'agent-0',
+        subagentName: 'coder',
+        parentToolCallId: 'generate-agents-md',
+      }),
+    );
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: 'turn.started',
+        agentId: 'agent-0',
+        origin: { kind: 'system_trigger', name: 'init' },
+      }),
+    );
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: 'subagent.completed',
+        agentId: 'main',
+        subagentId: 'agent-0',
+        parentToolCallId: 'generate-agents-md',
+      }),
+    );
+    expect(scripted.calls[0]?.history).toMatchObject([
+      {
+        role: 'user',
+        content: [
+          expect.objectContaining({
+            text: expect.stringContaining('Task requirements:'),
+          }),
+        ],
+      },
+    ]);
+
+    const contextText = mainAgent.context.history
+      .flatMap((message) => message.content)
+      .map((part) => (part.type === 'text' ? part.text : ''))
+      .join('\n');
+    expect(contextText).toContain('<system-reminder>');
+    expect(contextText).toContain('Latest AGENTS.md file content:');
+    expect(contextText).toContain('latest project instructions');
+    expect(contextText).not.toContain('Task requirements:');
+  });
+
+  it('tracks connected and failed MCP server totals after initial load', async () => {
+    const workDir = await makeTempDir();
+    const sessionDir = await makeTempDir();
+    const records: TelemetryRecord[] = [];
+    const session = new Session({
+      runtime: { kaos: localKaos, osEnv: OS_ENV },
+      homedir: sessionDir,
+      cwd: workDir,
+      rpc: createSessionRpc([]),
+      providerManager: testProviderManager(),
+      mcpConfig: {
+        servers: {
+          connected: {
+            transport: 'stdio',
+            command: process.execPath,
+            args: [mcpStdioFixture],
+          },
+          failed: {
+            transport: 'stdio',
+            command: '/this/path/does/not/exist/anywhere',
+          },
+          disabled: {
+            transport: 'stdio',
+            command: process.execPath,
+            args: [mcpStdioFixture],
+            enabled: false,
+          },
+        },
+      },
+      telemetry: recordingTelemetry(records),
+    });
+
+    try {
+      await session.mcp.waitForInitialLoad();
+      await expect(new SessionAPIImpl(session).getMcpStartupMetrics({})).resolves.toEqual({
+        durationMs: expect.any(Number),
+      });
+
+      expect(records).toContainEqual({
+        event: 'mcp_connected',
+        properties: {
+          server_count: 1,
+          total_count: 2,
+        },
+      });
+      expect(records).toContainEqual({
+        event: 'mcp_failed',
+        properties: {
+          failed_count: 1,
+          total_count: 2,
+        },
+      });
+    } finally {
+      await session.close();
+    }
+  }, 20000);
+});
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'kimi-core-init-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function testProviderManager(): ProviderManager {
+  return new ProviderManager({
+    config: {
+      providers: {
+        test: {
+          type: MOCK_PROVIDER.type,
+          apiKey: MOCK_PROVIDER.apiKey,
+        },
+      },
+      models: {
+        [MOCK_PROVIDER.model]: {
+          provider: 'test',
+          model: MOCK_PROVIDER.model,
+          maxContextSize: 1_000_000,
+        },
+      },
+    },
+  });
+}
+
+function testProfile(): ResolvedAgentProfile {
+  return {
+    name: 'test',
+    systemPrompt: () => '<system-prompt>',
+    tools: [],
+  };
+}
+
+function createSessionRpc(events: Array<Record<string, unknown>>): SDKSessionRPC {
+  return {
+    emitEvent: vi.fn(async (event) => {
+      events.push(event);
+    }),
+    requestApproval: vi.fn(async () => ({ decision: 'cancelled' })),
+    requestQuestion: vi.fn(async () => null),
+    toolCall: vi.fn(async () => ({
+      output: 'custom tools are not supported in this test',
+      isError: true,
+    })),
+  } as SDKSessionRPC;
+}
diff --git a/packages/agent-core/test/session/lifecycle-hooks.test.ts b/packages/agent-core/test/session/lifecycle-hooks.test.ts
new file mode 100644
index 000000000..81d3759c3
--- /dev/null
+++ b/packages/agent-core/test/session/lifecycle-hooks.test.ts
@@ -0,0 +1,251 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import type { Writable } from 'node:stream';
+
+import { localKaos, type KaosProcess } from '@moonshot-ai/kaos';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { SDKSessionRPC } from '../../src/rpc';
+import { Session } from '../../src/session';
+
+const OS_ENV = {
+  osKind: 'Linux',
+  osArch: 'arm64',
+  osVersion: 'test',
+  shellPath: '/bin/bash',
+  shellName: 'bash',
+} as const;
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  vi.unstubAllEnvs();
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+describe('Session lifecycle hooks', () => {
+  it('fires SessionStart on startup and SessionEnd on close', async () => {
+    const { command, logPath, sessionDir, workDir } = await hookFixture();
+    const session = new Session({
+      runtime: { kaos: localKaos, osEnv: OS_ENV },
+      id: 'session-123',
+      homedir: sessionDir,
+      cwd: workDir,
+      rpc: createSessionRpc(),
+      skills: { explicitDirs: [join(workDir, 'missing-skills')] },
+      hooks: [
+        { event: 'SessionStart', matcher: 'startup', command, timeout: 5 },
+        { event: 'SessionEnd', matcher: 'exit', command, timeout: 5 },
+      ],
+    });
+
+    await session.createMain();
+    await session.close();
+
+    expect(await readHookPayloads(logPath)).toMatchObject([
+      {
+        hook_event_name: 'SessionStart',
+        session_id: 'session-123',
+        cwd: workDir,
+        source: 'startup',
+      },
+      {
+        hook_event_name: 'SessionEnd',
+        session_id: 'session-123',
+        cwd: workDir,
+        reason: 'exit',
+      },
+    ]);
+  });
+
+  it('fires SessionStart with resume source after loading metadata', async () => {
+    const { command, logPath, sessionDir, workDir } = await hookFixture();
+    await writeFile(
+      join(sessionDir, 'state.json'),
+      JSON.stringify({
+        createdAt: '2026-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+        title: 'Resumed Session',
+        isCustomTitle: false,
+        agents: {},
+        custom: {},
+      }),
+      'utf-8',
+    );
+    const session = new Session({
+      runtime: { kaos: localKaos, osEnv: OS_ENV },
+      id: 'session-456',
+      homedir: sessionDir,
+      cwd: workDir,
+      rpc: createSessionRpc(),
+      skills: { explicitDirs: [join(workDir, 'missing-skills')] },
+      hooks: [{ event: 'SessionStart', matcher: 'resume', command, timeout: 5 }],
+    });
+
+    await session.resume();
+
+    expect(await readHookPayloads(logPath)).toMatchObject([
+      {
+        hook_event_name: 'SessionStart',
+        session_id: 'session-456',
+        cwd: workDir,
+        source: 'resume',
+      },
+    ]);
+  });
+
+  it('does not let failing SessionStart or SessionEnd hook commands interrupt startup or close', async () => {
+    const { sessionDir, workDir } = await hookFixture();
+    const session = new Session({
+      runtime: { kaos: localKaos, osEnv: OS_ENV },
+      id: 'session-reject',
+      homedir: sessionDir,
+      cwd: workDir,
+      rpc: createSessionRpc(),
+      skills: { explicitDirs: [join(workDir, 'missing-skills')] },
+      hooks: [
+        { event: 'SessionStart', matcher: 'startup', command: 'exit 1', timeout: 5 },
+        { event: 'SessionEnd', matcher: 'exit', command: 'exit 1', timeout: 5 },
+      ],
+    });
+
+    await expect(session.createMain()).resolves.toBeDefined();
+    await expect(session.close()).resolves.toBeUndefined();
+  });
+
+  it('stops background tasks on close when keepAliveOnExit is false', async () => {
+    const { sessionDir, workDir } = await hookFixture();
+    const session = new Session({
+      runtime: { kaos: localKaos, osEnv: OS_ENV },
+      id: 'session-bg-cleanup',
+      homedir: sessionDir,
+      cwd: workDir,
+      rpc: createSessionRpc(),
+      skills: { explicitDirs: [join(workDir, 'missing-skills')] },
+      background: { keepAliveOnExit: false },
+    });
+    const agent = await session.createMain();
+    const { proc, killSpy } = pendingProcess();
+    const taskId = agent.background.register(proc, 'sleep 60', 'exit cleanup');
+
+    await session.close();
+
+    expect(killSpy).toHaveBeenCalledWith('SIGTERM');
+    expect(agent.background.getTask(taskId)?.status).toBe('killed');
+  });
+
+  it('lets the environment override config when deciding background task cleanup', async () => {
+    vi.stubEnv('KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT', '0');
+    const { sessionDir, workDir } = await hookFixture();
+    const session = new Session({
+      runtime: { kaos: localKaos, osEnv: OS_ENV },
+      id: 'session-bg-env-cleanup',
+      homedir: sessionDir,
+      cwd: workDir,
+      rpc: createSessionRpc(),
+      skills: { explicitDirs: [join(workDir, 'missing-skills')] },
+      background: { keepAliveOnExit: true },
+    });
+    const agent = await session.createMain();
+    const { proc, killSpy } = pendingProcess();
+    const taskId = agent.background.register(proc, 'sleep 60', 'env cleanup');
+
+    await session.close();
+
+    expect(killSpy).toHaveBeenCalledWith('SIGTERM');
+    expect(agent.background.getTask(taskId)?.status).toBe('killed');
+  });
+});
+
+async function hookFixture(): Promise<{
+  readonly command: string;
+  readonly logPath: string;
+  readonly sessionDir: string;
+  readonly workDir: string;
+}> {
+  const dir = await makeTempDir();
+  const workDir = join(dir, 'work');
+  const sessionDir = join(dir, 'session');
+  const logPath = join(dir, 'hooks.jsonl');
+  const scriptPath = join(dir, 'record-hook.cjs');
+  await mkdir(join(workDir, '.git'), { recursive: true });
+  await mkdir(sessionDir, { recursive: true });
+  await writeFile(
+    scriptPath,
+    [
+      "const { appendFileSync } = require('node:fs');",
+      "let input = '';",
+      "process.stdin.on('data', (chunk) => { input += chunk; });",
+      "process.stdin.on('end', () => { appendFileSync(process.argv[2], `${input.trim()}\\n`); });",
+      '',
+    ].join('\n'),
+    'utf-8',
+  );
+  return {
+    command: `node ${JSON.stringify(scriptPath)} ${JSON.stringify(logPath)}`,
+    logPath,
+    sessionDir,
+    workDir,
+  };
+}
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'kimi-session-hooks-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+async function readHookPayloads(path: string): Promise<readonly Record<string, unknown>[]> {
+  const text = await readFile(path, 'utf-8');
+  return text
+    .trim()
+    .split('\n')
+    .filter((line) => line.length > 0)
+    .map((line) => JSON.parse(line) as Record<string, unknown>);
+}
+
+function createSessionRpc(): SDKSessionRPC {
+  return {
+    emitEvent: vi.fn(async () => {}),
+    requestApproval: vi.fn(async () => ({ decision: 'cancelled' })),
+    requestQuestion: vi.fn(async () => null),
+    toolCall: vi.fn(async () => ({
+      output: 'custom tools are not supported in this test',
+      isError: true,
+    })),
+  } as SDKSessionRPC;
+}
+
+function pendingProcess(exitOnKill = 143): {
+  readonly proc: KaosProcess;
+  readonly killSpy: ReturnType<typeof vi.fn>;
+} {
+  let resolveWait: (n: number) => void = () => {
+    /* replaced below */
+  };
+  const waitPromise = new Promise<number>((resolve) => {
+    resolveWait = resolve;
+  });
+  let currentExitCode: number | null = null;
+  const killSpy = vi.fn(async () => {
+    if (currentExitCode !== null) return;
+    currentExitCode = exitOnKill;
+    resolveWait(exitOnKill);
+  });
+  const proc: KaosProcess = {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 54_321,
+    get exitCode(): number | null {
+      return currentExitCode;
+    },
+    wait: () => waitPromise,
+    kill: killSpy as unknown as KaosProcess['kill'],
+  };
+  return { proc, killSpy };
+}
diff --git a/packages/agent-core/test/session/subagent-host.test.ts b/packages/agent-core/test/session/subagent-host.test.ts
new file mode 100644
index 000000000..2f20b85ca
--- /dev/null
+++ b/packages/agent-core/test/session/subagent-host.test.ts
@@ -0,0 +1,1074 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { localKaos } from '@moonshot-ai/kaos';
+import type { ToolCall } from '@moonshot-ai/kosong';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { Agent } from '../../src/agent';
+import type { ResolvedAgentProfile } from '../../src/profile';
+import type { SDKSessionRPC } from '../../src/rpc';
+import { Session } from '../../src/session';
+import { collectGitContext } from '../../src/session/git-context';
+import { SessionSubagentHost } from '../../src/session/subagent-host';
+import { testAgent } from '../agent/harness/agent';
+import { createFakeKaos } from '../tools/fixtures/fake-kaos';
+
+// Git context collection is exercised in git-context.test.ts; here it is
+// mocked so subagent-host tests stay deterministic and assert only the
+// wiring (explore subagents get the block prepended, others do not).
+vi.mock('../../src/session/git-context', () => ({
+  collectGitContext: vi.fn(async () => ''),
+}));
+
+const signal = new AbortController().signal;
+const TEST_OS_ENV = {
+  osKind: 'Linux',
+  osArch: 'arm64',
+  osVersion: 'test',
+  shellPath: '/bin/bash',
+  shellName: 'bash',
+} as const;
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+describe('SessionSubagentHost', () => {
+  it('fires subagent lifecycle hooks around the child turn', async () => {
+    const child = testAgent();
+    const calls: Array<{ readonly event: string; readonly childLlmCallCount: number }> = [];
+    const trigger = vi.fn(async (event: string, _args?: unknown) => {
+      calls.push({ event, childLlmCallCount: child.llmCalls.length });
+      return [];
+    });
+    const fireAndForgetTrigger = vi.fn((event: string) => {
+      calls.push({ event, childLlmCallCount: child.llmCalls.length });
+      return Promise.resolve([]);
+    });
+    const parent = testAgent({
+      hookEngine: { trigger, fireAndForgetTrigger } as unknown as NonNullable<Agent['hooks']>,
+    });
+    parent.configure();
+    parent.newEvents();
+
+    const summary =
+      'Implemented the subagent task completely and returned a detailed enough summary for the parent agent to continue confidently without repeating the child agent work. '.repeat(
+        2,
+      );
+    child.mockNextResponse({ type: 'text', text: summary });
+    const session = fakeSession(parent.agent, child.agent);
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.spawn('coder', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Implement the fix',
+      description: 'Fix bug',
+      runInBackground: false,
+      signal,
+    });
+    await handle.completion;
+
+    const startArgs = trigger.mock.calls[0]?.[1];
+    expect(trigger.mock.calls[0]?.[0]).toBe('SubagentStart');
+    expect(startArgs).toMatchObject({
+      matcherValue: 'coder',
+      inputData: {
+        agentName: 'coder',
+        prompt: 'Implement the fix',
+      },
+    });
+    expect((startArgs as { readonly signal?: unknown } | undefined)?.signal).toBeInstanceOf(
+      AbortSignal,
+    );
+    expect(fireAndForgetTrigger).toHaveBeenCalledWith('SubagentStop', {
+      matcherValue: 'coder',
+      inputData: {
+        agentName: 'coder',
+        response: summary.trim(),
+      },
+    });
+    expect(calls).toEqual([
+      { event: 'SubagentStart', childLlmCallCount: 0 },
+      { event: 'SubagentStop', childLlmCallCount: 1 },
+    ]);
+  });
+
+  it('ignores blocking results from subagent lifecycle hooks', async () => {
+    const trigger = vi.fn(async () => [{ action: 'block', reason: 'observer only' }]);
+    const fireAndForgetTrigger = vi.fn(() => Promise.resolve([{ action: 'block' }]));
+    const parent = testAgent({
+      hookEngine: { trigger, fireAndForgetTrigger } as unknown as NonNullable<Agent['hooks']>,
+    });
+    parent.configure();
+    parent.newEvents();
+
+    const summary =
+      'Completed the subagent task with enough implementation detail and verification context for the parent agent to continue without repeating the work. '.repeat(
+        2,
+      );
+    const child = testAgent();
+    child.mockNextResponse({ type: 'text', text: summary });
+    const session = fakeSession(parent.agent, child.agent);
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.spawn('coder', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Implement the fix',
+      description: 'Fix bug',
+      runInBackground: false,
+      signal,
+    });
+
+    await expect(handle.completion).resolves.toMatchObject({ result: summary.trim() });
+    expect(parent.allEvents).toContainEqual(
+      expect.objectContaining({
+        type: '[rpc]',
+        event: 'subagent.completed',
+        args: expect.objectContaining({ subagentId: 'agent-0' }),
+      }),
+    );
+    expect(parent.allEvents).not.toContainEqual(
+      expect.objectContaining({
+        type: '[rpc]',
+        event: 'subagent.failed',
+      }),
+    );
+  });
+
+  it('runs a child agent turn and returns the last assistant text', async () => {
+    const telemetryTrack = vi.fn();
+    const parent = testAgent({ telemetry: { track: telemetryTrack } });
+    parent.configure();
+    await parent.rpc.setPermission({ mode: 'yolo' });
+    parent.agent.permission.rules = [
+      {
+        decision: 'allow',
+        scope: 'session-runtime',
+        pattern: 'Read',
+      },
+    ];
+    parent.newEvents();
+
+    const child = testAgent({
+      type: 'sub',
+      permission: { parent: parent.agent.permission },
+    });
+    child.mockNextResponse({ type: 'text', text: 'Investigated the request and completed the child task end to end. The relevant module was located, its behavior traced through every call site, and the requested change applied and verified against the existing test suite.' });
+    const session = fakeSession(parent.agent, child.agent);
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.spawn('explore', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Find the cause',
+      description: 'Find cause',
+      runInBackground: false,
+      signal,
+    });
+
+    await expect(handle.completion).resolves.toMatchObject({
+      result: 'Investigated the request and completed the child task end to end. The relevant module was located, its behavior traced through every call site, and the requested change applied and verified against the existing test suite.',
+    });
+    expect(handle.agentId).toBe('agent-0');
+    expect(handle.profileName).toBe('explore');
+
+    expect(parent.allEvents).toContainEqual(
+      expect.objectContaining({
+        type: '[rpc]',
+        event: 'subagent.spawned',
+        args: expect.objectContaining({
+          subagentId: 'agent-0',
+          subagentName: 'explore',
+          parentAgentId: 'main',
+          parentToolCallId: 'call_agent',
+        }),
+      }),
+    );
+    expect(telemetryTrack).toHaveBeenCalledWith('subagent_created', {
+      subagent_name: 'explore',
+      run_in_background: false,
+    });
+    expect(parent.allEvents).toContainEqual(
+      expect.objectContaining({
+        type: '[rpc]',
+        event: 'subagent.completed',
+        args: expect.objectContaining({
+          subagentId: 'agent-0',
+          parentToolCallId: 'call_agent',
+          resultSummary: 'Investigated the request and completed the child task end to end. The relevant module was located, its behavior traced through every call site, and the requested change applied and verified against the existing test suite.',
+        }),
+      }),
+    );
+    expect(child.agent.config.data()).toMatchObject({
+      cwd: parent.agent.config.cwd,
+      provider: parent.agent.config.data().provider,
+      profileName: 'explore',
+      thinkingLevel: parent.agent.config.thinkingLevel,
+    });
+    expect(child.agent.config.systemPrompt).toContain('codebase exploration specialist');
+    expect(child.agent.permission.mode).toBe('yolo');
+    expect(child.agent.permission.rules).toEqual([]);
+    expect(child.agent.permission.data().rules).toEqual(parent.agent.permission.rules);
+    expect(child.llmCalls[0]?.systemPrompt).toContain('codebase exploration specialist');
+    expect(child.llmCalls[0]?.tools.map((tool) => tool.name).toSorted()).toEqual([
+      'Bash',
+      'Glob',
+      'Grep',
+      'Read',
+    ]);
+    expect(child.llmCalls[0]?.history).toMatchObject([
+      {
+        role: 'user',
+        content: [{ type: 'text', text: 'Find the cause' }],
+      },
+    ]);
+  });
+
+  it('falls back to bundled subagent profiles when the parent profile is missing', async () => {
+    const parent = testAgent();
+    parent.configure();
+    parent.newEvents();
+
+    const child = testAgent();
+    child.mockNextResponse({ type: 'text', text: 'Implemented the requested fix in the target module, updated all affected call sites, and confirmed the change compiles cleanly and passes the existing test suite. No unrelated code paths were touched while making this change.' });
+    const session = fakeSession(parent.agent, child.agent);
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.spawn('coder', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Implement the fix',
+      description: 'Fix bug',
+      runInBackground: false,
+      signal,
+    });
+
+    await expect(handle.completion).resolves.toMatchObject({
+      result:
+        'Implemented the requested fix in the target module, updated all affected call sites, and confirmed the change compiles cleanly and passes the existing test suite. No unrelated code paths were touched while making this change.',
+    });
+    expect(child.agent.config.profileName).toBe('coder');
+    expect(child.llmCalls[0]?.systemPrompt).toContain('You are now running as a subagent.');
+    expect(child.llmCalls[0]?.tools.map((tool) => tool.name).toSorted()).toEqual([
+      'Bash',
+      'Edit',
+      'Glob',
+      'Grep',
+      'Read',
+      'Write',
+    ]);
+    expect(child.llmCalls[0]?.history).toMatchObject([
+      {
+        role: 'user',
+        content: [{ type: 'text', text: 'Implement the fix' }],
+      },
+    ]);
+  });
+
+  it('rejects unknown subagent types before creating a child agent', async () => {
+    const parent = testAgent();
+    parent.configure();
+    const createAgent = vi.fn();
+    const host = new SessionSubagentHost(
+      {
+        agents: new Map([['main', parent.agent]]),
+        createAgent,
+      } as never,
+      'main',
+    );
+
+    await expect(
+      host.spawn('missing', {
+        parentToolCallId: 'call_agent',
+        prompt: 'Find the cause',
+        description: 'Find cause',
+        runInBackground: false,
+        signal,
+      }),
+    ).rejects.toThrow('Subagent profile "missing" was not found');
+    expect(createAgent).not.toHaveBeenCalled();
+  });
+
+  it('cancels the child turn when the caller signal aborts', async () => {
+    const parent = testAgent();
+    parent.configure();
+    parent.newEvents();
+
+    const controller = new AbortController();
+    const child = testAgent();
+    child.mockNextResponse({ type: 'text', text: 'I will run Bash.' }, bashCall());
+    const session = fakeSession(parent.agent, child.agent);
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.spawn('explore', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Keep working',
+      description: 'Long task',
+      runInBackground: false,
+      signal: controller.signal,
+    });
+
+    await child.untilApprovalRequest();
+    controller.abort();
+
+    await expect(handle.completion).rejects.toThrow('Aborted');
+    expect(child.allEvents).toContainEqual(
+      expect.objectContaining({
+        type: '[wire]',
+        event: 'turn.cancel',
+        args: expect.objectContaining({ turnId: 0 }),
+      }),
+    );
+    expect(parent.allEvents).toContainEqual(
+      expect.objectContaining({
+        type: '[rpc]',
+        event: 'subagent.failed',
+        args: expect.objectContaining({
+          subagentId: 'agent-0',
+          parentToolCallId: 'call_agent',
+          error: 'Aborted',
+        }),
+      }),
+    );
+  });
+
+  it('cancelAll aborts foreground children', async () => {
+    const parent = testAgent();
+    parent.configure();
+    parent.newEvents();
+
+    const child = testAgent();
+    child.mockNextResponse({ type: 'text', text: 'I will run Bash.' }, bashCall());
+    const session = fakeSession(parent.agent, child.agent);
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.spawn('explore', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Keep working',
+      description: 'Long task',
+      runInBackground: false,
+      signal,
+    });
+
+    await child.untilApprovalRequest();
+    host.cancelAll();
+
+    await expect(handle.completion).rejects.toThrow('Aborted');
+    expect(child.allEvents).toContainEqual(
+      expect.objectContaining({
+        type: '[wire]',
+        event: 'turn.cancel',
+        args: expect.objectContaining({ turnId: 0 }),
+      }),
+    );
+  });
+
+  it('cancelAll leaves background children running until their task signal aborts', async () => {
+    const parent = testAgent();
+    parent.configure();
+    parent.newEvents();
+
+    const backgroundController = new AbortController();
+    const child = testAgent();
+    child.mockNextResponse({ type: 'text', text: 'I will run Bash.' }, bashCall());
+    const session = fakeSession(parent.agent, child.agent);
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.spawn('explore', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Keep working',
+      description: 'Long task',
+      runInBackground: true,
+      signal: backgroundController.signal,
+    });
+
+    await child.untilApprovalRequest();
+    host.cancelAll();
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    expect(child.agent.turn.hasActiveTurn).toBe(true);
+    expect(child.allEvents).not.toContainEqual(
+      expect.objectContaining({
+        type: '[wire]',
+        event: 'turn.cancel',
+        args: expect.objectContaining({ turnId: 0 }),
+      }),
+    );
+
+    backgroundController.abort();
+
+    await expect(handle.completion).rejects.toThrow('Aborted');
+    expect(child.allEvents).toContainEqual(
+      expect.objectContaining({
+        type: '[wire]',
+        event: 'turn.cancel',
+        args: expect.objectContaining({ turnId: 0 }),
+      }),
+    );
+  });
+
+  it('re-prompts the child when the first summary is too short', async () => {
+    const parent = testAgent();
+    parent.configure();
+    parent.newEvents();
+
+    const longSummary = 'Detailed findings: '.repeat(20);
+    const child = testAgent();
+    child.mockNextResponse({ type: 'text', text: 'done' });
+    child.mockNextResponse({ type: 'text', text: longSummary });
+    const session = fakeSession(parent.agent, child.agent);
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.spawn('coder', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Investigate',
+      description: 'Investigate',
+      runInBackground: false,
+      signal,
+    });
+
+    await expect(handle.completion).resolves.toMatchObject({ result: longSummary.trim() });
+    expect(child.llmCalls).toHaveLength(2);
+    expect(child.llmCalls[1]?.history.at(-1)).toMatchObject({
+      role: 'user',
+      content: [{ type: 'text', text: expect.stringContaining('too brief') }],
+    });
+  });
+
+  it('fails the child instead of re-prompting when the response is truncated', async () => {
+    const parent = testAgent();
+    parent.configure();
+    parent.newEvents();
+
+    const child = testAgent();
+    child.mockNextProviderResponse({
+      parts: [
+        { type: 'think', think: 'The child used its output budget before writing a summary.' },
+      ],
+      finishReason: 'truncated',
+      rawFinishReason: 'length',
+    });
+    const session = fakeSession(parent.agent, child.agent);
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.spawn('coder', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Investigate',
+      description: 'Investigate',
+      runInBackground: false,
+      signal,
+    });
+
+    await expect(handle.completion).rejects.toThrow(
+      'Subagent turn failed before completing its final summary: reason=max_tokens',
+    );
+    expect(child.llmCalls).toHaveLength(1);
+    expect(parent.allEvents).toContainEqual(
+      expect.objectContaining({
+        type: '[rpc]',
+        event: 'subagent.failed',
+        args: expect.objectContaining({
+          subagentId: 'agent-0',
+          parentToolCallId: 'call_agent',
+          error: expect.stringContaining(
+            'Subagent turn failed before completing its final summary: reason=max_tokens',
+          ),
+        }),
+      }),
+    );
+    expect(parent.allEvents).not.toContainEqual(
+      expect.objectContaining({
+        type: '[rpc]',
+        event: 'subagent.completed',
+      }),
+    );
+  });
+
+  it('does not re-prompt when the first summary is long enough', async () => {
+    const parent = testAgent();
+    parent.configure();
+    parent.newEvents();
+
+    const longSummary = 'Comprehensive technical summary. '.repeat(10);
+    const child = testAgent();
+    child.mockNextResponse({ type: 'text', text: longSummary });
+    const session = fakeSession(parent.agent, child.agent);
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.spawn('coder', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Investigate',
+      description: 'Investigate',
+      runInBackground: false,
+      signal,
+    });
+
+    await expect(handle.completion).resolves.toMatchObject({ result: longSummary.trim() });
+    expect(child.llmCalls).toHaveLength(1);
+  });
+
+  it('prepends git context to the prompt for explore subagents', async () => {
+    vi.mocked(collectGitContext).mockResolvedValueOnce(
+      '<git-context>\nWorking directory: /repo\nBranch: main\n</git-context>',
+    );
+    const parent = testAgent();
+    parent.configure();
+    parent.newEvents();
+
+    const summary =
+      'Explored the repository thoroughly and reported the findings in a complete and detailed summary that gives the parent agent everything it needs to continue the work without redoing the investigation all over again.';
+    const child = testAgent();
+    child.mockNextResponse({ type: 'text', text: summary });
+    const session = fakeSession(parent.agent, child.agent);
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.spawn('explore', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Find the cause',
+      description: 'Find cause',
+      runInBackground: false,
+      signal,
+    });
+    await handle.completion;
+
+    expect(child.llmCalls[0]?.history[0]).toMatchObject({
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text: '<git-context>\nWorking directory: /repo\nBranch: main\n</git-context>\n\nFind the cause',
+        },
+      ],
+    });
+  });
+
+  it('does not prepend git context for non-explore subagents', async () => {
+    const parent = testAgent();
+    parent.configure();
+    parent.newEvents();
+
+    const summary =
+      'Implemented the requested change in full and verified it against the existing test suite, leaving a thorough and complete summary so the parent agent can proceed without repeating any of the finished investigation work.';
+    const child = testAgent();
+    child.mockNextResponse({ type: 'text', text: summary });
+    const session = fakeSession(parent.agent, child.agent);
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.spawn('coder', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Implement the fix',
+      description: 'Fix bug',
+      runInBackground: false,
+      signal,
+    });
+    await handle.completion;
+
+    expect(child.llmCalls[0]?.history[0]).toMatchObject({
+      role: 'user',
+      content: [{ type: 'text', text: 'Implement the fix' }],
+    });
+  });
+
+  it('resumes an idle child agent by id', async () => {
+    const parent = testAgent();
+    parent.configure();
+    parent.agent.permission.setMode('yolo');
+
+    const child = testAgent({
+      type: 'sub',
+      permission: { parent: parent.agent.permission },
+    });
+    child.configure({ tools: ['Read'] });
+    child.agent.useProfile(
+      profile({ name: 'explore', tools: ['Read'], systemPrompt: 'explore prompt' }),
+    );
+    child.agent.context.appendUserMessage([{ type: 'text', text: 'Earlier context' }]);
+    child.mockNextResponse({
+      type: 'text',
+      text: 'Resumed the subagent from its earlier context and carried the task through to completion, then reported a full and detailed technical summary so the parent agent can continue without repeating prior work.',
+    });
+
+    const session = fakeSession(parent.agent, child.agent, {
+      'agent-0': {
+        homedir: '/tmp/kimi-session/agents/agent-0',
+        type: 'sub',
+        parentAgentId: 'main',
+      },
+    });
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.resume('agent-0', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Continue from context',
+      description: 'Continue work',
+      runInBackground: false,
+      signal,
+    });
+
+    expect(handle).toMatchObject({
+      agentId: 'agent-0',
+      profileName: 'explore',
+      resumed: true,
+    });
+    await expect(handle.completion).resolves.toMatchObject({
+      result:
+        'Resumed the subagent from its earlier context and carried the task through to completion, then reported a full and detailed technical summary so the parent agent can continue without repeating prior work.',
+    });
+    expect(session.createAgent).not.toHaveBeenCalled();
+    expect(child.agent.permission.mode).toBe('yolo');
+    expect(child.lastLlmInput()).toMatchInlineSnapshot(`
+      system: "explore prompt"
+      tools: Read
+      messages:
+        user: text "Earlier context\\n\\nContinue from context"
+    `);
+    expect(parent.allEvents).toContainEqual(
+      expect.objectContaining({
+        type: '[rpc]',
+        event: 'subagent.spawned',
+        args: expect.objectContaining({
+          subagentId: 'agent-0',
+          subagentName: 'explore',
+          parentToolCallId: 'call_agent',
+        }),
+      }),
+    );
+  });
+
+  it('realigns a resumed subagent to the parent agent current model', async () => {
+    const parent = testAgent();
+    parent.configure();
+    parent.agent.permission.setMode('yolo');
+
+    const child = testAgent();
+    child.configure({ tools: ['Read'] });
+    // The child was originally spawned with a model that no longer matches the
+    // parent agent's current model (as if the parent ran setModel afterwards).
+    child.agent.config.update({ modelAlias: 'stale-model-from-initial-spawn' });
+    child.agent.useProfile(
+      profile({ name: 'explore', tools: ['Read'], systemPrompt: 'explore prompt' }),
+    );
+    child.agent.context.appendUserMessage([{ type: 'text', text: 'Earlier context' }]);
+    child.mockNextResponse({
+      type: 'text',
+      text: 'Resumed the subagent from its earlier context and carried the task through to completion, then reported a full and detailed technical summary so the parent agent can continue without repeating prior work.',
+    });
+
+    const session = fakeSession(parent.agent, child.agent, {
+      'agent-0': {
+        homedir: '/tmp/kimi-session/agents/agent-0',
+        type: 'sub',
+        parentAgentId: 'main',
+      },
+    });
+    const host = new SessionSubagentHost(session, 'main');
+
+    const handle = await host.resume('agent-0', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Continue from context',
+      description: 'Continue work',
+      runInBackground: false,
+      signal,
+    });
+
+    await handle.completion;
+    // resume must realign the child to the parent agent's current model rather
+    // than leave it on the stale model from its initial spawn.
+    expect(child.agent.config.modelAlias).toBe(parent.agent.config.modelAlias);
+    expect(child.agent.config.modelAlias).not.toBe('stale-model-from-initial-spawn');
+  });
+});
+
+describe('Session resume permission parent chain', () => {
+  it('restores subagent live-derived permission when metadata lists the child first', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'kimi-permission-chain-'));
+    tempDirs.push(dir);
+    const sessionDir = join(dir, 'session');
+    const workDir = join(dir, 'work');
+    const mainDir = join(sessionDir, 'agents', 'main');
+    const childDir = join(sessionDir, 'agents', 'agent-0');
+    await mkdir(workDir, { recursive: true });
+    await mkdir(sessionDir, { recursive: true });
+    await writeFile(
+      join(sessionDir, 'state.json'),
+      JSON.stringify(
+        {
+          createdAt: '2026-01-01T00:00:00.000Z',
+          updatedAt: '2026-01-01T00:00:00.000Z',
+          title: 'Permission Chain',
+          isCustomTitle: false,
+          agents: {
+            'agent-0': {
+              homedir: childDir,
+              type: 'sub',
+              parentAgentId: 'main',
+            },
+            main: {
+              homedir: mainDir,
+              type: 'main',
+              parentAgentId: null,
+            },
+          },
+          custom: {},
+        },
+        null,
+        2,
+      ),
+      'utf-8',
+    );
+    await writeWire(mainDir, [
+      {
+        type: 'permission.set_mode',
+        mode: 'yolo',
+      },
+      {
+        type: 'permission.record_approval_result',
+        turnId: 0,
+        toolCallId: 'call_parent_bash',
+        toolName: 'Bash',
+        action: 'run command',
+        result: {
+          decision: 'approved',
+          scope: 'session',
+          selectedLabel: 'Approve for this session',
+        },
+      },
+    ]);
+    await writeWire(childDir, []);
+
+    const session = new Session({
+      runtime: { kaos: localKaos, osEnv: TEST_OS_ENV },
+      homedir: sessionDir,
+      cwd: workDir,
+      rpc: createSessionRpc(),
+      initializeMainAgent: false,
+      skills: { explicitDirs: [join(workDir, 'missing-skills')] },
+    });
+
+    try {
+      await session.resume();
+
+      const child = session.agents.get('agent-0');
+      expect(child?.permission.mode).toBe('yolo');
+      expect(child?.permission.rules).toEqual([]);
+      expect(child?.permission.data().rules).toContainEqual({
+        decision: 'allow',
+        scope: 'session-runtime',
+        pattern: 'Bash',
+        reason: 'approve_for_session: run command',
+      });
+    } finally {
+      await session.close();
+    }
+  });
+});
+
+describe('Session.createAgent', () => {
+  it('uses the Kaos current directory when the session cwd is omitted', async () => {
+    const workDir = '/remote/project';
+    const kaos = createFakeKaos({
+      getcwd: () => workDir,
+      mkdir: vi.fn(async () => {}),
+      writeText: vi.fn().mockResolvedValue(0),
+      stat: vi.fn(async (path: string) => {
+        if ([workDir, `${workDir}/.git`].includes(path)) {
+          return stat('dir');
+        }
+        if ([`${workDir}/README.md`, `${workDir}/AGENTS.md`].includes(path)) {
+          return stat('file');
+        }
+        throw new Error(`ENOENT ${path}`);
+      }),
+      iterdir: async function* (path: string) {
+        if (path === workDir) {
+          yield `${workDir}/README.md`;
+          return;
+        }
+        throw new Error(`ENOENT ${path}`);
+      },
+      readText: vi.fn(async (path: string) => {
+        if (path === `${workDir}/AGENTS.md`) return 'remote instructions';
+        throw new Error(`ENOENT ${path}`);
+      }),
+    });
+    const session = new Session({
+      id: 'test-subagent-remote-context',
+      runtime: {
+        kaos,
+        osEnv: {
+          osKind: 'Linux',
+          osArch: 'arm64',
+          osVersion: 'test',
+          shellPath: '/bin/bash',
+          shellName: 'bash',
+        },
+      },
+      homedir: '/tmp/kimi-session',
+      rpc: createSessionRpc(),
+      initializeMainAgent: false,
+    });
+
+    const created = await session.createAgent({ type: 'main' }, contextProfile());
+
+    expect(created.agent.config.systemPrompt).toContain('cwd=/remote/project');
+    expect(created.agent.config.systemPrompt).toContain('listing=└── README.md');
+    expect(created.agent.config.systemPrompt).toContain('remote instructions');
+  });
+
+  it('renders profiles with the current directory listing and merged AGENTS.md files', async () => {
+    const workDir = '/repo/packages/app';
+    const kaos = createFakeKaos({
+      mkdir: vi.fn(async () => {}),
+      writeText: vi.fn().mockResolvedValue(0),
+      stat: vi.fn(async (path: string) => {
+        if (
+          [
+            '/repo',
+            '/repo/.git',
+            '/repo/packages',
+            workDir,
+            `${workDir}/src`,
+            `${workDir}/.kimi-code`,
+          ].includes(path)
+        ) {
+          return stat('dir');
+        }
+        if (
+          [
+            '/repo/AGENTS.md',
+            `${workDir}/.kimi-code/AGENTS.md`,
+            `${workDir}/AGENTS.md`,
+            `${workDir}/package.json`,
+            `${workDir}/src/index.ts`,
+          ].includes(path)
+        ) {
+          return stat('file');
+        }
+        throw new Error(`ENOENT ${path}`);
+      }),
+      iterdir: async function* (path: string) {
+        if (path === workDir) {
+          yield `${workDir}/src`;
+          yield `${workDir}/package.json`;
+          return;
+        }
+        if (path === `${workDir}/src`) {
+          yield `${workDir}/src/index.ts`;
+          return;
+        }
+        throw new Error(`ENOENT ${path}`);
+      },
+      readText: vi.fn(async (path: string) => {
+        if (path === '/repo/AGENTS.md') return 'root instructions';
+        if (path === `${workDir}/.kimi-code/AGENTS.md`) return 'brand instructions';
+        if (path === `${workDir}/AGENTS.md`) return 'leaf instructions';
+        throw new Error(`ENOENT ${path}`);
+      }),
+    });
+    const session = new Session({
+      id: 'test-subagent-agents-md',
+      runtime: {
+        kaos,
+        osEnv: {
+          osKind: 'Linux',
+          osArch: 'arm64',
+          osVersion: 'test',
+          shellPath: '/bin/bash',
+          shellName: 'bash',
+        },
+      },
+      homedir: '/tmp/kimi-session',
+      cwd: workDir,
+      rpc: createSessionRpc(),
+      initializeMainAgent: false,
+    });
+
+    const created = await session.createAgent({ type: 'main' }, contextProfile());
+
+    expect(created.agent.config.systemPrompt).toContain('cwd=/repo/packages/app');
+    expect(created.agent.config.systemPrompt).toContain('listing=├── src/');
+    expect(created.agent.config.systemPrompt).toContain('│   └── index.ts');
+    expect(created.agent.config.systemPrompt).toContain('└── package.json');
+    expect(created.agent.config.systemPrompt).toContain('<!-- From: /repo/AGENTS.md -->');
+    expect(created.agent.config.systemPrompt).toContain('root instructions');
+    expect(created.agent.config.systemPrompt).toContain(
+      '<!-- From: /repo/packages/app/.kimi-code/AGENTS.md -->',
+    );
+    expect(created.agent.config.systemPrompt).toContain('brand instructions');
+    expect(created.agent.config.systemPrompt).toContain(
+      '<!-- From: /repo/packages/app/AGENTS.md -->',
+    );
+    expect(created.agent.config.systemPrompt).toContain('leaf instructions');
+  });
+
+  it('allocates the next unused generated agent id', async () => {
+    const session = new Session({
+      id: 'test-subagent-agent-id',
+      runtime: {
+        kaos: createFakeKaos({
+          mkdir: vi.fn().mockResolvedValue(undefined),
+          writeText: vi.fn().mockResolvedValue(0),
+        }),
+        osEnv: {
+          osKind: 'Linux',
+          osArch: 'arm64',
+          osVersion: 'test',
+          shellPath: '/bin/bash',
+          shellName: 'bash',
+        },
+      },
+      homedir: '/tmp/kimi-session',
+      rpc: createSessionRpc(),
+      initializeMainAgent: false,
+    });
+    session.metadata.agents['agent-0'] = {
+      homedir: '/tmp/kimi-session/agents/agent-0',
+      type: 'sub',
+      parentAgentId: null,
+    };
+
+    const created = await session.createAgent({ type: 'sub' });
+
+    expect(created.id).toBe('agent-1');
+    expect(session.agents.get('agent-1')).toBe(created.agent);
+    expect(session.metadata.agents['agent-1']).toMatchObject({
+      homedir: '/tmp/kimi-session/agents/agent-1',
+      type: 'sub',
+    });
+  });
+
+  it('shares the session McpConnectionManager with sub and main agents', async () => {
+    const session = new Session({
+      runtime: {
+        kaos: createFakeKaos({
+          mkdir: vi.fn().mockResolvedValue(undefined),
+          writeText: vi.fn().mockResolvedValue(0),
+        }),
+        osEnv: TEST_OS_ENV,
+      },
+      homedir: '/tmp/kimi-session',
+      rpc: createSessionRpc(),
+      initializeMainAgent: false,
+    });
+
+    const main = await session.createAgent({ type: 'main' });
+    expect(main.agent.mcp).toBe(session.mcp);
+
+    const sub = await session.createAgent({ type: 'sub' }, undefined, main.id);
+    expect(sub.agent.mcp).toBe(session.mcp);
+  });
+});
+
+function fakeSession(
+  parent: Agent,
+  child: Agent,
+  metadataAgents: Session['metadata']['agents'] = {},
+) {
+  const agents = new Map<string, Agent>([['main', parent]]);
+  if (metadataAgents['agent-0'] !== undefined) {
+    agents.set('agent-0', child);
+  }
+  return {
+    agents,
+    metadata: {
+      createdAt: '2026-01-01T00:00:00.000Z',
+      updatedAt: '2026-01-01T00:00:00.000Z',
+      title: 'Test Session',
+      isCustomTitle: false,
+      agents: metadataAgents,
+      custom: {},
+    },
+    writeMetadata: vi.fn(async () => {}),
+    createAgent: vi.fn(
+      async (
+        config: Parameters<Session['createAgent']>[0],
+        profile?: ResolvedAgentProfile,
+        parentAgentId?: string,
+      ) => {
+        agents.set('agent-0', child);
+        metadataAgents['agent-0'] = {
+          homedir: '/tmp/kimi-session/agents/agent-0',
+          type: config.type ?? 'main',
+          parentAgentId: parentAgentId ?? null,
+        };
+        if (profile !== undefined) {
+          child.useProfile(profile);
+        }
+        return { id: 'agent-0', agent: child };
+      },
+    ),
+  } as unknown as Session;
+}
+
+function contextProfile(): ResolvedAgentProfile {
+  return {
+    name: 'context-profile',
+    systemPrompt: (context) =>
+      [
+        `cwd=${context.cwd}`,
+        `listing=${context.cwdListing ?? ''}`,
+        `agents=${context.agentsMd ?? ''}`,
+      ].join('\n'),
+    tools: [],
+  };
+}
+
+function profile(input: {
+  readonly name: string;
+  readonly tools: readonly string[];
+  readonly systemPrompt: string;
+  readonly description?: string | undefined;
+  readonly subagents?: Record<string, ResolvedAgentProfile> | undefined;
+}): ResolvedAgentProfile {
+  return {
+    name: input.name,
+    description: input.description,
+    systemPrompt: () => input.systemPrompt,
+    tools: [...input.tools],
+    subagents: input.subagents,
+  };
+}
+
+function stat(kind: 'dir' | 'file') {
+  return {
+    stMode: kind === 'dir' ? 0o040000 : 0o100000,
+    stIno: 0,
+    stDev: 0,
+    stNlink: 1,
+    stUid: 0,
+    stGid: 0,
+    stSize: 0,
+    stAtime: 0,
+    stMtime: 0,
+    stCtime: 0,
+  };
+}
+
+async function writeWire(homedir: string, records: readonly Record<string, unknown>[]) {
+  await mkdir(homedir, { recursive: true });
+  const text = records.map((record) => JSON.stringify(record)).join('\n');
+  await writeFile(join(homedir, 'wire.jsonl'), text.length === 0 ? '' : `${text}\n`, 'utf-8');
+}
+
+function bashCall(): ToolCall {
+  return {
+    type: 'function',
+    id: 'call_bash',
+    function: {
+      name: 'Bash',
+      arguments: '{"command":"printf should-not-run","timeout":60}',
+    },
+  };
+}
+
+function createSessionRpc(): SDKSessionRPC {
+  return new Proxy(
+    {},
+    {
+      get: () => vi.fn(),
+    },
+  ) as SDKSessionRPC;
+}
diff --git a/packages/agent-core/test/skill/parser-frontmatter.test.ts b/packages/agent-core/test/skill/parser-frontmatter.test.ts
new file mode 100644
index 000000000..166ae0d95
--- /dev/null
+++ b/packages/agent-core/test/skill/parser-frontmatter.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+
+import { FrontmatterError, parseFrontmatter } from '../../src/skill/parser';
+
+describe('parseFrontmatter', () => {
+  it('parses a leading YAML block and discards it from body', () => {
+    const text = ['---', 'name: test-skill', 'description: A test skill', 'extra: 123', '---', '', '# Body', ''].join(
+      '\n',
+    );
+
+    const { data, body } = parseFrontmatter(text);
+
+    expect(data).toEqual({
+      name: 'test-skill',
+      description: 'A test skill',
+      extra: 123,
+    });
+    expect(body).not.toContain('extra: 123');
+    expect(body).toContain('# Body');
+  });
+
+  it('throws FrontmatterError on invalid YAML', () => {
+    const text = ['---', 'name: "unterminated', 'description: oops', '---', ''].join('\n');
+
+    expect(() => parseFrontmatter(text)).toThrow(FrontmatterError);
+  });
+});
diff --git a/packages/agent-core/test/skill/parser.test.ts b/packages/agent-core/test/skill/parser.test.ts
new file mode 100644
index 000000000..11b868ce2
--- /dev/null
+++ b/packages/agent-core/test/skill/parser.test.ts
@@ -0,0 +1,270 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  discoverSkills,
+  expandSkillParameters,
+  type SkillDefinition,
+  SkillRegistry,
+  type SkillRoot,
+} from '../../src/skill';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+describe('skill parser', () => {
+  it('uses the filename stem when a flat .md has no frontmatter name', async () => {
+    const root = await makeSkillsRoot();
+    await writeFlat(root, 'my-thing.md', ['---', 'description: Something', '---', 'Body']);
+
+    const skills = await discoverSkills({ roots: [userRoot(root)] });
+    expect(skills).toHaveLength(1);
+    expect(skills[0]?.name).toBe('my-thing');
+    expect(skills[0]?.description).toBe('Something');
+  });
+
+  it('falls back to the first non-empty body line as description when frontmatter is absent', async () => {
+    const root = await makeSkillsRoot();
+    await writeFlat(root, 'plain.md', ['', '', 'This is the headline description.', '', 'More body text here.']);
+
+    const skills = await discoverSkills({ roots: [userRoot(root)] });
+    expect(skills).toHaveLength(1);
+    expect(skills[0]?.name).toBe('plain');
+    expect(skills[0]?.description.toLowerCase()).toContain('headline description');
+  });
+
+  it('prefers frontmatter description over body first-line fallback', async () => {
+    const root = await makeSkillsRoot();
+    await writeFlat(root, 'a.md', ['---', 'description: From frontmatter', '---', 'Body first line']);
+
+    const skills = await discoverSkills({ roots: [userRoot(root)] });
+    expect(skills).toHaveLength(1);
+    expect(skills[0]?.description).toBe('From frontmatter');
+  });
+
+  it('truncates body-fallback descriptions to 240 chars including trailing ellipsis', async () => {
+    const root = await makeSkillsRoot();
+    await writeFlat(root, 'long.md', ['a'.repeat(300)]);
+
+    const skills = await discoverSkills({ roots: [userRoot(root)] });
+    expect(skills).toHaveLength(1);
+    const desc = skills[0]?.description ?? '';
+    expect(desc.length).toBe(240);
+    expect(desc.endsWith('…')).toBe(true);
+  });
+
+  it('does not truncate explicit frontmatter descriptions at the 240 cap', async () => {
+    const root = await makeSkillsRoot();
+    const longDesc = 'b'.repeat(900);
+    await writeFlatOrSubdirSkill(root, 'long', 'SKILL.md', [
+      '---',
+      'name: long',
+      `description: ${longDesc}`,
+      '---',
+      'Body here',
+    ]);
+
+    const skills = await discoverSkills({ roots: [userRoot(root)] });
+    expect(skills).toHaveLength(1);
+    expect(skills[0]?.description).toBe(longDesc);
+  });
+
+  it('flat skill frontmatter name wins over the filename stem', async () => {
+    const root = await makeSkillsRoot();
+    await writeFlat(root, 'filename-stem.md', ['---', 'name: real-name', 'description: ok', '---', 'Body']);
+
+    const skills = await discoverSkills({ roots: [userRoot(root)] });
+    expect(skills).toHaveLength(1);
+    expect(skills[0]?.name).toBe('real-name');
+    expect(skills[0]?.name).not.toBe('filename-stem');
+  });
+
+  it('flat skill with unclosed frontmatter fence is skipped with a warning', async () => {
+    const root = await makeSkillsRoot();
+    await writeFlat(root, 'demo.md', ['---', '# Hello', 'Body text.']);
+
+    const warnings: string[] = [];
+    const skills = await discoverSkills({
+      roots: [userRoot(root)],
+      onWarning: (message) => warnings.push(message),
+    });
+    expect(skills).toEqual([]);
+    expect(warnings.some((message) => message.includes('Invalid frontmatter'))).toBe(true);
+  });
+
+  it('subdir skill with unclosed frontmatter fence is skipped with a warning', async () => {
+    const root = await makeSkillsRoot();
+    await writeFlatOrSubdirSkill(root, 'demo', 'SKILL.md', ['---', '# Heading', 'Body.']);
+
+    const warnings: string[] = [];
+    const skills = await discoverSkills({
+      roots: [userRoot(root)],
+      onWarning: (message) => warnings.push(message),
+    });
+    expect(skills).toEqual([]);
+    expect(warnings.some((message) => message.includes('Invalid frontmatter'))).toBe(true);
+  });
+});
+
+describe('skill parameter expansion', () => {
+  it('expands raw, positional, named, and context placeholders', () => {
+    const out = expandSkillParameters(
+      'raw=$ARGUMENTS zero=$0 one=$1 second=$ARGUMENTS[1] flag=$flag message=$message dir=${KIMI_SKILL_DIR} session=${KIMI_SESSION_ID}',
+      '-m "fix login"',
+      {
+        skillDir: '/tmp/skills/commit',
+        sessionId: 'ses_1',
+        argumentNames: ['flag', 'message'],
+      },
+    );
+
+    expect(out).toBe(
+      'raw=-m "fix login" zero=-m one=fix login second=fix login flag=-m message=fix login dir=/tmp/skills/commit session=ses_1',
+    );
+  });
+
+  it('leaves unknown placeholders alone and clears missing indexed values', () => {
+    const out = expandSkillParameters('unknown=$missing actual=$0 missing=$1', 'hello', {
+      skillDir: '/x',
+      sessionId: 's',
+    });
+
+    expect(out).toBe('unknown=$missing actual=hello missing=');
+  });
+
+  it('treats backslash-dollar as a normal backslash before placeholders', () => {
+    const out = expandSkillParameters(
+      String.raw`raw=\$ARGUMENTS zero=\$0 indexed=\$ARGUMENTS[1] target=\$target`,
+      'src/app.ts careful',
+      {
+        skillDir: '/x',
+        argumentNames: ['target'],
+      },
+    );
+
+    expect(out).toBe(
+      String.raw`raw=\src/app.ts careful zero=\src/app.ts indexed=\careful target=\src/app.ts`,
+    );
+  });
+});
+
+describe('SkillRegistry.renderSkillPrompt', () => {
+  it('expands argument placeholders without appending duplicate arguments', () => {
+    const rendered = new SkillRegistry().renderSkillPrompt(
+      testSkill({
+        content: 'Review $target from $ARGUMENTS.',
+        metadata: { arguments: ['target'] },
+      }),
+      '"src/app.ts" carefully',
+    );
+
+    expect(rendered).toBe('Review src/app.ts from "src/app.ts" carefully.');
+    expect(rendered).not.toContain('ARGUMENTS:');
+  });
+
+  it('appends ARGUMENTS when the body has no argument placeholders', () => {
+    const rendered = new SkillRegistry().renderSkillPrompt(
+      testSkill({ content: 'Review this file.' }),
+      'src/app.ts',
+    );
+
+    expect(rendered).toBe('Review this file.\n\nARGUMENTS: src/app.ts');
+  });
+
+  it('expands context placeholders and still appends args when no argument placeholder is used', () => {
+    const rendered = new SkillRegistry({ sessionId: 'ses_1' }).renderSkillPrompt(
+      testSkill({ content: 'Use ${KIMI_SKILL_DIR}/references/checklist.md.' }),
+      'src/app.ts',
+    );
+
+    expect(rendered).toBe(
+      'Use /skills/review/references/checklist.md.\n\nARGUMENTS: src/app.ts',
+    );
+  });
+
+  it('does not treat longer variable names as declared argument placeholders', () => {
+    const rendered = new SkillRegistry().renderSkillPrompt(
+      testSkill({
+        content: 'Leave $targeted alone.',
+        metadata: { arguments: ['target'] },
+      }),
+      'src/app.ts',
+    );
+
+    expect(rendered).toBe('Leave $targeted alone.\n\nARGUMENTS: src/app.ts');
+  });
+
+  it('accepts space-separated argument names', () => {
+    const rendered = new SkillRegistry().renderSkillPrompt(
+      testSkill({
+        content: 'Target: $target\nMode: $mode',
+        metadata: { arguments: 'target mode' },
+      }),
+      'src/app.ts careful',
+    );
+
+    expect(rendered).toBe('Target: src/app.ts\nMode: careful');
+  });
+
+  it('ignores numeric argument names so positional placeholders keep shell-like semantics', () => {
+    const rendered = new SkillRegistry().renderSkillPrompt(
+      testSkill({
+        content: 'Zero: $0\nOne: $1',
+        metadata: { arguments: ['1'] },
+      }),
+      'first second',
+    );
+
+    expect(rendered).toBe('Zero: first\nOne: second');
+  });
+});
+
+async function makeSkillsRoot(): Promise<string> {
+  const tmp = await mkdtemp(path.join(tmpdir(), 'kimi-skill-parser-'));
+  tempDirs.push(tmp);
+  const root = path.join(tmp, 'skills');
+  await mkdir(root, { recursive: true });
+  return root;
+}
+
+function userRoot(root: string): SkillRoot {
+  return { path: root, source: 'user' };
+}
+
+async function writeFlat(root: string, name: string, lines: readonly string[]): Promise<void> {
+  await writeFile(path.join(root, name), lines.join('\n'));
+}
+
+async function writeFlatOrSubdirSkill(
+  root: string,
+  dirName: string,
+  fileName: string,
+  lines: readonly string[],
+): Promise<void> {
+  const dir = path.join(root, dirName);
+  await mkdir(dir, { recursive: true });
+  await writeFile(path.join(dir, fileName), lines.join('\n'));
+}
+
+function testSkill(input: {
+  readonly content: string;
+  readonly metadata?: SkillDefinition['metadata'];
+}): SkillDefinition {
+  return {
+    name: 'review',
+    description: 'Review things',
+    path: '/skills/review/SKILL.md',
+    dir: '/skills/review',
+    content: input.content,
+    metadata: input.metadata ?? {},
+    source: 'user',
+  };
+}
diff --git a/packages/agent-core/test/skill/registry.test.ts b/packages/agent-core/test/skill/registry.test.ts
new file mode 100644
index 000000000..688b4bca5
--- /dev/null
+++ b/packages/agent-core/test/skill/registry.test.ts
@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest';
+
+import { SkillRegistry } from '../../src/skill';
+import type { SkillDefinition, SkillSource } from '../../src/skill';
+
+describe('skill registry prompt rendering', () => {
+  it('groups skills by scope under canonical section headings', () => {
+    const registry = makeRegistry([
+      makeSkill('builtin-a', 'builtin'),
+      makeSkill('user-a', 'user'),
+      makeSkill('proj-a', 'project'),
+      makeSkill('extra-a', 'extra'),
+    ]);
+
+    const rendered = registry.getKimiSkillsDescription();
+
+    expect(rendered).toContain('### Project');
+    expect(rendered).toContain('### User');
+    expect(rendered).toContain('### Extra');
+    expect(rendered).toContain('### Built-in');
+
+    const projectIdx = rendered.indexOf('### Project');
+    const userIdx = rendered.indexOf('### User');
+    const extraIdx = rendered.indexOf('### Extra');
+    const builtinIdx = rendered.indexOf('### Built-in');
+    expect(projectIdx).toBeLessThan(userIdx);
+    expect(userIdx).toBeLessThan(extraIdx);
+    expect(extraIdx).toBeLessThan(builtinIdx);
+
+    expect(sectionFor(rendered, '### Project')).toContain('proj-a');
+    expect(sectionFor(rendered, '### User')).toContain('user-a');
+    expect(sectionFor(rendered, '### Extra')).toContain('extra-a');
+    expect(sectionFor(rendered, '### Built-in')).toContain('builtin-a');
+    expect(sectionFor(rendered, '### Project')).not.toContain('user-a');
+    expect(sectionFor(rendered, '### User')).not.toContain('proj-a');
+  });
+
+  it('omits scope headings that have no skills', () => {
+    const registry = makeRegistry([makeSkill('alpha', 'user')]);
+
+    const rendered = registry.getKimiSkillsDescription();
+
+    expect(rendered).toContain('### User');
+    expect(rendered).not.toContain('### Project');
+    expect(rendered).not.toContain('### Extra');
+    expect(rendered).not.toContain('### Built-in');
+  });
+
+  it('renders a "No skills" placeholder for an empty registry', () => {
+    const registry = new SkillRegistry();
+
+    const rendered = registry.getKimiSkillsDescription();
+
+    expect(rendered.trim()).not.toBe('');
+    expect(/no skills/i.test(rendered)).toBe(true);
+  });
+
+  it('sorts skills alphabetically within a scope', () => {
+    const registry = makeRegistry([
+      makeSkill('zebra', 'user'),
+      makeSkill('alpha', 'user'),
+      makeSkill('mango', 'user'),
+    ]);
+
+    const rendered = registry.getKimiSkillsDescription();
+
+    const a = rendered.indexOf('alpha');
+    const m = rendered.indexOf('mango');
+    const z = rendered.indexOf('zebra');
+    expect(a).toBeGreaterThan(-1);
+    expect(a).toBeLessThan(m);
+    expect(m).toBeLessThan(z);
+  });
+
+  it('end-to-end: a project skill that shadows other scopes renders once under Project', () => {
+    const registry = makeRegistry([makeSkill('foo', 'project', 'project version', '/tmp/proj/foo/SKILL.md')]);
+
+    const rendered = registry.getKimiSkillsDescription();
+
+    expect(rendered.match(/\n- foo\n/g) ?? []).toHaveLength(1);
+    expect(sectionFor(rendered, '### Project')).toContain('foo');
+    expect(rendered).toContain('/tmp/proj/foo/SKILL.md');
+    expect(rendered).toContain('project version');
+  });
+
+  it('renders each skill as name + Path + Description', () => {
+    const registry = makeRegistry([
+      makeSkill('alpha', 'user', 'Alpha does things', '/tmp/user/alpha/SKILL.md'),
+    ]);
+
+    const rendered = registry.getKimiSkillsDescription();
+
+    expect(rendered).toContain('- alpha');
+    expect(rendered).toContain('  - Path: /tmp/user/alpha/SKILL.md');
+    expect(rendered).toContain('  - Description: Alpha does things');
+  });
+});
+
+function makeRegistry(skills: readonly SkillDefinition[]): SkillRegistry {
+  const registry = new SkillRegistry();
+  for (const skill of skills) registry.register(skill);
+  return registry;
+}
+
+function makeSkill(
+  name: string,
+  source: SkillSource,
+  description = 'desc',
+  skillPath?: string,
+): SkillDefinition {
+  const finalPath = skillPath ?? `/tmp/${source}/${name}/SKILL.md`;
+  return {
+    name,
+    description,
+    path: finalPath,
+    dir: finalPath.replace(/\/SKILL\.md$/, ''),
+    content: '',
+    metadata: { type: 'prompt' },
+    source,
+  };
+}
+
+function sectionFor(rendered: string, header: string): string {
+  const start = rendered.indexOf(header);
+  if (start === -1) return '';
+  const next = rendered.indexOf('### ', start + header.length);
+  return next === -1 ? rendered.slice(start) : rendered.slice(start, next);
+}
diff --git a/packages/agent-core/test/skill/scanner.test.ts b/packages/agent-core/test/skill/scanner.test.ts
new file mode 100644
index 000000000..41d605690
--- /dev/null
+++ b/packages/agent-core/test/skill/scanner.test.ts
@@ -0,0 +1,1177 @@
+import { mkdtemp, mkdir, realpath, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { discoverSkills, resolveSkillRoots, SkillRegistry, type SkillRoot } from '../../src/skill';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+describe('skill discovery', () => {
+  it('resolves documented roots in precedence order with brand merging enabled by default', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    await mkdir(path.join(repoDir, '.kimi-code', 'skills'), { recursive: true });
+    await mkdir(path.join(repoDir, '.agents', 'skills'), { recursive: true });
+    await mkdir(path.join(homeDir, '.kimi-code', 'skills'), { recursive: true });
+    await mkdir(path.join(homeDir, '.agents', 'skills'), { recursive: true });
+    await mkdir(path.join(repoDir, 'team-skills'), { recursive: true });
+    const realRepoDir = await realpath(repoDir);
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      extraDirs: ['team-skills'],
+    });
+
+    expect(roots.map((root) => path.relative(realRepoDir, root.path))).toEqual([
+      '.kimi-code/skills',
+      '.agents/skills',
+      path.relative(realRepoDir, await realpath(path.join(homeDir, '.kimi-code', 'skills'))),
+      path.relative(realRepoDir, await realpath(path.join(homeDir, '.agents', 'skills'))),
+      'team-skills',
+    ]);
+    expect(roots.map((root) => root.source)).toEqual([
+      'project',
+      'project',
+      'user',
+      'user',
+      'extra',
+    ]);
+  });
+
+  it('uses only the first brand directory when brand merging is disabled', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    await mkdir(path.join(repoDir, '.kimi-code', 'skills'), { recursive: true });
+    await mkdir(path.join(homeDir, '.kimi-code', 'skills'), { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      mergeAllAvailableSkills: false,
+    });
+
+    expect(roots.map((root) => root.path)).toEqual([
+      await realpath(path.join(repoDir, '.kimi-code', 'skills')),
+      await realpath(path.join(homeDir, '.kimi-code', 'skills')),
+    ]);
+  });
+
+  it('lets explicit skill dirs replace automatic project and user discovery', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    await mkdir(path.join(repoDir, '.kimi-code', 'skills'), { recursive: true });
+    await mkdir(path.join(homeDir, '.kimi-code', 'skills'), { recursive: true });
+    await mkdir(path.join(repoDir, 'explicit-skills'), { recursive: true });
+    await mkdir(path.join(repoDir, 'extra-skills'), { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      explicitDirs: ['explicit-skills'],
+      extraDirs: ['extra-skills'],
+    });
+    const realRepoDir = await realpath(repoDir);
+
+    expect(roots.map((root) => [path.relative(realRepoDir, root.path), root.source])).toEqual([
+      ['explicit-skills', 'user'],
+      ['extra-skills', 'extra'],
+    ]);
+  });
+
+  it('discovers flat markdown skills, keeps directory skills over same-name flat files, and preserves source precedence', async () => {
+    const { homeDir, repoDir } = await makeWorkspace();
+    const projectRoot = path.join(repoDir, '.kimi-code', 'skills');
+    const userRoot = path.join(homeDir, '.kimi-code', 'skills');
+    await writeSkill(projectRoot, 'review.md', ['Project review body first line.', '', 'Details.']);
+    await writeSkill(userRoot, path.join('review', 'SKILL.md'), [
+      '---',
+      'name: review',
+      'description: User review',
+      '---',
+      '',
+      'User review body.',
+    ]);
+    await writeSkill(projectRoot, path.join('deploy', 'SKILL.md'), [
+      '---',
+      'name: deploy',
+      'description: Directory deploy',
+      '---',
+      '',
+      'Deploy body.',
+    ]);
+    await writeSkill(projectRoot, 'deploy.md', ['Flat deploy should be ignored.']);
+
+    const warnings: string[] = [];
+    const roots: SkillRoot[] = [
+      { path: projectRoot, source: 'project' },
+      { path: userRoot, source: 'user' },
+    ];
+    const skills = await discoverSkills({
+      roots,
+      onWarning: (message) => warnings.push(message),
+    });
+
+    expect(skills.map((skill) => [skill.name, skill.description, skill.source])).toEqual([
+      ['deploy', 'Directory deploy', 'project'],
+      ['review', 'Project review body first line.', 'project'],
+    ]);
+    expect(warnings.some((message) => message.includes('Ignoring flat skill'))).toBe(true);
+  });
+
+  it('keeps flow skills user-visible while excluding them from model invocation', async () => {
+    const { repoDir } = await makeWorkspace();
+    const projectRoot = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(projectRoot, path.join('review-flow', 'SKILL.md'), [
+      '---',
+      'name: review-flow',
+      'description: Review flow',
+      'type: flow',
+      '---',
+      '',
+      '```mermaid',
+      'flowchart TD',
+      'BEGIN --> END',
+      '```',
+    ]);
+
+    const registry = new SkillRegistry();
+    await registry.loadRoots([{ path: projectRoot, source: 'project' }]);
+
+    expect(registry.listSkills().map((skill) => skill.name)).toEqual(['review-flow']);
+    expect(registry.listInvocableSkills()).toEqual([]);
+  });
+
+  it('skips directory skills with missing frontmatter metadata', async () => {
+    const { repoDir } = await makeWorkspace();
+    const projectRoot = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(projectRoot, path.join('valid', 'SKILL.md'), [
+      '---',
+      'name: valid',
+      'description: Valid skill',
+      '---',
+      '',
+      'Valid body.',
+    ]);
+    await writeSkill(projectRoot, path.join('no-frontmatter', 'SKILL.md'), [
+      '# Heading should not become a description',
+      '',
+      'Body.',
+    ]);
+    await writeSkill(projectRoot, path.join('missing-name', 'SKILL.md'), [
+      '---',
+      'description: Missing name',
+      '---',
+      '',
+      'Body.',
+    ]);
+    await writeSkill(projectRoot, path.join('missing-description', 'SKILL.md'), [
+      '---',
+      'name: missing-description',
+      '---',
+      '',
+      '# Heading should not become a description',
+    ]);
+
+    const warnings: string[] = [];
+    const skills = await discoverSkills({
+      roots: [{ path: projectRoot, source: 'project' }],
+      onWarning: (message) => warnings.push(message),
+    });
+
+    expect(skills.map((skill) => skill.name)).toEqual(['valid']);
+    expect(warnings).toHaveLength(3);
+    expect(warnings.some((message) => message.includes('Missing frontmatter'))).toBe(true);
+    expect(warnings.some((message) => message.includes('"name"'))).toBe(true);
+    expect(warnings.some((message) => message.includes('"description"'))).toBe(true);
+  });
+});
+
+describe('discoverSkills shape and ordering', () => {
+  it('parses frontmatter name/description for subdir skills', async () => {
+    const { repoDir } = await makeWorkspace();
+    const root = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(root, path.join('alpha', 'SKILL.md'), [
+      '---',
+      'name: alpha-skill',
+      'description: Alpha description',
+      '---',
+    ]);
+
+    const skills = await discoverSkills({ roots: [{ path: root, source: 'user' }] });
+
+    expect(skills.map((skill) => [skill.name, skill.description, skill.source])).toEqual([
+      ['alpha-skill', 'Alpha description', 'user'],
+    ]);
+  });
+
+  it('keeps the first roots version when a skill name appears in multiple roots', async () => {
+    const { repoDir } = await makeWorkspace();
+    const rootA = path.join(repoDir, 'root_a');
+    const rootB = path.join(repoDir, 'root_b');
+    await writeSkill(rootA, path.join('greet', 'SKILL.md'), [
+      '---',
+      'name: greet',
+      'description: A',
+      '---',
+      'Hello from A',
+    ]);
+    await writeSkill(rootB, path.join('greet', 'SKILL.md'), [
+      '---',
+      'name: greet',
+      'description: B',
+      '---',
+      'Hello from B',
+    ]);
+
+    const skills = await discoverSkills({
+      roots: [
+        { path: rootA, source: 'builtin' },
+        { path: rootB, source: 'user' },
+      ],
+    });
+
+    expect(skills).toHaveLength(1);
+    expect(skills[0]?.description).toBe('A');
+  });
+
+  it('does not register a top-level SKILL.md as a flat skill', async () => {
+    const { repoDir } = await makeWorkspace();
+    const root = path.join(repoDir, '.kimi-code', 'skills');
+    await mkdir(root, { recursive: true });
+    await writeFile(
+      path.join(root, 'SKILL.md'),
+      ['---', 'name: not-a-skill', 'description: accidental', '---'].join('\n'),
+    );
+
+    const skills = await discoverSkills({ roots: [{ path: root, source: 'user' }] });
+
+    expect(skills).toEqual([]);
+  });
+
+  it('lists flat skills with frontmatter name and description', async () => {
+    const { repoDir } = await makeWorkspace();
+    const root = path.join(repoDir, '.kimi-code', 'skills');
+    await mkdir(root, { recursive: true });
+    await writeFile(
+      path.join(root, 'demo-ui-components.md'),
+      ['---', 'name: demo-ui-components', 'description: Demo UI', '---', 'Body'].join('\n'),
+    );
+
+    const skills = await discoverSkills({ roots: [{ path: root, source: 'user' }] });
+
+    expect(skills).toHaveLength(1);
+    expect(skills[0]?.name).toBe('demo-ui-components');
+    expect(skills[0]?.description).toBe('Demo UI');
+  });
+
+  it('discovers both flat and subdir skills alongside in the same root', async () => {
+    const { repoDir } = await makeWorkspace();
+    const root = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(root, path.join('subdir-skill', 'SKILL.md'), [
+      '---',
+      'name: subdir-skill',
+      'description: From subdir',
+      '---',
+    ]);
+    await mkdir(root, { recursive: true });
+    await writeFile(
+      path.join(root, 'flat-skill.md'),
+      ['---', 'name: flat-skill', 'description: From flat', '---'].join('\n'),
+    );
+
+    const skills = await discoverSkills({ roots: [{ path: root, source: 'user' }] });
+    expect(skills.map((s) => s.name).toSorted()).toEqual(['flat-skill', 'subdir-skill']);
+  });
+
+  it('prefers the subdir version when a flat and subdir skill share a name', async () => {
+    const { repoDir } = await makeWorkspace();
+    const root = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(root, path.join('greet', 'SKILL.md'), [
+      '---',
+      'name: greet',
+      'description: From subdir',
+      '---',
+    ]);
+    await mkdir(root, { recursive: true });
+    await writeFile(
+      path.join(root, 'greet.md'),
+      ['---', 'name: greet', 'description: From flat', '---'].join('\n'),
+    );
+
+    const skills = await discoverSkills({ roots: [{ path: root, source: 'user' }] });
+    expect(skills).toHaveLength(1);
+    expect(skills[0]?.description).toBe('From subdir');
+  });
+
+  it('discovers skills nested in subdirectories at multiple depths', async () => {
+    const { repoDir } = await makeWorkspace();
+    const root = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(root, path.join('top', 'SKILL.md'), [
+      '---',
+      'name: top',
+      'description: Top level',
+      '---',
+    ]);
+    await writeSkill(root, path.join('group', 'alpha', 'SKILL.md'), [
+      '---',
+      'name: alpha',
+      'description: One level deep',
+      '---',
+    ]);
+    await writeSkill(root, path.join('a', 'b', 'beta', 'SKILL.md'), [
+      '---',
+      'name: beta',
+      'description: Two levels deep',
+      '---',
+    ]);
+    // A loose .md below the top level is skill payload, not a skill.
+    await writeFile(path.join(root, 'group', 'notes.md'), 'just some notes');
+
+    const skills = await discoverSkills({ roots: [{ path: root, source: 'user' }] });
+
+    expect(skills.map((s) => s.name)).toEqual(['alpha', 'beta', 'top']);
+  });
+
+  it('does not descend into a skill bundle subdirectory', async () => {
+    const { repoDir } = await makeWorkspace();
+    const root = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(root, path.join('outer', 'SKILL.md'), [
+      '---',
+      'name: outer',
+      'description: The real skill',
+      '---',
+    ]);
+    await writeSkill(root, path.join('outer', 'references', 'inner', 'SKILL.md'), [
+      '---',
+      'name: inner',
+      'description: Should be ignored',
+      '---',
+    ]);
+
+    const skills = await discoverSkills({ roots: [{ path: root, source: 'user' }] });
+
+    expect(skills.map((s) => s.name)).toEqual(['outer']);
+  });
+
+  it('skips node_modules when scanning nested directories', async () => {
+    const { repoDir } = await makeWorkspace();
+    const root = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(root, path.join('real', 'SKILL.md'), [
+      '---',
+      'name: real',
+      'description: A real skill',
+      '---',
+    ]);
+    await writeSkill(root, path.join('node_modules', 'pkg', 'vendored', 'SKILL.md'), [
+      '---',
+      'name: vendored',
+      'description: Should never load',
+      '---',
+    ]);
+
+    const skills = await discoverSkills({ roots: [{ path: root, source: 'user' }] });
+
+    expect(skills.map((s) => s.name)).toEqual(['real']);
+  });
+
+  it('stops recursing past the maximum scan depth', async () => {
+    const { repoDir } = await makeWorkspace();
+    const root = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(root, path.join('shallow', 'SKILL.md'), [
+      '---',
+      'name: shallow',
+      'description: Near the root',
+      '---',
+    ]);
+    const deepSegments = Array.from({ length: 11 }, (_, i) => `lvl-${i}`);
+    await writeSkill(root, path.join(...deepSegments, 'deep', 'SKILL.md'), [
+      '---',
+      'name: deep',
+      'description: Far below the depth cap',
+      '---',
+    ]);
+
+    const skills = await discoverSkills({ roots: [{ path: root, source: 'user' }] });
+
+    expect(skills.map((s) => s.name)).toEqual(['shallow']);
+  });
+
+  it('prefers a shallower skill over a deeper one with the same name', async () => {
+    const { repoDir } = await makeWorkspace();
+    const root = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(root, path.join('dup', 'SKILL.md'), [
+      '---',
+      'name: dup',
+      'description: Shallow wins',
+      '---',
+    ]);
+    await writeSkill(root, path.join('group', 'dup', 'SKILL.md'), [
+      '---',
+      'name: dup',
+      'description: Deep loses',
+      '---',
+    ]);
+
+    const skills = await discoverSkills({ roots: [{ path: root, source: 'user' }] });
+
+    expect(skills).toHaveLength(1);
+    expect(skills[0]?.description).toBe('Shallow wins');
+  });
+
+  it('resolves a same-name collision across sibling directories deterministically', async () => {
+    const { repoDir } = await makeWorkspace();
+    const root = path.join(repoDir, '.kimi-code', 'skills');
+    // Created out of alphabetical order so the result cannot depend on
+    // filesystem readdir order; the alphabetically-first sibling must win.
+    await writeSkill(root, path.join('group-b', 'dup', 'SKILL.md'), [
+      '---',
+      'name: dup',
+      'description: From group-b',
+      '---',
+    ]);
+    await writeSkill(root, path.join('group-a', 'dup', 'SKILL.md'), [
+      '---',
+      'name: dup',
+      'description: From group-a',
+      '---',
+    ]);
+
+    const skills = await discoverSkills({ roots: [{ path: root, source: 'user' }] });
+
+    expect(skills).toHaveLength(1);
+    expect(skills[0]?.description).toBe('From group-a');
+  });
+
+  it('returns an empty list when the skill root cannot be read', async () => {
+    const { repoDir } = await makeWorkspace();
+    const root = path.join(repoDir, 'locked');
+    await mkdir(root, { recursive: true });
+
+    const skills = await discoverSkills({
+      roots: [{ path: root, source: 'extra' }],
+      readdir: async () => {
+        throw Object.assign(new Error('simulated'), { code: 'EACCES' });
+      },
+    });
+
+    expect(skills).toEqual([]);
+  });
+});
+
+describe('resolveSkillRoots ordering and priority', () => {
+  it('returns project then user then builtin in priority order', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const userGeneric = path.join(homeDir, '.agents', 'skills');
+    await mkdir(userGeneric, { recursive: true });
+    const projectGeneric = path.join(repoDir, '.agents', 'skills');
+    await mkdir(projectGeneric, { recursive: true });
+    const builtin = path.join(repoDir, 'builtin');
+    await mkdir(builtin, { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      builtinDir: builtin,
+    });
+
+    expect(roots.map((root) => root.source)).toEqual(['project', 'user', 'builtin']);
+  });
+
+  it('treats empty explicit dirs identically to omitting them', async () => {
+    const { homeDir, workDir } = await makeWorkspace();
+
+    const omitted = await resolveSkillRoots({ paths: { userHomeDir: homeDir, workDir } });
+    const empty = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      explicitDirs: [],
+    });
+
+    expect(empty).toEqual(omitted);
+  });
+
+  it('returns no user roots when no skill dirs exist in the home directory', async () => {
+    const { homeDir, workDir } = await makeWorkspace();
+
+    const roots = await resolveSkillRoots({ paths: { userHomeDir: homeDir, workDir } });
+
+    expect(roots.filter((r) => r.source === 'user')).toEqual([]);
+  });
+
+  it('prefers brand over generic user dirs even when both contain skills with the same name', async () => {
+    const { homeDir, workDir } = await makeWorkspace();
+    const generic = path.join(homeDir, '.agents', 'skills');
+    await writeSkill(generic, path.join('greet', 'SKILL.md'), [
+      '---',
+      'name: greet',
+      'description: generic version',
+      '---',
+    ]);
+    const brand = path.join(homeDir, '.kimi-code', 'skills');
+    await writeSkill(brand, path.join('greet', 'SKILL.md'), [
+      '---',
+      'name: greet',
+      'description: brand version',
+      '---',
+    ]);
+
+    const roots = await resolveSkillRoots({ paths: { userHomeDir: homeDir, workDir } });
+    const skills = await discoverSkills({ roots });
+
+    expect(skills).toHaveLength(1);
+    expect(skills[0]?.description).toBe('brand version');
+  });
+
+  it('returns proj-brand, proj-generic, user-brand, user-generic, builtin in that order without merging', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const userBrand = path.join(homeDir, '.kimi-code', 'skills');
+    const userGeneric = path.join(homeDir, '.agents', 'skills');
+    const projBrand = path.join(repoDir, '.kimi-code', 'skills');
+    const projGeneric = path.join(repoDir, '.agents', 'skills');
+    const builtin = path.join(repoDir, 'builtin');
+    for (const d of [userBrand, userGeneric, projBrand, projGeneric, builtin]) {
+      await mkdir(d, { recursive: true });
+    }
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      builtinDir: builtin,
+      mergeAllAvailableSkills: false,
+    });
+
+    expect(roots.map((r) => r.path)).toEqual([
+      await realpath(projBrand),
+      await realpath(projGeneric),
+      await realpath(userBrand),
+      await realpath(userGeneric),
+      await realpath(builtin),
+    ]);
+  });
+
+  it('keeps brand user skills visible when the generic group is empty', async () => {
+    const { homeDir, workDir } = await makeWorkspace();
+    const generic = path.join(homeDir, '.config', 'agents', 'skills');
+    await mkdir(generic, { recursive: true });
+    const brand = path.join(homeDir, '.kimi-code', 'skills');
+    await writeSkill(brand, path.join('deploy', 'SKILL.md'), [
+      '---',
+      'name: deploy',
+      'description: Deploy to prod',
+      '---',
+    ]);
+
+    const roots = await resolveSkillRoots({ paths: { userHomeDir: homeDir, workDir } });
+    const skills = await discoverSkills({ roots });
+
+    expect(skills.map((s) => s.name)).toContain('deploy');
+  });
+
+  it('defaults to merging user brand dirs', async () => {
+    const { homeDir, workDir } = await makeWorkspace();
+    await mkdir(path.join(homeDir, '.kimi-code', 'skills'), { recursive: true });
+
+    const roots = await resolveSkillRoots({ paths: { userHomeDir: homeDir, workDir } });
+
+    const paths = roots.map((r) => r.path);
+    expect(paths).toContain(await realpath(path.join(homeDir, '.kimi-code', 'skills')));
+  });
+});
+
+describe('resolveSkillRoots extra dirs', () => {
+  it('appends extra dirs to the resolved roots', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const extra = path.join(repoDir, 'my-extra');
+    await mkdir(extra, { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      extraDirs: [extra],
+    });
+
+    expect(roots.map((r) => r.path)).toContain(await realpath(extra));
+  });
+
+  it('expands a leading ~/ in extra dirs against the user home directory', async () => {
+    const { homeDir, workDir } = await makeWorkspace();
+    const target = path.join(homeDir, 'my-skills');
+    await mkdir(target, { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      extraDirs: ['~/my-skills'],
+    });
+
+    expect(roots.map((r) => r.path)).toContain(await realpath(target));
+  });
+
+  it('resolves a relative extra dir against the project root (.git ancestor), not the work dir', async () => {
+    const { homeDir, repoDir } = await makeWorkspace();
+    const nested = path.join(repoDir, 'sub', 'dir');
+    await mkdir(nested, { recursive: true });
+    const extraAtRoot = path.join(repoDir, 'my-dir');
+    await mkdir(extraAtRoot, { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir: nested },
+      extraDirs: ['my-dir'],
+    });
+
+    const paths = roots.map((r) => r.path);
+    expect(paths).toContain(await realpath(extraAtRoot));
+    expect(paths).not.toContain(path.join(nested, 'my-dir'));
+  });
+
+  it('uses absolute extra-dir paths as-is', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const absExtra = path.join(repoDir, '..', 'somewhere-else');
+    await mkdir(absExtra, { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      extraDirs: [absExtra],
+    });
+
+    expect(roots.map((r) => r.path)).toContain(await realpath(absExtra));
+  });
+
+  it('silently drops missing extra-dir entries', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const real = path.join(repoDir, 'real');
+    await mkdir(real, { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      extraDirs: [real, path.join(repoDir, 'nowhere'), path.join(repoDir, 'nope')],
+    });
+
+    const paths = roots.map((r) => r.path);
+    expect(paths).toContain(await realpath(real));
+    expect(paths).not.toContain(path.join(repoDir, 'nowhere'));
+  });
+
+  it('deduplicates duplicate entries in extra dirs', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const real = path.join(repoDir, 'real');
+    await mkdir(real, { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      extraDirs: [real, real],
+    });
+
+    const realResolved = await realpath(real);
+    const matches = roots.filter((r) => r.path === realResolved);
+    expect(matches).toHaveLength(1);
+  });
+
+  it('stamps skills discovered via extra dirs with source=extra', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const extra = path.join(repoDir, 'my-extra');
+    await writeSkill(extra, path.join('xs', 'SKILL.md'), [
+      '---',
+      'name: xs',
+      'description: x',
+      '---',
+    ]);
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      extraDirs: [extra],
+    });
+    const skills = await discoverSkills({ roots });
+    const xs = skills.find((s) => s.name === 'xs');
+
+    expect(xs?.source).toBe('extra');
+  });
+
+  it('combines explicit dirs with extra dirs and suppresses auto-discovery', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const userBrand = path.join(homeDir, '.kimi-code', 'skills');
+    await mkdir(userBrand, { recursive: true });
+    const projectBrand = path.join(repoDir, '.kimi-code', 'skills');
+    await mkdir(projectBrand, { recursive: true });
+    const cli = path.join(repoDir, 'cli');
+    await mkdir(cli, { recursive: true });
+    const extra = path.join(repoDir, 'extra');
+    await mkdir(extra, { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      explicitDirs: [cli],
+      extraDirs: [extra],
+    });
+
+    const paths = roots.map((r) => r.path);
+    expect(paths).toContain(await realpath(cli));
+    expect(paths).toContain(await realpath(extra));
+    expect(paths).not.toContain(await realpath(userBrand));
+    expect(paths).not.toContain(await realpath(projectBrand));
+  });
+
+  it('collapses a real dir and a symlink to the same target into one root', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const real = path.join(repoDir, 'real');
+    await mkdir(real, { recursive: true });
+    const link = path.join(repoDir, 'link');
+    await symlink(real, link);
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      extraDirs: [real, link],
+    });
+
+    const extras = roots.filter((r) => r.source === 'extra');
+    expect(extras).toHaveLength(1);
+    expect(extras[0]?.path).toBe(await realpath(real));
+  });
+
+  it('collapses entries differing only by trailing slash', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const real = path.join(repoDir, 'real');
+    await mkdir(real, { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      extraDirs: [real, `${real}/`],
+    });
+
+    const extras = roots.filter((r) => r.source === 'extra');
+    expect(extras).toHaveLength(1);
+  });
+
+  it('preserves source=extra on the surviving root after symlink dedup', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const real = path.join(repoDir, 'real');
+    await mkdir(real, { recursive: true });
+    const link = path.join(repoDir, 'link');
+    await symlink(real, link);
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      extraDirs: [real, link],
+    });
+
+    const extras = roots.filter((r) => r.source === 'extra');
+    expect(extras).toHaveLength(1);
+    expect(extras[0]?.source).toBe('extra');
+  });
+
+  it('stores the real path, not the symlink path, for a symlinked extra dir', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const real = path.join(repoDir, 'real');
+    await mkdir(real, { recursive: true });
+    const link = path.join(repoDir, 'link');
+    await symlink(real, link);
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      extraDirs: [link],
+    });
+
+    const extras = roots.filter((r) => r.source === 'extra');
+    expect(extras).toHaveLength(1);
+    expect(extras[0]?.path).toBe(await realpath(real));
+    expect(extras[0]?.path).not.toBe(link);
+  });
+
+  it('keeps the higher-priority scope when an extra dir overlaps with auto-discovered user dirs', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const userBrand = path.join(homeDir, '.kimi-code', 'skills');
+    await writeSkill(userBrand, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: user version',
+      '---',
+    ]);
+    await mkdir(path.join(repoDir, '.git'), { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      extraDirs: [userBrand],
+    });
+
+    const realUserBrand = await realpath(userBrand);
+    const matching = roots.filter((r) => r.path === realUserBrand);
+    expect(matching).toHaveLength(1);
+    expect(matching[0]?.source).toBe('user');
+  });
+});
+
+describe('scope priority across resolution and discovery', () => {
+  it('lets a user-scope skill win over a same-named builtin', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const builtin = path.join(repoDir, 'builtin');
+    await writeSkill(builtin, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: builtin version',
+      '---',
+    ]);
+    const userBrand = path.join(homeDir, '.kimi-code', 'skills');
+    await writeSkill(userBrand, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: user version',
+      '---',
+    ]);
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      builtinDir: builtin,
+    });
+    const skills = await discoverSkills({ roots });
+    const foo = skills.find((s) => s.name === 'foo');
+
+    expect(foo?.source).toBe('user');
+    expect(foo?.description).toBe('user version');
+  });
+
+  it('lets a project-scope skill win over a same-named user-scope skill', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const userBrand = path.join(homeDir, '.kimi-code', 'skills');
+    await writeSkill(userBrand, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: user version',
+      '---',
+    ]);
+    const projBrand = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(projBrand, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: project version',
+      '---',
+    ]);
+
+    const roots = await resolveSkillRoots({ paths: { userHomeDir: homeDir, workDir } });
+    const skills = await discoverSkills({ roots });
+    const foo = skills.find((s) => s.name === 'foo');
+
+    expect(foo?.source).toBe('project');
+    expect(foo?.description).toBe('project version');
+  });
+
+  it('lets a project-scope skill win over a same-named builtin', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const builtin = path.join(repoDir, 'builtin');
+    await writeSkill(builtin, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: builtin version',
+      '---',
+    ]);
+    const projBrand = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(projBrand, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: project version',
+      '---',
+    ]);
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      builtinDir: builtin,
+    });
+    const skills = await discoverSkills({ roots });
+    const foo = skills.find((s) => s.name === 'foo');
+
+    expect(foo?.source).toBe('project');
+    expect(foo?.description).toBe('project version');
+  });
+
+  it('lets an extra-scope skill win over a same-named builtin', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const builtin = path.join(repoDir, 'builtin');
+    await writeSkill(builtin, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: builtin version',
+      '---',
+    ]);
+    const extra = path.join(repoDir, 'extra');
+    await writeSkill(extra, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: extra version',
+      '---',
+    ]);
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      builtinDir: builtin,
+      extraDirs: [extra],
+    });
+    const skills = await discoverSkills({ roots });
+    const foo = skills.find((s) => s.name === 'foo');
+
+    expect(foo?.source).toBe('extra');
+    expect(foo?.description).toBe('extra version');
+  });
+
+  it('lets a user-scope skill win over a same-named extra-scope skill', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const userBrand = path.join(homeDir, '.kimi-code', 'skills');
+    await writeSkill(userBrand, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: user version',
+      '---',
+    ]);
+    const extra = path.join(repoDir, 'extra');
+    await writeSkill(extra, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: extra version',
+      '---',
+    ]);
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      extraDirs: [extra],
+    });
+    const skills = await discoverSkills({ roots });
+    const foo = skills.find((s) => s.name === 'foo');
+
+    expect(foo?.source).toBe('user');
+    expect(foo?.description).toBe('user version');
+  });
+
+  it('fully excludes user and project scopes when explicit dirs are supplied', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const userBrand = path.join(homeDir, '.kimi-code', 'skills');
+    await writeSkill(userBrand, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: user version',
+      '---',
+    ]);
+    const projBrand = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(projBrand, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: project version',
+      '---',
+    ]);
+    const cli = path.join(repoDir, 'cli');
+    await writeSkill(cli, path.join('bar', 'SKILL.md'), [
+      '---',
+      'name: bar',
+      'description: cli version',
+      '---',
+    ]);
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      explicitDirs: [cli],
+    });
+    const skills = await discoverSkills({ roots });
+    const names = new Set(skills.map((s) => s.name));
+
+    expect(names.has('bar')).toBe(true);
+    expect(names.has('foo')).toBe(false);
+  });
+
+  it('resolves a three-scope (builtin/user/project) conflict to a single project entry', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const builtin = path.join(repoDir, 'builtin');
+    await writeSkill(builtin, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: builtin version',
+      '---',
+    ]);
+    const userBrand = path.join(homeDir, '.kimi-code', 'skills');
+    await writeSkill(userBrand, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: user version',
+      '---',
+    ]);
+    const projBrand = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(projBrand, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: project version',
+      '---',
+    ]);
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      builtinDir: builtin,
+    });
+    const skills = await discoverSkills({ roots });
+    const foos = skills.filter((s) => s.name === 'foo');
+
+    expect(foos).toHaveLength(1);
+    expect(foos[0]?.source).toBe('project');
+    expect(foos[0]?.description).toBe('project version');
+  });
+
+  it('lets explicit (CLI) skills win over extra skills with the same name', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const cli = path.join(repoDir, 'cli');
+    await writeSkill(cli, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: cli version',
+      '---',
+    ]);
+    const extra = path.join(repoDir, 'extra');
+    await writeSkill(extra, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: extra version',
+      '---',
+    ]);
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      explicitDirs: [cli],
+      extraDirs: [extra],
+    });
+    const skills = await discoverSkills({ roots });
+    const foos = skills.filter((s) => s.name === 'foo');
+
+    expect(foos).toHaveLength(1);
+    expect(foos[0]?.description).toBe('cli version');
+  });
+});
+
+describe('explicit dir override and scope stamping', () => {
+  it('suppresses user and project auto-discovery when explicit dirs are present', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const userBrand = path.join(homeDir, '.kimi-code', 'skills');
+    await mkdir(userBrand, { recursive: true });
+    const projBrand = path.join(repoDir, '.kimi-code', 'skills');
+    await mkdir(projBrand, { recursive: true });
+    const extraA = path.join(repoDir, 'extra_a');
+    const extraB = path.join(repoDir, 'extra_b');
+    await mkdir(extraA, { recursive: true });
+    await mkdir(extraB, { recursive: true });
+    const builtin = path.join(repoDir, 'builtin');
+    await mkdir(builtin, { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+      builtinDir: builtin,
+      explicitDirs: [extraA, extraB],
+    });
+
+    const paths = roots.map((r) => r.path);
+    expect(paths).toContain(await realpath(extraA));
+    expect(paths).toContain(await realpath(extraB));
+    expect(paths).toContain(await realpath(builtin));
+    expect(paths).not.toContain(await realpath(userBrand));
+    expect(paths).not.toContain(await realpath(projBrand));
+  });
+
+  it('returns both brand and generic user dirs when generic is empty (no shadowing)', async () => {
+    const { homeDir, workDir } = await makeWorkspace();
+    const generic = path.join(homeDir, '.agents', 'skills');
+    await mkdir(generic, { recursive: true });
+    const brand = path.join(homeDir, '.kimi-code', 'skills');
+    await mkdir(brand, { recursive: true });
+
+    const roots = await resolveSkillRoots({ paths: { userHomeDir: homeDir, workDir } });
+    const userPaths = roots.filter((r) => r.source === 'user').map((r) => r.path);
+
+    expect(userPaths).toContain(await realpath(brand));
+    expect(userPaths).toContain(await realpath(generic));
+    expect(userPaths.indexOf(await realpath(brand))).toBeLessThan(
+      userPaths.indexOf(await realpath(generic)),
+    );
+  });
+
+  it('stamps each discovered skill with the scope of its root', async () => {
+    const { homeDir, repoDir, workDir } = await makeWorkspace();
+    const userBrand = path.join(homeDir, '.kimi-code', 'skills');
+    await writeSkill(userBrand, path.join('user-skill', 'SKILL.md'), [
+      '---',
+      'name: user-skill',
+      'description: u',
+      '---',
+    ]);
+    const projBrand = path.join(repoDir, '.kimi-code', 'skills');
+    await writeSkill(projBrand, path.join('proj-skill', 'SKILL.md'), [
+      '---',
+      'name: proj-skill',
+      'description: p',
+      '---',
+    ]);
+
+    const roots = await resolveSkillRoots({ paths: { userHomeDir: homeDir, workDir } });
+    const skills = await discoverSkills({ roots });
+    const byName = new Map(skills.map((s) => [s.name, s] as const));
+
+    expect(byName.get('user-skill')?.source).toBe('user');
+    expect(byName.get('proj-skill')?.source).toBe('project');
+  });
+});
+
+async function makeWorkspace(): Promise<{
+  readonly homeDir: string;
+  readonly repoDir: string;
+  readonly workDir: string;
+}> {
+  const tmp = await mkdtemp(path.join(tmpdir(), 'kimi-skill-scanner-'));
+  tempDirs.push(tmp);
+  const homeDir = path.join(tmp, 'home');
+  const repoDir = path.join(tmp, 'repo');
+  const workDir = path.join(repoDir, 'packages', 'app');
+  await mkdir(path.join(repoDir, '.git'), { recursive: true });
+  await mkdir(workDir, { recursive: true });
+  return { homeDir, repoDir, workDir };
+}
+
+describe('project root discovery (.git walk-up)', () => {
+  it('walks up to the nearest .git ancestor for project-scope discovery', async () => {
+    const { homeDir } = await makeWorkspace();
+    const repo = await mkdtemp(path.join(tmpdir(), 'kimi-skill-walkup-'));
+    tempDirs.push(repo);
+    await mkdir(path.join(repo, '.git'), { recursive: true });
+    const repoKimi = path.join(repo, '.kimi-code', 'skills');
+    await writeSkill(repoKimi, path.join('foo', 'SKILL.md'), [
+      '---',
+      'name: foo',
+      'description: repo-root foo',
+      '---',
+    ]);
+    const nested = path.join(repo, 'packages', 'sub', 'pkg');
+    await mkdir(nested, { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir: nested },
+    });
+    const projectPaths = roots.filter((r) => r.source === 'project').map((r) => r.path);
+
+    expect(projectPaths).toContain(await realpath(repoKimi));
+  });
+
+  it('falls back to the work dir when no .git marker is found anywhere up the chain', async () => {
+    const { homeDir } = await makeWorkspace();
+    const noGitTmp = await mkdtemp(path.join(tmpdir(), 'kimi-skill-nogit-'));
+    tempDirs.push(noGitTmp);
+    const project = path.join(noGitTmp, 'project');
+    await mkdir(path.join(project, '.kimi-code', 'skills'), { recursive: true });
+    const workDir = path.join(project, 'foo');
+    await mkdir(workDir, { recursive: true });
+
+    const roots = await resolveSkillRoots({
+      paths: { userHomeDir: homeDir, workDir },
+    });
+    const projectPaths = roots.filter((r) => r.source === 'project').map((r) => r.path);
+
+    expect(projectPaths.some((p) => p.includes(path.join('project', '.kimi-code', 'skills')))).toBe(false);
+  });
+});
+
+async function writeSkill(
+  root: string,
+  relativePath: string,
+  lines: readonly string[],
+): Promise<void> {
+  const target = path.join(root, relativePath);
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, lines.join('\n'));
+}
diff --git a/packages/agent-core/test/tools/agent.test.ts b/packages/agent-core/test/tools/agent.test.ts
new file mode 100644
index 000000000..9a4e4837c
--- /dev/null
+++ b/packages/agent-core/test/tools/agent.test.ts
@@ -0,0 +1,718 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { ToolAccesses } from '../../src/loop';
+import type { Logger, LogPayload } from '../../src/logging';
+import type { ResolvedAgentProfile } from '../../src/profile';
+import type { SessionSubagentHost } from '../../src/session/subagent-host';
+import { BackgroundProcessManager } from '../../src/tools/background/manager';
+import { AgentTool, AgentToolInputSchema } from '../../src/tools/builtin/collaboration/agent';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+function context<Input>(args: Input, toolCallId = 'call_agent') {
+  return { turnId: '0', toolCallId, args, signal };
+}
+
+function mockSubagentHost<T extends Pick<SessionSubagentHost, 'spawn'> & Partial<SessionSubagentHost>>(
+  host: T,
+): T & SessionSubagentHost {
+  return { resume: vi.fn(), ...host } as unknown as T & SessionSubagentHost;
+}
+
+interface CapturedLogEntry {
+  readonly level: 'error' | 'warn' | 'info' | 'debug';
+  readonly message: string;
+  readonly payload: LogPayload | undefined;
+}
+
+function captureLogs(): { logger: Logger; entries: CapturedLogEntry[] } {
+  const entries: CapturedLogEntry[] = [];
+  const capture =
+    (level: CapturedLogEntry['level']) => (message: string, payload?: LogPayload) => {
+      entries.push({ level, message, payload });
+    };
+  const logger: Logger = {
+    error: capture('error'),
+    warn: capture('warn'),
+    info: capture('info'),
+    debug: capture('debug'),
+    createChild: () => logger,
+  };
+  return {
+    entries,
+    logger,
+  };
+}
+
+describe('AgentTool', () => {
+  it('accepts the snake_case background parameter', () => {
+    const parsed = AgentToolInputSchema.parse({
+      prompt: 'Investigate',
+      description: 'Find cause',
+      subagent_type: 'explore',
+      run_in_background: true,
+    });
+
+    expect(parsed).toMatchObject({
+      prompt: 'Investigate',
+      description: 'Find cause',
+      subagent_type: 'explore',
+      run_in_background: true,
+    });
+  });
+
+  it('exposes run_in_background and not runInBackground in the JSON schema', () => {
+    const host = mockSubagentHost({ spawn: vi.fn() });
+    const tool = new AgentTool(host);
+    const properties = (tool.parameters as { properties: Record<string, unknown> }).properties;
+
+    expect(properties).toHaveProperty('run_in_background');
+    expect(properties).not.toHaveProperty('runInBackground');
+  });
+
+  it('describes subagent_type and run_in_background parameters', () => {
+    const host = mockSubagentHost({ spawn: vi.fn() });
+    const tool = new AgentTool(host);
+    const properties = (
+      tool.parameters as {
+        properties: Record<string, { description?: string }>;
+      }
+    ).properties;
+
+    const subagentTypeDescription = properties['subagent_type']?.description ?? '';
+    // #7: the description states the default is coder
+    expect(subagentTypeDescription).toContain('coder');
+    // #6: terminology aligned with the "Available agent types" prose heading —
+    // no longer "agent registry"
+    expect(subagentTypeDescription).not.toContain('registry');
+    expect(subagentTypeDescription).toContain('agent type');
+    expect(properties['run_in_background']?.description).toContain('false');
+  });
+
+  it('does not mention background-only timeout details in the timeout description', () => {
+    const host = mockSubagentHost({ spawn: vi.fn() });
+    const tool = new AgentTool(host);
+    const properties = (
+      tool.parameters as {
+        properties: Record<string, { description?: string }>;
+      }
+    ).properties;
+
+    const timeoutDescription = properties['timeout']?.description ?? '';
+    // #5: the background default-timeout note is kept out of the static
+    // describe — it would mislead in the background-disabled variant
+    expect(timeoutDescription).not.toContain('Background');
+    expect(timeoutDescription).not.toContain('15min');
+  });
+
+  it('explains background timeout fallback in the background-enabled description without claiming a 15min default', () => {
+    const host = mockSubagentHost({ spawn: vi.fn() });
+    const tool = new AgentTool(host, new BackgroundProcessManager());
+
+    // #5: the background-enabled variant describes the real timeout fallback —
+    // an omitted timeout falls back to the operator-configured background
+    // timeout, or no time limit when the operator configured none — and must
+    // never claim an incorrect "15min default".
+    expect(tool.description).toContain('operator-configured background timeout');
+    expect(tool.description).toContain('no time limit');
+    expect(tool.description).not.toContain('15min');
+  });
+
+  it('does not expose a model parameter in the JSON schema', () => {
+    const host = mockSubagentHost({ spawn: vi.fn() });
+    const tool = new AgentTool(host);
+    const properties = (tool.parameters as { properties: Record<string, unknown> }).properties;
+
+    expect(properties).not.toHaveProperty('model');
+  });
+
+  it('renders the tool set for each subagent type', () => {
+    const host = mockSubagentHost({ spawn: vi.fn() });
+    const subagents = {
+      explore: profile({
+        name: 'explore',
+        description: 'Read-only exploration.',
+        tools: ['Read', 'Grep', 'Glob'],
+      }),
+      coder: profile({
+        name: 'coder',
+        description: 'General coding.',
+        tools: ['Read', 'Write', 'Edit', 'Bash'],
+      }),
+    };
+
+    const tool = new AgentTool(host, undefined, subagents);
+
+    expect(tool.description).toContain('Tools: Read, Grep, Glob');
+    expect(tool.description).toContain('Tools: Read, Write, Edit, Bash');
+  });
+
+  it('mentions resume preference and result visibility in the description', () => {
+    const host = mockSubagentHost({ spawn: vi.fn() });
+    const tool = new AgentTool(host);
+
+    expect(tool.description.toLowerCase()).toContain('resume');
+    expect(tool.description.toLowerCase()).toContain('only visible to you');
+    expect(tool.description.toLowerCase()).toContain('when not to');
+  });
+
+  it('normalizes the default subagent type into tool args', () => {
+    expect(
+      AgentToolInputSchema.parse({
+        prompt: 'Investigate',
+        description: 'Find cause',
+      }).subagent_type,
+    ).toBe('coder');
+    expect(
+      AgentToolInputSchema.parse({
+        prompt: 'Investigate',
+        description: 'Find cause',
+        subagent_type: '',
+      }).subagent_type,
+    ).toBe('coder');
+    expect(
+      AgentToolInputSchema.parse({
+        prompt: 'Continue',
+        description: 'Continue work',
+        resume: 'agent-existing',
+      }).subagent_type,
+    ).toBeUndefined();
+  });
+
+  it('describes configured subagent types', () => {
+    const host = mockSubagentHost({ spawn: vi.fn() });
+    const subagents = {
+      explore: profile({
+        name: 'explore',
+        description: 'Read-only exploration.',
+        whenToUse: 'Use for searches.',
+      }),
+      coder: profile({ name: 'coder', description: 'General coding.' }),
+    };
+
+    const tool = new AgentTool(host, undefined, subagents);
+
+    expect(tool.description).toContain('Available agent types');
+    expect(tool.description).toContain('- explore: Read-only exploration. Use for searches.');
+    expect(tool.description).toContain('- coder: General coding.');
+  });
+
+  it('spawns a foreground subagent and returns its summary', async () => {
+    const host = mockSubagentHost({
+      spawn: vi.fn().mockResolvedValue({
+        agentId: 'agent-child',
+        profileName: 'explore',
+        resumed: false,
+        completion: Promise.resolve({ result: 'child result' }),
+      }),
+    });
+    const tool = new AgentTool(host);
+
+    const result = await executeTool(tool,
+      context({
+        prompt: 'Investigate',
+        description: 'Find cause',
+        subagent_type: 'explore',
+      }),
+    );
+
+    expect(host.spawn).toHaveBeenCalledWith('explore', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Investigate',
+      description: 'Find cause',
+      runInBackground: false,
+      signal,
+    });
+    expect(result.output).toContain('agent_id: agent-child');
+    expect(result.output).toContain('actual_subagent_type: explore');
+    expect(result.output).toContain('child result');
+  });
+
+  it('falls back to coder for an empty subagent type', async () => {
+    const host = mockSubagentHost({
+      spawn: vi.fn().mockResolvedValue({
+        agentId: 'agent-child',
+        profileName: 'coder',
+        resumed: false,
+        completion: Promise.resolve({ result: 'child result' }),
+      }),
+    });
+    const tool = new AgentTool(host);
+
+    await executeTool(tool,
+      context({
+        prompt: 'Investigate',
+        description: 'Find cause',
+        subagent_type: '',
+      }),
+    );
+
+    expect(host.spawn).toHaveBeenCalledWith(
+      'coder',
+      expect.objectContaining({
+        parentToolCallId: 'call_agent',
+      }),
+    );
+  });
+
+  it('resumes a foreground subagent when resume is provided', async () => {
+    const host = mockSubagentHost({
+      spawn: vi.fn(),
+      resume: vi.fn().mockResolvedValue({
+        agentId: 'agent-existing',
+        profileName: 'explore',
+        resumed: true,
+        completion: Promise.resolve({ result: 'resumed result' }),
+      }),
+    });
+    const tool = new AgentTool(host);
+
+    const result = await executeTool(tool,
+      context({
+        prompt: 'Continue',
+        description: 'Continue work',
+        resume: 'agent-existing',
+      }),
+    );
+
+    expect(host.spawn).not.toHaveBeenCalled();
+    expect(host.resume).toHaveBeenCalledWith('agent-existing', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Continue',
+      description: 'Continue work',
+      runInBackground: false,
+      signal,
+    });
+    expect(result.output).toContain('agent_id: agent-existing');
+    expect(result.output).toContain('actual_subagent_type: explore');
+    expect(result.output).toContain('resumed result');
+  });
+
+  it('returns an error when resuming with a subagent type', async () => {
+    const host = mockSubagentHost({
+      spawn: vi.fn(),
+      resume: vi.fn(),
+    });
+    const tool = new AgentTool(host);
+
+    const result = await executeTool(tool,
+      context({
+        prompt: 'Continue',
+        description: 'Continue work',
+        resume: 'agent-existing',
+        subagent_type: 'explore',
+      }),
+    );
+
+    expect(result).toMatchObject({
+      isError: true,
+      output: 'Cannot set subagent_type when resuming an existing agent. Resume by agent id only.',
+    });
+    expect(host.resume).not.toHaveBeenCalled();
+  });
+
+  it('does not consume a background task slot when validation fails before launch', async () => {
+    const completion = new Promise<{ result: string }>(() => {});
+    const background = new BackgroundProcessManager({ maxRunningTasks: 1 });
+    const host = mockSubagentHost({
+      spawn: vi.fn().mockResolvedValue({
+        agentId: 'agent-child',
+        profileName: 'coder',
+        resumed: false,
+        completion,
+      }),
+      resume: vi.fn(),
+    });
+    const tool = new AgentTool(host, background);
+
+    const invalid = await executeTool(tool,
+      context({
+        prompt: 'Continue',
+        description: 'Invalid background resume',
+        resume: 'agent-existing',
+        subagent_type: 'explore',
+        run_in_background: true,
+      }),
+    );
+    const valid = await executeTool(tool,
+      context({
+        prompt: 'Investigate',
+        description: 'Find cause',
+        run_in_background: true,
+      }),
+    );
+
+    expect(invalid).toMatchObject({
+      isError: true,
+      output: 'Cannot set subagent_type when resuming an existing agent. Resume by agent id only.',
+    });
+    expect(valid.output).toContain('status: running');
+    expect(host.resume).not.toHaveBeenCalled();
+    expect(host.spawn).toHaveBeenCalledTimes(1);
+  });
+
+  it('resumes by id without constraining the subagent type', async () => {
+    const host = mockSubagentHost({
+      spawn: vi.fn(),
+      resume: vi.fn().mockResolvedValue({
+        agentId: 'agent-existing',
+        profileName: 'explore',
+        resumed: true,
+        completion: Promise.resolve({ result: 'resumed result' }),
+      }),
+    });
+    const tool = new AgentTool(host);
+
+    const result = await executeTool(tool,
+      context({
+        prompt: 'Continue',
+        description: 'Continue work',
+        resume: 'agent-existing',
+      }),
+    );
+
+    expect(host.spawn).not.toHaveBeenCalled();
+    expect(host.resume).toHaveBeenCalledWith('agent-existing', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Continue',
+      description: 'Continue work',
+      runInBackground: false,
+      signal,
+    });
+    expect(result.output).toContain('actual_subagent_type: explore');
+  });
+
+  it('declares no resource accesses so concurrent Agent calls can run in parallel', () => {
+    const host = mockSubagentHost({ spawn: vi.fn() });
+    const tool = new AgentTool(host);
+    const execution = tool.resolveExecution({
+      prompt: 'Investigate',
+      description: 'Find cause',
+      subagent_type: 'explore',
+    });
+
+    if (execution.isError === true) throw new Error('expected runnable execution');
+    expect(execution.accesses).toEqual(ToolAccesses.none());
+  });
+
+  it('uses the resumed agent profile in the activity description', () => {
+    const host = mockSubagentHost({
+      spawn: vi.fn(),
+      getProfileName: vi.fn().mockReturnValue('explore'),
+    });
+    const tool = new AgentTool(host);
+    const execution = tool.resolveExecution({
+      prompt: 'Continue',
+      description: 'Continue work',
+      resume: ' agent-existing ',
+    });
+
+    expect(execution.isError).toBeFalsy();
+    if (execution.isError === true) throw new Error('expected runnable execution');
+    expect(execution.description).toBe('Launching explore agent: Continue work');
+    expect(host.getProfileName).toHaveBeenCalledWith('agent-existing');
+  });
+
+  it('registers background subagents with the background manager', async () => {
+    const completion = new Promise<{ result: string }>(() => {});
+    const host = mockSubagentHost({
+      spawn: vi.fn().mockResolvedValue({
+        agentId: 'agent-child',
+        profileName: 'coder',
+        resumed: false,
+        completion,
+      }),
+    });
+    const background = new BackgroundProcessManager();
+    const tool = new AgentTool(host, background);
+
+    const result = await executeTool(tool,
+      context({
+        prompt: 'Investigate',
+        description: 'Find cause',
+        run_in_background: true,
+      }),
+    );
+
+    expect(result.output).toContain('status: running');
+    expect(result.output).toContain('agent_id: agent-child');
+    if (typeof result.output !== 'string') throw new TypeError('expected string output');
+    const taskId = result.output.match(/task_id: (agent-[0-9a-z]{8})/)?.[1];
+    expect(taskId).toBeDefined();
+    expect(background.getTask(taskId!)).toMatchObject({
+      status: 'running',
+      description: 'Find cause',
+    });
+  });
+
+  it('guides the AI with a non-blocking query hint and a resume hint on background launch', async () => {
+    const host = mockSubagentHost({
+      spawn: vi.fn().mockResolvedValue({
+        agentId: 'agent-child',
+        profileName: 'coder',
+        resumed: false,
+        completion: new Promise<{ result: string }>(() => {}),
+      }),
+    });
+    const background = new BackgroundProcessManager();
+    const tool = new AgentTool(host, background);
+
+    const result = await executeTool(tool,
+      context({
+        prompt: 'Investigate',
+        description: 'Find cause',
+        run_in_background: true,
+      }),
+    );
+
+    if (typeof result.output !== 'string') throw new TypeError('expected string output');
+    const taskId = result.output.match(/task_id: (agent-[0-9a-z]{8})/)?.[1];
+    expect(taskId).toBeDefined();
+    // M9: next_step — non-blocking progress check via TaskOutput
+    expect(result.output).toContain('next_step:');
+    expect(result.output).toContain(`TaskOutput(task_id="${taskId!}", block=false)`);
+    // M9: resume_hint — continue the same subagent instance
+    expect(result.output).toContain('resume_hint:');
+    expect(result.output).toContain('Agent(resume="agent-child"');
+  });
+
+  it('rejects background subagents when background management is unavailable', async () => {
+    const host = mockSubagentHost({
+      spawn: vi.fn().mockResolvedValue({
+        agentId: 'agent-child',
+        profileName: 'coder',
+        resumed: false,
+        completion: new Promise<{ result: string }>(() => {}),
+      }),
+    });
+    const tool = new AgentTool(host);
+
+    expect(tool.description).toContain('Background agent execution is disabled for this agent.');
+    expect(tool.description).not.toContain('the subagent runs detached from this turn');
+
+    const result = await executeTool(tool,
+      context({
+        prompt: 'Investigate',
+        description: 'Find cause',
+        run_in_background: true,
+      }),
+    );
+
+    expect(result).toMatchObject({
+      isError: true,
+      output:
+        'Background agent execution is not available for this agent because TaskList, TaskOutput, and TaskStop are not enabled.',
+    });
+    expect(host.spawn).not.toHaveBeenCalled();
+  });
+
+  it('does not spawn background subagents when the task limit is reached', async () => {
+    const background = new BackgroundProcessManager({ maxRunningTasks: 1 });
+    background.registerAgentTask(new Promise(() => {}), 'existing agent');
+    const host = mockSubagentHost({
+      spawn: vi.fn().mockResolvedValue({
+        agentId: 'agent-child',
+        profileName: 'coder',
+        resumed: false,
+        completion: new Promise<{ result: string }>(() => {}),
+      }),
+    });
+    const tool = new AgentTool(host, background);
+
+    const result = await executeTool(tool,
+      context({
+        prompt: 'Investigate',
+        description: 'Find cause',
+        run_in_background: true,
+      }),
+    );
+
+    expect(result).toMatchObject({
+      isError: true,
+      output: 'Too many background tasks are already running.',
+    });
+    expect(host.spawn).not.toHaveBeenCalled();
+  });
+
+  it('reserves a task slot before spawning concurrent background subagents', async () => {
+    const background = new BackgroundProcessManager({ maxRunningTasks: 1 });
+    const host = mockSubagentHost({
+      spawn: vi
+        .fn()
+        .mockResolvedValueOnce({
+          agentId: 'agent-first',
+          profileName: 'coder',
+          resumed: false,
+          completion: new Promise<{ result: string }>(() => {}),
+        })
+        .mockResolvedValueOnce({
+          agentId: 'agent-second',
+          profileName: 'coder',
+          resumed: false,
+          completion: Promise.resolve({ result: 'second result' }),
+        }),
+    });
+    const tool = new AgentTool(host, background);
+
+    const first = executeTool(tool,
+      context({
+        prompt: 'Investigate first',
+        description: 'Find first',
+        run_in_background: true,
+      }),
+    );
+    const second = executeTool(tool,
+      context({
+        prompt: 'Investigate second',
+        description: 'Find second',
+        run_in_background: true,
+      }),
+    );
+
+    const results = await Promise.all([first, second]);
+
+    expect(host.spawn).toHaveBeenCalledTimes(1);
+    expect(results).toContainEqual(
+      expect.objectContaining({ output: expect.stringContaining('status: running') }),
+    );
+    expect(results).toContainEqual(
+      expect.objectContaining({
+        isError: true,
+        output: 'Too many background tasks are already running.',
+      }),
+    );
+  });
+
+  it('returns tool errors when spawning fails', async () => {
+    const error = new Error('missing subagent');
+    const { logger, entries } = captureLogs();
+    const host = mockSubagentHost({
+      spawn: vi.fn().mockRejectedValue(error),
+    });
+    const tool = new AgentTool(host, undefined, undefined, { log: logger });
+
+    const result = await executeTool(tool,
+      context({ prompt: 'Investigate', description: 'Find cause' }),
+    );
+
+    expect(result).toMatchObject({
+      isError: true,
+      output: 'subagent error: missing subagent',
+    });
+    expect(entries).toEqual([
+      {
+        level: 'warn',
+        message: 'subagent launch failed',
+        payload: expect.objectContaining({
+          toolCallId: 'call_agent',
+          runInBackground: false,
+          operation: 'spawn',
+          subagentType: 'coder',
+          error,
+        }),
+      },
+    ]);
+  });
+
+  it('logs background registration failures', async () => {
+    const error = new Error('background unavailable');
+    const { logger, entries } = captureLogs();
+    const host = mockSubagentHost({
+      spawn: vi.fn().mockResolvedValue({
+        agentId: 'agent-child',
+        profileName: 'coder',
+        resumed: false,
+        completion: new Promise<{ result: string }>(() => {}),
+      }),
+    });
+    const background = new BackgroundProcessManager();
+    vi.spyOn(background, 'registerAgentTask').mockImplementation(() => {
+      throw error;
+    });
+    const tool = new AgentTool(host, background, undefined, { log: logger });
+
+    const result = await executeTool(tool,
+      context({
+        prompt: 'Investigate',
+        description: 'Find cause',
+        run_in_background: true,
+      }),
+    );
+
+    expect(result).toMatchObject({
+      isError: true,
+      output: 'background unavailable',
+    });
+    expect(entries).toEqual([
+      {
+        level: 'warn',
+        message: 'background agent task registration failed',
+        payload: expect.objectContaining({
+          toolCallId: 'call_agent',
+          agentId: 'agent-child',
+          subagentType: 'coder',
+          error,
+        }),
+      },
+    ]);
+  });
+
+  it('returns the spawned agent id when a foreground subagent times out', async () => {
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+    try {
+      const host = mockSubagentHost({
+        spawn: vi.fn((_profileName: string, options: { signal: AbortSignal }) =>
+          Promise.resolve({
+            agentId: 'agent-child',
+            profileName: 'coder',
+            resumed: false,
+            completion: new Promise<{ result: string }>((_resolve, reject) => {
+              options.signal.addEventListener(
+                'abort',
+                () => {
+                  reject(options.signal.reason);
+                },
+                { once: true },
+              );
+            }),
+          }),
+        ),
+      });
+      const tool = new AgentTool(host);
+
+      const resultPromise = executeTool(tool,
+        context({
+          prompt: 'Investigate',
+          description: 'Find cause',
+          timeout: 30,
+        }),
+      );
+      await vi.advanceTimersByTimeAsync(30_000);
+      const result = await resultPromise;
+
+      expect(result).toMatchObject({ isError: true });
+      expect(result.output).toContain('agent_id: agent-child');
+      expect(result.output).toContain('actual_subagent_type: coder');
+      expect(result.output).toContain('status: failed');
+      expect(result.output).toContain('subagent error: Agent timed out after 30s.');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+function profile(input: {
+  readonly name: string;
+  readonly description?: string;
+  readonly whenToUse?: string;
+  readonly tools?: readonly string[];
+}): ResolvedAgentProfile {
+  return {
+    name: input.name,
+    description: input.description,
+    whenToUse: input.whenToUse,
+    systemPrompt: () => `${input.name} prompt`,
+    tools: [...(input.tools ?? [])],
+  };
+}
diff --git a/packages/agent-core/test/tools/ask-user.test.ts b/packages/agent-core/test/tools/ask-user.test.ts
new file mode 100644
index 000000000..be69ac363
--- /dev/null
+++ b/packages/agent-core/test/tools/ask-user.test.ts
@@ -0,0 +1,263 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Agent } from '../../src/agent';
+import type { PermissionMode } from '../../src/agent/permission';
+import { ErrorCodes, KimiError } from '../../src/errors';
+import type { QuestionRequest, QuestionResult } from '../../src/rpc';
+import {
+  AskUserQuestionInputSchema,
+  AskUserQuestionTool,
+  type AskUserQuestionInput,
+} from '../../src/tools/builtin/collaboration/ask-user';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+function input(
+  overrides: Partial<AskUserQuestionInput['questions'][number]> = {},
+): AskUserQuestionInput {
+  return {
+    questions: [
+      {
+        question: 'Which database?',
+        header: 'Storage',
+        options: [
+          { label: 'Postgres', description: 'Relational storage' },
+          { label: 'SQLite', description: 'Embedded storage' },
+        ],
+        multi_select: false,
+        ...overrides,
+      },
+    ],
+  };
+}
+
+function makeTool(
+  options: {
+    readonly mode?: PermissionMode;
+    readonly requestQuestion?: (
+      request: QuestionRequest,
+      options: { readonly signal?: AbortSignal },
+    ) => Promise<QuestionResult>;
+  } = {},
+): {
+  readonly tool: AskUserQuestionTool;
+  readonly requestQuestion: ReturnType<typeof vi.fn>;
+  readonly telemetryTrack: ReturnType<typeof vi.fn>;
+} {
+  const requestQuestion = vi.fn(
+    options.requestQuestion ??
+      (async () => ({
+        Postgres: true,
+      })),
+  );
+  const telemetryTrack = vi.fn();
+  const agent = {
+    permission: { mode: options.mode ?? 'manual' },
+    rpc: { requestQuestion },
+    telemetry: { track: telemetryTrack },
+  } as unknown as Agent;
+  return { tool: new AskUserQuestionTool(agent), requestQuestion, telemetryTrack };
+}
+
+describe('AskUserQuestionTool', () => {
+  it('exposes current metadata and schema', () => {
+    const { tool } = makeTool();
+
+    expect(tool.name).toBe('AskUserQuestion');
+    expect(tool.description).toContain('structured options');
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: { questions: { type: 'array' } },
+    });
+    expect(AskUserQuestionInputSchema.safeParse(input()).success).toBe(true);
+    expect(AskUserQuestionInputSchema.safeParse({ questions: [] }).success).toBe(false);
+    expect(
+      AskUserQuestionInputSchema.safeParse(
+        input({
+          options: [{ label: 'Only one', description: 'Not enough choices' }],
+        }),
+      ).success,
+    ).toBe(false);
+  });
+
+  it('describes the no-Other rule on options and the Recommended hint on label', () => {
+    const { tool } = makeTool();
+    const params = tool.parameters as {
+      properties: {
+        questions: {
+          items: {
+            properties: {
+              options: {
+                description?: string;
+                items: { properties: { label: { description?: string } } };
+              };
+            };
+          };
+        };
+      };
+    };
+
+    const optionsSchema = params.properties.questions.items.properties.options;
+    expect(optionsSchema.description).toContain("Do NOT include an 'Other' option");
+    expect(optionsSchema.description).toContain('the system adds one automatically');
+
+    const labelSchema = optionsSchema.items.properties.label;
+    expect(labelSchema.description).toContain("append '(Recommended)'");
+  });
+
+  it.each(['manual', 'yolo'] as const)(
+    'dispatches questions through the agent rpc in %s mode',
+    async (mode) => {
+      const { tool, requestQuestion, telemetryTrack } = makeTool({ mode });
+
+      const result = await executeTool(tool, {
+        turnId: '0',
+        toolCallId: 'call_question',
+        args: input({ multi_select: true }),
+        signal,
+      });
+
+      expect(result.isError).toBe(false);
+      expect(result.output).toBe(JSON.stringify({ answers: { Postgres: true } }));
+      expect(requestQuestion).toHaveBeenCalledWith(
+        {
+          turnId: 0,
+          toolCallId: 'call_question',
+          questions: [
+            {
+              question: 'Which database?',
+              header: 'Storage',
+              options: [
+                { label: 'Postgres', description: 'Relational storage' },
+                { label: 'SQLite', description: 'Embedded storage' },
+              ],
+              multiSelect: true,
+            },
+          ],
+        },
+        { signal },
+      );
+      expect(telemetryTrack).toHaveBeenCalledWith('question_answered', {
+        answered: 1,
+      });
+    },
+  );
+
+  it('tracks the structured question answer method without leaking it into output', async () => {
+    const { tool, telemetryTrack } = makeTool({
+      requestQuestion: async () => ({
+        answers: { 'Which database?': 'SQLite' },
+        method: 'number_key',
+      }),
+    });
+
+    const result = await executeTool(tool, {
+      turnId: '0',
+      toolCallId: 'call_question',
+      args: input(),
+      signal,
+    });
+
+    expect(result).toMatchObject({ isError: false });
+    expect(result.output).toBe(JSON.stringify({ answers: { 'Which database?': 'SQLite' } }));
+    expect(telemetryTrack).toHaveBeenCalledWith('question_answered', {
+      answered: 1,
+      method: 'number_key',
+    });
+  });
+
+  it('returns a dismissed message when every question is dismissed', async () => {
+    const { tool, telemetryTrack } = makeTool({ requestQuestion: async () => null });
+
+    const result = await executeTool(tool, {
+      turnId: '0',
+      toolCallId: 'call_question',
+      args: {
+        questions: [input().questions[0]!, input({ question: 'Which cache?' }).questions[0]!],
+      },
+      signal,
+    });
+
+    expect(result).toMatchObject({ isError: false });
+    expect(result.output).toContain('dismissed');
+    expect(result.output).toContain('answers');
+    expect(telemetryTrack).toHaveBeenCalledWith('question_dismissed');
+  });
+
+  it('resolves question rpc error responses as dismissed answers', async () => {
+    const { tool } = makeTool({
+      requestQuestion: async () => {
+        throw new KimiError(ErrorCodes.INTERNAL, 'JSON-RPC question error response');
+      },
+    });
+
+    const result = await executeTool(tool, {
+      turnId: '0',
+      toolCallId: 'call_question',
+      args: input(),
+      signal,
+    });
+
+    expect(result).toMatchObject({ isError: false });
+    expect(result.output).toContain('dismissed');
+    expect(typeof result.output).toBe('string');
+    const output = typeof result.output === 'string' ? result.output : '';
+    expect(JSON.parse(output)).toEqual({
+      answers: {},
+      note: 'User dismissed the question without answering.',
+    });
+    expect(result.output).not.toContain('Do NOT call this tool again');
+  });
+
+  it('propagates aborts while waiting for question rpc', async () => {
+    const controller = new AbortController();
+    const { tool } = makeTool({
+      requestQuestion: async (_request, options) =>
+        new Promise<QuestionResult>((_resolve, reject) => {
+          options.signal?.addEventListener(
+            'abort',
+            () => {
+              const error = new Error('Aborted');
+              error.name = 'AbortError';
+              reject(error);
+            },
+            { once: true },
+          );
+        }),
+    });
+
+    const result = executeTool(tool, {
+      turnId: '0',
+      toolCallId: 'call_question',
+      args: input(),
+      signal: controller.signal,
+    });
+    controller.abort();
+
+    await expect(result).rejects.toHaveProperty('name', 'AbortError');
+  });
+
+  // Migrated from PR #107:
+  // py: tests/tools/test_ask_user.py::test_ask_user_client_unsupported.
+  it('returns a distinct hard error when the client signals unsupported', async () => {
+    const { tool } = makeTool({
+      requestQuestion: async () => {
+        throw new KimiError(ErrorCodes.NOT_IMPLEMENTED, 'Client does not support questions');
+      },
+    });
+
+    const result = await executeTool(tool, {
+      turnId: '0',
+      toolCallId: 'tc-ask-unsupported',
+      args: input(),
+      signal,
+    });
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('connected client');
+    expect(result.output).toContain('does not support interactive questions');
+    expect(result.output).toContain('Do NOT call this tool again');
+    expect(result.output).toContain('Ask the user directly in your text response instead');
+  });
+});
diff --git a/packages/agent-core/test/tools/background/agent-timeout.test.ts b/packages/agent-core/test/tools/background/agent-timeout.test.ts
new file mode 100644
index 000000000..9455bf4b2
--- /dev/null
+++ b/packages/agent-core/test/tools/background/agent-timeout.test.ts
@@ -0,0 +1,137 @@
+/**
+ * `registerAgentTask` `timeoutMs` option.
+ *
+ * Semantics:
+ *   - external deadline fires → status=`failed`, `timedOut=true`
+ *   - no `timeoutMs` → the task runs to completion without a wrapper
+ *   - internal `TimeoutError` rejection (e.g. aiohttp sock_read) is a
+ *     generic `failed` with `timedOut` left unset — the flag must
+ *     only be set for the caller-driven deadline
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BackgroundProcessManager } from '../../../src/tools/background/manager';
+
+describe('BackgroundProcessManager.registerAgentTask — timeoutMs', () => {
+  const manager = new BackgroundProcessManager();
+
+  afterEach(() => {
+    manager._reset();
+    vi.useRealTimers();
+  });
+
+  it('external deadline marks task failed with timedOut=true', async () => {
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+    // A never-resolving completion — only the deadline will fire.
+    const hangForever = new Promise<{ result: string }>(() => {});
+    const taskId = manager.registerAgentTask(hangForever, 'hang', { timeoutMs: 2_000 });
+
+    // Advance past the deadline; awaitTerminal resolves once the race
+    // finishes and the `.finally` block runs.
+    const terminalPromise = manager.waitForTerminal(taskId);
+    await vi.advanceTimersByTimeAsync(2_100);
+    const info = await terminalPromise;
+
+    expect(info?.status).toBe('failed');
+    expect(info?.timedOut).toBe(true);
+  });
+
+  it('omitting timeoutMs lets the task run to completion (no wrapper)', async () => {
+    let resolveFn!: (r: { result: string }) => void;
+    const completion = new Promise<{ result: string }>((res) => {
+      resolveFn = res;
+    });
+    const taskId = manager.registerAgentTask(completion, 'no deadline');
+
+    resolveFn({ result: 'finished' });
+    const info = await manager.waitForTerminal(taskId);
+    expect(info?.status).toBe('completed');
+    expect(info?.timedOut).toBeUndefined();
+  });
+
+  it('internal TimeoutError rejection = generic failure, timedOut unset', async () => {
+    // Even with a deadline set, an internal TimeoutError that fires
+    // BEFORE the deadline must land as a plain `failed` (not as a
+    // deadline-driven timeout).
+    const internalErr = new Error('aiohttp sock_read timeout');
+    internalErr.name = 'TimeoutError';
+    const rejecting = Promise.reject(internalErr);
+    const taskId = manager.registerAgentTask(rejecting, 'internal timeout', {
+      timeoutMs: 900_000,
+    });
+
+    const info = await manager.waitForTerminal(taskId);
+    expect(info?.status).toBe('failed');
+    // Deadline never fired → timedOut must NOT be set.
+    expect(info?.timedOut).toBeUndefined();
+  });
+
+  // Explicit per-task timeoutMs must be surfaced on the task info so
+  // downstream wait-cap consumers can honour the agent-supplied value
+  // instead of falling back to a hard-coded default. (gap #6 family.)
+  //
+  // Uses fake timers so the 30-min deadline armed by registerAgentTask
+  // does not leak across the test boundary into the Vitest worker —
+  // the `completion` promise here never resolves, so the lifecycle
+  // promise's `.finally(clearTimeout)` would not run under real time.
+  it('explicit timeoutMs is persisted on the task info', () => {
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+    const taskId = manager.registerAgentTask(new Promise(() => {}), 'persist timeout', {
+      timeoutMs: 1_800_000,
+    });
+    const info = manager.getTask(taskId);
+    expect((info as unknown as { timeoutMs?: number }).timeoutMs).toBe(1_800_000);
+  });
+
+  // Decision (confirmed with team, 2026-05-19): background tasks in
+  // kimi-code do NOT carry an implicit default timeout. The Python
+  // kimi-cli enforced a 30-min default because its agents were
+  // expected to be short-lived; kimi-code's agents may legitimately
+  // run a dev server, a long compile, or a watch loop, and an
+  // auto-kill would be a footgun. The shutdown wait-cap that reads
+  // timeoutMs falls back to its own policy when the field is
+  // undefined; the BPM does not invent a default.
+  //
+  // This test is kept (rather than deleted) to act as a regression
+  // guard: if someone later adds a hard-coded default in
+  // registerAgentTask, the assertion below catches it.
+  it('omitted timeoutMs leaves the task info field undefined', () => {
+    const taskId = manager.registerAgentTask(new Promise(() => {}), 'default timeout');
+    const info = manager.getTask(taskId);
+    expect((info as unknown as { timeoutMs?: number }).timeoutMs).toBeUndefined();
+  });
+
+  // Contract decision (2026-05-21): kimi-code treats `timeoutMs: 0`
+  // as "record the value but do NOT arm a deadline" rather than
+  // Python's "fire immediately" semantics. The field is preserved on
+  // the task info so shutdown wait-caps / UI can read it; the
+  // deadline-arming check (`opts.timeoutMs > 0`) deliberately skips
+  // zero so a caller writing `0` does not lose its task to an
+  // immediate kill.
+  it('timeoutMs=0 is preserved on the task info and does not arm a deadline', async () => {
+    const taskId = manager.registerAgentTask(new Promise(() => {}), 'zero timeout', {
+      timeoutMs: 0,
+    });
+    // The literal zero is preserved on the task info.
+    const initial = manager.getTask(taskId);
+    expect((initial as unknown as { timeoutMs?: number }).timeoutMs).toBe(0);
+
+    // No deadline armed: the task stays running. We bound the wait
+    // with a short race so the test does not hang on the never-
+    // settling completion promise; the racing branch winning is the
+    // expected outcome.
+    const raced = await Promise.race<{ status: string; timedOut?: boolean } | undefined>([
+      manager.waitForTerminal(taskId).then((info) =>
+        info === undefined ? undefined : { status: info.status, timedOut: info.timedOut },
+      ),
+      new Promise<{ status: string; timedOut?: boolean }>((res) => {
+        setTimeout(() => {
+          res({ status: 'running' });
+        }, 100);
+      }),
+    ]);
+    expect(raced?.status).toBe('running');
+    expect(raced?.timedOut).toBeUndefined();
+  });
+});
diff --git a/packages/agent-core/test/tools/background/heartbeat-stale.test.ts b/packages/agent-core/test/tools/background/heartbeat-stale.test.ts
new file mode 100644
index 000000000..ef22ab477
--- /dev/null
+++ b/packages/agent-core/test/tools/background/heartbeat-stale.test.ts
@@ -0,0 +1,88 @@
+/**
+ * BPM reconcile identifies stale ghost tasks on startup and fires a
+ * single `onTerminal` callback (lost) per ghost, deduped on a second
+ * reconcile.
+ *
+ * Uses **real timers**: reconcile is a batch operation driven by
+ * `started_at` comparisons, not setTimeout, so fake timers would only
+ * add noise.
+ *
+ * The broader BPM ↔ notification wiring used to live in a host integration
+ * test; here we validate the BPM surface (callback shape + idempotency) in
+ * isolation.
+ */
+
+import { mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { BackgroundProcessManager } from '../../../src/tools/background/manager';
+import { writeTask } from '../../../src/tools/background/persist';
+
+let sessionDir: string;
+
+beforeEach(async () => {
+  sessionDir = join(
+    tmpdir(),
+    `kimi-hb-stale-${String(Date.now())}-${Math.random().toString(36).slice(2)}`,
+  );
+  await mkdir(sessionDir, { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(sessionDir, { recursive: true, force: true });
+});
+
+describe('BPM reconcile — stale heartbeat ghost detection', () => {
+  it('fires onTerminal with status=lost for a stale running ghost', async () => {
+    // Seed a ghost that started 1 hour ago and was never closed out.
+    const oneHourAgo = Date.now() - 60 * 60 * 1000;
+    await writeTask(sessionDir, {
+      task_id: 'bash-stale000',
+      command: 'some_old_cmd',
+      description: 'ghost from a prior crash',
+      pid: 1234,
+      started_at: oneHourAgo,
+      ended_at: null,
+      exit_code: null,
+      status: 'running',
+    });
+
+    const mgr = new BackgroundProcessManager();
+    const fired: Array<{ taskId: string; status: string }> = [];
+    mgr.onTerminal((info) => {
+      fired.push({ taskId: info.taskId, status: info.status });
+    });
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    await mgr.reconcile();
+
+    expect(fired).toEqual([{ taskId: 'bash-stale000', status: 'lost' }]);
+  });
+
+  it('second reconcile does NOT refire onTerminal for the same ghost', async () => {
+    await writeTask(sessionDir, {
+      task_id: 'bash-dedup000',
+      command: 'x',
+      description: 'dedupe stale',
+      pid: 99,
+      started_at: Date.now() - 30 * 60 * 1000,
+      ended_at: null,
+      exit_code: null,
+      status: 'running',
+    });
+
+    const mgr = new BackgroundProcessManager();
+    const fired: string[] = [];
+    mgr.onTerminal((info) => {
+      fired.push(info.taskId);
+    });
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    await mgr.reconcile();
+    await mgr.reconcile();
+    expect(fired).toEqual(['bash-dedup000']);
+  });
+});
diff --git a/packages/agent-core/test/tools/background/ids.test.ts b/packages/agent-core/test/tools/background/ids.test.ts
new file mode 100644
index 000000000..cf00a9818
--- /dev/null
+++ b/packages/agent-core/test/tools/background/ids.test.ts
@@ -0,0 +1,75 @@
+/**
+ * Task id format: `{bash|agent}-{8 base36 chars}`.
+ *
+ * Legacy `bg_<hex>` format is NOT accepted.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { generateTaskId, VALID_TASK_ID } from '../../../src/tools/background/index';
+
+describe('background task id format', () => {
+  it('generated ids pass VALID_TASK_ID for every kind', () => {
+    for (const kind of ['bash', 'agent'] as const) {
+      for (let i = 0; i < 32; i++) {
+        const id = generateTaskId(kind);
+        expect(id).toMatch(VALID_TASK_ID);
+        expect(id.startsWith(`${kind}-`)).toBe(true);
+      }
+    }
+  });
+
+  it('rejects malformed ids', () => {
+    const rejected = [
+      '', // empty
+      'x', // too short
+      '-bash', // wrong prefix
+      'BASH-12345678', // uppercase
+      'bash_12345678', // underscore separator
+      '../escape', // path traversal
+      'bash-1234567', // 7-char suffix
+      'bash-123456789', // 9-char suffix
+      'agent-ABCDEFGH', // uppercase suffix
+      'bg_12345678', // legacy format is no longer accepted
+      'a'.repeat(26), // long junk
+    ];
+    for (const bad of rejected) {
+      expect(VALID_TASK_ID.test(bad)).toBe(false);
+    }
+    // Spot-check one *valid* id so the negative assertions aren't
+    // drifting (a regex that rejects everything would pass the block
+    // above on its own).
+    expect(VALID_TASK_ID.test('bash-00000000')).toBe(true);
+    expect(VALID_TASK_ID.test('agent-zzzzzzzz')).toBe(true);
+  });
+
+  // Cross-module invariant: every id produced by the generator must
+  // satisfy the validation regex used by the persistence store. Run
+  // multiple iterations because the suffix is random.
+  it('every generated id passes VALID_TASK_ID for every kind', () => {
+    for (const kind of ['bash', 'agent'] as const) {
+      for (let i = 0; i < 128; i++) {
+        const id = generateTaskId(kind);
+        expect(VALID_TASK_ID.test(id)).toBe(true);
+        expect(id.startsWith(`${kind}-`)).toBe(true);
+      }
+    }
+  });
+
+  // Negative invariant: empty / too-short / wrong-prefix / uppercase /
+  // underscore / path-traversal must all be rejected.
+  it('explicit rejection set', () => {
+    const cases = [
+      '',
+      'x',
+      '-bash',
+      'BASH-12345678',
+      'bash_12345678',
+      '../escape',
+      'a'.repeat(26),
+    ];
+    for (const bad of cases) {
+      expect(VALID_TASK_ID.test(bad)).toBe(false);
+    }
+  });
+});
diff --git a/packages/agent-core/test/tools/background/lifecycle.test.ts b/packages/agent-core/test/tools/background/lifecycle.test.ts
new file mode 100644
index 000000000..806a278d3
--- /dev/null
+++ b/packages/agent-core/test/tools/background/lifecycle.test.ts
@@ -0,0 +1,257 @@
+/**
+ * BackgroundProcessManager — onLifecycle hook.
+ *
+ * Covers the three lifecycle events emitted to subscribers:
+ *   - 'started' on register / registerAgentTask
+ *   - 'updated' on awaiting_approval enter / leave
+ *   - 'terminated' on natural exit / failure / stop / reconcile-as-lost
+ *
+ * Subscribers must receive each phase exactly once per task, in order,
+ * with the current `BackgroundTaskInfo` snapshot.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import type { Writable } from 'node:stream';
+
+import type { KaosProcess } from '@moonshot-ai/kaos';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  BackgroundProcessManager,
+  type BackgroundTaskInfo,
+} from '../../../src/tools/background/manager';
+
+type LifecycleEvent = 'started' | 'updated' | 'terminated';
+
+interface CallRecord {
+  event: LifecycleEvent;
+  info: BackgroundTaskInfo;
+}
+
+function makeRecorder(): {
+  records: CallRecord[];
+  callback: (event: LifecycleEvent, info: BackgroundTaskInfo) => void;
+} {
+  const records: CallRecord[] = [];
+  return {
+    records,
+    callback: (event, info) => {
+      records.push({ event, info });
+    },
+  };
+}
+
+function immediateProcess(exitCode: number): KaosProcess {
+  return {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 20000 + exitCode,
+    exitCode,
+    wait: vi.fn().mockResolvedValue(exitCode) as KaosProcess['wait'],
+    kill: vi.fn().mockResolvedValue(undefined) as KaosProcess['kill'],
+  };
+}
+
+function pendingProcess(): KaosProcess {
+  let resolveWait: (code: number) => void = () => {};
+  const waitPromise = new Promise<number>((res) => {
+    resolveWait = res;
+  });
+  let currentExitCode: number | null = null;
+  return {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 88888,
+    get exitCode(): number | null {
+      return currentExitCode;
+    },
+    wait: () => waitPromise,
+    kill: vi.fn(async () => {
+      if (currentExitCode === null) {
+        currentExitCode = 143;
+        resolveWait(143);
+      }
+    }) as unknown as KaosProcess['kill'],
+  };
+}
+
+describe('BackgroundProcessManager — onLifecycle', () => {
+  let manager: BackgroundProcessManager;
+
+  beforeEach(() => {
+    manager = new BackgroundProcessManager();
+  });
+
+  afterEach(() => {
+    manager._reset();
+  });
+
+  it("fires 'started' immediately on register()", () => {
+    const { records, callback } = makeRecorder();
+    manager.onLifecycle(callback);
+
+    const taskId = manager.register(pendingProcess(), 'sleep 60', 'long task');
+
+    expect(records.length).toBe(1);
+    expect(records[0]!.event).toBe('started');
+    expect(records[0]!.info.taskId).toBe(taskId);
+    expect(records[0]!.info.status).toBe('running');
+  });
+
+  it("fires 'started' on registerAgentTask()", () => {
+    const { records, callback } = makeRecorder();
+    manager.onLifecycle(callback);
+
+    const taskId = manager.registerAgentTask(new Promise(() => {}), 'an agent');
+
+    expect(records.length).toBe(1);
+    expect(records[0]!.event).toBe('started');
+    expect(records[0]!.info.taskId).toBe(taskId);
+    expect(records[0]!.info.taskId).toMatch(/^agent-/);
+  });
+
+  it("fires 'updated' on markAwaitingApproval / clearAwaitingApproval", () => {
+    const { records, callback } = makeRecorder();
+    const taskId = manager.register(pendingProcess(), 'sleep', 'demo');
+    manager.onLifecycle(callback);
+
+    manager.markAwaitingApproval(taskId, 'needs permission');
+    manager.clearAwaitingApproval(taskId);
+
+    const events = records.map((r) => r.event);
+    expect(events).toEqual(['updated', 'updated']);
+    expect(records[0]!.info.status).toBe('awaiting_approval');
+    expect(records[0]!.info.approvalReason).toBe('needs permission');
+    expect(records[1]!.info.status).toBe('running');
+    expect(records[1]!.info.approvalReason).toBeUndefined();
+  });
+
+  it("does not fire 'updated' for no-op markAwaitingApproval / clearAwaitingApproval", () => {
+    const { records, callback } = makeRecorder();
+    manager.onLifecycle(callback);
+
+    // unknown task
+    manager.markAwaitingApproval('bash-deadbeef', 'nope');
+    manager.clearAwaitingApproval('bash-deadbeef');
+
+    // clear when not in awaiting_approval state is a no-op
+    const taskId = manager.register(pendingProcess(), 'sleep', 'demo');
+    records.length = 0;
+    manager.clearAwaitingApproval(taskId);
+
+    expect(records.length).toBe(0);
+  });
+
+  it("fires 'terminated' on natural process exit (completed)", async () => {
+    const { records, callback } = makeRecorder();
+    manager.onLifecycle(callback);
+
+    manager.register(immediateProcess(0), 'echo', 'done');
+    await new Promise((r) => setTimeout(r, 20));
+
+    const terminated = records.filter((r) => r.event === 'terminated');
+    expect(terminated.length).toBe(1);
+    expect(terminated[0]!.info.status).toBe('completed');
+    expect(terminated[0]!.info.exitCode).toBe(0);
+  });
+
+  it("fires 'terminated' on non-zero exit (failed)", async () => {
+    const { records, callback } = makeRecorder();
+    manager.onLifecycle(callback);
+
+    manager.register(immediateProcess(2), 'false', 'fail');
+    await new Promise((r) => setTimeout(r, 20));
+
+    const terminated = records.filter((r) => r.event === 'terminated');
+    expect(terminated.length).toBe(1);
+    expect(terminated[0]!.info.status).toBe('failed');
+    expect(terminated[0]!.info.exitCode).toBe(2);
+  });
+
+  it("fires 'terminated' exactly once for the same task (idempotent)", async () => {
+    const { records, callback } = makeRecorder();
+    manager.onLifecycle(callback);
+
+    manager.register(immediateProcess(0), 'echo', 'done');
+    await new Promise((r) => setTimeout(r, 20));
+    // Manual settle attempt — should not produce a second terminated event.
+    await manager.settlePendingExits();
+
+    const terminated = records.filter((r) => r.event === 'terminated');
+    expect(terminated.length).toBe(1);
+  });
+
+  it("fires 'started' -> 'terminated' in order on full lifecycle", async () => {
+    const { records, callback } = makeRecorder();
+    manager.onLifecycle(callback);
+
+    manager.register(immediateProcess(0), 'echo', 'done');
+    await new Promise((r) => setTimeout(r, 20));
+
+    const events = records.map((r) => r.event);
+    expect(events).toEqual(['started', 'terminated']);
+  });
+
+  it("fires 'terminated' with status='killed' on stop()", async () => {
+    const { records, callback } = makeRecorder();
+    manager.onLifecycle(callback);
+
+    const taskId = manager.register(pendingProcess(), 'sleep 60', 'long');
+    await manager.stop(taskId, 'user requested');
+
+    const terminated = records.filter((r) => r.event === 'terminated');
+    expect(terminated.length).toBe(1);
+    expect(terminated[0]!.info.status).toBe('killed');
+    expect(terminated[0]!.info.stopReason).toBe('user requested');
+  });
+
+  it("fires 'terminated' for ghost reconcile (lost)", async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'bpm-lifecycle-'));
+    try {
+      // Seed disk with a running ghost the way persist would.
+      const tasksDir = join(dir, 'tasks');
+      mkdirSync(tasksDir, { recursive: true });
+      const ghost = {
+        task_id: 'bash-deadbeef',
+        command: 'sleep 9999',
+        description: 'ghost task',
+        pid: 99999,
+        started_at: Date.now() - 60_000,
+        ended_at: null,
+        exit_code: null,
+        status: 'running',
+        approval_reason: undefined,
+        timed_out: undefined,
+        stop_reason: undefined,
+      };
+      writeFileSync(join(tasksDir, 'bash-deadbeef.json'), JSON.stringify(ghost));
+
+      const { records, callback } = makeRecorder();
+      manager.attachSessionDir(dir);
+      await manager.loadFromDisk();
+      manager.onLifecycle(callback);
+
+      const result = await manager.reconcile();
+
+      expect(result.lost).toEqual(['bash-deadbeef']);
+      const terminated = records.filter((r) => r.event === 'terminated');
+      expect(terminated.length).toBe(1);
+      expect(terminated[0]!.info.status).toBe('lost');
+      expect(terminated[0]!.info.taskId).toBe('bash-deadbeef');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('swallows subscriber errors so main flow is unaffected', () => {
+    manager.onLifecycle(() => {
+      throw new Error('boom');
+    });
+    expect(() => manager.register(pendingProcess(), 'sleep', 'x')).not.toThrow();
+  });
+});
diff --git a/packages/agent-core/test/tools/background/manager.test.ts b/packages/agent-core/test/tools/background/manager.test.ts
new file mode 100644
index 000000000..b7fb74a2f
--- /dev/null
+++ b/packages/agent-core/test/tools/background/manager.test.ts
@@ -0,0 +1,758 @@
+/**
+ * Covers: BackgroundProcessManager.
+ *
+ * Uses KaosProcess fakes — the manager accepts KaosProcess directly,
+ * with no ChildProcess dependency.
+ */
+
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import type { Writable } from 'node:stream';
+
+import type { KaosProcess } from '@moonshot-ai/kaos';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BackgroundProcessManager } from '../../../src/tools/background/manager';
+
+/**
+ * Creates a KaosProcess that completes immediately with the given exit code.
+ * stdout emits `stdoutText` if provided.
+ */
+function immediateProcess(exitCode: number, stdoutText = ''): KaosProcess {
+  return {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from(stdoutText ? [stdoutText] : []),
+    stderr: Readable.from([]),
+    pid: 10000 + exitCode,
+    exitCode,
+    wait: vi.fn().mockResolvedValue(exitCode) as KaosProcess['wait'],
+    // oxlint-disable-next-line unicorn/no-useless-undefined
+    kill: vi.fn().mockResolvedValue(undefined) as KaosProcess['kill'],
+  };
+}
+
+/**
+ * Creates a KaosProcess that stays running until `kill()` is called.
+ * Calling `kill()` resolves `wait()` with `exitOnKill`.
+ */
+function pendingProcess(exitOnKill = 143): {
+  proc: KaosProcess;
+  killSpy: ReturnType<typeof vi.fn>;
+} {
+  let resolveWait: (n: number) => void = () => {
+    /* replaced below */
+  };
+  const waitPromise = new Promise<number>((res) => {
+    resolveWait = res;
+  });
+  let currentExitCode: number | null = null;
+  const killSpy = vi.fn(async () => {
+    if (currentExitCode === null) {
+      currentExitCode = exitOnKill;
+      resolveWait(exitOnKill);
+    }
+  });
+  const proc: KaosProcess = {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 54321,
+    get exitCode(): number | null {
+      return currentExitCode;
+    },
+    wait: () => waitPromise,
+    kill: killSpy as unknown as KaosProcess['kill'],
+  };
+  return { proc, killSpy };
+}
+
+function manuallyResolvedProcess(): {
+  proc: KaosProcess;
+  killSpy: ReturnType<typeof vi.fn>;
+  resolve: (exitCode: number) => void;
+} {
+  let resolveWait: (n: number) => void = () => {
+    /* replaced below */
+  };
+  const waitPromise = new Promise<number>((res) => {
+    resolveWait = res;
+  });
+  let currentExitCode: number | null = null;
+  const killSpy = vi.fn().mockResolvedValue(undefined);
+  const proc: KaosProcess = {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 54324,
+    get exitCode(): number | null {
+      return currentExitCode;
+    },
+    wait: () => waitPromise,
+    kill: killSpy as unknown as KaosProcess['kill'],
+  };
+  return {
+    proc,
+    killSpy,
+    resolve: (exitCode) => {
+      if (currentExitCode !== null) return;
+      currentExitCode = exitCode;
+      resolveWait(exitCode);
+    },
+  };
+}
+
+function waiterCount(manager: BackgroundProcessManager, taskId: string): number {
+  const processes = (
+    manager as unknown as {
+      processes: Map<string, { waiters: Array<() => void> }>;
+    }
+  ).processes;
+  return processes.get(taskId)?.waiters.length ?? 0;
+}
+
+function processExitingAfterSigkill(
+  exitOnKill = 137,
+  delayMs = 25,
+): {
+  proc: KaosProcess;
+  killSpy: ReturnType<typeof vi.fn>;
+} {
+  let resolveWait: (n: number) => void = () => {
+    /* replaced below */
+  };
+  const waitPromise = new Promise<number>((res) => {
+    resolveWait = res;
+  });
+  let currentExitCode: number | null = null;
+  const killSpy = vi.fn(async (signal?: NodeJS.Signals) => {
+    if (signal !== 'SIGKILL' || currentExitCode !== null) return;
+    setTimeout(() => {
+      currentExitCode = exitOnKill;
+      resolveWait(exitOnKill);
+    }, delayMs);
+  });
+  const proc: KaosProcess = {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 54323,
+    get exitCode(): number | null {
+      return currentExitCode;
+    },
+    wait: () => waitPromise,
+    kill: killSpy as unknown as KaosProcess['kill'],
+  };
+  return { proc, killSpy };
+}
+
+function processWithVisibleExitCodeBeforeWait(exitCode = 143): {
+  proc: KaosProcess;
+  markExited: () => void;
+} {
+  let currentExitCode: number | null = null;
+  const proc: KaosProcess = {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 54322,
+    get exitCode(): number | null {
+      return currentExitCode;
+    },
+    wait: () => new Promise<number>(() => {}),
+    // oxlint-disable-next-line unicorn/no-useless-undefined
+    kill: vi.fn().mockResolvedValue(undefined) as KaosProcess['kill'],
+  };
+  return {
+    proc,
+    markExited: () => {
+      currentExitCode = exitCode;
+    },
+  };
+}
+
+describe('BackgroundProcessManager', () => {
+  const manager = new BackgroundProcessManager();
+
+  afterEach(() => {
+    manager._reset();
+  });
+
+  it('register returns a task ID and tracks the process', () => {
+    const proc = immediateProcess(0);
+    const taskId = manager.register(proc, 'echo hello', 'test echo');
+    // Id format is `{bash|agent}-{8 base36}`.
+    expect(taskId).toMatch(/^bash-[0-9a-z]{8}$/);
+    const info = manager.getTask(taskId);
+    expect(info).toBeDefined();
+    expect(info!.command).toBe('echo hello');
+    expect(info!.description).toBe('test echo');
+    expect(info!.pid).toBe(proc.pid);
+  });
+
+  it('records failed runtime when proc.wait() rejects', async () => {
+    // Simulate a Kaos launch that resolves into a KaosProcess whose
+    // subsequent wait() rejects (e.g. shell fork failure mid-exec).
+    const proc: KaosProcess = {
+      stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+      stdout: Readable.from([]),
+      stderr: Readable.from([]),
+      pid: 99999,
+      exitCode: null,
+      wait: vi.fn().mockRejectedValue(new Error('launch failed')) as KaosProcess['wait'],
+      // oxlint-disable-next-line unicorn/no-useless-undefined
+      kill: vi.fn().mockResolvedValue(undefined) as KaosProcess['kill'],
+    };
+    const taskId = manager.register(proc, '/bogus/cmd', 'broken launch');
+
+    // Let the wait() rejection propagate through the .finally block.
+    await new Promise((r) => {
+      setTimeout(r, 20);
+    });
+
+    const info = manager.getTask(taskId);
+    expect(info!.status).toBe('failed');
+    expect(info!.endedAt).not.toBeNull();
+  });
+
+  it('registerAgentTask registers as running with agent- id prefix', () => {
+    // Promise that never resolves — we only inspect the initial register
+    // snapshot here.
+    const taskId = manager.registerAgentTask(new Promise(() => {}), 'agent task');
+    expect(taskId).toMatch(/^agent-[0-9a-z]{8}$/);
+    const info = manager.getTask(taskId);
+    expect(info).toBeDefined();
+    expect(info!.status).toBe('running');
+    // Agent tasks use pid=0 (dummy KaosProcess).
+    expect(info!.pid).toBe(0);
+    // Spec marker: command includes the `[agent]` tag so LLM renderers
+    // can distinguish bash vs agent entries when scrolling tasks.
+    expect(info!.command).toContain('[agent]');
+  });
+
+  it('getTask on an unknown id does not touch disk or create state', () => {
+    // Live + ghost maps stay untouched; no partial creation.
+    const before = manager.list(false).length;
+    expect(manager.getTask('bash-deadbeef')).toBeUndefined();
+    const after = manager.list(false).length;
+    expect(after).toBe(before);
+  });
+
+  it('list returns active tasks by default', () => {
+    const { proc: proc1 } = pendingProcess();
+    const { proc: proc2 } = pendingProcess();
+    manager.register(proc1, 'sleep 60', 'task 1');
+    manager.register(proc2, 'sleep 60', 'task 2');
+    const active = manager.list(true);
+    expect(active.length).toBe(2);
+  });
+
+  it('rejects new bash tasks when maxRunningTasks is reached', () => {
+    const limited = new BackgroundProcessManager({ maxRunningTasks: 1 });
+    const { proc: first } = pendingProcess();
+    const { proc: second } = pendingProcess();
+
+    limited.register(first, 'sleep 60', 'first task');
+
+    expect(() => {
+      limited.register(second, 'sleep 60', 'second task');
+    }).toThrow('Too many background tasks are already running.');
+  });
+
+  it('rejects new agent tasks when maxRunningTasks is reached', () => {
+    const limited = new BackgroundProcessManager({ maxRunningTasks: 1 });
+
+    limited.registerAgentTask(new Promise(() => {}), 'first agent');
+
+    expect(() => {
+      limited.registerAgentTask(new Promise(() => {}), 'second agent');
+    }).toThrow('Too many background tasks are already running.');
+  });
+
+  it('getOutput returns captured stdout', async () => {
+    const proc = immediateProcess(0, 'captured output\n');
+    const taskId = manager.register(proc, 'echo captured output', 'capture test');
+
+    // Allow the wait() promise and stream data events to settle.
+    await new Promise((r) => {
+      setTimeout(r, 50);
+    });
+
+    const output = manager.getOutput(taskId);
+    expect(output).toContain('captured output');
+  });
+
+  it('task status transitions to completed on exit code 0', async () => {
+    const proc = immediateProcess(0, 'done');
+    const taskId = manager.register(proc, 'echo done', 'completion test');
+
+    // Allow the wait() promise to settle.
+    await new Promise((r) => {
+      setTimeout(r, 20);
+    });
+
+    const info = manager.getTask(taskId);
+    expect(info!.status).toBe('completed');
+    expect(info!.exitCode).toBe(0);
+  });
+
+  it('task status transitions to failed on non-zero exit', async () => {
+    const proc = immediateProcess(42);
+    const taskId = manager.register(proc, 'exit 42', 'fail test');
+
+    await new Promise((r) => {
+      setTimeout(r, 20);
+    });
+
+    const info = manager.getTask(taskId);
+    expect(info!.status).toBe('failed');
+    expect(info!.exitCode).toBe(42);
+  });
+
+  it('does not finalize task status from a visible process exit code before wait settles', () => {
+    const { proc, markExited } = processWithVisibleExitCodeBeforeWait(143);
+    const taskId = manager.register(proc, 'sleep 60', 'external kill test');
+
+    markExited();
+
+    const info = manager.getTask(taskId);
+    expect(info!.status).toBe('running');
+    expect(info!.exitCode).toBeNull();
+    expect(info!.endedAt).toBeNull();
+  });
+
+  it('does not resolve wait from a visible process exit code before wait settles', async () => {
+    const { proc, markExited } = processWithVisibleExitCodeBeforeWait(143);
+    const taskId = manager.register(proc, 'sleep 60', 'external kill wait test');
+
+    markExited();
+
+    const info = await manager.wait(taskId, 1);
+    expect(info!.status).toBe('running');
+    expect(info!.exitCode).toBeNull();
+  });
+
+  it('stop kills a running task via KaosProcess.kill()', async () => {
+    const { proc, killSpy } = pendingProcess(143);
+    const taskId = manager.register(proc, 'sleep 60', 'kill test');
+
+    const result = await manager.stop(taskId);
+    expect(result).toBeDefined();
+    expect(result!.status).toBe('killed');
+    expect(killSpy).toHaveBeenCalledWith('SIGTERM');
+  });
+
+  it('stop normalizes a blank reason instead of recording an empty stopReason', async () => {
+    const { proc, resolve } = manuallyResolvedProcess();
+    const taskId = manager.register(proc, 'sleep 60', 'blank reason test');
+
+    const stopPromise = manager.stop(taskId, '   ');
+    resolve(0);
+    const result = await stopPromise;
+
+    // A whitespace-only reason must not be persisted as a blank stopReason.
+    // Public callers (SDK/RPC) reach manager.stop() directly, bypassing the
+    // TaskStop tool's own normalization, so the boundary must guard it.
+    expect(result!.stopReason).toBeUndefined();
+  });
+
+  it('stop keeps graceful process shutdown classified as killed', async () => {
+    const { proc, killSpy, resolve } = manuallyResolvedProcess();
+    const taskId = manager.register(proc, 'sleep 60', 'process race test');
+
+    const stopPromise = manager.stop(taskId, 'user requested');
+    resolve(0);
+    const result = await stopPromise;
+
+    expect(result!.status).toBe('killed');
+    expect(result!.stopReason).toBe('user requested');
+    expect(killSpy).toHaveBeenCalledWith('SIGTERM');
+    expect(killSpy).not.toHaveBeenCalledWith('SIGKILL');
+  });
+
+  it('persists graceful process shutdown as killed when stop requested', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-stop-race-'));
+    try {
+      const writer = new BackgroundProcessManager();
+      writer.attachSessionDir(sessionDir);
+      const { proc, resolve } = manuallyResolvedProcess();
+      const taskId = writer.register(proc, 'sleep 60', 'persisted process race test');
+
+      const stopPromise = writer.stop(taskId, 'user requested');
+      resolve(0);
+      await stopPromise;
+
+      const reader = new BackgroundProcessManager();
+      reader.attachSessionDir(sessionDir);
+      await reader.loadFromDisk();
+
+      const persisted = reader.getTask(taskId);
+      expect(persisted?.status).toBe('killed');
+      expect(persisted?.exitCode).toBe(0);
+      expect(persisted?.stopReason).toBe('user requested');
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('stop preserves agent task completion that settles during the grace window', async () => {
+    let resolveCompletion!: (value: { result: string }) => void;
+    const completion = new Promise<{ result: string }>((resolve) => {
+      resolveCompletion = resolve;
+    });
+    const abort = vi.fn();
+    const taskId = manager.registerAgentTask(completion, 'agent race test', { abort });
+
+    const stopPromise = manager.stop(taskId, 'user requested');
+    resolveCompletion({ result: 'finished naturally' });
+    const result = await stopPromise;
+
+    expect(result!.status).toBe('completed');
+    expect(result!.stopReason).toBeUndefined();
+    expect(manager.getOutput(taskId)).toContain('finished naturally');
+    expect(abort).toHaveBeenCalled();
+  });
+
+  it('stop preserves agent task failure when a non-abort rejection wins', async () => {
+    let rejectCompletion!: (error: Error) => void;
+    const completion = new Promise<{ result: string }>((_resolve, reject) => {
+      rejectCompletion = reject;
+    });
+    const abort = vi.fn();
+    const taskId = manager.registerAgentTask(completion, 'agent failure race test', { abort });
+
+    const stopPromise = manager.stop(taskId, 'user requested');
+    rejectCompletion(new Error('model failed'));
+    const result = await stopPromise;
+
+    expect(result!.status).toBe('failed');
+    expect(result!.stopReason).toBeUndefined();
+    expect(abort).toHaveBeenCalled();
+  });
+
+  it('stop marks agent task killed when abort rejection wins', async () => {
+    let rejectCompletion!: (error: Error) => void;
+    const completion = new Promise<{ result: string }>((_resolve, reject) => {
+      rejectCompletion = reject;
+    });
+    const abortError = new Error('The operation was aborted.');
+    abortError.name = 'AbortError';
+    const abort = vi.fn(() => {
+      rejectCompletion(abortError);
+    });
+    const taskId = manager.registerAgentTask(completion, 'agent abort test', { abort });
+
+    const result = await manager.stop(taskId, 'user requested');
+
+    expect(result!.status).toBe('killed');
+    expect(result!.stopReason).toBe('user requested');
+    expect(abort).toHaveBeenCalled();
+  });
+
+  it('stop finalizes a never-settling agent task after the grace window', async () => {
+    vi.useFakeTimers();
+    try {
+      const local = new BackgroundProcessManager();
+      const abort = vi.fn();
+      const taskId = local.registerAgentTask(new Promise(() => {}), 'hung agent task', { abort });
+      const terminalPromise = local.waitForTerminal(taskId);
+
+      const stopPromise = local.stop(taskId, 'user requested');
+      await Promise.resolve();
+      await vi.advanceTimersByTimeAsync(5_000);
+      const [stopped, terminal] = await Promise.all([stopPromise, terminalPromise]);
+
+      expect(stopped?.status).toBe('killed');
+      expect(stopped?.stopReason).toBe('user requested');
+      expect(terminal?.status).toBe('killed');
+      expect(abort).toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('updates endedAt when a killed task finally exits after SIGKILL', async () => {
+    vi.useFakeTimers();
+    try {
+      const local = new BackgroundProcessManager();
+      const terminated: string[] = [];
+      local.onLifecycle((event, info) => {
+        if (event === 'terminated') terminated.push(info.status);
+      });
+      const { proc, killSpy } = processExitingAfterSigkill(137, 25);
+      const taskId = local.register(proc, 'sleep 60', 'forced kill test');
+
+      const stopPromise = local.stop(taskId);
+      await vi.advanceTimersByTimeAsync(5_000);
+      const stopped = await stopPromise;
+      const stopEndedAt = stopped!.endedAt;
+
+      expect(stopped!.status).toBe('killed');
+      expect(killSpy).toHaveBeenCalledWith('SIGKILL');
+
+      await vi.advanceTimersByTimeAsync(25);
+
+      const info = local.getTask(taskId);
+      expect(info!.exitCode).toBe(137);
+      expect(info!.endedAt).toBeGreaterThan(stopEndedAt!);
+      expect(terminated).toEqual(['killed']);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('wait resolves when task completes', async () => {
+    const proc = immediateProcess(0, 'fast');
+    const taskId = manager.register(proc, 'echo fast', 'wait test');
+
+    const info = await manager.wait(taskId, 5000);
+    expect(info).toBeDefined();
+    expect(info!.status).toBe('completed');
+  });
+
+  it('wait removes its waiter when the timeout branch wins', async () => {
+    const { proc } = pendingProcess();
+    const taskId = manager.register(proc, 'sleep 60', 'timeout cleanup test');
+
+    const info = await manager.wait(taskId, 0);
+
+    expect(info).toBeDefined();
+    expect(info!.status).toBe('running');
+    expect(waiterCount(manager, taskId)).toBe(0);
+  });
+
+  it('getTask returns undefined for unknown ID', () => {
+    expect(manager.getTask('bash-nonexist')).toBeUndefined();
+  });
+
+  it('getOutput returns empty string for unknown ID', () => {
+    expect(manager.getOutput('bash-nonexist')).toBe('');
+  });
+
+  it('stop returns terminal info for already-exited task', async () => {
+    const proc = immediateProcess(0);
+    const taskId = manager.register(proc, 'echo done', 'already done');
+
+    // Let wait() settle first.
+    await new Promise((r) => {
+      setTimeout(r, 20);
+    });
+
+    const result = await manager.stop(taskId);
+    expect(result).toBeDefined();
+    expect(result!.status).toBe('completed');
+  });
+});
+
+// ── py-aligned coverage for bash + agent registration semantics ────────
+
+describe('BackgroundProcessManager — registration semantics', () => {
+  const manager = new BackgroundProcessManager();
+
+  afterEach(() => {
+    manager._reset();
+  });
+
+  // The freshly-registered bash task should be immediately observable
+  // in `starting` (or `running`) with the worker pid wired in. Py
+  // distinguishes `starting` vs `running`; TS collapses to `running`
+  // and exposes that pre-output.
+  it('a newly-registered bash task is immediately visible with a starting/running state and worker pid', () => {
+    const proc = pendingProcess().proc;
+    const taskId = manager.register(proc, 'sleep 1', 'short sleep');
+    expect(taskId.startsWith('bash-')).toBe(true);
+    const info = manager.getTask(taskId);
+    expect(info).toBeDefined();
+    // Py: 'starting' state visible. TS: starting status is collapsed
+    // into 'running' here — the assertion lives at the py level.
+    expect((info!.status as string) === 'starting' || info!.status === 'running').toBe(true);
+    expect(info!.pid).toBe(proc.pid);
+  });
+
+  // Race-safety invariant: if the worker writes a terminal state
+  // (completed) DURING register's startup transition, the registrar
+  // must NOT clobber it back to `starting`/`running`.
+  it('register does not overwrite a worker-written terminal completion', async () => {
+    const proc = immediateProcess(0, 'done\n');
+    const taskId = manager.register(proc, 'echo done', 'instant completion');
+    // Let the immediate-exit `wait()` settle.
+    await new Promise((r) => {
+      setTimeout(r, 20);
+    });
+    const info = manager.getTask(taskId);
+    expect(info!.status).toBe('completed');
+    expect(info!.exitCode).toBe(0);
+  });
+
+  // Worker launch raises → manager re-raises, AND persists a `failed`
+  // runtime record so the orphan never leaks as a zombie `running`.
+  it('records a failed runtime when the worker launch raises', async () => {
+    const proc: KaosProcess = {
+      stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+      stdout: Readable.from([]),
+      stderr: Readable.from([]),
+      pid: 99999,
+      exitCode: null,
+      wait: vi.fn().mockRejectedValue(new Error('launch boom')) as KaosProcess['wait'],
+      // oxlint-disable-next-line unicorn/no-useless-undefined
+      kill: vi.fn().mockResolvedValue(undefined) as KaosProcess['kill'],
+    };
+    const taskId = manager.register(proc, '/bogus', 'broken launch');
+    await new Promise((r) => {
+      setTimeout(r, 20);
+    });
+    const info = manager.getTask(taskId);
+    expect(info!.status).toBe('failed');
+    expect(info!.endedAt).not.toBeNull();
+  });
+
+  // Agent task registration places kind_payload-style info on the task
+  // info (agent_id / subagent_type carried through), status visible.
+  it('agent task registration exposes agent metadata on the task info', () => {
+    const taskId = manager.registerAgentTask(new Promise(() => {}), 'investigate bug');
+    expect(taskId.startsWith('agent-')).toBe(true);
+    const info = manager.getTask(taskId);
+    expect(info).toBeDefined();
+    // Py: `kind_payload.agent_id / subagent_type`. TS exposes neither
+    // today — assertion lives at the py spec level.
+    const extended = info as unknown as {
+      readonly agentId?: string;
+      readonly subagentType?: string;
+      readonly kindPayload?: { agent_id?: string; subagent_type?: string };
+    };
+    const agentId = extended.agentId ?? extended.kindPayload?.agent_id;
+    const subagentType = extended.subagentType ?? extended.kindPayload?.subagent_type;
+    expect(agentId).toBeDefined();
+    expect(subagentType).toBeDefined();
+  });
+
+  // Lookup for an unknown task id must return undefined AND must NOT
+  // create any task directory on disk.
+  it('getTask on an unknown id never creates on-disk state', async () => {
+    const sessionDir = await import('node:fs/promises').then((m) =>
+      m.mkdtemp(join(tmpdir(), 'kimi-bg-mgr-missing-')),
+    );
+    try {
+      const m2 = new BackgroundProcessManager();
+      m2.attachSessionDir(sessionDir);
+      expect(m2.getTask('bash-bogusss0')).toBeUndefined();
+      const { readdir } = await import('node:fs/promises');
+      // The tasks/ dir may not exist at all — the lookup must not have
+      // touched it.
+      const top = await readdir(sessionDir);
+      expect(top.includes('tasks')).toBe(false);
+    } finally {
+      const { rm } = await import('node:fs/promises');
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  // Terminal-notification dedupe behavior: a subscriber that maintains
+  // its own seen-set should observe each task exactly once. Python
+  // expressed this via a `publish_terminal_notifications(limit=N)`
+  // entry point that skipped tasks whose dedupe_key was already
+  // recorded; TS pushes the dedupe responsibility to the consumer (the
+  // `BackgroundManager` subclass in `agent/background/index.ts` uses
+  // `scheduledNotificationKeys` for the same effect). The behavior we
+  // care about is "duplicate terminal events are filterable by the
+  // consumer"; the entry-point method itself is not part of the TS BPM
+  // surface.
+  it('terminal-notification dedupe via onTerminal subscriber yields each task once', async () => {
+    const seen = new Set<string>();
+    const published: string[] = [];
+    manager.onTerminal((info) => {
+      if (seen.has(info.taskId)) return;
+      seen.add(info.taskId);
+      published.push(info.taskId);
+    });
+
+    const taskId = manager.register(immediateProcess(0), 'echo a', 'a');
+    await new Promise((r) => {
+      setTimeout(r, 20);
+    });
+    // A second subscriber observing the same terminal event must not
+    // cause the first subscriber's published list to grow.
+    manager.onTerminal(() => {
+      /* no-op */
+    });
+    expect(published).toEqual([taskId]);
+  });
+
+  // E2E: launch a real child process and wait for it to land in
+  // `completed` with the output captured.
+  it('launches a real worker and waits to completion', async () => {
+    const { spawn } = await import('node:child_process');
+    const child = spawn(
+      process.execPath,
+      ['-e', "process.stdout.write('bg-ok\\n')"],
+      { stdio: 'pipe' },
+    );
+    const proc: KaosProcess = {
+      stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+      stdout: child.stdout,
+      stderr: child.stderr,
+      pid: child.pid ?? 0,
+      get exitCode(): number | null {
+        return child.exitCode;
+      },
+      wait: () =>
+        new Promise<number>((resolve) => {
+          child.on('exit', (code) => {
+            resolve(code ?? 0);
+          });
+        }),
+      kill: vi.fn(async (sig?: NodeJS.Signals) => {
+        child.kill(sig ?? 'SIGTERM');
+      }) as unknown as KaosProcess['kill'],
+    };
+    const taskId = manager.register(proc, 'node -e <stdout bg-ok>', 'real worker smoke');
+    const info = await manager.wait(taskId, 10_000);
+    expect(info!.status).toBe('completed');
+    expect(info!.exitCode).toBe(0);
+    expect(manager.getOutput(taskId)).toContain('bg-ok');
+  }, 15_000);
+
+  // Calling stop(taskId) on a running bg agent transitions runtime to
+  // `killed` with stopReason carried from the caller; failure_reason
+  // not overwritten by the late agent_runner CancelledError handler.
+  it('stop on a running agent transitions to killed with caller-supplied reason', async () => {
+    // Wire abort → reject completion so stop() doesn't have to ride
+    // the 5s SIGTERM grace period. The rejection must carry
+    // `name: 'AbortError'` so the lifecycle catch handler can
+    // distinguish it from an unrelated model failure that happens to
+    // race against the stop (the "non-abort rejection wins" case is
+    // covered separately and must remain `failed`).
+    let rejectCompletion!: (err: unknown) => void;
+    const completion = new Promise<{ result: string }>((_res, rej) => {
+      rejectCompletion = rej;
+    });
+    const taskId = manager.registerAgentTask(completion, 'killable', {
+      abort: () => {
+        const abortError = new Error('cancelled');
+        abortError.name = 'AbortError';
+        rejectCompletion(abortError);
+      },
+    });
+    const stopped = await manager.stop(taskId, 'test kill');
+    expect(stopped?.status).toBe('killed');
+    expect(stopped?.stopReason).toBe('test kill');
+  });
+
+  // kill() on an already-completed task is a no-op: returns the current
+  // view unchanged; failure_reason stays null; subagent record stays
+  // `idle` (the completion side already cleaned up).
+  it('stop on an already-completed task is a no-op', async () => {
+    const proc = immediateProcess(0, 'done');
+    const taskId = manager.register(proc, 'echo done', 'quick');
+    await new Promise((r) => {
+      setTimeout(r, 20);
+    });
+    expect(manager.getTask(taskId)?.status).toBe('completed');
+
+    const after = await manager.stop(taskId, 'too late');
+    expect(after?.status).toBe('completed');
+    // No stopReason should be recorded on a noop stop.
+    expect(after?.stopReason).toBeUndefined();
+  });
+});
diff --git a/packages/agent-core/test/tools/background/output-access.test.ts b/packages/agent-core/test/tools/background/output-access.test.ts
new file mode 100644
index 000000000..1e55ef6d9
--- /dev/null
+++ b/packages/agent-core/test/tools/background/output-access.test.ts
@@ -0,0 +1,141 @@
+/**
+ * BackgroundProcessManager — output retrieval surface.
+ *
+ * Covers the two methods consumed by the `/tasks` UI:
+ *   - `readOutput(taskId, tail?)` reads the persisted
+ *     `<sessionDir>/tasks/<id>/output.log` first so callers are not
+ *     limited by the in-memory ring buffer.
+ *   - `getOutputPath(taskId)` returns the absolute path when the
+ *     persisted output log exists so callers can hand it to a pager.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import type { Writable } from 'node:stream';
+
+import type { KaosProcess } from '@moonshot-ai/kaos';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { BackgroundProcessManager } from '../../../src/tools/background/manager';
+import { appendTaskOutput } from '../../../src/tools/background/persist';
+
+function immediateProcess(exitCode: number, stdoutText = ''): KaosProcess {
+  return {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from(stdoutText ? [stdoutText] : []),
+    stderr: Readable.from([]),
+    pid: 50000 + exitCode,
+    exitCode,
+    wait: vi.fn().mockResolvedValue(exitCode) as KaosProcess['wait'],
+    kill: vi.fn().mockResolvedValue(undefined) as KaosProcess['kill'],
+  };
+}
+
+async function waitForLiveOutput(
+  manager: BackgroundProcessManager,
+  taskId: string,
+  expected: string,
+): Promise<void> {
+  for (let i = 0; i < 20; i++) {
+    if (manager.getOutput(taskId).includes(expected)) return;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  throw new Error(`Timed out waiting for live output: ${expected}`);
+}
+
+describe('BackgroundProcessManager — readOutput / getOutputPath', () => {
+  let sessionDir: string;
+  let manager: BackgroundProcessManager;
+
+  beforeEach(() => {
+    sessionDir = mkdtempSync(join(tmpdir(), 'bpm-output-'));
+    manager = new BackgroundProcessManager();
+    manager.attachSessionDir(sessionDir);
+  });
+
+  afterEach(() => {
+    manager._reset();
+    rmSync(sessionDir, { recursive: true, force: true });
+  });
+
+  it('getOutputPath returns <sessionDir>/tasks/<id>/output.log when persisted output exists', async () => {
+    const taskId = manager.register(immediateProcess(0, 'hello\n'), 'echo', 'demo');
+    await waitForLiveOutput(manager, taskId, 'hello');
+    await manager.flushOutput(taskId);
+
+    const path = manager.getOutputPath(taskId);
+    expect(path).toBeDefined();
+    expect(path).toContain(sessionDir);
+    expect(path).toContain(taskId);
+    expect(path!.endsWith('output.log')).toBe(true);
+  });
+
+  it('getOutputPath returns undefined when no persisted log file exists', async () => {
+    const taskId = manager.register(immediateProcess(0), 'sleep 1', 'silent task');
+    await manager.wait(taskId);
+    await manager.flushOutput(taskId);
+
+    expect(manager.getOutputPath(taskId)).toBeUndefined();
+  });
+
+  it('getOutputPath returns undefined for unknown task ids', () => {
+    expect(manager.getOutputPath('bash-deadbeef')).toBeUndefined();
+  });
+
+  it('readOutput returns live ring-buffer content while task is in memory', async () => {
+    const taskId = manager.register(immediateProcess(0, 'live content\n'), 'echo', 'demo');
+    await new Promise((r) => setTimeout(r, 30));
+    const out = await manager.readOutput(taskId);
+    expect(out).toContain('live content');
+  });
+
+  it('readOutput prefers disk over the live ring buffer when persisted output exists', async () => {
+    const taskId = manager.register(immediateProcess(0, 'ring-only\n'), 'echo', 'demo');
+    await waitForLiveOutput(manager, taskId, 'ring-only');
+    await appendTaskOutput(sessionDir, taskId, 'disk-only\n');
+
+    const out = await manager.readOutput(taskId);
+
+    expect(out).toContain('disk-only');
+  });
+
+  it('readOutput falls back to disk for ghost (reconciled lost) tasks', async () => {
+    // Stage 1: live manager appends output to disk.
+    // Wait deterministically: `manager.wait` resolves only after
+    // `persistWriteQueue` drains (so `task.json` is on disk), and
+    // `flushOutput` drains `outputWriteQueue` (so `output.log` is too).
+    // Sleeping 30ms here was flaky on slow CI disks — `task.json` might
+    // still be in flight when the fresh manager scans the session dir,
+    // and a missing ghost makes readOutput return ''.
+    const taskId = manager.register(immediateProcess(0, 'persisted line\n'), 'echo', 'demo');
+    await manager.wait(taskId);
+    await manager.flushOutput(taskId);
+    expect((await manager.readOutput(taskId)).length).toBeGreaterThan(0);
+
+    // Stage 2: simulate a fresh restart — new manager, same sessionDir.
+    const fresh = new BackgroundProcessManager();
+    fresh.attachSessionDir(sessionDir);
+    await fresh.loadFromDisk();
+    await fresh.reconcile();
+
+    // The reloaded task is a ghost (terminal); the in-memory ring buffer
+    // is empty but readOutput should still find the disk log.
+    const recovered = await fresh.readOutput(taskId);
+    expect(recovered).toContain('persisted line');
+    fresh._reset();
+  });
+
+  it('readOutput respects tail length', async () => {
+    const taskId = manager.register(
+      immediateProcess(0, 'aaaaa-bbbbb-ccccc-ddddd'),
+      'echo',
+      'demo',
+    );
+    await new Promise((r) => setTimeout(r, 30));
+    const tail = await manager.readOutput(taskId, 5);
+    expect(tail.length).toBeLessThanOrEqual(5);
+    expect(tail).toBe('ddddd');
+  });
+});
diff --git a/packages/agent-core/test/tools/background/persist.test.ts b/packages/agent-core/test/tools/background/persist.test.ts
new file mode 100644
index 000000000..cc33fa63a
--- /dev/null
+++ b/packages/agent-core/test/tools/background/persist.test.ts
@@ -0,0 +1,276 @@
+/**
+ * Background task persistence tests.
+ */
+
+import { mkdir, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  appendTaskOutput,
+  listTasks,
+  readTask,
+  readTaskOutputBytes,
+  removeTask,
+  taskOutputSizeBytes,
+  writeTask,
+  type PersistedTask,
+} from '../../../src/tools/background/persist';
+
+let sessionDir: string;
+
+function sample(overrides: Partial<PersistedTask> = {}): PersistedTask {
+  return {
+    task_id: 'bash-11111111',
+    command: 'npm install',
+    description: 'install deps',
+    pid: 12345,
+    started_at: 1_700_000_000,
+    ended_at: null,
+    exit_code: null,
+    status: 'running',
+    ...overrides,
+  };
+}
+
+beforeEach(async () => {
+  sessionDir = join(
+    tmpdir(),
+    `kimi-bg-persist-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  await mkdir(sessionDir, { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(sessionDir, { recursive: true, force: true });
+});
+
+describe('background/persist', () => {
+  it('round-trips a task via write/read', async () => {
+    await writeTask(sessionDir, sample());
+    const loaded = await readTask(sessionDir, 'bash-11111111');
+    expect(loaded).toEqual(sample());
+  });
+
+  it('returns undefined when task file is missing', async () => {
+    expect(await readTask(sessionDir, 'bash-missing0')).toBeUndefined();
+  });
+
+  it('overwrites on subsequent write', async () => {
+    await writeTask(sessionDir, sample({ status: 'running' }));
+    await writeTask(
+      sessionDir,
+      sample({ status: 'completed', exit_code: 0, ended_at: 1_700_000_100 }),
+    );
+    const t = await readTask(sessionDir, 'bash-11111111');
+    expect(t?.status).toBe('completed');
+    expect(t?.exit_code).toBe(0);
+    expect(t?.ended_at).toBe(1_700_000_100);
+  });
+
+  it('listTasks enumerates all persisted entries', async () => {
+    await writeTask(sessionDir, sample({ task_id: 'bash-11111111' }));
+    await writeTask(sessionDir, sample({ task_id: 'bash-22222222', command: 'pnpm test' }));
+    const all = await listTasks(sessionDir);
+    expect(all).toHaveLength(2);
+    expect(all.map((t) => t.task_id).toSorted()).toEqual(['bash-11111111', 'bash-22222222']);
+  });
+
+  it('listTasks returns empty when tasks dir does not exist', async () => {
+    expect(await listTasks(sessionDir)).toEqual([]);
+  });
+
+  it('listTasks skips corrupt files', async () => {
+    await writeTask(sessionDir, sample());
+    // Corrupt a sibling file
+    const { writeFile } = await import('node:fs/promises');
+    // Needs a *valid-format* id for listTasks to even attempt parsing
+    // (invalid-id files are silently skipped).
+    await writeFile(join(sessionDir, 'tasks', 'bash-baaaaaaa.json'), '{not json', 'utf-8');
+    const all = await listTasks(sessionDir);
+    expect(all).toHaveLength(1);
+    expect(all[0]?.task_id).toBe('bash-11111111');
+  });
+
+  it('removeTask deletes file (idempotent)', async () => {
+    await writeTask(sessionDir, sample());
+    await removeTask(sessionDir, 'bash-11111111');
+    expect(await readTask(sessionDir, 'bash-11111111')).toBeUndefined();
+    // Second remove no-op
+    await expect(removeTask(sessionDir, 'bash-11111111')).resolves.toBeUndefined();
+  });
+
+  it('writeTask creates tasks dir with mode 0700', async () => {
+    await writeTask(sessionDir, sample());
+    const st = await stat(join(sessionDir, 'tasks'));
+    // eslint-disable-next-line no-bitwise
+    expect(st.mode & 0o777).toBe(0o700);
+  });
+
+  it('rejects path-traversal task ids', async () => {
+    await expect(writeTask(sessionDir, sample({ task_id: '../../etc/passwd' }))).rejects.toThrow(
+      /Invalid task id/,
+    );
+    await expect(readTask(sessionDir, '../etc/passwd')).rejects.toThrow(/Invalid task id/);
+    await expect(removeTask(sessionDir, '../etc/passwd')).rejects.toThrow(/Invalid task id/);
+  });
+
+  it('listTasks silently skips non-validating task_id files', async () => {
+    // Seed a valid task alongside a sibling file whose basename does
+    // NOT match `^(bash|agent)-[0-9a-z]{8}$`.
+    await writeTask(sessionDir, sample());
+    const { writeFile } = await import('node:fs/promises');
+    await writeFile(
+      join(sessionDir, 'tasks', 'BAD-ID!!!.json'),
+      JSON.stringify(sample({ task_id: 'BAD-ID!!!' })),
+      'utf-8',
+    );
+    const all = await listTasks(sessionDir);
+    expect(all).toHaveLength(1);
+    expect(all[0]?.task_id).toBe('bash-11111111');
+  });
+
+  it('listTasks skips specs missing required fields', async () => {
+    await writeTask(sessionDir, sample());
+    const { writeFile } = await import('node:fs/promises');
+    // Valid JSON, valid filename, but shape is wrong (missing status / pid).
+    await writeFile(
+      join(sessionDir, 'tasks', 'bash-cccccccc.json'),
+      JSON.stringify({ task_id: 'bash-cccccccc', command: 'x' }),
+      'utf-8',
+    );
+    const all = await listTasks(sessionDir);
+    expect(all).toHaveLength(1);
+    expect(all[0]?.task_id).toBe('bash-11111111');
+  });
+
+  // ── shell_info round-trip ─────────────────────────────────────────
+
+  it('shell_info round-trips through write/read', async () => {
+    const task = sample({
+      task_id: 'bash-abc12345',
+      shell_info: {
+        name: 'bash',
+        path: '/bin/bash',
+        cwd: '/tmp/work',
+      },
+    });
+    await writeTask(sessionDir, task);
+    const loaded = await readTask(sessionDir, 'bash-abc12345');
+    expect(loaded?.shell_info).toEqual({
+      name: 'bash',
+      path: '/bin/bash',
+      cwd: '/tmp/work',
+    });
+  });
+
+  it('stop_reason round-trips through write/read', async () => {
+    await writeTask(
+      sessionDir,
+      sample({
+        task_id: 'bash-stop0000',
+        status: 'killed',
+        stop_reason: 'no longer needed',
+      }),
+    );
+    const loaded = await readTask(sessionDir, 'bash-stop0000');
+    expect(loaded?.stop_reason).toBe('no longer needed');
+  });
+
+  // All read paths for an unknown task must return defaults AND must
+  // NOT create the on-disk task directory as a side effect.
+  it('readTask for an unknown task does not create a directory', async () => {
+    const { readdir } = await import('node:fs/promises');
+    expect(await readTask(sessionDir, 'bash-noexis00')).toBeUndefined();
+    const top = await readdir(sessionDir);
+    expect(top.includes('tasks')).toBe(false);
+  });
+
+  // listTasks must filter directories whose name does not match the
+  // valid task-id format — stray subdirectories must not appear.
+  it('listTasks skips invalid task directories', async () => {
+    await writeTask(sessionDir, sample({ task_id: 'bash-88888888' }));
+    const { mkdir } = await import('node:fs/promises');
+    await mkdir(join(sessionDir, 'tasks', 'b-invalid'), { recursive: true });
+    const all = await listTasks(sessionDir);
+    expect(all.map((t) => t.task_id)).toEqual(['bash-88888888']);
+  });
+
+  // Even if a stray directory has a spec.json file inside, list_views
+  // still skips it when the directory name fails task-id validation.
+  it('listTasks skips a directory whose name fails validation even when it contains a spec file', async () => {
+    await writeTask(sessionDir, sample({ task_id: 'bash-77777777' }));
+    const { mkdir, writeFile } = await import('node:fs/promises');
+    await mkdir(join(sessionDir, 'tasks', 'bad-task!'), { recursive: true });
+    await writeFile(
+      join(sessionDir, 'tasks', 'bad-task!', 'spec.json'),
+      JSON.stringify({}),
+      'utf-8',
+    );
+    const all = await listTasks(sessionDir);
+    expect(all.map((t) => t.task_id)).toEqual(['bash-77777777']);
+  });
+
+  // Corrupt runtime.json content (truncated JSON missing closing brace)
+  // must NOT raise — readTask returns undefined and listTasks silently
+  // skips that entry. Py treats this as "fall back to default runtime".
+  it('readTask on truncated JSON returns undefined (does not throw)', async () => {
+    const { writeFile, mkdir } = await import('node:fs/promises');
+    await mkdir(join(sessionDir, 'tasks'), { recursive: true });
+    await writeFile(
+      join(sessionDir, 'tasks', 'bash-99999998.json'),
+      '{"status":"running"',
+      'utf-8',
+    );
+    const loaded = await readTask(sessionDir, 'bash-99999998');
+    expect(loaded).toBeUndefined();
+  });
+
+  // listTasks skips a task whose spec is unparseable / missing required
+  // fields, while still returning sibling valid tasks.
+  it('listTasks skips a task with a corrupted spec while keeping siblings', async () => {
+    await writeTask(sessionDir, sample({ task_id: 'bash-99999996' }));
+    const { writeFile, mkdir } = await import('node:fs/promises');
+    await mkdir(join(sessionDir, 'tasks'), { recursive: true });
+    await writeFile(
+      join(sessionDir, 'tasks', 'bash-99999997.json'),
+      JSON.stringify({ oops: 1 }),
+      'utf-8',
+    );
+    const all = await listTasks(sessionDir);
+    expect(all.map((t) => t.task_id)).toEqual(['bash-99999996']);
+  });
+
+  // ── byte-paged output read ────────────────────────────────────────
+
+  describe('readTaskOutputBytes / taskOutputSizeBytes', () => {
+    it('taskOutputSizeBytes reports the full byte size of output.log', async () => {
+      await appendTaskOutput(sessionDir, 'bash-size0000', 'abcdefghij'); // 10 bytes
+      expect(await taskOutputSizeBytes(sessionDir, 'bash-size0000')).toBe(10);
+    });
+
+    it('taskOutputSizeBytes returns 0 when output.log is absent', async () => {
+      expect(await taskOutputSizeBytes(sessionDir, 'bash-none0000')).toBe(0);
+    });
+
+    it('readTaskOutputBytes returns the exact byte window for offset + maxBytes', async () => {
+      // 26 single-byte ASCII chars.
+      await appendTaskOutput(sessionDir, 'bash-page0000', 'abcdefghijklmnopqrstuvwxyz');
+
+      // A middle window.
+      expect(await readTaskOutputBytes(sessionDir, 'bash-page0000', 5, 10)).toBe('fghijklmno');
+      // From the start.
+      expect(await readTaskOutputBytes(sessionDir, 'bash-page0000', 0, 3)).toBe('abc');
+      // A window that runs past EOF is clamped to whatever remains.
+      expect(await readTaskOutputBytes(sessionDir, 'bash-page0000', 20, 100)).toBe('uvwxyz');
+      // An offset at/after EOF yields an empty string.
+      expect(await readTaskOutputBytes(sessionDir, 'bash-page0000', 26, 10)).toBe('');
+    });
+
+    it('readTaskOutputBytes returns empty string when output.log is absent', async () => {
+      expect(await readTaskOutputBytes(sessionDir, 'bash-none0001', 0, 100)).toBe('');
+    });
+  });
+});
diff --git a/packages/agent-core/test/tools/background/reconcile.test.ts b/packages/agent-core/test/tools/background/reconcile.test.ts
new file mode 100644
index 000000000..dd24e48f6
--- /dev/null
+++ b/packages/agent-core/test/tools/background/reconcile.test.ts
@@ -0,0 +1,317 @@
+/**
+ * BackgroundProcessManager reconcile + persistence integration tests.
+ */
+
+import { mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { BackgroundProcessManager } from '../../../src/tools/background/manager';
+import { writeTask, listTasks } from '../../../src/tools/background/persist';
+
+let sessionDir: string;
+
+beforeEach(async () => {
+  sessionDir = join(
+    tmpdir(),
+    `kimi-bg-reconcile-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  await mkdir(sessionDir, { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(sessionDir, { recursive: true, force: true });
+});
+
+describe('BackgroundProcessManager — loadFromDisk + reconcile', () => {
+  it('loadFromDisk does nothing when sessionDir not attached', async () => {
+    const mgr = new BackgroundProcessManager();
+    await mgr.loadFromDisk();
+    expect(mgr.list(false)).toEqual([]);
+  });
+
+  it('reconciles a previously-running task as lost', async () => {
+    // Seed disk as if a previous CLI process registered a task.
+    await writeTask(sessionDir, {
+      task_id: 'bash-orphan00',
+      command: 'npm install',
+      description: 'install',
+      pid: 99999,
+      started_at: 1_700_000_000,
+      ended_at: null,
+      exit_code: null,
+      status: 'running',
+    });
+
+    const mgr = new BackgroundProcessManager();
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    const result = await mgr.reconcile();
+
+    expect(result.lost).toEqual(['bash-orphan00']);
+    expect(result.lostInfo).toHaveLength(1);
+    expect(result.lostInfo[0]?.status).toBe('lost');
+    // Persisted state updated
+    const onDisk = await listTasks(sessionDir);
+    expect(onDisk[0]?.status).toBe('lost');
+  });
+
+  it('does not reclassify already-terminal tasks', async () => {
+    await writeTask(sessionDir, {
+      task_id: 'bash-done0000',
+      command: 'echo hi',
+      description: 'echo',
+      pid: 88888,
+      started_at: 1_700_000_000,
+      ended_at: 1_700_000_010,
+      exit_code: 0,
+      status: 'completed',
+    });
+    await writeTask(sessionDir, {
+      task_id: 'bash-running0',
+      command: 'sleep 1000',
+      description: 'sleep',
+      pid: 77777,
+      started_at: 1_700_000_000,
+      ended_at: null,
+      exit_code: null,
+      status: 'running',
+    });
+
+    const mgr = new BackgroundProcessManager();
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    const result = await mgr.reconcile();
+    expect([...result.lost].toSorted()).toEqual(['bash-running0']);
+
+    const all = await listTasks(sessionDir);
+    const byId = new Map(all.map((t) => [t.task_id, t]));
+    expect(byId.get('bash-done0000')?.status).toBe('completed');
+    expect(byId.get('bash-running0')?.status).toBe('lost');
+  });
+
+  it('list(activeOnly=false) includes ghosts; list(true) excludes them', async () => {
+    await writeTask(sessionDir, {
+      task_id: 'bash-lost0000',
+      command: 'x',
+      description: 'd',
+      pid: 1,
+      started_at: 0,
+      ended_at: null,
+      exit_code: null,
+      status: 'running',
+    });
+    const mgr = new BackgroundProcessManager();
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    await mgr.reconcile();
+    expect(mgr.list(true)).toEqual([]); // active-only: no live tasks
+    const all = mgr.list(false);
+    expect(all).toHaveLength(1);
+    expect(all[0]?.status).toBe('lost');
+  });
+
+  it('getTask returns ghost when the live process map has no entry', async () => {
+    await writeTask(sessionDir, {
+      task_id: 'bash-ghost000',
+      command: 'x',
+      description: 'd',
+      pid: 1,
+      started_at: 0,
+      ended_at: null,
+      exit_code: null,
+      status: 'running',
+    });
+    const mgr = new BackgroundProcessManager();
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    await mgr.reconcile();
+    const t = mgr.getTask('bash-ghost000');
+    expect(t?.status).toBe('lost');
+  });
+
+  it('forgetTask drops ghost and disk entry', async () => {
+    await writeTask(sessionDir, {
+      task_id: 'bash-forget00',
+      command: 'x',
+      description: 'd',
+      pid: 1,
+      started_at: 0,
+      ended_at: null,
+      exit_code: null,
+      status: 'running',
+    });
+    const mgr = new BackgroundProcessManager();
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    await mgr.reconcile();
+    await mgr.forgetTask('bash-forget00');
+    expect(mgr.getTask('bash-forget00')).toBeUndefined();
+    expect(await listTasks(sessionDir)).toEqual([]);
+  });
+
+  it('reconcile returns empty when no ghosts loaded', async () => {
+    const mgr = new BackgroundProcessManager();
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    const result = await mgr.reconcile();
+    expect(result.lost).toEqual([]);
+    expect(result.lostInfo).toEqual([]);
+  });
+
+  it('reconcile fires onTerminal for each newly-lost ghost', async () => {
+    await writeTask(sessionDir, {
+      task_id: 'bash-publish0',
+      command: 'sleep 9999',
+      description: 'publish lost',
+      pid: 42,
+      started_at: 1_700_000_000,
+      ended_at: null,
+      exit_code: null,
+      status: 'running',
+    });
+    const mgr = new BackgroundProcessManager();
+    const fired: { taskId: string; status: string }[] = [];
+    mgr.onTerminal((info) => {
+      fired.push({ taskId: info.taskId, status: info.status });
+    });
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    await mgr.reconcile();
+
+    expect(fired).toHaveLength(1);
+    expect(fired[0]?.taskId).toBe('bash-publish0');
+    expect(fired[0]?.status).toBe('lost');
+  });
+
+  it('reconcile treats corrupted runtime (awaiting_approval ghost) as lost', async () => {
+    // awaiting_approval is non-terminal — when the previous process
+    // died mid-approval, the task cannot possibly resume; reconcile
+    // must downgrade it to `lost` just like a running ghost.
+    await writeTask(sessionDir, {
+      task_id: 'bash-corrupt0',
+      command: 'do_approval',
+      description: 'corrupted approval',
+      pid: 7777,
+      started_at: 1_700_000_000,
+      ended_at: null,
+      exit_code: null,
+      status: 'awaiting_approval',
+      approval_reason: 'ghost reason that should be cleared',
+    });
+    const mgr = new BackgroundProcessManager();
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    const result = await mgr.reconcile();
+
+    expect(result.lost).toEqual(['bash-corrupt0']);
+    expect(result.lostInfo[0]?.status).toBe('lost');
+    expect(result.lostInfo[0]?.approvalReason).toBeUndefined();
+  });
+
+  it('reconcile does not republish already-lost ghosts on second pass', async () => {
+    await writeTask(sessionDir, {
+      task_id: 'bash-nodup000',
+      command: 'sleep 9999',
+      description: 'dedupe check',
+      pid: 42,
+      started_at: 1_700_000_000,
+      ended_at: null,
+      exit_code: null,
+      status: 'running',
+    });
+    const mgr = new BackgroundProcessManager();
+    const fired: string[] = [];
+    mgr.onTerminal((info) => {
+      fired.push(info.taskId);
+    });
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    await mgr.reconcile();
+    // Second reconcile should find nothing to downgrade.
+    const again = await mgr.reconcile();
+    expect(again.lost).toEqual([]);
+    expect(fired).toEqual(['bash-nodup000']);
+  });
+
+  // Stale running task with heartbeat older than threshold gets
+  // reclassified as `lost` AND its failure_reason is set to the
+  // canonical "heartbeat expired" string.
+  it('recover marks a stale heartbeat as lost with the expected failure reason', async () => {
+    await writeTask(sessionDir, {
+      task_id: 'bash-stale001',
+      command: 'sleep 10',
+      description: 'stale task',
+      pid: 111,
+      started_at: 1_700_000_000,
+      ended_at: null,
+      exit_code: null,
+      status: 'running',
+    });
+    const mgr = new BackgroundProcessManager();
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    const result = await mgr.reconcile();
+    expect(result.lost).toEqual(['bash-stale001']);
+    const ghost = mgr.getTask('bash-stale001');
+    // Py: failure_reason == "Background worker heartbeat expired".
+    // TS does not carry a failureReason field — gap at the manager
+    // surface. Assert the py contract.
+    expect((ghost as unknown as { failureReason?: string }).failureReason).toBe(
+      'Background worker heartbeat expired',
+    );
+  });
+
+  // Full reconcile integration: stale-running task is downgraded to
+  // lost AND a single `task.lost` notification is published.
+  it('full reconcile downgrades a stale task and publishes exactly one task.lost notification', async () => {
+    await writeTask(sessionDir, {
+      task_id: 'bash-publish1',
+      command: 'sleep 10',
+      description: 'publish lost',
+      pid: 333,
+      started_at: 1_700_000_000,
+      ended_at: null,
+      exit_code: null,
+      status: 'running',
+    });
+    const fired: { taskId: string; status: string }[] = [];
+    const mgr = new BackgroundProcessManager();
+    mgr.onTerminal((info) => {
+      fired.push({ taskId: info.taskId, status: info.status });
+    });
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    await mgr.reconcile();
+    expect(fired).toEqual([{ taskId: 'bash-publish1', status: 'lost' }]);
+  });
+
+  // Idempotency: a second reconcile() pass over the same already-terminal
+  // task does NOT republish its notification (dedupe by task_id).
+  it('idempotent reconcile: a second pass over a terminal task does not republish', async () => {
+    await writeTask(sessionDir, {
+      task_id: 'bash-once0001',
+      command: 'echo done',
+      description: 'one-shot',
+      pid: 42,
+      started_at: 1_700_000_000,
+      ended_at: 1_700_000_010,
+      exit_code: 0,
+      status: 'completed',
+    });
+    const fired: string[] = [];
+    const mgr = new BackgroundProcessManager();
+    mgr.onTerminal((info) => {
+      fired.push(info.taskId);
+    });
+    mgr.attachSessionDir(sessionDir);
+    await mgr.loadFromDisk();
+    const first = await mgr.reconcile();
+    const second = await mgr.reconcile();
+    expect(first.lost).toEqual([]);
+    expect(second.lost).toEqual([]);
+    expect(fired).toEqual([]);
+  });
+});
diff --git a/packages/agent-core/test/tools/background/state-transitions.test.ts b/packages/agent-core/test/tools/background/state-transitions.test.ts
new file mode 100644
index 000000000..6ec71784e
--- /dev/null
+++ b/packages/agent-core/test/tools/background/state-transitions.test.ts
@@ -0,0 +1,190 @@
+/**
+ * `awaiting_approval` state transitions.
+ *
+ * BPM has 6 states:
+ *   running ↔ awaiting_approval → {completed, failed, killed, lost}
+ *
+ * Semantics:
+ *   - mark / clear are no-ops unless the target task exists and is not
+ *     terminal
+ *   - UI reads the BPM state directly (ApprovalRuntime remains the
+ *     policy layer); BPM is the single source of truth for "is this
+ *     task actively running or gated"
+ *   - `stop()` applied to an awaiting_approval task transitions
+ *     straight to `killed` with the approvalReason cleared
+ */
+
+import { Readable } from 'node:stream';
+import type { Writable } from 'node:stream';
+
+import type { KaosProcess } from '@moonshot-ai/kaos';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BackgroundProcessManager } from '../../../src/tools/background/manager';
+
+function pendingProcess(): { proc: KaosProcess; resolve: (code: number) => void } {
+  let resolveWait: (code: number) => void = () => {};
+  const waitPromise = new Promise<number>((res) => {
+    resolveWait = res;
+  });
+  let currentExitCode: number | null = null;
+  const proc: KaosProcess = {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 42_042,
+    get exitCode(): number | null {
+      return currentExitCode;
+    },
+    wait: () => waitPromise,
+    kill: vi.fn(async () => {
+      if (currentExitCode === null) {
+        currentExitCode = 143;
+        resolveWait(143);
+      }
+    }) as unknown as KaosProcess['kill'],
+  };
+  return {
+    proc,
+    resolve: (code) => {
+      if (currentExitCode === null) {
+        currentExitCode = code;
+        resolveWait(code);
+      }
+    },
+  };
+}
+
+describe('BackgroundProcessManager — awaiting_approval state', () => {
+  const manager = new BackgroundProcessManager();
+
+  afterEach(() => {
+    manager._reset();
+  });
+
+  it('markAwaitingApproval flips running → awaiting_approval and stores reason', () => {
+    const { proc } = pendingProcess();
+    const taskId = manager.register(proc, 'sleep 999', 'approval test');
+
+    manager.markAwaitingApproval(taskId, 'Write to /etc/hosts');
+    const info = manager.getTask(taskId);
+    expect(info?.status).toBe('awaiting_approval');
+    expect(info?.approvalReason).toBe('Write to /etc/hosts');
+  });
+
+  it('clearAwaitingApproval flips awaiting_approval → running and drops reason', () => {
+    const { proc } = pendingProcess();
+    const taskId = manager.register(proc, 'x', 'd');
+    manager.markAwaitingApproval(taskId, 'do thing');
+
+    manager.clearAwaitingApproval(taskId);
+    const info = manager.getTask(taskId);
+    expect(info?.status).toBe('running');
+    expect(info?.approvalReason).toBeUndefined();
+  });
+
+  it('markAwaitingApproval is a no-op on terminal tasks', async () => {
+    const { proc, resolve } = pendingProcess();
+    const taskId = manager.register(proc, 'x', 'd');
+    resolve(0);
+    await new Promise((r) => {
+      setTimeout(r, 20);
+    });
+    expect(manager.getTask(taskId)?.status).toBe('completed');
+
+    manager.markAwaitingApproval(taskId, 'too late');
+    // Status and approvalReason unchanged.
+    const info = manager.getTask(taskId);
+    expect(info?.status).toBe('completed');
+    expect(info?.approvalReason).toBeUndefined();
+  });
+
+  it('stop on an awaiting_approval task flips to killed and clears reason', async () => {
+    const { proc } = pendingProcess();
+    const taskId = manager.register(proc, 'x', 'd');
+    manager.markAwaitingApproval(taskId, 'waiting…');
+
+    const stopped = await manager.stop(taskId);
+    expect(stopped?.status).toBe('killed');
+    expect(stopped?.approvalReason).toBeUndefined();
+  });
+
+  it('list(true) includes awaiting_approval (non-terminal is active)', () => {
+    const { proc } = pendingProcess();
+    const taskId = manager.register(proc, 'x', 'd');
+    manager.markAwaitingApproval(taskId, 'waiting…');
+
+    const active = manager.list(true);
+    expect(active).toHaveLength(1);
+    expect(active[0]?.status).toBe('awaiting_approval');
+  });
+
+  it('clearAwaitingApproval on a non-awaiting task is a no-op', () => {
+    const { proc } = pendingProcess();
+    const taskId = manager.register(proc, 'x', 'd');
+    // Task is still `running` — nothing to clear.
+    manager.clearAwaitingApproval(taskId);
+    expect(manager.getTask(taskId)?.status).toBe('running');
+  });
+
+  // _mark_task_running is a no-op if the task is already in a terminal
+  // state. Prevents a late approval-resolve from clobbering `killed`
+  // or `completed`.
+  it('a state transition does not overwrite a terminal status', async () => {
+    const { proc, resolve } = pendingProcess();
+    const taskId = manager.register(proc, 'x', 'd');
+    resolve(0);
+    await new Promise((r) => {
+      setTimeout(r, 20);
+    });
+    expect(manager.getTask(taskId)?.status).toBe('completed');
+
+    // Try to flip to awaiting_approval and back — both must be no-ops.
+    manager.markAwaitingApproval(taskId, 'too late');
+    manager.clearAwaitingApproval(taskId);
+    expect(manager.getTask(taskId)?.status).toBe('completed');
+  });
+
+  // State transitions out of awaiting_approval must clear failure_reason
+  // (which carried the approval prompt). Both transitions back to
+  // running AND straight to completed must clear it.
+  it('leaving awaiting_approval clears the carried approval reason', async () => {
+    const { proc, resolve } = pendingProcess();
+    const taskId = manager.register(proc, 'x', 'd');
+    manager.markAwaitingApproval(taskId, 'pending approval prompt');
+    expect(manager.getTask(taskId)?.approvalReason).toBe('pending approval prompt');
+
+    // Path 1: awaiting → running clears reason.
+    manager.clearAwaitingApproval(taskId);
+    expect(manager.getTask(taskId)?.approvalReason).toBeUndefined();
+
+    // Path 2: awaiting → completed must ALSO clear approval reason.
+    manager.markAwaitingApproval(taskId, 'second prompt');
+    resolve(0);
+    await new Promise((r) => {
+      setTimeout(r, 20);
+    });
+    const finalInfo = manager.getTask(taskId);
+    expect(finalInfo?.status).toBe('completed');
+    expect(finalInfo?.approvalReason).toBeUndefined();
+  });
+
+  // RunCancelled propagating from the background runner marks the task
+  // as `killed` (not `failed`) — Ctrl+C is cancel, not failure. The TS
+  // agent code today maps internal rejections to `failed`; this is the
+  // py contract that diverges at the agent-runner layer.
+  it('RunCancelled in an agent run marks the task as killed (not failed)', async () => {
+    class RunCancelled extends Error {
+      constructor() {
+        super('run cancelled');
+        this.name = 'RunCancelled';
+      }
+    }
+    const taskId = manager.registerAgentTask(
+      Promise.reject(new RunCancelled()),
+      'run cancelled bg',
+    );
+    const info = await manager.waitForTerminal(taskId);
+    expect(info?.status).toBe('killed');
+  });
+});
diff --git a/packages/agent-core/test/tools/background/task-tools.test.ts b/packages/agent-core/test/tools/background/task-tools.test.ts
new file mode 100644
index 000000000..d2d465bc0
--- /dev/null
+++ b/packages/agent-core/test/tools/background/task-tools.test.ts
@@ -0,0 +1,1222 @@
+/**
+ * Covers: TaskListTool, TaskOutputTool, TaskStopTool.
+ *
+ * Uses KaosProcess fakes.
+ */
+
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import type { Writable } from 'node:stream';
+
+import type { KaosProcess } from '@moonshot-ai/kaos';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BackgroundProcessManager } from '../../../src/tools/background/manager';
+import { writeTask } from '../../../src/tools/background/persist';
+import { TaskListTool } from '../../../src/tools/background/task-list';
+import { TaskOutputTool } from '../../../src/tools/background/task-output';
+import { TaskStopTool } from '../../../src/tools/background/task-stop';
+import { toolContentString } from '../fixtures/fake-kaos';
+import { executeTool } from '../fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+async function flushMicrotasks(): Promise<void> {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+function context<Input>(toolCallId: string, args: Input) {
+  return { turnId: '0', toolCallId, args, signal };
+}
+
+function immediateProcess(exitCode: number, stdoutText = ''): KaosProcess {
+  return {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from(stdoutText ? [stdoutText] : []),
+    stderr: Readable.from([]),
+    pid: 10000 + exitCode,
+    exitCode,
+    wait: vi.fn().mockResolvedValue(exitCode) as KaosProcess['wait'],
+    // oxlint-disable-next-line unicorn/no-useless-undefined
+    kill: vi.fn().mockResolvedValue(undefined) as KaosProcess['kill'],
+  };
+}
+
+function pendingProcess(): KaosProcess {
+  let resolveWait: (n: number) => void = () => {};
+  const waitPromise = new Promise<number>((res) => {
+    resolveWait = res;
+  });
+  let currentExitCode: number | null = null;
+  const killSpy = vi.fn(async () => {
+    if (currentExitCode === null) {
+      currentExitCode = 143;
+      resolveWait(143);
+    }
+  });
+  return {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 54321,
+    get exitCode(): number | null {
+      return currentExitCode;
+    },
+    wait: () => waitPromise,
+    kill: killSpy as unknown as KaosProcess['kill'],
+  };
+}
+
+function processExitingAfterTimer(exitCode = 143, delayMs = 5): KaosProcess {
+  let currentExitCode: number | null = null;
+  const waitPromise = new Promise<number>((resolve) => {
+    setTimeout(() => {
+      currentExitCode = exitCode;
+      resolve(exitCode);
+    }, delayMs);
+  });
+  return {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 54322,
+    get exitCode(): number | null {
+      return currentExitCode;
+    },
+    wait: () => waitPromise,
+    // oxlint-disable-next-line unicorn/no-useless-undefined
+    kill: vi.fn().mockResolvedValue(undefined) as KaosProcess['kill'],
+  };
+}
+
+async function waitForPersistedOutput(
+  manager: BackgroundProcessManager,
+  taskId: string,
+  expectedOutput: string,
+) {
+  const tool = new TaskOutputTool(manager);
+  let lastContent = '';
+  for (let i = 0; i < 20; i++) {
+    await manager.loadFromDisk();
+    const result = await executeTool(tool, context('c_persisted', { task_id: taskId }));
+    lastContent = toolContentString(result);
+    if (
+      result.isError === false &&
+      lastContent.includes('status: completed') &&
+      lastContent.includes(expectedOutput)
+    ) {
+      return { result, content: lastContent };
+    }
+    await new Promise((r) => {
+      setTimeout(r, 10);
+    });
+  }
+  throw new Error(`Task ${taskId} did not persist expected output. Last output:\n${lastContent}`);
+}
+
+async function waitForLiveOutput(
+  manager: BackgroundProcessManager,
+  taskId: string,
+  expectedOutput: string,
+): Promise<void> {
+  for (let i = 0; i < 20; i++) {
+    if (manager.getOutput(taskId).includes(expectedOutput)) return;
+    await new Promise((resolve) => {
+      setTimeout(resolve, 5);
+    });
+  }
+  throw new Error(`Task ${taskId} did not capture expected live output: ${expectedOutput}`);
+}
+
+describe('TaskListTool', () => {
+  const manager = new BackgroundProcessManager();
+  const tool = new TaskListTool(manager);
+
+  afterEach(() => {
+    manager._reset();
+  });
+
+  it('has name "TaskList"', () => {
+    expect(tool.name).toBe('TaskList');
+  });
+
+  it('returns "No background tasks found." when empty', async () => {
+    const result = await executeTool(tool, context('c1', { active_only: true }));
+    expect(toolContentString(result)).toContain('No background tasks found');
+  });
+
+  it('lists active tasks', () => {
+    const proc = pendingProcess();
+    manager.register(proc, 'sleep 60', 'test task');
+    // Synchronous check — the task is running immediately after register.
+    const tasks = manager.list(true);
+    expect(tasks.length).toBe(1);
+    expect(tasks[0]!.command).toBe('sleep 60');
+  });
+
+  it('does not sleep when listing a normally running task', async () => {
+    vi.useFakeTimers();
+    try {
+      const proc = pendingProcess();
+      manager.register(proc, 'sleep 60', 'running list latency test');
+
+      let settled = false;
+      const resultPromise = executeTool(tool, context('c_running_list_latency', { active_only: true }));
+      void resultPromise.then(() => {
+        settled = true;
+      });
+
+      await flushMicrotasks();
+
+      expect(settled).toBe(true);
+      const result = await resultPromise;
+      expect(toolContentString(result)).toContain('sleep 60');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('does not list an already-exited process as active', async () => {
+    const proc = processExitingAfterTimer(143, 0);
+    manager.register(proc, 'sleep 60', 'external kill list test');
+    await new Promise((resolve) => {
+      setTimeout(resolve, 0);
+    });
+
+    const result = await executeTool(tool, context('c_just_exited_list', { active_only: true }));
+
+    expect(toolContentString(result)).toContain('No background tasks found');
+  });
+
+  it('includes a task-count header in the output body', async () => {
+    const proc = pendingProcess();
+    manager.register(proc, 'sleep 60', 'header test');
+    const result = await executeTool(tool, context('c_header', { active_only: true }));
+    expect(toolContentString(result)).toMatch(/^active_background_tasks:\s*1/);
+  });
+
+  it('reports a zero task count when no tasks exist', async () => {
+    const result = await executeTool(tool, context('c_header_empty', { active_only: true }));
+    expect(toolContentString(result)).toMatch(/^active_background_tasks:\s*0/);
+  });
+
+  it('labels the header background_tasks (not active) when active_only=false', async () => {
+    const proc = immediateProcess(0);
+    manager.register(proc, 'echo done', 'header label test');
+    await flushMicrotasks();
+    const result = await executeTool(tool, context('c_header_all', { active_only: false }));
+    const content = toolContentString(result);
+    // A terminal task is not "active"; the all-tasks view must use a neutral label.
+    expect(content).toMatch(/^background_tasks:\s*1/);
+    expect(content).not.toContain('active_background_tasks');
+  });
+
+  it('includes exit_code for terminal tasks', async () => {
+    const proc = immediateProcess(7);
+    manager.register(proc, 'exit 7', 'exit code test');
+    await flushMicrotasks();
+    const result = await executeTool(tool, context('c_exit_code', { active_only: false }));
+    const content = toolContentString(result);
+    expect(content).toContain('exit_code: 7');
+  });
+
+  it('includes the stop reason for tasks ended by TaskStop', async () => {
+    const proc = pendingProcess();
+    const taskId = manager.register(proc, 'sleep 60', 'stop reason test');
+    await manager.stop(taskId, 'superseded by newer task');
+    const result = await executeTool(tool, context('c_stop_reason', { active_only: false }));
+    const content = toolContentString(result);
+    expect(content).toContain('reason: superseded by newer task');
+    expect(content).not.toContain('stop_reason:');
+  });
+
+  it('omits exit_code and reason for non-terminal tasks', async () => {
+    const proc = pendingProcess();
+    manager.register(proc, 'sleep 60', 'non-terminal test');
+    const result = await executeTool(tool, context('c_non_terminal', { active_only: true }));
+    const content = toolContentString(result);
+    expect(content).not.toContain('exit_code:');
+    expect(content).not.toContain('reason:');
+  });
+
+  describe('description', () => {
+    it('explains the core purpose of enumerating background tasks', () => {
+      expect(tool.description).toContain('background tasks');
+      expect(tool.description.length).toBeGreaterThan(120);
+    });
+
+    it('documents the limit parameter bounds and default', () => {
+      expect(tool.description).toContain('limit');
+      expect(tool.description).toContain('20');
+      expect(tool.description).toMatch(/1\s*(to|-|–|and)\s*100|between 1 and 100/i);
+    });
+
+    it('warns that active_only=false may include lost tasks from a prior process', () => {
+      expect(tool.description).toMatch(/lost/i);
+    });
+
+    it('includes a Guidelines section', () => {
+      expect(tool.description).toContain('Guidelines:');
+    });
+
+    it('guides re-enumerating tasks after compaction or when task IDs are lost', () => {
+      expect(tool.description).toMatch(/compaction/i);
+      expect(tool.description).toMatch(/re-?enumerate|re-?discover/i);
+    });
+
+    it('recommends keeping the default active_only=true', () => {
+      expect(tool.description).toContain('active_only');
+      expect(tool.description).toContain('true');
+    });
+
+    it('directs locating a task ID here before using TaskOutput for detail', () => {
+      expect(tool.description).toContain('TaskOutput');
+    });
+
+    it('states the tool is read-only and safe in plan mode', () => {
+      expect(tool.description).toMatch(/read-only/i);
+      expect(tool.description).toMatch(/plan mode/i);
+    });
+  });
+});
+
+describe('TaskOutputTool', () => {
+  const manager = new BackgroundProcessManager();
+  const tool = new TaskOutputTool(manager);
+
+  afterEach(() => {
+    manager._reset();
+  });
+
+  it('has name "TaskOutput"', () => {
+    expect(tool.name).toBe('TaskOutput');
+  });
+
+  it('returns error for unknown task', async () => {
+    const result = await executeTool(tool, context('c1', { task_id: 'bash-unknown0' }));
+    expect(result.isError).toBe(true);
+    expect(toolContentString(result)).toContain('Task not found');
+  });
+
+  it('returns output for a completed task', async () => {
+    // TaskOutput reads output exclusively from the on-disk log, so this
+    // test runs with a session directory attached — matching production,
+    // where the manager is always constructed with one. A self-contained
+    // manager + a terminal task keep teardown free of the cleanup race
+    // that non-terminal tasks (still flushing persistence) would cause.
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-output-tool-'));
+    const ownManager = new BackgroundProcessManager();
+    ownManager.attachSessionDir(sessionDir);
+    try {
+      const taskId = ownManager.register(
+        immediateProcess(0, 'STDOUT-PAYLOAD-LINE\n'),
+        'echo demo',
+        'output test',
+      );
+      await expect(ownManager.wait(taskId, 5_000)).resolves.toMatchObject({
+        status: 'completed',
+      });
+
+      const result = await executeTool(new TaskOutputTool(ownManager),
+        context('c2', { task_id: taskId }),
+      );
+      expect(result.isError).toBe(false);
+      const content = toolContentString(result);
+      expect(content).toContain('status: completed');
+      // Assert on a payload marker that does NOT collide with the command
+      // or description, so this genuinely verifies output retrieval rather
+      // than matching an echoed metadata field.
+      expect(content).toContain('[output]\nSTDOUT-PAYLOAD-LINE');
+    } finally {
+      ownManager._reset();
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('returns live output when no persisted log is available', async () => {
+    const taskId = manager.register(
+      immediateProcess(0, 'DETACHED-PAYLOAD-LINE\n'),
+      'echo demo',
+      'detached output test',
+    );
+    await expect(manager.wait(taskId, 5_000)).resolves.toMatchObject({
+      status: 'completed',
+    });
+    await waitForLiveOutput(manager, taskId, 'DETACHED-PAYLOAD-LINE');
+
+    const result = await executeTool(tool, context('c_detached_output', { task_id: taskId }));
+
+    expect(result.isError).toBe(false);
+    const content = toolContentString(result);
+    expect(content).toContain('status: completed');
+    expect(content).toContain('[output]\nDETACHED-PAYLOAD-LINE');
+    expect(content).toContain(
+      `output_size_bytes: ${String(Buffer.byteLength('DETACHED-PAYLOAD-LINE\n'))}`,
+    );
+    expect(content).not.toContain('output_path:');
+  });
+
+  it('reads persisted output for a task loaded after restart', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-output-'));
+    try {
+      const writer = new BackgroundProcessManager();
+      writer.attachSessionDir(sessionDir);
+      const taskId = writer.register(
+        immediateProcess(0, 'persisted output\n'),
+        'echo persisted output',
+        'persist output test',
+      );
+
+      await expect(writer.wait(taskId, 5_000)).resolves.toMatchObject({ status: 'completed' });
+
+      const reader = new BackgroundProcessManager();
+      reader.attachSessionDir(sessionDir);
+      const { result, content } = await waitForPersistedOutput(reader, taskId, 'persisted output');
+
+      expect(result.isError).toBe(false);
+      expect(content).toContain('status: completed');
+      expect(content).toContain('output_path:');
+      expect(content).toContain('persisted output');
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('reports awaiting_approval as not_ready when block=false', async () => {
+    const proc = pendingProcess();
+    const taskId = manager.register(proc, 'sleep 60', 'approval output test');
+    manager.markAwaitingApproval(taskId, 'waiting for root approval');
+
+    const result = await executeTool(tool, context('c_awaiting_output', { task_id: taskId }));
+
+    expect(result.isError).toBe(false);
+    const content = toolContentString(result);
+    expect(content).toContain('retrieval_status: not_ready');
+    expect(content).toContain('status: awaiting_approval');
+  });
+
+  it('settles an already-exited process before reporting non-blocking output', async () => {
+    const proc = processExitingAfterTimer(143, 0);
+    const taskId = manager.register(proc, 'sleep 60', 'external kill output test');
+    await new Promise((resolve) => {
+      setTimeout(resolve, 0);
+    });
+
+    const result = await executeTool(tool, context('c_just_exited_output', { task_id: taskId }));
+
+    expect(result.isError).toBe(false);
+    const content = toolContentString(result);
+    expect(content).toContain('retrieval_status: success');
+    expect(content).toContain('status: failed');
+    expect(content).toContain('exit_code: 143');
+  });
+
+  it('waits on awaiting_approval when block=true and reports timeout if still non-terminal', async () => {
+    const proc = pendingProcess();
+    const taskId = manager.register(proc, 'sleep 60', 'approval blocking output test');
+    manager.markAwaitingApproval(taskId, 'waiting for root approval');
+
+    const result = await executeTool(tool,
+      context('c_awaiting_output_block', { task_id: taskId, block: true, timeout: 0 }),
+    );
+
+    expect(result.isError).toBe(false);
+    const content = toolContentString(result);
+    expect(content).toContain('retrieval_status: timeout');
+    expect(content).toContain('status: awaiting_approval');
+  });
+});
+
+describe('TaskOutputTool — large output truncation + paging protocol', () => {
+  let sessionDir: string | undefined;
+
+  afterEach(async () => {
+    if (sessionDir !== undefined) {
+      await rm(sessionDir, { recursive: true, force: true });
+      sessionDir = undefined;
+    }
+  });
+
+  it('truncates output > 32 KiB to a tail preview and reports paging metadata', async () => {
+    sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-trunc-'));
+    const manager = new BackgroundProcessManager();
+    manager.attachSessionDir(sessionDir);
+    try {
+      // 200 KiB of distinct content: head marker ... tail marker.
+      const head = 'HEAD-MARKER\n';
+      const tail = 'TAIL-MARKER\n';
+      const filler = 'x'.repeat(200 * 1024);
+      const big = head + filler + tail;
+      const taskId = manager.register(immediateProcess(0, big), 'echo big', 'large output test');
+      await expect(manager.wait(taskId, 5_000)).resolves.toMatchObject({ status: 'completed' });
+
+      const tool = new TaskOutputTool(manager);
+      const result = await executeTool(tool, context('c_big', { task_id: taskId }));
+      expect(result.isError).toBe(false);
+      const content = toolContentString(result);
+
+      // Structured paging metadata.
+      expect(content).toContain('output_truncated: true');
+      expect(content).toContain(`output_size_bytes: ${String(Buffer.byteLength(big))}`);
+      expect(content).toMatch(/output_preview_bytes: \d+/);
+      expect(content).toContain('full_output_available: true');
+      expect(content).toContain('full_output_tool: Read');
+      expect(content).toMatch(/full_output_hint:.*Read/);
+
+      // Preview is the TAIL, not the head, and carries the truncation banner.
+      expect(content).toContain('[Truncated. Full output:');
+      expect(content).toContain('TAIL-MARKER');
+      expect(content).not.toContain('HEAD-MARKER');
+    } finally {
+      manager._reset();
+    }
+  });
+
+  it('does not silently drop the head of a > 1 MiB running task', async () => {
+    sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-ring-'));
+    const manager = new BackgroundProcessManager();
+    manager.attachSessionDir(sessionDir);
+    try {
+      // Stream > 1 MiB so the in-memory ring buffer (1 MiB cap) would
+      // otherwise shift() away the earliest chunks.
+      const chunks = [
+        'FIRST-CHUNK\n',
+        'a'.repeat(700 * 1024),
+        'b'.repeat(700 * 1024),
+        'LAST-CHUNK\n',
+      ];
+      const proc: KaosProcess = {
+        stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+        stdout: Readable.from(chunks),
+        stderr: Readable.from([]),
+        pid: 60001,
+        exitCode: 0,
+        wait: vi.fn().mockResolvedValue(0) as KaosProcess['wait'],
+        // oxlint-disable-next-line unicorn/no-useless-undefined
+        kill: vi.fn().mockResolvedValue(undefined) as KaosProcess['kill'],
+      };
+      const totalBytes = chunks.reduce((s, c) => s + Buffer.byteLength(c), 0);
+      const taskId = manager.register(proc, 'echo huge', 'huge running output');
+      await expect(manager.wait(taskId, 5_000)).resolves.toMatchObject({ status: 'completed' });
+
+      const tool = new TaskOutputTool(manager);
+      const result = await executeTool(tool, context('c_huge', { task_id: taskId }));
+      expect(result.isError).toBe(false);
+      const content = toolContentString(result);
+
+      // The reported size is the FULL disk size — nothing was dropped.
+      expect(content).toContain(`output_size_bytes: ${String(totalBytes)}`);
+      expect(content).toContain('output_truncated: true');
+    } finally {
+      manager._reset();
+    }
+  });
+
+  it('exposes paging guidance (Read + output_path) in the tool description', () => {
+    const tool = new TaskOutputTool(new BackgroundProcessManager());
+    const desc = tool.description;
+    // Guideline 6 from the parity source: when the preview is truncated,
+    // page the full log with the `Read` tool and the returned output_path.
+    expect(desc).toContain('Read');
+    expect(desc).toContain('output_path');
+    expect(desc.toLowerCase()).toContain('truncat');
+    // Must not leak the Python tool name.
+    expect(desc).not.toContain('ReadFile');
+  });
+
+  it('does not mark small output (< 32 KiB) as truncated', async () => {
+    sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-small-'));
+    const manager = new BackgroundProcessManager();
+    manager.attachSessionDir(sessionDir);
+    try {
+      const small = 'small output line\n';
+      const taskId = manager.register(immediateProcess(0, small), 'echo small', 'small test');
+      await expect(manager.wait(taskId, 5_000)).resolves.toMatchObject({ status: 'completed' });
+
+      const tool = new TaskOutputTool(manager);
+      const result = await executeTool(tool, context('c_small', { task_id: taskId }));
+      expect(result.isError).toBe(false);
+      const content = toolContentString(result);
+
+      expect(content).toContain('output_truncated: false');
+      expect(content).not.toContain('[Truncated. Full output:');
+      expect(content).toContain('small output line');
+      expect(content).toContain(`output_size_bytes: ${String(Buffer.byteLength(small))}`);
+    } finally {
+      manager._reset();
+    }
+  });
+
+  it('flags truncation when the tail window starts mid-multibyte character', async () => {
+    sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-utf8-'));
+    const manager = new BackgroundProcessManager();
+    manager.attachSessionDir(sessionDir);
+    try {
+      // A 3-byte char at the head, then ASCII filler so the log is exactly
+      // one byte over the 32 KiB preview window. The tail window therefore
+      // starts at byte offset 1 — inside the leading multibyte char — so
+      // its first bytes decode to replacement chars (each 3 bytes in
+      // UTF-8). Counting decoded-string bytes would overshoot the real
+      // window size and mis-report this truncated output as untruncated.
+      const previewWindow = 32 * 1024;
+      const text = '中' + 'a'.repeat(previewWindow - 2);
+      const sizeBytes = Buffer.byteLength(text);
+      expect(sizeBytes).toBe(previewWindow + 1);
+
+      const taskId = manager.register(immediateProcess(0, text), 'echo utf8', 'utf8 boundary test');
+      await expect(manager.wait(taskId, 5_000)).resolves.toMatchObject({ status: 'completed' });
+
+      const tool = new TaskOutputTool(manager);
+      const result = await executeTool(tool, context('c_utf8', { task_id: taskId }));
+      expect(result.isError).toBe(false);
+      const content = toolContentString(result);
+
+      expect(content).toContain(`output_size_bytes: ${String(sizeBytes)}`);
+      expect(content).toContain('output_truncated: true');
+      expect(content).toContain(`output_preview_bytes: ${String(previewWindow)}`);
+      expect(content).toContain('full_output_available: true');
+      expect(content).toContain('[Truncated. Full output:');
+    } finally {
+      manager._reset();
+    }
+  });
+
+  it('keeps preview and metadata consistent from a single log-size snapshot', async () => {
+    sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-grow-'));
+    const manager = new BackgroundProcessManager();
+    manager.attachSessionDir(sessionDir);
+    try {
+      // A 40 KiB ASCII log — larger than the 32 KiB preview window.
+      const big = 'a'.repeat(40 * 1024);
+      const taskId = manager.register(immediateProcess(0, big), 'echo grow', 'growing output');
+      await expect(manager.wait(taskId, 5_000)).resolves.toMatchObject({ status: 'completed' });
+
+      // Simulate the race: the size snapshot driving the metadata is taken
+      // while the log is still smaller (30000 bytes) than its real on-disk
+      // size (40 KiB) — e.g. a running task that grew after flushOutput().
+      // The preview window and the reported metadata must agree regardless.
+      vi.spyOn(manager, 'getOutputSizeBytes').mockResolvedValue(30_000);
+
+      const result = await executeTool(new TaskOutputTool(manager),
+        context('c_grow', { task_id: taskId }),
+      );
+      expect(result.isError).toBe(false);
+      const content = toolContentString(result);
+
+      // The [output] section must contain exactly output_preview_bytes
+      // bytes — never a 32 KiB tail paired with stale, smaller metadata.
+      const previewBytesMatch = content.match(/output_preview_bytes: (\d+)/);
+      expect(previewBytesMatch).not.toBeNull();
+      const marker = '[output]\n';
+      const outputSection = content.slice(content.indexOf(marker) + marker.length);
+      expect(Buffer.byteLength(outputSection)).toBe(Number(previewBytesMatch![1]));
+    } finally {
+      vi.restoreAllMocks();
+      manager._reset();
+    }
+  });
+});
+
+describe('TaskOutputTool — terminal metadata fields', () => {
+  it('exposes timed_out and terminal_reason for an agent task aborted by its deadline', async () => {
+    const manager = new BackgroundProcessManager();
+    try {
+      // An agent task whose completion never resolves, with a 0ms deadline:
+      // the external deadline fires and finalizes the task with timedOut=true.
+      const taskId = manager.registerAgentTask(new Promise<{ result: string }>(() => {}), 'slow agent', {
+        timeoutMs: 1,
+      });
+      await expect(manager.wait(taskId, 5_000)).resolves.toMatchObject({
+        status: 'failed',
+        timedOut: true,
+      });
+
+      const result = await executeTool(
+        new TaskOutputTool(manager),
+        context('c_timed_out', { task_id: taskId }),
+      );
+      expect(result.isError).toBe(false);
+      const content = toolContentString(result);
+      expect(content).toContain('timed_out: true');
+      expect(content).toContain('terminal_reason: timed_out');
+      expect(content).not.toContain('stop_reason:');
+    } finally {
+      manager._reset();
+    }
+  });
+
+  it('exposes stop_reason and terminal_reason for a task stopped via TaskStop', async () => {
+    const manager = new BackgroundProcessManager();
+    try {
+      const proc = pendingProcess();
+      const taskId = manager.register(proc, 'sleep 60', 'stoppable task');
+      await manager.stop(taskId, 'operator cancelled');
+      expect(manager.getTask(taskId)).toMatchObject({
+        status: 'killed',
+        stopReason: 'operator cancelled',
+      });
+
+      const result = await executeTool(
+        new TaskOutputTool(manager),
+        context('c_stopped', { task_id: taskId }),
+      );
+      expect(result.isError).toBe(false);
+      const content = toolContentString(result);
+      expect(content).toContain('stop_reason: operator cancelled');
+      expect(content).toContain('terminal_reason: stopped');
+    } finally {
+      manager._reset();
+    }
+  });
+
+  it('omits timed_out / stop_reason / terminal_reason for a normally completed task', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-meta-'));
+    const manager = new BackgroundProcessManager();
+    manager.attachSessionDir(sessionDir);
+    try {
+      const taskId = manager.register(immediateProcess(0, 'done\n'), 'echo done', 'normal task');
+      await expect(manager.wait(taskId, 5_000)).resolves.toMatchObject({ status: 'completed' });
+
+      const result = await executeTool(
+        new TaskOutputTool(manager),
+        context('c_normal', { task_id: taskId }),
+      );
+      expect(result.isError).toBe(false);
+      const content = toolContentString(result);
+      expect(content).not.toContain('timed_out:');
+      expect(content).not.toContain('stop_reason:');
+      expect(content).not.toContain('terminal_reason:');
+    } finally {
+      manager._reset();
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('TaskOutputTool — full-output guidance', () => {
+  it('does not advertise an output_path when the persisted log file does not exist', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-empty-'));
+    const manager = new BackgroundProcessManager();
+    manager.attachSessionDir(sessionDir);
+    try {
+      const taskId = manager.register(immediateProcess(0), 'sleep 1', 'silent task');
+      await expect(manager.wait(taskId, 5_000)).resolves.toMatchObject({ status: 'completed' });
+
+      const result = await executeTool(
+        new TaskOutputTool(manager),
+        context('c_no_output_file', { task_id: taskId }),
+      );
+      expect(result.isError).toBe(false);
+      const content = toolContentString(result);
+
+      expect(content).not.toContain('output_path:');
+      expect(content).toContain('output_size_bytes: 0');
+      expect(content).toContain('full_output_available: false');
+    } finally {
+      manager._reset();
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('emits full_output_available / full_output_tool even when output is not truncated', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-untrunc-'));
+    const manager = new BackgroundProcessManager();
+    manager.attachSessionDir(sessionDir);
+    try {
+      const small = 'small output line\n';
+      const taskId = manager.register(immediateProcess(0, small), 'echo small', 'small test');
+      await expect(manager.wait(taskId, 5_000)).resolves.toMatchObject({ status: 'completed' });
+
+      const result = await executeTool(
+        new TaskOutputTool(manager),
+        context('c_untrunc', { task_id: taskId }),
+      );
+      expect(result.isError).toBe(false);
+      const content = toolContentString(result);
+
+      expect(content).toContain('output_truncated: false');
+      expect(content).toContain('full_output_available: true');
+      expect(content).toContain('full_output_tool: Read');
+      expect(content).toMatch(/full_output_hint:.*Read/);
+    } finally {
+      manager._reset();
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('TaskStopTool', () => {
+  const manager = new BackgroundProcessManager();
+  const tool = new TaskStopTool(manager);
+
+  afterEach(() => {
+    manager._reset();
+  });
+
+  it('has name "TaskStop"', () => {
+    expect(tool.name).toBe('TaskStop');
+  });
+
+  it('description warns about destructive side effects and usage constraints', () => {
+    const description = tool.description;
+    // Only use when cancellation is genuinely required.
+    expect(description).toContain('TaskOutput');
+    expect(description.toLowerCase()).toContain('cancel');
+    // Destructive risk warning.
+    expect(description.toLowerCase()).toContain('destructive');
+    expect(description.toLowerCase()).toContain('side effect');
+    // Already-finished tasks just return current status.
+    expect(description.toLowerCase()).toContain('already');
+  });
+
+  it('returns error for unknown task', async () => {
+    const result = await executeTool(tool, context('c1', { task_id: 'bash-unknown0' }));
+    expect(result.isError).toBe(true);
+    expect(toolContentString(result)).toContain('Task not found');
+  });
+
+  it('stops a running task', async () => {
+    const proc = pendingProcess();
+    const taskId = manager.register(proc, 'sleep 60', 'stop test');
+    const result = await executeTool(tool,
+      context('c2', { task_id: taskId, reason: 'custom stop reason' }),
+    );
+    expect(result.isError).toBe(false);
+    expect(toolContentString(result)).toContain('killed');
+    expect(toolContentString(result)).toContain('custom stop reason');
+    expect(manager.getTask(taskId)?.stopReason).toBe('custom stop reason');
+  });
+
+  it('stops an awaiting_approval task', async () => {
+    const proc = pendingProcess();
+    const taskId = manager.register(proc, 'sleep 60', 'approval stop test');
+    manager.markAwaitingApproval(taskId, 'waiting for root approval');
+
+    const result = await executeTool(tool, context('c_awaiting_stop', { task_id: taskId }));
+
+    expect(result.isError).toBe(false);
+    expect(toolContentString(result)).toContain('status: killed');
+    expect(manager.getTask(taskId)?.approvalReason).toBeUndefined();
+  });
+
+  it('persists stop reason when attached to a session directory', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-stop-reason-'));
+    try {
+      const writer = new BackgroundProcessManager();
+      writer.attachSessionDir(sessionDir);
+      const taskId = writer.register(pendingProcess(), 'sleep 60', 'persist stop reason test');
+
+      const result = await executeTool(new TaskStopTool(writer),
+        context('c_stop_reason', { task_id: taskId, reason: 'operator cancelled' }),
+      );
+      expect(result.isError).toBe(false);
+
+      const reader = new BackgroundProcessManager();
+      reader.attachSessionDir(sessionDir);
+      await reader.loadFromDisk();
+      expect(reader.getTask(taskId)?.stopReason).toBe('operator cancelled');
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  // The empty-string case is the core of the fix: `args.reason ?? default`
+  // does NOT coalesce `''` (since `'' ?? x === ''`), so the implementation
+  // must trim-and-`||` instead. An explicit `''` case guards that, alongside
+  // a whitespace-only string and an omitted `reason`.
+  it.each([
+    { label: 'an empty-string reason', reason: '' },
+    { label: 'a whitespace-only reason', reason: '   ' },
+    { label: 'an omitted reason', reason: undefined as string | undefined },
+  ])('falls back to default reason given $label', async ({ reason }) => {
+    const proc = pendingProcess();
+    const taskId = manager.register(proc, 'sleep 60', 'empty reason test');
+    const result = await executeTool(tool,
+      context('c_empty_reason', { task_id: taskId, reason }),
+    );
+    expect(result.isError).toBe(false);
+    expect(toolContentString(result)).toContain('reason: Stopped by TaskStop');
+    expect(manager.getTask(taskId)?.stopReason).toBe('Stopped by TaskStop');
+  });
+
+  it('returns info when task is already in terminal state', async () => {
+    const proc = immediateProcess(0);
+    const taskId = manager.register(proc, 'echo done', 'terminal test');
+
+    // Let wait() settle.
+    await new Promise((r) => {
+      setTimeout(r, 20);
+    });
+
+    const result = await executeTool(tool, context('c3', { task_id: taskId }));
+    expect(result.isError).toBe(false);
+    // Terminal-state path uses the same structured multi-line format as the
+    // normal stop path: task_id / status / reason — each on its own line.
+    const lines = toolContentString(result).trim().split('\n');
+    expect(lines).toHaveLength(3);
+    expect(lines[0]).toBe(`task_id: ${taskId}`);
+    expect(lines[1]).toBe('status: completed');
+    // A cleanly exited task has no stopReason, so this exercises the
+    // placeholder fallback used when `stopReason` is undefined.
+    expect(lines[2]).toBe('reason: Task already in terminal state');
+  });
+
+  it('falls back to the placeholder when a terminal task has a blank stored reason', async () => {
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-blank-stored-reason-'));
+    try {
+      // A task persisted by an older build (or a caller that passed `''`)
+      // can carry a blank `stop_reason` on disk; the terminal-state branch
+      // must not surface it as a bare `reason: ` line.
+      await writeTask(sessionDir, {
+        task_id: 'bash-deadbeef',
+        command: 'sleep 60',
+        description: 'legacy blank reason',
+        pid: 999,
+        started_at: 1_700_000_000,
+        ended_at: 1_700_000_001,
+        exit_code: null,
+        status: 'killed',
+        stop_reason: '',
+      });
+      const reader = new BackgroundProcessManager();
+      reader.attachSessionDir(sessionDir);
+      await reader.loadFromDisk();
+
+      const result = await executeTool(
+        new TaskStopTool(reader),
+        context('c_blank_stored', { task_id: 'bash-deadbeef' }),
+      );
+
+      expect(result.isError).toBe(false);
+      const lines = toolContentString(result).trim().split('\n');
+      expect(lines[2]).toBe('reason: Task already in terminal state');
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ── py-aligned envelope contracts ──────────────────────────────────────
+
+describe('TaskOutputTool — py envelope contract', () => {
+  const manager = new BackgroundProcessManager();
+  const tool = new TaskOutputTool(manager);
+
+  afterEach(() => {
+    manager._reset();
+  });
+
+  // Completed task envelope must include: retrieval_status:success +
+  // status:completed + output_path + output_truncated:false +
+  // full_output_tool: Read + full_output_hint.
+  // TS only emits the full_output_tool / hint pair when a persisted log
+  // exists, so the manager must be attached to a session dir.
+  it('completed task returns a rich envelope with output_truncated/full_output_tool/full_output_hint', async () => {
+    const { mkdtemp, rm } = await import('node:fs/promises');
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-env-'));
+    try {
+      const m2 = new BackgroundProcessManager();
+      m2.attachSessionDir(sessionDir);
+      const t = new TaskOutputTool(m2);
+      const proc = immediateProcess(0, 'build line 1\nbuild line 2\n');
+      const taskId = m2.register(proc, 'make build', 'completed envelope');
+      await m2.wait(taskId, 5_000);
+      const result = await executeTool(t, context('c_env', { task_id: taskId, block: true, timeout: 1 }));
+      expect(result.isError).toBe(false);
+      const text = toolContentString(result);
+      expect(text).toContain('retrieval_status: success');
+      expect(text).toContain('status: completed');
+      expect(text).toContain('output_truncated: false');
+      // TS uses `Read` rather than Python's `ReadFile`; test asserts the
+      // TS-native tool name (see decision in PR description).
+      expect(text).toContain('full_output_tool: Read');
+      expect(text).toContain('full_output_hint:');
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  // block omitted defaults to non-blocking → not_ready + a brief
+  // "Task snapshot retrieved." surface.
+  it('omitting block defaults to non-blocking with a "Task snapshot retrieved." brief', async () => {
+    const proc = pendingProcess();
+    const taskId = manager.register(proc, 'sleep 60', 'default block');
+    const result = await executeTool(tool, context('c_default', { task_id: taskId }));
+    expect(result.isError).toBe(false);
+    const text = toolContentString(result);
+    expect(text).toContain('retrieval_status: not_ready');
+    expect(text).toContain('status: running');
+    // Py: result.message == "Task snapshot retrieved."
+    const message = (result as unknown as { message?: string }).message;
+    expect(message).toBe('Task snapshot retrieved.');
+  });
+
+  // block=True + timeout=0 on a still-running task surfaces
+  // retrieval_status:timeout (not_ready is for non-blocking only).
+  it('block=true with timeout=0 on a running task surfaces retrieval_status:timeout', async () => {
+    const proc = pendingProcess();
+    const taskId = manager.register(proc, 'sleep 60', 'blocking timeout');
+    const result = await executeTool(
+      tool,
+      context('c_block_timeout', { task_id: taskId, block: true, timeout: 0 }),
+    );
+    expect(result.isError).toBe(false);
+    const text = toolContentString(result);
+    expect(text).toContain('retrieval_status: timeout');
+    expect(text).toContain('status: running');
+  });
+
+  // Lookup of a non-existent task returns error AND must not create a
+  // ghost entry or any task file on disk.
+  it('lookup of a non-existent task does not pollute the store', async () => {
+    const { mkdtemp, readdir, rm } = await import('node:fs/promises');
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-missing-'));
+    try {
+      const m2 = new BackgroundProcessManager();
+      m2.attachSessionDir(sessionDir);
+      const t = new TaskOutputTool(m2);
+      const r = await executeTool(t, context('c_missing', { task_id: 'bash-noex0000' }));
+      expect(r.isError).toBe(true);
+      expect(toolContentString(r)).toContain('Task not found');
+      const top = await readdir(sessionDir);
+      expect(top.includes('tasks')).toBe(false);
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  // For a task that timed out (failed terminal state with timedOut=true),
+  // the envelope surfaces: status:failed + timed_out:true +
+  // terminal_reason:timed_out. The Python contract also includes
+  // `interrupted: true` and a standalone `reason:` line; TS deliberately
+  // omits both — `interrupted` is not modeled, and the categorical
+  // `terminal_reason` is preferred over a separate prose `reason` field
+  // (PR#243 by-design exclusion). The TS contract assertions below
+  // suffice; the dropped assertions are documented for traceability.
+  it('a timed-out task surfaces the full timeout contract', async () => {
+    // Build a manager state where status=failed and timedOut=true.
+    const taskId = manager.registerAgentTask(new Promise(() => {}), 'will time out', {
+      timeoutMs: 50,
+    });
+    const info = await manager.waitForTerminal(taskId);
+    expect(info?.status).toBe('failed');
+    expect(info?.timedOut).toBe(true);
+
+    const result = await executeTool(
+      tool,
+      context('c_timeout_contract', { task_id: taskId, block: true, timeout: 1 }),
+    );
+    expect(result.isError).toBe(false);
+    const text = toolContentString(result);
+    expect(text).toContain('status: failed');
+    expect(text).toContain('timed_out: true');
+    expect(text).toContain('terminal_reason: timed_out');
+  });
+
+  // Oversized output (>32KB): the envelope truncates to a preview
+  // (32KB tail) + output_path + output_preview_bytes:32768 +
+  // output_size_bytes + output_truncated:true + a "Truncated. Full
+  // output: ${path}" banner + ReadFile hint with line_offset/n_lines.
+  // (gap #5.)
+  it('oversized output surfaces a truncated preview and full log path', async () => {
+    const { mkdtemp, rm } = await import('node:fs/promises');
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-trunc-'));
+    try {
+      const big = 'first marker\n' + 'x'.repeat(33 * 1024) + '\nlast marker\n';
+      const m2 = new BackgroundProcessManager();
+      m2.attachSessionDir(sessionDir);
+      const taskId = m2.register(immediateProcess(0, big), 'big', 'big output');
+      await m2.wait(taskId, 5_000);
+
+      const t = new TaskOutputTool(m2);
+      const r = await executeTool(t, context('c_trunc', { task_id: taskId, block: true, timeout: 1 }));
+      expect(r.isError).toBe(false);
+      const text = toolContentString(r);
+      expect(text).toContain('output_preview_bytes: 32768');
+      expect(text).toContain('output_truncated: true');
+      expect(text).toMatch(/output_size_bytes: \d+/);
+      expect(text).toMatch(/\[Truncated\. Full output: .*\]/);
+      // Tail preview should keep the last marker, drop the head.
+      expect(text).toContain('last marker');
+      expect(text).not.toContain('first marker');
+      // TS uses prose ("Use the Read tool with the output_path ...
+      // parameters: path, line_offset, n_lines") instead of Python's
+      // literal `ReadFile(path=..., line_offset=1, n_lines=N)` call
+      // syntax. Assert the keywords that signal the same intent.
+      expect(text).toMatch(/Read/);
+      expect(text).toMatch(/line_offset/);
+      expect(text).toMatch(/n_lines/);
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('TaskListTool — py envelope contract', () => {
+  const manager = new BackgroundProcessManager();
+  const tool = new TaskListTool(manager);
+
+  afterEach(() => {
+    manager._reset();
+  });
+
+  // TaskList(active_only=True) emits an 'active_background_tasks: N'
+  // header so the LLM can see the count distinct from the per-task body.
+  it('active_only=true emits an active_background_tasks header', async () => {
+    const proc = pendingProcess();
+    manager.register(proc, 'sleep 60', 'running');
+    const result = await executeTool(tool, context('c_active_header', { active_only: true }));
+    expect(result.isError).toBe(false);
+    expect(toolContentString(result)).toContain('active_background_tasks: 1');
+  });
+
+  // TaskList(active_only=False, limit=1) emits a 'background_tasks: N'
+  // header and honours the limit.
+  it('active_only=false emits a background_tasks header and honours limit', async () => {
+    const proc = immediateProcess(0);
+    const taskId = manager.register(proc, 'echo done', 'done');
+    await new Promise((r) => {
+      setTimeout(r, 20);
+    });
+    expect(manager.getTask(taskId)?.status).toBe('completed');
+    const result = await executeTool(
+      tool,
+      context('c_all_header', { active_only: false, limit: 1 }),
+    );
+    expect(result.isError).toBe(false);
+    const text = toolContentString(result);
+    expect(text).toContain('background_tasks: 1');
+    expect(text).toContain(taskId);
+  });
+});
+
+// task-list / task-stop / task-output description copy contracts —
+// the LLM-facing description text must mention specific keywords so
+// agents know when to reach for each tool.
+
+describe('background tool descriptions', () => {
+  const manager = new BackgroundProcessManager();
+  afterEach(() => {
+    manager._reset();
+  });
+
+  it('TaskOutput description mentions background tasks, block param, output_path, Read fallback', () => {
+    const tool = new TaskOutputTool(manager);
+    const desc = tool.description;
+    expect(desc).toMatch(/background/i);
+    expect(desc).toMatch(/block/);
+    expect(desc).toMatch(/output_path/);
+    // TS uses `Read` rather than Python's `ReadFile` for the full-log
+    // fallback tool; assert the TS-native name.
+    expect(desc).toMatch(/Read/);
+  });
+
+  it('TaskList description mentions active_only default, read-only, plan-mode safe', () => {
+    const tool = new TaskListTool(manager);
+    const desc = tool.description;
+    expect(desc).toMatch(/active_only/);
+    expect(desc).toMatch(/read[- ]only/i);
+    expect(desc).toMatch(/plan[- ]mode/i);
+    expect(desc).toMatch(/background tasks?/i);
+  });
+
+  it('TaskStop description clarifies destructive cancellation and is generic (not bash-only)', () => {
+    const tool = new TaskStopTool(manager);
+    const desc = tool.description;
+    expect(desc).toMatch(/destructive/i);
+    expect(desc).toMatch(/cancel/i);
+    // TS phrasing uses "general-purpose"; Python uses "generic". Accept
+    // either since they convey the same "not bash-specific" intent.
+    expect(desc).toMatch(/general[-\s]?purpose|generic/i);
+    expect(desc).not.toMatch(/bash[- ]?only/i);
+  });
+});
+
+// Behavioral coverage for partial-output reads. Python exposes
+// `read_output(offset, max_bytes) → {text, next_offset, eof}` and a
+// dedicated `tail_output(max_bytes, max_lines)` on the BPM. TS solves
+// the same problems through different surfaces: byte-range reads go
+// through `readOutputBytesFromDisk` and line-bounded tails go through
+// `getOutput(taskId, tail)`. These tests exercise the TS surface to
+// lock down the underlying behavior, not the Python method names.
+describe('background store — partial output reads (TS surface)', () => {
+  const manager = new BackgroundProcessManager();
+  afterEach(() => {
+    manager._reset();
+  });
+
+  it('readOutputBytesFromDisk returns the requested byte window', async () => {
+    const { mkdtemp, rm } = await import('node:fs/promises');
+    const sessionDir = await mkdtemp(join(tmpdir(), 'kimi-bg-range-'));
+    try {
+      const m2 = new BackgroundProcessManager();
+      m2.attachSessionDir(sessionDir);
+      const proc = immediateProcess(0, 'line1\nline2\nline3\n');
+      const taskId = m2.register(proc, 'echo lines', 'range read');
+      await m2.wait(taskId, 5_000);
+      // Behavior contract: byte offset 0, length 7 returns "line1\nl".
+      const chunk = await m2.readOutputBytesFromDisk(taskId, 0, 7);
+      expect(chunk).toBe('line1\nl');
+      // A second window that starts where the first ended returns the
+      // next slice — i.e. callers can paginate by tracking the offset.
+      const next = await m2.readOutputBytesFromDisk(taskId, 7, 7);
+      expect(next).toBe('ine2\nli');
+    } finally {
+      await rm(sessionDir, { recursive: true, force: true });
+    }
+  });
+
+  it('getOutput with a tail arg returns the last N characters', async () => {
+    const proc = immediateProcess(0, 'line1\nline2\nline3\n');
+    const taskId = manager.register(proc, 'echo lines', 'tail read');
+    await new Promise((r) => {
+      setTimeout(r, 50);
+    });
+    // Behavior contract: TS's tail is character-bounded (Python's was
+    // line-bounded; the line-tail concern is satisfied at the
+    // task-output.ts layer instead). Asking for the last 12 chars of
+    // "line1\nline2\nline3\n" yields "line2\nline3\n".
+    const tail = manager.getOutput(taskId, 12);
+    expect(tail).toBe('line2\nline3\n');
+  });
+});
+
+// A background agent paused in `awaiting_approval` can be killed via
+// the TaskStop tool — the task transitions to `killed`. The
+// downstream side effect (clearing pending approvals on the
+// ApprovalRuntime) lives outside the BPM in TS by design and is
+// covered by ApprovalRuntime's own tests; this test scopes only the
+// status transition through the tool boundary.
+describe('TaskStopTool on awaiting-approval agents', () => {
+  const manager = new BackgroundProcessManager();
+  const stop = new TaskStopTool(manager);
+
+  afterEach(() => {
+    manager._reset();
+  });
+
+  it('TaskStop on an awaiting_approval agent transitions the task to killed', async () => {
+    let rejectCompletion!: (err: unknown) => void;
+    const completion = new Promise<{ result: string }>((_res, rej) => {
+      rejectCompletion = rej;
+    });
+    const taskId = manager.registerAgentTask(completion, 'awaiting kill', {
+      abort: () => {
+        const abortError = new Error('cancelled');
+        abortError.name = 'AbortError';
+        rejectCompletion(abortError);
+      },
+    });
+    manager.markAwaitingApproval(taskId, 'edit file');
+    const result = await executeTool(stop, context('c_stop_awaiting', { task_id: taskId }));
+    expect(result.isError).toBe(false);
+    const info = manager.getTask(taskId);
+    expect(info?.status).toBe('killed');
+  });
+});
+
+// Reuse imports from the top of the file. The helper-suite needs
+// mkdtemp/tmpdir/join — already imported at the top.
diff --git a/packages/agent-core/test/tools/bash-env.test.ts b/packages/agent-core/test/tools/bash-env.test.ts
new file mode 100644
index 000000000..541a9cfe8
--- /dev/null
+++ b/packages/agent-core/test/tools/bash-env.test.ts
@@ -0,0 +1,68 @@
+import { Readable, type Writable } from 'node:stream';
+
+import type { KaosProcess } from '@moonshot-ai/kaos';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BashTool } from '../../src/tools/builtin/shell/bash';
+import type { Environment } from '../../src/utils/environment';
+import { executeTool } from './fixtures/execute-tool';
+import { createFakeKaos } from './fixtures/fake-kaos';
+
+const posixEnv: Environment = {
+  osKind: 'Linux',
+  osArch: 'x86_64',
+  osVersion: 'test',
+  shellPath: '/bin/bash',
+  shellName: 'bash',
+};
+
+function fakeProcess(): KaosProcess {
+  return {
+    stdin: { end: vi.fn(), write: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 401,
+    exitCode: 0,
+    wait: vi.fn(async () => 0),
+    kill: vi.fn(async () => {}),
+  };
+}
+
+const signal = new AbortController().signal;
+
+async function captureSpawnEnv(): Promise<Record<string, string>> {
+  const execWithEnv = vi.fn().mockResolvedValue(fakeProcess());
+  const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv);
+  await executeTool(tool, {
+    turnId: '0',
+    toolCallId: 'tc_env',
+    args: { command: 'true', timeout: 1000 },
+    signal,
+  });
+  return execWithEnv.mock.calls[0]?.[1] as Record<string, string>;
+}
+
+describe('BashTool noninteractive env semantics', () => {
+  it('preserves an existing GIT_TERMINAL_PROMPT from the ambient env', async () => {
+    const previous = process.env['GIT_TERMINAL_PROMPT'];
+    process.env['GIT_TERMINAL_PROMPT'] = '1';
+    try {
+      const env = await captureSpawnEnv();
+      expect(env['GIT_TERMINAL_PROMPT']).toBe('1');
+    } finally {
+      if (previous === undefined) delete process.env['GIT_TERMINAL_PROMPT'];
+      else process.env['GIT_TERMINAL_PROMPT'] = previous;
+    }
+  });
+
+  it('defaults GIT_TERMINAL_PROMPT to "0" when the ambient env does not set it', async () => {
+    const previous = process.env['GIT_TERMINAL_PROMPT'];
+    delete process.env['GIT_TERMINAL_PROMPT'];
+    try {
+      const env = await captureSpawnEnv();
+      expect(env['GIT_TERMINAL_PROMPT']).toBe('0');
+    } finally {
+      if (previous !== undefined) process.env['GIT_TERMINAL_PROMPT'] = previous;
+    }
+  });
+});
diff --git a/packages/agent-core/test/tools/bash-windows-kill.test.ts b/packages/agent-core/test/tools/bash-windows-kill.test.ts
new file mode 100644
index 000000000..1ff98eb4d
--- /dev/null
+++ b/packages/agent-core/test/tools/bash-windows-kill.test.ts
@@ -0,0 +1,10 @@
+/**
+ * Windows-only: default Node `kill` does not stop the whole process tree, so
+ * background Bash can leave orphaned child processes. Once tree kill lands
+ * (e.g. `taskkill /T`), assert grandchildren are reaped within the grace window.
+ */
+import { describe, it } from 'vitest';
+
+describe.skipIf(process.platform !== 'win32')('BashTool background — Windows kill tree', () => {
+  it.todo('stop() terminates grandchild processes via taskkill /T');
+});
diff --git a/packages/agent-core/test/tools/bash.test.ts b/packages/agent-core/test/tools/bash.test.ts
new file mode 100644
index 000000000..b4dd417be
--- /dev/null
+++ b/packages/agent-core/test/tools/bash.test.ts
@@ -0,0 +1,908 @@
+import { PassThrough, Readable, type Writable } from 'node:stream';
+
+import type { KaosProcess } from '@moonshot-ai/kaos';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BackgroundProcessManager } from '../../src/tools/background/manager';
+import { type BashInput, BashInputSchema, BashTool } from '../../src/tools/builtin/shell/bash';
+import type { Environment } from '../../src/utils/environment';
+import { createFakeKaos } from './fixtures/fake-kaos';
+import { executeTool } from './fixtures/execute-tool';
+
+const posixEnv: Environment = {
+  osKind: 'Linux',
+  osArch: 'arm64',
+  osVersion: 'test',
+  shellPath: '/bin/bash',
+  shellName: 'bash',
+};
+
+const windowsBashEnv: Environment = {
+  osKind: 'Windows',
+  osArch: 'x64',
+  osVersion: 'test',
+  shellPath: 'C:\\Program Files\\Git\\bin\\bash.exe',
+  shellName: 'bash',
+};
+
+function processWithOutput(
+  options: {
+    readonly stdout?: string | Buffer;
+    readonly stderr?: string | Buffer;
+    readonly exitCode?: number;
+    readonly wait?: () => Promise<number>;
+    readonly kill?: (signal?: NodeJS.Signals) => Promise<void>;
+  } = {},
+): KaosProcess {
+  const exitCode = options.exitCode ?? 0;
+  return {
+    stdin: { end: vi.fn(), write: vi.fn() } as unknown as Writable,
+    stdout: Readable.from(options.stdout === undefined ? [] : [options.stdout]),
+    stderr: Readable.from(options.stderr === undefined ? [] : [options.stderr]),
+    pid: 123,
+    exitCode,
+    wait: vi.fn(options.wait ?? (async () => exitCode)),
+    kill: vi.fn(options.kill ?? (async () => {})),
+  };
+}
+
+function processWithInterleavedOutput(
+  events: ReadonlyArray<{
+    readonly stream: 'stdout' | 'stderr';
+    readonly text: string;
+    readonly delayMs: number;
+  }>,
+  exitCode = 0,
+): KaosProcess {
+  const stdout = new PassThrough();
+  const stderr = new PassThrough();
+  const lastDelay = Math.max(...events.map((event) => event.delayMs), 0);
+  const waitPromise = new Promise<number>((resolve) => {
+    for (const event of events) {
+      setTimeout(() => {
+        const target = event.stream === 'stdout' ? stdout : stderr;
+        target.write(event.text);
+      }, event.delayMs);
+    }
+    setTimeout(() => {
+      stdout.end();
+      stderr.end();
+      resolve(exitCode);
+    }, lastDelay + 1);
+  });
+
+  return {
+    stdin: { end: vi.fn(), write: vi.fn() } as unknown as Writable,
+    stdout,
+    stderr,
+    pid: 124,
+    exitCode,
+    wait: vi.fn(async () => waitPromise),
+    kill: vi.fn(async () => {}),
+  };
+}
+
+function processWithVisibleExitBeforeWait(exitCode = 0): {
+  proc: KaosProcess;
+  finishWait: () => void;
+  markExited: () => void;
+} {
+  let currentExitCode: number | null = null;
+  let resolveWait: (code: number) => void = () => {};
+  const waitPromise = new Promise<number>((resolve) => {
+    resolveWait = resolve;
+  });
+  const proc: KaosProcess = {
+    stdin: { end: vi.fn(), write: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 125,
+    get exitCode(): number | null {
+      return currentExitCode;
+    },
+    wait: vi.fn(async () => waitPromise),
+    kill: vi.fn(async () => {}),
+  };
+
+  return {
+    proc,
+    finishWait: () => {
+      resolveWait(exitCode);
+    },
+    markExited: () => {
+      currentExitCode = exitCode;
+    },
+  };
+}
+
+function processThatNeverExits(): KaosProcess {
+  return {
+    stdin: { end: vi.fn(), write: vi.fn() } as unknown as Writable,
+    stdout: new PassThrough(),
+    stderr: new PassThrough(),
+    pid: 126,
+    exitCode: null,
+    wait: vi.fn(async () => new Promise<number>(() => {})),
+    kill: vi.fn(async () => {}),
+  };
+}
+
+function context(args: BashInput, signal = new AbortController().signal) {
+  return { turnId: '0', toolCallId: 'call_bash', args, signal };
+}
+
+describe('BashTool', () => {
+  it('exposes current metadata and schema', () => {
+    const tool = new BashTool(createFakeKaos(), '/workspace', posixEnv);
+
+    expect(tool.name).toBe('Bash');
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: { command: { type: 'string' } },
+    });
+    expect(BashInputSchema.safeParse({ command: 'echo hello' }).success).toBe(true);
+    expect(BashInputSchema.safeParse({ command: '' }).success).toBe(false);
+    expect(BashInputSchema.safeParse({ command: 'echo x', timeout: 0 }).success).toBe(false);
+    expect(BashInputSchema.safeParse({ command: 'echo x', timeout: 300 }).success).toBe(true);
+    expect(BashInputSchema.safeParse({ command: 'echo x', timeout: 301 }).success).toBe(false);
+    expect(BashInputSchema.safeParse({ command: 'echo x', timeout: 300_000 }).success).toBe(false);
+    expect(BashInputSchema.safeParse({ command: 'echo x', timeout: 300_001 }).success).toBe(false);
+    expect(
+      BashInputSchema.safeParse({
+        command: 'watch',
+        run_in_background: true,
+        description: 'watch files',
+        timeout: 86_400,
+      }).success,
+    ).toBe(true);
+    expect(
+      BashInputSchema.safeParse({
+        command: 'watch',
+        run_in_background: true,
+        description: 'watch files',
+        timeout: 86_401,
+      }).success,
+    ).toBe(false);
+    expect(
+      BashInputSchema.safeParse({
+        command: 'watch',
+        run_in_background: true,
+        description: 'watch files',
+        timeout: 600_000,
+      }).success,
+    ).toBe(false);
+    expect(
+      BashInputSchema.safeParse({
+        command: 'watch',
+        run_in_background: true,
+        description: 'watch files',
+        disable_timeout: true,
+      }).success,
+    ).toBe(true);
+  });
+
+  it('describes the cwd, command, run_in_background, description, and disable_timeout parameters', () => {
+    const tool = new BashTool(createFakeKaos(), '/workspace', posixEnv);
+    const properties = (tool.parameters as { properties: Record<string, { description?: string }> })
+      .properties;
+
+    for (const name of [
+      'cwd',
+      'command',
+      'run_in_background',
+      'description',
+      'disable_timeout',
+    ] as const) {
+      const description = properties[name]?.description;
+      expect(description, `${name} should have a non-empty description`).toBeTruthy();
+      expect((description ?? '').trim().length).toBeGreaterThan(0);
+    }
+  });
+
+  it('exposes a default timeout in the JSON Schema', () => {
+    const tool = new BashTool(createFakeKaos(), '/workspace', posixEnv);
+    const properties = (tool.parameters as { properties: Record<string, { default?: number }> })
+      .properties;
+
+    expect(properties['timeout']?.default).toBe(60);
+  });
+
+  it('interprets small timeout values as seconds at runtime', async () => {
+    vi.useFakeTimers();
+    try {
+      let resolveWait: (code: number) => void = () => {};
+      const waitPromise = new Promise<number>((resolve) => {
+        resolveWait = resolve;
+      });
+      const proc = processWithOutput({
+        wait: async () => waitPromise,
+        kill: async () => {
+          resolveWait(143);
+        },
+      });
+      const tool = new BashTool(
+        createFakeKaos({ execWithEnv: vi.fn().mockResolvedValue(proc) }),
+        '/workspace',
+        posixEnv,
+      );
+
+      const running = executeTool(tool, context({ command: 'sleep 3', timeout: 2 }));
+      await vi.advanceTimersByTimeAsync(1_999);
+      expect(proc.kill).not.toHaveBeenCalled();
+
+      await vi.advanceTimersByTimeAsync(1);
+      const result = await running;
+
+      expect(proc.kill).toHaveBeenCalled();
+      expect(result.output).toContain('Command killed by timeout (2s)');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('renders the available commands section and the /tasks hint', () => {
+    const tool = new BashTool(
+      createFakeKaos(),
+      '/workspace',
+      posixEnv,
+      new BackgroundProcessManager(),
+    );
+
+    expect(tool.description).toContain('Commands available');
+    expect(tool.description).toContain('/tasks');
+  });
+
+  it('runs through execWithEnv, injects cwd, noninteractive env, and closes stdin', async () => {
+    const proc = processWithOutput({ stdout: 'ok\n' });
+    const execWithEnv = vi.fn().mockResolvedValue(proc);
+    const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv);
+
+    const result = await executeTool(tool, context({ command: 'printf ok', timeout: 60 }));
+
+    expect(execWithEnv).toHaveBeenCalledTimes(1);
+    const [argv, env] = execWithEnv.mock.calls[0]!;
+    expect(argv).toEqual(['/bin/bash', '-c', "cd '/workspace' && printf ok"]);
+    expect(env).toMatchObject({
+      NO_COLOR: '1',
+      TERM: 'dumb',
+    });
+    expect(proc.stdin.end).toHaveBeenCalledTimes(1);
+    expect(result).toMatchObject({
+      output: 'ok\n',
+      isError: false,
+      message: 'Command executed successfully.',
+    });
+  });
+
+  it('uses args.cwd when provided', async () => {
+    const execWithEnv = vi.fn().mockResolvedValue(processWithOutput({ stdout: 'sub\n' }));
+    const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv);
+
+    await executeTool(tool, context({ command: 'pwd', cwd: '/tmp/project', timeout: 60 }));
+
+    expect(execWithEnv.mock.calls[0]?.[0]).toEqual(['/bin/bash', '-c', "cd '/tmp/project' && pwd"]);
+  });
+
+  it('uses Git Bash semantics on Windows', async () => {
+    const proc = processWithOutput({ stdout: 'ok\n' });
+    const execWithEnv = vi.fn().mockResolvedValue(proc);
+    const tool = new BashTool(
+      createFakeKaos({ execWithEnv }),
+      'C:\\Users\\me\\project',
+      windowsBashEnv,
+    );
+
+    const result = await executeTool(tool, context({ command: 'echo ok 2>nul', timeout: 60 }));
+
+    expect(execWithEnv).toHaveBeenCalledTimes(1);
+    const [argv, env] = execWithEnv.mock.calls[0]!;
+    expect(argv).toEqual([
+      'C:\\Program Files\\Git\\bin\\bash.exe',
+      '-c',
+      "cd '/c/Users/me/project' && echo ok 2>/dev/null",
+    ]);
+    expect(env).toMatchObject({ SHELL: 'C:\\Program Files\\Git\\bin\\bash.exe' });
+    expect(result).toMatchObject({
+      output: 'ok\n',
+      isError: false,
+      message: 'Command executed successfully.',
+    });
+  });
+
+  it('returns stderr and marks non-zero exit codes as tool errors', async () => {
+    const tool = new BashTool(
+      createFakeKaos({
+        execWithEnv: vi
+          .fn()
+          .mockResolvedValue(processWithOutput({ stderr: 'boom\n', exitCode: 2 })),
+      }),
+      '/workspace',
+      posixEnv,
+    );
+
+    const result = await executeTool(tool, context({ command: 'exit 2', timeout: 60 }));
+
+    expect(result).toMatchObject({
+      isError: true,
+      message: 'Command failed with exit code: 2.',
+      brief: 'Failed with exit code: 2',
+    });
+    expect(result.output).toContain('boom\n');
+    expect(result.output).toContain('Command failed with exit code: 2.');
+  });
+
+  it('returns both stdout and stderr when a command succeeds', async () => {
+    const tool = new BashTool(
+      createFakeKaos({
+        execWithEnv: vi
+          .fn()
+          .mockResolvedValue(processWithOutput({ stdout: 'out\n', stderr: 'warn\n' })),
+      }),
+      '/workspace',
+      posixEnv,
+    );
+
+    const result = await executeTool(tool, context({ command: 'mixed', timeout: 60 }));
+
+    expect(result).toMatchObject({
+      output: 'out\nwarn\n',
+      isError: false,
+      message: 'Command executed successfully.',
+    });
+  });
+
+  it('returns both stdout and stderr when a command fails', async () => {
+    const tool = new BashTool(
+      createFakeKaos({
+        execWithEnv: vi.fn().mockResolvedValue(
+          processWithOutput({
+            stdout: 'partial\n',
+            stderr: 'boom\n',
+            exitCode: 2,
+          }),
+        ),
+      }),
+      '/workspace',
+      posixEnv,
+    );
+
+    const result = await executeTool(tool, context({ command: 'mixed fail', timeout: 60 }));
+
+    expect(result).toMatchObject({
+      isError: true,
+      message: 'Command failed with exit code: 2.',
+      brief: 'Failed with exit code: 2',
+    });
+    expect(result.output).toContain('partial\nboom\n');
+    expect(result.output).toContain('Command failed with exit code: 2.');
+  });
+
+  it('preserves foreground stdout and stderr arrival order', async () => {
+    vi.useFakeTimers();
+    try {
+      const proc = processWithInterleavedOutput([
+        { stream: 'stderr', text: 'err-first\n', delayMs: 0 },
+        { stream: 'stdout', text: 'out-second\n', delayMs: 5 },
+        { stream: 'stderr', text: 'err-third\n', delayMs: 10 },
+      ]);
+      const tool = new BashTool(
+        createFakeKaos({
+          execWithEnv: vi.fn().mockResolvedValue(proc),
+        }),
+        '/workspace',
+        posixEnv,
+      );
+
+      const resultPromise = executeTool(tool, context({ command: 'mixed', timeout: 60 }));
+      await vi.advanceTimersByTimeAsync(11);
+
+      const result = await resultPromise;
+      expect(result).toMatchObject({
+        isError: false,
+        output: 'err-first\nout-second\nerr-third\n',
+        message: 'Command executed successfully.',
+      });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('does not spawn when the signal is already aborted', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const execWithEnv = vi.fn();
+    const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv);
+
+    const result = await executeTool(tool, context({ command: 'echo nope' }, controller.signal));
+
+    expect(result).toEqual({ isError: true, output: 'Aborted before command started' });
+    expect(execWithEnv).not.toHaveBeenCalled();
+  });
+
+  it('kills the process and returns an abort result when aborted while running', async () => {
+    let resolveWait: (code: number) => void = () => {};
+    const waitPromise = new Promise<number>((resolve) => {
+      resolveWait = resolve;
+    });
+    const proc = processWithOutput({
+      wait: async () => waitPromise,
+      kill: async () => {
+        resolveWait(143);
+      },
+    });
+    const execWithEnv = vi.fn().mockResolvedValue(proc);
+    const controller = new AbortController();
+    const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv);
+
+    const running = executeTool(tool, context({ command: 'sleep 10' }, controller.signal));
+    await vi.waitFor(() => {
+      expect(proc.stdin.end).toHaveBeenCalled();
+    });
+    controller.abort();
+    const result = await running;
+
+    expect(proc.kill).toHaveBeenCalledWith('SIGTERM');
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('Interrupted by user');
+  });
+
+  it('requires a background manager and description for background commands', async () => {
+    const proc = processWithOutput();
+    const execWithEnv = vi.fn().mockResolvedValue(proc);
+    const withoutManager = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv);
+
+    const unavailable = await executeTool(withoutManager,
+      context({ command: 'sleep 10', run_in_background: true, description: 'watch' }),
+    );
+    expect(unavailable).toMatchObject({ isError: true });
+    expect(unavailable.output).toContain('Background execution is not available');
+    expect(execWithEnv).not.toHaveBeenCalled();
+
+    const manager = new BackgroundProcessManager();
+    const withManager = new BashTool(
+      createFakeKaos({ execWithEnv }),
+      '/workspace',
+      posixEnv,
+      manager,
+    );
+    const missingDescription = await executeTool(withManager,
+      context({ command: 'sleep 10', run_in_background: true }),
+    );
+
+    expect(missingDescription).toMatchObject({ isError: true });
+    expect(missingDescription.output).toContain('description is required');
+    expect(execWithEnv).not.toHaveBeenCalled();
+  });
+
+  it('registers background commands and returns a task id', async () => {
+    const proc = processWithOutput();
+    const execWithEnv = vi.fn().mockResolvedValue(proc);
+    const manager = new BackgroundProcessManager();
+    const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv, manager);
+
+    const result = await executeTool(tool,
+      context({ command: 'sleep 10', run_in_background: true, description: 'long running task' }),
+    );
+
+    expect(result.output).toMatch(/task_id: bash-[0-9a-z]{8}/);
+    expect(result.output).toContain('automatic_notification: true');
+    expect(manager.list(false)).toHaveLength(1);
+  });
+
+  it('does not spawn background commands when the task limit is reached', async () => {
+    const manager = new BackgroundProcessManager({ maxRunningTasks: 1 });
+    manager.register(processWithOutput(), 'sleep 10', 'existing task');
+    const execWithEnv = vi.fn().mockResolvedValue(processWithOutput());
+    const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv, manager);
+
+    const result = await executeTool(tool,
+      context({ command: 'sleep 10', run_in_background: true, description: 'second task' }),
+    );
+
+    expect(result).toMatchObject({
+      isError: true,
+      output: 'Too many background tasks are already running.',
+    });
+    expect(execWithEnv).not.toHaveBeenCalled();
+  });
+
+  it('reserves a task slot before spawning concurrent background commands', async () => {
+    const manager = new BackgroundProcessManager({ maxRunningTasks: 1 });
+    const execWithEnv = vi
+      .fn()
+      .mockResolvedValueOnce(
+        processWithOutput({
+          wait: () => new Promise(() => {}),
+        }),
+      )
+      .mockResolvedValueOnce(processWithOutput());
+    const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv, manager);
+
+    const first = executeTool(tool,
+      context({ command: 'sleep 10', run_in_background: true, description: 'first task' }),
+    );
+    const second = executeTool(tool,
+      context({ command: 'sleep 10', run_in_background: true, description: 'second task' }),
+    );
+
+    const results = await Promise.all([first, second]);
+
+    expect(execWithEnv).toHaveBeenCalledTimes(1);
+    expect(results).toContainEqual(expect.objectContaining({ isError: false }));
+    expect(results).toContainEqual(
+      expect.objectContaining({
+        isError: true,
+        output: 'Too many background tasks are already running.',
+      }),
+    );
+  });
+
+  it('preserves background reservations while using Git Bash semantics on Windows', async () => {
+    const manager = new BackgroundProcessManager({ maxRunningTasks: 1 });
+    const execWithEnv = vi
+      .fn()
+      .mockResolvedValueOnce(
+        processWithOutput({
+          wait: () => new Promise(() => {}),
+        }),
+      )
+      .mockResolvedValueOnce(processWithOutput());
+    const tool = new BashTool(
+      createFakeKaos({ execWithEnv }),
+      'C:\\Users\\me\\project',
+      windowsBashEnv,
+      manager,
+    );
+
+    const first = executeTool(tool,
+      context({
+        command: 'echo ok 2>nul',
+        run_in_background: true,
+        description: 'first task',
+      }),
+    );
+    const second = executeTool(tool,
+      context({
+        command: 'echo second',
+        run_in_background: true,
+        description: 'second task',
+      }),
+    );
+
+    const results = await Promise.all([first, second]);
+
+    expect(execWithEnv).toHaveBeenCalledTimes(1);
+    const [argv, env] = execWithEnv.mock.calls[0]!;
+    expect(argv).toEqual([
+      'C:\\Program Files\\Git\\bin\\bash.exe',
+      '-c',
+      "cd '/c/Users/me/project' && echo ok 2>/dev/null",
+    ]);
+    expect(env).toMatchObject({ SHELL: 'C:\\Program Files\\Git\\bin\\bash.exe' });
+    expect(results).toContainEqual(expect.objectContaining({ isError: false }));
+    expect(results).toContainEqual(
+      expect.objectContaining({
+        isError: true,
+        output: 'Too many background tasks are already running.',
+      }),
+    );
+  });
+
+  it('does not timeout-stop a background task whose exit is visible before wait settles', async () => {
+    vi.useFakeTimers();
+    try {
+      const { proc, finishWait, markExited } = processWithVisibleExitBeforeWait(0);
+      const execWithEnv = vi.fn().mockResolvedValue(proc);
+      const manager = new BackgroundProcessManager();
+      const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv, manager);
+
+      const result = await executeTool(tool,
+        context({
+          command: 'sleep 10',
+          run_in_background: true,
+          description: 'exit before close',
+          timeout: 1,
+        }),
+      );
+      expect(typeof result.output).toBe('string');
+      if (typeof result.output !== 'string') throw new Error('Expected string tool output.');
+      const taskId = result.output.match(/task_id: (bash-[0-9a-z]{8})/)?.[1];
+      expect(taskId).toBeDefined();
+
+      markExited();
+      await vi.advanceTimersByTimeAsync(1_000);
+
+      expect(proc.kill).not.toHaveBeenCalled();
+
+      finishWait();
+      await vi.runAllTimersAsync();
+
+      expect(manager.getTask(taskId!)?.status).toBe('completed');
+      expect(proc.kill).not.toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('timeout-stops a background task after the default 10 minute deadline', async () => {
+    vi.useFakeTimers();
+    try {
+      const proc = processThatNeverExits();
+      const execWithEnv = vi.fn().mockResolvedValue(proc);
+      const manager = new BackgroundProcessManager();
+      const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv, manager);
+
+      const result = await executeTool(tool,
+        context({
+          command: 'sleep 999',
+          run_in_background: true,
+          description: 'default deadline',
+        }),
+      );
+      expect(result).toMatchObject({ isError: false });
+
+      await vi.advanceTimersByTimeAsync(600_000);
+
+      expect(proc.kill).toHaveBeenCalledWith('SIGTERM');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('does not timeout-stop a background task when disable_timeout is true', async () => {
+    vi.useFakeTimers();
+    try {
+      const proc = processThatNeverExits();
+      const execWithEnv = vi.fn().mockResolvedValue(proc);
+      const manager = new BackgroundProcessManager();
+      const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv, manager);
+
+      const result = await executeTool(tool,
+        context({
+          command: 'sleep 999',
+          run_in_background: true,
+          description: 'no deadline',
+          disable_timeout: true,
+        }),
+      );
+      expect(result).toMatchObject({ isError: false });
+
+      await vi.advanceTimersByTimeAsync(600_000 + 10_000);
+
+      expect(proc.kill).not.toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('adds a truncation note when stdout exceeds the cap', async () => {
+    const huge = Buffer.alloc(10 * 1024 * 1024 + 1, 'x');
+    const tool = new BashTool(
+      createFakeKaos({
+        execWithEnv: vi.fn().mockResolvedValue(processWithOutput({ stdout: huge })),
+      }),
+      '/workspace',
+      posixEnv,
+    );
+
+    const result = await executeTool(tool, context({ command: 'yes', timeout: 60 }));
+
+    expect(result.output).toContain('[...truncated]');
+    expect(result.output).toContain('Output is truncated');
+    expect((result as { message?: string }).message).toContain('Output is truncated');
+  });
+
+  it('marks the truncated output buffer with a "[...truncated]" sentinel at the cut point', async () => {
+    const huge = Buffer.alloc(10 * 1024 * 1024 + 1, 'x');
+    const tool = new BashTool(
+      createFakeKaos({
+        execWithEnv: vi.fn().mockResolvedValue(processWithOutput({ stdout: huge })),
+      }),
+      '/workspace',
+      posixEnv,
+    );
+
+    const result = await executeTool(tool, context({ command: 'yes', timeout: 60 }));
+
+    expect(typeof result.output).toBe('string');
+    const output = result.output as string;
+    expect(output).toContain('[...truncated]');
+  });
+
+  it('truncates output with the sentinel even when the command fails', async () => {
+    const huge = Buffer.alloc(10 * 1024 * 1024 + 1, 'E');
+    const tool = new BashTool(
+      createFakeKaos({
+        execWithEnv: vi
+          .fn()
+          .mockResolvedValue(processWithOutput({ stdout: huge, exitCode: 1 })),
+      }),
+      '/workspace',
+      posixEnv,
+    );
+
+    const result = await executeTool(tool, context({ command: 'fail-and-flood', timeout: 60 }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(typeof result.output).toBe('string');
+    const output = result.output as string;
+    expect(output).toContain('[...truncated]');
+    expect(output).toContain('Output is truncated');
+  });
+
+  it('reports a timed-out command with both message and brief lines', async () => {
+    vi.useFakeTimers();
+    try {
+      let resolveWait: (code: number) => void = () => {};
+      const waitPromise = new Promise<number>((resolve) => {
+        resolveWait = resolve;
+      });
+      const proc = processWithOutput({
+        wait: async () => waitPromise,
+        kill: async () => {
+          resolveWait(143);
+        },
+      });
+      const tool = new BashTool(
+        createFakeKaos({ execWithEnv: vi.fn().mockResolvedValue(proc) }),
+        '/workspace',
+        posixEnv,
+      );
+
+      const running = executeTool(tool, context({ command: 'sleep 2', timeout: 1 }));
+      await vi.advanceTimersByTimeAsync(1000);
+      const result = await running;
+
+      expect(result).toMatchObject({
+        isError: true,
+        brief: 'Killed by timeout (1s)',
+      });
+      expect(result.output).toContain('Command killed by timeout (1s)');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('rejects empty-string commands at the schema layer', () => {
+    expect(BashInputSchema.safeParse({ command: '' }).success).toBe(false);
+  });
+
+  it('does not inject GIT_SSH_COMMAND into the spawn environment', async () => {
+    const previous = process.env['GIT_SSH_COMMAND'];
+    delete process.env['GIT_SSH_COMMAND'];
+    try {
+      const execWithEnv = vi.fn().mockResolvedValue(processWithOutput({ stdout: 'ok\n' }));
+      const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv);
+
+      await executeTool(tool, context({ command: 'true', timeout: 60 }));
+
+      const env = execWithEnv.mock.calls[0]?.[1] as Record<string, string>;
+      expect(Object.prototype.hasOwnProperty.call(env, 'GIT_SSH_COMMAND')).toBe(false);
+    } finally {
+      if (previous !== undefined) process.env['GIT_SSH_COMMAND'] = previous;
+    }
+  });
+
+  it('reports background task startup with task_id, status, automatic_notification, and a human-shell hint', async () => {
+    const proc = processWithOutput();
+    const execWithEnv = vi.fn().mockResolvedValue(proc);
+    const manager = new BackgroundProcessManager();
+    const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv, manager);
+
+    const result = await executeTool(
+      tool,
+      context({ command: 'sleep 1', run_in_background: true, description: 'sleep task' }),
+    );
+
+    expect(typeof result.output).toBe('string');
+    const output = result.output as string;
+    expect(output).toContain('task_id:');
+    expect(output).toContain('status: running');
+    expect(output).toContain('automatic_notification: true');
+    expect(output).toContain('human_shell_hint:');
+    expect(output).toContain('/tasks');
+  });
+
+  it('rejects background command without description (description-required guard)', async () => {
+    const manager = new BackgroundProcessManager();
+    const execWithEnv = vi.fn().mockResolvedValue(processWithOutput());
+    const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv, manager);
+
+    const result = await executeTool(
+      tool,
+      context({ command: 'sleep 1', run_in_background: true }),
+    );
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('description is required');
+    expect(execWithEnv).not.toHaveBeenCalled();
+  });
+
+  it('rewrites nul-redirect on Windows so the spawned argv has /dev/null', async () => {
+    const execWithEnv = vi.fn().mockResolvedValue(processWithOutput({ stdout: '' }));
+    const tool = new BashTool(
+      createFakeKaos({ execWithEnv }),
+      'C:\\Users\\me\\project',
+      windowsBashEnv,
+    );
+
+    await executeTool(tool, context({ command: 'ls 2>nul', timeout: 60 }));
+
+    const argv = execWithEnv.mock.calls[0]?.[0] as readonly string[];
+    expect(argv[2]).toBe("cd '/c/Users/me/project' && ls 2>/dev/null");
+  });
+
+  it('passes nul-redirect through unchanged on Linux so the argv keeps the literal file target', async () => {
+    const execWithEnv = vi.fn().mockResolvedValue(processWithOutput({ stdout: '' }));
+    const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv);
+
+    await executeTool(tool, context({ command: 'ls 2>nul', timeout: 60 }));
+
+    const argv = execWithEnv.mock.calls[0]?.[0] as readonly string[];
+    expect(argv[2]).toBe("cd '/workspace' && ls 2>nul");
+  });
+
+  it('exposes a shell description that documents /bin/bash, TaskOutput/TaskStop, safety and efficiency sections, and background semantics', () => {
+    const tool = new BashTool(
+      createFakeKaos(),
+      '/workspace',
+      posixEnv,
+      new BackgroundProcessManager(),
+    );
+
+    const description = tool.description;
+    expect(description).toContain('`bash`');
+    expect(description).toContain('TaskOutput');
+    expect(description).toContain('TaskStop');
+    expect(description).toContain('**Guidelines for safety and security:**');
+    expect(description).toContain('**Guidelines for efficiency:**');
+    expect(description).toContain('run_in_background=true');
+    expect(description).toContain('automatically notified');
+  });
+});
+
+describe('BashTool prompt / runtime consistency', () => {
+  it('reports unavailable background using only tools the prompt documents', async () => {
+    const execWithEnv = vi.fn();
+
+    // The set of background tools the prompt actually introduces — taken from
+    // the background-enabled prompt, which is the only variant that documents
+    // any Task* tool.
+    const enabledTool = new BashTool(
+      createFakeKaos({ execWithEnv }),
+      '/workspace',
+      posixEnv,
+      new BackgroundProcessManager(),
+    );
+    const promptToolNames = new Set(
+      [...enabledTool.description.matchAll(/`(Task[A-Za-z]+)`/g)].map((match) => match[1]),
+    );
+
+    const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv);
+    const result = await executeTool(tool,
+      context({ command: 'sleep 10', run_in_background: true, description: 'watch' }),
+    );
+
+    expect(result).toMatchObject({ isError: true });
+    expect(typeof result.output).toBe('string');
+    const errorToolNames = [...(result.output as string).matchAll(/\b(Task[A-Za-z]+)\b/g)].map(
+      (match) => match[1],
+    );
+
+    // The unavailable-background error message must not name a tool that the
+    // prompt never introduces, otherwise the model is told about a tool it
+    // has no guidance for.
+    for (const name of errorToolNames) {
+      expect(promptToolNames).toContain(name);
+    }
+    expect(errorToolNames.length).toBeGreaterThan(0);
+  });
+
+  it('does not claim failure exit codes appear in a system tag', () => {
+    const tool = new BashTool(createFakeKaos({}), '/workspace', posixEnv);
+
+    // The implementation reports failures as plain text inside the output
+    // (`Command failed with exit code: N`), never via a system tag.
+    expect(tool.description).not.toMatch(/exit code will be provided in a system tag/);
+  });
+});
diff --git a/packages/agent-core/test/tools/builtin-current.test.ts b/packages/agent-core/test/tools/builtin-current.test.ts
new file mode 100644
index 000000000..fda3782d4
--- /dev/null
+++ b/packages/agent-core/test/tools/builtin-current.test.ts
@@ -0,0 +1,304 @@
+/**
+ * Current builtin tool smoke coverage.
+ *
+ * This complements focused tool tests by ensuring every current builtin
+ * has at least one schema assertion and one execution/error-path assertion.
+ */
+
+import { Readable, type Writable } from 'node:stream';
+
+import type { Kaos, KaosProcess } from '@moonshot-ai/kaos';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Agent } from '../../src/agent';
+import type { SessionSubagentHost } from '../../src/session/subagent-host';
+import { SkillRegistry } from '../../src/skill';
+import { BackgroundProcessManager } from '../../src/tools/background/manager';
+import { TaskListInputSchema } from '../../src/tools/background/task-list';
+import { TaskOutputInputSchema } from '../../src/tools/background/task-output';
+import { TaskStopInputSchema } from '../../src/tools/background/task-stop';
+import { AgentTool, AgentToolInputSchema } from '../../src/tools/builtin/collaboration/agent';
+import {
+  AskUserQuestionInputSchema,
+  AskUserQuestionTool,
+} from '../../src/tools/builtin/collaboration/ask-user';
+import { SkillTool, SkillToolInputSchema } from '../../src/tools/builtin/collaboration/skill-tool';
+import { EditInputSchema, EditTool } from '../../src/tools/builtin/file/edit';
+import { GlobInputSchema, GlobTool } from '../../src/tools/builtin/file/glob';
+import { GrepInputSchema, GrepTool } from '../../src/tools/builtin/file/grep';
+import { ReadInputSchema, ReadTool } from '../../src/tools/builtin/file/read';
+import { WriteInputSchema, WriteTool } from '../../src/tools/builtin/file/write';
+import { BashInputSchema, BashTool } from '../../src/tools/builtin/shell/bash';
+import type { WorkspaceConfig } from '../../src/tools/support/workspace';
+import { createFakeKaos } from './fixtures/fake-kaos';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+const workspace: WorkspaceConfig = { workspaceDir: '/workspace', additionalDirs: [] };
+const regularFileStat = {
+  stMode: 0o100_644,
+  stIno: 1,
+  stDev: 1,
+  stNlink: 1,
+  stUid: 1000,
+  stGid: 1000,
+  stSize: 0,
+  stAtime: 0,
+  stMtime: 0,
+  stCtime: 0,
+} satisfies Awaited<ReturnType<Kaos['stat']>>;
+const directoryStat = {
+  ...regularFileStat,
+  stMode: 0o040_755,
+} satisfies Awaited<ReturnType<Kaos['stat']>>;
+
+function context<Input>(args: Input, toolCallId = 'call_1') {
+  return { turnId: '0', toolCallId, args, signal };
+}
+
+function mockSubagentHost<T extends Pick<SessionSubagentHost, 'spawn'> & Partial<SessionSubagentHost>>(
+  host: T,
+): T & SessionSubagentHost {
+  return { resume: vi.fn(), ...host } as unknown as T & SessionSubagentHost;
+}
+
+function processWithOutput(stdout: string, exitCode = 0): KaosProcess {
+  return {
+    stdin: { write: vi.fn(), end: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([stdout]),
+    stderr: Readable.from([]),
+    pid: 123,
+    exitCode,
+    wait: vi.fn().mockResolvedValue(exitCode),
+    kill: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe('current builtin file and shell tools', () => {
+  it('Read exposes parameters and reads text content', async () => {
+    const content = 'alpha\nbeta\n';
+    const bytes = Buffer.from(content, 'utf8');
+    const tool = new ReadTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue(regularFileStat),
+        readBytes: vi.fn<Kaos['readBytes']>().mockImplementation(async (_path, n) => {
+          return n === undefined ? bytes : bytes.subarray(0, n);
+        }),
+        readLines: vi.fn<Kaos['readLines']>().mockImplementation(async function* readLines() {
+          yield 'alpha\n';
+          yield 'beta\n';
+        }),
+      }),
+      workspace,
+    );
+
+    expect(ReadInputSchema.safeParse({ path: '/workspace/a.txt' }).success).toBe(true);
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: { path: { type: 'string' } },
+    });
+
+    const result = await executeTool(tool, context({ path: '/workspace/a.txt' }));
+    expect(result.output).toBe(
+      [
+        '1\talpha',
+        '2\tbeta',
+        '<system>2 lines read from file starting from line 1. Total lines in file: 2. End of file reached.</system>',
+      ].join('\n'),
+    );
+  });
+
+  it('Write exposes parameters and writes through kaos', async () => {
+    const writeText = vi.fn().mockResolvedValue(5);
+    const tool = new WriteTool(
+      createFakeKaos({ writeText, stat: vi.fn<Kaos['stat']>().mockResolvedValue(directoryStat) }),
+      workspace,
+    );
+
+    expect(WriteInputSchema.safeParse({ path: '/workspace/a.txt', content: 'hello' }).success).toBe(
+      true,
+    );
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: { content: { type: 'string' } },
+    });
+
+    const result = await executeTool(tool, context({ path: '/workspace/a.txt', content: 'hello' }));
+    expect(writeText).toHaveBeenCalledWith('/workspace/a.txt', 'hello');
+    expect(result.output).toContain('Wrote 5 bytes');
+  });
+
+  it('Edit exposes parameters and errors when old_string is missing', async () => {
+    const tool = new EditTool(
+      createFakeKaos({ readText: vi.fn().mockResolvedValue('alpha\nbeta\n') }),
+      workspace,
+    );
+
+    expect(
+      EditInputSchema.safeParse({
+        path: '/workspace/a.txt',
+        old_string: 'gamma',
+        new_string: 'delta',
+      }).success,
+    ).toBe(true);
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: { old_string: { type: 'string' } },
+    });
+
+    const result = await executeTool(tool,
+      context({ path: '/workspace/a.txt', old_string: 'gamma', new_string: 'delta' }),
+    );
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('old_string not found');
+  });
+
+  it('Glob exposes parameters and rejects pure wildcard patterns', async () => {
+    const tool = new GlobTool(createFakeKaos(), workspace);
+
+    expect(GlobInputSchema.safeParse({ pattern: '*.ts' }).success).toBe(true);
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: { pattern: { type: 'string' } },
+    });
+
+    const result = await executeTool(tool, context({ pattern: '**' }));
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('pure wildcard');
+  });
+
+  it('Grep exposes parameters and rejects relative workspace escapes before spawning rg', async () => {
+    const kaos = createFakeKaos({ exec: vi.fn() });
+    const tool = new GrepTool(kaos, workspace);
+
+    expect(GrepInputSchema.safeParse({ pattern: 'needle' }).success).toBe(true);
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: { pattern: { type: 'string' } },
+    });
+
+    const result = await executeTool(tool, context({ pattern: 'needle', path: '../outside' }));
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('outside the working directory');
+    expect(kaos.exec).not.toHaveBeenCalled();
+  });
+
+  it('Bash exposes parameters and returns foreground stdout', async () => {
+    const tool = new BashTool(
+      createFakeKaos({ execWithEnv: vi.fn().mockResolvedValue(processWithOutput('ok\n')) }),
+      '/workspace',
+      {
+        osKind: 'Linux',
+        osArch: 'arm64',
+        osVersion: 'test',
+        shellPath: '/bin/bash',
+        shellName: 'bash',
+      },
+    );
+
+    expect(BashInputSchema.safeParse({ command: 'printf ok' }).success).toBe(true);
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: { command: { type: 'string' } },
+    });
+
+    const result = await executeTool(tool, context({ command: 'printf ok', timeout: 1000 }));
+    expect(result).toMatchObject({ output: 'ok\n' });
+  });
+});
+
+describe('current builtin collaboration tools', () => {
+  it('AskUserQuestion exposes parameters and asks through rpc in yolo mode', async () => {
+    const tool = new AskUserQuestionTool({
+      permission: { mode: 'yolo' },
+      rpc: {
+        requestQuestion: vi.fn(async () => ({ 'Which path?': 'A' })),
+      },
+      telemetry: { track: vi.fn() },
+    } as unknown as Agent);
+
+    const input = {
+      questions: [
+        {
+          question: 'Which path?',
+          header: 'Path',
+          options: [
+            { label: 'A', description: 'Use A' },
+            { label: 'B', description: 'Use B' },
+          ],
+          multi_select: false,
+        },
+      ],
+    };
+    expect(AskUserQuestionInputSchema.safeParse(input).success).toBe(true);
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: { questions: { type: 'array' } },
+    });
+
+    const result = await executeTool(tool, context(input));
+    expect(result.output).toBe(JSON.stringify({ answers: { 'Which path?': 'A' } }));
+  });
+
+  it('Agent exposes parameters and returns a foreground subagent summary', async () => {
+    const host = mockSubagentHost({
+      spawn: vi.fn().mockResolvedValue({
+        agentId: 'agent-child',
+        profileName: 'coder',
+        resumed: false,
+        completion: Promise.resolve({ result: 'child result' }),
+      }),
+    });
+    const tool = new AgentTool(host);
+
+    const input = { prompt: 'Investigate', description: 'Find cause' };
+    expect(AgentToolInputSchema.safeParse(input).success).toBe(true);
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: { prompt: { type: 'string' } },
+    });
+
+    const result = await executeTool(tool, context(input, 'call_agent'));
+    expect(host.spawn).toHaveBeenCalledWith('coder', {
+      parentToolCallId: 'call_agent',
+      prompt: 'Investigate',
+      description: 'Find cause',
+      runInBackground: false,
+      signal,
+    });
+    expect(result.output).toContain('child result');
+  });
+
+  it('Skill exposes parameters and reports unknown skills as tool errors', async () => {
+    const tool = new SkillTool({
+      skills: {
+        registry: new SkillRegistry(),
+        recordActivation: vi.fn(),
+      },
+      context: {
+        appendSystemReminder: vi.fn(),
+      },
+    } as unknown as Agent);
+
+    expect(SkillToolInputSchema.safeParse({ skill: 'missing' }).success).toBe(true);
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: { skill: { type: 'string' } },
+    });
+
+    const result = await executeTool(tool, context({ skill: 'missing' }));
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('not found');
+  });
+});
+
+describe('current builtin background tool schemas', () => {
+  it('background task schemas and manager-backed tools are covered', () => {
+    const manager = new BackgroundProcessManager();
+
+    expect(TaskListInputSchema.safeParse({ active_only: true }).success).toBe(true);
+    expect(TaskOutputInputSchema.safeParse({ task_id: 'bash-1' }).success).toBe(true);
+    expect(TaskStopInputSchema.safeParse({ task_id: 'bash-1' }).success).toBe(true);
+    expect(manager.list()).toEqual([]);
+  });
+});
diff --git a/packages/agent-core/test/tools/default-permissions.test.ts b/packages/agent-core/test/tools/default-permissions.test.ts
new file mode 100644
index 000000000..b5d9528bc
--- /dev/null
+++ b/packages/agent-core/test/tools/default-permissions.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  getBuiltinToolDefaultPermission,
+  isDefaultAutoAllowTool,
+} from '../../src/tools/policies/default-permissions';
+
+describe('builtin tool default permissions', () => {
+  it('marks read-only and interaction tools as auto-allow', () => {
+    for (const toolName of ['Read', 'Glob', 'TodoList', 'AskUserQuestion', 'Agent']) {
+      expect(isDefaultAutoAllowTool(toolName), toolName).toBe(true);
+    }
+  });
+
+  it('marks side-effectful tools as ask', () => {
+    for (const toolName of ['Bash', 'Write', 'Edit', 'TaskStop']) {
+      expect(getBuiltinToolDefaultPermission(toolName), toolName).toBe('ask');
+    }
+  });
+
+  it('leaves external and MCP tools unspecified', () => {
+    expect(getBuiltinToolDefaultPermission('mcp__server__tool')).toBeUndefined();
+    expect(isDefaultAutoAllowTool('external-tool')).toBe(false);
+  });
+});
diff --git a/packages/agent-core/test/tools/edit.test.ts b/packages/agent-core/test/tools/edit.test.ts
new file mode 100644
index 000000000..379ca173f
--- /dev/null
+++ b/packages/agent-core/test/tools/edit.test.ts
@@ -0,0 +1,413 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { type EditInput, EditInputSchema, EditTool } from '../../src/tools/builtin/file/edit';
+import { createFakeKaos, PERMISSIVE_WORKSPACE } from './fixtures/fake-kaos';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+function context(args: EditInput) {
+  return { turnId: '0', toolCallId: 'call_edit', args, signal };
+}
+
+describe('EditTool', () => {
+  it('exposes current metadata and schema', () => {
+    const tool = new EditTool(createFakeKaos(), PERMISSIVE_WORKSPACE);
+
+    expect(tool.name).toBe('Edit');
+    expect(tool.description).toContain('text view returned by Read');
+    expect(tool.description).toContain('omit the line-number prefix');
+    expect(tool.description).toContain('old_string must occur exactly once');
+    expect(tool.description).toContain('multiple Edit calls in parallel');
+    // Editing files should go through Edit, not a Shell `sed` command.
+    expect(tool.description).toContain('Shell `sed`');
+    // Parallel Edit calls on the same file are serialized and applied in
+    // response order; mismatched old_string fails explicitly.
+    expect(tool.description).toContain('they apply in the order the calls appear in your response');
+    expect(tool.description).toContain('old_string not found');
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: expect.stringContaining('working directory'),
+        },
+        old_string: {
+          type: 'string',
+          description: expect.stringContaining('without the line-number prefix'),
+        },
+        new_string: {
+          type: 'string',
+          description: expect.stringContaining('same Read output view'),
+        },
+      },
+    });
+    expect(
+      EditInputSchema.safeParse({
+        path: '/tmp/a.txt',
+        old_string: 'old',
+        new_string: 'new',
+      }).success,
+    ).toBe(true);
+    expect(
+      EditInputSchema.safeParse({
+        path: '/tmp/a.txt',
+        old_string: '',
+        new_string: 'new',
+      }).success,
+    ).toBe(false);
+  });
+
+  it('replaces a unique first occurrence and writes the updated content', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('alpha beta'),
+        writeText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/a.txt', old_string: 'beta', new_string: 'gamma' }),
+    );
+
+    expect(result.output).toContain('Replaced 1 occurrence');
+    expect(writeText).toHaveBeenCalledWith('/tmp/a.txt', 'alpha gamma');
+  });
+
+  it('expands leading tilde paths using the kaos home directory', async () => {
+    const readText = vi.fn().mockResolvedValue('alpha beta');
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(createFakeKaos({ readText, writeText }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool,
+      context({ path: '~/notes/today.txt', old_string: 'beta', new_string: 'gamma' }),
+    );
+
+    expect(result.output).toContain('Replaced 1 occurrence');
+    expect(readText).toHaveBeenCalledWith('/home/test/notes/today.txt');
+    expect(writeText).toHaveBeenCalledWith('/home/test/notes/today.txt', 'alpha gamma');
+  });
+
+  it('treats replacement dollar sequences literally for single edits', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('alpha beta gamma'),
+        writeText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/a.txt', old_string: 'beta', new_string: "$& $$ $` $'" }),
+    );
+
+    expect(result.output).toContain('Replaced 1 occurrence');
+    expect(writeText).toHaveBeenCalledWith('/tmp/a.txt', "alpha $& $$ $` $' gamma");
+  });
+
+  it('treats replacement dollar sequences literally for replace_all edits', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('a b a'),
+        writeText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/a.txt', old_string: 'a', new_string: '$&', replace_all: true }),
+    );
+
+    expect(result.output).toContain('Replaced 2 occurrences');
+    expect(writeText).toHaveBeenCalledWith('/tmp/a.txt', '$& b $&');
+  });
+
+  it('matches pure CRLF files through the LF model view and writes back CRLF', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('alpha\r\nbeta\r\ngamma\r\n'),
+        writeText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/a.txt', old_string: 'alpha\nbeta', new_string: 'one\ntwo' }),
+    );
+
+    expect(result.output).toContain('Replaced 1 occurrence');
+    expect(writeText).toHaveBeenCalledWith('/tmp/a.txt', 'one\r\ntwo\r\ngamma\r\n');
+  });
+
+  it('does not double carriage returns when editing pure CRLF files', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('alpha\r\nbeta\r\n'),
+        writeText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/a.txt', old_string: 'alpha\nbeta', new_string: 'one\r\ntwo' }),
+    );
+
+    expect(result.output).toContain('Replaced 1 occurrence');
+    expect(writeText).toHaveBeenCalledWith('/tmp/a.txt', 'one\r\ntwo\r\n');
+  });
+
+  it('keeps mixed line ending files on the raw exact path', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('alpha\r\nbeta\ngamma\r\n'),
+        writeText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/a.txt', old_string: 'alpha\nbeta', new_string: 'one\ntwo' }),
+    );
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('old_string not found');
+    expect(writeText).not.toHaveBeenCalled();
+  });
+
+  it('allows exact raw edits in mixed line ending files without normalizing the rest', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('alpha\r\nbeta\ngamma\r\n'),
+        writeText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/a.txt', old_string: 'alpha\r\nbeta', new_string: 'one\r\ntwo' }),
+    );
+
+    expect(result.output).toContain('Replaced 1 occurrence');
+    expect(writeText).toHaveBeenCalledWith('/tmp/a.txt', 'one\r\ntwo\ngamma\r\n');
+  });
+
+  it('replace_all replaces every occurrence', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('a b a'),
+        writeText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/a.txt', old_string: 'a', new_string: 'x', replace_all: true }),
+    );
+
+    expect(result.output).toContain('Replaced 2 occurrences');
+    expect(writeText).toHaveBeenCalledWith('/tmp/a.txt', 'x b x');
+  });
+
+  it('rejects no-op edits before file I/O', async () => {
+    const readText = vi.fn().mockResolvedValue('same');
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(createFakeKaos({ readText, writeText }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool,
+      context({
+        path: '/tmp/a.txt',
+        old_string: 'same',
+        new_string: 'same',
+        replace_all: true,
+      }),
+    );
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('No changes to make');
+    expect(readText).not.toHaveBeenCalled();
+    expect(writeText).not.toHaveBeenCalled();
+  });
+
+  it('errors when old_string is missing', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('alpha beta'),
+        writeText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/a.txt', old_string: 'delta', new_string: 'gamma' }),
+    );
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('old_string not found');
+    expect(writeText).not.toHaveBeenCalled();
+  });
+
+  it('errors when old_string is not unique and replace_all is false', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('same same'),
+        writeText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/a.txt', old_string: 'same', new_string: 'other' }),
+    );
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('not unique');
+    expect(result.output).toContain('set replace_all=true');
+    expect(result.output).toContain('include more surrounding context');
+    expect(writeText).not.toHaveBeenCalled();
+  });
+
+  it('rejects relative traversal edits before reading', async () => {
+    const readText = vi.fn().mockResolvedValue('secret');
+    const tool = new EditTool(createFakeKaos({ readText }), {
+      workspaceDir: '/workspace/project',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool,
+      context({ path: '../outside.txt', old_string: 'secret', new_string: 'x' }),
+    );
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('absolute path');
+    expect(readText).not.toHaveBeenCalled();
+  });
+
+  it('replaces unicode strings (CJK) and round-trips the surrounding text', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('Hello 世界! café'),
+        writeText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/u.txt', old_string: '世界', new_string: '地球' }),
+    );
+
+    expect(result.output).toContain('Replaced 1 occurrence');
+    expect(writeText).toHaveBeenCalledWith('/tmp/u.txt', 'Hello 地球! café');
+  });
+
+  it('leaves the file byte-identical when old_string is not present', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const original = 'Hello world!';
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue(original),
+        writeText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/n.txt', old_string: 'notfound', new_string: 'replacement' }),
+    );
+
+    expect(result.isError).toBe(true);
+    // Lockdown the negative side-effect: no write should have been issued.
+    expect(writeText).not.toHaveBeenCalled();
+  });
+
+  it('errors with an is-not-a-file phrasing when the path resolves to a directory', async () => {
+    // py wording is "is not a file"; TS currently relies on readText to fail.
+    // fake-kaos's notImplemented() defaults make this surface a generic
+    // readText error today — fail-divergent until the path-type check moves
+    // upstream of read.
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockRejectedValue(
+          Object.assign(new Error('EISDIR: illegal operation on a directory'), {
+            code: 'EISDIR',
+          }),
+        ),
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/dir', old_string: 'old', new_string: 'new' }),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.output).toContain('is not a file');
+  });
+
+  it('replaces a substring with an empty new_string (deletion)', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('Hello world!'),
+        writeText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/e.txt', old_string: 'world', new_string: '' }),
+    );
+
+    expect(result.output).toContain('Replaced 1 occurrence');
+    expect(writeText).toHaveBeenCalledWith('/tmp/e.txt', 'Hello !');
+  });
+
+  it('allows absolute edits outside the workspace under default policy', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('old content'),
+        writeText,
+      }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/outside.txt', old_string: 'old', new_string: 'new' }),
+    );
+
+    expect(result.isError).toBeFalsy();
+    expect(writeText).toHaveBeenCalledWith('/tmp/outside.txt', 'new content');
+  });
+
+  it('allows absolute edits to a sibling dir that merely shares the work-dir prefix', async () => {
+    // /workspace-sneaky/* is outside /workspace — string prefix check must not
+    // mistake "shares a prefix" for "inside workspace".
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new EditTool(
+      createFakeKaos({
+        readText: vi.fn().mockResolvedValue('content'),
+        writeText,
+      }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool,
+      context({ path: '/workspace-sneaky/test.txt', old_string: 'content', new_string: 'new' }),
+    );
+
+    expect(result.isError).toBeFalsy();
+    expect(writeText).toHaveBeenCalledWith('/workspace-sneaky/test.txt', 'new');
+  });
+});
diff --git a/packages/agent-core/test/tools/enter-plan-mode.test.ts b/packages/agent-core/test/tools/enter-plan-mode.test.ts
new file mode 100644
index 000000000..b7f0acead
--- /dev/null
+++ b/packages/agent-core/test/tools/enter-plan-mode.test.ts
@@ -0,0 +1,164 @@
+/**
+ * EnterPlanModeTool tests against the current Agent-backed tool surface.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Agent } from '../../src/agent';
+import type { PermissionMode } from '../../src/agent/permission';
+import {
+  EnterPlanModeInputSchema,
+  EnterPlanModeTool,
+} from '../../src/tools/builtin/planning/enter-plan-mode';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+function makeAgent(
+  input: {
+    readonly active?: boolean;
+    readonly mode?: PermissionMode;
+    readonly planFilePath?: string | null;
+    readonly enter?: () => Promise<void>;
+    readonly emit?: (event: unknown) => void;
+  } = {},
+): { agent: Agent; requestApproval: ReturnType<typeof vi.fn>; emit: ReturnType<typeof vi.fn> } {
+  let active = input.active ?? false;
+  const requestApproval = vi.fn(async () => {
+    return { decision: 'approved' };
+  });
+  const emit = vi.fn((event: unknown) => {
+    input.emit?.(event);
+    if ((event as { type?: string }).type === 'plan_mode.enter') active = true;
+  });
+  const enter =
+    input.enter ??
+    vi.fn(async () => {
+      active = true;
+    });
+  const agent = {
+    planMode: {
+      get isActive() {
+        return active;
+      },
+      get planFilePath() {
+        return input.planFilePath ?? null;
+      },
+      enter: async (id = 'mock-plan') => {
+        emit({ type: 'plan_mode.enter', id });
+        await enter();
+      },
+    },
+    permission: { mode: input.mode ?? 'manual' },
+    rpc: { requestApproval },
+    telemetry: { track: vi.fn() },
+    emit,
+  } as unknown as Agent;
+  return { agent, requestApproval, emit };
+}
+
+describe('EnterPlanModeTool', () => {
+  it('has name, description, and parameters from the current schema', () => {
+    const { agent } = makeAgent();
+    const tool = new EnterPlanModeTool(agent);
+
+    expect(tool.name).toBe('EnterPlanMode');
+    expect(tool.description.length).toBeGreaterThan(0);
+    expect(tool.description).toContain('Use it when ANY of these conditions apply');
+    expect(tool.description).toContain('New Feature Implementation');
+    expect(tool.description).toContain('When NOT to use');
+    expect(tool.description).toContain('subagent_type="explore"');
+    expect(EnterPlanModeInputSchema.safeParse({}).success).toBe(true);
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: {},
+    });
+    expect((tool.parameters['properties'] as Record<string, unknown>)['reason']).toBeUndefined();
+  });
+
+  it('returns an error when plan mode is already active', async () => {
+    const { agent } = makeAgent({ active: true });
+    const result = await executeTool(new EnterPlanModeTool(agent), {
+      turnId: '0',
+      toolCallId: 'tc_1',
+      args: {},
+      signal,
+    });
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('already active');
+  });
+
+  it.each(['manual', 'auto', 'yolo'] satisfies PermissionMode[])(
+    'enters in %s mode without an approval request',
+    async (mode) => {
+      const { agent, requestApproval, emit } = makeAgent({ mode });
+
+      const result = await executeTool(new EnterPlanModeTool(agent), {
+        turnId: '0',
+        toolCallId: `tc_${mode}`,
+        args: {},
+        signal,
+      });
+
+      expect(result.isError).toBeFalsy();
+      expect(result.output).toContain('Plan mode is now active');
+      expect(requestApproval).not.toHaveBeenCalled();
+      expect(emit).toHaveBeenCalledWith({ type: 'plan_mode.enter', id: expect.any(String) });
+    },
+  );
+
+  it('uses inline guidance when no plan file path is available', async () => {
+    const { agent } = makeAgent({ mode: 'yolo', planFilePath: null });
+
+    const result = await executeTool(new EnterPlanModeTool(agent), {
+      turnId: '0',
+      toolCallId: 'tc_inline',
+      args: {},
+      signal,
+    });
+
+    expect(result.output).toContain('host to provide a plan file path');
+    expect(result.output).not.toContain('`plan` parameter');
+    expect(result.output).not.toContain('Write the plan to the plan file');
+  });
+
+  it('uses plan-file guidance when the host provides a plan file path', async () => {
+    const { agent } = makeAgent({ mode: 'yolo', planFilePath: '/tmp/kimi/plans/example.md' });
+
+    const result = await executeTool(new EnterPlanModeTool(agent), {
+      turnId: '0',
+      toolCallId: 'tc_file',
+      args: {},
+      signal,
+    });
+
+    expect(result.output).toContain('Plan file: /tmp/kimi/plans/example.md');
+    expect(result.output).toContain('Write the plan to the plan file');
+  });
+
+  it('returns an error when entering plan mode fails', async () => {
+    const { agent } = makeAgent({
+      mode: 'yolo',
+      enter: vi.fn().mockRejectedValue(new Error('state error')),
+    });
+
+    const result = await executeTool(new EnterPlanModeTool(agent), {
+      turnId: '0',
+      toolCallId: 'tc_error',
+      args: {},
+      signal,
+    });
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('state error');
+  });
+
+  it('resolveExecution description returns a stable phrase', () => {
+    const { agent } = makeAgent();
+    const execution = new EnterPlanModeTool(agent).resolveExecution({});
+    expect(execution.isError).toBeFalsy();
+    if (execution.isError === true) throw new Error('expected runnable execution');
+    expect(execution.description).toContain('plan mode');
+  });
+});
diff --git a/packages/agent-core/test/tools/exit-plan-mode-options.test.ts b/packages/agent-core/test/tools/exit-plan-mode-options.test.ts
new file mode 100644
index 000000000..5443e8c80
--- /dev/null
+++ b/packages/agent-core/test/tools/exit-plan-mode-options.test.ts
@@ -0,0 +1,279 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Agent } from '../../src/agent';
+import {
+  ExitPlanModeInputSchema,
+  ExitPlanModeTool,
+  type ExitPlanModeInput,
+} from '../../src/tools/builtin/planning/exit-plan-mode';
+import DESCRIPTION from '../../src/tools/builtin/planning/exit-plan-mode.md';
+import { executeTool } from './fixtures/execute-tool';
+import { toolContentString } from './fixtures/fake-kaos';
+
+const signal = new AbortController().signal;
+
+const options = [
+  { label: 'Approach A', description: 'Use the smaller refactor.' },
+  { label: 'Approach B', description: 'Use the more complete refactor.' },
+] satisfies NonNullable<ExitPlanModeInput['options']>;
+
+function makeAgent(
+  input: {
+    readonly active?: boolean | undefined;
+    readonly plan?: string | null | undefined;
+    readonly path?: string | undefined;
+    readonly planFilePath?: string | null | undefined;
+    readonly emit?: ((event: unknown) => void) | undefined;
+  } = {},
+): { agent: Agent; requestApproval: ReturnType<typeof vi.fn>; emit: ReturnType<typeof vi.fn> } {
+  let active = input.active ?? true;
+  const requestApproval = vi.fn(async () => ({ decision: 'approved' }));
+  const emit = vi.fn((event: unknown) => {
+    input.emit?.(event);
+    if ((event as { type?: string }).type === 'plan_mode.exit') active = false;
+  });
+  const agent = {
+    planMode: {
+      get isActive() {
+        return active;
+      },
+      get planFilePath() {
+        return input.planFilePath ?? null;
+      },
+      data: vi.fn(async () => {
+        if (input.plan === null) return null;
+        return {
+          content: input.plan ?? 'plan from file',
+          path: input.path ?? '/tmp/plan.md',
+        };
+      }),
+      exit: () => {
+        emit({ type: 'plan_mode.exit' });
+      },
+    },
+    rpc: { requestApproval },
+    telemetry: { track: vi.fn() },
+    emit,
+  } as unknown as Agent;
+  return { agent, requestApproval, emit };
+}
+
+function execute(
+  tool: ExitPlanModeTool,
+  args: ExitPlanModeInput,
+  metadata?: unknown,
+) {
+  return executeTool(tool, {
+    turnId: '7',
+    toolCallId: 'call_exit_plan',
+    args,
+    metadata,
+    signal,
+  });
+}
+
+describe('ExitPlanMode options schema', () => {
+  it('accepts 1-3 options and rejects inline plan fallback', () => {
+    expect(
+      ExitPlanModeInputSchema.safeParse({
+        options: [{ label: 'A', description: 'do A' }],
+      }).success,
+    ).toBe(true);
+    expect(
+      ExitPlanModeInputSchema.safeParse({
+        options: [
+          { label: 'A', description: 'do A' },
+          { label: 'B', description: 'do B' },
+          { label: 'C', description: 'do C' },
+        ],
+      }).success,
+    ).toBe(true);
+    expect(ExitPlanModeInputSchema.safeParse({}).success).toBe(true);
+    expect(ExitPlanModeInputSchema.safeParse({ plan: 'Plan' }).success).toBe(false);
+  });
+
+  it('rejects too many options, duplicate labels, reserved labels, and invalid labels', () => {
+    expect(
+      ExitPlanModeInputSchema.safeParse({
+        options: [
+          { label: 'A', description: 'x' },
+          { label: 'B', description: 'x' },
+          { label: 'C', description: 'x' },
+          { label: 'D', description: 'x' },
+        ],
+      }).success,
+    ).toBe(false);
+    expect(
+      ExitPlanModeInputSchema.safeParse({
+        options: [{ label: '', description: 'x' }],
+      }).success,
+    ).toBe(false);
+    expect(
+      ExitPlanModeInputSchema.safeParse({
+        options: [{ label: 'a'.repeat(81), description: 'x' }],
+      }).success,
+    ).toBe(false);
+    expect(
+      ExitPlanModeInputSchema.safeParse({
+        options: [
+          { label: 'A', description: 'x' },
+          { label: 'A', description: 'y' },
+        ],
+      }).success,
+    ).toBe(false);
+    expect(
+      ExitPlanModeInputSchema.safeParse({
+        options: [{ label: 'Reject', description: 'reserved' }],
+      }).success,
+    ).toBe(false);
+    expect(
+      ExitPlanModeInputSchema.safeParse({
+        options: [{ label: 'reject', description: 'reserved' }],
+      }).success,
+    ).toBe(false);
+    expect(
+      ExitPlanModeInputSchema.safeParse({
+        options: [{ label: '  Reject  ', description: 'reserved' }],
+      }).success,
+    ).toBe(false);
+    expect(
+      ExitPlanModeInputSchema.safeParse({
+        options: [
+          { label: 'Patch config', description: 'x' },
+          { label: '  patch CONFIG  ', description: 'y' },
+        ],
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe('ExitPlanMode option output', () => {
+  it('uses permission metadata to report the selected option', async () => {
+    const { agent, requestApproval, emit } = makeAgent({
+      plan: 'plan from file',
+    });
+
+    const result = await execute(
+      new ExitPlanModeTool(agent),
+      { options },
+      {
+        selectedOption: options[1],
+      },
+    );
+
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(emit).toHaveBeenCalledWith({ type: 'plan_mode.exit' });
+    expect(result).toMatchObject({ isError: false });
+    expect(result.output).toContain('Selected approach: Approach B');
+    expect(result.output).toContain('Execute ONLY the selected approach');
+    expect(result.output).toContain('plan from file');
+  });
+
+  it('treats a single option as plain plan approval', async () => {
+    const { agent, requestApproval, emit } = makeAgent({
+      plan: 'single option plan',
+    });
+
+    const result = await execute(new ExitPlanModeTool(agent), {
+      options: [{ label: 'Approach A', description: 'Only path' }],
+    });
+
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(emit).toHaveBeenCalledWith({ type: 'plan_mode.exit' });
+    expect(result.output).toContain('Exited plan mode');
+  });
+
+  it('does not use inline plan fallback for option approval when no plan file exists', async () => {
+    const { agent, requestApproval, emit } = makeAgent({
+      plan: null,
+    });
+
+    const result = await execute(new ExitPlanModeTool(agent), {
+      options,
+    });
+
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(emit).not.toHaveBeenCalled();
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('No plan file found');
+  });
+
+  it('returns success without a "User feedback:" prefix when revise has no feedback', async () => {
+    const { agent } = makeAgent({ plan: 'draft plan' });
+
+    const result = await execute(new ExitPlanModeTool(agent), { options });
+
+    expect(result.isError).toBeFalsy();
+    expect(toolContentString(result)).not.toContain('User feedback:');
+  });
+});
+
+describe('ExitPlanMode reserved-label validation', () => {
+  it('rejects reserved label "Reject"', () => {
+    const parsed = ExitPlanModeInputSchema.safeParse({
+      options: [{ label: 'Reject', description: 'x' }],
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('rejects reserved label "reject" case-insensitively', () => {
+    const parsed = ExitPlanModeInputSchema.safeParse({
+      options: [{ label: 'reject', description: 'x' }],
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('rejects reserved label "Revise"', () => {
+    const parsed = ExitPlanModeInputSchema.safeParse({
+      options: [{ label: 'Revise', description: 'x' }],
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('rejects reserved label "Approve"', () => {
+    const parsed = ExitPlanModeInputSchema.safeParse({
+      options: [{ label: 'Approve', description: 'x' }],
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('rejects reserved label after whitespace trim ("  Reject  ")', () => {
+    const parsed = ExitPlanModeInputSchema.safeParse({
+      options: [{ label: '  Reject  ', description: 'x' }],
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it('rejects duplicate option labels (case-insensitive uniqueness)', () => {
+    const parsed = ExitPlanModeInputSchema.safeParse({
+      options: [
+        { label: 'Patch config', description: '' },
+        { label: 'patch config', description: 'different desc' },
+      ],
+    });
+    expect(parsed.success).toBe(false);
+  });
+});
+
+describe('ExitPlanMode options documentation consistency', () => {
+  function optionsParamDescription(): string {
+    const tool = new ExitPlanModeTool({} as Agent);
+    const parameters = tool.parameters as {
+      properties?: { options?: { description?: string } };
+    };
+    const description = parameters.properties?.options?.description;
+    expect(typeof description).toBe('string');
+    return description as string;
+  }
+
+  it('does not advertise a 2-3 option minimum that contradicts the minItems:1 schema', () => {
+    expect(DESCRIPTION).not.toMatch(/2-3 options/);
+    expect(optionsParamDescription()).not.toMatch(/2-3 options/);
+  });
+
+  it('documents that a single option is equivalent to a plain plan approval', () => {
+    expect(DESCRIPTION).toMatch(/single option/i);
+    expect(DESCRIPTION).toMatch(/plain plan approval/i);
+    expect(optionsParamDescription()).toMatch(/single option/i);
+  });
+});
diff --git a/packages/agent-core/test/tools/exit-plan-mode.test.ts b/packages/agent-core/test/tools/exit-plan-mode.test.ts
new file mode 100644
index 000000000..301640f76
--- /dev/null
+++ b/packages/agent-core/test/tools/exit-plan-mode.test.ts
@@ -0,0 +1,216 @@
+/**
+ * ExitPlanModeTool tests against the current Agent-backed tool surface.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Agent } from '../../src/agent';
+import {
+  ExitPlanModeInputSchema,
+  ExitPlanModeTool,
+} from '../../src/tools/builtin/planning/exit-plan-mode';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+function makeAgent(
+  input: {
+    readonly active?: boolean | undefined;
+    readonly plan?: string | null | undefined;
+    readonly path?: string | undefined;
+    readonly planFilePath?: string | null | undefined;
+    readonly emit?: ((event: unknown) => void) | undefined;
+  } = {},
+): { agent: Agent; requestApproval: ReturnType<typeof vi.fn>; emit: ReturnType<typeof vi.fn> } {
+  let active = input.active ?? true;
+  const requestApproval = vi.fn(async () => ({ decision: 'approved' }));
+  const emit = vi.fn((event: unknown) => {
+    input.emit?.(event);
+    if ((event as { type?: string }).type === 'plan_mode.exit') active = false;
+  });
+  const agent = {
+    planMode: {
+      get isActive() {
+        return active;
+      },
+      get planFilePath() {
+        return input.planFilePath ?? null;
+      },
+      data: vi.fn(async () => {
+        if (input.plan === null) return null;
+        return {
+          content: input.plan ?? 'Step 1: read files\nStep 2: fix bug',
+          path: input.path ?? '/tmp/kimi-plan.md',
+        };
+      }),
+      exit: () => {
+        emit({ type: 'plan_mode.exit' });
+      },
+    },
+    rpc: { requestApproval },
+    telemetry: { track: vi.fn() },
+    emit,
+  } as unknown as Agent;
+  return { agent, requestApproval, emit };
+}
+
+describe('ExitPlanModeTool', () => {
+  it('has name, description, and parameters from the current schema', () => {
+    const { agent } = makeAgent();
+    const tool = new ExitPlanModeTool(agent);
+
+    expect(tool.name).toBe('ExitPlanMode');
+    expect(tool.description.length).toBeGreaterThan(0);
+    expect(tool.description).toContain('This tool does NOT take the plan content as a parameter');
+    expect(tool.description).toContain('For research tasks');
+    expect(tool.description).toContain('append "(Recommended)"');
+    expect(tool.description).toContain('If rejected, revise based on feedback');
+    expect(ExitPlanModeInputSchema.safeParse({}).success).toBe(true);
+    expect(ExitPlanModeInputSchema.safeParse({ plan: '' }).success).toBe(false);
+    expect(ExitPlanModeInputSchema.safeParse({ plan: 'a plan' }).success).toBe(false);
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: {
+        options: { type: 'array' },
+      },
+    });
+    const optionsSchema = (tool.parameters['properties'] as Record<string, unknown>)[
+      'options'
+    ] as {
+      description?: string;
+      items?: {
+        properties?: Record<string, { description?: string }>;
+      };
+    };
+    expect(optionsSchema.description).toContain('up to 3 options');
+    expect(optionsSchema.description).toContain('single option');
+    expect(optionsSchema.items?.properties?.['label']?.description).toContain('(Recommended)');
+    expect(optionsSchema.items?.properties?.['description']?.description).toContain('trade-offs');
+    expect((tool.parameters['properties'] as Record<string, unknown>)['plan']).toBeUndefined();
+  });
+
+  it('refuses to exit when plan mode is inactive', async () => {
+    const { agent, emit } = makeAgent({ active: false });
+
+    const result = await executeTool(new ExitPlanModeTool(agent), {
+      turnId: '0',
+      toolCallId: 'call_1',
+      args: {},
+      signal,
+    });
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('plan mode');
+    expect(emit).not.toHaveBeenCalled();
+  });
+
+  it('exits with the current plan without consulting permission approval', async () => {
+    const { agent, requestApproval, emit } = makeAgent({
+      plan: '# File Plan',
+      path: '/tmp/kimi-plan.md',
+    });
+
+    const result = await executeTool(new ExitPlanModeTool(agent), {
+      turnId: '0',
+      toolCallId: 'call_1',
+      args: {},
+      signal,
+    });
+
+    expect(result.isError).toBe(false);
+    expect(requestApproval).not.toHaveBeenCalled();
+    expect(emit).toHaveBeenCalledWith({ type: 'plan_mode.exit' });
+    expect(result.output).toContain('Plan saved to: /tmp/kimi-plan.md');
+    expect(result.output).toContain('# File Plan');
+  });
+
+  it('does not use inline plan fallback when no plan file exists', async () => {
+    const { agent, emit } = makeAgent({ plan: null });
+
+    const result = await executeTool(new ExitPlanModeTool(agent), {
+      turnId: '0',
+      toolCallId: 'call_inline',
+      args: {},
+      signal,
+    });
+
+    expect(result.isError).toBe(true);
+    expect(emit).not.toHaveBeenCalled();
+    expect(result.output).toContain('No plan file found');
+  });
+
+  it('returns an error when no plan content is available', async () => {
+    const { agent, emit } = makeAgent({
+      plan: '',
+      path: '/tmp/kimi-plan.md',
+    });
+
+    const result = await executeTool(new ExitPlanModeTool(agent), {
+      turnId: '0',
+      toolCallId: 'call_empty',
+      args: {},
+      signal,
+    });
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('Write your plan to /tmp/kimi-plan.md first');
+    expect(emit).not.toHaveBeenCalled();
+  });
+
+  it('surfaces errors from plan exit as a tool error', async () => {
+    const { agent } = makeAgent({
+      emit: () => {
+        throw new Error('journal write failed');
+      },
+    });
+
+    const result = await executeTool(new ExitPlanModeTool(agent), {
+      turnId: '0',
+      toolCallId: 'call_fail',
+      args: {},
+      signal,
+    });
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('journal write failed');
+  });
+});
+
+describe('ExitPlanMode option description optionality', () => {
+  it('exposes options[].description as optional with a default of empty string', () => {
+    const { agent } = makeAgent();
+    const tool = new ExitPlanModeTool(agent);
+
+    const optionItems = (
+      (tool.parameters['properties'] as Record<string, unknown>)['options'] as {
+        items?: {
+          required?: readonly string[];
+          properties?: Record<string, { default?: unknown }>;
+        };
+      }
+    ).items;
+
+    expect(optionItems?.required).toEqual(['label']);
+    expect(optionItems?.required).not.toContain('description');
+    expect(optionItems?.properties?.['description']?.default).toBe('');
+  });
+
+  it('accepts an option that omits description', () => {
+    const result = ExitPlanModeInputSchema.safeParse({
+      options: [{ label: 'Approach A' }],
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('defaults a missing option description to an empty string', () => {
+    const result = ExitPlanModeInputSchema.safeParse({
+      options: [{ label: 'Approach A' }],
+    });
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.options?.[0]?.description).toBe('');
+    }
+  });
+});
diff --git a/packages/agent-core/test/tools/fetch-url.test.ts b/packages/agent-core/test/tools/fetch-url.test.ts
new file mode 100644
index 000000000..0e5c55ee6
--- /dev/null
+++ b/packages/agent-core/test/tools/fetch-url.test.ts
@@ -0,0 +1,288 @@
+/**
+ * Covers: FetchURLTool.
+ *
+ * Uses a fake UrlFetcher to test tool behaviour in isolation.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  FetchURLInputSchema,
+  FetchURLTool,
+  HttpFetchError,
+  type UrlFetcher,
+} from '../../src/tools/builtin/web/fetch-url';
+import { MoonshotFetchURLProvider } from '../../src/tools/providers/moonshot-fetch-url';
+import { toolContentString } from './fixtures/fake-kaos';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+function fakeFetcher(
+  content = '',
+  kind: 'passthrough' | 'extracted' = 'extracted',
+): UrlFetcher {
+  return { fetch: vi.fn().mockResolvedValue({ content, kind }) };
+}
+
+describe('FetchURLTool', () => {
+  it('has name "FetchURL" and a non-empty description', () => {
+    const tool = new FetchURLTool(fakeFetcher());
+    expect(tool.name).toBe('FetchURL');
+    expect(tool.description.length).toBeGreaterThan(0);
+  });
+
+  it('parameters are generated from the current input schema', () => {
+    const tool = new FetchURLTool(fakeFetcher());
+    expect(FetchURLInputSchema.safeParse({ url: 'https://example.com' }).success).toBe(true);
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: {
+        url: { type: 'string' },
+      },
+    });
+  });
+
+  it('does not expose a "format" parameter in its JSON Schema', () => {
+    const tool = new FetchURLTool(fakeFetcher());
+    const properties = (tool.parameters as { properties?: Record<string, unknown> }).properties;
+    expect(properties).toBeDefined();
+    expect(properties).not.toHaveProperty('format');
+  });
+
+  it('returns fetched content from provider', async () => {
+    const tool = new FetchURLTool(fakeFetcher('Hello, world!'));
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c1',
+      args: { url: 'https://example.com' },
+      signal,
+    });
+    expect(result.isError).toBe(false);
+    expect(toolContentString(result)).toBe('Hello, world!');
+  });
+
+  it('reports an extraction-specific message for extracted content', async () => {
+    const tool = new FetchURLTool(fakeFetcher('Article body', 'extracted'));
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c-extracted',
+      args: { url: 'https://example.com/article' },
+      signal,
+    });
+    expect(result.isError).toBe(false);
+    expect((result as { message?: string }).message).toBe(
+      'The returned content is the main text extracted from the page.',
+    );
+  });
+
+  it('reports a passthrough-specific message for verbatim content', async () => {
+    const tool = new FetchURLTool(fakeFetcher('# Raw markdown', 'passthrough'));
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c-passthrough',
+      args: { url: 'https://example.com/readme.md' },
+      signal,
+    });
+    expect(result.isError).toBe(false);
+    expect((result as { message?: string }).message).toBe(
+      'The returned content is the full response body, returned verbatim.',
+    );
+  });
+
+  it('returns empty message when fetcher returns empty string', async () => {
+    const tool = new FetchURLTool(fakeFetcher(''));
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c2',
+      args: { url: 'https://example.com/empty' },
+      signal,
+    });
+    expect(result.isError).toBe(false);
+    expect(toolContentString(result)).toContain('empty');
+  });
+
+  it('truncates oversized fetched content through the shared builder', async () => {
+    const tool = new FetchURLTool(fakeFetcher('x'.repeat(60_000)));
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c-large',
+      args: { url: 'https://example.com/large' },
+      signal,
+    });
+
+    const content = toolContentString(result);
+    expect(result.isError).toBe(false);
+    expect(content).toContain('[...truncated]');
+    expect(content).toContain('Output is truncated');
+    expect(content.length).toBeLessThan(60_000);
+    expect((result as { message?: string }).message).toContain('Output is truncated');
+  });
+
+  it('returns error when fetcher throws', async () => {
+    const fetcher: UrlFetcher = {
+      fetch: vi.fn().mockRejectedValue(new Error('timeout')),
+    };
+    const tool = new FetchURLTool(fetcher);
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c3',
+      args: { url: 'https://example.com/fail' },
+      signal,
+    });
+    expect(result.isError).toBe(true);
+    expect(toolContentString(result)).toContain('timeout');
+  });
+
+  it('passes the tool call id to the fetcher', async () => {
+    const fetcher = fakeFetcher('content');
+    const tool = new FetchURLTool(fetcher);
+    await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c4',
+      args: { url: 'https://example.com' },
+      signal,
+    });
+    expect(fetcher.fetch).toHaveBeenCalledWith('https://example.com', {
+      toolCallId: 'c4',
+    });
+  });
+
+  it('resolveExecution description truncates long URLs', () => {
+    const tool = new FetchURLTool(fakeFetcher());
+    const execution = tool.resolveExecution({ url: 'https://example.com/' + 'a'.repeat(60) });
+    expect(execution.isError).toBeFalsy();
+    if (execution.isError === true) throw new Error('expected runnable execution');
+    const desc = execution.description;
+    const text = desc ?? '';
+    expect(text.length).toBeLessThanOrEqual(65);
+    expect(text).toContain('…');
+  });
+
+  it('description names URL fetching as the tool surface', () => {
+    const tool = new FetchURLTool(fakeFetcher());
+    expect(tool.description).toContain('URL');
+    expect(tool.description.toLowerCase()).toContain('fetch');
+  });
+
+  it('extracts visible article text and metadata from an HTML page, stripping tags', async () => {
+    // The host provider is responsible for HTML→text extraction. Lock down
+    // that when the fetcher returns trafilatura-style cleaned text, the tool
+    // forwards it verbatim and keeps the meaningful tokens (no raw tags).
+    const extracted = [
+      'title: Sample Bug Report',
+      'description: The default value should be lowercase.',
+      '',
+      'Sample Bug Report',
+      'The default parameter value for optimizer should probably be adamw instead of adamW.',
+    ].join('\n');
+    const tool = new FetchURLTool(fakeFetcher(extracted));
+
+    const result = await executeTool(tool,{
+      turnId: 't1',
+      toolCallId: 'c_html',
+      args: { url: 'https://example.com/bug' },
+      signal,
+    });
+
+    expect(result.isError).toBe(false);
+    const content = toolContentString(result);
+    expect(content).toContain('optimizer');
+    expect(content).toContain('adamw');
+    expect(content).toContain('adamW');
+    expect(content).not.toContain('<article>');
+    expect(content).not.toContain('<code>');
+    expect(content.toLowerCase()).toContain('title:');
+    expect(content.toLowerCase()).toContain('description:');
+  });
+
+  it('surfaces HTTP status in the error message for 404 responses', async () => {
+    // py contract: "Failed to fetch URL. Status: 404. ..." Fetcher signals
+    // the HTTP status via a typed HttpFetchError; tool renders Status: N.
+    const fetcher: UrlFetcher = {
+      fetch: vi.fn().mockRejectedValue(new HttpFetchError(404, 'Not Found')),
+    };
+    const tool = new FetchURLTool(fetcher);
+
+    const result = await executeTool(tool,{
+      turnId: 't1',
+      toolCallId: 'c_404',
+      args: { url: 'https://example.com/missing' },
+      signal,
+    });
+
+    expect(result.isError).toBe(true);
+    expect(toolContentString(result)).toContain('Status: 404');
+  });
+
+  it('reports the empty URL verbatim in the error message', async () => {
+    // py renders: "Failed to fetch URL due to network error: . ..." with the
+    // empty URL surfaced where the URL would normally go.
+    const fetcher: UrlFetcher = {
+      fetch: vi.fn().mockRejectedValue(new Error('network error: ')),
+    };
+    const tool = new FetchURLTool(fetcher);
+
+    const result = await executeTool(tool,{
+      turnId: 't1',
+      toolCallId: 'c_empty',
+      args: { url: '' },
+      signal,
+    });
+
+    expect(result.isError).toBe(true);
+    expect(toolContentString(result)).toMatch(/due to network error/i);
+  });
+
+  it('passes through markdown content verbatim instead of running text extraction', async () => {
+    // py: when the server returns text/markdown, extraction is skipped and
+    // the body is returned as-is with a different status message. The
+    // fetcher signals the bypass via UrlFetchResult.kind = 'passthrough'.
+    const markdown = '# Title\n\nThis is a markdown document.\n';
+    const fetcher: UrlFetcher = {
+      fetch: vi.fn().mockResolvedValue({ content: markdown, kind: 'passthrough' }),
+    };
+    const tool = new FetchURLTool(fetcher);
+
+    const result = await executeTool(tool,{
+      turnId: 't1',
+      toolCallId: 'c_md',
+      args: { url: 'https://example.com/page.md' },
+      signal,
+    });
+
+    expect(result.isError).toBe(false);
+    expect(toolContentString(result)).toBe(markdown);
+    // The passthrough message says the LLM is seeing the full response
+    // body (py wording was "full content"; main #238 uses the broader
+    // "full response body" phrasing).
+    const message = (result as { message?: string }).message ?? '';
+    expect(message).toContain('full response body');
+  });
+});
+
+describe('MoonshotFetchURLProvider', () => {
+  it('does not force-refresh request auth after a 401 response', async () => {
+    const getAccessToken = vi.fn().mockResolvedValue('fresh-token');
+    const localFallback = fakeFetcher('fallback content');
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(new Response('unauthorized', { status: 401 }));
+    const provider = new MoonshotFetchURLProvider({
+      tokenProvider: { getAccessToken },
+      baseUrl: 'https://fetch.example/v1',
+      localFallback,
+      fetchImpl,
+    });
+
+    await expect(provider.fetch('https://example.com/page')).resolves.toEqual({
+      content: 'fallback content',
+      kind: 'extracted',
+    });
+
+    expect(getAccessToken).toHaveBeenCalledTimes(1);
+    expect(getAccessToken).toHaveBeenCalledWith();
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    expect(localFallback.fetch).toHaveBeenCalledWith('https://example.com/page', {});
+  });
+});
diff --git a/packages/agent-core/test/tools/file-type.test.ts b/packages/agent-core/test/tools/file-type.test.ts
new file mode 100644
index 000000000..43e92e947
--- /dev/null
+++ b/packages/agent-core/test/tools/file-type.test.ts
@@ -0,0 +1,481 @@
+/**
+ * file-type — magic-byte + extension detection.
+ *
+ * Tests pin:
+ *   - magic-byte recognition for PNG / JPEG / GIF / WebP / AVIF /
+ *     MP4 ftyp / MKV / AVI
+ *   - extension lookup for each `IMAGE_MIME_BY_SUFFIX` / `VIDEO_MIME_BY_SUFFIX`
+ *   - NUL bytes → unknown
+ *   - extension hints a different kind than sniff → unknown
+ *   - `NON_TEXT_SUFFIXES` lookup returns unknown (so binaries aren't
+ *     treated as text on a blind read)
+ *   - no header provided → extension-only detection
+ */
+
+import { describe, expect, it } from 'vitest';
+
+// eslint-disable-next-line import/no-unresolved
+import {
+  detectFileType,
+  sniffImageDimensions,
+  sniffMediaFromMagic,
+  MEDIA_SNIFF_BYTES,
+  IMAGE_MIME_BY_SUFFIX,
+  VIDEO_MIME_BY_SUFFIX,
+  NON_TEXT_SUFFIXES,
+  type FileType,
+  type ImageDimensions,
+} from '../../src/tools/support/file-type';
+
+describe('sniffMediaFromMagic', () => {
+  it('recognises PNG magic bytes', () => {
+    const header = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0]);
+    expect(sniffMediaFromMagic(header)).toEqual<FileType>({
+      kind: 'image',
+      mimeType: 'image/png',
+    });
+  });
+
+  it('recognises JPEG magic bytes', () => {
+    const header = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0, 0]);
+    expect(sniffMediaFromMagic(header)).toEqual<FileType>({
+      kind: 'image',
+      mimeType: 'image/jpeg',
+    });
+  });
+
+  it('recognises GIF87a and GIF89a magic bytes', () => {
+    expect(sniffMediaFromMagic(Buffer.from('GIF87a\0\0', 'binary'))).toEqual<FileType>({
+      kind: 'image',
+      mimeType: 'image/gif',
+    });
+    expect(sniffMediaFromMagic(Buffer.from('GIF89a\0\0', 'binary'))).toEqual<FileType>({
+      kind: 'image',
+      mimeType: 'image/gif',
+    });
+  });
+
+  it('recognises WebP magic bytes (RIFF…WEBP)', () => {
+    const header = Buffer.concat([
+      Buffer.from('RIFF'),
+      Buffer.from([0, 0, 0, 0]),
+      Buffer.from('WEBP'),
+    ]);
+    expect(sniffMediaFromMagic(header)).toEqual<FileType>({
+      kind: 'image',
+      mimeType: 'image/webp',
+    });
+  });
+
+  it('recognises AVIF via ftyp brand', () => {
+    const header = Buffer.concat([
+      Buffer.from([0, 0, 0, 0x20]),
+      Buffer.from('ftyp'),
+      Buffer.from('avif'),
+      Buffer.alloc(16),
+    ]);
+    expect(sniffMediaFromMagic(header)).toEqual<FileType>({
+      kind: 'image',
+      mimeType: 'image/avif',
+    });
+  });
+
+  it('recognises MP4 via ftyp mp42/isom brand', () => {
+    const header = Buffer.concat([
+      Buffer.from([0, 0, 0, 0x18]),
+      Buffer.from('ftyp'),
+      Buffer.from('mp42'),
+      Buffer.from([0, 0, 0, 0]),
+      Buffer.from('mp42isom'),
+    ]);
+    const result = sniffMediaFromMagic(header);
+    expect(result?.kind).toBe('video');
+    expect(result?.mimeType).toBe('video/mp4');
+  });
+
+  it('recognises Matroska / WebM via EBML header', () => {
+    const ebml = Buffer.from([0x1a, 0x45, 0xdf, 0xa3]);
+    const matroskaHeader = Buffer.concat([ebml, Buffer.from('.matroska.', 'binary')]);
+    expect(sniffMediaFromMagic(matroskaHeader)).toEqual<FileType>({
+      kind: 'video',
+      mimeType: 'video/x-matroska',
+    });
+    const webmHeader = Buffer.concat([ebml, Buffer.from('.webm.', 'binary')]);
+    expect(sniffMediaFromMagic(webmHeader)).toEqual<FileType>({
+      kind: 'video',
+      mimeType: 'video/webm',
+    });
+  });
+
+  it('recognises AVI via RIFF…AVI ', () => {
+    const header = Buffer.concat([
+      Buffer.from('RIFF'),
+      Buffer.from([0, 0, 0, 0]),
+      Buffer.from('AVI '),
+    ]);
+    expect(sniffMediaFromMagic(header)).toEqual<FileType>({
+      kind: 'video',
+      mimeType: 'video/x-msvideo',
+    });
+  });
+
+  it('returns null for unrecognised magic bytes', () => {
+    expect(sniffMediaFromMagic(Buffer.from('plain text content'))).toBeNull();
+  });
+
+  it('uses MEDIA_SNIFF_BYTES as the header slice size ceiling', () => {
+    // Typed constant guard.
+    expect(MEDIA_SNIFF_BYTES).toBe(512);
+  });
+});
+
+describe('detectFileType', () => {
+  it('resolves images by extension when no header is given', () => {
+    expect(detectFileType('foo.png')).toEqual<FileType>({
+      kind: 'image',
+      mimeType: 'image/png',
+    });
+    expect(detectFileType('foo.JPG')).toEqual<FileType>({
+      kind: 'image',
+      mimeType: 'image/jpeg',
+    });
+    expect(detectFileType('foo.heic')).toEqual<FileType>({
+      kind: 'image',
+      mimeType: 'image/heic',
+    });
+  });
+
+  it('resolves videos by extension when no header is given', () => {
+    expect(detectFileType('foo.mp4')).toEqual<FileType>({
+      kind: 'video',
+      mimeType: 'video/mp4',
+    });
+    expect(detectFileType('foo.mpg')).toEqual<FileType>({
+      kind: 'video',
+      mimeType: 'video/mpeg',
+    });
+    expect(detectFileType('foo.mpeg')).toEqual<FileType>({
+      kind: 'video',
+      mimeType: 'video/mpeg',
+    });
+    expect(detectFileType('foo.mkv')).toEqual<FileType>({
+      kind: 'video',
+      mimeType: 'video/x-matroska',
+    });
+    expect(detectFileType('foo.ogv')).toEqual<FileType>({
+      kind: 'video',
+      mimeType: 'video/ogg',
+    });
+    expect(detectFileType('foo.mov')).toEqual<FileType>({
+      kind: 'video',
+      mimeType: 'video/quicktime',
+    });
+  });
+
+  it('treats .svg (text) as text, not image, even though the MIME is image/*', () => {
+    // SVG is XML text even though its MIME says `image/svg+xml`.
+    const result = detectFileType('pic.svg');
+    expect(result.kind).toBe('text');
+    expect(result.mimeType).toBe('image/svg+xml');
+  });
+
+  it('NUL byte in header → unknown (binary signal)', () => {
+    const header = Buffer.concat([Buffer.from('partial'), Buffer.from([0x00, 0x00])]);
+    const result = detectFileType('mystery.bin', header);
+    expect(result.kind).toBe('unknown');
+  });
+
+  it('extension + sniff disagree → unknown', () => {
+    // `.mp4` extension but JPEG magic bytes — when the mime types
+    // disagree we refuse to guess and return `unknown`.
+    const jpegHeader = Buffer.from([0xff, 0xd8, 0xff, 0xe0]);
+    const result = detectFileType('mismatch.mp4', jpegHeader);
+    expect(result.kind).toBe('unknown');
+  });
+
+  it('extension in NON_TEXT_SUFFIXES → unknown', () => {
+    // A `.zip` file with no header and no image/video hint must not
+    // be treated as text.
+    const result = detectFileType('archive.zip');
+    expect(result.kind).toBe('unknown');
+  });
+
+  it('falls back to plain text for unknown suffix with no magic bytes', () => {
+    const result = detectFileType('README');
+    expect(result.kind).toBe('text');
+    expect(result.mimeType).toBe('text/plain');
+  });
+
+  it('exposes the suffix maps as readonly records', () => {
+    expect(IMAGE_MIME_BY_SUFFIX['.png']).toBe('image/png');
+    expect(VIDEO_MIME_BY_SUFFIX['.mkv']).toBe('video/x-matroska');
+    expect(NON_TEXT_SUFFIXES.has('.pdf')).toBe(true);
+    expect(NON_TEXT_SUFFIXES.has('.zip')).toBe(true);
+    expect(NON_TEXT_SUFFIXES.has('.dll')).toBe(true);
+  });
+
+  it('classifies common suffixes, dotfiles, and case-insensitive variants', () => {
+    expect(detectFileType('image.PNG').kind).toBe('image');
+    expect(detectFileType('clip.mp4').kind).toBe('video');
+    expect(detectFileType('notes.txt').kind).toBe('text');
+    // No suffix at all → falls through to text/plain.
+    expect(detectFileType('Makefile').kind).toBe('text');
+    // Leading dot-only names have no suffix → text/plain fallback.
+    expect(detectFileType('.env').kind).toBe('text');
+    expect(detectFileType('icon.svg').kind).toBe('text');
+    expect(detectFileType('archive.tar.gz').kind).toBe('unknown');
+    expect(detectFileType('my file.pdf').kind).toBe('unknown');
+  });
+
+  it('keeps TypeScript suffixes as text rather than MPEG-TS video', () => {
+    // Regression lockdown: the `.ts` suffix maps to video/mp2t in some MIME
+    // tables. We must NOT classify .ts/.tsx/.mts/.cts as video — they are
+    // source files.
+    expect(detectFileType('app.ts').kind).toBe('text');
+    expect(detectFileType('component.tsx').kind).toBe('text');
+    expect(detectFileType('module.mts').kind).toBe('text');
+    expect(detectFileType('common.cts').kind).toBe('text');
+  });
+
+  it('header sniffing picks up extensionless video and refines unknown-suffix MIME', () => {
+    const iso5Header = Buffer.concat([
+      Buffer.from([0, 0, 0, 0x18]),
+      Buffer.from('ftyp'),
+      Buffer.from('iso5'),
+      Buffer.from([0, 0, 0, 0]),
+      Buffer.from('iso5isom'),
+    ]);
+    expect(detectFileType('sample', iso5Header).kind).toBe('video');
+
+    const pngHeader = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0]);
+    // .bin is in NON_TEXT_SUFFIXES; a sniffed PNG header refines it to image/png.
+    expect(detectFileType('sample.bin', pngHeader).mimeType).toBe('image/png');
+
+    // NUL byte in header overrides the .txt text hint.
+    const binaryHeader = Buffer.concat([Buffer.from('partial'), Buffer.from([0x00, 0x00])]);
+    expect(detectFileType('notes.txt', binaryHeader).kind).toBe('unknown');
+  });
+});
+
+// ── sniffImageDimensions ──────────────────────────────────────────────
+//
+// Minimal valid header builders for each supported raster format. Each
+// produces just enough bytes for `sniffImageDimensions` to locate the
+// dimension fields.
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+/** PNG IHDR: width/height are big-endian uint32 at offsets 16 and 20. */
+function buildPng(width: number, height: number): Buffer {
+  const buf = Buffer.alloc(24);
+  Buffer.from(PNG_SIGNATURE).copy(buf, 0);
+  Buffer.from('IHDR').copy(buf, 12);
+  buf.writeUInt32BE(width, 16);
+  buf.writeUInt32BE(height, 20);
+  return buf;
+}
+
+/** GIF logical-screen: width/height are little-endian uint16 at 6 and 8. */
+function buildGif(signature: 'GIF87a' | 'GIF89a', width: number, height: number): Buffer {
+  const buf = Buffer.alloc(10);
+  Buffer.from(signature, 'latin1').copy(buf, 0);
+  buf.writeUInt16LE(width, 6);
+  buf.writeUInt16LE(height, 8);
+  return buf;
+}
+
+/** BMP DIB header: width/height are little-endian int32 at 18 and 22. */
+function buildBmp(width: number, height: number): Buffer {
+  const buf = Buffer.alloc(26);
+  Buffer.from('BM', 'latin1').copy(buf, 0);
+  buf.writeInt32LE(width, 18);
+  buf.writeInt32LE(height, 22);
+  return buf;
+}
+
+/** WebP VP8 (lossy): 14-bit width/height masked from uint16 at 26 and 28. */
+function buildWebpVp8(width: number, height: number): Buffer {
+  const buf = Buffer.alloc(30);
+  Buffer.from('RIFF', 'latin1').copy(buf, 0);
+  Buffer.from('WEBP', 'latin1').copy(buf, 8);
+  Buffer.from('VP8 ', 'latin1').copy(buf, 12);
+  buf.writeUInt16LE(width & 0x3fff, 26);
+  buf.writeUInt16LE(height & 0x3fff, 28);
+  return buf;
+}
+
+/** WebP VP8L (lossless): width-1 / height-1 bit-packed into uint32 at 21. */
+function buildWebpVp8l(width: number, height: number): Buffer {
+  const buf = Buffer.alloc(30);
+  Buffer.from('RIFF', 'latin1').copy(buf, 0);
+  Buffer.from('WEBP', 'latin1').copy(buf, 8);
+  Buffer.from('VP8L', 'latin1').copy(buf, 12);
+  const bits = ((width - 1) & 0x3fff) | (((height - 1) & 0x3fff) << 14);
+  buf.writeUInt32LE(Math.trunc(bits), 21);
+  return buf;
+}
+
+/** WebP VP8X (extended): width-1 / height-1 as 24-bit LE at 24 and 27. */
+function buildWebpVp8x(width: number, height: number): Buffer {
+  const buf = Buffer.alloc(30);
+  Buffer.from('RIFF', 'latin1').copy(buf, 0);
+  Buffer.from('WEBP', 'latin1').copy(buf, 8);
+  Buffer.from('VP8X', 'latin1').copy(buf, 12);
+  const w = width - 1;
+  const h = height - 1;
+  buf[24] = w & 0xff;
+  buf[25] = (w >> 8) & 0xff;
+  buf[26] = (w >> 16) & 0xff;
+  buf[27] = h & 0xff;
+  buf[28] = (h >> 8) & 0xff;
+  buf[29] = (h >> 16) & 0xff;
+  return buf;
+}
+
+/**
+ * JPEG with one SOF0 frame: SOI marker, an APP0 segment to exercise the
+ * segment-skipping loop, then the SOF0 segment carrying height/width as
+ * big-endian uint16.
+ */
+function buildJpeg(width: number, height: number): Buffer {
+  const soi = Buffer.from([0xff, 0xd8]);
+  // APP0 segment: marker + length(2) + 4 bytes of payload.
+  const app0 = Buffer.from([0xff, 0xe0, 0x00, 0x06, 0x00, 0x00, 0x00, 0x00]);
+  // SOF0: marker, length(0x0011=17), precision, height(BE), width(BE), …
+  const sof0 = Buffer.alloc(19);
+  sof0[0] = 0xff;
+  sof0[1] = 0xc0;
+  sof0.writeUInt16BE(17, 2);
+  sof0[4] = 8; // sample precision
+  sof0.writeUInt16BE(height, 5);
+  sof0.writeUInt16BE(width, 7);
+  return Buffer.concat([soi, app0, sof0]);
+}
+
+describe('sniffImageDimensions', () => {
+  const cases: ReadonlyArray<{
+    name: string;
+    data: Buffer;
+    expected: ImageDimensions;
+  }> = [
+    { name: 'PNG (IHDR big-endian uint32)', data: buildPng(800, 600), expected: { width: 800, height: 600 } },
+    {
+      name: 'GIF87a (logical screen little-endian uint16)',
+      data: buildGif('GIF87a', 320, 240),
+      expected: { width: 320, height: 240 },
+    },
+    {
+      name: 'GIF89a (logical screen little-endian uint16)',
+      data: buildGif('GIF89a', 1024, 768),
+      expected: { width: 1024, height: 768 },
+    },
+    { name: 'BMP (DIB little-endian int32)', data: buildBmp(640, 480), expected: { width: 640, height: 480 } },
+    {
+      name: 'BMP top-down (negative height → absolute value)',
+      data: buildBmp(640, -480),
+      expected: { width: 640, height: 480 },
+    },
+    {
+      name: 'WebP VP8 (14-bit masked dimensions)',
+      data: buildWebpVp8(256, 192),
+      expected: { width: 256, height: 192 },
+    },
+    {
+      name: 'WebP VP8L (bit-packed, stored as value-1)',
+      data: buildWebpVp8l(300, 200),
+      expected: { width: 300, height: 200 },
+    },
+    {
+      name: 'WebP VP8X (24-bit little-endian, stored as value-1)',
+      data: buildWebpVp8x(4000, 3000),
+      expected: { width: 4000, height: 3000 },
+    },
+    {
+      name: 'JPEG (SOF0 segment, height before width)',
+      data: buildJpeg(1280, 720),
+      expected: { width: 1280, height: 720 },
+    },
+  ];
+
+  it.each(cases)('parses dimensions from $name', ({ data, expected }) => {
+    expect(sniffImageDimensions(data)).toEqual(expected);
+  });
+
+  it('reads VP8 14-bit masking — values above 0x3fff wrap to the low bits', () => {
+    // 14-bit field tops out at 16383; the mask discards higher bits.
+    const data = buildWebpVp8(16383, 1);
+    expect(sniffImageDimensions(data)).toEqual({ width: 16383, height: 1 });
+  });
+
+  it('keeps JPEG height/width order distinct (non-square frame)', () => {
+    // A non-square frame proves the SOF0 reader does not transpose axes.
+    const data = buildJpeg(100, 700);
+    expect(sniffImageDimensions(data)).toEqual({ width: 100, height: 700 });
+  });
+
+  describe('truncated / malformed input returns null without throwing', () => {
+    const malformed: ReadonlyArray<{ name: string; data: Buffer }> = [
+      {
+        name: 'PNG header shorter than 24 bytes',
+        data: Buffer.from([...PNG_SIGNATURE, 0x00, 0x00, 0x00]),
+      },
+      {
+        name: 'GIF header shorter than 10 bytes',
+        data: Buffer.from('GIF89a\0', 'latin1'),
+      },
+      {
+        name: 'BMP header shorter than 26 bytes',
+        data: Buffer.concat([Buffer.from('BM', 'latin1'), Buffer.alloc(10)]),
+      },
+      {
+        name: 'WebP RIFF container shorter than 30 bytes',
+        data: Buffer.concat([
+          Buffer.from('RIFF', 'latin1'),
+          Buffer.alloc(4),
+          Buffer.from('WEBP', 'latin1'),
+          Buffer.from('VP8 ', 'latin1'),
+        ]),
+      },
+      {
+        name: 'WebP VP8L chunk shorter than 25 bytes',
+        data: (() => {
+          const buf = Buffer.alloc(30);
+          Buffer.from('RIFF', 'latin1').copy(buf, 0);
+          Buffer.from('WEBP', 'latin1').copy(buf, 8);
+          Buffer.from('VP8L', 'latin1').copy(buf, 12);
+          return buf.subarray(0, 24);
+        })(),
+      },
+      {
+        name: 'JPEG with no SOF segment (only SOI + truncated APP0)',
+        data: Buffer.from([0xff, 0xd8, 0xff, 0xe0]),
+      },
+      {
+        name: 'JPEG with an illegal segment length (< 2) before any SOF',
+        // SOI then an APP0 marker whose declared length is 0; the
+        // `segmentLength < 2` guard must break instead of looping forever.
+        data: Buffer.from([
+          0xff, 0xd8, 0xff, 0xe0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+        ]),
+      },
+      {
+        name: 'JPEG SOF marker whose payload runs past the buffer end',
+        // SOI + SOF0 marker but the segment body is cut short, so the
+        // `offset + 9 < buf.length` guard stops the loop before reading.
+        data: Buffer.from([0xff, 0xd8, 0xff, 0xc0, 0x00, 0x11, 0x08, 0x00]),
+      },
+      {
+        name: 'completely unrecognised bytes',
+        data: Buffer.from('not an image at all', 'latin1'),
+      },
+    ];
+
+    it.each(malformed)('$name', ({ data }) => {
+      let result: ImageDimensions | null = null;
+      expect(() => {
+        result = sniffImageDimensions(data);
+      }).not.toThrow();
+      expect(result).toBeNull();
+    });
+  });
+});
diff --git a/packages/agent-core/test/tools/fixtures/execute-tool.ts b/packages/agent-core/test/tools/fixtures/execute-tool.ts
new file mode 100644
index 000000000..4ea5c2fc2
--- /dev/null
+++ b/packages/agent-core/test/tools/fixtures/execute-tool.ts
@@ -0,0 +1,27 @@
+import type { ExecutableTool, ExecutableToolContext, ToolExecution } from '../../../src/loop';
+import { PathSecurityError } from '../../../src/tools/policies/path-access';
+
+export type TestExecutableToolContext<Input> = ExecutableToolContext & {
+  readonly args: Input;
+};
+
+export function executeTool<Input>(
+  tool: ExecutableTool<Input>,
+  context: TestExecutableToolContext<Input>,
+) {
+  const { args, ...executionContext } = context;
+  let execution: ToolExecution;
+  try {
+    execution = tool.resolveExecution(args);
+  } catch (error) {
+    const output =
+      error instanceof PathSecurityError
+        ? error.message
+        : `Tool "${tool.name}" failed to resolve execution: ${
+            error instanceof Error ? error.message : String(error)
+          }`;
+    return Promise.resolve({ isError: true, output });
+  }
+  if (execution.isError === true) return Promise.resolve(execution);
+  return execution.execute(executionContext);
+}
diff --git a/packages/agent-core/test/tools/fixtures/fake-kaos.ts b/packages/agent-core/test/tools/fixtures/fake-kaos.ts
new file mode 100644
index 000000000..0f6c558ee
--- /dev/null
+++ b/packages/agent-core/test/tools/fixtures/fake-kaos.ts
@@ -0,0 +1,62 @@
+/**
+ * Fake Kaos — minimal stub for tool constructor injection in tests.
+ *
+ * All methods throw by default. Individual tests can override specific
+ * methods with vi.fn() to provide scripted responses for the tool
+ * under test.
+ *
+ * Also provides `PERMISSIVE_WORKSPACE` (`/` as workspaceDir) — most tool
+ * tests care about behaviour, not path safety, so they default to a
+ * workspace that accepts any absolute path. Attack-vector tests create
+ * their own `WorkspaceConfig` with narrower bounds.
+ */
+
+import type { ExecutableToolResult } from '#/loop';
+import type { Kaos } from '@moonshot-ai/kaos';
+
+import type { WorkspaceConfig } from '../../../src/tools/support/workspace';
+
+function notImplemented(method: string): never {
+  throw new Error(`FakeKaos.${method} not implemented — override in test`);
+}
+
+export function createFakeKaos(overrides?: Partial<Kaos>): Kaos {
+  const base: Kaos = {
+    name: 'fake',
+    pathClass: () => 'posix',
+    normpath: (p: string) => p,
+    gethome: () => '/home/test',
+    getcwd: () => '/workspace',
+    chdir: () => notImplemented('chdir'),
+    stat: () => notImplemented('stat'),
+    iterdir: () => notImplemented('iterdir'),
+    glob: () => notImplemented('glob'),
+    readBytes: () => notImplemented('readBytes'),
+    readText: () => notImplemented('readText'),
+    readLines: () => notImplemented('readLines'),
+    writeBytes: () => notImplemented('writeBytes'),
+    writeText: () => notImplemented('writeText'),
+    mkdir: () => notImplemented('mkdir'),
+    exec: () => notImplemented('exec'),
+    execWithEnv: () => notImplemented('execWithEnv'),
+  };
+  return { ...base, ...overrides } as Kaos;
+}
+
+export const PERMISSIVE_WORKSPACE: WorkspaceConfig = {
+  workspaceDir: '/',
+  additionalDirs: [],
+};
+
+/**
+ * Assert that a `ToolResult`'s `content` is a string and return it.
+ * Keeps the lint rule `typescript-eslint(no-base-to-string)` happy by
+ * narrowing the `string | ToolResultContent[]` union in one place.
+ */
+export function toolContentString(result: ExecutableToolResult): string {
+  const c = result.output;
+  if (typeof c !== 'string') {
+    throw new TypeError(`expected string content, got ${typeof c}`);
+  }
+  return c;
+}
diff --git a/packages/agent-core/test/tools/glob.test.ts b/packages/agent-core/test/tools/glob.test.ts
new file mode 100644
index 000000000..8cb4c2707
--- /dev/null
+++ b/packages/agent-core/test/tools/glob.test.ts
@@ -0,0 +1,588 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { type GlobInput, GlobInputSchema, GlobTool, MAX_MATCHES } from '../../src/tools/builtin/file/glob';
+import type { WorkspaceConfig } from '../../src/tools/support/workspace';
+import { createFakeKaos } from './fixtures/fake-kaos';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+const workspace: WorkspaceConfig = { workspaceDir: '/workspace', additionalDirs: ['/extra'] };
+
+async function* asyncPaths(paths: readonly string[]) {
+  for (const item of paths) yield item;
+}
+
+function stat(mtime: number, mode = 0o100000) {
+  return { stMtime: mtime, stMode: mode };
+}
+
+function context(args: GlobInput) {
+  return { turnId: '0', toolCallId: 'call_glob', args, signal };
+}
+
+describe('GlobTool', () => {
+  it('exposes current metadata and schema', () => {
+    const tool = new GlobTool(createFakeKaos(), workspace);
+
+    expect(tool.name).toBe('Glob');
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: { pattern: { type: 'string' } },
+    });
+    expect(GlobInputSchema.safeParse({ pattern: 'src/**/*.ts' }).success).toBe(true);
+    expect(GlobInputSchema.safeParse({ pattern: '*.js', path: '/src' }).success).toBe(true);
+  });
+
+  it('exposes the include_dirs default in its JSON Schema without making it required', () => {
+    const tool = new GlobTool(createFakeKaos(), workspace);
+    const schema = tool.parameters as {
+      properties: { include_dirs: { default?: unknown } };
+      required?: string[];
+    };
+
+    // The default must be structurally visible to the model, not only
+    // described in prose, so it survives without an explicit argument.
+    expect(schema.properties.include_dirs.default).toBe(true);
+    // A default value must not promote include_dirs into `required`.
+    expect(schema.required ?? []).not.toContain('include_dirs');
+  });
+
+  it('injects the Windows path hint into the description on a win32 backend', () => {
+    const tool = new GlobTool(createFakeKaos({ pathClass: () => 'win32' }), workspace);
+
+    expect(tool.description).toContain('Windows');
+    expect(tool.description).toContain('forward slashes');
+    expect(tool.description).toContain('Bash');
+  });
+
+  it('omits the Windows path hint from the description on a non-Windows backend', () => {
+    const tool = new GlobTool(createFakeKaos({ pathClass: () => 'posix' }), workspace);
+
+    expect(tool.description).not.toContain('forward slashes');
+  });
+
+  it('returns matching paths sorted by mtime and relative to an explicit search root', async () => {
+    const glob = vi
+      .fn()
+      .mockReturnValue(asyncPaths(['/workspace/src/old.ts', '/workspace/src/new.ts']));
+    const tool = new GlobTool(
+      createFakeKaos({
+        glob,
+        stat: vi.fn().mockResolvedValueOnce(stat(1)).mockResolvedValueOnce(stat(10)),
+      }),
+      workspace,
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'src/**/*.ts', path: '/workspace' }));
+
+    expect(result.output).toBe('src/new.ts\nsrc/old.ts');
+    expect(glob).toHaveBeenCalledWith('/workspace', 'src/**/*.ts');
+  });
+
+  it('uses the backend path class when displaying paths relative to a windows root', async () => {
+    const glob = vi.fn().mockReturnValue(asyncPaths(['C:\\workspace\\src\\old.ts']));
+    const tool = new GlobTool(
+      createFakeKaos({
+        pathClass: () => 'win32',
+        glob,
+        stat: vi.fn().mockResolvedValue(stat(1)),
+      }),
+      { workspaceDir: 'C:\\workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'src/**/*.ts', path: 'C:\\WORKSPACE' }));
+
+    expect(result.output).toBe('src\\old.ts');
+    expect(glob).toHaveBeenCalledWith('C:\\WORKSPACE', 'src/**/*.ts');
+  });
+
+  it('rejects pure wildcard patterns before walking the tree', async () => {
+    const glob = vi.fn();
+    const tool = new GlobTool(
+      createFakeKaos({
+        glob,
+        iterdir: vi.fn().mockReturnValue(asyncPaths(['/workspace/src'])),
+        stat: vi.fn().mockResolvedValue(stat(0, 0o040000)),
+      }),
+      workspace,
+    );
+
+    const result = await executeTool(tool, context({ pattern: '**' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('pure wildcard');
+    expect(result.output).toContain('/workspace');
+    expect(glob).not.toHaveBeenCalled();
+  });
+
+  it('rejects brace expansion patterns with a clear split-call hint', async () => {
+    const glob = vi.fn();
+    const tool = new GlobTool(createFakeKaos({ glob }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: '*.{ts,tsx}' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('brace expansion');
+    expect(result.output).toContain('Split it into separate calls');
+    expect(glob).not.toHaveBeenCalled();
+  });
+
+  it('searches only the current workspace when path is omitted', async () => {
+    const glob = vi.fn().mockReturnValue(asyncPaths(['/workspace/a.ts', '/workspace/shared.ts']));
+    const tool = new GlobTool(
+      createFakeKaos({
+        glob,
+        stat: vi.fn().mockResolvedValue(stat(1)),
+      }),
+      workspace,
+    );
+
+    const result = await executeTool(tool, context({ pattern: '*.ts' }));
+
+    expect(glob).toHaveBeenCalledTimes(1);
+    expect(glob).toHaveBeenCalledWith('/workspace', '*.ts');
+    expect(result.output).toBe('a.ts\nshared.ts');
+  });
+
+  it('can search an additional directory when path is explicit', async () => {
+    const glob = vi.fn().mockReturnValue(asyncPaths(['/extra/pkg/a.ts']));
+    const tool = new GlobTool(
+      createFakeKaos({ glob, stat: vi.fn().mockResolvedValue(stat(1)) }),
+      workspace,
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'pkg/**/*.ts', path: '/extra' }));
+
+    expect(result.output).toBe('pkg/a.ts');
+    expect(glob).toHaveBeenCalledTimes(1);
+    expect(glob).toHaveBeenCalledWith('/extra', 'pkg/**/*.ts');
+  });
+
+  it('filters directories when include_dirs is false', async () => {
+    const glob = vi.fn().mockReturnValue(asyncPaths(['/workspace/src', '/workspace/src/a.ts']));
+    const tool = new GlobTool(
+      createFakeKaos({
+        glob,
+        stat: vi
+          .fn()
+          .mockResolvedValueOnce(stat(2, 0o040000))
+          .mockResolvedValueOnce(stat(1, 0o100000)),
+      }),
+      workspace,
+    );
+
+    const result = await executeTool(tool,
+      context({ pattern: 'src*', path: '/workspace', include_dirs: false }),
+    );
+
+    expect(result.output).toBe('src/a.ts');
+  });
+
+  it('caps returned matches and surfaces the truncation header', async () => {
+    const paths = Array.from({ length: MAX_MATCHES + 1 }, (_, i) => `/workspace/${String(i)}.ts`);
+    const tool = new GlobTool(
+      createFakeKaos({
+        glob: vi.fn().mockReturnValue(asyncPaths(paths)),
+        stat: vi.fn().mockResolvedValue(stat(1)),
+      }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: '*.ts' }));
+
+    expect(result.output).toContain(`[Truncated at ${String(MAX_MATCHES)} matches`);
+    expect(result.output).toContain('0.ts');
+    expect(result.output).not.toContain(`${String(MAX_MATCHES)}.ts`);
+  });
+
+  describe('skills / additional dirs', () => {
+    const skillsWorkspace: WorkspaceConfig = {
+      workspaceDir: '/workspace',
+      additionalDirs: ['/skills'],
+    };
+
+    it('searches inside a registered additionalDir entry', async () => {
+      const glob = vi
+        .fn()
+        .mockReturnValue(asyncPaths(['/skills/read_content.py', '/skills/utils.py']));
+      const tool = new GlobTool(
+        createFakeKaos({ glob, stat: vi.fn().mockResolvedValue(stat(1)) }),
+        skillsWorkspace,
+      );
+
+      const result = await executeTool(tool, context({ pattern: '*.py', path: '/skills' }));
+
+      expect(result.output).toContain('read_content.py');
+      expect(result.output).toContain('utils.py');
+      expect(glob).toHaveBeenCalledWith('/skills', '*.py');
+    });
+
+    it('searches inside a subdirectory of an additionalDir entry', async () => {
+      const glob = vi
+        .fn()
+        .mockReturnValue(asyncPaths(['/skills/feishu/scripts/read_content.py']));
+      const tool = new GlobTool(
+        createFakeKaos({ glob, stat: vi.fn().mockResolvedValue(stat(1)) }),
+        skillsWorkspace,
+      );
+
+      const result = await executeTool(tool,
+        context({ pattern: '*.py', path: '/skills/feishu/scripts' }),
+      );
+
+      expect(result.output).toContain('read_content.py');
+    });
+
+    it('rejects a relative path that escapes both workspace and additionalDirs', async () => {
+      const glob = vi.fn();
+      const tool = new GlobTool(createFakeKaos({ glob }), {
+        workspaceDir: '/workspace/project',
+        additionalDirs: ['/skills'],
+      });
+
+      const result = await executeTool(tool, context({ pattern: '*.py', path: '../../tmp/evil' }));
+
+      expect(result).toMatchObject({ isError: true });
+      expect(result.output).toContain('absolute path');
+      expect(glob).not.toHaveBeenCalled();
+    });
+
+    it('accepts a path inside a deeply nested additionalDir entry', async () => {
+      const glob = vi
+        .fn()
+        .mockReturnValue(asyncPaths(['/skills/my-skill/scripts/helper.py']));
+      const tool = new GlobTool(
+        createFakeKaos({ glob, stat: vi.fn().mockResolvedValue(stat(1)) }),
+        skillsWorkspace,
+      );
+
+      const result = await executeTool(tool,
+        context({ pattern: '*.py', path: '/skills/my-skill/scripts' }),
+      );
+
+      expect(result.output).toContain('helper.py');
+    });
+  });
+
+  it('rejects "**/" prefix patterns even with a literal anchor', async () => {
+    // py rejects every pattern starting with "**/". TS only rejects pure-
+    // wildcard patterns and accepts "**/*.py" because the `.py` literal
+    // anchors the walk. Test as a lockdown of the py contract — expected
+    // to fail under the current TS policy.
+    const glob = vi.fn();
+    const tool = new GlobTool(
+      createFakeKaos({
+        glob,
+        iterdir: vi.fn().mockReturnValue(asyncPaths([])),
+        stat: vi.fn().mockResolvedValue(stat(0, 0o040000)),
+      }),
+      workspace,
+    );
+
+    const result = await executeTool(tool, context({ pattern: '**/*.py' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toMatch(/starts with '\*\*' which is not allowed/);
+  });
+
+  it('walks safe recursive patterns with a literal subdirectory anchor', async () => {
+    const glob = vi.fn().mockReturnValue(
+      asyncPaths([
+        '/workspace/src/main.py',
+        '/workspace/src/utils.py',
+        '/workspace/src/main/app.py',
+        '/workspace/src/main/config.py',
+        '/workspace/src/test/test_app.py',
+        '/workspace/src/test/test_config.py',
+      ]),
+    );
+    const tool = new GlobTool(
+      createFakeKaos({ glob, stat: vi.fn().mockResolvedValue(stat(1)) }),
+      workspace,
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'src/**/*.py', path: '/workspace' }));
+
+    expect(result.output).toContain('src/main.py');
+    expect(result.output).toContain('src/utils.py');
+    expect(result.output).toContain('src/main/app.py');
+    expect(result.output).toContain('src/main/config.py');
+    expect(result.output).toContain('src/test/test_app.py');
+    expect(result.output).toContain('src/test/test_config.py');
+  });
+
+  it('surfaces an explicit no-match message when no paths are yielded', async () => {
+    const glob = vi.fn().mockReturnValue(asyncPaths([]));
+    const tool = new GlobTool(createFakeKaos({ glob }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: '*.xyz', path: '/workspace' }));
+
+    expect(result.isError).toBeFalsy();
+    expect(result.output).toContain('No matches found');
+  });
+
+  it('reports "does not exist" when the search directory is missing', async () => {
+    // Real kaos.glob silently returns empty for a missing root because
+    // its _globWalk catches readdir failures. The tool now pre-checks
+    // with iterdir so ENOENT surfaces before glob runs. Realistic mock:
+    // iterdir throws ENOENT, glob is never called.
+    const iterdir = vi.fn(async function* (): AsyncGenerator<string> {
+      await Promise.resolve();
+      throw Object.assign(new Error('ENOENT: no such file or directory'), { code: 'ENOENT' });
+      yield ''; // eslint-disable-line no-unreachable -- satisfies require-yield
+    });
+    const glob = vi.fn();
+    const tool = new GlobTool(createFakeKaos({ iterdir, glob }), workspace);
+
+    const result = await executeTool(tool,
+      context({ pattern: '*.py', path: '/workspace/nonexistent' }),
+    );
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('does not exist');
+    expect(glob).not.toHaveBeenCalled();
+  });
+
+  it('reports "is not a directory" when the search target is a file', async () => {
+    // Real kaos.glob silently returns empty when the root is a regular
+    // file because its _globWalk's readdir hits ENOTDIR and exits. The
+    // pre-check uses iterdir, which raises ENOTDIR on file-as-dir.
+    // Realistic mock: iterdir throws ENOTDIR, glob is never called.
+    const iterdir = vi.fn(async function* (): AsyncGenerator<string> {
+      await Promise.resolve();
+      throw Object.assign(new Error('ENOTDIR: not a directory'), { code: 'ENOTDIR' });
+      yield ''; // eslint-disable-line no-unreachable -- satisfies require-yield
+    });
+    const glob = vi.fn();
+    const tool = new GlobTool(createFakeKaos({ iterdir, glob }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: '*.py', path: '/workspace/file.txt' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('is not a directory');
+    expect(glob).not.toHaveBeenCalled();
+  });
+
+  it('surfaces a "first N matches" header when matches exceed MAX_MATCHES', async () => {
+    const paths = Array.from(
+      { length: MAX_MATCHES + 50 },
+      (_, i) => `/workspace/file_${String(i)}.txt`,
+    );
+    const tool = new GlobTool(
+      createFakeKaos({
+        glob: vi.fn().mockReturnValue(asyncPaths(paths)),
+        stat: vi.fn().mockResolvedValue(stat(1)),
+      }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: '*.txt' }));
+
+    expect(result.output).toContain(`Only the first ${String(MAX_MATCHES)} matches are returned`);
+  });
+
+  it('includes a directory listing in the rejection message for "**/" patterns', async () => {
+    // py rejection includes the top-level directory listing as a hint.
+    const iterdir = vi
+      .fn()
+      .mockReturnValue(asyncPaths(['/workspace/file1.txt', '/workspace/file2.py', '/workspace/src', '/workspace/docs']));
+    const glob = vi.fn();
+    const tool = new GlobTool(
+      createFakeKaos({
+        glob,
+        iterdir,
+        stat: vi.fn().mockResolvedValue(stat(0, 0o100000)),
+      }),
+      workspace,
+    );
+
+    const result = await executeTool(tool, context({ pattern: '**/*.txt' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toMatch(/starts with '\*\*' which is not allowed/);
+    expect(result.output).toContain('Use more specific patterns instead');
+    expect(result.output).toContain('file1.txt');
+    expect(result.output).toContain('file2.py');
+    expect(result.output).toContain('src');
+    expect(result.output).toContain('docs');
+  });
+
+  it('returns a "Found N matches" footer at exactly MAX_MATCHES without truncation', async () => {
+    const paths = Array.from(
+      { length: MAX_MATCHES },
+      (_, i) => `/workspace/test_${String(i)}.py`,
+    );
+    const tool = new GlobTool(
+      createFakeKaos({
+        glob: vi.fn().mockReturnValue(asyncPaths(paths)),
+        stat: vi.fn().mockResolvedValue(stat(1)),
+      }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: '*.py' }));
+
+    expect(result.output).not.toContain('Only the first');
+    expect(result.output).toContain(`Found ${String(MAX_MATCHES)} matches`);
+  });
+
+  it('rejects "**/" patterns with literal subdirectory anchors after the prefix', async () => {
+    const glob = vi.fn();
+    const tool = new GlobTool(
+      createFakeKaos({
+        glob,
+        iterdir: vi.fn().mockReturnValue(asyncPaths([])),
+        stat: vi.fn().mockResolvedValue(stat(0, 0o040000)),
+      }),
+      workspace,
+    );
+
+    const result = await executeTool(tool, context({ pattern: '**/main/*.py' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toMatch(/starts with '\*\*' which is not allowed/);
+    expect(glob).not.toHaveBeenCalled();
+  });
+
+  it('matches dotfiles like .gitlab-ci.yml under a simple "*.yml" pattern', async () => {
+    const glob = vi
+      .fn()
+      .mockReturnValue(asyncPaths(['/workspace/.gitlab-ci.yml', '/workspace/config.yml']));
+    const tool = new GlobTool(
+      createFakeKaos({ glob, stat: vi.fn().mockResolvedValue(stat(1)) }),
+      workspace,
+    );
+
+    const result = await executeTool(tool, context({ pattern: '*.yml' }));
+
+    expect(result.output).toContain('.gitlab-ci.yml');
+    expect(result.output).toContain('config.yml');
+  });
+
+  it('descends into hidden directories under a recursive pattern', async () => {
+    const glob = vi.fn().mockReturnValue(asyncPaths(['/workspace/src/.config/settings.yml']));
+    const tool = new GlobTool(
+      createFakeKaos({ glob, stat: vi.fn().mockResolvedValue(stat(1)) }),
+      workspace,
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'src/**/*.yml' }));
+
+    expect(result.output).toContain('src/.config/settings.yml');
+  });
+
+  it('matches files inside an explicitly addressed hidden directory', async () => {
+    const glob = vi.fn().mockReturnValue(asyncPaths(['/workspace/.github/workflows/ci.yml']));
+    const tool = new GlobTool(
+      createFakeKaos({ glob, stat: vi.fn().mockResolvedValue(stat(1)) }),
+      workspace,
+    );
+
+    const result = await executeTool(tool, context({ pattern: '.github/**/*.yml' }));
+
+    expect(result.output).toContain('.github/workflows/ci.yml');
+  });
+
+  it('picks up a freshly appended additionalDir without rebuilding the tool', async () => {
+    // py rejects `/extra` before it is registered in additional_dirs, then
+    // allows it after a runtime append. TS Glob runs with the
+    // `absolute-outside-allowed` policy so the first call is NOT rejected.
+    // Divergence lockdown — captures the cost of TS's looser default.
+    const additionalDirs: string[] = [];
+    const mutable: WorkspaceConfig = { workspaceDir: '/workspace', additionalDirs };
+    const glob = vi.fn((root: string) =>
+      asyncPaths(root === '/extra' ? ['/extra/test.py'] : []),
+    );
+    const tool = new GlobTool(
+      createFakeKaos({ glob, stat: vi.fn().mockResolvedValue(stat(1)) }),
+      mutable,
+    );
+
+    const before = await executeTool(tool, context({ pattern: '*.py', path: '/extra' }));
+    expect(before).toMatchObject({ isError: true });
+    expect(before.output).toContain('outside the working directory');
+
+    additionalDirs.push('/extra');
+
+    const after = await executeTool(tool, context({ pattern: '*.py', path: '/extra' }));
+    expect(after.isError).toBeFalsy();
+    expect(after.output).toContain('test.py');
+  });
+
+  it('rejects a relative path argument before resolving it against any cwd', async () => {
+    // py rejects any relative `directory` outright with "not an absolute
+    // path". TS currently joins relative paths onto the workspace cwd and
+    // proceeds — divergence lockdown.
+    const glob = vi.fn().mockReturnValue(asyncPaths([]));
+    const tool = new GlobTool(
+      createFakeKaos({ glob, stat: vi.fn().mockResolvedValue(stat(1)) }),
+      workspace,
+    );
+
+    const result = await executeTool(tool, context({ pattern: '*.py', path: 'relative/path' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('not an absolute path');
+  });
+
+  it('expands a leading "~/" path before applying the workspace guard', async () => {
+    // py: `~/` is expanded to the home dir, which is outside the
+    // workspace; the guard then rejects with "outside the workspace".
+    // The key invariant under test is that tilde expansion happens BEFORE
+    // the absolute-path check — otherwise the user would see the misleading
+    // "not an absolute path" error. TS currently runs Glob with
+    // `absolute-outside-allowed` so the workspace check does NOT reject
+    // outside paths once tilde expansion makes them absolute — divergence
+    // lockdown.
+    const glob = vi.fn().mockReturnValue(asyncPaths([]));
+    const tool = new GlobTool(
+      createFakeKaos({ glob, gethome: () => '/home/test', stat: vi.fn().mockResolvedValue(stat(1)) }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: '*.py', path: '~/' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('outside the workspace');
+    expect(result.output).not.toContain('not an absolute path');
+  });
+
+  it('rejects a path sharing the workspace prefix but outside it', async () => {
+    // py rejects shared-prefix outside paths with "outside the workspace".
+    // TS Glob uses `absolute-outside-allowed`, so an absolute path outside
+    // the workspace is accepted by design. Divergence lockdown.
+    const glob = vi.fn().mockReturnValue(asyncPaths([]));
+    const tool = new GlobTool(
+      createFakeKaos({ glob, stat: vi.fn().mockResolvedValue(stat(1)) }),
+      { workspaceDir: '/parent/workdir', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool,
+      context({ pattern: '*.py', path: '/parent/workdir-sneaky' }),
+    );
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toMatch(/outside the workspace|outside the working directory/);
+  });
+
+  it('locks down rejection phrasing and large-directory caveats in the description', () => {
+    const tool = new GlobTool(createFakeKaos(), workspace);
+
+    expect(tool.description).toContain('**');
+    expect(tool.description).toMatch(/\*\*\/\*\.py/);
+    expect(tool.description).toContain('node_modules');
+    expect(tool.description).not.toContain('On Windows');
+  });
+
+  it('mentions Windows path forms in the description on win32 backends', () => {
+    // py emits an OS-conditional hint about C:\Users\foo and /c/Users/foo
+    // forms; TS currently uses a single static description.
+    const tool = new GlobTool(createFakeKaos({ pathClass: () => 'win32' }), {
+      workspaceDir: 'C:\\workspace',
+      additionalDirs: [],
+    });
+
+    expect(tool.description).toContain('C:\\Users\\foo');
+    expect(tool.description).toContain('/c/Users/foo');
+  });
+});
diff --git a/packages/agent-core/test/tools/grep.test.ts b/packages/agent-core/test/tools/grep.test.ts
new file mode 100644
index 000000000..b31931d59
--- /dev/null
+++ b/packages/agent-core/test/tools/grep.test.ts
@@ -0,0 +1,1890 @@
+import { Readable, type Writable } from 'node:stream';
+
+import type { KaosProcess, StatResult } from '@moonshot-ai/kaos';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { type GrepInput, GrepInputSchema, GrepTool } from '../../src/tools/builtin/file/grep';
+import { SENSITIVE_DOT_VARIANT_SUFFIXES } from '../../src/tools/policies/sensitive';
+import { ensureRgPath } from '../../src/tools/support/rg-locator';
+import type { WorkspaceConfig } from '../../src/tools/support/workspace';
+import { createFakeKaos, toolContentString } from './fixtures/fake-kaos';
+import { executeTool } from './fixtures/execute-tool';
+
+vi.mock('../../src/tools/support/rg-locator', () => ({
+  ensureRgPath: vi.fn(async () => ({ path: '/mock/rg', source: 'system-path' })),
+  rgUnavailableMessage: (cause: unknown) =>
+    `rg unavailable: ${cause instanceof Error ? cause.message : String(cause)}`,
+}));
+
+const signal = new AbortController().signal;
+const workspace: WorkspaceConfig = { workspaceDir: '/workspace', additionalDirs: ['/extra'] };
+// `--max-columns` is applied only outside `content` output mode, so it is kept
+// as a separate segment: non-content modes use `DEFAULT_RG_ARGS`, while
+// `content` mode uses `CONTENT_RG_ARGS` without the column cap.
+const MAX_COLUMNS_RG_ARGS = ['--max-columns', '500'] as const;
+const COMMON_RG_ARGS = [
+  '--null',
+  '--glob',
+  '!.git',
+  '--glob',
+  '!.svn',
+  '--glob',
+  '!.hg',
+  '--glob',
+  '!.bzr',
+  '--glob',
+  '!.jj',
+  '--glob',
+  '!.sl',
+] as const;
+const DEFAULT_RG_ARGS = ['--hidden', ...MAX_COLUMNS_RG_ARGS, ...COMMON_RG_ARGS] as const;
+const CONTENT_RG_ARGS = ['--hidden', ...COMMON_RG_ARGS] as const;
+const SENSITIVE_KEY_BASENAMES = ['id_rsa', 'id_ed25519', 'id_ecdsa'] as const;
+const SENSITIVE_KEY_RG_ARGS = SENSITIVE_KEY_BASENAMES.flatMap((basename) => [
+  '--glob',
+  `!**/${basename}`,
+  '--glob',
+  `!**/${basename}[-_]*`,
+  ...SENSITIVE_DOT_VARIANT_SUFFIXES.flatMap((suffix) => [
+    '--glob',
+    `!**/${basename}${suffix}`,
+  ]),
+]);
+const SENSITIVE_RG_ARGS = [
+  '--glob',
+  '!**/.env',
+  ...SENSITIVE_KEY_RG_ARGS,
+  '--glob',
+  '!**/.aws/credentials',
+  '--glob',
+  '!**/.aws/credentials/**',
+  '--glob',
+  '!**/.gcp/credentials',
+  '--glob',
+  '!**/.gcp/credentials/**',
+] as const;
+
+function processWithOutput(stdout: string, stderr = '', exitCode = 0): KaosProcess {
+  return {
+    stdin: { end: vi.fn(), write: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([stdout]),
+    stderr: Readable.from([stderr]),
+    pid: 123,
+    exitCode,
+    wait: vi.fn().mockResolvedValue(exitCode),
+    kill: vi.fn(async () => {}),
+  };
+}
+
+function statResult(mtime: number): StatResult {
+  return {
+    stMode: 0o100000,
+    stIno: 1,
+    stDev: 1,
+    stNlink: 1,
+    stUid: 0,
+    stGid: 0,
+    stSize: 0,
+    stAtime: mtime,
+    stMtime: mtime,
+    stCtime: mtime,
+  };
+}
+
+function processThatExitsOnKill(stdout: string, stderr = '', exitCode = 143): KaosProcess {
+  let currentExitCode: number | null = null;
+  let resolveWait: (code: number) => void;
+  const waitPromise = new Promise<number>((resolve) => {
+    resolveWait = resolve;
+  });
+
+  return {
+    stdin: { end: vi.fn(), write: vi.fn() } as unknown as Writable,
+    stdout: Readable.from(stdout === '' ? [] : [stdout]),
+    stderr: Readable.from(stderr === '' ? [] : [stderr]),
+    pid: 123,
+    get exitCode() {
+      return currentExitCode;
+    },
+    wait: vi.fn(() => waitPromise),
+    kill: vi.fn(async () => {
+      currentExitCode = exitCode;
+      resolveWait(exitCode);
+    }),
+  };
+}
+
+function context(args: GrepInput, abortSignal = signal) {
+  return { turnId: '0', toolCallId: 'call_grep', args, signal: abortSignal };
+}
+
+function nullRecord(filePath: string, payload = ''): string {
+  return `${filePath}\0${payload}`;
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('GrepTool', () => {
+  it('exposes current metadata and schema', () => {
+    const tool = new GrepTool(createFakeKaos(), workspace);
+
+    expect(tool.name).toBe('Grep');
+    expect(tool.description).toContain('unknown content or unknown file locations');
+    expect(tool.description).toContain('Do not use shell `grep` or `rg` directly');
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: {
+        pattern: {
+          type: 'string',
+          description: expect.stringContaining('Regular expression'),
+        },
+        path: {
+          description: expect.stringContaining('Use Read instead'),
+        },
+      },
+    });
+    expect(GrepInputSchema.safeParse({ pattern: 'needle' }).success).toBe(true);
+    expect(GrepInputSchema.safeParse({ pattern: 'needle', output_mode: 'content' }).success).toBe(
+      true,
+    );
+    expect(GrepInputSchema.safeParse({ pattern: 'needle', output_mode: 'bad' }).success).toBe(
+      false,
+    );
+  });
+
+  describe('output_mode enum value', () => {
+    it('accepts count_matches as the third output mode', () => {
+      expect(
+        GrepInputSchema.safeParse({ pattern: 'needle', output_mode: 'count_matches' }).success,
+      ).toBe(true);
+    });
+
+    it('rejects the legacy count value', () => {
+      expect(
+        GrepInputSchema.safeParse({ pattern: 'needle', output_mode: 'count' }).success,
+      ).toBe(false);
+    });
+
+    it('exposes count_matches and not count in the JSON Schema enum', () => {
+      const tool = new GrepTool(createFakeKaos(), workspace);
+      const params = tool.parameters as {
+        properties: { output_mode: { enum?: string[] } };
+      };
+      const enumValues = params.properties.output_mode.enum ?? [];
+      expect(enumValues).toContain('count_matches');
+      expect(enumValues).not.toContain('count');
+    });
+  });
+
+  describe('parameter descriptions', () => {
+    it('gives every documented parameter a non-empty description', () => {
+      const tool = new GrepTool(createFakeKaos(), workspace);
+      const params = tool.parameters as {
+        properties: Record<string, { description?: string }>;
+      };
+      const documented = [
+        'output_mode',
+        '-i',
+        '-n',
+        '-A',
+        '-B',
+        '-C',
+        'offset',
+        'multiline',
+        'include_ignored',
+      ];
+      for (const name of documented) {
+        const description = params.properties[name]?.description;
+        expect(description, `${name} should have a description`).toBeTruthy();
+        expect(
+          (description ?? '').trim().length,
+          `${name} description should be non-empty`,
+        ).toBeGreaterThan(0);
+      }
+    });
+
+    it('notes that context flags require content output mode', () => {
+      const tool = new GrepTool(createFakeKaos(), workspace);
+      const params = tool.parameters as {
+        properties: Record<string, { description?: string }>;
+      };
+      for (const name of ['-A', '-B', '-C', '-n']) {
+        expect(params.properties[name]?.description).toContain('content');
+      }
+    });
+
+    it('mentions count_matches in the output_mode description', () => {
+      const tool = new GrepTool(createFakeKaos(), workspace);
+      const params = tool.parameters as {
+        properties: Record<string, { description?: string }>;
+      };
+      expect(params.properties['output_mode']?.description).toContain('count_matches');
+    });
+
+    it('does not present an absolute path as a hard requirement for path', () => {
+      const tool = new GrepTool(createFakeKaos(), workspace);
+      const params = tool.parameters as {
+        properties: Record<string, { description?: string }>;
+      };
+      const description = params.properties['path']?.description ?? '';
+      expect(description).not.toMatch(/^Absolute path/);
+      expect(description.toLowerCase()).toContain('relative');
+    });
+
+    it('guides type as the more efficient filter over glob', () => {
+      const tool = new GrepTool(createFakeKaos(), workspace);
+      const params = tool.parameters as {
+        properties: Record<string, { description?: string }>;
+      };
+      const description = params.properties['type']?.description ?? '';
+      expect(description).toContain('glob');
+      expect(description).toContain('efficient');
+    });
+
+    it('describes include_ignored as covering all ignore files, not just .gitignore', () => {
+      const tool = new GrepTool(createFakeKaos(), workspace);
+      const params = tool.parameters as {
+        properties: Record<string, { description?: string }>;
+      };
+      const description = params.properties['include_ignored']?.description ?? '';
+      expect(description).toContain('.gitignore');
+      expect(description).toContain('.ignore');
+      expect(description).toContain('.rgignore');
+    });
+  });
+
+  describe('prompt content', () => {
+    it('explains ripgrep regex syntax and brace escaping', () => {
+      const tool = new GrepTool(createFakeKaos(), workspace);
+      expect(tool.description).toContain('ripgrep');
+      expect(tool.description).toContain('\\{');
+    });
+
+    it('explains hidden files, include_ignored, and sensitive-file behavior', () => {
+      const tool = new GrepTool(createFakeKaos(), workspace);
+      expect(tool.description).toContain('include_ignored');
+      expect(tool.description.toLowerCase()).toContain('hidden file');
+      expect(tool.description).toContain('.env');
+    });
+  });
+
+  it('searches only the current workspace when path is omitted', async () => {
+    const exec = vi.fn().mockResolvedValue(processWithOutput('/workspace/src/a.ts\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit' }));
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...DEFAULT_RG_ARGS,
+      '-l',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'hit',
+      '/workspace',
+    );
+    expect(result.output).toBe('src/a.ts');
+  });
+
+  it('can search an additional directory when path is explicit', async () => {
+    const exec = vi.fn().mockResolvedValue(processWithOutput('/extra/pkg/b.ts\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit', path: '/extra' }));
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...DEFAULT_RG_ARGS,
+      '-l',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'hit',
+      '/extra',
+    );
+    expect(result.output).toBe('/extra/pkg/b.ts');
+  });
+
+  it('keeps non-workspace grep result paths absolute in content and count modes', async () => {
+    const exec = vi
+      .fn()
+      .mockResolvedValueOnce(processWithOutput('/extra/pkg/b.ts:10:hit\n'))
+      .mockResolvedValueOnce(processWithOutput('/extra/pkg/b.ts:2\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const contentResult = await executeTool(tool,
+      context({ pattern: 'hit', path: '/extra', output_mode: 'content' }),
+    );
+    const countResult = await executeTool(tool,
+      context({ pattern: 'hit', path: '/extra', output_mode: 'count_matches' }),
+    );
+
+    expect(toolContentString(contentResult)).toBe('/extra/pkg/b.ts:10:hit');
+    expect(toolContentString(countResult)).toBe('/extra/pkg/b.ts:2');
+    expect((countResult as { message?: string }).message).toBe(
+      'Found 2 total occurrences across 1 file.',
+    );
+  });
+
+  it('returns an explicit non-sensitive message when ripgrep finds no matches', async () => {
+    const exec = vi.fn().mockResolvedValue(processWithOutput('', '', 1));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'missing' }));
+
+    expect(result.output).toBe('No non-sensitive matches found');
+  });
+
+  it('sorts files_with_matches by mtime before pagination after sensitive filtering', async () => {
+    const stdout = ['/workspace/src/old.ts', '/workspace/.env', '/workspace/src/new.ts', ''].join(
+      '\n',
+    );
+    const stat = vi.fn(async (path: string) => {
+      if (path === '/workspace/src/new.ts') return statResult(10);
+      if (path === '/workspace/src/old.ts') return statResult(1);
+      throw new Error(`unexpected stat: ${path}`);
+    });
+    const tool = new GrepTool(
+      createFakeKaos({ exec: vi.fn().mockResolvedValue(processWithOutput(stdout)), stat }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'hit', head_limit: 1 }));
+
+    expect(toolContentString(result)).toBe(
+      [
+        'src/new.ts',
+        'Filtered 1 sensitive file(s): .env',
+        'Results truncated to 1 lines (total: 2). Use offset=1 to see more.',
+      ].join('\n'),
+    );
+    expect(stat).toHaveBeenCalledTimes(2);
+    expect(stat).toHaveBeenCalledWith('/workspace/src/old.ts');
+    expect(stat).toHaveBeenCalledWith('/workspace/src/new.ts');
+  });
+
+  it('limits concurrent mtime stats while sorting files_with_matches', async () => {
+    const filePaths = Array.from(
+      { length: 40 },
+      (_, index) => `/workspace/src/file-${String(index).padStart(2, '0')}.ts`,
+    );
+    let activeStats = 0;
+    let maxActiveStats = 0;
+    const stat = vi.fn(async (path: string) => {
+      activeStats += 1;
+      maxActiveStats = Math.max(maxActiveStats, activeStats);
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, 0);
+      });
+      activeStats -= 1;
+      const mtime = Number(path.match(/file-(\d+)\.ts$/)?.[1] ?? 0);
+      return statResult(mtime);
+    });
+    const tool = new GrepTool(
+      createFakeKaos({
+        exec: vi.fn().mockResolvedValue(processWithOutput(`${filePaths.join('\n')}\n`)),
+        stat,
+      }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'hit', head_limit: 0 }));
+    const lines = toolContentString(result).split('\n');
+
+    expect(stat).toHaveBeenCalledTimes(filePaths.length);
+    expect(maxActiveStats).toBeLessThanOrEqual(32);
+    expect(lines.at(0)).toBe('src/file-39.ts');
+    expect(lines.at(-1)).toBe('src/file-00.ts');
+  });
+
+  it('stops scheduling mtime stats when aborted during files_with_matches sorting', async () => {
+    const filePaths = Array.from(
+      { length: 40 },
+      (_, index) => `/workspace/src/file-${String(index).padStart(2, '0')}.ts`,
+    );
+    const abortController = new AbortController();
+    const stat = vi.fn(async () => {
+      abortController.abort();
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, 0);
+      });
+      return statResult(1);
+    });
+    const tool = new GrepTool(
+      createFakeKaos({
+        exec: vi.fn().mockResolvedValue(processWithOutput(`${filePaths.join('\n')}\n`)),
+        stat,
+      }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool,
+      context({ pattern: 'hit', head_limit: 0 }, abortController.signal),
+    );
+
+    expect(result).toMatchObject({ isError: true, output: 'Grep aborted' });
+    expect(stat.mock.calls.length).toBeLessThan(filePaths.length);
+  });
+
+  it('keeps files_with_matches entries when mtime stat fails', async () => {
+    const stdout = [
+      '/workspace/src/old.ts',
+      '/workspace/src/missing.ts',
+      '/workspace/src/new.ts',
+      '',
+    ].join('\n');
+    const stat = vi.fn(async (path: string) => {
+      if (path === '/workspace/src/new.ts') return statResult(10);
+      if (path === '/workspace/src/old.ts') return statResult(1);
+      throw new Error('stat failed');
+    });
+    const tool = new GrepTool(
+      createFakeKaos({ exec: vi.fn().mockResolvedValue(processWithOutput(stdout)), stat }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'hit', head_limit: 0 }));
+
+    expect(toolContentString(result)).toBe(
+      ['src/new.ts', 'src/old.ts', 'src/missing.ts'].join('\n'),
+    );
+  });
+
+  it('uses count-matches and ignores context flags outside content output mode', async () => {
+    const exec = vi.fn().mockResolvedValue(processWithOutput('/workspace/src/a.ts:2\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    await executeTool(tool,
+      context({ pattern: 'hit', output_mode: 'count_matches', '-A': 2, '-B': 3, '-C': 4 }),
+    );
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...DEFAULT_RG_ARGS,
+      '--count-matches',
+      '--with-filename',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'hit',
+      '/workspace',
+    );
+  });
+
+  it('retries EAGAIN ripgrep failures with a single-threaded search', async () => {
+    const exec = vi
+      .fn()
+      .mockResolvedValueOnce(
+        processWithOutput('', 'rg: failed to spawn worker: Resource temporarily unavailable\n', 2),
+      )
+      .mockResolvedValueOnce(processWithOutput('/workspace/src/a.ts\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit' }));
+
+    expect(toolContentString(result)).toBe('src/a.ts');
+    expect(exec).toHaveBeenCalledTimes(2);
+    expect(exec.mock.calls[0]).not.toContain('-j');
+    expect(exec).toHaveBeenNthCalledWith(
+      2,
+      '/mock/rg',
+      '-j',
+      '1',
+      ...DEFAULT_RG_ARGS,
+      '-l',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'hit',
+      '/workspace',
+    );
+  });
+
+  it('passes public ripgrep flags through argv', async () => {
+    const exec = vi.fn().mockResolvedValue(processWithOutput('/workspace/src/a.ts\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    await executeTool(tool,
+      context({
+        pattern: 'hit',
+        '-i': true,
+        type: 'ts',
+        multiline: true,
+        include_ignored: true,
+      }),
+    );
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...DEFAULT_RG_ARGS,
+      '-l',
+      '-i',
+      '--type',
+      'ts',
+      '-U',
+      '--multiline-dotall',
+      '--no-ignore',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'hit',
+      '/workspace',
+    );
+  });
+
+  it('gives -C precedence over before and after context in content mode', async () => {
+    const exec = vi.fn().mockResolvedValue(processWithOutput('/workspace/src/a.ts:2:hit\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    await executeTool(tool,
+      context({ pattern: 'hit', output_mode: 'content', '-A': 2, '-B': 3, '-C': 4 }),
+    );
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...CONTENT_RG_ARGS,
+      '--with-filename',
+      '-n',
+      '-C',
+      '4',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'hit',
+      '/workspace',
+    );
+  });
+
+  describe('column cap by output mode', () => {
+    it('does not cap columns in content output mode so long matching lines are returned in full', async () => {
+      const exec = vi.fn().mockResolvedValue(processWithOutput('/workspace/src/a.ts:1:hit\n'));
+      const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+      await executeTool(tool, context({ pattern: 'hit', output_mode: 'content' }));
+
+      const [, ...args] = exec.mock.calls[0] ?? [];
+      expect(args).not.toContain('--max-columns');
+    });
+
+    it('caps columns in files_with_matches output mode', async () => {
+      const exec = vi.fn().mockResolvedValue(processWithOutput('/workspace/src/a.ts\n'));
+      const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+      await executeTool(tool, context({ pattern: 'hit' }));
+
+      const [, ...args] = exec.mock.calls[0] ?? [];
+      expect(args).toContain('--max-columns');
+    });
+
+    it('caps columns in count_matches output mode', async () => {
+      const exec = vi.fn().mockResolvedValue(processWithOutput('/workspace/src/a.ts:2\n'));
+      const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+      await executeTool(tool, context({ pattern: 'hit', output_mode: 'count_matches' }));
+
+      const [, ...args] = exec.mock.calls[0] ?? [];
+      expect(args).toContain('--max-columns');
+    });
+  });
+
+  it('rejects relative path escapes before spawning ripgrep', async () => {
+    const exec = vi.fn();
+    const tool = new GrepTool(createFakeKaos({ exec }), {
+      workspaceDir: '/workspace/project',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool, context({ pattern: 'hit', path: '../outside' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('absolute path');
+    expect(exec).not.toHaveBeenCalled();
+  });
+
+  it('appends sensitive prefilter globs after user glob filters', async () => {
+    const exec = vi.fn().mockResolvedValue(processWithOutput(nullRecord('/workspace/src/main.ts')));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit', glob: '**/.env' }));
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...DEFAULT_RG_ARGS,
+      '-l',
+      '--glob',
+      '**/.env',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'hit',
+      '/workspace',
+    );
+    expect(toolContentString(result)).toBe('src/main.ts');
+  });
+
+  it('does not prefilter public key files that the sensitive policy allows', async () => {
+    const stdout = [
+      '/workspace/id_rsa.pub:1:ssh-rsa hit',
+      '/workspace/id_ed25519.pub:1:ssh-ed25519 hit',
+      '/workspace/id_ecdsa.pub:1:ecdsa-sha2 hit',
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'content' }));
+
+    const [, ...args] = exec.mock.calls[0] ?? [];
+    expect(args).not.toContain('--glob !**/id_rsa[-_.]*');
+    expect(args).not.toContain('!**/id_rsa[-_.]*');
+    expect(args).not.toContain('!**/id_ed25519[-_.]*');
+    expect(args).not.toContain('!**/id_ecdsa[-_.]*');
+    expect(args).not.toContain('!**/id_rsa.pub');
+    expect(args).not.toContain('!**/id_ed25519.pub');
+    expect(args).not.toContain('!**/id_ecdsa.pub');
+    expect(toolContentString(result)).toContain('id_rsa.pub:1:ssh-rsa hit');
+    expect(toolContentString(result)).toContain('id_ed25519.pub:1:ssh-ed25519 hit');
+    expect(toolContentString(result)).toContain('id_ecdsa.pub:1:ecdsa-sha2 hit');
+    expect(toolContentString(result)).not.toContain('Filtered ');
+  });
+
+  it('filters sensitive files from content output and appends a warning', async () => {
+    const stdout = ['/workspace/src/main.ts:10:hit', '/workspace/.env:1:SECRET=hit', ''].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'content' }));
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...CONTENT_RG_ARGS,
+      '--with-filename',
+      '-n',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'hit',
+      '/workspace',
+    );
+    expect(result.output).toContain('src/main.ts:10:hit');
+    expect(result.output).not.toContain('SECRET=hit');
+    expect(result.output).toContain('Filtered 1 sensitive file(s): .env');
+  });
+
+  it('uses null-delimited content paths for sensitive filtering', async () => {
+    const stdout =
+      [
+        nullRecord('/workspace/foo-10-/.aws/credentials', '1:SECRET=hit'),
+        nullRecord('/workspace/foo:10:/.aws/credentials', '1:SECRET=hit'),
+        nullRecord('/workspace/src/main.ts', '1:hit'),
+      ].join('\n') + '\n';
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'content' }));
+
+    expect(toolContentString(result)).toBe(
+      [
+        'src/main.ts:1:hit',
+        'Filtered 2 sensitive file(s): foo-10-/.aws/credentials, foo:10:/.aws/credentials',
+      ].join('\n'),
+    );
+  });
+
+  it('reconstructs null-delimited content context separators for display', async () => {
+    const stdout =
+      [
+        nullRecord('/workspace/src/main.ts', '1-before'),
+        nullRecord('/workspace/src/main.ts', '2:hit'),
+        nullRecord('/workspace/src/main.ts', '3-after'),
+      ].join('\n') + '\n';
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'content', '-C': 1 }));
+
+    expect(toolContentString(result)).toBe(
+      ['src/main.ts-1-before', 'src/main.ts:2:hit', 'src/main.ts-3-after'].join('\n'),
+    );
+  });
+
+  it('uses a colon for null-delimited content display when line numbers are disabled', async () => {
+    const stdout = `${nullRecord('/workspace/src/main.ts', '123-hello')}\n`;
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool,
+      context({ pattern: '123', output_mode: 'content', '-n': false }),
+    );
+
+    expect(toolContentString(result)).toBe('src/main.ts:123-hello');
+  });
+
+  it('passes through bracketed payload text in content and context lines unchanged', async () => {
+    const stdout = [
+      '/workspace/src/main.ts:1:[a bracketed payload]',
+      '/workspace/src/main.ts-2-[a bracketed context payload]',
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'content', '-C': 1 }));
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...CONTENT_RG_ARGS,
+      '--with-filename',
+      '-n',
+      '-C',
+      '1',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'hit',
+      '/workspace',
+    );
+    expect(toolContentString(result)).toBe(
+      [
+        'src/main.ts:1:[a bracketed payload]',
+        'src/main.ts-2-[a bracketed context payload]',
+      ].join('\n'),
+    );
+  });
+
+  it('filters sensitive files even when content payloads contain bracketed text', async () => {
+    const stdout = [
+      '/workspace/.env:1:[a bracketed payload]',
+      '/workspace/.env-2-[a bracketed context payload]',
+      '--',
+      '/workspace/src/main.ts:1:hit',
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'content', '-C': 1 }));
+
+    expect(toolContentString(result)).toBe(
+      ['src/main.ts:1:hit', 'Filtered 1 sensitive file(s): .env'].join('\n'),
+    );
+  });
+
+  it('preserves content lines that look like workspace paths when no grep path prefix is present', async () => {
+    const exec = vi.fn().mockResolvedValue(processWithOutput('/workspace/not-a-path\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'workspace', output_mode: 'content' }));
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...CONTENT_RG_ARGS,
+      '--with-filename',
+      '-n',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'workspace',
+      '/workspace',
+    );
+    expect(result.output).toBe('/workspace/not-a-path');
+  });
+
+  it('uses the backend path class when filtering sensitive grep results', async () => {
+    const stdout = [
+      'C:\\workspace\\src\\main.ts:10:hit',
+      'C:\\workspace\\.env:1:SECRET=hit',
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec, pathClass: () => 'win32' }), {
+      workspaceDir: 'C:\\workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'content' }));
+
+    expect(result.output).toContain('src\\main.ts:10:hit');
+    expect(result.output).not.toContain('SECRET=hit');
+    expect(result.output).toContain('Filtered 1 sensitive file(s): .env');
+  });
+
+  it('uses the backend path class for Windows content output without line numbers', async () => {
+    const stdout = [
+      'C:\\workspace\\src\\main.ts:hit',
+      'C:\\workspace\\.aws\\credentials:SECRET=hit',
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec, pathClass: () => 'win32' }), {
+      workspaceDir: 'C:\\workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool,
+      context({ pattern: 'hit', output_mode: 'content', '-n': false }),
+    );
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...CONTENT_RG_ARGS,
+      '--with-filename',
+      '--field-context-separator',
+      ':',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'hit',
+      'C:\\workspace',
+    );
+    expect(toolContentString(result)).toBe(
+      ['src\\main.ts:hit', 'Filtered 1 sensitive file(s): .aws\\credentials'].join('\n'),
+    );
+  });
+
+  it('uses null-delimited Windows content paths for sensitive filtering', async () => {
+    const stdout =
+      [
+        nullRecord('C:\\workspace\\foo-10-\\.aws\\credentials', '1:SECRET=hit'),
+        nullRecord('C:\\workspace\\src\\main.ts', '1:hit'),
+      ].join('\n') + '\n';
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec, pathClass: () => 'win32' }), {
+      workspaceDir: 'C:\\workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'content' }));
+
+    expect(toolContentString(result)).toBe(
+      ['src\\main.ts:1:hit', 'Filtered 1 sensitive file(s): foo-10-\\.aws\\credentials'].join('\n'),
+    );
+  });
+
+  it('filters sensitive context lines when content output omits line numbers', async () => {
+    const stdout = [
+      '/workspace/.env:SECRET before',
+      '/workspace/.env:SECRET=hit',
+      '/workspace/.env:SECRET after',
+      '--',
+      '/workspace/src/main.ts:before',
+      '/workspace/src/main.ts:hit',
+      '/workspace/src/main.ts:after',
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool,
+      context({ pattern: 'hit', output_mode: 'content', '-n': false, '-C': 1 }),
+    );
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...CONTENT_RG_ARGS,
+      '--with-filename',
+      '--field-context-separator',
+      ':',
+      '-C',
+      '1',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'hit',
+      '/workspace',
+    );
+    expect(toolContentString(result)).toBe(
+      [
+        'src/main.ts:before',
+        'src/main.ts:hit',
+        'src/main.ts:after',
+        'Filtered 1 sensitive file(s): .env',
+      ].join('\n'),
+    );
+  });
+
+  it('filters Windows sensitive context lines when content output omits line numbers', async () => {
+    const stdout = [
+      'C:\\workspace\\.aws\\credentials:SECRET before',
+      'C:\\workspace\\.aws\\credentials:SECRET=hit',
+      'C:\\workspace\\.aws\\credentials:SECRET after',
+      '--',
+      'C:\\workspace\\src\\main.ts:before',
+      'C:\\workspace\\src\\main.ts:hit',
+      'C:\\workspace\\src\\main.ts:after',
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec, pathClass: () => 'win32' }), {
+      workspaceDir: 'C:\\workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool,
+      context({ pattern: 'hit', output_mode: 'content', '-n': false, '-C': 1 }),
+    );
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...CONTENT_RG_ARGS,
+      '--with-filename',
+      '--field-context-separator',
+      ':',
+      '-C',
+      '1',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'hit',
+      'C:\\workspace',
+    );
+    expect(toolContentString(result)).toBe(
+      [
+        'src\\main.ts:before',
+        'src\\main.ts:hit',
+        'src\\main.ts:after',
+        'Filtered 1 sensitive file(s): .aws\\credentials',
+      ].join('\n'),
+    );
+  });
+
+  it('explains when every grep result is filtered as sensitive', async () => {
+    const stdout = ['/workspace/.env:1:SECRET=hit', '/workspace/.aws/credentials:2:hit', ''].join(
+      '\n',
+    );
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), {
+      workspaceDir: '/workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'content' }));
+
+    expect(toolContentString(result)).toBe(
+      [
+        'No non-sensitive matches found',
+        'Filtered 2 sensitive file(s): .env, .aws/credentials',
+      ].join('\n'),
+    );
+  });
+
+  it('normalizes content separators after filtering sensitive grep results', async () => {
+    const stdout = [
+      '/workspace/.env:1:SECRET=hit',
+      '--',
+      '/workspace/src/main.ts:10:hit',
+      '--',
+      '/workspace/.aws/credentials:1:hit',
+      '--',
+      '/workspace/src/other.ts:7:hit',
+      '--',
+      '/workspace/credentials:1:hit',
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), {
+      workspaceDir: '/workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'content' }));
+
+    const output = toolContentString(result);
+    const content = output.split('\nFiltered ')[0] ?? output;
+    expect(content).toBe(['src/main.ts:10:hit', '--', 'src/other.ts:7:hit'].join('\n'));
+    expect(output).not.toContain('SECRET=hit');
+    expect(output).toContain('Filtered 3 sensitive file(s): .env, .aws/credentials, credentials');
+  });
+
+  it('applies offset and head_limit after rg output is collected', async () => {
+    const stdout = ['a.ts:1:hit', 'b.ts:2:hit', 'c.ts:3:hit', 'd.ts:4:hit', ''].join('\n');
+    const tool = new GrepTool(
+      createFakeKaos({ exec: vi.fn().mockResolvedValue(processWithOutput(stdout)) }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool,
+      context({ pattern: 'hit', output_mode: 'content', offset: 1, head_limit: 2 }),
+    );
+
+    expect(result.output).toContain('b.ts:2:hit');
+    expect(result.output).toContain('c.ts:3:hit');
+    expect(result.output).not.toContain('a.ts:1:hit');
+    expect(result.output).toContain('Use offset=3 to see more');
+  });
+
+  it('limits grep output to 250 lines by default', async () => {
+    const paths = Array.from({ length: 251 }, (_, index) => `/workspace/src/${String(index)}.ts`);
+    const displayPaths = Array.from({ length: 251 }, (_, index) => `src/${String(index)}.ts`);
+    const stdout = [...paths, ''].join('\n');
+    const tool = new GrepTool(
+      createFakeKaos({ exec: vi.fn().mockResolvedValue(processWithOutput(stdout)) }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'hit' }));
+    const output = toolContentString(result);
+    const lines = output.split('\n');
+
+    expect(lines.slice(0, 250)).toEqual(displayPaths.slice(0, 250));
+    expect(output).not.toContain(displayPaths[250]);
+    expect(output).toContain(
+      'Results truncated to 250 lines (total: 251). Use offset=250 to see more.',
+    );
+  });
+
+  it('treats head_limit zero as unlimited', async () => {
+    const paths = Array.from({ length: 251 }, (_, index) => `/workspace/src/${String(index)}.ts`);
+    const displayPaths = Array.from({ length: 251 }, (_, index) => `src/${String(index)}.ts`);
+    const stdout = [...paths, ''].join('\n');
+    const tool = new GrepTool(
+      createFakeKaos({ exec: vi.fn().mockResolvedValue(processWithOutput(stdout)) }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'hit', head_limit: 0 }));
+    const output = toolContentString(result);
+
+    expect(output.split('\n')).toEqual(displayPaths);
+    expect(output).not.toContain('Results truncated');
+  });
+
+  it('parses null-delimited files_with_matches output', async () => {
+    const stdout = nullRecord('/workspace/src/main.ts') + nullRecord('/workspace/.env');
+    const tool = new GrepTool(
+      createFakeKaos({ exec: vi.fn().mockResolvedValue(processWithOutput(stdout)) }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'hit' }));
+
+    expect(toolContentString(result)).toBe(
+      ['src/main.ts', 'Filtered 1 sensitive file(s): .env'].join('\n'),
+    );
+  });
+
+  it('returns an error when grep times out without partial output', async () => {
+    vi.useFakeTimers();
+    const proc = processThatExitsOnKill('');
+    const exec = vi.fn().mockResolvedValue(proc);
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const resultPromise = executeTool(tool, context({ pattern: 'slow' }));
+    await vi.advanceTimersByTimeAsync(20_000);
+    const result = await resultPromise;
+
+    expect(result).toEqual({
+      isError: true,
+      output: 'Grep timed out after 20s. Try a more specific path or pattern.',
+    });
+    expect(proc.kill).toHaveBeenCalledWith('SIGTERM');
+  });
+
+  it('returns partial grep output when timeout produced usable stdout', async () => {
+    vi.useFakeTimers();
+    const proc = processThatExitsOnKill('/workspace/src/a.ts\n');
+    const exec = vi.fn().mockResolvedValue(proc);
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const resultPromise = executeTool(tool, context({ pattern: 'slow' }));
+    await vi.advanceTimersByTimeAsync(20_000);
+    const result = await resultPromise;
+
+    expect(toolContentString(result)).toBe(
+      ['src/a.ts', 'Grep timed out after 20s; partial results returned'].join('\n'),
+    );
+    expect(proc.kill).toHaveBeenCalledWith('SIGTERM');
+  });
+
+  it('drops incomplete trailing stdout records after timeout', async () => {
+    vi.useFakeTimers();
+    const proc = processThatExitsOnKill('/workspace/src/a.ts\n/workspace/src/partial.ts');
+    const exec = vi.fn().mockResolvedValue(proc);
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const resultPromise = executeTool(tool, context({ pattern: 'slow' }));
+    await vi.advanceTimersByTimeAsync(20_000);
+    const result = await resultPromise;
+
+    expect(toolContentString(result)).toBe(
+      ['src/a.ts', 'Grep timed out after 20s; partial results returned'].join('\n'),
+    );
+  });
+
+  it('drops incomplete trailing null-delimited files_with_matches records after timeout', async () => {
+    vi.useFakeTimers();
+    const stdout = `${nullRecord('/workspace/src/a.ts')}/workspace/src/partial.ts`;
+    const proc = processThatExitsOnKill(stdout);
+    const exec = vi.fn().mockResolvedValue(proc);
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const resultPromise = executeTool(tool, context({ pattern: 'slow' }));
+    await vi.advanceTimersByTimeAsync(20_000);
+    const result = await resultPromise;
+
+    expect(toolContentString(result)).toBe(
+      ['src/a.ts', 'Grep timed out after 20s; partial results returned'].join('\n'),
+    );
+  });
+
+  it('drops incomplete trailing null-delimited content records after timeout', async () => {
+    vi.useFakeTimers();
+    const stdout = `${nullRecord('/workspace/src/a.ts', '1:hit')}\n${nullRecord(
+      '/workspace/src/partial.ts',
+      '2:hit',
+    )}`;
+    const proc = processThatExitsOnKill(stdout);
+    const exec = vi.fn().mockResolvedValue(proc);
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const resultPromise = executeTool(tool, context({ pattern: 'slow', output_mode: 'content' }));
+    await vi.advanceTimersByTimeAsync(20_000);
+    const result = await resultPromise;
+
+    expect(toolContentString(result)).toBe(
+      ['src/a.ts:1:hit', 'Grep timed out after 20s; partial results returned'].join('\n'),
+    );
+  });
+
+  it('keeps complete null-delimited context separators when timeout drops a trailing record', async () => {
+    vi.useFakeTimers();
+    const stdout = [
+      nullRecord('/workspace/src/a.ts', '1:hit'),
+      '--\r',
+      nullRecord('/workspace/src/b.ts', '2:hit'),
+      '--',
+      nullRecord('/workspace/src/c.ts', '3:hit'),
+    ].join('\n');
+    const proc = processThatExitsOnKill(
+      `${stdout}\n${nullRecord('/workspace/src/partial.ts', '4:hit')}`,
+    );
+    const exec = vi.fn().mockResolvedValue(proc);
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const resultPromise = executeTool(tool, context({ pattern: 'slow', output_mode: 'content' }));
+    await vi.advanceTimersByTimeAsync(20_000);
+    const result = await resultPromise;
+
+    expect(toolContentString(result)).toBe(
+      [
+        'src/a.ts:1:hit',
+        '--',
+        'src/b.ts:2:hit',
+        '--',
+        'src/c.ts:3:hit',
+        'Grep timed out after 20s; partial results returned',
+      ].join('\n'),
+    );
+  });
+
+  it('drops incomplete trailing stdout lines after buffer truncation', async () => {
+    const maxOutputBytes = 10 * 1024 * 1024;
+    const completeLine = '/workspace/src/a.ts:1:hit';
+    const displayedCompleteLine = 'src/a.ts:1:hit';
+    const partialLine = '/workspace/src/partial.ts:2:hit';
+    const stdout = `${completeLine}\n${partialLine}${'x'.repeat(maxOutputBytes)}`;
+    const tool = new GrepTool(
+      createFakeKaos({ exec: vi.fn().mockResolvedValue(processWithOutput(stdout)) }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'content' }));
+
+    expect(toolContentString(result)).toBe(
+      [
+        displayedCompleteLine,
+        '[stdout truncated at 10485760 bytes; incomplete trailing line omitted]',
+      ].join('\n'),
+    );
+  });
+
+  it('summarizes count output across all non-sensitive results', async () => {
+    const stdout = ['/workspace/src/a.ts:3', '/workspace/src/b.ts:7', ''].join('\n');
+    const tool = new GrepTool(
+      createFakeKaos({ exec: vi.fn().mockResolvedValue(processWithOutput(stdout)) }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'count_matches' }));
+
+    expect(toolContentString(result)).toBe(['src/a.ts:3', 'src/b.ts:7'].join('\n'));
+    expect((result as { message?: string }).message).toBe(
+      'Found 10 total occurrences across 2 files.',
+    );
+  });
+
+  it('parses null-delimited count output before sensitive filtering and summary', async () => {
+    const stdout =
+      [nullRecord('/workspace/src/a.ts', '3'), nullRecord('/workspace/.env', '99')].join('\n') +
+      '\n';
+    const tool = new GrepTool(
+      createFakeKaos({ exec: vi.fn().mockResolvedValue(processWithOutput(stdout)) }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'count_matches' }));
+
+    expect(toolContentString(result)).toBe(
+      ['src/a.ts:3', 'Filtered 1 sensitive file(s): .env'].join('\n'),
+    );
+    expect((result as { message?: string }).message).toBe(
+      'Found 3 total non-sensitive occurrences across 1 file.',
+    );
+  });
+
+  it('summarizes count output before pagination and after sensitive filtering', async () => {
+    const stdout = [
+      '/workspace/src/a.ts:3',
+      '/workspace/.env:99',
+      '/workspace/src/b.ts:7',
+      '/workspace/src/c.ts:1',
+      '',
+    ].join('\n');
+    const tool = new GrepTool(
+      createFakeKaos({ exec: vi.fn().mockResolvedValue(processWithOutput(stdout)) }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool,
+      context({ pattern: 'hit', output_mode: 'count_matches', head_limit: 2 }),
+    );
+
+    expect(toolContentString(result)).toBe(
+      ['src/a.ts:3', 'src/b.ts:7', 'Filtered 1 sensitive file(s): .env'].join('\n'),
+    );
+    expect((result as { message?: string }).message).toBe(
+      [
+        'Found 11 total non-sensitive occurrences across 3 files.',
+        'Results truncated to 2 lines (total: 3). Use offset=2 to see more.',
+      ].join('\n'),
+    );
+  });
+
+  it('does not add a zero count summary when every count result is sensitive', async () => {
+    const stdout = ['/workspace/.env:3', '/workspace/.aws/credentials:7', ''].join('\n');
+    const tool = new GrepTool(
+      createFakeKaos({ exec: vi.fn().mockResolvedValue(processWithOutput(stdout)) }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'count_matches' }));
+
+    expect(toolContentString(result)).toBe(
+      [
+        'No non-sensitive matches found',
+        'Filtered 2 sensitive file(s): .env, .aws/credentials',
+      ].join('\n'),
+    );
+  });
+
+  it('forces filename in count_matches argv so single-file searches stay consistent', async () => {
+    // ripgrep omits the filename in --count-matches output when only one file
+    // is searched, so the tool must pass --with-filename. Otherwise the
+    // per-file display line and the summary disagree (e.g. `25850` followed by
+    // `Found 0 total occurrences across 0 files.`).
+    const stdout = `${nullRecord('/workspace/src/only.ts', '25850')}\n`;
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool,
+      context({
+        pattern: 'yyyy',
+        path: '/workspace/src/only.ts',
+        output_mode: 'count_matches',
+      }),
+    );
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...DEFAULT_RG_ARGS,
+      '--count-matches',
+      '--with-filename',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'yyyy',
+      '/workspace/src/only.ts',
+    );
+    expect(toolContentString(result)).toBe('src/only.ts:25850');
+    expect((result as { message?: string }).message).toBe(
+      'Found 25850 total occurrences across 1 file.',
+    );
+  });
+
+  it('surfaces ripgrep parse errors with stderr detail', async () => {
+    const stderr = 'rg: regex parse error:\nerror: unclosed character class\n';
+    const exec = vi.fn().mockResolvedValue(processWithOutput('', stderr, 2));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: '[' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('Failed to grep: error: unclosed character class');
+    expect(result.output).toContain('ripgrep stderr:');
+    expect(exec).toHaveBeenCalledTimes(1);
+  });
+
+  it('surfaces ripgrep failures even when stderr is empty', async () => {
+    const exec = vi.fn().mockResolvedValue(processWithOutput('', '', 2));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit' }));
+
+    expect(result).toEqual({ isError: true, output: 'Failed to grep: ripgrep exited with code 2' });
+  });
+
+  it('marks ripgrep stderr as truncated when error output exceeds the cap', async () => {
+    const maxOutputBytes = 10 * 1024 * 1024;
+    const stderr = `error: very large failure\n${'x'.repeat(maxOutputBytes)}`;
+    const exec = vi.fn().mockResolvedValue(processWithOutput('', stderr, 2));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('Failed to grep: error: very large failure');
+    expect(result.output).toContain('[stderr truncated at 10485760 bytes]');
+  });
+
+  it('returns a locator error when ripgrep cannot be resolved', async () => {
+    vi.mocked(ensureRgPath).mockRejectedValueOnce(new Error('download failed'));
+    const exec = vi.fn();
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit' }));
+
+    expect(result).toEqual({ isError: true, output: 'rg unavailable: download failed' });
+    expect(exec).not.toHaveBeenCalled();
+  });
+
+  it('returns an install hint when spawning the resolved ripgrep path hits ENOENT', async () => {
+    const error = Object.assign(new Error('spawn /mock/rg ENOENT'), { code: 'ENOENT' });
+    const exec = vi.fn().mockRejectedValue(error);
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit' }));
+
+    expect(result).toEqual({
+      isError: true,
+      output: 'rg unavailable: spawn /mock/rg ENOENT',
+    });
+  });
+
+  it('returns generic spawn errors from kaos.exec', async () => {
+    const exec = vi.fn().mockRejectedValue(new Error('permission denied'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit' }));
+
+    expect(result).toEqual({ isError: true, output: 'permission denied' });
+  });
+
+  it('aborts while resolving the ripgrep path without spawning', async () => {
+    const controller = new AbortController();
+    const exec = vi.fn();
+    vi.mocked(ensureRgPath).mockImplementationOnce(({ signal: locatorSignal } = {}) => {
+      expect(locatorSignal).toBe(controller.signal);
+      return new Promise((_resolve, reject) => {
+        const rejectAbort = (): void => {
+          const error = new Error('Aborted');
+          error.name = 'AbortError';
+          reject(error);
+        };
+        if (locatorSignal?.aborted === true) {
+          rejectAbort();
+          return;
+        }
+        locatorSignal?.addEventListener('abort', rejectAbort, { once: true });
+      });
+    });
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const resultPromise = executeTool(tool, context({ pattern: 'hit' }, controller.signal));
+    controller.abort();
+    const result = await Promise.race([
+      resultPromise,
+      new Promise<'timed out'>((resolve) => {
+        setTimeout(() => {
+          resolve('timed out');
+        }, 50);
+      }),
+    ]);
+
+    expect(result).toEqual({ isError: true, output: 'Grep aborted' });
+    expect(exec).not.toHaveBeenCalled();
+  });
+
+  it('includes lines before the match for -B without -C', async () => {
+    const stdout = [
+      '/workspace/src/a.ts-1-pre1',
+      '/workspace/src/a.ts-2-pre2',
+      '/workspace/src/a.ts:3:TestClass match',
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool,
+      context({ pattern: 'TestClass', output_mode: 'content', '-B': 2 }),
+    );
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...CONTENT_RG_ARGS,
+      '--with-filename',
+      '-n',
+      '-B',
+      '2',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'TestClass',
+      '/workspace',
+    );
+    expect(toolContentString(result)).toContain('TestClass');
+    expect(toolContentString(result)).toContain('pre1');
+    expect(toolContentString(result)).toContain('pre2');
+  });
+
+  it('includes lines after the match for -A without -C', async () => {
+    const stdout = [
+      '/workspace/src/a.ts:3:TestClass match',
+      '/workspace/src/a.ts-4-post1',
+      '/workspace/src/a.ts-5-post2',
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool,
+      context({ pattern: 'TestClass', output_mode: 'content', '-A': 2 }),
+    );
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...CONTENT_RG_ARGS,
+      '--with-filename',
+      '-n',
+      '-A',
+      '2',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'TestClass',
+      '/workspace',
+    );
+    expect(toolContentString(result)).toContain('post1');
+    expect(toolContentString(result)).toContain('post2');
+  });
+
+  it('places the count-mode summary in a separate message channel', async () => {
+    // py: count_matches output is pure "path:count" lines; the
+    // human-readable "Found N occurrences" summary lives on a separate
+    // separate message channel so it never contaminates the data stream.
+    const counts = Array.from(
+      { length: 10 },
+      (_, i) => `/workspace/f${String(i)}.txt:3`,
+    );
+    const stdout = `${counts.join('\n')}\n`;
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), {
+      workspaceDir: '/workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool,
+      context({ pattern: 'word', output_mode: 'count_matches', head_limit: 3 }),
+    );
+
+    const output = toolContentString(result);
+    const summary = (result as { message?: unknown }).message;
+
+    expect(output.split('\n').filter((line) => line.trim() !== '')).toHaveLength(3);
+    for (const line of output.split('\n')) {
+      if (line.trim() === '') continue;
+      expect(line).not.toContain('Found');
+    }
+    expect(typeof summary).toBe('string');
+    expect(summary).toContain('Found 30 total occurrences across 10 files');
+    expect(summary).toContain('Results truncated to 3 lines');
+  });
+
+  it('truncates extremely long rg output with a byte-level safety cap message', async () => {
+    // py applies a DEFAULT_MAX_CHARS truncation in addition to head_limit;
+    // checks the message contains "Output is truncated".
+    const longLine = '/workspace/big.txt:1:' + 'x'.repeat(100);
+    const stdout = `${Array.from({ length: 5000 }, () => longLine).join('\n')}\n`;
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool,
+      context({ pattern: 'match', output_mode: 'content', head_limit: 0 }),
+    );
+
+    const message = (result as { message?: unknown }).message;
+    expect(typeof message).toBe('string');
+    expect(message).toContain('Output is truncated');
+  });
+
+  it('matches a pattern spanning a newline when multiline is set', async () => {
+    const stdout = [
+      "/workspace/multiline.py:2:    '''This is a",
+      "/workspace/multiline.py:3:    multiline docstring'''",
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool,
+      context({
+        pattern: String.raw`This is a\n    multiline`,
+        output_mode: 'content',
+        multiline: true,
+      }),
+    );
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...CONTENT_RG_ARGS,
+      '--with-filename',
+      '-n',
+      '-U',
+      '--multiline-dotall',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      String.raw`This is a\n    multiline`,
+      '/workspace',
+    );
+    expect(toolContentString(result)).toContain('This is a');
+    expect(toolContentString(result)).toContain('multiline');
+  });
+
+  it('reports a descriptive failure when the regex is unparseable', async () => {
+    const stderr =
+      'rg: regex parse error:\n    "[invalid"\n     ^\nerror: unclosed character class\n';
+    const exec = vi.fn().mockResolvedValue(processWithOutput('', stderr, 2));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool,
+      context({ pattern: '[invalid', output_mode: 'files_with_matches' }),
+    );
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('Failed to grep');
+  });
+
+  it('returns content when searching a single file path', async () => {
+    const exec = vi
+      .fn()
+      .mockResolvedValue(processWithOutput('/workspace/target.py:1:hello world\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool,
+      context({ pattern: 'hello', path: '/workspace/target.py', output_mode: 'content' }),
+    );
+
+    expect(exec).toHaveBeenCalledWith(
+      '/mock/rg',
+      ...CONTENT_RG_ARGS,
+      '--with-filename',
+      '-n',
+      ...SENSITIVE_RG_ARGS,
+      '--',
+      'hello',
+      '/workspace/target.py',
+    );
+    expect(toolContentString(result)).toContain('hello');
+    expect(toolContentString(result).trim().length).toBeGreaterThan(0);
+  });
+
+  it('returns a clean no-match result when offset exceeds total entries', async () => {
+    const exec = vi.fn().mockResolvedValue(processWithOutput('/workspace/only.txt\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool,
+      context({ pattern: 'data', output_mode: 'files_with_matches', offset: 100 }),
+    );
+
+    expect(result.isError).toBeFalsy();
+    expect(toolContentString(result)).toContain('No');
+    expect(toolContentString(result)).toContain('matches found');
+  });
+
+  it('emits line numbers by default in content mode', async () => {
+    const exec = vi.fn().mockResolvedValue(processWithOutput('/workspace/a.txt:1:hello\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    await executeTool(tool, context({ pattern: 'hello', output_mode: 'content' }));
+
+    const flags = exec.mock.calls[0] as string[];
+    expect(flags).toContain('-n');
+  });
+
+  it('drops the line-number column when "-n" is explicitly false', async () => {
+    const exec = vi.fn().mockResolvedValue(processWithOutput('/workspace/a.txt:hello\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool,
+      context({ pattern: 'hello', output_mode: 'content', '-n': false }),
+    );
+
+    const flags = exec.mock.calls[0] as string[];
+    expect(flags).not.toContain('-n');
+    const output = toolContentString(result);
+    for (const line of output.split('\n')) {
+      if (line.trim() === '' || line.startsWith('--')) continue;
+      expect(line.split(':')).toHaveLength(2);
+    }
+  });
+
+  it('maps schema flags onto ripgrep equivalents and tilde-expands ~ in path', async () => {
+    const exec = vi.fn().mockResolvedValue(processWithOutput('/workspace/a.ts:1:hello\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    await executeTool(tool,
+      context({
+        pattern: 'test',
+        path: '/workspace',
+        output_mode: 'content',
+        '-i': true,
+        multiline: true,
+        '-B': 2,
+        '-A': 3,
+        '-C': 1,
+        '-n': true,
+        glob: '*.py',
+        type: 'py',
+      }),
+    );
+
+    const flags = exec.mock.calls[0] as string[];
+    // -C takes precedence over -A/-B in content mode (matches existing TS lockdown)
+    expect(flags).toContain('-i');
+    expect(flags).toContain('-U');
+    expect(flags).toContain('--multiline-dotall');
+    expect(flags).toContain('-C');
+    expect(flags).toContain('-n');
+    expect(flags).toContain('--glob');
+    expect(flags).toContain('*.py');
+    expect(flags).toContain('--type');
+    expect(flags).toContain('py');
+    const ddIdx = flags.indexOf('--');
+    expect(flags[ddIdx + 1]).toBe('test');
+    expect(flags[ddIdx + 2]).toBe('/workspace');
+
+    // expanduser on ~ in path: assert the exact post-expansion path so
+    // the test fails if Grep silently treats `~` as a literal directory
+    // (canonicalizes to "/home/test/~/foo") instead of expanding it.
+    const homeTool = new GrepTool(
+      createFakeKaos({ exec, gethome: () => '/home/test' }),
+      { workspaceDir: '/home/test', additionalDirs: [] },
+    );
+    exec.mockClear();
+    await executeTool(homeTool, context({ pattern: 'x', path: '~/foo' }));
+    const expanded = exec.mock.calls[0] as string[];
+    expect(expanded.at(-1)).toBe('/home/test/foo');
+  });
+
+  it('preserves the sensitive-filter warning when every match is sensitive', async () => {
+    const exec = vi
+      .fn()
+      .mockResolvedValue(processWithOutput('/workspace/.env\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), {
+      workspaceDir: '/workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool,
+      context({ pattern: 'ONLY_IN_ENV', output_mode: 'files_with_matches' }),
+    );
+
+    const output = toolContentString(result);
+    expect(output).toContain('No non-sensitive matches found');
+    expect(output).toContain('Filtered 1 sensitive file(s): .env');
+  });
+
+  it('does not flag .env.example as sensitive', async () => {
+    const exec = vi
+      .fn()
+      .mockResolvedValue(processWithOutput('/workspace/.env.example\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), {
+      workspaceDir: '/workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool,
+      context({ pattern: 'API_KEY', output_mode: 'files_with_matches' }),
+    );
+
+    const output = toolContentString(result);
+    expect(output).toContain('.env.example');
+    expect(output).not.toContain('Filtered');
+  });
+
+  it('strips workspace prefix from rg output across record kinds (posix)', async () => {
+    const stdout = [
+      '/workspace/src/a.py:42:code',
+      '/workspace/src/b.py-41-context',
+      '--',
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), {
+      workspaceDir: '/workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool, context({ pattern: 'code', output_mode: 'content' }));
+
+    const lines = toolContentString(result).split('\n');
+    expect(lines[0]).toBe('src/a.py:42:code');
+    expect(lines[1]).toBe('src/b.py-41-context');
+  });
+
+  it('strips workspace prefix from rg output across record kinds (win32)', async () => {
+    const stdout = [
+      'C:\\repo\\src\\a.py:42:code',
+      'C:\\repo\\src\\b.py-41-context',
+      '--',
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(
+      createFakeKaos({ exec, pathClass: () => 'win32' }),
+      { workspaceDir: 'C:\\repo', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool, context({ pattern: 'code', output_mode: 'content' }));
+
+    const lines = toolContentString(result).split('\n');
+    expect(lines[0]).toBe('src\\a.py:42:code');
+    expect(lines[1]).toBe('src\\b.py-41-context');
+  });
+
+  it('passes lines through unchanged when path is not under the workspace', async () => {
+    const stdout = '/other/path/file.py:1:hit\n--\n';
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), {
+      workspaceDir: '/home/user/project',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool, context({ pattern: 'hit', output_mode: 'content' }));
+
+    const lines = toolContentString(result).split('\n');
+    expect(lines[0]).toBe('/other/path/file.py:1:hit');
+  });
+
+  it('treats a trailing-slash workspace dir the same as one without', async () => {
+    const withSep = new GrepTool(
+      createFakeKaos({ exec: vi.fn().mockResolvedValue(processWithOutput('/tmp/dir/file.py\n')) }),
+      { workspaceDir: '/tmp/dir/', additionalDirs: [] },
+    );
+    const noSep = new GrepTool(
+      createFakeKaos({ exec: vi.fn().mockResolvedValue(processWithOutput('/tmp/dir/file.py\n')) }),
+      { workspaceDir: '/tmp/dir', additionalDirs: [] },
+    );
+
+    const withSepResult = await executeTool(withSep,
+      context({ pattern: 'x', output_mode: 'files_with_matches' }),
+    );
+    const noSepResult = await executeTool(noSep,
+      context({ pattern: 'x', output_mode: 'files_with_matches' }),
+    );
+
+    expect(toolContentString(withSepResult)).toContain('file.py');
+    expect(toolContentString(noSepResult)).toContain('file.py');
+    expect(toolContentString(withSepResult)).not.toContain('/tmp/dir/file.py');
+    expect(toolContentString(noSepResult)).not.toContain('/tmp/dir/file.py');
+  });
+
+  it('does not strip a workspace dir prefix when it would match a sibling name', async () => {
+    const stdout = ['/tmp/abc/file.py', '/tmp/a/file.py', ''].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), {
+      workspaceDir: '/tmp/a',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool,
+      context({ pattern: 'x', output_mode: 'files_with_matches' }),
+    );
+    const output = toolContentString(result);
+    expect(output).toContain('/tmp/abc/file.py');
+    expect(output).toContain('file.py');
+    // The /tmp/a entry should be relativized to "file.py"; the /tmp/abc
+    // entry must stay absolute so it does not collide with the relative form.
+    expect(output.split('\n')).toEqual(expect.arrayContaining(['file.py', '/tmp/abc/file.py']));
+  });
+
+  it('relativizes a single-file absolute path against the workspace dir', async () => {
+    const exec = vi
+      .fn()
+      .mockResolvedValue(processWithOutput('/workspace/target.py:1:foo\n'));
+    const tool = new GrepTool(createFakeKaos({ exec }), {
+      workspaceDir: '/workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool,
+      context({ pattern: 'foo', path: '/workspace/target.py', output_mode: 'content' }),
+    );
+
+    const output = toolContentString(result);
+    for (const line of output.split('\n')) {
+      if (line.trim() === '' || line.startsWith('--')) continue;
+      expect(line.startsWith('/')).toBe(false);
+    }
+    expect(output).toContain('target.py');
+  });
+
+  it('filters sensitive .env inside a hyphenated subdirectory in content mode', async () => {
+    const stdout = [
+      '/workspace/my-project/.env:1:SECRET=leaked',
+      '/workspace/my-project/.env-2-context',
+      '--',
+      '/workspace/safe.txt:1:SECRET=ok',
+      '',
+    ].join('\n');
+    const exec = vi.fn().mockResolvedValue(processWithOutput(stdout));
+    const tool = new GrepTool(createFakeKaos({ exec }), {
+      workspaceDir: '/workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool,
+      context({ pattern: 'SECRET', output_mode: 'content', '-C': 1 }),
+    );
+
+    const output = toolContentString(result);
+    expect(output).toContain('safe.txt');
+    expect(output).not.toContain('leaked');
+    expect(output).toContain('Filtered');
+    expect(output).toContain('my-project/.env');
+  });
+
+  it('locks the grep description to ripgrep-tip phrasing about hidden files and include_ignored', () => {
+    const tool = new GrepTool(createFakeKaos(), workspace);
+
+    expect(tool.description).toContain('ripgrep');
+    expect(tool.description).toContain('Hidden files');
+    expect(tool.description).toContain('include_ignored');
+    expect(tool.description).toMatch(/sensitive/i);
+    expect(tool.description).toMatch(/ALWAYS use Grep tool instead of running `grep` or `rg`/);
+  });
+
+  it('aborts and kills ripgrep after the process has spawned', async () => {
+    const controller = new AbortController();
+    const proc = processThatExitsOnKill('/workspace/src/a.ts\n');
+    const exec = vi.fn(async () => {
+      controller.abort();
+      return proc;
+    });
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit' }, controller.signal));
+
+    expect(result).toEqual({ isError: true, output: 'Grep aborted' });
+    expect(exec).toHaveBeenCalledTimes(1);
+    expect(proc.kill).toHaveBeenCalledWith('SIGTERM');
+  });
+
+  it('returns an abort error without spawning when the signal is already aborted', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const exec = vi.fn();
+    const tool = new GrepTool(createFakeKaos({ exec }), workspace);
+
+    const result = await executeTool(tool, context({ pattern: 'hit' }, controller.signal));
+
+    expect(result).toEqual({ isError: true, output: 'Aborted before search started' });
+    expect(exec).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/agent-core/test/tools/input-schema-io.test.ts b/packages/agent-core/test/tools/input-schema-io.test.ts
new file mode 100644
index 000000000..4ec2b644e
--- /dev/null
+++ b/packages/agent-core/test/tools/input-schema-io.test.ts
@@ -0,0 +1,90 @@
+/**
+ * Project-level guard: every builtin tool must expose its parameter schema
+ * to the model as an *input* JSON Schema.
+ *
+ * zod v4's default `toJSONSchema` serializes the *output* view, which marks
+ * any field carrying a chain-tail `.default()` as `required`. A schema that
+ * advertises both `default` and `required` for the same field is internally
+ * contradictory, and — worse — the runtime AJV validator rejects otherwise
+ * legal tool calls that omit those defaulted fields.
+ *
+ * These tests pin the correct behavior: defaulted fields stay optional in the
+ * exposed schema, and a minimal `{}` call passes runtime argument validation.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { TaskListTool } from '../../src/tools/background/task-list';
+import { compileToolArgsValidator, validateToolArgs } from '../../src/tools/args-validator';
+import { AskUserQuestionTool } from '../../src/tools/builtin/collaboration/ask-user';
+
+/** Collect every `required` array nested anywhere inside a JSON Schema. */
+function collectRequired(schema: unknown, acc: string[] = []): string[] {
+  if (Array.isArray(schema)) {
+    for (const item of schema) collectRequired(item, acc);
+    return acc;
+  }
+  if (typeof schema !== 'object' || schema === null) return acc;
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === 'required' && Array.isArray(value)) {
+      for (const name of value) if (typeof name === 'string') acc.push(name);
+    } else {
+      collectRequired(value, acc);
+    }
+  }
+  return acc;
+}
+
+describe('builtin tool input JSON Schema', () => {
+  it('keeps AskUserQuestion defaulted fields out of `required`', () => {
+    const schema = new AskUserQuestionTool({} as never).parameters;
+    const required = collectRequired(schema);
+    // `header`, `multi_select` and option `description` all carry `.default()`
+    // and must therefore stay optional in the model-facing schema.
+    expect(required).not.toContain('header');
+    expect(required).not.toContain('multi_select');
+    expect(required).not.toContain('description');
+  });
+
+  it('keeps TaskList defaulted field out of `required`', () => {
+    const schema = new TaskListTool({} as never).parameters;
+    expect(collectRequired(schema)).not.toContain('active_only');
+  });
+
+  it('accepts an empty `{}` TaskList call through runtime argument validation', () => {
+    const tool = new TaskListTool({} as never);
+    const validator = compileToolArgsValidator(tool.parameters);
+    // `TaskList()` with no arguments is the documented default usage.
+    expect(validateToolArgs(validator, {})).toBeNull();
+  });
+
+  it('rejects an unknown top-level argument through runtime validation', () => {
+    const tool = new AskUserQuestionTool({} as never);
+    const validator = compileToolArgsValidator(tool.parameters);
+    const question = {
+      question: 'Which?',
+      options: [
+        { label: 'A', description: '' },
+        { label: 'B', description: '' },
+      ],
+    };
+    // A misspelled / hallucinated argument must surface as an invalid-args
+    // error rather than being silently accepted and dropped.
+    expect(validateToolArgs(validator, { questions: [question], bogus: true })).not.toBeNull();
+  });
+
+  it('rejects an unknown nested argument through runtime validation', () => {
+    const tool = new AskUserQuestionTool({} as never);
+    const validator = compileToolArgsValidator(tool.parameters);
+    const question = {
+      question: 'Which?',
+      options: [
+        { label: 'A', description: '' },
+        { label: 'B', description: '' },
+      ],
+      bogus: true,
+    };
+    // The closed-object guard must hold at every nesting level.
+    expect(validateToolArgs(validator, { questions: [question] })).not.toBeNull();
+  });
+});
diff --git a/packages/agent-core/test/tools/list-directory.test.ts b/packages/agent-core/test/tools/list-directory.test.ts
new file mode 100644
index 000000000..f86de5d46
--- /dev/null
+++ b/packages/agent-core/test/tools/list-directory.test.ts
@@ -0,0 +1,246 @@
+import type { Kaos } from '@moonshot-ai/kaos';
+import { describe, expect, it } from 'vitest';
+
+import {
+  LIST_DIR_CHILD_WIDTH,
+  listDirectory,
+} from '../../src/tools/support/list-directory';
+import { createFakeKaos } from './fixtures/fake-kaos';
+
+describe('listDirectory', () => {
+  it('renders a two-level tree with dirs first then files', async () => {
+    const kaos = createFakeKaos({
+      iterdir: async function* (p: string) {
+        if (p === '/w') {
+          yield '/w/src';
+          yield '/w/README.md';
+          yield '/w/package.json';
+        } else if (p === '/w/src') {
+          yield '/w/src/index.ts';
+          yield '/w/src/utils.ts';
+        }
+      } as unknown as Kaos['iterdir'],
+      stat: (async (p: string) => ({
+        // list-directory reads stMode: S_IFDIR (0o040000) vs S_IFREG (0o100000).
+        stMode: p.endsWith('src') ? 0o040_755 : 0o100_644,
+        stIno: 1,
+        stDev: 1,
+        stNlink: 1,
+        stUid: 0,
+        stGid: 0,
+        stSize: 1,
+        stAtime: 0,
+        stMtime: 0,
+        stCtime: 0,
+      })) as unknown as Kaos['stat'],
+    });
+    const tree = await listDirectory(kaos, '/w');
+    expect(tree.split('\n')[0]).toContain('src/');
+    expect(tree).toMatch(/README\.md(?!\/)/);
+    expect(tree).toMatch(/index\.ts/);
+    expect(tree).toMatch(/utils\.ts/);
+  });
+
+  it('uses the backend path class when reading child directories', async () => {
+    const seenDirs: string[] = [];
+    const kaos = createFakeKaos({
+      pathClass: () => 'win32',
+      iterdir: async function* (p: string) {
+        seenDirs.push(p);
+        if (p === 'C:\\workspace') {
+          yield 'C:\\workspace\\src';
+        } else if (p === 'C:\\workspace\\src') {
+          yield 'C:\\workspace\\src\\index.ts';
+        }
+      } as unknown as Kaos['iterdir'],
+      stat: (async (p: string) => ({
+        stMode: p.endsWith('\\src') ? 0o040_755 : 0o100_644,
+        stIno: 1,
+        stDev: 1,
+        stNlink: 1,
+        stUid: 0,
+        stGid: 0,
+        stSize: 1,
+        stAtime: 0,
+        stMtime: 0,
+        stCtime: 0,
+      })) as unknown as Kaos['stat'],
+    });
+
+    const tree = await listDirectory(kaos, 'C:\\workspace');
+
+    expect(seenDirs).toEqual(['C:\\workspace', 'C:\\workspace\\src']);
+    expect(tree).toContain('src/');
+    expect(tree).toContain('index.ts');
+  });
+
+  it('returns "(empty directory)" when the dir has no entries', async () => {
+    const kaos = createFakeKaos({
+      // eslint-disable-next-line require-yield
+      iterdir: async function* (_p: string) {} as unknown as Kaos['iterdir'],
+    });
+    const result = await listDirectory(kaos, '/empty');
+    expect(result).toBe('(empty directory)');
+  });
+
+  it('truncates to LIST_DIR_ROOT_WIDTH entries at depth 0', async () => {
+    const kaos = createFakeKaos({
+      iterdir: async function* (_p: string) {
+        for (let i = 0; i < 50; i++) {
+          yield `/w/file_${String(i).padStart(2, '0')}.txt`;
+        }
+      } as unknown as Kaos['iterdir'],
+      stat: (async () => ({
+        stMode: 0o100_644,
+        stIno: 1,
+        stDev: 1,
+        stNlink: 1,
+        stUid: 0,
+        stGid: 0,
+        stSize: 1,
+        stAtime: 0,
+        stMtime: 0,
+        stCtime: 0,
+      })) as unknown as Kaos['stat'],
+    });
+    const tree = await listDirectory(kaos, '/w');
+    expect(tree).toMatch(/\.\.\. and 20 more entries/);
+  });
+
+  it('returns [not readable] when the root directory itself is inaccessible', async () => {
+    const kaos = createFakeKaos({
+      iterdir: async function* (_p: string) {
+        throw new Error('EACCES');
+        // eslint-disable-next-line no-unreachable
+        yield '';
+      } as unknown as Kaos['iterdir'],
+    } as Parameters<typeof createFakeKaos>[0]);
+    const result = await listDirectory(kaos, '/no-access');
+    expect(result).toBe('[not readable]');
+  });
+
+  it('shows [not readable] for inaccessible subdirectory', async () => {
+    const kaos = createFakeKaos({
+      iterdir: async function* (p: string) {
+        if (p === '/w') {
+          yield '/w/locked';
+        } else {
+          throw new Error('EACCES');
+        }
+      } as unknown as Kaos['iterdir'],
+      stat: (async () => ({
+        stMode: 0o040_000,
+        stIno: 1,
+        stDev: 1,
+        stNlink: 1,
+        stUid: 0,
+        stGid: 0,
+        stSize: 1,
+        stAtime: 0,
+        stMtime: 0,
+        stCtime: 0,
+      })) as unknown as Kaos['stat'],
+    });
+    const tree = await listDirectory(kaos, '/w');
+    expect(tree).toContain('locked/');
+    expect(tree).toContain('[not readable]');
+  });
+
+  it('still lists an entry as a file when stat() throws (covers the stat-catch path)', async () => {
+    // Real-world parallel: a dangling symlink can iterdir() fine but throw
+    // on stat. The entry must still appear, plain-name (no trailing slash).
+    const kaos = createFakeKaos({
+      iterdir: async function* (p: string) {
+        if (p === '/w') {
+          yield '/w/regular.txt';
+          yield '/w/broken-link';
+        }
+      } as unknown as Kaos['iterdir'],
+      stat: (async (p: string) => {
+        if (p.endsWith('broken-link')) {
+          throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+        }
+        return {
+          stMode: 0o100_644,
+          stIno: 1,
+          stDev: 1,
+          stNlink: 1,
+          stUid: 0,
+          stGid: 0,
+          stSize: 1,
+          stAtime: 0,
+          stMtime: 0,
+          stCtime: 0,
+        };
+      }) as unknown as Kaos['stat'],
+    });
+
+    const tree = await listDirectory(kaos, '/w');
+    expect(tree).toContain('regular.txt');
+    expect(tree).toContain('broken-link');
+    expect(tree).not.toContain('broken-link/');
+  });
+
+  it('truncates child entries at LIST_DIR_CHILD_WIDTH and prints overflow under the parent', async () => {
+    const overflow = 5;
+    const childCount = LIST_DIR_CHILD_WIDTH + overflow;
+    const kaos = createFakeKaos({
+      iterdir: async function* (p: string) {
+        if (p === '/w') {
+          yield '/w/subdir';
+        } else if (p === '/w/subdir') {
+          for (let i = 0; i < childCount; i++) {
+            yield `/w/subdir/child_${String(i).padStart(3, '0')}.txt`;
+          }
+        }
+      } as unknown as Kaos['iterdir'],
+      stat: (async (p: string) => ({
+        stMode: p.endsWith('subdir') ? 0o040_755 : 0o100_644,
+        stIno: 1,
+        stDev: 1,
+        stNlink: 1,
+        stUid: 0,
+        stGid: 0,
+        stSize: 1,
+        stAtime: 0,
+        stMtime: 0,
+        stCtime: 0,
+      })) as unknown as Kaos['stat'],
+    });
+
+    const tree = await listDirectory(kaos, '/w');
+    const lines = tree.split('\n');
+    expect(lines).toHaveLength(1 + LIST_DIR_CHILD_WIDTH + 1);
+    expect(lines[0]).toContain('subdir/');
+    expect(lines.at(-1)).toBe(`    └── ... and ${String(overflow)} more`);
+  });
+
+  it('uses a 4-space prefix (not "│   ") when the last root entry is a directory', async () => {
+    // Branch lockdown: when there is no sibling after a dir, child rows
+    // align under a blank gutter — `└── only_dir/\n    └── child.txt`.
+    const kaos = createFakeKaos({
+      iterdir: async function* (p: string) {
+        if (p === '/w') {
+          yield '/w/only_dir';
+        } else if (p === '/w/only_dir') {
+          yield '/w/only_dir/child.txt';
+        }
+      } as unknown as Kaos['iterdir'],
+      stat: (async (p: string) => ({
+        stMode: p.endsWith('only_dir') ? 0o040_755 : 0o100_644,
+        stIno: 1,
+        stDev: 1,
+        stNlink: 1,
+        stUid: 0,
+        stGid: 0,
+        stSize: 1,
+        stAtime: 0,
+        stMtime: 0,
+        stCtime: 0,
+      })) as unknown as Kaos['stat'],
+    });
+
+    const tree = await listDirectory(kaos, '/w');
+    expect(tree).toBe('└── only_dir/\n    └── child.txt');
+  });
+});
diff --git a/packages/agent-core/test/tools/path-guard.test.ts b/packages/agent-core/test/tools/path-guard.test.ts
new file mode 100644
index 000000000..75c54eda7
--- /dev/null
+++ b/packages/agent-core/test/tools/path-guard.test.ts
@@ -0,0 +1,411 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  canonicalizePath,
+  DEFAULT_WORKSPACE_ACCESS_POLICY,
+  isWithinDirectory,
+  isWithinWorkspace,
+  normalizeUserPath,
+  PathSecurityError,
+  STRICT_WORKSPACE_ACCESS_POLICY,
+  assertPathAllowed,
+  resolvePathAccess,
+  resolvePathAccessPath,
+} from '../../src/tools/policies/path-access';
+import { isSensitiveFile } from '../../src/tools/policies/sensitive';
+import type { WorkspaceConfig } from '../../src/tools/support/workspace';
+
+const WORKSPACE: WorkspaceConfig = {
+  workspaceDir: '/workspace',
+  additionalDirs: ['/extra'],
+};
+
+const WIN_WORKSPACE: WorkspaceConfig = {
+  workspaceDir: 'C:\\workspace',
+  additionalDirs: ['D:\\extra'],
+};
+
+const POSIX_KAOS = {
+  pathClass: () => 'posix' as const,
+  gethome: () => '/home/test',
+};
+
+describe('path access policy', () => {
+  it('strict policy rejects absolute paths outside workspace roots', () => {
+    expect(() =>
+      resolvePathAccess('/etc/hosts', '/workspace', WORKSPACE, {
+        operation: 'read',
+        policy: STRICT_WORKSPACE_ACCESS_POLICY,
+      }),
+    ).toThrow(PathSecurityError);
+  });
+
+  it('default policy allows absolute paths outside workspace roots', () => {
+    const result = resolvePathAccess('/etc/hosts', '/workspace', WORKSPACE, {
+      operation: 'read',
+      policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+    });
+    expect(result).toEqual({ path: '/etc/hosts', outsideWorkspace: true });
+  });
+
+  it('default policy rejects relative paths that escape workspace roots', () => {
+    expect(() =>
+      resolvePathAccess('../../outside.txt', '/workspace/project', WORKSPACE, {
+        operation: 'read',
+        policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+      }),
+    ).toThrow(/absolute path/);
+  });
+
+  it('does not duplicate outside-working-directory wording for search paths', () => {
+    try {
+      resolvePathAccess('../../outside.txt', '/workspace/project', WORKSPACE, {
+        operation: 'search',
+        policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+      });
+    } catch (error) {
+      expect(error).toBeInstanceOf(PathSecurityError);
+      const message = (error as PathSecurityError).message;
+      const matches = message.match(/outside the working directory/g) ?? [];
+      expect(matches).toHaveLength(1);
+      expect(message).toBe(
+        '"../../outside.txt" is not an absolute path. You must provide an absolute path to search outside the working directory.',
+      );
+      return;
+    }
+
+    throw new Error('Expected resolvePathAccess to reject escaping relative search path');
+  });
+
+  it('disabled policy allows relative paths that escape workspace roots', () => {
+    const result = resolvePathAccess('../../outside.txt', '/workspace/project', WORKSPACE, {
+      operation: 'read',
+      policy: { guardMode: 'disabled', checkSensitive: true },
+    });
+    expect(result).toEqual({ path: '/outside.txt', outsideWorkspace: true });
+  });
+
+  it('expands leading tilde paths against the provided home directory', () => {
+    const file = resolvePathAccess('~/notes/today.txt', '/workspace', WORKSPACE, {
+      operation: 'read',
+      policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+      homeDir: '/home/test',
+    });
+    expect(file).toEqual({ path: '/home/test/notes/today.txt', outsideWorkspace: true });
+
+    const home = resolvePathAccess('~', '/workspace', WORKSPACE, {
+      operation: 'read',
+      policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+      homeDir: '/home/test',
+    });
+    expect(home).toEqual({ path: '/home/test', outsideWorkspace: true });
+
+    const namedUser = resolvePathAccess('~other/notes.txt', '/workspace', WORKSPACE, {
+      operation: 'read',
+      policy: { guardMode: 'disabled', checkSensitive: true },
+      homeDir: '/home/test',
+    });
+    expect(namedUser).toEqual({ path: '/workspace/~other/notes.txt', outsideWorkspace: false });
+  });
+
+  it('sensitive-file protection is independent from workspace policy', () => {
+    expect(() =>
+      resolvePathAccess('/tmp/.env', '/workspace', WORKSPACE, {
+        operation: 'read',
+        policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+      }),
+    ).toThrow(/sensitive-file pattern/);
+  });
+
+  it('resolves only the canonical path for file tools', () => {
+    const result = resolvePathAccessPath('src/../README.md', {
+      kaos: POSIX_KAOS,
+      workspace: { workspaceDir: '/workspace/project', additionalDirs: [] },
+      operation: 'read',
+    });
+
+    expect(result).toBe('/workspace/project/README.md');
+  });
+
+  it('expands home for file tools unless explicitly disabled', () => {
+    const workspace = { workspaceDir: '/workspace', additionalDirs: [] };
+
+    expect(
+      resolvePathAccessPath('~/notes/today.txt', {
+        kaos: POSIX_KAOS,
+        workspace,
+        operation: 'read',
+      }),
+    ).toBe('/home/test/notes/today.txt');
+    expect(
+      resolvePathAccessPath('~/notes/today.txt', {
+        kaos: POSIX_KAOS,
+        workspace,
+        operation: 'read',
+        expandHome: false,
+      }),
+    ).toBe('/workspace/~/notes/today.txt');
+  });
+
+  it('legacy assertPathAllowed keeps strict shared-prefix behavior', () => {
+    expect(() =>
+      assertPathAllowed('/workspace-evil/secrets.txt', '/workspace', WORKSPACE, {
+        mode: 'read',
+      }),
+    ).toThrow(/outside the workspace/);
+  });
+
+  it('canonicalizes paths with an explicit posix path class', () => {
+    expect(canonicalizePath('../file.txt', '/workspace/project', 'posix')).toBe(
+      '/workspace/file.txt',
+    );
+  });
+
+  it('canonicalizes and checks windows paths with an explicit win32 path class', () => {
+    const result = resolvePathAccess('sub\\..\\file.txt', 'C:\\workspace', WIN_WORKSPACE, {
+      operation: 'read',
+      pathClass: 'win32',
+      policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+    });
+
+    expect(result).toEqual({ path: 'C:\\workspace\\file.txt', outsideWorkspace: false });
+    expect(isWithinDirectory('C:\\WORKSPACE\\file.txt', 'c:\\workspace', 'win32')).toBe(true);
+  });
+
+  it('converts Git Bash POSIX drive paths before applying win32 workspace checks', () => {
+    const result = resolvePathAccess('/c/workspace/file.txt', 'C:\\workspace', WIN_WORKSPACE, {
+      operation: 'read',
+      pathClass: 'win32',
+      policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+      homeDir: 'C:\\Users\\test',
+    });
+
+    expect(result).toEqual({ path: 'C:\\workspace\\file.txt', outsideWorkspace: false });
+  });
+
+  it('uses the provided path class when deciding whether an outside path is absolute', () => {
+    const result = resolvePathAccess('C:\\outside\\file.txt', 'C:\\workspace', WIN_WORKSPACE, {
+      operation: 'read',
+      pathClass: 'win32',
+      policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+    });
+
+    expect(result).toEqual({ path: 'C:\\outside\\file.txt', outsideWorkspace: true });
+  });
+
+  it('expands leading tilde paths with the provided win32 home directory', () => {
+    const result = resolvePathAccess('~\\notes\\today.txt', 'C:\\workspace', WIN_WORKSPACE, {
+      operation: 'read',
+      pathClass: 'win32',
+      policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+      homeDir: 'C:\\Users\\test',
+    });
+
+    expect(result).toEqual({
+      path: 'C:\\Users\\test\\notes\\today.txt',
+      outsideWorkspace: true,
+    });
+  });
+
+  it('rejects windows drive-relative paths without consulting host cwd state', () => {
+    expect(() =>
+      resolvePathAccess('D:outside.txt', 'C:\\workspace', WIN_WORKSPACE, {
+        operation: 'read',
+        pathClass: 'win32',
+        policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+      }),
+    ).toThrow(/drive-relative Windows path/);
+  });
+
+  it('uses the provided path class for sensitive-file detection', () => {
+    expect(() =>
+      resolvePathAccess('C:\\tmp\\.env', 'C:\\workspace', WIN_WORKSPACE, {
+        operation: 'read',
+        pathClass: 'win32',
+        policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+      }),
+    ).toThrow(/sensitive-file pattern/);
+  });
+
+  it('matches sensitive-file patterns case-insensitively for windows paths', () => {
+    expect(() =>
+      resolvePathAccess('C:\\tmp\\.ENV', 'C:\\workspace', WIN_WORKSPACE, {
+        operation: 'read',
+        pathClass: 'win32',
+        policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+      }),
+    ).toThrow(/sensitive-file pattern/);
+
+    expect(() =>
+      resolvePathAccess('C:\\Users\\me\\.AWS\\Credentials', 'C:\\workspace', WIN_WORKSPACE, {
+        operation: 'read',
+        pathClass: 'win32',
+        policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+      }),
+    ).toThrow(/sensitive-file pattern/);
+  });
+
+  it('treats a directory as within itself', () => {
+    expect(isWithinDirectory('/home/user/project', '/home/user/project')).toBe(true);
+  });
+
+  it('accepts the workspace root path against itself', () => {
+    expect(isWithinWorkspace('/workspace', WORKSPACE)).toBe(true);
+  });
+
+  it('accepts an additionalDir entry path itself', () => {
+    expect(isWithinDirectory('/extra', '/extra')).toBe(true);
+    expect(isWithinWorkspace('/extra', WORKSPACE)).toBe(true);
+  });
+
+  it('accepts paths inside any additionalDir entry', () => {
+    expect(isWithinWorkspace('/extra/lib/file.py', WORKSPACE)).toBe(true);
+
+    const result = resolvePathAccess('/extra/lib/file.py', '/workspace', WORKSPACE, {
+      operation: 'read',
+      policy: DEFAULT_WORKSPACE_ACCESS_POLICY,
+    });
+    expect(result).toEqual({ path: '/extra/lib/file.py', outsideWorkspace: false });
+  });
+
+  it('treats multiple additionalDir entries as a union', () => {
+    const multi: WorkspaceConfig = {
+      workspaceDir: '/workspace',
+      additionalDirs: ['/lib', '/opt/shared'],
+    };
+    expect(isWithinWorkspace('/opt/shared/config.json', multi)).toBe(true);
+    expect(isWithinWorkspace('/lib/module.js', multi)).toBe(true);
+    expect(isWithinWorkspace('/elsewhere/file', multi)).toBe(false);
+  });
+
+  it('rejects a shared-prefix attack against an additionalDir entry', () => {
+    const cfg: WorkspaceConfig = {
+      workspaceDir: '/workspace',
+      additionalDirs: ['/lib'],
+    };
+    expect(isWithinWorkspace('/lib-evil/hack.py', cfg)).toBe(false);
+    expect(() =>
+      resolvePathAccess('/lib-evil/hack.py', '/workspace', cfg, {
+        operation: 'read',
+        policy: STRICT_WORKSPACE_ACCESS_POLICY,
+      }),
+    ).toThrow(PathSecurityError);
+  });
+
+  it('uses path-segment containment rather than naive startsWith for additionalDir entries', () => {
+    const cfg: WorkspaceConfig = {
+      workspaceDir: '/workspace',
+      additionalDirs: ['/app-data'],
+    };
+    expect(isWithinWorkspace('/app-data/file.txt', cfg)).toBe(true);
+    expect(isWithinWorkspace('/app-data-evil/file.txt', cfg)).toBe(false);
+  });
+
+  it('tolerates forward slashes in win32 mode for containment checks', () => {
+    expect(
+      isWithinDirectory(
+        'C:/Users/user/project/src/main.py',
+        'C:/Users/user/project',
+        'win32',
+      ),
+    ).toBe(true);
+  });
+
+  describe('normalizeUserPath on win32', () => {
+    it('rewrites MSYS-style drive paths to native form', () => {
+      expect(normalizeUserPath('/c/Users/foo/file.txt', 'win32')).toBe('C:\\Users\\foo\\file.txt');
+    });
+
+    it('rewrites a bare MSYS drive root to native form', () => {
+      expect(normalizeUserPath('/c/', 'win32')).toBe('C:\\');
+      expect(normalizeUserPath('/c', 'win32')).toBe('C:\\');
+    });
+
+    it('canonicalizes the drive letter to uppercase', () => {
+      expect(normalizeUserPath('/C/Users/foo', 'win32')).toBe('C:\\Users\\foo');
+    });
+
+    it('rewrites cygdrive-style paths to native form', () => {
+      expect(normalizeUserPath('/cygdrive/c/Users/foo', 'win32')).toBe('C:\\Users\\foo');
+      expect(normalizeUserPath('/cygdrive/d/Projects', 'win32')).toBe('D:\\Projects');
+    });
+
+    it('rewrites UNC paths by flipping every slash', () => {
+      expect(normalizeUserPath('//server/share/file', 'win32')).toBe('\\\\server\\share\\file');
+      expect(normalizeUserPath('//server/share', 'win32')).toBe('\\\\server\\share');
+    });
+
+    it('leaves already-native windows paths untouched', () => {
+      expect(normalizeUserPath('C:\\Users\\foo', 'win32')).toBe('C:\\Users\\foo');
+      expect(normalizeUserPath('D:\\Projects', 'win32')).toBe('D:\\Projects');
+    });
+
+    it('does not rewrite relative paths', () => {
+      expect(normalizeUserPath('relative/path', 'win32')).toBe('relative/path');
+      expect(normalizeUserPath('relative\\path', 'win32')).toBe('relative\\path');
+      expect(normalizeUserPath('file.txt', 'win32')).toBe('file.txt');
+    });
+
+    it('leaves leading tilde untouched (expansion happens elsewhere)', () => {
+      expect(normalizeUserPath('~/Documents', 'win32')).toBe('~/Documents');
+    });
+
+  });
+
+  describe('normalizeUserPath on posix', () => {
+    it('leaves MSYS-shaped paths alone', () => {
+      expect(normalizeUserPath('/c/Users/foo', 'posix')).toBe('/c/Users/foo');
+      expect(normalizeUserPath('/cygdrive/x', 'posix')).toBe('/cygdrive/x');
+    });
+
+    it('leaves UNC-shaped paths alone', () => {
+      expect(normalizeUserPath('//server/share', 'posix')).toBe('//server/share');
+    });
+  });
+
+  describe('normalizeUserPath full posix-to-windows coverage', () => {
+    const cases: ReadonlyArray<readonly [string, string]> = [
+      ['/c/Users/foo', 'C:\\Users\\foo'],
+      ['/d/Projects/kimi', 'D:\\Projects\\kimi'],
+      ['/C/Users/foo', 'C:\\Users\\foo'],
+      ['/c/', 'C:\\'],
+      ['/c', 'C:\\'],
+      ['/cygdrive/c/Users/foo', 'C:\\Users\\foo'],
+      ['/cygdrive/d/Projects', 'D:\\Projects'],
+      ['//server/share', '\\\\server\\share'],
+      ['//server/share/file.txt', '\\\\server\\share\\file.txt'],
+      ['relative/path/file.txt', 'relative/path/file.txt'],
+      ['relative\\already\\windows', 'relative\\already\\windows'],
+      ['filename.txt', 'filename.txt'],
+    ];
+
+    for (const [input, expected] of cases) {
+      it(`normalizes "${input}"`, () => {
+        expect(normalizeUserPath(input, 'win32')).toBe(expected);
+      });
+    }
+  });
+
+  it('aggressively rewrites short-input forms on win32', () => {
+    // Pathological short inputs: empty, lone slash, and a single character.
+    // Treated as a divergence lockdown — the bare "/" branch differs from
+    // the upstream raw helper which flips the slash.
+    expect(normalizeUserPath('', 'win32')).toBe('');
+    expect(normalizeUserPath('/', 'win32')).toBe('\\');
+    expect(normalizeUserPath('a', 'win32')).toBe('a');
+  });
+
+  describe('isSensitiveFile SSH key coverage', () => {
+    const keys = ['id_rsa', 'id_ed25519', 'id_ecdsa'];
+
+    for (const key of keys) {
+      it(`flags ${key} as sensitive by basename`, () => {
+        expect(isSensitiveFile(key, 'posix')).toBe(true);
+      });
+
+      it(`flags /home/user/.ssh/${key} as sensitive`, () => {
+        expect(isSensitiveFile(`/home/user/.ssh/${key}`, 'posix')).toBe(true);
+      });
+    }
+  });
+});
diff --git a/packages/agent-core/test/tools/plan-mode-hard-block.test.ts b/packages/agent-core/test/tools/plan-mode-hard-block.test.ts
new file mode 100644
index 000000000..2cea3b42e
--- /dev/null
+++ b/packages/agent-core/test/tools/plan-mode-hard-block.test.ts
@@ -0,0 +1,177 @@
+import type { ToolCall } from '@moonshot-ai/kosong';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Agent } from '../../src/agent';
+import { PlanModeGuardPermissionPolicy } from '../../src/agent/permission/policies/plan';
+import type { PermissionMode } from '../../src/agent/permission/types';
+import type { PermissionPolicyContext } from '../../src/agent/permission/policy';
+import { PlanMode } from '../../src/agent/plan';
+import type { ToolExecutionHookContext } from '../../src/loop';
+
+const signal = new AbortController().signal;
+
+async function activePlanAgent(): Promise<{ agent: Agent; planMode: PlanMode }> {
+  const agent = {
+    homedir: '/tmp/kimi-plan-test',
+    emitStatusUpdated: vi.fn(),
+    records: { logRecord: vi.fn() },
+    replayBuilder: { push: vi.fn() },
+    runtime: {
+      kaos: {
+        mkdir: vi.fn().mockResolvedValue(undefined),
+      },
+    },
+  } as unknown as Agent;
+  const planMode = new PlanMode(agent);
+  Object.assign(agent, { planMode });
+  await planMode.enter('current-plan', false);
+  return { agent, planMode };
+}
+
+function hookContext(toolName: string, args: unknown): ToolExecutionHookContext {
+  return {
+    turnId: '0',
+    stepNumber: 1,
+    signal,
+    llm: {},
+    args,
+    toolCall: {
+      type: 'function',
+      id: `call_${toolName}`,
+      function: {
+        name: toolName,
+        arguments: JSON.stringify(args),
+      },
+    } satisfies ToolCall,
+  } as ToolExecutionHookContext;
+}
+
+function policyContext(
+  agent: Agent,
+  toolName: string,
+  args: unknown,
+  mode: PermissionMode = 'manual',
+): PermissionPolicyContext {
+  return {
+    agent,
+    mode,
+    toolCallContext: hookContext(toolName, args),
+    matchedRule: undefined,
+    recordApprovalResult: vi.fn(),
+  };
+}
+
+describe('Plan mode permission policy', () => {
+  it('allows Write and Edit to the active plan file', async () => {
+    const { agent, planMode } = await activePlanAgent();
+    const planPath = planMode.planFilePath;
+    if (planPath === null) throw new Error('expected plan path');
+
+    expect(
+      await PlanModeGuardPermissionPolicy.evaluate(policyContext(agent, 'Write', { path: planPath })),
+    ).toEqual({ kind: 'allow' });
+    expect(
+      await PlanModeGuardPermissionPolicy.evaluate(
+        policyContext(agent, 'Edit', {
+          path: planPath,
+          old_string: 'A',
+          new_string: 'B',
+        }),
+      ),
+    ).toEqual({ kind: 'allow' });
+  });
+
+  it('blocks Write and Edit to non-plan files before permission approval', async () => {
+    const { agent } = await activePlanAgent();
+
+    const write = await PlanModeGuardPermissionPolicy.evaluate(
+      policyContext(agent, 'Write', { path: '/workspace/src/main.ts', content: 'x' }),
+    );
+    const edit = await PlanModeGuardPermissionPolicy.evaluate(
+      policyContext(agent, 'Edit', {
+        path: '/workspace/src/main.ts',
+        old_string: 'A',
+        new_string: 'B',
+      }),
+    );
+
+    expect(write).toMatchObject({ kind: 'result', result: { block: true } });
+    expect(write?.kind === 'result' ? write.result.reason : '').toContain('current plan file');
+    expect(write?.kind === 'result' ? write.result.reason : '').toContain('ExitPlanMode');
+    expect(edit).toMatchObject({ kind: 'result', result: { block: true } });
+    expect(edit?.kind === 'result' ? edit.result.reason : '').toContain('current plan file');
+  });
+
+  it('blocks file edits when plan mode has no selected plan file path', async () => {
+    const { agent, planMode } = await activePlanAgent();
+    (planMode as unknown as { _planFilePath: string | null })._planFilePath = null;
+
+    const result = await PlanModeGuardPermissionPolicy.evaluate(
+      policyContext(agent, 'Edit', {
+        path: '/workspace/src/other.ts',
+        old_string: 'A',
+        new_string: 'B',
+      }),
+    );
+
+    expect(result).toMatchObject({ kind: 'result', result: { block: true } });
+    expect(result?.kind === 'result' ? result.result.reason : '').toContain(
+      '(no plan file selected yet)',
+    );
+    expect(result?.kind === 'result' ? result.result.reason : '').toContain('ExitPlanMode');
+  });
+
+  it.each(['manual', 'yolo', 'auto'] as const)(
+    'defers Bash to ordinary %s permission handling while plan mode is active',
+    async (mode) => {
+      const { agent } = await activePlanAgent();
+
+      expect(
+        await PlanModeGuardPermissionPolicy.evaluate(
+          policyContext(agent, 'Bash', { command: 'rm foo.txt' }, mode),
+        ),
+      ).toBeUndefined();
+      expect(
+        await PlanModeGuardPermissionPolicy.evaluate(
+          policyContext(agent, 'Bash', { command: 'ls -la' }, mode),
+        ),
+      ).toBeUndefined();
+    },
+  );
+
+  it.each(['manual', 'yolo', 'auto'] as const)(
+    'blocks TaskStop while plan mode is active in %s mode',
+    async (mode) => {
+      const { agent } = await activePlanAgent();
+
+      const result = await PlanModeGuardPermissionPolicy.evaluate(
+        policyContext(agent, 'TaskStop', { task_id: 'bash-abc12345' }, mode),
+      );
+
+      expect(result).toMatchObject({ kind: 'result', result: { block: true } });
+      expect(result?.kind === 'result' ? result.result.reason : '').toContain('plan mode');
+      expect(result?.kind === 'result' ? result.result.reason : '').toContain('ExitPlanMode');
+    },
+  );
+
+  it('does not block anything once plan mode has exited', async () => {
+    const { agent, planMode } = await activePlanAgent();
+    planMode.exit();
+
+    expect(
+      await PlanModeGuardPermissionPolicy.evaluate(
+        policyContext(agent, 'Write', { path: '/workspace/src/main.ts' }),
+      ),
+    ).toBeUndefined();
+    expect(
+      await PlanModeGuardPermissionPolicy.evaluate(
+        policyContext(agent, 'Bash', { command: 'rm foo.txt' }),
+      ),
+    ).toBeUndefined();
+    expect(
+      await PlanModeGuardPermissionPolicy.evaluate(
+        policyContext(agent, 'TaskStop', { task_id: 'bash-abc12345' }),
+      ),
+    ).toBeUndefined();
+  });
+});
diff --git a/packages/agent-core/test/tools/planning/enter-plan-mode-telemetry.test.ts b/packages/agent-core/test/tools/planning/enter-plan-mode-telemetry.test.ts
new file mode 100644
index 000000000..2b6d6d8cf
--- /dev/null
+++ b/packages/agent-core/test/tools/planning/enter-plan-mode-telemetry.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Agent } from '../../../src/agent';
+import type { PermissionMode } from '../../../src/agent/permission';
+import { EnterPlanModeTool } from '../../../src/tools/builtin/planning/enter-plan-mode';
+import { executeTool } from '../fixtures/execute-tool';
+
+function makeAgent(mode: PermissionMode): {
+  readonly agent: Agent;
+  readonly requestApproval: ReturnType<typeof vi.fn>;
+  readonly telemetryTrack: ReturnType<typeof vi.fn>;
+} {
+  let active = false;
+  const requestApproval = vi.fn(async () => ({ decision: 'approved' }));
+  const telemetryTrack = vi.fn();
+  const agent = {
+    planMode: {
+      get isActive() {
+        return active;
+      },
+      get planFilePath() {
+        return '/tmp/kimi-plan.md';
+      },
+      enter: vi.fn(async () => {
+        active = true;
+      }),
+    },
+    permission: { mode },
+    rpc: { requestApproval },
+    telemetry: { track: telemetryTrack },
+  } as unknown as Agent;
+  return { agent, requestApproval, telemetryTrack };
+}
+
+describe('EnterPlanMode telemetry', () => {
+  it.each(['manual', 'auto', 'yolo'] satisfies PermissionMode[])(
+    'tracks direct entry as auto_approved in %s mode',
+    async (mode) => {
+      const { agent, requestApproval, telemetryTrack } = makeAgent(mode);
+
+      const result = await executeTool(new EnterPlanModeTool(agent), {
+        turnId: '0',
+        toolCallId: `call_${mode}`,
+        args: {},
+        signal: new AbortController().signal,
+      });
+
+      expect(result.isError).toBeFalsy();
+      expect(requestApproval).not.toHaveBeenCalled();
+      expect(telemetryTrack).toHaveBeenCalledWith('plan_enter_resolved', {
+        outcome: 'auto_approved',
+      });
+    },
+  );
+});
diff --git a/packages/agent-core/test/tools/planning/exit-plan-mode-telemetry.test.ts b/packages/agent-core/test/tools/planning/exit-plan-mode-telemetry.test.ts
new file mode 100644
index 000000000..ddba6e47e
--- /dev/null
+++ b/packages/agent-core/test/tools/planning/exit-plan-mode-telemetry.test.ts
@@ -0,0 +1,195 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Agent } from '../../../src/agent';
+import {
+  PermissionManager,
+  type ApprovalResponse,
+  type PermissionMode,
+} from '../../../src/agent/permission';
+import type { ToolExecutionHookContext } from '../../../src/loop';
+import {
+  ExitPlanModeTool,
+  type ExitPlanModeInput,
+} from '../../../src/tools/builtin/planning/exit-plan-mode';
+import { createFakeKaos } from '../fixtures/fake-kaos';
+import { executeTool } from '../fixtures/execute-tool';
+
+const options = [
+  { label: 'Approach A', description: 'Small change.' },
+  { label: 'Approach B', description: 'Larger change.' },
+] satisfies NonNullable<ExitPlanModeInput['options']>;
+
+function makeAgent(input: {
+  readonly mode: PermissionMode;
+  readonly approval?: ApprovalResponse;
+}): {
+  readonly agent: Agent;
+  readonly telemetryTrack: ReturnType<typeof vi.fn>;
+  readonly exitPlanMode: ReturnType<typeof vi.fn>;
+} {
+  let active = true;
+  const telemetryTrack = vi.fn();
+  const exitPlanMode = vi.fn(() => {
+    active = false;
+  });
+  const agent = {
+    planMode: {
+      get isActive() {
+        return active;
+      },
+      get planFilePath() {
+        return '/tmp/kimi-plan.md';
+      },
+      data: vi.fn(async () => ({
+        content: '# Plan',
+        path: '/tmp/kimi-plan.md',
+      })),
+      exit: exitPlanMode,
+    },
+    permission: { mode: input.mode },
+    type: 'main',
+    config: { cwd: '/workspace' },
+    runtime: { kaos: createFakeKaos() },
+    emitStatusUpdated: vi.fn(),
+    records: { logRecord: vi.fn() },
+    replayBuilder: { push: vi.fn() },
+    rpc: {
+      requestApproval: vi.fn(async () => input.approval ?? { decision: 'approved' }),
+    },
+    telemetry: { track: telemetryTrack },
+  } as unknown as Agent;
+  return { agent, telemetryTrack, exitPlanMode };
+}
+
+async function execute(agent: Agent, args: ExitPlanModeInput = {}) {
+  const manager = new PermissionManager(agent);
+  manager.mode = agent.permission.mode;
+  const permissionResult = await manager.beforeToolCall(permissionContext(args));
+  if (permissionResult?.syntheticResult !== undefined) {
+    return permissionResult.syntheticResult;
+  }
+  return executeTool(new ExitPlanModeTool(agent), {
+    turnId: '7',
+    toolCallId: 'call_exit_plan',
+    args,
+    metadata: permissionResult?.executionMetadata,
+    signal: new AbortController().signal,
+  });
+}
+
+function permissionContext(args: ExitPlanModeInput): ToolExecutionHookContext {
+  return {
+    turnId: '7',
+    stepNumber: 1,
+    signal: new AbortController().signal,
+    llm: {} as ToolExecutionHookContext['llm'],
+    toolCall: {
+      id: 'call_exit_plan',
+      type: 'function',
+      function: {
+        name: 'ExitPlanMode',
+        arguments: JSON.stringify(args),
+      },
+    },
+    args,
+  };
+}
+
+describe('ExitPlanMode telemetry', () => {
+  it('tracks submitted without options and auto approval', async () => {
+    const { agent, telemetryTrack, exitPlanMode } = makeAgent({ mode: 'auto' });
+
+    const result = await execute(agent);
+
+    expect(result.isError).toBe(false);
+    expect(exitPlanMode).toHaveBeenCalledTimes(1);
+    expect(telemetryTrack).toHaveBeenCalledWith('plan_submitted', { has_options: false });
+    expect(telemetryTrack).toHaveBeenCalledWith('plan_resolved', {
+      outcome: 'auto_approved',
+    });
+  });
+
+  it('tracks approved multi-option plans with the chosen option', async () => {
+    const { agent, telemetryTrack, exitPlanMode } = makeAgent({
+      mode: 'manual',
+      approval: { decision: 'approved', selectedLabel: 'Approach B' },
+    });
+
+    const result = await execute(agent, { options });
+
+    expect(result.isError).toBe(false);
+    expect(exitPlanMode).toHaveBeenCalledTimes(1);
+    expect(telemetryTrack).toHaveBeenCalledWith('plan_submitted', { has_options: true });
+    expect(telemetryTrack).toHaveBeenCalledWith('plan_resolved', {
+      outcome: 'approved',
+      chosen_option: 'Approach B',
+    });
+  });
+
+  it('tracks revision requests with feedback', async () => {
+    const { agent, telemetryTrack, exitPlanMode } = makeAgent({
+      mode: 'manual',
+      approval: {
+        decision: 'rejected',
+        selectedLabel: 'Revise',
+        feedback: 'Add verification.',
+      },
+    });
+
+    const result = await execute(agent);
+
+    expect(result.isError).toBe(false);
+    expect(exitPlanMode).not.toHaveBeenCalled();
+    expect(telemetryTrack).toHaveBeenCalledWith('plan_resolved', {
+      outcome: 'revise',
+      has_feedback: true,
+    });
+  });
+
+  it('tracks plain rejections without exiting plan mode', async () => {
+    const { agent, telemetryTrack, exitPlanMode } = makeAgent({
+      mode: 'manual',
+      approval: { decision: 'rejected' },
+    });
+
+    const result = await execute(agent);
+
+    expect(result.isError).toBe(true);
+    expect(exitPlanMode).not.toHaveBeenCalled();
+    expect(telemetryTrack).toHaveBeenCalledWith('plan_resolved', {
+      outcome: 'rejected',
+    });
+  });
+
+  it('tracks dismissed approval dialogs without exiting plan mode', async () => {
+    const { agent, telemetryTrack, exitPlanMode } = makeAgent({
+      mode: 'manual',
+      approval: { decision: 'cancelled' },
+    });
+
+    const result = await execute(agent);
+
+    expect(result.isError).toBe(false);
+    expect(result.output).toContain('dismissed');
+    expect(exitPlanMode).not.toHaveBeenCalled();
+    expect(telemetryTrack).toHaveBeenCalledWith('plan_resolved', {
+      outcome: 'dismissed',
+    });
+  });
+
+  it('tracks reject-and-exit and exits plan mode', async () => {
+    const { agent, telemetryTrack, exitPlanMode } = makeAgent({
+      mode: 'manual',
+      approval: { decision: 'rejected', selectedLabel: 'Reject and Exit' },
+    });
+
+    const result = await execute(agent);
+
+    expect(result.isError).toBe(true);
+    expect(result.output).toContain('Plan mode deactivated');
+    expect(exitPlanMode).toHaveBeenCalledTimes(1);
+    expect(telemetryTrack).toHaveBeenCalledWith('plan_resolved', {
+      outcome: 'rejected_and_exited',
+    });
+  });
+});
diff --git a/packages/agent-core/test/tools/policies/sensitive.test.ts b/packages/agent-core/test/tools/policies/sensitive.test.ts
new file mode 100644
index 000000000..e5859ff93
--- /dev/null
+++ b/packages/agent-core/test/tools/policies/sensitive.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+
+import { isSensitiveFile } from '../../../src/tools/policies/sensitive';
+
+describe('isSensitiveFile', () => {
+  it('flags base .env files in any directory', () => {
+    for (const path of ['.env', '/app/.env', 'project/.env']) {
+      expect(isSensitiveFile(path), path).toBe(true);
+    }
+  });
+
+  it('flags .env.<environment> variants', () => {
+    for (const path of ['.env.local', '.env.production', '/app/.env.staging']) {
+      expect(isSensitiveFile(path), path).toBe(true);
+    }
+  });
+
+  it('flags cloud credential file locations', () => {
+    for (const path of [
+      '/home/user/.aws/credentials',
+      '/home/user/.gcp/credentials',
+      '.aws/credentials',
+      '.gcp/credentials',
+      'credentials',
+    ]) {
+      expect(isSensitiveFile(path), path).toBe(true);
+    }
+  });
+
+  it('does not flag normal source / config files or env exemplars', () => {
+    // Mirrors the py parametrization exactly. `.envrc`, `environment.py`,
+    // `.env_example`, `server.key.example`, `id_rsa.pub`, `credentials.json`
+    // (basename is `credentials.json`, not the bare `credentials` token) must
+    // all pass through.
+    for (const path of [
+      'app.py',
+      'config.yml',
+      'README.md',
+      'package.json',
+      'server.key.example',
+      'id_rsa.pub',
+      'credentials.json',
+      '.envrc',
+      'environment.py',
+      '.env_example',
+      '.env.example',
+      '.env.sample',
+      '.env.template',
+      '/app/.env.example',
+    ]) {
+      expect(isSensitiveFile(path), path).toBe(false);
+    }
+  });
+});
diff --git a/packages/agent-core/test/tools/providers/local-fetch-url.test.ts b/packages/agent-core/test/tools/providers/local-fetch-url.test.ts
new file mode 100644
index 000000000..2c0ce931f
--- /dev/null
+++ b/packages/agent-core/test/tools/providers/local-fetch-url.test.ts
@@ -0,0 +1,58 @@
+/**
+ * Covers: LocalFetchURLProvider content-kind reporting.
+ *
+ * Verifies the provider tells callers whether the returned content is a
+ * verbatim passthrough of the response body or the main text extracted
+ * from an HTML page.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { LocalFetchURLProvider } from '../../../src/tools/providers/local-fetch-url';
+
+function htmlResponse(body: string, contentType: string): Response {
+  return new Response(body, {
+    status: 200,
+    headers: { 'content-type': contentType },
+  });
+}
+
+describe('LocalFetchURLProvider content kind', () => {
+  it('reports text/plain bodies as a verbatim passthrough', async () => {
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(htmlResponse('plain body', 'text/plain; charset=utf-8'));
+    const provider = new LocalFetchURLProvider({ fetchImpl });
+
+    const result = await provider.fetch('https://example.com/file.txt');
+
+    expect(result).toEqual({ content: 'plain body', kind: 'passthrough' });
+  });
+
+  it('reports text/markdown bodies as a verbatim passthrough', async () => {
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(htmlResponse('# Title\n\nbody', 'text/markdown'));
+    const provider = new LocalFetchURLProvider({ fetchImpl });
+
+    const result = await provider.fetch('https://example.com/readme.md');
+
+    expect(result).toEqual({ content: '# Title\n\nbody', kind: 'passthrough' });
+  });
+
+  it('reports HTML bodies as extracted main content', async () => {
+    const html =
+      '<html><head><title>Doc</title></head><body><article>' +
+      '<p>The quick brown fox jumps over the lazy dog. '.repeat(20) +
+      '</p></article></body></html>';
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(htmlResponse(html, 'text/html; charset=utf-8'));
+    const provider = new LocalFetchURLProvider({ fetchImpl });
+
+    const result = await provider.fetch('https://example.com/page');
+
+    expect(result.kind).toBe('extracted');
+    expect(result.content).toContain('quick brown fox');
+  });
+});
diff --git a/packages/agent-core/test/tools/providers/moonshot-fetch-url.test.ts b/packages/agent-core/test/tools/providers/moonshot-fetch-url.test.ts
new file mode 100644
index 000000000..59c5f224e
--- /dev/null
+++ b/packages/agent-core/test/tools/providers/moonshot-fetch-url.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { UrlFetcher } from '../../../src/tools/builtin/web/fetch-url';
+import { MoonshotFetchURLProvider } from '../../../src/tools/providers/moonshot-fetch-url';
+
+function fakeFetcher(
+  content = '',
+  kind: 'passthrough' | 'extracted' = 'extracted',
+): UrlFetcher {
+  return { fetch: vi.fn().mockResolvedValue({ content, kind }) };
+}
+
+describe('MoonshotFetchURLProvider auth fallback', () => {
+  it('falls back to the configured API key when the token provider has no token', async () => {
+    // Mirrors py test_resolve_api_key_falls_back_to_api_key_when_no_token:
+    // the host should call moonshot with the static api key when oauth
+    // returns nothing — without needing a separate prime step.
+    const getAccessToken = vi.fn<() => Promise<string>>().mockResolvedValue('');
+    const fetchImpl = vi.fn<typeof fetch>().mockResolvedValue(new Response('ok', { status: 200 }));
+    const provider = new MoonshotFetchURLProvider({
+      tokenProvider: { getAccessToken },
+      apiKey: 'fallback-key',
+      baseUrl: 'https://fetch.example/v1',
+      localFallback: fakeFetcher('fallback content'),
+      fetchImpl,
+    });
+
+    await provider.fetch('https://example.com/page');
+
+    expect(getAccessToken).toHaveBeenCalledTimes(1);
+    const init = fetchImpl.mock.calls[0]?.[1];
+    const authHeader = (init?.headers as Record<string, string> | undefined)?.['Authorization'];
+    expect(authHeader).toBe('Bearer fallback-key');
+  });
+
+  it('drops the rejected oauth token and uses the static api key on the next call', async () => {
+    // Mirrors py test_resolve_api_key_falls_back_after_rejected_refresh_token:
+    // once the refresh path has been rejected with 401, subsequent fetches
+    // must prefer the static api key instead of the persisted oauth token.
+    const getAccessToken = vi
+      .fn<(o?: { force?: boolean }) => Promise<string>>()
+      .mockRejectedValue(new Error('revoked'));
+    const fetchImpl = vi.fn<typeof fetch>().mockResolvedValue(new Response('ok', { status: 200 }));
+    const provider = new MoonshotFetchURLProvider({
+      tokenProvider: { getAccessToken },
+      apiKey: 'fallback-key',
+      baseUrl: 'https://fetch.example/v1',
+      localFallback: fakeFetcher('fallback content'),
+      fetchImpl,
+    });
+
+    await provider.fetch('https://example.com/page');
+
+    const init = fetchImpl.mock.calls[0]?.[1];
+    const authHeader = (init?.headers as Record<string, string> | undefined)?.['Authorization'];
+    expect(authHeader).toBe('Bearer fallback-key');
+  });
+});
+
+describe('MoonshotFetchURLProvider content kind', () => {
+  it('reports service responses as extracted content', async () => {
+    const getAccessToken = vi.fn<() => Promise<string>>().mockResolvedValue('token');
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(new Response('# Extracted markdown', { status: 200 }));
+    const provider = new MoonshotFetchURLProvider({
+      tokenProvider: { getAccessToken },
+      baseUrl: 'https://fetch.example/v1',
+      localFallback: fakeFetcher('fallback content'),
+      fetchImpl,
+    });
+
+    const result = await provider.fetch('https://example.com/page');
+
+    expect(result).toEqual({ content: '# Extracted markdown', kind: 'extracted' });
+  });
+
+  it('forwards the content kind from the local fallback', async () => {
+    const getAccessToken = vi.fn<() => Promise<string>>().mockResolvedValue('token');
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(new Response('boom', { status: 503 }));
+    const provider = new MoonshotFetchURLProvider({
+      tokenProvider: { getAccessToken },
+      baseUrl: 'https://fetch.example/v1',
+      localFallback: fakeFetcher('verbatim body', 'passthrough'),
+      fetchImpl,
+    });
+
+    const result = await provider.fetch('https://example.com/page');
+
+    expect(result).toEqual({ content: 'verbatim body', kind: 'passthrough' });
+  });
+});
diff --git a/packages/agent-core/test/tools/read-file.test.ts b/packages/agent-core/test/tools/read-file.test.ts
new file mode 100644
index 000000000..35337bb70
--- /dev/null
+++ b/packages/agent-core/test/tools/read-file.test.ts
@@ -0,0 +1,71 @@
+import type { Kaos } from '@moonshot-ai/kaos';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ReadTool } from '../../src/tools/builtin/file/read';
+import { createFakeKaos, PERMISSIVE_WORKSPACE } from './fixtures/fake-kaos';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+const REGULAR_FILE_STAT = {
+  stMode: 0o100_644,
+  stIno: 1,
+  stDev: 1,
+  stNlink: 1,
+  stUid: 1000,
+  stGid: 1000,
+  stSize: 0,
+  stAtime: 0,
+  stMtime: 0,
+  stCtime: 0,
+} satisfies Awaited<ReturnType<Kaos['stat']>>;
+
+function linesFromContent(content: string): string[] {
+  if (content === '') return [];
+  const rawLines = content.split('\n');
+  return rawLines.flatMap((line, index) => {
+    if (index < rawLines.length - 1) return [`${line}\n`];
+    return line === '' ? [] : [line];
+  });
+}
+
+function readLinesFromContent(content: string): Kaos['readLines'] {
+  return async function* readLines(): AsyncGenerator<string> {
+    for (const line of linesFromContent(content)) {
+      yield line;
+    }
+  };
+}
+
+function toolWithContent(content: string): ReadTool {
+  const bytes = Buffer.from(content, 'utf8');
+  return new ReadTool(
+    createFakeKaos({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue(REGULAR_FILE_STAT),
+      readBytes: vi.fn<Kaos['readBytes']>().mockImplementation(async (_path, n) => {
+        return n === undefined ? bytes : bytes.subarray(0, n);
+      }),
+      readLines: vi.fn<Kaos['readLines']>().mockImplementation(readLinesFromContent(content)),
+    }),
+    PERMISSIVE_WORKSPACE,
+  );
+}
+
+describe('ReadTool — total-lines message channel', () => {
+  it('reports the file total in the status message even with a positive line_offset window', async () => {
+    // Five-line file, request just line 3 with n_lines=1. The status
+    // line must still surface the file's full length so the model can plan
+    // a follow-up read of the rest of the file.
+    const tool = toolWithContent('a\nb\nc\nd\ne');
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c1',
+      args: { path: '/tmp/sample.txt', line_offset: 3, n_lines: 1 },
+      signal,
+    });
+
+    expect(result.isError).toBeFalsy();
+    expect(result.output).toContain('3\tc');
+    expect(result.output).toContain('Total lines in file: 5.');
+  });
+});
diff --git a/packages/agent-core/test/tools/read-media-desc.test.ts b/packages/agent-core/test/tools/read-media-desc.test.ts
new file mode 100644
index 000000000..84cc17f2a
--- /dev/null
+++ b/packages/agent-core/test/tools/read-media-desc.test.ts
@@ -0,0 +1,46 @@
+import type { ModelCapability } from '@moonshot-ai/kosong';
+import { describe, expect, it } from 'vitest';
+
+import { ReadMediaFileTool } from '../../src/tools/builtin/file/read-media';
+import { createFakeKaos, PERMISSIVE_WORKSPACE } from './fixtures/fake-kaos';
+
+function capability(input: Partial<ModelCapability>): ModelCapability {
+  return input as ModelCapability;
+}
+
+function makeTool(capabilities: Partial<ModelCapability>): ReadMediaFileTool {
+  return new ReadMediaFileTool(createFakeKaos(), PERMISSIVE_WORKSPACE, capability(capabilities));
+}
+
+describe('ReadMediaFileTool description by capabilities', () => {
+  it('mentions image and video when both capabilities are present', () => {
+    const tool = makeTool({ image_in: true, video_in: true });
+    expect(tool.description).toContain('supports image and video');
+  });
+
+  it('mentions image but flags video unsupported when only image_in is present', () => {
+    const tool = makeTool({ image_in: true, video_in: false });
+    expect(tool.description).toContain('supports image files for the current model');
+    expect(tool.description).toContain('Video files are not supported');
+  });
+
+  it('mentions video but flags image unsupported when only video_in is present', () => {
+    const tool = makeTool({ image_in: false, video_in: true });
+    expect(tool.description).toContain('supports video files for the current model');
+    expect(tool.description).toContain('Image files are not supported');
+  });
+
+  it('throws when no image/video capability is present', () => {
+    expect(() => makeTool({ image_in: false, video_in: false })).toThrow(/image_in or video_in/);
+  });
+
+  it('description pins the stable contract phrases: image+video, 100MB, parallel reads, Read pointer', () => {
+    const tool = makeTool({ image_in: true, video_in: true });
+    expect(tool.description).toContain('image and video');
+    expect(tool.description).toContain('100MB');
+    expect(tool.description).toContain('parallel');
+    // TS renamed the sibling tool to `Read` (py was `ReadFile`); the
+    // description must still point readers at the text-file tool.
+    expect(tool.description).toContain('Read tool');
+  });
+});
diff --git a/packages/agent-core/test/tools/read-media.test.ts b/packages/agent-core/test/tools/read-media.test.ts
new file mode 100644
index 000000000..59913a1e4
--- /dev/null
+++ b/packages/agent-core/test/tools/read-media.test.ts
@@ -0,0 +1,564 @@
+/**
+ * ReadMediaFileTool tests for the current output/capability contract.
+ */
+
+import type { Kaos } from '@moonshot-ai/kaos';
+import type { ContentPart, ModelCapability } from '@moonshot-ai/kosong';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ToolAccesses } from '../../src/loop';
+import type { ExecutableToolResult } from '../../src/loop';
+import {
+  ReadMediaFileInputSchema,
+  ReadMediaFileTool,
+} from '../../src/tools/builtin/file/read-media';
+import { MEDIA_SNIFF_BYTES } from '../../src/tools/support/file-type';
+import { createFakeKaos, PERMISSIVE_WORKSPACE } from './fixtures/fake-kaos';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+const DEFAULT_STAT = {
+  stMode: 0o100644,
+  stIno: 0,
+  stDev: 0,
+  stNlink: 1,
+  stUid: 0,
+  stGid: 0,
+  stSize: 1024,
+  stAtime: 0,
+  stMtime: 0,
+  stCtime: 0,
+};
+
+const PNG_HEADER = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const MP4_HEADER = Buffer.concat([
+  Buffer.from([0x00, 0x00, 0x00, 0x18]),
+  Buffer.from('ftyp'),
+  Buffer.from('mp42'),
+  Buffer.from([0x00, 0x00, 0x00, 0x00]),
+  Buffer.from('mp42isom'),
+]);
+
+function capabilities(overrides: Partial<ModelCapability> = {}): ModelCapability {
+  return {
+    image_in: true,
+    video_in: true,
+    audio_in: false,
+    thinking: false,
+    tool_use: true,
+    max_context_tokens: 0,
+    ...overrides,
+  };
+}
+
+function makeReadMediaTool(
+  input: {
+    readonly stat?: Kaos['stat'] | undefined;
+    readonly readBytes?: Kaos['readBytes'] | undefined;
+    readonly modelCapabilities?: ModelCapability | undefined;
+  } = {},
+): ReadMediaFileTool {
+  const kaos = createFakeKaos({
+    stat: input.stat ?? vi.fn<Kaos['stat']>().mockResolvedValue(DEFAULT_STAT),
+    readBytes: input.readBytes ?? vi.fn<Kaos['readBytes']>().mockResolvedValue(PNG_HEADER),
+  });
+  return new ReadMediaFileTool(
+    kaos,
+    PERMISSIVE_WORKSPACE,
+    input.modelCapabilities ?? capabilities(),
+  );
+}
+
+function outputParts(result: ExecutableToolResult): ContentPart[] {
+  expect(result.isError).toBeFalsy();
+  expect(Array.isArray(result.output)).toBe(true);
+  return result.output as ContentPart[];
+}
+
+describe('ReadMediaFileTool', () => {
+  it('has name, parameters, and path-scoped resource accesses', () => {
+    const tool = makeReadMediaTool();
+
+    expect(tool.name).toBe('ReadMediaFile');
+    expect(ReadMediaFileInputSchema.safeParse({ path: '/workspace/sample.png' }).success).toBe(
+      true,
+    );
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: {
+        path: { type: 'string' },
+      },
+    });
+    const execution = tool.resolveExecution({ path: '/workspace/sample.png' });
+    expect(execution.isError).toBeFalsy();
+    if (execution.isError === true) throw new Error('expected runnable execution');
+    expect(execution.accesses).toEqual(ToolAccesses.readFile('/workspace/sample.png'));
+  });
+
+  it('describes the path parameter with accurate working-directory semantics', () => {
+    const tool = makeReadMediaTool();
+    const pathSchema = (tool.parameters as { properties: { path: { description?: string } } })
+      .properties.path;
+
+    expect(pathSchema.description).toBeDefined();
+    const description = pathSchema.description ?? '';
+    // The description must explain that relative paths resolve against the
+    // working directory — not the misleading "Absolute path" wording.
+    expect(description).toMatch(/working directory/i);
+    expect(description).not.toMatch(/^Absolute path/);
+    // The useful "directories and text files are not supported" note stays.
+    expect(description).toMatch(/text file/i);
+  });
+
+  it('throws when constructed without image or video capability', () => {
+    expect(
+      () =>
+        new ReadMediaFileTool(
+          createFakeKaos(),
+          PERMISSIVE_WORKSPACE,
+          capabilities({ image_in: false, video_in: false }),
+        ),
+    ).toThrow(/image_in or video_in/);
+  });
+
+  it('returns a system/text/image/text wrap for PNG files', async () => {
+    const data = Buffer.concat([PNG_HEADER, Buffer.from('pngdata')]);
+    const tool = makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({ ...DEFAULT_STAT, stSize: data.length }),
+      readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(data),
+    });
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c1',
+      args: { path: '/workspace/sample.png' },
+      signal,
+    });
+
+    const parts = outputParts(result);
+    expect(parts).toHaveLength(4);
+    expect(parts[0]).toMatchObject({ type: 'text' });
+    expect((parts[0] as { text: string }).text).toMatch(/^<system>.*<\/system>$/s);
+    expect(parts[1]).toEqual({ type: 'text', text: '<image path="/workspace/sample.png">' });
+    expect(parts[2]).toMatchObject({ type: 'image_url' });
+    expect((parts[2] as { imageUrl: { url: string } }).imageUrl.url).toBe(
+      `data:image/png;base64,${data.toString('base64')}`,
+    );
+    expect(parts[3]).toEqual({ type: 'text', text: '</image>' });
+  });
+
+  it('emits a <system> summary with mime type and byte size for images', async () => {
+    const data = Buffer.concat([PNG_HEADER, Buffer.from('pngdata')]);
+    const tool = makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({ ...DEFAULT_STAT, stSize: data.length }),
+      readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(data),
+    });
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c_sys',
+      args: { path: '/workspace/sample.png' },
+      signal,
+    });
+
+    const parts = outputParts(result);
+    const systemText = (parts[0] as { text: string }).text;
+    expect(systemText).toContain('image/png');
+    expect(systemText).toContain(`${String(data.length)} bytes`);
+    // The re-read reminder is included regardless of dimensions.
+    expect(systemText).toMatch(/read the result back/i);
+  });
+
+  it('includes original pixel dimensions in the <system> summary for images', async () => {
+    // 4x2 PNG: IHDR width=4, height=2.
+    const ihdr = Buffer.alloc(25);
+    Buffer.from('IHDR').copy(ihdr, 4);
+    ihdr.writeUInt32BE(4, 8);
+    ihdr.writeUInt32BE(2, 12);
+    const data = Buffer.concat([PNG_HEADER, ihdr]);
+    const tool = makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({ ...DEFAULT_STAT, stSize: data.length }),
+      readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(data),
+    });
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c_dim',
+      args: { path: '/workspace/sized.png' },
+      signal,
+    });
+
+    const parts = outputParts(result);
+    const systemText = (parts[0] as { text: string }).text;
+    expect(systemText).toContain('4x2');
+    // With the original size known, the coordinate guidance is included.
+    expect(systemText).toMatch(/relative coordinates first/i);
+    expect(systemText).toContain('original image size');
+  });
+
+  it('omits the dimensions line when the header is too short to size the image', async () => {
+    // An 8-byte PNG: enough magic bytes to be recognised as an image,
+    // but too short for the IHDR chunk, so sniffImageDimensions returns
+    // null and the <system> block must drop the "Original dimensions" line.
+    const data = Buffer.from(PNG_HEADER);
+    const tool = makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({ ...DEFAULT_STAT, stSize: data.length }),
+      readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(data),
+    });
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c_nodim',
+      args: { path: '/workspace/tiny.png' },
+      signal,
+    });
+
+    const parts = outputParts(result);
+    const systemText = (parts[0] as { text: string }).text;
+    // mime type and byte size are still reported …
+    expect(systemText).toContain('image/png');
+    expect(systemText).toContain(`${String(data.length)} bytes`);
+    // … but the dimensions line is absent …
+    expect(systemText).not.toContain('Original dimensions');
+    // … and so is the coordinate guidance, which would otherwise dangle by
+    // referencing an original size that is not present in the block.
+    expect(systemText).not.toMatch(/coordinates/i);
+  });
+
+  it('emits a <system> summary for videos without pixel dimensions', async () => {
+    const tool = makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({
+        ...DEFAULT_STAT,
+        stSize: MP4_HEADER.length,
+      }),
+      readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(MP4_HEADER),
+    });
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c_vsys',
+      args: { path: '/workspace/clip.mp4' },
+      signal,
+    });
+
+    const parts = outputParts(result);
+    const systemText = (parts[0] as { text: string }).text;
+    expect(systemText).toContain('video/mp4');
+    expect(systemText).toContain(`${String(MP4_HEADER.length)} bytes`);
+    // The re-read reminder is included for videos too.
+    expect(systemText).toMatch(/read the result back/i);
+  });
+
+  it('detects an extensionless PNG via magic-byte sniffing', async () => {
+    const data = Buffer.concat([PNG_HEADER, Buffer.from('pngdata')]);
+    const tool = makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({ ...DEFAULT_STAT, stSize: data.length }),
+      readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(data),
+    });
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c2',
+      args: { path: '/workspace/sample' },
+      signal,
+    });
+
+    const parts = outputParts(result);
+    expect(parts[1]).toEqual({ type: 'text', text: '<image path="/workspace/sample">' });
+    expect((parts[2] as { imageUrl: { url: string } }).imageUrl.url).toContain('image/png');
+  });
+
+  it('expands leading tilde paths using the kaos home directory', async () => {
+    const data = Buffer.concat([PNG_HEADER, Buffer.from('pngdata')]);
+    const readBytes = vi.fn<Kaos['readBytes']>().mockResolvedValue(data);
+    const tool = makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({ ...DEFAULT_STAT, stSize: data.length }),
+      readBytes,
+    });
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c_home',
+      args: { path: '~/images/sample.png' },
+      signal,
+    });
+
+    const parts = outputParts(result);
+    expect(readBytes).toHaveBeenCalledWith('/home/test/images/sample.png', MEDIA_SNIFF_BYTES);
+    expect(readBytes).toHaveBeenCalledWith('/home/test/images/sample.png');
+    expect(parts[1]).toEqual({ type: 'text', text: '<image path="/home/test/images/sample.png">' });
+  });
+
+  it('returns a text/video/text wrap for MP4 files', async () => {
+    const tool = makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({
+        ...DEFAULT_STAT,
+        stSize: MP4_HEADER.length,
+      }),
+      readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(MP4_HEADER),
+    });
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c3',
+      args: { path: '/workspace/sample.mp4' },
+      signal,
+    });
+
+    const parts = outputParts(result);
+    expect(parts).toHaveLength(4);
+    expect(parts[0]).toMatchObject({ type: 'text' });
+    expect((parts[0] as { text: string }).text).toMatch(/^<system>.*<\/system>$/s);
+    expect(parts[1]).toEqual({ type: 'text', text: '<video path="/workspace/sample.mp4">' });
+    expect(parts[2]).toMatchObject({ type: 'video_url' });
+    expect((parts[2] as { videoUrl: { url: string } }).videoUrl.url).toBe(
+      `data:video/mp4;base64,${MP4_HEADER.toString('base64')}`,
+    );
+    expect(parts[3]).toEqual({ type: 'text', text: '</video>' });
+  });
+
+  it('uses injected videoUploader for video files when available', async () => {
+    const videoUploader = vi.fn().mockResolvedValue({
+      type: 'video_url',
+      videoUrl: { url: 'ms://file-123', id: 'file-123' },
+    });
+    const tool = new ReadMediaFileTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue({
+          ...DEFAULT_STAT,
+          stSize: MP4_HEADER.length,
+        }),
+        readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(MP4_HEADER),
+      }),
+      PERMISSIVE_WORKSPACE,
+      capabilities(),
+      videoUploader,
+    );
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c4',
+      args: { path: '/workspace/sample.mp4' },
+      signal,
+    });
+
+    expect(videoUploader).toHaveBeenCalledWith({
+      data: MP4_HEADER,
+      mimeType: 'video/mp4',
+      filename: 'sample.mp4',
+    });
+    const parts = outputParts(result);
+    expect(parts[2]).toEqual({
+      type: 'video_url',
+      videoUrl: { url: 'ms://file-123', id: 'file-123' },
+    });
+  });
+
+  it('rejects text files with a Read hint', async () => {
+    const text = Buffer.from('hello');
+    const tool = makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({ ...DEFAULT_STAT, stSize: text.length }),
+      readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(text),
+    });
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c5',
+      args: { path: '/workspace/sample.txt' },
+      signal,
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.output).toBe(
+      '"/workspace/sample.txt" is a text file. Use Read to read text files.',
+    );
+    expect(result.output).not.toContain('ReadFile');
+  });
+
+  it('rejects unknown binary files without legacy Python-tool wording', async () => {
+    const blob = Buffer.from([0x00, 0x01, 0x02, 0x03]);
+    const tool = makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({ ...DEFAULT_STAT, stSize: blob.length }),
+      readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(blob),
+    });
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c_unknown',
+      args: { path: '/workspace/blob.bin' },
+      signal,
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.output).toBe(
+      '"/workspace/blob.bin" is not a supported image or video file. Use Read for text files, or Bash or an MCP tool for other binary formats.',
+    );
+    expect(result.output).not.toContain('Python tools');
+  });
+
+  it('errors when the current model lacks video input capability', async () => {
+    const tool = makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({
+        ...DEFAULT_STAT,
+        stSize: MP4_HEADER.length,
+      }),
+      readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(MP4_HEADER),
+      modelCapabilities: capabilities({ image_in: true, video_in: false }),
+    });
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c6',
+      args: { path: '/workspace/sample.mp4' },
+      signal,
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.output).toMatch(/video input/i);
+  });
+
+  it('rejects empty files and files exceeding the media size limit', async () => {
+    const empty = await executeTool(makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({ ...DEFAULT_STAT, stSize: 0 }),
+    }), {
+      turnId: 't1',
+      toolCallId: 'c_empty',
+      args: { path: '/workspace/empty.png' },
+      signal,
+    });
+    expect(empty).toMatchObject({ isError: true });
+    expect(empty.output).toMatch(/empty/i);
+
+    const huge = await executeTool(makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({
+        ...DEFAULT_STAT,
+        stSize: 200 * 1024 * 1024,
+      }),
+    }), {
+      turnId: 't1',
+      toolCallId: 'c_huge',
+      args: { path: '/workspace/huge.png' },
+      signal,
+    });
+    expect(huge).toMatchObject({ isError: true });
+    expect(huge.output).toMatch(/exceeds|100/i);
+  });
+
+  it('exposes a <system> summary with the original pixel size for sized images', async () => {
+    // A real 3x4 RGB PNG (validated by sharp/pillow). Reading should surface
+    // the original dimensions in the <system> summary so the model can map
+    // coordinates. The bytes below are a hand-built minimum-valid 3x4 PNG.
+    // py contract asked for a `message` sidecar with "Loaded image file ...
+    // original size 3x4px"; TS settled on a leading <system> ContentPart with
+    // `Read image file. ... Original dimensions: 3x4 pixels.` — same intent,
+    // different wording and channel.
+    const png = Buffer.from(
+      '89504e470d0a1a0a0000000d49484452000000030000000408020000003a' +
+        '63dc1c0000001949444154789c63606060f8cf80019aa0a8a020' +
+        '00000000ffff03000c1d03014b0000000049454e44ae426082',
+      'hex',
+    );
+    const tool = makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({ ...DEFAULT_STAT, stSize: png.length }),
+      readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(png),
+    });
+
+    const result = await executeTool(tool,{
+      turnId: 't1',
+      toolCallId: 'c_size',
+      args: { path: '/workspace/valid.png' },
+      signal,
+    });
+
+    const parts = outputParts(result);
+    const systemText = (parts[0] as { text: string }).text;
+    expect(systemText).toContain('Read image file');
+    expect(systemText).toContain('image/png');
+    expect(systemText).toContain('3x4 pixels');
+  });
+
+  it('reports a <system> summary for extensionless image files', async () => {
+    // Extensionless path → magic-byte sniff identifies PNG. <system> summary
+    // still announces the kind, mime type, and byte size; dimensions are
+    // omitted because the header is too short to read IHDR.
+    const data = Buffer.concat([PNG_HEADER, Buffer.from('pngdata')]);
+    const tool = makeReadMediaTool({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue({ ...DEFAULT_STAT, stSize: data.length }),
+      readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(data),
+    });
+
+    const result = await executeTool(tool,{
+      turnId: 't1',
+      toolCallId: 'c_extless_msg',
+      args: { path: '/workspace/sample' },
+      signal,
+    });
+
+    const parts = outputParts(result);
+    const systemText = (parts[0] as { text: string }).text;
+    expect(systemText).toContain('Read image file');
+    expect(systemText).toContain('image/png');
+    expect(systemText).toContain(`${String(data.length)} bytes`);
+  });
+
+  it('description by capabilities lockdown — image + video points at Read for text fallback', () => {
+    const tool = new ReadMediaFileTool(createFakeKaos(), PERMISSIVE_WORKSPACE, capabilities());
+    // Long-form description contract from sibling docs: 100MB ceiling and
+    // pointer to the text-file tool for non-media content. TS renames the
+    // sibling tool to `Read` (py was `ReadFile`).
+    expect(tool.description).toContain('100MB');
+    expect(tool.description).toContain('Read tool');
+    expect(tool.description).toContain('supports image and video files for the current model');
+  });
+
+  it('omits the tool from the toolset when the model has neither image_in nor video_in', () => {
+    // Strict skip semantics: construction returns a sentinel the loader can
+    // use to drop the tool entirely, instead of registering a tool that
+    // always errors. Currently TS throws a regular Error — fail-unimplemented
+    // surfaces the gap.
+    let caught: unknown = null;
+    const construct = (): ReadMediaFileTool =>
+      new ReadMediaFileTool(
+        createFakeKaos(),
+        PERMISSIVE_WORKSPACE,
+        capabilities({ image_in: false, video_in: false }),
+      );
+    try {
+      construct();
+    } catch (error) {
+      caught = error;
+    }
+    expect((caught as { name?: string } | null)?.name).toBe('SkipThisTool');
+  });
+
+  it('allows absolute media paths outside workspace but rejects relative escapes', async () => {
+    const readBytes = vi.fn<Kaos['readBytes']>().mockResolvedValue(PNG_HEADER);
+    const tool = new ReadMediaFileTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue(DEFAULT_STAT),
+        readBytes,
+      }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+      capabilities(),
+    );
+
+    const absolute = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c_abs',
+      args: { path: '/tmp/outside.png' },
+      signal,
+    });
+    expect(absolute.isError).toBeFalsy();
+
+    readBytes.mockClear();
+    const relative = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c_rel',
+      args: { path: '../secret.png' },
+      signal,
+    });
+    expect(relative.isError).toBe(true);
+    expect(readBytes).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/agent-core/test/tools/read.test.ts b/packages/agent-core/test/tools/read.test.ts
new file mode 100644
index 000000000..a60b08183
--- /dev/null
+++ b/packages/agent-core/test/tools/read.test.ts
@@ -0,0 +1,826 @@
+import type { Kaos } from '@moonshot-ai/kaos';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  MAX_BYTES,
+  MAX_LINE_LENGTH,
+  MAX_LINES,
+  type ReadInput,
+  ReadInputSchema,
+  ReadTool,
+} from '../../src/tools/builtin/file/read';
+import { MEDIA_SNIFF_BYTES } from '../../src/tools/support/file-type';
+import type { WorkspaceConfig } from '../../src/tools/support/workspace';
+import { createFakeKaos, PERMISSIVE_WORKSPACE, toolContentString } from './fixtures/fake-kaos';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+const REGULAR_FILE_STAT = {
+  stMode: 0o100_644,
+  stIno: 1,
+  stDev: 1,
+  stNlink: 1,
+  stUid: 1000,
+  stGid: 1000,
+  stSize: 0,
+  stAtime: 0,
+  stMtime: 0,
+  stCtime: 0,
+} satisfies Awaited<ReturnType<Kaos['stat']>>;
+
+const DIRECTORY_STAT = {
+  ...REGULAR_FILE_STAT,
+  stMode: 0o040_755,
+} satisfies Awaited<ReturnType<Kaos['stat']>>;
+
+function context(args: ReadInput) {
+  return {
+    turnId: '0',
+    toolCallId: 'call_read',
+    args,
+    signal,
+  };
+}
+
+function linesFromContent(content: string): string[] {
+  if (content === '') return [];
+  const rawLines = content.split('\n');
+  return rawLines.flatMap((line, index) => {
+    if (index < rawLines.length - 1) return [`${line}\n`];
+    return line === '' ? [] : [line];
+  });
+}
+
+function readLinesFromContent(content: string): Kaos['readLines'] {
+  return async function* readLines(): AsyncGenerator<string> {
+    for (const line of linesFromContent(content)) {
+      yield line;
+    }
+  };
+}
+
+function withReadStatus(output: string, status: string): string {
+  const note = `<system>${status}</system>`;
+  return output.length > 0 ? `${output}\n${note}` : note;
+}
+
+function toolWithContent(content: string, workspace: WorkspaceConfig = PERMISSIVE_WORKSPACE) {
+  const bytes = Buffer.from(content, 'utf8');
+  return new ReadTool(
+    createFakeKaos({
+      stat: vi.fn<Kaos['stat']>().mockResolvedValue(REGULAR_FILE_STAT),
+      readBytes: vi.fn<Kaos['readBytes']>().mockImplementation(async (_path, n) => {
+        return n === undefined ? bytes : bytes.subarray(0, n);
+      }),
+      readLines: vi.fn<Kaos['readLines']>().mockImplementation(readLinesFromContent(content)),
+      readText: vi.fn<Kaos['readText']>().mockResolvedValue(content),
+    }),
+    workspace,
+  );
+}
+
+describe('ReadTool', () => {
+  it('exposes current metadata and schema', () => {
+    const tool = toolWithContent('');
+
+    expect(tool.name).toBe('Read');
+    expect(tool.description).toContain('concrete file path');
+    expect(tool.description).toContain('Pure CRLF files are displayed with LF');
+    expect(tool.description).not.toContain('skip the verification re-read');
+    expect(tool.description).toContain('final external contract');
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: expect.stringContaining('working directory'),
+        },
+        line_offset: {
+          description: expect.stringContaining('line number to start reading from'),
+        },
+        n_lines: {
+          description: expect.stringContaining('number of lines to read'),
+        },
+      },
+    });
+    expect(ReadInputSchema.safeParse({ path: '/tmp/test.txt' }).success).toBe(true);
+    expect(
+      ReadInputSchema.safeParse({ path: '/tmp/test.txt', line_offset: 1, n_lines: 2 }).success,
+    ).toBe(true);
+    expect(ReadInputSchema.safeParse({ path: '/tmp/test.txt', line_offset: 0 }).success).toBe(
+      false,
+    );
+    expect(
+      ReadInputSchema.safeParse({ path: '/tmp/test.txt', line_offset: -(MAX_LINES + 1) }).success,
+    ).toBe(false);
+  });
+
+  it('reads text content with stable one-based line numbers', async () => {
+    const tool = toolWithContent('alpha\nbeta\n');
+
+    const result = await executeTool(tool, context({ path: '/tmp/a.txt' }));
+
+    expect(result).toEqual({
+      output: withReadStatus(
+        '1\talpha\n2\tbeta',
+        '2 lines read from file starting from line 1. Total lines in file: 2. End of file reached.',
+      ),
+    });
+  });
+
+  it('normalizes pure CRLF files to the LF model view', async () => {
+    const tool = toolWithContent('alpha\r\nbeta\r\n');
+
+    const result = await executeTool(tool, context({ path: '/tmp/a.txt' }));
+
+    expect(result.output).toBe(
+      withReadStatus(
+        ['1\talpha', '2\tbeta'].join('\n'),
+        '2 lines read from file starting from line 1. Total lines in file: 2. End of file reached.',
+      ),
+    );
+  });
+
+  it('makes mixed carriage returns visible instead of normalizing them', async () => {
+    const tool = toolWithContent('alpha\r\nbeta\ngamma\rdone');
+
+    const result = await executeTool(tool, context({ path: '/tmp/a.txt' }));
+
+    expect(result.output).toBe(
+      withReadStatus(
+        ['1\talpha\\r', '2\tbeta', '3\tgamma\\rdone'].join('\n'),
+        '3 lines read from file starting from line 1. Total lines in file: 3. End of file reached. Mixed or lone carriage-return line endings are shown as \\r. Use exact \\r\\n or \\r escapes in Edit.old_string for those lines.',
+      ),
+    );
+  });
+
+  it('respects one-based line_offset and positive n_lines', async () => {
+    const tool = toolWithContent('a\nb\nc\nd\ne');
+
+    const result = await executeTool(tool, context({ path: '/tmp/a.txt', line_offset: 2, n_lines: 2 }));
+
+    expect(result).toEqual({
+      output: withReadStatus(
+        '2\tb\n3\tc',
+        '2 lines read from file starting from line 2. Total lines in file: 5.',
+      ),
+    });
+  });
+
+  it('returns an empty successful output when line_offset is beyond EOF', async () => {
+    const tool = toolWithContent('a\nb');
+
+    const result = await executeTool(tool, context({ path: '/tmp/a.txt', line_offset: 20 }));
+
+    expect(result).toEqual({
+      output: withReadStatus(
+        '',
+        'No lines read from file. Total lines in file: 2. End of file reached.',
+      ),
+    });
+  });
+
+  it('supports negative line_offset as tail mode with absolute line numbers', async () => {
+    const tool = toolWithContent('a\nb\nc\nd\ne');
+
+    const result = await executeTool(tool, context({ path: '/tmp/a.txt', line_offset: -3 }));
+
+    expect(result).toEqual({
+      output: withReadStatus(
+        '3\tc\n4\td\n5\te',
+        '3 lines read from file starting from line 3. Total lines in file: 5. End of file reached.',
+      ),
+    });
+  });
+
+  it('applies n_lines from the start of the negative line_offset tail window', async () => {
+    const tool = toolWithContent('a\nb\nc\nd\ne');
+
+    const result = await executeTool(tool, context({ path: '/tmp/a.txt', line_offset: -5, n_lines: 2 }));
+
+    expect(result.output).toBe(
+      withReadStatus(
+        '1\ta\n2\tb',
+        '2 lines read from file starting from line 1. Total lines in file: 5.',
+      ),
+    );
+  });
+
+  it('rejects relative traversal before reading', async () => {
+    const readText = vi.fn().mockResolvedValue('secret');
+    const tool = new ReadTool(createFakeKaos({ readText }), {
+      workspaceDir: '/workspace/project',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool, context({ path: '../../outside.txt' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('absolute path');
+    expect(readText).not.toHaveBeenCalled();
+  });
+
+  it('allows explicit absolute paths outside the workspace', async () => {
+    const content = 'external';
+    const bytes = Buffer.from(content, 'utf8');
+    const readBytes = vi.fn<Kaos['readBytes']>().mockImplementation(async (_path, n) => {
+      return n === undefined ? bytes : bytes.subarray(0, n);
+    });
+    const readLines = vi.fn<Kaos['readLines']>().mockImplementation(readLinesFromContent(content));
+    const tool = new ReadTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue(REGULAR_FILE_STAT),
+        readBytes,
+        readLines,
+      }),
+      {
+        workspaceDir: '/workspace',
+        additionalDirs: [],
+      },
+    );
+
+    const result = await executeTool(tool, context({ path: '/tmp/external.txt' }));
+
+    expect(result.output).toBe(
+      withReadStatus(
+        '1\texternal',
+        '1 line read from file starting from line 1. Total lines in file: 1. End of file reached.',
+      ),
+    );
+    expect(readBytes).toHaveBeenCalledWith('/tmp/external.txt', MEDIA_SNIFF_BYTES);
+    expect(readLines).toHaveBeenCalledWith('/tmp/external.txt', { errors: 'strict' });
+  });
+
+  it('returns a friendly error for missing files before sniffing bytes', async () => {
+    const statError = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    const readBytes = vi
+      .fn<Kaos['readBytes']>()
+      .mockRejectedValue(new Error('readBytes should not be called for missing files'));
+    const readLines = vi.fn<Kaos['readLines']>().mockImplementation(readLinesFromContent(''));
+    const tool = new ReadTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockRejectedValue(statError),
+        readBytes,
+        readLines,
+      }),
+      {
+        workspaceDir: '/workspace',
+        additionalDirs: [],
+      },
+    );
+
+    const result = await executeTool(tool, context({ path: '/workspace/missing.txt' }));
+
+    expect(result).toEqual({
+      isError: true,
+      output: '"/workspace/missing.txt" does not exist.',
+    });
+    expect(readBytes).not.toHaveBeenCalled();
+    expect(readLines).not.toHaveBeenCalled();
+  });
+
+  it('returns a friendly error for directories before sniffing bytes', async () => {
+    const readBytes = vi
+      .fn<Kaos['readBytes']>()
+      .mockRejectedValue(new Error('readBytes should not be called for directories'));
+    const readLines = vi.fn<Kaos['readLines']>().mockImplementation(readLinesFromContent(''));
+    const tool = new ReadTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue(DIRECTORY_STAT),
+        readBytes,
+        readLines,
+      }),
+      {
+        workspaceDir: '/workspace',
+        additionalDirs: [],
+      },
+    );
+
+    const result = await executeTool(tool, context({ path: '/workspace/src' }));
+
+    expect(result).toEqual({
+      isError: true,
+      output: '"/workspace/src" is not a file.',
+    });
+    expect(readBytes).not.toHaveBeenCalled();
+    expect(readLines).not.toHaveBeenCalled();
+  });
+
+  it('expands leading tilde paths using the kaos home directory', async () => {
+    const content = 'home note';
+    const bytes = Buffer.from(content, 'utf8');
+    const readBytes = vi.fn<Kaos['readBytes']>().mockImplementation(async (_path, n) => {
+      return n === undefined ? bytes : bytes.subarray(0, n);
+    });
+    const readLines = vi.fn<Kaos['readLines']>().mockImplementation(readLinesFromContent(content));
+    const tool = new ReadTool(
+      createFakeKaos({
+        gethome: () => '/home/test',
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue(REGULAR_FILE_STAT),
+        readBytes,
+        readLines,
+      }),
+      {
+        workspaceDir: '/workspace',
+        additionalDirs: [],
+      },
+    );
+
+    const result = await executeTool(tool, context({ path: '~/notes/today.txt' }));
+
+    expect(result.output).toBe(
+      withReadStatus(
+        '1\thome note',
+        '1 line read from file starting from line 1. Total lines in file: 1. End of file reached.',
+      ),
+    );
+    expect(readBytes).toHaveBeenCalledWith('/home/test/notes/today.txt', MEDIA_SNIFF_BYTES);
+    expect(readLines).toHaveBeenCalledWith('/home/test/notes/today.txt', { errors: 'strict' });
+  });
+
+  it('blocks sensitive files independently from workspace access', async () => {
+    const readText = vi.fn().mockResolvedValue('SECRET=value');
+    const tool = new ReadTool(createFakeKaos({ readText }), {
+      workspaceDir: '/workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool, context({ path: '/workspace/.env' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('sensitive-file pattern');
+    expect(readText).not.toHaveBeenCalled();
+  });
+
+  it('rejects image files before text decoding and points to ReadMediaFile', async () => {
+    const pngHeader = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    const readText = vi
+      .fn<Kaos['readText']>()
+      .mockRejectedValue(new Error('readText should not be called for images'));
+    const tool = new ReadTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue(REGULAR_FILE_STAT),
+        readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(pngHeader),
+        readText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool, context({ path: '/tmp/sample.png' }));
+    const output = toolContentString(result);
+
+    expect(result.isError).toBe(true);
+    expect(output).toMatch(/image file/i);
+    expect(output).toMatch(/ReadMediaFile|media/i);
+    expect(readText).not.toHaveBeenCalled();
+  });
+
+  it('rejects extensionless image files using magic-byte sniffing', async () => {
+    const pngHeader = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    const readText = vi
+      .fn<Kaos['readText']>()
+      .mockRejectedValue(new Error('readText should not be called for extensionless images'));
+    const tool = new ReadTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue(REGULAR_FILE_STAT),
+        readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(pngHeader),
+        readText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool, context({ path: '/tmp/sample' }));
+    const output = toolContentString(result);
+
+    expect(result.isError).toBe(true);
+    expect(output).toMatch(/image file/i);
+    expect(readText).not.toHaveBeenCalled();
+  });
+
+  it('rejects video files before text decoding', async () => {
+    const mp4Header = Buffer.concat([
+      Buffer.from([0x00, 0x00, 0x00, 0x18]),
+      Buffer.from('ftyp'),
+      Buffer.from('mp42'),
+      Buffer.from([0x00, 0x00, 0x00, 0x00]),
+      Buffer.from('mp42isom'),
+    ]);
+    const readText = vi
+      .fn<Kaos['readText']>()
+      .mockRejectedValue(new Error('readText should not be called for videos'));
+    const tool = new ReadTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue(REGULAR_FILE_STAT),
+        readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(mp4Header),
+        readText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool, context({ path: '/tmp/sample.mp4' }));
+    const output = toolContentString(result);
+
+    expect(result.isError).toBe(true);
+    expect(output).toMatch(/video file/i);
+    expect(output).toMatch(/ReadMediaFile|media/i);
+    expect(readText).not.toHaveBeenCalled();
+  });
+
+  it('rejects NUL-containing binary files before text decoding', async () => {
+    const header = Buffer.concat([Buffer.from('plain prefix'), Buffer.from([0x00, 0x01])]);
+    const readText = vi
+      .fn<Kaos['readText']>()
+      .mockRejectedValue(new Error('readText should not be called for binary files'));
+    const tool = new ReadTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue(REGULAR_FILE_STAT),
+        readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(header),
+        readText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool, context({ path: '/tmp/blob.bin' }));
+    const output = toolContentString(result);
+
+    expect(result.isError).toBe(true);
+    expect(output).toBe(
+      '"/tmp/blob.bin" is not readable as UTF-8 text. If it is an image or video, use ReadMediaFile. For other binary formats, use Bash or an MCP tool if available.',
+    );
+    expect(output).not.toContain('Python tools');
+    expect(readText).not.toHaveBeenCalled();
+  });
+
+  it('rejects NUL bytes that appear after the preflight header', async () => {
+    const header = Buffer.from('text prefix without nul', 'utf8');
+    const readLines = vi.fn<Kaos['readLines']>().mockImplementation(async function* readLines() {
+      yield 'safe text\n';
+      yield `binary${String.fromCodePoint(0)}tail\n`;
+    });
+    const tool = new ReadTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue(REGULAR_FILE_STAT),
+        readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(header),
+        readLines,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool, context({ path: '/tmp/blob-with-late-nul' }));
+    const output = toolContentString(result);
+
+    expect(result.isError).toBe(true);
+    expect(output).toBe(
+      '"/tmp/blob-with-late-nul" is not readable as UTF-8 text. If it is an image or video, use ReadMediaFile. For other binary formats, use Bash or an MCP tool if available.',
+    );
+    expect(output).not.toContain('Python tools');
+  });
+
+  it('rejects invalid UTF-8 instead of returning replacement characters', async () => {
+    const replacement = String.fromCodePoint(0xfffd);
+    const readLines = vi.fn<Kaos['readLines']>().mockImplementation(async function* readLines(
+      _path,
+      options,
+    ) {
+      if (options?.errors === 'strict') {
+        throw new TypeError('The encoded data was not valid for encoding utf-8');
+      }
+      yield `bad${replacement}text\n`;
+    });
+    const tool = new ReadTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue(REGULAR_FILE_STAT),
+        readBytes: vi.fn<Kaos['readBytes']>().mockResolvedValue(Buffer.from('text header')),
+        readLines,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool, context({ path: '/tmp/not-utf8.txt' }));
+    const output = toolContentString(result);
+
+    expect(result.isError).toBe(true);
+    expect(output).toBe(
+      '"/tmp/not-utf8.txt" is not readable as UTF-8 text. If it is an image or video, use ReadMediaFile. For other binary formats, use Bash or an MCP tool if available.',
+    );
+    expect(output).not.toContain('Python tools');
+    expect(output).not.toContain(replacement);
+    expect(output).not.toContain('encoded data was not valid');
+  });
+
+  it('truncates long lines and surfaces the affected line numbers', async () => {
+    const long = 'x'.repeat(MAX_LINE_LENGTH + 10);
+    const tool = toolWithContent([long, 'short', long].join('\n'));
+
+    const result = await executeTool(tool, context({ path: '/tmp/long.txt' }));
+
+    expect(result.output).toContain('Lines [1, 3] were truncated.');
+    expect(result.output).toContain('...');
+  });
+
+  it('checks the byte cap before adding the next rendered line', async () => {
+    const line = 'x'.repeat(MAX_LINE_LENGTH);
+    const content = Array.from({ length: 80 }, () => line).join('\n');
+    const tool = toolWithContent(content);
+
+    const result = await executeTool(tool, context({ path: '/tmp/bytes.txt' }));
+    const output = toolContentString(result);
+
+    const marker = '\n<system>';
+    const markerIndex = output.indexOf(marker);
+    expect(markerIndex).toBeGreaterThan(0);
+    const body = output.slice(0, markerIndex);
+    expect(Buffer.byteLength(body, 'utf8')).toBeLessThanOrEqual(MAX_BYTES);
+    expect(output).toContain(`Max ${String(MAX_BYTES)} bytes reached.`);
+  });
+
+  it('reads through bounded byte preflight and streams line iteration without full readText', async () => {
+    const content = Array.from({ length: MAX_LINES + 5 }, (_, i) => `line ${String(i + 1)}`).join(
+      '\n',
+    );
+    const bytes = Buffer.from(content, 'utf8');
+    const readText = vi
+      .fn<Kaos['readText']>()
+      .mockRejectedValue(new Error('full readText should not be called'));
+    let consumed = 0;
+    const readLines: Kaos['readLines'] = async function* readLines(): AsyncGenerator<string> {
+      for (let i = 1; i <= MAX_LINES + 5; i += 1) {
+        consumed = i;
+        yield `line ${String(i)}\n`;
+      }
+    };
+    const readBytes = vi.fn<Kaos['readBytes']>().mockImplementation(async (_path, n) => {
+      return n === undefined ? bytes : bytes.subarray(0, n);
+    });
+    const tool = new ReadTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue(REGULAR_FILE_STAT),
+        readBytes,
+        readLines,
+        readText,
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool, context({ path: '/tmp/large.txt' }));
+    const output = toolContentString(result);
+
+    expect(result.isError).toBeFalsy();
+    expect(output).toContain('1\tline 1');
+    expect(output).toContain(`${String(MAX_LINES)}\tline ${String(MAX_LINES)}`);
+    expect(output).toContain(`Total lines in file: ${String(MAX_LINES + 5)}.`);
+    expect(output).toContain(`Max ${String(MAX_LINES)} lines reached.`);
+    expect(consumed).toBe(MAX_LINES + 5);
+    expect(readBytes).toHaveBeenCalledWith('/tmp/large.txt', MEDIA_SNIFF_BYTES);
+    expect(readText).not.toHaveBeenCalled();
+  });
+
+  it('caps default reads at MAX_LINES', async () => {
+    const content = Array.from({ length: MAX_LINES + 1 }, (_, i) => `line ${String(i + 1)}`).join(
+      '\n',
+    );
+    const tool = toolWithContent(content);
+
+    const result = await executeTool(tool, context({ path: '/tmp/big.txt' }));
+
+    expect(result.output).toContain(`Max ${String(MAX_LINES)} lines reached.`);
+    expect(result.output).toContain(`${String(MAX_LINES)}\tline ${String(MAX_LINES)}`);
+    expect(result.output).not.toContain(`${String(MAX_LINES + 1)}\tline ${String(MAX_LINES + 1)}`);
+  });
+
+  it('tail byte truncation keeps the newest lines closest to EOF', async () => {
+    const numLines = Math.floor(MAX_BYTES / 1001) + 20;
+    const content = Array.from({ length: numLines }, (_, i) => {
+      return `${String(i + 1).padStart(4, '0')}${'B'.repeat(996)}`;
+    }).join('\n');
+    const tool = toolWithContent(content);
+
+    const result = await executeTool(tool, context({ path: '/tmp/tail-bytes.txt', line_offset: -1000 }));
+    const output = toolContentString(result);
+    const outputLines = output
+      .split('\n')
+      .filter((line) => line.includes('\t') && !line.startsWith('<system>'));
+
+    expect(output).toContain(`Max ${String(MAX_BYTES)} bytes reached.`);
+    expect(outputLines.at(-1)).toContain(String(numLines).padStart(4, '0'));
+    expect(outputLines[0]).not.toContain('0001');
+  });
+
+  it('tail n_lines is applied before byte truncation', async () => {
+    const numLines = 500;
+    const content = Array.from({ length: numLines }, (_, i) => {
+      return `${String(i + 1).padStart(4, '0')}${'X'.repeat(1996)}`;
+    }).join('\n');
+    const tool = toolWithContent(content);
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/tail-small-window.txt', line_offset: -200, n_lines: 1 }),
+    );
+    const output = toolContentString(result);
+
+    expect(output).toMatch(/^301\t0301/);
+    expect(output).not.toContain('Max');
+  });
+
+  it('description pins line/byte caps, tail mode, and the Grep-over-Read preference', () => {
+    const tool = toolWithContent('');
+    // Numeric caps are part of the stable contract.
+    expect(tool.description).toContain(String(MAX_LINES));
+    expect(tool.description).toContain(String(MAX_LINE_LENGTH));
+    // Tail mode (negative line_offset) is documented.
+    expect(tool.description).toMatch(/negative line_offset|reads from the end/i);
+    // Recommend Grep when searching for unknown content.
+    expect(tool.description).toContain('Grep');
+  });
+
+  it('reads files inside additional_dirs via absolute path', async () => {
+    const content = 'extra-dir note';
+    const bytes = Buffer.from(content, 'utf8');
+    const tool = new ReadTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockResolvedValue(REGULAR_FILE_STAT),
+        readBytes: vi.fn<Kaos['readBytes']>().mockImplementation(async (_path, n) => {
+          return n === undefined ? bytes : bytes.subarray(0, n);
+        }),
+        readLines: vi.fn<Kaos['readLines']>().mockImplementation(readLinesFromContent(content)),
+      }),
+      { workspaceDir: '/workspace', additionalDirs: ['/extra'] },
+    );
+
+    const result = await executeTool(tool,context({ path: '/extra/notes.txt' }));
+
+    expect(result.isError).toBeFalsy();
+    expect(result.output).toContain('1\textra-dir note');
+  });
+
+  it('reports nonexistent files with the expected does-not-exist phrasing', async () => {
+    const statError = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    const tool = new ReadTool(
+      createFakeKaos({
+        stat: vi.fn<Kaos['stat']>().mockRejectedValue(statError),
+      }),
+      { workspaceDir: '/workspace', additionalDirs: [] },
+    );
+
+    const result = await executeTool(tool,context({ path: '/workspace/ghost.txt' }));
+
+    expect(result.isError).toBe(true);
+    expect(result.output).toContain('does not exist');
+    // py also surfaces a separate `brief` channel with "File not found";
+    // TS only has the `output` string, so we check for the equivalent
+    // human phrasing in the message itself.
+    expect(result.output).toMatch(/not found|does not exist/i);
+  });
+
+  it('returns empty output and Total lines: 0 for an empty file', async () => {
+    const tool = toolWithContent('');
+
+    const result = await executeTool(tool,context({ path: '/tmp/empty.txt' }));
+
+    expect(result.isError).toBeFalsy();
+    expect(result.output).toBe(
+      withReadStatus('', 'No lines read from file. Total lines in file: 0. End of file reached.'),
+    );
+  });
+
+  it('reads unicode (CJK + emoji + accented Latin) without loss', async () => {
+    const tool = toolWithContent('Hello 世界 🌍\nUnicode test: café, naïve, résumé');
+
+    const result = await executeTool(tool,context({ path: '/tmp/unicode.txt' }));
+
+    expect(result.isError).toBeFalsy();
+    expect(result.output).toContain('1\tHello 世界 🌍');
+    expect(result.output).toContain('2\tUnicode test: café, naïve, résumé');
+  });
+
+  it('schema validation rejects n_lines=0 and n_lines=-1 with an n_lines-keyed error', () => {
+    const zero = ReadInputSchema.safeParse({ path: '/tmp/a.txt', n_lines: 0 });
+    expect(zero.success).toBe(false);
+    if (!zero.success) {
+      const message = JSON.stringify(zero.error.issues);
+      expect(message).toContain('n_lines');
+    }
+
+    const negative = ReadInputSchema.safeParse({ path: '/tmp/a.txt', n_lines: -1 });
+    expect(negative.success).toBe(false);
+    if (!negative.success) {
+      const message = JSON.stringify(negative.error.issues);
+      expect(message).toContain('n_lines');
+    }
+  });
+
+  it('schema validation accepts -1 and -MAX_LINES but rejects -(MAX_LINES + 1)', () => {
+    expect(ReadInputSchema.safeParse({ path: '/tmp/a.txt', line_offset: -1 }).success).toBe(true);
+    expect(ReadInputSchema.safeParse({ path: '/tmp/a.txt', line_offset: -MAX_LINES }).success).toBe(
+      true,
+    );
+    expect(
+      ReadInputSchema.safeParse({ path: '/tmp/a.txt', line_offset: -(MAX_LINES + 1) }).success,
+    ).toBe(false);
+  });
+
+  it('reads non-sensitive dotfiles like .gitignore successfully', async () => {
+    const tool = toolWithContent('node_modules/\n');
+
+    const result = await executeTool(tool,context({ path: '/workspace/.gitignore' }));
+
+    expect(result.isError).toBeFalsy();
+    expect(result.output).toContain('node_modules/');
+  });
+
+  it('negative line_offset exceeding total lines returns the entire file', async () => {
+    const tool = toolWithContent('a\nb\nc\nd\ne');
+
+    const result = await executeTool(tool,context({ path: '/tmp/short.txt', line_offset: -100 }));
+
+    expect(result.isError).toBeFalsy();
+    expect(result.output).toContain('1\ta');
+    expect(result.output).toContain('5\te');
+    expect(result.output).toContain('Total lines in file: 5.');
+  });
+
+  it('tail mode on an empty file returns empty output without erroring', async () => {
+    const tool = toolWithContent('');
+
+    const result = await executeTool(tool,context({ path: '/tmp/empty-tail.txt', line_offset: -10 }));
+
+    expect(result.isError).toBeFalsy();
+    expect(result.output).toContain('Total lines in file: 0.');
+  });
+
+  it('line_offset=-1 returns only the last line with its absolute line number', async () => {
+    const tool = toolWithContent('a\nb\nc\nd\ne');
+
+    const result = await executeTool(tool,context({ path: '/tmp/last.txt', line_offset: -1 }));
+
+    expect(result.isError).toBeFalsy();
+    expect(result.output).toContain('5\te');
+    expect(result.output).toContain('1 line read from file starting from line 5.');
+  });
+
+  it('tail mode reports absolute line numbers when long lines are truncated', async () => {
+    const shortLine = 'short';
+    const longLine = 'X'.repeat(MAX_LINE_LENGTH + 500);
+    const content = [shortLine, longLine, shortLine, longLine, shortLine].join('\n');
+    const tool = toolWithContent(content);
+
+    const result = await executeTool(tool,context({ path: '/tmp/tail-trunc.txt', line_offset: -3 }));
+
+    expect(result.isError).toBeFalsy();
+    // Last 3 lines = 3, 4, 5; line 4 is the long one.
+    expect(result.output).toContain('Total lines in file: 5.');
+    expect(result.output).toContain('Lines [4] were truncated.');
+  });
+});
+
+describe('ReadTool description and schema parity', () => {
+  it('encourages reading multiple files in parallel', () => {
+    const tool = toolWithContent('');
+
+    expect(tool.description).toMatch(/parallel/i);
+    expect(tool.description).toMatch(/multiple `Read` calls in a single response/i);
+  });
+
+  it('explains the trailing <system> status block', () => {
+    const tool = toolWithContent('');
+
+    expect(tool.description).toContain('<system>');
+    // The TS implementation appends the status block after the content.
+    expect(tool.description).toMatch(/after the file content/i);
+  });
+
+  it('describes the path parameter with accurate working-directory semantics', () => {
+    const tool = toolWithContent('');
+    const pathProperty = (
+      tool.parameters as { properties: { path: { description: string } } }
+    ).properties.path;
+
+    expect(pathProperty.description).toContain('working directory');
+    expect(pathProperty.description).not.toMatch(/^Absolute path/);
+  });
+
+  it('documents the default for n_lines when omitted', () => {
+    const tool = toolWithContent('');
+    const nLinesProperty = (
+      tool.parameters as { properties: { n_lines: { description: string } } }
+    ).properties.n_lines;
+
+    // Omitting n_lines reads up to MAX_LINES; the schema description must say so.
+    expect(nLinesProperty.description).toMatch(/omit/i);
+    expect(nLinesProperty.description).toContain(String(MAX_LINES));
+  });
+
+  it('warns that sensitive files are refused', () => {
+    const tool = toolWithContent('');
+
+    expect(tool.description).toMatch(/refuse|reject|decline|block/i);
+    expect(tool.description).toMatch(/sensitive|credential|secret|\.env|SSH key/i);
+  });
+
+  it('explains that non-UTF-8 and binary files are refused', () => {
+    const tool = toolWithContent('');
+
+    expect(tool.description).toMatch(/UTF-?8/i);
+    expect(tool.description).toMatch(/binary/i);
+  });
+});
diff --git a/packages/agent-core/test/tools/result-builder.test.ts b/packages/agent-core/test/tools/result-builder.test.ts
new file mode 100644
index 000000000..a746b8136
--- /dev/null
+++ b/packages/agent-core/test/tools/result-builder.test.ts
@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+
+import { ToolResultBuilder } from '../../src/tools/support/result-builder';
+
+describe('ToolResultBuilder', () => {
+  it('returns concatenated output and a confirmation message under the limit', () => {
+    const builder = new ToolResultBuilder({ maxChars: 50 });
+
+    expect(builder.write('Hello')).toBe(5);
+    expect(builder.write(' world')).toBe(6);
+
+    const result = builder.ok('Operation completed');
+    expect(result.output).toBe('Hello world');
+    expect(result.message).toBe('Operation completed.');
+    expect(builder.nChars).toBe(11);
+  });
+
+  it('truncates with marker at the cut point and appends the message after', () => {
+    const builder = new ToolResultBuilder({ maxChars: 10 });
+
+    expect(builder.write('Hello')).toBe(5);
+    expect(builder.write(' world!')).toBe(14);
+    expect(builder.nChars).toBeGreaterThanOrEqual(10);
+
+    const result = builder.ok('Operation completed');
+    expect(result.output).toContain('Hello[...truncated]');
+    expect(result.output).toContain('Output is truncated');
+    expect(result.output.endsWith('Output is truncated to fit in the message.')).toBe(true);
+    expect(result.message).toContain('Operation completed.');
+    expect(result.message).toContain('Output is truncated');
+    expect(result.truncated).toBe(true);
+  });
+
+  it('truncates lines that exceed maxLineLength', () => {
+    const builder = new ToolResultBuilder({ maxChars: 100, maxLineLength: 20 });
+
+    expect(builder.write('This is a very long line that should be truncated\n')).toBe(20);
+
+    const result = builder.ok();
+    expect(result.output).toContain('[...truncated]');
+    expect(result.message).toContain('Output is truncated');
+  });
+
+  it('respects both per-line and per-buffer limits at once', () => {
+    const builder = new ToolResultBuilder({ maxChars: 40, maxLineLength: 20 });
+
+    expect(builder.write('Line 1\n')).toBe(7);
+    expect(builder.write('This is a very long line that exceeds limit\n')).toBe(20);
+    expect(builder.write('This would exceed char limit')).toBe(14);
+    expect(builder.write('ignored')).toBe(0);
+
+    const result = builder.ok();
+    expect(result.output).toContain('[...truncated]');
+    expect(result.message).toContain('Output is truncated');
+  });
+
+  it('tracks nChars as the buffer grows', () => {
+    const builder = new ToolResultBuilder({ maxChars: 20, maxLineLength: 30 });
+
+    expect(builder.nChars).toBe(0);
+
+    builder.write('Short\n');
+    expect(builder.nChars).toBe(6);
+
+    builder.write('1\n2\n');
+    expect(builder.nChars).toBe(10);
+
+    builder.write('More text that exceeds');
+    expect(builder.nChars).toBeGreaterThanOrEqual(20);
+  });
+
+  it('marks truncation when non-empty text arrives after the buffer is full', () => {
+    const builder = new ToolResultBuilder({ maxChars: 5 });
+
+    expect(builder.write('Hello')).toBe(5);
+    expect(builder.write(' world')).toBe(0);
+
+    const result = builder.ok();
+    expect(result.output).toContain('Hello[...truncated]');
+    expect(result.output).toContain('Output is truncated');
+    expect(result.truncated).toBe(true);
+  });
+
+  it('marks truncation when a multi-line write leaves unprocessed lines', () => {
+    const builder = new ToolResultBuilder({ maxChars: 6 });
+
+    expect(builder.write('Hello\nworld')).toBe(6);
+
+    const result = builder.ok();
+    expect(result.output).toContain('Hello\n[...truncated]');
+    expect(result.message).toContain('Output is truncated');
+  });
+
+  it('keeps unterminated trailing text in output', () => {
+    const builder = new ToolResultBuilder({ maxChars: 100 });
+
+    expect(builder.write('Line 1\nLine 2\nLine 3')).toBe(20);
+
+    const result = builder.ok();
+    expect(result.output).toBe('Line 1\nLine 2\nLine 3');
+  });
+
+  it('treats an empty write as a no-op', () => {
+    const builder = new ToolResultBuilder({ maxChars: 50 });
+
+    expect(builder.write('')).toBe(0);
+    expect(builder.nChars).toBe(0);
+  });
+
+  it('returns the accumulated output with the supplied message and brief', () => {
+    const builder = new ToolResultBuilder({ maxChars: 20 });
+
+    builder.write('Some output');
+    const result = builder.error('Something went wrong', { brief: 'Error occurred' });
+
+    expect(result.output).toContain('Some output');
+    expect(result.output).toContain('Something went wrong');
+    expect(result.message).toBe('Something went wrong');
+    expect(result.brief).toBe('Error occurred');
+  });
+
+  it('preserves an explicitly empty brief', () => {
+    const builder = new ToolResultBuilder({ maxChars: 20 });
+
+    const result = builder.ok('Done', { brief: '' });
+
+    expect(result.brief).toBe('');
+  });
+
+  it('preserves the truncation hint and brief together on error', () => {
+    const builder = new ToolResultBuilder({ maxChars: 10 });
+
+    builder.write('Very long output that exceeds limit');
+    const result = builder.error('Command failed', { brief: 'Failed' });
+
+    expect(result.output).toContain('[...truncated]');
+    expect(result.message).toContain('Command failed');
+    expect(result.message).toContain('Output is truncated');
+    expect(result.brief).toBe('Failed');
+  });
+
+  it('returns executable output with critical messages included', () => {
+    const builder = new ToolResultBuilder({ maxChars: 10 });
+
+    builder.write('Very long output that exceeds limit');
+    const result = builder.ok('Operation completed');
+
+    expect(result.output).toContain('[...truncated]');
+    expect(result.output).toContain('Output is truncated');
+    expect(result.message).toContain('Output is truncated');
+  });
+
+  it('keeps normal success messages out of non-empty output', () => {
+    const builder = new ToolResultBuilder({ maxChars: 100 });
+
+    builder.write('ok\n');
+    const result = builder.ok('Command executed successfully.');
+
+    expect(result.output).toBe('ok\n');
+    expect(result.message).toBe('Command executed successfully.');
+  });
+});
diff --git a/packages/agent-core/test/tools/rg-locator.test.ts b/packages/agent-core/test/tools/rg-locator.test.ts
new file mode 100644
index 000000000..b0aaee155
--- /dev/null
+++ b/packages/agent-core/test/tools/rg-locator.test.ts
@@ -0,0 +1,478 @@
+/**
+ * Covers: rg-locator (ripgrep hybrid binary resolution).
+ *
+ * Pure-lookup pins (no real CDN download):
+ *   - `findExistingRg` returns undefined when PATH + share-bin are both empty
+ *   - Resolves from `<shareDir>/bin/rg` when that binary exists
+ *   - Prefers system PATH over share-dir cache when both are available
+ *   - `rgUnavailableMessage` surfaces the underlying cause + install hints
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync } from 'node:fs';
+import type * as FsPromises from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { extract as extractTar } from 'tar';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ZipFile } from 'yazl';
+
+import {
+  detectTarget,
+  ensureRgPath,
+  extractRgFromZip,
+  findExistingRg,
+  rgUnavailableMessage,
+  verifyArchiveChecksum,
+} from '../../src/tools/support/rg-locator';
+
+// Download-branch tests mock `tar.extract` so the archive layout is
+// controlled by the test, not the real CDN. `fetch` is replaced per-test
+// on `globalThis` to drive the failure and success paths.
+vi.mock('tar', () => ({ extract: vi.fn() }));
+
+describe('findExistingRg', () => {
+  let fakeShare: string;
+  let savedPath: string | undefined;
+  beforeEach(() => {
+    fakeShare = join(tmpdir(), `kimi-rg-${String(Date.now())}-${String(Math.random()).slice(2)}`);
+    mkdirSync(join(fakeShare, 'bin'), { recursive: true });
+    savedPath = process.env['PATH'];
+    // Empty PATH → rules out step 1 (system-path) for the default case.
+    process.env['PATH'] = '';
+  });
+  afterEach(() => {
+    rmSync(fakeShare, { recursive: true, force: true });
+    if (savedPath === undefined) delete process.env['PATH'];
+    else process.env['PATH'] = savedPath;
+  });
+
+  it('returns undefined when no rg anywhere', async () => {
+    const result = await findExistingRg(fakeShare);
+    expect(result).toBeUndefined();
+  });
+
+  it('resolves from share-dir when cached', async () => {
+    const cached = join(fakeShare, 'bin', process.platform === 'win32' ? 'rg.exe' : 'rg');
+    writeFileSync(cached, '#!/bin/sh\necho ripgrep 15.0.0\n');
+    chmodSync(cached, 0o755);
+    const result = await findExistingRg(fakeShare);
+    expect(result).toEqual({ path: cached, source: 'share-bin-cached' });
+  });
+
+  it('prefers system PATH over share-dir when both are available', async () => {
+    // Stage a fake rg on PATH.
+    const pathDir = join(fakeShare, 'path');
+    mkdirSync(pathDir, { recursive: true });
+    const onPath = join(pathDir, process.platform === 'win32' ? 'rg.exe' : 'rg');
+    writeFileSync(onPath, '#!/bin/sh\n');
+    chmodSync(onPath, 0o755);
+    process.env['PATH'] = pathDir;
+    // Also stage a cached one to confirm the order.
+    const cached = join(fakeShare, 'bin', process.platform === 'win32' ? 'rg.exe' : 'rg');
+    writeFileSync(cached, '#!/bin/sh\n');
+    chmodSync(cached, 0o755);
+    const result = await findExistingRg(fakeShare);
+    expect(result?.source).toBe('system-path');
+    expect(result?.path).toBe(onPath);
+  });
+});
+
+describe('detectTarget', () => {
+  let savedArch: string;
+  let savedPlatform: string;
+  beforeEach(() => {
+    savedArch = process.arch;
+    savedPlatform = process.platform;
+  });
+  afterEach(() => {
+    Object.defineProperty(process, 'arch', { value: savedArch });
+    Object.defineProperty(process, 'platform', { value: savedPlatform });
+  });
+
+  function setPlatform(arch: string, platform: string): void {
+    Object.defineProperty(process, 'arch', { value: arch });
+    Object.defineProperty(process, 'platform', { value: platform });
+  }
+
+  it('darwin arm64 → aarch64-apple-darwin', () => {
+    setPlatform('arm64', 'darwin');
+    expect(detectTarget()).toBe('aarch64-apple-darwin');
+  });
+  it('darwin x64 → x86_64-apple-darwin', () => {
+    setPlatform('x64', 'darwin');
+    expect(detectTarget()).toBe('x86_64-apple-darwin');
+  });
+  it('linux x64 → x86_64-unknown-linux-musl', () => {
+    setPlatform('x64', 'linux');
+    expect(detectTarget()).toBe('x86_64-unknown-linux-musl');
+  });
+  it('linux arm64 → aarch64-unknown-linux-gnu', () => {
+    setPlatform('arm64', 'linux');
+    expect(detectTarget()).toBe('aarch64-unknown-linux-gnu');
+  });
+  it('win32 x64 → x86_64-pc-windows-msvc', () => {
+    setPlatform('x64', 'win32');
+    expect(detectTarget()).toBe('x86_64-pc-windows-msvc');
+  });
+  it('unsupported arch → undefined', () => {
+    setPlatform('mips', 'linux');
+    expect(detectTarget()).toBeUndefined();
+  });
+});
+
+describe('rgUnavailableMessage', () => {
+  it('surfaces the underlying cause and install hints', () => {
+    const msg = rgUnavailableMessage(new Error('fetch failed'));
+    expect(msg).toContain('fetch failed');
+    expect(msg).toContain('brew install ripgrep');
+    expect(msg).toContain('https://github.com/BurntSushi/ripgrep');
+  });
+
+  it('handles non-Error causes (string, unknown)', () => {
+    const a = rgUnavailableMessage('boom');
+    expect(a).toContain('boom');
+    const b = rgUnavailableMessage(42);
+    expect(b).toContain('unknown error');
+  });
+});
+
+describe('verifyArchiveChecksum', () => {
+  let fakeDir: string;
+  beforeEach(() => {
+    fakeDir = join(tmpdir(), `kimi-rg-sha-${String(Date.now())}-${String(Math.random()).slice(2)}`);
+    mkdirSync(fakeDir, { recursive: true });
+  });
+  afterEach(() => {
+    rmSync(fakeDir, { recursive: true, force: true });
+  });
+
+  it('accepts a file whose SHA-256 matches the expected digest', async () => {
+    const archivePath = join(fakeDir, 'archive.tar.gz');
+    const payload = Buffer.from('trusted archive bytes', 'utf8');
+    writeFileSync(archivePath, payload);
+    const expectedSha256 = createHash('sha256').update(payload).digest('hex');
+
+    await expect(
+      verifyArchiveChecksum(archivePath, 'archive.tar.gz', expectedSha256),
+    ).resolves.toBeUndefined();
+  });
+
+  it('rejects a file whose SHA-256 differs from the expected digest', async () => {
+    const archivePath = join(fakeDir, 'archive.tar.gz');
+    writeFileSync(archivePath, 'tampered archive bytes');
+
+    await expect(
+      verifyArchiveChecksum(archivePath, 'archive.tar.gz', '0'.repeat(64)),
+    ).rejects.toThrow(/checksum mismatch/);
+  });
+});
+
+describe('ensureRgPath download branch', () => {
+  let fakeShare: string;
+  let savedPath: string | undefined;
+  let savedFetch: typeof globalThis.fetch | undefined;
+  beforeEach(() => {
+    fakeShare = join(
+      tmpdir(),
+      `kimi-rg-dl-${String(Date.now())}-${String(Math.random()).slice(2)}`,
+    );
+    mkdirSync(join(fakeShare, 'bin'), { recursive: true });
+    savedPath = process.env['PATH'];
+    process.env['PATH'] = ''; // force the locator past `whichRg`
+    savedFetch = globalThis.fetch;
+  });
+  afterEach(() => {
+    rmSync(fakeShare, { recursive: true, force: true });
+    if (savedPath === undefined) delete process.env['PATH'];
+    else process.env['PATH'] = savedPath;
+    if (savedFetch === undefined) {
+      // oxlint-disable-next-line @typescript-eslint/no-explicit-any
+      delete (globalThis as unknown as { fetch?: typeof fetch }).fetch;
+    } else {
+      globalThis.fetch = savedFetch;
+    }
+    vi.restoreAllMocks();
+  });
+
+  it('surfaces a network error when fetch rejects', async () => {
+    globalThis.fetch = vi.fn().mockRejectedValue(new Error('network unreachable')) as typeof fetch;
+    await expect(ensureRgPath({ shareDir: fakeShare })).rejects.toThrow(/network unreachable/);
+  });
+
+  it('does not start bootstrap work when the caller is already aborted', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const fetchMock = vi.fn();
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    await expect(
+      ensureRgPath({ shareDir: fakeShare, signal: controller.signal }),
+    ).rejects.toHaveProperty('name', 'AbortError');
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('does not start bootstrap work when aborted after lookup misses', async () => {
+    const controller = new AbortController();
+    const fetchMock = vi.fn(() => new Promise<Response>(() => {}));
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    let rejectFirstStat: ((error: Error) => void) | undefined;
+    let statCalls = 0;
+    const statMock = vi.fn(() => {
+      statCalls += 1;
+      if (statCalls === 1) {
+        return new Promise<never>((_resolve, reject) => {
+          rejectFirstStat = reject;
+        });
+      }
+      return Promise.reject(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+    });
+
+    vi.resetModules();
+    vi.doMock('node:fs/promises', async () => {
+      const actual = await vi.importActual<typeof FsPromises>('node:fs/promises');
+      return { ...actual, stat: statMock };
+    });
+
+    try {
+      const { ensureRgPath: isolatedEnsureRgPath } =
+        await import('../../src/tools/support/rg-locator');
+      const resultPromise = isolatedEnsureRgPath({
+        shareDir: fakeShare,
+        signal: controller.signal,
+      });
+
+      await vi.waitFor(() => {
+        expect(statMock).toHaveBeenCalledTimes(1);
+      });
+      controller.abort();
+      rejectFirstStat?.(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+
+      await expect(resultPromise).rejects.toHaveProperty('name', 'AbortError');
+      await new Promise((resolve) => {
+        setTimeout(resolve, 20);
+      });
+
+      expect(statMock).toHaveBeenCalledTimes(1);
+      expect(fetchMock).not.toHaveBeenCalled();
+    } finally {
+      vi.doUnmock('node:fs/promises');
+      vi.resetModules();
+    }
+  });
+
+  it('aborts the current caller wait while shared bootstrap work continues', async () => {
+    const controller = new AbortController();
+    let resolveFetch: (response: {
+      ok: false;
+      status: number;
+      statusText: string;
+      body: null;
+    }) => void = () => {};
+    const fetchResponse = new Promise<{
+      ok: false;
+      status: number;
+      statusText: string;
+      body: null;
+    }>((resolve) => {
+      resolveFetch = resolve;
+    });
+    globalThis.fetch = vi.fn(() => fetchResponse) as unknown as typeof fetch;
+
+    const resultPromise = ensureRgPath({ shareDir: fakeShare, signal: controller.signal });
+    await vi.waitFor(() => {
+      expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    });
+
+    controller.abort();
+    await expect(resultPromise).rejects.toHaveProperty('name', 'AbortError');
+
+    resolveFetch({ ok: false, status: 499, statusText: 'Client Closed', body: null });
+    await expect(ensureRgPath({ shareDir: fakeShare })).rejects.toThrow(/HTTP 499 Client Closed/);
+  });
+
+  it('surfaces HTTP failure (non-2xx response) with status + statusText', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 404,
+      statusText: 'Not Found',
+      body: null,
+    }) as unknown as typeof fetch;
+    await expect(ensureRgPath({ shareDir: fakeShare })).rejects.toThrow(/HTTP 404 Not Found/);
+  });
+
+  it('fetches ripgrep over HTTPS', async () => {
+    const body = bodyFromBuffer(Buffer.from('not a real archive', 'utf8'));
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      body,
+    });
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    await expect(ensureRgPath({ shareDir: fakeShare })).rejects.toThrow();
+
+    const [url] = fetchMock.mock.calls[0] as [string];
+    expect(new URL(url).protocol).toBe('https:');
+  });
+
+  it('rejects archives that do not match the pinned SHA-256 before extraction', async () => {
+    const tarMock = vi.mocked(extractTar);
+    tarMock.mockClear();
+    const body = bodyFromBuffer(Buffer.from('tampered archive', 'utf8'));
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      body,
+    }) as unknown as typeof fetch;
+
+    await expect(ensureRgPath({ shareDir: fakeShare })).rejects.toThrow(/checksum/i);
+
+    expect(tarMock).not.toHaveBeenCalled();
+    expect(existsSync(join(fakeShare, 'bin', process.platform === 'win32' ? 'rg.exe' : 'rg'))).toBe(
+      false,
+    );
+  });
+});
+
+// ── Windows zip download branch ─────────────────────────────────────────
+//
+// Counterpart to the Linux `ensureRgPath download branch` tests but
+// drives the `target.includes('windows')` path: the CDN delivers a `.zip`,
+// yauzl walks the entries, and `rg.exe` lands at `<shareDir>/bin/rg.exe`.
+// `detectTarget()` reads `process.platform` + `process.arch`, so we
+// override both per-test via Object.defineProperty (the same trick used
+// by the `detectTarget` suite above).
+//
+// Fixture zips are built in-memory with `yazl` so tests stay hermetic
+// (no committed binary fixtures on the repo). The archive uses the
+// layout the CDN actually ships (`ripgrep-{ver}-{target}/rg.exe`).
+
+function buildFixtureZip(entries: Array<{ name: string; content: Buffer }>): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const zip = new ZipFile();
+    for (const { name, content } of entries) {
+      zip.addBuffer(content, name);
+    }
+    zip.end();
+    const chunks: Buffer[] = [];
+    zip.outputStream.on('data', (c: Buffer) => chunks.push(c));
+    zip.outputStream.on('end', () => {
+      resolve(Buffer.concat(chunks));
+    });
+    zip.outputStream.on('error', reject);
+  });
+}
+
+function bodyFromBuffer(buf: Buffer): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(new Uint8Array(buf));
+      controller.close();
+    },
+  });
+}
+
+describe('ensureRgPath Windows download branch', () => {
+  let fakeShare: string;
+  let savedPath: string | undefined;
+  let savedFetch: typeof globalThis.fetch | undefined;
+  let savedArch: string;
+  let savedPlatform: string;
+  beforeEach(() => {
+    fakeShare = join(
+      tmpdir(),
+      `kimi-rg-win-${String(Date.now())}-${String(Math.random()).slice(2)}`,
+    );
+    mkdirSync(join(fakeShare, 'bin'), { recursive: true });
+    savedPath = process.env['PATH'];
+    process.env['PATH'] = ''; // force past whichRg
+    savedFetch = globalThis.fetch;
+    savedArch = process.arch;
+    savedPlatform = process.platform;
+    // Simulate a Windows host end-to-end — `rgBinaryName()`, `whichRg()`
+    // (PATH sep), and `detectTarget()` all key off these two values.
+    Object.defineProperty(process, 'arch', { value: 'x64' });
+    Object.defineProperty(process, 'platform', { value: 'win32' });
+  });
+  afterEach(() => {
+    rmSync(fakeShare, { recursive: true, force: true });
+    if (savedPath === undefined) delete process.env['PATH'];
+    else process.env['PATH'] = savedPath;
+    if (savedFetch === undefined) {
+      delete (globalThis as unknown as { fetch?: typeof fetch }).fetch;
+    } else {
+      globalThis.fetch = savedFetch;
+    }
+    Object.defineProperty(process, 'arch', { value: savedArch });
+    Object.defineProperty(process, 'platform', { value: savedPlatform });
+    vi.restoreAllMocks();
+  });
+
+  it('fetches the .zip URL (not .tar.gz) on Windows target', async () => {
+    const zipBuf = await buildFixtureZip([
+      {
+        name: 'ripgrep-15.0.0-x86_64-pc-windows-msvc/rg.exe',
+        content: Buffer.from('MZfake-pe-bytes', 'utf8'),
+      },
+    ]);
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      body: bodyFromBuffer(zipBuf),
+    });
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    await expect(ensureRgPath({ shareDir: fakeShare })).rejects.toThrow(/checksum mismatch/);
+
+    const [url] = fetchMock.mock.calls[0] as [string];
+    expect(url).toMatch(/ripgrep-15\.0\.0-x86_64-pc-windows-msvc\.zip$/);
+  });
+
+  it('extracts rg.exe into <shareDir>/bin/rg.exe', async () => {
+    const payload = Buffer.from('MZfake-pe-bytes-extracted', 'utf8');
+    const zipBuf = await buildFixtureZip([
+      {
+        name: 'ripgrep-15.0.0-x86_64-pc-windows-msvc/rg.exe',
+        content: payload,
+      },
+    ]);
+
+    const archivePath = join(fakeShare, 'fixture.zip');
+    const installed = join(fakeShare, 'bin', 'rg.exe');
+    writeFileSync(archivePath, zipBuf);
+
+    await extractRgFromZip(archivePath, installed);
+
+    expect(existsSync(installed)).toBe(true);
+    expect(readFileSync(installed)).toEqual(payload);
+  });
+
+  it('throws with "CDN content may have changed" when the zip omits rg.exe', async () => {
+    // Archive is well-formed but holds the wrong entry — mirrors the
+    // Counterpart to the Linux third-download test's sentinel.
+    const zipBuf = await buildFixtureZip([{ name: 'README.md', content: Buffer.from('readme') }]);
+    const archivePath = join(fakeShare, 'fixture.zip');
+    const installed = join(fakeShare, 'bin', 'rg.exe');
+    writeFileSync(archivePath, zipBuf);
+
+    await expect(extractRgFromZip(archivePath, installed)).rejects.toThrow(
+      /CDN content may have changed/,
+    );
+  });
+
+  it('surfaces HTTP failure on Windows with status + statusText', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 502,
+      statusText: 'Bad Gateway',
+      body: null,
+    }) as unknown as typeof fetch;
+    await expect(ensureRgPath({ shareDir: fakeShare })).rejects.toThrow(/HTTP 502 Bad Gateway/);
+  });
+});
diff --git a/packages/agent-core/test/tools/shell-cancel.test.ts b/packages/agent-core/test/tools/shell-cancel.test.ts
new file mode 100644
index 000000000..efa44e102
--- /dev/null
+++ b/packages/agent-core/test/tools/shell-cancel.test.ts
@@ -0,0 +1,57 @@
+import { Readable, type Writable } from 'node:stream';
+
+import type { KaosProcess } from '@moonshot-ai/kaos';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BashTool } from '../../src/tools/builtin/shell/bash';
+import type { Environment } from '../../src/utils/environment';
+import { executeTool } from './fixtures/execute-tool';
+import { createFakeKaos } from './fixtures/fake-kaos';
+
+const posixEnv: Environment = {
+  osKind: 'Linux',
+  osArch: 'x86_64',
+  osVersion: 'test',
+  shellPath: '/bin/bash',
+  shellName: 'bash',
+};
+
+describe('BashTool cancellation contract', () => {
+  it('reports the cancellation with an "Interrupted by user" message and kills the process', async () => {
+    let resolveWait: (code: number) => void = () => {};
+    const waitPromise = new Promise<number>((resolve) => {
+      resolveWait = resolve;
+    });
+    const kill = vi.fn(async () => {
+      resolveWait(143);
+    });
+    const proc: KaosProcess = {
+      stdin: { end: vi.fn(), write: vi.fn() } as unknown as Writable,
+      stdout: Readable.from([]),
+      stderr: Readable.from([]),
+      pid: 501,
+      exitCode: null,
+      wait: vi.fn(async () => waitPromise),
+      kill,
+    };
+    const execWithEnv = vi.fn().mockResolvedValue(proc);
+    const controller = new AbortController();
+    const tool = new BashTool(createFakeKaos({ execWithEnv }), '/workspace', posixEnv);
+
+    const running = executeTool(tool, {
+      turnId: '0',
+      toolCallId: 'tc_cancel',
+      args: { command: 'sleep 2 && printf should-not-exist > cancel_output.txt' },
+      signal: controller.signal,
+    });
+    await vi.waitFor(() => {
+      expect(proc.stdin.end).toHaveBeenCalled();
+    });
+    controller.abort();
+    const result = await running;
+
+    expect(kill).toHaveBeenCalledWith('SIGTERM');
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('Interrupted by user');
+  });
+});
diff --git a/packages/agent-core/test/tools/shell-quoting.test.ts b/packages/agent-core/test/tools/shell-quoting.test.ts
new file mode 100644
index 000000000..6ec94f793
--- /dev/null
+++ b/packages/agent-core/test/tools/shell-quoting.test.ts
@@ -0,0 +1,135 @@
+import { Readable, type Writable } from 'node:stream';
+
+import type { KaosProcess } from '@moonshot-ai/kaos';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BashInputSchema, BashTool } from '../../src/tools/builtin/shell/bash';
+import type { Environment } from '../../src/utils/environment';
+import { executeTool } from './fixtures/execute-tool';
+import { createFakeKaos } from './fixtures/fake-kaos';
+
+const linuxEnv: Environment = {
+  osKind: 'Linux',
+  osArch: 'x86_64',
+  osVersion: 'test',
+  shellPath: '/bin/bash',
+  shellName: 'bash',
+};
+
+const windowsBashEnv: Environment = {
+  osKind: 'Windows',
+  osArch: 'x86_64',
+  osVersion: 'test',
+  shellPath: 'C:\\Program Files\\Git\\bin\\bash.exe',
+  shellName: 'bash',
+};
+
+function fakeProcess(): KaosProcess {
+  return {
+    stdin: { end: vi.fn(), write: vi.fn() } as unknown as Writable,
+    stdout: Readable.from([]),
+    stderr: Readable.from([]),
+    pid: 321,
+    exitCode: 0,
+    wait: vi.fn(async () => 0),
+    kill: vi.fn(async () => {}),
+  };
+}
+
+const signal = new AbortController().signal;
+
+function captureCommandRewrite(
+  env: Environment,
+  command: string,
+): Promise<{ rewritten: string; argv: readonly string[] }> {
+  const execWithEnv = vi.fn().mockResolvedValue(fakeProcess());
+  const cwd = env.osKind === 'Windows' ? 'C:\\work' : '/work';
+  const tool = new BashTool(createFakeKaos({ execWithEnv }), cwd, env);
+
+  return executeTool(tool, {
+    turnId: '0',
+    toolCallId: 'tc_quote',
+    args: { command, timeout: 1000 },
+    signal,
+  }).then(() => {
+      const argv = execWithEnv.mock.calls[0]?.[0] as readonly string[];
+      // The shell wrapper is "cd '<cwd>' && <rewritten>"; isolate the rewrite.
+      const wrapped = argv[2]!;
+      const match = /^cd '[^']+' && (.*)$/.exec(wrapped)!;
+      return { rewritten: match[1]!, argv };
+    });
+}
+
+// Helpers above test the same defensive rewrite the standalone util tests
+// exercise: the windows-only nul redirect rewrite must survive composition
+// inside the BashTool argv pipeline.
+describe('shell command nul-redirect rewrite (Windows Git Bash)', () => {
+  it.each([
+    ['ls >nul', 'ls >/dev/null'],
+    ['ls > NUL', 'ls > /dev/null'],
+    ['ls 2>nul', 'ls 2>/dev/null'],
+    ['ls &>nul', 'ls &>/dev/null'],
+    ['ls >>nul', 'ls >>/dev/null'],
+    ['ls >Nul', 'ls >/dev/null'],
+    ['ls >NUL', 'ls >/dev/null'],
+    ['ls 2>nul | grep foo', 'ls 2>/dev/null | grep foo'],
+    ['ls 2>nul; echo done', 'ls 2>/dev/null; echo done'],
+    ['ls 2>nul && echo ok', 'ls 2>/dev/null && echo ok'],
+    ['ls 2>nul) ', 'ls 2>/dev/null) '],
+    ['ls 2>  nul', 'ls 2>  /dev/null'],
+    ['foo >nul; bar 2>nul', 'foo >/dev/null; bar 2>/dev/null'],
+  ])('rewrites %s', async (before, after) => {
+    const { rewritten } = await captureCommandRewrite(windowsBashEnv, before);
+    expect(rewritten).toBe(after);
+  });
+});
+
+describe('shell command nul-redirect non-rewrites (Windows Git Bash)', () => {
+  it.each([
+    'ls >null',
+    'ls >nullable',
+    'ls >nul.txt',
+    'cat nul.txt',
+    'echo nul',
+    "echo 'nul'",
+    'ls > nul_file',
+    'ls >nulX',
+  ])('leaves %s unchanged', async (command) => {
+    const { rewritten } = await captureCommandRewrite(windowsBashEnv, command);
+    expect(rewritten).toBe(command);
+  });
+
+  it('does not rewrite quoted >nul with trailing double-quote', async () => {
+    const command = 'echo ">nul"';
+    const { rewritten } = await captureCommandRewrite(windowsBashEnv, command);
+    expect(rewritten).toBe(command);
+  });
+});
+
+describe('shell command unchanged paths (Windows Git Bash)', () => {
+  it('passes a plain command through untouched', async () => {
+    const command = 'git status && git diff';
+    const { rewritten } = await captureCommandRewrite(windowsBashEnv, command);
+    expect(rewritten).toBe(command);
+  });
+
+  // The rewrite helper is not exported, so the empty-command contract is
+  // only observable at the schema boundary: BashInputSchema rejects ''
+  // before the rewrite is ever invoked.
+  it('rejects empty command at the schema layer', () => {
+    expect(BashInputSchema.safeParse({ command: '' }).success).toBe(false);
+  });
+});
+
+describe('shell command nul-redirect — non-Windows passthrough', () => {
+  it.each([
+    'ls >nul',
+    'ls 2>nul',
+    'ls &>nul',
+    'ls >>nul',
+    'foo >nul; bar 2>nul',
+  ])('does not rewrite %s on Linux', async (command) => {
+    const { rewritten } = await captureCommandRewrite(linuxEnv, command);
+    expect(rewritten).toBe(command);
+  });
+});
diff --git a/packages/agent-core/test/tools/skill-tool-dispatch.test.ts b/packages/agent-core/test/tools/skill-tool-dispatch.test.ts
new file mode 100644
index 000000000..32701dea2
--- /dev/null
+++ b/packages/agent-core/test/tools/skill-tool-dispatch.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Agent } from '../../src/agent';
+import type { SkillActivationOrigin } from '../../src/agent/context';
+import { SkillRegistry, type SkillDefinition } from '../../src/skill';
+import {
+  MAX_SKILL_QUERY_DEPTH,
+  NestedSkillTooDeepError,
+  SkillTool,
+} from '../../src/tools/builtin/collaboration/skill-tool';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+function skill(name: string, metadata: SkillDefinition['metadata'] = {}): SkillDefinition {
+  return {
+    name,
+    description: `desc for ${name}`,
+    path: `/skills/${name}/SKILL.md`,
+    dir: `/skills/${name}`,
+    content: `body of ${name}`,
+    metadata,
+    source: 'user',
+  };
+}
+
+function registry(skills: readonly SkillDefinition[] = []): SkillRegistry {
+  const registry = new SkillRegistry();
+  for (const item of skills) {
+    registry.register(item);
+  }
+  return registry;
+}
+
+interface SkillToolMethods {
+  readonly recordSkillActivation: (origin: SkillActivationOrigin) => void;
+  readonly recordSystemReminder: (content: string, origin: SkillActivationOrigin) => void;
+}
+
+function skillToolMethods() {
+  return {
+    recordSkillActivation: vi.fn<SkillToolMethods['recordSkillActivation']>(),
+    recordSystemReminder: vi.fn<SkillToolMethods['recordSystemReminder']>(),
+  } satisfies SkillToolMethods;
+}
+
+function skillToolAgent(skills: SkillRegistry, methods: SkillToolMethods): Agent {
+  return {
+    skills: {
+      registry: skills,
+      recordActivation: methods.recordSkillActivation,
+    },
+    context: {
+      appendSystemReminder: methods.recordSystemReminder,
+    },
+  } as unknown as Agent;
+}
+
+function skillTool(
+  skills: SkillRegistry,
+  methods = skillToolMethods(),
+  options?: ConstructorParameters<typeof SkillTool>[1],
+): SkillTool {
+  return new SkillTool(skillToolAgent(skills, methods), options);
+}
+
+function execute(tool: SkillTool, args: { skill: string; args?: string }) {
+  return executeTool(tool, {
+    turnId: '0',
+    toolCallId: 'call_skill',
+    args,
+    signal,
+  });
+}
+
+describe('SkillTool dispatch edges', () => {
+  it('treats prompt skills as inline skills', async () => {
+    const methods = skillToolMethods();
+    const tool = skillTool(registry([skill('prompt-skill', { type: 'prompt' })]), methods);
+
+    const result = await execute(tool, { skill: 'prompt-skill' });
+
+    expect(result.output).toContain('loaded inline');
+    expect(result.output).not.toContain('body of prompt-skill');
+    expect(methods.recordSystemReminder.mock.calls[0]?.[0]).toContain('body of prompt-skill');
+    expect(methods.recordSkillActivation).toHaveBeenCalledTimes(1);
+  });
+
+  it('treats omitted skill type as inline for backwards-compatible skill files', async () => {
+    const methods = skillToolMethods();
+    const tool = skillTool(registry([skill('legacy')]), methods);
+
+    const result = await execute(tool, { skill: 'legacy' });
+
+    expect(result.output).toContain('loaded inline');
+    expect(result.output).not.toContain('body of legacy');
+    expect(methods.recordSystemReminder.mock.calls[0]?.[0]).toContain('body of legacy');
+    expect(methods.recordSkillActivation).toHaveBeenCalledTimes(1);
+  });
+
+  it('honors initialQueryDepth as an alias for queryDepth', async () => {
+    const tool = skillTool(registry([skill('loop')]), skillToolMethods(), {
+      initialQueryDepth: MAX_SKILL_QUERY_DEPTH,
+    });
+
+    await expect(execute(tool, { skill: 'loop' })).rejects.toBeInstanceOf(NestedSkillTooDeepError);
+  });
+});
diff --git a/packages/agent-core/test/tools/skill-tool.test.ts b/packages/agent-core/test/tools/skill-tool.test.ts
new file mode 100644
index 000000000..49a343eae
--- /dev/null
+++ b/packages/agent-core/test/tools/skill-tool.test.ts
@@ -0,0 +1,247 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Agent } from '../../src/agent';
+import type { SkillActivationOrigin } from '../../src/agent/context';
+import { SkillRegistry, type SkillDefinition } from '../../src/skill';
+import {
+  MAX_SKILL_QUERY_DEPTH,
+  NestedSkillTooDeepError,
+  SkillTool,
+  SkillToolInputSchema,
+} from '../../src/tools/builtin/collaboration/skill-tool';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+function skill(
+  name: string,
+  metadata: SkillDefinition['metadata'] = {},
+  content = `body of ${name}`,
+): SkillDefinition {
+  return {
+    name,
+    description: `desc for ${name}`,
+    path: `/skills/${name}/SKILL.md`,
+    dir: `/skills/${name}`,
+    content,
+    metadata,
+    source: 'user',
+  };
+}
+
+function registry(
+  skills: readonly SkillDefinition[] = [],
+  options: { readonly sessionId?: string } = {},
+): SkillRegistry {
+  const registry = new SkillRegistry(options);
+  for (const item of skills) {
+    registry.register(item);
+  }
+  return registry;
+}
+
+interface SkillToolMethods {
+  readonly recordSkillActivation: (origin: SkillActivationOrigin) => void;
+  readonly recordSystemReminder: (content: string, origin: SkillActivationOrigin) => void;
+}
+
+function skillToolMethods() {
+  return {
+    recordSkillActivation: vi.fn<SkillToolMethods['recordSkillActivation']>(),
+    recordSystemReminder: vi.fn<SkillToolMethods['recordSystemReminder']>(),
+  } satisfies SkillToolMethods;
+}
+
+function skillToolAgent(skills: SkillRegistry, methods: SkillToolMethods): Agent {
+  return {
+    skills: {
+      registry: skills,
+      recordActivation: methods.recordSkillActivation,
+    },
+    context: {
+      appendSystemReminder: methods.recordSystemReminder,
+    },
+  } as unknown as Agent;
+}
+
+function skillTool(
+  skills: SkillRegistry,
+  methods = skillToolMethods(),
+  options?: ConstructorParameters<typeof SkillTool>[1],
+): SkillTool {
+  return new SkillTool(skillToolAgent(skills, methods), options);
+}
+
+function execute(tool: SkillTool, args: { skill: string; args?: string }) {
+  return executeTool(tool, {
+    turnId: '0',
+    toolCallId: 'call_skill',
+    args,
+    signal,
+  });
+}
+
+describe('SkillTool metadata and schema', () => {
+  it('exposes the current tool contract', () => {
+    const tool = skillTool(registry());
+
+    expect(tool.name).toBe('Skill');
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: { skill: { type: 'string' } },
+    });
+    expect(SkillToolInputSchema.safeParse({ skill: 'commit' }).success).toBe(true);
+    expect(SkillToolInputSchema.safeParse({ skill: 'commit', args: '-m fix' }).success).toBe(true);
+    expect(SkillToolInputSchema.safeParse({}).success).toBe(false);
+    expect(MAX_SKILL_QUERY_DEPTH).toBe(3);
+  });
+});
+
+describe('SkillTool execution', () => {
+  it('returns a tool error when the skill is unknown', async () => {
+    const tool = skillTool(registry());
+
+    const result = await execute(tool, { skill: 'missing' });
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('not found');
+  });
+
+  it('rejects skills that disable model invocation', async () => {
+    const tool = skillTool(registry([skill('secret', { disableModelInvocation: true })]));
+
+    const result = await execute(tool, { skill: 'secret' });
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('can only be triggered by the user');
+  });
+
+  it('rejects non-inline skill types in the current v1 runtime', async () => {
+    const methods = skillToolMethods();
+    const tool = skillTool(registry([skill('review', { type: 'fork' })]), methods);
+
+    const result = await execute(tool, { skill: 'review' });
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('not an inline skill');
+    expect(methods.recordSkillActivation).not.toHaveBeenCalled();
+  });
+
+  it('records inline skill content as a system reminder', async () => {
+    const methods = skillToolMethods();
+    const tool = skillTool(registry([skill('commit')]), methods);
+
+    const result = await execute(tool, { skill: 'commit', args: 'message text' });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.output).toContain('loaded inline');
+    expect(result.output).not.toContain('body of commit');
+    expect(methods.recordSkillActivation).toHaveBeenCalledTimes(1);
+    expect(methods.recordSystemReminder).toHaveBeenCalledTimes(1);
+    expect(methods.recordSystemReminder.mock.calls[0]?.[0]).toContain(
+      '<kimi-skill-loaded name="commit" args="message text">\nbody of commit\n\nARGUMENTS: message text\n</kimi-skill-loaded>',
+    );
+  });
+
+  it('expands skill body placeholders for model-invoked inline skills', async () => {
+    const methods = skillToolMethods();
+    const tool = skillTool(
+      registry([
+        skill(
+          'commit',
+          { arguments: ['flag', 'message'] },
+          'Flag: $flag\nCommit message: $message\nRaw: $ARGUMENTS',
+        ),
+      ]),
+      methods,
+    );
+
+    await execute(tool, { skill: 'commit', args: '-m "fix login"' });
+
+    expect(methods.recordSystemReminder.mock.calls[0]?.[0]).toContain(
+      '<kimi-skill-loaded name="commit" args="-m &quot;fix login&quot;">\nFlag: -m\nCommit message: fix login\nRaw: -m "fix login"\n</kimi-skill-loaded>',
+    );
+    expect(methods.recordSystemReminder.mock.calls[0]?.[0]).not.toContain('ARGUMENTS:');
+  });
+
+  it('expands session id from the skill registry for model-invoked skills', async () => {
+    const methods = skillToolMethods();
+    const tool = skillTool(
+      registry([skill('session-aware', {}, 'Session: ${KIMI_SESSION_ID}')], {
+        sessionId: 'ses_model_skill',
+      }),
+      methods,
+    );
+
+    await execute(tool, { skill: 'session-aware' });
+
+    expect(methods.recordSystemReminder.mock.calls[0]?.[0]).toContain(
+      '<kimi-skill-loaded name="session-aware" args="">\nSession: ses_model_skill\n</kimi-skill-loaded>',
+    );
+  });
+
+  it('notifies inline skill activation without exposing the skill body', async () => {
+    const methods = skillToolMethods();
+    const tool = skillTool(registry([skill('commit')]), methods);
+
+    await execute(tool, { skill: 'commit', args: 'message text' });
+
+    expect(methods.recordSkillActivation).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: 'skill_activation',
+        activationId: expect.any(String),
+        skillName: 'commit',
+        skillArgs: 'message text',
+        trigger: 'model-tool',
+        skillPath: '/skills/commit/SKILL.md',
+        skillSource: 'user',
+      }),
+    );
+    expect(JSON.stringify(methods.recordSkillActivation.mock.calls[0]?.[0])).not.toContain(
+      'body of commit',
+    );
+  });
+
+  it('escapes skill name and args in the wrapper boundaries', async () => {
+    const methods = skillToolMethods();
+    const tool = skillTool(registry([skill('a&b')]), methods);
+
+    await execute(tool, { skill: 'a&b', args: '<raw "value">' });
+
+    expect(methods.recordSystemReminder.mock.calls[0]?.[0]).toContain(
+      '<kimi-skill-loaded name="a&amp;b" args="&lt;raw &quot;value&quot;&gt;">\nbody of a&b\n\nARGUMENTS: <raw "value">\n</kimi-skill-loaded>',
+    );
+    expect(methods.recordSkillActivation).toHaveBeenCalledTimes(1);
+  });
+
+  it('marks nested skill activations when invoked from inside another skill', async () => {
+    const methods = skillToolMethods();
+    const tool = skillTool(registry([skill('nested')]), methods, { queryDepth: 1 });
+
+    await execute(tool, { skill: 'nested' });
+
+    expect(methods.recordSkillActivation).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: 'skill_activation',
+        skillName: 'nested',
+        trigger: 'nested-skill',
+      }),
+    );
+  });
+});
+
+describe('SkillTool recursion guard', () => {
+  it('throws NestedSkillTooDeepError when the depth cap has already been reached', async () => {
+    const tool = skillTool(registry([skill('loop')]), skillToolMethods(), {
+      queryDepth: MAX_SKILL_QUERY_DEPTH,
+    });
+
+    await expect(execute(tool, { skill: 'loop' })).rejects.toBeInstanceOf(NestedSkillTooDeepError);
+  });
+
+  it('withInitialQueryDepth returns a tool seeded with that depth', async () => {
+    const tool = skillTool(registry([skill('loop')])).withInitialQueryDepth(MAX_SKILL_QUERY_DEPTH);
+
+    await expect(execute(tool, { skill: 'loop' })).rejects.toBeInstanceOf(NestedSkillTooDeepError);
+  });
+});
diff --git a/packages/agent-core/test/tools/todo-list.test.ts b/packages/agent-core/test/tools/todo-list.test.ts
new file mode 100644
index 000000000..965c110fa
--- /dev/null
+++ b/packages/agent-core/test/tools/todo-list.test.ts
@@ -0,0 +1,169 @@
+/**
+ * Covers the current TodoListTool contract.
+ *
+ * The todo state now lives in the agent tool store. The tool returns a
+ * user-readable string in `output` and persists structured todos through
+ * the injected store.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  TodoListInputSchema,
+  TodoListTool,
+  type TodoItem,
+} from '../../src/tools/builtin/state/todo-list';
+import type { ToolStore } from '../../src/tools/store';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+function makeStore(initial: readonly TodoItem[] = []): {
+  store: ToolStore;
+  getTodos(): readonly TodoItem[];
+} {
+  let todos = [...initial];
+  return {
+    store: {
+      get: (key) => (key === 'todo' ? todos : undefined),
+      set: (key, value) => {
+        if (key === 'todo') {
+          todos = [...(value as readonly TodoItem[])];
+        }
+      },
+    },
+    getTodos: () => todos,
+  };
+}
+
+function makeTool(initial: readonly TodoItem[] = []): {
+  tool: TodoListTool;
+  getTodos(): readonly TodoItem[];
+} {
+  const { store, getTodos } = makeStore(initial);
+  return { tool: new TodoListTool(store), getTodos };
+}
+
+describe('TodoListTool', () => {
+  it('has name, description, and parameters from the current schema', () => {
+    const { tool } = makeTool();
+
+    expect(tool.name).toBe('TodoList');
+    expect(tool.description.length).toBeGreaterThan(0);
+    expect(TodoListInputSchema.safeParse({}).success).toBe(true);
+    expect(
+      TodoListInputSchema.safeParse({ todos: [{ title: 'x', status: 'wip' }] }).success,
+    ).toBe(false);
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: {
+        todos: { type: 'array' },
+      },
+    });
+  });
+
+  it('description includes an Avoid churn section with the anti-spin guardrails', () => {
+    const { tool } = makeTool();
+    const { description } = tool;
+
+    expect(description).toContain('**Avoid churn:**');
+    // (1) do not re-call the tool when nothing meaningful changed between calls.
+    expect(description).toMatch(/nothing meaningful has changed/i);
+    expect(description).toMatch(/real progress/i);
+    // (2) when unsure of the current state, use query mode first.
+    expect(description).toMatch(/query mode/i);
+    // (3) when stuck, tell the user instead of repeatedly re-ordering todos.
+    expect(description).toMatch(/tell the user/i);
+  });
+
+  it('query mode renders the current list without mutating it', async () => {
+    const { tool, getTodos } = makeTool([{ title: 'existing', status: 'in_progress' }]);
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'call_1',
+      args: {},
+      signal,
+    });
+
+    expect(result).toMatchObject({ isError: false });
+    expect(result.output).toContain('Current todo list');
+    expect(result.output).toContain('[in_progress] existing');
+    expect(getTodos()).toEqual([{ title: 'existing', status: 'in_progress' }]);
+  });
+
+  it('write mode replaces the list and defensively copies todos into the store', async () => {
+    const { tool, getTodos } = makeTool();
+    const todos: TodoItem[] = [
+      { title: 'first', status: 'pending' },
+      { title: 'second', status: 'in_progress' },
+    ];
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'call_1',
+      args: { todos },
+      signal,
+    });
+    todos[0] = { title: 'leaked', status: 'done' };
+
+    expect(result).toMatchObject({ isError: false });
+    expect(result.output).toContain('Todo list updated');
+    expect(result.output).toContain('[pending] first');
+    expect(result.output).toContain('[in_progress] second');
+    expect(getTodos()).toEqual([
+      { title: 'first', status: 'pending' },
+      { title: 'second', status: 'in_progress' },
+    ]);
+  });
+
+  it('renders a done todo with a marker matching the status enum value', async () => {
+    const { tool } = makeTool([{ title: 'shipped', status: 'done' }]);
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'call_1',
+      args: {},
+      signal,
+    });
+
+    expect(result).toMatchObject({ isError: false });
+    expect(result.output).toContain('[done] shipped');
+    expect(result.output).not.toContain('[completed]');
+  });
+
+  it('clear mode empties the list', async () => {
+    const { tool, getTodos } = makeTool([{ title: 'x', status: 'pending' }]);
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'call_1',
+      args: { todos: [] },
+      signal,
+    });
+
+    expect(result).toMatchObject({ isError: false, output: 'Todo list cleared.' });
+    expect(getTodos()).toEqual([]);
+  });
+
+  it('resolveExecution description reflects the mode', () => {
+    const { tool } = makeTool();
+    const readExecution = tool.resolveExecution({});
+    const clearExecution = tool.resolveExecution({ todos: [] });
+    const updateExecution = tool.resolveExecution({ todos: [{ title: 'x', status: 'pending' }] });
+
+    expect(readExecution.isError).toBeFalsy();
+    expect(clearExecution.isError).toBeFalsy();
+    expect(updateExecution.isError).toBeFalsy();
+    if (
+      readExecution.isError === true ||
+      clearExecution.isError === true ||
+      updateExecution.isError === true
+    ) {
+      throw new TypeError('expected runnable executions');
+    }
+    expect(readExecution.description).toBe('Reading todo list');
+    expect(clearExecution.description).toBe('Clearing todo list');
+    expect(updateExecution.description).toBe('Updating todo list');
+  });
+});
diff --git a/packages/agent-core/test/tools/web-search.test.ts b/packages/agent-core/test/tools/web-search.test.ts
new file mode 100644
index 000000000..94a1f4064
--- /dev/null
+++ b/packages/agent-core/test/tools/web-search.test.ts
@@ -0,0 +1,289 @@
+/**
+ * Covers: WebSearchTool.
+ *
+ * Uses a fake WebSearchProvider to test tool behaviour in isolation.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  WebSearchInputSchema,
+  WebSearchTool,
+  type WebSearchProvider,
+} from '../../src/tools/builtin/web/web-search';
+import { MoonshotWebSearchProvider } from '../../src/tools/providers/moonshot-web-search';
+import { toolContentString } from './fixtures/fake-kaos';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+function fakeProvider(
+  results: Awaited<ReturnType<WebSearchProvider['search']>> = [],
+): WebSearchProvider {
+  return { search: vi.fn().mockResolvedValue(results) };
+}
+
+describe('WebSearchTool', () => {
+  it('has name "WebSearch" and a non-empty description', () => {
+    const tool = new WebSearchTool(fakeProvider());
+    expect(tool.name).toBe('WebSearch');
+    expect(tool.description.length).toBeGreaterThan(0);
+  });
+
+  it('parameters are generated from the current input schema', () => {
+    const tool = new WebSearchTool(fakeProvider());
+    expect(WebSearchInputSchema.safeParse({ query: 'test' }).success).toBe(true);
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: {
+        query: { type: 'string' },
+      },
+    });
+  });
+
+  it('limit description guides toward refining the query instead of raising limit', () => {
+    const tool = new WebSearchTool(fakeProvider());
+    const limit = (tool.parameters as { properties: Record<string, { description?: string }> })
+      .properties['limit'];
+    expect(limit?.description).toContain('Typically you do not need to set this value');
+    expect(limit?.description).toContain('more concrete query');
+  });
+
+  it('include_content description warns about token cost at large limits', () => {
+    const tool = new WebSearchTool(fakeProvider());
+    const includeContent = (
+      tool.parameters as { properties: Record<string, { description?: string }> }
+    ).properties['include_content'];
+    expect(includeContent?.description).toContain('consume a large amount of tokens');
+    expect(includeContent?.description).toContain('avoid enabling this when `limit` is set');
+    // Use the TS/JSON boolean literal, not Python's capitalized `True`.
+    expect(includeContent?.description).toContain('set to true');
+    expect(includeContent?.description).not.toContain('True');
+  });
+
+  it('returns formatted results from provider', async () => {
+    const provider = fakeProvider([
+      { title: 'Result 1', url: 'https://example.com/1', snippet: 'Snippet 1' },
+      { title: 'Result 2', url: 'https://example.com/2', snippet: 'Snippet 2', date: '2024-01-01' },
+    ]);
+    const tool = new WebSearchTool(provider);
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c1',
+      args: { query: 'test query' },
+      signal,
+    });
+    expect(result.isError).toBe(false);
+    const content = toolContentString(result);
+    expect(content).toContain('Result 1');
+    expect(content).toContain('https://example.com/1');
+    expect(content).toContain('Result 2');
+    expect(content).toContain('2024-01-01');
+  });
+
+  it('renders the snippet under a "Snippet:" label consistent with the schema term', async () => {
+    const provider = fakeProvider([
+      { title: 'Result 1', url: 'https://example.com/1', snippet: 'Snippet 1' },
+    ]);
+    const tool = new WebSearchTool(provider);
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c-snippet',
+      args: { query: 'test query' },
+      signal,
+    });
+    const content = toolContentString(result);
+    expect(content).toContain('Snippet: Snippet 1');
+    expect(content).not.toContain('Summary:');
+  });
+
+  it('describes every returned field (date and content) in the tool description', () => {
+    const tool = new WebSearchTool(fakeProvider());
+    const description = tool.description.toLowerCase();
+    expect(description).toContain('title');
+    expect(description).toContain('url');
+    expect(description).toContain('snippet');
+    expect(description).toContain('date');
+    expect(description).toContain('content');
+  });
+
+  it('does not promise page content unconditionally for every result', () => {
+    // Page content is rendered only when the provider returns it (`include_content`
+    // is merely forwarded to the provider). The description must not claim it is
+    // appended for every result, or it repeats the overpromise this PR fixes.
+    const tool = new WebSearchTool(fakeProvider());
+    const description = tool.description.toLowerCase();
+    expect(description).not.toContain('for each result');
+  });
+
+  it('returns no results message when provider returns empty', async () => {
+    const tool = new WebSearchTool(fakeProvider([]));
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c2',
+      args: { query: 'nothing' },
+      signal,
+    });
+    expect(result.isError).toBe(false);
+    expect(toolContentString(result)).toContain('No search results found');
+  });
+
+  it('truncates oversized result content through the shared builder', async () => {
+    const tool = new WebSearchTool(
+      fakeProvider([
+        {
+          title: 'Large result',
+          url: 'https://example.com/large',
+          snippet: 'Large snippet',
+          content: 'x'.repeat(60_000),
+        },
+      ]),
+    );
+
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c-large',
+      args: { query: 'large', include_content: true },
+      signal,
+    });
+
+    const content = toolContentString(result);
+    expect(result.isError).toBe(false);
+    expect(content).toContain('[...truncated]');
+    expect(content).toContain('Output is truncated');
+    expect(content.length).toBeLessThan(60_000);
+    expect((result as { message?: string }).message).toContain('Output is truncated');
+  });
+
+  it('returns error when provider throws', async () => {
+    const provider: WebSearchProvider = {
+      search: vi.fn().mockRejectedValue(new Error('network error')),
+    };
+    const tool = new WebSearchTool(provider);
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c3',
+      args: { query: 'fail' },
+      signal,
+    });
+    expect(result.isError).toBe(true);
+    expect(toolContentString(result)).toContain('network error');
+  });
+
+  it('classifies authentication failures', async () => {
+    const provider: WebSearchProvider = {
+      search: vi
+        .fn()
+        .mockRejectedValue(
+          new Error('Moonshot search request failed: HTTP 401 (auth/unauthorized).'),
+        ),
+    };
+    const tool = new WebSearchTool(provider);
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c-auth',
+      args: { query: 'fail' },
+      signal,
+    });
+    expect(result.isError).toBe(true);
+    const content = toolContentString(result);
+    // Assert the classification prefix, not text that already appears in the raw error.
+    expect(content).toContain('Search failed (authentication):');
+    // The original error text is preserved alongside the prefix.
+    expect(content).toContain('HTTP 401');
+  });
+
+  it('classifies timeout failures', async () => {
+    const err = new Error('request timed out');
+    err.name = 'TimeoutError';
+    const provider: WebSearchProvider = { search: vi.fn().mockRejectedValue(err) };
+    const tool = new WebSearchTool(provider);
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c-timeout',
+      args: { query: 'fail' },
+      signal,
+    });
+    expect(result.isError).toBe(true);
+    const content = toolContentString(result);
+    // Assert the classification prefix, which does not overlap with the raw error text.
+    expect(content).toContain('Search timed out:');
+    // The original error text is preserved alongside the prefix.
+    expect(content).toContain('request timed out');
+  });
+
+  it('classifies aborted requests', async () => {
+    const err = new Error('The operation was aborted');
+    err.name = 'AbortError';
+    const provider: WebSearchProvider = { search: vi.fn().mockRejectedValue(err) };
+    const tool = new WebSearchTool(provider);
+    const result = await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c-abort',
+      args: { query: 'fail' },
+      signal,
+    });
+    expect(result.isError).toBe(true);
+    const content = toolContentString(result);
+    // Assert the classification prefix, not text that already appears in the raw error.
+    expect(content).toContain('Search cancelled:');
+    // The original error text is preserved alongside the prefix.
+    expect(content).toContain('The operation was aborted');
+  });
+
+  it('passes limit and includeContent to provider', async () => {
+    const provider = fakeProvider([]);
+    const tool = new WebSearchTool(provider);
+    await executeTool(tool, {
+      turnId: 't1',
+      toolCallId: 'c4',
+      args: { query: 'test', limit: 10, include_content: true },
+      signal,
+    });
+    expect(provider.search).toHaveBeenCalledWith('test', {
+      limit: 10,
+      includeContent: true,
+      toolCallId: 'c4',
+    });
+  });
+
+  it('resolveExecution description truncates long queries', () => {
+    const tool = new WebSearchTool(fakeProvider());
+    const execution = tool.resolveExecution({ query: 'a'.repeat(60) });
+    expect(execution.isError).toBeFalsy();
+    if (execution.isError === true) throw new Error('expected runnable execution');
+    const desc = execution.description;
+    const text = desc ?? '';
+    expect(text.length).toBeLessThanOrEqual(55);
+    expect(text).toContain('…');
+  });
+
+  it('description names internet search as the tool surface', () => {
+    const tool = new WebSearchTool(fakeProvider());
+    expect(tool.description.toLowerCase()).toMatch(/internet|search the web/);
+    expect(tool.description.toLowerCase()).toContain('search');
+  });
+});
+
+describe('MoonshotWebSearchProvider', () => {
+  it('does not force-refresh request auth after a 401 response', async () => {
+    const getAccessToken = vi.fn().mockResolvedValue('fresh-token');
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(new Response('unauthorized', { status: 401 }));
+    const provider = new MoonshotWebSearchProvider({
+      tokenProvider: { getAccessToken },
+      baseUrl: 'https://search.example/v1',
+      fetchImpl,
+    });
+
+    await expect(provider.search('query')).rejects.toThrow(/HTTP 401/);
+
+    expect(getAccessToken).toHaveBeenCalledTimes(1);
+    expect(getAccessToken).toHaveBeenCalledWith();
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    expect(fetchImpl.mock.calls[0]?.[1]?.headers).toMatchObject({
+      Authorization: 'Bearer fresh-token',
+    });
+  });
+});
diff --git a/packages/agent-core/test/tools/write.test.ts b/packages/agent-core/test/tools/write.test.ts
new file mode 100644
index 000000000..536b2060a
--- /dev/null
+++ b/packages/agent-core/test/tools/write.test.ts
@@ -0,0 +1,328 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { type WriteInput, WriteInputSchema, WriteTool } from '../../src/tools/builtin/file/write';
+import { createFakeKaos, PERMISSIVE_WORKSPACE, toolContentString } from './fixtures/fake-kaos';
+import { executeTool } from './fixtures/execute-tool';
+
+const signal = new AbortController().signal;
+
+function context(args: WriteInput) {
+  return { turnId: '0', toolCallId: 'call_write', args, signal };
+}
+
+/** stat() result for an existing directory (S_IFDIR mode bits). */
+const DIR_STAT = vi.fn().mockResolvedValue({ stMode: 0o040755 });
+
+describe('WriteTool', () => {
+  it('exposes current metadata and schema', () => {
+    const tool = new WriteTool(createFakeKaos(), PERMISSIVE_WORKSPACE);
+
+    expect(tool.name).toBe('Write');
+    expect(tool.description).toContain('exactly as provided');
+    expect(tool.description).toContain('append adds content to the end without adding a newline');
+    expect(tool.description).toContain('does not preserve or infer the previous line-ending style');
+    expect(tool.parameters).toMatchObject({
+      type: 'object',
+      properties: {
+        content: {
+          type: 'string',
+          description: expect.stringContaining('Raw full file content'),
+        },
+        mode: {
+          enum: ['overwrite', 'append'],
+          description: expect.stringContaining('Defaults to overwrite'),
+        },
+      },
+    });
+    expect(WriteInputSchema.safeParse({ path: '/tmp/out.txt', content: 'hello' }).success).toBe(
+      true,
+    );
+    expect(
+      WriteInputSchema.safeParse({ path: '/tmp/out.txt', content: 'hello', mode: 'append' })
+        .success,
+    ).toBe(true);
+    expect(
+      WriteInputSchema.safeParse({ path: '/tmp/out.txt', content: 'hello', mode: 'bad' }).success,
+    ).toBe(false);
+    expect(WriteInputSchema.safeParse({ path: '/tmp/out.txt' }).success).toBe(false);
+  });
+
+  it('describes the working-directory rule for the path parameter', () => {
+    const tool = new WriteTool(createFakeKaos(), PERMISSIVE_WORKSPACE);
+    const params = tool.parameters as {
+      properties: { path: { description: string } };
+    };
+
+    expect(params.properties.path.description).toContain('working directory');
+    expect(params.properties.path.description).toMatch(/relative/i);
+    expect(params.properties.path.description).toMatch(/absolute/i);
+  });
+
+  it('guides batching large content across multiple write calls', () => {
+    const tool = new WriteTool(createFakeKaos(), PERMISSIVE_WORKSPACE);
+
+    // The guidance must mention splitting large content across multiple calls,
+    // and spell out the first-overwrite-then-append ordering.
+    expect(tool.description).toMatch(/large/i);
+    expect(tool.description).toMatch(/split[^.]*multiple calls/i);
+    expect(tool.description).toMatch(/first[^.]*overwrite[^.]*then[^.]*append/i);
+  });
+
+  it('writes content through kaos and reports bytes written', async () => {
+    const writeText = vi.fn().mockResolvedValue(5);
+    const tool = new WriteTool(createFakeKaos({ writeText, stat: DIR_STAT }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool, context({ path: '/tmp/new.txt', content: 'hello' }));
+
+    expect(writeText).toHaveBeenCalledWith('/tmp/new.txt', 'hello');
+    expect(result.output).toContain('Wrote 5 bytes');
+  });
+
+  it('expands leading tilde paths using the kaos home directory', async () => {
+    const writeText = vi.fn().mockResolvedValue(5);
+    const tool = new WriteTool(createFakeKaos({ writeText, stat: DIR_STAT }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool, context({ path: '~/notes/today.txt', content: 'hello' }));
+
+    expect(writeText).toHaveBeenCalledWith('/home/test/notes/today.txt', 'hello');
+    expect(result.output).toContain('Wrote 5 bytes');
+  });
+
+  it('appends content through kaos and reports appended bytes', async () => {
+    const writeText = vi.fn().mockResolvedValue(6);
+    const tool = new WriteTool(createFakeKaos({ writeText, stat: DIR_STAT }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/existing.txt', content: '\nhello', mode: 'append' }),
+    );
+
+    expect(writeText).toHaveBeenCalledWith('/tmp/existing.txt', '\nhello', { mode: 'a' });
+    expect(result.output).toContain('Appended 6 bytes');
+  });
+
+  it('reports the real UTF-8 byte count for non-ASCII content', async () => {
+    // Six Japanese characters: each encodes to 3 UTF-8 bytes → 18 bytes total,
+    // even though the JS string length is 6. The reported count must reflect
+    // the bytes that land on disk, not the code-unit count.
+    const content = 'こんにちは。';
+    const expectedBytes = Buffer.byteLength(content, 'utf8');
+    expect(expectedBytes).toBe(18);
+
+    // writeText's contract returns a character count; the tool must not rely
+    // on it for the byte figure.
+    const writeText = vi.fn().mockResolvedValue(content.length);
+    const tool = new WriteTool(createFakeKaos({ writeText, stat: DIR_STAT }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool, context({ path: '/tmp/jp.txt', content }));
+
+    expect(result.output).toContain('Wrote 18 bytes');
+    expect(result.output).not.toContain('Wrote 6 bytes');
+  });
+
+  it('reports the real UTF-8 byte count for content with surrogate-pair emoji', async () => {
+    // 'hi😀': the emoji is a single code point encoded as a UTF-16 surrogate
+    // pair, so JS string length is 4 (2 for 'hi' + 2 code units), but the
+    // UTF-8 encoding is 6 bytes (2 for 'hi' + 4 for the emoji). The reported
+    // count must reflect the bytes on disk, not the code-unit count — this
+    // is the sharpest edge of the byte-counting bug.
+    const content = 'hi😀';
+    expect(content.length).toBe(4);
+    const expectedBytes = Buffer.byteLength(content, 'utf8');
+    expect(expectedBytes).toBe(6);
+
+    // writeText's contract returns a character count; the tool must not rely
+    // on it for the byte figure.
+    const writeText = vi.fn().mockResolvedValue(content.length);
+    const tool = new WriteTool(createFakeKaos({ writeText, stat: DIR_STAT }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool, context({ path: '/tmp/emoji.txt', content }));
+
+    expect(result.output).toContain('Wrote 6 bytes');
+    expect(result.output).not.toContain('Wrote 4 bytes');
+  });
+
+  it('reports the real UTF-8 byte count for non-ASCII append content', async () => {
+    const content = 'café';
+    const expectedBytes = Buffer.byteLength(content, 'utf8');
+    expect(expectedBytes).toBe(5);
+
+    const writeText = vi.fn().mockResolvedValue(content.length);
+    const tool = new WriteTool(createFakeKaos({ writeText, stat: DIR_STAT }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/menu.txt', content, mode: 'append' }),
+    );
+
+    expect(result.output).toContain('Appended 5 bytes');
+  });
+
+  it('reports a friendly error when the parent directory does not exist', async () => {
+    const enoent = Object.assign(new Error('ENOENT: no such file or directory'), {
+      code: 'ENOENT',
+    });
+    const stat = vi.fn().mockRejectedValue(enoent);
+    const writeText = vi.fn().mockResolvedValue(4);
+    const tool = new WriteTool(createFakeKaos({ stat, writeText }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/missing-dir/file.txt', content: 'data' }),
+    );
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('/tmp/missing-dir');
+    expect(result.output).toMatch(/parent directory/i);
+    expect(writeText).not.toHaveBeenCalled();
+  });
+
+  it('rejects writing when the parent path is not a directory', async () => {
+    // A regular file (S_IFREG) standing where a directory is expected.
+    const stat = vi.fn().mockResolvedValue({ stMode: 0o100644 });
+    const writeText = vi.fn().mockResolvedValue(4);
+    const tool = new WriteTool(createFakeKaos({ stat, writeText }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/a-file/child.txt', content: 'data' }),
+    );
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toMatch(/not a directory/i);
+    expect(writeText).not.toHaveBeenCalled();
+  });
+
+  it('writes when the parent directory exists', async () => {
+    const stat = vi.fn().mockResolvedValue({ stMode: 0o040755 });
+    const writeText = vi.fn().mockResolvedValue(4);
+    const tool = new WriteTool(createFakeKaos({ stat, writeText }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool, context({ path: '/tmp/exists/file.txt', content: 'data' }));
+
+    expect(result.isError).toBeUndefined();
+    expect(writeText).toHaveBeenCalledWith('/tmp/exists/file.txt', 'data');
+  });
+
+  it('surfaces kaos write failures as tool errors', async () => {
+    const tool = new WriteTool(
+      createFakeKaos({
+        stat: DIR_STAT,
+        writeText: vi.fn().mockRejectedValue(new Error('disk full')),
+      }),
+      PERMISSIVE_WORKSPACE,
+    );
+
+    const result = await executeTool(tool, context({ path: '/some/file.txt', content: 'data' }));
+
+    expect(result).toMatchObject({ isError: true, output: 'disk full' });
+  });
+
+  it('allows explicit absolute writes outside the workspace', async () => {
+    const writeText = vi.fn().mockResolvedValue(1);
+    const tool = new WriteTool(createFakeKaos({ writeText, stat: DIR_STAT }), {
+      workspaceDir: '/workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool, context({ path: '/tmp/pwned.txt', content: 'x' }));
+
+    expect(result.isError).toBeUndefined();
+    expect(writeText).toHaveBeenCalledWith('/tmp/pwned.txt', 'x');
+  });
+
+  it('rejects relative traversal writes before kaos I/O', async () => {
+    const writeText = vi.fn().mockResolvedValue(1);
+    const tool = new WriteTool(createFakeKaos({ writeText }), {
+      workspaceDir: '/workspace/project',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool, context({ path: '../outside.txt', content: 'x' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('absolute path');
+    expect(writeText).not.toHaveBeenCalled();
+  });
+
+  it('blocks sensitive file writes', async () => {
+    const writeText = vi.fn().mockResolvedValue(1);
+    const tool = new WriteTool(createFakeKaos({ writeText }), {
+      workspaceDir: '/workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool, context({ path: '/workspace/id_rsa', content: 'key' }));
+
+    expect(result).toMatchObject({ isError: true });
+    expect(result.output).toContain('sensitive-file pattern');
+    expect(writeText).not.toHaveBeenCalled();
+  });
+
+  it('round-trips unicode content (CJK + emoji + accented Latin) through kaos.writeText', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new WriteTool(createFakeKaos({ writeText }), PERMISSIVE_WORKSPACE);
+    const content = 'Hello 世界 🌍\nUnicode: café, naïve, résumé';
+
+    const result = await executeTool(tool,context({ path: '/tmp/unicode.txt', content }));
+
+    expect(result.isError).toBeFalsy();
+    expect(writeText).toHaveBeenCalledWith('/tmp/unicode.txt', content);
+  });
+
+  it('writes empty content as a zero-byte file via kaos.writeText("")', async () => {
+    const writeText = vi.fn().mockResolvedValue(0);
+    const tool = new WriteTool(createFakeKaos({ writeText }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool,context({ path: '/tmp/empty.txt', content: '' }));
+
+    expect(result.isError).toBeFalsy();
+    expect(writeText).toHaveBeenCalledWith('/tmp/empty.txt', '');
+  });
+
+  it('reports a parent-directory-does-not-exist message when the directory is missing', async () => {
+    // py surfaces `parent directory does not exist` so the model can `mkdir`
+    // before retrying. TS currently forwards whatever the host throws.
+    const writeText = vi
+      .fn()
+      .mockRejectedValue(
+        Object.assign(new Error('ENOENT: no such file or directory'), { code: 'ENOENT' }),
+      );
+    const tool = new WriteTool(createFakeKaos({ writeText }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/missing-dir/file.txt', content: 'data' }),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.output).toContain('parent directory does not exist');
+  });
+
+  it('appending to a nonexistent file creates it with just the appended bytes', async () => {
+    // py spec: append mode on a missing path returns success and creates
+    // the file. Lock down the create-on-append contract.
+    const writeText = vi.fn().mockResolvedValue(11);
+    const tool = new WriteTool(createFakeKaos({ writeText }), PERMISSIVE_WORKSPACE);
+
+    const result = await executeTool(tool,
+      context({ path: '/tmp/new-append.txt', content: 'New content', mode: 'append' }),
+    );
+
+    expect(result.isError).toBeFalsy();
+    expect(toolContentString(result).toLowerCase()).toContain('appended');
+    expect(writeText).toHaveBeenCalledWith('/tmp/new-append.txt', 'New content', { mode: 'a' });
+  });
+
+  it('allows absolute writes to a sibling dir that merely shares the work-dir prefix', async () => {
+    // Path policy must distinguish "shares a prefix with workspaceDir" from
+    // "is inside workspaceDir". /workspace-sneaky/* is outside /workspace.
+    const writeText = vi.fn().mockResolvedValue(1);
+    const tool = new WriteTool(createFakeKaos({ writeText }), {
+      workspaceDir: '/workspace',
+      additionalDirs: [],
+    });
+
+    const result = await executeTool(tool,
+      context({ path: '/workspace-sneaky/file.txt', content: 'content' }),
+    );
+
+    expect(result.isError).toBeFalsy();
+    expect(writeText).toHaveBeenCalledWith('/workspace-sneaky/file.txt', 'content');
+  });
+});
diff --git a/packages/agent-core/test/utils/completion-budget.test.ts b/packages/agent-core/test/utils/completion-budget.test.ts
new file mode 100644
index 000000000..fe84a3b4c
--- /dev/null
+++ b/packages/agent-core/test/utils/completion-budget.test.ts
@@ -0,0 +1,339 @@
+import type {
+  ChatProvider,
+  Message,
+  ModelCapability,
+  Tool,
+} from '@moonshot-ai/kosong';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  applyCompletionBudget,
+  computeCompletionBudgetCap,
+  resolveCompletionBudget,
+} from '../../src/utils/completion-budget';
+
+function makeMessages(approxAsciiTokens: number): Message[] {
+  // estimateTokens treats ASCII as ~4 chars/token. Pad with a single
+  // string so the message lands near the requested count.
+  const charCount = approxAsciiTokens * 4;
+  return [
+    {
+      role: 'user',
+      content: [{ type: 'text', text: 'a'.repeat(charCount) }],
+      toolCalls: [],
+    },
+  ];
+}
+
+function makeCapability(maxContextTokens: number): ModelCapability {
+  return {
+    image_in: false,
+    video_in: false,
+    audio_in: false,
+    thinking: false,
+    tool_use: true,
+    max_context_tokens: maxContextTokens,
+  };
+}
+
+function makeTool(name: string, asciiCharsInDescription: number): Tool {
+  return {
+    name,
+    description: 'd'.repeat(asciiCharsInDescription),
+    parameters: { type: 'object', properties: {} },
+  };
+}
+
+describe('computeCompletionBudgetCap', () => {
+  it('returns desired when context size is unknown', () => {
+    const cap = computeCompletionBudgetCap({
+      budget: { desired: 8192 },
+      capability: undefined,
+      messages: makeMessages(100),
+    });
+    expect(cap).toBe(8192);
+  });
+
+  it('preserves a small desired when context size is unknown — no artificial floor', () => {
+    const cap = computeCompletionBudgetCap({
+      budget: { desired: 10 },
+      capability: makeCapability(0),
+      messages: makeMessages(100),
+    });
+    expect(cap).toBe(10);
+  });
+
+  it('floors at 1 when desired is zero or negative', () => {
+    expect(
+      computeCompletionBudgetCap({
+        budget: { desired: 0 },
+        capability: undefined,
+        messages: makeMessages(10),
+      }),
+    ).toBe(1);
+    expect(
+      computeCompletionBudgetCap({
+        budget: { desired: -100 },
+        capability: undefined,
+        messages: makeMessages(10),
+      }),
+    ).toBe(1);
+  });
+
+  it('clamps desired down to the remaining context window', () => {
+    // max_context_tokens 10000, input ~ 1000, safetyMargin 1024 → remaining ~ 7976
+    const cap = computeCompletionBudgetCap({
+      budget: { desired: 32000 },
+      capability: makeCapability(10000),
+      messages: makeMessages(1000),
+    });
+    expect(cap).toBeLessThanOrEqual(10000 - 1000 - 1024);
+    expect(cap).toBeGreaterThan(7000);
+  });
+
+  it('returns 1 when input already exceeds context minus margin', () => {
+    const cap = computeCompletionBudgetCap({
+      budget: { desired: 32000 },
+      capability: makeCapability(10000),
+      messages: makeMessages(11000),
+    });
+    expect(cap).toBe(1);
+  });
+
+  it('never exceeds remaining context, even when remaining is below the historical floor', () => {
+    // input ~ 8900, safetyMargin 1024 → remaining ~ 75 (positive but below 256).
+    // The cap MUST stay <= remaining so the request does not overflow.
+    const maxCtx = 10000;
+    const cap = computeCompletionBudgetCap({
+      budget: { desired: 32000 },
+      capability: makeCapability(maxCtx),
+      messages: makeMessages(8900),
+    });
+    expect(cap).toBeGreaterThanOrEqual(1);
+    expect(cap).toBeLessThanOrEqual(maxCtx - 8900 - 1024);
+  });
+
+  it('respects custom safetyMargin', () => {
+    const cap = computeCompletionBudgetCap({
+      budget: { desired: 32000, safetyMargin: 4096 },
+      capability: makeCapability(20000),
+      messages: makeMessages(1000),
+    });
+    // remaining = 20000 - (1000 + 1 for 'user' role) - 4096 = 14903
+    expect(cap).toBe(14903);
+  });
+
+  it('keeps desired when smaller than remaining', () => {
+    const cap = computeCompletionBudgetCap({
+      budget: { desired: 1024 },
+      capability: makeCapability(100000),
+      messages: makeMessages(1000),
+    });
+    expect(cap).toBe(1024);
+  });
+
+  it('counts the system prompt as input', () => {
+    const maxCtx = 10000;
+    const safetyMargin = 1024;
+    const systemPrompt = 'a'.repeat(2000 * 4); // ~2000 tokens
+    const cap = computeCompletionBudgetCap({
+      budget: { desired: 32000, safetyMargin },
+      capability: makeCapability(maxCtx),
+      messages: makeMessages(1000),
+      systemPrompt,
+    });
+    // remaining = 10000 - (1001 + 2000) - 1024 = 5975
+    expect(cap).toBeLessThanOrEqual(maxCtx - 1001 - 2000 - safetyMargin);
+    expect(cap).toBeGreaterThan(5500);
+  });
+
+  it('counts tool schemas as input', () => {
+    const maxCtx = 10000;
+    const safetyMargin = 1024;
+    const tools: Tool[] = [
+      makeTool('tool_a', 4000), // ~1000 tokens of description per tool
+      makeTool('tool_b', 4000),
+    ];
+    const capWithTools = computeCompletionBudgetCap({
+      budget: { desired: 32000, safetyMargin },
+      capability: makeCapability(maxCtx),
+      messages: makeMessages(1000),
+      tools,
+    });
+    const capWithoutTools = computeCompletionBudgetCap({
+      budget: { desired: 32000, safetyMargin },
+      capability: makeCapability(maxCtx),
+      messages: makeMessages(1000),
+    });
+    expect(capWithTools).toBeLessThan(capWithoutTools);
+    // Tool descriptions add ~2000 tokens, so cap should drop by roughly that.
+    expect(capWithoutTools - capWithTools).toBeGreaterThan(1500);
+  });
+});
+
+describe('applyCompletionBudget', () => {
+  let withMaxCompletionTokens: ReturnType<typeof vi.fn>;
+  let original: ChatProvider;
+
+  beforeEach(() => {
+    const cloneFactory = (n: number): ChatProvider => {
+      const clone = { ...original, _maxTokensApplied: n };
+      return clone as unknown as ChatProvider;
+    };
+    withMaxCompletionTokens = vi.fn(cloneFactory);
+    original = {
+      name: 'mock',
+      modelName: 'mock-model',
+      thinkingEffort: null,
+      generate: vi.fn() as unknown as ChatProvider['generate'],
+      withThinking: vi.fn() as unknown as ChatProvider['withThinking'],
+      withMaxCompletionTokens: withMaxCompletionTokens as unknown as (
+        n: number,
+      ) => ChatProvider,
+    };
+  });
+
+  it('returns the original provider when no budget is configured', () => {
+    const result = applyCompletionBudget({
+      provider: original,
+      budget: undefined,
+      capability: makeCapability(10000),
+      messages: makeMessages(100),
+    });
+    expect(result).toBe(original);
+    expect(withMaxCompletionTokens).not.toHaveBeenCalled();
+  });
+
+  it('returns the original provider when withMaxCompletionTokens is not implemented', () => {
+    const { withMaxCompletionTokens: _drop, ...rest } = original;
+    void _drop;
+    const opaque = rest as unknown as ChatProvider;
+    const result = applyCompletionBudget({
+      provider: opaque,
+      budget: { desired: 8192 },
+      capability: makeCapability(10000),
+      messages: makeMessages(100),
+    });
+    expect(result).toBe(opaque);
+  });
+
+  it('clones the provider with the clamped cap when budget is configured', () => {
+    const result = applyCompletionBudget({
+      provider: original,
+      budget: { desired: 32000 },
+      capability: makeCapability(10000),
+      messages: makeMessages(1000),
+    });
+    expect(withMaxCompletionTokens).toHaveBeenCalledOnce();
+    const cap = withMaxCompletionTokens.mock.calls[0]?.[0] as number;
+    expect(cap).toBeLessThanOrEqual(10000 - 1000 - 1024);
+    expect(cap).toBeGreaterThan(7000);
+    expect(result).not.toBe(original);
+  });
+
+  it('forwards systemPrompt and tools to the cap computation', () => {
+    const tools: Tool[] = [makeTool('tool_a', 4000)];
+    const systemPrompt = 'a'.repeat(4000); // ~1000 tokens
+    applyCompletionBudget({
+      provider: original,
+      budget: { desired: 32000 },
+      capability: makeCapability(10000),
+      messages: makeMessages(1000),
+      systemPrompt,
+      tools,
+    });
+    const capWithExtras = withMaxCompletionTokens.mock.calls[0]?.[0] as number;
+    withMaxCompletionTokens.mockClear();
+    applyCompletionBudget({
+      provider: original,
+      budget: { desired: 32000 },
+      capability: makeCapability(10000),
+      messages: makeMessages(1000),
+    });
+    const capBare = withMaxCompletionTokens.mock.calls[0]?.[0] as number;
+    expect(capWithExtras).toBeLessThan(capBare);
+  });
+});
+
+describe('resolveCompletionBudget', () => {
+  it('reads KIMI_MODEL_MAX_COMPLETION_TOKENS first', () => {
+    const budget = resolveCompletionBudget({
+      reservedContextSize: 1000,
+      env: {
+        KIMI_MODEL_MAX_COMPLETION_TOKENS: '4096',
+        KIMI_MODEL_MAX_TOKENS: '2048',
+      },
+    });
+    expect(budget?.desired).toBe(4096);
+  });
+
+  it('falls back to legacy KIMI_MODEL_MAX_TOKENS when the new var is unset', () => {
+    const budget = resolveCompletionBudget({
+      reservedContextSize: 1000,
+      env: { KIMI_MODEL_MAX_TOKENS: '2048' },
+    });
+    expect(budget?.desired).toBe(2048);
+  });
+
+  it('uses reservedContextSize when no env var is set', () => {
+    const budget = resolveCompletionBudget({
+      reservedContextSize: 12345,
+      env: {},
+    });
+    expect(budget?.desired).toBe(12345);
+  });
+
+  it('falls back to the historical default 32000 when nothing is configured', () => {
+    const budget = resolveCompletionBudget({ env: {} });
+    expect(budget?.desired).toBe(32000);
+  });
+
+  it('ignores reservedContextSize when it is 0', () => {
+    const budget = resolveCompletionBudget({
+      reservedContextSize: 0,
+      env: {},
+    });
+    expect(budget?.desired).toBe(32000);
+  });
+
+  it('treats non-positive KIMI_MODEL_MAX_COMPLETION_TOKENS as an opt-out', () => {
+    expect(
+      resolveCompletionBudget({
+        reservedContextSize: 1000,
+        env: { KIMI_MODEL_MAX_COMPLETION_TOKENS: '0' },
+      }),
+    ).toBeUndefined();
+    expect(
+      resolveCompletionBudget({
+        reservedContextSize: 1000,
+        env: { KIMI_MODEL_MAX_COMPLETION_TOKENS: '-1' },
+      }),
+    ).toBeUndefined();
+  });
+
+  it('treats non-positive legacy KIMI_MODEL_MAX_TOKENS as an opt-out when the new var is unset', () => {
+    expect(
+      resolveCompletionBudget({
+        reservedContextSize: 1000,
+        env: { KIMI_MODEL_MAX_TOKENS: '-1' },
+      }),
+    ).toBeUndefined();
+  });
+
+  it('lets the new var override a legacy disable signal', () => {
+    const budget = resolveCompletionBudget({
+      env: {
+        KIMI_MODEL_MAX_COMPLETION_TOKENS: '4096',
+        KIMI_MODEL_MAX_TOKENS: '-1',
+      },
+    });
+    expect(budget?.desired).toBe(4096);
+  });
+
+  it('falls back to defaults when the env var is non-numeric garbage', () => {
+    const budget = resolveCompletionBudget({
+      env: { KIMI_MODEL_MAX_COMPLETION_TOKENS: 'not-a-number' },
+    });
+    expect(budget?.desired).toBe(32000);
+  });
+});
diff --git a/packages/agent-core/test/utils/environment.test.ts b/packages/agent-core/test/utils/environment.test.ts
new file mode 100644
index 000000000..145df37a2
--- /dev/null
+++ b/packages/agent-core/test/utils/environment.test.ts
@@ -0,0 +1,234 @@
+/**
+ * Environment detection.
+ *
+ * Pins the cross-platform shape of `detectEnvironment()`:
+ *
+ *   - macOS / Linux / Windows / unknown → `osKind`
+ *   - POSIX path probing prefers /bin/bash, falls back to /usr/bin/bash,
+ *     /usr/local/bin/bash, then /bin/sh (with shellName 'sh').
+ *   - Windows resolves Git Bash via `KIMI_SHELL_PATH`, `git.exe` on PATH,
+ *     or well-known install locations; throws `shell.git_bash_not_found`
+ *     if none are present.
+ *   - `osArch` / `osVersion` are populated from the Node OS APIs.
+ *
+ * All tests expect `detectEnvironment()` to be a pure function of
+ * injected platform probes (no ambient state) so the same suite runs
+ * identically on macOS/Linux/Windows CI runners.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { ErrorCodes, KimiError } from '../../src/errors';
+import {
+  detectEnvironment,
+  type Environment,
+  type OsKind,
+  type ShellName,
+} from '../../src/utils/environment';
+
+interface StubOpts {
+  readonly platform: NodeJS.Platform;
+  readonly arch?: string;
+  readonly release?: string;
+  readonly env?: Record<string, string | undefined>;
+  readonly existingPaths?: readonly string[];
+  readonly executables?: Readonly<Record<string, string>>;
+}
+
+/** Build a stub deps bag mimicking Node's `os` + `process` surface. */
+function stubDeps(opts: StubOpts): Parameters<typeof detectEnvironment>[0] {
+  const existing = new Set(opts.existingPaths ?? []);
+  const executables = opts.executables ?? {};
+  return {
+    platform: opts.platform,
+    arch: opts.arch ?? 'x86_64',
+    release: opts.release ?? '1.2.3',
+    env: opts.env ?? {},
+    isFile: async (path: string) => existing.has(path),
+    findExecutable: async (name: string) => executables[name],
+  };
+}
+
+describe('detectEnvironment', () => {
+  it('reports osKind "macOS" on darwin', async () => {
+    const env: Environment = await detectEnvironment(
+      stubDeps({
+        platform: 'darwin',
+        arch: 'arm64',
+        release: '23.4.0',
+        existingPaths: ['/bin/bash'],
+      }),
+    );
+    expect(env.osKind satisfies OsKind).toBe('macOS');
+    expect(env.osArch).toBe('arm64');
+    expect(env.osVersion).toBe('23.4.0');
+  });
+
+  it('reports osKind "Linux" on linux', async () => {
+    const env = await detectEnvironment(
+      stubDeps({ platform: 'linux', existingPaths: ['/bin/bash'] }),
+    );
+    expect(env.osKind).toBe('Linux');
+  });
+
+  it('reports osKind "Windows" on win32', async () => {
+    const env = await detectEnvironment(
+      stubDeps({
+        platform: 'win32',
+        existingPaths: ['C:\\Program Files\\Git\\bin\\bash.exe'],
+      }),
+    );
+    expect(env.osKind).toBe('Windows');
+  });
+
+  it('passes through unknown platform string verbatim', async () => {
+    const env = await detectEnvironment(
+      stubDeps({ platform: 'freebsd' as NodeJS.Platform, existingPaths: ['/bin/sh'] }),
+    );
+    // Python `Environment.detect` returns `platform.system()` verbatim
+    // for unknown OS strings; TS mirrors that behaviour.
+    expect(env.osKind).toBe('freebsd');
+  });
+
+  // ── POSIX shell probing ────────────────────────────────────────────
+
+  it('prefers /bin/bash when it exists (shellName=bash)', async () => {
+    const env = await detectEnvironment(
+      stubDeps({
+        platform: 'linux',
+        existingPaths: ['/bin/bash', '/usr/bin/bash', '/usr/local/bin/bash'],
+      }),
+    );
+    expect(env.shellName satisfies ShellName).toBe('bash');
+    expect(env.shellPath).toBe('/bin/bash');
+  });
+
+  it('falls back to /usr/bin/bash when /bin/bash is missing', async () => {
+    const env = await detectEnvironment(
+      stubDeps({
+        platform: 'linux',
+        existingPaths: ['/usr/bin/bash', '/usr/local/bin/bash'],
+      }),
+    );
+    expect(env.shellName).toBe('bash');
+    expect(env.shellPath).toBe('/usr/bin/bash');
+  });
+
+  it('falls back to /usr/local/bin/bash when /bin and /usr/bin are missing', async () => {
+    const env = await detectEnvironment(
+      stubDeps({
+        platform: 'linux',
+        existingPaths: ['/usr/local/bin/bash'],
+      }),
+    );
+    expect(env.shellName).toBe('bash');
+    expect(env.shellPath).toBe('/usr/local/bin/bash');
+  });
+
+  it('falls back to /bin/sh with shellName=sh when no bash is found', async () => {
+    const env = await detectEnvironment(stubDeps({ platform: 'linux', existingPaths: [] }));
+    expect(env.shellName).toBe('sh');
+    expect(env.shellPath).toBe('/bin/sh');
+  });
+
+  // ── Windows Git Bash probing ───────────────────────────────────────
+
+  it('uses KIMI_SHELL_PATH override when set and the file exists', async () => {
+    const env = await detectEnvironment(
+      stubDeps({
+        platform: 'win32',
+        env: { KIMI_SHELL_PATH: 'D:\\custom\\bash.exe' },
+        existingPaths: ['D:\\custom\\bash.exe', 'C:\\Program Files\\Git\\bin\\bash.exe'],
+      }),
+    );
+    expect(env.shellName satisfies ShellName).toBe('bash');
+    expect(env.shellPath).toBe('D:\\custom\\bash.exe');
+  });
+
+  it('infers Git Bash from git.exe on PATH when override is absent', async () => {
+    const env = await detectEnvironment(
+      stubDeps({
+        platform: 'win32',
+        executables: { 'git.exe': 'C:\\Program Files\\Git\\cmd\\git.exe' },
+        existingPaths: ['C:\\Program Files\\Git\\bin\\bash.exe'],
+      }),
+    );
+    expect(env.shellName).toBe('bash');
+    expect(env.shellPath).toBe('C:\\Program Files\\Git\\bin\\bash.exe');
+  });
+
+  it('falls back to the well-known Program Files install location', async () => {
+    const env = await detectEnvironment(
+      stubDeps({
+        platform: 'win32',
+        existingPaths: ['C:\\Program Files\\Git\\bin\\bash.exe'],
+      }),
+    );
+    expect(env.shellPath).toBe('C:\\Program Files\\Git\\bin\\bash.exe');
+  });
+
+  it('falls back to LOCALAPPDATA install when present', async () => {
+    const env = await detectEnvironment(
+      stubDeps({
+        platform: 'win32',
+        env: { LOCALAPPDATA: 'C:\\Users\\me\\AppData\\Local' },
+        existingPaths: ['C:\\Users\\me\\AppData\\Local\\Programs\\Git\\bin\\bash.exe'],
+      }),
+    );
+    expect(env.shellPath).toBe('C:\\Users\\me\\AppData\\Local\\Programs\\Git\\bin\\bash.exe');
+  });
+
+  it('throws KimiError with the shell.git_bash_not_found code when no candidate is found', async () => {
+    const error = await detectEnvironment(
+      stubDeps({
+        platform: 'win32',
+        env: { LOCALAPPDATA: 'C:\\Users\\me\\AppData\\Local' },
+        existingPaths: [],
+      }),
+    ).then(
+      () => {
+        throw new Error('expected throw');
+      },
+      (error: unknown) => error,
+    );
+    expect(error).toBeInstanceOf(KimiError);
+    expect((error as KimiError).code).toBe(ErrorCodes.SHELL_GIT_BASH_NOT_FOUND);
+  });
+
+  it('includes attempted paths in the thrown KimiError message', async () => {
+    const error = await detectEnvironment(
+      stubDeps({
+        platform: 'win32',
+        env: { KIMI_SHELL_PATH: 'D:\\custom\\bash.exe' },
+        existingPaths: [],
+      }),
+    ).then(
+      () => {
+        throw new Error('expected throw');
+      },
+      (error: unknown) => error as KimiError,
+    );
+    expect(error.message).toContain('D:\\custom\\bash.exe');
+    expect(error.message).toContain('C:\\Program Files\\Git\\bin\\bash.exe');
+  });
+
+  // ── arch / version passthrough ─────────────────────────────────────
+
+  it('reports osArch verbatim from the injected probe', async () => {
+    const env = await detectEnvironment(
+      stubDeps({ platform: 'darwin', arch: 'arm64', existingPaths: ['/bin/bash'] }),
+    );
+    expect(env.osArch).toBe('arm64');
+  });
+
+  it('reports osVersion verbatim from the injected probe', async () => {
+    const env = await detectEnvironment(
+      stubDeps({
+        platform: 'linux',
+        release: '6.1.0-test',
+        existingPaths: ['/bin/bash'],
+      }),
+    );
+    expect(env.osVersion).toBe('6.1.0-test');
+  });
+});
diff --git a/packages/agent-core/test/utils/hero-slug.test.ts b/packages/agent-core/test/utils/hero-slug.test.ts
new file mode 100644
index 000000000..ab63cbb05
--- /dev/null
+++ b/packages/agent-core/test/utils/hero-slug.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { HERO_NAMES, generateHeroSlug } from '../../src/utils/hero-slug';
+
+describe('generateHeroSlug', () => {
+  it('returns a slug made of exactly 3 hero names joined by "-"', () => {
+    const slug = generateHeroSlug('ses_0001', new Set());
+    const heroPattern = HERO_NAMES.map((n) => n.replaceAll('-', '\\-')).join('|');
+    const re = new RegExp(`^(${heroPattern})-(${heroPattern})-(${heroPattern})$`);
+    expect(slug).toMatch(re);
+  });
+
+  it('appends the first 8 chars of id when every 3-name combo collides', () => {
+    // "Universal-match" Set: always reports `has() === true` so the
+    // generator exhausts its retry limit and falls back to the suffixed
+    // slug, regardless of RNG output.
+    const universal = new (class extends Set<string> {
+      override has(_v: string): boolean {
+        return true;
+      }
+    })();
+    const slug = generateHeroSlug('sess_abcdefgh_XXXX', universal as unknown as Set<string>);
+    expect(slug).toMatch(/-sess_abc$/);
+  });
+});
diff --git a/packages/agent-core/tsconfig.json b/packages/agent-core/tsconfig.json
new file mode 100644
index 000000000..46f71c10f
--- /dev/null
+++ b/packages/agent-core/tsconfig.json
@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {},
+  "include": ["src", "test"]
+}
diff --git a/packages/agent-core/tsdown.config.ts b/packages/agent-core/tsdown.config.ts
new file mode 100644
index 000000000..67b51cb2d
--- /dev/null
+++ b/packages/agent-core/tsdown.config.ts
@@ -0,0 +1,16 @@
+import { defineConfig } from 'tsdown';
+
+import { rawTextPlugin } from '../../build/raw-text-plugin.mjs';
+
+export default defineConfig({
+  entry: ['./src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  outDir: 'dist',
+  clean: true,
+  plugins: [rawTextPlugin()],
+  deps: {
+    alwaysBundle: ['picomatch'],
+    neverBundle: ['@moonshot-ai/kosong', '@moonshot-ai/kaos'],
+  },
+});
diff --git a/packages/agent-core/vitest.config.ts b/packages/agent-core/vitest.config.ts
new file mode 100644
index 000000000..0fad8a162
--- /dev/null
+++ b/packages/agent-core/vitest.config.ts
@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+
+import { rawTextPlugin } from '../../build/raw-text-plugin.mjs';
+
+export default defineConfig({
+  plugins: [rawTextPlugin()],
+  test: {
+    name: 'kimi-core',
+    include: ['test/**/*.{test,e2e}.ts'],
+  },
+});
diff --git a/packages/kaos/README.md b/packages/kaos/README.md
new file mode 100644
index 000000000..d0c80f0bb
--- /dev/null
+++ b/packages/kaos/README.md
@@ -0,0 +1,11 @@
+# @moonshot-ai/kaos
+
+Execution environment abstraction used by Kimi Code.
+
+Part of the [Kimi Code](https://github.com/MoonshotAI/kimi-code) monorepo.
+
+See the main repository for documentation, issues, and contribution guidelines.
+
+## License
+
+MIT
diff --git a/packages/kaos/package.json b/packages/kaos/package.json
new file mode 100644
index 000000000..934181385
--- /dev/null
+++ b/packages/kaos/package.json
@@ -0,0 +1,56 @@
+{
+  "name": "@moonshot-ai/kaos",
+  "version": "0.1.1",
+  "private": true,
+  "description": "Execution environment abstraction for AI agent applications",
+  "license": "MIT",
+  "author": "Moonshot AI",
+  "homepage": "https://github.com/MoonshotAI/kimi-code/tree/main/packages/kaos#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MoonshotAI/kimi-code.git",
+    "directory": "packages/kaos"
+  },
+  "bugs": {
+    "url": "https://github.com/MoonshotAI/kimi-code/issues"
+  },
+  "keywords": [
+    "kimi",
+    "agent",
+    "execution",
+    "sandbox",
+    "process",
+    "filesystem"
+  ],
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "imports": {
+    "#/*": [
+      "./src/*.ts",
+      "./src/*/index.ts"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./ssh": {
+      "types": "./src/ssh.ts",
+      "default": "./src/ssh.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "ssh2": "^1.17.0"
+  },
+  "devDependencies": {
+    "@types/ssh2": "^1.15.5"
+  }
+}
diff --git a/packages/kaos/src/current.ts b/packages/kaos/src/current.ts
new file mode 100644
index 000000000..8932ca6e7
--- /dev/null
+++ b/packages/kaos/src/current.ts
@@ -0,0 +1,50 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import type { Kaos } from './kaos';
+import { localKaos } from './local';
+
+const kaosStorage = new AsyncLocalStorage<Kaos>();
+
+function getDefaultKaos(): Kaos {
+  return localKaos;
+}
+
+/**
+ * Return the {@link Kaos} instance for the current async context.
+ *
+ * If {@link runWithKaos} has bound an instance for this context it is
+ * returned; otherwise a lazily-created {@link LocalKaos} default is used.
+ */
+export function getCurrentKaos(): Kaos {
+  return kaosStorage.getStore() ?? getDefaultKaos();
+}
+
+export function runWithKaos<T>(kaos: Kaos, fn: () => T): T {
+  return kaosStorage.run(kaos, fn);
+}
+
+/**
+ * Token returned by setCurrentKaos, used to restore the previous instance.
+ * Mirrors Python's ContextVar Token pattern.
+ */
+export interface KaosToken {
+  readonly previousKaos: Kaos | null;
+}
+
+/**
+ * Set the current kaos instance and return a token for restoring the previous one.
+ *
+ * Unlike a plain module-level global, this binds the override to the current
+ * async context so concurrent tasks do not pollute each other. The returned
+ * token can later be passed to {@link resetCurrentKaos} to restore the
+ * previously-visible instance, mirroring Python's ContextVar token pattern.
+ */
+export function setCurrentKaos(kaos: Kaos): KaosToken {
+  const token: KaosToken = { previousKaos: getCurrentKaos() };
+  kaosStorage.enterWith(kaos);
+  return token;
+}
+
+export function resetCurrentKaos(token: KaosToken): void {
+  kaosStorage.enterWith(token.previousKaos ?? getDefaultKaos());
+}
diff --git a/packages/kaos/src/errors.ts b/packages/kaos/src/errors.ts
new file mode 100644
index 000000000..03fbb15f3
--- /dev/null
+++ b/packages/kaos/src/errors.ts
@@ -0,0 +1,29 @@
+/**
+ * Base error class for the kaos package.
+ */
+export class KaosError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'KaosError';
+  }
+}
+
+/**
+ * Equivalent to Python's ValueError — indicates an invalid argument was passed.
+ */
+export class KaosValueError extends KaosError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'KaosValueError';
+  }
+}
+
+/**
+ * Equivalent to Python's FileExistsError — indicates a file or directory already exists.
+ */
+export class KaosFileExistsError extends KaosError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'KaosFileExistsError';
+  }
+}
diff --git a/packages/kaos/src/index.ts b/packages/kaos/src/index.ts
new file mode 100644
index 000000000..e855c1659
--- /dev/null
+++ b/packages/kaos/src/index.ts
@@ -0,0 +1,96 @@
+import { getCurrentKaos } from './current';
+import type { KaosProcess } from './process';
+import type { StatResult } from './types';
+
+export type { StatResult } from './types';
+export type { KaosProcess } from './process';
+export type { Kaos } from './kaos';
+export type { KaosToken } from './current';
+export { KaosError, KaosValueError, KaosFileExistsError } from './errors';
+export { KaosPath } from './path';
+export { LocalKaos, localKaos } from './local';
+export { setCurrentKaos, resetCurrentKaos, runWithKaos } from './current';
+export { getCurrentKaos };
+
+// Module-level convenience functions for the current Kaos instance.
+
+export function readText(
+  path: string,
+  options?: { encoding?: BufferEncoding; errors?: 'strict' | 'replace' | 'ignore' },
+): Promise<string> {
+  return getCurrentKaos().readText(path, options);
+}
+
+export function writeText(
+  path: string,
+  data: string,
+  options?: { mode?: 'w' | 'a'; encoding?: BufferEncoding },
+): Promise<number> {
+  return getCurrentKaos().writeText(path, data, options);
+}
+
+export function readLines(
+  path: string,
+  options?: { encoding?: BufferEncoding; errors?: 'strict' | 'replace' | 'ignore' },
+): AsyncGenerator<string> {
+  return getCurrentKaos().readLines(path, options);
+}
+
+export function exec(...args: string[]): Promise<KaosProcess> {
+  return getCurrentKaos().exec(...args);
+}
+
+export function readBytes(path: string, n?: number): Promise<Buffer> {
+  return getCurrentKaos().readBytes(path, n);
+}
+
+export function writeBytes(path: string, data: Buffer): Promise<number> {
+  return getCurrentKaos().writeBytes(path, data);
+}
+
+export function stat(path: string, options?: { followSymlinks?: boolean }): Promise<StatResult> {
+  return getCurrentKaos().stat(path, options);
+}
+
+export function mkdir(
+  path: string,
+  options?: { parents?: boolean; existOk?: boolean },
+): Promise<void> {
+  return getCurrentKaos().mkdir(path, options);
+}
+
+export function iterdir(path: string): AsyncGenerator<string> {
+  return getCurrentKaos().iterdir(path);
+}
+
+export function glob(
+  path: string,
+  pattern: string,
+  options?: { caseSensitive?: boolean },
+): AsyncGenerator<string> {
+  return getCurrentKaos().glob(path, pattern, options);
+}
+
+export function chdir(path: string): Promise<void> {
+  return getCurrentKaos().chdir(path);
+}
+
+export function getcwd(): string {
+  return getCurrentKaos().getcwd();
+}
+
+export function gethome(): string {
+  return getCurrentKaos().gethome();
+}
+
+export function normpath(path: string): string {
+  return getCurrentKaos().normpath(path);
+}
+
+export function pathClass(): 'posix' | 'win32' {
+  return getCurrentKaos().pathClass();
+}
+
+export function execWithEnv(args: string[], env?: Record<string, string>): Promise<KaosProcess> {
+  return getCurrentKaos().execWithEnv(args, env);
+}
diff --git a/packages/kaos/src/internal.ts b/packages/kaos/src/internal.ts
new file mode 100644
index 000000000..323a1245d
--- /dev/null
+++ b/packages/kaos/src/internal.ts
@@ -0,0 +1,279 @@
+import { Readable } from 'node:stream';
+
+function isUtf8Continuation(byte: number): boolean {
+  return byte >= 0x80 && byte <= 0xbf;
+}
+
+function decodeUtf8Ignore(data: Buffer): string {
+  let output = '';
+  let i = 0;
+
+  while (i < data.length) {
+    const b0 = data[i];
+    if (b0 === undefined) break;
+
+    if (b0 <= 0x7f) {
+      output += String.fromCodePoint(b0);
+      i += 1;
+      continue;
+    }
+
+    if (b0 >= 0xc2 && b0 <= 0xdf) {
+      const b1 = data[i + 1];
+      if (b1 !== undefined && isUtf8Continuation(b1)) {
+        output += String.fromCodePoint(((b0 & 0x1f) << 6) | (b1 & 0x3f));
+        i += 2;
+        continue;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (b0 >= 0xe0 && b0 <= 0xef) {
+      const b1 = data[i + 1];
+      const b2 = data[i + 2];
+      const validSecond =
+        b1 !== undefined &&
+        ((b0 === 0xe0 && b1 >= 0xa0 && b1 <= 0xbf) ||
+          (b0 >= 0xe1 && b0 <= 0xec && isUtf8Continuation(b1)) ||
+          (b0 === 0xed && b1 >= 0x80 && b1 <= 0x9f) ||
+          (b0 >= 0xee && b0 <= 0xef && isUtf8Continuation(b1)));
+
+      if (validSecond && b2 !== undefined && isUtf8Continuation(b2)) {
+        output += String.fromCodePoint(((b0 & 0x0f) << 12) | ((b1 & 0x3f) << 6) | (b2 & 0x3f));
+        i += 3;
+        continue;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (b0 >= 0xf0 && b0 <= 0xf4) {
+      const b1 = data[i + 1];
+      const b2 = data[i + 2];
+      const b3 = data[i + 3];
+      const validSecond =
+        b1 !== undefined &&
+        ((b0 === 0xf0 && b1 >= 0x90 && b1 <= 0xbf) ||
+          (b0 >= 0xf1 && b0 <= 0xf3 && isUtf8Continuation(b1)) ||
+          (b0 === 0xf4 && b1 >= 0x80 && b1 <= 0x8f));
+
+      if (
+        validSecond &&
+        b2 !== undefined &&
+        b3 !== undefined &&
+        isUtf8Continuation(b2) &&
+        isUtf8Continuation(b3)
+      ) {
+        output += String.fromCodePoint(
+          ((b0 & 0x07) << 18) | ((b1 & 0x3f) << 12) | ((b2 & 0x3f) << 6) | (b3 & 0x3f),
+        );
+        i += 4;
+        continue;
+      }
+      i += 1;
+      continue;
+    }
+
+    i += 1;
+  }
+
+  return output;
+}
+
+function decodeUtf16LeIgnore(data: Buffer): string {
+  let output = '';
+  let i = 0;
+
+  while (i + 1 < data.length) {
+    const first = data[i];
+    const second = data[i + 1];
+    if (first === undefined || second === undefined) break;
+
+    const codeUnit = first | (second << 8);
+
+    if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+      const lowFirst = data[i + 2];
+      const lowSecond = data[i + 3];
+      if (lowFirst !== undefined && lowSecond !== undefined) {
+        const low = lowFirst | (lowSecond << 8);
+        if (low >= 0xdc00 && low <= 0xdfff) {
+          const codePoint = 0x10000 + ((codeUnit - 0xd800) << 10) + (low - 0xdc00);
+          output += String.fromCodePoint(codePoint);
+          i += 4;
+          continue;
+        }
+      }
+      i += 2;
+      continue;
+    }
+
+    if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+      i += 2;
+      continue;
+    }
+
+    output += String.fromCodePoint(codeUnit);
+    i += 2;
+  }
+
+  return output;
+}
+
+/**
+ * Decode a Buffer into a string with Python-compatible `errors` handling.
+ *
+ * - `'strict'` (default): throw on invalid sequences (via TextDecoder `fatal: true`)
+ * - `'replace'`: substitute each invalid sequence with U+FFFD (TextDecoder default)
+ * - `'ignore'`: drop invalid input sequences while preserving valid U+FFFD characters
+ *
+ * Falls back to `Buffer.toString(encoding)` for encodings TextDecoder does not
+ * support (e.g. `hex`, `base64`, `binary`, `latin1`) — those are lossless
+ * byte-to-character mappings so `errors` has no effect.
+ * @internal
+ */
+export function decodeTextWithErrors(
+  data: Buffer,
+  encoding: BufferEncoding,
+  errors: 'strict' | 'replace' | 'ignore' = 'strict',
+): string {
+  // Map Node's BufferEncoding names to Web TextDecoder labels where the two
+  // diverge. Only UTF-family encodings participate in the strict/replace/
+  // ignore dance; the others are lossless and use Buffer.toString directly.
+  let webLabel: string | undefined;
+  // eslint-disable-next-line typescript-eslint/switch-exhaustiveness-check
+  switch (encoding) {
+    case 'utf-8':
+    case 'utf8':
+      webLabel = 'utf-8';
+      break;
+    case 'utf16le':
+    case 'ucs2':
+    case 'ucs-2':
+      webLabel = 'utf-16le';
+      break;
+    default:
+      webLabel = undefined;
+  }
+
+  if (webLabel === undefined) {
+    // Non-UTF encodings (hex/base64/latin1/binary/ascii) are lossless byte↔
+    // character mappings; `errors` is meaningless for them. Return raw.
+    return data.toString(encoding);
+  }
+
+  if (errors === 'strict') {
+    return new TextDecoder(webLabel, { fatal: true }).decode(data);
+  }
+
+  // 'ignore' must skip invalid input bytes/code units, not delete every
+  // replacement character in the decoded output. A file can contain a valid
+  // U+FFFD, and Python preserves it under errors="ignore".
+  if (errors === 'ignore') {
+    return webLabel === 'utf-8' ? decodeUtf8Ignore(data) : decodeUtf16LeIgnore(data);
+  }
+
+  // 'replace' → substitute each invalid sequence with U+FFFD (default).
+  return new TextDecoder(webLabel, { fatal: false }).decode(data);
+}
+
+/**
+ * Convert a glob pattern segment (e.g. "*.txt", "file?.log") into a RegExp.
+ * Mirrors Python pathlib behavior: includes dotfiles, case-sensitive by default.
+ * @internal
+ */
+export function globPatternToRegex(pattern: string, caseSensitive: boolean): RegExp {
+  let regex = '^';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === undefined) break;
+    switch (ch) {
+      case '*':
+        regex += '[^/]*';
+        break;
+      case '?':
+        regex += '[^/]';
+        break;
+      case '[': {
+        const end = pattern.indexOf(']', i + 1);
+        if (end === -1) {
+          regex += '\\[';
+        } else {
+          // Glob character classes only use `!` for negation. A literal
+          // leading `^` must remain literal even though JS regex char
+          // classes treat it as negation in the first position.
+          let charClass = pattern.slice(i + 1, end);
+          if (charClass.startsWith('!')) {
+            charClass = '^' + charClass.slice(1);
+          } else if (charClass.startsWith('^')) {
+            charClass = '\\' + charClass;
+          }
+          regex += '[' + charClass + ']';
+          i = end;
+        }
+        break;
+      }
+      default:
+        regex += ch.replaceAll(/[{}()+.\\^$|]/g, '\\$&');
+    }
+  }
+  regex += '$';
+  return new RegExp(regex, caseSensitive ? '' : 'i');
+}
+
+/**
+ * A Readable wrapper that preserves source backpressure while still allowing
+ * consumers to read buffered output after the source has ended.
+ * @internal
+ */
+export class BufferedReadable extends Readable {
+  private readonly _source: Readable;
+  private _ended: boolean = false;
+
+  constructor(source: Readable) {
+    // Keep a modest prefetch window so wait()-then-read still works for
+    // common small/medium outputs without draining unboundedly.
+    super({ highWaterMark: 128 * 1024 });
+    this._source = source;
+    this._source.on('data', this._onData);
+    this._source.on('end', this._onEnd);
+    this._source.on('close', this._onClose);
+    this._source.on('error', this._onError);
+  }
+
+  override _read(): void {
+    if (!this._ended && !this.destroyed) {
+      this._source.resume();
+    }
+  }
+
+  override _destroy(error: Error | null, callback: (error?: Error | null) => void): void {
+    this._source.off('data', this._onData);
+    this._source.off('end', this._onEnd);
+    this._source.off('close', this._onClose);
+    this._source.off('error', this._onError);
+    callback(error);
+  }
+
+  private readonly _onData = (chunk: string | Uint8Array): void => {
+    if (!this.push(chunk)) {
+      this._source.pause();
+    }
+  };
+
+  private readonly _onEnd = (): void => {
+    this._ended = true;
+    this.push(null);
+  };
+
+  private readonly _onClose = (): void => {
+    if (!this._ended) {
+      this._ended = true;
+      this.push(null);
+    }
+  };
+
+  private readonly _onError = (error: Error): void => {
+    this.destroy(error);
+  };
+}
diff --git a/packages/kaos/src/kaos.ts b/packages/kaos/src/kaos.ts
new file mode 100644
index 000000000..252bae20f
--- /dev/null
+++ b/packages/kaos/src/kaos.ts
@@ -0,0 +1,80 @@
+import type { KaosProcess } from './process';
+import type { StatResult } from './types';
+
+/**
+ * Kimi Agent Operating System (KAOS) interface.
+ *
+ * This is the core abstraction that allows the agent to interact with
+ * different execution environments (local, SSH, containers, etc.)
+ * through a unified API.
+ */
+export interface Kaos {
+  /** Human-readable name for this environment (e.g. `"local"`, `"ssh:host"`). */
+  readonly name: string;
+
+  // ── Path operations (sync) ──────────────────────────────────────────
+
+  /** Return the path style used by this environment. */
+  pathClass(): 'posix' | 'win32';
+  /** Normalize the given path string (resolve `.` / `..` segments). */
+  normpath(path: string): string;
+  /** Return the home directory of the current user. */
+  gethome(): string;
+  /** Return the current working directory. */
+  getcwd(): string;
+
+  // ── Directory operations (async) ────────────────────────────────────
+
+  /** Change the working directory to `path`. */
+  chdir(path: string): Promise<void>;
+  /** Return stat metadata for `path`. */
+  stat(path: string, options?: { followSymlinks?: boolean }): Promise<StatResult>;
+  /** Yield entry names in the directory at `path`. */
+  iterdir(path: string): AsyncGenerator<string>;
+  /** Yield paths matching `pattern` under `path`. */
+  glob(
+    path: string,
+    pattern: string,
+    options?: { caseSensitive?: boolean },
+  ): AsyncGenerator<string>;
+
+  // ── File operations (async) ─────────────────────────────────────────
+
+  /** Read up to `n` bytes from `path` (all bytes if `n` is omitted). */
+  readBytes(path: string, n?: number): Promise<Buffer>;
+  /**
+   * Read the file at `path` as a string.
+   *
+   * `errors` controls how decode errors are handled — mirrors Python's
+   * `open(..., errors=)` parameter:
+   * - `'strict'` (default): throw on any invalid byte for the encoding
+   * - `'replace'`: substitute each invalid byte with U+FFFD (REPLACEMENT CHARACTER)
+   * - `'ignore'`: drop invalid bytes silently
+   */
+  readText(
+    path: string,
+    options?: { encoding?: BufferEncoding; errors?: 'strict' | 'replace' | 'ignore' },
+  ): Promise<string>;
+  /** Yield lines from the file at `path` one by one. */
+  readLines(
+    path: string,
+    options?: { encoding?: BufferEncoding; errors?: 'strict' | 'replace' | 'ignore' },
+  ): AsyncGenerator<string>;
+  /** Write raw bytes to `path`, returning the number of bytes written. */
+  writeBytes(path: string, data: Buffer): Promise<number>;
+  /** Write text to `path`, returning the number of characters written. */
+  writeText(
+    path: string,
+    data: string,
+    options?: { mode?: 'w' | 'a'; encoding?: BufferEncoding },
+  ): Promise<number>;
+  /** Create a directory at `path`. */
+  mkdir(path: string, options?: { parents?: boolean; existOk?: boolean }): Promise<void>;
+
+  // ── Process execution ───────────────────────────────────────────────
+
+  /** Spawn a process with the given arguments. */
+  exec(...args: string[]): Promise<KaosProcess>;
+  /** Spawn a process with explicit environment variables. */
+  execWithEnv(args: string[], env?: Record<string, string>): Promise<KaosProcess>;
+}
diff --git a/packages/kaos/src/local.ts b/packages/kaos/src/local.ts
new file mode 100644
index 000000000..d0c679500
--- /dev/null
+++ b/packages/kaos/src/local.ts
@@ -0,0 +1,560 @@
+import type { ChildProcess } from 'node:child_process';
+import { spawn } from 'node:child_process';
+import {
+  appendFile,
+  lstat,
+  mkdir,
+  open,
+  readdir,
+  readFile,
+  stat,
+  writeFile,
+} from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join as pathJoin, normalize } from 'node:path';
+import type { Readable, Writable } from 'node:stream';
+
+import { KaosFileExistsError } from './errors';
+import { BufferedReadable, decodeTextWithErrors, globPatternToRegex } from './internal';
+import type { Kaos } from './kaos';
+import type { KaosProcess } from './process';
+import type { StatResult } from './types';
+
+const isWindows: boolean = process.platform === 'win32';
+
+/**
+ * Build the `(dev, ino)` cycle-detection key used by `_globWalk`'s
+ * visited set. Returns `null` when `ino` is 0, which Node returns on
+ * filesystems that don't carry inodes (Windows FAT/exFAT, some SMB/NFS
+ * mounts). A null key signals "no reliable identity for this dir" so
+ * the caller skips visited tracking for that descent — cycle safety
+ * is weakened on those filesystems, but normal walking works instead
+ * of every directory colliding on the shared key `"<dev>:0"`.
+ */
+function cycleKey(s: { dev: number; ino: number }): string | null {
+  if (s.ino === 0) return null;
+  return `${String(s.dev)}:${String(s.ino)}`;
+}
+
+class LocalProcess implements KaosProcess {
+  readonly stdin: Writable;
+  readonly stdout: Readable;
+  readonly stderr: Readable;
+  readonly pid: number;
+
+  private readonly _child: ChildProcess;
+  private _exitCode: number | null = null;
+  private readonly _exitPromise: Promise<number>;
+
+  constructor(child: ChildProcess) {
+    if (child.stdin === null || child.stdout === null || child.stderr === null) {
+      throw new Error('Process must be created with stdin/stdout/stderr pipes.');
+    }
+
+    this._child = child;
+    this.stdin = child.stdin;
+    this.stdout = new BufferedReadable(child.stdout);
+    this.stderr = new BufferedReadable(child.stderr);
+    this.pid = child.pid ?? -1;
+
+    this._exitPromise = new Promise<number>((resolve, reject) => {
+      child.on('close', (code: number | null) => {
+        this._exitCode = code ?? -1;
+        resolve(this._exitCode);
+      });
+      child.on('error', (error: Error) => {
+        reject(error);
+      });
+    });
+  }
+
+  get exitCode(): number | null {
+    return this._exitCode;
+  }
+
+  async wait(): Promise<number> {
+    return this._exitPromise;
+  }
+
+  kill(signal?: NodeJS.Signals): Promise<void> {
+    // Reject if the process never actually started (spawn failed).
+    // pid <= 0 indicates ChildProcess.pid was undefined, which happens
+    // when spawn() fails to find/execute the command. Calling
+    // process.kill(-1, ...) on POSIX would signal the entire process
+    // group, potentially killing unrelated processes.
+    if (this.pid <= 0) {
+      return Promise.resolve();
+    }
+
+    // On Windows, `ChildProcess.kill()` only signals the shell parent, leaving
+    // grandchildren alive. Use `taskkill /T` so the caller's graceful and force
+    // kill phases apply to the whole process tree.
+    if (isWindows) {
+      const useForce = signal === 'SIGKILL';
+      const taskkillArgs = useForce
+        ? ['/T', '/F', '/PID', String(this.pid)]
+        : ['/T', '/PID', String(this.pid)];
+      return new Promise<void>((resolve) => {
+        const killer = spawn('taskkill', taskkillArgs, {
+          stdio: 'ignore',
+          windowsHide: true,
+        });
+        const done = (): void => {
+          resolve();
+        };
+        killer.once('error', done);
+        killer.once('close', done);
+      });
+    }
+
+    // On POSIX, `detached:true` makes the child a process-group leader
+    // (pgid === pid). A plain `ChildProcess.kill()` still only signals the
+    // direct child, so a shell like `bash -c 'sleep 100 & sleep 100'` leaves
+    // grandchildren orphaned. `process.kill(-pid, signal)` signals the group
+    // (negative pid = process-group id under POSIX kill(2)).
+    try {
+      process.kill(-this.pid, signal ?? 'SIGTERM');
+    } catch (error) {
+      const err = error as NodeJS.ErrnoException;
+      // ESRCH = group already gone (child exited + reaped between
+      // `wait()` racing spawn + this call). Treat as successful kill.
+      if (err.code === 'ESRCH') return Promise.resolve();
+      // EPERM is typically a misconfiguration (e.g. non-detached
+      // spawn earlier in the file); fall back to direct `.kill()` so
+      // we at least signal the direct child instead of throwing.
+      if (err.code === 'EPERM') {
+        try {
+          this._child.kill(signal ?? 'SIGTERM');
+        } catch {
+          /* best effort */
+        }
+        return Promise.resolve();
+      }
+      throw error;
+    }
+    return Promise.resolve();
+  }
+}
+
+/**
+ * A KAOS implementation that directly interacts with the local filesystem.
+ *
+ * Note: LocalKaos maintains its own per-instance working directory (`_cwd`)
+ * rather than mutating `process.cwd()`. This lets multiple LocalKaos instances
+ * coexist with independent cwds (e.g. when switching contexts via
+ * `runWithKaos`) without cross-polluting each other's relative-path resolution.
+ */
+export class LocalKaos implements Kaos {
+  readonly name: string = 'local';
+  private _cwd: string;
+
+  constructor() {
+    // Snapshot the process cwd at construction time. After this point we
+    // never touch process.cwd() / process.chdir() — all path resolution
+    // goes through this._cwd.
+    this._cwd = process.cwd();
+  }
+
+  private _resolvePath(path: string): string {
+    if (isAbsolute(path)) return path;
+    return pathJoin(this._cwd, path);
+  }
+
+  pathClass(): 'posix' | 'win32' {
+    return isWindows ? 'win32' : 'posix';
+  }
+
+  normpath(path: string): string {
+    return normalize(path);
+  }
+
+  gethome(): string {
+    return homedir();
+  }
+
+  getcwd(): string {
+    return this._cwd;
+  }
+
+  /**
+   * Change the working directory of this LocalKaos instance.
+   *
+   * Unlike Python's `os.chdir`, this is instance-scoped and never touches
+   * `process.cwd()`. Child processes spawned via {@link exec} inherit this
+   * instance's `_cwd`; concurrent LocalKaos instances each carry their own
+   * independent cwd. If you need Python-compatible process-global cwd,
+   * call `process.chdir(x)` directly.
+   */
+  async chdir(path: string): Promise<void> {
+    const resolved = this._resolvePath(path);
+    const s = await stat(resolved);
+    if (!s.isDirectory()) {
+      throw new Error(`Not a directory: ${resolved}`);
+    }
+    this._cwd = resolved;
+  }
+
+  async stat(path: string, options?: { followSymlinks?: boolean }): Promise<StatResult> {
+    const resolved = this._resolvePath(path);
+    const followSymlinks = options?.followSymlinks ?? true;
+    const s = followSymlinks ? await stat(resolved) : await lstat(resolved);
+    return {
+      stMode: s.mode,
+      stIno: s.ino,
+      stDev: s.dev,
+      stNlink: s.nlink,
+      stUid: s.uid,
+      stGid: s.gid,
+      stSize: s.size,
+      stAtime: s.atimeMs / 1000,
+      stMtime: s.mtimeMs / 1000,
+      stCtime: isWindows ? s.birthtimeMs / 1000 : s.ctimeMs / 1000,
+    };
+  }
+
+  async *iterdir(path: string): AsyncGenerator<string> {
+    const resolved = this._resolvePath(path);
+    const entries = await readdir(resolved);
+    for (const entry of entries) {
+      // Use pathJoin so root paths like "/" or "C:\\" don't produce "//entry"
+      // or "C:\\\\entry" — pathJoin normalizes trailing separators correctly.
+      yield pathJoin(resolved, entry);
+    }
+  }
+
+  async *glob(
+    path: string,
+    pattern: string,
+    options?: { caseSensitive?: boolean },
+  ): AsyncGenerator<string> {
+    const resolved = this._resolvePath(path);
+    const caseSensitive = options?.caseSensitive ?? true;
+    const patternParts = pattern.split('/');
+    // Seed `visited` with basePath's own inode so that a symlink inside
+    // basePath that points back at basePath is caught on its first
+    // encounter (not on the second level — the "+1 depth" off-by-one
+    // that would otherwise leak if the caller globs directly from the
+    // loop root). `stat` failure here is tolerated: `_globWalk` will
+    // hit the same error via readdir and return empty.
+    const initVisited = new Set<string>();
+    try {
+      const rootStat = await stat(resolved);
+      const rootKey = cycleKey(rootStat);
+      if (rootKey !== null) initVisited.add(rootKey);
+    } catch {
+      // base does not exist / not accessible — walker handles via its own catch
+    }
+    yield* this._globWalk(resolved, patternParts, caseSensitive, initVisited);
+  }
+
+  // `visited` holds the `(stDev, stIno)` keys of directories on the
+  // current descent path. Before recursing into a subdirectory, we
+  // check its key against `visited`; if present we skip it (cycle
+  // detected) and otherwise recurse with a fresh Set containing the
+  // additional key. The per-recurse copy gives the check path-local
+  // semantics: two legitimate symlinks to the same target in separate
+  // branches both traverse, which is more permissive than Python stdlib
+  // while still cycle-safe.
+  // Same-directory self-recursion (e.g. `**` matching zero dirs with
+  // pattern tail) passes `visited` unchanged — no descent, no cycle
+  // risk.
+  //
+  // Windows note: Node's `fs.Stats.ino` returns `0` on filesystems
+  // that don't support inodes (FAT/exFAT, some SMB/NFS mounts). If we
+  // keyed on `ino=0`, every directory on such a drive would share the
+  // key `"<dev>:0"` and the first would "visit" all others. The
+  // module-level `cycleKey` helper returns `null` in that case, which
+  // causes the call sites to skip visited tracking for that descent
+  // — cycle safety is lost on those filesystems, but normal walking
+  // works.
+  private async *_globWalk(
+    basePath: string,
+    patternParts: string[],
+    caseSensitive: boolean,
+    visited: Set<string>,
+  ): AsyncGenerator<string> {
+    if (patternParts.length === 0) {
+      return;
+    }
+
+    const [currentPattern, ...remainingParts] = patternParts;
+
+    if (currentPattern === '**') {
+      // `**` matches zero or more directory components.
+      //
+      // There are exactly two cases to handle:
+      //   (a) `**` matches zero directories → continue at basePath with the
+      //       remaining pattern parts (or yield basePath itself when `**`
+      //       is the final segment).
+      //   (b) `**` matches one or more directories → recurse into each
+      //       subdirectory, keeping `**` (i.e. the full patternParts) at
+      //       the front. The "zero directories" case is then re-evaluated
+      //       at the subdirectory level by that recursive call.
+      //
+      // We must NOT additionally recurse with `remainingParts` on
+      // subdirectories — that would double-count every match at depth ≥ 1
+      // because case (a) inside the child recursion already yields those
+      // results.
+      if (remainingParts.length > 0) {
+        yield* this._globWalk(basePath, remainingParts, caseSensitive, visited);
+      } else {
+        // Pattern ends with `**`: yield basePath itself (zero-dir match).
+        yield basePath;
+      }
+
+      let entries: string[];
+      try {
+        entries = await readdir(basePath);
+      } catch {
+        return;
+      }
+
+      for (const entry of entries) {
+        // Use pathJoin to avoid "//entry" when basePath is a filesystem root.
+        const fullPath = pathJoin(basePath, entry);
+        let entryStat;
+        try {
+          entryStat = await stat(fullPath);
+        } catch {
+          continue;
+        }
+        if (entryStat.isDirectory()) {
+          const key = cycleKey(entryStat);
+          if (key !== null && visited.has(key)) continue;
+          yield* this._globWalk(
+            fullPath,
+            patternParts,
+            caseSensitive,
+            key !== null ? new Set([...visited, key]) : visited,
+          );
+        } else if (remainingParts.length === 0) {
+          // Pattern ends with `**`: non-directory entries match too
+          // (since `**` matches "anything").
+          yield fullPath;
+        }
+      }
+    } else {
+      const regex = globPatternToRegex(currentPattern ?? '', caseSensitive);
+
+      let entries: string[];
+      try {
+        entries = await readdir(basePath);
+      } catch {
+        return;
+      }
+
+      for (const entry of entries) {
+        if (!regex.test(entry)) {
+          continue;
+        }
+
+        // Use pathJoin to avoid "//entry" when basePath is a filesystem root.
+        const fullPath = pathJoin(basePath, entry);
+
+        if (remainingParts.length === 0) {
+          yield fullPath;
+        } else {
+          let entryStat;
+          try {
+            entryStat = await stat(fullPath);
+          } catch {
+            continue;
+          }
+          if (entryStat.isDirectory()) {
+            const key = cycleKey(entryStat);
+            if (key !== null && visited.has(key)) continue;
+            yield* this._globWalk(
+              fullPath,
+              remainingParts,
+              caseSensitive,
+              key !== null ? new Set([...visited, key]) : visited,
+            );
+          }
+        }
+      }
+    }
+  }
+
+  async readBytes(path: string, n?: number): Promise<Buffer> {
+    const resolved = this._resolvePath(path);
+    if (n === undefined) {
+      return Buffer.from(await readFile(resolved));
+    }
+    const fh = await open(resolved, 'r');
+    try {
+      const buf = Buffer.alloc(n);
+      const { bytesRead } = await fh.read(buf, 0, n, 0);
+      return buf.subarray(0, bytesRead);
+    } finally {
+      await fh.close();
+    }
+  }
+
+  async readText(
+    path: string,
+    options?: { encoding?: BufferEncoding; errors?: 'strict' | 'replace' | 'ignore' },
+  ): Promise<string> {
+    const resolved = this._resolvePath(path);
+    const encoding = options?.encoding ?? 'utf-8';
+    const errors = options?.errors ?? 'strict';
+    const data = await readFile(resolved);
+    return decodeTextWithErrors(data, encoding, errors);
+  }
+
+  async *readLines(
+    path: string,
+    options?: { encoding?: BufferEncoding; errors?: 'strict' | 'replace' | 'ignore' },
+  ): AsyncGenerator<string> {
+    const resolved = this._resolvePath(path);
+    const encoding = options?.encoding ?? 'utf-8';
+    const errors = options?.errors ?? 'strict';
+    const buf = await readFile(resolved);
+    const content = decodeTextWithErrors(buf, encoding, errors);
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (line === undefined) continue;
+      if (i < lines.length - 1) {
+        yield line + '\n';
+      } else if (line !== '') {
+        yield line;
+      }
+    }
+  }
+
+  async writeBytes(path: string, data: Buffer): Promise<number> {
+    const resolved = this._resolvePath(path);
+    await writeFile(resolved, data);
+    return data.length;
+  }
+
+  async writeText(
+    path: string,
+    data: string,
+    options?: { mode?: 'w' | 'a'; encoding?: BufferEncoding },
+  ): Promise<number> {
+    const resolved = this._resolvePath(path);
+    const encoding = options?.encoding ?? 'utf-8';
+    const mode = options?.mode ?? 'w';
+    if (mode === 'a') {
+      await appendFile(resolved, data, encoding);
+    } else {
+      await writeFile(resolved, data, encoding);
+    }
+    return data.length;
+  }
+
+  async mkdir(path: string, options?: { parents?: boolean; existOk?: boolean }): Promise<void> {
+    const resolved = this._resolvePath(path);
+    const parents = options?.parents ?? false;
+    const existOk = options?.existOk ?? false;
+
+    if (parents) {
+      // `fs.mkdir(..., { recursive: true })` silently succeeds when the
+      // target already exists — it does NOT raise EEXIST. To honor the
+      // `existOk: false` semantics, we must probe for existence ourselves
+      // before delegating to the recursive mkdir.
+      if (!existOk) {
+        try {
+          const s = await stat(resolved);
+          if (s.isDirectory()) {
+            throw new KaosFileExistsError(`${resolved} already exists`);
+          }
+          // Path exists but is not a directory — let `mkdir` surface the
+          // appropriate error (EEXIST/ENOTDIR) below.
+        } catch (error: unknown) {
+          if (error instanceof KaosFileExistsError) throw error;
+          const err = error as NodeJS.ErrnoException;
+          if (err.code !== 'ENOENT') throw error;
+          // ENOENT: target doesn't exist yet — proceed to mkdir.
+        }
+      }
+      await mkdir(resolved, { recursive: true });
+      return;
+    }
+
+    // Non-recursive: fs.mkdir naturally throws EEXIST on collision.
+    try {
+      await mkdir(resolved);
+    } catch (error: unknown) {
+      if (
+        existOk &&
+        error instanceof Error &&
+        'code' in error &&
+        (error as NodeJS.ErrnoException).code === 'EEXIST'
+      ) {
+        // `existOk` only applies when the conflicting path is itself a
+        // directory. If a regular file (or other non-directory) already
+        // occupies the path, silently returning would be a lie — the
+        // requested directory still does not exist. Surface the conflict
+        // explicitly so callers cannot mistake "file collision" for
+        // "directory already present".
+        const s = await stat(resolved);
+        if (!s.isDirectory()) {
+          throw new KaosFileExistsError(`${resolved} already exists but is not a directory`);
+        }
+        return;
+      }
+      throw error;
+    }
+  }
+
+  async exec(...args: string[]): Promise<KaosProcess> {
+    const command = args[0];
+    if (command === undefined) {
+      throw new Error('LocalKaos.exec(): at least one argument (the command to run) is required.');
+    }
+    const restArgs = args.slice(1);
+    const child = spawn(command, restArgs, {
+      cwd: this._cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      // POSIX `detached:true` makes the child a process-group leader so
+      // `LocalProcess.kill()` can signal the entire tree. No-op on Windows
+      // (`taskkill /T` handles the tree there). We do not call `child.unref()`
+      // because the parent still waits on the child's exit through `wait()`.
+      detached: !isWindows,
+    });
+    await waitForSpawn(child);
+    return new LocalProcess(child);
+  }
+
+  async execWithEnv(args: string[], env?: Record<string, string>): Promise<KaosProcess> {
+    const command = args[0];
+    if (command === undefined) {
+      throw new Error(
+        'LocalKaos.execWithEnv(): at least one argument (the command to run) is required.',
+      );
+    }
+    const restArgs = args.slice(1);
+    const child = spawn(command, restArgs, {
+      cwd: this._cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: !isWindows,
+      env,
+    });
+    await waitForSpawn(child);
+    return new LocalProcess(child);
+  }
+}
+
+// Wait for a freshly spawned ChildProcess to either emit 'spawn' (success) or
+// 'error' (ENOENT / EACCES / etc.). Until this resolves, callers should not
+// assume the child is running — they may otherwise write to the stdin of a
+// process that never existed.
+function waitForSpawn(child: ChildProcess): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const onSpawn = (): void => {
+      child.off('error', onError);
+      resolve();
+    };
+    const onError = (err: Error): void => {
+      child.off('spawn', onSpawn);
+      reject(err);
+    };
+    child.once('spawn', onSpawn);
+    child.once('error', onError);
+  });
+}
+
+/** The default local KAOS instance. */
+export const localKaos: LocalKaos = new LocalKaos();
diff --git a/packages/kaos/src/path.ts b/packages/kaos/src/path.ts
new file mode 100644
index 000000000..7c895d212
--- /dev/null
+++ b/packages/kaos/src/path.ts
@@ -0,0 +1,433 @@
+import * as posixPath from 'node:path/posix';
+import * as win32Path from 'node:path/win32';
+
+import { getCurrentKaos } from './current';
+import { KaosValueError } from './errors';
+import type { Kaos } from './kaos';
+import type { StatResult } from './types';
+
+type PathClass = 'posix' | 'win32';
+type PathModule = typeof posixPath;
+
+// S_IFMT mask and S_IFDIR/S_IFREG constants for mode checking
+const S_IFMT = 0o170000;
+const S_IFDIR = 0o040000;
+const S_IFREG = 0o100000;
+
+/**
+ * Return the path module matching the current Kaos path class.
+ */
+function getPathMod(pathClass: PathClass = getCurrentKaos().pathClass()): PathModule {
+  return pathClass === 'win32' ? win32Path : posixPath;
+}
+
+function splitPathLexically(pathMod: PathModule, path: string): { root: string; parts: string[] } {
+  const root = pathMod.parse(path).root;
+  const tail = root.length > 0 ? path.slice(root.length) : path;
+  return {
+    root,
+    parts: tail.split(pathMod.sep).filter((part) => part.length > 0),
+  };
+}
+
+function splitPosixPart(path: string): { root: string; parts: string[] } {
+  const root =
+    path.startsWith('//') && !path.startsWith('///') ? '//' : path.startsWith('/') ? '/' : '';
+  const tail = root.length > 0 ? path.slice(root.length) : path;
+  return {
+    root,
+    parts: tail.split('/').filter((part) => part.length > 0 && part !== '.'),
+  };
+}
+
+function joinPosixPure(parts: string[]): string {
+  let root = '';
+  let pathParts: string[] = [];
+
+  for (const part of parts) {
+    if (part === '') continue;
+    const parsed = splitPosixPart(part);
+    if (parsed.root !== '') {
+      root = parsed.root;
+      pathParts = parsed.parts;
+    } else {
+      pathParts.push(...parsed.parts);
+    }
+  }
+
+  if (root !== '') {
+    return pathParts.length === 0 ? root : root + pathParts.join('/');
+  }
+  return pathParts.length === 0 ? '.' : pathParts.join('/');
+}
+
+interface Win32Part {
+  drive: string;
+  root: '' | '\\';
+  parts: string[];
+}
+
+function splitWin32Part(path: string): Win32Part {
+  const normalized = path.replaceAll('/', '\\');
+  const parsed = win32Path.parse(normalized);
+  let drive = '';
+  let root: '' | '\\' = '';
+
+  if (/^[A-Za-z]:/.test(parsed.root)) {
+    drive = parsed.root.slice(0, 2);
+    root = parsed.root.length > 2 ? '\\' : '';
+  } else if (parsed.root.startsWith('\\\\')) {
+    // UNC roots are already complete anchors, e.g. "\\server\\share\\".
+    drive = parsed.root.endsWith('\\') ? parsed.root.slice(0, -1) : parsed.root;
+    root = '\\';
+  } else if (parsed.root === '\\' || parsed.root === '/') {
+    root = '\\';
+  }
+
+  const tail = normalized.slice(parsed.root.length);
+  return {
+    drive,
+    root,
+    parts: tail.split('\\').filter((part) => part.length > 0 && part !== '.'),
+  };
+}
+
+function formatWin32Pure(drive: string, root: '' | '\\', parts: string[]): string {
+  const anchor = drive + root;
+  if (anchor !== '') {
+    return parts.length === 0 ? anchor : anchor + parts.join('\\');
+  }
+  return parts.length === 0 ? '.' : parts.join('\\');
+}
+
+function joinWin32Pure(parts: string[]): string {
+  let drive = '';
+  let root: '' | '\\' = '';
+  let pathParts: string[] = [];
+
+  for (const part of parts) {
+    if (part === '') continue;
+    const parsed = splitWin32Part(part);
+
+    if (parsed.root !== '') {
+      drive = parsed.drive !== '' ? parsed.drive : drive;
+      root = parsed.root;
+      pathParts = parsed.parts;
+      continue;
+    }
+
+    if (parsed.drive !== '') {
+      if (drive.toLowerCase() !== parsed.drive.toLowerCase()) {
+        drive = parsed.drive;
+        root = '';
+        pathParts = parsed.parts;
+      } else {
+        pathParts.push(...parsed.parts);
+      }
+      continue;
+    }
+
+    pathParts.push(...parsed.parts);
+  }
+
+  return formatWin32Pure(drive, root, pathParts);
+}
+
+function joinPure(pathClass: PathClass, parts: string[]): string {
+  return pathClass === 'win32' ? joinWin32Pure(parts) : joinPosixPure(parts);
+}
+
+function isWin32DriveRelative(path: string): boolean {
+  return /^[A-Za-z]:(?:$|[^\\/])/.test(path);
+}
+
+/**
+ * A path wrapper class that delegates all I/O operations to the current Kaos instance.
+ * The path string is interpreted with the path class active at construction time.
+ */
+export class KaosPath {
+  private _path: string;
+  private _pathClass: PathClass;
+
+  constructor(...args: string[]) {
+    this._pathClass = getCurrentKaos().pathClass();
+    if (args.length === 0) {
+      this._path = '.';
+    } else {
+      this._path = joinPure(this._pathClass, args);
+    }
+  }
+
+  private static _from(path: string, pathClass: PathClass): KaosPath {
+    const ret = new KaosPath();
+    ret._path = path;
+    ret._pathClass = pathClass;
+    return ret;
+  }
+
+  private _currentKaos(operation: string): Kaos {
+    const kaos = getCurrentKaos();
+    const currentPathClass = kaos.pathClass();
+    if (currentPathClass !== this._pathClass) {
+      throw new KaosValueError(
+        `Cannot ${operation} ${this._pathClass} path ${this._path} with ${currentPathClass} kaos`,
+      );
+    }
+    if (this._pathClass === 'win32' && isWin32DriveRelative(this._path)) {
+      throw new KaosValueError(
+        `Cannot ${operation} drive-relative win32 path ${this._path}; use an absolute path like C:\\\\path or a path relative to cwd`,
+      );
+    }
+    return kaos;
+  }
+
+  // --- Properties ---
+
+  /** The final component of this path (like Python's Path.name). */
+  get name(): string {
+    return getPathMod(this._pathClass).basename(this._path);
+  }
+
+  /** The logical parent of this path (like Python's Path.parent). */
+  get parent(): KaosPath {
+    const dir = getPathMod(this._pathClass).dirname(this._path);
+    return KaosPath._from(dir, this._pathClass);
+  }
+
+  // --- Path operations (sync, no I/O) ---
+
+  isAbsolute(): boolean {
+    return getPathMod(this._pathClass).isAbsolute(this._path);
+  }
+
+  joinpath(...other: string[]): KaosPath {
+    return KaosPath._from(joinPure(this._pathClass, [this._path, ...other]), this._pathClass);
+  }
+
+  /** Division operator equivalent: join with another path segment. */
+  div(other: string | KaosPath): KaosPath {
+    if (other instanceof KaosPath && other._pathClass !== this._pathClass) {
+      throw new KaosValueError(`Cannot join ${other._pathClass} path to ${this._pathClass} path`);
+    }
+    const otherStr = other instanceof KaosPath ? other.toString() : other;
+    return this.joinpath(otherStr);
+  }
+
+  /**
+   * Canonicalize the path without touching the filesystem.
+   * Makes the path absolute (relative to cwd) and resolves '..' segments.
+   */
+  canonical(): KaosPath {
+    const kaos = this._currentKaos('canonicalize');
+    const pathMod = getPathMod(this._pathClass);
+
+    if (pathMod.isAbsolute(this._path)) {
+      return KaosPath._from(pathMod.normalize(this._path), this._pathClass);
+    }
+    const cwd = kaos.getcwd();
+    if (!pathMod.isAbsolute(cwd)) {
+      throw new KaosValueError(`Cannot canonicalize ${this._path} against non-absolute cwd ${cwd}`);
+    }
+    const abs = pathMod.resolve(cwd, this._path);
+    return KaosPath._from(pathMod.normalize(abs), this._pathClass);
+  }
+
+  /** Compute a relative path from `other` to this path. */
+  relativeTo(other: KaosPath): KaosPath {
+    if (other._pathClass !== this._pathClass) {
+      throw new KaosValueError(`${this._path} is not within ${other.toString()}`);
+    }
+    const pathMod = getPathMod(this._pathClass);
+    const target = splitPathLexically(pathMod, this._path);
+    const base = splitPathLexically(pathMod, other.toString());
+
+    const sameRoot =
+      this._pathClass === 'win32'
+        ? target.root.toLowerCase() === base.root.toLowerCase()
+        : target.root === base.root;
+
+    if (!sameRoot) {
+      throw new KaosValueError(`${this._path} is not within ${other.toString()}`);
+    }
+    if (base.parts.length > target.parts.length) {
+      throw new KaosValueError(`${this._path} is not within ${other.toString()}`);
+    }
+    for (let i = 0; i < base.parts.length; i++) {
+      const targetPart = target.parts[i];
+      const basePart = base.parts[i];
+      const samePart =
+        this._pathClass === 'win32'
+          ? targetPart?.toLowerCase() === basePart?.toLowerCase()
+          : targetPart === basePart;
+      if (!samePart) {
+        throw new KaosValueError(`${this._path} is not within ${other.toString()}`);
+      }
+    }
+
+    const relParts = target.parts.slice(base.parts.length);
+    return KaosPath._from(
+      relParts.length === 0 ? '.' : relParts.join(pathMod.sep),
+      this._pathClass,
+    );
+  }
+
+  /** Expand leading ~ to the home directory. */
+  expanduser(): KaosPath {
+    if (this._path === '~' || this._path.startsWith('~/') || this._path.startsWith('~\\')) {
+      const kaos = this._currentKaos('expand');
+      const home = kaos.gethome();
+      if (this._path === '~') {
+        return KaosPath._from(home, this._pathClass);
+      }
+      const rest = this._path.slice(2); // strip "~/" or "~\"
+      return KaosPath._from(joinPure(this._pathClass, [home, rest]), this._pathClass);
+    }
+    return KaosPath._from(this._path, this._pathClass);
+  }
+
+  // --- Static methods ---
+
+  static home(): KaosPath {
+    const kaos = getCurrentKaos();
+    return new KaosPath(kaos.gethome());
+  }
+
+  static cwd(): KaosPath {
+    const kaos = getCurrentKaos();
+    return new KaosPath(kaos.getcwd());
+  }
+
+  // --- Conversion ---
+
+  /** Create a KaosPath from a local filesystem path string. */
+  static fromLocalPath(localPath: string): KaosPath {
+    return new KaosPath(localPath);
+  }
+
+  /** Return the underlying path string for local filesystem use. */
+  toLocalPath(): string {
+    return this._path;
+  }
+
+  toString(): string {
+    return this._path;
+  }
+
+  equals(other: KaosPath): boolean {
+    return this._pathClass === other._pathClass && this._path === other.toString();
+  }
+
+  // --- File operations (async, delegate to getCurrentKaos) ---
+
+  /** Get stat information for this path. */
+  async stat(options?: { followSymlinks?: boolean }): Promise<StatResult> {
+    const kaos = this._currentKaos('stat');
+    return kaos.stat(this._path, options);
+  }
+
+  /** Check if this path exists on the filesystem. */
+  async exists(options?: { followSymlinks?: boolean }): Promise<boolean> {
+    const kaos = this._currentKaos('check');
+    try {
+      await kaos.stat(this._path, options);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Check if this path points to a regular file. */
+  async isFile(options?: { followSymlinks?: boolean }): Promise<boolean> {
+    const kaos = this._currentKaos('check');
+    try {
+      const s = await kaos.stat(this._path, options);
+      return (s.stMode & S_IFMT) === S_IFREG;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Check if this path points to a directory. */
+  async isDir(options?: { followSymlinks?: boolean }): Promise<boolean> {
+    const kaos = this._currentKaos('check');
+    try {
+      const s = await kaos.stat(this._path, options);
+      return (s.stMode & S_IFMT) === S_IFDIR;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Iterate over entries in this directory. */
+  async *iterdir(): AsyncGenerator<KaosPath> {
+    const kaos = this._currentKaos('iterate');
+    for await (const entry of kaos.iterdir(this._path)) {
+      yield KaosPath._from(entry, this._pathClass);
+    }
+  }
+
+  /** Glob for entries matching a pattern under this path. */
+  async *glob(pattern: string, options?: { caseSensitive?: boolean }): AsyncGenerator<KaosPath> {
+    const kaos = this._currentKaos('glob');
+    for await (const match of kaos.glob(this._path, pattern, options)) {
+      yield KaosPath._from(match, this._pathClass);
+    }
+  }
+
+  /** Read the file content as a Buffer. */
+  async readBytes(n?: number): Promise<Buffer> {
+    const kaos = this._currentKaos('read');
+    return kaos.readBytes(this._path, n);
+  }
+
+  /** Read the file content as a string. */
+  async readText(options?: {
+    encoding?: BufferEncoding;
+    errors?: 'strict' | 'replace' | 'ignore';
+  }): Promise<string> {
+    const kaos = this._currentKaos('read');
+    return kaos.readText(this._path, options);
+  }
+
+  /** Yield lines from the file one by one. */
+  async *readLines(options?: {
+    encoding?: BufferEncoding;
+    errors?: 'strict' | 'replace' | 'ignore';
+  }): AsyncGenerator<string> {
+    const kaos = this._currentKaos('read');
+    for await (const line of kaos.readLines(this._path, options)) {
+      yield line;
+    }
+  }
+
+  /** Write binary data to this path, return the number of bytes written. */
+  async writeBytes(data: Buffer): Promise<number> {
+    const kaos = this._currentKaos('write');
+    return kaos.writeBytes(this._path, data);
+  }
+
+  /** Write text to this path, return the number of characters written. */
+  async writeText(
+    data: string,
+    options?: { mode?: 'w' | 'a'; encoding?: BufferEncoding },
+  ): Promise<number> {
+    const kaos = this._currentKaos('write');
+    return kaos.writeText(this._path, data, options);
+  }
+
+  /** Append text to this path, return the number of characters written. */
+  async appendText(data: string, options?: { encoding?: BufferEncoding }): Promise<number> {
+    const kaos = this._currentKaos('append');
+    const writeOpts: { mode: 'a'; encoding?: BufferEncoding } = { mode: 'a' };
+    if (options?.encoding !== undefined) {
+      writeOpts.encoding = options.encoding;
+    }
+    return kaos.writeText(this._path, data, writeOpts);
+  }
+
+  /** Create this path as a directory. */
+  async mkdir(options?: { parents?: boolean; existOk?: boolean }): Promise<void> {
+    const kaos = this._currentKaos('mkdir');
+    await kaos.mkdir(this._path, options);
+  }
+}
diff --git a/packages/kaos/src/process.ts b/packages/kaos/src/process.ts
new file mode 100644
index 000000000..fe32a9db0
--- /dev/null
+++ b/packages/kaos/src/process.ts
@@ -0,0 +1,25 @@
+import type { Readable, Writable } from 'node:stream';
+
+/**
+ * A running process spawned by a {@link Kaos} environment.
+ *
+ * Provides access to standard I/O streams, the process ID, and lifecycle
+ * management (wait / kill). The interface is intentionally minimal so it
+ * can be backed by local child processes, SSH sessions, or container runtimes.
+ */
+export interface KaosProcess {
+  /** Writable stream connected to the process's standard input. */
+  readonly stdin: Writable;
+  /** Readable stream for the process's standard output. */
+  readonly stdout: Readable;
+  /** Readable stream for the process's standard error. */
+  readonly stderr: Readable;
+  /** Operating-system process ID. */
+  readonly pid: number;
+  /** Exit code if the process has already terminated, otherwise `null`. */
+  readonly exitCode: number | null;
+  /** Wait for the process to exit and return its exit code. */
+  wait(): Promise<number>;
+  /** Send a signal to the process (defaults to `SIGTERM`). */
+  kill(signal?: NodeJS.Signals): Promise<void>;
+}
diff --git a/packages/kaos/src/ssh.ts b/packages/kaos/src/ssh.ts
new file mode 100644
index 000000000..71a92caef
--- /dev/null
+++ b/packages/kaos/src/ssh.ts
@@ -0,0 +1,902 @@
+import { readFile } from 'node:fs/promises';
+import { posix } from 'node:path';
+import type { Readable, Writable } from 'node:stream';
+
+import * as ssh2 from 'ssh2';
+import type {
+  AnyAuthMethod,
+  Client,
+  ClientChannel,
+  ConnectConfig,
+  SFTPWrapper,
+  Stats as SFTPStats,
+} from 'ssh2';
+
+import { KaosError, KaosFileExistsError, KaosValueError } from './errors';
+import { BufferedReadable, decodeTextWithErrors, globPatternToRegex } from './internal';
+import type { Kaos } from './kaos';
+import type { KaosProcess } from './process';
+import type { StatResult } from './types';
+
+// ── stat mode constants ────────────────────────────────────────────────
+const S_IFMT = 0o170000;
+const S_IFREG = 0o100000;
+const S_IFDIR = 0o040000;
+const S_IFLNK = 0o120000;
+const S_IFSOCK = 0o140000;
+const S_IFCHR = 0o020000;
+const S_IFBLK = 0o060000;
+const S_IFIFO = 0o010000;
+
+const DEFAULT_SFTP_STATUS_CODE = {
+  BAD_MESSAGE: 5,
+  CONNECTION_LOST: 7,
+  FAILURE: 4,
+  NO_CONNECTION: 6,
+  NO_SUCH_FILE: 2,
+  OP_UNSUPPORTED: 8,
+  PERMISSION_DENIED: 3,
+} as const;
+
+// ── SSH options ────────────────────────────────────────────────────────
+
+/**
+ * Advanced ssh2 connect options that may be passed through `SSHKaosOptions.extraOptions`.
+ *
+ * Excludes fields that SSHKaos manages itself (`host`, `port`, `username`,
+ * `password`, `privateKey`, `authHandler`, `hostVerifier`) — those are derived
+ * from the top-level `SSHKaosOptions` fields and cannot be overridden here.
+ */
+export type SSHKaosExtraOptions = Omit<
+  ConnectConfig,
+  'host' | 'port' | 'username' | 'password' | 'privateKey' | 'authHandler' | 'hostVerifier'
+>;
+
+export interface SSHKaosOptions {
+  host: string;
+  port?: number;
+  username: string;
+  password?: string;
+  keyPaths?: string[];
+  keyContents?: string[];
+  cwd?: string;
+  /**
+   * Pass-through for advanced ssh2 `ConnectConfig` fields such as `algorithms`,
+   * `keepaliveInterval`, `readyTimeout`, `debug`, `tryKeyboard`, `agent`, etc.
+   *
+   * Managed fields (`host`, `port`, `username`, `password`, `privateKey`,
+   * `authHandler`, `hostVerifier`) are excluded from this type and will take
+   * precedence over anything set here.
+   */
+  extraOptions?: SSHKaosExtraOptions;
+}
+
+// ── SSH error types ───────────────────────────────────────────────────
+
+export class KaosSSHError extends KaosError {
+  readonly code: number | undefined;
+
+  constructor(message: string, code?: number) {
+    super(message);
+    this.name = 'KaosSSHError';
+    this.code = code;
+  }
+}
+
+export class KaosFileNotFoundError extends KaosSSHError {
+  constructor(message: string, code?: number) {
+    super(message, code);
+    this.name = 'KaosFileNotFoundError';
+  }
+}
+
+export class KaosPermissionError extends KaosSSHError {
+  constructor(message: string, code?: number) {
+    super(message, code);
+    this.name = 'KaosPermissionError';
+  }
+}
+
+export class KaosConnectionError extends KaosSSHError {
+  constructor(message: string, code?: number) {
+    super(message, code);
+    this.name = 'KaosConnectionError';
+  }
+}
+
+// ── shell quoting ──────────────────────────────────────────────────────
+
+/**
+ * Shell-escape a single argument (POSIX sh compatible).
+ * Mirrors Python's shlex.quote().
+ */
+function shellQuote(arg: string): string {
+  if (arg === '') return "''";
+  // If the string is safe (only contains safe chars), return as-is
+  if (/^[A-Za-z0-9_./:=@%^,+-]+$/.test(arg)) return arg;
+  // Otherwise wrap in single quotes, escaping any embedded single quotes
+  return "'" + arg.replaceAll("'", "'\"'\"'") + "'";
+}
+
+// ── stat mode builder ──────────────────────────────────────────────────
+
+/**
+ * Build a POSIX st_mode from SFTP Stats.
+ * ssh2's Stats has .mode which already includes both file-type bits and
+ * permission bits, but we also check the boolean helpers as a fallback.
+ */
+function buildStMode(attrs: SFTPStats): number {
+  const raw = attrs.mode;
+  // If mode already contains file-type bits, return as-is
+  if ((raw & S_IFMT) !== 0) return raw;
+
+  // Derive file-type bits from the is* helpers
+  let typeBits = 0;
+  if (attrs.isDirectory()) typeBits = S_IFDIR;
+  else if (attrs.isFile()) typeBits = S_IFREG;
+  else if (attrs.isSymbolicLink()) typeBits = S_IFLNK;
+  else if (attrs.isSocket()) typeBits = S_IFSOCK;
+  else if (attrs.isCharacterDevice()) typeBits = S_IFCHR;
+  else if (attrs.isBlockDevice()) typeBits = S_IFBLK;
+  else if (attrs.isFIFO()) typeBits = S_IFIFO;
+
+  return (raw & ~S_IFMT) | typeBits;
+}
+
+function getSftpStatusCode(): typeof DEFAULT_SFTP_STATUS_CODE {
+  return {
+    ...DEFAULT_SFTP_STATUS_CODE,
+    ...ssh2.utils?.sftp?.STATUS_CODE,
+  };
+}
+
+function getErrorCode(error: unknown): number | undefined {
+  if (typeof error !== 'object' || error === null) {
+    return undefined;
+  }
+  const { code } = error as { code?: unknown };
+  return typeof code === 'number' ? code : undefined;
+}
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+function mapSftpError(operation: string, error: unknown): KaosSSHError {
+  const code = getErrorCode(error);
+  const message = `${operation} failed: ${getErrorMessage(error)}`;
+  const statusCode = getSftpStatusCode();
+
+  if (code === statusCode.NO_SUCH_FILE) {
+    return new KaosFileNotFoundError(message, code);
+  }
+  if (code === statusCode.PERMISSION_DENIED) {
+    return new KaosPermissionError(message, code);
+  }
+  if (code === statusCode.NO_CONNECTION || code === statusCode.CONNECTION_LOST) {
+    return new KaosConnectionError(message, code);
+  }
+  return new KaosSSHError(message, code);
+}
+
+function buildAuthHandler(
+  username: string,
+  privateKeys: readonly (Buffer | string)[],
+  password?: string,
+): ConnectConfig['authHandler'] {
+  const authQueue: AnyAuthMethod[] = privateKeys.map((key) => ({
+    key,
+    type: 'publickey',
+    username,
+  }));
+  if (password !== undefined) {
+    authQueue.push({
+      password,
+      type: 'password',
+      username,
+    });
+  }
+
+  let index = 0;
+  return (_authsLeft, _partialSuccess, next) => {
+    const nextAuth = authQueue[index];
+    index += 1;
+    const nextWithFalse = next as (auth: AnyAuthMethod | false) => void;
+    nextWithFalse(nextAuth ?? false);
+  };
+}
+
+// ── SSH process ────────────────────────────────────────────────────────
+
+/** Exported for unit tests only. Do not use directly. */
+export class SSHProcess implements KaosProcess {
+  readonly stdin: Writable;
+  readonly stdout: Readable;
+  readonly stderr: Readable;
+  readonly pid: number = -1;
+
+  private _exitCode: number | null = null;
+  private readonly _exitPromise: Promise<number>;
+  private readonly _channel: ClientChannel;
+
+  constructor(channel: ClientChannel) {
+    this._channel = channel;
+    this.stdin = channel;
+    this.stdout = new BufferedReadable(channel as unknown as Readable);
+    this.stderr = new BufferedReadable(channel.stderr);
+
+    this._exitPromise = new Promise<number>((resolve) => {
+      // Listen to 'close' on the channel, not 'exit', to ensure all
+      // buffered output is flushed before we resolve.
+      channel.on('close', (code: number | null) => {
+        // Some ssh2 backends surface the exit status only on 'close'.
+        this._exitCode ??= code ?? 1;
+        resolve(this._exitCode);
+      });
+      channel.on('exit', (code: number | null) => {
+        this._exitCode = code ?? 1;
+      });
+    });
+  }
+
+  get exitCode(): number | null {
+    return this._exitCode;
+  }
+
+  async wait(): Promise<number> {
+    return this._exitPromise;
+  }
+
+  kill(signal?: NodeJS.Signals): Promise<void> {
+    // SSH signals must be stripped of the "SIG" prefix (RFC 4254 §6.9):
+    // e.g. 'SIGTERM' → 'TERM', 'SIGKILL' → 'KILL', 'SIGINT' → 'INT'.
+    // Honor the caller's requested signal so that remote processes can
+    // perform graceful shutdown on SIGTERM/SIGINT.
+    const rawSignal = signal ?? 'SIGTERM';
+    const sshSignal = rawSignal.startsWith('SIG') ? rawSignal.slice(3) : rawSignal;
+    this._channel.signal(sshSignal);
+    return Promise.resolve();
+  }
+}
+
+// ── Promisified SSH helpers ────────────────────────────────────────────
+
+function connectClient(config: ConnectConfig): Promise<Client> {
+  const client = new ssh2.Client();
+  return new Promise<Client>((resolve, reject) => {
+    client.on('ready', () => {
+      resolve(client);
+    });
+    client.on('error', (err: Error) => {
+      reject(err);
+    });
+    client.connect(config);
+  });
+}
+
+function getSftp(client: Client): Promise<SFTPWrapper> {
+  return new Promise<SFTPWrapper>((resolve, reject) => {
+    client.sftp((err, sftp) => {
+      if (err) {
+        reject(err);
+      } else {
+        resolve(sftp);
+      }
+    });
+  });
+}
+
+// Every promisified SFTP helper funnels rejections through `mapSftpError` so
+// callers see a KaosSSHError subclass (KaosFileNotFoundError / KaosPermissionError /
+// KaosConnectionError / generic KaosSSHError) instead of the raw ssh2 error.
+// The operation label is the underlying SFTP RPC name — it shows up in the
+// error message for debugging and is the same label used by `stat()` before
+// this was hoisted into the helpers.
+
+function sftpRealpath(sftp: SFTPWrapper, path: string): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    sftp.realpath(path, (err, absPath) => {
+      if (err) {
+        reject(mapSftpError('realpath', err));
+      } else {
+        resolve(absPath);
+      }
+    });
+  });
+}
+
+function sftpStat(sftp: SFTPWrapper, path: string): Promise<SFTPStats> {
+  return new Promise<SFTPStats>((resolve, reject) => {
+    sftp.stat(path, (err, stats) => {
+      if (err) {
+        reject(mapSftpError('stat', err));
+      } else {
+        resolve(stats);
+      }
+    });
+  });
+}
+
+function sftpLstat(sftp: SFTPWrapper, path: string): Promise<SFTPStats> {
+  return new Promise<SFTPStats>((resolve, reject) => {
+    sftp.lstat(path, (err, stats) => {
+      if (err) {
+        reject(mapSftpError('lstat', err));
+      } else {
+        resolve(stats);
+      }
+    });
+  });
+}
+
+interface SFTPFileEntry {
+  filename: string;
+  attrs: SFTPStats;
+}
+
+function sftpReaddir(sftp: SFTPWrapper, path: string): Promise<SFTPFileEntry[]> {
+  return new Promise<SFTPFileEntry[]>((resolve, reject) => {
+    sftp.readdir(path, (err, list) => {
+      if (err) {
+        reject(mapSftpError('readdir', err));
+      } else {
+        resolve(list as SFTPFileEntry[]);
+      }
+    });
+  });
+}
+
+function sftpMkdir(sftp: SFTPWrapper, path: string): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    sftp.mkdir(path, (err) => {
+      if (err) {
+        reject(mapSftpError('mkdir', err));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+function sftpExists(sftp: SFTPWrapper, path: string): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    sftp.exists(path, (exists) => {
+      resolve(exists);
+    });
+  });
+}
+
+function sftpReadFile(sftp: SFTPWrapper, path: string): Promise<Buffer> {
+  return new Promise<Buffer>((resolve, reject) => {
+    sftp.readFile(path, (err, data) => {
+      if (err) {
+        reject(mapSftpError('readFile', err));
+      } else {
+        resolve(data);
+      }
+    });
+  });
+}
+
+function sftpWriteFile(sftp: SFTPWrapper, path: string, data: string | Buffer): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    sftp.writeFile(path, data, (err) => {
+      if (err) {
+        reject(mapSftpError('writeFile', err));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+function sftpAppendFile(sftp: SFTPWrapper, path: string, data: string | Buffer): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    sftp.appendFile(path, data, (err) => {
+      if (err) {
+        reject(mapSftpError('appendFile', err));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+function clientExec(client: Client, command: string): Promise<ClientChannel> {
+  return new Promise<ClientChannel>((resolve, reject) => {
+    client.exec(command, (err: Error | undefined, channel: ClientChannel) => {
+      if (err) {
+        reject(err);
+      } else {
+        resolve(channel);
+      }
+    });
+  });
+}
+
+// ── SSHKaos ────────────────────────────────────────────────────────────
+
+/**
+ * A KAOS implementation that interacts with a remote machine via SSH and SFTP.
+ */
+export class SSHKaos implements Kaos {
+  readonly name: string = 'ssh';
+
+  private _client: Client;
+  private _sftp: SFTPWrapper;
+  private _home: string;
+  private _cwd: string;
+
+  private constructor(client: Client, sftp: SFTPWrapper, home: string, cwd: string) {
+    this._client = client;
+    this._sftp = sftp;
+    this._home = home;
+    this._cwd = cwd;
+  }
+
+  private _resolvePath(path: string): string {
+    if (posix.isAbsolute(path)) return path;
+    return posix.join(this._cwd, path);
+  }
+
+  /**
+   * Factory method to create an SSHKaos instance.
+   * Establishes the SSH connection and SFTP session.
+   */
+  static async create(options: SSHKaosOptions): Promise<SSHKaos> {
+    // Start from extraOptions (advanced ssh2 options) so our managed fields
+    // below take precedence.
+    const config: ConnectConfig = {
+      ...options.extraOptions,
+      host: options.host,
+      port: options.port ?? 22,
+      username: options.username,
+    };
+
+    if (options.password !== undefined) {
+      config.password = options.password;
+    }
+
+    // Build private keys from keyContents and keyPaths
+    const privateKeys: (Buffer | string)[] = [];
+    if (options.keyContents) {
+      for (const content of options.keyContents) {
+        privateKeys.push(content);
+      }
+    }
+    if (options.keyPaths) {
+      const keyPromises = options.keyPaths.map((keyPath) => readFile(keyPath, 'utf-8'));
+      const keyData = await Promise.all(keyPromises);
+      for (const key of keyData) {
+        privateKeys.push(key);
+      }
+    }
+    if (privateKeys.length > 0) {
+      const authHandler = buildAuthHandler(options.username, privateKeys, options.password);
+      if (authHandler !== undefined) {
+        config.authHandler = authHandler;
+      }
+    }
+
+    // Disable host key verification (like asyncssh known_hosts=None)
+    config.hostVerifier = () => true;
+
+    const client = await connectClient(config);
+    try {
+      const sftp = await getSftp(client);
+
+      // Determine home and cwd
+      const home = await sftpRealpath(sftp, '.');
+      let cwd: string;
+      if (options.cwd === undefined) {
+        cwd = home;
+      } else {
+        cwd = await sftpRealpath(sftp, options.cwd);
+        const attrs = await sftpStat(sftp, cwd);
+        if (!attrs.isDirectory()) {
+          throw new KaosValueError(`${cwd} is not a directory`);
+        }
+      }
+
+      return new SSHKaos(client, sftp, home, cwd);
+    } catch (error) {
+      client.end();
+      throw error;
+    }
+  }
+
+  // ── Path operations (sync) ─────────────────────────────────────────
+
+  pathClass(): 'posix' | 'win32' {
+    return 'posix';
+  }
+
+  normpath(path: string): string {
+    return posix.normalize(path);
+  }
+
+  gethome(): string {
+    return this._home;
+  }
+
+  getcwd(): string {
+    return this._cwd;
+  }
+
+  // ── Directory operations (async) ───────────────────────────────────
+
+  async chdir(path: string): Promise<void> {
+    let target: string;
+    if (posix.isAbsolute(path)) {
+      target = path;
+    } else {
+      target = posix.resolve(this._cwd, path);
+    }
+    // Resolve to the real path via SFTP
+    const resolved = await sftpRealpath(this._sftp, target);
+    // Verify the resolved target is actually a directory. Without this
+    // guard, `realpath` happily returns file paths, causing later relative
+    // reads/writes/execs to treat a regular file as a working directory.
+    const attrs = await sftpStat(this._sftp, resolved);
+    if (!attrs.isDirectory()) {
+      throw new KaosValueError(`${resolved} is not a directory`);
+    }
+    this._cwd = resolved;
+  }
+
+  async stat(path: string, options?: { followSymlinks?: boolean }): Promise<StatResult> {
+    const resolved = this._resolvePath(path);
+    const followSymlinks = options?.followSymlinks ?? true;
+    // sftpStat / sftpLstat already wrap errors via mapSftpError.
+    const st = followSymlinks
+      ? await sftpStat(this._sftp, resolved)
+      : await sftpLstat(this._sftp, resolved);
+
+    return {
+      stMode: buildStMode(st),
+      // SFTP does not provide inode
+      stIno: 0,
+      // SFTP does not provide device
+      stDev: 0,
+      // ssh2 Stats does not expose nlink
+      stNlink: 0,
+      stUid: st.uid,
+      stGid: st.gid,
+      stSize: st.size,
+      stAtime: st.atime,
+      stMtime: st.mtime,
+      // SFTP v3 has no ctime, fallback to mtime
+      stCtime: st.mtime,
+    };
+  }
+
+  async *iterdir(path: string): AsyncGenerator<string> {
+    const resolved = this._resolvePath(path);
+    const entries = await sftpReaddir(this._sftp, resolved);
+    for (const entry of entries) {
+      if (entry.filename === '.' || entry.filename === '..') continue;
+      yield posix.join(resolved, entry.filename);
+    }
+  }
+
+  async *glob(
+    path: string,
+    pattern: string,
+    options?: { caseSensitive?: boolean },
+  ): AsyncGenerator<string> {
+    const resolved = this._resolvePath(path);
+    const caseSensitive = options?.caseSensitive ?? true;
+    if (!caseSensitive) {
+      throw new KaosValueError('Case insensitive glob is not supported in current environment');
+    }
+    // Use local glob implementation over SFTP readdir
+    const patternParts = pattern.split('/');
+    yield* this._globWalk(resolved, patternParts, caseSensitive);
+  }
+
+  private async *_globWalk(
+    basePath: string,
+    patternParts: string[],
+    caseSensitive: boolean,
+  ): AsyncGenerator<string> {
+    if (patternParts.length === 0) return;
+
+    const [currentPattern, ...remainingParts] = patternParts;
+
+    if (currentPattern === '**') {
+      // `**` matches zero or more directory components.
+      //
+      // Two cases to handle:
+      //   (a) `**` matches zero directories → continue at basePath with
+      //       the remaining pattern parts (or yield basePath when `**` is
+      //       the final segment).
+      //   (b) `**` matches one or more directories → recurse into each
+      //       subdirectory, keeping `**` (the full patternParts) at the
+      //       front. The "zero directories" case is re-evaluated at the
+      //       subdirectory level by that recursive call.
+      //
+      // Do NOT additionally recurse with `remainingParts` on subdirectories
+      // — that would double-count matches at depth ≥ 1 because case (a)
+      // inside the child recursion already yields those results.
+      if (remainingParts.length > 0) {
+        yield* this._globWalk(basePath, remainingParts, caseSensitive);
+      } else {
+        // Pattern ends with `**`: yield basePath itself (zero-dir match).
+        yield basePath;
+      }
+
+      let entries: SFTPFileEntry[];
+      try {
+        entries = await sftpReaddir(this._sftp, basePath);
+      } catch {
+        return;
+      }
+
+      for (const entry of entries) {
+        if (entry.filename === '.' || entry.filename === '..') continue;
+        const fullPath = posix.join(basePath, entry.filename);
+        if (entry.attrs.isDirectory()) {
+          yield* this._globWalk(fullPath, patternParts, caseSensitive);
+        } else if (remainingParts.length === 0) {
+          // Pattern ends with `**`: non-directory entries match too.
+          yield fullPath;
+        }
+      }
+    } else {
+      const regex = globPatternToRegex(currentPattern ?? '', caseSensitive);
+
+      let entries: SFTPFileEntry[];
+      try {
+        entries = await sftpReaddir(this._sftp, basePath);
+      } catch {
+        return;
+      }
+
+      for (const entry of entries) {
+        if (entry.filename === '.' || entry.filename === '..') continue;
+        if (!regex.test(entry.filename)) continue;
+
+        const fullPath = posix.join(basePath, entry.filename);
+
+        if (remainingParts.length === 0) {
+          yield fullPath;
+        } else if (entry.attrs.isDirectory()) {
+          yield* this._globWalk(fullPath, remainingParts, caseSensitive);
+        }
+      }
+    }
+  }
+
+  // ── File operations (async) ────────────────────────────────────────
+
+  async readBytes(path: string, n?: number): Promise<Buffer> {
+    const data = await sftpReadFile(this._sftp, this._resolvePath(path));
+    if (n === undefined) return data;
+    return data.subarray(0, n);
+  }
+
+  async readText(
+    path: string,
+    options?: { encoding?: BufferEncoding; errors?: 'strict' | 'replace' | 'ignore' },
+  ): Promise<string> {
+    const encoding = options?.encoding ?? 'utf-8';
+    const errors = options?.errors ?? 'strict';
+    const data = await sftpReadFile(this._sftp, this._resolvePath(path));
+    return decodeTextWithErrors(data, encoding, errors);
+  }
+
+  async *readLines(
+    path: string,
+    options?: { encoding?: BufferEncoding; errors?: 'strict' | 'replace' | 'ignore' },
+  ): AsyncGenerator<string> {
+    // SFTP does not support streaming line reads; read all then split.
+    // Match Python's splitlines() semantics: returned lines do NOT include
+    // the line terminator, and a trailing newline does not create an extra
+    // empty line.
+    const text = await this.readText(this._resolvePath(path), options);
+    if (text === '') {
+      return;
+    }
+
+    const lines = text.split(/\r\n|[\n\r]/u);
+    if (/(?:\r\n|[\n\r])$/u.test(text)) {
+      lines.pop();
+    }
+    for (const line of lines) {
+      yield line ?? '';
+    }
+  }
+
+  async writeBytes(path: string, data: Buffer): Promise<number> {
+    await sftpWriteFile(this._sftp, this._resolvePath(path), data);
+    return data.length;
+  }
+
+  async writeText(
+    path: string,
+    data: string,
+    options?: { mode?: 'w' | 'a'; encoding?: BufferEncoding },
+  ): Promise<number> {
+    const resolved = this._resolvePath(path);
+    const mode = options?.mode ?? 'w';
+    const encoding = options?.encoding ?? 'utf-8';
+    const buf = Buffer.from(data, encoding);
+    if (mode === 'a') {
+      await sftpAppendFile(this._sftp, resolved, buf);
+    } else {
+      await sftpWriteFile(this._sftp, resolved, buf);
+    }
+    return data.length;
+  }
+
+  async mkdir(path: string, options?: { parents?: boolean; existOk?: boolean }): Promise<void> {
+    const resolved = this._resolvePath(path);
+    const parents = options?.parents ?? false;
+    const existOk = options?.existOk ?? false;
+
+    if (parents) {
+      await this._mkdirRecursive(resolved, existOk);
+    } else {
+      const exists = await sftpExists(this._sftp, resolved);
+      if (exists) {
+        if (!existOk) {
+          throw new KaosFileExistsError(`${resolved} already exists`);
+        }
+        // `existOk` only applies when the conflicting path is itself a
+        // directory. A regular file sitting at the target path is still
+        // a conflict — we must not pretend mkdir succeeded.
+        const st = await sftpStat(this._sftp, resolved);
+        if (!st.isDirectory()) {
+          throw new KaosFileExistsError(`${resolved} already exists but is not a directory`);
+        }
+        return;
+      }
+      await sftpMkdir(this._sftp, resolved);
+    }
+  }
+
+  private async _mkdirRecursive(path: string, existOk: boolean): Promise<void> {
+    // Split path into components and create each level.
+    const parts = path.split('/').filter(Boolean);
+    let current = path.startsWith('/') ? '/' : '';
+    const lastIndex = parts.length - 1;
+    for (const [i, part] of parts.entries()) {
+      current = current ? posix.join(current, part) : part;
+
+      const isFinal = i === lastIndex;
+
+      // eslint-disable-next-line no-await-in-loop
+      const exists = await sftpExists(this._sftp, current);
+      if (exists) {
+        // For intermediate components, it's fine (and expected) for the
+        // path to already exist. For the final target, honor `existOk`.
+        if (isFinal && !existOk) {
+          throw new KaosFileExistsError(`${current} already exists`);
+        }
+        // Regardless of whether this is an intermediate or the final
+        // component, an existing path must actually be a directory.
+        // An intermediate non-directory would cause the next `sftpMkdir`
+        // to fail with a confusing error; a final non-directory would
+        // otherwise be silently accepted when `existOk` is true.
+        // eslint-disable-next-line no-await-in-loop
+        const st = await sftpStat(this._sftp, current);
+        if (!st.isDirectory()) {
+          throw new KaosFileExistsError(`${current} already exists but is not a directory`);
+        }
+        continue;
+      }
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await sftpMkdir(this._sftp, current);
+      } catch (error) {
+        // Race condition: another process may have created it.
+        // eslint-disable-next-line no-await-in-loop
+        const nowExists = await sftpExists(this._sftp, current);
+        if (!nowExists) throw new Error(`Failed to create directory: ${current}`, { cause: error });
+        // A raced path must still be a directory. Another process may have
+        // created a regular file at the same pathname after our exists()
+        // check but before mkdir(), which must remain a hard conflict.
+        // eslint-disable-next-line no-await-in-loop
+        const st = await sftpStat(this._sftp, current);
+        if (!st.isDirectory()) {
+          throw new KaosFileExistsError(`${current} already exists but is not a directory`);
+        }
+        // If the final component lost a race and existOk=false, surface the
+        // conflict to match the non-race path above.
+        if (isFinal && !existOk) {
+          throw new KaosFileExistsError(`${current} already exists`);
+        }
+      }
+    }
+  }
+
+  // ── Process execution ──────────────────────────────────────────────
+
+  exec(...args: string[]): Promise<KaosProcess> {
+    if (args.length === 0) {
+      throw new KaosValueError(
+        'SSHKaos.exec(): at least one argument (the command to run) is required.',
+      );
+    }
+    return this._execInternal(args);
+  }
+
+  execWithEnv(args: string[], env?: Record<string, string>): Promise<KaosProcess> {
+    if (args.length === 0) {
+      throw new KaosValueError(
+        'SSHKaos.execWithEnv(): at least one argument (the command to run) is required.',
+      );
+    }
+    return this._execInternal(args, env);
+  }
+
+  /**
+   * Build the full remote shell command string that will be handed to
+   * `client.exec`. Exposed as a static so it can be unit-tested without
+   * needing a live SSH connection — see `ssh.test.ts`.
+   *
+   * Shape: `cd '<cwd>' && KEY1='v1' KEY2='v2' <cmd> <arg1> <arg2> ...`
+   *
+   * Environment variables are injected as POSIX inline assignments instead
+   * of being passed through ssh2's `ExecOptions.env`. The env-request path
+   * silently drops anything not whitelisted by sshd's `AcceptEnv` directive
+   * (stock OpenSSH only allows LANG/LC_*), which is a well-known footgun
+   * inherited from the Python / asyncssh implementation. Inline assignments
+   * run inside the remote shell itself, so they bypass AcceptEnv entirely
+   * and reach the command regardless of server configuration.
+   */
+  private static _buildExecCommand(
+    args: string[],
+    cwd: string,
+    env?: Record<string, string>,
+  ): string {
+    let command = args.map((arg) => shellQuote(arg)).join(' ');
+
+    if (env !== undefined) {
+      const assignments: string[] = [];
+      for (const [key, value] of Object.entries(env)) {
+        // Reject anything that isn't a POSIX-valid shell variable name so
+        // the injected prefix can never become a shell-injection vector.
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+          throw new KaosValueError(
+            `SSHKaos.execWithEnv(): invalid env variable name ${JSON.stringify(key)}`,
+          );
+        }
+        assignments.push(`${key}=${shellQuote(value)}`);
+      }
+      if (assignments.length > 0) {
+        command = `${assignments.join(' ')} ${command}`;
+      }
+    }
+
+    if (cwd !== '') {
+      command = `cd ${shellQuote(cwd)} && ${command}`;
+    }
+
+    return command;
+  }
+
+  private async _execInternal(args: string[], env?: Record<string, string>): Promise<KaosProcess> {
+    const command = SSHKaos._buildExecCommand(args, this._cwd, env);
+    const channel = await clientExec(this._client, command);
+    return new SSHProcess(channel);
+  }
+
+  // ── SSH lifecycle ──────────────────────────────────────────────────
+
+  /**
+   * Close the SSH connection. After this, the SSHKaos instance is unusable.
+   */
+  close(): Promise<void> {
+    this._sftp.end();
+    return new Promise<void>((resolve) => {
+      this._client.once('close', () => {
+        resolve();
+      });
+      this._client.end();
+    });
+  }
+}
diff --git a/packages/kaos/src/types.ts b/packages/kaos/src/types.ts
new file mode 100644
index 000000000..7ef03d33d
--- /dev/null
+++ b/packages/kaos/src/types.ts
@@ -0,0 +1,15 @@
+/**
+ * KAOS stat result, mirroring Python's os.stat_result fields.
+ */
+export interface StatResult {
+  stMode: number;
+  stIno: number;
+  stDev: number;
+  stNlink: number;
+  stUid: number;
+  stGid: number;
+  stSize: number;
+  stAtime: number;
+  stMtime: number;
+  stCtime: number;
+}
diff --git a/packages/kaos/test/cmd.test.ts b/packages/kaos/test/cmd.test.ts
new file mode 100644
index 000000000..2c90edad4
--- /dev/null
+++ b/packages/kaos/test/cmd.test.ts
@@ -0,0 +1,116 @@
+import { mkdtemp, rm, stat as fsStat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { resetCurrentKaos, setCurrentKaos } from '#/current';
+import type { KaosToken } from '#/current';
+import type { Kaos } from '#/kaos';
+import { LocalKaos } from '#/local';
+import type { KaosProcess } from '#/process';
+
+/**
+ * Helper to run a cmd.exe command and collect stdout/stderr/exitCode.
+ * Prepends `chcp 65001>nul &` to ensure UTF-8 output.
+ */
+async function runCmd(
+  kaos: Kaos,
+  command: string,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const proc: KaosProcess = await kaos.exec('cmd.exe', '/c', `chcp 65001>nul & ${command}`);
+
+  proc.stdin.end();
+
+  const stdoutChunks: Buffer[] = [];
+  const stderrChunks: Buffer[] = [];
+
+  const stdoutDone = new Promise<void>((resolve) => {
+    proc.stdout.on('data', (chunk: Buffer) => {
+      stdoutChunks.push(chunk);
+    });
+    proc.stdout.on('end', () => {
+      resolve();
+    });
+  });
+
+  const stderrDone = new Promise<void>((resolve) => {
+    proc.stderr.on('data', (chunk: Buffer) => {
+      stderrChunks.push(chunk);
+    });
+    proc.stderr.on('end', () => {
+      resolve();
+    });
+  });
+
+  const exitCode = await proc.wait();
+  await stdoutDone;
+  await stderrDone;
+
+  return {
+    stdout: Buffer.concat(stdoutChunks).toString('utf-8'),
+    stderr: Buffer.concat(stderrChunks).toString('utf-8'),
+    exitCode,
+  };
+}
+
+describe.skipIf(process.platform !== 'win32')('LocalKaos cmd.exe', () => {
+  let kaos: Kaos;
+  let token: KaosToken;
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'kaos-cmd-'));
+    kaos = new LocalKaos();
+    token = setCurrentKaos(kaos);
+  });
+
+  afterEach(async () => {
+    resetCurrentKaos(token);
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('should run a simple command', async () => {
+    const { exitCode, stdout, stderr } = await runCmd(kaos, 'echo Hello Windows');
+    expect(exitCode).toBe(0);
+    expect(stdout.trim()).toBe('Hello Windows');
+    expect(stderr).toBe('');
+  });
+
+  it('should handle command with error exit', async () => {
+    // `exit /b 1` must produce neither stdout nor stderr — pinning that
+    // keeps us honest if cmd.exe or the chcp prefix ever leaks output.
+    const { exitCode, stdout, stderr } = await runCmd(kaos, 'exit /b 1');
+    expect(exitCode).toBe(1);
+    expect(stdout).toBe('');
+    expect(stderr).toBe('');
+  });
+
+  it('should support command chaining', async () => {
+    const { exitCode, stdout, stderr } = await runCmd(kaos, 'echo First&& echo Second');
+    expect(exitCode).toBe(0);
+    expect(stdout.replaceAll('\r\n', '\n')).toBe('First\nSecond\n');
+    expect(stderr).toBe('');
+  });
+
+  it('should perform file operations', async () => {
+    // Mirror Python test_local_kaos_cmd.py::test_file_operations: two separate
+    // kaos.exec invocations (write via redirect, then read back via type),
+    // assert the file lands on disk between them, and pin the exact stdout
+    // byte-for-byte so any CRLF drift is caught immediately.
+    const filePath = join(tmpDir, 'test_file.txt').replaceAll('/', '\\');
+
+    const write = await runCmd(kaos, `echo Test content> "${filePath}"`);
+    expect(write.exitCode).toBe(0);
+    expect(write.stdout).toBe('');
+    expect(write.stderr).toBe('');
+
+    const statInfo = await fsStat(filePath);
+    expect(statInfo.isFile()).toBe(true);
+
+    const read = await runCmd(kaos, `type "${filePath}"`);
+    expect(read.exitCode).toBe(0);
+    expect(read.stdout).toBe('Test content\r\n');
+    expect(read.stderr).toBe('');
+  });
+});
diff --git a/packages/kaos/test/current.test.ts b/packages/kaos/test/current.test.ts
new file mode 100644
index 000000000..92baa00bd
--- /dev/null
+++ b/packages/kaos/test/current.test.ts
@@ -0,0 +1,396 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { Readable, Writable } from 'node:stream';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  chdir,
+  exec,
+  execWithEnv,
+  getCurrentKaos,
+  gethome,
+  getcwd,
+  glob,
+  iterdir,
+  localKaos,
+  LocalKaos,
+  mkdir,
+  normpath,
+  pathClass,
+  readBytes,
+  readLines,
+  readText,
+  resetCurrentKaos,
+  setCurrentKaos,
+  stat,
+  writeBytes,
+  writeText,
+} from '#/index';
+import type { Kaos, KaosToken } from '#/index';
+
+function createMockKaos(name: string): Kaos {
+  return {
+    name,
+    pathClass: () => 'posix' as const,
+    normpath: (p: string) => p,
+    gethome: () => '/',
+    getcwd: () => '/',
+    chdir: async () => {},
+    stat: () =>
+      Promise.resolve({
+        stMode: 0,
+        stIno: 0,
+        stDev: 0,
+        stNlink: 0,
+        stUid: 0,
+        stGid: 0,
+        stSize: 0,
+        stAtime: 0,
+        stMtime: 0,
+        stCtime: 0,
+      }),
+    iterdir: async function* () {},
+    glob: async function* () {},
+    readBytes: () => Promise.resolve(Buffer.alloc(0)),
+    readText: () => Promise.resolve(''),
+    readLines: async function* () {},
+    writeBytes: () => Promise.resolve(0),
+    writeText: () => Promise.resolve(0),
+    mkdir: () => Promise.resolve(),
+    exec: () =>
+      Promise.resolve({
+        stdin: null as unknown as Writable,
+        stdout: null as unknown as Readable,
+        stderr: null as unknown as Readable,
+        pid: -1,
+        exitCode: 0,
+        wait: () => Promise.resolve(0),
+        kill: () => Promise.resolve(),
+      }),
+    execWithEnv: () =>
+      Promise.resolve({
+        stdin: null as unknown as Writable,
+        stdout: null as unknown as Readable,
+        stderr: null as unknown as Readable,
+        pid: -1,
+        exitCode: 0,
+        wait: () => Promise.resolve(0),
+        kill: () => Promise.resolve(),
+      }),
+  };
+}
+
+describe('current kaos context', () => {
+  let token: KaosToken | undefined;
+
+  afterEach(() => {
+    if (token !== undefined) {
+      resetCurrentKaos(token);
+      token = undefined;
+    }
+  });
+
+  it('should return a LocalKaos instance by default', () => {
+    const kaos = getCurrentKaos();
+    expect(kaos).toBeInstanceOf(LocalKaos);
+    expect(kaos.name).toBe('local');
+    expect(kaos).toBe(localKaos);
+  });
+
+  it('should return a token from setCurrentKaos', () => {
+    const original = getCurrentKaos();
+    token = setCurrentKaos(new LocalKaos());
+    expect(token.previousKaos).toBe(original);
+  });
+
+  it('should allow setting a custom kaos instance', () => {
+    const mockKaos = createMockKaos('mock');
+    token = setCurrentKaos(mockKaos);
+    const current = getCurrentKaos();
+    expect(current.name).toBe('mock');
+    expect(current).toBe(mockKaos);
+  });
+
+  it('should restore previous kaos with resetCurrentKaos', () => {
+    const original = getCurrentKaos();
+    token = setCurrentKaos(new LocalKaos());
+    expect(getCurrentKaos()).not.toBe(original);
+    resetCurrentKaos(token);
+    expect(getCurrentKaos()).toBe(original);
+    // already restored
+    token = undefined;
+  });
+
+  it('should support nested set/reset', () => {
+    const original = getCurrentKaos();
+
+    const first = new LocalKaos();
+    const token1 = setCurrentKaos(first);
+    expect(getCurrentKaos()).toBe(first);
+
+    const second = new LocalKaos();
+    const token2 = setCurrentKaos(second);
+    expect(getCurrentKaos()).toBe(second);
+
+    resetCurrentKaos(token2);
+    expect(getCurrentKaos()).toBe(first);
+
+    resetCurrentKaos(token1);
+    expect(getCurrentKaos()).toBe(original);
+  });
+
+  it('isolates set/reset across concurrent async flows', async () => {
+    const kaosA = createMockKaos('A');
+    const kaosB = createMockKaos('B');
+
+    const [seenA, seenB] = await Promise.all([
+      (async () => {
+        const tokenA = setCurrentKaos(kaosA);
+        try {
+          await Promise.resolve();
+          await new Promise((resolve) => {
+            setTimeout(resolve, 20);
+          });
+          return getCurrentKaos().name;
+        } finally {
+          resetCurrentKaos(tokenA);
+        }
+      })(),
+      (async () => {
+        const tokenB = setCurrentKaos(kaosB);
+        try {
+          await Promise.resolve();
+          await new Promise((resolve) => {
+            setTimeout(resolve, 5);
+          });
+          return getCurrentKaos().name;
+        } finally {
+          resetCurrentKaos(tokenB);
+        }
+      })(),
+    ]);
+
+    expect(seenA).toBe('A');
+    expect(seenB).toBe('B');
+  });
+});
+
+describe('module-level proxy functions', () => {
+  it('normpath delegates to the current kaos instance', () => {
+    // LocalKaos on posix normalizes '/foo/../bar' to '/bar'
+    const result = normpath('/foo/../bar');
+    expect(typeof result).toBe('string');
+    expect(result.endsWith('bar')).toBe(true);
+  });
+
+  it('pathClass returns posix or win32 from the current kaos', () => {
+    const result = pathClass();
+    expect(result === 'posix' || result === 'win32').toBe(true);
+  });
+
+  it('readLines proxies to the current kaos and yields lines', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'kaos-readlines-'));
+    try {
+      const filePath = join(dir, 'lines.txt');
+      await writeText(filePath, 'alpha\nbravo\ncharlie');
+      const collected: string[] = [];
+      for await (const line of readLines(filePath)) {
+        collected.push(line);
+      }
+      // readLines preserves newline terminators on each line.
+      expect(collected).toEqual(['alpha\n', 'bravo\n', 'charlie']);
+      expect(collected.join('')).toBe('alpha\nbravo\ncharlie');
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('writeText accepts an encoding option through the module-level proxy', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'kaos-writetext-enc-'));
+    try {
+      const filePath = join(dir, 'enc.txt');
+      // Pass a non-default encoding to prove the option flows through the
+      // proxy signature without a TypeScript error.
+      await writeText(filePath, 'hello-latin1', { encoding: 'latin1' });
+      const contents = await readText(filePath, { encoding: 'latin1' });
+      expect(contents).toBe('hello-latin1');
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('execWithEnv proxies to the current kaos', async () => {
+    // Use the real LocalKaos to run `env | grep CUSTOM_VAR`
+    const proc = await execWithEnv(['sh', '-c', 'echo "$CUSTOM_VAR"'], {
+      CUSTOM_VAR: 'proxy_test_value',
+      // Preserve PATH so sh can be found
+      PATH: process.env['PATH'] ?? '/usr/bin:/bin',
+    });
+
+    const chunks: Buffer[] = [];
+    for await (const chunk of proc.stdout) {
+      chunks.push(chunk as Buffer);
+    }
+    const stdout = Buffer.concat(chunks).toString('utf-8').trim();
+    await proc.wait();
+
+    expect(stdout).toBe('proxy_test_value');
+  });
+
+  // These tests pin the remaining module-level facade functions to their
+  // `getCurrentKaos()` delegate. Using a spy Kaos lets us assert delegation
+  // happened without needing real filesystem I/O for each proxy.
+  it('delegates every facade function to the current kaos instance', async () => {
+    const calls: string[] = [];
+    const spyKaos: Kaos = {
+      ...createMockKaos('spy'),
+      pathClass: () => {
+        calls.push('pathClass');
+        return 'posix';
+      },
+      normpath: (p) => {
+        calls.push(`normpath:${p}`);
+        return p;
+      },
+      gethome: () => {
+        calls.push('gethome');
+        return '/mock-home';
+      },
+      getcwd: () => {
+        calls.push('getcwd');
+        return '/mock-cwd';
+      },
+      chdir: async (p) => {
+        calls.push(`chdir:${p}`);
+      },
+      stat: async (p) => {
+        calls.push(`stat:${p}`);
+        return {
+          stMode: 0,
+          stIno: 0,
+          stDev: 0,
+          stNlink: 0,
+          stUid: 0,
+          stGid: 0,
+          stSize: 0,
+          stAtime: 0,
+          stMtime: 0,
+          stCtime: 0,
+        };
+      },
+      iterdir: async function* (p) {
+        calls.push(`iterdir:${p}`);
+        // Yield a throwaway value so this function is a valid non-empty
+        // generator — the test just wants to observe that the push ran.
+        yield `${p}/dummy`;
+      },
+      glob: async function* (p, pat) {
+        calls.push(`glob:${p}:${pat}`);
+        yield `${p}/${pat}`;
+      },
+      readBytes: async (p, n) => {
+        calls.push(`readBytes:${p}:${String(n)}`);
+        return Buffer.alloc(0);
+      },
+      readText: async (p) => {
+        calls.push(`readText:${p}`);
+        return '';
+      },
+      readLines: async function* (p) {
+        calls.push(`readLines:${p}`);
+        yield `${p}:line`;
+      },
+      writeBytes: async (p, d) => {
+        calls.push(`writeBytes:${p}:${String(d.length)}`);
+        return d.length;
+      },
+      writeText: async (p, d) => {
+        calls.push(`writeText:${p}:${String(d.length)}`);
+        return d.length;
+      },
+      mkdir: async (p) => {
+        calls.push(`mkdir:${p}`);
+      },
+    };
+
+    const spyToken = setCurrentKaos(spyKaos);
+    try {
+      // Sync proxies
+      expect(pathClass()).toBe('posix');
+      expect(normpath('/a/b')).toBe('/a/b');
+      expect(gethome()).toBe('/mock-home');
+      expect(getcwd()).toBe('/mock-cwd');
+
+      // Async single-value proxies
+      await chdir('/dst');
+      await stat('/path');
+      await readBytes('/f', 10);
+      await readText('/f2');
+      await writeBytes('/f3', Buffer.from([1, 2, 3]));
+      await writeText('/f4', 'hello');
+      await mkdir('/d');
+
+      // Async-generator proxies — must be consumed to execute body
+      for await (const _ of iterdir('/d2')) {
+        // body intentionally empty
+        void _;
+      }
+      for await (const _ of glob('/d3', '*.txt')) {
+        void _;
+      }
+    } finally {
+      resetCurrentKaos(spyToken);
+    }
+
+    expect(calls).toEqual([
+      'pathClass',
+      'normpath:/a/b',
+      'gethome',
+      'getcwd',
+      'chdir:/dst',
+      'stat:/path',
+      'readBytes:/f:10',
+      'readText:/f2',
+      'writeBytes:/f3:3',
+      'writeText:/f4:5',
+      'mkdir:/d',
+      'iterdir:/d2',
+      'glob:/d3:*.txt',
+    ]);
+  });
+
+  it('exec proxies to the current kaos instance', async () => {
+    let received: string[] = [];
+    const spyKaos: Kaos = {
+      ...createMockKaos('spy-exec'),
+      exec: async (...args) => {
+        received = args;
+        throw new Error('intentionally stopped for the spy');
+      },
+    };
+
+    const spyToken = setCurrentKaos(spyKaos);
+    try {
+      await expect(exec('cmd', 'a', 'b')).rejects.toThrow('intentionally stopped for the spy');
+    } finally {
+      resetCurrentKaos(spyToken);
+    }
+    expect(received).toEqual(['cmd', 'a', 'b']);
+  });
+});
+
+describe('resetCurrentKaos null-token fallback', () => {
+  it('falls back to the default LocalKaos when previousKaos is null', () => {
+    // Construct a synthetic token whose previousKaos is null. This mirrors
+    // the state a token would be in if the ambient context had no override
+    // at all when `setCurrentKaos` was called.
+    const syntheticToken: KaosToken = { previousKaos: null };
+    resetCurrentKaos(syntheticToken);
+
+    // After reset, the current kaos should be the default LocalKaos.
+    const current = getCurrentKaos();
+    expect(current.name).toBe('local');
+  });
+});
diff --git a/packages/kaos/test/e2e/async-isolation.test.ts b/packages/kaos/test/e2e/async-isolation.test.ts
new file mode 100644
index 000000000..345c0db69
--- /dev/null
+++ b/packages/kaos/test/e2e/async-isolation.test.ts
@@ -0,0 +1,202 @@
+import { describe, expect, it } from 'vitest';
+
+import { getCurrentKaos, runWithKaos } from '#/current';
+import type { Kaos } from '#/kaos';
+import { LocalKaos } from '#/local';
+
+// ── Mock Kaos ─────────────────────────────────────────────────────────
+
+function createNamedKaos(kaosName: string): Kaos {
+  const base = new LocalKaos();
+  return {
+    name: kaosName,
+    pathClass: () => base.pathClass(),
+    normpath: (p: string) => base.normpath(p),
+    gethome: () => base.gethome(),
+    getcwd: () => base.getcwd(),
+    chdir: async (p: string) => base.chdir(p),
+    stat: async (p: string, opts?: { followSymlinks?: boolean }) => base.stat(p, opts),
+    iterdir: (p: string) => base.iterdir(p),
+    glob: (p: string, pattern: string, opts?: { caseSensitive?: boolean }) =>
+      base.glob(p, pattern, opts),
+    readBytes: async (p: string, n?: number) => base.readBytes(p, n),
+    readText: async (
+      p: string,
+      opts?: { encoding?: BufferEncoding; errors?: 'strict' | 'ignore' | 'replace' },
+    ) => base.readText(p, opts),
+    readLines: (p: string, opts?: { encoding?: BufferEncoding }) => base.readLines(p, opts),
+    writeBytes: async (p: string, data: Buffer) => base.writeBytes(p, data),
+    writeText: async (
+      p: string,
+      data: string,
+      opts?: { mode?: 'w' | 'a'; encoding?: BufferEncoding },
+    ) => base.writeText(p, data, opts),
+    mkdir: async (p: string, opts?: { parents?: boolean; existOk?: boolean }) =>
+      base.mkdir(p, opts),
+    exec: async (...args: string[]) => base.exec(...args),
+    execWithEnv: async (args: string[], env?: Record<string, string>) =>
+      base.execWithEnv(args, env),
+  };
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise<void>((r) => setTimeout(r, ms));
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────
+
+describe('e2e: async isolation (AsyncLocalStorage)', () => {
+  describe('runWithKaos provides true isolation between concurrent calls', () => {
+    it('two concurrent runWithKaos with different Kaos instances return correct instances', async () => {
+      const kaosA = createNamedKaos('kaos-A');
+      const kaosB = createNamedKaos('kaos-B');
+
+      const [nameA, nameB] = await Promise.all([
+        runWithKaos(kaosA, async () => {
+          // Yield the event loop to let B start
+          await delay(5);
+          return getCurrentKaos().name;
+        }),
+        runWithKaos(kaosB, async () => {
+          // Yield the event loop to let A continue
+          await delay(5);
+          return getCurrentKaos().name;
+        }),
+      ]);
+
+      expect(nameA).toBe('kaos-A');
+      expect(nameB).toBe('kaos-B');
+    });
+
+    it('many concurrent runWithKaos calls maintain isolation', async () => {
+      const count = 20;
+      const results = await Promise.all(
+        Array.from({ length: count }, (_, i) => {
+          const kaos = createNamedKaos(`kaos-${i}`);
+          return runWithKaos(kaos, async () => {
+            await delay(Math.random() * 10);
+            return getCurrentKaos().name;
+          });
+        }),
+      );
+
+      for (let i = 0; i < count; i++) {
+        expect(results[i]).toBe(`kaos-${i}`);
+      }
+    });
+  });
+
+  describe('nested runWithKaos', () => {
+    it('inner scope sees inner Kaos, outer scope restores after exit', async () => {
+      const kaosOuter = createNamedKaos('outer');
+      const kaosInner = createNamedKaos('inner');
+
+      const result = await runWithKaos(kaosOuter, async () => {
+        const beforeNest = getCurrentKaos().name;
+
+        const innerResult = await runWithKaos(kaosInner, async () => {
+          return getCurrentKaos().name;
+        });
+
+        const afterNest = getCurrentKaos().name;
+
+        return { beforeNest, innerResult, afterNest };
+      });
+
+      expect(result.beforeNest).toBe('outer');
+      expect(result.innerResult).toBe('inner');
+      expect(result.afterNest).toBe('outer');
+    });
+
+    it('triple nested runWithKaos restores correctly at each level', async () => {
+      const kaosA = createNamedKaos('level-A');
+      const kaosB = createNamedKaos('level-B');
+      const kaosC = createNamedKaos('level-C');
+
+      const result = await runWithKaos(kaosA, async () => {
+        const atA = getCurrentKaos().name;
+
+        const inner = await runWithKaos(kaosB, async () => {
+          const atB = getCurrentKaos().name;
+
+          const deepest = await runWithKaos(kaosC, async () => {
+            return getCurrentKaos().name;
+          });
+
+          const afterC = getCurrentKaos().name;
+          return { atB, deepest, afterC };
+        });
+
+        const afterB = getCurrentKaos().name;
+        return { atA, ...inner, afterB };
+      });
+
+      expect(result.atA).toBe('level-A');
+      expect(result.atB).toBe('level-B');
+      expect(result.deepest).toBe('level-C');
+      expect(result.afterC).toBe('level-B');
+      expect(result.afterB).toBe('level-A');
+    });
+  });
+
+  describe('runWithKaos context survives await', () => {
+    it('context is maintained after await delay', async () => {
+      const kaos = createNamedKaos('awaited');
+
+      const result = await runWithKaos(kaos, async () => {
+        const before = getCurrentKaos().name;
+        await delay(10);
+        const after = getCurrentKaos().name;
+        return { before, after };
+      });
+
+      expect(result.before).toBe('awaited');
+      expect(result.after).toBe('awaited');
+    });
+
+    it('context is maintained across multiple awaits', async () => {
+      const kaos = createNamedKaos('multi-await');
+
+      const result = await runWithKaos(kaos, async () => {
+        const names: string[] = [];
+        for (let i = 0; i < 5; i++) {
+          await delay(2);
+          names.push(getCurrentKaos().name);
+        }
+        return names;
+      });
+
+      expect(result).toEqual([
+        'multi-await',
+        'multi-await',
+        'multi-await',
+        'multi-await',
+        'multi-await',
+      ]);
+    });
+
+    it('context survives Promise.all inside runWithKaos', async () => {
+      const kaos = createNamedKaos('promise-all');
+
+      const result = await runWithKaos(kaos, async () => {
+        const names = await Promise.all([
+          (async () => {
+            await delay(5);
+            return getCurrentKaos().name;
+          })(),
+          (async () => {
+            await delay(10);
+            return getCurrentKaos().name;
+          })(),
+          (async () => {
+            await delay(1);
+            return getCurrentKaos().name;
+          })(),
+        ]);
+        return names;
+      });
+
+      expect(result).toEqual(['promise-all', 'promise-all', 'promise-all']);
+    });
+  });
+});
diff --git a/packages/kaos/test/e2e/concurrent-operations.test.ts b/packages/kaos/test/e2e/concurrent-operations.test.ts
new file mode 100644
index 000000000..4c67b1717
--- /dev/null
+++ b/packages/kaos/test/e2e/concurrent-operations.test.ts
@@ -0,0 +1,234 @@
+import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { LocalKaos } from '#/local';
+
+// ── Tests ─────────────────────────────────────────────────────────────
+
+describe('e2e: concurrent operations', () => {
+  let kaos: LocalKaos;
+  let tempDir: string;
+  let originalCwd: string;
+
+  beforeEach(async () => {
+    kaos = new LocalKaos();
+    originalCwd = process.cwd();
+    tempDir = await realpath(await mkdtemp(join(tmpdir(), 'kaos-concurrent-')));
+    process.chdir(tempDir);
+  });
+
+  afterEach(async () => {
+    process.chdir(originalCwd);
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe('concurrent reads and writes on different files', () => {
+    it('10 concurrent writeText + readText on separate files → all consistent', async () => {
+      const count = 10;
+      const promises = Array.from({ length: count }, async (_, i): Promise<void> => {
+        const filePath = join(tempDir, `file-${i}.txt`);
+        const content = `content-${i}-${'data'.repeat(100)}`;
+        await kaos.writeText(filePath, content);
+        const readBack = await kaos.readText(filePath);
+        expect(readBack).toBe(content);
+      });
+
+      await Promise.all(promises);
+    });
+  });
+
+  describe('concurrent writes to the same file', () => {
+    it('sequential writes to same file → last write wins', async () => {
+      const filePath = join(tempDir, 'shared.txt');
+      const writes = 20;
+
+      // Write sequentially to guarantee ordering
+      for (let i = 0; i < writes; i++) {
+        await kaos.writeText(filePath, `version-${i}`);
+      }
+
+      // The file should have the last written content
+      const content = await kaos.readText(filePath);
+      expect(content).toBe(`version-${writes - 1}`);
+    });
+
+    it('concurrent appends to same file → all data present', async () => {
+      const filePath = join(tempDir, 'append-target.txt');
+      await kaos.writeText(filePath, '');
+
+      const count = 20;
+      const promises: Promise<number>[] = [];
+
+      for (let i = 0; i < count; i++) {
+        promises.push(kaos.writeText(filePath, `line-${i}\n`, { mode: 'a' }));
+      }
+
+      await Promise.all(promises);
+
+      const content = await kaos.readText(filePath);
+      const lines = content.trimEnd().split('\n');
+
+      // All lines should be present (order may vary due to concurrency)
+      expect(lines).toHaveLength(count);
+      const lineSet = new Set(lines);
+      for (let i = 0; i < count; i++) {
+        expect(lineSet.has(`line-${i}`)).toBe(true);
+      }
+    });
+  });
+
+  describe('concurrent exec of multiple subprocesses', () => {
+    it('5 concurrent node processes → all complete independently', async () => {
+      const count = 5;
+      const promises = Array.from(
+        { length: count },
+        async (_, i): Promise<{ index: number; exitCode: number; stdout: string }> => {
+          const code = `process.stdout.write('proc-${i}');`;
+          const proc = await kaos.exec('node', '-e', code);
+          const exitCode = await proc.wait();
+
+          const chunks: Buffer[] = [];
+          for await (const chunk of proc.stdout) {
+            chunks.push(Buffer.from(chunk as Buffer));
+          }
+          const stdout = Buffer.concat(chunks).toString('utf-8');
+
+          return { index: i, exitCode, stdout };
+        },
+      );
+
+      const results = await Promise.all(promises);
+
+      for (const result of results) {
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toBe(`proc-${result.index}`);
+      }
+    });
+
+    it('concurrent processes with different exit codes', async () => {
+      const exitCodes = [0, 1, 2, 42, 0];
+      const promises = exitCodes.map(async (code) => {
+        const proc = await kaos.exec('node', '-e', `process.exit(${code})`);
+        return proc.wait();
+      });
+
+      const results = await Promise.all(promises);
+      expect(results).toEqual(exitCodes);
+    });
+  });
+
+  describe('concurrent iterdir + file creation', () => {
+    it('iterdir does not crash when files are being created concurrently', async () => {
+      // Pre-create some files
+      for (let i = 0; i < 5; i++) {
+        await kaos.writeText(join(tempDir, `existing-${i}.txt`), `data-${i}`);
+      }
+
+      // Start iterdir and file creation concurrently
+      const iterdirPromise = (async (): Promise<string[]> => {
+        const entries: string[] = [];
+        for await (const entry of kaos.iterdir(tempDir)) {
+          entries.push(entry);
+        }
+        return entries;
+      })();
+
+      const creationPromise = (async (): Promise<void> => {
+        for (let i = 0; i < 5; i++) {
+          await kaos.writeText(join(tempDir, `new-${i}.txt`), `new-data-${i}`);
+        }
+      })();
+
+      const [entries] = await Promise.all([iterdirPromise, creationPromise]);
+
+      // iterdir should return at least the pre-existing files
+      // (new files may or may not be included depending on timing)
+      expect(entries.length).toBeGreaterThanOrEqual(5);
+    });
+  });
+
+  describe('concurrent glob operations', () => {
+    it('multiple concurrent globs return correct results', async () => {
+      // Create files with different extensions
+      await kaos.writeText(join(tempDir, 'a.ts'), 'ts');
+      await kaos.writeText(join(tempDir, 'b.ts'), 'ts');
+      await kaos.writeText(join(tempDir, 'c.js'), 'js');
+      await kaos.writeText(join(tempDir, 'd.js'), 'js');
+      await kaos.writeText(join(tempDir, 'e.json'), 'json');
+
+      const [tsFiles, jsFiles, jsonFiles] = await Promise.all([
+        collectGlob(kaos, tempDir, '*.ts'),
+        collectGlob(kaos, tempDir, '*.js'),
+        collectGlob(kaos, tempDir, '*.json'),
+      ]);
+
+      expect(tsFiles.toSorted()).toEqual([join(tempDir, 'a.ts'), join(tempDir, 'b.ts')].toSorted());
+      expect(jsFiles.toSorted()).toEqual([join(tempDir, 'c.js'), join(tempDir, 'd.js')].toSorted());
+      expect(jsonFiles).toEqual([join(tempDir, 'e.json')]);
+    });
+
+    it('10 concurrent glob(*.txt) on same directory → consistent results', async () => {
+      // Use a flat glob pattern to avoid ** duplication behavior
+      await kaos.writeText(join(tempDir, 'a.txt'), 'a');
+      await kaos.writeText(join(tempDir, 'b.txt'), 'b');
+      await kaos.writeText(join(tempDir, 'c.txt'), 'c');
+
+      const expected = [
+        join(tempDir, 'a.txt'),
+        join(tempDir, 'b.txt'),
+        join(tempDir, 'c.txt'),
+      ].toSorted();
+
+      const promises: Promise<string[]>[] = [];
+      for (let i = 0; i < 10; i++) {
+        promises.push(collectGlob(kaos, tempDir, '*.txt'));
+      }
+
+      const results = await Promise.all(promises);
+
+      for (const result of results) {
+        expect(result.toSorted()).toEqual(expected);
+      }
+    });
+  });
+
+  describe('concurrent mixed operations', () => {
+    it('read + write + stat + iterdir concurrently on same directory', async () => {
+      const filePath = join(tempDir, 'mixed.txt');
+      await kaos.writeText(filePath, 'initial');
+
+      const [readResult, _writeResult, statResult, entries] = await Promise.all([
+        kaos.readText(filePath),
+        kaos.writeText(join(tempDir, 'another.txt'), 'other'),
+        kaos.stat(filePath),
+        collectIterdir(kaos, tempDir),
+      ]);
+
+      // readResult might be 'initial' (read before write) or a valid string
+      expect(typeof readResult).toBe('string');
+      expect(statResult.stSize).toBeGreaterThan(0);
+      expect(entries.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+});
+
+// ── Helper functions ──────────────────────────────────────────────────
+
+async function collectGlob(kaos: LocalKaos, path: string, pattern: string): Promise<string[]> {
+  const results: string[] = [];
+  for await (const entry of kaos.glob(path, pattern)) {
+    results.push(entry);
+  }
+  return results;
+}
+
+async function collectIterdir(kaos: LocalKaos, path: string): Promise<string[]> {
+  const results: string[] = [];
+  for await (const entry of kaos.iterdir(path)) {
+    results.push(entry);
+  }
+  return results;
+}
diff --git a/packages/kaos/test/e2e/cwd-isolation.test.ts b/packages/kaos/test/e2e/cwd-isolation.test.ts
new file mode 100644
index 000000000..bcf9c9ddb
--- /dev/null
+++ b/packages/kaos/test/e2e/cwd-isolation.test.ts
@@ -0,0 +1,195 @@
+import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { getCurrentKaos, runWithKaos } from '#/current';
+import { LocalKaos } from '#/local';
+
+// ── Instance-level cwd isolation: real concurrent file operations ─────
+//
+// LocalKaos maintains its own per-instance `_cwd` rather than mutating
+// `process.cwd()`. Two concurrent LocalKaos instances chdir-ing into
+// different temp directories and issuing relative-path reads/writes
+// must not clobber each other.
+
+describe('e2e: LocalKaos instance-level cwd isolation (concurrent, real FS)', () => {
+  const tempDirs: string[] = [];
+
+  async function makeTempDir(label: string): Promise<string> {
+    const dir = await realpath(await mkdtemp(join(tmpdir(), `kaos-cwd-iso-${label}-`)));
+    tempDirs.push(dir);
+    return dir;
+  }
+
+  afterEach(async () => {
+    while (tempDirs.length > 0) {
+      const dir = tempDirs.pop();
+      if (dir !== undefined) {
+        await rm(dir, { recursive: true, force: true });
+      }
+    }
+  });
+
+  it('two concurrent runWithKaos scopes with different LocalKaos cwds each read their own files', async () => {
+    const dirA = await makeTempDir('A');
+    const dirB = await makeTempDir('B');
+
+    const kaosA = new LocalKaos();
+    const kaosB = new LocalKaos();
+
+    // Pre-seed distinct files in each dir using absolute paths.
+    await kaosA.writeText(join(dirA, 'marker.txt'), 'A-content');
+    await kaosB.writeText(join(dirB, 'marker.txt'), 'B-content');
+
+    // Run two concurrent scopes. Each scope chdirs into its own temp
+    // directory and reads 'marker.txt' via a *relative* path. Yielding
+    // the event loop between the chdir and the read gives the other
+    // scope a chance to clobber shared state if it exists.
+    const [a, b] = await Promise.all([
+      runWithKaos(kaosA, async () => {
+        const k = getCurrentKaos();
+        await k.chdir(dirA);
+        // Yield to the other concurrent scope.
+        await new Promise<void>((r) => setImmediate(r));
+        const value = await k.readText('marker.txt');
+        // Yield again after reading.
+        await new Promise<void>((r) => setImmediate(r));
+        const cwdAfter = k.getcwd();
+        return { value, cwdAfter };
+      }),
+      runWithKaos(kaosB, async () => {
+        const k = getCurrentKaos();
+        await k.chdir(dirB);
+        await new Promise<void>((r) => setImmediate(r));
+        const value = await k.readText('marker.txt');
+        await new Promise<void>((r) => setImmediate(r));
+        const cwdAfter = k.getcwd();
+        return { value, cwdAfter };
+      }),
+    ]);
+
+    expect(a.value).toBe('A-content');
+    expect(b.value).toBe('B-content');
+    expect(a.cwdAfter).toBe(dirA);
+    expect(b.cwdAfter).toBe(dirB);
+
+    // Neither chdir should have touched the node-level process.cwd().
+    // (We don't assert a specific value — the test runner controls it —
+    //  but the two LocalKaos instances must hold distinct _cwds.)
+    expect(kaosA.getcwd()).toBe(dirA);
+    expect(kaosB.getcwd()).toBe(dirB);
+  });
+
+  it('interleaved concurrent relative writes stay isolated', async () => {
+    const dirA = await makeTempDir('wA');
+    const dirB = await makeTempDir('wB');
+
+    const kaosA = new LocalKaos();
+    const kaosB = new LocalKaos();
+    await kaosA.chdir(dirA);
+    await kaosB.chdir(dirB);
+
+    // Perform many interleaved relative writes from both scopes.
+    const tasks: Promise<void>[] = [];
+    for (let i = 0; i < 20; i++) {
+      tasks.push(
+        runWithKaos(kaosA, async () => {
+          await new Promise<void>((r) => setImmediate(r));
+          await getCurrentKaos().writeText(`a-${i}.txt`, `A-${i}`);
+        }),
+      );
+      tasks.push(
+        runWithKaos(kaosB, async () => {
+          await new Promise<void>((r) => setImmediate(r));
+          await getCurrentKaos().writeText(`b-${i}.txt`, `B-${i}`);
+        }),
+      );
+    }
+    await Promise.all(tasks);
+
+    // All A files must live in dirA with A content, and B in dirB.
+    for (let i = 0; i < 20; i++) {
+      const aVal = await kaosA.readText(join(dirA, `a-${i}.txt`));
+      const bVal = await kaosB.readText(join(dirB, `b-${i}.txt`));
+      expect(aVal).toBe(`A-${i}`);
+      expect(bVal).toBe(`B-${i}`);
+    }
+
+    // And no cross-contamination: A files must NOT exist under dirB.
+    await expect(kaosA.readText(join(dirB, 'a-0.txt'))).rejects.toThrow();
+    await expect(kaosB.readText(join(dirA, 'b-0.txt'))).rejects.toThrow();
+  });
+
+  it('nested runWithKaos with different cwds restores the outer cwd correctly', async () => {
+    const dirOuter = await makeTempDir('outer');
+    const dirInner = await makeTempDir('inner');
+
+    const kaosOuter = new LocalKaos();
+    const kaosInner = new LocalKaos();
+    await kaosOuter.chdir(dirOuter);
+    await kaosInner.chdir(dirInner);
+
+    await kaosOuter.writeText(join(dirOuter, 'outer.txt'), 'OUTER');
+    await kaosInner.writeText(join(dirInner, 'inner.txt'), 'INNER');
+
+    const result = await runWithKaos(kaosOuter, async () => {
+      const beforeNest = await getCurrentKaos().readText('outer.txt');
+
+      const innerValue = await runWithKaos(kaosInner, async () => {
+        return getCurrentKaos().readText('inner.txt');
+      });
+
+      const afterNest = await getCurrentKaos().readText('outer.txt');
+      return { beforeNest, innerValue, afterNest };
+    });
+
+    expect(result.beforeNest).toBe('OUTER');
+    expect(result.innerValue).toBe('INNER');
+    expect(result.afterNest).toBe('OUTER');
+  });
+
+  it('LocalKaos.chdir never mutates process.cwd()', async () => {
+    const dirA = await makeTempDir('nochangeA');
+    const originalProcessCwd = process.cwd();
+
+    const kaos = new LocalKaos();
+    await kaos.chdir(dirA);
+
+    // The instance cwd must have changed.
+    expect(kaos.getcwd()).toBe(dirA);
+    // But the process-global cwd must not have been touched.
+    expect(process.cwd()).toBe(originalProcessCwd);
+  });
+
+  it('exec respects instance-level cwd (two instances with different cwds)', async () => {
+    const dirA = await makeTempDir('execA');
+    const dirB = await makeTempDir('execB');
+
+    const kaosA = new LocalKaos();
+    const kaosB = new LocalKaos();
+    await kaosA.chdir(dirA);
+    await kaosB.chdir(dirB);
+
+    async function readStdout(proc: Awaited<ReturnType<LocalKaos['exec']>>): Promise<string> {
+      const chunks: Buffer[] = [];
+      for await (const chunk of proc.stdout) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as string));
+      }
+      await proc.wait();
+      return Buffer.concat(chunks).toString('utf-8').trim();
+    }
+
+    // Run `pwd` concurrently in both instances. Each must report its own cwd.
+    const [outA, outB] = await Promise.all([
+      kaosA.exec('sh', '-c', 'pwd').then(readStdout),
+      kaosB.exec('sh', '-c', 'pwd').then(readStdout),
+    ]);
+
+    // On macOS /tmp is a symlink to /private/tmp — we already realpath'd
+    // the temp dir during creation, so comparing strings is safe.
+    expect(outA).toBe(dirA);
+    expect(outB).toBe(dirB);
+  });
+});
diff --git a/packages/kaos/test/e2e/exec-edge-cases.test.ts b/packages/kaos/test/e2e/exec-edge-cases.test.ts
new file mode 100644
index 000000000..36f9ed3ee
--- /dev/null
+++ b/packages/kaos/test/e2e/exec-edge-cases.test.ts
@@ -0,0 +1,225 @@
+import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { LocalKaos } from '#/local';
+
+// ── E2E: exec edge cases ──────────────────────────────────────────────
+//
+// Covers exec() scenarios that the other kaos suites do not touch:
+//
+//   - spawning a non-existent command and safely awaiting the error,
+//   - killing a running child with SIGTERM,
+//   - closing stdin while the child is still alive,
+//   - >10MB stdout throughput without dropping or corrupting bytes,
+//   - proving that each LocalKaos instance carries its OWN cwd into
+//     concurrent child processes (isolation invariant).
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+async function streamToString(stream: NodeJS.ReadableStream): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.from(chunk as Buffer));
+  }
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+async function streamByteLength(stream: NodeJS.ReadableStream): Promise<number> {
+  let n = 0;
+  for await (const chunk of stream) {
+    n += (chunk as Buffer).length;
+  }
+  return n;
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────
+
+describe('e2e: exec edge cases', () => {
+  let kaos: LocalKaos;
+  let tempDir: string;
+  let originalCwd: string;
+
+  beforeEach(async () => {
+    kaos = new LocalKaos();
+    originalCwd = process.cwd();
+    tempDir = await realpath(await mkdtemp(join(tmpdir(), 'kaos-exec-edge-')));
+    await kaos.chdir(tempDir);
+  });
+
+  afterEach(async () => {
+    // Restore original cwd in case any test accidentally mutated it
+    // (though LocalKaos should never touch process.cwd()).
+    process.chdir(originalCwd);
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe('spawning a non-existent command', () => {
+    it('exec() rejects promptly when the binary does not exist (never hangs)', async () => {
+      // Contract: LocalKaos.exec() awaits the child's 'spawn' or 'error' event
+      // before returning, so a missing binary becomes a synchronous rejection
+      // rather than a ghost process handle.
+      await expect(kaos.exec('this-binary-does-not-exist-kaos-edge-test-12345')).rejects.toThrow(
+        /ENOENT|ENOTFOUND|not found|spawn/i,
+      );
+    });
+  });
+
+  describe('kill() terminates a running child', () => {
+    it('long-running child can be killed with SIGTERM', async () => {
+      // A node script that sleeps forever.
+      const proc = await kaos.exec('node', '-e', 'setInterval(() => {}, 1000 * 60);');
+
+      expect(proc.pid).toBeGreaterThan(0);
+
+      // Give the child a moment to actually start.
+      await new Promise<void>((r) => setTimeout(r, 20));
+
+      await proc.kill('SIGTERM');
+
+      const exitCode = await proc.wait();
+      // SIGTERM typically produces exitCode = null → -1 under our wrapper,
+      // or 143 (128 + 15). Either way, it must NOT be 0.
+      expect(exitCode).not.toBe(0);
+    });
+
+    it('kill() after the child has already exited is a no-op (no ESRCH leak)', async () => {
+      const proc = await kaos.exec('node', '-e', 'process.exit(0);');
+      const exitCode = await proc.wait();
+      expect(exitCode).toBe(0);
+
+      // Killing an already-exited process must not throw.
+      await expect(proc.kill('SIGTERM')).resolves.toBeUndefined();
+    });
+  });
+
+  describe('stdin lifecycle', () => {
+    it('closing stdin while the child keeps running does not corrupt stdout', async () => {
+      // Child reads stdin until EOF, then emits "done:<bytes>".
+      const proc = await kaos.exec(
+        'node',
+        '-e',
+        `
+          let total = 0;
+          process.stdin.on('data', (chunk) => { total += chunk.length; });
+          process.stdin.on('end', () => {
+            // Intentionally wait before writing, simulating child work
+            // continuing after stdin EOF.
+            setTimeout(() => {
+              process.stdout.write('done:' + total);
+              process.exit(0);
+            }, 20);
+          });
+        `,
+      );
+
+      proc.stdin.write('abc');
+      proc.stdin.write('def');
+      proc.stdin.end();
+
+      const stdout = await streamToString(proc.stdout);
+      const exitCode = await proc.wait();
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toBe('done:6');
+    });
+  });
+
+  describe('large stdout throughput', () => {
+    it('>10MB of stdout streams through without byte loss', async () => {
+      // 10.5MB: 10500 writes of a 1KB payload. Using a tight loop in the
+      // child guarantees the OS pipe buffer gets exercised and we exit
+      // the BufferedReadable backpressure path.
+      const targetKB = 10500;
+      const proc = await kaos.exec(
+        'node',
+        '-e',
+        `
+          const chunk = Buffer.alloc(1024, 0x61); // 1KB of 'a'
+          let written = 0;
+          function tick() {
+            while (written < ${targetKB} - 1) {
+              const ok = process.stdout.write(chunk);
+              written++;
+              if (!ok) {
+                process.stdout.once('drain', tick);
+                return;
+              }
+            }
+            // Final write with callback guarantees bytes are flushed to the
+            // pipe before we exit. Without this, process.exit() races with
+            // the internal libuv write queue and drops the tail.
+            process.stdout.write(chunk, () => process.exit(0));
+          }
+          tick();
+        `,
+      );
+
+      // Read stream and wait concurrently to avoid races where wait() resolves
+      // before the stream pipe has flushed (BufferedReadable continues to
+      // accumulate after the child exits, but the consumer must be drained
+      // explicitly before checking length).
+      const [stdoutLen, exitCode] = await Promise.all([streamByteLength(proc.stdout), proc.wait()]);
+
+      expect(exitCode).toBe(0);
+      expect(stdoutLen).toBe(targetKB * 1024);
+    });
+  });
+
+  describe('cwd isolation for concurrent instances', () => {
+    it('two LocalKaos instances with different cwds run concurrent child processes that each see their own cwd', async () => {
+      const subA = join(tempDir, 'A');
+      const subB = join(tempDir, 'B');
+
+      await kaos.mkdir(subA);
+      await kaos.mkdir(subB);
+
+      const kaosA = new LocalKaos();
+      const kaosB = new LocalKaos();
+      await kaosA.chdir(subA);
+      await kaosB.chdir(subB);
+
+      // Verify process.cwd() is NOT mutated by chdir.
+      expect(process.cwd()).not.toBe(subA);
+      expect(process.cwd()).not.toBe(subB);
+
+      // Run concurrently: each child prints its cwd to stdout.
+      const [procA, procB] = await Promise.all([
+        kaosA.exec('node', '-e', 'process.stdout.write(process.cwd())'),
+        kaosB.exec('node', '-e', 'process.stdout.write(process.cwd())'),
+      ]);
+
+      const [outA, outB, exitA, exitB] = await Promise.all([
+        streamToString(procA.stdout),
+        streamToString(procB.stdout),
+        procA.wait(),
+        procB.wait(),
+      ]);
+
+      expect(exitA).toBe(0);
+      expect(exitB).toBe(0);
+
+      // Each child's cwd MUST equal its kaos instance's cwd.
+      // On macOS `tmpdir()` can be either `/var/folders/...` or
+      // `/private/var/folders/...`. We already realpath'd tempDir so
+      // string equality should hold.
+      expect(outA).toBe(subA);
+      expect(outB).toBe(subB);
+    });
+
+    it('execWithEnv honors the per-instance cwd and injects env vars', async () => {
+      const proc = await kaos.execWithEnv(
+        ['node', '-e', 'process.stdout.write(process.env.KAOS_TEST_MARKER + "|" + process.cwd())'],
+        { KAOS_TEST_MARKER: 'beacon42', PATH: process.env['PATH'] ?? '' },
+      );
+      const stdout = await streamToString(proc.stdout);
+      const exitCode = await proc.wait();
+
+      expect(exitCode).toBe(0);
+      expect(stdout.startsWith('beacon42|')).toBe(true);
+      expect(stdout.endsWith(tempDir)).toBe(true);
+    });
+  });
+});
diff --git a/packages/kaos/test/e2e/glob-boundaries-parity.test.ts b/packages/kaos/test/e2e/glob-boundaries-parity.test.ts
new file mode 100644
index 000000000..18b5b2d71
--- /dev/null
+++ b/packages/kaos/test/e2e/glob-boundaries-parity.test.ts
@@ -0,0 +1,66 @@
+import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { LocalKaos } from '#/local';
+
+describe('e2e: glob parity boundaries', () => {
+  let kaos: LocalKaos;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    kaos = new LocalKaos();
+    tempDir = await realpath(await mkdtemp(join(tmpdir(), 'kaos-glob-')));
+    await kaos.chdir(tempDir);
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('** traverses hidden directories and yields each nested match only once', async () => {
+    await kaos.mkdir(join(tempDir, 'visible', 'nested'), { parents: true });
+    await kaos.mkdir(join(tempDir, '.hidden-root'), { parents: true });
+    await kaos.mkdir(join(tempDir, 'visible', '.hidden-dir'), { parents: true });
+
+    await kaos.writeText(join(tempDir, 'root-visible.txt'), 'root-visible');
+    await kaos.writeText(join(tempDir, '.hidden-root', 'root-hidden.txt'), 'root-hidden');
+    await kaos.writeText(join(tempDir, 'visible', 'nested', 'deep.txt'), 'deep');
+    await kaos.writeText(join(tempDir, 'visible', '.hidden-dir', 'secret.txt'), 'secret');
+    await kaos.writeText(join(tempDir, 'visible', '.hidden-dir', 'skip.log'), 'skip');
+
+    const results: string[] = [];
+    for await (const entry of kaos.glob(tempDir, '**/*.txt')) {
+      results.push(entry);
+    }
+
+    expect(results).toHaveLength(4);
+    expect(new Set(results).size).toBe(4);
+    expect(results).toEqual(
+      expect.arrayContaining([
+        join(tempDir, 'root-visible.txt'),
+        join(tempDir, '.hidden-root', 'root-hidden.txt'),
+        join(tempDir, 'visible', 'nested', 'deep.txt'),
+        join(tempDir, 'visible', '.hidden-dir', 'secret.txt'),
+      ]),
+    );
+    expect(results.some((entry) => entry.endsWith('skip.log'))).toBe(false);
+  });
+
+  it('root-level glob includes hidden dotfiles', async () => {
+    await kaos.writeText(join(tempDir, '.hidden.txt'), 'hidden');
+    await kaos.writeText(join(tempDir, 'visible.txt'), 'visible');
+    await kaos.writeText(join(tempDir, 'visible.log'), 'log');
+
+    const results: string[] = [];
+    for await (const entry of kaos.glob(tempDir, '*.txt')) {
+      results.push(entry);
+    }
+
+    expect(new Set(results)).toEqual(
+      new Set([join(tempDir, '.hidden.txt'), join(tempDir, 'visible.txt')]),
+    );
+  });
+});
diff --git a/packages/kaos/test/e2e/path-cross-platform.test.ts b/packages/kaos/test/e2e/path-cross-platform.test.ts
new file mode 100644
index 000000000..adf845faa
--- /dev/null
+++ b/packages/kaos/test/e2e/path-cross-platform.test.ts
@@ -0,0 +1,297 @@
+import { describe, expect, it } from 'vitest';
+
+import { getCurrentKaos, runWithKaos } from '#/current';
+import type { Kaos } from '#/kaos';
+import { KaosPath } from '#/path';
+import type { KaosProcess } from '#/process';
+import type { StatResult } from '#/types';
+
+// ── Minimal mock Kaos ────────────────────────────────────────────────
+
+function createMockKaos(overrides: Partial<Kaos> & { name: string }): Kaos {
+  const defaults: Kaos = {
+    name: overrides.name,
+    pathClass(): 'posix' | 'win32' {
+      return 'posix';
+    },
+    normpath(path: string): string {
+      return path;
+    },
+    gethome(): string {
+      return '/default/home';
+    },
+    getcwd(): string {
+      return '/default/cwd';
+    },
+    async chdir(): Promise<void> {
+      // no-op
+    },
+    async stat(): Promise<StatResult> {
+      return {
+        stMode: 0,
+        stIno: 0,
+        stDev: 0,
+        stNlink: 0,
+        stUid: 0,
+        stGid: 0,
+        stSize: 0,
+        stAtime: 0,
+        stMtime: 0,
+        stCtime: 0,
+      };
+    },
+    async *iterdir(): AsyncGenerator<string> {
+      // empty
+    },
+    async *glob(): AsyncGenerator<string> {
+      // empty
+    },
+    async readBytes(): Promise<Buffer> {
+      return Buffer.alloc(0);
+    },
+    async readText(): Promise<string> {
+      return '';
+    },
+    async *readLines(): AsyncGenerator<string> {
+      // empty
+    },
+    async writeBytes(): Promise<number> {
+      return 0;
+    },
+    async writeText(): Promise<number> {
+      return 0;
+    },
+    async mkdir(): Promise<void> {
+      // no-op
+    },
+    async exec(): Promise<KaosProcess> {
+      throw new Error('Not implemented');
+    },
+    async execWithEnv(): Promise<KaosProcess> {
+      throw new Error('Not implemented');
+    },
+  };
+
+  return { ...defaults, ...overrides };
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe('e2e: KaosPath cross-platform', () => {
+  describe('expanduser delegates to kaos.gethome()', () => {
+    it('~ expands to custom home from mock Kaos', () => {
+      const mockKaos = createMockKaos({
+        name: 'custom-home',
+        gethome(): string {
+          return '/custom/home';
+        },
+      });
+
+      const result = runWithKaos(mockKaos, () => {
+        return new KaosPath('~').expanduser().toString();
+      });
+
+      expect(result).toBe('/custom/home');
+    });
+
+    it('~/subpath expands correctly', () => {
+      const mockKaos = createMockKaos({
+        name: 'custom-home-sub',
+        gethome(): string {
+          return '/users/testuser';
+        },
+      });
+
+      const result = runWithKaos(mockKaos, () => {
+        return new KaosPath('~/Documents/file.txt').expanduser().toString();
+      });
+
+      expect(result).toBe('/users/testuser/Documents/file.txt');
+    });
+
+    it('non-tilde path is unchanged', () => {
+      const mockKaos = createMockKaos({
+        name: 'no-expand',
+        gethome(): string {
+          return '/should/not/appear';
+        },
+      });
+
+      const result = runWithKaos(mockKaos, () => {
+        return new KaosPath('/absolute/path').expanduser().toString();
+      });
+
+      expect(result).toBe('/absolute/path');
+    });
+  });
+
+  describe('canonical uses correct path module', () => {
+    it('posix pathClass uses posix rules', () => {
+      const mockKaos = createMockKaos({
+        name: 'posix-canonical',
+        pathClass(): 'posix' | 'win32' {
+          return 'posix';
+        },
+        getcwd(): string {
+          return '/home/user/project';
+        },
+      });
+
+      const result = runWithKaos(mockKaos, () => {
+        return new KaosPath('src/../lib/utils.ts').canonical().toString();
+      });
+
+      // posix normalize of /home/user/project/src/../lib/utils.ts
+      expect(result).toBe('/home/user/project/lib/utils.ts');
+    });
+
+    it('absolute path is normalized without prepending cwd', () => {
+      const mockKaos = createMockKaos({
+        name: 'abs-canonical',
+        pathClass(): 'posix' | 'win32' {
+          return 'posix';
+        },
+        getcwd(): string {
+          return '/should/not/appear';
+        },
+      });
+
+      const result = runWithKaos(mockKaos, () => {
+        return new KaosPath('/a/b/../c/./d').canonical().toString();
+      });
+
+      expect(result).toBe('/a/c/d');
+    });
+
+    it('relative path is resolved against cwd', () => {
+      const mockKaos = createMockKaos({
+        name: 'rel-canonical',
+        pathClass(): 'posix' | 'win32' {
+          return 'posix';
+        },
+        getcwd(): string {
+          return '/workspace';
+        },
+      });
+
+      const result = runWithKaos(mockKaos, () => {
+        return new KaosPath('src/main.ts').canonical().toString();
+      });
+
+      expect(result).toBe('/workspace/src/main.ts');
+    });
+  });
+
+  describe('runWithKaos concurrent isolation', () => {
+    it('concurrent runWithKaos calls return their own Kaos instances', async () => {
+      const kaos1 = createMockKaos({
+        name: 'kaos-1',
+        gethome(): string {
+          return '/home/user1';
+        },
+      });
+
+      const kaos2 = createMockKaos({
+        name: 'kaos-2',
+        gethome(): string {
+          return '/home/user2';
+        },
+      });
+
+      const results = await Promise.all([
+        new Promise<{ name: string; home: string }>((resolve) => {
+          runWithKaos(kaos1, () => {
+            // Small delay to ensure overlap
+            setTimeout(() => {
+              const current = getCurrentKaos();
+              resolve({
+                name: current.name,
+                home: current.gethome(),
+              });
+            }, 10);
+          });
+        }),
+        new Promise<{ name: string; home: string }>((resolve) => {
+          runWithKaos(kaos2, () => {
+            setTimeout(() => {
+              const current = getCurrentKaos();
+              resolve({
+                name: current.name,
+                home: current.gethome(),
+              });
+            }, 10);
+          });
+        }),
+      ]);
+
+      expect(results[0].name).toBe('kaos-1');
+      expect(results[0].home).toBe('/home/user1');
+      expect(results[1].name).toBe('kaos-2');
+      expect(results[1].home).toBe('/home/user2');
+    });
+
+    it('nested runWithKaos scopes correctly', () => {
+      const outerKaos = createMockKaos({
+        name: 'outer',
+        gethome(): string {
+          return '/outer/home';
+        },
+      });
+
+      const innerKaos = createMockKaos({
+        name: 'inner',
+        gethome(): string {
+          return '/inner/home';
+        },
+      });
+
+      const outerHome = runWithKaos(outerKaos, () => {
+        const before = getCurrentKaos().gethome();
+
+        const innerHome = runWithKaos(innerKaos, () => {
+          return getCurrentKaos().gethome();
+        });
+
+        const after = getCurrentKaos().gethome();
+
+        return { before, innerHome, after };
+      });
+
+      expect(outerHome.before).toBe('/outer/home');
+      expect(outerHome.innerHome).toBe('/inner/home');
+      expect(outerHome.after).toBe('/outer/home');
+    });
+  });
+
+  describe('KaosPath static methods via mock', () => {
+    it('KaosPath.home() delegates to getCurrentKaos', () => {
+      const mockKaos = createMockKaos({
+        name: 'static-home',
+        gethome(): string {
+          return '/mock/home/dir';
+        },
+      });
+
+      const result = runWithKaos(mockKaos, () => {
+        return KaosPath.home().toString();
+      });
+
+      expect(result).toBe('/mock/home/dir');
+    });
+
+    it('KaosPath.cwd() delegates to getCurrentKaos', () => {
+      const mockKaos = createMockKaos({
+        name: 'static-cwd',
+        getcwd(): string {
+          return '/mock/working/dir';
+        },
+      });
+
+      const result = runWithKaos(mockKaos, () => {
+        return KaosPath.cwd().toString();
+      });
+
+      expect(result).toBe('/mock/working/dir');
+    });
+  });
+});
diff --git a/packages/kaos/test/e2e/process-lifecycle.test.ts b/packages/kaos/test/e2e/process-lifecycle.test.ts
new file mode 100644
index 000000000..54347eaca
--- /dev/null
+++ b/packages/kaos/test/e2e/process-lifecycle.test.ts
@@ -0,0 +1,342 @@
+import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { LocalKaos } from '#/local';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+// ── Helper ────────────────────────────────────────────────────────────
+
+async function streamToBuffer(stream: NodeJS.ReadableStream): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.from(chunk as Buffer));
+  }
+  return Buffer.concat(chunks);
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────
+
+describe('e2e: process lifecycle', () => {
+  let kaos: LocalKaos;
+  let tempDir: string;
+  let originalCwd: string;
+
+  beforeEach(async () => {
+    kaos = new LocalKaos();
+    originalCwd = process.cwd();
+    tempDir = await realpath(await mkdtemp(join(tmpdir(), 'kaos-proc-')));
+    process.chdir(tempDir);
+  });
+
+  afterEach(async () => {
+    process.chdir(originalCwd);
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe('stdin → stdout → wait → exitCode', () => {
+    it('write to stdin, read from stdout, wait for exit', async () => {
+      // Node script that reads stdin and echoes it to stdout
+      const code = `
+        let data = '';
+        process.stdin.setEncoding('utf-8');
+        process.stdin.on('data', (chunk) => { data += chunk; });
+        process.stdin.on('end', () => {
+          process.stdout.write('echo:' + data);
+        });
+      `;
+      const proc = await kaos.exec('node', '-e', code);
+
+      // Write to stdin
+      proc.stdin.write('hello from test');
+      proc.stdin.end();
+
+      // Wait for process to complete
+      const exitCode = await proc.wait();
+      expect(exitCode).toBe(0);
+
+      // Read stdout
+      const stdout = await streamToBuffer(proc.stdout);
+      expect(stdout.toString('utf-8')).toBe('echo:hello from test');
+    });
+
+    it('multiple stdin writes before end', async () => {
+      const code = `
+        let data = '';
+        process.stdin.setEncoding('utf-8');
+        process.stdin.on('data', (chunk) => { data += chunk; });
+        process.stdin.on('end', () => {
+          process.stdout.write(data.toUpperCase());
+        });
+      `;
+      const proc = await kaos.exec('node', '-e', code);
+
+      proc.stdin.write('hello ');
+      proc.stdin.write('world ');
+      proc.stdin.write('test');
+      proc.stdin.end();
+
+      const exitCode = await proc.wait();
+      expect(exitCode).toBe(0);
+
+      const stdout = await streamToBuffer(proc.stdout);
+      expect(stdout.toString('utf-8')).toBe('HELLO WORLD TEST');
+    });
+
+    it('exitCode is null before wait, correct after wait', async () => {
+      const proc = await kaos.exec('node', '-e', 'process.exit(42)');
+
+      // Before wait, exitCode may be null
+      // (it could also be set if process is very fast, so we just check after wait)
+      const exitCode = await proc.wait();
+      expect(exitCode).toBe(42);
+      expect(proc.exitCode).toBe(42);
+    });
+  });
+
+  describe('long-running process → kill', () => {
+    it('start → verify running → kill → confirm exit', async () => {
+      // Process that runs indefinitely
+      const code = `
+        process.stdout.write('started\\n');
+        setInterval(() => {}, 1000);
+      `;
+      const proc = await kaos.exec('node', '-e', code);
+
+      expect(proc.pid).toBeGreaterThan(0);
+
+      // Kill it
+      await proc.kill('SIGTERM');
+
+      const exitCode = await proc.wait();
+      // On SIGTERM, node typically exits with non-zero
+      expect(typeof exitCode).toBe('number');
+    });
+
+    it('kill with SIGKILL → immediate termination', async () => {
+      const code = `
+        // Trap SIGTERM to test that SIGKILL forces exit
+        process.on('SIGTERM', () => { /* ignore */ });
+        process.stdout.write('alive\\n');
+        setInterval(() => {}, 1000);
+      `;
+      const proc = await kaos.exec('node', '-e', code);
+
+      await proc.kill('SIGKILL');
+      const exitCode = await proc.wait();
+
+      // SIGKILL cannot be caught - process is terminated
+      expect(exitCode).not.toBe(0);
+    });
+
+    it('multiple wait() calls return same exit code', async () => {
+      const proc = await kaos.exec('node', '-e', 'process.exit(7)');
+
+      const code1 = await proc.wait();
+      const code2 = await proc.wait();
+      const code3 = await proc.wait();
+
+      expect(code1).toBe(7);
+      expect(code2).toBe(7);
+      expect(code3).toBe(7);
+    });
+  });
+
+  describe('stdin close → natural exit', () => {
+    it('closing stdin causes stdin-reading process to exit naturally', async () => {
+      // Process that exits when stdin closes
+      const code = `
+        process.stdin.resume();
+        process.stdin.on('end', () => {
+          process.stdout.write('stdin closed');
+          process.exit(0);
+        });
+      `;
+      const proc = await kaos.exec('node', '-e', code);
+
+      // Close stdin immediately
+      proc.stdin.end();
+
+      const exitCode = await proc.wait();
+      expect(exitCode).toBe(0);
+
+      const stdout = await streamToBuffer(proc.stdout);
+      expect(stdout.toString('utf-8')).toBe('stdin closed');
+    });
+
+    it('cat-like process exits when stdin is closed', async () => {
+      const code = `
+        process.stdin.setEncoding('utf-8');
+        process.stdin.on('data', (chunk) => {
+          process.stdout.write(chunk);
+        });
+        process.stdin.on('end', () => {
+          process.exit(0);
+        });
+      `;
+      const proc = await kaos.exec('node', '-e', code);
+
+      proc.stdin.write('line1\n');
+      proc.stdin.write('line2\n');
+      proc.stdin.end();
+
+      const exitCode = await proc.wait();
+      expect(exitCode).toBe(0);
+
+      const stdout = await streamToBuffer(proc.stdout);
+      expect(stdout.toString('utf-8')).toBe('line1\nline2\n');
+    });
+  });
+
+  describe('process.pid validity', () => {
+    it('pid is a positive integer', async () => {
+      const proc = await kaos.exec('node', '-e', 'process.exit(0)');
+      expect(proc.pid).toBeGreaterThan(0);
+      expect(Number.isInteger(proc.pid)).toBe(true);
+
+      await proc.wait();
+    });
+
+    it('different processes have different pids', async () => {
+      const proc1 = await kaos.exec('node', '-e', 'process.exit(0)');
+      const proc2 = await kaos.exec('node', '-e', 'process.exit(0)');
+
+      expect(proc1.pid).not.toBe(proc2.pid);
+
+      await Promise.all([proc1.wait(), proc2.wait()]);
+    });
+
+    it('pid matches the actual child process pid', async () => {
+      // Have the child process report its own pid
+      const code = `process.stdout.write(String(process.pid))`;
+      const proc = await kaos.exec('node', '-e', code);
+      await proc.wait();
+
+      const stdout = await streamToBuffer(proc.stdout);
+      const reportedPid = Number(stdout.toString('utf-8'));
+
+      expect(proc.pid).toBe(reportedPid);
+    });
+  });
+
+  describe('exec failure (command not found)', () => {
+    it('non-existent command → error on wait()', async () => {
+      // exec() itself may succeed (spawn returns) but wait() should
+      // report the error or the process should fail
+      try {
+        const proc = await kaos.exec('this-command-absolutely-does-not-exist-xyz-123');
+        // If exec resolves, wait should give a rejection
+        await expect(proc.wait()).rejects.toThrow();
+      } catch (error: unknown) {
+        // If exec itself throws, that's also acceptable
+        expect(error).toBeInstanceOf(Error);
+      }
+    });
+
+    it('exec with empty arguments rejects', async () => {
+      // exec() is now async, so validation errors (missing command) surface
+      // as rejected promises rather than synchronous throws.
+      await expect(kaos.exec()).rejects.toThrow(/at least one argument/);
+    });
+  });
+
+  describe('execWithEnv', () => {
+    it('passes custom environment variables to the child process', async () => {
+      const code = `process.stdout.write(process.env.MY_VAR || 'undefined')`;
+      const proc = await kaos.execWithEnv(['node', '-e', code], {
+        ...(process.env as Record<string, string>),
+        MY_VAR: 'test-value-123',
+      });
+      const exitCode = await proc.wait();
+      expect(exitCode).toBe(0);
+
+      const stdout = await streamToBuffer(proc.stdout);
+      expect(stdout.toString('utf-8')).toBe('test-value-123');
+    });
+
+    it('custom env overrides specific variables', async () => {
+      // Passing a custom env with PATH so node can still run,
+      // but with a custom variable that overrides a default one.
+      const code = `process.stdout.write(process.env.MY_CUSTOM || 'missing')`;
+      const proc = await kaos.execWithEnv(['node', '-e', code], {
+        PATH: process.env['PATH'] ?? '',
+        MY_CUSTOM: 'overridden-value',
+      });
+      const exitCode = await proc.wait();
+      expect(exitCode).toBe(0);
+
+      const stdout = await streamToBuffer(proc.stdout);
+      expect(stdout.toString('utf-8')).toBe('overridden-value');
+    });
+  });
+
+  describe('process output ordering', () => {
+    it('stdout preserves line order for sequential writes', async () => {
+      const code = `
+        for (let i = 0; i < 100; i++) {
+          process.stdout.write(i + '\\n');
+        }
+      `;
+      const proc = await kaos.exec('node', '-e', code);
+      const exitCode = await proc.wait();
+      expect(exitCode).toBe(0);
+
+      const stdout = await streamToBuffer(proc.stdout);
+      const lines = stdout.toString('utf-8').trimEnd().split('\n');
+
+      expect(lines).toHaveLength(100);
+      for (let i = 0; i < 100; i++) {
+        expect(lines[i]).toBe(String(i));
+      }
+    });
+
+    it('stderr preserves line order for sequential writes', async () => {
+      const code = `
+        for (let i = 0; i < 50; i++) {
+          process.stderr.write('err-' + i + '\\n');
+        }
+      `;
+      const proc = await kaos.exec('node', '-e', code);
+      const exitCode = await proc.wait();
+      expect(exitCode).toBe(0);
+
+      const stderr = await streamToBuffer(proc.stderr);
+      const lines = stderr.toString('utf-8').trimEnd().split('\n');
+
+      expect(lines).toHaveLength(50);
+      for (let i = 0; i < 50; i++) {
+        expect(lines[i]).toBe(`err-${i}`);
+      }
+    });
+  });
+
+  describe('process exit codes', () => {
+    it('exit code 0 for successful process', async () => {
+      const proc = await kaos.exec('node', '-e', 'process.exit(0)');
+      expect(await proc.wait()).toBe(0);
+    });
+
+    it('exit code 1 for generic failure', async () => {
+      const proc = await kaos.exec('node', '-e', 'process.exit(1)');
+      expect(await proc.wait()).toBe(1);
+    });
+
+    it('custom exit codes (2, 42, 127, 255)', async () => {
+      for (const code of [2, 42, 127, 255]) {
+        const proc = await kaos.exec('node', '-e', `process.exit(${code})`);
+        expect(await proc.wait()).toBe(code);
+      }
+    });
+
+    it('uncaught exception results in exit code 1', async () => {
+      const code = `throw new Error('uncaught')`;
+      const proc = await kaos.exec('node', '-e', code);
+      const exitCode = await proc.wait();
+      expect(exitCode).toBe(1);
+
+      // stderr should contain the error message
+      const stderr = await streamToBuffer(proc.stderr);
+      expect(stderr.toString('utf-8')).toContain('uncaught');
+    });
+  });
+});
diff --git a/packages/kaos/test/e2e/ssh-mock.test.ts b/packages/kaos/test/e2e/ssh-mock.test.ts
new file mode 100644
index 000000000..a3b66ed41
--- /dev/null
+++ b/packages/kaos/test/e2e/ssh-mock.test.ts
@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest';
+
+// ── Tests: SSHKaos parameter validation ──────────────────────────────
+//
+// SSHKaos.create() requires a live SSH connection to proceed past
+// connectClient(). These tests verify the parameter validation and
+// shell quoting logic without needing a real SSH server.
+
+describe('e2e: SSH mock tests', () => {
+  describe('SSHKaos.create() parameter validation', () => {
+    it('missing host -> connect attempt with empty host', async () => {
+      // SSHKaos.create() passes the host directly to ssh2's connect().
+      // With an empty/undefined host, ssh2 will fail to connect.
+      // We verify the error is thrown.
+      const { SSHKaos } = await import('#/ssh');
+
+      await expect(
+        SSHKaos.create({
+          host: '',
+          username: 'testuser',
+        }),
+      ).rejects.toThrow();
+    });
+
+    it('missing username -> connect attempt with empty username', async () => {
+      const { SSHKaos } = await import('#/ssh');
+
+      await expect(
+        SSHKaos.create({
+          host: '127.0.0.1',
+          port: 99999, // Use an unlikely port to ensure fast failure
+          username: '',
+        }),
+      ).rejects.toThrow();
+    });
+
+    it('invalid port -> connection error', async () => {
+      const { SSHKaos } = await import('#/ssh');
+
+      // Port 1 is unlikely to have an SSH server; should fail quickly
+      await expect(
+        SSHKaos.create({
+          host: '127.0.0.1',
+          port: 1,
+          username: 'testuser',
+        }),
+      ).rejects.toThrow();
+    });
+  });
+
+  describe('shell quoting logic', () => {
+    // We test the shellQuote function indirectly by examining its behavior.
+    // The function is not exported, but we can verify its contract:
+    // - Empty string -> ''
+    // - Safe chars -> unchanged
+    // - Special chars -> single-quoted with embedded quote escaping
+
+    it('shellQuote rules verified via regex match', () => {
+      // The shellQuote regex for safe chars: /^[A-Za-z0-9_./:=@%^,+-]+$/
+      const safeRegex = /^[A-Za-z0-9_./:=@%^,+-]+$/;
+
+      // These should be considered safe (no quoting needed)
+      expect(safeRegex.test('simple')).toBe(true);
+      expect(safeRegex.test('/usr/bin/node')).toBe(true);
+      expect(safeRegex.test('key=value')).toBe(true);
+      expect(safeRegex.test('file.txt')).toBe(true);
+
+      // These should need quoting
+      expect(safeRegex.test('')).toBe(false);
+      expect(safeRegex.test('hello world')).toBe(false);
+      expect(safeRegex.test("it's")).toBe(false);
+      expect(safeRegex.test('$HOME')).toBe(false);
+      expect(safeRegex.test('a|b')).toBe(false);
+      expect(safeRegex.test('a"b')).toBe(false);
+      expect(safeRegex.test('a;b')).toBe(false);
+      expect(safeRegex.test('a&b')).toBe(false);
+      expect(safeRegex.test('a`b')).toBe(false);
+    });
+
+    it('shellQuote single-quote escaping pattern is correct', () => {
+      // shellQuote wraps in single quotes, replacing ' with '"'"'
+      // Verify the pattern: 'text'"'"'more' handles embedded quotes
+      const input = "it's a test";
+      const escaped = "'" + input.replaceAll("'", "'\"'\"'") + "'";
+
+      expect(escaped).toBe("'it'\"'\"'s a test'");
+      // This should be safe to use in a shell command
+      expect(escaped).toContain("'\"'\"'");
+    });
+
+    it('special characters that need quoting', () => {
+      const specialChars = [' ', "'", '"', '$', '|', '&', ';', '`', '(', ')', '{', '}', '<', '>'];
+      const safeRegex = /^[A-Za-z0-9_./:=@%^,+-]+$/;
+
+      for (const ch of specialChars) {
+        expect(safeRegex.test(`arg${ch}value`)).toBe(false);
+      }
+    });
+
+    it('empty string quoting produces two single quotes', () => {
+      // shellQuote('') should return "''"
+      const emptyQuoted = "''";
+      expect(emptyQuoted).toBe("''");
+      expect(emptyQuoted.length).toBe(2);
+    });
+  });
+
+  describe('SSHKaosOptions type constraints', () => {
+    it('options structure has required fields', () => {
+      // Verify at compile time and runtime that SSHKaosOptions
+      // requires host and username
+      const validOptions = {
+        host: 'example.com',
+        username: 'user',
+      };
+
+      expect(validOptions.host).toBe('example.com');
+      expect(validOptions.username).toBe('user');
+    });
+
+    it('options with all optional fields', () => {
+      const fullOptions = {
+        host: 'example.com',
+        port: 2222,
+        username: 'user',
+        password: 'pass',
+        keyPaths: ['/path/to/key'],
+        keyContents: ['ssh-rsa AAAA...'],
+        cwd: '/home/user',
+      };
+
+      expect(fullOptions.port).toBe(2222);
+      expect(fullOptions.password).toBe('pass');
+      expect(fullOptions.keyPaths).toHaveLength(1);
+      expect(fullOptions.keyContents).toHaveLength(1);
+      expect(fullOptions.cwd).toBe('/home/user');
+    });
+  });
+});
diff --git a/packages/kaos/test/e2e/ssh-resolve-path.test.ts b/packages/kaos/test/e2e/ssh-resolve-path.test.ts
new file mode 100644
index 000000000..a9623414f
--- /dev/null
+++ b/packages/kaos/test/e2e/ssh-resolve-path.test.ts
@@ -0,0 +1,450 @@
+import type { Client, SFTPWrapper, Stats as SFTPStats } from 'ssh2';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { KaosFileExistsError } from '#/errors';
+import { KaosFileNotFoundError, SSHKaos } from '#/ssh';
+
+// ── SSH path resolution: mock SFTP harness ────────────────────────────
+//
+// This test file validates that SSHKaos file/dir operations correctly
+// resolve *relative* paths against the instance's current working
+// directory (`_cwd`) before handing the path off to SFTP.
+//
+// We mock the underlying `SFTPWrapper` so no network traffic is needed.
+// Every SFTP method (readFile, writeFile, stat, lstat, mkdir, appendFile,
+// exists, readdir, realpath) records the absolute path it receives, and
+// returns a deterministic response. After each SSHKaos operation we
+// inspect the recorded path to ensure the resolution worked.
+//
+// The private SSHKaos constructor is bypassed via `Reflect.construct` —
+// TypeScript `private` is compile-time only, and we need a test-only
+// instance that is not backed by a real SSH connection.
+
+// ── Mock helpers ──────────────────────────────────────────────────────
+
+interface MockSFTP {
+  calls: { method: string; path: string; data?: string | Buffer }[];
+  files: Map<string, Buffer>;
+  dirs: Set<string>;
+  mkdirFailures: Map<string, { error: Error; materializeAs: 'dir' | 'file' }>;
+}
+
+function makeMockStats(isDir: boolean, size: number = 0): SFTPStats {
+  return {
+    mode: isDir ? 0o040755 : 0o100644,
+    uid: 1000,
+    gid: 1000,
+    size,
+    atime: 0,
+    mtime: 0,
+    isDirectory: () => isDir,
+    isFile: () => !isDir,
+    isSymbolicLink: () => false,
+    isSocket: () => false,
+    isCharacterDevice: () => false,
+    isBlockDevice: () => false,
+    isFIFO: () => false,
+  } as unknown as SFTPStats;
+}
+
+function createMockSftp(state: MockSFTP): SFTPWrapper {
+  // Only stub the SFTP methods used by the tests below.
+  const sftp = {
+    realpath(path: string, cb: (err: unknown, absPath: string) => void): void {
+      state.calls.push({ method: 'realpath', path });
+      // Mock realpath: if path is already absolute, echo it.
+      // Otherwise it would be relative — but since SSHKaos always
+      // resolves first, we should never see a relative input here.
+      cb(null, path);
+    },
+    stat(path: string, cb: (err: unknown, stats: SFTPStats) => void): void {
+      state.calls.push({ method: 'stat', path });
+      if (state.dirs.has(path)) {
+        cb(null, makeMockStats(true));
+        return;
+      }
+      const buf = state.files.get(path);
+      if (buf !== undefined) {
+        cb(null, makeMockStats(false, buf.length));
+        return;
+      }
+      // Missing — surface an ENOENT-shaped error.
+      const err = Object.assign(new Error(`ENOENT: ${path}`), { code: 2 });
+      cb(err, undefined as unknown as SFTPStats);
+    },
+    lstat(path: string, cb: (err: unknown, stats: SFTPStats) => void): void {
+      state.calls.push({ method: 'lstat', path });
+      sftp.stat(path, cb);
+    },
+    readFile(path: string, cb: (err: unknown, data: Buffer) => void): void {
+      state.calls.push({ method: 'readFile', path });
+      const buf = state.files.get(path);
+      if (buf === undefined) {
+        cb(new Error(`ENOENT: ${path}`), Buffer.alloc(0));
+        return;
+      }
+      cb(null, buf);
+    },
+    writeFile(path: string, data: string | Buffer, cb: (err: unknown) => void): void {
+      state.calls.push({ method: 'writeFile', path, data });
+      const buf = typeof data === 'string' ? Buffer.from(data) : data;
+      state.files.set(path, buf);
+      cb(null);
+    },
+    appendFile(path: string, data: string | Buffer, cb: (err: unknown) => void): void {
+      state.calls.push({ method: 'appendFile', path, data });
+      const buf = typeof data === 'string' ? Buffer.from(data) : data;
+      const existing = state.files.get(path) ?? Buffer.alloc(0);
+      state.files.set(path, Buffer.concat([existing, buf]));
+      cb(null);
+    },
+    exists(path: string, cb: (exists: boolean) => void): void {
+      state.calls.push({ method: 'exists', path });
+      cb(state.files.has(path) || state.dirs.has(path));
+    },
+    mkdir(path: string, cb: (err: unknown) => void): void {
+      state.calls.push({ method: 'mkdir', path });
+      const failure = state.mkdirFailures.get(path);
+      if (failure) {
+        if (failure.materializeAs === 'dir') {
+          state.dirs.add(path);
+        } else {
+          state.files.set(path, Buffer.from('collision'));
+        }
+        cb(failure.error);
+        return;
+      }
+      state.dirs.add(path);
+      cb(null);
+    },
+    readdir(
+      path: string,
+      cb: (err: unknown, list: { filename: string; attrs: SFTPStats }[]) => void,
+    ): void {
+      state.calls.push({ method: 'readdir', path });
+      // Return empty listing for simplicity.
+      cb(null, []);
+    },
+    end(): void {
+      // no-op
+    },
+  };
+  return sftp as unknown as SFTPWrapper;
+}
+
+function createMockClient(): Client {
+  return {
+    end(): void {
+      // no-op
+    },
+  } as unknown as Client;
+}
+
+/**
+ * Construct an SSHKaos with the private constructor bypassed. TS
+ * `private` is compile-time only — runtime reflection works. We use
+ * `Reflect.construct` to hand-build an instance seeded with the mock
+ * SFTP wrapper and a chosen home/cwd.
+ */
+function createMockedKaos(sftp: SFTPWrapper, home: string, cwd: string): SSHKaos {
+  const client = createMockClient();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const CtorAny = SSHKaos as any;
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+  return new CtorAny(client, sftp, home, cwd) as SSHKaos;
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────
+
+describe('e2e: SSHKaos relative path resolution after chdir (mocked SFTP)', () => {
+  let state: MockSFTP;
+  let sftp: SFTPWrapper;
+  let kaos: SSHKaos;
+
+  beforeEach(() => {
+    state = {
+      calls: [],
+      files: new Map<string, Buffer>(),
+      dirs: new Set<string>(),
+      mkdirFailures: new Map<string, { error: Error; materializeAs: 'dir' | 'file' }>(),
+    };
+    sftp = createMockSftp(state);
+    kaos = createMockedKaos(sftp, '/home/user', '/home/user');
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('readText / readBytes / readLines', () => {
+    it('readText resolves relative path against current cwd', async () => {
+      // chdir to /remote/tmp; relative "file.txt" must resolve to /remote/tmp/file.txt.
+      state.dirs.add('/remote/tmp');
+      await kaos.chdir('/remote/tmp');
+
+      state.files.set('/remote/tmp/file.txt', Buffer.from('hello'));
+
+      const text = await kaos.readText('file.txt');
+      expect(text).toBe('hello');
+
+      // Verify the SFTP readFile call received the absolute resolved path.
+      const readCalls = state.calls.filter((c) => c.method === 'readFile');
+      expect(readCalls).toHaveLength(1);
+      expect(readCalls[0]!.path).toBe('/remote/tmp/file.txt');
+    });
+
+    it('readText accepts absolute path unchanged', async () => {
+      state.dirs.add('/remote/tmp');
+      await kaos.chdir('/remote/tmp');
+      state.files.set('/etc/hosts', Buffer.from('127.0.0.1 localhost'));
+
+      const text = await kaos.readText('/etc/hosts');
+      expect(text).toBe('127.0.0.1 localhost');
+
+      const readCalls = state.calls.filter((c) => c.method === 'readFile');
+      expect(readCalls.some((c) => c.path === '/etc/hosts')).toBe(true);
+      // And NOT /remote/tmp/etc/hosts
+      expect(readCalls.some((c) => c.path === '/remote/tmp/etc/hosts')).toBe(false);
+    });
+
+    it('readBytes resolves relative path against current cwd', async () => {
+      state.dirs.add('/opt/data');
+      await kaos.chdir('/opt/data');
+      state.files.set('/opt/data/blob.bin', Buffer.from([1, 2, 3, 4]));
+
+      const bytes = await kaos.readBytes('blob.bin');
+      expect(Array.from(bytes)).toEqual([1, 2, 3, 4]);
+
+      const readCalls = state.calls.filter((c) => c.method === 'readFile');
+      expect(readCalls.some((c) => c.path === '/opt/data/blob.bin')).toBe(true);
+    });
+
+    it('readLines resolves relative path against current cwd', async () => {
+      state.dirs.add('/var/log');
+      await kaos.chdir('/var/log');
+      state.files.set('/var/log/app.log', Buffer.from('line1\nline2\nline3'));
+
+      const lines: string[] = [];
+      for await (const line of kaos.readLines('app.log')) {
+        lines.push(line);
+      }
+      expect(lines).toEqual(['line1', 'line2', 'line3']);
+
+      const readCalls = state.calls.filter((c) => c.method === 'readFile');
+      expect(readCalls.some((c) => c.path === '/var/log/app.log')).toBe(true);
+    });
+
+    it('readLines strips CRLF terminators', async () => {
+      state.dirs.add('/var/log');
+      await kaos.chdir('/var/log');
+      state.files.set('/var/log/app-crlf.log', Buffer.from('line1\r\nline2\r\n'));
+
+      const lines: string[] = [];
+      for await (const line of kaos.readLines('app-crlf.log')) {
+        lines.push(line);
+      }
+
+      expect(lines).toEqual(['line1', 'line2']);
+    });
+  });
+
+  describe('writeText / writeBytes / appendFile', () => {
+    it('writeText resolves relative path against current cwd', async () => {
+      state.dirs.add('/workspace');
+      await kaos.chdir('/workspace');
+
+      const n = await kaos.writeText('out.txt', 'hello world');
+      expect(n).toBe('hello world'.length);
+
+      const writeCalls = state.calls.filter((c) => c.method === 'writeFile');
+      expect(writeCalls).toHaveLength(1);
+      expect(writeCalls[0]!.path).toBe('/workspace/out.txt');
+
+      // Mock file store now contains the file at the resolved path.
+      expect(state.files.get('/workspace/out.txt')?.toString('utf-8')).toBe('hello world');
+    });
+
+    it('writeBytes resolves relative path against current cwd', async () => {
+      state.dirs.add('/workspace');
+      await kaos.chdir('/workspace');
+
+      const data = Buffer.from([0xde, 0xad, 0xbe, 0xef]);
+      const n = await kaos.writeBytes('blob.bin', data);
+      expect(n).toBe(4);
+
+      const writeCalls = state.calls.filter((c) => c.method === 'writeFile');
+      expect(writeCalls).toHaveLength(1);
+      expect(writeCalls[0]!.path).toBe('/workspace/blob.bin');
+    });
+
+    it('writeText with mode=a uses appendFile and resolves path', async () => {
+      state.dirs.add('/logs');
+      await kaos.chdir('/logs');
+
+      await kaos.writeText('a.log', 'line1\n', { mode: 'a' });
+      await kaos.writeText('a.log', 'line2\n', { mode: 'a' });
+
+      const appendCalls = state.calls.filter((c) => c.method === 'appendFile');
+      expect(appendCalls).toHaveLength(2);
+      expect(appendCalls[0]!.path).toBe('/logs/a.log');
+      expect(appendCalls[1]!.path).toBe('/logs/a.log');
+
+      expect(state.files.get('/logs/a.log')?.toString('utf-8')).toBe('line1\nline2\n');
+    });
+  });
+
+  describe('stat / mkdir', () => {
+    it('stat resolves relative path against current cwd', async () => {
+      state.dirs.add('/srv');
+      await kaos.chdir('/srv');
+      state.files.set('/srv/config.json', Buffer.from('{}'));
+
+      const result = await kaos.stat('config.json');
+      expect(result.stSize).toBe(2);
+
+      const statCalls = state.calls.filter((c) => c.method === 'stat');
+      expect(statCalls.some((c) => c.path === '/srv/config.json')).toBe(true);
+    });
+
+    it('stat preserves NO_SUCH_FILE as KaosFileNotFoundError', async () => {
+      state.dirs.add('/srv');
+      await kaos.chdir('/srv');
+
+      await expect(kaos.stat('missing.json')).rejects.toBeInstanceOf(KaosFileNotFoundError);
+      await expect(kaos.stat('missing.json')).rejects.toMatchObject({ code: 2 });
+    });
+
+    it('stat with followSymlinks=false uses lstat and resolves path', async () => {
+      state.dirs.add('/srv');
+      await kaos.chdir('/srv');
+      state.files.set('/srv/link', Buffer.from('data'));
+
+      await kaos.stat('link', { followSymlinks: false });
+
+      const lstatCalls = state.calls.filter((c) => c.method === 'lstat');
+      expect(lstatCalls).toHaveLength(1);
+      expect(lstatCalls[0]!.path).toBe('/srv/link');
+    });
+
+    it('mkdir resolves relative path against current cwd', async () => {
+      state.dirs.add('/workspace');
+      await kaos.chdir('/workspace');
+
+      await kaos.mkdir('newdir');
+
+      const mkdirCalls = state.calls.filter((c) => c.method === 'mkdir');
+      expect(mkdirCalls).toHaveLength(1);
+      expect(mkdirCalls[0]!.path).toBe('/workspace/newdir');
+    });
+
+    it('mkdir with parents=true resolves and creates intermediate dirs', async () => {
+      state.dirs.add('/workspace');
+      await kaos.chdir('/workspace');
+
+      await kaos.mkdir('a/b/c', { parents: true });
+
+      const mkdirCalls = state.calls.filter((c) => c.method === 'mkdir');
+      const mkdirPaths = mkdirCalls.map((c) => c.path);
+      expect(mkdirPaths).toContain('/workspace/a');
+      expect(mkdirPaths).toContain('/workspace/a/b');
+      expect(mkdirPaths).toContain('/workspace/a/b/c');
+      expect(mkdirPaths.every((path) => !path.includes('//'))).toBe(true);
+    });
+
+    it('mkdir existOk=true is idempotent against the resolved path', async () => {
+      state.dirs.add('/workspace');
+      await kaos.chdir('/workspace');
+      // Pre-seed the target directory.
+      state.dirs.add('/workspace/existing');
+
+      await expect(kaos.mkdir('existing', { existOk: true })).resolves.toBeUndefined();
+
+      // Without existOk, it should throw.
+      await expect(kaos.mkdir('existing', { existOk: false })).rejects.toThrow();
+    });
+
+    it('mkdir with parents=true rejects a raced file collision when existOk=true', async () => {
+      state.dirs.add('/workspace');
+      await kaos.chdir('/workspace');
+
+      const racePaths = ['/workspace/collision', '//workspace/collision'];
+      for (const racePath of racePaths) {
+        state.mkdirFailures.set(racePath, {
+          error: new Error('EEXIST'),
+          materializeAs: 'file',
+        });
+      }
+
+      await expect(
+        kaos.mkdir('collision', { parents: true, existOk: true }),
+      ).rejects.toBeInstanceOf(KaosFileExistsError);
+    });
+  });
+
+  describe('iterdir', () => {
+    it('iterdir with relative "." resolves to cwd', async () => {
+      state.dirs.add('/workspace');
+      await kaos.chdir('/workspace');
+
+      const entries: string[] = [];
+      for await (const entry of kaos.iterdir('.')) {
+        entries.push(entry);
+      }
+      // (readdir mock returns empty list; we're asserting the path passed to readdir)
+
+      const readdirCalls = state.calls.filter((c) => c.method === 'readdir');
+      expect(readdirCalls).toHaveLength(1);
+      // posix.join('/workspace', '.') normalises to '/workspace'
+      expect(readdirCalls[0]!.path).toBe('/workspace');
+      expect(entries).toEqual([]);
+    });
+
+    it('iterdir with named relative subdir resolves under cwd', async () => {
+      state.dirs.add('/workspace');
+      state.dirs.add('/workspace/sub');
+      await kaos.chdir('/workspace');
+
+      const entries: string[] = [];
+      for await (const entry of kaos.iterdir('sub')) {
+        entries.push(entry);
+      }
+
+      const readdirCalls = state.calls.filter((c) => c.method === 'readdir');
+      expect(readdirCalls).toHaveLength(1);
+      expect(readdirCalls[0]!.path).toBe('/workspace/sub');
+      expect(entries).toEqual([]);
+    });
+  });
+
+  describe('chdir follows realpath and affects subsequent relative ops', () => {
+    it('consecutive chdir + readText rebase the working directory each time', async () => {
+      state.dirs.add('/a');
+      state.dirs.add('/b');
+      state.files.set('/a/one.txt', Buffer.from('A'));
+      state.files.set('/b/two.txt', Buffer.from('B'));
+
+      await kaos.chdir('/a');
+      expect(await kaos.readText('one.txt')).toBe('A');
+
+      await kaos.chdir('/b');
+      expect(await kaos.readText('two.txt')).toBe('B');
+
+      // After chdir(/b), a relative path that only exists under /a
+      // must NOT resolve — confirming we've truly rebased.
+      await expect(kaos.readText('one.txt')).rejects.toThrow();
+    });
+
+    it('chdir with a relative argument resolves against the prior cwd', async () => {
+      state.dirs.add('/home/user');
+      state.dirs.add('/home/user/project');
+
+      await kaos.chdir('/home/user');
+      await kaos.chdir('project');
+
+      expect(kaos.getcwd()).toBe('/home/user/project');
+
+      state.files.set('/home/user/project/README.md', Buffer.from('readme'));
+      expect(await kaos.readText('README.md')).toBe('readme');
+    });
+  });
+});
diff --git a/packages/kaos/test/e2e/symlink-stat-parity.test.ts b/packages/kaos/test/e2e/symlink-stat-parity.test.ts
new file mode 100644
index 000000000..1dc9b476e
--- /dev/null
+++ b/packages/kaos/test/e2e/symlink-stat-parity.test.ts
@@ -0,0 +1,67 @@
+import { mkdtemp, realpath, rm, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { LocalKaos } from '#/local';
+
+const S_IFMT = 0o170000;
+const S_IFDIR = 0o040000;
+const S_IFLNK = 0o120000;
+const S_IFREG = 0o100000;
+
+describe.skipIf(process.platform === 'win32')('e2e: symlink stat parity', () => {
+  let kaos: LocalKaos;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    kaos = new LocalKaos();
+    tempDir = await realpath(await mkdtemp(join(tmpdir(), 'kaos-symlink-')));
+    await kaos.chdir(tempDir);
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('follows file symlinks by default and preserves lstat metadata when followSymlinks=false', async () => {
+    const targetFile = join(tempDir, 'target.txt');
+    const linkFile = join(tempDir, 'target-link.txt');
+    const payload = 'payload through symlink';
+
+    await kaos.writeText(targetFile, payload);
+    await symlink(targetFile, linkFile);
+
+    const linkStat = await kaos.stat(linkFile, { followSymlinks: false });
+    expect(linkStat.stMode & S_IFMT).toBe(S_IFLNK);
+
+    const resolvedStat = await kaos.stat(linkFile);
+    expect(resolvedStat.stMode & S_IFMT).toBe(S_IFREG);
+    expect(resolvedStat.stSize).toBe(Buffer.byteLength(payload, 'utf-8'));
+    expect(await kaos.readText(linkFile)).toBe(payload);
+  });
+
+  it('follows directory symlinks while lstat still reports a symlink', async () => {
+    const targetDir = join(tempDir, 'target-dir');
+    const linkDir = join(tempDir, 'target-dir-link');
+    const nestedFile = join(targetDir, 'nested.txt');
+
+    await kaos.mkdir(targetDir);
+    await kaos.writeText(nestedFile, 'directory payload');
+    await symlink(targetDir, linkDir);
+
+    const linkStat = await kaos.stat(linkDir, { followSymlinks: false });
+    expect(linkStat.stMode & S_IFMT).toBe(S_IFLNK);
+
+    const resolvedStat = await kaos.stat(linkDir);
+    expect(resolvedStat.stMode & S_IFMT).toBe(S_IFDIR);
+
+    const entries: string[] = [];
+    for await (const entry of kaos.iterdir(linkDir)) {
+      entries.push(entry);
+    }
+
+    expect(entries).toEqual([join(linkDir, 'nested.txt')]);
+  });
+});
diff --git a/packages/kaos/test/internal.test.ts b/packages/kaos/test/internal.test.ts
new file mode 100644
index 000000000..058f63db2
--- /dev/null
+++ b/packages/kaos/test/internal.test.ts
@@ -0,0 +1,257 @@
+import { PassThrough } from 'node:stream';
+import { setImmediate as defer, setTimeout as delay } from 'node:timers/promises';
+
+import { describe, expect, it } from 'vitest';
+
+import { BufferedReadable, decodeTextWithErrors, globPatternToRegex } from '#/internal';
+
+async function collectBytes(readable: AsyncIterable<Uint8Array | string>): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of readable) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  return Promise.race([
+    promise,
+    (async () => {
+      await delay(timeoutMs);
+      throw new Error(`timed out after ${timeoutMs}ms`);
+    })(),
+  ]);
+}
+
+describe('BufferedReadable', () => {
+  it('preserves source backpressure until the consumer starts reading', () => {
+    const source = new PassThrough({ highWaterMark: 64 * 1024 });
+    const buffered = new BufferedReadable(source);
+    const chunk = Buffer.alloc(32 * 1024, 0x61);
+
+    let writes = 0;
+    let writeOk = true;
+    while (writes < 20 && writeOk) {
+      writeOk = source.write(chunk);
+      writes++;
+    }
+
+    buffered.destroy();
+    source.destroy();
+
+    expect(writeOk).toBe(false);
+    expect(writes).toBeLessThan(10);
+  });
+
+  it('stops pushing when its readable buffer reaches highWaterMark', async () => {
+    const source = new PassThrough();
+    const chunk = Buffer.alloc(32 * 1024, 0x62);
+
+    for (let index = 0; index < 10; index++) {
+      source.write(chunk);
+    }
+    source.end();
+
+    const buffered = new BufferedReadable(source);
+    buffered.read(0);
+    await defer();
+
+    expect(buffered.readableLength).toBeLessThanOrEqual(buffered.readableHighWaterMark);
+
+    const output = await collectBytes(buffered);
+    expect(output).toHaveLength(chunk.length * 10);
+  });
+
+  it('ends async iteration when the source closes without emitting end', async () => {
+    const source = new PassThrough();
+    const buffered = new BufferedReadable(source);
+    const outputPromise = collectBytes(buffered).then((output) => output.toString('utf8'));
+
+    await defer();
+    source.write('hello');
+    await defer();
+    source.destroy();
+
+    await expect(withTimeout(outputPromise, 250)).resolves.toBe('hello');
+  });
+
+  it('propagates a source error through destroy()', async () => {
+    // When the source emits an 'error' event, BufferedReadable must tear
+    // itself down with the same error so consumers see the failure rather
+    // than waiting forever for data.
+    const source = new PassThrough();
+    const buffered = new BufferedReadable(source);
+    const boom = new Error('source boom');
+
+    const errorReceived = new Promise<Error>((resolve) => {
+      buffered.on('error', (err: Error) => {
+        resolve(err);
+      });
+    });
+
+    source.emit('error', boom);
+
+    const received = await withTimeout(errorReceived, 250);
+    expect(received).toBe(boom);
+    expect(buffered.destroyed).toBe(true);
+  });
+});
+
+describe('decodeTextWithErrors', () => {
+  it('decodes utf-16le content under strict mode', () => {
+    // Covers the utf16le / ucs2 / ucs-2 alias branches that the readText
+    // tests (which only exercise utf-8) never touch.
+    const data = Buffer.from('hello', 'utf16le');
+    expect(decodeTextWithErrors(data, 'utf16le')).toBe('hello');
+  });
+
+  it('accepts the ucs2 and ucs-2 encoding aliases', () => {
+    const data = Buffer.from('hello', 'utf16le');
+    expect(decodeTextWithErrors(data, 'ucs2')).toBe('hello');
+    expect(decodeTextWithErrors(data, 'ucs-2' as BufferEncoding)).toBe('hello');
+  });
+
+  it('falls back to Buffer.toString for non-UTF encodings', () => {
+    // hex / base64 / latin1 are lossless byte↔character mappings so `errors`
+    // has no effect; the helper must take the non-TextDecoder branch.
+    const data = Buffer.from([0x68, 0x69]); // 'hi' in latin1
+    expect(decodeTextWithErrors(data, 'latin1')).toBe('hi');
+    expect(decodeTextWithErrors(data, 'hex')).toBe('6869');
+  });
+
+  it('preserves valid U+FFFD when ignoring invalid utf-8 bytes', () => {
+    const data = Buffer.concat([
+      Buffer.from('A\uFFFDB', 'utf-8'),
+      Buffer.from([0xff]),
+      Buffer.from('C', 'utf-8'),
+    ]);
+
+    expect(decodeTextWithErrors(data, 'utf-8', 'ignore')).toBe('A\uFFFDBC');
+  });
+
+  it('matches Python ignore behavior for invalid utf-8 sequence boundaries', () => {
+    const cases: Buffer[] = [
+      Buffer.from([0xc2, 0x41]),
+      Buffer.from([0xe0, 0xa0, 0x41]),
+      Buffer.from([0xf0, 0x90, 0x80, 0x41]),
+      Buffer.from([0xed, 0xa0, 0x80, 0x41]),
+    ];
+
+    for (const data of cases) {
+      expect(decodeTextWithErrors(data, 'utf-8', 'ignore')).toBe('A');
+    }
+  });
+
+  it('preserves valid U+FFFD when ignoring invalid utf-16le code units', () => {
+    const data = Buffer.concat([
+      Buffer.from('A\uFFFDB', 'utf16le'),
+      Buffer.from([0x3d, 0xd8]), // lone high surrogate
+      Buffer.from('C', 'utf16le'),
+      Buffer.from([0xff]), // trailing half code unit
+    ]);
+
+    expect(decodeTextWithErrors(data, 'utf16le', 'ignore')).toBe('A\uFFFDBC');
+  });
+
+  it('matches Python ignore behavior for utf-16le surrogate boundaries', () => {
+    const emojiPair = Buffer.from([0x3d, 0xd8, 0x00, 0xde]);
+    expect(decodeTextWithErrors(emojiPair, 'utf16le', 'ignore')).toBe('\u{1F600}');
+
+    const highThenNormalThenLow = Buffer.from([0x3d, 0xd8, 0x58, 0x00, 0x00, 0xdc]);
+    expect(decodeTextWithErrors(highThenNormalThenLow, 'utf16le', 'ignore')).toBe('X');
+  });
+});
+
+describe('globPatternToRegex additional cases', () => {
+  it('converts ? to a single-character class that excludes /', () => {
+    const regex = globPatternToRegex('f?o.txt', true);
+    expect(regex.test('foo.txt')).toBe(true);
+    expect(regex.test('fao.txt')).toBe(true);
+    // ? must match exactly one character
+    expect(regex.test('fo.txt')).toBe(false);
+    // ? must not cross path segments
+    expect(regex.test('f/o.txt')).toBe(false);
+  });
+
+  it('treats an unclosed [ as a literal bracket', () => {
+    // Mirrors Python fnmatch/glob: a bare `[` with no closing `]` is
+    // re-emitted as an escaped literal instead of starting a char class.
+    const regex = globPatternToRegex('file[', true);
+    expect(regex.test('file[')).toBe(true);
+    expect(regex.test('file]')).toBe(false);
+  });
+
+  it('escapes regex metacharacters in the default branch', () => {
+    // `+`, `.`, `(`, `)`, `$`, `^`, `|`, `{`, `}`, `\` must be escaped so
+    // `a+b.c$d(e)` in a glob pattern matches that literal filename.
+    const regex = globPatternToRegex('a+b.c$d(e)', true);
+    expect(regex.test('a+b.c$d(e)')).toBe(true);
+    // Without escaping, `+` would make `ab` match via one-or-more repetition.
+    expect(regex.test('ab.c$d(e)')).toBe(false);
+  });
+});
+
+describe('globPatternToRegex', () => {
+  it('treats [!...] as a negated character class', () => {
+    const regex = globPatternToRegex('[!a].txt', true);
+
+    expect(regex.test('a.txt')).toBe(false);
+    expect(regex.test('b.txt')).toBe(true);
+  });
+
+  it('treats ^ as a literal character inside glob character classes', () => {
+    const regex = globPatternToRegex('[^a].txt', true);
+
+    expect(regex.test('^.txt')).toBe(true);
+    expect(regex.test('a.txt')).toBe(true);
+    expect(regex.test('b.txt')).toBe(false);
+  });
+
+  describe('glob semantic compatibility (Python parity)', () => {
+    it('treats brace expansion syntax as literal characters', () => {
+      const regex = globPatternToRegex('*.{js,ts}', true);
+
+      expect(regex.test('file.js')).toBe(false);
+      expect(regex.test('file.ts')).toBe(false);
+      expect(regex.test('file.{js,ts}')).toBe(true);
+    });
+
+    it('treats leading ^ as a literal character inside character classes', () => {
+      const regex = globPatternToRegex('[^a].txt', true);
+
+      expect(regex.test('^.txt')).toBe(true);
+      expect(regex.test('a.txt')).toBe(true);
+      expect(regex.test('b.txt')).toBe(false);
+    });
+
+    it('uses ! for character class negation', () => {
+      const regex = globPatternToRegex('[!a].txt', true);
+
+      expect(regex.test('b.txt')).toBe(true);
+      expect(regex.test('a.txt')).toBe(false);
+    });
+
+    it('matches hidden files with dot-prefixed patterns', () => {
+      const regex = globPatternToRegex('.*', true);
+
+      expect(regex.test('.hidden')).toBe(true);
+      expect(regex.test('.config')).toBe(true);
+    });
+
+    it.skip('Python treats **/foo.txt as recursive; current helper is segment-based and does not implement zero-or-more directories', () => {
+      const regex = globPatternToRegex('**/foo.txt', true);
+
+      expect(regex.test('foo.txt')).toBe(true);
+      expect(regex.test('a/foo.txt')).toBe(true);
+      expect(regex.test('a/b/foo.txt')).toBe(true);
+    });
+
+    it('keeps single-star matching to a single path segment', () => {
+      const regex = globPatternToRegex('*/foo.txt', true);
+
+      expect(regex.test('a/foo.txt')).toBe(true);
+      expect(regex.test('foo.txt')).toBe(false);
+      expect(regex.test('a/b/foo.txt')).toBe(false);
+    });
+  });
+});
diff --git a/packages/kaos/test/local.test.ts b/packages/kaos/test/local.test.ts
new file mode 100644
index 000000000..dd8b88b6c
--- /dev/null
+++ b/packages/kaos/test/local.test.ts
@@ -0,0 +1,852 @@
+import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { KaosFileExistsError } from '#/errors';
+import { LocalKaos } from '#/local';
+import { afterEach, beforeEach, describe, expect, it, test } from 'vitest';
+
+function nodeArgs(code: string): string[] {
+  return ['node', '-e', code];
+}
+
+describe('LocalKaos', () => {
+  let kaos: LocalKaos;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    kaos = new LocalKaos();
+    tempDir = await realpath(await mkdtemp(join(tmpdir(), 'kaos-test-')));
+    await kaos.chdir(tempDir);
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe('pathClass, gethome, getcwd', () => {
+    it('should return posix or win32 pathClass', () => {
+      const cls = kaos.pathClass();
+      if (process.platform === 'win32') {
+        expect(cls).toBe('win32');
+      } else {
+        expect(cls).toBe('posix');
+      }
+    });
+
+    it('should return the home directory', () => {
+      // Python test_local_kaos.py pins `str(gethome()) == str(Path.home())`;
+      // asserting length > 0 alone was too weak — a stub returning any
+      // non-empty string would pass.
+      const home = kaos.gethome();
+      expect(home).toBe(homedir());
+    });
+
+    it('should return the current working directory', () => {
+      const cwd = kaos.getcwd();
+      expect(cwd).toBe(tempDir);
+    });
+  });
+
+  describe('chdir + stat', () => {
+    it('should change directory and stat a file', async () => {
+      const nested = join(tempDir, 'nested');
+      await kaos.mkdir(nested);
+
+      await kaos.chdir(nested);
+      expect(kaos.getcwd()).toBe(nested);
+
+      const filePath = join(nested, 'file.txt');
+      await kaos.writeText(filePath, 'hello world');
+
+      const statResult = await kaos.stat(filePath);
+      expect(statResult.stSize).toBe(Buffer.byteLength('hello world', 'utf-8'));
+    });
+
+    it('should reject chdir into a regular file', async () => {
+      // chdir must explicitly refuse targets that resolve to non-directories
+      // so relative I/O calls after the chdir do not silently treat a file
+      // path as a working directory.
+      const filePath = join(tempDir, 'not-a-dir.txt');
+      await kaos.writeText(filePath, 'content');
+      await expect(kaos.chdir(filePath)).rejects.toThrow(/Not a directory/);
+    });
+  });
+
+  describe('iterdir path normalization', () => {
+    it('should produce normalized paths even when the argument has a trailing separator', async () => {
+      // Regression: previously, iterdir manually concatenated `resolved + sep
+      // + entry`, which produced `//entry` for roots like `/` and `C:\\entry`
+      // for Windows drives. Using pathJoin correctly collapses the extra
+      // separator.
+      await kaos.writeText(join(tempDir, 'file.txt'), 'x');
+
+      const entries: string[] = [];
+      // Pass tempDir with an explicit trailing slash to simulate the root
+      // edge case without needing a writable filesystem root in the test.
+      for await (const entry of kaos.iterdir(tempDir + '/')) {
+        entries.push(entry);
+      }
+
+      expect(entries).toContain(join(tempDir, 'file.txt'));
+      // No entry should contain duplicated separators.
+      expect(entries.every((e) => !e.includes('//'))).toBe(true);
+    });
+  });
+
+  describe('iterdir + glob', () => {
+    it('should list directory entries and match glob patterns', async () => {
+      await kaos.mkdir(join(tempDir, 'alpha'));
+      await kaos.writeText(join(tempDir, 'bravo.txt'), 'bravo');
+      await kaos.writeText(join(tempDir, 'charlie.TXT'), 'charlie');
+
+      const entries: string[] = [];
+      for await (const entry of kaos.iterdir(tempDir)) {
+        entries.push(entry);
+      }
+      const names = entries.map((e) => e.split('/').pop()!);
+      expect(new Set(names)).toEqual(new Set(['alpha', 'bravo.txt', 'charlie.TXT']));
+
+      const matched: string[] = [];
+      for await (const entry of kaos.glob(tempDir, '*.txt')) {
+        matched.push(entry);
+      }
+      const matchedNames = matched.map((e) => e.split('/').pop()!);
+      expect(new Set(matchedNames)).toEqual(new Set(['bravo.txt']));
+    });
+  });
+
+  describe('glob hidden files', () => {
+    it('should include hidden files in glob results', async () => {
+      await kaos.writeText(join(tempDir, '.gitlab-ci.yml'), 'stages: [build]');
+      await kaos.writeText(join(tempDir, 'config.yml'), 'key: value');
+
+      const matched: string[] = [];
+      for await (const entry of kaos.glob(tempDir, '*.yml')) {
+        matched.push(entry);
+      }
+      const names = matched.map((e) => e.split('/').pop()!);
+      expect(names).toContain('.gitlab-ci.yml');
+      expect(names).toContain('config.yml');
+    });
+
+    it('should glob through hidden directories with ** pattern', async () => {
+      await kaos.mkdir(join(tempDir, 'src'));
+      await kaos.mkdir(join(tempDir, 'src', '.config'));
+      await kaos.writeText(join(tempDir, 'src', '.config', 'settings.yml'), 'debug: true');
+      await kaos.writeText(join(tempDir, 'src', 'main.ts'), 'pass');
+
+      const deepMatched: string[] = [];
+      for await (const entry of kaos.glob(tempDir, 'src/**/*.yml')) {
+        deepMatched.push(entry);
+      }
+      expect(deepMatched.some((p) => p.includes('.config'))).toBe(true);
+    });
+  });
+
+  describe('readText/writeText', () => {
+    it('should write, read, append, and readLines', async () => {
+      const filePath = join(tempDir, 'note.txt');
+
+      const written = await kaos.writeText(filePath, 'line1');
+      expect(written).toBe('line1'.length);
+
+      const content = await kaos.readText(filePath);
+      expect(content).toBe('line1');
+
+      await kaos.writeText(filePath, '\nline2', { mode: 'a' });
+
+      const lines: string[] = [];
+      for await (const line of kaos.readLines(filePath)) {
+        lines.push(line);
+      }
+      expect(lines.join('')).toBe('line1\nline2');
+    });
+  });
+
+  describe('readText errors parameter (Python compat)', () => {
+    // A file with a valid UTF-8 prefix "中", an invalid standalone byte 0xff,
+    // and a valid UTF-8 suffix "文". Under strict decoding this throws.
+    const invalidBytes = Buffer.concat([
+      Buffer.from([0xe4, 0xb8, 0xad]), // 中
+      Buffer.from([0xff]),
+      Buffer.from([0xe6, 0x96, 0x87]), // 文
+    ]);
+
+    it('throws on invalid utf-8 with errors="strict" (default)', async () => {
+      const filePath = join(tempDir, 'invalid.txt');
+      await kaos.writeBytes(filePath, invalidBytes);
+
+      await expect(kaos.readText(filePath)).rejects.toThrow();
+      await expect(kaos.readText(filePath, { errors: 'strict' })).rejects.toThrow();
+    });
+
+    it('returns U+FFFD replacement characters with errors="replace"', async () => {
+      const filePath = join(tempDir, 'replace.txt');
+      await kaos.writeBytes(filePath, invalidBytes);
+
+      const content = await kaos.readText(filePath, { errors: 'replace' });
+      expect(content).toContain('\uFFFD');
+      expect(content).toContain('中');
+      expect(content).toContain('文');
+    });
+
+    it('drops invalid bytes with errors="ignore"', async () => {
+      const filePath = join(tempDir, 'ignore.txt');
+      await kaos.writeBytes(filePath, invalidBytes);
+
+      const content = await kaos.readText(filePath, { errors: 'ignore' });
+      expect(content).toBe('中文');
+      expect(content).not.toContain('\uFFFD');
+    });
+
+    it('preserves valid U+FFFD characters with errors="ignore"', async () => {
+      const filePath = join(tempDir, 'ignore-valid-replacement.txt');
+      const data = Buffer.concat([
+        Buffer.from('A\uFFFDB', 'utf-8'),
+        Buffer.from([0xff]),
+        Buffer.from('C', 'utf-8'),
+      ]);
+      await kaos.writeBytes(filePath, data);
+
+      const content = await kaos.readText(filePath, { errors: 'ignore' });
+      expect(content).toBe('A\uFFFDBC');
+    });
+  });
+
+  describe('LF preservation', () => {
+    it('should not convert LF to CRLF', async () => {
+      const filePath = join(tempDir, 'lf.txt');
+      await kaos.writeText(filePath, 'hello\nworld\n');
+
+      const raw = await kaos.readBytes(filePath);
+      expect(raw).toEqual(Buffer.from('hello\nworld\n'));
+    });
+  });
+
+  describe('CRLF preservation', () => {
+    it('should preserve CRLF line endings', async () => {
+      const filePath = join(tempDir, 'crlf.txt');
+      await kaos.writeText(filePath, 'hello\r\nworld\r\n');
+
+      const raw = await kaos.readBytes(filePath);
+      expect(raw).toEqual(Buffer.from('hello\r\nworld\r\n'));
+    });
+  });
+
+  describe('mkdir recursive', () => {
+    it('should create nested directories with parents option', async () => {
+      const nested = join(tempDir, 'a', 'b', 'c');
+      await kaos.mkdir(nested, { parents: true });
+
+      const s = await kaos.stat(nested);
+      // Check it's a directory (mode has the directory bit set)
+      // S_IFDIR = 0o040000
+      expect(s.stMode & 0o170000).toBe(0o040000);
+    });
+
+    it('should throw when parents:true + existOk:false on existing dir', async () => {
+      // Regression: fs.mkdir({ recursive: true }) silently succeeds on an
+      // existing directory. mkdir({ parents: true, existOk: false }) must
+      // still reject to match the advertised semantics.
+      const existing = join(tempDir, 'existing');
+      await kaos.mkdir(existing);
+
+      await expect(kaos.mkdir(existing, { parents: true, existOk: false })).rejects.toThrow();
+    });
+
+    it('should succeed when parents:true + existOk:true on existing dir', async () => {
+      const existing = join(tempDir, 'existing');
+      await kaos.mkdir(existing);
+
+      await expect(kaos.mkdir(existing, { parents: true, existOk: true })).resolves.toBeUndefined();
+    });
+
+    it('should throw when existOk:true but conflicting path is a file', async () => {
+      // If the target path already exists as a regular file, `existOk` must
+      // not silently "succeed" because there is still no directory there.
+      const filePath = join(tempDir, 'not-a-dir.txt');
+      await kaos.writeText(filePath, 'hello');
+
+      await expect(kaos.mkdir(filePath, { existOk: true })).rejects.toBeInstanceOf(
+        KaosFileExistsError,
+      );
+    });
+  });
+
+  describe('glob character class negation', () => {
+    it('[!a] should match non-a files (glob negation, not literal `!`)', async () => {
+      // Glob character classes use `!` for negation, unlike JavaScript regex.
+      await kaos.writeText(join(tempDir, 'a.txt'), '');
+      await kaos.writeText(join(tempDir, 'b.txt'), '');
+      await kaos.writeText(join(tempDir, '!.txt'), '');
+
+      const matches: string[] = [];
+      for await (const m of kaos.glob(tempDir, '[!a].txt')) {
+        matches.push(m);
+      }
+      const names = new Set(matches.map((p) => p.split(/[/\\]/).pop()!));
+
+      expect(names.has('a.txt')).toBe(false);
+      expect(names.has('b.txt')).toBe(true);
+      expect(names.has('!.txt')).toBe(true);
+    });
+  });
+
+  describe('glob ** pattern', () => {
+    it('should not return duplicates when ** matches nested paths', async () => {
+      // Regression for the `**` double-recursion bug: a single file nested
+      // two levels deep must appear exactly once, not 2^depth times.
+      await kaos.mkdir(join(tempDir, 'a', 'b'), { parents: true });
+      await kaos.writeText(join(tempDir, 'a', 'b', 'file.txt'), 'content');
+
+      const matches: string[] = [];
+      for await (const m of kaos.glob(tempDir, '**/*.txt')) {
+        matches.push(m);
+      }
+
+      expect(matches).toHaveLength(1);
+      expect(new Set(matches).size).toBe(matches.length);
+    });
+
+    it('should match ** at multiple depths without duplicates', async () => {
+      await kaos.mkdir(join(tempDir, 'a', 'b', 'c'), { parents: true });
+      await kaos.writeText(join(tempDir, 'root.txt'), '');
+      await kaos.writeText(join(tempDir, 'a', 'mid.txt'), '');
+      await kaos.writeText(join(tempDir, 'a', 'b', 'c', 'deep.txt'), '');
+
+      const matches: string[] = [];
+      for await (const m of kaos.glob(tempDir, '**/*.txt')) {
+        matches.push(m);
+      }
+
+      expect(matches).toHaveLength(3);
+      expect(new Set(matches).size).toBe(3);
+      const names = new Set(matches.map((p) => p.split(/[/\\]/).pop()!));
+      expect(names).toEqual(new Set(['root.txt', 'mid.txt', 'deep.txt']));
+    });
+
+    it('should not duplicate matches for deep ** patterns', async () => {
+      // Before the fix, each added depth level doubled the duplicate count.
+      // Build a 4-level-deep tree with a file at the bottom.
+      await kaos.mkdir(join(tempDir, 'l1', 'l2', 'l3', 'l4'), { parents: true });
+      await kaos.writeText(join(tempDir, 'l1', 'l2', 'l3', 'l4', 'deep.txt'), 'x');
+
+      const matches: string[] = [];
+      for await (const m of kaos.glob(tempDir, '**/*.txt')) {
+        matches.push(m);
+      }
+
+      expect(matches).toHaveLength(1);
+    });
+
+    it('should yield basePath and every recursive entry when the whole pattern is **', async () => {
+      // A bare `**` pattern enters the final-segment branch of _globWalk and
+      // must (a) emit basePath itself for the zero-directory match and
+      // (b) walk every file/dir below it as additional matches.
+      await kaos.mkdir(join(tempDir, 'sub'));
+      await kaos.writeText(join(tempDir, 'root.txt'), 'r');
+      await kaos.writeText(join(tempDir, 'sub', 'nested.txt'), 'n');
+
+      const matches: string[] = [];
+      for await (const m of kaos.glob(tempDir, '**')) {
+        matches.push(m);
+      }
+
+      const names = new Set(matches.map((p) => p.split(/[/\\]/).pop() ?? ''));
+      expect(matches).toContain(tempDir);
+      expect(names.has('root.txt')).toBe(true);
+      expect(names.has('nested.txt')).toBe(true);
+      expect(names.has('sub')).toBe(true);
+    });
+  });
+
+  // ── Symlink cycle safety ────────────────────────────────────────────
+  //
+  // These tests use real filesystem symlinks. Note: macOS/Linux apply
+  // SYMLOOP_MAX (~40 components) at the kernel level, so an unfixed
+  // walker doesn't hang forever — it yields a bounded-but-large number
+  // of cyclic paths (observed ~16 for a self-loop) before ELOOP. The
+  // assertions here are therefore tight (single-digit expected counts)
+  // so they distinguish "OS-ELOOP bailout" (buggy) from "app-level
+  // cycle detection" (fixed). HARD_STOP is a final safety belt in case
+  // a future kernel allows deeper symlink chains — tests shouldn't hang.
+  describe('glob symlink cycle safety', () => {
+    const HARD_STOP = 1000;
+
+    it('T-C1 self-symlink cycle yields exactly one match', async () => {
+      const { symlink, writeFile, mkdir } = await import('node:fs/promises');
+      // tempDir/ring/self → tempDir/ring (self-loop dir)
+      // tempDir/ring/leaf.txt (the only real file)
+      const ring = join(tempDir, 'ring');
+      await mkdir(ring);
+      await writeFile(join(ring, 'leaf.txt'), 'real');
+      await symlink(ring, join(ring, 'self'));
+
+      const matches: string[] = [];
+      for await (const m of kaos.glob(tempDir, '**/*.txt')) {
+        matches.push(m);
+        if (matches.length >= HARD_STOP) break;
+      }
+      // Fixed: visited-inode detects the self-loop on the first recurse
+      // into `ring/self` (whose resolved inode matches `ring`'s), so the
+      // walker yields `ring/leaf.txt` exactly once.
+      // Unfixed: ~16 copies like `ring/self/self/.../leaf.txt` before
+      // the kernel's SYMLOOP_MAX trips.
+      expect(matches).toHaveLength(1);
+      expect(matches[0]!.endsWith('leaf.txt')).toBe(true);
+    });
+
+    it('T-C2 mutual cycle (A/to_b→B, B/to_a→A) yields only finite real reaches', async () => {
+      const { symlink, writeFile, mkdir } = await import('node:fs/promises');
+      const a = join(tempDir, 'A');
+      const b = join(tempDir, 'B');
+      await mkdir(a);
+      await mkdir(b);
+      await writeFile(join(a, 'aleaf.txt'), 'a');
+      await writeFile(join(b, 'bleaf.txt'), 'b');
+      await symlink(b, join(a, 'to_b'));
+      await symlink(a, join(b, 'to_a'));
+
+      const matches: string[] = [];
+      for await (const m of kaos.glob(tempDir, '**/*.txt')) {
+        matches.push(m);
+        if (matches.length >= HARD_STOP) break;
+      }
+      // Fixed: path-local visited allows each legitimate descent (A→to_b
+      // which hits a fresh B, and B→to_a which hits a fresh A) but
+      // blocks the close-the-loop second step. Expected exactly 4:
+      //   root/A/aleaf.txt, root/A/to_b/bleaf.txt,
+      //   root/B/bleaf.txt, root/B/to_a/aleaf.txt.
+      // Unfixed: kernel ELOOP bailout yields many more (observed ~66
+      // on macOS). A shared-visited (non-path-local) impl would yield
+      // only 2 because entering B from the walker's root already marks
+      // B as visited before A→to_b is traversed.
+      expect(matches).toHaveLength(4);
+      expect(matches.filter((p) => p.endsWith('aleaf.txt'))).toHaveLength(2);
+      expect(matches.filter((p) => p.endsWith('bleaf.txt'))).toHaveLength(2);
+    });
+
+    it('T-C3 legit non-cyclic symlink to a sibling tree is followed', async () => {
+      const { symlink, writeFile, mkdir } = await import('node:fs/promises');
+      // target/ is a sibling not under root/, reached only via root/shortcut.
+      const root = join(tempDir, 'root');
+      const target = join(tempDir, 'target');
+      await mkdir(root);
+      await mkdir(target);
+      await writeFile(join(target, 'reachable.txt'), 'hi');
+      await symlink(target, join(root, 'shortcut'));
+
+      const matches: string[] = [];
+      for await (const m of kaos.glob(root, '**/*.txt')) {
+        matches.push(m);
+      }
+      // User-created symlinks to legitimate subtrees should still be followed;
+      // cycle detection only trips on actual cycles.
+      expect(matches.some((p) => p.endsWith('reachable.txt'))).toBe(true);
+    });
+
+    it('T-C4 broken symlink does not crash the walk', async () => {
+      const { symlink, writeFile, mkdir } = await import('node:fs/promises');
+      const root = join(tempDir, 'broken-root');
+      await mkdir(root);
+      await writeFile(join(root, 'real.txt'), 'r');
+      // Points at a path that doesn't exist.
+      await symlink(join(tempDir, 'does-not-exist'), join(root, 'dangling'));
+
+      const matches: string[] = [];
+      // Pattern must not match "dangling" (no .txt); we want the real
+      // file yielded and the walker to not throw on the broken symlink
+      // (whose stat() rejects).
+      for await (const m of kaos.glob(root, '**/*.txt')) {
+        matches.push(m);
+      }
+      expect(matches.some((p) => p.endsWith('real.txt'))).toBe(true);
+    });
+
+    it('T-C5 regression — non-symlink tree results are unchanged', async () => {
+      // Plain, non-symlink trees should not be filtered by cycle tracking.
+      await kaos.mkdir(join(tempDir, 'a', 'b', 'c'), { parents: true });
+      await kaos.writeText(join(tempDir, 'r1.txt'), '');
+      await kaos.writeText(join(tempDir, 'a', 'r2.txt'), '');
+      await kaos.writeText(join(tempDir, 'a', 'b', 'c', 'r3.txt'), '');
+
+      const matches: string[] = [];
+      for await (const m of kaos.glob(tempDir, '**/*.txt')) {
+        matches.push(m);
+      }
+      expect(matches).toHaveLength(3);
+      const names = new Set(matches.map((p) => p.split(/[/\\]/).pop()!));
+      expect(names).toEqual(new Set(['r1.txt', 'r2.txt', 'r3.txt']));
+    });
+
+    it('T-C6 two non-cyclic symlinks to same target both traverse (path-local visited)', async () => {
+      const { symlink, writeFile, mkdir } = await import('node:fs/promises');
+      // root/a → target, root/b → target. Both are legitimate (not
+      // cycles) — the user deliberately aliased the target twice.
+      const root = join(tempDir, 'root-aliases');
+      const target = join(tempDir, 'aliased-target');
+      await mkdir(root);
+      await mkdir(target);
+      await writeFile(join(target, 'shared.txt'), 'x');
+      await symlink(target, join(root, 'a'));
+      await symlink(target, join(root, 'b'));
+
+      const matches: string[] = [];
+      for await (const m of kaos.glob(root, '**/*.txt')) {
+        matches.push(m);
+      }
+      // Each alias branch has its own visited set copy, so both aliased paths
+      // surface. A shared visited set would yield only one of them.
+      expect(matches.some((p) => p.endsWith(`a/shared.txt`) || p.endsWith(`a\\shared.txt`))).toBe(
+        true,
+      );
+      expect(matches.some((p) => p.endsWith(`b/shared.txt`) || p.endsWith(`b\\shared.txt`))).toBe(
+        true,
+      );
+    });
+  });
+
+  describe('readBytes/writeBytes', () => {
+    it('should round-trip binary data', async () => {
+      const filePath = join(tempDir, 'data.bin');
+      const data = Buffer.from([0x00, 0x01, 0x02, 0xff]);
+
+      const written = await kaos.writeBytes(filePath, data);
+      expect(written).toBe(4);
+
+      const read = await kaos.readBytes(filePath);
+      expect(Buffer.compare(read, data)).toBe(0);
+    });
+  });
+
+  describe('exec streaming', () => {
+    it('should run a command and stream stdout/stderr', async () => {
+      const code = `process.stdout.write('hello\\n'); process.stderr.write('stderr line\\n');`;
+      const proc = await kaos.exec(...nodeArgs(code));
+
+      const stdoutChunks: Buffer[] = [];
+      const stderrChunks: Buffer[] = [];
+
+      const stdoutDone = new Promise<void>((resolve) => {
+        proc.stdout.on('data', (chunk: Buffer) => {
+          stdoutChunks.push(chunk);
+        });
+        proc.stdout.on('end', () => {
+          resolve();
+        });
+      });
+
+      const stderrDone = new Promise<void>((resolve) => {
+        proc.stderr.on('data', (chunk: Buffer) => {
+          stderrChunks.push(chunk);
+        });
+        proc.stderr.on('end', () => {
+          resolve();
+        });
+      });
+
+      const exitCode = await proc.wait();
+      await stdoutDone;
+      await stderrDone;
+
+      expect(exitCode).toBe(0);
+      expect(Buffer.concat(stdoutChunks).toString('utf-8').trim()).toBe('hello');
+      expect(Buffer.concat(stderrChunks).toString('utf-8').trim()).toBe('stderr line');
+    });
+  });
+
+  describe('exec wait-before-read', () => {
+    it('should buffer output and allow reading after wait', async () => {
+      const code = `process.stdout.write('hello\\n'); process.stderr.write('stderr line\\n');`;
+      const proc = await kaos.exec(...nodeArgs(code));
+
+      const exitCode = await proc.wait();
+      expect(exitCode).toBe(0);
+
+      // Read streams after process has already exited
+      const stdoutData = await streamToBuffer(proc.stdout);
+      const stderrData = await streamToBuffer(proc.stderr);
+
+      expect(stdoutData.toString('utf-8').trim()).toBe('hello');
+      expect(stderrData.toString('utf-8').trim()).toBe('stderr line');
+    });
+  });
+
+  describe('exec non-zero exit', () => {
+    it('should return the correct exit code', async () => {
+      const proc = await kaos.exec(...nodeArgs('process.exit(7)'));
+      const exitCode = await proc.wait();
+      expect(exitCode).toBe(7);
+      expect(proc.exitCode).toBe(7);
+    });
+  });
+
+  describe('exec spawn failure', () => {
+    it('should reject when the binary does not exist', async () => {
+      await expect(kaos.exec('/absolutely/non-existent/binary')).rejects.toThrow();
+    });
+
+    it('should reject exec() with no arguments', async () => {
+      // exec(...args) requires at least one argument (the command name).
+      // Cast through the loose signature so the call even compiles.
+      await expect((kaos.exec as () => Promise<unknown>)()).rejects.toThrow(
+        /at least one argument/,
+      );
+    });
+
+    it('should reject execWithEnv() with an empty args array', async () => {
+      // Mirrors the exec() guard: execWithEnv must also demand at least
+      // one argument (the command itself).
+      await expect(kaos.execWithEnv([])).rejects.toThrow(/at least one argument/);
+    });
+  });
+
+  describe('exec timeout', () => {
+    it('should allow killing a long-running process', async () => {
+      const code = `setTimeout(() => {}, 10000);`;
+      const proc = await kaos.exec(...nodeArgs(code));
+
+      expect(proc.pid).toBeGreaterThan(0);
+
+      // Use a short timeout via Promise.race
+      const result = await Promise.race([
+        proc.wait().then((exitCode) => ({ kind: 'exited' as const, code: exitCode })),
+        new Promise<{ kind: 'timeout' }>((resolve) =>
+          setTimeout(() => {
+            resolve({ kind: 'timeout' });
+          }, 50),
+        ),
+      ]);
+
+      expect(result.kind).toBe('timeout');
+
+      // Kill the process
+      await proc.kill('SIGKILL');
+      const exitCode = await proc.wait();
+      // On Unix, killed processes typically have negative exit or 137
+      expect(exitCode).not.toBe(0);
+    });
+  });
+});
+
+describe('LocalKaos instance isolation', () => {
+  test('instances have isolated cwds (no process.cwd pollution)', async () => {
+    const kaosA = new LocalKaos();
+    const kaosB = new LocalKaos();
+
+    const tmpA = await realpath(await mkdtemp(join(tmpdir(), 'kaos-a-')));
+    const tmpB = await realpath(await mkdtemp(join(tmpdir(), 'kaos-b-')));
+
+    try {
+      await kaosA.chdir(tmpA);
+      await kaosB.chdir(tmpB);
+
+      // kaosA.chdir must not affect kaosB's cwd (no process.chdir pollution).
+      expect(kaosA.getcwd()).toBe(tmpA);
+      expect(kaosB.getcwd()).toBe(tmpB);
+
+      // Write a file named "marker.txt" in each cwd using a relative path.
+      await kaosA.writeText('marker.txt', 'A');
+      await kaosB.writeText('marker.txt', 'B');
+
+      // Read back via each kaos — each should get its own version.
+      expect(await kaosA.readText('marker.txt')).toBe('A');
+      expect(await kaosB.readText('marker.txt')).toBe('B');
+
+      // exec() should also honour the instance cwd.
+      const procA = await kaosA.exec('node', '-e', 'process.stdout.write(process.cwd())');
+      const procB = await kaosB.exec('node', '-e', 'process.stdout.write(process.cwd())');
+      await procA.wait();
+      await procB.wait();
+      const outA = await streamToBuffer(procA.stdout);
+      const outB = await streamToBuffer(procB.stdout);
+      expect(outA.toString('utf-8')).toBe(tmpA);
+      expect(outB.toString('utf-8')).toBe(tmpB);
+    } finally {
+      await rm(tmpA, { recursive: true, force: true });
+      await rm(tmpB, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('LocalProcess.kill safety', () => {
+  test('kill() is safe when spawn failed (pid -1 must not signal process group)', async () => {
+    const kaos = new LocalKaos();
+
+    // Try to spawn a nonexistent command. Node's spawn() returns a
+    // ChildProcess immediately with pid=undefined; the "error" event
+    // arrives asynchronously.
+    let proc;
+    try {
+      proc = await kaos.exec('this-command-does-not-exist-xyz123');
+    } catch {
+      // If the environment threw synchronously, there's nothing to kill.
+      return;
+    }
+
+    // If pid is -1, kill must be a no-op and must NOT call
+    // process.kill(-1, ...) which would signal the entire process group.
+    if (proc.pid <= 0) {
+      await expect(proc.kill('SIGTERM')).resolves.toBeUndefined();
+    }
+
+    // Drain error event so the test runner doesn't leak unhandled errors.
+    try {
+      await proc.wait();
+    } catch {
+      // Expected for nonexistent commands.
+    }
+  });
+
+  test('kill() handles already-exited process gracefully (ESRCH ignored)', async () => {
+    const kaos = new LocalKaos();
+    const proc = await kaos.exec('node', '-e', 'process.exit(0)');
+    await proc.wait();
+
+    // Calling kill after exit should not throw — ESRCH is ignored.
+    await expect(proc.kill('SIGTERM')).resolves.toBeUndefined();
+  });
+
+  // ── Windows process-tree kill ───────────────────────────────────────
+  //
+  // On Windows the Node default kills only the shell parent; grandchildren can
+  // leak and run beyond the two-phase kill grace window.
+  //
+  // This test boots a nested process chain (parent → child → grandchild)
+  // and asserts that `proc.kill('SIGTERM')` tears the whole tree down.
+  // The grandchild is probed via its pidfile: if the file still names a
+  // live pid after the kill, the tree leaked.
+  test.skipIf(process.platform !== 'win32')(
+    'kill() terminates the grandchild on Windows (process tree)',
+    async () => {
+      const kaos = new LocalKaos();
+      const tmp = await realpath(await mkdtemp(join(tmpdir(), 'kaos-killtree-')));
+      try {
+        const pidFile = join(tmp, 'grandchild.pid').replaceAll('\\', '\\\\');
+        // Parent: spawns a child that spawns a grandchild (long-running).
+        // The grandchild writes its own pid to a file so the test can
+        // later check if it's still alive.
+        const code = `
+          const { spawn } = require('node:child_process');
+          const child = spawn(process.execPath, ['-e', \`
+            const { spawn } = require('node:child_process');
+            const { writeFileSync } = require('node:fs');
+            const g = spawn(process.execPath, ['-e', 'setTimeout(() => {}, 60000)']);
+            writeFileSync('${pidFile}', String(g.pid));
+            setInterval(() => {}, 1000);
+          \`], { stdio: 'inherit' });
+          setInterval(() => {}, 1000);
+        `;
+        const proc = await kaos.exec('node', '-e', code);
+
+        // Wait for grandchild pid to be written.
+        const { stat, readFile } = await import('node:fs/promises');
+        const pidPath = join(tmp, 'grandchild.pid');
+        const start = Date.now();
+        while (Date.now() - start < 5000) {
+          try {
+            if ((await stat(pidPath)).isFile()) break;
+          } catch {
+            /* not yet */
+          }
+          await new Promise((r) => setTimeout(r, 50));
+        }
+        const grandchildPid = Number.parseInt((await readFile(pidPath, 'utf-8')).trim(), 10);
+        expect(Number.isNaN(grandchildPid)).toBe(false);
+
+        // Kill parent — on Windows this currently leaks the grandchild
+        // unless `taskkill /T /F` (or equivalent) is used.
+        await proc.kill('SIGTERM');
+        await proc.wait();
+
+        // Give the OS up to 2s to reap the grandchild.
+        const reaped = await (async (): Promise<boolean> => {
+          for (let i = 0; i < 40; i += 1) {
+            try {
+              process.kill(grandchildPid, 0); // "is it still alive?"
+            } catch {
+              return true; // ESRCH — grandchild gone
+            }
+            await new Promise((r) => setTimeout(r, 50));
+          }
+          return false;
+        })();
+
+        expect(reaped).toBe(true);
+      } finally {
+        await rm(tmp, { recursive: true, force: true });
+      }
+    },
+    15_000,
+  );
+
+  // ── POSIX process-group kill ────────────────────────────────────────
+  //
+  // Structure mirrors the Windows grandchild test above: a Node parent
+  // spawns a child that spawns a long-running grandchild and writes its
+  // pid to a file. After `proc.kill('SIGTERM')`, the grandchild must
+  // be gone within a generous (~2 s) reap window.
+  test.skipIf(process.platform === 'win32')(
+    'kill() terminates the grandchild on POSIX (process tree)',
+    async () => {
+      const kaos = new LocalKaos();
+      const tmp = await realpath(await mkdtemp(join(tmpdir(), 'kaos-killtree-posix-')));
+      try {
+        const pidFile = join(tmp, 'grandchild.pid');
+        // `exec('bash', '-c', …)` spawns bash as the direct child; the
+        // embedded node chain spawns a long-running grandchild under it.
+        // The grandchild writes its pid so we can poll liveness.
+        const script = `
+          node -e 'const { spawn } = require("node:child_process");
+            const { writeFileSync } = require("node:fs");
+            const g = spawn(process.execPath, ["-e", "setTimeout(() => {}, 60000)"]);
+            writeFileSync(${JSON.stringify(pidFile)}, String(g.pid));
+            setInterval(() => {}, 1000);'
+        `;
+        const proc = await kaos.exec('bash', '-c', script);
+
+        const { stat, readFile } = await import('node:fs/promises');
+        const start = Date.now();
+        while (Date.now() - start < 5000) {
+          try {
+            if ((await stat(pidFile)).isFile()) break;
+          } catch {
+            /* not yet */
+          }
+          await new Promise((r) => setTimeout(r, 50));
+        }
+        const grandchildPid = Number.parseInt((await readFile(pidFile, 'utf-8')).trim(), 10);
+        expect(Number.isNaN(grandchildPid)).toBe(false);
+
+        await proc.kill('SIGTERM');
+        await proc.wait();
+
+        const reaped = await (async (): Promise<boolean> => {
+          for (let i = 0; i < 40; i += 1) {
+            try {
+              process.kill(grandchildPid, 0);
+            } catch {
+              return true;
+            }
+            await new Promise((r) => setTimeout(r, 50));
+          }
+          return false;
+        })();
+
+        expect(reaped).toBe(true);
+      } finally {
+        await rm(tmp, { recursive: true, force: true });
+      }
+    },
+    15_000,
+  );
+});
+
+async function streamToBuffer(stream: NodeJS.ReadableStream): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.from(chunk as Buffer));
+  }
+  return Buffer.concat(chunks);
+}
diff --git a/packages/kaos/test/path.test.ts b/packages/kaos/test/path.test.ts
new file mode 100644
index 000000000..a290c36b7
--- /dev/null
+++ b/packages/kaos/test/path.test.ts
@@ -0,0 +1,481 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as win32Path from 'node:path/win32';
+
+import { resetCurrentKaos, setCurrentKaos } from '#/current';
+import type { KaosToken } from '#/current';
+import type { Kaos } from '#/kaos';
+import { LocalKaos } from '#/local';
+import { KaosPath } from '#/path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+function makeMockKaos(pathClass: 'posix' | 'win32', overrides: Partial<Kaos> = {}): Kaos {
+  return {
+    name: `mock-${pathClass}`,
+    pathClass: () => pathClass,
+    normpath: (p: string) => (pathClass === 'win32' ? win32Path.normalize(p) : p),
+    gethome: () => (pathClass === 'win32' ? 'C:\\Users\\test' : '/home/test'),
+    getcwd: () => (pathClass === 'win32' ? 'C:\\work\\project' : '/work/project'),
+    chdir: async () => {},
+    stat: async () => ({
+      stMode: 0,
+      stIno: 0,
+      stDev: 0,
+      stNlink: 0,
+      stUid: 0,
+      stGid: 0,
+      stSize: 0,
+      stAtime: 0,
+      stMtime: 0,
+      stCtime: 0,
+    }),
+    iterdir: async function* () {},
+    glob: async function* () {},
+    readBytes: async () => Buffer.alloc(0),
+    readText: async () => '',
+    readLines: async function* () {},
+    writeBytes: async () => 0,
+    writeText: async () => 0,
+    mkdir: async () => {},
+    exec: async () => {
+      throw new Error('not implemented');
+    },
+    execWithEnv: async () => {
+      throw new Error('not implemented');
+    },
+    ...overrides,
+  };
+}
+
+describe('KaosPath', () => {
+  let token: KaosToken;
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'kaos-path-'));
+    const kaos = new LocalKaos();
+    token = setCurrentKaos(kaos);
+  });
+
+  afterEach(async () => {
+    resetCurrentKaos(token);
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('join and parent', () => {
+    it('should join paths with div', () => {
+      const p = new KaosPath('/usr');
+      const child = p.div('local').div('bin');
+      expect(child.toString()).toBe('/usr/local/bin');
+    });
+
+    it('should join paths with joinpath', () => {
+      const p = new KaosPath('/usr');
+      const child = p.joinpath('local', 'bin');
+      expect(child.toString()).toBe('/usr/local/bin');
+    });
+
+    it('should treat absolute joinpath segments as new roots', () => {
+      const p = new KaosPath('/usr');
+      expect(p.joinpath('/etc').toString()).toBe('/etc');
+      expect(new KaosPath('/usr', '/etc').toString()).toBe('/etc');
+    });
+
+    it('should preserve parent references until canonical()', () => {
+      const p = new KaosPath('/usr').joinpath('../etc');
+      expect(p.toString()).toBe('/usr/../etc');
+      expect(p.canonical().toString()).toBe('/etc');
+    });
+
+    it('should accept another KaosPath as div() argument', () => {
+      // Exercises the `other instanceof KaosPath` branch in div() — the
+      // existing tests only pass raw strings so this covers the other
+      // side of the ternary.
+      const p = new KaosPath('/usr');
+      const sub = new KaosPath('local');
+      expect(p.div(sub).toString()).toBe('/usr/local');
+    });
+
+    it('should return the parent path', () => {
+      const p = new KaosPath('/usr/local/bin');
+      expect(p.parent.toString()).toBe('/usr/local');
+      expect(p.parent.parent.toString()).toBe('/usr');
+    });
+
+    it('should return the name', () => {
+      const p = new KaosPath('/usr/local/bin');
+      expect(p.name).toBe('bin');
+    });
+
+    it('should detect absolute paths', () => {
+      expect(new KaosPath('/usr').isAbsolute()).toBe(true);
+      expect(new KaosPath('relative/path').isAbsolute()).toBe(false);
+    });
+
+    it('should default to "." when constructed with no arguments', () => {
+      // KaosPath() with no args represents the current directory placeholder.
+      // Used as a neutral starting point before chaining .div()/.joinpath().
+      const p = new KaosPath();
+      expect(p.toString()).toBe('.');
+    });
+  });
+
+  describe('home and cwd', () => {
+    it('should return home directory via KaosPath.home()', () => {
+      const home = KaosPath.home();
+      expect(home.isAbsolute()).toBe(true);
+      expect(home.toString()).toBe(homedir());
+    });
+
+    it('should return cwd via KaosPath.cwd()', () => {
+      const cwd = KaosPath.cwd();
+      expect(cwd.isAbsolute()).toBe(true);
+      expect(cwd.toString()).toBe(process.cwd());
+    });
+  });
+
+  describe('expanduser', () => {
+    it('should expand ~ to home directory', () => {
+      const p = new KaosPath('~/Documents');
+      const expanded = p.expanduser();
+      expect(expanded.toString()).toBe(join(homedir(), 'Documents'));
+      expect(expanded.isAbsolute()).toBe(true);
+    });
+
+    it('should expand bare ~ to home directory', () => {
+      const p = new KaosPath('~');
+      const expanded = p.expanduser();
+      expect(expanded.toString()).toBe(homedir());
+    });
+
+    it('should not expand ~ in the middle of a path', () => {
+      const p = new KaosPath('/usr/~test');
+      const expanded = p.expanduser();
+      expect(expanded.toString()).toBe('/usr/~test');
+    });
+  });
+
+  describe('canonical and relativeTo', () => {
+    it('should resolve .. in an absolute path', () => {
+      const p = new KaosPath('/usr/local/../bin');
+      const c = p.canonical();
+      expect(c.toString()).toBe('/usr/bin');
+    });
+
+    it('should make relative paths absolute using cwd', () => {
+      const p = new KaosPath('foo/bar');
+      const c = p.canonical();
+      expect(c.isAbsolute()).toBe(true);
+      expect(c.toString()).toBe(join(process.cwd(), 'foo/bar'));
+    });
+
+    it('should resolve .. in a relative path against cwd', () => {
+      // Pins the Python test_kaos_path.py::test_canonical_and_relative_to case:
+      // a relative input that also contains '..' must first rebase to cwd and
+      // then collapse the parent reference.
+      const p = new KaosPath('nested/../file.txt').canonical();
+      expect(p.isAbsolute()).toBe(true);
+      expect(p.toString()).toBe(join(process.cwd(), 'file.txt'));
+    });
+
+    it('should compute relativeTo correctly', () => {
+      const child = new KaosPath('/usr/local/bin');
+      const base = new KaosPath('/usr/local');
+      const rel = child.relativeTo(base);
+      expect(rel.toString()).toBe('bin');
+    });
+
+    it('should return dot for identical paths', () => {
+      const p = new KaosPath('/usr/local');
+      expect(p.relativeTo(new KaosPath('/usr/local')).toString()).toBe('.');
+    });
+
+    it('should reject sibling paths for relativeTo', () => {
+      const a = new KaosPath('/usr/local/lib');
+      const base = new KaosPath('/usr/local/bin');
+      expect(() => a.relativeTo(base)).toThrow(/not within/);
+    });
+
+    it('should reject when base is deeper than target', () => {
+      // The target is strictly shorter than base — there is no way for it to
+      // live "within" a deeper base. Hits the parts-length guard separately
+      // from the loop-based prefix-mismatch guard.
+      const a = new KaosPath('/usr');
+      const base = new KaosPath('/usr/local/bin');
+      expect(() => a.relativeTo(base)).toThrow(/not within/);
+    });
+
+    it('should compute relativeTo between two relative paths (empty root)', () => {
+      // Both operands have no absolute root, so splitPathLexically takes
+      // the `root.length === 0 ? path : path.slice(root.length)` else branch.
+      // Pinning this keeps the purely-relative relativeTo path honest.
+      const child = new KaosPath('a/b/c');
+      const base = new KaosPath('a/b');
+      expect(child.relativeTo(base).toString()).toBe('c');
+    });
+
+    it('should use win32 separators when the current kaos reports win32', async () => {
+      // Build a minimal Kaos mock that claims win32 path semantics. Canonical
+      // must not hard-code POSIX separators — it should use win32's resolver
+      // so relative paths joined with the Windows cwd use backslashes.
+      const winKaos: Kaos = {
+        name: 'mock-win32',
+        pathClass: () => 'win32',
+        normpath: (p: string) => win32Path.normalize(p),
+        gethome: () => 'C:\\Users\\test',
+        getcwd: () => 'C:\\work\\project',
+        chdir: async () => {},
+        stat: async () => ({
+          stMode: 0,
+          stIno: 0,
+          stDev: 0,
+          stNlink: 0,
+          stUid: 0,
+          stGid: 0,
+          stSize: 0,
+          stAtime: 0,
+          stMtime: 0,
+          stCtime: 0,
+        }),
+        iterdir: async function* () {},
+        glob: async function* () {},
+        readBytes: async () => Buffer.alloc(0),
+        readText: async () => '',
+        readLines: async function* () {},
+        writeBytes: async () => 0,
+        writeText: async () => 0,
+        mkdir: async () => {},
+        exec: async () => {
+          throw new Error('not implemented');
+        },
+        execWithEnv: async () => {
+          throw new Error('not implemented');
+        },
+      };
+
+      // Nested set so the outer beforeEach token is still restored cleanly
+      // by afterEach; we explicitly reset the inner token here.
+      const innerToken = setCurrentKaos(winKaos);
+      try {
+        const rel = new KaosPath('foo\\bar').canonical();
+        // Resolved against 'C:\\work\\project' → 'C:\\work\\project\\foo\\bar'.
+        // Critically: NO forward slashes in the result.
+        expect(rel.toString()).toBe('C:\\work\\project\\foo\\bar');
+        expect(rel.toString().includes('/')).toBe(false);
+
+        const abs = new KaosPath('C:\\foo\\..\\bar').canonical();
+        expect(abs.toString()).toBe('C:\\bar');
+
+        expect(() => new KaosPath('D:\\logs').relativeTo(new KaosPath('C:\\work'))).toThrow(
+          /not within/,
+        );
+        expect(
+          new KaosPath('C:\\Work\\Project').relativeTo(new KaosPath('c:\\work')).toString(),
+        ).toBe('Project');
+
+        expect(new KaosPath('C:\\base').joinpath('D:\\logs').toString()).toBe('D:\\logs');
+        expect(new KaosPath('C:\\base').joinpath('\\rooted').toString()).toBe('C:\\rooted');
+        expect(new KaosPath('C:\\base').joinpath('C:relative').toString()).toBe(
+          'C:\\base\\relative',
+        );
+        expect(new KaosPath('C:\\base').joinpath('D:relative').toString()).toBe('D:relative');
+        expect(() => new KaosPath('D:relative').canonical()).toThrow(/drive-relative/);
+        await expect(new KaosPath('D:relative').readText()).rejects.toThrow(/drive-relative/);
+      } finally {
+        resetCurrentKaos(innerToken);
+      }
+    });
+  });
+
+  describe('exists and file operations', () => {
+    it('should reject I/O when the current kaos path class differs from the path', async () => {
+      const innerToken = setCurrentKaos(makeMockKaos('win32'));
+      const p = new KaosPath('C:\\work\\project\\file.txt');
+      resetCurrentKaos(innerToken);
+
+      await expect(p.readText()).rejects.toThrow(/Cannot read win32 path/);
+      await expect(p.stat()).rejects.toThrow(/Cannot stat win32 path/);
+      await expect(p.exists()).rejects.toThrow(/Cannot check win32 path/);
+    });
+
+    it('should detect file existence', async () => {
+      const p = new KaosPath(join(tmpDir, 'hello.txt'));
+      expect(await p.exists()).toBe(false);
+      await p.writeText('hello');
+      expect(await p.exists()).toBe(true);
+    });
+
+    it('should write and read text', async () => {
+      const p = new KaosPath(join(tmpDir, 'test.txt'));
+      await p.writeText('hello world');
+      const text = await p.readText();
+      expect(text).toBe('hello world');
+    });
+
+    it('should identify files and directories', async () => {
+      const f = new KaosPath(join(tmpDir, 'file.txt'));
+      await f.writeText('content');
+      expect(await f.isFile()).toBe(true);
+      expect(await f.isDir()).toBe(false);
+
+      const d = new KaosPath(tmpDir);
+      expect(await d.isDir()).toBe(true);
+      expect(await d.isFile()).toBe(false);
+    });
+
+    it('should append text', async () => {
+      const p = new KaosPath(join(tmpDir, 'append.txt'));
+      await p.writeText('hello');
+      await p.appendText(' world');
+      const text = await p.readText();
+      expect(text).toBe('hello world');
+    });
+
+    it('should create directories', async () => {
+      const d = new KaosPath(join(tmpDir, 'a', 'b', 'c'));
+      await d.mkdir({ parents: true });
+      expect(await d.isDir()).toBe(true);
+    });
+
+    it('should handle existOk for mkdir', async () => {
+      const d = new KaosPath(tmpDir);
+      await expect(d.mkdir({ existOk: true })).resolves.toBeUndefined();
+    });
+
+    it('should return false for isFile on a non-existent path', async () => {
+      // exists()/isFile()/isDir() all swallow stat errors and return false
+      // for missing paths. Pin that behavior so a regression does not
+      // silently start throwing on absent files.
+      const p = new KaosPath(join(tmpDir, 'does-not-exist.txt'));
+      expect(await p.isFile()).toBe(false);
+    });
+
+    it('should return false for isDir on a non-existent path', async () => {
+      const p = new KaosPath(join(tmpDir, 'also-missing'));
+      expect(await p.isDir()).toBe(false);
+    });
+
+    it('should append text with an explicit encoding option', async () => {
+      // appendText accepts an encoding option that threads through to
+      // kaos.writeText({ mode: 'a', encoding }). Exercising the explicit
+      // encoding branch keeps the option wiring honest.
+      const p = new KaosPath(join(tmpDir, 'enc-append.txt'));
+      await p.writeText('head-');
+      await p.appendText('tail', { encoding: 'utf-8' });
+      expect(await p.readText()).toBe('head-tail');
+    });
+  });
+
+  describe('iterdir and glob', () => {
+    it('should iterate directory entries', async () => {
+      await new KaosPath(join(tmpDir, 'a.txt')).writeText('a');
+      await new KaosPath(join(tmpDir, 'b.txt')).writeText('b');
+      await new KaosPath(join(tmpDir, 'c.md')).writeText('c');
+
+      const entries: string[] = [];
+      const dir = new KaosPath(tmpDir);
+      for await (const entry of dir.iterdir()) {
+        entries.push(entry.name);
+      }
+      expect([...entries].toSorted()).toEqual(['a.txt', 'b.txt', 'c.md']);
+    });
+
+    it('should glob for matching files', async () => {
+      await new KaosPath(join(tmpDir, 'foo.txt')).writeText('foo');
+      await new KaosPath(join(tmpDir, 'bar.txt')).writeText('bar');
+      await new KaosPath(join(tmpDir, 'baz.md')).writeText('baz');
+
+      const matches: string[] = [];
+      const dir = new KaosPath(tmpDir);
+      for await (const entry of dir.glob('*.txt')) {
+        matches.push(entry.name);
+      }
+      expect([...matches].toSorted()).toEqual(['bar.txt', 'foo.txt']);
+    });
+  });
+
+  describe('read and write bytes', () => {
+    it('should write and read binary data', async () => {
+      const p = new KaosPath(join(tmpDir, 'data.bin'));
+      const data = Buffer.from([0x00, 0x01, 0x02, 0xfe, 0xff]);
+      const written = await p.writeBytes(data);
+      expect(written).toBe(5);
+
+      const read = await p.readBytes();
+      expect(Buffer.compare(read, data)).toBe(0);
+    });
+  });
+
+  describe('readLines', () => {
+    it('should yield lines from a file', async () => {
+      const p = new KaosPath(join(tmpDir, 'lines.txt'));
+      await p.writeText('line1\nline2\nline3');
+
+      const lines: string[] = [];
+      for await (const line of p.readLines()) {
+        lines.push(line);
+      }
+      // readLines yields lines with trailing \n except for the last line
+      expect(lines).toEqual(['line1\n', 'line2\n', 'line3']);
+    });
+  });
+
+  describe('fromLocalPath and toLocalPath', () => {
+    it('should round-trip a path string', () => {
+      const original = '/usr/local/bin/node';
+      const p = KaosPath.fromLocalPath(original);
+      expect(p.toLocalPath()).toBe(original);
+      expect(p.toString()).toBe(original);
+    });
+  });
+
+  describe('equals', () => {
+    it('returns true for two KaosPath instances with the same path string', () => {
+      const a = new KaosPath('/foo/bar');
+      const b = new KaosPath('/foo/bar');
+      expect(a.equals(b)).toBe(true);
+    });
+
+    it('returns false for different path strings', () => {
+      const a = new KaosPath('/foo/bar');
+      const b = new KaosPath('/foo/baz');
+      expect(a.equals(b)).toBe(false);
+    });
+
+    it('returns true after joining equivalent segments', () => {
+      const a = new KaosPath('/foo').div('bar');
+      const b = new KaosPath('/foo/bar');
+      expect(a.equals(b)).toBe(true);
+    });
+
+    it('is symmetric', () => {
+      const a = new KaosPath('/a/b/c');
+      const b = new KaosPath('/a/b/c');
+      expect(a.equals(b)).toBe(b.equals(a));
+    });
+
+    it('returns false for the same string with different path classes', () => {
+      const posixPath = new KaosPath('C:\\workspace');
+      const innerToken = setCurrentKaos(makeMockKaos('win32'));
+      try {
+        const winPath = new KaosPath('C:\\workspace');
+        expect(posixPath.toString()).toBe(winPath.toString());
+        expect(posixPath.equals(winPath)).toBe(false);
+      } finally {
+        resetCurrentKaos(innerToken);
+      }
+    });
+
+    it('rejects div() with a KaosPath from a different path class', () => {
+      const posixPath = new KaosPath('/workspace');
+      const innerToken = setCurrentKaos(makeMockKaos('win32'));
+      try {
+        const winPath = new KaosPath('C:\\workspace');
+        expect(() => posixPath.div(winPath)).toThrow(/Cannot join win32 path to posix path/);
+      } finally {
+        resetCurrentKaos(innerToken);
+      }
+    });
+  });
+});
diff --git a/packages/kaos/test/shell.test.ts b/packages/kaos/test/shell.test.ts
new file mode 100644
index 000000000..c1e5f0d96
--- /dev/null
+++ b/packages/kaos/test/shell.test.ts
@@ -0,0 +1,246 @@
+import { mkdtemp, rm, stat as fsStat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { resetCurrentKaos, setCurrentKaos } from '#/current';
+import type { KaosToken } from '#/current';
+import type { Kaos } from '#/kaos';
+import { LocalKaos } from '#/local';
+import type { KaosProcess } from '#/process';
+
+/**
+ * Helper to run a shell command via /bin/sh -c and collect stdout/stderr/exitCode.
+ * Since the new Kaos.exec(...args) doesn't take options, timeout is implemented
+ * by killing the process after the given duration.
+ */
+async function runSh(
+  kaos: Kaos,
+  command: string,
+  options?: { timeout?: number; stdinData?: string },
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const proc: KaosProcess = await kaos.exec('/bin/sh', '-c', command);
+
+  // Set up timeout if requested
+  let timedOut = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  if (options?.timeout !== undefined) {
+    timer = setTimeout(() => {
+      timedOut = true;
+      void proc.kill('SIGKILL');
+    }, options.timeout);
+  }
+
+  // If stdinData is provided, write it and close stdin
+  if (options?.stdinData !== undefined) {
+    proc.stdin.write(options.stdinData);
+    proc.stdin.end();
+  } else {
+    proc.stdin.end();
+  }
+
+  // Collect stdout and stderr concurrently with waiting for process exit
+  const stdoutChunks: Buffer[] = [];
+  const stderrChunks: Buffer[] = [];
+
+  const stdoutDone = new Promise<void>((resolve) => {
+    proc.stdout.on('data', (chunk: Buffer) => {
+      stdoutChunks.push(chunk);
+    });
+    proc.stdout.on('end', () => {
+      resolve();
+    });
+  });
+
+  const stderrDone = new Promise<void>((resolve) => {
+    proc.stderr.on('data', (chunk: Buffer) => {
+      stderrChunks.push(chunk);
+    });
+    proc.stderr.on('end', () => {
+      resolve();
+    });
+  });
+
+  const exitCode = await proc.wait();
+  await stdoutDone;
+  await stderrDone;
+
+  if (timer !== undefined) {
+    clearTimeout(timer);
+  }
+
+  return {
+    stdout: Buffer.concat(stdoutChunks).toString('utf-8'),
+    stderr: Buffer.concat(stderrChunks).toString('utf-8'),
+    exitCode: timedOut ? -1 : exitCode,
+  };
+}
+
+describe.skipIf(process.platform === 'win32')('LocalKaos shell operations', () => {
+  let kaos: Kaos;
+  let token: KaosToken;
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'kaos-shell-'));
+    kaos = new LocalKaos();
+    token = setCurrentKaos(kaos);
+  });
+
+  afterEach(async () => {
+    resetCurrentKaos(token);
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  // NOTE: These tests mirror Python test_local_kaos_sh.py one-for-one.
+  // Python pins stderr to '' on every non-error case and uses inline_snapshot
+  // for exact stdout comparisons — the TS side now matches that strength so
+  // any future drift (e.g. a rogue newline or a leaked warning) is caught.
+
+  it('should run a simple command', async () => {
+    const result = await runSh(kaos, "echo 'Hello World'");
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe('Hello World\n');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should handle command with error', async () => {
+    const result = await runSh(kaos, 'ls /nonexistent/directory');
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stdout).toBe('');
+    expect(result.stderr).toContain('No such file or directory');
+  });
+
+  it('should support command chaining with &&', async () => {
+    const result = await runSh(kaos, "echo 'First' && echo 'Second'");
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe('First\nSecond\n');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should support command pipe', async () => {
+    const result = await runSh(kaos, "echo 'Hello World' | wc -w");
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.trim()).toBe('2');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should handle command with timeout (completes before timeout)', async () => {
+    // Python asserts stdout='' for `sleep 0.1` so pin that exactly — if the
+    // helper ever introduces its own chatter we want to hear about it.
+    const result = await runSh(kaos, 'sleep 0.1', { timeout: 5000 });
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe('');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should handle timeout expiration', async () => {
+    // Python raises TimeoutError from its helper; the TS helper surfaces the
+    // same condition as exitCode === -1 after force-killing the process.
+    // The contract pinned here is "super-short timeout kills a long sleep".
+    const result = await runSh(kaos, 'sleep 60', { timeout: 100 });
+    expect(result.exitCode).toBe(-1);
+  });
+
+  it('should pass environment variables to shell', async () => {
+    const result = await runSh(kaos, 'TEST_VAR=\'test_value\'; export TEST_VAR; echo "$TEST_VAR"');
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe('test_value\n');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should perform file operations', async () => {
+    // Mirror Python test_file_operations: two separate kaos.exec calls so
+    // that the "file lands on disk between calls" invariant is actually
+    // exercised, plus explicit stat() check.
+    const filePath = join(tmpDir, 'test_file.txt');
+
+    const write = await runSh(kaos, `echo 'Test content' > "${filePath}"`);
+    expect(write.exitCode).toBe(0);
+    expect(write.stdout).toBe('');
+    expect(write.stderr).toBe('');
+
+    const statInfo = await fsStat(filePath);
+    expect(statInfo.isFile()).toBe(true);
+
+    const read = await runSh(kaos, `cat "${filePath}"`);
+    expect(read.exitCode).toBe(0);
+    expect(read.stdout).toBe('Test content\n');
+    expect(read.stderr).toBe('');
+  });
+
+  it('should handle stdin data', async () => {
+    // Mirror Python test_command_reads_stdin: use the shell `read` builtin,
+    // which requires a newline-terminated input. Previously the TS version
+    // was a trivial `cat` passthrough that did not exercise `read`.
+    const result = await runSh(kaos, 'read value; printf \'%s\\n\' "$value"', {
+      stdinData: 'from stdin\n',
+    });
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe('from stdin\n');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should execute commands sequentially with ;', async () => {
+    const result = await runSh(kaos, "echo 'One'; echo 'Two'");
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe('One\nTwo\n');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should support conditional execution with ||', async () => {
+    const result = await runSh(kaos, "false || echo 'Success'");
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe('Success\n');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should support multiple pipes', async () => {
+    const result = await runSh(kaos, "printf '1\\n2\\n3\\n' | grep '2' | wc -l");
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.trim()).toBe('1');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should handle text processing with sed', async () => {
+    const result = await runSh(kaos, "echo 'apple banana cherry' | sed 's/banana/orange/'");
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe('apple orange cherry\n');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should support command substitution', async () => {
+    const result = await runSh(kaos, 'echo "Result: $(echo hello)"');
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe('Result: hello\n');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should support arithmetic substitution', async () => {
+    const result = await runSh(kaos, 'echo "Answer: $((2 + 2))"');
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe('Answer: 4\n');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should handle very long output', async () => {
+    const result = await runSh(kaos, 'seq 1 100 | head -50');
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain('1');
+    expect(result.stdout).toContain('50');
+    expect(result.stdout).not.toContain('51');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should read multiple lines from stdin', async () => {
+    const result = await runSh(
+      kaos,
+      'count=0; while IFS= read -r _; do count=$((count+1)); done; printf \'%s\\n\' "$count"',
+      { stdinData: 'alpha\nbeta\ngamma\n' },
+    );
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.trim()).toBe('3');
+    expect(result.stderr).toBe('');
+  });
+});
diff --git a/packages/kaos/test/ssh-create.test.ts b/packages/kaos/test/ssh-create.test.ts
new file mode 100644
index 000000000..72135eaf3
--- /dev/null
+++ b/packages/kaos/test/ssh-create.test.ts
@@ -0,0 +1,375 @@
+import { EventEmitter } from 'node:events';
+
+import type { AnyAuthMethod, ConnectConfig, SFTPWrapper, Stats as SFTPStats } from 'ssh2';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { SSHKaos as SSHKaosType } from '#/ssh';
+
+interface CreateHarnessState {
+  attemptedKeys: string[];
+  connectConfigs: ConnectConfig[];
+  endCalls: number;
+  readFileCalls: string[];
+}
+
+interface CreateHarnessOptions {
+  onConnect?: (client: EventEmitter, config: ConnectConfig, state: CreateHarnessState) => void;
+  readFileValues?: Record<string, string>;
+  sftp?: SFTPWrapper;
+  sftpError?: Error;
+}
+
+function makeStats(isDirectory: boolean): SFTPStats {
+  return {
+    mode: isDirectory ? 0o040755 : 0o100644,
+    uid: 1000,
+    gid: 1000,
+    size: 0,
+    atime: 0,
+    mtime: 0,
+    isDirectory: () => isDirectory,
+    isFile: () => !isDirectory,
+    isBlockDevice: () => false,
+    isCharacterDevice: () => false,
+    isSymbolicLink: () => false,
+    isFIFO: () => false,
+    isSocket: () => false,
+  };
+}
+
+function createSuccessfulSftp(): SFTPWrapper {
+  return {
+    realpath(path: string, callback: (err: Error | undefined, absPath: string) => void): void {
+      if (path === '.') {
+        callback(undefined, '/home/tester');
+        return;
+      }
+      callback(undefined, path);
+    },
+    stat(path: string, callback: (err: Error | undefined, stats: SFTPStats) => void): void {
+      callback(undefined, makeStats(path !== '/home/tester/file.txt'));
+    },
+    end(): void {
+      // no-op
+    },
+  } as SFTPWrapper;
+}
+
+async function loadSSHModule(options: CreateHarnessOptions = {}): Promise<{
+  SSHKaos: typeof SSHKaosType;
+  state: CreateHarnessState;
+}> {
+  vi.resetModules();
+
+  const state: CreateHarnessState = {
+    attemptedKeys: [],
+    connectConfigs: [],
+    endCalls: 0,
+    readFileCalls: [],
+  };
+
+  class MockClient extends EventEmitter {
+    connect(config: ConnectConfig): void {
+      state.connectConfigs.push(config);
+      if (options.onConnect) {
+        options.onConnect(this, config, state);
+        return;
+      }
+      queueMicrotask(() => {
+        this.emit('ready');
+      });
+    }
+
+    end(): void {
+      state.endCalls += 1;
+      queueMicrotask(() => {
+        this.emit('close');
+      });
+    }
+
+    sftp(callback: (err?: Error, sftp?: SFTPWrapper) => void): void {
+      if (options.sftpError) {
+        callback(options.sftpError);
+        return;
+      }
+      callback(undefined, options.sftp ?? createSuccessfulSftp());
+    }
+  }
+
+  vi.doMock('ssh2', () => ({
+    Client: MockClient,
+    utils: {
+      sftp: {
+        STATUS_CODE: {
+          NO_SUCH_FILE: 2,
+          PERMISSION_DENIED: 3,
+          FAILURE: 4,
+          NO_CONNECTION: 6,
+          CONNECTION_LOST: 7,
+          OP_UNSUPPORTED: 8,
+        },
+      },
+    },
+  }));
+
+  vi.doMock('node:fs/promises', () => ({
+    readFile: vi.fn(async (path: string) => {
+      state.readFileCalls.push(path);
+      const value = options.readFileValues?.[path];
+      if (value === undefined) {
+        throw new Error(`Unexpected readFile(${path})`);
+      }
+      return value;
+    }),
+  }));
+
+  const { SSHKaos } = await import('#/ssh');
+  return { SSHKaos, state };
+}
+
+afterEach(() => {
+  vi.doUnmock('ssh2');
+  vi.restoreAllMocks();
+  vi.resetModules();
+});
+
+describe('SSHKaos.create()', () => {
+  it('initializes cwd equal to gethome() when no cwd option is passed', async () => {
+    // Pins the Python test_ssh_kaos.py::test_pathclass_home_and_cwd invariant:
+    // on a fresh SSH connection without an explicit cwd, `getcwd()` must equal
+    // `gethome()`. The smoke-level SSH suite can't cover this because its
+    // beforeEach chdirs into a per-test remote dir; this mock harness lets us
+    // check the invariant without a live SSH server.
+    const { SSHKaos } = await loadSSHModule();
+
+    const ssh = await SSHKaos.create({
+      host: 'example.com',
+      username: 'tester',
+    });
+
+    expect(ssh.pathClass()).toBe('posix');
+    expect(ssh.gethome()).toBe('/home/tester');
+    expect(ssh.getcwd()).toBe('/home/tester');
+    expect(ssh.getcwd()).toBe(ssh.gethome());
+  });
+
+  it('rejects a cwd that resolves to a regular file', async () => {
+    const sftp = {
+      realpath(path: string, callback: (err: Error | undefined, absPath: string) => void): void {
+        if (path === '.') {
+          callback(undefined, '/home/tester');
+          return;
+        }
+        callback(undefined, '/home/tester/file.txt');
+      },
+      stat(_path: string, callback: (err: Error | undefined, stats: SFTPStats) => void): void {
+        callback(undefined, makeStats(false));
+      },
+      end(): void {
+        // no-op
+      },
+    } as SFTPWrapper;
+
+    const { SSHKaos, state } = await loadSSHModule({ sftp });
+
+    const error = await SSHKaos.create({
+      host: 'example.com',
+      username: 'tester',
+      cwd: 'file.txt',
+    }).catch((error: unknown) => error);
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).name).toBe('KaosValueError');
+    expect((error as Error).message).toMatch(/not a directory/);
+    expect(state.endCalls).toBe(1);
+  });
+
+  it('tries multiple private keys via authHandler until one succeeds', async () => {
+    const { SSHKaos, state } = await loadSSHModule({
+      readFileValues: {
+        '/keys/second': 'second-key',
+      },
+      onConnect(client, config, harnessState) {
+        const authHandler = config.authHandler;
+        if (typeof authHandler !== 'function') {
+          client.emit('error', new Error('missing authHandler'));
+          return;
+        }
+
+        const requestNextKey = (): void => {
+          authHandler([], false, (auth: string | AnyAuthMethod | false) => {
+            expect(auth).not.toBe(false);
+            expect(typeof auth).toBe('object');
+            if (auth === false || typeof auth !== 'object') {
+              client.emit('error', new Error('authHandler returned no auth method'));
+              return;
+            }
+            if (auth.type !== 'publickey') {
+              client.emit('error', new Error(`unexpected auth type: ${auth.type}`));
+              return;
+            }
+            const key =
+              typeof auth.key === 'string'
+                ? auth.key
+                : Buffer.isBuffer(auth.key)
+                  ? auth.key.toString('utf-8')
+                  : JSON.stringify(auth.key);
+            harnessState.attemptedKeys.push(key);
+            if (key === 'first-key') {
+              requestNextKey();
+              return;
+            }
+            queueMicrotask(() => {
+              client.emit('ready');
+            });
+          });
+        };
+
+        requestNextKey();
+      },
+    });
+
+    const ssh = await SSHKaos.create({
+      host: 'example.com',
+      username: 'tester',
+      keyContents: ['first-key'],
+      keyPaths: ['/keys/second'],
+    });
+
+    expect(ssh.getcwd()).toBe('/home/tester');
+    expect(state.readFileCalls).toEqual(['/keys/second']);
+    expect(state.attemptedKeys).toEqual(['first-key', 'second-key']);
+    expect(state.connectConfigs[0]?.authHandler).toBeTypeOf('function');
+    expect(state.connectConfigs[0]?.privateKey).toBeUndefined();
+  });
+
+  it('ends the client when opening SFTP fails after connect succeeds', async () => {
+    const { SSHKaos, state } = await loadSSHModule({
+      sftpError: new Error('sftp open failed'),
+    });
+
+    await expect(
+      SSHKaos.create({
+        host: 'example.com',
+        username: 'tester',
+      }),
+    ).rejects.toThrow(/sftp open failed/);
+    expect(state.endCalls).toBe(1);
+  });
+
+  it('merges extraOptions into the ssh2 ConnectConfig', async () => {
+    const { SSHKaos, state } = await loadSSHModule();
+
+    await SSHKaos.create({
+      host: 'example.com',
+      username: 'tester',
+      extraOptions: {
+        keepaliveInterval: 10_000,
+        readyTimeout: 5_000,
+        // Cast to the ssh2 Algorithms shape — deliberately narrow for the test
+        // harness so we can assert pass-through without pulling the full ssh2
+        // type graph.
+        algorithms: { cipher: ['aes256-ctr'] } as never,
+      },
+    });
+
+    const cfg = state.connectConfigs[0];
+    expect(cfg).toBeDefined();
+    expect(cfg?.keepaliveInterval).toBe(10_000);
+    expect(cfg?.readyTimeout).toBe(5_000);
+    expect(cfg?.algorithms).toEqual({ cipher: ['aes256-ctr'] });
+    // Managed fields must still come from top-level options.
+    expect(cfg?.host).toBe('example.com');
+    expect(cfg?.username).toBe('tester');
+  });
+
+  it('managed fields override extraOptions when both are specified', async () => {
+    const { SSHKaos, state } = await loadSSHModule();
+
+    await SSHKaos.create({
+      host: 'managed.example.com',
+      username: 'managed',
+      extraOptions: {
+        // Malicious / accidental attempts to override managed fields must
+        // NOT win — the top-level values take precedence.
+        host: 'attacker.example.com',
+        username: 'attacker',
+        port: 1234,
+      } as never,
+    });
+
+    const cfg = state.connectConfigs[0];
+    expect(cfg?.host).toBe('managed.example.com');
+    expect(cfg?.username).toBe('managed');
+    expect(cfg?.port).toBe(22); // default, not the 1234 from extraOptions
+  });
+
+  it('forwards a password-only connection without building an authHandler', async () => {
+    // Password auth without any private keys must wire ssh2 ConnectConfig.password
+    // directly rather than constructing an authHandler (the handler is only
+    // needed when we're rotating through multiple private keys).
+    const { SSHKaos, state } = await loadSSHModule();
+
+    const ssh = await SSHKaos.create({
+      host: 'example.com',
+      username: 'tester',
+      password: 'hunter2',
+    });
+
+    const cfg = state.connectConfigs[0];
+    expect(cfg?.password).toBe('hunter2');
+    expect(cfg?.authHandler).toBeUndefined();
+    expect(ssh.getcwd()).toBe('/home/tester');
+  });
+
+  it('queues password after private keys when both are provided', async () => {
+    // When the user supplies both keyContents and a password, buildAuthHandler
+    // should try every private key first, then fall back to password auth.
+    // We observe this by walking the handler to exhaustion and recording
+    // which auth entries it yields.
+    const yielded: string[] = [];
+    const { SSHKaos } = await loadSSHModule({
+      onConnect(client, config) {
+        const handler = config.authHandler;
+        if (typeof handler !== 'function') {
+          client.emit('error', new Error('missing authHandler'));
+          return;
+        }
+
+        // Drain the handler — it yields one auth method per call until it
+        // runs out, at which point it must emit `false` to signal "no more
+        // auth methods" (but we stop as soon as we see the password entry).
+        const pump = (): void => {
+          handler([], false, (auth: string | AnyAuthMethod | false) => {
+            if (auth === false) {
+              client.emit('error', new Error('unexpected end of auth queue'));
+              return;
+            }
+            if (typeof auth !== 'object') {
+              client.emit('error', new Error(`unexpected auth: ${auth}`));
+              return;
+            }
+            yielded.push(auth.type);
+            if (auth.type === 'password') {
+              queueMicrotask(() => {
+                client.emit('ready');
+              });
+              return;
+            }
+            pump();
+          });
+        };
+        pump();
+      },
+    });
+
+    await SSHKaos.create({
+      host: 'example.com',
+      username: 'tester',
+      keyContents: ['only-key'],
+      password: 'hunter2',
+    });
+
+    expect(yielded).toEqual(['publickey', 'password']);
+  });
+});
diff --git a/packages/kaos/test/ssh-process.test.ts b/packages/kaos/test/ssh-process.test.ts
new file mode 100644
index 000000000..c0d46d542
--- /dev/null
+++ b/packages/kaos/test/ssh-process.test.ts
@@ -0,0 +1,223 @@
+import { spawn } from 'node:child_process';
+import { PassThrough } from 'node:stream';
+
+import { describe, expect, test } from 'vitest';
+
+import { SSHProcess } from '#/ssh';
+
+/**
+ * Build a minimal fake ssh2 ClientChannel that satisfies SSHProcess's needs:
+ *
+ * - behaves as a Readable (for stdout) via PassThrough
+ * - exposes .stderr as a Readable via a second PassThrough
+ * - records .signal() and .close() calls
+ * - emits 'close' / 'exit' on-demand
+ */
+function createFakeChannel(): {
+  channel: unknown;
+  signalCalls: string[];
+  closeCalls: number;
+  emitClose: () => void;
+  emitExit: (code: number) => void;
+} {
+  const stdout = new PassThrough();
+  const stderr = new PassThrough();
+  const signalCalls: string[] = [];
+  let closeCalls = 0;
+
+  // Listeners registered via channel.on(...)
+  const listeners = new Map<string, Array<(...args: unknown[]) => void>>();
+
+  const channel = Object.assign(stdout, {
+    stderr,
+    signal(name: string): void {
+      signalCalls.push(name);
+    },
+    close(): void {
+      closeCalls++;
+    },
+    // Override .on to capture lifecycle listeners ('close', 'exit') while
+    // still letting the underlying Readable receive 'data'/'end'/'error'.
+    on(event: string, cb: (...args: unknown[]) => void): unknown {
+      if (event === 'close' || event === 'exit') {
+        let arr = listeners.get(event);
+        if (!arr) {
+          arr = [];
+          listeners.set(event, arr);
+        }
+        arr.push(cb);
+        return channel;
+      }
+      return PassThrough.prototype.on.call(stdout, event, cb);
+    },
+  });
+
+  function emit(event: string, ...args: unknown[]): void {
+    const arr = listeners.get(event);
+    if (!arr) return;
+    for (const cb of arr) {
+      cb(...args);
+    }
+  }
+
+  return {
+    channel,
+    signalCalls,
+    get closeCalls() {
+      return closeCalls;
+    },
+    emitClose: () => {
+      emit('close');
+    },
+    emitExit: (code: number) => {
+      emit('exit', code);
+    },
+  };
+}
+
+function createChildBackedChannel(): { channel: unknown } {
+  const child = spawn(process.execPath, [
+    '-e',
+    [
+      "process.on('SIGTERM', () => {",
+      "  console.log('cleanup done');",
+      '  process.exit(42);',
+      '});',
+      "console.log('ready');",
+      'setInterval(() => {}, 1000);',
+    ].join('\n'),
+  ]);
+
+  const stdout = new PassThrough();
+  child.stdout.pipe(stdout);
+
+  const channel = Object.assign(stdout, {
+    stderr: child.stderr,
+    signal(name: string): void {
+      child.kill(`SIG${name}` as NodeJS.Signals);
+    },
+    close(): void {
+      child.kill('SIGTERM');
+    },
+    on(event: string, listener: (...args: unknown[]) => void): unknown {
+      if (event === 'exit' || event === 'close') {
+        child.on(event, listener as (...args: [number | null]) => void);
+        return channel;
+      }
+      return PassThrough.prototype.on.call(stdout, event, listener);
+    },
+  });
+
+  return { channel };
+}
+
+describe('SSHProcess.kill()', () => {
+  test('kill("SIGTERM") sends "TERM" to channel.signal (strips SIG prefix)', async () => {
+    const fake = createFakeChannel();
+    const proc = new SSHProcess(fake.channel as never);
+
+    await proc.kill('SIGTERM');
+
+    expect(fake.signalCalls).toEqual(['TERM']);
+    expect(fake.closeCalls).toBe(0);
+  });
+
+  test('kill("SIGINT") sends "INT"', async () => {
+    const fake = createFakeChannel();
+    const proc = new SSHProcess(fake.channel as never);
+
+    await proc.kill('SIGINT');
+
+    expect(fake.signalCalls).toEqual(['INT']);
+  });
+
+  test('kill("SIGKILL") sends "KILL"', async () => {
+    const fake = createFakeChannel();
+    const proc = new SSHProcess(fake.channel as never);
+
+    await proc.kill('SIGKILL');
+
+    expect(fake.signalCalls).toEqual(['KILL']);
+  });
+
+  test('kill() with no signal defaults to "TERM"', async () => {
+    const fake = createFakeChannel();
+    const proc = new SSHProcess(fake.channel as never);
+
+    await proc.kill();
+
+    expect(fake.signalCalls).toEqual(['TERM']);
+  });
+
+  test('kill() with a signal that does not start with "SIG" is passed through unchanged', async () => {
+    const fake = createFakeChannel();
+    const proc = new SSHProcess(fake.channel as never);
+
+    // Cast through unknown because NodeJS.Signals is a string-literal type.
+    await proc.kill('USR1' as unknown as NodeJS.Signals);
+
+    expect(fake.signalCalls).toEqual(['USR1']);
+  });
+
+  test('wait() resolves with the exit code emitted before close', async () => {
+    const fake = createFakeChannel();
+    const proc = new SSHProcess(fake.channel as never);
+
+    // Fire exit first, then close.
+    fake.emitExit(42);
+    fake.emitClose();
+
+    const code = await proc.wait();
+    expect(code).toBe(42);
+    expect(proc.exitCode).toBe(42);
+  });
+
+  test('wait() resolves with 1 (abnormal) when close arrives without exit', async () => {
+    const fake = createFakeChannel();
+    const proc = new SSHProcess(fake.channel as never);
+
+    fake.emitClose();
+
+    const code = await proc.wait();
+    expect(code).toBe(1);
+    expect(proc.exitCode).toBe(1);
+  });
+
+  test('kill(SIGTERM) preserves cleanup output and the real exit status', async () => {
+    const { channel } = createChildBackedChannel();
+    const proc = new SSHProcess(channel as never);
+    const stdoutChunks: Buffer[] = [];
+
+    proc.stdout.on('data', (chunk: Buffer) => {
+      stdoutChunks.push(Buffer.from(chunk));
+    });
+    const stdoutEnded = new Promise<void>((resolve) => {
+      proc.stdout.on('end', () => {
+        resolve();
+      });
+    });
+
+    const firstChunk = await new Promise<Buffer>((resolve) => {
+      proc.stdout.once('data', (chunk: Buffer) => {
+        resolve(chunk);
+      });
+    });
+    expect(firstChunk.toString()).toContain('ready');
+
+    await proc.kill('SIGTERM');
+
+    const exitCode = await proc.wait();
+    await Promise.race([
+      stdoutEnded,
+      new Promise<void>((resolve) => {
+        setTimeout(resolve, 250);
+      }),
+    ]);
+    const stdout = Buffer.concat(stdoutChunks).toString('utf-8');
+
+    expect(exitCode).toBe(42);
+    expect(proc.exitCode).toBe(42);
+    expect(stdout).toContain('ready');
+    expect(stdout).toContain('cleanup done');
+  }, 10000);
+});
diff --git a/packages/kaos/test/ssh.test.ts b/packages/kaos/test/ssh.test.ts
new file mode 100644
index 000000000..9d441f67e
--- /dev/null
+++ b/packages/kaos/test/ssh.test.ts
@@ -0,0 +1,1473 @@
+import { EventEmitter } from 'node:events';
+
+import { resetCurrentKaos, setCurrentKaos } from '#/current';
+import type { KaosToken } from '#/current';
+import { KaosFileExistsError, KaosValueError } from '#/errors';
+import { KaosPath } from '#/path';
+import {
+  KaosConnectionError,
+  KaosFileNotFoundError,
+  KaosPermissionError,
+  KaosSSHError,
+  SSHKaos,
+} from '#/ssh';
+import type { StatResult } from '#/types';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, test } from 'vitest';
+
+// Environment variable configuration for SSH connection
+const SSH_SMOKE = process.env['KAOS_SSH_SMOKE'] === '1';
+const SSH_HOST = process.env['KAOS_SSH_HOST'] ?? '127.0.0.1';
+const SSH_PORT = Number(process.env['KAOS_SSH_PORT'] ?? '22');
+const SSH_USERNAME = process.env['KAOS_SSH_USERNAME'];
+const SSH_PASSWORD = process.env['KAOS_SSH_PASSWORD'];
+const SSH_KEY_PATHS = process.env['KAOS_SSH_KEY_PATHS']?.split(',').filter(Boolean);
+const SSH_KEY_CONTENTS = process.env['KAOS_SSH_KEY_CONTENTS']?.split('|||').filter(Boolean);
+
+// S_IFMT mask and file type constants
+const S_IFMT = 0o170000;
+const S_IFDIR = 0o040000;
+const S_IFREG = 0o100000;
+
+async function streamToBuffer(stream: NodeJS.ReadableStream): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.from(chunk as Buffer));
+  }
+  return Buffer.concat(chunks);
+}
+
+// Explicit opt-in smoke: set KAOS_SSH_SMOKE=1 plus SSH credentials.
+describe.skipIf(process.platform === 'win32' || !SSH_SMOKE)('SSHKaos smoke', () => {
+  let sshKaos: SSHKaos;
+  let remoteBase = '';
+  let token: KaosToken | undefined;
+
+  beforeAll(async () => {
+    if (SSH_USERNAME === undefined) {
+      throw new Error('KAOS_SSH_SMOKE=1 requires KAOS_SSH_USERNAME');
+    }
+
+    // Dynamic import to avoid compilation errors when ssh2 is not available
+    const { SSHKaos: SSHKaosClass } = await import('#/ssh');
+    sshKaos = await SSHKaosClass.create({
+      host: SSH_HOST,
+      port: SSH_PORT,
+      username: SSH_USERNAME,
+      password: SSH_PASSWORD,
+      keyPaths: SSH_KEY_PATHS,
+      keyContents: SSH_KEY_CONTENTS,
+    });
+  });
+
+  beforeEach(async () => {
+    // Create an isolated remote directory for each test
+    const uuid = Math.random().toString(36).slice(2);
+    remoteBase = `${sshKaos.gethome()}/.kaos_test_${process.pid}_${uuid}`;
+    await sshKaos.mkdir(remoteBase, { parents: true, existOk: true });
+    await sshKaos.chdir(remoteBase);
+  });
+
+  afterEach(async () => {
+    if (token !== undefined) {
+      resetCurrentKaos(token);
+      token = undefined;
+    }
+    // Cleanup the remote directory best-effort, but always restore cwd.
+    if (remoteBase.length > 0) {
+      try {
+        const proc = await sshKaos.exec('rm', '-rf', remoteBase);
+        await proc.wait();
+      } finally {
+        remoteBase = '';
+        await sshKaos.chdir(sshKaos.gethome());
+      }
+    }
+  });
+
+  afterAll(async () => {
+    if (sshKaos) await sshKaos.close();
+  });
+
+  test('pathClass, home, and cwd', () => {
+    const home = sshKaos.gethome();
+    const cwd = sshKaos.getcwd();
+
+    expect(sshKaos.pathClass()).toBe('posix');
+    expect(home.length).toBeGreaterThan(0);
+    expect(cwd.length).toBeGreaterThan(0);
+    // Home should be absolute
+    expect(home.startsWith('/')).toBe(true);
+    // cwd should be absolute
+    expect(cwd.startsWith('/')).toBe(true);
+  });
+
+  test('cwd defaults to home immediately after connect', () => {
+    // A freshly connected session sets cwd to the remote home directory,
+    // so the two must be string-equal before any chdir.
+    expect(sshKaos.getcwd()).toBe(sshKaos.gethome());
+  });
+
+  test('chdir updates real path', async () => {
+    await sshKaos.chdir(remoteBase);
+    expect(sshKaos.getcwd()).toBe(remoteBase);
+
+    await sshKaos.mkdir(remoteBase + '/child', { existOk: true });
+    await sshKaos.chdir('child');
+    expect(sshKaos.getcwd()).toBe(remoteBase + '/child');
+
+    await sshKaos.chdir('..');
+    expect(sshKaos.getcwd()).toBe(remoteBase);
+  });
+
+  test('exec respects cwd', async () => {
+    await sshKaos.chdir(remoteBase);
+
+    const proc = await sshKaos.exec('pwd');
+    const out = (await streamToBuffer(proc.stdout)).toString().trim();
+    const code = await proc.wait();
+
+    expect(code).toBe(0);
+    expect(out).toBe(remoteBase);
+  });
+
+  test('exec wait before read', async () => {
+    const proc = await sshKaos.exec('echo', 'output');
+
+    const exitCode = await proc.wait();
+    const output = (await streamToBuffer(proc.stdout)).toString().trim();
+
+    expect(exitCode).toBe(0);
+    expect(output).toBe('output');
+  });
+
+  test('mkdir respects existOk', async () => {
+    const nestedDir = remoteBase + '/deep/level';
+
+    await sshKaos.mkdir(nestedDir, { parents: true, existOk: false });
+
+    // Python test_mkdir_respects_exist_ok pins `pytest.raises(FileExistsError)`
+    // — match that strength by asserting the specific KaosFileExistsError class
+    // rather than any throwable.
+    await expect(sshKaos.mkdir(nestedDir, { existOk: false })).rejects.toBeInstanceOf(
+      KaosFileExistsError,
+    );
+
+    await sshKaos.mkdir(nestedDir, { parents: true, existOk: true });
+  });
+
+  test('stat reports directory and file metadata', async () => {
+    const dirStat = await sshKaos.stat(remoteBase, { followSymlinks: false });
+    expect((dirStat.stMode & S_IFMT) === S_IFDIR).toBe(true);
+
+    const filePath = remoteBase + '/payload.txt';
+    const payload = 'metadata';
+    await sshKaos.writeText(filePath, payload);
+
+    const fileStat = await sshKaos.stat(filePath);
+    expect((fileStat.stMode & S_IFMT) === S_IFREG).toBe(true);
+    expect(fileStat.stSize).toBe(payload.length);
+    expect(fileStat.stNlink).toBeGreaterThanOrEqual(0);
+  });
+
+  test('KaosPath roundtrip via SSH', async () => {
+    token = setCurrentKaos(sshKaos);
+    await sshKaos.chdir(remoteBase);
+
+    const textPath = remoteBase + '/text.txt';
+    const bytesPath = remoteBase + '/blob.bin';
+
+    const textPayload = 'Hello SSH\n';
+    const appended = 'More data\n';
+    const written = await sshKaos.writeText(textPath, textPayload);
+    expect(written).toBe(textPayload.length);
+
+    const appendedLen = await sshKaos.writeText(textPath, appended, { mode: 'a' });
+    expect(appendedLen).toBe(appended.length);
+
+    const fullText = await sshKaos.readText(textPath);
+    expect(fullText).toBe(textPayload + appended);
+
+    const lines: string[] = [];
+    for await (const line of sshKaos.readLines(textPath)) {
+      lines.push(line);
+    }
+    expect(lines).toEqual(['Hello SSH', 'More data']);
+
+    const bytesPayload = Buffer.from(Array.from({ length: 32 }, (_, i) => i));
+    const bytesWritten = await sshKaos.writeBytes(bytesPath, bytesPayload);
+    expect(bytesWritten).toBe(bytesPayload.length);
+
+    const roundtrip = await sshKaos.readBytes(bytesPath);
+    expect(Buffer.compare(roundtrip, bytesPayload)).toBe(0);
+
+    expect(KaosPath.cwd().toString()).toBe(remoteBase);
+  });
+
+  test('iterdir lists child entries', async () => {
+    await sshKaos.writeText(remoteBase + '/file1.txt', '1');
+    await sshKaos.writeText(remoteBase + '/file2.log', '2');
+    await sshKaos.mkdir(remoteBase + '/subdir', { existOk: true });
+
+    const entries: string[] = [];
+    for await (const entry of sshKaos.iterdir(remoteBase)) {
+      entries.push(entry);
+    }
+    const names = new Set(entries.map((e) => e.split('/').pop()!));
+
+    expect(names).toEqual(new Set(['file1.txt', 'file2.log', 'subdir']));
+  });
+
+  test('glob is case sensitive', async () => {
+    await sshKaos.writeText(remoteBase + '/file.log', 'lowercase');
+    await sshKaos.writeText(remoteBase + '/FILE.LOG', 'uppercase');
+
+    const matches = new Set<string>();
+    for await (const path of sshKaos.glob(remoteBase, '*.log')) {
+      matches.add(path);
+    }
+    expect(matches.has(remoteBase + '/file.log')).toBe(true);
+    expect(matches.has(remoteBase + '/FILE.LOG')).toBe(false);
+
+    await expect(async () => {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      for await (const _ of sshKaos.glob(remoteBase, '*.log', { caseSensitive: false })) {
+        // should throw before yielding
+      }
+    }).rejects.toThrow('Case insensitive glob is not supported');
+  });
+
+  test('exec streams stdout and stderr', async () => {
+    const proc = await sshKaos.exec('sh', '-c', "printf 'out\\n' && printf 'err\\n' 1>&2");
+
+    const [stdoutData, stderrData] = await Promise.all([
+      streamToBuffer(proc.stdout),
+      streamToBuffer(proc.stderr),
+    ]);
+    const exitCode = await proc.wait();
+
+    expect(exitCode).toBe(0);
+    expect(proc.exitCode).toBe(0);
+    expect(stdoutData.toString().trim()).toBe('out');
+    expect(stderrData.toString().trim()).toBe('err');
+  });
+
+  // NOTE: these execWithEnv tests require the remote sshd to accept the
+  // injected variable names via its `AcceptEnv` directive (or an equivalent
+  // mechanism). Stock OpenSSH only whitelists LANG/LC_*; if the test server
+  // is not configured to accept KAOS_TEST_*, these tests will fail — which
+  // is exactly the signal we want (it reveals the silent env-drop bug that
+  // the Python version has).
+  test('execWithEnv delivers a single env var to the remote process', async () => {
+    const proc = await sshKaos.execWithEnv(['sh', '-c', 'printf "%s" "${KAOS_TEST_MARKER}"'], {
+      KAOS_TEST_MARKER: 'beacon42',
+    });
+    const out = (await streamToBuffer(proc.stdout)).toString();
+    const code = await proc.wait();
+
+    expect(code).toBe(0);
+    expect(out).toBe('beacon42');
+  });
+
+  test('execWithEnv delivers multiple env vars', async () => {
+    const proc = await sshKaos.execWithEnv(
+      ['sh', '-c', 'printf "%s|%s" "${KAOS_TEST_A}" "${KAOS_TEST_B}"'],
+      { KAOS_TEST_A: 'hello', KAOS_TEST_B: 'world' },
+    );
+    const out = (await streamToBuffer(proc.stdout)).toString();
+    const code = await proc.wait();
+
+    expect(code).toBe(0);
+    expect(out).toBe('hello|world');
+  });
+
+  test('execWithEnv preserves values with shell metacharacters', async () => {
+    // Single quotes, dollar signs, backticks, pipes, ampersands, redirects,
+    // double quotes, and a backslash — anything an unsafe impl might mangle.
+    const value = `it's $HOME \`id\`; | & < > " \\`;
+    const proc = await sshKaos.execWithEnv(['sh', '-c', 'printf "%s" "${KAOS_TEST_VALUE}"'], {
+      KAOS_TEST_VALUE: value,
+    });
+    const out = (await streamToBuffer(proc.stdout)).toString();
+    const code = await proc.wait();
+
+    expect(code).toBe(0);
+    expect(out).toBe(value);
+  });
+
+  test('exec rejects empty command', async () => {
+    await expect((sshKaos.exec as (...args: string[]) => Promise<unknown>)()).rejects.toThrow();
+  });
+
+  test('process kill updates returncode', async () => {
+    const proc = await sshKaos.exec('sh', '-c', 'echo ready; sleep 30');
+
+    // Read the first line to know the process has started
+    const firstChunk = await new Promise<Buffer>((resolve) => {
+      proc.stdout.once('data', (chunk: Buffer) => {
+        resolve(chunk);
+      });
+    });
+    expect(firstChunk.toString().trim()).toBe('ready');
+    expect(proc.exitCode).toBeNull();
+
+    await proc.kill();
+    const exitCode = await proc.wait();
+
+    expect(exitCode).not.toBe(0);
+    expect(proc.exitCode).toBe(exitCode);
+    expect(proc.pid).toBe(-1);
+  });
+});
+
+// These tests don't need a live SSH connection — they exercise the
+// argument-validation guards that run before any network I/O. We invoke the
+// methods through the prototype so no real instance is constructed.
+describe('SSHKaos argument validation', () => {
+  it('exec() throws with the correct class name when args is empty', () => {
+    const fakeThis = {} as SSHKaos;
+    expect(() => SSHKaos.prototype.exec.call(fakeThis)).toThrow(KaosValueError);
+    expect(() => SSHKaos.prototype.exec.call(fakeThis)).toThrow(/SSHKaos\.exec\(\)/);
+  });
+
+  it('execWithEnv() throws with the correct class name when args is empty', () => {
+    const fakeThis = {} as SSHKaos;
+    expect(() => SSHKaos.prototype.execWithEnv.call(fakeThis, [])).toThrow(KaosValueError);
+    expect(() => SSHKaos.prototype.execWithEnv.call(fakeThis, [])).toThrow(
+      /SSHKaos\.execWithEnv\(\)/,
+    );
+  });
+
+  // glob() is an async generator, so the caseSensitive=false guard fires on
+  // the first pull rather than at call-time. We verify both the error class
+  // (KaosValueError) and the fact that it rejects before touching SFTP.
+  it('glob(caseSensitive: false) rejects with KaosValueError', async () => {
+    const instance = Object.create(SSHKaos.prototype) as SSHKaos;
+    const internal = instance as unknown as { _cwd: string; _sftp: unknown };
+    internal._cwd = '/tmp';
+    internal._sftp = {};
+
+    const gen = instance.glob('/some/path', '*', { caseSensitive: false });
+    await expect(gen.next()).rejects.toBeInstanceOf(KaosValueError);
+  });
+});
+
+// chdir should refuse to treat a regular file (or anything that isn't a
+// directory) as the new working directory. Without this guard, `sftp.realpath`
+// happily returns file paths and later relative reads/writes/execs would
+// resolve against a file — silently wrong. We exercise this by constructing
+// a fake SFTP that returns a file stat so the test needs no live SSH.
+describe('SSHKaos.chdir directory validation', () => {
+  // Minimal SFTPWrapper stub with only the methods chdir needs.
+  function makeFakeSftp(target: string, isDir: boolean): unknown {
+    return {
+      realpath(_path: string, cb: (err: Error | null | undefined, absPath: string) => void): void {
+        cb(null, target);
+      },
+      stat(
+        _path: string,
+        cb: (err: Error | null | undefined, stats: Record<string, unknown>) => void,
+      ): void {
+        cb(null, {
+          mode: isDir ? 0o040755 : 0o100644,
+          size: 0,
+          uid: 0,
+          gid: 0,
+          atime: 0,
+          mtime: 0,
+          isDirectory: () => isDir,
+          isFile: () => !isDir,
+          isSymbolicLink: () => false,
+          isSocket: () => false,
+          isCharacterDevice: () => false,
+          isBlockDevice: () => false,
+          isFIFO: () => false,
+        });
+      },
+    };
+  }
+
+  function makeFakeInstance(sftp: unknown, cwd: string): SSHKaos {
+    // Bypass the real constructor (which requires a live ssh2 client) and
+    // populate just the private fields that chdir touches.
+    const instance = Object.create(SSHKaos.prototype) as SSHKaos;
+    const internal = instance as unknown as { _sftp: unknown; _cwd: string };
+    internal._sftp = sftp;
+    internal._cwd = cwd;
+    return instance;
+  }
+
+  it('rejects a target that resolves to a regular file', async () => {
+    const target = '/tmp/not-a-dir.txt';
+    const sftp = makeFakeSftp(target, /*isDir=*/ false);
+    const kaos = makeFakeInstance(sftp, '/tmp');
+
+    await expect(kaos.chdir(target)).rejects.toThrow(KaosValueError);
+    await expect(kaos.chdir(target)).rejects.toThrow(/not a directory/);
+    // cwd must remain unchanged on failure.
+    expect(kaos.getcwd()).toBe('/tmp');
+  });
+
+  it('accepts a target that resolves to a directory', async () => {
+    const target = '/tmp/real-dir';
+    const sftp = makeFakeSftp(target, /*isDir=*/ true);
+    const kaos = makeFakeInstance(sftp, '/tmp');
+
+    await kaos.chdir(target);
+    expect(kaos.getcwd()).toBe(target);
+  });
+});
+
+// These tests pin the SFTPError → KaosError mapping contract. They use a
+// fake SFTPWrapper that invokes callbacks with errors carrying the standard
+// SFTP status codes (NO_SUCH_FILE=2, PERMISSION_DENIED=3), so they run in
+// CI without needing a live SSH connection.
+//
+// The mapping lives in the promisified SFTP helpers in ssh.ts, so every
+// SSHKaos method that touches SFTP automatically throws a KaosSSHError
+// subclass (KaosFileNotFoundError / KaosPermissionError / …) instead of
+// the raw ssh2 error.
+describe('SSHKaos SFTP error mapping', () => {
+  const NO_SUCH_FILE = 2;
+  const PERMISSION_DENIED = 3;
+
+  interface FailingMethods {
+    stat?: boolean;
+    lstat?: boolean;
+    readFile?: boolean;
+    writeFile?: boolean;
+    appendFile?: boolean;
+    mkdir?: boolean;
+    readdir?: boolean;
+  }
+
+  function makeSftpError(errorCode: number): Error {
+    const err = new Error('simulated SFTP error');
+    (err as unknown as { code: number }).code = errorCode;
+    return err;
+  }
+
+  // Minimal SFTPWrapper stub. For each I/O method, when `failing[method]` is
+  // true the callback is invoked with an error carrying `code`; otherwise
+  // a harmless default is returned. Only the methods that SSHKaos actually
+  // calls need to be stubbed.
+  function makeFakeSftp(errorCode: number, failing: FailingMethods): unknown {
+    const dirStats = {
+      mode: 0o040755,
+      size: 0,
+      uid: 0,
+      gid: 0,
+      atime: 0,
+      mtime: 0,
+      isDirectory: (): boolean => true,
+      isFile: (): boolean => false,
+      isSymbolicLink: (): boolean => false,
+      isSocket: (): boolean => false,
+      isCharacterDevice: (): boolean => false,
+      isBlockDevice: (): boolean => false,
+      isFIFO: (): boolean => false,
+    };
+
+    return {
+      realpath(path: string, cb: (err: Error | null, abs: string) => void): void {
+        cb(null, path);
+      },
+      stat(_path: string, cb: (err: Error | null, stats?: unknown) => void): void {
+        if (failing.stat === true) {
+          cb(makeSftpError(errorCode));
+          return;
+        }
+        cb(null, dirStats);
+      },
+      lstat(_path: string, cb: (err: Error | null, stats?: unknown) => void): void {
+        if (failing.lstat === true) {
+          cb(makeSftpError(errorCode));
+          return;
+        }
+        cb(null, dirStats);
+      },
+      readFile(_path: string, cb: (err: Error | null, data?: Buffer) => void): void {
+        if (failing.readFile === true) {
+          cb(makeSftpError(errorCode));
+          return;
+        }
+        cb(null, Buffer.alloc(0));
+      },
+      writeFile(_path: string, _data: unknown, cb: (err: Error | null) => void): void {
+        if (failing.writeFile === true) {
+          cb(makeSftpError(errorCode));
+          return;
+        }
+        cb(null);
+      },
+      appendFile(_path: string, _data: unknown, cb: (err: Error | null) => void): void {
+        if (failing.appendFile === true) {
+          cb(makeSftpError(errorCode));
+          return;
+        }
+        cb(null);
+      },
+      mkdir(_path: string, cb: (err: Error | null) => void): void {
+        if (failing.mkdir === true) {
+          cb(makeSftpError(errorCode));
+          return;
+        }
+        cb(null);
+      },
+      readdir(_path: string, cb: (err: Error | null, list?: unknown[]) => void): void {
+        if (failing.readdir === true) {
+          cb(makeSftpError(errorCode));
+          return;
+        }
+        cb(null, []);
+      },
+      // exists() always reports the file is absent so plain mkdir takes the
+      // create path (where `failing.mkdir` decides the outcome).
+      exists(_path: string, cb: (exists: boolean) => void): void {
+        cb(false);
+      },
+    };
+  }
+
+  function makeFakeKaos(sftp: unknown): SSHKaos {
+    const instance = Object.create(SSHKaos.prototype) as SSHKaos;
+    const internal = instance as unknown as { _sftp: unknown; _cwd: string; _home: string };
+    internal._sftp = sftp;
+    internal._cwd = '/';
+    internal._home = '/';
+    return instance;
+  }
+
+  // ── stat(): the one method that already wraps errors. ────────────────
+
+  it('stat() maps NO_SUCH_FILE → KaosFileNotFoundError', async () => {
+    const kaos = makeFakeKaos(makeFakeSftp(NO_SUCH_FILE, { stat: true }));
+    await expect(kaos.stat('/missing')).rejects.toBeInstanceOf(KaosFileNotFoundError);
+  });
+
+  it('stat() maps PERMISSION_DENIED → KaosPermissionError', async () => {
+    const kaos = makeFakeKaos(makeFakeSftp(PERMISSION_DENIED, { stat: true }));
+    await expect(kaos.stat('/forbidden')).rejects.toBeInstanceOf(KaosPermissionError);
+  });
+
+  it('stat({ followSymlinks: false }) wraps lstat errors the same way', async () => {
+    const kaos = makeFakeKaos(makeFakeSftp(NO_SUCH_FILE, { lstat: true }));
+    await expect(kaos.stat('/missing', { followSymlinks: false })).rejects.toBeInstanceOf(
+      KaosFileNotFoundError,
+    );
+  });
+
+  it('stat() wraps unmapped failures as the base KaosSSHError', async () => {
+    // FAILURE=4 is not specifically mapped → generic KaosSSHError.
+    const kaos = makeFakeKaos(makeFakeSftp(4, { stat: true }));
+    await expect(kaos.stat('/x')).rejects.toBeInstanceOf(KaosSSHError);
+  });
+
+  it('stat() maps NO_CONNECTION → KaosConnectionError', async () => {
+    // SFTP STATUS_CODE.NO_CONNECTION = 6
+    const kaos = makeFakeKaos(makeFakeSftp(6, { stat: true }));
+    await expect(kaos.stat('/x')).rejects.toBeInstanceOf(KaosConnectionError);
+  });
+
+  it('stat() maps CONNECTION_LOST → KaosConnectionError', async () => {
+    // SFTP STATUS_CODE.CONNECTION_LOST = 7
+    const kaos = makeFakeKaos(makeFakeSftp(7, { stat: true }));
+    await expect(kaos.stat('/x')).rejects.toBeInstanceOf(KaosConnectionError);
+  });
+
+  it('stat() wraps errors without a numeric code as generic KaosSSHError', async () => {
+    // An error object whose `.code` is not a number (or absent entirely)
+    // must still be wrapped — the mapSftpError fallback should kick in.
+    const sftp = {
+      realpath(p: string, cb: (err: Error | null, abs: string) => void): void {
+        cb(null, p);
+      },
+      stat(_p: string, cb: (err: Error | null) => void): void {
+        // Error with no .code field
+        cb(new Error('no code here'));
+      },
+    };
+    const kaos = makeFakeKaos(sftp);
+    const err = await kaos.stat('/x').catch((error: unknown) => error);
+    expect(err).toBeInstanceOf(KaosSSHError);
+    expect((err as KaosSSHError).message).toContain('no code here');
+  });
+
+  it('stat() wraps non-Error rejections by stringifying them', async () => {
+    // The helper's getErrorMessage fallback handles non-Error values by
+    // calling String(error). Reject with a plain string and verify the
+    // wrap still produces a KaosSSHError with the string in the message.
+    const sftp = {
+      realpath(p: string, cb: (err: Error | null, abs: string) => void): void {
+        cb(null, p);
+      },
+      stat(_p: string, cb: (err: unknown) => void): void {
+        // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+        cb('raw-string-rejection');
+      },
+    };
+    const kaos = makeFakeKaos(sftp);
+    const err = await kaos.stat('/x').catch((error: unknown) => error);
+    expect(err).toBeInstanceOf(KaosSSHError);
+    expect((err as KaosSSHError).message).toContain('raw-string-rejection');
+  });
+
+  it('chdir() propagates a realpath failure as a KaosSSHError', async () => {
+    // sftpRealpath now runs through mapSftpError too — pin that contract.
+    const sftp = {
+      realpath(_p: string, cb: (err: Error) => void): void {
+        const err = new Error('realpath broke');
+        (err as unknown as { code: number }).code = 2;
+        cb(err);
+      },
+      stat(_p: string, _cb: unknown): void {
+        throw new Error('should not be called');
+      },
+    };
+    const instance = Object.create(SSHKaos.prototype) as SSHKaos;
+    const internal = instance as unknown as { _sftp: unknown; _cwd: string };
+    internal._sftp = sftp;
+    internal._cwd = '/';
+    await expect(instance.chdir('/missing')).rejects.toBeInstanceOf(KaosFileNotFoundError);
+  });
+
+  // ── Other I/O methods: mapping is pushed into the promisified helpers
+  // in ssh.ts so every method gets the same wrapping for free. ─────────
+
+  it('readText() maps NO_SUCH_FILE → KaosFileNotFoundError', async () => {
+    const kaos = makeFakeKaos(makeFakeSftp(NO_SUCH_FILE, { readFile: true }));
+    await expect(kaos.readText('/missing')).rejects.toBeInstanceOf(KaosFileNotFoundError);
+  });
+
+  it('readBytes() maps NO_SUCH_FILE → KaosFileNotFoundError', async () => {
+    const kaos = makeFakeKaos(makeFakeSftp(NO_SUCH_FILE, { readFile: true }));
+    await expect(kaos.readBytes('/missing')).rejects.toBeInstanceOf(KaosFileNotFoundError);
+  });
+
+  it('writeText() maps PERMISSION_DENIED → KaosPermissionError', async () => {
+    const kaos = makeFakeKaos(makeFakeSftp(PERMISSION_DENIED, { writeFile: true }));
+    await expect(kaos.writeText('/forbidden', 'data')).rejects.toBeInstanceOf(KaosPermissionError);
+  });
+
+  it('writeText(append) maps PERMISSION_DENIED → KaosPermissionError', async () => {
+    const kaos = makeFakeKaos(makeFakeSftp(PERMISSION_DENIED, { appendFile: true }));
+    await expect(kaos.writeText('/forbidden', 'data', { mode: 'a' })).rejects.toBeInstanceOf(
+      KaosPermissionError,
+    );
+  });
+
+  it('writeBytes() maps PERMISSION_DENIED → KaosPermissionError', async () => {
+    const kaos = makeFakeKaos(makeFakeSftp(PERMISSION_DENIED, { writeFile: true }));
+    await expect(kaos.writeBytes('/forbidden', Buffer.from('x'))).rejects.toBeInstanceOf(
+      KaosPermissionError,
+    );
+  });
+
+  it('mkdir() maps PERMISSION_DENIED → KaosPermissionError', async () => {
+    const kaos = makeFakeKaos(makeFakeSftp(PERMISSION_DENIED, { mkdir: true }));
+    await expect(kaos.mkdir('/forbidden')).rejects.toBeInstanceOf(KaosPermissionError);
+  });
+
+  it('iterdir() maps NO_SUCH_FILE → KaosFileNotFoundError', async () => {
+    const kaos = makeFakeKaos(makeFakeSftp(NO_SUCH_FILE, { readdir: true }));
+    const gen = kaos.iterdir('/missing');
+    await expect(gen.next()).rejects.toBeInstanceOf(KaosFileNotFoundError);
+  });
+});
+
+// These tests exercise the pure command-building logic behind execWithEnv
+// without needing a live SSH connection. The actual end-to-end delivery of
+// env vars is validated by the smoke tests above when KAOS_SSH_SMOKE=1.
+describe('SSHKaos._buildExecCommand', () => {
+  // Bracket access so we can reach the private static helper from tests
+  // without changing its visibility in the public API.
+  const build = (
+    SSHKaos as unknown as {
+      _buildExecCommand: (args: string[], cwd: string, env?: Record<string, string>) => string;
+    }
+  )._buildExecCommand;
+
+  it('cd prefix + bare command when no env is supplied', () => {
+    expect(build(['ls', '-la'], '/home/user')).toBe('cd /home/user && ls -la');
+  });
+
+  it('injects inline assignments before the command', () => {
+    expect(build(['echo', 'x'], '/home/user', { FOO: 'bar' })).toBe(
+      'cd /home/user && FOO=bar echo x',
+    );
+  });
+
+  it('injects multiple env vars in declaration order', () => {
+    const out = build(['sh', '-c', 'echo $A $B'], '/home/user', { A: '1', B: '2' });
+    expect(out).toBe("cd /home/user && A=1 B=2 sh -c 'echo $A $B'");
+  });
+
+  it('quotes values containing shell metacharacters', () => {
+    // Single quote in value → shellQuote escapes via the '"'"' trick.
+    expect(build(['cmd'], '/home/user', { V: "it's" })).toBe(`cd /home/user && V='it'"'"'s' cmd`);
+    // Dollar sign, backticks, pipe, ampersand → single-quoted wholesale.
+    expect(build(['cmd'], '/home/user', { V: '$HOME `id` | &' })).toBe(
+      `cd /home/user && V='$HOME \`id\` | &' cmd`,
+    );
+  });
+
+  it('quotes an empty value as empty single quotes', () => {
+    expect(build(['cmd'], '/home/user', { V: '' })).toBe("cd /home/user && V='' cmd");
+  });
+
+  it('rejects env var names that are not valid POSIX identifiers', () => {
+    expect(() => build(['cmd'], '/home/user', { '1BAD': 'x' })).toThrow(KaosValueError);
+    expect(() => build(['cmd'], '/home/user', { 'WITH SPACE': 'x' })).toThrow(KaosValueError);
+    expect(() => build(['cmd'], '/home/user', { 'WITH=EQUALS': 'x' })).toThrow(KaosValueError);
+    expect(() => build(['cmd'], '/home/user', { '': 'x' })).toThrow(KaosValueError);
+  });
+
+  it('accepts underscored and mixed-case identifiers', () => {
+    expect(build(['cmd'], '/home/user', { _UNDER: '1', camelCase: '2' })).toBe(
+      'cd /home/user && _UNDER=1 camelCase=2 cmd',
+    );
+  });
+
+  it('skips the cd prefix when cwd is the empty string', () => {
+    expect(build(['cmd', 'arg'], '', { FOO: 'bar' })).toBe('FOO=bar cmd arg');
+  });
+
+  it('quotes cwd paths with spaces and special characters', () => {
+    expect(build(['cmd'], "/home/u ser's dir")).toBe(`cd '/home/u ser'"'"'s dir' && cmd`);
+  });
+
+  it('omits the assignment section entirely when env is an empty object', () => {
+    // Matches the behavior of plain exec() — no leading space, no KEY=...
+    expect(build(['cmd', 'arg'], '/home/user', {})).toBe('cd /home/user && cmd arg');
+  });
+});
+
+// These tests drive the SSHKaos read/stat/glob/iterdir happy paths via
+// fake SFTP wrappers, so they run in CI without a live SSH server. Without
+// them the smoke block is the only route to those code paths, which means
+// CI only sees the error branches.
+describe('SSHKaos mock success paths', () => {
+  interface TreeNode {
+    type: 'dir' | 'file';
+    children?: Record<string, TreeNode>;
+    content?: Buffer;
+    // Permission bits only — forces buildStMode to derive the type bits
+    // from the is* helpers (the "mode without type bits" branch) when true.
+    stripTypeBits?: boolean;
+  }
+
+  function makeStats(node: TreeNode): unknown {
+    const isDir = node.type === 'dir';
+    // Either include type bits (0o040000/0o100000) or strip them to force
+    // the buildStMode helper to derive them via isDirectory()/isFile().
+    const baseMode = isDir ? 0o040755 : 0o100644;
+    const mode = node.stripTypeBits === true ? baseMode & 0o7777 : baseMode;
+    return {
+      mode,
+      size: node.content ? node.content.length : 0,
+      uid: 1000,
+      gid: 1000,
+      atime: 100,
+      mtime: 200,
+      isDirectory: () => isDir,
+      isFile: () => !isDir,
+      isSymbolicLink: () => false,
+      isSocket: () => false,
+      isCharacterDevice: () => false,
+      isBlockDevice: () => false,
+      isFIFO: () => false,
+    };
+  }
+
+  function lookup(root: TreeNode, path: string): TreeNode | undefined {
+    if (path === '/') return root;
+    const parts = path.split('/').filter(Boolean);
+    let current: TreeNode | undefined = root;
+    for (const part of parts) {
+      if (!current?.children?.[part]) return undefined;
+      current = current.children[part];
+    }
+    return current;
+  }
+
+  // Fake SFTP that exposes a tree and implements the handful of callbacks
+  // SSHKaos actually calls. Anything not needed is left unimplemented.
+  function makeTreeSftp(root: TreeNode): unknown {
+    return {
+      realpath(path: string, cb: (err: Error | null, abs: string) => void): void {
+        cb(null, path);
+      },
+      stat(path: string, cb: (err: Error | null, stats?: unknown) => void): void {
+        const node = lookup(root, path);
+        if (!node) {
+          const err = new Error(`no such file: ${path}`);
+          (err as unknown as { code: number }).code = 2;
+          cb(err);
+          return;
+        }
+        cb(null, makeStats(node));
+      },
+      lstat(path: string, cb: (err: Error | null, stats?: unknown) => void): void {
+        const node = lookup(root, path);
+        if (!node) {
+          const err = new Error(`no such file: ${path}`);
+          (err as unknown as { code: number }).code = 2;
+          cb(err);
+          return;
+        }
+        cb(null, makeStats(node));
+      },
+      readdir(path: string, cb: (err: Error | null, list?: unknown[]) => void): void {
+        const node = lookup(root, path);
+        if (!node || node.type !== 'dir' || !node.children) {
+          const err = new Error(`not a directory: ${path}`);
+          (err as unknown as { code: number }).code = 2;
+          cb(err);
+          return;
+        }
+        cb(
+          null,
+          Object.entries(node.children).map(([filename, child]) => ({
+            filename,
+            attrs: makeStats(child),
+          })),
+        );
+      },
+      readFile(path: string, cb: (err: Error | null, data?: Buffer) => void): void {
+        const node = lookup(root, path);
+        if (!node || node.type !== 'file') {
+          const err = new Error(`no such file: ${path}`);
+          (err as unknown as { code: number }).code = 2;
+          cb(err);
+          return;
+        }
+        cb(null, node.content ?? Buffer.alloc(0));
+      },
+    };
+  }
+
+  function makeFakeKaos(sftp: unknown, cwd = '/'): SSHKaos {
+    const instance = Object.create(SSHKaos.prototype) as SSHKaos;
+    const internal = instance as unknown as { _sftp: unknown; _cwd: string; _home: string };
+    internal._sftp = sftp;
+    internal._cwd = cwd;
+    internal._home = '/home/tester';
+    return instance;
+  }
+
+  // ── path helpers ────────────────────────────────────────────────────
+
+  it('normpath delegates to posix.normalize', () => {
+    // No I/O — just the pure path function. Pins that normpath collapses
+    // `..` segments.
+    const kaos = makeFakeKaos(makeTreeSftp({ type: 'dir', children: {} }));
+    expect(kaos.normpath('/a/b/../c')).toBe('/a/c');
+  });
+
+  // ── stat + buildStMode variants ─────────────────────────────────────
+
+  it('stat() returns a StatResult with file-type bits preserved', async () => {
+    const root: TreeNode = {
+      type: 'dir',
+      children: {
+        'file.txt': { type: 'file', content: Buffer.from('hi') },
+      },
+    };
+    const kaos = makeFakeKaos(makeTreeSftp(root));
+
+    const fileStat: StatResult = await kaos.stat('/file.txt');
+    expect((fileStat.stMode & 0o170000) === 0o100000).toBe(true);
+    expect(fileStat.stSize).toBe(2);
+    expect(fileStat.stUid).toBe(1000);
+  });
+
+  it('stat() derives type bits from is* helpers when mode lacks them', async () => {
+    // mode = 0o755 has zero in the S_IFMT bits, so buildStMode must fall
+    // back to isDirectory()/isFile() to fill them in.
+    const root: TreeNode = {
+      type: 'dir',
+      stripTypeBits: true,
+      children: {
+        'bare.txt': { type: 'file', stripTypeBits: true, content: Buffer.from('x') },
+      },
+    };
+    const kaos = makeFakeKaos(makeTreeSftp(root));
+
+    const dirStat = await kaos.stat('/');
+    expect((dirStat.stMode & 0o170000) === 0o040000).toBe(true);
+
+    const fileStat = await kaos.stat('/bare.txt');
+    expect((fileStat.stMode & 0o170000) === 0o100000).toBe(true);
+  });
+
+  it('stat({ followSymlinks: false }) uses the lstat branch', async () => {
+    // No actual symlinks — just verify the alternate code path is taken
+    // (lstat callback is wired up, it returns stats without throwing).
+    const root: TreeNode = {
+      type: 'dir',
+      children: { 'a.txt': { type: 'file', content: Buffer.from('hi') } },
+    };
+    const kaos = makeFakeKaos(makeTreeSftp(root));
+    const result = await kaos.stat('/a.txt', { followSymlinks: false });
+    expect(result.stSize).toBe(2);
+  });
+
+  // ── iterdir ────────────────────────────────────────────────────────
+
+  it('iterdir yields directory entries', async () => {
+    const root: TreeNode = {
+      type: 'dir',
+      children: {
+        tree: {
+          type: 'dir',
+          children: {
+            'a.txt': { type: 'file', content: Buffer.from('a') },
+            'b.txt': { type: 'file', content: Buffer.from('b') },
+            sub: { type: 'dir', children: {} },
+          },
+        },
+      },
+    };
+    const kaos = makeFakeKaos(makeTreeSftp(root));
+
+    const entries: string[] = [];
+    for await (const entry of kaos.iterdir('/tree')) {
+      entries.push(entry);
+    }
+    expect(new Set(entries)).toEqual(new Set(['/tree/a.txt', '/tree/b.txt', '/tree/sub']));
+  });
+
+  // ── glob ────────────────────────────────────────────────────────────
+
+  it('glob matches flat patterns against the directory', async () => {
+    const root: TreeNode = {
+      type: 'dir',
+      children: {
+        tree: {
+          type: 'dir',
+          children: {
+            'root.txt': { type: 'file', content: Buffer.from('r') },
+            'root.log': { type: 'file', content: Buffer.from('l') },
+          },
+        },
+      },
+    };
+    const kaos = makeFakeKaos(makeTreeSftp(root));
+
+    const matches: string[] = [];
+    for await (const m of kaos.glob('/tree', '*.txt')) {
+      matches.push(m);
+    }
+    expect(matches).toEqual(['/tree/root.txt']);
+  });
+
+  it('glob recurses with **/pattern to match nested files', async () => {
+    const root: TreeNode = {
+      type: 'dir',
+      children: {
+        tree: {
+          type: 'dir',
+          children: {
+            'root.txt': { type: 'file', content: Buffer.from('r') },
+            sub: {
+              type: 'dir',
+              children: {
+                'nested.txt': { type: 'file', content: Buffer.from('n') },
+                deep: {
+                  type: 'dir',
+                  children: {
+                    'deeper.txt': { type: 'file', content: Buffer.from('d') },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+    const kaos = makeFakeKaos(makeTreeSftp(root));
+
+    const matches: string[] = [];
+    for await (const m of kaos.glob('/tree', '**/*.txt')) {
+      matches.push(m);
+    }
+    const names = new Set(matches);
+    expect(names).toEqual(
+      new Set(['/tree/root.txt', '/tree/sub/nested.txt', '/tree/sub/deep/deeper.txt']),
+    );
+    // Pin the de-dup invariant — no single file should appear twice.
+    expect(matches.length).toBe(new Set(matches).size);
+  });
+
+  it('glob with bare ** yields basePath and every nested entry', async () => {
+    const root: TreeNode = {
+      type: 'dir',
+      children: {
+        tree: {
+          type: 'dir',
+          children: {
+            'root.txt': { type: 'file', content: Buffer.from('r') },
+            sub: {
+              type: 'dir',
+              children: {
+                'nested.txt': { type: 'file', content: Buffer.from('n') },
+              },
+            },
+          },
+        },
+      },
+    };
+    const kaos = makeFakeKaos(makeTreeSftp(root));
+
+    const matches: string[] = [];
+    for await (const m of kaos.glob('/tree', '**')) {
+      matches.push(m);
+    }
+    const set = new Set(matches);
+    expect(set.has('/tree')).toBe(true);
+    expect(set.has('/tree/root.txt')).toBe(true);
+    expect(set.has('/tree/sub')).toBe(true);
+    expect(set.has('/tree/sub/nested.txt')).toBe(true);
+  });
+
+  it('glob with a nested literal path recurses only into the named dir', async () => {
+    // Pattern `sub/*.txt` → literal `sub` segment, then `*.txt` inside it.
+    // Exercises the non-`**` recursive branch.
+    const root: TreeNode = {
+      type: 'dir',
+      children: {
+        tree: {
+          type: 'dir',
+          children: {
+            'root.txt': { type: 'file', content: Buffer.from('r') },
+            sub: {
+              type: 'dir',
+              children: {
+                'a.txt': { type: 'file', content: Buffer.from('a') },
+                'b.log': { type: 'file', content: Buffer.from('b') },
+              },
+            },
+          },
+        },
+      },
+    };
+    const kaos = makeFakeKaos(makeTreeSftp(root));
+
+    const matches: string[] = [];
+    for await (const m of kaos.glob('/tree', 'sub/*.txt')) {
+      matches.push(m);
+    }
+    expect(matches).toEqual(['/tree/sub/a.txt']);
+  });
+
+  it('glob silently skips unreadable directories', async () => {
+    // If readdir() fails the generator should return without throwing —
+    // makes glob tolerant of permission-limited subtrees.
+    const sftp = {
+      realpath(p: string, cb: (err: Error | null, abs: string) => void): void {
+        cb(null, p);
+      },
+      readdir(_p: string, cb: (err: Error | null, list?: unknown[]) => void): void {
+        const err = new Error('permission denied');
+        (err as unknown as { code: number }).code = 3;
+        cb(err);
+      },
+    };
+    const kaos = makeFakeKaos(sftp);
+
+    const matches: string[] = [];
+    for await (const m of kaos.glob('/locked', '*.txt')) {
+      matches.push(m);
+    }
+    expect(matches).toEqual([]);
+  });
+
+  // ── readLines empty-file early return ─────────────────────────────
+
+  it('readLines yields nothing for an empty file', async () => {
+    // `readText` returns an empty string, so the generator must take the
+    // early-return branch instead of walking `splitlines()`.
+    const root: TreeNode = {
+      type: 'dir',
+      children: { 'empty.txt': { type: 'file', content: Buffer.alloc(0) } },
+    };
+    const kaos = makeFakeKaos(makeTreeSftp(root));
+
+    const lines: string[] = [];
+    for await (const line of kaos.readLines('/empty.txt')) {
+      lines.push(line);
+    }
+    expect(lines).toEqual([]);
+  });
+
+  it('readText preserves valid U+FFFD while ignoring invalid utf-8 bytes', async () => {
+    const data = Buffer.concat([
+      Buffer.from('A\uFFFDB', 'utf-8'),
+      Buffer.from([0xff]),
+      Buffer.from('C', 'utf-8'),
+    ]);
+    const root: TreeNode = {
+      type: 'dir',
+      children: { 'mixed.txt': { type: 'file', content: data } },
+    };
+    const kaos = makeFakeKaos(makeTreeSftp(root));
+
+    await expect(kaos.readText('/mixed.txt', { errors: 'ignore' })).resolves.toBe('A\uFFFDBC');
+  });
+
+  // ── . / .. filter coverage ────────────────────────────────────────
+
+  it('iterdir at root "/" does not produce double-slash paths', async () => {
+    // Regression: `basePath + '/' + entry.filename` produced `//foo` when
+    // basePath was the filesystem root. Now uses `posix.join` to collapse.
+    const root: TreeNode = {
+      type: 'dir',
+      children: {
+        'a.txt': { type: 'file', content: Buffer.from('a') },
+        sub: { type: 'dir', children: {} },
+      },
+    };
+    const kaos = makeFakeKaos(makeTreeSftp(root), '/');
+
+    const entries: string[] = [];
+    for await (const entry of kaos.iterdir('/')) {
+      entries.push(entry);
+    }
+    expect(new Set(entries)).toEqual(new Set(['/a.txt', '/sub']));
+    expect(entries.every((e) => !e.includes('//'))).toBe(true);
+  });
+
+  it('glob at root "/" does not produce double-slash paths', async () => {
+    const root: TreeNode = {
+      type: 'dir',
+      children: {
+        'file.txt': { type: 'file', content: Buffer.from('x') },
+      },
+    };
+    const kaos = makeFakeKaos(makeTreeSftp(root), '/');
+
+    const matches: string[] = [];
+    for await (const m of kaos.glob('/', '*.txt')) {
+      matches.push(m);
+    }
+    expect(matches).toEqual(['/file.txt']);
+    expect(matches.every((p) => !p.includes('//'))).toBe(true);
+  });
+
+  it('iterdir filters out "." and ".." entries from readdir output', async () => {
+    // Some SFTP servers include `.` / `..` in readdir results, so the
+    // filter in SSHKaos.iterdir must skip them unconditionally. Inject
+    // those entries into the fake to exercise the filter branch.
+    const sftp = {
+      realpath(p: string, cb: (err: Error | null, abs: string) => void): void {
+        cb(null, p);
+      },
+      readdir(_p: string, cb: (err: Error | null, list?: unknown[]) => void): void {
+        cb(null, [
+          { filename: '.', attrs: { isDirectory: (): boolean => true } },
+          { filename: '..', attrs: { isDirectory: (): boolean => true } },
+          { filename: 'real.txt', attrs: { isDirectory: (): boolean => false } },
+        ]);
+      },
+    };
+    const kaos = makeFakeKaos(sftp, '/tree');
+
+    const entries: string[] = [];
+    for await (const e of kaos.iterdir('/tree')) {
+      entries.push(e);
+    }
+    // Only the real entry survives — the `.` / `..` are silently dropped.
+    expect(entries).toEqual(['/tree/real.txt']);
+  });
+
+  it('glob filters "." and ".." entries in both the ** and literal branches', async () => {
+    // Same fake readdir in two walks: one with `**` (covers the `**`
+    // branch filter) and one with a literal pattern (covers the non-`**`
+    // branch filter).
+    const sftp = {
+      realpath(p: string, cb: (err: Error | null, abs: string) => void): void {
+        cb(null, p);
+      },
+      readdir(_p: string, cb: (err: Error | null, list?: unknown[]) => void): void {
+        cb(null, [
+          {
+            filename: '.',
+            attrs: {
+              isDirectory: (): boolean => true,
+              isFile: (): boolean => false,
+            },
+          },
+          {
+            filename: '..',
+            attrs: {
+              isDirectory: (): boolean => true,
+              isFile: (): boolean => false,
+            },
+          },
+          {
+            filename: 'keeper.txt',
+            attrs: {
+              isDirectory: (): boolean => false,
+              isFile: (): boolean => true,
+            },
+          },
+        ]);
+      },
+    };
+    const kaos = makeFakeKaos(sftp, '/tree');
+
+    const viaStar: string[] = [];
+    for await (const m of kaos.glob('/tree', '*.txt')) viaStar.push(m);
+    expect(viaStar).toEqual(['/tree/keeper.txt']);
+
+    const viaStarStar: string[] = [];
+    for await (const m of kaos.glob('/tree', '**')) viaStarStar.push(m);
+    // The recursion into `.` / `..` must be skipped — we should see only
+    // the base dir and the keeper file, never an infinite loop.
+    expect(new Set(viaStarStar)).toEqual(new Set(['/tree', '/tree/keeper.txt']));
+  });
+
+  // ── glob error handling in the ** branch ──────────────────────────
+
+  it('glob ** silently aborts when readdir fails', async () => {
+    // Similar to the non-`**` readdir-error test, but forcing the code
+    // through the `**` case's own try/catch. Passing a bare `**` pattern
+    // takes the `currentPattern === '**'` branch, and the failing
+    // readdir exercises the swallow-and-return path inside it.
+    const sftp = {
+      realpath(p: string, cb: (err: Error | null, abs: string) => void): void {
+        cb(null, p);
+      },
+      readdir(_p: string, cb: (err: Error | null, list?: unknown[]) => void): void {
+        const err = new Error('denied');
+        (err as unknown as { code: number }).code = 3;
+        cb(err);
+      },
+    };
+    const kaos = makeFakeKaos(sftp, '/tree');
+
+    const matches: string[] = [];
+    for await (const m of kaos.glob('/tree', '**')) {
+      matches.push(m);
+    }
+    // Pattern `**` with zero-directory match yields basePath itself
+    // BEFORE the readdir even runs, so we still see `/tree`. The
+    // important bit is that no exception propagates out.
+    expect(matches).toEqual(['/tree']);
+  });
+
+  // ── readBytes ──────────────────────────────────────────────────────
+
+  it('readBytes(n) returns only the first n bytes of the file', async () => {
+    const content = Buffer.from('0123456789');
+    const root: TreeNode = {
+      type: 'dir',
+      children: { 'data.bin': { type: 'file', content } },
+    };
+    const kaos = makeFakeKaos(makeTreeSftp(root));
+
+    const full = await kaos.readBytes('/data.bin');
+    expect(Buffer.compare(full, content)).toBe(0);
+
+    const first4 = await kaos.readBytes('/data.bin', 4);
+    expect(first4.toString()).toBe('0123');
+  });
+
+  // ── execWithEnv body ───────────────────────────────────────────────
+
+  it('execWithEnv calls clientExec with the env-prefixed command', async () => {
+    // We only exercise the _execInternal path via execWithEnv here — the
+    // command-building detail is already covered by the _buildExecCommand
+    // describe block. This test just pins that execWithEnv() with a valid
+    // non-empty args array routes through the internal helper.
+    const commands: string[] = [];
+    const fakeClient = {
+      exec(cmd: string, _a: unknown, _b?: unknown): void {
+        commands.push(cmd);
+        // Mimic a channel that never emits — we just want to observe the
+        // command string, not wait for real I/O.
+        throw new Error('stop');
+      },
+    };
+    const instance = Object.create(SSHKaos.prototype) as SSHKaos;
+    const internal = instance as unknown as { _client: unknown; _cwd: string; _home: string };
+    internal._client = fakeClient;
+    internal._cwd = '/home/tester';
+    internal._home = '/home/tester';
+
+    await expect(instance.execWithEnv(['echo', 'hi'], { FOO: 'bar' })).rejects.toThrow('stop');
+
+    expect(commands).toHaveLength(1);
+    expect(commands[0]).toBe('cd /home/tester && FOO=bar echo hi');
+  });
+});
+
+// These tests pin the non-race mkdir error branches in SSHKaos — the
+// "path already exists but is a file" and "parents=true with a final
+// directory already present under existOk=false" cases. All driven via
+// fake SFTP wrappers so no live server is required.
+describe('SSHKaos mkdir existOk edge cases', () => {
+  function makeFakeKaos(sftp: unknown): SSHKaos {
+    const instance = Object.create(SSHKaos.prototype) as SSHKaos;
+    const internal = instance as unknown as { _sftp: unknown; _cwd: string };
+    internal._sftp = sftp;
+    internal._cwd = '/';
+    return instance;
+  }
+
+  function makeFileStats(): unknown {
+    return {
+      mode: 0o100644,
+      size: 0,
+      uid: 0,
+      gid: 0,
+      atime: 0,
+      mtime: 0,
+      isDirectory: (): boolean => false,
+      isFile: (): boolean => true,
+      isSymbolicLink: (): boolean => false,
+      isSocket: (): boolean => false,
+      isCharacterDevice: (): boolean => false,
+      isBlockDevice: (): boolean => false,
+      isFIFO: (): boolean => false,
+    };
+  }
+
+  function makeDirStats(): unknown {
+    return {
+      mode: 0o040755,
+      size: 0,
+      uid: 0,
+      gid: 0,
+      atime: 0,
+      mtime: 0,
+      isDirectory: (): boolean => true,
+      isFile: (): boolean => false,
+      isSymbolicLink: (): boolean => false,
+      isSocket: (): boolean => false,
+      isCharacterDevice: (): boolean => false,
+      isBlockDevice: (): boolean => false,
+      isFIFO: (): boolean => false,
+    };
+  }
+
+  it('mkdir (non-parents) rejects when existOk=true but path is a file', async () => {
+    // simple mkdir branch: exists=true + existOk=true + not a directory
+    // must throw instead of silently accepting the file collision.
+    const sftp = {
+      realpath(p: string, cb: (err: Error | null, abs: string) => void): void {
+        cb(null, p);
+      },
+      exists(_p: string, cb: (exists: boolean) => void): void {
+        cb(true);
+      },
+      stat(_p: string, cb: (err: Error | null, stats: unknown) => void): void {
+        cb(null, makeFileStats());
+      },
+    };
+    const kaos = makeFakeKaos(sftp);
+    await expect(kaos.mkdir('/existing-file', { existOk: true })).rejects.toBeInstanceOf(
+      KaosFileExistsError,
+    );
+  });
+
+  it('mkdir(parents=true) rejects when the final path exists and existOk=false', async () => {
+    // Recursive branch: walks to the final component, finds it already
+    // exists (as a directory, even), and since existOk=false the call
+    // must surface a KaosFileExistsError instead of silently succeeding.
+    const sftp = {
+      realpath(p: string, cb: (err: Error | null, abs: string) => void): void {
+        cb(null, p);
+      },
+      exists(_p: string, cb: (exists: boolean) => void): void {
+        cb(true);
+      },
+      stat(_p: string, cb: (err: Error | null, stats: unknown) => void): void {
+        cb(null, makeDirStats());
+      },
+    };
+    const kaos = makeFakeKaos(sftp);
+    await expect(kaos.mkdir('/a/b/c', { parents: true, existOk: false })).rejects.toBeInstanceOf(
+      KaosFileExistsError,
+    );
+  });
+
+  it('mkdir(parents=true) rejects when an intermediate path is a regular file', async () => {
+    // Recursive branch: during the walk, an intermediate component
+    // already exists but is a regular file (not a directory). That must
+    // be a hard failure regardless of existOk, because the next sftpMkdir
+    // would otherwise fail with a confusing ENOTDIR.
+    const sftp = {
+      realpath(p: string, cb: (err: Error | null, abs: string) => void): void {
+        cb(null, p);
+      },
+      exists(_p: string, cb: (exists: boolean) => void): void {
+        cb(true);
+      },
+      stat(_p: string, cb: (err: Error | null, stats: unknown) => void): void {
+        cb(null, makeFileStats());
+      },
+    };
+    const kaos = makeFakeKaos(sftp);
+    await expect(kaos.mkdir('/a/b/c', { parents: true, existOk: true })).rejects.toBeInstanceOf(
+      KaosFileExistsError,
+    );
+  });
+});
+
+describe('SSHKaos.close lifecycle', () => {
+  class FakeClient extends EventEmitter {
+    closed = false;
+
+    end(): void {
+      queueMicrotask(() => {
+        this.closed = true;
+        this.emit('close');
+      });
+    }
+
+    exec(
+      _command: string,
+      optionsOrCallback:
+        | ((err: Error | undefined, channel: never) => void)
+        | Record<string, unknown>,
+      maybeCallback?: (err: Error | undefined, channel: never) => void,
+    ): void {
+      const callback = typeof optionsOrCallback === 'function' ? optionsOrCallback : maybeCallback;
+      if (callback === undefined) {
+        return;
+      }
+      if (this.closed) {
+        callback(new Error('channel closed'), undefined as never);
+        return;
+      }
+      callback(undefined, undefined as never);
+    }
+  }
+
+  function createCloseableKaos(): SSHKaos {
+    const instance = Object.create(SSHKaos.prototype) as SSHKaos;
+    const internals = instance as unknown as {
+      _client: FakeClient;
+      _cwd: string;
+      _home: string;
+      _sftp: { end(): void };
+    };
+    internals._client = new FakeClient();
+    internals._cwd = '/tmp';
+    internals._home = '/tmp';
+    internals._sftp = {
+      end(): void {
+        // no-op
+      },
+    };
+    return instance;
+  }
+
+  it('awaits the close event before allowing follow-up execs to observe the closed state', async () => {
+    const kaos = createCloseableKaos();
+
+    await kaos.close();
+
+    await expect(kaos.exec('pwd')).rejects.toThrow(/channel closed/);
+  });
+});
diff --git a/packages/kaos/tsconfig.json b/packages/kaos/tsconfig.json
new file mode 100644
index 000000000..ef502e89c
--- /dev/null
+++ b/packages/kaos/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src", "test"]
+}
diff --git a/packages/kaos/tsdown.config.ts b/packages/kaos/tsdown.config.ts
new file mode 100644
index 000000000..f7c3080d5
--- /dev/null
+++ b/packages/kaos/tsdown.config.ts
@@ -0,0 +1,21 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['./src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  outDir: 'dist',
+  clean: true,
+  banner: {
+    js: [
+      "import { fileURLToPath as __cjsShimFileURLToPath } from 'node:url';",
+      "import { dirname as __cjsShimDirname } from 'node:path';",
+      'const __filename = __cjsShimFileURLToPath(import.meta.url);',
+      'const __dirname = __cjsShimDirname(__filename);',
+    ].join('\n'),
+  },
+  deps: {
+    alwaysBundle: [],
+    neverBundle: [],
+  },
+});
diff --git a/packages/kaos/vitest.config.ts b/packages/kaos/vitest.config.ts
new file mode 100644
index 000000000..99c9c1373
--- /dev/null
+++ b/packages/kaos/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    name: 'kaos',
+    include: ['test/**/*.test.ts'],
+  },
+});
diff --git a/packages/kosong/README.md b/packages/kosong/README.md
new file mode 100644
index 000000000..afc7768ef
--- /dev/null
+++ b/packages/kosong/README.md
@@ -0,0 +1,11 @@
+# @moonshot-ai/kosong
+
+LLM abstraction layer used by Kimi Code.
+
+Part of the [Kimi Code](https://github.com/MoonshotAI/kimi-code) monorepo.
+
+See the main repository for documentation, issues, and contribution guidelines.
+
+## License
+
+MIT
diff --git a/packages/kosong/package.json b/packages/kosong/package.json
new file mode 100644
index 000000000..05aff883b
--- /dev/null
+++ b/packages/kosong/package.json
@@ -0,0 +1,59 @@
+{
+  "name": "@moonshot-ai/kosong",
+  "version": "0.1.1",
+  "private": true,
+  "description": "The LLM abstraction layer for modern AI agent applications",
+  "license": "MIT",
+  "author": "Moonshot AI",
+  "homepage": "https://github.com/MoonshotAI/kimi-code/tree/main/packages/kosong#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MoonshotAI/kimi-code.git",
+    "directory": "packages/kosong"
+  },
+  "bugs": {
+    "url": "https://github.com/MoonshotAI/kimi-code/issues"
+  },
+  "keywords": [
+    "llm",
+    "ai",
+    "agent",
+    "provider"
+  ],
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "imports": {
+    "#/*": [
+      "./src/*.ts",
+      "./src/*/index.ts"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./providers/*": {
+      "types": "./src/providers/*.ts",
+      "default": "./src/providers/*.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.95.2",
+    "@google/genai": "^1.49.0",
+    "openai": "^6.34.0",
+    "zod": "catalog:",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "devDependencies": {
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1"
+  }
+}
diff --git a/packages/kosong/src/capability.ts b/packages/kosong/src/capability.ts
new file mode 100644
index 000000000..e5bc24582
--- /dev/null
+++ b/packages/kosong/src/capability.ts
@@ -0,0 +1,55 @@
+/**
+ * Declared capabilities for a specific model exposed by a {@link ChatProvider}.
+ *
+ * Providers return one of these from {@link ChatProvider.getCapability} so
+ * callers can gate requests against modalities the model does not accept
+ * without dispatching the request and watching it fail upstream.
+ *
+ * `max_context_tokens: 0` means "unknown"; callers that do not gate on
+ * context length can ignore the field.
+ */
+export interface ModelCapability {
+  readonly image_in: boolean;
+  readonly video_in: boolean;
+  readonly audio_in: boolean;
+  readonly thinking: boolean;
+  readonly tool_use: boolean;
+  readonly max_context_tokens: number;
+}
+
+const UNKNOWN_CAPABILITY_MARKER = Symbol.for('moonshot-ai.kosong.UNKNOWN_CAPABILITY');
+
+/**
+ * Shared read-only default returned when a provider has not catalogued a
+ * given model. Frozen so accidental mutation at one call site cannot leak
+ * into another.
+ */
+export const UNKNOWN_CAPABILITY: ModelCapability = Object.freeze(
+  Object.defineProperty(
+    {
+      image_in: false,
+      video_in: false,
+      audio_in: false,
+      thinking: false,
+      tool_use: false,
+      max_context_tokens: 0,
+    },
+    UNKNOWN_CAPABILITY_MARKER,
+    { value: true },
+  ),
+);
+
+export function isUnknownCapability(capability: ModelCapability): boolean {
+  if (capability === UNKNOWN_CAPABILITY) return true;
+  const marked =
+    (capability as unknown as Record<PropertyKey, unknown>)[UNKNOWN_CAPABILITY_MARKER] === true;
+  if (marked) return true;
+  return (
+    !capability.image_in &&
+    !capability.video_in &&
+    !capability.audio_in &&
+    !capability.thinking &&
+    !capability.tool_use &&
+    capability.max_context_tokens === 0
+  );
+}
diff --git a/packages/kosong/src/errors.ts b/packages/kosong/src/errors.ts
new file mode 100644
index 000000000..721e2abfe
--- /dev/null
+++ b/packages/kosong/src/errors.ts
@@ -0,0 +1,92 @@
+/**
+ * Base error for all chat provider errors.
+ */
+export class ChatProviderError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ChatProviderError';
+  }
+}
+
+/**
+ * Network-level connection failure.
+ */
+export class APIConnectionError extends ChatProviderError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'APIConnectionError';
+  }
+}
+
+/**
+ * Request timed out.
+ */
+export class APITimeoutError extends ChatProviderError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'APITimeoutError';
+  }
+}
+
+/**
+ * HTTP status error from the API.
+ */
+export class APIStatusError extends ChatProviderError {
+  readonly statusCode: number;
+  readonly requestId: string | null;
+
+  constructor(statusCode: number, message: string, requestId?: string | null) {
+    super(message);
+    this.name = 'APIStatusError';
+    this.statusCode = statusCode;
+    this.requestId = requestId ?? null;
+  }
+}
+
+/**
+ * HTTP status error that specifically means the request exceeded the model
+ * context window.
+ */
+export class APIContextOverflowError extends APIStatusError {
+  constructor(statusCode: number, message: string, requestId?: string | null) {
+    super(statusCode, message, requestId);
+    this.name = 'APIContextOverflowError';
+  }
+}
+
+/**
+ * The API returned an empty response (no content, no tool calls).
+ */
+export class APIEmptyResponseError extends ChatProviderError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'APIEmptyResponseError';
+  }
+}
+
+const CONTEXT_OVERFLOW_MESSAGE_PATTERNS = [
+  /context[ _-]?length/,
+  /(?:context[ _-]?window.*exceed|exceed.*context[ _-]?window)/,
+  /maximum context/,
+  /exceed(?:ed|s|ing)?\s+(?:the\s+)?max(?:imum)?\s+tokens?/,
+  /(?:too many tokens.*(?:prompt|input|context)|(?:prompt|input|context).*too many tokens)/,
+  /prompt is too long.*maximum/,
+  /input token count.*exceeds?.*maximum number of tokens/,
+] as const;
+
+export function normalizeAPIStatusError(
+  statusCode: number,
+  message: string,
+  requestId?: string | null,
+): APIStatusError {
+  if (isContextOverflowStatusError(statusCode, message)) {
+    return new APIContextOverflowError(statusCode, message, requestId);
+  }
+  return new APIStatusError(statusCode, message, requestId);
+}
+
+function isContextOverflowStatusError(statusCode: number, message: string): boolean {
+  if (statusCode !== 400 && statusCode !== 413 && statusCode !== 422) return false;
+  const lowerMessage = message.toLowerCase();
+  return CONTEXT_OVERFLOW_MESSAGE_PATTERNS.some((pattern) => pattern.test(lowerMessage));
+}
diff --git a/packages/kosong/src/generate.ts b/packages/kosong/src/generate.ts
new file mode 100644
index 000000000..3dd9f3e23
--- /dev/null
+++ b/packages/kosong/src/generate.ts
@@ -0,0 +1,284 @@
+import { APIEmptyResponseError } from './errors';
+import {
+  isContentPart,
+  isToolCall,
+  isToolCallPart,
+  mergeInPlace,
+  type Message,
+  type StreamedMessagePart,
+  type ToolCall,
+} from './message';
+import type { ChatProvider, FinishReason, GenerateOptions, StreamedMessage } from './provider';
+import type { Tool } from './tool';
+import type { TokenUsage } from './usage';
+
+/** Snapshot of a ToolCall excluding the internal `_streamIndex` routing field. */
+type StoredToolCall = Omit<ToolCall, '_streamIndex'>;
+
+/**
+ * The result of a single {@link generate} call.
+ *
+ * Contains the fully-assembled assistant {@link message}, an optional
+ * provider-assigned {@link id}, and token {@link usage} statistics.
+ */
+export interface GenerateResult {
+  /** Provider-assigned response identifier, or `null` if unavailable. */
+  readonly id: string | null;
+  /** The fully-assembled assistant message with merged content parts and tool calls. */
+  readonly message: Message;
+  /** Token usage for this generation, or `null` if not reported. */
+  readonly usage: TokenUsage | null;
+  /**
+   * Normalized finish reason reported by the provider, or `null` if no
+   * finish_reason was emitted (for example, the stream was interrupted
+   * before the final event).
+   */
+  readonly finishReason: FinishReason | null;
+  /**
+   * Raw provider-specific finish_reason string preserved verbatim.
+   * `null` if the provider did not emit one.
+   */
+  readonly rawFinishReason: string | null;
+}
+
+export interface GenerateCallbacks {
+  onMessagePart?: (part: StreamedMessagePart) => void | Promise<void>;
+  /**
+   * Fires once per fully-assembled tool call after the stream drains, in the
+   * order tool calls appear in the final assistant message.
+   *
+   * Tool calls are deliberately deferred until after the stream completes:
+   * parallel-tool-call streams may interleave argument deltas across calls
+   * (e.g. tc0-header → tc1-header → tc0-args → tc1-args), so firing mid-stream
+   * would dispatch a tool with half-parsed arguments and trigger toolParseError.
+   */
+  onToolCall?: (toolCall: ToolCall) => void | Promise<void>;
+}
+
+/**
+ * Generate one assistant message by streaming from the given provider.
+ *
+ * Parts of the message are streamed and merged: consecutive compatible parts
+ * (e.g. TextPart + TextPart, ToolCall + ToolCallPart) are merged in-place so
+ * the returned message always contains fully-assembled parts.
+ *
+ * **Tool call completion** is inferred from merge boundaries (a non-merging
+ * next part flushes the pending tool call into `message.toolCalls`) and from
+ * stream end. Provider adapters translate native "done" signals into this
+ * unified form; the generate loop never sees a separate done event.
+ *
+ * @param provider - The chat provider to generate from.
+ * @param systemPrompt - System-level instruction prepended to the request.
+ * @param tools - Tool definitions the model may invoke.
+ * @param history - The conversation history sent as context.
+ * @param callbacks - Optional streaming callbacks.
+ * @param options - Optional per-call settings (e.g. an {@link AbortSignal}).
+ *
+ * @throws {DOMException} with name `"AbortError"` when `options.signal` is
+ *   aborted before or during streaming.
+ * @throws {APIEmptyResponseError} when the response contains no content and
+ *   no tool calls, or only thinking content without any text or tool calls.
+ */
+export async function generate(
+  provider: ChatProvider,
+  systemPrompt: string,
+  tools: Tool[],
+  history: Message[],
+  callbacks?: GenerateCallbacks,
+  options?: GenerateOptions,
+): Promise<GenerateResult> {
+  const message: Message = { role: 'assistant', content: [], toolCalls: [] };
+  let pendingPart: StreamedMessagePart | null = null;
+
+  // Map from provider streaming index (e.g. OpenAI Chat `index`, Responses
+  // `item_id`) to the position inside `message.toolCalls`. Used to route
+  // interleaved argument deltas from parallel tool calls to the correct call.
+  const toolCallIndexMap = new Map<number | string, number>();
+
+  // Pre-flight abort check: if the caller's signal is already aborted, we
+  // must not issue the provider request at all. Providers that do not
+  // themselves honor `signal` would otherwise emit a network call that the
+  // caller has explicitly cancelled.
+  if (options?.signal?.aborted) {
+    throwAbortError();
+  }
+
+  const stream = await provider.generate(systemPrompt, tools, history, options);
+
+  // Post-await abort check: `provider.generate()` may have resolved before
+  // noticing a mid-flight abort. Reject immediately rather than draining
+  // the stream.
+  await throwIfAborted(options?.signal, stream);
+
+  for await (const part of stream) {
+    await throwIfAborted(options?.signal, stream);
+
+    // Notify raw part callback (deep copy to avoid aliasing mutations).
+    if (callbacks?.onMessagePart !== undefined) {
+      await callbacks.onMessagePart(deepCopyPart(part));
+      await throwIfAborted(options?.signal, stream);
+    }
+
+    // Index-based routing for parallel tool call argument deltas.
+    // When a ToolCallPart arrives with an index referring to a tool call
+    // that is NOT the currently-pending one, append it directly to the
+    // correct ToolCall in message.toolCalls instead of relying on sequential
+    // merging. This prevents argument cross-contamination across parallel calls.
+    if (
+      isToolCallPart(part) &&
+      part.index !== undefined &&
+      !isPendingToolCallAtIndex(pendingPart, part.index)
+    ) {
+      const arrayIdx = toolCallIndexMap.get(part.index);
+      if (arrayIdx !== undefined) {
+        const target = message.toolCalls[arrayIdx];
+        if (target !== undefined && part.argumentsPart !== null) {
+          target.function.arguments =
+            target.function.arguments === null
+              ? part.argumentsPart
+              : target.function.arguments + part.argumentsPart;
+        }
+        continue;
+      }
+      // Unknown index — fall through to the sequential logic as a safety net.
+    }
+
+    if (pendingPart === null) {
+      pendingPart = part;
+    } else if (!mergeInPlace(pendingPart, part)) {
+      // Could not merge — flush the pending part and start a new one.
+      // For parallel tool calls this happens when a new ToolCall header arrives
+      // while a previous ToolCall is still pending; the flush finalizes the
+      // previous tool call into `message.toolCalls`.
+      flushPart(message, pendingPart, toolCallIndexMap);
+      pendingPart = part;
+    }
+  }
+
+  await throwIfAborted(options?.signal, stream);
+
+  // Flush the last pending part.
+  if (pendingPart !== null) {
+    flushPart(message, pendingPart, toolCallIndexMap);
+  }
+  if (message.content.length === 0 && message.toolCalls.length === 0) {
+    throw new APIEmptyResponseError(
+      `The API returned an empty response (no content, no tool calls). Provider: ${provider.name}, model: ${provider.modelName}`,
+    );
+  }
+
+  // Think-only response (no real text, no tool calls) is treated as incomplete.
+  const hasThink = message.content.some((p) => p.type === 'think');
+  const hasText = message.content.some((p) => p.type === 'text' && p.text.trim().length > 0);
+  const hasToolCalls = message.toolCalls.length > 0;
+
+  if (hasThink && !hasText && !hasToolCalls) {
+    throw new APIEmptyResponseError(
+      'The API returned a response containing only thinking content ' +
+        'without any text or tool calls. This usually indicates the ' +
+        'stream was interrupted or the output token budget was exhausted ' +
+        `during reasoning. Provider: ${provider.name}, model: ${provider.modelName}`,
+    );
+  }
+
+  // Fire onToolCall for every fully-assembled tool call, in final order.
+  if (callbacks?.onToolCall !== undefined) {
+    for (const toolCall of message.toolCalls) {
+      await throwIfAborted(options?.signal, stream);
+      await callbacks.onToolCall(toolCall);
+    }
+  }
+
+  return {
+    id: stream.id,
+    message,
+    usage: stream.usage,
+    finishReason: stream.finishReason,
+    rawFinishReason: stream.rawFinishReason,
+  };
+}
+
+type CancelableStream = StreamedMessage & {
+  cancel?: () => unknown;
+  return?: () => unknown;
+};
+
+function throwAbortError(): never {
+  throw new DOMException('The operation was aborted.', 'AbortError');
+}
+
+async function cancelStream(stream: StreamedMessage): Promise<void> {
+  const cancelable = stream as CancelableStream;
+
+  try {
+    await cancelable.cancel?.();
+  } catch {}
+
+  try {
+    await cancelable.return?.();
+  } catch {}
+}
+
+async function throwIfAborted(signal?: AbortSignal, stream?: StreamedMessage): Promise<void> {
+  if (!signal?.aborted) {
+    return;
+  }
+
+  if (stream !== undefined) {
+    await cancelStream(stream);
+  }
+
+  throwAbortError();
+}
+
+/** True when `pending` is a ToolCall whose _streamIndex equals `index`. */
+function isPendingToolCallAtIndex(
+  pending: StreamedMessagePart | null,
+  index: number | string,
+): pending is ToolCall {
+  return pending !== null && isToolCall(pending) && pending._streamIndex === index;
+}
+
+/**
+ * Append a fully-merged part to the message.
+ *
+ * - ContentPart -> message.content
+ * - ToolCall    -> message.toolCalls (the `_streamIndex` routing key is
+ *                  registered in the map and stripped before storage).
+ * - ToolCallPart -> ignored (orphaned delta without a matching pending call)
+ */
+function flushPart(
+  message: Message,
+  part: StreamedMessagePart,
+  toolCallIndexMap: Map<number | string, number>,
+): void {
+  if (isContentPart(part)) {
+    message.content.push(part);
+    return;
+  }
+  if (isToolCall(part)) {
+    const streamIndex = part._streamIndex;
+    const stored: StoredToolCall = {
+      type: 'function',
+      id: part.id,
+      function: part.function,
+      extras: part.extras,
+    };
+    const ordinal = message.toolCalls.length;
+    message.toolCalls.push(stored as ToolCall);
+    if (streamIndex !== undefined) {
+      toolCallIndexMap.set(streamIndex, ordinal);
+    }
+  }
+  // ToolCallPart: orphaned delta — silently ignore.
+}
+
+/**
+ * Produce a shallow-ish copy of a StreamedMessagePart.
+ *
+ * This is intentionally minimal: we only need isolation for the mutable
+ * string fields that `mergeInPlace` mutates (text, think, arguments).
+ */
+function deepCopyPart(part: StreamedMessagePart): StreamedMessagePart {
+  return structuredClone(part);
+}
diff --git a/packages/kosong/src/index.ts b/packages/kosong/src/index.ts
new file mode 100644
index 000000000..224a55c9d
--- /dev/null
+++ b/packages/kosong/src/index.ts
@@ -0,0 +1,62 @@
+// Message types
+export {
+  createAssistantMessage,
+  createToolMessage,
+  createUserMessage,
+  extractText,
+  isContentPart,
+  isToolCall,
+  isToolCallPart,
+  mergeInPlace,
+} from './message';
+export type {
+  AudioURLPart,
+  ContentPart,
+  ImageURLPart,
+  Message,
+  Role,
+  StreamedMessagePart,
+  TextPart,
+  ThinkPart,
+  ToolCall,
+  ToolCallFunction,
+  ToolCallPart,
+  VideoURLPart,
+} from './message';
+
+// Provider interfaces
+export * from './provider';
+export { createProvider } from './providers';
+export type { ProviderConfig } from './providers';
+
+// Model capability matrix
+export { UNKNOWN_CAPABILITY, isUnknownCapability } from './capability';
+export type { ModelCapability } from './capability';
+
+// Core functions
+export { generate } from './generate';
+export type { GenerateCallbacks, GenerateResult } from './generate';
+
+// Tool wire schema
+export type { Tool } from './tool';
+
+// Token usage
+export { addUsage, emptyUsage, grandTotal, inputTotal } from './usage';
+export type { TokenUsage } from './usage';
+
+// Errors
+export {
+  APIConnectionError,
+  APIContextOverflowError,
+  APIEmptyResponseError,
+  APIStatusError,
+  APITimeoutError,
+  ChatProviderError,
+} from './errors';
+
+/**
+ * Concrete provider adapters stay off the root barrel because their SDK type
+ * graphs pollute downstream declaration bundles. Import them from subpaths:
+ * `@moonshot-ai/kosong/providers/kimi`,
+ * `@moonshot-ai/kosong/providers/openai-legacy`, etc.
+ */
diff --git a/packages/kosong/src/message.ts b/packages/kosong/src/message.ts
new file mode 100644
index 000000000..5bea821d8
--- /dev/null
+++ b/packages/kosong/src/message.ts
@@ -0,0 +1,226 @@
+export type Role = 'system' | 'user' | 'assistant' | 'tool';
+
+export interface TextPart {
+  type: 'text';
+  text: string;
+}
+
+export interface ThinkPart {
+  type: 'think';
+  think: string;
+  encrypted?: string; // Provider-specific reasoning signature
+}
+
+export interface ImageURLPart {
+  type: 'image_url';
+  imageUrl: { url: string; id?: string };
+}
+
+export interface AudioURLPart {
+  type: 'audio_url';
+  audioUrl: { url: string; id?: string };
+}
+
+export interface VideoURLPart {
+  type: 'video_url';
+  videoUrl: { url: string; id?: string | undefined };
+}
+
+/**
+ * A single piece of content within a {@link Message}.
+ *
+ * The union covers text, model reasoning ("think"), images, audio, and video.
+ * Providers convert these to their native content-block format during
+ * {@link ChatProvider.generate}.
+ */
+export type ContentPart = TextPart | ThinkPart | ImageURLPart | AudioURLPart | VideoURLPart;
+
+export interface ToolCallFunction {
+  name: string;
+  arguments: string | null;
+}
+
+export interface ToolCall {
+  type: 'function';
+  id: string;
+  function: ToolCallFunction;
+  extras?: Record<string, unknown>;
+  /**
+   * Provider-specific streaming index used to route argument deltas to the
+   * correct parallel tool call. Set by streaming providers (OpenAI Chat
+   * Completions `index`, Responses API `item_id`). Consumed internally by
+   * {@link generate} and stripped before the ToolCall is stored on a Message.
+   *
+   * @internal
+   */
+  _streamIndex?: number | string;
+}
+
+/** Streaming delta for tool call arguments. */
+export interface ToolCallPart {
+  type: 'tool_call_part';
+  argumentsPart: string | null;
+  /**
+   * Provider-specific index for routing this streaming delta to the correct
+   * parallel tool call. Used by OpenAI Chat Completions (`index`) and
+   * Responses API (`item_id`/`output_index`). When absent, the delta is
+   * appended to the most-recently-seen ToolCall (single-tool-call fallback).
+   */
+  index?: number | string;
+}
+
+/**
+ * A single chunk yielded by {@link StreamedMessage}'s async iterator.
+ *
+ * During streaming, the generate loop receives a sequence of these parts and
+ * merges compatible consecutive parts (e.g. TextPart + TextPart) in-place so
+ * the final {@link Message} contains fully-assembled content.
+ *
+ * Tool-call completion is inferred from merge boundaries (a non-merging next
+ * part flushes the pending tool call) and from stream end. Provider adapters
+ * are responsible for translating their native "done" signals into this
+ * shape; they do not emit a separate done event.
+ */
+export type StreamedMessagePart = ContentPart | ToolCall | ToolCallPart;
+
+/**
+ * A single message in a conversation.
+ *
+ * Messages carry a {@link role} (system, user, assistant, or tool), an array
+ * of {@link ContentPart} content blocks, and optional {@link ToolCall} entries.
+ * Tool result messages set {@link toolCallId} to correlate with the originating
+ * call.
+ */
+export interface Message {
+  /** The role of the message sender. */
+  role: Role;
+  /** Optional display name for the sender (used by some providers). */
+  name?: string;
+  /** Ordered content parts (text, images, thinking, etc.). */
+  content: ContentPart[];
+  /** Tool calls requested by the assistant in this message. */
+  toolCalls: ToolCall[];
+  /** For `tool` role messages, the ID of the tool call this result answers. */
+  toolCallId?: string;
+  /** When `true`, indicates the message was not fully received (e.g. stream interrupted). */
+  partial?: boolean;
+}
+
+/** Check if a streamed part is a ContentPart (text, think, image_url, audio_url, video_url). */
+export function isContentPart(part: StreamedMessagePart): part is ContentPart {
+  const t = part.type;
+  return (
+    t === 'text' || t === 'think' || t === 'image_url' || t === 'audio_url' || t === 'video_url'
+  );
+}
+
+/** Check if a streamed part is a ToolCall. */
+export function isToolCall(part: StreamedMessagePart): part is ToolCall {
+  return part.type === 'function';
+}
+
+/** Check if a streamed part is a ToolCallPart (streaming argument delta). */
+export function isToolCallPart(part: StreamedMessagePart): part is ToolCallPart {
+  return part.type === 'tool_call_part';
+}
+
+/**
+ * Merge `source` into `target` in-place for streaming accumulation.
+ *
+ * Supported combinations:
+ * - TextPart + TextPart -> concatenate text
+ * - ThinkPart + ThinkPart -> concatenate think (refuse if target.encrypted already set)
+ * - ToolCall + ToolCallPart -> append arguments
+ *
+ * **Routing for parallel tool calls**: When OpenAI (or compatible) APIs stream
+ * multiple tool calls in parallel, argument deltas may interleave across calls.
+ * To handle this, {@link generate} routes ToolCallParts by their optional
+ * {@link ToolCallPart.index} field (mirroring the provider's streaming index)
+ * to the correct pending ToolCall, rather than relying on sequential ordering.
+ * This function still performs sequential merging as a fallback when the
+ * pending part matches the incoming one.
+ *
+ * Returns `true` if the merge was performed, `false` otherwise.
+ */
+export function mergeInPlace(target: StreamedMessagePart, source: StreamedMessagePart): boolean {
+  // TextPart + TextPart
+  if (target.type === 'text' && source.type === 'text') {
+    target.text += source.text;
+    return true;
+  }
+
+  // ThinkPart + ThinkPart
+  if (target.type === 'think' && source.type === 'think') {
+    if (target.encrypted !== undefined) {
+      return false;
+    }
+    target.think += source.think;
+    if (source.encrypted !== undefined) {
+      target.encrypted = source.encrypted;
+    }
+    return true;
+  }
+
+  // ToolCall + ToolCallPart
+  if (target.type === 'function' && source.type === 'tool_call_part') {
+    if (source.argumentsPart !== null) {
+      target.function.arguments =
+        target.function.arguments === null
+          ? source.argumentsPart
+          : target.function.arguments + source.argumentsPart;
+    }
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Extract the concatenated text from a message's content parts.
+ *
+ * @param message The message to extract text from.
+ * @param sep Separator between text parts. Defaults to empty string.
+ */
+export function extractText(message: Message, sep: string = ''): string {
+  return message.content
+    .filter((part): part is TextPart => part.type === 'text')
+    .map((part) => part.text)
+    .join(sep);
+}
+
+/**
+ * @deprecated Use `extractText` instead.
+ */
+export function getTextContent(message: Message): string {
+  return extractText(message);
+}
+
+/** Create a simple user message with a single text part. */
+export function createUserMessage(content: string): Message {
+  return {
+    role: 'user',
+    content: [{ type: 'text', text: content }],
+    toolCalls: [],
+  };
+}
+
+/** Create an assistant message from content parts and optional tool calls. */
+export function createAssistantMessage(content: ContentPart[], toolCalls?: ToolCall[]): Message {
+  return {
+    role: 'assistant',
+    content,
+    toolCalls: toolCalls ?? [],
+  };
+}
+
+/** Create a tool result message. */
+export function createToolMessage(toolCallId: string, output: string | ContentPart[]): Message {
+  const content: ContentPart[] =
+    typeof output === 'string' ? [{ type: 'text', text: output }] : output;
+  return {
+    role: 'tool',
+    content,
+    toolCalls: [],
+    toolCallId,
+  };
+}
diff --git a/packages/kosong/src/provider.ts b/packages/kosong/src/provider.ts
new file mode 100644
index 000000000..9297313d0
--- /dev/null
+++ b/packages/kosong/src/provider.ts
@@ -0,0 +1,170 @@
+import type { ModelCapability } from './capability';
+import type { Message, StreamedMessagePart, VideoURLPart } from './message';
+import type { Tool } from './tool';
+import type { TokenUsage } from './usage';
+
+/**
+ * Normalized thinking effort level used across providers.
+ *
+ * Values above `high` are provider/model-specific and may be clamped by the
+ * adapter when the native API has no matching level. OpenAI maps `max` to its
+ * `xhigh` ceiling; Kimi and Gemini cap `xhigh`/`max` at `high`; Anthropic
+ * supports `xhigh`/`max` only on selected models and otherwise clamps to
+ * `high`.
+ */
+export type ThinkingEffort = 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+
+/**
+ * Normalized finish-reason signal indicating why a generation stopped.
+ *
+ * Each provider's native stop value is mapped to one of these, and the
+ * unmapped original string is preserved in `rawFinishReason` as an escape
+ * hatch. `null` means the provider did not emit a finish_reason (e.g. the
+ * stream was cut off before the final event).
+ *
+ * - `'completed'`: normal completion (OpenAI `'stop'`, Anthropic
+ *   `'end_turn'` / `'stop_sequence'`, Gemini `'STOP'`).
+ * - `'tool_calls'`: generation paused so the caller can dispatch tool
+ *   calls and feed their results back. Note that the OpenAI Responses API
+ *   and Google GenAI report `'completed'` here; only the Chat
+ *   Completions–style providers and Anthropic surface a dedicated value.
+ * - `'truncated'`: token budget exhausted (OpenAI `'length'`, Anthropic
+ *   `'max_tokens'`, Gemini `'MAX_TOKENS'`, Responses `'max_output_tokens'`).
+ * - `'filtered'`: content filter or safety policy blocked the response.
+ * - `'paused'`: Anthropic-specific `'pause_turn'`.
+ * - `'other'`: recognized non-null reason that does not fit the categories
+ *   above.
+ */
+export type FinishReason =
+  | 'completed'
+  | 'tool_calls'
+  | 'truncated'
+  | 'filtered'
+  | 'paused'
+  | 'other';
+
+/**
+ * An async-iterable stream of message parts produced by a single LLM response.
+ *
+ * Consumers iterate over the stream with `for await..of` to receive
+ * {@link StreamedMessagePart} chunks. After the iteration completes, the
+ * {@link id}, {@link usage}, {@link finishReason}, and
+ * {@link rawFinishReason} properties reflect the final values reported by
+ * the provider.
+ */
+export interface StreamedMessage {
+  [Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart>;
+  /** Provider-assigned response identifier, or `null` if not available. */
+  readonly id: string | null;
+  /** Token usage statistics, populated after the stream completes. */
+  readonly usage: TokenUsage | null;
+  /**
+   * Normalized finish reason, populated after the stream completes.
+   *
+   * `null` if the provider did not emit a finish_reason (for example, the
+   * stream was interrupted before the final event arrived).
+   */
+  readonly finishReason: FinishReason | null;
+  /**
+   * Raw provider-specific finish_reason string, preserved verbatim as an
+   * escape hatch for callers that need the original wire value.
+   *
+   * `null` if the provider did not emit a finish_reason.
+   */
+  readonly rawFinishReason: string | null;
+}
+
+/**
+ * Options that can be forwarded to a single {@link ChatProvider.generate} call.
+ */
+export interface ProviderRequestAuth {
+  /** Bearer/API token resolved for this specific provider request. */
+  apiKey?: string;
+  /** Request-scoped headers. These override constructor-level default headers. */
+  headers?: Record<string, string>;
+}
+
+export interface GenerateOptions {
+  /**
+   * An {@link AbortSignal} that, when aborted, requests cancellation of the
+   * in-flight generate call. Providers that accept a signal will forward it
+   * to their underlying HTTP client; the generate loop in
+   * {@link generate | generate()} also checks the signal between streamed
+   * parts.
+   */
+  signal?: AbortSignal;
+  /**
+   * Request-scoped provider auth. Hosts should resolve this immediately before
+   * each request/retry so providers never retain mutable credential state.
+   */
+  auth?: ProviderRequestAuth;
+}
+
+/**
+ * In-memory video bytes for providers that require an uploaded file
+ * reference instead of an inline data URL.
+ */
+export interface VideoUploadInput {
+  readonly data: Uint8Array;
+  readonly mimeType: string;
+  readonly filename?: string | undefined;
+}
+
+/**
+ * Unified interface for an LLM chat provider.
+ *
+ * Each provider implementation (Kimi, OpenAI, Anthropic, Google GenAI, etc.)
+ * converts the common {@link Message} / {@link Tool} types into the
+ * provider-specific wire format, streams back a {@link StreamedMessage}, and
+ * exposes configuration helpers such as {@link withThinking}.
+ */
+export interface ChatProvider {
+  /** Short identifier for the provider backend (e.g. `"kimi"`, `"anthropic"`). */
+  readonly name: string;
+  /** Model name passed to the upstream API (e.g. `"moonshot-v1-auto"`). */
+  readonly modelName: string;
+  /** Current thinking-effort level, or `null` if thinking is not configured. */
+  readonly thinkingEffort: ThinkingEffort | null;
+  /**
+   * Send a conversation to the LLM and return a streamed response.
+   *
+   * @param systemPrompt - System-level instruction prepended to the request.
+   * @param tools - Tool definitions the model may invoke.
+   * @param history - The conversation history (user, assistant, tool messages).
+   * @param options - Optional per-call settings such as an {@link AbortSignal}.
+   */
+  generate(
+    systemPrompt: string,
+    tools: Tool[],
+    history: Message[],
+    options?: GenerateOptions,
+  ): Promise<StreamedMessage>;
+  /** Return a shallow copy of this provider with the given thinking effort. */
+  withThinking(effort: ThinkingEffort): ChatProvider;
+  /**
+   * Return a shallow copy of this provider with the per-request completion
+   * budget clamped to `maxCompletionTokens`. Optional because not every
+   * backend benefits from a client-computed cap.
+   *
+   * Implementations MUST NOT mutate or replace internal HTTP clients on the
+   * returned clone — the clone is expected to share transport state with the
+   * original. See `KimiChatProvider._clone()` for the rationale.
+   */
+  withMaxCompletionTokens?(maxCompletionTokens: number): ChatProvider;
+  /** Upload a video and return a content part that can be sent to this provider. */
+  uploadVideo?(input: string | VideoUploadInput, options?: GenerateOptions): Promise<VideoURLPart>;
+  /**
+   * Return declared capabilities for `model` (defaults to `modelName`).
+   *
+   * Unknown / uncatalogued models return {@link UNKNOWN_CAPABILITY} rather
+   * than throwing, so capability checks stay non-fatal and operators can
+   * point at private/custom deployments without crashing.
+   *
+   * Optional on the interface so pre-existing test mocks (which predate
+   * the capability matrix) still structurally satisfy `ChatProvider`
+   * without churn. Callers that gate on modalities should fall back to
+   * {@link UNKNOWN_CAPABILITY} when a provider does not expose it.
+   */
+  getCapability?(model?: string): ModelCapability;
+  getContextSizeLimit?(): number | undefined;
+}
diff --git a/packages/kosong/src/providers/anthropic.ts b/packages/kosong/src/providers/anthropic.ts
new file mode 100644
index 000000000..d70dff794
--- /dev/null
+++ b/packages/kosong/src/providers/anthropic.ts
@@ -0,0 +1,1075 @@
+import type { ModelCapability } from '#/capability';
+import {
+  APIConnectionError,
+  APITimeoutError,
+  ChatProviderError,
+  normalizeAPIStatusError,
+} from '#/errors';
+import type { ContentPart, Message, StreamedMessagePart, ToolCall } from '#/message';
+import type {
+  ChatProvider,
+  FinishReason,
+  GenerateOptions,
+  ProviderRequestAuth,
+  StreamedMessage,
+  ThinkingEffort,
+} from '#/provider';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+import Anthropic, {
+  APIError as AnthropicAPIError,
+  APIConnectionError as AnthropicConnectionError,
+  AnthropicError,
+  APIConnectionTimeoutError as AnthropicTimeoutError,
+} from '@anthropic-ai/sdk';
+import type {
+  Tool as AnthropicTool,
+  ContentBlockParam,
+  MessageCreateParams,
+  MessageParam,
+  MessageStreamEvent,
+  RawContentBlockDeltaEvent,
+  RawContentBlockStartEvent,
+  RawMessageStartEvent,
+  TextBlockParam,
+  ThinkingBlockParam,
+  ToolResultBlockParam,
+  ToolUseBlockParam,
+} from '@anthropic-ai/sdk/resources/messages/messages.js';
+
+import { getAnthropicModelCapability } from './capability-registry';
+import {
+  mergeRequestHeaders,
+  requireProviderApiKey,
+  resolveAuthBackedClient,
+} from './request-auth';
+
+/**
+ * Normalize an Anthropic `stop_reason` string to the unified
+ * {@link FinishReason} enum.
+ *
+ * Source: `message.stop_reason` (non-stream) or the last `message_delta`
+ * event's `delta.stop_reason` (stream).
+ */
+function normalizeAnthropicStopReason(raw: string | null | undefined): {
+  finishReason: FinishReason | null;
+  rawFinishReason: string | null;
+} {
+  if (raw === null || raw === undefined) {
+    return { finishReason: null, rawFinishReason: null };
+  }
+  switch (raw) {
+    case 'end_turn':
+    case 'stop_sequence':
+      return { finishReason: 'completed', rawFinishReason: raw };
+    case 'max_tokens':
+      return { finishReason: 'truncated', rawFinishReason: raw };
+    case 'tool_use':
+      return { finishReason: 'tool_calls', rawFinishReason: raw };
+    case 'pause_turn':
+      return { finishReason: 'paused', rawFinishReason: raw };
+    case 'refusal':
+      return { finishReason: 'filtered', rawFinishReason: raw };
+    default:
+      return { finishReason: 'other', rawFinishReason: raw };
+  }
+}
+export interface AnthropicOptions {
+  apiKey?: string | undefined;
+  baseUrl?: string | undefined;
+  model: string;
+  defaultMaxTokens?: number | undefined;
+  betaFeatures?: string[] | undefined;
+  defaultHeaders?: Record<string, string>;
+  metadata?: Record<string, string> | undefined;
+  /** Use streaming API. Defaults to true. Set to false for non-streaming (test/fallback). */
+  stream?: boolean | undefined;
+  clientFactory?: (auth: ProviderRequestAuth) => Anthropic;
+}
+
+interface AnthropicGenerationKwargs {
+  max_tokens?: number | undefined;
+  temperature?: number | undefined;
+  top_k?: number | undefined;
+  top_p?: number | undefined;
+  thinking?: MessageCreateParams['thinking'] | undefined;
+  output_config?: MessageCreateParams['output_config'] | undefined;
+  betaFeatures?: string[] | undefined;
+}
+
+const INTERLEAVED_THINKING_BETA = 'interleaved-thinking-2025-05-14';
+const FAMILY_VERSION_RE = /(?:opus|sonnet|haiku)[.-](\d+)[.-](\d{1,2})(?!\d)/;
+const OPUS_VERSION_RE = /opus[.-](\d+)[.-](\d{1,2})(?!\d)/;
+const ADAPTIVE_MIN_VERSION = { major: 4, minor: 6 } as const;
+
+/**
+ * Per-version default output ceilings sourced from Anthropic's Messages
+ * API model cards (platform.claude.com/docs/en/about-claude/models/overview).
+ * Values are the documented synchronous Messages-API maximum — we send
+ * the full ceiling because Claude 4 + interleaved-thinking shares this
+ * budget with encrypted reasoning, so anything below the documented cap
+ * can silently truncate mid-`tool_use`.
+ *
+ * Keys are `<family>-<major>[-<minor>]`. Lookups try the most specific
+ * key first, then fall back to the family/major-only entry, so an
+ * unrecognized minor version (e.g. a future `opus-4-10`) gets the
+ * family's baseline rather than the generic fallback.
+ */
+const CEILING_BY_FAMILY_VERSION: Readonly<Record<string, number>> = {
+  // Claude Opus per minor version. 4.6 and 4.7 raised the cap to 128k;
+  // 4.5 ships at 64k; 4.1 and the dated 4.0 release stay at 32k.
+  'opus-4-7': 128000,
+  'opus-4-6': 128000,
+  'opus-4-5': 64000,
+  'opus-4-1': 32000,
+  'opus-4-0': 32000,
+  'opus-4': 32000,
+  // Claude Sonnet 4.x: 4.0 / 4.5 / 4.6 all document a 64k ceiling.
+  'sonnet-4-6': 64000,
+  'sonnet-4-5': 64000,
+  'sonnet-4-0': 64000,
+  'sonnet-4': 64000,
+  // Claude Haiku 4.5 is 64k; the family-only entry keeps future dated
+  // 4.x Haiku releases on the same ceiling.
+  'haiku-4-5': 64000,
+  'haiku-4': 64000,
+  // Claude 3.5 / 3.7 documented at 8192 (standard endpoint).
+  'opus-3-5': 8192,
+  'sonnet-3-5': 8192,
+  'sonnet-3-7': 8192,
+  'haiku-3-5': 8192,
+  // Original Claude 3 generation.
+  'opus-3': 4096,
+  'sonnet-3': 4096,
+  'haiku-3': 4096,
+};
+
+const FALLBACK_MAX_TOKENS = 32000;
+
+type ClaudeFamily = 'opus' | 'sonnet' | 'haiku';
+
+interface ClaudeVersion {
+  family: ClaudeFamily;
+  major: number;
+  minor: number | null;
+}
+
+// Family-first form: "opus-4-7", "sonnet-4.6", "haiku-4-5-20251001".
+// Version numbers are capped at 1–2 digits with a non-digit lookahead so
+// 8-digit date suffixes (e.g. `-20251001`) don't get consumed as version
+// components.
+const FAMILY_FIRST_RE =
+  /(opus|sonnet|haiku)[-._](\d{1,2})(?!\d)(?:[-._](\d{1,2})(?!\d))?/;
+// Legacy version-first form: "3-5-sonnet", "3.7.opus" — used by older
+// Anthropic model ids and Bedrock variants of Claude 3.x.
+const VERSION_FIRST_RE = /(\d{1,2})[-._](\d{1,2})[-._](opus|sonnet|haiku)/;
+// Bare family form for base Claude 3 (no minor): "3-opus", "3.haiku".
+const BARE_FAMILY_RE = /(\d{1,2})[-._](opus|sonnet|haiku)/;
+
+/**
+ * Extract Claude family + version from a model id.
+ *
+ * Designed to survive the naming variants we see across vendors:
+ * vendor prefixes (`anthropic.`, `aws/`, `openrouter/`,
+ * `online-`), suffixes (date stamps like `-20251001`, build tags
+ * like `-construct`, `-v1:0`), and `.` vs `-` separators between
+ * the family and version components.
+ *
+ * Returns `null` when the id contains no Claude marker or no
+ * recognizable family/version, in which case the resolver should fall
+ * back to the override or {@link FALLBACK_MAX_TOKENS}.
+ */
+function parseClaudeVersion(model: string): ClaudeVersion | null {
+  const normalized = model.toLowerCase();
+  // Guard against false positives on non-Claude models that happen to
+  // contain an `opus-4-7`-like substring (e.g. fine-tunes named after a
+  // checkpoint). The Anthropic provider might still be configured for
+  // non-Claude endpoints, so without this guard we'd quietly apply
+  // Claude ceilings to unrelated models.
+  if (!normalized.includes('claude')) return null;
+
+  const familyFirst = FAMILY_FIRST_RE.exec(normalized);
+  if (familyFirst !== null) {
+    return {
+      family: familyFirst[1] as ClaudeFamily,
+      major: Number.parseInt(familyFirst[2]!, 10),
+      minor: familyFirst[3] !== undefined ? Number.parseInt(familyFirst[3], 10) : null,
+    };
+  }
+  const versionFirst = VERSION_FIRST_RE.exec(normalized);
+  if (versionFirst !== null) {
+    return {
+      major: Number.parseInt(versionFirst[1]!, 10),
+      minor: Number.parseInt(versionFirst[2]!, 10),
+      family: versionFirst[3] as ClaudeFamily,
+    };
+  }
+  const bare = BARE_FAMILY_RE.exec(normalized);
+  if (bare !== null) {
+    return {
+      major: Number.parseInt(bare[1]!, 10),
+      minor: null,
+      family: bare[2] as ClaudeFamily,
+    };
+  }
+  return null;
+}
+
+function lookupClaudeCeiling(version: ClaudeVersion): number | undefined {
+  const { family, major, minor } = version;
+  if (minor !== null) {
+    const exact = CEILING_BY_FAMILY_VERSION[`${family}-${major}-${minor}`];
+    if (exact !== undefined) return exact;
+  }
+  return CEILING_BY_FAMILY_VERSION[`${family}-${major}`];
+}
+
+/**
+ * Resolve the default `max_tokens` for an Anthropic request.
+ *
+ * Precedence:
+ *   1. Caller-provided `override` (e.g. `models.<alias>.maxOutputSize`
+ *      from the harness config) — honored when present so users can
+ *      intentionally lower the budget (handy for forcing truncation
+ *      in tests) or raise it on a model we don't yet know about.
+ *   2. When the model id parses to a known Claude family + version,
+ *      the override is clamped to the documented Messages-API ceiling
+ *      so we never send a value the server would reject.
+ *   3. With no override and no recognized version, fall back to
+ *      {@link FALLBACK_MAX_TOKENS}.
+ */
+export function resolveDefaultMaxTokens(model: string, override?: number): number {
+  const parsed = parseClaudeVersion(model);
+  const ceiling = parsed === null ? undefined : lookupClaudeCeiling(parsed);
+  if (ceiling === undefined) {
+    return override ?? FALLBACK_MAX_TOKENS;
+  }
+  return override === undefined ? ceiling : Math.min(override, ceiling);
+}
+
+function parseVersion(match: RegExpExecArray): { major: number; minor: number } {
+  const majorRaw = match[1];
+  const minorRaw = match[2];
+  if (majorRaw === undefined || minorRaw === undefined) {
+    throw new Error('Model version regex did not capture major and minor versions.');
+  }
+  return { major: Number.parseInt(majorRaw, 10), minor: Number.parseInt(minorRaw, 10) };
+}
+
+function versionAtLeast(
+  version: { major: number; minor: number },
+  minimum: { major: number; minor: number },
+): boolean {
+  return (
+    version.major > minimum.major ||
+    (version.major === minimum.major && version.minor >= minimum.minor)
+  );
+}
+
+function supportsAdaptiveThinking(model: string): boolean {
+  const normalized = model.toLowerCase();
+  const match = FAMILY_VERSION_RE.exec(normalized);
+  if (match === null) {
+    return false;
+  }
+  return versionAtLeast(parseVersion(match), ADAPTIVE_MIN_VERSION);
+}
+
+function isOpus47(model: string): boolean {
+  const match = OPUS_VERSION_RE.exec(model.toLowerCase());
+  if (match === null) {
+    return false;
+  }
+  const version = parseVersion(match);
+  return version.major === 4 && version.minor === 7;
+}
+
+function supportsEffortParam(model: string): boolean {
+  if (supportsAdaptiveThinking(model)) {
+    return true;
+  }
+  const normalized = model.toLowerCase();
+  return normalized.includes('opus-4-5') || normalized.includes('opus-4.5');
+}
+
+function clampEffort(effort: ThinkingEffort, model: string): ThinkingEffort {
+  if (effort === 'off') {
+    return effort;
+  }
+  if (effort === 'xhigh' && !isOpus47(model)) {
+    return 'high';
+  }
+  if (effort === 'max' && !supportsAdaptiveThinking(model)) {
+    return 'high';
+  }
+  return effort;
+}
+
+function budgetTokensForEffort(effort: ThinkingEffort): number {
+  switch (effort) {
+    case 'low':
+      return 1024;
+    case 'medium':
+      return 4096;
+    case 'high':
+      return 32_000;
+    case 'off':
+    case 'xhigh':
+    case 'max':
+      throw new Error(`Unsupported budget-based thinking effort: ${effort}`);
+  }
+  throw new Error(`Unknown thinking effort: ${String(effort)}`);
+}
+const CACHE_CONTROL = { type: 'ephemeral' as const };
+
+type CacheableBlock = ContentBlockParam & { cache_control?: { type: 'ephemeral' } };
+
+/**
+ * Content block types that support cache_control injection.
+ */
+const CACHEABLE_TYPES = new Set([
+  'text',
+  'image',
+  'document',
+  'search_result',
+  'tool_use',
+  'tool_result',
+  'server_tool_use',
+  'web_search_tool_result',
+]);
+
+function injectCacheControlOnLastBlock(messages: MessageParam[]): void {
+  const lastMessage = messages.at(-1);
+  if (lastMessage === undefined) return;
+  const content = lastMessage.content;
+  if (!Array.isArray(content) || content.length === 0) return;
+  const lastBlock = content.at(-1) as CacheableBlock | undefined;
+  if (lastBlock === undefined) return;
+  if (CACHEABLE_TYPES.has(lastBlock.type)) {
+    lastBlock.cache_control = CACHE_CONTROL;
+  }
+}
+
+/**
+ * Check whether a MessageParam is a user message whose content consists
+ * entirely of `tool_result` blocks.
+ *
+ * Used to detect adjacent tool-result-only messages that must be merged
+ * before hitting the Anthropic wire. Per the Messages API parallel-tool-use
+ * spec, all `tool_result` blocks answering parallel `tool_use` calls must
+ * live in a single user message — splitting them across consecutive user
+ * messages fails on strict Anthropic-compatible backends (HTTP 400) and
+ * silently degrades parallel tool use on api.anthropic.com.
+ */
+function isToolResultOnly(message: MessageParam): boolean {
+  if (message.role !== 'user') return false;
+  const content = message.content;
+  if (!Array.isArray(content) || content.length === 0) return false;
+  return content.every((block) => block.type === 'tool_result');
+}
+interface AnthropicImageBlock {
+  type: 'image';
+  source: { type: 'base64'; data: string; media_type: string } | { type: 'url'; url: string };
+  cache_control?: { type: 'ephemeral' };
+}
+
+const SUPPORTED_B64_MEDIA_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+
+function imageUrlPartToAnthropic(url: string): AnthropicImageBlock {
+  if (url.startsWith('data:')) {
+    const withoutScheme = url.slice(5);
+    const parts = withoutScheme.split(';base64,', 2);
+    if (parts.length !== 2 || parts[0] === undefined || parts[1] === undefined) {
+      throw new ChatProviderError(`Invalid data URL for image: ${url}`);
+    }
+    const mediaType = parts[0];
+    const data = parts[1];
+    if (!SUPPORTED_B64_MEDIA_TYPES.has(mediaType)) {
+      throw new ChatProviderError(
+        `Unsupported media type for base64 image: ${mediaType}, url: ${url}`,
+      );
+    }
+    return {
+      type: 'image',
+      source: { type: 'base64', data, media_type: mediaType },
+    };
+  }
+  return {
+    type: 'image',
+    source: { type: 'url', url },
+  };
+}
+interface AnthropicToolParam extends AnthropicTool {
+  cache_control?: { type: 'ephemeral' } | null;
+}
+
+function convertTool(tool: Tool): AnthropicToolParam {
+  return {
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.parameters as AnthropicTool['input_schema'],
+  };
+}
+function toolResultToBlock(toolCallId: string, content: ContentPart[]): ToolResultBlockParam {
+  const blocks: Array<TextBlockParam | AnthropicImageBlock> = [];
+  for (const part of content) {
+    if (part.type === 'text') {
+      if (part.text) {
+        blocks.push({ type: 'text', text: part.text });
+      }
+    } else if (part.type === 'image_url') {
+      blocks.push(imageUrlPartToAnthropic(part.imageUrl.url));
+    }
+    // Other types not supported by Anthropic in tool results
+  }
+  return {
+    type: 'tool_result',
+    tool_use_id: toolCallId,
+    content: blocks,
+  } as ToolResultBlockParam;
+}
+function convertMessage(message: Message): MessageParam {
+  const role = message.role;
+
+  // system role -> <system>...</system> wrapped user message
+  if (role === 'system') {
+    const text = message.content
+      .filter((p) => p.type === 'text')
+      .map((p) => p.text)
+      .join('\n');
+    return {
+      role: 'user',
+      content: [{ type: 'text', text: `<system>${text}</system>` }],
+    };
+  }
+
+  // tool role -> ToolResultBlockParam in user message
+  if (role === 'tool') {
+    if (message.toolCallId === undefined) {
+      throw new ChatProviderError('Tool message missing `toolCallId`.');
+    }
+    const block = toolResultToBlock(message.toolCallId, message.content);
+    return { role: 'user', content: [block as ContentBlockParam] };
+  }
+
+  // user or assistant
+  const blocks: ContentBlockParam[] = [];
+  for (const part of message.content) {
+    if (part.type === 'text') {
+      blocks.push({ type: 'text', text: part.text } satisfies TextBlockParam);
+    } else if (part.type === 'image_url') {
+      blocks.push(imageUrlPartToAnthropic(part.imageUrl.url) as unknown as ContentBlockParam);
+    } else if (part.type === 'think') {
+      // ThinkPart with encrypted -> ThinkingBlockParam; no encrypted -> skip
+      if (part.encrypted === undefined) {
+        continue;
+      }
+      blocks.push({
+        type: 'thinking',
+        thinking: part.think,
+        signature: part.encrypted,
+      } satisfies ThinkingBlockParam);
+    }
+    // audio_url, video_url: not supported by Anthropic, skip
+  }
+
+  // Tool calls -> ToolUseBlockParam
+  if (message.toolCalls.length > 0) {
+    for (const tc of message.toolCalls) {
+      let toolInput: Record<string, unknown> = {};
+      if (tc.function.arguments) {
+        try {
+          const parsed: unknown = JSON.parse(tc.function.arguments);
+          if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            toolInput = parsed as Record<string, unknown>;
+          } else {
+            throw new ChatProviderError('Tool call arguments must be a JSON object.');
+          }
+        } catch (error) {
+          if (error instanceof ChatProviderError) throw error;
+          throw new ChatProviderError('Tool call arguments must be valid JSON.');
+        }
+      }
+      blocks.push({
+        type: 'tool_use',
+        id: tc.id,
+        name: tc.function.name,
+        input: toolInput,
+      } satisfies ToolUseBlockParam);
+    }
+  }
+
+  return { role: role, content: blocks };
+}
+export function convertAnthropicError(error: unknown): ChatProviderError {
+  // Check timeout before connection (APIConnectionTimeoutError extends APIConnectionError)
+  if (error instanceof AnthropicTimeoutError) {
+    return new APITimeoutError(error.message);
+  }
+  if (error instanceof AnthropicConnectionError) {
+    return new APIConnectionError(error.message);
+  }
+  // APIError with a status code => status error
+  if (error instanceof AnthropicAPIError && typeof error.status === 'number') {
+    const reqId = error.requestID ?? null;
+    return normalizeAPIStatusError(error.status, error.message, reqId);
+  }
+  if (error instanceof AnthropicError) {
+    return new ChatProviderError(`Anthropic error: ${error.message}`);
+  }
+  if (error instanceof Error) {
+    return new ChatProviderError(`Error: ${error.message}`);
+  }
+  return new ChatProviderError(`Error: ${String(error)}`);
+}
+class AnthropicStreamedMessage implements StreamedMessage {
+  private _id: string | null = null;
+  private _usage: TokenUsage = {
+    inputOther: 0,
+    output: 0,
+    inputCacheRead: 0,
+    inputCacheCreation: 0,
+  };
+  private _finishReason: FinishReason | null = null;
+  private _rawFinishReason: string | null = null;
+  private readonly _iter: AsyncGenerator<StreamedMessagePart>;
+
+  constructor(response: unknown, isStream: boolean) {
+    if (isStream) {
+      this._iter = this._convertStreamResponse(response as AsyncIterable<MessageStreamEvent>);
+    } else {
+      this._iter = this._convertNonStreamResponse(
+        response as {
+          id: string;
+          stop_reason?: string | null;
+          usage: {
+            input_tokens: number;
+            output_tokens: number;
+            cache_read_input_tokens?: number;
+            cache_creation_input_tokens?: number;
+          };
+          content: Array<{
+            type: string;
+            text?: string;
+            thinking?: string;
+            signature?: string;
+            data?: string;
+            id?: string;
+            name?: string;
+            input?: unknown;
+          }>;
+        },
+      );
+    }
+  }
+
+  get id(): string | null {
+    return this._id;
+  }
+
+  get usage(): TokenUsage | null {
+    return this._usage;
+  }
+
+  get finishReason(): FinishReason | null {
+    return this._finishReason;
+  }
+
+  get rawFinishReason(): string | null {
+    return this._rawFinishReason;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+    yield* this._iter;
+  }
+
+  private _captureStopReason(raw: string | null | undefined): void {
+    const normalized = normalizeAnthropicStopReason(raw);
+    this._finishReason = normalized.finishReason;
+    this._rawFinishReason = normalized.rawFinishReason;
+  }
+
+  private _extractUsage(usage: {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+  }): void {
+    this._usage = {
+      inputOther: usage.input_tokens ?? 0,
+      output: usage.output_tokens ?? 0,
+      inputCacheRead: usage.cache_read_input_tokens ?? 0,
+      inputCacheCreation: usage.cache_creation_input_tokens ?? 0,
+    };
+  }
+
+  private async *_convertNonStreamResponse(response: {
+    id: string;
+    stop_reason?: string | null;
+    usage: {
+      input_tokens: number;
+      output_tokens: number;
+      cache_read_input_tokens?: number;
+      cache_creation_input_tokens?: number;
+    };
+    content: Array<{
+      type: string;
+      text?: string;
+      thinking?: string;
+      signature?: string;
+      data?: string;
+      id?: string;
+      name?: string;
+      input?: unknown;
+    }>;
+  }): AsyncGenerator<StreamedMessagePart> {
+    this._id = response.id;
+    this._extractUsage(response.usage);
+    this._captureStopReason(response.stop_reason);
+
+    for (const block of response.content) {
+      switch (block.type) {
+        case 'text':
+          if (block.text !== undefined) {
+            yield { type: 'text', text: block.text };
+          }
+          break;
+        case 'thinking':
+          yield block.signature !== undefined
+            ? { type: 'think' as const, think: block.thinking ?? '', encrypted: block.signature }
+            : { type: 'think' as const, think: block.thinking ?? '' };
+          break;
+        case 'redacted_thinking':
+          yield block.data !== undefined
+            ? { type: 'think' as const, think: '', encrypted: block.data }
+            : { type: 'think' as const, think: '' };
+          break;
+        case 'tool_use':
+          yield {
+            type: 'function',
+            id: block.id ?? crypto.randomUUID(),
+            function: {
+              name: block.name ?? '',
+              arguments: block.input !== undefined ? JSON.stringify(block.input) : null,
+            },
+          } satisfies ToolCall;
+          break;
+      }
+    }
+  }
+
+  private async *_convertStreamResponse(
+    response: AsyncIterable<MessageStreamEvent>,
+  ): AsyncGenerator<StreamedMessagePart> {
+    const toolUseBlockIndexes = new Set<number>();
+
+    try {
+      for await (const event of response) {
+        const evt = event as unknown as Record<string, unknown>;
+        const eventType = evt['type'] as string;
+
+        if (eventType === 'message_start') {
+          const startEvt = evt as unknown as RawMessageStartEvent;
+          this._id = startEvt.message.id;
+          this._extractUsage(
+            startEvt.message.usage as {
+              input_tokens?: number;
+              output_tokens?: number;
+              cache_read_input_tokens?: number;
+              cache_creation_input_tokens?: number;
+            },
+          );
+        } else if (eventType === 'content_block_start') {
+          const blockEvt = evt as unknown as RawContentBlockStartEvent;
+          const block = blockEvt.content_block;
+          const blockIndex = blockEvt.index;
+          // eslint-disable-next-line typescript-eslint/switch-exhaustiveness-check
+          switch (block.type) {
+            case 'text':
+              yield { type: 'text', text: block.text };
+              break;
+            case 'thinking':
+              yield { type: 'think', think: block.thinking };
+              break;
+            case 'redacted_thinking':
+              yield {
+                type: 'think',
+                think: '',
+                encrypted: (block as unknown as { data: string }).data,
+              };
+              break;
+            case 'tool_use':
+              toolUseBlockIndexes.add(blockIndex);
+              yield {
+                type: 'function',
+                id: block.id,
+                function: {
+                  name: block.name,
+                  arguments: '',
+                },
+                // Carry the Anthropic block index so parallel tool_use
+                // blocks' interleaved input_json_delta chunks can be routed
+                // to the correct ToolCall by the generate loop.
+                _streamIndex: blockIndex,
+              } satisfies ToolCall;
+              break;
+          }
+        } else if (eventType === 'content_block_delta') {
+          const deltaEvt = evt as unknown as RawContentBlockDeltaEvent;
+          const delta = deltaEvt.delta;
+          const blockIndex = deltaEvt.index;
+          // eslint-disable-next-line typescript-eslint/switch-exhaustiveness-check
+          switch (delta.type) {
+            case 'text_delta':
+              yield { type: 'text', text: delta.text };
+              break;
+            case 'thinking_delta':
+              yield { type: 'think', think: delta.thinking };
+              break;
+            case 'input_json_delta':
+              yield {
+                type: 'tool_call_part',
+                argumentsPart: delta.partial_json,
+                // Carry the Anthropic block index so this delta is routed
+                // to the matching ToolCall (parallel tool_use support).
+                index: blockIndex,
+              };
+              break;
+            case 'signature_delta':
+              yield {
+                type: 'think',
+                think: '',
+                encrypted: delta.signature,
+              };
+              break;
+          }
+        } else if (eventType === 'content_block_stop') {
+          // No-op: the generate loop infers tool-call completion from the
+          // next non-merging part (typically the next content_block_start)
+          // or from stream end. Anthropic's block boundary is therefore
+          // absorbed inside the adapter rather than surfaced upstream.
+        } else if (eventType === 'message_delta') {
+          // Update usage from delta
+          const deltaUsage = (evt as { usage?: Record<string, unknown> }).usage;
+          if (deltaUsage !== undefined) {
+            if (typeof deltaUsage['output_tokens'] === 'number') {
+              this._usage.output = deltaUsage['output_tokens'];
+            }
+            if (typeof deltaUsage['cache_read_input_tokens'] === 'number') {
+              this._usage.inputCacheRead = deltaUsage['cache_read_input_tokens'];
+            }
+            if (typeof deltaUsage['cache_creation_input_tokens'] === 'number') {
+              this._usage.inputCacheCreation = deltaUsage['cache_creation_input_tokens'];
+            }
+            if (typeof deltaUsage['input_tokens'] === 'number') {
+              this._usage.inputOther = deltaUsage['input_tokens'];
+            }
+          }
+          // The terminal `stop_reason` lives on `delta.stop_reason` of the
+          // last `message_delta` event for this response. Capture it here.
+          //
+          // Accept `null` explicitly: if the key is present we forward the
+          // value (including null) to `_captureStopReason`, which maps it to
+          // `{null, null}`. Only a missing key skips the capture. This avoids
+          // a stale prior capture persisting after an explicit null reset.
+          const messageDeltaPayload = (evt as { delta?: Record<string, unknown> }).delta;
+          if (messageDeltaPayload !== undefined && 'stop_reason' in messageDeltaPayload) {
+            this._captureStopReason(
+              messageDeltaPayload['stop_reason'] as string | null | undefined,
+            );
+          }
+        }
+        // message_stop: nothing to do
+      }
+    } catch (error: unknown) {
+      throw convertAnthropicError(error);
+    }
+  }
+}
+export class AnthropicChatProvider implements ChatProvider {
+  readonly name: string = 'anthropic';
+
+  private _model: string;
+  private _stream: boolean;
+  private _client: Anthropic | undefined;
+  private _generationKwargs: AnthropicGenerationKwargs;
+  private _metadata: Record<string, string> | undefined;
+  private _apiKey: string | undefined;
+  private _baseUrl: string | undefined;
+  private _defaultHeaders: Record<string, string> | undefined;
+  private _clientFactory: ((auth: ProviderRequestAuth) => Anthropic) | undefined;
+
+  constructor(options: AnthropicOptions) {
+    this._model = options.model;
+    this._stream = options.stream ?? true;
+    this._metadata = options.metadata;
+    const apiKey = options.apiKey ?? process.env['ANTHROPIC_API_KEY'];
+    this._apiKey = apiKey === undefined || apiKey.length === 0 ? undefined : apiKey;
+    this._baseUrl = options.baseUrl;
+    this._defaultHeaders = options.defaultHeaders;
+    this._clientFactory = options.clientFactory;
+    this._client = this._apiKey === undefined ? undefined : this._buildClient(this._apiKey);
+    this._generationKwargs = {
+      max_tokens: resolveDefaultMaxTokens(options.model, options.defaultMaxTokens),
+      betaFeatures: options.betaFeatures ?? [INTERLEAVED_THINKING_BETA],
+    };
+  }
+
+  get modelName(): string {
+    return this._model;
+  }
+
+  get thinkingEffort(): ThinkingEffort | null {
+    const thinkingConfig = this._generationKwargs.thinking;
+    if (thinkingConfig === undefined || thinkingConfig === null) {
+      return null;
+    }
+    if (thinkingConfig.type === 'disabled') {
+      return 'off';
+    }
+    if (thinkingConfig.type === 'adaptive') {
+      const effort = this._generationKwargs.output_config?.effort;
+      if (effort === undefined || effort === null) {
+        return 'high';
+      }
+      switch (effort) {
+        case 'low':
+        case 'medium':
+        case 'high':
+        case 'xhigh':
+        case 'max':
+          return effort;
+      }
+    }
+    // budget-based
+    const budget = (thinkingConfig as { budget_tokens?: number }).budget_tokens ?? 0;
+    if (budget <= 1024) {
+      return 'low';
+    }
+    if (budget <= 4096) {
+      return 'medium';
+    }
+    return 'high';
+  }
+
+  get modelParameters(): Record<string, unknown> {
+    return {
+      model: this._model,
+      ...this._generationKwargs,
+    };
+  }
+
+  getCapability(model?: string): ModelCapability {
+    return getAnthropicModelCapability(model ?? this._model);
+  }
+
+  async generate(
+    systemPrompt: string,
+    tools: Tool[],
+    history: Message[],
+    options?: GenerateOptions,
+  ): Promise<StreamedMessage> {
+    // Build system param
+    const system: TextBlockParam[] | undefined = systemPrompt
+      ? [
+          {
+            type: 'text',
+            text: systemPrompt,
+            cache_control: CACHE_CONTROL,
+          } as TextBlockParam,
+        ]
+      : undefined;
+
+    // Convert messages, merging consecutive tool-result-only user messages
+    // into a single user message (Anthropic parallel-tool-use spec).
+    const messages: MessageParam[] = [];
+    for (const msg of history) {
+      const converted = convertMessage(msg);
+      const last = messages.at(-1);
+      if (last !== undefined && isToolResultOnly(last) && isToolResultOnly(converted)) {
+        last.content = [
+          ...(last.content as ContentBlockParam[]),
+          ...(converted.content as ContentBlockParam[]),
+        ];
+      } else {
+        messages.push(converted);
+      }
+    }
+
+    // Inject cache_control on last content block of last message (after merge,
+    // so it lands on the final tool_result block in the merged user message).
+    injectCacheControlOnLastBlock(messages);
+
+    // Build generation kwargs (excluding betaFeatures)
+    const kwargs: Record<string, unknown> = {};
+    if (this._generationKwargs.max_tokens !== undefined) {
+      kwargs['max_tokens'] = this._generationKwargs.max_tokens;
+    }
+    if (this._generationKwargs.temperature !== undefined) {
+      kwargs['temperature'] = this._generationKwargs.temperature;
+    }
+    if (this._generationKwargs.top_k !== undefined) {
+      kwargs['top_k'] = this._generationKwargs.top_k;
+    }
+    if (this._generationKwargs.top_p !== undefined) {
+      kwargs['top_p'] = this._generationKwargs.top_p;
+    }
+    if (this._generationKwargs.thinking !== undefined) {
+      kwargs['thinking'] = this._generationKwargs.thinking;
+    }
+    if (this._generationKwargs.output_config !== undefined) {
+      kwargs['output_config'] = this._generationKwargs.output_config;
+    }
+
+    // Build beta headers
+    const betas = this._generationKwargs.betaFeatures ?? [];
+    const extraHeaders: Record<string, string> = {};
+    if (betas.length > 0) {
+      extraHeaders['anthropic-beta'] = betas.join(',');
+    }
+
+    // Convert tools
+    const anthropicTools: AnthropicToolParam[] = tools.map((t) => convertTool(t));
+    if (anthropicTools.length > 0) {
+      const lastTool = anthropicTools.at(-1);
+      if (lastTool !== undefined) {
+        lastTool.cache_control = CACHE_CONTROL;
+      }
+    }
+
+    // Build the create params
+    const createParams: Record<string, unknown> = {
+      model: this._model,
+      messages,
+      ...kwargs,
+    };
+
+    if (system !== undefined) {
+      createParams['system'] = system;
+    }
+
+    if (anthropicTools.length > 0) {
+      createParams['tools'] = anthropicTools;
+    }
+
+    if (this._metadata !== undefined) {
+      createParams['metadata'] = this._metadata;
+    }
+
+    const requestOptions: Record<string, unknown> = {};
+    const headers = mergeRequestHeaders(extraHeaders, options?.auth?.headers);
+    if (headers !== undefined) {
+      requestOptions['headers'] = headers;
+    }
+    if (options?.signal) {
+      requestOptions['signal'] = options.signal;
+    }
+    const finalRequestOptions = Object.keys(requestOptions).length > 0 ? requestOptions : undefined;
+    const client = this._createClient(options?.auth);
+
+    if (this._stream) {
+      // Streaming mode: use client.messages.stream() which returns an AsyncIterable<MessageStreamEvent>
+      try {
+        const stream = client.messages.stream(
+          createParams as unknown as MessageCreateParams,
+          finalRequestOptions,
+        );
+        return new AnthropicStreamedMessage(stream, true);
+      } catch (error: unknown) {
+        throw convertAnthropicError(error);
+      }
+    }
+
+    // Non-streaming fallback
+    try {
+      const response = await client.messages.create(
+        { ...createParams, stream: false } as unknown as MessageCreateParams,
+        finalRequestOptions,
+      );
+      return new AnthropicStreamedMessage(response, false);
+    } catch (error: unknown) {
+      throw convertAnthropicError(error);
+    }
+  }
+
+  private _createClient(auth: ProviderRequestAuth | undefined): Anthropic {
+    return resolveAuthBackedClient(
+      { cachedClient: this._client, clientFactory: this._clientFactory },
+      auth,
+      (a) => this._buildClient(requireProviderApiKey('AnthropicChatProvider', a, this._apiKey)),
+    );
+  }
+
+  private _buildClient(apiKey: string): Anthropic {
+    return new Anthropic({
+      apiKey,
+      baseURL: this._baseUrl,
+      defaultHeaders: this._defaultHeaders,
+    });
+  }
+
+  withThinking(effort: ThinkingEffort): AnthropicChatProvider {
+    if (effort === 'off') {
+      let newBetas = [...(this._generationKwargs.betaFeatures ?? [])];
+      if (supportsAdaptiveThinking(this._model)) {
+        newBetas = newBetas.filter((b) => b !== INTERLEAVED_THINKING_BETA);
+      }
+      const clone = this._withGenerationKwargs({
+        thinking: { type: 'disabled' },
+        betaFeatures: newBetas,
+      });
+      delete clone._generationKwargs.output_config;
+      return clone;
+    }
+
+    const effectiveEffort = clampEffort(effort, this._model);
+    if (effectiveEffort === 'off') {
+      throw new Error('Non-off thinking effort unexpectedly clamped to off.');
+    }
+
+    let newBetas = [...(this._generationKwargs.betaFeatures ?? [])];
+
+    if (supportsAdaptiveThinking(this._model)) {
+      newBetas = newBetas.filter((b) => b !== INTERLEAVED_THINKING_BETA);
+      return this._withGenerationKwargs({
+        thinking: { type: 'adaptive', display: 'summarized' },
+        output_config: { effort: effectiveEffort },
+        betaFeatures: newBetas,
+      });
+    }
+
+    const kwargs: Partial<AnthropicGenerationKwargs> = {
+      thinking: { type: 'enabled', budget_tokens: budgetTokensForEffort(effectiveEffort) },
+      betaFeatures: newBetas,
+    };
+    if (supportsEffortParam(this._model)) {
+      kwargs.output_config = { effort: effectiveEffort };
+    } else {
+      kwargs.output_config = undefined;
+    }
+    const clone = this._withGenerationKwargs(kwargs);
+    if (!supportsEffortParam(this._model)) {
+      delete clone._generationKwargs.output_config;
+    }
+    return clone;
+  }
+
+  withGenerationKwargs(kwargs: Partial<AnthropicGenerationKwargs>): AnthropicChatProvider {
+    return this._withGenerationKwargs(kwargs);
+  }
+
+  private _withGenerationKwargs(kwargs: Partial<AnthropicGenerationKwargs>): AnthropicChatProvider {
+    const clone = this._clone();
+    clone._generationKwargs = { ...clone._generationKwargs, ...kwargs };
+    return clone;
+  }
+
+  private _clone(): AnthropicChatProvider {
+    const clone = Object.assign(
+      Object.create(Object.getPrototypeOf(this) as object) as AnthropicChatProvider,
+      this,
+    );
+    clone._generationKwargs = { ...this._generationKwargs };
+    return clone;
+  }
+}
diff --git a/packages/kosong/src/providers/capability-registry.ts b/packages/kosong/src/providers/capability-registry.ts
new file mode 100644
index 000000000..17ec9d6bd
--- /dev/null
+++ b/packages/kosong/src/providers/capability-registry.ts
@@ -0,0 +1,203 @@
+import { UNKNOWN_CAPABILITY, type ModelCapability } from '#/capability';
+
+type CapabilityMatcher = (normalizedModelName: string) => boolean;
+
+interface CapabilityCatalogEntry {
+  readonly matches: CapabilityMatcher;
+  readonly capability: ModelCapability;
+}
+
+const OPENAI_RESPONSES_DEVELOPER_ROLE_MODELS = new Set([
+  'gpt-4.1',
+  'gpt-4.1-mini',
+  'gpt-4.1-nano',
+  'gpt-5-codex',
+  'o1',
+  'o1-mini',
+  'o1-pro',
+  'o3',
+  'o3-mini',
+  'o3-pro',
+  'o4-mini',
+]);
+
+const OPENAI_VISION_TOOL_PREFIXES = [
+  'gpt-4o',
+  'gpt-4-turbo',
+  'gpt-4.1',
+  'gpt-4.5',
+] as const;
+
+const CLAUDE_3_PREFIXES = ['claude-3-', 'claude-3.5-', 'claude-3.7-'] as const;
+
+const CLAUDE_4_PREFIXES = [
+  'claude-opus-4',
+  'claude-sonnet-4',
+  'claude-haiku-4',
+] as const;
+
+const GEMINI_CATALOGUED_PREFIXES = [
+  'gemini-1.5-pro',
+  'gemini-1.5-flash',
+  'gemini-2.0-flash',
+  'gemini-2.0-pro',
+  'gemini-2.5-pro',
+  'gemini-2.5-flash',
+] as const;
+
+const OPENAI_REASONING_CAPABILITY: ModelCapability = Object.freeze({
+  image_in: false,
+  video_in: false,
+  audio_in: false,
+  thinking: true,
+  tool_use: true,
+  max_context_tokens: 0,
+});
+
+const OPENAI_VISION_TOOL_CAPABILITY: ModelCapability = Object.freeze({
+  image_in: true,
+  video_in: false,
+  audio_in: false,
+  thinking: false,
+  tool_use: true,
+  max_context_tokens: 0,
+});
+
+const OPENAI_TEXT_TOOL_CAPABILITY: ModelCapability = Object.freeze({
+  image_in: false,
+  video_in: false,
+  audio_in: false,
+  thinking: false,
+  tool_use: true,
+  max_context_tokens: 0,
+});
+
+const ANTHROPIC_VISION_TOOL_CAPABILITY: ModelCapability = Object.freeze({
+  image_in: true,
+  video_in: false,
+  audio_in: false,
+  thinking: false,
+  tool_use: true,
+  max_context_tokens: 0,
+});
+
+const ANTHROPIC_THINKING_VISION_TOOL_CAPABILITY: ModelCapability = Object.freeze({
+  image_in: true,
+  video_in: false,
+  audio_in: false,
+  thinking: true,
+  tool_use: true,
+  max_context_tokens: 0,
+});
+
+const GEMINI_MULTIMODAL_TOOL_CAPABILITY: ModelCapability = Object.freeze({
+  image_in: true,
+  video_in: true,
+  audio_in: true,
+  thinking: false,
+  tool_use: true,
+  max_context_tokens: 0,
+});
+
+const GEMINI_THINKING_MULTIMODAL_TOOL_CAPABILITY: ModelCapability = Object.freeze({
+  image_in: true,
+  video_in: true,
+  audio_in: true,
+  thinking: true,
+  tool_use: true,
+  max_context_tokens: 0,
+});
+
+const OPENAI_LEGACY_CAPABILITY_CATALOG: readonly CapabilityCatalogEntry[] = [
+  {
+    matches: isOpenAIReasoningModel,
+    capability: OPENAI_REASONING_CAPABILITY,
+  },
+  {
+    matches: (name) => hasPrefix(name, OPENAI_VISION_TOOL_PREFIXES),
+    capability: OPENAI_VISION_TOOL_CAPABILITY,
+  },
+  {
+    matches: (name) => name.startsWith('gpt-3.5-turbo'),
+    capability: OPENAI_TEXT_TOOL_CAPABILITY,
+  },
+];
+
+const OPENAI_RESPONSES_CAPABILITY_CATALOG: readonly CapabilityCatalogEntry[] = [
+  {
+    matches: isOpenAIReasoningModel,
+    capability: OPENAI_REASONING_CAPABILITY,
+  },
+  {
+    matches: (name) => hasPrefix(name, OPENAI_VISION_TOOL_PREFIXES),
+    capability: OPENAI_VISION_TOOL_CAPABILITY,
+  },
+];
+
+const ANTHROPIC_CAPABILITY_CATALOG: readonly CapabilityCatalogEntry[] = [
+  {
+    matches: (name) => hasPrefix(name, CLAUDE_3_PREFIXES),
+    capability: ANTHROPIC_VISION_TOOL_CAPABILITY,
+  },
+  {
+    matches: (name) => hasPrefix(name, CLAUDE_4_PREFIXES),
+    capability: ANTHROPIC_THINKING_VISION_TOOL_CAPABILITY,
+  },
+];
+
+function normalizeModelName(modelName: string): string {
+  return modelName.toLowerCase();
+}
+
+function hasPrefix(modelName: string, prefixes: readonly string[]): boolean {
+  return prefixes.some((prefix) => modelName.startsWith(prefix));
+}
+
+function isOpenAIReasoningModel(modelName: string): boolean {
+  return /^o\d/.test(modelName);
+}
+
+function capabilityFromCatalog(
+  modelName: string,
+  catalog: readonly CapabilityCatalogEntry[],
+): ModelCapability {
+  const normalized = normalizeModelName(modelName);
+  for (const entry of catalog) {
+    if (entry.matches(normalized)) {
+      return entry.capability;
+    }
+  }
+  return UNKNOWN_CAPABILITY;
+}
+
+export function getOpenAILegacyModelCapability(modelName: string): ModelCapability {
+  return capabilityFromCatalog(modelName, OPENAI_LEGACY_CAPABILITY_CATALOG);
+}
+
+export function getOpenAIResponsesModelCapability(modelName: string): ModelCapability {
+  return capabilityFromCatalog(modelName, OPENAI_RESPONSES_CAPABILITY_CATALOG);
+}
+
+export function getAnthropicModelCapability(modelName: string): ModelCapability {
+  return capabilityFromCatalog(modelName, ANTHROPIC_CAPABILITY_CATALOG);
+}
+
+export function getGoogleGenAIModelCapability(modelName: string): ModelCapability {
+  const normalized = normalizeModelName(modelName);
+  if (!normalized.startsWith('gemini-')) return UNKNOWN_CAPABILITY;
+  if (!hasPrefix(normalized, GEMINI_CATALOGUED_PREFIXES)) return UNKNOWN_CAPABILITY;
+
+  if (normalized.startsWith('gemini-2.5-') || normalized.includes('thinking')) {
+    return GEMINI_THINKING_MULTIMODAL_TOOL_CAPABILITY;
+  }
+  return GEMINI_MULTIMODAL_TOOL_CAPABILITY;
+}
+
+export function usesOpenAIResponsesDeveloperRole(modelName: string): boolean {
+  const normalized = normalizeModelName(modelName);
+  if (OPENAI_RESPONSES_DEVELOPER_ROLE_MODELS.has(normalized)) return true;
+  for (const cataloguedModel of OPENAI_RESPONSES_DEVELOPER_ROLE_MODELS) {
+    if (normalized.startsWith(cataloguedModel + '-')) return true;
+  }
+  return false;
+}
diff --git a/packages/kosong/src/providers/chat-completions-stream.ts b/packages/kosong/src/providers/chat-completions-stream.ts
new file mode 100644
index 000000000..8d1114f7b
--- /dev/null
+++ b/packages/kosong/src/providers/chat-completions-stream.ts
@@ -0,0 +1,110 @@
+import type { StreamedMessagePart, ToolCall } from '#/message';
+
+export interface ChatCompletionStreamToolFunctionDelta {
+  readonly name?: string;
+  readonly arguments?: string;
+}
+
+export interface ChatCompletionStreamToolCallDelta {
+  readonly index?: number | string;
+  readonly id?: string;
+  readonly function?: ChatCompletionStreamToolFunctionDelta | null;
+}
+
+export interface BufferedChatCompletionToolCall {
+  id?: string;
+  arguments: string;
+  emitted: boolean;
+}
+
+/**
+ * Convert an OpenAI Chat Completions-style streamed tool-call delta into the
+ * normalized kosong stream part protocol.
+ *
+ * OpenAI-compatible providers may emit argument chunks before the function name
+ * for a stream index. Buffer those early argument chunks until the first named
+ * header arrives, then emit subsequent chunks as indexed `tool_call_part`s so
+ * the shared generate loop can route interleaved parallel calls.
+ */
+export function convertChatCompletionStreamToolCall(
+  toolCall: ChatCompletionStreamToolCallDelta,
+  bufferedByIndex: Map<number | string, BufferedChatCompletionToolCall>,
+): StreamedMessagePart[] {
+  if (toolCall.function === undefined || toolCall.function === null) {
+    return [];
+  }
+
+  const streamIndex = toolCall.index;
+  const functionName = toolCall.function.name;
+  const functionArguments = toolCall.function.arguments;
+  const hasConcreteName = typeof functionName === 'string' && functionName.length > 0;
+  const hasArguments = typeof functionArguments === 'string' && functionArguments.length > 0;
+
+  if (streamIndex === undefined) {
+    if (hasConcreteName) {
+      return [
+        {
+          type: 'function',
+          id: toolCall.id ?? crypto.randomUUID(),
+          function: {
+            name: functionName,
+            arguments: functionArguments ?? null,
+          },
+        } satisfies ToolCall,
+      ];
+    }
+
+    if (hasArguments) {
+      return [
+        { type: 'tool_call_part', argumentsPart: functionArguments } satisfies StreamedMessagePart,
+      ];
+    }
+
+    return [];
+  }
+
+  const buffered = bufferedByIndex.get(streamIndex) ?? { arguments: '', emitted: false };
+  if (toolCall.id !== undefined) {
+    buffered.id = toolCall.id;
+  }
+
+  if (!buffered.emitted) {
+    if (!hasConcreteName) {
+      if (hasArguments) {
+        buffered.arguments += functionArguments;
+      }
+      bufferedByIndex.set(streamIndex, buffered);
+      return [];
+    }
+
+    buffered.emitted = true;
+    const initialArguments =
+      buffered.arguments.length > 0
+        ? buffered.arguments + (functionArguments ?? '')
+        : (functionArguments ?? null);
+    buffered.arguments = '';
+    bufferedByIndex.set(streamIndex, buffered);
+
+    const toolCallHeader: ToolCall = {
+      type: 'function',
+      id: buffered.id ?? toolCall.id ?? crypto.randomUUID(),
+      function: {
+        name: functionName,
+        arguments: initialArguments,
+      },
+      _streamIndex: streamIndex,
+    };
+    return [toolCallHeader];
+  }
+
+  if (!hasArguments) {
+    return [];
+  }
+
+  const part: StreamedMessagePart & { index: number | string } = {
+    type: 'tool_call_part',
+    argumentsPart: functionArguments,
+    index: streamIndex,
+  };
+  return [part];
+}
diff --git a/packages/kosong/src/providers/google-genai.ts b/packages/kosong/src/providers/google-genai.ts
new file mode 100644
index 000000000..bd9805820
--- /dev/null
+++ b/packages/kosong/src/providers/google-genai.ts
@@ -0,0 +1,901 @@
+import type { ModelCapability } from '#/capability';
+import {
+  APIConnectionError,
+  APITimeoutError,
+  ChatProviderError,
+  normalizeAPIStatusError,
+} from '#/errors';
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import type {
+  ChatProvider,
+  FinishReason,
+  GenerateOptions,
+  ProviderRequestAuth,
+  StreamedMessage,
+  ThinkingEffort,
+} from '#/provider';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+import { ApiError as GoogleApiError, GoogleGenAI as GenAIClient } from '@google/genai';
+
+import { getGoogleGenAIModelCapability } from './capability-registry';
+import { requireProviderApiKey, resolveAuthBackedClient } from './request-auth';
+
+/**
+ * Normalize a Google GenAI (Gemini) `finishReason` value to the unified
+ * {@link FinishReason} enum.
+ *
+ * Source: `candidates[0].finishReason` (works for both stream and
+ * non-stream — the SDK normalizes them). Gemini does not emit a
+ * `tool_calls`-style reason; tool calls come via `parts[].functionCall`
+ * and `finishReason` stays `'completed'` even when the model produces
+ * function calls.
+ */
+function normalizeGoogleGenAIFinishReason(raw: unknown): {
+  finishReason: FinishReason | null;
+  rawFinishReason: string | null;
+} {
+  if (raw === null || raw === undefined) {
+    return { finishReason: null, rawFinishReason: null };
+  }
+  // The SDK normally hands us a plain string but older builds wrap it in
+  // an enum-like object. Accept both shapes and uppercase to match the
+  // documented constants. Anything else collapses to "no signal" so we
+  // never emit a junk `[object Object]` raw value.
+  let rawString: string;
+  if (typeof raw === 'string') {
+    rawString = raw.toUpperCase();
+  } else if (typeof raw === 'number' || typeof raw === 'bigint' || typeof raw === 'boolean') {
+    rawString = String(raw).toUpperCase();
+  } else {
+    return { finishReason: null, rawFinishReason: null };
+  }
+  if (rawString === 'FINISH_REASON_UNSPECIFIED' || rawString === '') {
+    return { finishReason: null, rawFinishReason: null };
+  }
+  switch (rawString) {
+    case 'STOP':
+      return { finishReason: 'completed', rawFinishReason: rawString };
+    case 'MAX_TOKENS':
+      return { finishReason: 'truncated', rawFinishReason: rawString };
+    case 'SAFETY':
+    case 'RECITATION':
+    case 'BLOCKLIST':
+    case 'PROHIBITED_CONTENT':
+    case 'SPII':
+    case 'IMAGE_SAFETY':
+      return { finishReason: 'filtered', rawFinishReason: rawString };
+    case 'MALFORMED_FUNCTION_CALL':
+    case 'OTHER':
+    case 'LANGUAGE':
+      return { finishReason: 'other', rawFinishReason: rawString };
+    default:
+      return { finishReason: 'other', rawFinishReason: rawString };
+  }
+}
+export interface GoogleGenAIOptions {
+  apiKey?: string | undefined;
+  model: string;
+  vertexai?: boolean | undefined;
+  project?: string | undefined;
+  location?: string | undefined;
+  stream?: boolean | undefined;
+  clientFactory?: (auth: ProviderRequestAuth) => GenAIClient;
+}
+
+export interface GoogleGenAIGenerationKwargs {
+  max_output_tokens?: number | undefined;
+  temperature?: number | undefined;
+  top_k?: number | undefined;
+  top_p?: number | undefined;
+  thinking_config?: ThinkingConfig | undefined;
+  [key: string]: unknown;
+}
+
+interface ThinkingConfig {
+  include_thoughts?: boolean;
+  thinking_budget?: number;
+  thinking_level?: string;
+}
+interface GoogleFunctionDeclaration {
+  name: string;
+  description: string;
+  parameters_json_schema: Record<string, unknown>;
+}
+
+interface GoogleTool {
+  function_declarations: GoogleFunctionDeclaration[];
+}
+
+function toolToGoogleGenAI(tool: Tool): GoogleTool {
+  return {
+    function_declarations: [
+      {
+        name: tool.name,
+        description: tool.description,
+        parameters_json_schema: tool.parameters,
+      },
+    ],
+  };
+}
+interface GoogleContent {
+  role: string;
+  parts: GooglePart[];
+}
+
+interface GooglePart {
+  text?: string;
+  function_call?: { name: string; args: Record<string, unknown> };
+  function_response?: {
+    name: string;
+    response: Record<string, string>;
+    parts: unknown[];
+  };
+  thought_signature?: string;
+  [key: string]: unknown;
+}
+
+function toolCallIdToName(toolCallId: string, toolNameById: Map<string, string>): string {
+  const name = toolNameById.get(toolCallId);
+  if (name !== undefined) return name;
+  // Fallback: ids produced by this provider follow the format
+  // "{tool_name}_{id_suffix}" where `tool_name` may itself contain
+  // underscores (e.g. `fetch_image`) and `id_suffix` is a single trailing
+  // token without underscores (e.g. a random hex / UUID fragment). We strip
+  // the last "_<suffix>" segment by matching it explicitly — splitting on
+  // the first underscore would truncate multi-word tool names like
+  // `fetch_image_<id>` to just `fetch`.
+  const match = /^(.+)_[^_]+$/.exec(toolCallId);
+  return match?.[1] ?? toolCallId;
+}
+
+/**
+ * Convert a data URL or HTTP URL to a Google GenAI inline/file data part.
+ * - data: URLs are parsed into { inlineData: { mimeType, data } }
+ * - http(s): URLs use { fileData: { fileUri, mimeType } }
+ */
+function convertMediaUrl(
+  url: string,
+  fallbackMimeType: string,
+):
+  | { inlineData: { mimeType: string; data: string } }
+  | { fileData: { fileUri: string; mimeType: string } } {
+  if (url.startsWith('data:')) {
+    const commaIndex = url.indexOf(',');
+    if (commaIndex === -1) {
+      return { fileData: { fileUri: url, mimeType: fallbackMimeType } };
+    }
+    const meta = url.slice(0, commaIndex);
+    const data = url.slice(commaIndex + 1);
+    const colonIndex = meta.indexOf(':');
+    const semiIndex = meta.indexOf(';');
+    const mimeType =
+      colonIndex !== -1 && semiIndex !== -1
+        ? meta.slice(colonIndex + 1, semiIndex)
+        : fallbackMimeType;
+    return { inlineData: { mimeType, data } };
+  }
+  // For HTTP(S) URLs, try to guess mime type from extension
+  let mimeType = fallbackMimeType;
+  try {
+    const pathname = new URL(url).pathname.toLowerCase();
+    if (pathname.endsWith('.png')) mimeType = 'image/png';
+    else if (pathname.endsWith('.jpg') || pathname.endsWith('.jpeg')) mimeType = 'image/jpeg';
+    else if (pathname.endsWith('.gif')) mimeType = 'image/gif';
+    else if (pathname.endsWith('.webp')) mimeType = 'image/webp';
+    else if (pathname.endsWith('.mp3') || pathname.endsWith('.mpeg')) mimeType = 'audio/mpeg';
+    else if (pathname.endsWith('.wav')) mimeType = 'audio/wav';
+    else if (pathname.endsWith('.ogg')) mimeType = 'audio/ogg';
+  } catch {
+    // URL parsing failed, use fallback
+  }
+  return { fileData: { fileUri: url, mimeType } };
+}
+
+function createAbortError(): DOMException {
+  return new DOMException('The operation was aborted.', 'AbortError');
+}
+
+async function abortPromise(signal: AbortSignal | undefined): Promise<never> {
+  if (signal === undefined) {
+    return new Promise(() => {
+      // Intentionally never settles when no signal is provided.
+    });
+  }
+  if (signal.aborted) {
+    throw createAbortError();
+  }
+  return new Promise((_, reject) => {
+    signal.addEventListener(
+      'abort',
+      () => {
+        reject(createAbortError());
+      },
+      { once: true },
+    );
+  });
+}
+
+function messageToGoogleGenAI(message: Message): GoogleContent {
+  if (message.role === 'tool') {
+    throw new ChatProviderError(
+      'Tool messages must be converted via messagesToGoogleGenAIContents.',
+    );
+  }
+
+  // GoogleGenAI uses "model" instead of "assistant"
+  const role = message.role === 'assistant' ? 'model' : message.role;
+  const parts: GooglePart[] = [];
+
+  // Handle content parts
+  for (const part of message.content) {
+    switch (part.type) {
+      case 'text':
+        parts.push({ text: part.text });
+        break;
+      case 'think':
+        // Skip think parts (synthetic)
+        break;
+      case 'image_url':
+        parts.push(convertMediaUrl(part.imageUrl.url, 'image/jpeg'));
+        break;
+      case 'audio_url':
+        parts.push(convertMediaUrl(part.audioUrl.url, 'audio/mpeg'));
+        break;
+      case 'video_url':
+        parts.push(convertMediaUrl(part.videoUrl.url, 'video/mp4'));
+        break;
+    }
+  }
+
+  // Handle tool calls
+  for (const toolCall of message.toolCalls) {
+    let args: Record<string, unknown> = {};
+    if (toolCall.function.arguments) {
+      try {
+        const parsed: unknown = JSON.parse(toolCall.function.arguments);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+          args = parsed as Record<string, unknown>;
+        } else {
+          throw new ChatProviderError('Tool call arguments must be a JSON object.');
+        }
+      } catch (error) {
+        if (error instanceof ChatProviderError) throw error;
+        throw new ChatProviderError('Tool call arguments must be valid JSON.');
+      }
+    }
+
+    const functionCallPart: GooglePart = {
+      function_call: {
+        name: toolCall.function.name,
+        args,
+      },
+    };
+
+    // Restore thought_signature if available
+    if (toolCall.extras && 'thought_signature_b64' in toolCall.extras) {
+      functionCallPart['thought_signature'] = toolCall.extras['thought_signature_b64'] as string;
+    }
+
+    parts.push(functionCallPart);
+  }
+
+  return { role, parts };
+}
+
+/**
+ * Convert a tool message into a list of Google GenAI parts.
+ *
+ * Returns a `functionResponse` part carrying the text output, followed by
+ * independent media parts (`inlineData` / `fileData`) for any image/audio/video
+ * content in the tool result. This preserves multimodal tool outputs so the
+ * next Gemini/Vertex turn can see them — returning only the text would silently
+ * drop media and break tool chains that rely on images or audio.
+ */
+function toolMessageToFunctionResponseParts(
+  message: Message,
+  toolNameById: Map<string, string>,
+): GooglePart[] {
+  if (message.role !== 'tool') {
+    throw new ChatProviderError('Expected a tool message.');
+  }
+  if (message.toolCallId === undefined) {
+    throw new ChatProviderError('Tool response is missing `toolCallId`.');
+  }
+
+  // Separate text output from media parts
+  let textOutput = '';
+  const mediaParts: GooglePart[] = [];
+  for (const part of message.content) {
+    switch (part.type) {
+      case 'text':
+        if (part.text) textOutput += part.text;
+        break;
+      case 'image_url':
+        mediaParts.push(convertMediaUrl(part.imageUrl.url, 'image/jpeg'));
+        break;
+      case 'audio_url':
+        mediaParts.push(convertMediaUrl(part.audioUrl.url, 'audio/mpeg'));
+        break;
+      case 'video_url':
+        mediaParts.push(convertMediaUrl(part.videoUrl.url, 'video/mp4'));
+        break;
+      case 'think':
+        // Skip — handled separately via reasoning channel.
+        break;
+    }
+  }
+
+  const functionResponsePart: GooglePart = {
+    function_response: {
+      name: toolCallIdToName(message.toolCallId, toolNameById),
+      response: { output: textOutput },
+      parts: [],
+    },
+  };
+
+  return [functionResponsePart, ...mediaParts];
+}
+
+export function messagesToGoogleGenAIContents(messages: Message[]): GoogleContent[] {
+  const contents: GoogleContent[] = [];
+  const toolNameById = new Map<string, string>();
+
+  let i = 0;
+  while (i < messages.length) {
+    const message = messages[i];
+    if (message === undefined) break;
+
+    if (message.role === 'system') {
+      // Google GenAI's `Content.role` only accepts "user" or "model", so a
+      // system message in the history (e.g. from session restore or
+      // cross-provider migration) would be rejected by the API. Preserve
+      // the content by wrapping it in a `<system>` tag and attaching it as
+      // a user turn — mirrors the Anthropic provider's behavior. The
+      // dedicated top-level `systemPrompt` still flows into
+      // `system_instruction` separately; only historical system messages
+      // come through here.
+      const text = message.content
+        .filter((p): p is { type: 'text'; text: string } => p.type === 'text')
+        .map((p) => p.text)
+        .join('\n');
+      if (text.length > 0) {
+        contents.push({
+          role: 'user',
+          parts: [{ text: `<system>${text}</system>` }],
+        });
+      }
+      i += 1;
+      continue;
+    }
+
+    if (message.role === 'assistant' && message.toolCalls.length > 0) {
+      contents.push(messageToGoogleGenAI(message));
+      const expectedToolCallIds: string[] = [];
+      for (const toolCall of message.toolCalls) {
+        toolNameById.set(toolCall.id, toolCall.function.name);
+        expectedToolCallIds.push(toolCall.id);
+      }
+
+      // Collect consecutive tool messages
+      let j = i + 1;
+      const toolMessages: Message[] = [];
+      while (j < messages.length) {
+        const toolMsg = messages[j];
+        if (toolMsg === undefined || toolMsg.role !== 'tool') break;
+        toolMessages.push(toolMsg);
+        j += 1;
+      }
+
+      if (toolMessages.length > 0) {
+        // Sort tool results to match the order of tool calls in the assistant
+        // message, and reject incomplete / duplicated / unexpected results.
+        // Gemini/Vertex expects the next user turn to contain a matching set of
+        // function responses for the preceding function calls.
+        const toolMsgById = new Map<string, Message>();
+        const seenToolCallIds = new Set<string>();
+        for (const toolMsg of toolMessages) {
+          if (toolMsg.toolCallId === undefined) {
+            throw new ChatProviderError('Tool response is missing `toolCallId`.');
+          }
+          if (seenToolCallIds.has(toolMsg.toolCallId)) {
+            throw new ChatProviderError(`Duplicate tool response for id: ${toolMsg.toolCallId}`);
+          }
+          seenToolCallIds.add(toolMsg.toolCallId);
+          toolMsgById.set(toolMsg.toolCallId, toolMsg);
+        }
+
+        const sortedToolMessages: Message[] = [];
+        for (const expectedId of expectedToolCallIds) {
+          const msg = toolMsgById.get(expectedId);
+          if (msg === undefined) {
+            throw new ChatProviderError(`Missing tool responses for ids: ${expectedId}`);
+          }
+          sortedToolMessages.push(msg);
+          toolMsgById.delete(expectedId);
+        }
+        if (toolMsgById.size > 0) {
+          throw new ChatProviderError(
+            `Unexpected tool responses for ids: ${JSON.stringify([...toolMsgById.keys()])}`,
+          );
+        }
+
+        // Pack all tool results into a single user Content.
+        // Each tool result may expand to multiple parts (functionResponse +
+        // media parts for image/audio/video outputs).
+        const parts: GooglePart[] = [];
+        for (const toolMsg of sortedToolMessages) {
+          parts.push(...toolMessageToFunctionResponseParts(toolMsg, toolNameById));
+        }
+        contents.push({ role: 'user', parts });
+        i = j;
+        continue;
+      }
+
+      i += 1;
+      continue;
+    }
+
+    if (message.role === 'tool') {
+      // Tool message without preceding assistant message
+      const parts: GooglePart[] = toolMessageToFunctionResponseParts(message, toolNameById);
+      contents.push({ role: 'user', parts });
+      i += 1;
+      continue;
+    }
+
+    contents.push(messageToGoogleGenAI(message));
+    i += 1;
+  }
+
+  return contents;
+}
+export class GoogleGenAIStreamedMessage implements StreamedMessage {
+  private _id: string | null = null;
+  private _usage: TokenUsage | null = null;
+  private _finishReason: FinishReason | null = null;
+  private _rawFinishReason: string | null = null;
+  private readonly _iter: AsyncGenerator<StreamedMessagePart>;
+
+  constructor(
+    response: AsyncIterable<Record<string, unknown>> | Record<string, unknown>,
+    isStream: boolean,
+    signal?: AbortSignal,
+  ) {
+    if (isStream) {
+      this._iter = this._convertStreamResponse(
+        response as AsyncIterable<Record<string, unknown>>,
+        signal,
+      );
+    } else {
+      this._iter = this._convertNonStreamResponse(response as Record<string, unknown>, signal);
+    }
+  }
+
+  get id(): string | null {
+    return this._id;
+  }
+
+  get usage(): TokenUsage | null {
+    return this._usage;
+  }
+
+  get finishReason(): FinishReason | null {
+    return this._finishReason;
+  }
+
+  get rawFinishReason(): string | null {
+    return this._rawFinishReason;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+    yield* this._iter;
+  }
+
+  private _captureFinishReason(response: Record<string, unknown>): void {
+    const candidates = response['candidates'] as unknown[] | undefined;
+    if (!candidates || candidates.length === 0) {
+      return;
+    }
+    const first = candidates[0] as Record<string, unknown> | undefined;
+    if (first === undefined) {
+      return;
+    }
+    const raw = first['finishReason'] ?? first['finish_reason'];
+    if (raw === undefined) {
+      return;
+    }
+    const normalized = normalizeGoogleGenAIFinishReason(raw);
+    // Only overwrite when we got a definitive signal — early stream
+    // chunks may contain `FINISH_REASON_UNSPECIFIED` while the model is
+    // still generating, and we treat those as "not yet known".
+    if (normalized.finishReason !== null || normalized.rawFinishReason !== null) {
+      this._finishReason = normalized.finishReason;
+      this._rawFinishReason = normalized.rawFinishReason;
+    }
+  }
+
+  /** Yield parts from a single (non-streamed) GenerateContentResponse. */
+  private _extractChunkParts(response: Record<string, unknown>): StreamedMessagePart[] {
+    const parts: StreamedMessagePart[] = [];
+
+    const candidates = response['candidates'] as unknown[] | undefined;
+    for (const candidate of candidates ?? []) {
+      const cand = candidate as Record<string, unknown>;
+      const content = cand['content'] as Record<string, unknown> | undefined;
+      const contentParts = content?.['parts'] as unknown[] | undefined;
+      if (!contentParts) continue;
+
+      for (const part of contentParts) {
+        const p = part as Record<string, unknown>;
+        if (p['thought'] === true && p['text']) {
+          parts.push({ type: 'think', think: p['text'] as string });
+        } else if (p['text']) {
+          parts.push({ type: 'text', text: p['text'] as string });
+        } else if (p['functionCall'] || p['function_call']) {
+          const fc = (p['functionCall'] ?? p['function_call']) as Record<string, unknown>;
+          const name = fc['name'] as string;
+          if (!name) continue;
+          const id_ = (fc['id'] as string) ?? crypto.randomUUID();
+          const toolCallId = `${name}_${id_}`;
+          const thoughtSigB64 = p['thoughtSignature'] ?? p['thought_signature'];
+          parts.push({
+            type: 'function',
+            id: toolCallId,
+            function: {
+              name,
+              arguments: fc['args'] ? JSON.stringify(fc['args']) : '{}',
+            },
+            ...(thoughtSigB64
+              ? { extras: { thought_signature_b64: thoughtSigB64 as string } }
+              : {}),
+          } satisfies ToolCall);
+        }
+      }
+    }
+
+    return parts;
+  }
+
+  /** Extract usage metadata from a response chunk. */
+  private _extractUsage(response: Record<string, unknown>): void {
+    const usageMetadata = response['usageMetadata'] as Record<string, unknown> | undefined;
+    if (usageMetadata) {
+      const promptTokenCount =
+        typeof usageMetadata['promptTokenCount'] === 'number'
+          ? usageMetadata['promptTokenCount']
+          : 0;
+      const cachedContentTokenCount =
+        typeof usageMetadata['cachedContentTokenCount'] === 'number'
+          ? usageMetadata['cachedContentTokenCount']
+          : 0;
+      this._usage = {
+        inputOther: Math.max(promptTokenCount - cachedContentTokenCount, 0),
+        output: (usageMetadata['candidatesTokenCount'] as number) ?? 0,
+        inputCacheRead: cachedContentTokenCount,
+        inputCacheCreation: 0,
+      };
+    }
+  }
+
+  /** Extract response ID from a response chunk. */
+  private _extractId(response: Record<string, unknown>): void {
+    if (response['responseId'] !== undefined) {
+      this._id = response['responseId'] as string;
+    }
+  }
+
+  private _throwIfAborted(signal: AbortSignal | undefined): void {
+    // Helper kept small so TypeScript's control-flow narrowing does not
+    // collapse `signal.aborted` to `false | undefined` at call sites that
+    // check the signal repeatedly between async steps.
+    if (signal !== undefined && signal.aborted) {
+      throw createAbortError();
+    }
+  }
+
+  private async *_convertNonStreamResponse(
+    response: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): AsyncGenerator<StreamedMessagePart> {
+    this._throwIfAborted(signal);
+    this._extractUsage(response);
+    this._extractId(response);
+    this._captureFinishReason(response);
+    for (const part of this._extractChunkParts(response)) {
+      this._throwIfAborted(signal);
+      yield part;
+    }
+  }
+
+  private async *_convertStreamResponse(
+    response: AsyncIterable<Record<string, unknown>>,
+    signal?: AbortSignal,
+  ): AsyncGenerator<StreamedMessagePart> {
+    try {
+      for await (const chunk of response) {
+        // Check abort at each chunk boundary so users who pass an
+        // AbortSignal see cancellation honored promptly even though the
+        // Google GenAI SDK does not forward it to the underlying fetch.
+        this._throwIfAborted(signal);
+        this._extractUsage(chunk);
+        this._extractId(chunk);
+        this._captureFinishReason(chunk);
+        for (const part of this._extractChunkParts(chunk)) {
+          this._throwIfAborted(signal);
+          yield part;
+        }
+      }
+    } catch (error: unknown) {
+      // Preserve AbortError identity so the retry/generate loop can
+      // distinguish it from transient provider errors.
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        throw error;
+      }
+      throw convertGoogleGenAIError(error);
+    }
+  }
+}
+const NETWORK_RE = /network|connection|connect|disconnect|fetch failed/i;
+const TIMEOUT_RE = /timed?\s*out|timeout|deadline/i;
+
+/**
+ * Convert a Google GenAI SDK error (or raw Error) to a kosong `ChatProviderError`.
+ */
+export function convertGoogleGenAIError(error: unknown): ChatProviderError {
+  // Google SDK's exported ApiError carries an HTTP status code
+  if (error instanceof GoogleApiError) {
+    return normalizeAPIStatusError(error.status, error.message);
+  }
+  if (error instanceof Error) {
+    const msg = error.message;
+    // Timeout takes priority over network (a timeout is also a connection issue)
+    if (TIMEOUT_RE.test(msg)) {
+      return new APITimeoutError(msg);
+    }
+    // Network / fetch errors (e.g. TypeError: fetch failed)
+    if (NETWORK_RE.test(msg) || (error instanceof TypeError && msg.includes('fetch'))) {
+      return new APIConnectionError(msg);
+    }
+    // Try to extract status code from unknown error shapes
+    const statusCode = (error as { code?: number }).code;
+    if (typeof statusCode === 'number') {
+      return normalizeAPIStatusError(statusCode, msg);
+    }
+    return new ChatProviderError(`GoogleGenAI error: ${msg}`);
+  }
+  return new ChatProviderError(`GoogleGenAI error: ${String(error)}`);
+}
+export class GoogleGenAIChatProvider implements ChatProvider {
+  readonly name: string = 'google_genai';
+
+  private _model: string;
+  private _client: GenAIClient | undefined;
+  private _generationKwargs: GoogleGenAIGenerationKwargs;
+  private _vertexai: boolean;
+  private _stream: boolean;
+  private _apiKey: string | undefined;
+  private _project: string | undefined;
+  private _location: string | undefined;
+  private _clientFactory: ((auth: ProviderRequestAuth) => GenAIClient) | undefined;
+
+  constructor(options: GoogleGenAIOptions) {
+    this._model = options.model;
+    this._vertexai = options.vertexai ?? false;
+    this._stream = options.stream ?? true;
+    this._generationKwargs = {};
+
+    const apiKey = options.apiKey ?? process.env['GOOGLE_API_KEY'];
+    this._apiKey = apiKey === undefined || apiKey.length === 0 ? undefined : apiKey;
+    this._project = options.project;
+    this._location = options.location;
+    this._clientFactory = options.clientFactory;
+    this._client =
+      this._vertexai || this._apiKey !== undefined ? this._buildClient(this._apiKey) : undefined;
+  }
+
+  private _buildClient(apiKey: string | undefined): GenAIClient {
+    return new GenAIClient({
+      apiKey,
+      ...(this._vertexai
+        ? {
+            vertexai: true,
+            project: this._project,
+            location: this._location,
+          }
+        : {}),
+    });
+  }
+
+  get modelName(): string {
+    return this._model;
+  }
+
+  get thinkingEffort(): ThinkingEffort | null {
+    const thinkingConfig = this._generationKwargs.thinking_config;
+    if (thinkingConfig === undefined) return null;
+
+    // For gemini-3 models that use thinking_level
+    if (thinkingConfig.thinking_level !== undefined) {
+      switch (thinkingConfig.thinking_level) {
+        case 'MINIMAL':
+          // MINIMAL + suppressed thoughts is how 'off' is encoded for Gemini 3,
+          // which has no true "disabled" level.
+          return thinkingConfig.include_thoughts === false ? 'off' : 'low';
+        case 'LOW':
+          return 'low';
+        case 'MEDIUM':
+          return 'medium';
+        case 'HIGH':
+          return 'high';
+        default:
+          return null;
+      }
+    }
+
+    // For other models that use thinking_budget
+    if (thinkingConfig.thinking_budget !== undefined) {
+      if (thinkingConfig.thinking_budget === 0) return 'off';
+      if (thinkingConfig.thinking_budget <= 1024) return 'low';
+      if (thinkingConfig.thinking_budget <= 4096) return 'medium';
+      return 'high';
+    }
+
+    return null;
+  }
+
+  get modelParameters(): Record<string, unknown> {
+    return {
+      model: this._model,
+      ...this._generationKwargs,
+    };
+  }
+
+  getCapability(model?: string): ModelCapability {
+    return getGoogleGenAIModelCapability(model ?? this._model);
+  }
+
+  async generate(
+    systemPrompt: string,
+    tools: Tool[],
+    history: Message[],
+    options?: GenerateOptions,
+  ): Promise<StreamedMessage> {
+    // Short-circuit if the caller has already aborted — the Google GenAI
+    // SDK will not honor the signal natively, so we must check manually.
+    if (options?.signal?.aborted === true) {
+      throw createAbortError();
+    }
+
+    const contents = messagesToGoogleGenAIContents(history);
+
+    const config: Record<string, unknown> = {
+      ...this._generationKwargs,
+      system_instruction: systemPrompt,
+      ...(tools.length > 0 ? { tools: tools.map((t) => toolToGoogleGenAI(t)) } : {}),
+    };
+
+    try {
+      const client = this._createClient(options?.auth);
+      const models = client.models as unknown as {
+        generateContent(params: Record<string, unknown>): Promise<unknown>;
+        generateContentStream(params: Record<string, unknown>): Promise<AsyncGenerator>;
+      };
+
+      const params = { model: this._model, contents, config };
+
+      // The Google GenAI SDK does not accept an AbortSignal, so we must race
+      // the initial SDK request against the caller's abort signal ourselves.
+      // Once we have a response/stream object, the wrapper below continues to
+      // check the signal at each chunk boundary.
+      if (this._stream) {
+        const stream = await Promise.race([
+          models.generateContentStream(params),
+          abortPromise(options?.signal),
+        ]);
+        return new GoogleGenAIStreamedMessage(
+          stream as AsyncIterable<Record<string, unknown>>,
+          true,
+          options?.signal,
+        );
+      }
+
+      const response = await Promise.race([
+        models.generateContent(params),
+        abortPromise(options?.signal),
+      ]);
+      return new GoogleGenAIStreamedMessage(
+        response as Record<string, unknown>,
+        false,
+        options?.signal,
+      );
+    } catch (error: unknown) {
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        throw error;
+      }
+      throw convertGoogleGenAIError(error);
+    }
+  }
+
+  private _createClient(auth: ProviderRequestAuth | undefined): GenAIClient {
+    return resolveAuthBackedClient(
+      { cachedClient: this._client, clientFactory: this._clientFactory },
+      auth,
+      (a) => {
+        // Vertex AI auth flows through google-auth-library service credentials,
+        // not a request-scoped apiKey, and the @google/genai SDK has no
+        // perRequest header channel — so neither `auth.apiKey` nor
+        // `auth.headers` is propagated in vertexai mode. Callers that need
+        // request-scoped credentials should instead point their service
+        // account at the right principal.
+        if (this._vertexai) return this._buildClient(this._apiKey);
+        return this._buildClient(requireProviderApiKey('GoogleGenAIChatProvider', a, this._apiKey));
+      },
+    );
+  }
+
+  withThinking(effort: ThinkingEffort): GoogleGenAIChatProvider {
+    const thinkingConfig: ThinkingConfig = { include_thoughts: true };
+
+    if (this._model.includes('gemini-3')) {
+      // Gemini 3 models use thinking_level (MINIMAL/LOW/MEDIUM/HIGH). The SDK
+      // does not expose a "disabled" level, so 'off' maps to MINIMAL with
+      // thought output suppressed — the lowest thinking intensity available.
+      switch (effort) {
+        case 'off':
+          thinkingConfig.thinking_level = 'MINIMAL';
+          thinkingConfig.include_thoughts = false;
+          break;
+        case 'low':
+          thinkingConfig.thinking_level = 'LOW';
+          break;
+        case 'medium':
+          thinkingConfig.thinking_level = 'MEDIUM';
+          break;
+        case 'high':
+        case 'xhigh':
+        case 'max':
+          thinkingConfig.thinking_level = 'HIGH';
+          break;
+      }
+    } else {
+      switch (effort) {
+        case 'off':
+          thinkingConfig.thinking_budget = 0;
+          thinkingConfig.include_thoughts = false;
+          break;
+        case 'low':
+          thinkingConfig.thinking_budget = 1024;
+          thinkingConfig.include_thoughts = true;
+          break;
+        case 'medium':
+          thinkingConfig.thinking_budget = 4096;
+          thinkingConfig.include_thoughts = true;
+          break;
+        case 'high':
+        case 'xhigh':
+        case 'max':
+          thinkingConfig.thinking_budget = 32_000;
+          thinkingConfig.include_thoughts = true;
+          break;
+      }
+    }
+
+    return this.withGenerationKwargs({ thinking_config: thinkingConfig });
+  }
+
+  withGenerationKwargs(kwargs: GoogleGenAIGenerationKwargs): GoogleGenAIChatProvider {
+    const clone = this._clone();
+    clone._generationKwargs = { ...clone._generationKwargs, ...kwargs };
+    return clone;
+  }
+
+  private _clone(): GoogleGenAIChatProvider {
+    const clone = Object.assign(
+      Object.create(Object.getPrototypeOf(this) as object) as GoogleGenAIChatProvider,
+      this,
+    );
+    clone._generationKwargs = { ...this._generationKwargs };
+    return clone;
+  }
+}
diff --git a/packages/kosong/src/providers/index.ts b/packages/kosong/src/providers/index.ts
new file mode 100644
index 000000000..4d5940844
--- /dev/null
+++ b/packages/kosong/src/providers/index.ts
@@ -0,0 +1,35 @@
+import type { ChatProvider } from '../provider';
+import { AnthropicChatProvider, type AnthropicOptions } from './anthropic';
+import { GoogleGenAIChatProvider, type GoogleGenAIOptions } from './google-genai';
+import { KimiChatProvider, type KimiOptions } from './kimi';
+import { OpenAILegacyChatProvider, type OpenAILegacyOptions } from './openai-legacy';
+import { OpenAIResponsesChatProvider, type OpenAIResponsesOptions } from './openai-responses';
+
+export type ProviderConfig =
+  | ({ type: 'anthropic' } & AnthropicOptions)
+  | ({ type: 'openai' } & OpenAILegacyOptions)
+  | ({ type: 'kimi' } & KimiOptions)
+  | ({ type: 'google-genai' } & GoogleGenAIOptions)
+  | ({ type: 'openai_responses' } & OpenAIResponsesOptions)
+  | ({ type: 'vertexai' } & GoogleGenAIOptions);
+
+export function createProvider(config: ProviderConfig): ChatProvider {
+  switch (config.type) {
+    case 'anthropic':
+      return new AnthropicChatProvider(config);
+    case 'openai':
+      return new OpenAILegacyChatProvider(config);
+    case 'kimi':
+      return new KimiChatProvider(config);
+    case 'google-genai':
+      return new GoogleGenAIChatProvider(config);
+    case 'openai_responses':
+      return new OpenAIResponsesChatProvider(config);
+    case 'vertexai':
+      return new GoogleGenAIChatProvider(config);
+    default: {
+      const exhaustive: never = config;
+      throw new Error(`Unknown provider type: ${String(exhaustive)}`);
+    }
+  }
+}
diff --git a/packages/kosong/src/providers/kimi-files.ts b/packages/kosong/src/providers/kimi-files.ts
new file mode 100644
index 000000000..c0ea87c4f
--- /dev/null
+++ b/packages/kosong/src/providers/kimi-files.ts
@@ -0,0 +1,191 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { ChatProviderError } from '#/errors';
+import type { VideoURLPart } from '#/message';
+import type { ProviderRequestAuth, VideoUploadInput } from '#/provider';
+import type OpenAI from 'openai';
+import OpenAIClient from 'openai';
+
+import { convertOpenAIError } from './openai-common';
+import {
+  mergeRequestHeaders,
+  requireProviderApiKey,
+  resolveAuthBackedClient,
+} from './request-auth';
+
+export interface KimiUploadOptions {
+  auth?: ProviderRequestAuth;
+  signal?: AbortSignal;
+}
+
+export interface KimiFilesOptions {
+  apiKey?: string;
+  baseUrl: string;
+  defaultHeaders?: Record<string, string>;
+  clientFactory?: (auth: ProviderRequestAuth) => OpenAI;
+}
+
+/**
+ * Kimi-specific file upload client.
+ *
+ * Wraps the underlying OpenAI-compatible `files.create` API to upload videos
+ * to Moonshot's file service and return them as {@link VideoURLPart} values
+ * suitable for use in chat messages.
+ *
+ * A `KimiFiles` instance is typically obtained from
+ * {@link KimiChatProvider.files}.
+ */
+export class KimiFiles {
+  private readonly _apiKey: string | undefined;
+  private readonly _baseUrl: string;
+  private readonly _defaultHeaders: Record<string, string> | undefined;
+  private readonly _client: OpenAI | undefined;
+  private readonly _clientFactory: ((auth: ProviderRequestAuth) => OpenAI) | undefined;
+
+  constructor(options: KimiFilesOptions) {
+    this._apiKey = options.apiKey;
+    this._baseUrl = options.baseUrl;
+    this._defaultHeaders = options.defaultHeaders;
+    this._clientFactory = options.clientFactory;
+    this._client =
+      options.apiKey === undefined || options.apiKey.length === 0
+        ? undefined
+        : new OpenAIClient({
+            apiKey: options.apiKey,
+            baseURL: options.baseUrl,
+            defaultHeaders: options.defaultHeaders,
+          });
+  }
+
+  /**
+   * Upload a video file to Kimi/Moonshot for use in chat messages.
+   *
+   * Accepts either a local filesystem path or an in-memory
+   * {@link VideoUploadInput}. Returns a {@link VideoURLPart} referencing the
+   * uploaded file by its Moonshot file id.
+   *
+   * @param input - Local path string or `{ data, mimeType }` object.
+   * @returns A `VideoURLPart` whose `url` references the uploaded file
+   *          by its Moonshot file id (e.g. `ms://<file-id>`).
+   * @throws {ChatProviderError} if the input is not a video or the upload
+   *         fails.
+   */
+  async uploadVideo(
+    input: string | VideoUploadInput,
+    options?: KimiUploadOptions,
+  ): Promise<VideoURLPart> {
+    let file: unknown;
+
+    if (typeof input === 'string') {
+      // Validate the path eagerly so callers get a clear synchronous-ish
+      // failure rather than a generic stream error from the upload pipeline.
+      if (!fs.existsSync(input)) {
+        throw new ChatProviderError(`Video file not found: ${input}`);
+      }
+      const filename = path.basename(input);
+      // Infer mime type from the file extension and reject anything that is
+      // not a recognised video type. Without this check, callers passing a
+      // non-video file (e.g. `note.txt`) would still hit the upload API and
+      // fail with a confusing server error; surfacing the issue here keeps
+      // the API contract honest and matches the `VideoUploadInput` branch.
+      const mimeType = guessMimeTypeFromExt(filename);
+      if (mimeType === undefined || !mimeType.startsWith('video/')) {
+        throw new ChatProviderError(
+          `KimiFiles.uploadVideo: file extension does not indicate a video type: ${filename}`,
+        );
+      }
+      // Read the file into memory and wrap it in a File/Blob. We avoid
+      // `fs.createReadStream` here because a still-open stream would race
+      // with callers that delete the source file after `uploadVideo`
+      // resolves (also common in tests with tmp directories).
+      const data = await fs.promises.readFile(input);
+      const blob = new Blob([new Uint8Array(data)], { type: mimeType });
+      file = new File([blob], filename, { type: mimeType });
+    } else {
+      if (!input.mimeType.startsWith('video/')) {
+        throw new ChatProviderError(`Expected a video mime type, got ${input.mimeType}`);
+      }
+      const filename = input.filename ?? guessFilename(input.mimeType);
+      // The OpenAI SDK's `Uploadable` accepts a File-like object. We build
+      // one via the standard Web `File` constructor (available in Node 20+).
+      // `Blob` and `File` are available as globals in Node 20+. The cast via
+      // `Uint8Array` satisfies `BlobPart` in both Node and DOM lib contexts.
+      const bytes = input.data instanceof Uint8Array ? input.data : new Uint8Array(input.data);
+      const blob = new Blob([bytes], { type: input.mimeType });
+      file = new File([blob], filename, { type: input.mimeType });
+    }
+
+    let uploaded: { id: string };
+    try {
+      const client = this._createClient(options?.auth);
+      uploaded = (await client.files.create(
+        {
+          file: file as never,
+          purpose: 'video' as never,
+        },
+        options?.signal ? { signal: options.signal } : undefined,
+      )) as unknown as { id: string };
+    } catch (error: unknown) {
+      throw convertOpenAIError(error);
+    }
+
+    return {
+      type: 'video_url',
+      videoUrl: {
+        url: `ms://${uploaded.id}`,
+        id: uploaded.id,
+      },
+    };
+  }
+
+  private _createClient(auth: ProviderRequestAuth | undefined): OpenAI {
+    return resolveAuthBackedClient(
+      { cachedClient: this._client, clientFactory: this._clientFactory },
+      auth,
+      (a) => {
+        const defaultHeaders = mergeRequestHeaders(this._defaultHeaders, a?.headers);
+        return new OpenAIClient({
+          apiKey: requireProviderApiKey('KimiFiles.uploadVideo', a, this._apiKey),
+          baseURL: this._baseUrl,
+          defaultHeaders,
+        });
+      },
+    );
+  }
+}
+
+/**
+ * Guess a filename for an upload from a video MIME type.
+ * Falls back to `upload.bin` for unknown types.
+ */
+function guessFilename(mimeType: string): string {
+  const ext = MIME_TO_EXT[mimeType.toLowerCase()] ?? 'bin';
+  return `upload.${ext}`;
+}
+
+const MIME_TO_EXT: Record<string, string> = {
+  'video/mp4': 'mp4',
+  'video/mpeg': 'mpeg',
+  'video/quicktime': 'mov',
+  'video/webm': 'webm',
+  'video/x-matroska': 'mkv',
+  'video/x-msvideo': 'avi',
+  'video/x-flv': 'flv',
+  'video/3gpp': '3gp',
+};
+
+const EXT_TO_MIME: Record<string, string> = Object.fromEntries(
+  Object.entries(MIME_TO_EXT).map(([mime, ext]) => [ext, mime]),
+);
+
+/**
+ * Guess a MIME type from a filename extension. Only recognises the video
+ * types listed in {@link MIME_TO_EXT}; returns `undefined` otherwise.
+ */
+function guessMimeTypeFromExt(filename: string): string | undefined {
+  const dot = filename.lastIndexOf('.');
+  if (dot < 0) return undefined;
+  const ext = filename.slice(dot + 1).toLowerCase();
+  return EXT_TO_MIME[ext];
+}
diff --git a/packages/kosong/src/providers/kimi-schema.ts b/packages/kosong/src/providers/kimi-schema.ts
new file mode 100644
index 000000000..f603a144c
--- /dev/null
+++ b/packages/kosong/src/providers/kimi-schema.ts
@@ -0,0 +1,424 @@
+/**
+ * Dereference all `$ref` references in a JSON Schema by inlining definitions
+ * from local JSON pointers such as `$defs` and draft-7 `definitions`. Resolved
+ * top-level definition buckets are removed from the result.
+ *
+ * Circular references are detected and left as `$ref` to avoid infinite
+ * recursion; in that case the referenced definition bucket is preserved so the
+ * remaining local `$ref` pointers stay resolvable to a JSON Schema validator.
+ */
+export function derefJsonSchema(schema: Record<string, unknown>): Record<string, unknown> {
+  const visited = new Set<string>();
+  const result = resolveNode(schema, schema, visited) as Record<string, unknown>;
+
+  // Only delete definition buckets if no refs into them remain in the result.
+  // Cyclic refs are intentionally preserved by resolveNode() and still need
+  // their definition buckets; dropping them would leave dangling pointers.
+  if (!hasUnresolvedDefinitionRef(result, '$defs')) {
+    delete result['$defs'];
+  }
+  if (!hasUnresolvedDefinitionRef(result, 'definitions')) {
+    delete result['definitions'];
+  }
+  return result;
+}
+
+type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+type SchemaSlotKind = 'single' | 'array' | 'map' | 'schema-or-array';
+type StructuralJsonSchemaType = Extract<JsonSchemaType, 'string' | 'object' | 'array'>;
+
+interface ChildSchemaSlot {
+  key: string;
+  kind: SchemaSlotKind;
+  parentType?: StructuralJsonSchemaType;
+}
+
+const TYPE_COMPLETION_SKIP_KEYS = new Set([
+  '$ref',
+  'allOf',
+  'anyOf',
+  'else',
+  'if',
+  'not',
+  'oneOf',
+  'then',
+]);
+
+// Child-schema positions that this Kimi normalizer knows how to walk. This is
+// also the source of truth for child-schema keywords that imply the parent
+// schema's type. It is not a list of keywords that Moonshot accepts on the wire.
+const CHILD_SCHEMA_SLOTS = [
+  { key: '$defs', kind: 'map' },
+  { key: 'definitions', kind: 'map' },
+  { key: 'dependencies', kind: 'map', parentType: 'object' },
+  { key: 'dependentSchemas', kind: 'map', parentType: 'object' },
+  { key: 'patternProperties', kind: 'map', parentType: 'object' },
+  { key: 'properties', kind: 'map', parentType: 'object' },
+  { key: 'additionalItems', kind: 'single', parentType: 'array' },
+  { key: 'additionalProperties', kind: 'single', parentType: 'object' },
+  { key: 'contains', kind: 'single', parentType: 'array' },
+  { key: 'contentSchema', kind: 'single', parentType: 'string' },
+  { key: 'else', kind: 'single' },
+  { key: 'if', kind: 'single' },
+  { key: 'not', kind: 'single' },
+  { key: 'propertyNames', kind: 'single', parentType: 'object' },
+  { key: 'then', kind: 'single' },
+  { key: 'unevaluatedItems', kind: 'single', parentType: 'array' },
+  { key: 'unevaluatedProperties', kind: 'single', parentType: 'object' },
+  { key: 'allOf', kind: 'array' },
+  { key: 'anyOf', kind: 'array' },
+  { key: 'oneOf', kind: 'array' },
+  { key: 'prefixItems', kind: 'array', parentType: 'array' },
+  { key: 'items', kind: 'schema-or-array', parentType: 'array' },
+] as const satisfies readonly ChildSchemaSlot[];
+
+const OBJECT_STRUCTURE_KEYS = new Set([
+  ...childSchemaKeysForParentType('object'),
+  'dependentRequired',
+  'maxProperties',
+  'minProperties',
+  'required',
+]);
+
+const ARRAY_STRUCTURE_KEYS = new Set([
+  ...childSchemaKeysForParentType('array'),
+  'maxContains',
+  'maxItems',
+  'minContains',
+  'minItems',
+  'uniqueItems',
+]);
+
+const STRING_STRUCTURE_KEYS = new Set([
+  ...childSchemaKeysForParentType('string'),
+  'contentEncoding',
+  'contentMediaType',
+  'format',
+  'maxLength',
+  'minLength',
+  'pattern',
+]);
+
+const NUMERIC_STRUCTURE_KEYS = new Set([
+  'exclusiveMaximum',
+  'exclusiveMinimum',
+  'maximum',
+  'minimum',
+  'multipleOf',
+]);
+
+/**
+ * Return a deep-cloned JSON Schema with missing `type` fields filled in for
+ * Kimi tool compatibility.
+ *
+ * Moonshot's tool validator rejects some valid JSON Schema shapes when nested
+ * property schemas omit `type` (for example enum-only MCP properties). This is
+ * a provider-compatibility normalizer, not a complete JSON Schema compiler:
+ * it resolves local refs, preserves combinator nodes, infers obvious
+ * scalar/object/array types, and falls back to `string` only for nested
+ * typeless property schemas. The root schema object is treated as a container
+ * and is not itself normalized.
+ */
+export function normalizeKimiToolSchema(schema: Record<string, unknown>): Record<string, unknown> {
+  return ensureKimiPropertyTypes(derefJsonSchema(schema));
+}
+
+function ensureKimiPropertyTypes(schema: Record<string, unknown>): Record<string, unknown> {
+  const normalized = cloneJsonValue(schema);
+  if (!isRecord(normalized)) {
+    throw new Error('JSON Schema root must normalize to an object.');
+  }
+  recurseSchema(normalized);
+  return normalized;
+}
+
+function hasUnresolvedDefinitionRef(node: unknown, bucketKey: string): boolean {
+  if (Array.isArray(node)) {
+    return node.some((child) => hasUnresolvedDefinitionRef(child, bucketKey));
+  }
+  if (typeof node === 'object' && node !== null) {
+    const obj = node as Record<string, unknown>;
+    const ref = obj['$ref'];
+    if (typeof ref === 'string' && ref.startsWith(`#/${bucketKey}/`)) {
+      return true;
+    }
+    for (const [key, value] of Object.entries(obj)) {
+      // Skip the definition bucket itself when walking the result — we only
+      // care about `$ref` pointers living elsewhere in the schema.
+      if (key === bucketKey) continue;
+      if (hasUnresolvedDefinitionRef(value, bucketKey)) return true;
+    }
+    return false;
+  }
+  return false;
+}
+
+function resolveNode(node: unknown, root: Record<string, unknown>, visited: Set<string>): unknown {
+  if (Array.isArray(node)) {
+    return node.map((item) => resolveNode(item, root, visited));
+  }
+
+  if (typeof node === 'object' && node !== null) {
+    const obj = node as Record<string, unknown>;
+
+    // Handle $ref
+    if (typeof obj['$ref'] === 'string') {
+      const ref = obj['$ref'];
+      if (isLocalJsonPointerRef(ref)) {
+        if (visited.has(ref)) {
+          // Circular reference — return the $ref as-is to avoid infinite recursion
+          return obj;
+        }
+        const resolvedRef = resolveLocalJsonPointer(root, ref);
+        if (resolvedRef.found) {
+          visited.add(ref);
+          const resolved = resolveNode(resolvedRef.value, root, visited);
+          visited.delete(ref);
+          // Preserve sibling keywords (JSON Schema 2020-12 semantics):
+          // a node may contain `$ref` alongside other fields like
+          // `description`, `default`, or local constraints. Python's deref
+          // implementation merges these with the resolved definition;
+          // sibling keys on the local node take precedence.
+          if (typeof resolved === 'object' && resolved !== null && !Array.isArray(resolved)) {
+            const merged: Record<string, unknown> = { ...(resolved as Record<string, unknown>) };
+            for (const [key, value] of Object.entries(obj)) {
+              if (key === '$ref') continue;
+              merged[key] = resolveNode(value, root, visited);
+            }
+            return merged;
+          }
+          return resolved;
+        }
+      }
+      // Unknown $ref — return as-is
+      return obj;
+    }
+
+    const resolved: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      resolved[key] = resolveNode(value, root, visited);
+    }
+    return resolved;
+  }
+
+  return node;
+}
+
+function isLocalJsonPointerRef(ref: string): boolean {
+  return ref === '#' || ref.startsWith('#/');
+}
+
+function resolveLocalJsonPointer(
+  root: Record<string, unknown>,
+  ref: string,
+): { found: true; value: unknown } | { found: false } {
+  if (ref === '#') {
+    return { found: true, value: root };
+  }
+  let current: unknown = root;
+  for (const rawPart of ref.slice(2).split('/')) {
+    const part = unescapeJsonPointerPart(rawPart);
+    if (isRecord(current)) {
+      if (!hasOwn(current, part)) {
+        return { found: false };
+      }
+      current = current[part];
+    } else if (Array.isArray(current)) {
+      const index = parseJsonPointerArrayIndex(part);
+      if (index === null || index >= current.length) {
+        return { found: false };
+      }
+      current = current[index];
+    } else {
+      return { found: false };
+    }
+  }
+  return { found: true, value: current };
+}
+
+function unescapeJsonPointerPart(part: string): string {
+  return part.replaceAll('~1', '/').replaceAll('~0', '~');
+}
+
+function parseJsonPointerArrayIndex(part: string): number | null {
+  if (!/^(0|[1-9]\d*)$/.test(part)) {
+    return null;
+  }
+  return Number(part);
+}
+
+function recurseSchema(node: unknown): void {
+  if (!isRecord(node)) {
+    return;
+  }
+
+  visitChildSchemas(node, normalizeProperty);
+}
+
+function visitChildSchemas(node: Record<string, unknown>, visit: (schema: unknown) => void): void {
+  for (const { key, kind } of CHILD_SCHEMA_SLOTS) {
+    const value = node[key];
+    if (kind === 'single') {
+      if (isRecord(value)) {
+        visit(value);
+      }
+    } else if (kind === 'array') {
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          visit(item);
+        }
+      }
+    } else if (kind === 'map') {
+      if (isRecord(value)) {
+        for (const item of Object.values(value)) {
+          visit(item);
+        }
+      }
+    } else if (kind === 'schema-or-array') {
+      if (isRecord(value)) {
+        visit(value);
+      } else if (Array.isArray(value)) {
+        for (const item of value) {
+          visit(item);
+        }
+      }
+    }
+  }
+}
+
+function childSchemaKeysForParentType(parentType: StructuralJsonSchemaType): string[] {
+  return CHILD_SCHEMA_SLOTS.flatMap((slot) => {
+    if (!('parentType' in slot) || slot.parentType !== parentType) {
+      return [];
+    }
+    return [slot.key];
+  });
+}
+
+function normalizeProperty(node: unknown): void {
+  if (!isRecord(node)) {
+    return;
+  }
+
+  if (!hasOwn(node, 'type') && !hasAnyKey(node, TYPE_COMPLETION_SKIP_KEYS)) {
+    const enumValues = node['enum'];
+    if (Array.isArray(enumValues) && enumValues.length > 0) {
+      node['type'] = inferTypeFromValues(enumValues);
+    } else if (hasOwn(node, 'const')) {
+      node['type'] = inferTypeFromValues([node['const']]);
+    } else {
+      node['type'] = inferTypeFromStructure(node);
+    }
+  }
+
+  recurseSchema(node);
+}
+
+function inferTypeFromStructure(schema: Record<string, unknown>): JsonSchemaType {
+  if (hasAnyKey(schema, OBJECT_STRUCTURE_KEYS)) {
+    return 'object';
+  }
+  if (hasAnyKey(schema, ARRAY_STRUCTURE_KEYS)) {
+    return 'array';
+  }
+  if (hasAnyKey(schema, STRING_STRUCTURE_KEYS)) {
+    return 'string';
+  }
+  if (hasAnyKey(schema, NUMERIC_STRUCTURE_KEYS)) {
+    return 'number';
+  }
+  return 'string';
+}
+
+function inferTypeFromValues(values: unknown[]): JsonSchemaType {
+  const inferred = new Set<JsonSchemaType>();
+  for (const value of values) {
+    const valueType = inferValueType(value);
+    if (valueType === undefined) {
+      throw new Error('Cannot infer JSON Schema type from non-JSON enum or const value.');
+    }
+    inferred.add(valueType);
+  }
+  const types = normalizeInferredTypes(inferred);
+  if (types.length === 1) {
+    const onlyType = types[0];
+    if (onlyType === undefined) {
+      throw new Error('Cannot infer JSON Schema type from an empty enum.');
+    }
+    return onlyType;
+  }
+  throw new Error('Mixed JSON Schema enum or const types are not supported by Kimi tool schemas.');
+}
+
+function inferValueType(value: unknown): JsonSchemaType | undefined {
+  if (value === null) {
+    return 'null';
+  }
+  if (Array.isArray(value)) {
+    return 'array';
+  }
+  switch (typeof value) {
+    case 'string':
+      return 'string';
+    case 'number':
+      return Number.isInteger(value) ? 'integer' : 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'object':
+      return 'object';
+    case 'bigint':
+    case 'function':
+    case 'symbol':
+    case 'undefined':
+      return undefined;
+  }
+  return undefined;
+}
+
+function normalizeInferredTypes(types: Set<JsonSchemaType>): JsonSchemaType[] {
+  const normalized = new Set(types);
+  if (normalized.has('number')) {
+    normalized.delete('integer');
+  }
+  const order: JsonSchemaType[] = [
+    'string',
+    'number',
+    'integer',
+    'boolean',
+    'object',
+    'array',
+    'null',
+  ];
+  return order.filter((type) => normalized.has(type));
+}
+
+function hasAnyKey(obj: Record<string, unknown>, keys: Set<string>): boolean {
+  for (const key of keys) {
+    if (hasOwn(obj, key)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function cloneJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => cloneJsonValue(item));
+  }
+  if (isRecord(value)) {
+    const cloned: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(value)) {
+      cloned[key] = cloneJsonValue(child);
+    }
+    return cloned;
+  }
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function hasOwn(obj: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
diff --git a/packages/kosong/src/providers/kimi.ts b/packages/kosong/src/providers/kimi.ts
new file mode 100644
index 000000000..1aebb8a1a
--- /dev/null
+++ b/packages/kosong/src/providers/kimi.ts
@@ -0,0 +1,582 @@
+import { UNKNOWN_CAPABILITY, type ModelCapability } from '#/capability';
+import { normalizeKimiToolSchema } from './kimi-schema';
+import type { ContentPart, Message, StreamedMessagePart, ToolCall } from '#/message';
+import type {
+  ChatProvider,
+  FinishReason,
+  GenerateOptions,
+  ProviderRequestAuth,
+  StreamedMessage,
+  ThinkingEffort,
+  VideoUploadInput,
+} from '#/provider';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+import OpenAI from 'openai';
+
+import { KimiFiles } from './kimi-files';
+import {
+  convertChatCompletionStreamToolCall,
+  type BufferedChatCompletionToolCall,
+} from './chat-completions-stream';
+import {
+  convertContentPart,
+  convertOpenAIError,
+  extractUsage,
+  isFunctionToolCall,
+  normalizeOpenAIFinishReason,
+  type OpenAIContentPart,
+  type OpenAIToolParam,
+  reasoningEffortToThinkingEffort,
+  toolToOpenAI,
+} from './openai-common';
+import {
+  mergeRequestHeaders,
+  requireProviderApiKey,
+  resolveAuthBackedClient,
+} from './request-auth';
+export interface KimiOptions {
+  apiKey?: string | undefined;
+  baseUrl?: string | undefined;
+  model: string;
+  stream?: boolean | undefined;
+  defaultHeaders?: Record<string, string> | undefined;
+  generationKwargs?: GenerationKwargs | undefined;
+  clientFactory?: (auth: ProviderRequestAuth) => OpenAI;
+}
+
+export interface GenerationKwargs {
+  /**
+   * Legacy completion-budget alias. The Moonshot Kimi API still accepts
+   * `max_tokens`, but for reasoning models it shares the budget with
+   * `reasoning_content` and a small value can cause a 200 response with no
+   * `content`. Prefer `max_completion_tokens`. When both are set
+   * `max_completion_tokens` wins; this provider normalizes by sending only
+   * `max_completion_tokens` on the wire.
+   */
+  max_tokens?: number | undefined;
+  max_completion_tokens?: number | undefined;
+  temperature?: number | undefined;
+  top_p?: number | undefined;
+  n?: number | undefined;
+  presence_penalty?: number | undefined;
+  frequency_penalty?: number | undefined;
+  stop?: string | string[] | undefined;
+  reasoning_effort?: string | undefined;
+  prompt_cache_key?: string | undefined;
+  extra_body?: ExtraBody;
+}
+
+export interface ThinkingConfig {
+  type?: 'enabled' | 'disabled';
+  keep?: unknown;
+  [key: string]: unknown;
+}
+
+export interface ExtraBody {
+  thinking?: ThinkingConfig;
+  [key: string]: unknown;
+}
+interface OpenAIMessage {
+  role: string;
+  content?: string | OpenAIContentPart[] | undefined;
+  tool_calls?: OpenAIToolCallOut[] | undefined;
+  tool_call_id?: string | undefined;
+  name?: string | undefined;
+  reasoning_content?: string | undefined;
+}
+
+interface OpenAIToolCallOut {
+  type: string;
+  id: string;
+  function: { name: string; arguments: string | null };
+  extras?: Record<string, unknown> | undefined;
+}
+
+function isEffectivelyEmptyContent(parts: ContentPart[]): boolean {
+  for (const part of parts) {
+    if (part.type !== 'text') return false;
+    if (part.text.trim() !== '') return false;
+  }
+  return true;
+}
+
+function convertMessage(message: Message): OpenAIMessage {
+  let reasoningContent = '';
+  const nonThinkParts: ContentPart[] = [];
+
+  for (const part of message.content) {
+    if (part.type === 'think') {
+      reasoningContent += part.think;
+    } else {
+      nonThinkParts.push(part);
+    }
+  }
+
+  // Build the OpenAI message.
+  const result: OpenAIMessage = { role: message.role };
+  const hasToolCalls = message.toolCalls.length > 0;
+  const shouldOmitContent =
+    message.role === 'assistant' && hasToolCalls && isEffectivelyEmptyContent(nonThinkParts);
+
+  if (!shouldOmitContent) {
+    // content: serialize to string if single text, array otherwise
+    const firstPart = nonThinkParts[0];
+    if (nonThinkParts.length === 1 && firstPart?.type === 'text') {
+      result.content = firstPart.text;
+    } else if (nonThinkParts.length > 0) {
+      result.content = nonThinkParts
+        .map((p) => convertContentPart(p))
+        .filter((p): p is OpenAIContentPart => p !== null);
+    }
+  }
+
+  if (message.name !== undefined) {
+    result.name = message.name;
+  }
+
+  if (hasToolCalls) {
+    result.tool_calls = message.toolCalls.map((tc) => {
+      const mapped: OpenAIToolCallOut = {
+        type: tc.type,
+        id: tc.id,
+        function: { name: tc.function.name, arguments: tc.function.arguments },
+      };
+      if (tc.extras !== undefined) {
+        mapped.extras = tc.extras;
+      }
+      return mapped;
+    });
+  }
+
+  if (message.toolCallId !== undefined) {
+    result.tool_call_id = message.toolCallId;
+  }
+
+  if (reasoningContent) {
+    result.reasoning_content = reasoningContent;
+  }
+
+  return result;
+}
+function convertTool(tool: Tool): OpenAIToolParam {
+  if (tool.name.startsWith('$')) {
+    // Kimi builtin functions start with `$`
+    return {
+      type: 'builtin_function',
+      function: { name: tool.name },
+    };
+  }
+  const converted = toolToOpenAI(tool);
+  return {
+    ...converted,
+    function: {
+      ...converted.function,
+      parameters: normalizeKimiToolSchema(tool.parameters),
+    },
+  };
+}
+/**
+ * Extract usage from a streaming chunk. Moonshot may place usage in
+ * `choices[0].usage` in addition to the top-level `usage` field.
+ */
+export function extractUsageFromChunk(
+  chunk: Record<string, unknown>,
+): Record<string, unknown> | null {
+  // Top-level usage
+  if (
+    chunk['usage'] !== null &&
+    chunk['usage'] !== undefined &&
+    typeof chunk['usage'] === 'object'
+  ) {
+    return chunk['usage'] as Record<string, unknown>;
+  }
+  // choices[0].usage (Moonshot proprietary)
+  const choices = chunk['choices'];
+  if (!Array.isArray(choices) || choices.length === 0) {
+    return null;
+  }
+  const firstChoice = choices[0] as Record<string, unknown> | undefined;
+  if (firstChoice === undefined) {
+    return null;
+  }
+  const choiceUsage = firstChoice['usage'];
+  if (choiceUsage !== null && choiceUsage !== undefined && typeof choiceUsage === 'object') {
+    return choiceUsage as Record<string, unknown>;
+  }
+  return null;
+}
+
+class KimiStreamedMessage implements StreamedMessage {
+  private _id: string | null = null;
+  private _usage: TokenUsage | null = null;
+  private _finishReason: FinishReason | null = null;
+  private _rawFinishReason: string | null = null;
+  private readonly _iter: AsyncGenerator<StreamedMessagePart>;
+
+  constructor(
+    response: OpenAI.Chat.ChatCompletion | AsyncIterable<OpenAI.Chat.ChatCompletionChunk>,
+    isStream: boolean,
+  ) {
+    if (isStream) {
+      this._iter = this._convertStreamResponse(
+        response as AsyncIterable<OpenAI.Chat.ChatCompletionChunk>,
+      );
+    } else {
+      this._iter = this._convertNonStreamResponse(response as OpenAI.Chat.ChatCompletion);
+    }
+  }
+
+  get id(): string | null {
+    return this._id;
+  }
+
+  get usage(): TokenUsage | null {
+    return this._usage;
+  }
+
+  get finishReason(): FinishReason | null {
+    return this._finishReason;
+  }
+
+  get rawFinishReason(): string | null {
+    return this._rawFinishReason;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+    yield* this._iter;
+  }
+
+  private _captureFinishReason(raw: string | null | undefined): void {
+    const normalized = normalizeOpenAIFinishReason(raw);
+    this._finishReason = normalized.finishReason;
+    this._rawFinishReason = normalized.rawFinishReason;
+  }
+
+  private async *_convertNonStreamResponse(
+    response: OpenAI.Chat.ChatCompletion,
+  ): AsyncGenerator<StreamedMessagePart> {
+    this._id = response.id;
+    if (response.usage) {
+      this._usage = extractUsage(response.usage) ?? null;
+    }
+    this._captureFinishReason(response.choices[0]?.finish_reason ?? null);
+
+    const message = response.choices[0]?.message;
+    if (!message) return;
+
+    // reasoning_content (Moonshot proprietary)
+    const rc = (message as unknown as Record<string, unknown>)['reasoning_content'];
+    if (typeof rc === 'string' && rc) {
+      yield { type: 'think', think: rc } satisfies StreamedMessagePart;
+    }
+
+    if (message.content) {
+      yield { type: 'text', text: message.content } satisfies StreamedMessagePart;
+    }
+
+    if (message.tool_calls) {
+      for (const toolCall of message.tool_calls) {
+        if (!isFunctionToolCall(toolCall)) continue;
+        yield {
+          type: 'function',
+          id: toolCall.id || crypto.randomUUID(),
+          function: {
+            name: toolCall.function.name,
+            arguments: toolCall.function.arguments,
+          },
+        } satisfies ToolCall;
+      }
+    }
+  }
+
+  private async *_convertStreamResponse(
+    response: AsyncIterable<OpenAI.Chat.ChatCompletionChunk>,
+  ): AsyncGenerator<StreamedMessagePart> {
+    const bufferedToolCalls = new Map<number | string, BufferedChatCompletionToolCall>();
+
+    try {
+      for await (const chunk of response) {
+        if (chunk.id) {
+          this._id = chunk.id;
+        }
+
+        // Extract usage from chunk (supports top-level and choices[0].usage)
+        const rawChunk = chunk as unknown as Record<string, unknown>;
+        const rawUsage = extractUsageFromChunk(rawChunk);
+        if (rawUsage) {
+          this._usage = extractUsage(rawUsage) ?? null;
+        }
+
+        if (!chunk.choices || chunk.choices.length === 0) {
+          continue;
+        }
+
+        const choice = chunk.choices[0];
+        if (!choice) continue;
+
+        // Capture finish_reason whenever the chunk carries one. The Chat
+        // Completions API only sets it on the final chunk for a given
+        // choice, but defensively re-capturing on every non-null value
+        // keeps the latest signal available even if upstream re-emits.
+        if (choice.finish_reason !== null && choice.finish_reason !== undefined) {
+          this._captureFinishReason(choice.finish_reason);
+        }
+
+        const delta = choice.delta;
+
+        // reasoning_content (Moonshot proprietary)
+        const rc = (delta as unknown as Record<string, unknown>)['reasoning_content'];
+        if (typeof rc === 'string' && rc) {
+          yield { type: 'think', think: rc } satisfies StreamedMessagePart;
+        }
+
+        // text content
+        if (delta.content) {
+          yield { type: 'text', text: delta.content } satisfies StreamedMessagePart;
+        }
+
+        // tool calls — preserve `index` on every yielded part so the generate
+        // loop can route interleaved argument deltas from parallel tool calls.
+        for (const toolCall of delta.tool_calls ?? []) {
+          for (const part of convertChatCompletionStreamToolCall(toolCall, bufferedToolCalls)) {
+            yield part;
+          }
+        }
+      }
+    } catch (error: unknown) {
+      throw convertOpenAIError(error);
+    }
+  }
+}
+export class KimiChatProvider implements ChatProvider {
+  readonly name: string = 'kimi';
+
+  private _model: string;
+  private _stream: boolean;
+  private _apiKey: string | undefined;
+  private _baseUrl: string;
+  private _defaultHeaders: Record<string, string> | undefined;
+  private _generationKwargs: GenerationKwargs;
+  private _client: OpenAI | undefined;
+  private _clientFactory: ((auth: ProviderRequestAuth) => OpenAI) | undefined;
+  private _files: KimiFiles | undefined;
+
+  constructor(options: KimiOptions) {
+    const apiKey = options.apiKey ?? process.env['KIMI_API_KEY'];
+    this._apiKey = apiKey === undefined || apiKey.length === 0 ? undefined : apiKey;
+    this._baseUrl = options.baseUrl ?? process.env['KIMI_BASE_URL'] ?? 'https://api.moonshot.ai/v1';
+    this._defaultHeaders = options.defaultHeaders;
+    this._clientFactory = options.clientFactory;
+    this._model = options.model;
+    this._stream = options.stream ?? true;
+    this._generationKwargs = { ...options.generationKwargs };
+    this._client =
+      this._apiKey === undefined
+        ? undefined
+        : new OpenAI({
+            apiKey: this._apiKey,
+            baseURL: this._baseUrl,
+            defaultHeaders: this._defaultHeaders,
+          });
+  }
+
+  get modelName(): string {
+    return this._model;
+  }
+
+  /**
+   * File upload client for Kimi/Moonshot.
+   *
+   * Use this to upload videos (and other media in the future) to the file
+   * service and receive a content part that can be embedded in chat
+   * messages.
+   */
+  get files(): KimiFiles {
+    this._files ??= new KimiFiles({
+      apiKey: this._apiKey,
+      baseUrl: this._baseUrl,
+      defaultHeaders: this._defaultHeaders,
+      clientFactory: this._clientFactory,
+    });
+    return this._files;
+  }
+
+  uploadVideo(input: string | VideoUploadInput, options?: GenerateOptions) {
+    return this.files.uploadVideo(input, options);
+  }
+
+  get thinkingEffort(): ThinkingEffort | null {
+    return reasoningEffortToThinkingEffort(this._generationKwargs.reasoning_effort);
+  }
+
+  get modelParameters(): Record<string, unknown> {
+    return {
+      model: this._model,
+      baseUrl: this._baseUrl,
+      ...this._generationKwargs,
+    };
+  }
+
+  async generate(
+    systemPrompt: string,
+    tools: Tool[],
+    history: Message[],
+    options?: GenerateOptions,
+  ): Promise<StreamedMessage> {
+    const messages: OpenAIMessage[] = [];
+    if (systemPrompt) {
+      messages.push({ role: 'system', content: systemPrompt });
+    }
+    for (const msg of history) {
+      messages.push(convertMessage(msg));
+    }
+
+    const kwargs: Record<string, unknown> = {
+      ...this._generationKwargs,
+    };
+
+    // Remove undefined values from kwargs
+    for (const key of Object.keys(kwargs)) {
+      if (kwargs[key] === undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete kwargs[key];
+      }
+    }
+
+    // Normalize the legacy `max_tokens` alias to Kimi's preferred
+    // `max_completion_tokens`. When both are set, `max_completion_tokens`
+    // wins (confirmed against the live Moonshot API). When neither is
+    // set, send no cap — the upstream loop is responsible for clamping
+    // against the current input size and model context window.
+    if (
+      kwargs['max_completion_tokens'] === undefined &&
+      kwargs['max_tokens'] !== undefined
+    ) {
+      kwargs['max_completion_tokens'] = kwargs['max_tokens'];
+    }
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+    delete kwargs['max_tokens'];
+
+    const { extra_body: extraBody, ...requestKwargs } = kwargs;
+
+    const createParams: Record<string, unknown> = {
+      model: this._model,
+      messages,
+      stream: this._stream,
+      ...requestKwargs,
+      ...(extraBody as Record<string, unknown> | undefined),
+    };
+
+    if (tools.length > 0) {
+      createParams['tools'] = tools.map((t) => convertTool(t));
+    }
+
+    if (this._stream) {
+      createParams['stream_options'] = { include_usage: true };
+    }
+
+    try {
+      const client = this._createClient(options?.auth);
+      // Use type assertion via unknown because we pass Moonshot-proprietary fields
+      // (reasoning_effort, thinking) that don't exist in the OpenAI type definitions.
+      const response = (await client.chat.completions.create(
+        createParams as unknown as OpenAI.Chat.ChatCompletionCreateParamsNonStreaming,
+        options?.signal ? { signal: options.signal } : undefined,
+      )) as unknown as OpenAI.Chat.ChatCompletion | AsyncIterable<OpenAI.Chat.ChatCompletionChunk>;
+      return new KimiStreamedMessage(response, this._stream);
+    } catch (error: unknown) {
+      throw convertOpenAIError(error);
+    }
+  }
+
+  getCapability(_model?: string): ModelCapability {
+    return UNKNOWN_CAPABILITY;
+  }
+
+  withThinking(effort: ThinkingEffort): KimiChatProvider {
+    const thinking: ThinkingConfig = {
+      type: effort === 'off' ? 'disabled' : 'enabled',
+    };
+    let reasoningEffort: string | undefined;
+    switch (effort) {
+      case 'off':
+        reasoningEffort = undefined;
+        break;
+      case 'low':
+        reasoningEffort = 'low';
+        break;
+      case 'medium':
+        reasoningEffort = 'medium';
+        break;
+      case 'high':
+      case 'xhigh':
+      case 'max':
+        reasoningEffort = 'high';
+        break;
+    }
+    return this._withGenerationKwargs({ reasoning_effort: reasoningEffort }).withExtraBody({
+      thinking,
+    });
+  }
+
+  withGenerationKwargs(kwargs: GenerationKwargs): KimiChatProvider {
+    return this._withGenerationKwargs(kwargs);
+  }
+
+  withMaxCompletionTokens(maxCompletionTokens: number): KimiChatProvider {
+    return this._withGenerationKwargs({ max_completion_tokens: maxCompletionTokens });
+  }
+
+  withExtraBody(extraBody: ExtraBody): KimiChatProvider {
+    const oldExtra = this._generationKwargs.extra_body ?? {};
+    const merged: ExtraBody = { ...oldExtra, ...extraBody };
+    const oldThinking = oldExtra.thinking;
+    const newThinking = extraBody.thinking;
+    if (oldThinking !== undefined && newThinking !== undefined) {
+      merged.thinking = { ...oldThinking, ...newThinking };
+    }
+    return this._withGenerationKwargs({ extra_body: merged });
+  }
+
+  private _createClient(auth: ProviderRequestAuth | undefined): OpenAI {
+    return resolveAuthBackedClient(
+      { cachedClient: this._client, clientFactory: this._clientFactory },
+      auth,
+      (a) => {
+        const defaultHeaders = mergeRequestHeaders(this._defaultHeaders, a?.headers);
+        return new OpenAI({
+          apiKey: requireProviderApiKey('KimiChatProvider', a, this._apiKey),
+          baseURL: this._baseUrl,
+          defaultHeaders,
+        });
+      },
+    );
+  }
+
+  private _withGenerationKwargs(kwargs: GenerationKwargs): KimiChatProvider {
+    const clone = this._clone();
+    clone._generationKwargs = { ...clone._generationKwargs, ...kwargs };
+    return clone;
+  }
+
+  private _clone(): KimiChatProvider {
+    const clone = Object.assign(
+      Object.create(Object.getPrototypeOf(this) as object) as KimiChatProvider,
+      this,
+    );
+    clone._generationKwargs = { ...this._generationKwargs };
+    // Do not share the memoized KimiFiles instance with the clone; let it be
+    // lazily re-created on first access.
+    clone._files = undefined;
+    // `_client` is intentionally shared with the original instance. Per-step
+    // budget clamping (see KosongLLM.chatOnce) relies on this clone being
+    // cheap. If a future change introduces a retry path that REPLACES
+    // `clone._client` with a freshly built client (and closes the old one),
+    // the original instance's `_client` would become a dangling reference to
+    // a closed socket. Keep `_client` shared and never mutate it after
+    // construction; instead build a new KimiChatProvider when a real new
+    // client is required.
+    return clone;
+  }
+}
diff --git a/packages/kosong/src/providers/openai-common.ts b/packages/kosong/src/providers/openai-common.ts
new file mode 100644
index 000000000..120490c24
--- /dev/null
+++ b/packages/kosong/src/providers/openai-common.ts
@@ -0,0 +1,293 @@
+import {
+  APIConnectionError,
+  APITimeoutError,
+  ChatProviderError,
+  normalizeAPIStatusError,
+} from '#/errors';
+import { extractText } from '#/message';
+import type { ContentPart, Message } from '#/message';
+import type { FinishReason, ThinkingEffort } from '#/provider';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+import {
+  APIConnectionError as OpenAIConnectionError,
+  APIConnectionTimeoutError as OpenAITimeoutError,
+  APIError as OpenAIAPIError,
+  OpenAIError,
+} from 'openai';
+export interface OpenAIContentPart {
+  type: string;
+  text?: string | undefined;
+  image_url?: { url: string; id?: string | null } | undefined;
+  audio_url?: { url: string; id?: string | null } | undefined;
+  video_url?: { url: string; id?: string | null } | undefined;
+}
+
+/**
+ * Convert a kosong `ContentPart` to OpenAI-compatible content part.
+ * Returns `null` for think parts (handled separately as reasoning_content).
+ */
+export function convertContentPart(part: ContentPart): OpenAIContentPart | null {
+  switch (part.type) {
+    case 'text':
+      return { type: 'text', text: part.text };
+    case 'think':
+      // Think parts are handled separately as reasoning_content — skip them here.
+      return null;
+    case 'image_url':
+      return {
+        type: 'image_url',
+        image_url:
+          part.imageUrl.id === undefined
+            ? { url: part.imageUrl.url }
+            : { url: part.imageUrl.url, id: part.imageUrl.id },
+      };
+    case 'audio_url':
+      return {
+        type: 'audio_url',
+        audio_url:
+          part.audioUrl.id === undefined
+            ? { url: part.audioUrl.url }
+            : { url: part.audioUrl.url, id: part.audioUrl.id },
+      };
+    case 'video_url':
+      return {
+        type: 'video_url',
+        video_url:
+          part.videoUrl.id === undefined
+            ? { url: part.videoUrl.url }
+            : { url: part.videoUrl.url, id: part.videoUrl.id },
+      };
+    default:
+      throw new Error(`Unknown content part type: ${(part as ContentPart).type}`);
+  }
+}
+export interface OpenAIToolParam {
+  type: string;
+  function: {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+  };
+}
+
+/**
+ * Convert a kosong `Tool` to OpenAI tool format.
+ */
+export function toolToOpenAI(tool: Tool): OpenAIToolParam {
+  return {
+    type: 'function',
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+    },
+  };
+}
+const NETWORK_RE = /network|connection|connect|disconnect/i;
+const TIMEOUT_RE = /timed?\s*out|timeout|deadline/i;
+
+function classifyBaseApiError(message: string): ChatProviderError {
+  if (TIMEOUT_RE.test(message)) {
+    return new APITimeoutError(message);
+  }
+  if (NETWORK_RE.test(message)) {
+    return new APIConnectionError(message);
+  }
+  return new ChatProviderError(`Error: ${message}`);
+}
+
+/**
+ * Convert an OpenAI SDK error (or raw Error) to a kosong `ChatProviderError`.
+ */
+export function convertOpenAIError(error: unknown): ChatProviderError {
+  if (error instanceof ChatProviderError) {
+    return error;
+  }
+  // v6: APIConnectionTimeoutError extends APIConnectionError, check timeout first
+  if (error instanceof OpenAITimeoutError) {
+    return new APITimeoutError(error.message);
+  }
+  if (error instanceof OpenAIConnectionError) {
+    return new APIConnectionError(error.message);
+  }
+  // APIError with a status code => status error
+  if (error instanceof OpenAIAPIError && typeof error.status === 'number') {
+    const reqId = error.requestID ?? null;
+    return normalizeAPIStatusError(error.status, error.message, reqId);
+  }
+  // Base APIError with no status and no body => transport-layer failure.
+  // When the error has a body (e.g. SSE error events from the server),
+  // skip the heuristic to avoid misclassifying server-side errors.
+  if (
+    error instanceof OpenAIAPIError &&
+    error.constructor === OpenAIAPIError &&
+    error.error === undefined
+  ) {
+    return classifyBaseApiError(error.message);
+  }
+  if (error instanceof OpenAIError) {
+    return new ChatProviderError(`Error: ${error.message}`);
+  }
+  if (error instanceof Error) {
+    return new ChatProviderError(`Error: ${error.message}`);
+  }
+  return new ChatProviderError(`Error: ${String(error)}`);
+}
+/** Shape of a function-type tool call (subset used by the guard). */
+export interface FunctionToolCallShape {
+  type: 'function';
+  id: string;
+  function: { name: string; arguments: string | null };
+}
+
+/**
+ * Type guard: narrow a tool call union to the function-type variant.
+ * Works with OpenAI SDK's `ChatCompletionMessageToolCall` as well as
+ * any object carrying `{ type: string }`.
+ */
+export function isFunctionToolCall<T extends { type: string }>(
+  tc: T,
+): tc is T & FunctionToolCallShape {
+  return tc.type === 'function';
+}
+/**
+ * Map kosong `ThinkingEffort` to OpenAI `reasoning_effort` string.
+ */
+export function thinkingEffortToReasoningEffort(effort: ThinkingEffort): string | undefined {
+  switch (effort) {
+    case 'off':
+      return undefined;
+    case 'low':
+      return 'low';
+    case 'medium':
+      return 'medium';
+    case 'high':
+      return 'high';
+    case 'xhigh':
+    case 'max':
+      return 'xhigh';
+    default:
+      throw new Error(`Unknown thinking effort: ${String(effort)}`);
+  }
+}
+
+/**
+ * Map OpenAI `reasoning_effort` string back to kosong `ThinkingEffort`.
+ */
+export function reasoningEffortToThinkingEffort(
+  reasoning: string | undefined,
+): ThinkingEffort | null {
+  if (reasoning === undefined || reasoning === null) {
+    return null;
+  }
+  switch (reasoning) {
+    case 'low':
+    case 'minimal':
+      return 'low';
+    case 'medium':
+      return 'medium';
+    case 'high':
+      return 'high';
+    case 'xhigh':
+    case 'max':
+      return 'xhigh';
+    case 'none':
+      return 'off';
+    default:
+      return 'off';
+  }
+}
+/**
+ * Extract `TokenUsage` from an OpenAI-compatible usage object.
+ */
+export function extractUsage(usage: unknown): TokenUsage | null {
+  if (usage === null || usage === undefined || typeof usage !== 'object') {
+    return null;
+  }
+  const u = usage as Record<string, unknown>;
+  const promptTokens = typeof u['prompt_tokens'] === 'number' ? u['prompt_tokens'] : 0;
+  const completionTokens = typeof u['completion_tokens'] === 'number' ? u['completion_tokens'] : 0;
+
+  let cached = 0;
+  // Moonshot proprietary: top-level cached_tokens
+  if (typeof u['cached_tokens'] === 'number') {
+    cached = u['cached_tokens'];
+  } else if (
+    typeof u['prompt_tokens_details'] === 'object' &&
+    u['prompt_tokens_details'] !== null
+  ) {
+    const details = u['prompt_tokens_details'] as Record<string, unknown>;
+    if (typeof details['cached_tokens'] === 'number') {
+      cached = details['cached_tokens'];
+    }
+  }
+
+  return {
+    inputOther: promptTokens - cached,
+    output: completionTokens,
+    inputCacheRead: cached,
+    inputCacheCreation: 0,
+  };
+}
+/**
+ * Normalize an OpenAI Chat Completions–style `finish_reason` string to the
+ * unified {@link FinishReason} enum.
+ *
+ * Used by both the Kimi and OpenAI Legacy adapters because they share the
+ * Chat Completions wire format. Returns `{ finishReason: null,
+ * rawFinishReason: null }` when the upstream value is missing or `null` so
+ * callers can treat "no signal" uniformly.
+ *
+ * Mapping:
+ * - `'stop'` → `'completed'`
+ * - `'tool_calls'` → `'tool_calls'`
+ * - `'function_call'` → `'tool_calls'` (legacy alias)
+ * - `'length'` → `'truncated'`
+ * - `'content_filter'` → `'filtered'`
+ * - any other non-null string → `'other'`
+ */
+export function normalizeOpenAIFinishReason(raw: string | null | undefined): {
+  finishReason: FinishReason | null;
+  rawFinishReason: string | null;
+} {
+  if (raw === null || raw === undefined) {
+    return { finishReason: null, rawFinishReason: null };
+  }
+  switch (raw) {
+    case 'stop':
+      return { finishReason: 'completed', rawFinishReason: raw };
+    case 'tool_calls':
+    case 'function_call':
+      return { finishReason: 'tool_calls', rawFinishReason: raw };
+    case 'length':
+      return { finishReason: 'truncated', rawFinishReason: raw };
+    case 'content_filter':
+      return { finishReason: 'filtered', rawFinishReason: raw };
+    default:
+      return { finishReason: 'other', rawFinishReason: raw };
+  }
+}
+/**
+ * Strategy for converting tool-role message content.
+ *
+ * - `'extract_text'`: flatten all content parts into a single text string
+ *   (some providers require tool results as plain text).
+ * - `null`: convert content parts to the standard OpenAI content-part array.
+ */
+export type ToolMessageConversion = 'extract_text' | null;
+
+/**
+ * Convert tool-role message content according to the chosen strategy.
+ */
+export function convertToolMessageContent(
+  message: Message,
+  conversion: ToolMessageConversion,
+): string | OpenAIContentPart[] {
+  if (conversion === 'extract_text') {
+    return extractText(message);
+  }
+  return message.content
+    .map((p) => convertContentPart(p))
+    .filter((p): p is OpenAIContentPart => p !== null);
+}
diff --git a/packages/kosong/src/providers/openai-legacy.ts b/packages/kosong/src/providers/openai-legacy.ts
new file mode 100644
index 000000000..07de4b7f9
--- /dev/null
+++ b/packages/kosong/src/providers/openai-legacy.ts
@@ -0,0 +1,480 @@
+import type { ModelCapability } from '#/capability';
+import type { ContentPart, Message, StreamedMessagePart, ToolCall } from '#/message';
+import type {
+  ChatProvider,
+  FinishReason,
+  GenerateOptions,
+  ProviderRequestAuth,
+  StreamedMessage,
+  ThinkingEffort,
+} from '#/provider';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+import OpenAI from 'openai';
+
+import { getOpenAILegacyModelCapability } from './capability-registry';
+import {
+  convertContentPart,
+  convertOpenAIError,
+  convertToolMessageContent,
+  extractUsage,
+  isFunctionToolCall,
+  normalizeOpenAIFinishReason,
+  type OpenAIContentPart,
+  type ToolMessageConversion,
+  reasoningEffortToThinkingEffort,
+  thinkingEffortToReasoningEffort,
+  toolToOpenAI,
+} from './openai-common';
+import {
+  convertChatCompletionStreamToolCall,
+  type BufferedChatCompletionToolCall,
+} from './chat-completions-stream';
+import {
+  mergeRequestHeaders,
+  requireProviderApiKey,
+  resolveAuthBackedClient,
+} from './request-auth';
+export interface OpenAILegacyOptions {
+  apiKey?: string | undefined;
+  baseUrl?: string | undefined;
+  model: string;
+  stream?: boolean | undefined;
+  maxTokens?: number | undefined;
+  reasoningKey?: string | undefined;
+  httpClient?: unknown;
+  defaultHeaders?: Record<string, string>;
+  toolMessageConversion?: ToolMessageConversion | undefined;
+  clientFactory?: (auth: ProviderRequestAuth) => OpenAI;
+}
+
+export interface OpenAILegacyGenerationKwargs {
+  max_tokens?: number | undefined;
+  temperature?: number | undefined;
+  top_p?: number | undefined;
+  n?: number | undefined;
+  presence_penalty?: number | undefined;
+  frequency_penalty?: number | undefined;
+  stop?: string | string[] | undefined;
+  [key: string]: unknown;
+}
+interface OpenAIMessage {
+  role: string;
+  content?: string | OpenAIContentPart[] | undefined;
+  tool_calls?: OpenAIToolCallOut[] | undefined;
+  tool_call_id?: string | undefined;
+  name?: string | undefined;
+  [key: string]: unknown;
+}
+
+interface OpenAIToolCallOut {
+  type: string;
+  id: string;
+  function: { name: string; arguments: string | null };
+}
+
+function convertMessage(
+  message: Message,
+  reasoningKey: string | undefined,
+  toolMessageConversion: ToolMessageConversion,
+): OpenAIMessage {
+  let reasoningContent = '';
+  const nonThinkParts: ContentPart[] = [];
+
+  for (const part of message.content) {
+    if (part.type === 'think') {
+      reasoningContent += part.think;
+    } else {
+      nonThinkParts.push(part);
+    }
+  }
+
+  // Build the OpenAI message.
+  const result: OpenAIMessage = { role: message.role };
+
+  if (message.role === 'tool') {
+    // OpenAI Chat Completions `tool` messages only accept text content.
+    // Any non-text content parts (image_url, audio_url, video_url) would be
+    // rejected by the API with a 400. Detect multimodal tool output and
+    // force the `extract_text` path in that case, regardless of the caller's
+    // `toolMessageConversion` setting. For pure-text tool results we honor
+    // the configured strategy (or fall through to the default content-part
+    // array when it is unset).
+    const hasNonTextPart = message.content.some((p) => p.type !== 'text' && p.type !== 'think');
+    const effectiveConversion: ToolMessageConversion = hasNonTextPart
+      ? 'extract_text'
+      : toolMessageConversion;
+
+    if (effectiveConversion !== null) {
+      result.content = convertToolMessageContent(message, effectiveConversion);
+    } else {
+      // Pure-text tool result with no conversion configured: serialize via the
+      // generic content-part path so single-text messages become a plain string.
+      const firstPart = nonThinkParts[0];
+      if (nonThinkParts.length === 1 && firstPart?.type === 'text') {
+        result.content = firstPart.text;
+      } else if (nonThinkParts.length > 0) {
+        result.content = nonThinkParts
+          .map((p) => convertContentPart(p))
+          .filter((p): p is OpenAIContentPart => p !== null);
+      }
+    }
+  } else {
+    // content: serialize to string if single text, array otherwise
+    const firstPart = nonThinkParts[0];
+    if (nonThinkParts.length === 1 && firstPart?.type === 'text') {
+      result.content = firstPart.text;
+    } else if (nonThinkParts.length > 0) {
+      result.content = nonThinkParts
+        .map((p) => convertContentPart(p))
+        .filter((p): p is OpenAIContentPart => p !== null);
+    }
+  }
+
+  if (message.name !== undefined) {
+    result.name = message.name;
+  }
+
+  if (message.toolCalls.length > 0) {
+    result.tool_calls = message.toolCalls.map((tc) => ({
+      type: tc.type,
+      id: tc.id,
+      function: { name: tc.function.name, arguments: tc.function.arguments },
+    }));
+  }
+
+  if (message.toolCallId !== undefined) {
+    result.tool_call_id = message.toolCallId;
+  }
+
+  // Place reasoning content under the configured key (e.g. "reasoning_content" for DeepSeek)
+  if (reasoningContent && reasoningKey) {
+    result[reasoningKey] = reasoningContent;
+  }
+
+  return result;
+}
+export class OpenAILegacyStreamedMessage implements StreamedMessage {
+  private _id: string | null = null;
+  private _usage: TokenUsage | null = null;
+  private _finishReason: FinishReason | null = null;
+  private _rawFinishReason: string | null = null;
+  private readonly _iter: AsyncGenerator<StreamedMessagePart>;
+
+  constructor(
+    response: OpenAI.Chat.ChatCompletion | AsyncIterable<OpenAI.Chat.ChatCompletionChunk>,
+    isStream: boolean,
+    reasoningKey: string | undefined,
+  ) {
+    if (isStream) {
+      this._iter = this._convertStreamResponse(
+        response as AsyncIterable<OpenAI.Chat.ChatCompletionChunk>,
+        reasoningKey,
+      );
+    } else {
+      this._iter = this._convertNonStreamResponse(
+        response as OpenAI.Chat.ChatCompletion,
+        reasoningKey,
+      );
+    }
+  }
+
+  get id(): string | null {
+    return this._id;
+  }
+
+  get usage(): TokenUsage | null {
+    return this._usage;
+  }
+
+  get finishReason(): FinishReason | null {
+    return this._finishReason;
+  }
+
+  get rawFinishReason(): string | null {
+    return this._rawFinishReason;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+    yield* this._iter;
+  }
+
+  private _captureFinishReason(raw: string | null | undefined): void {
+    const normalized = normalizeOpenAIFinishReason(raw);
+    this._finishReason = normalized.finishReason;
+    this._rawFinishReason = normalized.rawFinishReason;
+  }
+
+  private async *_convertNonStreamResponse(
+    response: OpenAI.Chat.ChatCompletion,
+    reasoningKey: string | undefined,
+  ): AsyncGenerator<StreamedMessagePart> {
+    this._id = response.id;
+    if (response.usage) {
+      this._usage = extractUsage(response.usage) ?? null;
+    }
+    this._captureFinishReason(response.choices[0]?.finish_reason ?? null);
+
+    const message = response.choices[0]?.message;
+    if (!message) return;
+
+    // Reasoning content via configured key
+    if (reasoningKey) {
+      const rc = (message as unknown as Record<string, unknown>)[reasoningKey];
+      if (typeof rc === 'string' && rc) {
+        yield { type: 'think', think: rc } satisfies StreamedMessagePart;
+      }
+    }
+
+    if (message.content) {
+      yield { type: 'text', text: message.content } satisfies StreamedMessagePart;
+    }
+
+    if (message.tool_calls) {
+      for (const toolCall of message.tool_calls) {
+        if (!isFunctionToolCall(toolCall)) continue;
+        yield {
+          type: 'function',
+          id: toolCall.id || crypto.randomUUID(),
+          function: {
+            name: toolCall.function.name,
+            arguments: toolCall.function.arguments,
+          },
+        } satisfies ToolCall;
+      }
+    }
+  }
+
+  private async *_convertStreamResponse(
+    response: AsyncIterable<OpenAI.Chat.ChatCompletionChunk>,
+    reasoningKey: string | undefined,
+  ): AsyncGenerator<StreamedMessagePart> {
+    const bufferedToolCalls = new Map<number | string, BufferedChatCompletionToolCall>();
+
+    try {
+      for await (const chunk of response) {
+        if (chunk.id) {
+          this._id = chunk.id;
+        }
+
+        if (chunk.usage) {
+          this._usage = extractUsage(chunk.usage) ?? null;
+        }
+
+        if (!chunk.choices || chunk.choices.length === 0) {
+          continue;
+        }
+
+        const choice = chunk.choices[0];
+        if (!choice) continue;
+
+        // Capture finish_reason whenever the chunk carries one. Chat
+        // Completions only sets it on the final chunk for a given choice.
+        if (choice.finish_reason !== null && choice.finish_reason !== undefined) {
+          this._captureFinishReason(choice.finish_reason);
+        }
+
+        const delta = choice.delta;
+
+        // Reasoning content via configured key
+        if (reasoningKey) {
+          const rc = (delta as unknown as Record<string, unknown>)[reasoningKey];
+          if (typeof rc === 'string' && rc) {
+            yield { type: 'think', think: rc } satisfies StreamedMessagePart;
+          }
+        }
+
+        // text content
+        if (delta.content) {
+          yield { type: 'text', text: delta.content } satisfies StreamedMessagePart;
+        }
+
+        // tool calls — preserve `index` on every yielded part so the generate
+        // loop can route interleaved argument deltas from parallel tool calls.
+        for (const toolCall of delta.tool_calls ?? []) {
+          for (const part of convertChatCompletionStreamToolCall(toolCall, bufferedToolCalls)) {
+            yield part;
+          }
+        }
+      }
+    } catch (error: unknown) {
+      throw convertOpenAIError(error);
+    }
+  }
+}
+export class OpenAILegacyChatProvider implements ChatProvider {
+  readonly name: string = 'openai';
+
+  private _model: string;
+  private _stream: boolean;
+  private _apiKey: string | undefined;
+  private _baseUrl: string | undefined;
+  private _defaultHeaders: Record<string, string> | undefined;
+  private _reasoningKey: string | undefined;
+  private _reasoningEffort: string | undefined;
+  private _generationKwargs: OpenAILegacyGenerationKwargs;
+  private _toolMessageConversion: ToolMessageConversion;
+  private _client: OpenAI | undefined;
+  private _httpClient: unknown;
+  private _clientFactory: ((auth: ProviderRequestAuth) => OpenAI) | undefined;
+
+  constructor(options: OpenAILegacyOptions) {
+    const apiKey = options.apiKey ?? process.env['OPENAI_API_KEY'];
+    this._apiKey = apiKey === undefined || apiKey.length === 0 ? undefined : apiKey;
+    this._baseUrl = options.baseUrl ?? 'https://api.openai.com/v1';
+    this._defaultHeaders = options.defaultHeaders;
+    this._model = options.model;
+    this._stream = options.stream ?? true;
+    this._reasoningKey = options.reasoningKey;
+    this._reasoningEffort = undefined;
+    this._generationKwargs = {};
+    if (options.maxTokens !== undefined) {
+      this._generationKwargs.max_tokens = options.maxTokens;
+    }
+    this._toolMessageConversion = options.toolMessageConversion ?? null;
+    this._httpClient = options.httpClient;
+    this._clientFactory = options.clientFactory;
+
+    this._client = this._apiKey === undefined ? undefined : this._buildClient(this._apiKey);
+  }
+
+  get modelName(): string {
+    return this._model;
+  }
+
+  get thinkingEffort(): ThinkingEffort | null {
+    return reasoningEffortToThinkingEffort(this._reasoningEffort);
+  }
+
+  get modelParameters(): Record<string, unknown> {
+    return {
+      model: this._model,
+      baseUrl: this._baseUrl,
+      ...this._generationKwargs,
+    };
+  }
+
+  getCapability(model?: string): ModelCapability {
+    return getOpenAILegacyModelCapability(model ?? this._model);
+  }
+
+  async generate(
+    systemPrompt: string,
+    tools: Tool[],
+    history: Message[],
+    options?: GenerateOptions,
+  ): Promise<StreamedMessage> {
+    const messages: OpenAIMessage[] = [];
+    if (systemPrompt) {
+      messages.push({ role: 'system', content: systemPrompt });
+    }
+    for (const msg of history) {
+      messages.push(convertMessage(msg, this._reasoningKey, this._toolMessageConversion));
+    }
+
+    const kwargs: Record<string, unknown> = {
+      ...this._generationKwargs,
+    };
+
+    // Determine reasoning_effort
+    let reasoningEffort: string | undefined = this._reasoningEffort;
+
+    // Auto-enable reasoning_effort when the history contains ThinkPart but reasoning
+    // was not explicitly configured. This prevents server validation errors from APIs
+    // (e.g. One API) that require reasoning_effort when messages contain reasoning_content.
+    // See: https://github.com/MoonshotAI/kimi-code/issues/1616
+    if (reasoningEffort === undefined && this._reasoningKey) {
+      const hasThinkPart = history.some((message) =>
+        message.content.some((part) => part.type === 'think'),
+      );
+      if (hasThinkPart) {
+        reasoningEffort = 'medium';
+      }
+    }
+
+    // Remove undefined values from kwargs
+    for (const key of Object.keys(kwargs)) {
+      if (kwargs[key] === undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete kwargs[key];
+      }
+    }
+
+    // Build the create params
+    const createParams: Record<string, unknown> = {
+      model: this._model,
+      messages,
+      stream: this._stream,
+      ...kwargs,
+    };
+
+    if (tools.length > 0) {
+      createParams['tools'] = tools.map((t) => toolToOpenAI(t));
+    }
+
+    if (this._stream) {
+      createParams['stream_options'] = { include_usage: true };
+    }
+
+    if (reasoningEffort !== undefined) {
+      createParams['reasoning_effort'] = reasoningEffort;
+    }
+
+    try {
+      const client = this._createClient(options?.auth);
+      const response = (await client.chat.completions.create(
+        createParams as unknown as OpenAI.Chat.ChatCompletionCreateParamsNonStreaming,
+        options?.signal ? { signal: options.signal } : undefined,
+      )) as unknown as OpenAI.Chat.ChatCompletion | AsyncIterable<OpenAI.Chat.ChatCompletionChunk>;
+      return new OpenAILegacyStreamedMessage(response, this._stream, this._reasoningKey);
+    } catch (error: unknown) {
+      throw convertOpenAIError(error);
+    }
+  }
+
+  withThinking(effort: ThinkingEffort): OpenAILegacyChatProvider {
+    const reasoningEffort = thinkingEffortToReasoningEffort(effort);
+    const clone = this._clone();
+    clone._reasoningEffort = reasoningEffort;
+    return clone;
+  }
+
+  withGenerationKwargs(kwargs: OpenAILegacyGenerationKwargs): OpenAILegacyChatProvider {
+    const clone = this._clone();
+    clone._generationKwargs = { ...clone._generationKwargs, ...kwargs };
+    return clone;
+  }
+
+  private _clone(): OpenAILegacyChatProvider {
+    const clone = Object.assign(
+      Object.create(Object.getPrototypeOf(this) as object) as OpenAILegacyChatProvider,
+      this,
+    );
+    clone._generationKwargs = { ...this._generationKwargs };
+    return clone;
+  }
+
+  private _createClient(auth: ProviderRequestAuth | undefined): OpenAI {
+    return resolveAuthBackedClient(
+      { cachedClient: this._client, clientFactory: this._clientFactory },
+      auth,
+      (a) =>
+        this._buildClient(requireProviderApiKey('OpenAILegacyChatProvider', a, this._apiKey), a),
+    );
+  }
+
+  private _buildClient(apiKey: string, auth?: ProviderRequestAuth): OpenAI {
+    const clientOpts: Record<string, unknown> = {
+      apiKey,
+      baseURL: this._baseUrl,
+    };
+    const defaultHeaders = mergeRequestHeaders(this._defaultHeaders, auth?.headers);
+    if (defaultHeaders !== undefined) {
+      clientOpts['defaultHeaders'] = defaultHeaders;
+    }
+    if (this._httpClient !== undefined) {
+      clientOpts['httpClient'] = this._httpClient;
+    }
+    return new OpenAI(clientOpts as ConstructorParameters<typeof OpenAI>[0]);
+  }
+}
diff --git a/packages/kosong/src/providers/openai-responses.ts b/packages/kosong/src/providers/openai-responses.ts
new file mode 100644
index 000000000..1802a2f89
--- /dev/null
+++ b/packages/kosong/src/providers/openai-responses.ts
@@ -0,0 +1,979 @@
+import type { ModelCapability } from '#/capability';
+import { ChatProviderError } from '#/errors';
+import type { ContentPart, Message, StreamedMessagePart, ToolCall } from '#/message';
+import { extractText } from '#/message';
+import type {
+  ChatProvider,
+  FinishReason,
+  GenerateOptions,
+  ProviderRequestAuth,
+  StreamedMessage,
+  ThinkingEffort,
+} from '#/provider';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+import OpenAI from 'openai';
+
+import {
+  getOpenAIResponsesModelCapability,
+  usesOpenAIResponsesDeveloperRole,
+} from './capability-registry';
+import {
+  convertOpenAIError,
+  type ToolMessageConversion,
+  reasoningEffortToThinkingEffort,
+  thinkingEffortToReasoningEffort,
+} from './openai-common';
+import {
+  mergeRequestHeaders,
+  requireProviderApiKey,
+  resolveAuthBackedClient,
+} from './request-auth';
+
+/**
+ * Normalize the Responses API status / incomplete_details into the unified
+ * {@link FinishReason} enum.
+ *
+ * Note: the Responses API has no `tool_calls`-style status. When a response
+ * completes with `function_call` items inline the status is still
+ * `'completed'`; callers detect tool calls via `message.toolCalls.length`,
+ * not via finishReason.
+ */
+function normalizeResponsesFinishReason(
+  status: string | null | undefined,
+  incompleteReason: string | null | undefined,
+): { finishReason: FinishReason | null; rawFinishReason: string | null } {
+  if (status === null || status === undefined) {
+    return { finishReason: null, rawFinishReason: null };
+  }
+  if (status === 'completed') {
+    return { finishReason: 'completed', rawFinishReason: 'completed' };
+  }
+  if (status === 'incomplete') {
+    if (incompleteReason === 'max_output_tokens') {
+      return { finishReason: 'truncated', rawFinishReason: 'max_output_tokens' };
+    }
+    if (incompleteReason === 'content_filter') {
+      return { finishReason: 'filtered', rawFinishReason: 'content_filter' };
+    }
+    return {
+      finishReason: 'other',
+      rawFinishReason: incompleteReason ?? 'incomplete',
+    };
+  }
+  if (status === 'failed') {
+    return { finishReason: 'other', rawFinishReason: 'failed' };
+  }
+  return { finishReason: null, rawFinishReason: null };
+}
+
+type RawObject = Record<string, unknown>;
+
+type ResponseOutputItemView =
+  | {
+      type: 'message';
+      content: RawObject[];
+    }
+  | {
+      type: 'function_call';
+      itemId?: string;
+      callId?: string;
+      name?: string;
+      arguments?: string | null;
+    }
+  | {
+      type: 'reasoning';
+      encryptedContent?: string;
+      summary: RawObject[];
+    }
+  | {
+      type: 'other';
+    };
+
+function asRawObject(value: unknown): RawObject | null {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  return value as RawObject;
+}
+
+function readStringField(object: RawObject, key: string): string | undefined {
+  const value = object[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+function readNullableStringField(object: RawObject, key: string): string | null | undefined {
+  const value = object[key];
+  if (value === null) return null;
+  return typeof value === 'string' ? value : undefined;
+}
+
+function readNumberField(object: RawObject, key: string): number | undefined {
+  const value = object[key];
+  return typeof value === 'number' ? value : undefined;
+}
+
+function readObjectField(object: RawObject, key: string): RawObject | undefined {
+  return asRawObject(object[key]) ?? undefined;
+}
+
+function readObjectArrayField(object: RawObject, key: string): RawObject[] | undefined {
+  const value = object[key];
+  if (!Array.isArray(value)) return undefined;
+  return value.flatMap((item) => {
+    const objectItem = asRawObject(item);
+    return objectItem === null ? [] : [objectItem];
+  });
+}
+
+function failResponsesDecode(context: string, detail: string): never {
+  throw new ChatProviderError(`OpenAI Responses decode error: ${context} ${detail}`);
+}
+
+function requireStringField(object: RawObject, key: string, context: string): string {
+  const value = readStringField(object, key);
+  if (value === undefined) {
+    failResponsesDecode(`${context}.${key}`, 'must be a string.');
+  }
+  return value;
+}
+
+function requireObjectField(object: RawObject, key: string, context: string): RawObject {
+  const value = readObjectField(object, key);
+  if (value === undefined) {
+    failResponsesDecode(`${context}.${key}`, 'must be an object.');
+  }
+  return value;
+}
+
+function readResponseOutputItem(
+  value: unknown,
+  context: string,
+): ResponseOutputItemView {
+  const item = asRawObject(value);
+  if (item === null) {
+    failResponsesDecode(context, 'must be an object.');
+  }
+
+  const type = requireStringField(item, 'type', context);
+
+  if (type === 'message') {
+    return {
+      type,
+      content: readObjectArrayField(item, 'content') ?? [],
+    };
+  }
+
+  if (type === 'function_call') {
+    return {
+      type,
+      itemId: readStringField(item, 'id'),
+      callId: readStringField(item, 'call_id'),
+      name: readStringField(item, 'name'),
+      arguments: readNullableStringField(item, 'arguments'),
+    };
+  }
+
+  if (type === 'reasoning') {
+    return {
+      type,
+      encryptedContent: readStringField(item, 'encrypted_content'),
+      summary: readObjectArrayField(item, 'summary') ?? [],
+    };
+  }
+
+  return { type: 'other' };
+}
+
+function responseStreamIndex(
+  itemId: string | undefined,
+  outputIndex: number | undefined,
+): string | number | undefined {
+  return itemId ?? outputIndex;
+}
+
+function formatResponseStreamIndex(streamIndex: string | number | undefined): string {
+  return streamIndex === undefined ? '<unindexed>' : String(streamIndex);
+}
+
+function requireFunctionCallName(item: { name?: string }): string {
+  if (item.name === undefined) {
+    throw new ChatProviderError('OpenAI Responses function_call item is missing a name.');
+  }
+  return item.name;
+}
+
+function functionCallId(callId: string | undefined): string {
+  return callId === undefined || callId.length === 0 ? crypto.randomUUID() : callId;
+}
+
+function formatResponsesErrorEvent(
+  code: string | null,
+  message: string,
+  param: string | null,
+): string {
+  const codeText = code ?? 'unknown';
+  const paramText = param === null ? '' : ` (param: ${param})`;
+  return `${codeText}: ${message}${paramText}`;
+}
+
+function formatResponsesFailedResponse(response: RawObject): string {
+  const error = readObjectField(response, 'error');
+  if (error !== undefined) {
+    const code = readNullableStringField(error, 'code') ?? 'unknown';
+    const message = readStringField(error, 'message') ?? 'no message';
+    return `${code}: ${message}`;
+  }
+
+  const incompleteDetails = readObjectField(response, 'incomplete_details');
+  const reason =
+    incompleteDetails === undefined ? undefined : readStringField(incompleteDetails, 'reason');
+  return reason === undefined
+    ? 'Unknown error (no error details in response)'
+    : `incomplete: ${reason}`;
+}
+
+export interface OpenAIResponsesOptions {
+  apiKey?: string | undefined;
+  baseUrl?: string | undefined;
+  model: string;
+  maxOutputTokens?: number | undefined;
+  httpClient?: unknown;
+  defaultHeaders?: Record<string, string>;
+  toolMessageConversion?: ToolMessageConversion | undefined;
+  clientFactory?: (auth: ProviderRequestAuth) => OpenAI;
+}
+
+export interface OpenAIResponsesGenerationKwargs {
+  max_output_tokens?: number | undefined;
+  temperature?: number | undefined;
+  top_p?: number | undefined;
+  reasoning_effort?: string | undefined;
+  [key: string]: unknown;
+}
+interface ResponseInputItem {
+  [key: string]: unknown;
+}
+
+interface ResponseToolParam {
+  type: string;
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  strict: boolean;
+}
+function contentPartsToInputItems(parts: ContentPart[]): unknown[] {
+  const items: unknown[] = [];
+  for (const part of parts) {
+    switch (part.type) {
+      case 'text':
+        if (part.text) {
+          items.push({ type: 'input_text', text: part.text });
+        }
+        break;
+      case 'image_url':
+        items.push({
+          type: 'input_image',
+          detail: 'auto',
+          image_url: part.imageUrl.url,
+        });
+        break;
+      case 'audio_url': {
+        const mapped = mapAudioUrlToInputItem(part.audioUrl.url);
+        if (mapped !== null) {
+          items.push(mapped);
+        }
+        break;
+      }
+      case 'think':
+      case 'video_url':
+        // think: handled separately. video_url: not supported by Responses API.
+        break;
+    }
+  }
+  return items;
+}
+
+function contentPartsToOutputItems(parts: ContentPart[]): unknown[] {
+  const items: unknown[] = [];
+  for (const part of parts) {
+    if (part.type === 'text' && part.text) {
+      items.push({ type: 'output_text', text: part.text, annotations: [] });
+    }
+  }
+  return items;
+}
+
+function messageContentToFunctionOutputItems(content: ContentPart[]): string | unknown[] {
+  const items: unknown[] = [];
+  for (const part of content) {
+    switch (part.type) {
+      case 'text':
+        if (part.text) {
+          items.push({ type: 'input_text', text: part.text });
+        }
+        break;
+      case 'image_url':
+        items.push({ type: 'input_image', image_url: part.imageUrl.url });
+        break;
+      case 'audio_url': {
+        // Tool results can legitimately include audio (e.g. a TTS tool
+        // returning generated speech). The user-message path already
+        // encodes audio via `mapAudioUrlToInputItem`; without the same
+        // branch here, audio returned by a tool would be dropped on the
+        // next turn.
+        const mapped = mapAudioUrlToInputItem(part.audioUrl.url);
+        if (mapped !== null) {
+          items.push(mapped);
+        }
+        break;
+      }
+      case 'think':
+      case 'video_url':
+        // think / video_url still intentionally skipped: the Responses
+        // API has no representation for them inside a function_call_output.
+        break;
+    }
+  }
+  return items;
+}
+
+function mapAudioUrlToInputItem(url: string): unknown {
+  if (url.startsWith('data:audio/')) {
+    try {
+      const parts = url.split(',', 2);
+      if (parts.length !== 2 || parts[0] === undefined || parts[1] === undefined) return null;
+      const header = parts[0];
+      const b64 = parts[1];
+      const subtypePart = header.split('/')[1];
+      if (subtypePart === undefined) return null;
+      const [subtypeHead = ''] = subtypePart.split(';');
+      const subtype = subtypeHead.toLowerCase();
+      const ext =
+        subtype === 'mp3' || subtype === 'mpeg' ? 'mp3' : subtype === 'wav' ? 'wav' : null;
+      if (ext === null) return null;
+      return { type: 'input_file', file_data: b64, filename: `inline.${ext}` };
+    } catch {
+      return null;
+    }
+  }
+  if (url.startsWith('http://') || url.startsWith('https://')) {
+    return { type: 'input_file', file_url: url };
+  }
+  return null;
+}
+
+function convertMessage(
+  message: Message,
+  modelName: string,
+  toolMessageConversion: ToolMessageConversion,
+): ResponseInputItem[] {
+  let role: string = message.role;
+  if (usesOpenAIResponsesDeveloperRole(modelName) && role === 'system') {
+    role = 'developer';
+  }
+
+  // tool role -> function_call_output
+  if (role === 'tool') {
+    const callId = message.toolCallId ?? '';
+    const output: string | unknown[] =
+      toolMessageConversion === 'extract_text'
+        ? extractText(message)
+        : messageContentToFunctionOutputItems(message.content);
+    return [
+      {
+        call_id: callId,
+        output,
+        type: 'function_call_output',
+      },
+    ];
+  }
+
+  const result: ResponseInputItem[] = [];
+
+  // Process content parts
+  if (message.content.length > 0) {
+    const pendingParts: ContentPart[] = [];
+
+    const flushPendingParts = (): void => {
+      if (pendingParts.length === 0) return;
+      if (role === 'assistant') {
+        result.push({
+          content: contentPartsToOutputItems(pendingParts),
+          role,
+          type: 'message',
+        });
+      } else {
+        result.push({
+          content: contentPartsToInputItems(pendingParts),
+          role,
+          type: 'message',
+        });
+      }
+      pendingParts.length = 0;
+    };
+
+    let i = 0;
+    const n = message.content.length;
+    while (i < n) {
+      const part = message.content[i];
+      if (part === undefined) break;
+      if (part.type === 'think') {
+        // Flush accumulated non-reasoning parts first
+        flushPendingParts();
+        // Aggregate consecutive ThinkParts with the same `encrypted` value
+        const encryptedValue = part.encrypted;
+        const summaries: unknown[] = [{ type: 'summary_text', text: part.think || '' }];
+        i += 1;
+        while (i < n) {
+          const nextPart = message.content[i];
+          if (nextPart === undefined) break;
+          if (nextPart.type !== 'think') break;
+          if (nextPart.encrypted !== encryptedValue) break;
+          summaries.push({ type: 'summary_text', text: nextPart.think || '' });
+          i += 1;
+        }
+        result.push({
+          summary: summaries,
+          type: 'reasoning',
+          encrypted_content: encryptedValue,
+        });
+      } else {
+        pendingParts.push(part);
+        i += 1;
+      }
+    }
+
+    // Handle remaining trailing non-reasoning parts
+    flushPendingParts();
+  }
+
+  // Handle tool calls
+  for (const toolCall of message.toolCalls) {
+    result.push({
+      arguments: toolCall.function.arguments ?? '{}',
+      call_id: toolCall.id,
+      name: toolCall.function.name,
+      type: 'function_call',
+    });
+  }
+
+  return result;
+}
+
+function convertTool(tool: Tool): ResponseToolParam {
+  return {
+    type: 'function',
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters,
+    strict: false,
+  };
+}
+export class OpenAIResponsesStreamedMessage implements StreamedMessage {
+  private _id: string | null = null;
+  private _usage: TokenUsage | null = null;
+  private _finishReason: FinishReason | null = null;
+  private _rawFinishReason: string | null = null;
+  private readonly _iter: AsyncGenerator<StreamedMessagePart>;
+
+  constructor(response: unknown, isStream: boolean) {
+    if (isStream) {
+      this._iter = this._convertStreamResponse(response as AsyncIterable<RawObject>);
+    } else {
+      this._iter = this._convertNonStreamResponse(response as RawObject);
+    }
+  }
+
+  get id(): string | null {
+    return this._id;
+  }
+
+  get usage(): TokenUsage | null {
+    return this._usage;
+  }
+
+  get finishReason(): FinishReason | null {
+    return this._finishReason;
+  }
+
+  get rawFinishReason(): string | null {
+    return this._rawFinishReason;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+    yield* this._iter;
+  }
+
+  private _captureFinishReasonFromResponse(response: RawObject): void {
+    const status = readNullableStringField(response, 'status');
+    const incomplete = readObjectField(response, 'incomplete_details');
+    const incompleteReason = incomplete ? readStringField(incomplete, 'reason') : null;
+    const normalized = normalizeResponsesFinishReason(status, incompleteReason);
+    this._finishReason = normalized.finishReason;
+    this._rawFinishReason = normalized.rawFinishReason;
+  }
+
+  private _extractUsage(usage: RawObject): void {
+    const inputTokens = readNumberField(usage, 'input_tokens') ?? 0;
+    const outputTokens = readNumberField(usage, 'output_tokens') ?? 0;
+    const details = readObjectField(usage, 'input_tokens_details');
+    const cached = details ? (readNumberField(details, 'cached_tokens') ?? 0) : 0;
+    this._usage = {
+      inputOther: inputTokens - cached,
+      output: outputTokens,
+      inputCacheRead: cached,
+      inputCacheCreation: 0,
+    };
+  }
+
+  private async *_convertNonStreamResponse(
+    response: RawObject,
+  ): AsyncGenerator<StreamedMessagePart> {
+    this._id = readStringField(response, 'id') ?? null;
+    const usage = readObjectField(response, 'usage');
+    if (usage !== undefined) {
+      this._extractUsage(usage);
+    }
+    this._captureFinishReasonFromResponse(response);
+
+    const output = readObjectArrayField(response, 'output');
+    if (output === undefined) return;
+
+    for (const item of output) {
+      const outputItem = readResponseOutputItem(item, 'response.output item');
+
+      if (outputItem.type === 'message') {
+        for (const contentItem of outputItem.content) {
+          if (contentItem['type'] === 'output_text') {
+            const text = readStringField(contentItem, 'text');
+            if (text !== undefined) {
+              yield { type: 'text', text };
+            }
+          }
+        }
+      } else if (outputItem.type === 'function_call') {
+        yield {
+          type: 'function',
+          id: functionCallId(outputItem.callId),
+          function: {
+            name: requireFunctionCallName(outputItem),
+            arguments: outputItem.arguments ?? null,
+          },
+        } satisfies ToolCall;
+      } else if (outputItem.type === 'reasoning') {
+        for (const summary of outputItem.summary) {
+          const text = readStringField(summary, 'text');
+          if (text === undefined) continue;
+          const thinkPart: StreamedMessagePart = {
+            type: 'think',
+            think: text,
+          };
+          if (outputItem.encryptedContent !== undefined) {
+            (thinkPart as { encrypted: string }).encrypted = outputItem.encryptedContent;
+          }
+          yield thinkPart;
+        }
+      }
+    }
+  }
+
+  private async *_convertStreamResponse(
+    response: AsyncIterable<RawObject>,
+  ): AsyncGenerator<StreamedMessagePart> {
+    const functionCallArgumentsByIndex = new Map<number | string, string>();
+    let unindexedFunctionCallArguments: string | undefined;
+
+    const hasFunctionCallArguments = (streamIndex: number | string | undefined): boolean =>
+      streamIndex === undefined
+        ? unindexedFunctionCallArguments !== undefined
+        : functionCallArgumentsByIndex.has(streamIndex);
+
+    const getFunctionCallArguments = (streamIndex: number | string | undefined): string =>
+      streamIndex === undefined
+        ? (unindexedFunctionCallArguments as string)
+        : functionCallArgumentsByIndex.get(streamIndex)!;
+
+    const setFunctionCallArguments = (
+      streamIndex: number | string | undefined,
+      argumentsValue: string,
+    ): void => {
+      if (streamIndex === undefined) {
+        unindexedFunctionCallArguments = argumentsValue;
+      } else {
+        functionCallArgumentsByIndex.set(streamIndex, argumentsValue);
+      }
+    };
+
+    const appendFunctionCallArguments = (
+      streamIndex: number | string | undefined,
+      argumentsPart: string,
+      context: string,
+    ): void => {
+      if (!hasFunctionCallArguments(streamIndex)) {
+        failResponsesDecode(
+          context,
+          `received function-call arguments for unknown stream index ${formatResponseStreamIndex(streamIndex)}.`,
+        );
+      }
+      setFunctionCallArguments(
+        streamIndex,
+        getFunctionCallArguments(streamIndex) + argumentsPart,
+      );
+    };
+
+    const yieldFinalArgumentsSuffix = function* (
+      streamIndex: number | string | undefined,
+      finalArguments: string,
+      context: string,
+    ): Generator<StreamedMessagePart> {
+      if (!hasFunctionCallArguments(streamIndex)) {
+        failResponsesDecode(
+          context,
+          `received final function-call arguments for unknown stream index ${formatResponseStreamIndex(streamIndex)}.`,
+        );
+      }
+
+      const accumulatedArguments = getFunctionCallArguments(streamIndex);
+      if (finalArguments === accumulatedArguments) {
+        return;
+      }
+
+      if (!finalArguments.startsWith(accumulatedArguments)) {
+        throw new ChatProviderError(
+          `OpenAI Responses final function-call arguments for stream index ${formatResponseStreamIndex(
+            streamIndex,
+          )} do not match the streamed argument deltas.`,
+        );
+      }
+
+      const suffix = finalArguments.slice(accumulatedArguments.length);
+      setFunctionCallArguments(streamIndex, finalArguments);
+      if (suffix.length === 0) {
+        return;
+      }
+
+      const part: StreamedMessagePart = {
+        type: 'tool_call_part',
+        argumentsPart: suffix,
+      };
+      if (streamIndex !== undefined) {
+        (part as { index: number | string }).index = streamIndex;
+      }
+      yield part;
+    };
+
+    try {
+      for await (const chunk of response) {
+        const type = requireStringField(chunk, 'type', 'stream event');
+
+        switch (type) {
+          case 'response.output_text.delta':
+            yield { type: 'text', text: requireStringField(chunk, 'delta', type) };
+            break;
+          case 'response.created':
+          case 'response.in_progress': {
+            const responseObject = requireObjectField(chunk, 'response', type);
+            // Initial events carry the Responses API `response.id`. Record it
+            // here so callers that inspect `stream.id` before the stream
+            // completes see the actual response id rather than a later
+            // output-item identifier.
+            const respId = readStringField(responseObject, 'id');
+            if (respId !== undefined) {
+              this._id = respId;
+            }
+            break;
+          }
+          case 'response.output_item.added': {
+            const item = readResponseOutputItem(chunk['item'], `${type}.item`);
+            const outputIndex = readNumberField(chunk, 'output_index');
+            // NOTE: `item.id` here is an output-item identifier, not the
+            // Responses API `response.id`. Do NOT overwrite `this._id` — it
+            // would clobber the real response id (or leave it undefined for
+            // tool-call items that have no `item.id`).
+            if (item.type === 'function_call') {
+              // The Responses API routes streaming argument deltas via
+              // `item_id`, which matches `item.id` on output_item.added.
+              // Preserve it so the generate loop can dispatch interleaved
+              // deltas across parallel function calls correctly.
+              const streamIndex = responseStreamIndex(item.itemId, outputIndex);
+              setFunctionCallArguments(streamIndex, item.arguments ?? '');
+              const tc: ToolCall = {
+                type: 'function',
+                id: functionCallId(item.callId),
+                function: {
+                  name: requireFunctionCallName(item),
+                  arguments: item.arguments ?? null,
+                },
+              };
+              if (streamIndex !== undefined) {
+                tc._streamIndex = streamIndex;
+              }
+              yield tc;
+            }
+            break;
+          }
+          case 'response.output_item.done': {
+            const item = readResponseOutputItem(chunk['item'], `${type}.item`);
+            const outputIndex = readNumberField(chunk, 'output_index');
+            // Same as output_item.added: `item.id` is not the response id.
+            if (item.type === 'reasoning') {
+              const thinkPart: StreamedMessagePart = { type: 'think', think: '' };
+              if (item.encryptedContent !== undefined) {
+                (thinkPart as { encrypted: string }).encrypted = item.encryptedContent;
+              }
+              yield thinkPart;
+            } else if (item.type === 'function_call' && typeof item.arguments === 'string') {
+              const streamIndex = responseStreamIndex(item.itemId, outputIndex);
+              yield* yieldFinalArgumentsSuffix(streamIndex, item.arguments, type);
+            }
+            break;
+          }
+          case 'response.function_call_arguments.delta': {
+            // `item_id` uniquely identifies the function_call output item this
+            // delta belongs to; use it as the streaming index.
+            const streamIndex = responseStreamIndex(
+              readStringField(chunk, 'item_id'),
+              readNumberField(chunk, 'output_index'),
+            );
+            const argumentsPart = requireStringField(chunk, 'delta', type);
+            const part: StreamedMessagePart = {
+              type: 'tool_call_part',
+              argumentsPart,
+            };
+            appendFunctionCallArguments(streamIndex, argumentsPart, type);
+            if (streamIndex !== undefined) {
+              (part as { index: number | string }).index = streamIndex;
+            }
+            yield part;
+            break;
+          }
+          case 'response.function_call_arguments.done': {
+            const functionArguments = requireStringField(chunk, 'arguments', type);
+            const streamIndex = responseStreamIndex(
+              readStringField(chunk, 'item_id'),
+              readNumberField(chunk, 'output_index'),
+            );
+            yield* yieldFinalArgumentsSuffix(streamIndex, functionArguments, type);
+            break;
+          }
+          case 'response.reasoning_summary_part.added':
+            yield { type: 'think', think: '' };
+            break;
+          case 'response.reasoning_summary_text.delta':
+            yield { type: 'think', think: requireStringField(chunk, 'delta', type) };
+            break;
+          case 'response.completed':
+          case 'response.incomplete': {
+            const responseObject = requireObjectField(chunk, 'response', type);
+            // Final event confirms the Responses API `response.id`. Prefer
+            // it over any earlier value in case the API refines it.
+            const respId = readStringField(responseObject, 'id');
+            if (respId !== undefined) {
+              this._id = respId;
+            }
+            const usage = readObjectField(responseObject, 'usage');
+            if (usage !== undefined) {
+              this._extractUsage(usage);
+            }
+            this._captureFinishReasonFromResponse(responseObject);
+            break;
+          }
+          case 'error': {
+            const message = requireStringField(chunk, 'message', type);
+            throw new ChatProviderError(
+              `OpenAI Responses stream error: ${formatResponsesErrorEvent(
+                readNullableStringField(chunk, 'code') ?? null,
+                message,
+                readNullableStringField(chunk, 'param') ?? null,
+              )}`,
+            );
+          }
+          case 'response.failed': {
+            const responseObject = requireObjectField(chunk, 'response', type);
+            throw new ChatProviderError(
+              `OpenAI Responses response.failed: ${formatResponsesFailedResponse(responseObject)}`,
+            );
+          }
+          default:
+            // Unknown future event types carry no data we currently consume.
+            break;
+        }
+      }
+    } catch (error: unknown) {
+      throw convertOpenAIError(error);
+    }
+  }
+}
+export class OpenAIResponsesChatProvider implements ChatProvider {
+  readonly name: string = 'openai-responses';
+
+  private _model: string;
+  private _stream: boolean;
+  private _apiKey: string | undefined;
+  private _baseUrl: string | undefined;
+  private _defaultHeaders: Record<string, string> | undefined;
+  private _generationKwargs: OpenAIResponsesGenerationKwargs;
+  private _toolMessageConversion: ToolMessageConversion;
+  private _client: OpenAI | undefined;
+  private _httpClient: unknown;
+  private _clientFactory: ((auth: ProviderRequestAuth) => OpenAI) | undefined;
+
+  constructor(options: OpenAIResponsesOptions) {
+    const apiKey = options.apiKey ?? process.env['OPENAI_API_KEY'];
+    this._apiKey = apiKey === undefined || apiKey.length === 0 ? undefined : apiKey;
+    this._baseUrl = options.baseUrl ?? 'https://api.openai.com/v1';
+    this._defaultHeaders = options.defaultHeaders;
+    this._model = options.model;
+    this._stream = true; // Responses API always supports streaming
+    this._generationKwargs = {};
+    this._toolMessageConversion = options.toolMessageConversion ?? null;
+    this._httpClient = options.httpClient;
+    this._clientFactory = options.clientFactory;
+
+    if (options.maxOutputTokens !== undefined) {
+      this._generationKwargs.max_output_tokens = options.maxOutputTokens;
+    }
+
+    this._client = this._apiKey === undefined ? undefined : this._buildClient(this._apiKey);
+  }
+
+  get modelName(): string {
+    return this._model;
+  }
+
+  get thinkingEffort(): ThinkingEffort | null {
+    return reasoningEffortToThinkingEffort(this._generationKwargs.reasoning_effort);
+  }
+
+  get modelParameters(): Record<string, unknown> {
+    return {
+      model: this._model,
+      baseUrl: this._baseUrl,
+      ...this._generationKwargs,
+    };
+  }
+
+  getCapability(model?: string): ModelCapability {
+    return getOpenAIResponsesModelCapability(model ?? this._model);
+  }
+
+  async generate(
+    systemPrompt: string,
+    tools: Tool[],
+    history: Message[],
+    options?: GenerateOptions,
+  ): Promise<StreamedMessage> {
+    const input: unknown[] = [];
+    if (systemPrompt) {
+      const sysItem: Record<string, unknown> = { role: 'system', content: systemPrompt };
+      if (usesOpenAIResponsesDeveloperRole(this._model)) {
+        sysItem['role'] = 'developer';
+      }
+      input.push(sysItem);
+    }
+
+    for (const msg of history) {
+      input.push(...convertMessage(msg, this._model, this._toolMessageConversion));
+    }
+
+    const kwargs: Record<string, unknown> = { ...this._generationKwargs };
+    const reasoningEffort = kwargs['reasoning_effort'] as string | undefined;
+    delete kwargs['reasoning_effort'];
+
+    if (reasoningEffort !== undefined) {
+      kwargs['reasoning'] = {
+        effort: reasoningEffort,
+        summary: 'auto',
+      };
+      kwargs['include'] = ['reasoning.encrypted_content'];
+    }
+
+    // Remove undefined values
+    for (const key of Object.keys(kwargs)) {
+      if (kwargs[key] === undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete kwargs[key];
+      }
+    }
+
+    try {
+      const client = this._createClient(options?.auth);
+      const createParams: Record<string, unknown> = {
+        model: this._model,
+        input,
+        tools: tools.map((t) => convertTool(t)),
+        store: false,
+        stream: this._stream,
+        ...kwargs,
+      };
+
+      if (
+        !('responses' in client) ||
+        typeof (client as { responses?: { create?: unknown } }).responses?.create !== 'function'
+      ) {
+        throw new Error(
+          'OpenAI SDK version does not support Responses API. Upgrade to >=4.x with responses support.',
+        );
+      }
+
+      const response = await (
+        client.responses as {
+          create(params: unknown, opts?: unknown): Promise<unknown>;
+        }
+      ).create(createParams, options?.signal ? { signal: options.signal } : undefined);
+      return new OpenAIResponsesStreamedMessage(response, this._stream);
+    } catch (error: unknown) {
+      throw convertOpenAIError(error);
+    }
+  }
+
+  withThinking(effort: ThinkingEffort): OpenAIResponsesChatProvider {
+    const reasoningEffort = thinkingEffortToReasoningEffort(effort);
+    const clone = this._clone();
+    clone._generationKwargs = {
+      ...clone._generationKwargs,
+      reasoning_effort: reasoningEffort,
+    };
+    return clone;
+  }
+
+  withGenerationKwargs(kwargs: OpenAIResponsesGenerationKwargs): OpenAIResponsesChatProvider {
+    const clone = this._clone();
+    clone._generationKwargs = { ...clone._generationKwargs, ...kwargs };
+    return clone;
+  }
+
+  private _clone(): OpenAIResponsesChatProvider {
+    const clone = Object.assign(
+      Object.create(Object.getPrototypeOf(this) as object) as OpenAIResponsesChatProvider,
+      this,
+    );
+    clone._generationKwargs = { ...this._generationKwargs };
+    return clone;
+  }
+
+  private _createClient(auth: ProviderRequestAuth | undefined): OpenAI {
+    return resolveAuthBackedClient(
+      { cachedClient: this._client, clientFactory: this._clientFactory },
+      auth,
+      (a) =>
+        this._buildClient(requireProviderApiKey('OpenAIResponsesChatProvider', a, this._apiKey), a),
+    );
+  }
+
+  private _buildClient(apiKey: string, auth?: ProviderRequestAuth): OpenAI {
+    const clientOpts: Record<string, unknown> = {
+      apiKey,
+      baseURL: this._baseUrl,
+    };
+    const defaultHeaders = mergeRequestHeaders(this._defaultHeaders, auth?.headers);
+    if (defaultHeaders !== undefined) {
+      clientOpts['defaultHeaders'] = defaultHeaders;
+    }
+    if (this._httpClient !== undefined) {
+      clientOpts['httpClient'] = this._httpClient;
+    }
+    return new OpenAI(clientOpts as ConstructorParameters<typeof OpenAI>[0]);
+  }
+}
diff --git a/packages/kosong/src/providers/request-auth.ts b/packages/kosong/src/providers/request-auth.ts
new file mode 100644
index 000000000..aadc1a11c
--- /dev/null
+++ b/packages/kosong/src/providers/request-auth.ts
@@ -0,0 +1,69 @@
+import { ChatProviderError } from '#/errors';
+import type { ProviderRequestAuth } from '#/provider';
+
+export function requireProviderApiKey(
+  providerName: string,
+  auth: ProviderRequestAuth | undefined,
+  defaultApiKey?: string,
+): string {
+  const apiKey = auth?.apiKey ?? defaultApiKey;
+  if (apiKey === undefined || apiKey.length === 0) {
+    throw new ChatProviderError(
+      `${providerName}: apiKey is required. Provide it via the constructor options, the provider's API-key environment variable, options.auth.apiKey on each request, or an OAuth login.`,
+    );
+  }
+  return apiKey;
+}
+
+export function mergeRequestHeaders(
+  defaultHeaders: Record<string, string> | undefined,
+  requestHeaders: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  const merged: Record<string, string> = {};
+  if (defaultHeaders !== undefined) {
+    Object.assign(merged, defaultHeaders);
+  }
+  if (requestHeaders !== undefined) {
+    Object.assign(merged, requestHeaders);
+  }
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+/**
+ * Resolve the SDK client to use for a single provider request, applying the
+ * standard precedence shared by every provider adapter:
+ *
+ * 1. If a `clientFactory` was supplied, delegate to it (it receives the
+ *    per-request {@link ProviderRequestAuth}, defaulting to `{}`).
+ * 2. Otherwise, if no per-request auth is needed AND a constructor-time
+ *    client was cached, reuse the cached instance.
+ * 3. Otherwise, call `build(auth)` to construct a fresh client for this
+ *    request — typically using `requireProviderApiKey` plus
+ *    `mergeRequestHeaders`.
+ *
+ * Note: when per-request `auth` is provided (e.g. an OAuth bearer token
+ * resolved immediately before each call), step 3 fires and a brand-new SDK
+ * client is constructed per request. This is intentional — it keeps short-lived
+ * credentials out of any long-lived shared state and avoids racing concurrent
+ * requests on a mutable client. The trade-off is that connection-pool / keep-
+ * alive state inside the SDK client isn't reused across requests on the OAuth
+ * path. For the current agent-CLI workload (one LLM call per turn step) this
+ * is fine; if a future host needs high-throughput per-request auth, the
+ * obvious optimization is a small LRU keyed on `(apiKey, headers digest)`.
+ */
+export function resolveAuthBackedClient<TClient>(
+  state: {
+    readonly cachedClient: TClient | undefined;
+    readonly clientFactory: ((auth: ProviderRequestAuth) => TClient) | undefined;
+  },
+  auth: ProviderRequestAuth | undefined,
+  build: (auth: ProviderRequestAuth | undefined) => TClient,
+): TClient {
+  if (state.clientFactory !== undefined) {
+    return state.clientFactory(auth ?? {});
+  }
+  if (auth === undefined && state.cachedClient !== undefined) {
+    return state.cachedClient;
+  }
+  return build(auth);
+}
diff --git a/packages/kosong/src/tool.ts b/packages/kosong/src/tool.ts
new file mode 100644
index 000000000..470b1f937
--- /dev/null
+++ b/packages/kosong/src/tool.ts
@@ -0,0 +1,15 @@
+/**
+ * A tool that the model may invoke during generation.
+ *
+ * The definition is provider-agnostic; each provider implementation converts
+ * it to the appropriate wire format (e.g. OpenAI function-calling, Anthropic
+ * tool-use, Google function declarations).
+ */
+export interface Tool {
+  /** Unique tool name used to match invocations. */
+  name: string;
+  /** Human-readable description shown to the model. */
+  description: string;
+  /** JSON Schema describing the tool's parameters. */
+  parameters: Record<string, unknown>;
+}
diff --git a/packages/kosong/src/usage.ts b/packages/kosong/src/usage.ts
new file mode 100644
index 000000000..c6d269021
--- /dev/null
+++ b/packages/kosong/src/usage.ts
@@ -0,0 +1,54 @@
+/**
+ * Token usage breakdown for a single LLM generation.
+ *
+ * Providers map their native usage counters into this common shape so
+ * callers can aggregate costs without caring about the backend.
+ */
+export interface TokenUsage {
+  /** Input tokens that were neither cache-read nor cache-created. */
+  inputOther: number;
+  /** Output (completion) tokens generated by the model. */
+  output: number;
+  /** Input tokens served from the provider's prompt cache. */
+  inputCacheRead: number;
+  /** Input tokens written into the provider's prompt cache. */
+  inputCacheCreation: number;
+}
+
+/**
+ * Compute total input tokens (other + cache read + cache creation).
+ */
+export function inputTotal(usage: TokenUsage): number {
+  return usage.inputOther + usage.inputCacheRead + usage.inputCacheCreation;
+}
+
+/**
+ * Compute grand total tokens (input total + output).
+ */
+export function grandTotal(usage: TokenUsage): number {
+  return inputTotal(usage) + usage.output;
+}
+
+/**
+ * Create a zero-valued TokenUsage.
+ */
+export function emptyUsage(): TokenUsage {
+  return {
+    inputOther: 0,
+    output: 0,
+    inputCacheRead: 0,
+    inputCacheCreation: 0,
+  };
+}
+
+/**
+ * Sum two TokenUsage values.
+ */
+export function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
+  return {
+    inputOther: a.inputOther + b.inputOther,
+    output: a.output + b.output,
+    inputCacheRead: a.inputCacheRead + b.inputCacheRead,
+    inputCacheCreation: a.inputCacheCreation + b.inputCacheCreation,
+  };
+}
diff --git a/packages/kosong/test/anthropic-errors.test.ts b/packages/kosong/test/anthropic-errors.test.ts
new file mode 100644
index 000000000..0ddf92874
--- /dev/null
+++ b/packages/kosong/test/anthropic-errors.test.ts
@@ -0,0 +1,356 @@
+import {
+  APIConnectionError,
+  APIContextOverflowError,
+  APIStatusError,
+  APITimeoutError,
+  ChatProviderError,
+} from '#/errors';
+import { convertAnthropicError, AnthropicChatProvider } from '#/providers/anthropic';
+import {
+  APIConnectionError as AnthropicConnectionError,
+  APIConnectionTimeoutError as AnthropicTimeoutError,
+  APIError as AnthropicAPIError,
+  AnthropicError,
+  AuthenticationError as AnthropicAuthenticationError,
+  RateLimitError as AnthropicRateLimitError,
+} from '@anthropic-ai/sdk';
+import { describe, it, expect, vi } from 'vitest';
+describe('convertAnthropicError', () => {
+  it('APIConnectionTimeoutError -> APITimeoutError (not misclassified as connection)', () => {
+    const err = new AnthropicTimeoutError({ message: 'timed out' });
+    const result = convertAnthropicError(err);
+    expect(result).toBeInstanceOf(APITimeoutError);
+    // Must NOT be a plain APIConnectionError
+    expect(result.constructor).toBe(APITimeoutError);
+  });
+
+  it('APIConnectionError -> APIConnectionError', () => {
+    const err = new AnthropicConnectionError({ message: 'connection refused' });
+    const result = convertAnthropicError(err);
+    expect(result).toBeInstanceOf(APIConnectionError);
+  });
+
+  it('APIError with status -> APIStatusError', () => {
+    const err = AnthropicAPIError.generate(
+      502,
+      { type: 'error', error: { type: 'api_error', message: 'bad gateway' } },
+      'bad gateway',
+      new Headers(),
+    );
+    const result = convertAnthropicError(err);
+    expect(result).toBeInstanceOf(APIStatusError);
+    expect((result as APIStatusError).statusCode).toBe(502);
+  });
+
+  it('context overflow APIError -> APIContextOverflowError', () => {
+    const err = AnthropicAPIError.generate(
+      422,
+      {
+        type: 'error',
+        error: {
+          type: 'invalid_request_error',
+          message: 'prompt is too long: 210000 tokens exceeds the maximum',
+        },
+      },
+      'prompt is too long: 210000 tokens exceeds the maximum',
+      new Headers(),
+    );
+    const result = convertAnthropicError(err);
+    expect(result).toBeInstanceOf(APIContextOverflowError);
+    expect((result as APIContextOverflowError).statusCode).toBe(422);
+  });
+
+  it('AuthenticationError -> APIStatusError with 401', () => {
+    const err = new AnthropicAuthenticationError(
+      401,
+      { type: 'error', error: { type: 'authentication_error', message: 'invalid key' } },
+      'invalid key',
+      new Headers(),
+    );
+    const result = convertAnthropicError(err);
+    expect(result).toBeInstanceOf(APIStatusError);
+    expect((result as APIStatusError).statusCode).toBe(401);
+  });
+
+  it('RateLimitError -> APIStatusError with 429', () => {
+    const err = new AnthropicRateLimitError(
+      429,
+      { type: 'error', error: { type: 'rate_limit_error', message: 'rate limited' } },
+      'rate limited',
+      new Headers(),
+    );
+    const result = convertAnthropicError(err);
+    expect(result).toBeInstanceOf(APIStatusError);
+    expect((result as APIStatusError).statusCode).toBe(429);
+  });
+
+  it('generic AnthropicError -> ChatProviderError', () => {
+    const err = new AnthropicError('something went wrong');
+    const result = convertAnthropicError(err);
+    expect(result).toBeInstanceOf(ChatProviderError);
+    expect(result.message).toContain('something went wrong');
+  });
+
+  it('plain Error -> ChatProviderError', () => {
+    const err = new Error('unexpected');
+    const result = convertAnthropicError(err);
+    expect(result).toBeInstanceOf(ChatProviderError);
+    expect(result.message).toContain('unexpected');
+  });
+
+  it('non-Error value -> ChatProviderError', () => {
+    const result = convertAnthropicError('string error');
+    expect(result).toBeInstanceOf(ChatProviderError);
+    expect(result.message).toContain('string error');
+  });
+});
+describe('non-stream error propagation', () => {
+  function createNonStreamProvider(): AnthropicChatProvider {
+    return new AnthropicChatProvider({
+      model: 'k25',
+      apiKey: 'test-key',
+      defaultMaxTokens: 1024,
+      stream: false,
+    });
+  }
+
+  it('APIConnectionTimeoutError during generate is converted', async () => {
+    const provider = createNonStreamProvider();
+    const sdkError = new AnthropicTimeoutError({ message: 'stream timed out' });
+    (provider as any)._client.messages.create = vi.fn().mockRejectedValue(sdkError);
+
+    await expect(
+      provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      ),
+    ).rejects.toThrow(APITimeoutError);
+  });
+
+  it('APIConnectionError during generate is converted', async () => {
+    const provider = createNonStreamProvider();
+    const sdkError = new AnthropicConnectionError({ message: 'connection reset' });
+    (provider as any)._client.messages.create = vi.fn().mockRejectedValue(sdkError);
+
+    await expect(
+      provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      ),
+    ).rejects.toThrow(APIConnectionError);
+  });
+
+  it('APIError with status during generate is converted to APIStatusError', async () => {
+    const provider = createNonStreamProvider();
+    const sdkError = AnthropicAPIError.generate(
+      500,
+      { type: 'error', error: { type: 'api_error', message: 'internal error' } },
+      'internal error',
+      new Headers(),
+    );
+    (provider as any)._client.messages.create = vi.fn().mockRejectedValue(sdkError);
+
+    await expect(
+      provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      ),
+    ).rejects.toThrow(APIStatusError);
+  });
+
+  it('RateLimitError during generate is converted to APIStatusError(429)', async () => {
+    const provider = createNonStreamProvider();
+    const sdkError = new AnthropicRateLimitError(
+      429,
+      { type: 'error', error: { type: 'rate_limit_error', message: 'too many requests' } },
+      'too many requests',
+      new Headers(),
+    );
+    (provider as any)._client.messages.create = vi.fn().mockRejectedValue(sdkError);
+
+    try {
+      await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+      expect.unreachable('Should have thrown');
+    } catch (error) {
+      expect(error).toBeInstanceOf(APIStatusError);
+      expect((error as APIStatusError).statusCode).toBe(429);
+    }
+  });
+
+  it('AuthenticationError during generate is converted to APIStatusError(401)', async () => {
+    const provider = createNonStreamProvider();
+    const sdkError = new AnthropicAuthenticationError(
+      401,
+      { type: 'error', error: { type: 'authentication_error', message: 'invalid' } },
+      'invalid',
+      new Headers(),
+    );
+    (provider as any)._client.messages.create = vi.fn().mockRejectedValue(sdkError);
+
+    try {
+      await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+      expect.unreachable('Should have thrown');
+    } catch (error) {
+      expect(error).toBeInstanceOf(APIStatusError);
+      expect((error as APIStatusError).statusCode).toBe(401);
+    }
+  });
+});
+describe('stream error propagation', () => {
+  function createStreamProvider(): AnthropicChatProvider {
+    return new AnthropicChatProvider({
+      model: 'k25',
+      apiKey: 'test-key',
+      defaultMaxTokens: 1024,
+      stream: true,
+    });
+  }
+
+  function makeErrorStream(error: Error) {
+    return {
+      async *[Symbol.asyncIterator]() {
+        yield {
+          type: 'message_start',
+          message: { id: 'msg_err', usage: { input_tokens: 0 } },
+        };
+        throw error;
+      },
+    };
+  }
+
+  it('APIConnectionTimeoutError during stream iteration is converted', async () => {
+    const provider = createStreamProvider();
+    const sdkError = new AnthropicTimeoutError({ message: 'stream timed out' });
+    (provider as any)._client.messages.stream = vi
+      .fn()
+      .mockReturnValue(makeErrorStream(sdkError)) as never;
+
+    const result = await provider.generate(
+      '',
+      [],
+      [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+    );
+    const parts: unknown[] = [];
+    await expect(
+      (async () => {
+        for await (const part of result) {
+          parts.push(part);
+        }
+      })(),
+    ).rejects.toThrow(APITimeoutError);
+  });
+
+  it('APIConnectionError during stream iteration is converted', async () => {
+    const provider = createStreamProvider();
+    const sdkError = new AnthropicConnectionError({ message: 'connection reset' });
+    (provider as any)._client.messages.stream = vi
+      .fn()
+      .mockReturnValue(makeErrorStream(sdkError)) as never;
+
+    const result = await provider.generate(
+      '',
+      [],
+      [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+    );
+    await expect(
+      (async () => {
+        for await (const _ of result) {
+          void _;
+        }
+      })(),
+    ).rejects.toThrow(APIConnectionError);
+  });
+
+  it('APIError with status during stream iteration is converted to APIStatusError', async () => {
+    const provider = createStreamProvider();
+    const sdkError = AnthropicAPIError.generate(
+      500,
+      { type: 'error', error: { type: 'api_error', message: 'internal error' } },
+      'internal error',
+      new Headers(),
+    );
+    (provider as any)._client.messages.stream = vi
+      .fn()
+      .mockReturnValue(makeErrorStream(sdkError)) as never;
+
+    const result = await provider.generate(
+      '',
+      [],
+      [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+    );
+    await expect(
+      (async () => {
+        for await (const _ of result) {
+          void _;
+        }
+      })(),
+    ).rejects.toThrow(APIStatusError);
+  });
+
+  it('RateLimitError during stream iteration is converted to APIStatusError(429)', async () => {
+    const provider = createStreamProvider();
+    const sdkError = new AnthropicRateLimitError(
+      429,
+      { type: 'error', error: { type: 'rate_limit_error', message: 'too many requests' } },
+      'too many requests',
+      new Headers(),
+    );
+    (provider as any)._client.messages.stream = vi
+      .fn()
+      .mockReturnValue(makeErrorStream(sdkError)) as never;
+
+    const result = await provider.generate(
+      '',
+      [],
+      [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+    );
+    try {
+      for await (const _ of result) {
+        void _;
+      }
+      expect.unreachable('Should have thrown');
+    } catch (error) {
+      expect(error).toBeInstanceOf(APIStatusError);
+      expect((error as APIStatusError).statusCode).toBe(429);
+    }
+  });
+
+  it('AuthenticationError during stream iteration is converted to APIStatusError(401)', async () => {
+    const provider = createStreamProvider();
+    const sdkError = new AnthropicAuthenticationError(
+      401,
+      { type: 'error', error: { type: 'authentication_error', message: 'invalid' } },
+      'invalid',
+      new Headers(),
+    );
+    (provider as any)._client.messages.stream = vi
+      .fn()
+      .mockReturnValue(makeErrorStream(sdkError)) as never;
+
+    const result = await provider.generate(
+      '',
+      [],
+      [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+    );
+    try {
+      for await (const _ of result) {
+        void _;
+      }
+      expect.unreachable('Should have thrown');
+    } catch (error) {
+      expect(error).toBeInstanceOf(APIStatusError);
+      expect((error as APIStatusError).statusCode).toBe(401);
+    }
+  });
+});
diff --git a/packages/kosong/test/anthropic.test.ts b/packages/kosong/test/anthropic.test.ts
new file mode 100644
index 000000000..5cfe4292c
--- /dev/null
+++ b/packages/kosong/test/anthropic.test.ts
@@ -0,0 +1,2046 @@
+import { ChatProviderError } from '#/errors';
+import type { ContentPart, Message, StreamedMessagePart, ToolCall } from '#/message';
+import { AnthropicChatProvider, resolveDefaultMaxTokens } from '#/providers/anthropic';
+import type { Tool } from '#/tool';
+import { describe, it, expect, vi } from 'vitest';
+
+function makeAnthropicResponse(model: string = 'k25') {
+  return {
+    id: 'msg_test_123',
+    type: 'message',
+    role: 'assistant',
+    model,
+    content: [{ type: 'text', text: 'Hello' }],
+    stop_reason: 'end_turn',
+    usage: { input_tokens: 10, output_tokens: 5 },
+  };
+}
+
+function createProvider(
+  model: string = 'k25',
+  metadata?: Record<string, string>,
+): AnthropicChatProvider {
+  return new AnthropicChatProvider({
+    model,
+    apiKey: 'test-key',
+    defaultMaxTokens: 1024,
+    metadata,
+    stream: false,
+  });
+}
+
+function createStreamProvider(model: string = 'k25'): AnthropicChatProvider {
+  return new AnthropicChatProvider({
+    model,
+    apiKey: 'test-key',
+    defaultMaxTokens: 1024,
+    stream: true,
+  });
+}
+
+type AnthropicGenerationState = {
+  max_tokens?: number | undefined;
+  temperature?: number | undefined;
+  top_k?: number | undefined;
+  top_p?: number | undefined;
+  thinking?:
+    | { type: 'disabled' }
+    | { type: 'adaptive'; display?: string | undefined }
+    | { type: 'enabled'; budget_tokens: number }
+    | undefined;
+  output_config?: { effort: string } | undefined;
+  betaFeatures?: string[] | undefined;
+};
+
+function getGenerationState(provider: AnthropicChatProvider): AnthropicGenerationState {
+  return Reflect.get(provider, '_generationKwargs') as AnthropicGenerationState;
+}
+
+/** Capture the request body sent to Anthropic by mocking the client (non-stream mode). */
+async function captureRequestBody(
+  provider: AnthropicChatProvider,
+  systemPrompt: string,
+  tools: Tool[],
+  history: Message[],
+): Promise<Record<string, unknown>> {
+  let capturedParams: Record<string, unknown> | undefined;
+  let capturedOptions: Record<string, unknown> | undefined;
+
+  (provider as any)._client.messages.create = vi
+    .fn()
+    .mockImplementation((params: unknown, options?: unknown) => {
+      capturedParams = params as Record<string, unknown>;
+      capturedOptions = options as Record<string, unknown> | undefined;
+      return Promise.resolve(makeAnthropicResponse());
+    });
+
+  const stream = await provider.generate(systemPrompt, tools, history);
+  for await (const part of stream) {
+    void part;
+  }
+
+  if (capturedParams === undefined) {
+    throw new Error('Expected provider.generate() to call messages.create');
+  }
+
+  const result = { ...capturedParams };
+  if (capturedOptions !== undefined && capturedOptions['headers'] !== undefined) {
+    result['_extra_headers'] = capturedOptions['headers'];
+  }
+  return result;
+}
+
+/** Create a mock stream that yields the given events as an async iterable. */
+function mockStream(events: unknown[]) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (const event of events) {
+        yield event;
+      }
+    },
+  };
+}
+
+/** Collect all parts from a StreamedMessage. */
+async function collectParts(
+  streamedMessage: AsyncIterable<StreamedMessagePart>,
+): Promise<StreamedMessagePart[]> {
+  const parts: StreamedMessagePart[] = [];
+  for await (const part of streamedMessage) {
+    parts.push(part);
+  }
+  return parts;
+}
+
+const ADD_TOOL: Tool = {
+  name: 'add',
+  description: 'Add two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+const MUL_TOOL: Tool = {
+  name: 'multiply',
+  description: 'Multiply two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+const B64_PNG =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAA' +
+  'DUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+describe('AnthropicChatProvider', () => {
+  describe('message conversion', () => {
+    it('simple user message with system prompt', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hello!' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, 'You are helpful.', [], history);
+
+      expect(body['messages']).toEqual([
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Hello!', cache_control: { type: 'ephemeral' } }],
+        },
+      ]);
+      expect(body['system']).toEqual([
+        { type: 'text', text: 'You are helpful.', cache_control: { type: 'ephemeral' } },
+      ]);
+    });
+
+    it('multi-turn conversation', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        { role: 'assistant', content: [{ type: 'text', text: '2+2 equals 4.' }], toolCalls: [] },
+        { role: 'user', content: [{ type: 'text', text: 'And 3+3?' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['messages']).toEqual([
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }] },
+        { role: 'assistant', content: [{ type: 'text', text: '2+2 equals 4.' }] },
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'And 3+3?', cache_control: { type: 'ephemeral' } }],
+        },
+      ]);
+      // No system when empty
+      expect(body['system']).toBeUndefined();
+    });
+
+    it('multi-turn with system prompt', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        { role: 'assistant', content: [{ type: 'text', text: '2+2 equals 4.' }], toolCalls: [] },
+        { role: 'user', content: [{ type: 'text', text: 'And 3+3?' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, 'You are a math tutor.', [], history);
+
+      expect(body['system']).toEqual([
+        { type: 'text', text: 'You are a math tutor.', cache_control: { type: 'ephemeral' } },
+      ]);
+      expect(body['messages']).toEqual([
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }] },
+        { role: 'assistant', content: [{ type: 'text', text: '2+2 equals 4.' }] },
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'And 3+3?', cache_control: { type: 'ephemeral' } }],
+        },
+      ]);
+    });
+
+    it('image url content (url source)', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: "What's in this image?" },
+            { type: 'image_url', imageUrl: { url: 'https://example.com/image.png' } },
+          ] satisfies ContentPart[],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['messages']).toEqual([
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: "What's in this image?" },
+            {
+              type: 'image',
+              source: { type: 'url', url: 'https://example.com/image.png' },
+              cache_control: { type: 'ephemeral' },
+            },
+          ],
+        },
+      ]);
+    });
+
+    it('tool definitions with cache_control on last tool', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL, MUL_TOOL], history);
+
+      expect(body['tools']).toEqual([
+        {
+          name: 'add',
+          description: 'Add two integers.',
+          input_schema: {
+            type: 'object',
+            properties: {
+              a: { type: 'integer', description: 'First number' },
+              b: { type: 'integer', description: 'Second number' },
+            },
+            required: ['a', 'b'],
+          },
+        },
+        {
+          name: 'multiply',
+          description: 'Multiply two integers.',
+          input_schema: {
+            type: 'object',
+            properties: {
+              a: { type: 'integer', description: 'First number' },
+              b: { type: 'integer', description: 'Second number' },
+            },
+            required: ['a', 'b'],
+          },
+          cache_control: { type: 'ephemeral' },
+        },
+      ]);
+    });
+
+    it('tool call and tool result (Anthropic wire format)', async () => {
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_abc123',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll add those numbers for you." }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '5' }],
+          toolCallId: 'call_abc123',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      // Snapshot of the expected wire format:
+      // user message has NO cache_control, assistant has tool_use blocks,
+      // final user message's tool_result carries cache_control (last block).
+      expect(body['messages']).toEqual([
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Add 2 and 3' }],
+        },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'text', text: "I'll add those numbers for you." },
+            { type: 'tool_use', id: 'call_abc123', name: 'add', input: { a: 2, b: 3 } },
+          ],
+        },
+        {
+          role: 'user',
+          content: [
+            {
+              type: 'tool_result',
+              tool_use_id: 'call_abc123',
+              content: [{ type: 'text', text: '5' }],
+              cache_control: { type: 'ephemeral' },
+            },
+          ],
+        },
+      ]);
+    });
+
+    it('tool call with image result wraps image source inside tool_result', async () => {
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_abc123',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll add those numbers for you." }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: '5' },
+            { type: 'image_url', imageUrl: { url: 'https://example.com/image.png' } },
+          ] satisfies ContentPart[],
+          toolCallId: 'call_abc123',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      const messages = body['messages'] as unknown[];
+
+      // Tool result block carries both text and image.
+      expect(messages[2]).toEqual({
+        role: 'user',
+        content: [
+          {
+            type: 'tool_result',
+            tool_use_id: 'call_abc123',
+            content: [
+              { type: 'text', text: '5' },
+              {
+                type: 'image',
+                source: { type: 'url', url: 'https://example.com/image.png' },
+              },
+            ],
+            cache_control: { type: 'ephemeral' },
+          },
+        ],
+      });
+    });
+
+    it('parallel tool calls and tool results (request body capture)', async () => {
+      const provider = createProvider();
+      const tcAdd: ToolCall = {
+        type: 'function',
+        id: 'call_add',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const tcMul: ToolCall = {
+        type: 'function',
+        id: 'call_mul',
+        function: { name: 'multiply', arguments: '{"a": 4, "b": 5}' },
+      };
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Calculate 2+3 and 4*5' }],
+          toolCalls: [],
+        },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll calculate both." }],
+          toolCalls: [tcAdd, tcMul],
+        },
+        {
+          role: 'tool',
+          content: [
+            {
+              type: 'text',
+              text: '<system-reminder>This is a system reminder</system-reminder>',
+            },
+            { type: 'text', text: '5' },
+          ],
+          toolCallId: 'call_add',
+          toolCalls: [],
+        },
+        {
+          role: 'tool',
+          content: [
+            {
+              type: 'text',
+              text: '<system-reminder>This is a system reminder</system-reminder>',
+            },
+            { type: 'text', text: '20' },
+          ],
+          toolCallId: 'call_mul',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL, MUL_TOOL], history);
+
+      // Per the Anthropic Messages API parallel-tool-use spec, all tool_result
+      // blocks answering parallel tool_use calls MUST live in a single user
+      // message — not split across consecutive user messages. Splitting hard-
+      // fails strict Anthropic-compatible backends (HTTP 400) and silently
+      // degrades parallel tool use on api.anthropic.com. This asserts:
+      //  - exactly 3 messages in the expected order
+      //  - both tool_result blocks are bundled in the trailing user message
+      //  - cache_control lands on the LAST block after merging (call_mul's
+      //    tool_result), mirroring the "cache the longest prefix" policy.
+      expect(body['messages']).toEqual([
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Calculate 2+3 and 4*5' }],
+        },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'text', text: "I'll calculate both." },
+            { type: 'tool_use', id: 'call_add', name: 'add', input: { a: 2, b: 3 } },
+            { type: 'tool_use', id: 'call_mul', name: 'multiply', input: { a: 4, b: 5 } },
+          ],
+        },
+        {
+          role: 'user',
+          content: [
+            {
+              type: 'tool_result',
+              tool_use_id: 'call_add',
+              content: [
+                {
+                  type: 'text',
+                  text: '<system-reminder>This is a system reminder</system-reminder>',
+                },
+                { type: 'text', text: '5' },
+              ],
+            },
+            {
+              type: 'tool_result',
+              tool_use_id: 'call_mul',
+              content: [
+                {
+                  type: 'text',
+                  text: '<system-reminder>This is a system reminder</system-reminder>',
+                },
+                { type: 'text', text: '20' },
+              ],
+              cache_control: { type: 'ephemeral' },
+            },
+          ],
+        },
+      ]);
+    });
+
+    // Independent assertion-style regression test for the Anthropic
+    // parallel-tool-use spec. Documents the spec-required shape without
+    // relying on snapshot equality — so if anyone regenerates the
+    // snapshot above against buggy (split) output again, this test still
+    // fails.
+    it('parallel tool_results merged into single trailing user message', async () => {
+      const provider = createProvider();
+      const tcAdd: ToolCall = {
+        type: 'function',
+        id: 'call_add',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const tcMul: ToolCall = {
+        type: 'function',
+        id: 'call_mul',
+        function: { name: 'multiply', arguments: '{"a": 4, "b": 5}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Calculate 2+3 and 4*5' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll calculate both." }],
+          toolCalls: [tcAdd, tcMul],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '5' }],
+          toolCallId: 'call_add',
+          toolCalls: [],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '20' }],
+          toolCallId: 'call_mul',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL, MUL_TOOL], history);
+
+      type MsgParam = { role: string; content: Array<{ type: string; tool_use_id?: string }> };
+      const msgs = body['messages'] as MsgParam[];
+
+      // 3 messages: initial user prompt, assistant with parallel tool_use,
+      // and a single trailing user message carrying BOTH tool_result blocks.
+      expect(msgs).toHaveLength(3);
+      expect(msgs[0]!.role).toBe('user');
+      expect(msgs[1]!.role).toBe('assistant');
+      expect(msgs[2]!.role).toBe('user');
+
+      const trailing = msgs[2]!.content;
+      expect(trailing).toHaveLength(2);
+      expect(trailing[0]!.type).toBe('tool_result');
+      expect(trailing[0]!.tool_use_id).toBe('call_add');
+      expect(trailing[1]!.type).toBe('tool_result');
+      expect(trailing[1]!.tool_use_id).toBe('call_mul');
+    });
+
+    // Edge case: single (non-parallel) tool call should NOT trigger merge
+    // semantics — the one tool_result sits alone in its own user message,
+    // same as before. Guards against an over-eager merge that concatenates
+    // across turns.
+    it('single tool call: no merge triggered', async () => {
+      const provider = createProvider();
+      const tcAdd: ToolCall = {
+        type: 'function',
+        id: 'call_add',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+3?' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'Calculating.' }],
+          toolCalls: [tcAdd],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '5' }],
+          toolCallId: 'call_add',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL], history);
+
+      type MsgParam = { role: string; content: Array<{ type: string; tool_use_id?: string }> };
+      const msgs = body['messages'] as MsgParam[];
+
+      expect(msgs).toHaveLength(3);
+      expect(msgs[2]!.content).toHaveLength(1);
+      expect(msgs[2]!.content[0]!.type).toBe('tool_result');
+      expect(msgs[2]!.content[0]!.tool_use_id).toBe('call_add');
+    });
+
+    // Edge case: 3 parallel tool calls collapse into one user message with
+    // 3 tool_result blocks (order preserved).
+    it('three parallel tool_results merged in order', async () => {
+      const provider = createProvider();
+      const makeTc = (id: string, name: string): ToolCall => ({
+        type: 'function',
+        id,
+        function: { name, arguments: '{"a": 1, "b": 1}' },
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Do three things' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'Running.' }],
+          toolCalls: [makeTc('c1', 'add'), makeTc('c2', 'multiply'), makeTc('c3', 'add')],
+        },
+        { role: 'tool', content: [{ type: 'text', text: '2' }], toolCallId: 'c1', toolCalls: [] },
+        { role: 'tool', content: [{ type: 'text', text: '1' }], toolCallId: 'c2', toolCalls: [] },
+        { role: 'tool', content: [{ type: 'text', text: '2' }], toolCallId: 'c3', toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL, MUL_TOOL], history);
+
+      type MsgParam = { role: string; content: Array<{ type: string; tool_use_id?: string }> };
+      const msgs = body['messages'] as MsgParam[];
+
+      expect(msgs).toHaveLength(3);
+      const trailing = msgs[2]!.content;
+      expect(trailing).toHaveLength(3);
+      expect(trailing.map((b) => b.tool_use_id)).toEqual(['c1', 'c2', 'c3']);
+      expect(trailing.every((b) => b.type === 'tool_result')).toBe(true);
+    });
+
+    // Edge case: parallel tool results followed by a plain user text turn —
+    // only the tool_result-only user messages merge; the text message stays
+    // in its own message (proving the predicate is content-shape-aware, not
+    // just role-based).
+    it('text turn after parallel tool_results stays separate', async () => {
+      const provider = createProvider();
+      const tcAdd: ToolCall = {
+        type: 'function',
+        id: 'call_add',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const tcMul: ToolCall = {
+        type: 'function',
+        id: 'call_mul',
+        function: { name: 'multiply', arguments: '{"a": 4, "b": 5}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Do both' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'Running.' }],
+          toolCalls: [tcAdd, tcMul],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '5' }],
+          toolCallId: 'call_add',
+          toolCalls: [],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '20' }],
+          toolCallId: 'call_mul',
+          toolCalls: [],
+        },
+        { role: 'user', content: [{ type: 'text', text: 'Now summarize' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL, MUL_TOOL], history);
+
+      type MsgParam = {
+        role: string;
+        content: Array<{ type: string; tool_use_id?: string; text?: string }>;
+      };
+      const msgs = body['messages'] as MsgParam[];
+
+      // 4 messages: user prompt, assistant tool_use, merged tool_result user, final text user.
+      expect(msgs).toHaveLength(4);
+      expect(msgs[2]!.content).toHaveLength(2);
+      expect(msgs[2]!.content.every((b) => b.type === 'tool_result')).toBe(true);
+      expect(msgs[3]!.role).toBe('user');
+      expect(msgs[3]!.content).toHaveLength(1);
+      expect(msgs[3]!.content[0]!.type).toBe('text');
+      expect(msgs[3]!.content[0]!.text).toBe('Now summarize');
+    });
+
+    it('assistant with thinking (has encrypted -> ThinkingBlockParam)', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'think', think: 'Let me think...', encrypted: 'sig_abc123' },
+            { type: 'text', text: 'The answer is 4.' },
+          ],
+          toolCalls: [],
+        },
+        { role: 'user', content: [{ type: 'text', text: 'Thanks!' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      // Snapshot of the expected wire format:
+      // first user message has NO cache_control, assistant has thinking + text,
+      // LAST user message's text block carries cache_control.
+      expect(body['messages']).toEqual([
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'What is 2+2?' }],
+        },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'thinking', thinking: 'Let me think...', signature: 'sig_abc123' },
+            { type: 'text', text: 'The answer is 4.' },
+          ],
+        },
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Thanks!', cache_control: { type: 'ephemeral' } }],
+        },
+      ]);
+    });
+
+    it('thinking without signature is stripped', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'think', think: 'Thinking...' },
+            { type: 'text', text: 'Hello!' },
+          ],
+          toolCalls: [],
+        },
+        { role: 'user', content: [{ type: 'text', text: 'Bye' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      const messages = body['messages'] as unknown[];
+
+      // Assistant message should have thinking stripped (no encrypted)
+      expect(messages[1]).toEqual({
+        role: 'assistant',
+        content: [{ type: 'text', text: 'Hello!' }],
+      });
+    });
+
+    it('base64 image', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'Describe:' },
+            {
+              type: 'image_url',
+              imageUrl: { url: `data:image/png;base64,${B64_PNG}` },
+            },
+          ] satisfies ContentPart[],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['messages']).toEqual([
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'Describe:' },
+            {
+              type: 'image',
+              source: { type: 'base64', data: B64_PNG, media_type: 'image/png' },
+              cache_control: { type: 'ephemeral' },
+            },
+          ],
+        },
+      ]);
+    });
+
+    it('redacted thinking (empty think with encrypted)', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'think', think: '', encrypted: 'enc_redacted_sig_xyz' },
+            { type: 'text', text: '4.' },
+          ],
+          toolCalls: [],
+        },
+        { role: 'user', content: [{ type: 'text', text: 'Thanks!' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      const messages = body['messages'] as unknown[];
+
+      expect(messages[1]).toEqual({
+        role: 'assistant',
+        content: [
+          { type: 'thinking', thinking: '', signature: 'enc_redacted_sig_xyz' },
+          { type: 'text', text: '4.' },
+        ],
+      });
+    });
+  });
+
+  describe('generation kwargs', () => {
+    it('applies temperature, top_p, and max_tokens', async () => {
+      const provider = createProvider().withGenerationKwargs({
+        temperature: 0.7,
+        top_p: 0.9,
+        max_tokens: 2048,
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['temperature']).toBe(0.7);
+      expect(body['top_p']).toBe(0.9);
+      expect(body['max_tokens']).toBe(2048);
+    });
+
+    it('combines thinking and max_tokens in internal state', () => {
+      const provider = createProvider()
+        .withThinking('high')
+        .withGenerationKwargs({ max_tokens: 512 });
+      const state = getGenerationState(provider);
+
+      expect(state).toMatchObject({
+        max_tokens: 512,
+        thinking: { type: 'enabled', budget_tokens: 32_000 },
+      });
+    });
+
+    it('keeps the same internal state regardless of withThinking/withGenerationKwargs order', () => {
+      const thinkingThenKwargs = getGenerationState(
+        createProvider().withThinking('high').withGenerationKwargs({ max_tokens: 512 }),
+      );
+      const kwargsThenThinking = getGenerationState(
+        createProvider().withGenerationKwargs({ max_tokens: 512 }).withThinking('high'),
+      );
+
+      expect(kwargsThenThinking).toEqual(thinkingThenKwargs);
+    });
+
+    it('shallow-merges repeated withGenerationKwargs calls and replaces duplicate keys', () => {
+      const provider = createProvider()
+        .withGenerationKwargs({ max_tokens: 256, temperature: 0.1 })
+        .withGenerationKwargs({ max_tokens: 512 });
+
+      expect(getGenerationState(provider)).toMatchObject({
+        max_tokens: 512,
+        temperature: 0.1,
+      });
+    });
+  });
+
+  describe('with thinking', () => {
+    const thinkHistory: Message[] = [
+      { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+    ];
+
+    it('pre-4.6 model: high -> budget_tokens=32000', async () => {
+      const provider = createProvider('k25').withThinking('high');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'enabled', budget_tokens: 32000 });
+      expect(body['output_config']).toBeUndefined();
+    });
+
+    it('opus-4-6: uses adaptive thinking', async () => {
+      const provider = createProvider('opus-4-6').withThinking('high');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'adaptive', display: 'summarized' });
+      expect(body['output_config']).toEqual({ effort: 'high' });
+      // Adaptive should remove interleaved-thinking beta
+      const headers = body['_extra_headers'] as Record<string, string> | undefined;
+      if (headers !== undefined && headers['anthropic-beta'] !== undefined) {
+        expect(headers['anthropic-beta']).not.toContain('interleaved-thinking-2025-05-14');
+      }
+    });
+
+    it('opus-4-7: uses adaptive thinking with xhigh effort', async () => {
+      const provider = createProvider('claude-opus-4-7').withThinking('xhigh');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'adaptive', display: 'summarized' });
+      expect(body['output_config']).toEqual({ effort: 'xhigh' });
+    });
+
+    it.each([
+      'claude-sonnet-4-6',
+      'anthropic.claude-opus-4-7-v1:0',
+      'publishers/anthropic/models/claude-sonnet-4-6',
+    ])('%s: uses adaptive thinking', async (model) => {
+      const provider = createProvider(model).withThinking('high');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'adaptive', display: 'summarized' });
+      expect(body['output_config']).toEqual({ effort: 'high' });
+    });
+
+    it('future 4.6+ model uses adaptive thinking and clamps xhigh to high', async () => {
+      const provider = createProvider('claude-sonnet-4-8').withThinking('xhigh');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'adaptive', display: 'summarized' });
+      expect(body['output_config']).toEqual({ effort: 'high' });
+    });
+
+    it('opus-4-6 supports max effort', async () => {
+      const provider = createProvider('claude-opus-4-6').withThinking('max');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'adaptive', display: 'summarized' });
+      expect(body['output_config']).toEqual({ effort: 'max' });
+    });
+
+    it('pre-4.6 model clamps xhigh and max to high without output_config', async () => {
+      for (const effort of ['xhigh', 'max'] as const) {
+        const provider = createProvider('claude-sonnet-4-5').withThinking(effort);
+        const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+        expect(body['thinking']).toEqual({ type: 'enabled', budget_tokens: 32000 });
+        expect(body['output_config']).toBeUndefined();
+      }
+    });
+
+    it('opus-4-5 sends legacy budget thinking with clamped effort output_config', async () => {
+      const provider = createProvider('claude-opus-4-5').withThinking('xhigh');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'enabled', budget_tokens: 32000 });
+      expect(body['output_config']).toEqual({ effort: 'high' });
+    });
+
+    it('opus-4-6 with thinking off -> disabled', async () => {
+      const provider = createProvider('opus-4-6').withThinking('off');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'disabled' });
+      expect(body['output_config']).toBeUndefined();
+      const headers = body['_extra_headers'] as Record<string, string> | undefined;
+      expect(headers?.['anthropic-beta']).toBeUndefined();
+    });
+
+    it('adaptive thinking off clears stale output_config', async () => {
+      const provider = createProvider('opus-4-6').withThinking('high').withThinking('off');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'disabled' });
+      expect(body['output_config']).toBeUndefined();
+    });
+
+    it('replaces the previous thinking config when called again', () => {
+      const provider = createProvider().withThinking('high').withThinking('off');
+
+      expect(getGenerationState(provider).thinking).toEqual({ type: 'disabled' });
+    });
+
+    it('claude-3-5-sonnet legacy: high sends budget thinking without output_config', async () => {
+      const provider = createProvider('claude-3-5-sonnet-20240620').withThinking('high');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'enabled', budget_tokens: 32000 });
+      expect(body['output_config']).toBeUndefined();
+    });
+
+    it('haiku-4-5 legacy: medium sends budget thinking without output_config', async () => {
+      const provider = createProvider('claude-haiku-4-5-20251001').withThinking('medium');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'enabled', budget_tokens: 4096 });
+      expect(body['output_config']).toBeUndefined();
+    });
+
+    it('opus-4-7: low effort passes through to output_config', async () => {
+      const provider = createProvider('claude-opus-4-7').withThinking('low');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['output_config']).toEqual({ effort: 'low' });
+    });
+
+    it('opus-4-7: medium effort passes through to output_config', async () => {
+      const provider = createProvider('claude-opus-4-7').withThinking('medium');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['output_config']).toEqual({ effort: 'medium' });
+    });
+
+    it('future opus-4-8 uses adaptive thinking via regex extrapolation', async () => {
+      const provider = createProvider('claude-opus-4-8').withThinking('xhigh');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'adaptive', display: 'summarized' });
+      // xhigh is opus-4-7-only; clamps to high on future 4.8 until proven otherwise
+      expect(body['output_config']).toEqual({ effort: 'high' });
+    });
+
+    it('opus-4-7 + high stays high without clamping', async () => {
+      const provider = createProvider('claude-opus-4-7').withThinking('high');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'adaptive', display: 'summarized' });
+      expect(body['output_config']).toEqual({ effort: 'high' });
+    });
+
+    it.each([
+      ['low', 1024],
+      ['medium', 4096],
+      ['high', 32000],
+    ] as const)(
+      'sonnet-4 (pre-4.6) %s: budget_tokens=%i, no output_config',
+      async (effort, budget) => {
+        const provider = createProvider('claude-sonnet-4-20250514').withThinking(effort);
+        const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+        expect(body['thinking']).toEqual({ type: 'enabled', budget_tokens: budget });
+        expect(body['output_config']).toBeUndefined();
+      },
+    );
+
+    it.each([
+      // opus-4-7 passes all efforts through unchanged
+      ['claude-opus-4-7', 'low', 'low'],
+      ['claude-opus-4-7', 'medium', 'medium'],
+      ['claude-opus-4-7', 'high', 'high'],
+      ['claude-opus-4-7', 'xhigh', 'xhigh'],
+      ['claude-opus-4-7', 'max', 'max'],
+      // pre-4.7 opus: xhigh and max clamp to high/max respectively (xhigh -> high, max passes since adaptive)
+      ['claude-opus-4-6', 'xhigh', 'high'],
+      ['claude-opus-4-6', 'max', 'max'],
+    ] as const)(
+      'clampEffort wire body: %s + %s -> output_config.effort=%s',
+      async (model, effort, expected) => {
+        const provider = createProvider(model).withThinking(effort);
+        const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+        expect(body['output_config']).toEqual({ effort: expected });
+      },
+    );
+
+    it('clampEffort wire body: sonnet-4-5 (non-adaptive) has no output_config', async () => {
+      const provider = createProvider('claude-sonnet-4-5').withThinking('high');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['output_config']).toBeUndefined();
+    });
+
+    it.each([
+      'claude-opus-4-7',
+      'claude-opus-4-8',
+      'anthropic.claude-opus-4-7-v1:0',
+      'vertex_ai/claude-opus-4-7',
+      'bedrock/anthropic.claude-opus-4-6-v1:0',
+    ])('adaptive-capable model %s routes through adaptive path', async (model) => {
+      const provider = createProvider(model).withThinking('high');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'adaptive', display: 'summarized' });
+      expect(body['output_config']).toEqual({ effort: 'high' });
+    });
+
+    it.each([
+      'claude-sonnet-4-20250514',
+      'claude-3-5-sonnet-20240620',
+      'claude-haiku-4-5-20251001',
+    ])('non-adaptive model %s does not emit adaptive thinking', async (model) => {
+      const provider = createProvider(model).withThinking('high');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      expect(body['thinking']).toEqual({ type: 'enabled', budget_tokens: 32000 });
+      expect(body['output_config']).toBeUndefined();
+    });
+
+    it.each([
+      // effort-supporting models: output_config present
+      ['claude-opus-4-7', true],
+      ['anthropic.claude-opus-4-5-v1:0', true],
+      // non-effort-supporting models: output_config absent
+      ['claude-3-5-sonnet-20240620', false],
+      ['claude-haiku-4-5-20251001', false],
+    ] as const)('supportsEffortParam wire body: %s -> output_config=%s', async (model, supports) => {
+      const provider = createProvider(model).withThinking('high');
+      const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+      if (supports) {
+        expect(body['output_config']).toEqual({ effort: 'high' });
+      } else {
+        expect(body['output_config']).toBeUndefined();
+      }
+    });
+
+    // Full adaptive-thinking coverage matrix. Adaptive models must
+    // emit { type: 'adaptive' } and output_config; non-adaptive models
+    // must fall back to legacy budget thinking.
+    describe('supports adaptive thinking matrix', () => {
+      it.each([
+        // Opus 4.7 family (adaptive-only per Anthropic docs)
+        'claude-opus-4-7',
+        'claude-opus-4-7-20260301',
+        'claude-opus-4.7',
+        'CLAUDE-OPUS-4-7', // case-insensitive
+        // Opus 4.6 / Sonnet 4.6
+        'claude-opus-4-6',
+        'claude-opus-4-6-20260205',
+        'claude-opus-4.6',
+        'claude-sonnet-4-6',
+        'claude-sonnet-4-6-20260301',
+        'claude-sonnet-4.6',
+        // Future version extrapolation
+        'claude-opus-4-8',
+        'claude-opus-4-9',
+        'claude-opus-4-10',
+        'claude-opus-5-0',
+        'claude-opus-5-0-20270101',
+        'claude-sonnet-5-0',
+        'claude-haiku-4-6',
+        'claude-haiku-5-0',
+        // Bedrock / Vertex / proxy prefixes
+        'anthropic.claude-opus-4-7-v1:0',
+        'aws/claude-opus-4-7',
+        'bedrock/anthropic.claude-opus-4-6-v1:0',
+        'claude-opus-4-7@20260101',
+      ])('adaptive: %s -> type=adaptive', async (model) => {
+        const provider = createProvider(model).withThinking('high');
+        const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+        expect(body['thinking']).toEqual({ type: 'adaptive', display: 'summarized' });
+      });
+
+      it.each([
+        // Pre-4.6 models (legacy budget_tokens required)
+        'claude-opus-4',
+        'claude-opus-4-0',
+        'claude-opus-4-5',
+        'claude-opus-4-5-20251001',
+        'claude-opus-3-5',
+        'claude-opus-3-5-sonnet-20241022',
+        'claude-sonnet-4-20250514',
+        'claude-sonnet-4-5',
+        'claude-sonnet-4-5-20250929',
+        'claude-sonnet-3-5',
+        'claude-sonnet-3-7',
+        'claude-haiku-3-5',
+        'claude-haiku-4-5',
+        'claude-haiku-4-5-20251001',
+        // Non-Claude models / garbage input
+        'gpt-4',
+        'gpt-4-turbo',
+        'gemini-2.5-pro',
+        'unknown-model',
+        'claude', // no family word
+      ])('non-adaptive: %s -> type=enabled budget', async (model) => {
+        const provider = createProvider(model).withThinking('high');
+        const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+        expect(body['thinking']).toMatchObject({ type: 'enabled' });
+        expect((body['thinking'] as { type: string }).type).not.toBe('adaptive');
+      });
+    });
+
+    // Effort clamping per model capability: adaptive-capable models
+    // pass max effort through, others cap at high.
+    describe('clamp effort matrix', () => {
+      it.each([
+        // Opus 4.7: full range including xhigh and max
+        ['claude-opus-4-7', 'low', 'low'],
+        ['claude-opus-4-7', 'medium', 'medium'],
+        ['claude-opus-4-7', 'high', 'high'],
+        ['claude-opus-4-7', 'xhigh', 'xhigh'],
+        ['claude-opus-4-7', 'max', 'max'],
+        ['claude-opus-4-7-20260301', 'xhigh', 'xhigh'],
+        // Opus 4.6: max supported, xhigh clamps to high
+        ['claude-opus-4-6', 'max', 'max'],
+        ['claude-opus-4-6', 'xhigh', 'high'],
+        ['claude-opus-4-6-20260205', 'max', 'max'],
+        // Sonnet 4.6
+        ['claude-sonnet-4-6', 'max', 'max'],
+        ['claude-sonnet-4-6', 'xhigh', 'high'],
+        // low/medium/high passthrough
+        ['claude-opus-4-6', 'medium', 'medium'],
+        // Future 4.8+: inherits max but xhigh clamps to high
+        ['claude-opus-4-8', 'xhigh', 'high'],
+        ['claude-opus-4-8', 'max', 'max'],
+        ['claude-opus-5-0', 'max', 'max'],
+        ['claude-opus-5-0', 'xhigh', 'high'],
+      ] as const)(
+        'clamp adaptive: %s + %s -> effort=%s',
+        async (model, effort, expected) => {
+          const provider = createProvider(model).withThinking(effort);
+          const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+          expect(body['output_config']).toEqual({ effort: expected });
+        },
+      );
+
+      // Pre-4.6 non-adaptive models: effort clamps in legacy budget mode.
+      // output_config presence depends on _supports_effort_param; opus-4-5
+      // supports effort, sonnet/haiku-4 do not.
+      it.each([
+        ['claude-opus-4-5', 'max', 'high', true],
+        ['claude-opus-4-5', 'xhigh', 'high', true],
+        ['claude-opus-4-5', 'high', 'high', true],
+        ['claude-sonnet-4-20250514', 'max', 'high', false],
+        ['claude-sonnet-4-20250514', 'xhigh', 'high', false],
+        ['claude-sonnet-4-20250514', 'low', 'low', false],
+        ['claude-sonnet-4-5', 'xhigh', 'high', false],
+        ['claude-haiku-4-5', 'max', 'high', false],
+      ] as const)(
+        'clamp legacy: %s + %s -> effort=%s (supports=%s)',
+        async (model, effort, expected, supports) => {
+          const provider = createProvider(model).withThinking(effort);
+          const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+          if (supports) {
+            expect(body['output_config']).toEqual({ effort: expected });
+          } else {
+            expect(body['output_config']).toBeUndefined();
+          }
+        },
+      );
+    });
+
+    // Effort-param gating: adaptive-capable models and explicit
+    // allowlist entries (Opus 4.5 legacy) emit output_config; legacy
+    // year-first names and Bedrock-prefixed legacy must not.
+    describe('supports effort param matrix', () => {
+      it.each([
+        // Adaptive-capable: all support effort
+        'claude-opus-4-7',
+        'claude-opus-4-7-20260301',
+        'claude-opus-4-6',
+        'claude-opus-4-6-20260205',
+        'claude-sonnet-4-6',
+        'claude-opus-5-0',
+        // Opus 4.5 explicitly supports effort (legacy budget thinking + effort)
+        'claude-opus-4-5',
+        'claude-opus-4-5-20251001',
+        'claude-opus-4.5',
+        'anthropic.claude-opus-4-5-v1:0',
+      ])('effort supported: %s -> output_config present', async (model) => {
+        const provider = createProvider(model).withThinking('high');
+        const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+        expect(body['output_config']).toEqual({ effort: 'high' });
+      });
+
+      it.each([
+        // Sonnet/Haiku-4 (non-4.6): not explicitly listed → false
+        'claude-sonnet-4-20250514',
+        'claude-sonnet-4-5',
+        'claude-sonnet-4-5-20250929',
+        'claude-haiku-4-5',
+        'claude-haiku-4-5-20251001',
+        // Claude 3.x family: predates effort param
+        'claude-sonnet-3-7',
+        'claude-sonnet-3-7-20250219',
+        'claude-sonnet-3-5',
+        'claude-opus-3-5',
+        'claude-haiku-3-5',
+        // Old naming format (year-first)
+        'claude-3-opus-20240229',
+        'claude-3-5-sonnet-20240620',
+        'claude-3-5-haiku-20241022',
+        // Bedrock + old format
+        'anthropic.claude-3-5-sonnet-20240620-v1:0',
+        // Non-Claude / garbage
+        'gpt-4',
+        'claude-2.1',
+      ])('effort unsupported: %s -> output_config absent', async (model) => {
+        const provider = createProvider(model).withThinking('high');
+        const body = await captureRequestBody(provider, '', [], thinkHistory);
+
+        expect(body['output_config']).toBeUndefined();
+      });
+    });
+  });
+
+  describe('metadata', () => {
+    it('forwards metadata to the request', async () => {
+      const provider = createProvider('k25', {
+        user_id: 'test-session-id',
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['metadata']).toEqual({ user_id: 'test-session-id' });
+    });
+
+    it('omits metadata when not provided', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['metadata']).toBeUndefined();
+    });
+  });
+
+  describe('thinkingEffort property', () => {
+    it('returns null when no thinking configured', () => {
+      const provider = createProvider();
+      expect(provider.thinkingEffort).toBeNull();
+    });
+
+    it('opus-4-6 with thinking high -> "high" (adaptive)', () => {
+      const provider = createProvider('claude-opus-4-6').withThinking('high');
+      expect(provider.thinkingEffort).toBe('high');
+    });
+
+    it('opus-4-6 with thinking off -> "off"', () => {
+      const provider = createProvider('claude-opus-4-6').withThinking('off');
+      expect(provider.thinkingEffort).toBe('off');
+    });
+
+    it('opus-4-7 reports xhigh and max adaptive efforts', () => {
+      const xhigh = createProvider('claude-opus-4-7').withThinking('xhigh');
+      expect(xhigh.thinkingEffort).toBe('xhigh');
+
+      const max = createProvider('claude-opus-4-7').withThinking('max');
+      expect(max.thinkingEffort).toBe('max');
+    });
+
+    it('reports clamped adaptive effort', () => {
+      const provider = createProvider('claude-sonnet-4-6').withThinking('xhigh');
+      expect(provider.thinkingEffort).toBe('high');
+    });
+
+    it('pre-4.6 budget-based levels', () => {
+      const low = createProvider().withThinking('low');
+      expect(low.thinkingEffort).toBe('low');
+
+      const med = createProvider().withThinking('medium');
+      expect(med.thinkingEffort).toBe('medium');
+
+      const high = createProvider().withThinking('high');
+      expect(high.thinkingEffort).toBe('high');
+    });
+  });
+
+  describe('provider properties', () => {
+    it('has correct name and model', () => {
+      const provider = createProvider();
+      expect(provider.name).toBe('anthropic');
+      expect(provider.modelName).toBe('k25');
+    });
+
+    it('withThinking returns a new instance', () => {
+      const provider = createProvider();
+      const newProvider = provider.withThinking('high');
+      expect(newProvider).toBeInstanceOf(AnthropicChatProvider);
+      expect(newProvider).not.toBe(provider);
+    });
+  });
+
+  describe('non-stream response parsing', () => {
+    it('yields text content from non-stream response', async () => {
+      const provider = createProvider();
+      (provider as any)._client.messages.create = vi.fn().mockResolvedValue({
+        id: 'msg_123',
+        content: [{ type: 'text', text: 'Hello world' }],
+        usage: { input_tokens: 10, output_tokens: 5 },
+      });
+
+      const stream = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+
+      const parts = [];
+      for await (const part of stream) {
+        parts.push(part);
+      }
+
+      expect(parts).toEqual([{ type: 'text', text: 'Hello world' }]);
+      expect(stream.id).toBe('msg_123');
+      expect(stream.usage).toEqual({
+        inputOther: 10,
+        output: 5,
+        inputCacheRead: 0,
+        inputCacheCreation: 0,
+      });
+    });
+
+    it('yields thinking and tool_use from non-stream response', async () => {
+      const provider = createProvider();
+      (provider as any)._client.messages.create = vi.fn().mockResolvedValue({
+        id: 'msg_456',
+        content: [
+          { type: 'thinking', thinking: 'Let me think...', signature: 'sig_abc' },
+          { type: 'text', text: 'The answer is 4.' },
+          { type: 'tool_use', id: 'tool_1', name: 'add', input: { a: 2, b: 3 } },
+        ],
+        usage: { input_tokens: 15, output_tokens: 10, cache_read_input_tokens: 5 },
+      });
+
+      const stream = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'What is 2+3?' }], toolCalls: [] }],
+      );
+
+      const parts = [];
+      for await (const part of stream) {
+        parts.push(part);
+      }
+
+      expect(parts).toEqual([
+        { type: 'think', think: 'Let me think...', encrypted: 'sig_abc' },
+        { type: 'text', text: 'The answer is 4.' },
+        {
+          type: 'function',
+          id: 'tool_1',
+          function: { name: 'add', arguments: '{"a":2,"b":3}' },
+        },
+      ]);
+      expect(stream.usage).toEqual({
+        inputOther: 15,
+        output: 10,
+        inputCacheRead: 5,
+        inputCacheCreation: 0,
+      });
+    });
+  });
+
+  describe('stream response parsing', () => {
+    it('yields text delta from stream events', async () => {
+      const provider = createStreamProvider();
+      const stream = mockStream([
+        {
+          type: 'message_start',
+          message: {
+            id: 'msg_stream_001',
+            usage: { input_tokens: 10, cache_read_input_tokens: 3, cache_creation_input_tokens: 2 },
+          },
+        },
+        { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } },
+        { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'Hello' } },
+        { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: ' world' } },
+        { type: 'message_delta', delta: {}, usage: { output_tokens: 5 } },
+        { type: 'message_stop' },
+      ]);
+
+      (provider as any)._client.messages.stream = vi.fn().mockReturnValue(stream) as never;
+
+      const result = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+
+      const parts = await collectParts(result);
+
+      expect(parts).toEqual([
+        { type: 'text', text: '' },
+        { type: 'text', text: 'Hello' },
+        { type: 'text', text: ' world' },
+      ]);
+      expect(result.id).toBe('msg_stream_001');
+      expect(result.usage).toEqual({
+        inputOther: 10,
+        output: 5,
+        inputCacheRead: 3,
+        inputCacheCreation: 2,
+      });
+    });
+
+    it('yields thinking delta and signature from stream events', async () => {
+      const provider = createStreamProvider();
+      const stream = mockStream([
+        {
+          type: 'message_start',
+          message: { id: 'msg_stream_002', usage: { input_tokens: 20 } },
+        },
+        {
+          type: 'content_block_start',
+          index: 0,
+          content_block: { type: 'thinking', thinking: '' },
+        },
+        {
+          type: 'content_block_delta',
+          index: 0,
+          delta: { type: 'thinking_delta', thinking: 'Let me think' },
+        },
+        {
+          type: 'content_block_delta',
+          index: 0,
+          delta: { type: 'thinking_delta', thinking: ' about this' },
+        },
+        {
+          type: 'content_block_delta',
+          index: 0,
+          delta: { type: 'signature_delta', signature: 'sig_xyz' },
+        },
+        { type: 'content_block_start', index: 1, content_block: { type: 'text', text: '' } },
+        {
+          type: 'content_block_delta',
+          index: 1,
+          delta: { type: 'text_delta', text: 'The answer is 4.' },
+        },
+        { type: 'message_delta', delta: {}, usage: { output_tokens: 15 } },
+        { type: 'message_stop' },
+      ]);
+
+      (provider as any)._client.messages.stream = vi.fn().mockReturnValue(stream) as never;
+
+      const result = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] }],
+      );
+
+      const parts = await collectParts(result);
+
+      expect(parts).toEqual([
+        { type: 'think', think: '' },
+        { type: 'think', think: 'Let me think' },
+        { type: 'think', think: ' about this' },
+        { type: 'think', think: '', encrypted: 'sig_xyz' },
+        { type: 'text', text: '' },
+        { type: 'text', text: 'The answer is 4.' },
+      ]);
+      expect(result.id).toBe('msg_stream_002');
+      expect(result.usage).toEqual({
+        inputOther: 20,
+        output: 15,
+        inputCacheRead: 0,
+        inputCacheCreation: 0,
+      });
+    });
+
+    it('yields tool_use start and argument deltas from stream events', async () => {
+      const provider = createStreamProvider();
+      const stream = mockStream([
+        {
+          type: 'message_start',
+          message: { id: 'msg_stream_003', usage: { input_tokens: 15 } },
+        },
+        { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } },
+        {
+          type: 'content_block_delta',
+          index: 0,
+          delta: { type: 'text_delta', text: "I'll add those." },
+        },
+        {
+          type: 'content_block_start',
+          index: 1,
+          content_block: { type: 'tool_use', id: 'toolu_abc', name: 'add' },
+        },
+        {
+          type: 'content_block_delta',
+          index: 1,
+          delta: { type: 'input_json_delta', partial_json: '{"a":' },
+        },
+        {
+          type: 'content_block_delta',
+          index: 1,
+          delta: { type: 'input_json_delta', partial_json: '2,"b":3}' },
+        },
+        { type: 'message_delta', delta: {}, usage: { output_tokens: 8 } },
+        { type: 'message_stop' },
+      ]);
+
+      (provider as any)._client.messages.stream = vi.fn().mockReturnValue(stream) as never;
+
+      const result = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] }],
+      );
+
+      const parts = await collectParts(result);
+
+      expect(parts).toEqual([
+        { type: 'text', text: '' },
+        { type: 'text', text: "I'll add those." },
+        {
+          type: 'function',
+          id: 'toolu_abc',
+          function: { name: 'add', arguments: '' },
+          _streamIndex: 1,
+        },
+        { type: 'tool_call_part', argumentsPart: '{"a":', index: 1 },
+        { type: 'tool_call_part', argumentsPart: '2,"b":3}', index: 1 },
+      ]);
+      expect(result.id).toBe('msg_stream_003');
+    });
+
+    it('streaming: parallel tool_use blocks route input_json_delta by block index', async () => {
+      const provider = createStreamProvider();
+      const stream = mockStream([
+        {
+          type: 'message_start',
+          message: { id: 'msg_parallel_001', usage: { input_tokens: 10 } },
+        },
+        // Two tool_use blocks opened in order at index 0 and 1.
+        {
+          type: 'content_block_start',
+          index: 0,
+          content_block: { type: 'tool_use', id: 'toolu_a', name: 'tool_a', input: {} },
+        },
+        {
+          type: 'content_block_start',
+          index: 1,
+          content_block: { type: 'tool_use', id: 'toolu_b', name: 'tool_b', input: {} },
+        },
+        // Interleaved input_json_delta chunks across the two blocks.
+        {
+          type: 'content_block_delta',
+          index: 0,
+          delta: { type: 'input_json_delta', partial_json: '{"x":' },
+        },
+        {
+          type: 'content_block_delta',
+          index: 1,
+          delta: { type: 'input_json_delta', partial_json: '{"y":' },
+        },
+        {
+          type: 'content_block_delta',
+          index: 0,
+          delta: { type: 'input_json_delta', partial_json: '1}' },
+        },
+        {
+          type: 'content_block_delta',
+          index: 1,
+          delta: { type: 'input_json_delta', partial_json: '2}' },
+        },
+        { type: 'content_block_stop', index: 0 },
+        { type: 'content_block_stop', index: 1 },
+        {
+          type: 'message_delta',
+          delta: { stop_reason: 'tool_use' },
+          usage: { output_tokens: 5 },
+        },
+        { type: 'message_stop' },
+      ]);
+
+      (provider as any)._client.messages.stream = vi.fn().mockReturnValue(stream) as never;
+
+      const result = await provider.generate(
+        '',
+        [ADD_TOOL, MUL_TOOL],
+        [{ role: 'user', content: [{ type: 'text', text: 'Run both tools' }], toolCalls: [] }],
+      );
+
+      // Raw stream parts carry block index on both ToolCall and ToolCallPart.
+      // The Anthropic adapter absorbs `content_block_stop` for tool_use blocks
+      // internally — generate.ts infers completion from merge boundaries.
+      const parts = await collectParts(result);
+      expect(parts).toEqual([
+        {
+          type: 'function',
+          id: 'toolu_a',
+          function: { name: 'tool_a', arguments: '' },
+          _streamIndex: 0,
+        },
+        {
+          type: 'function',
+          id: 'toolu_b',
+          function: { name: 'tool_b', arguments: '' },
+          _streamIndex: 1,
+        },
+        { type: 'tool_call_part', argumentsPart: '{"x":', index: 0 },
+        { type: 'tool_call_part', argumentsPart: '{"y":', index: 1 },
+        { type: 'tool_call_part', argumentsPart: '1}', index: 0 },
+        { type: 'tool_call_part', argumentsPart: '2}', index: 1 },
+      ]);
+    });
+
+    it('streaming: generate() assembles parallel tool calls via index routing', async () => {
+      // End-to-end: verify that generate() routes interleaved deltas to the
+      // correct ToolCall using the block index, producing fully-assembled
+      // arguments per tool.
+      const { generate } = await import('#/generate');
+
+      const provider = createStreamProvider();
+      const stream = mockStream([
+        {
+          type: 'message_start',
+          message: { id: 'msg_parallel_002', usage: { input_tokens: 10 } },
+        },
+        {
+          type: 'content_block_start',
+          index: 0,
+          content_block: { type: 'tool_use', id: 'toolu_a', name: 'tool_a', input: {} },
+        },
+        {
+          type: 'content_block_start',
+          index: 1,
+          content_block: { type: 'tool_use', id: 'toolu_b', name: 'tool_b', input: {} },
+        },
+        {
+          type: 'content_block_delta',
+          index: 0,
+          delta: { type: 'input_json_delta', partial_json: '{"x":' },
+        },
+        {
+          type: 'content_block_delta',
+          index: 1,
+          delta: { type: 'input_json_delta', partial_json: '{"y":' },
+        },
+        {
+          type: 'content_block_delta',
+          index: 0,
+          delta: { type: 'input_json_delta', partial_json: '1}' },
+        },
+        {
+          type: 'content_block_delta',
+          index: 1,
+          delta: { type: 'input_json_delta', partial_json: '2}' },
+        },
+        { type: 'content_block_stop', index: 0 },
+        { type: 'content_block_stop', index: 1 },
+        {
+          type: 'message_delta',
+          delta: { stop_reason: 'tool_use' },
+          usage: { output_tokens: 5 },
+        },
+        { type: 'message_stop' },
+      ]);
+
+      (provider as any)._client.messages.stream = vi.fn().mockReturnValue(stream) as never;
+
+      const { message } = await generate(
+        provider,
+        '',
+        [ADD_TOOL, MUL_TOOL],
+        [{ role: 'user', content: [{ type: 'text', text: 'Run both' }], toolCalls: [] }],
+      );
+
+      expect(message.toolCalls.length).toBe(2);
+      expect(message.toolCalls[0]!.id).toBe('toolu_a');
+      expect(message.toolCalls[0]!.function.name).toBe('tool_a');
+      expect(message.toolCalls[0]!.function.arguments).toBe('{"x":1}');
+      expect(message.toolCalls[1]!.id).toBe('toolu_b');
+      expect(message.toolCalls[1]!.function.name).toBe('tool_b');
+      expect(message.toolCalls[1]!.function.arguments).toBe('{"y":2}');
+      // _streamIndex should be stripped from stored tool calls.
+      expect(
+        (message.toolCalls[0] as ToolCall & { _streamIndex?: number })._streamIndex,
+      ).toBeUndefined();
+      expect(
+        (message.toolCalls[1] as ToolCall & { _streamIndex?: number })._streamIndex,
+      ).toBeUndefined();
+    });
+
+    it('converts stream errors to ChatProviderError', async () => {
+      const provider = createStreamProvider();
+      const errorStream = {
+        async *[Symbol.asyncIterator]() {
+          yield {
+            type: 'message_start',
+            message: { id: 'msg_err', usage: { input_tokens: 5 } },
+          };
+          throw new Error('stream interrupted');
+        },
+      };
+
+      (provider as any)._client.messages.stream = vi.fn().mockReturnValue(errorStream) as never;
+
+      const result = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+
+      await expect(collectParts(result)).rejects.toThrow(ChatProviderError);
+    });
+
+    it('updates usage from message_delta with all fields', async () => {
+      const provider = createStreamProvider();
+      const stream = mockStream([
+        {
+          type: 'message_start',
+          message: {
+            id: 'msg_usage',
+            usage: {
+              input_tokens: 100,
+              cache_read_input_tokens: 50,
+              cache_creation_input_tokens: 20,
+            },
+          },
+        },
+        { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } },
+        { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'ok' } },
+        {
+          type: 'message_delta',
+          delta: {},
+          usage: {
+            output_tokens: 42,
+            cache_read_input_tokens: 55,
+            cache_creation_input_tokens: 25,
+            input_tokens: 105,
+          },
+        },
+        { type: 'message_stop' },
+      ]);
+
+      (provider as any)._client.messages.stream = vi.fn().mockReturnValue(stream) as never;
+
+      const result = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+
+      await collectParts(result);
+
+      expect(result.usage).toEqual({
+        inputOther: 105,
+        output: 42,
+        inputCacheRead: 55,
+        inputCacheCreation: 25,
+      });
+    });
+
+    it('redacted_thinking block yields encrypted think part', async () => {
+      const provider = createStreamProvider();
+      const stream = mockStream([
+        {
+          type: 'message_start',
+          message: { id: 'msg_redacted', usage: { input_tokens: 10 } },
+        },
+        {
+          type: 'content_block_start',
+          index: 0,
+          content_block: { type: 'redacted_thinking', data: 'enc_data_123' },
+        },
+        { type: 'content_block_start', index: 1, content_block: { type: 'text', text: '' } },
+        { type: 'content_block_delta', index: 1, delta: { type: 'text_delta', text: 'Done.' } },
+        { type: 'message_delta', delta: {}, usage: { output_tokens: 3 } },
+        { type: 'message_stop' },
+      ]);
+
+      (provider as any)._client.messages.stream = vi.fn().mockReturnValue(stream) as never;
+
+      const result = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] }],
+      );
+
+      const parts = await collectParts(result);
+
+      expect(parts).toEqual([
+        { type: 'think', think: '', encrypted: 'enc_data_123' },
+        { type: 'text', text: '' },
+        { type: 'text', text: 'Done.' },
+      ]);
+    });
+  });
+
+  describe('stream option', () => {
+    it('defaults to stream: true and calls messages.stream', async () => {
+      const provider = new AnthropicChatProvider({
+        model: 'k25',
+        apiKey: 'test-key',
+        defaultMaxTokens: 1024,
+      });
+
+      const stream = mockStream([
+        {
+          type: 'message_start',
+          message: { id: 'msg_default', usage: { input_tokens: 5 } },
+        },
+        { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } },
+        { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'Hi' } },
+        { type: 'message_stop' },
+      ]);
+
+      const streamFn = vi.fn().mockReturnValue(stream);
+      (provider as any)._client.messages.stream = streamFn as never;
+
+      const result = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+      await collectParts(result);
+
+      expect(streamFn).toHaveBeenCalledTimes(1);
+    });
+
+    it('stream: false calls messages.create', async () => {
+      const provider = createProvider(); // stream: false
+      const createFn = vi.fn().mockResolvedValue(makeAnthropicResponse());
+      (provider as any)._client.messages.create = createFn as never;
+
+      const result = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+      await collectParts(result);
+
+      expect(createFn).toHaveBeenCalledTimes(1);
+      // Verify stream: false is in the params
+      const params = createFn.mock.calls[0]![0] as Record<string, unknown>;
+      expect(params['stream']).toBe(false);
+    });
+  });
+
+  describe('modelParameters getter', () => {
+    it('returns model + generation kwargs', () => {
+      const provider = new AnthropicChatProvider({
+        model: 'k25',
+        apiKey: 'test-key',
+        defaultMaxTokens: 2048,
+      }).withGenerationKwargs({ temperature: 0.5 });
+
+      const params = provider.modelParameters;
+      expect(params).toMatchObject({
+        model: 'k25',
+        temperature: 0.5,
+      });
+    });
+  });
+
+  describe('generate without system prompt', () => {
+    it('omits the system array when systemPrompt is empty string', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      expect(body['system']).toBeUndefined();
+    });
+  });
+});
+
+describe('resolveDefaultMaxTokens', () => {
+  it('returns per-version Messages-API caps for known Claude 4 models', () => {
+    expect(resolveDefaultMaxTokens('claude-opus-4-7')).toBe(128000);
+    expect(resolveDefaultMaxTokens('claude-opus-4-6')).toBe(128000);
+    expect(resolveDefaultMaxTokens('claude-opus-4-5-20251101')).toBe(64000);
+    expect(resolveDefaultMaxTokens('claude-opus-4-1-20250805')).toBe(32000);
+    expect(resolveDefaultMaxTokens('claude-opus-4-20250514')).toBe(32000);
+    expect(resolveDefaultMaxTokens('claude-sonnet-4-6')).toBe(64000);
+    expect(resolveDefaultMaxTokens('claude-sonnet-4-5-20250929')).toBe(64000);
+    expect(resolveDefaultMaxTokens('claude-sonnet-4-20250514')).toBe(64000);
+    expect(resolveDefaultMaxTokens('claude-haiku-4-5-20251001')).toBe(64000);
+  });
+
+  it('returns the right ceiling for Claude 3.5 / 3.7 (both naming orders)', () => {
+    // version-first (legacy Anthropic id form)
+    expect(resolveDefaultMaxTokens('claude-3-5-sonnet-20240620')).toBe(8192);
+    expect(resolveDefaultMaxTokens('claude-3.5-sonnet')).toBe(8192);
+    expect(resolveDefaultMaxTokens('claude-3-7-sonnet')).toBe(8192);
+    expect(resolveDefaultMaxTokens('claude-3.7-sonnet')).toBe(8192);
+    // family-first (used throughout this repo's tests)
+    expect(resolveDefaultMaxTokens('claude-sonnet-3-7')).toBe(8192);
+    expect(resolveDefaultMaxTokens('claude-sonnet-3-5')).toBe(8192);
+    expect(resolveDefaultMaxTokens('claude-opus-3-5')).toBe(8192);
+    expect(resolveDefaultMaxTokens('claude-haiku-3-5')).toBe(8192);
+  });
+
+  it('returns 4096 for original Claude 3', () => {
+    expect(resolveDefaultMaxTokens('claude-3-opus-20240229')).toBe(4096);
+    expect(resolveDefaultMaxTokens('claude-3-sonnet-20240229')).toBe(4096);
+    expect(resolveDefaultMaxTokens('claude-3-haiku-20240307')).toBe(4096);
+  });
+
+  it('matches dotted version separators', () => {
+    expect(resolveDefaultMaxTokens('claude-opus-4.7')).toBe(128000);
+    expect(resolveDefaultMaxTokens('claude-opus-4.6')).toBe(128000);
+    expect(resolveDefaultMaxTokens('claude-sonnet-4.6')).toBe(64000);
+    expect(resolveDefaultMaxTokens('claude-haiku-4.5')).toBe(64000);
+  });
+
+  it('matches vendor-prefixed and suffixed third-party variants', () => {
+    // Bedrock / Vertex / proxy prefixes
+    expect(resolveDefaultMaxTokens('anthropic.claude-opus-4-7-v1:0')).toBe(128000);
+    expect(resolveDefaultMaxTokens('aws/claude-opus-4-7')).toBe(128000);
+    expect(resolveDefaultMaxTokens('vertex_ai/claude-opus-4-7')).toBe(128000);
+    expect(resolveDefaultMaxTokens('bedrock/anthropic.claude-opus-4-6-v1:0')).toBe(128000);
+    // OpenRouter / proxy-style prefixes the user has seen in the wild
+    expect(resolveDefaultMaxTokens('openrouter/claude-opus-4-7')).toBe(128000);
+    expect(resolveDefaultMaxTokens('online-claude-opus-4-7')).toBe(128000);
+    // Build / variant suffixes
+    expect(resolveDefaultMaxTokens('claude-opus-4-6-construct')).toBe(128000);
+    expect(resolveDefaultMaxTokens('claude-sonnet-4-5-20250929')).toBe(64000);
+    // Legacy id buried inside a vendor prefix
+    expect(resolveDefaultMaxTokens('anthropic.claude-3-5-sonnet-20240620-v1:0')).toBe(8192);
+  });
+
+  it('falls back to family-only ceiling for unknown minor versions', () => {
+    // Future opus-4-X release: minor not in table, falls back to opus-4 = 32000.
+    // Better to under-quote and fail loudly than over-quote a model we can't verify.
+    expect(resolveDefaultMaxTokens('claude-opus-4-10')).toBe(32000);
+    expect(resolveDefaultMaxTokens('claude-sonnet-4-9')).toBe(64000);
+    expect(resolveDefaultMaxTokens('claude-haiku-4-9')).toBe(64000);
+  });
+
+  it('matches case-insensitively', () => {
+    expect(resolveDefaultMaxTokens('CLAUDE-OPUS-4-7')).toBe(128000);
+    expect(resolveDefaultMaxTokens('Claude-Sonnet-4-6')).toBe(64000);
+    expect(resolveDefaultMaxTokens('Anthropic.Claude-Opus-4-7-v1:0')).toBe(128000);
+  });
+
+  it('honors the override for unknown models', () => {
+    expect(resolveDefaultMaxTokens('unknown-model', 12345)).toBe(12345);
+    expect(resolveDefaultMaxTokens('unknown-preview-001', 16000)).toBe(16000);
+  });
+
+  it('honors a lower override on known models (intentional truncation)', () => {
+    expect(resolveDefaultMaxTokens('claude-opus-4-7', 200)).toBe(200);
+    expect(resolveDefaultMaxTokens('claude-sonnet-4-6', 1024)).toBe(1024);
+    expect(resolveDefaultMaxTokens('claude-3-opus', 1000)).toBe(1000);
+  });
+
+  it('clamps an override above the documented ceiling for known models', () => {
+    expect(resolveDefaultMaxTokens('claude-opus-4-7', 999999)).toBe(128000);
+    expect(resolveDefaultMaxTokens('claude-sonnet-4-6', 200000)).toBe(64000);
+    expect(resolveDefaultMaxTokens('claude-3-opus', 99999)).toBe(4096);
+  });
+
+  it('falls back to 32000 when both lookup and override miss', () => {
+    expect(resolveDefaultMaxTokens('totally-unknown-model')).toBe(32000);
+    expect(resolveDefaultMaxTokens('gpt-5')).toBe(32000);
+  });
+
+  it('does not apply Claude ceilings to non-Claude ids that contain an opus/sonnet/haiku token', () => {
+    // No "claude" marker → fall through to the override / fallback rather
+    // than quietly applying a Claude ceiling to a fine-tune or unrelated model.
+    expect(resolveDefaultMaxTokens('vendor-opus-4-7-preview')).toBe(32000);
+    expect(resolveDefaultMaxTokens('vendor-opus-4-7-preview', 8000)).toBe(8000);
+  });
+});
+
+describe('AnthropicChatProvider constructor max_tokens', () => {
+  async function maxTokensFor(
+    model: string,
+    opts: Partial<{ defaultMaxTokens: number }> = {},
+  ): Promise<number> {
+    const provider = new AnthropicChatProvider({
+      model,
+      apiKey: 'test-key',
+      stream: false,
+      ...opts,
+    });
+    const history: Message[] = [
+      { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+    ];
+    const body = await captureRequestBody(provider, '', [], history);
+    return body['max_tokens'] as number;
+  }
+
+  it('uses per-version Messages-API caps for known Claude 4 models', async () => {
+    expect(await maxTokensFor('claude-opus-4-7')).toBe(128000);
+    expect(await maxTokensFor('claude-opus-4-6')).toBe(128000);
+    expect(await maxTokensFor('claude-opus-4-5')).toBe(64000);
+    expect(await maxTokensFor('claude-sonnet-4-6')).toBe(64000);
+    expect(await maxTokensFor('claude-haiku-4-5-20251001')).toBe(64000);
+  });
+
+  it('uses 4096 for Claude 3', async () => {
+    expect(await maxTokensFor('claude-3-opus-20240229')).toBe(4096);
+  });
+
+  it('honors defaultMaxTokens for unknown models', async () => {
+    expect(await maxTokensFor('unknown-model', { defaultMaxTokens: 12345 })).toBe(12345);
+  });
+
+  it('lets defaultMaxTokens lower the budget for known models', async () => {
+    expect(await maxTokensFor('claude-opus-4-7', { defaultMaxTokens: 200 })).toBe(200);
+  });
+
+  it('clamps defaultMaxTokens above the documented ceiling for known models', async () => {
+    expect(await maxTokensFor('claude-opus-4-7', { defaultMaxTokens: 999999 })).toBe(128000);
+  });
+});
diff --git a/packages/kosong/test/capability-providers.test.ts b/packages/kosong/test/capability-providers.test.ts
new file mode 100644
index 000000000..55f26d979
--- /dev/null
+++ b/packages/kosong/test/capability-providers.test.ts
@@ -0,0 +1,184 @@
+/**
+ * Per-provider `getCapability(model?)` table tests.
+ *
+ * For every provider:
+ *   - Known models return the capabilities the table declares for them.
+ *   - Unknown models return UNKNOWN_CAPABILITY (no throw) so the capability
+ *     gate stays non-fatal when the operator uses a model the provider has
+ *     not catalogued yet.
+ *
+ * Assertions stick to individual fields (image_in / video_in / …) rather
+ * than matching the whole object so future additions (e.g. new fields in
+ * `ModelCapability`) do not churn every row.
+ */
+
+import { UNKNOWN_CAPABILITY } from '#/capability';
+import { AnthropicChatProvider } from '#/providers/anthropic';
+import { GoogleGenAIChatProvider } from '#/providers/google-genai';
+import { KimiChatProvider } from '#/providers/kimi';
+import { OpenAILegacyChatProvider } from '#/providers/openai-legacy';
+import { OpenAIResponsesChatProvider } from '#/providers/openai-responses';
+import { describe, expect, it } from 'vitest';
+describe('KimiChatProvider.getCapability', () => {
+  function make(model: string): KimiChatProvider {
+    return new KimiChatProvider({ model, apiKey: 'test-key' });
+  }
+
+  it('does not infer capabilities from Kimi model names', () => {
+    for (const model of [
+      'kimi-for-coding',
+      'kimi-code',
+      'kimi-k2-turbo-preview',
+      'kimi-k2.5',
+      'kimi-thinking-preview',
+    ]) {
+      expect(make(model).getCapability()).toEqual(UNKNOWN_CAPABILITY);
+    }
+  });
+
+  it('explicit model arg overrides this.modelName', () => {
+    const provider = make('kimi-k2-turbo-preview');
+    expect(provider.getCapability('kimi-for-coding')).toEqual(UNKNOWN_CAPABILITY);
+  });
+
+  it('unknown Kimi model → UNKNOWN_CAPABILITY (no throw)', () => {
+    const cap = make('some-fake-model').getCapability();
+    expect(cap).toEqual(UNKNOWN_CAPABILITY);
+  });
+});
+describe('GoogleGenAIChatProvider.getCapability', () => {
+  function make(model: string): GoogleGenAIChatProvider {
+    return new GoogleGenAIChatProvider({ model, apiKey: 'test-key' });
+  }
+
+  it('gemini-1.5-pro → image_in + video_in + audio_in + tool_use', () => {
+    const cap = make('gemini-1.5-pro').getCapability();
+    expect(cap.image_in).toBe(true);
+    expect(cap.video_in).toBe(true);
+    expect(cap.audio_in).toBe(true);
+    expect(cap.tool_use).toBe(true);
+  });
+
+  it('gemini-1.5-flash → image_in + video_in + audio_in + tool_use', () => {
+    const cap = make('gemini-1.5-flash').getCapability();
+    expect(cap.image_in).toBe(true);
+    expect(cap.video_in).toBe(true);
+    expect(cap.audio_in).toBe(true);
+    expect(cap.tool_use).toBe(true);
+  });
+
+  it('gemini-2.0-flash → image_in + video_in + audio_in + tool_use', () => {
+    const cap = make('gemini-2.0-flash').getCapability();
+    expect(cap.image_in).toBe(true);
+    expect(cap.video_in).toBe(true);
+    expect(cap.audio_in).toBe(true);
+    expect(cap.tool_use).toBe(true);
+  });
+
+  it('unknown Gemini model → UNKNOWN_CAPABILITY (no throw)', () => {
+    const cap = make('gemini-not-real-xyz').getCapability();
+    expect(cap).toEqual(UNKNOWN_CAPABILITY);
+  });
+
+  it('non-gemini model name → UNKNOWN_CAPABILITY', () => {
+    const cap = make('claude-3-5-sonnet').getCapability();
+    expect(cap).toEqual(UNKNOWN_CAPABILITY);
+  });
+});
+describe('AnthropicChatProvider.getCapability', () => {
+  function make(model: string): AnthropicChatProvider {
+    return new AnthropicChatProvider({ model, apiKey: 'test-key', stream: false });
+  }
+
+  it('claude-3-5-sonnet → image_in + tool_use, audio_in=false', () => {
+    const cap = make('claude-3-5-sonnet').getCapability();
+    expect(cap.image_in).toBe(true);
+    expect(cap.tool_use).toBe(true);
+    expect(cap.audio_in).toBe(false);
+  });
+
+  it('claude-3-haiku → image_in + tool_use, audio_in=false, thinking=false', () => {
+    // Claude 3 Haiku supports vision (all Claude 3.x share vision support);
+    // Anthropic has no audio models; thinking is a Claude 4 feature.
+    const cap = make('claude-3-haiku').getCapability();
+    expect(cap.image_in).toBe(true);
+    expect(cap.tool_use).toBe(true);
+    expect(cap.audio_in).toBe(false);
+    expect(cap.thinking).toBe(false);
+  });
+
+  it('claude-opus-4 → image_in + thinking + tool_use', () => {
+    const cap = make('claude-opus-4').getCapability();
+    expect(cap.image_in).toBe(true);
+    expect(cap.thinking).toBe(true);
+    expect(cap.tool_use).toBe(true);
+  });
+
+  it('no Anthropic model supports audio_in', () => {
+    // Sanity: Anthropic has no audio-input models today. If one ships later
+    // and this fails, update the table — but make it a conscious decision.
+    for (const m of ['claude-3-5-sonnet', 'claude-3-haiku', 'claude-opus-4']) {
+      expect(make(m).getCapability().audio_in).toBe(false);
+    }
+  });
+
+  it('unknown Anthropic model → UNKNOWN_CAPABILITY', () => {
+    const cap = make('claude-not-real').getCapability();
+    expect(cap).toEqual(UNKNOWN_CAPABILITY);
+  });
+});
+describe('OpenAILegacyChatProvider.getCapability', () => {
+  function make(model: string): OpenAILegacyChatProvider {
+    return new OpenAILegacyChatProvider({ model, apiKey: 'test-key' });
+  }
+
+  it('gpt-4o → image_in + tool_use', () => {
+    const cap = make('gpt-4o').getCapability();
+    expect(cap.image_in).toBe(true);
+    expect(cap.tool_use).toBe(true);
+  });
+
+  it('gpt-3.5-turbo → image_in=false, tool_use=true', () => {
+    const cap = make('gpt-3.5-turbo').getCapability();
+    expect(cap.image_in).toBe(false);
+    expect(cap.tool_use).toBe(true);
+  });
+
+  it('o1 → thinking=true, tool_use=true', () => {
+    const cap = make('o1').getCapability();
+    expect(cap.thinking).toBe(true);
+    expect(cap.tool_use).toBe(true);
+  });
+
+  it('unknown OpenAI-legacy model → UNKNOWN_CAPABILITY', () => {
+    const cap = make('gpt-mystery').getCapability();
+    expect(cap).toEqual(UNKNOWN_CAPABILITY);
+  });
+});
+describe('OpenAIResponsesChatProvider.getCapability', () => {
+  function make(model: string): OpenAIResponsesChatProvider {
+    return new OpenAIResponsesChatProvider({ model, apiKey: 'test-key' });
+  }
+
+  it('gpt-4.1 → image_in + tool_use (Responses flagship)', () => {
+    const cap = make('gpt-4.1').getCapability();
+    expect(cap.image_in).toBe(true);
+    expect(cap.tool_use).toBe(true);
+  });
+
+  it('o1 → thinking=true, tool_use=true', () => {
+    const cap = make('o1').getCapability();
+    expect(cap.thinking).toBe(true);
+    expect(cap.tool_use).toBe(true);
+  });
+
+  it('o3-mini → thinking=true', () => {
+    const cap = make('o3-mini').getCapability();
+    expect(cap.thinking).toBe(true);
+  });
+
+  it('unknown Responses model → UNKNOWN_CAPABILITY', () => {
+    const cap = make('gpt-mystery').getCapability();
+    expect(cap).toEqual(UNKNOWN_CAPABILITY);
+  });
+});
diff --git a/packages/kosong/test/capability.test.ts b/packages/kosong/test/capability.test.ts
new file mode 100644
index 000000000..910ce0b9b
--- /dev/null
+++ b/packages/kosong/test/capability.test.ts
@@ -0,0 +1,63 @@
+/**
+ * `ModelCapability` type and `UNKNOWN_CAPABILITY` default — pure
+ * type/helper layer. Provider-specific `getCapability` tables live in
+ * `capability-providers.test.ts`.
+ */
+
+import { UNKNOWN_CAPABILITY, isUnknownCapability, type ModelCapability } from '#/capability';
+import { describe, expect, it } from 'vitest';
+
+describe('ModelCapability / UNKNOWN_CAPABILITY', () => {
+  it('UNKNOWN_CAPABILITY has all boolean fields false', () => {
+    expect(UNKNOWN_CAPABILITY.image_in).toBe(false);
+    expect(UNKNOWN_CAPABILITY.video_in).toBe(false);
+    expect(UNKNOWN_CAPABILITY.audio_in).toBe(false);
+    expect(UNKNOWN_CAPABILITY.thinking).toBe(false);
+    expect(UNKNOWN_CAPABILITY.tool_use).toBe(false);
+  });
+
+  it('UNKNOWN_CAPABILITY.max_context_tokens is 0 (unknown)', () => {
+    expect(UNKNOWN_CAPABILITY.max_context_tokens).toBe(0);
+  });
+
+  it('accepts a well-formed ModelCapability literal (type guard)', () => {
+    const cap: ModelCapability = {
+      image_in: true,
+      video_in: false,
+      audio_in: false,
+      thinking: true,
+      tool_use: true,
+      max_context_tokens: 128_000,
+    };
+    expect(cap.image_in).toBe(true);
+    expect(cap.max_context_tokens).toBe(128_000);
+  });
+
+  it('UNKNOWN_CAPABILITY is read-only (frozen or otherwise immutable)', () => {
+    // Defensive: future code should not be able to mutate the shared default.
+    // We accept either Object.isFrozen() or a thrown TypeError on mutation
+    // attempt (strict mode). Either way, the observed value afterwards must
+    // still be the conservative default.
+    const beforeImage = UNKNOWN_CAPABILITY.image_in;
+    try {
+      (UNKNOWN_CAPABILITY as unknown as { image_in: boolean }).image_in = true;
+    } catch {
+      // frozen in strict mode — fine
+    }
+    expect(UNKNOWN_CAPABILITY.image_in).toBe(beforeImage);
+    expect(UNKNOWN_CAPABILITY.image_in).toBe(false);
+  });
+
+  it('detects copied UNKNOWN_CAPABILITY objects by structure', () => {
+    const copiedUnknown: ModelCapability = {
+      image_in: false,
+      video_in: false,
+      audio_in: false,
+      thinking: false,
+      tool_use: false,
+      max_context_tokens: 0,
+    };
+    expect(isUnknownCapability(UNKNOWN_CAPABILITY)).toBe(true);
+    expect(isUnknownCapability(copiedUnknown)).toBe(true);
+  });
+});
diff --git a/packages/kosong/test/e2e/abort-cleanup.test.ts b/packages/kosong/test/e2e/abort-cleanup.test.ts
new file mode 100644
index 000000000..2ff5ea427
--- /dev/null
+++ b/packages/kosong/test/e2e/abort-cleanup.test.ts
@@ -0,0 +1,265 @@
+import { generate } from '#/generate';
+import type { Message, StreamedMessagePart } from '#/message';
+import { extractText } from '#/message';
+import type { ChatProvider, GenerateOptions, StreamedMessage, ThinkingEffort } from '#/provider';
+import { SimpleToolset, toolOk } from '../fixtures/simple-toolset';
+import type { ToolReturnValue } from '../fixtures/simple-toolset';
+import { step } from '../fixtures/step';
+import type { Tool } from '#/tool';
+import type { JsonValue } from '../fixtures/args-validator';
+import type { TokenUsage } from '#/usage';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * When an in-flight step() is aborted, tool handlers must settle, the provider
+ * stream must be released, and the same provider must remain reusable.
+ */
+interface StreamStats {
+  started: number;
+  completed: number;
+  abandoned: number;
+}
+
+/**
+ * Produce a fresh deep copy of the StreamedMessagePart template so that
+ * the generate() pipeline's in-place merge can never leak mutations
+ * across iterator invocations.
+ */
+function clonePart(part: StreamedMessagePart): StreamedMessagePart {
+  if (part.type === 'function') {
+    return {
+      type: 'function',
+      id: part.id,
+      function: { name: part.function.name, arguments: part.function.arguments },
+      ...(part.extras !== undefined ? { extras: { ...part.extras } } : {}),
+      _streamIndex: part._streamIndex,
+    };
+  }
+  if (part.type === 'tool_call_part') {
+    return {
+      type: 'tool_call_part',
+      argumentsPart: part.argumentsPart,
+      index: part.index,
+    };
+  }
+  // ContentPart shapes (text, think, *_url) are shallow-safe.
+  return { ...part } as StreamedMessagePart;
+}
+
+function createTrackingStream(
+  parts: StreamedMessagePart[],
+  stats: StreamStats,
+  delayMs: number,
+): StreamedMessage {
+  return {
+    get id(): string | null {
+      return null;
+    },
+    get usage(): TokenUsage | null {
+      return null;
+    },
+    finishReason: null,
+    rawFinishReason: null,
+    async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+      stats.started++;
+      let finishedNormally = false;
+      try {
+        for (const part of parts) {
+          if (delayMs > 0) {
+            await new Promise<void>((r) => setTimeout(r, delayMs));
+          }
+          yield clonePart(part);
+        }
+        finishedNormally = true;
+        stats.completed++;
+      } finally {
+        if (!finishedNormally) {
+          stats.abandoned++;
+        }
+      }
+    },
+  };
+}
+
+class TrackingProvider implements ChatProvider {
+  readonly name: string = 'tracking';
+  readonly modelName: string = 'tracking';
+  readonly thinkingEffort: ThinkingEffort | null = null;
+  readonly stats: StreamStats = { started: 0, completed: 0, abandoned: 0 };
+
+  private readonly _parts: StreamedMessagePart[];
+  private readonly _delayMs: number;
+
+  constructor(parts: StreamedMessagePart[], delayMs: number) {
+    this._parts = parts;
+    this._delayMs = delayMs;
+  }
+
+  async generate(
+    _systemPrompt: string,
+    _tools: Tool[],
+    _history: Message[],
+    _options?: GenerateOptions,
+  ): Promise<StreamedMessage> {
+    return createTrackingStream(this._parts, this.stats, this._delayMs);
+  }
+
+  withThinking(_effort: ThinkingEffort): ChatProvider {
+    return this;
+  }
+}
+describe('e2e: abort cleanup', () => {
+  it('aborting step() mid-stream awaits pending tool handlers before rethrowing', async () => {
+    // The provider emits a tool_call header, a few argument delta chunks,
+    // then a text delta. We abort in onMessagePart after seeing a couple
+    // of parts. Because the tool call is only dispatched on stream-drain,
+    // no tool handler will be in flight at abort time; but we still want
+    // to verify that subsequent generate() calls on the same provider
+    // succeed — i.e. the provider has no residual internal state.
+    const parts: StreamedMessagePart[] = [
+      { type: 'text', text: 'a' },
+      { type: 'text', text: 'b' },
+      { type: 'text', text: 'c' },
+      { type: 'text', text: 'd' },
+      { type: 'text', text: 'e' },
+    ];
+    const provider = new TrackingProvider(parts, 5);
+
+    const toolset = new SimpleToolset();
+
+    let partsSeen = 0;
+    const controller = new AbortController();
+    await expect(
+      step(
+        provider,
+        '',
+        toolset,
+        [],
+        {
+          onMessagePart: (): void => {
+            partsSeen++;
+            if (partsSeen === 2) {
+              controller.abort();
+            }
+          },
+        },
+        { signal: controller.signal },
+      ),
+    ).rejects.toThrow();
+
+    // Stream iterator started once and was abandoned (not completed).
+    expect(provider.stats.started).toBe(1);
+    expect(provider.stats.completed).toBe(0);
+
+    // The same provider instance must be reusable.
+    const result = await generate(provider, '', [], []);
+    expect(extractText(result.message)).toBe('abcde');
+    expect(provider.stats.started).toBe(2);
+    expect(provider.stats.completed).toBe(1);
+  });
+
+  it('aborting step() while a tool handler is running still awaits the handler before rethrowing (no dangling promise)', async () => {
+    // Provider drains synchronously, then the tool handler sleeps long.
+    // We trigger the abort signal AFTER step() has already progressed
+    // into calling toolResults(). This test verifies that even if the
+    // caller only awaits the outer error path, the tool-handler
+    // Promise does not get leaked: it completes (or rejects) before
+    // step() propagates the failure.
+    const parts: StreamedMessagePart[] = [
+      {
+        type: 'function',
+        id: 'tc_slow',
+        function: { name: 'slow', arguments: '{}' },
+      },
+    ];
+    const provider = new TrackingProvider(parts, 0);
+
+    let handlerStarted = false;
+    let handlerFinished = false;
+
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'slow', description: 'slow', parameters: { type: 'object', properties: {} } },
+      async (_args: JsonValue): Promise<ToolReturnValue> => {
+        handlerStarted = true;
+        await new Promise<void>((r) => setTimeout(r, 40));
+        handlerFinished = true;
+        return toolOk({ output: 'slow-done' });
+      },
+    );
+
+    // step() completes the generate phase (single tool_call, no args),
+    // then returns with a toolResults() function. Await the results.
+    const result = await step(provider, '', toolset, []);
+    expect(result.toolCalls).toHaveLength(1);
+    const toolResults = await result.toolResults();
+    expect(toolResults).toHaveLength(1);
+    expect(handlerStarted).toBe(true);
+    expect(handlerFinished).toBe(true);
+    expect(toolResults[0]!.returnValue.output).toBe('slow-done');
+  });
+
+  it('pre-aborted signal rejects without starting the stream iterator', async () => {
+    const provider = new TrackingProvider([{ type: 'text', text: 'should not reach' }], 0);
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(
+      generate(provider, '', [], [], undefined, { signal: controller.signal }),
+    ).rejects.toThrow();
+
+    // Stream was never drained.
+    expect(provider.stats.completed).toBe(0);
+    // The generate impl may or may not invoke provider.generate() (it
+    // checks signal first and throws). Either way, if it started the
+    // iterator it must also have abandoned it.
+    if (provider.stats.started > 0) {
+      expect(provider.stats.completed).toBe(0);
+    }
+
+    // Followup call must still work.
+    const result = await generate(provider, '', [], []);
+    expect(extractText(result.message)).toBe('should not reach');
+  });
+
+  it('a rejected generate() does not leave the toolset / toolResultPromises in an inconsistent state for a fresh step() call', async () => {
+    // First step(): aborts mid-stream.
+    // Second step(): no tool calls, should succeed cleanly.
+    const abortParts: StreamedMessagePart[] = [
+      { type: 'text', text: 'x' },
+      { type: 'text', text: 'y' },
+      { type: 'text', text: 'z' },
+    ];
+    const provider = new TrackingProvider(abortParts, 5);
+
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'unused', description: 'unused', parameters: { type: 'object', properties: {} } },
+      async (): Promise<ToolReturnValue> => toolOk({ output: 'never-called' }),
+    );
+
+    const controller = new AbortController();
+    let hits = 0;
+    await expect(
+      step(
+        provider,
+        '',
+        toolset,
+        [],
+        {
+          onMessagePart: (): void => {
+            hits++;
+            if (hits === 1) controller.abort();
+          },
+        },
+        { signal: controller.signal },
+      ),
+    ).rejects.toThrow();
+
+    // Now reuse the toolset in a second, unrelated step().
+    const textOnly = new TrackingProvider([{ type: 'text', text: 'ok' }], 0);
+    const result = await step(textOnly, '', toolset, []);
+    expect(result.toolCalls).toHaveLength(0);
+    expect(extractText(result.message)).toBe('ok');
+  });
+});
diff --git a/packages/kosong/test/e2e/abort-signal.test.ts b/packages/kosong/test/e2e/abort-signal.test.ts
new file mode 100644
index 000000000..e7829ec14
--- /dev/null
+++ b/packages/kosong/test/e2e/abort-signal.test.ts
@@ -0,0 +1,239 @@
+import { generate } from '#/generate';
+import type { Message, StreamedMessagePart } from '#/message';
+import { extractText } from '#/message';
+import type { ChatProvider, GenerateOptions, StreamedMessage, ThinkingEffort } from '#/provider';
+import { SimpleToolset, toolOk } from '../fixtures/simple-toolset';
+import type { ToolReturnValue } from '../fixtures/simple-toolset';
+import { step } from '../fixtures/step';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+import { describe, expect, it } from 'vitest';
+function createMockStream(
+  parts: StreamedMessagePart[],
+  opts?: { id?: string; usage?: TokenUsage; delayMs?: number },
+): StreamedMessage {
+  return {
+    get id(): string | null {
+      return opts?.id ?? null;
+    },
+    get usage(): TokenUsage | null {
+      return opts?.usage ?? null;
+    },
+    finishReason: null,
+    rawFinishReason: null,
+    async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+      for (const part of parts) {
+        if (opts?.delayMs !== undefined && opts.delayMs > 0) {
+          await new Promise<void>((r) => setTimeout(r, opts.delayMs));
+        }
+        yield part;
+      }
+    },
+  };
+}
+
+function createDelayedProvider(parts: StreamedMessagePart[], delayMs: number): ChatProvider {
+  return {
+    name: 'delayed',
+    modelName: 'delayed-model',
+    thinkingEffort: null,
+    async generate(
+      _systemPrompt: string,
+      _tools: Tool[],
+      _history: Message[],
+      _options?: GenerateOptions,
+    ): Promise<StreamedMessage> {
+      return createMockStream(parts, { delayMs });
+    },
+    withThinking(_effort: ThinkingEffort): ChatProvider {
+      return this;
+    },
+  };
+}
+
+function createMockProvider(stream: StreamedMessage): ChatProvider {
+  return {
+    name: 'mock',
+    modelName: 'mock-model',
+    thinkingEffort: null,
+    async generate(
+      _systemPrompt: string,
+      _tools: Tool[],
+      _history: Message[],
+      _options?: GenerateOptions,
+    ): Promise<StreamedMessage> {
+      return stream;
+    },
+    withThinking(_effort: ThinkingEffort): ChatProvider {
+      return this;
+    },
+  };
+}
+describe('e2e: abort signal', () => {
+  describe('abort during generate streaming loop', () => {
+    it('aborting in onMessagePart callback causes AbortError', async () => {
+      const controller = new AbortController();
+      let callbackCount = 0;
+
+      const provider = createDelayedProvider(
+        [
+          { type: 'text', text: 'chunk1' },
+          { type: 'text', text: 'chunk2' },
+          { type: 'text', text: 'chunk3' },
+        ],
+        5,
+      );
+
+      const promise = generate(
+        provider,
+        '',
+        [],
+        [],
+        {
+          onMessagePart(_part: StreamedMessagePart): void {
+            callbackCount++;
+            if (callbackCount >= 2) {
+              controller.abort();
+            }
+          },
+        },
+        { signal: controller.signal },
+      );
+
+      await expect(promise).rejects.toThrow('The operation was aborted.');
+    });
+  });
+
+  describe('abort during step tool execution', () => {
+    it('aborting during tool handler propagates to step', async () => {
+      const controller = new AbortController();
+
+      // Provider that emits a tool call
+      const toolCallStream = createMockStream([
+        { type: 'text', text: 'Calling tool...' },
+        {
+          type: 'function',
+          id: 'tool-1',
+          function: { name: 'slow-tool', arguments: '{}' },
+        },
+      ]);
+
+      const provider = createMockProvider(toolCallStream);
+
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'slow-tool', description: 'A slow tool', parameters: {} },
+        async (): Promise<ToolReturnValue> => {
+          // Abort while tool is "executing"
+          controller.abort();
+          await new Promise<void>((r) => setTimeout(r, 50));
+          return toolOk({ output: 'done' });
+        },
+      );
+
+      // step() itself should not throw from the abort since tool execution
+      // is async and the generate phase completed. The abort signal affects
+      // the generate loop, not the tool handler directly.
+      const result = await step(provider, '', toolset, [], undefined, {
+        signal: controller.signal,
+      });
+
+      // The step completed (generate finished before abort was triggered in
+      // the tool handler). The tool result should still resolve.
+      const toolResults = await result.toolResults();
+      expect(toolResults).toHaveLength(1);
+    });
+  });
+
+  describe('pre-aborted signal', () => {
+    it('immediately rejects without calling provider', async () => {
+      const controller = new AbortController();
+      controller.abort(); // pre-abort
+
+      const provider: ChatProvider = {
+        name: 'should-not-be-called',
+        modelName: 'should-not-be-called',
+        thinkingEffort: null,
+        async generate(
+          _systemPrompt: string,
+          _tools: Tool[],
+          _history: Message[],
+          _options?: GenerateOptions,
+        ): Promise<StreamedMessage> {
+          return createMockStream([{ type: 'text', text: 'should not reach' }]);
+        },
+        withThinking(_effort: ThinkingEffort): ChatProvider {
+          return this;
+        },
+      };
+
+      // With a pre-aborted signal, the generate loop should abort on the
+      // first iteration check. The provider.generate is called (because
+      // the abort check happens inside the for-await loop), but the stream
+      // should be interrupted immediately.
+      const promise = generate(provider, '', [], [], undefined, {
+        signal: controller.signal,
+      });
+
+      await expect(promise).rejects.toThrow();
+
+      // Even if the provider was called (it creates the stream), the
+      // iteration should abort on the very first signal check.
+    });
+  });
+
+  describe('abort does not affect other concurrent generate calls', () => {
+    it('aborting one generate does not affect another concurrent one', async () => {
+      const controllerA = new AbortController();
+
+      // Provider A: slow, will be aborted
+      const providerA = createDelayedProvider(
+        [
+          { type: 'text', text: 'A-chunk1' },
+          { type: 'text', text: 'A-chunk2' },
+          { type: 'text', text: 'A-chunk3' },
+          { type: 'text', text: 'A-chunk4' },
+        ],
+        10,
+      );
+
+      // Provider B: fast, should complete normally
+      const providerB = createDelayedProvider(
+        [
+          { type: 'text', text: 'B-chunk1' },
+          { type: 'text', text: 'B-chunk2' },
+        ],
+        2,
+      );
+
+      let aCallbackCount = 0;
+      const promiseA = generate(
+        providerA,
+        '',
+        [],
+        [],
+        {
+          onMessagePart(_part: StreamedMessagePart): void {
+            aCallbackCount++;
+            if (aCallbackCount >= 2) {
+              controllerA.abort();
+            }
+          },
+        },
+        { signal: controllerA.signal },
+      );
+
+      const promiseB = generate(providerB, '', [], []);
+
+      // A should fail, B should succeed
+      const [resultA, resultB] = await Promise.allSettled([promiseA, promiseB]);
+
+      expect(resultA.status).toBe('rejected');
+      expect(resultB.status).toBe('fulfilled');
+
+      if (resultB.status === 'fulfilled') {
+        expect(extractText(resultB.value.message)).toBe('B-chunk1B-chunk2');
+      }
+    });
+  });
+});
diff --git a/packages/kosong/test/e2e/anthropic-adapter.test.ts b/packages/kosong/test/e2e/anthropic-adapter.test.ts
new file mode 100644
index 000000000..a64517aac
--- /dev/null
+++ b/packages/kosong/test/e2e/anthropic-adapter.test.ts
@@ -0,0 +1,216 @@
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import { AnthropicChatProvider } from '#/providers/anthropic';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+import Anthropic from '@anthropic-ai/sdk';
+import { describe, expect, it } from 'vitest';
+
+import { createFakeProviderHarness } from './fake-provider-harness';
+
+function anthropicSseFrame(event: string, payload: unknown): string {
+  return `event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`;
+}
+
+async function collectParts(
+  streamedMessage: AsyncIterable<StreamedMessagePart>,
+): Promise<StreamedMessagePart[]> {
+  const parts: StreamedMessagePart[] = [];
+  for await (const part of streamedMessage) {
+    parts.push(part);
+  }
+  return parts;
+}
+
+function makeAnthropicProvider(): AnthropicChatProvider {
+  return new AnthropicChatProvider({
+    model: 'k25',
+    apiKey: 'test-key',
+    defaultMaxTokens: 1024,
+    stream: true,
+  });
+}
+
+const ADD_TOOL: Tool = {
+  name: 'add',
+  description: 'Add two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+const MUL_TOOL: Tool = {
+  name: 'multiply',
+  description: 'Multiply two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+describe('e2e: Anthropic adapter bridge', () => {
+  it('sends the adapter request body and parses streamed text, tool use, and usage', async () => {
+    const harness = await createFakeProviderHarness();
+    try {
+      harness.route('POST', '/v1/messages', async (request, reply) => {
+        const body = request.bodyJson as Record<string, unknown>;
+        expect(request.pathname).toBe('/v1/messages');
+        expect(request.headers['anthropic-beta']).toContain('interleaved-thinking-2025-05-14');
+        expect(request.headers['x-api-key']).toBe('test-key');
+        expect(body['model']).toBe('k25');
+        expect(body['system']).toEqual([
+          { type: 'text', text: 'You are helpful.', cache_control: { type: 'ephemeral' } },
+        ]);
+        expect(body['tools']).toEqual([
+          {
+            name: 'add',
+            description: 'Add two integers.',
+            input_schema: ADD_TOOL.parameters,
+          },
+          {
+            name: 'multiply',
+            description: 'Multiply two integers.',
+            input_schema: MUL_TOOL.parameters,
+            cache_control: { type: 'ephemeral' },
+          },
+        ]);
+        expect(body['messages']).toEqual([
+          {
+            role: 'user',
+            content: [
+              { type: 'text', text: 'Inspect the image.' },
+              {
+                type: 'image',
+                source: { type: 'url', url: 'https://example.com/image.png' },
+                cache_control: { type: 'ephemeral' },
+              },
+            ],
+          },
+        ]);
+
+        const stream = [
+          anthropicSseFrame('message_start', {
+            type: 'message_start',
+            message: {
+              id: 'msg_1',
+              type: 'message',
+              role: 'assistant',
+              model: 'k25',
+              content: [],
+              stop_reason: null,
+              stop_sequence: null,
+              usage: {
+                input_tokens: 19,
+                output_tokens: 0,
+                cache_read_input_tokens: 2,
+                cache_creation_input_tokens: 1,
+              },
+            },
+          }),
+          anthropicSseFrame('content_block_start', {
+            type: 'content_block_start',
+            index: 0,
+            content_block: { type: 'text', text: 'Hello from Anthropic' },
+          }),
+          anthropicSseFrame('content_block_stop', {
+            type: 'content_block_stop',
+            index: 0,
+          }),
+          anthropicSseFrame('content_block_start', {
+            type: 'content_block_start',
+            index: 1,
+            content_block: {
+              type: 'tool_use',
+              id: 'toolu_1',
+              name: 'add',
+              input: {},
+            },
+          }),
+          anthropicSseFrame('content_block_delta', {
+            type: 'content_block_delta',
+            index: 1,
+            delta: { type: 'input_json_delta', partial_json: '{"a":2' },
+          }),
+          anthropicSseFrame('content_block_delta', {
+            type: 'content_block_delta',
+            index: 1,
+            delta: { type: 'input_json_delta', partial_json: ',"b":3}' },
+          }),
+          anthropicSseFrame('content_block_stop', {
+            type: 'content_block_stop',
+            index: 1,
+          }),
+          anthropicSseFrame('message_delta', {
+            type: 'message_delta',
+            delta: { type: 'message_delta', stop_reason: 'tool_use', stop_sequence: null },
+            usage: {
+              input_tokens: 19,
+              output_tokens: 7,
+              cache_read_input_tokens: 2,
+              cache_creation_input_tokens: 1,
+            },
+          }),
+          anthropicSseFrame('message_stop', { type: 'message_stop' }),
+        ].join('');
+
+        await reply.raw(200, stream, {
+          'content-type': 'text/event-stream; charset=utf-8',
+          'cache-control': 'no-cache',
+          connection: 'keep-alive',
+        });
+      });
+
+      const provider = makeAnthropicProvider();
+      (provider as any)._client = new Anthropic({
+        apiKey: 'test-key',
+        baseURL: harness.baseUrl,
+      });
+
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'Inspect the image.' },
+            { type: 'image_url', imageUrl: { url: 'https://example.com/image.png' } },
+          ],
+          toolCalls: [],
+        },
+      ];
+
+      const stream = await provider.generate('You are helpful.', [ADD_TOOL, MUL_TOOL], history);
+      const parts = await collectParts(stream);
+
+      expect(parts).toEqual([
+        { type: 'text', text: 'Hello from Anthropic' },
+        {
+          type: 'function',
+          id: 'toolu_1',
+          function: { name: 'add', arguments: '' },
+          _streamIndex: 1,
+        } satisfies ToolCall,
+        { type: 'tool_call_part', argumentsPart: '{"a":2', index: 1 },
+        { type: 'tool_call_part', argumentsPart: ',"b":3}', index: 1 },
+      ]);
+
+      expect(stream.id).toBe('msg_1');
+      expect(stream.usage).toEqual({
+        inputOther: 19,
+        output: 7,
+        inputCacheRead: 2,
+        inputCacheCreation: 1,
+      } satisfies TokenUsage);
+
+      expect(harness.requests).toHaveLength(1);
+    } finally {
+      await harness.close();
+    }
+  });
+});
diff --git a/packages/kosong/test/e2e/cross-provider-consistency.test.ts b/packages/kosong/test/e2e/cross-provider-consistency.test.ts
new file mode 100644
index 000000000..3d16560a9
--- /dev/null
+++ b/packages/kosong/test/e2e/cross-provider-consistency.test.ts
@@ -0,0 +1,173 @@
+import { EchoChatProvider, ScriptedEchoChatProvider } from '../fixtures/echo-provider';
+import { generate } from '#/generate';
+import type { Message, StreamedMessagePart, TextPart } from '#/message';
+import { createUserMessage, extractText } from '#/message';
+import { MockChatProvider } from '../fixtures/mock-provider';
+import type { ChatProvider, ThinkingEffort } from '#/provider';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Verifies that MockChatProvider, EchoChatProvider, and
+ * ScriptedEchoChatProvider conform to the same ChatProvider contract.
+ */
+/** Build a one-text-part mock provider that emits "hello world". */
+function buildMockProvider(text: string = 'hello world'): MockChatProvider {
+  const parts: StreamedMessagePart[] = [{ type: 'text', text } satisfies TextPart];
+  return new MockChatProvider(parts);
+}
+
+function buildEchoProvider(): EchoChatProvider {
+  return new EchoChatProvider();
+}
+
+function buildScriptedEchoProvider(scripts: string[]): ScriptedEchoChatProvider {
+  return new ScriptedEchoChatProvider(scripts);
+}
+describe('e2e: cross-provider consistency', () => {
+  describe('interface compatibility', () => {
+    it('all test providers are assignable to ChatProvider', () => {
+      const mock: ChatProvider = buildMockProvider();
+      const echo: ChatProvider = buildEchoProvider();
+      const scripted: ChatProvider = buildScriptedEchoProvider(['text: hi']);
+
+      // Sanity: identity fields exist on all of them.
+      for (const p of [mock, echo, scripted]) {
+        expect(typeof p.name).toBe('string');
+        expect(typeof p.modelName).toBe('string');
+        expect(p.thinkingEffort === null || typeof p.thinkingEffort === 'string').toBe(true);
+      }
+    });
+
+    it('all test providers expose the same ChatProvider method shape', () => {
+      const providers: ChatProvider[] = [
+        buildMockProvider(),
+        buildEchoProvider(),
+        buildScriptedEchoProvider(['text: hi']),
+      ];
+
+      for (const p of providers) {
+        expect(typeof p.generate).toBe('function');
+        expect(typeof p.withThinking).toBe('function');
+      }
+    });
+  });
+
+  describe('withThinking returns a new, independent instance', () => {
+    const efforts: ThinkingEffort[] = ['off', 'low', 'medium', 'high'];
+
+    it('MockChatProvider.withThinking returns a distinct instance', () => {
+      const base = buildMockProvider();
+      for (const effort of efforts) {
+        const clone = base.withThinking(effort);
+        expect(clone).not.toBe(base);
+        // Base must not mutate — its thinkingEffort stays null.
+        expect(base.thinkingEffort).toBeNull();
+      }
+    });
+
+    it('EchoChatProvider.withThinking returns a distinct instance', () => {
+      const base = buildEchoProvider();
+      for (const effort of efforts) {
+        const clone = base.withThinking(effort);
+        expect(clone).not.toBe(base);
+        expect(base.thinkingEffort).toBeNull();
+      }
+    });
+
+    it('ScriptedEchoChatProvider.withThinking returns a distinct instance', () => {
+      const base = buildScriptedEchoProvider(['text: a', 'text: b', 'text: c']);
+      const clone = base.withThinking('high');
+      expect(clone).not.toBe(base);
+      expect(base.thinkingEffort).toBeNull();
+    });
+
+    it('withThinking does not touch the original provider across multiple effort values', () => {
+      const base = buildMockProvider();
+      const clones = efforts.map((e) => base.withThinking(e));
+      // All clones are distinct from each other and from base.
+      const allInstances = [base, ...clones];
+      const unique = new Set(allInstances);
+      expect(unique.size).toBe(allInstances.length);
+    });
+  });
+
+  describe('generate() consumes all test providers identically', () => {
+    it('MockChatProvider + EchoChatProvider + ScriptedEchoChatProvider produce the same text via generate', async () => {
+      const text = 'consistent hello world';
+
+      // Mock
+      const mock = new MockChatProvider([{ type: 'text', text } satisfies TextPart]);
+      const mockResult = await generate(mock, '', [], [createUserMessage('noop')]);
+
+      // Echo: text lives in the last user message
+      const echo = buildEchoProvider();
+      const echoHistory: Message[] = [createUserMessage(`text: ${text}`)];
+      const echoResult = await generate(echo, '', [], echoHistory);
+
+      // Scripted echo: provider ignores history, consumes its queue
+      const scripted = buildScriptedEchoProvider([`text: ${text}`]);
+      const scriptedResult = await generate(scripted, '', [], [createUserMessage('go')]);
+
+      for (const r of [mockResult, echoResult, scriptedResult]) {
+        expect(r.message.role).toBe('assistant');
+        expect(extractText(r.message)).toBe(text);
+        expect(r.message.toolCalls).toEqual([]);
+      }
+    });
+  });
+
+  describe('all test providers honor AbortSignal before the provider call', () => {
+    it('pre-aborted signal rejects through generate() for every test provider', async () => {
+      const providers: { name: string; provider: ChatProvider; history: Message[] }[] = [
+        {
+          name: 'mock',
+          provider: new MockChatProvider([
+            { type: 'text', text: 'should not emit' } satisfies TextPart,
+          ]),
+          history: [createUserMessage('noop')],
+        },
+        {
+          name: 'echo',
+          provider: buildEchoProvider(),
+          history: [createUserMessage('text: should not emit')],
+        },
+        {
+          name: 'scripted',
+          provider: buildScriptedEchoProvider(['text: should not emit']),
+          history: [createUserMessage('go')],
+        },
+      ];
+
+      for (const { provider, history } of providers) {
+        const controller = new AbortController();
+        controller.abort();
+        await expect(
+          generate(provider, '', [], history, undefined, { signal: controller.signal }),
+        ).rejects.toThrow();
+      }
+    });
+  });
+
+  describe('ScriptedEchoChatProvider respects withThinking queue semantics', () => {
+    it('withThinking returns a new instance sharing the remaining script queue', async () => {
+      const base = buildScriptedEchoProvider(['text: first', 'text: second', 'text: third']);
+
+      // Advance the base cursor by one call.
+      const first = await generate(base, '', [], [createUserMessage('go')]);
+      expect(extractText(first.message)).toBe('first');
+
+      const clone = base.withThinking('low');
+      expect(clone).not.toBe(base);
+
+      // Clone should see the REMAINING scripts (second, third).
+      const c1 = await generate(clone, '', [], [createUserMessage('go')]);
+      expect(extractText(c1.message)).toBe('second');
+      const c2 = await generate(clone, '', [], [createUserMessage('go')]);
+      expect(extractText(c2.message)).toBe('third');
+
+      // The base queue advances independently of the clone.
+      const second = await generate(base, '', [], [createUserMessage('go')]);
+      expect(extractText(second.message)).toBe('second');
+    });
+  });
+});
diff --git a/packages/kosong/test/e2e/error-recovery.test.ts b/packages/kosong/test/e2e/error-recovery.test.ts
new file mode 100644
index 000000000..0af05c548
--- /dev/null
+++ b/packages/kosong/test/e2e/error-recovery.test.ts
@@ -0,0 +1,416 @@
+import { APIConnectionError, APIStatusError, ChatProviderError } from '#/errors';
+import { generate } from '#/generate';
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import type { ChatProvider, StreamedMessage, ThinkingEffort } from '#/provider';
+import { SimpleToolset, toolOk } from '../fixtures/simple-toolset';
+import type { ToolReturnValue } from '../fixtures/simple-toolset';
+import { step } from '../fixtures/step';
+import type { Tool } from '#/tool';
+import type { JsonValue } from '../fixtures/args-validator';
+import type { TokenUsage } from '#/usage';
+import { describe, expect, it } from 'vitest';
+function createMockStream(
+  parts: StreamedMessagePart[],
+  opts?: { id?: string; usage?: TokenUsage },
+): StreamedMessage {
+  return {
+    get id(): string | null {
+      return opts?.id ?? null;
+    },
+    get usage(): TokenUsage | null {
+      return opts?.usage ?? null;
+    },
+    finishReason: null,
+    rawFinishReason: null,
+    async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+      for (const part of parts) {
+        yield part;
+      }
+    },
+  };
+}
+
+/** Provider whose generate() throws the given error. */
+function createThrowingProvider(error: Error): ChatProvider {
+  return {
+    name: 'throwing',
+    modelName: 'throwing',
+    thinkingEffort: null,
+    async generate(
+      _systemPrompt: string,
+      _tools: Tool[],
+      _history: Message[],
+    ): Promise<StreamedMessage> {
+      throw error;
+    },
+    withThinking(_effort: ThinkingEffort): ChatProvider {
+      return this;
+    },
+  };
+}
+
+/** Provider whose generate() succeeds, but the stream throws mid-iteration. */
+function createStreamErrorProvider(partsBefore: StreamedMessagePart[], error: Error): ChatProvider {
+  return {
+    name: 'stream-error',
+    modelName: 'stream-error',
+    thinkingEffort: null,
+    async generate(
+      _systemPrompt: string,
+      _tools: Tool[],
+      _history: Message[],
+    ): Promise<StreamedMessage> {
+      return {
+        get id(): string | null {
+          return null;
+        },
+        get usage(): TokenUsage | null {
+          return null;
+        },
+        finishReason: null,
+        rawFinishReason: null,
+        async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+          for (const part of partsBefore) {
+            yield part;
+          }
+          throw error;
+        },
+      };
+    },
+    withThinking(_effort: ThinkingEffort): ChatProvider {
+      return this;
+    },
+  };
+}
+
+function createMockProvider(stream: StreamedMessage): ChatProvider {
+  return {
+    name: 'mock',
+    modelName: 'mock',
+    thinkingEffort: null,
+    async generate(
+      _systemPrompt: string,
+      _tools: Tool[],
+      _history: Message[],
+    ): Promise<StreamedMessage> {
+      return stream;
+    },
+    withThinking(_effort: ThinkingEffort): ChatProvider {
+      return this;
+    },
+  };
+}
+describe('e2e: error recovery', () => {
+  describe('provider generate() throws', () => {
+    it('APIStatusError propagates through step()', async () => {
+      const error = new APIStatusError(429, 'Rate limited', 'req-123');
+      const provider = createThrowingProvider(error);
+      const toolset = new SimpleToolset();
+
+      await expect(
+        step(provider, '', toolset, [
+          { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+        ]),
+      ).rejects.toThrow(APIStatusError);
+
+      try {
+        await step(provider, '', toolset, [
+          { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+        ]);
+        expect.unreachable('should have thrown');
+      } catch (error: unknown) {
+        expect(error).toBeInstanceOf(APIStatusError);
+        const apiError = error as APIStatusError;
+        expect(apiError.statusCode).toBe(429);
+        expect(apiError.requestId).toBe('req-123');
+      }
+    });
+
+    it('APIConnectionError propagates through step()', async () => {
+      const error = new APIConnectionError('Connection reset');
+      const provider = createThrowingProvider(error);
+      const toolset = new SimpleToolset();
+
+      await expect(
+        step(provider, '', toolset, [
+          { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+        ]),
+      ).rejects.toThrow(APIConnectionError);
+    });
+
+    it('ChatProviderError propagates through generate()', async () => {
+      const error = new ChatProviderError('Unknown provider error');
+      const provider = createThrowingProvider(error);
+
+      await expect(generate(provider, '', [], [])).rejects.toThrow(ChatProviderError);
+    });
+
+    it('non-ChatProviderError also propagates through step()', async () => {
+      const error = new TypeError('Something unexpected');
+      const provider = createThrowingProvider(error);
+      const toolset = new SimpleToolset();
+
+      await expect(
+        step(provider, '', toolset, [
+          { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+        ]),
+      ).rejects.toThrow(TypeError);
+    });
+  });
+
+  describe('stream throws mid-iteration', () => {
+    it('error after some text parts propagates correctly', async () => {
+      const provider = createStreamErrorProvider(
+        [{ type: 'text', text: 'Partial response...' }],
+        new APIConnectionError('Stream disconnected'),
+      );
+      const toolset = new SimpleToolset();
+
+      await expect(
+        step(provider, '', toolset, [
+          { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+        ]),
+      ).rejects.toThrow(APIConnectionError);
+    });
+
+    it('error after tool call part propagates and cleans up pending tool promises', async () => {
+      // When the stream yields a ToolCall then immediately throws, the ToolCall
+      // is still in the pending-part buffer and has NOT been flushed/dispatched
+      // via onToolCall. This is correct behavior: generate() only fires
+      // onToolCall when a new non-mergeable part arrives or at stream end.
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc-1',
+        function: { name: 'slow_tool', arguments: '{}' },
+      };
+
+      const provider = createStreamErrorProvider(
+        [tc],
+        new APIConnectionError('Stream cut mid-tool'),
+      );
+
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'slow_tool', description: 'Slow', parameters: {} },
+        async (): Promise<ToolReturnValue> => {
+          return toolOk({ output: 'done' });
+        },
+      );
+
+      await expect(
+        step(provider, '', toolset, [
+          { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+        ]),
+      ).rejects.toThrow(APIConnectionError);
+    });
+
+    it('generic Error mid-stream propagates', async () => {
+      const provider = createStreamErrorProvider(
+        [{ type: 'text', text: 'start' }],
+        new Error('Random network failure'),
+      );
+
+      await expect(generate(provider, '', [], [])).rejects.toThrow('Random network failure');
+    });
+  });
+
+  describe('tool execution errors', () => {
+    it('tool handler throws → toolRuntimeError in results, other tools unaffected', async () => {
+      const tc1: ToolCall = {
+        type: 'function',
+        id: 'tc-ok',
+        function: { name: 'good_tool', arguments: '{}' },
+      };
+      const tc2: ToolCall = {
+        type: 'function',
+        id: 'tc-fail',
+        function: { name: 'bad_tool', arguments: '{}' },
+      };
+      const tc3: ToolCall = {
+        type: 'function',
+        id: 'tc-ok-2',
+        function: { name: 'good_tool', arguments: '{}' },
+      };
+
+      const stream = createMockStream([tc1, tc2, tc3]);
+      const provider = createMockProvider(stream);
+
+      const completionOrder: string[] = [];
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'good_tool', description: 'Works', parameters: {} },
+        async (
+          _args: JsonValue,
+          // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        ): Promise<ToolReturnValue> => {
+          completionOrder.push('good');
+          return toolOk({ output: 'success' });
+        },
+      );
+      toolset.add(
+        { name: 'bad_tool', description: 'Crashes', parameters: {} },
+        async (): Promise<ToolReturnValue> => {
+          completionOrder.push('bad');
+          throw new Error('Tool timeout simulation');
+        },
+      );
+
+      const result = await step(provider, '', toolset, []);
+      const toolResults = await result.toolResults();
+
+      expect(toolResults).toHaveLength(3);
+      // First tool: success
+      expect(toolResults[0]!.returnValue.isError).toBe(false);
+      expect(toolResults[0]!.returnValue.output).toBe('success');
+      // Second tool: runtime error
+      expect(toolResults[1]!.returnValue.isError).toBe(true);
+      expect(toolResults[1]!.returnValue.message).toBe(
+        'Error running tool: Tool timeout simulation',
+      );
+      // Third tool: success
+      expect(toolResults[2]!.returnValue.isError).toBe(false);
+      expect(toolResults[2]!.returnValue.output).toBe('success');
+    });
+
+    it('tool not found → toolNotFoundError in results', async () => {
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc-missing',
+        function: { name: 'nonexistent_tool', arguments: '{}' },
+      };
+
+      const stream = createMockStream([{ type: 'text', text: 'calling' }, tc]);
+      const provider = createMockProvider(stream);
+
+      const toolset = new SimpleToolset();
+      // No tools registered
+
+      const result = await step(provider, '', toolset, []);
+      const toolResults = await result.toolResults();
+
+      expect(toolResults).toHaveLength(1);
+      expect(toolResults[0]!.returnValue.isError).toBe(true);
+      expect(toolResults[0]!.returnValue.message).toContain('nonexistent_tool');
+    });
+
+    it('tool with invalid JSON arguments → toolParseError', async () => {
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc-bad-json',
+        function: { name: 'my_tool', arguments: '{invalid json' },
+      };
+
+      const stream = createMockStream([{ type: 'text', text: 'calling' }, tc]);
+      const provider = createMockProvider(stream);
+
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'my_tool', description: 'A tool', parameters: {} },
+        async (): Promise<ToolReturnValue> => toolOk({ output: 'ok' }),
+      );
+
+      const result = await step(provider, '', toolset, []);
+      const toolResults = await result.toolResults();
+
+      expect(toolResults).toHaveLength(1);
+      expect(toolResults[0]!.returnValue.isError).toBe(true);
+      // The message should describe a parse error
+      expect(toolResults[0]!.returnValue.display).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ type: 'brief', text: 'Invalid arguments' }),
+        ]),
+      );
+    });
+
+    it('tool throws non-Error value → still wrapped as runtime error', async () => {
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc-str-throw',
+        function: { name: 'throws_string', arguments: '{}' },
+      };
+
+      const stream = createMockStream([tc]);
+      const provider = createMockProvider(stream);
+
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'throws_string', description: 'Throws a string', parameters: {} },
+        async (): Promise<ToolReturnValue> => {
+          // eslint-disable-next-line @typescript-eslint/only-throw-error, no-throw-literal
+          throw 'a raw string error';
+        },
+      );
+
+      const result = await step(provider, '', toolset, []);
+      const toolResults = await result.toolResults();
+
+      expect(toolResults).toHaveLength(1);
+      expect(toolResults[0]!.returnValue.isError).toBe(true);
+      expect(toolResults[0]!.returnValue.message).toBe('Error running tool: a raw string error');
+    });
+  });
+
+  describe('provider error before tool dispatch', () => {
+    it('tool handlers are never invoked when the stream errors mid-way', async () => {
+      // Tool dispatch is deferred until after the stream has fully drained.
+      // A mid-stream error therefore means zero tools are dispatched.
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc-cleanup',
+        function: { name: 'cleanup_test', arguments: '{}' },
+      };
+
+      let handlerInvoked = false;
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'cleanup_test', description: 'Test cleanup', parameters: {} },
+        async (): Promise<ToolReturnValue> => {
+          handlerInvoked = true;
+          return toolOk({ output: 'done' });
+        },
+      );
+
+      // Custom provider: yields tc, then text, then throws mid-stream.
+      const provider: ChatProvider = {
+        name: 'cleanup-test',
+        modelName: 'cleanup-test',
+        thinkingEffort: null,
+        async generate(
+          _systemPrompt: string,
+          _tools: Tool[],
+          _history: Message[],
+        ): Promise<StreamedMessage> {
+          return {
+            get id(): string | null {
+              return null;
+            },
+            get usage(): TokenUsage | null {
+              return null;
+            },
+            finishReason: null,
+            rawFinishReason: null,
+            async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+              yield tc;
+              yield { type: 'text', text: 'some text' };
+              throw new ChatProviderError('Stream failure after tool dispatch');
+            },
+          };
+        },
+        withThinking(_effort: ThinkingEffort): ChatProvider {
+          return this;
+        },
+      };
+
+      await expect(
+        step(provider, '', toolset, [
+          { role: 'user', content: [{ type: 'text', text: 'go' }], toolCalls: [] },
+        ]),
+      ).rejects.toThrow(ChatProviderError);
+
+      // Give any in-flight microtasks a chance to run; the handler must
+      // still not have been invoked.
+      await new Promise<void>((r) => setTimeout(r, 50));
+      expect(handlerInvoked).toBe(false);
+    });
+  });
+});
diff --git a/packages/kosong/test/e2e/extreme-streams.test.ts b/packages/kosong/test/e2e/extreme-streams.test.ts
new file mode 100644
index 000000000..379eb5f0e
--- /dev/null
+++ b/packages/kosong/test/e2e/extreme-streams.test.ts
@@ -0,0 +1,182 @@
+import { generate } from '#/generate';
+import type { StreamedMessagePart } from '#/message';
+import { extractText } from '#/message';
+import { MockChatProvider } from '../fixtures/mock-provider';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Stresses stream merging for quadratic merges, routing regressions, accumulator
+ * leaks, and tool-call argument cross-contamination.
+ */
+
+describe('e2e: extreme streaming scenarios', () => {
+  describe('TextPart delta merging at scale', () => {
+    it('10000 TextPart deltas merge into a single content[0]', async () => {
+      const count = 10000;
+      const parts: StreamedMessagePart[] = [];
+      for (let i = 0; i < count; i++) {
+        parts.push({ type: 'text', text: 'a' });
+      }
+
+      const provider = new MockChatProvider(parts);
+      const t0 = Date.now();
+      const result = await generate(provider, '', [], []);
+      const elapsed = Date.now() - t0;
+
+      // Single merged text part.
+      expect(result.message.content).toHaveLength(1);
+      expect(result.message.content[0]!.type).toBe('text');
+
+      const text = extractText(result.message);
+      expect(text.length).toBe(count);
+      // Every character is 'a'.
+      expect(text).toBe('a'.repeat(count));
+
+      // This should complete quickly — a quadratic merge would turn this
+      // into tens of seconds. Give plenty of slack for CI (5s).
+      expect(elapsed).toBeLessThan(5000);
+    });
+
+    it('5000 TextPart deltas interleaved with ThinkParts produce exactly two merged blocks each', async () => {
+      // Alternating blocks: [text-batch, think-batch, text-batch, think-batch].
+      const parts: StreamedMessagePart[] = [];
+      for (let i = 0; i < 2500; i++) parts.push({ type: 'text', text: 'x' });
+      for (let i = 0; i < 2500; i++) parts.push({ type: 'think', think: 'y' });
+      for (let i = 0; i < 2500; i++) parts.push({ type: 'text', text: 'x' });
+      for (let i = 0; i < 2500; i++) parts.push({ type: 'think', think: 'y' });
+
+      const provider = new MockChatProvider(parts);
+      const result = await generate(provider, '', [], []);
+
+      // 4 merged blocks (2 text, 2 think) appearing in order.
+      expect(result.message.content).toHaveLength(4);
+      expect(result.message.content[0]!.type).toBe('text');
+      expect(result.message.content[1]!.type).toBe('think');
+      expect(result.message.content[2]!.type).toBe('text');
+      expect(result.message.content[3]!.type).toBe('think');
+
+      // Each block carries exactly 2500 characters.
+      const c0 = result.message.content[0]!;
+      const c2 = result.message.content[2]!;
+      expect(c0.type === 'text' && c0.text.length === 2500).toBe(true);
+      expect(c2.type === 'text' && c2.text.length === 2500).toBe(true);
+
+      const c1 = result.message.content[1]!;
+      const c3 = result.message.content[3]!;
+      expect(c1.type === 'think' && c1.think.length === 2500).toBe(true);
+      expect(c3.type === 'think' && c3.think.length === 2500).toBe(true);
+    });
+  });
+
+  describe('parallel tool call streaming at scale', () => {
+    it('100 parallel tool calls with interleaved arg deltas route to the correct call', async () => {
+      const n = 100;
+      const parts: StreamedMessagePart[] = [];
+
+      // Headers for 100 tool calls.
+      for (let i = 0; i < n; i++) {
+        parts.push({
+          type: 'function',
+          id: `tc_${i}`,
+          function: { name: 'f', arguments: null },
+          _streamIndex: i,
+        });
+      }
+
+      // Interleaved arg deltas: three passes (open → body → close),
+      // each pass walks 0..n-1, so deltas for tc_0 are at positions
+      // 0, n, 2n within the interleaved arg stream.
+      for (let i = 0; i < n; i++) {
+        parts.push({ type: 'tool_call_part', argumentsPart: '{"i":', index: i });
+      }
+      for (let i = 0; i < n; i++) {
+        parts.push({ type: 'tool_call_part', argumentsPart: String(i), index: i });
+      }
+      for (let i = 0; i < n; i++) {
+        parts.push({ type: 'tool_call_part', argumentsPart: '}', index: i });
+      }
+
+      const provider = new MockChatProvider(parts);
+      const result = await generate(provider, '', [], []);
+
+      // 100 tool calls emitted, in stream order, with fully-assembled
+      // arguments and NO cross-contamination.
+      expect(result.message.toolCalls).toHaveLength(n);
+      for (let i = 0; i < n; i++) {
+        const tc = result.message.toolCalls[i]!;
+        expect(tc.id).toBe(`tc_${i}`);
+        expect(tc.function.name).toBe('f');
+        expect(tc.function.arguments).toBe(`{"i":${i}}`);
+        // _streamIndex must be stripped from the stored ToolCall.
+        expect(tc).not.toHaveProperty('_streamIndex');
+      }
+    });
+
+    it('one tool call with 10,000 argument deltas assembles a 1MB+ argument string', async () => {
+      // 10,000 deltas × 120-char chunk = ~1.2MB of tool arguments.
+      const chunk = 'x'.repeat(120);
+      const parts: StreamedMessagePart[] = [
+        {
+          type: 'function',
+          id: 'tc_big',
+          function: { name: 'writeBlob', arguments: '{"blob":"' },
+          _streamIndex: 0,
+        },
+      ];
+      for (let i = 0; i < 10000; i++) {
+        parts.push({ type: 'tool_call_part', argumentsPart: chunk, index: 0 });
+      }
+      parts.push({ type: 'tool_call_part', argumentsPart: '"}', index: 0 });
+
+      const provider = new MockChatProvider(parts);
+      const t0 = Date.now();
+      const result = await generate(provider, '', [], []);
+      const elapsed = Date.now() - t0;
+
+      expect(result.message.toolCalls).toHaveLength(1);
+      const args = result.message.toolCalls[0]!.function.arguments;
+      if (args === null) {
+        throw new Error('Expected assembled tool-call arguments');
+      }
+      expect(args.length).toBeGreaterThan(1_200_000);
+      const parsed = JSON.parse(args) as { blob: string };
+      expect(parsed.blob.length).toBe(120 * 10000);
+      expect(parsed.blob[0]).toBe('x');
+
+      // Plenty of slack — this should complete well under a few seconds.
+      expect(elapsed).toBeLessThan(5000);
+    });
+
+    it('100 interleaved parallel tool calls where the first delta batch arrives in reverse order', async () => {
+      // Reversed first batch hits the "unknown index → fall through" path
+      // before all headers have been seen. We specifically want to test
+      // that AFTER all headers are flushed, the remaining deltas still
+      // route correctly.
+      const n = 100;
+      const parts: StreamedMessagePart[] = [];
+
+      for (let i = 0; i < n; i++) {
+        parts.push({
+          type: 'function',
+          id: `tc_${i}`,
+          function: { name: 'f', arguments: null },
+          _streamIndex: i,
+        });
+      }
+      // Deltas in REVERSE order, each carries the full JSON at once.
+      for (let i = n - 1; i >= 0; i--) {
+        parts.push({ type: 'tool_call_part', argumentsPart: `{"idx":${i}}`, index: i });
+      }
+
+      const provider = new MockChatProvider(parts);
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.toolCalls).toHaveLength(n);
+      for (let i = 0; i < n; i++) {
+        const tc = result.message.toolCalls[i]!;
+        // Assembled args preserve the per-call routing contract.
+        expect(tc.function.arguments).toBe(`{"idx":${i}}`);
+      }
+    });
+  });
+});
diff --git a/packages/kosong/test/e2e/fake-provider-harness.test.ts b/packages/kosong/test/e2e/fake-provider-harness.test.ts
new file mode 100644
index 000000000..191c0fc78
--- /dev/null
+++ b/packages/kosong/test/e2e/fake-provider-harness.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+
+import { createFakeProviderHarness, readSseData } from './fake-provider-harness';
+
+class ToyJsonAdapter {
+  constructor(private readonly baseUrl: string) {}
+
+  async request(prompt: string): Promise<{ echo: unknown }> {
+    const response = await fetch(`${this.baseUrl}/json`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ prompt }),
+    });
+    if (!response.ok) {
+      throw new Error(`unexpected status ${response.status}`);
+    }
+    return (await response.json()) as { echo: unknown };
+  }
+}
+
+class ToySseAdapter {
+  constructor(private readonly baseUrl: string) {}
+
+  async request(prompt: string): Promise<string> {
+    const response = await fetch(`${this.baseUrl}/stream`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ prompt }),
+    });
+    if (!response.ok) {
+      throw new Error(`unexpected status ${response.status}`);
+    }
+    const frames = await readSseData(response);
+    return frames
+      .map((frame) => JSON.parse(frame) as { delta: string })
+      .map((part) => part.delta)
+      .join('');
+  }
+}
+
+describe('e2e: fake provider harness', () => {
+  it('captures JSON requests and serves JSON responses', async () => {
+    const harness = await createFakeProviderHarness();
+    try {
+      harness.route('POST', '/json', async (request, reply) => {
+        expect(request.method).toBe('POST');
+        expect(request.pathname).toBe('/json');
+        expect(request.bodyJson).toEqual({ prompt: 'hello' });
+        expect(request.headers['content-type']).toContain('application/json');
+
+        await reply.json(200, {
+          id: 'json-1',
+          ok: true,
+          echo: request.bodyJson,
+        });
+      });
+
+      const adapter = new ToyJsonAdapter(harness.baseUrl);
+      const result = await adapter.request('hello');
+      expect(result).toEqual({
+        id: 'json-1',
+        ok: true,
+        echo: { prompt: 'hello' },
+      });
+
+      expect(harness.requests).toHaveLength(1);
+      expect(harness.requests[0]!.pathname).toBe('/json');
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('streams SSE frames and lets clients consume them in order', async () => {
+    const harness = await createFakeProviderHarness();
+    try {
+      harness.route('POST', '/stream', async (_request, reply) => {
+        await reply.sseJson(200, [{ delta: 'hel' }, { delta: 'lo' }]);
+      });
+
+      const adapter = new ToySseAdapter(harness.baseUrl);
+      const text = await adapter.request('stream');
+      expect(text).toBe('hello');
+
+      expect(harness.requests).toHaveLength(1);
+      expect(harness.requests[0]!.pathname).toBe('/stream');
+    } finally {
+      await harness.close();
+    }
+  });
+});
diff --git a/packages/kosong/test/e2e/fake-provider-harness.ts b/packages/kosong/test/e2e/fake-provider-harness.ts
new file mode 100644
index 000000000..e265965a7
--- /dev/null
+++ b/packages/kosong/test/e2e/fake-provider-harness.ts
@@ -0,0 +1,265 @@
+import * as node_http from 'node:http';
+import { TextDecoder } from 'node:util';
+
+export interface FakeProviderRequest {
+  readonly index: number;
+  readonly method: string;
+  readonly url: string;
+  readonly pathname: string;
+  readonly search: string;
+  readonly headers: Record<string, string>;
+  readonly bodyText: string;
+  readonly bodyJson: unknown;
+}
+
+export interface FakeProviderReply {
+  json(status: number, body: unknown, headers?: Record<string, string>): Promise<void>;
+  text(status: number, body: string, headers?: Record<string, string>): Promise<void>;
+  raw(status: number, body: string | Uint8Array, headers?: Record<string, string>): Promise<void>;
+  sseLines(status: number, lines: string[], headers?: Record<string, string>): Promise<void>;
+  sseJson(status: number, events: unknown[], headers?: Record<string, string>): Promise<void>;
+}
+
+export type FakeProviderRouteHandler = (
+  request: FakeProviderRequest,
+  reply: FakeProviderReply,
+) => void | Promise<void>;
+
+export interface FakeProviderHarness {
+  readonly baseUrl: string;
+  readonly requests: FakeProviderRequest[];
+  route(method: string, pathname: string, handler: FakeProviderRouteHandler): void;
+  close(): Promise<void>;
+}
+
+function normalizeHeaders(headers: node_http.IncomingHttpHeaders): Record<string, string> {
+  const normalized: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (value === undefined) {
+      continue;
+    }
+    normalized[key.toLowerCase()] = Array.isArray(value) ? value.join(', ') : value;
+  }
+  return normalized;
+}
+
+function withDefaultHeaders(
+  headers: Record<string, string>,
+  contentType: string,
+): Record<string, string> {
+  return {
+    'content-type': contentType,
+    ...headers,
+  };
+}
+
+function buildSseLines(events: unknown[]): string[] {
+  const lines: string[] = [];
+  for (const event of events) {
+    lines.push(`data: ${JSON.stringify(event)}`);
+    lines.push('');
+  }
+  lines.push('data: [DONE]');
+  lines.push('');
+  return lines;
+}
+
+export async function readSseData(response: Response): Promise<string[]> {
+  if (response.body === null) {
+    return [];
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  const events: string[] = [];
+
+  const flushBlock = (block: string): void => {
+    const dataLines = block
+      .split('\n')
+      .map((line) => line.trimEnd())
+      .filter((line) => line.startsWith('data:'));
+
+    if (dataLines.length === 0) {
+      return;
+    }
+
+    const payload = dataLines.map((line) => line.slice('data:'.length).trimStart()).join('\n');
+    if (payload !== '[DONE]') {
+      events.push(payload);
+    }
+  };
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    buffer += decoder.decode(value, { stream: true });
+    while (buffer.includes('\n\n')) {
+      const splitIndex = buffer.indexOf('\n\n');
+      const block = buffer.slice(0, splitIndex);
+      buffer = buffer.slice(splitIndex + 2);
+      flushBlock(block);
+    }
+  }
+
+  buffer += decoder.decode();
+  const trailingBlocks = buffer.split('\n\n');
+  for (const block of trailingBlocks) {
+    if (block.trim().length > 0) {
+      flushBlock(block);
+    }
+  }
+
+  return events;
+}
+
+export async function createFakeProviderHarness(): Promise<FakeProviderHarness> {
+  const requests: FakeProviderRequest[] = [];
+  const routes = new Map<string, FakeProviderRouteHandler>();
+
+  const server = node_http.createServer((req, res) => {
+    void (async () => {
+      const method = (req.method ?? 'GET').toUpperCase();
+      const requestUrl = new URL(req.url ?? '/', 'http://127.0.0.1');
+      const key = `${method} ${requestUrl.pathname}`;
+      const route = routes.get(key);
+
+      const chunks: Buffer[] = [];
+      for await (const chunk of req) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      }
+      const bodyText = Buffer.concat(chunks).toString('utf8');
+      let bodyJson: unknown = null;
+      if (bodyText.length > 0) {
+        try {
+          bodyJson = JSON.parse(bodyText) as unknown;
+        } catch {
+          bodyJson = null;
+        }
+      }
+
+      const request: FakeProviderRequest = {
+        index: requests.length,
+        method,
+        url: requestUrl.toString(),
+        pathname: requestUrl.pathname,
+        search: requestUrl.search,
+        headers: normalizeHeaders(req.headers),
+        bodyText,
+        bodyJson,
+      };
+      requests.push(request);
+
+      let responded = false;
+      const reply: FakeProviderReply = {
+        async json(
+          status: number,
+          body: unknown,
+          headers: Record<string, string> = {},
+        ): Promise<void> {
+          if (responded) {
+            return;
+          }
+          responded = true;
+          res.writeHead(status, withDefaultHeaders(headers, 'application/json; charset=utf-8'));
+          res.end(JSON.stringify(body));
+        },
+        async text(
+          status: number,
+          body: string,
+          headers: Record<string, string> = {},
+        ): Promise<void> {
+          if (responded) {
+            return;
+          }
+          responded = true;
+          res.writeHead(status, withDefaultHeaders(headers, 'text/plain; charset=utf-8'));
+          res.end(body);
+        },
+        async raw(
+          status: number,
+          body: string | Uint8Array,
+          headers: Record<string, string> = {},
+        ): Promise<void> {
+          if (responded) {
+            return;
+          }
+          responded = true;
+          res.writeHead(status, headers);
+          res.end(body);
+        },
+        async sseLines(
+          status: number,
+          lines: string[],
+          headers: Record<string, string> = {},
+        ): Promise<void> {
+          if (responded) {
+            return;
+          }
+          responded = true;
+          res.writeHead(status, {
+            'cache-control': 'no-cache',
+            connection: 'keep-alive',
+            'content-type': 'text/event-stream; charset=utf-8',
+            ...headers,
+          });
+          res.write(lines.join('\n'));
+          res.end();
+        },
+        async sseJson(
+          status: number,
+          events: unknown[],
+          headers: Record<string, string> = {},
+        ): Promise<void> {
+          await reply.sseLines(status, buildSseLines(events), headers);
+        },
+      };
+
+      if (route === undefined) {
+        await reply.text(404, `No fake route for ${method} ${requestUrl.pathname}`);
+        return;
+      }
+
+      await route(request, reply);
+
+      if (!responded) {
+        await reply.text(500, `Fake route for ${method} ${requestUrl.pathname} did not respond.`);
+      }
+    })();
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      resolve();
+    });
+  });
+
+  const address = server.address();
+  if (address === null || typeof address === 'string') {
+    throw new Error('Fake provider harness failed to bind a TCP port.');
+  }
+
+  return {
+    get baseUrl(): string {
+      return `http://127.0.0.1:${address.port}`;
+    },
+    requests,
+    route(method: string, pathname: string, handler: FakeProviderRouteHandler): void {
+      routes.set(`${method.toUpperCase()} ${pathname}`, handler);
+    },
+    async close(): Promise<void> {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error?: Error) => {
+          if (error !== undefined) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+    },
+  };
+}
diff --git a/packages/kosong/test/e2e/fixtures/python-jsonl-compat.jsonl b/packages/kosong/test/e2e/fixtures/python-jsonl-compat.jsonl
new file mode 100644
index 000000000..057e28680
--- /dev/null
+++ b/packages/kosong/test/e2e/fixtures/python-jsonl-compat.jsonl
@@ -0,0 +1,6 @@
+{"role":"user","content":"hello from python"}
+{"role":"assistant","content":[{"type":"think","think":"Let me reason about the request.","encrypted":"sig-123"},{"type":"text","text":"I will inspect the media."},{"type":"image_url","image_url":{"url":"https://example.com/image.png","id":"img-1"}},{"type":"audio_url","audio_url":{"url":"https://example.com/audio.mp3","id":"aud-1"}},{"type":"video_url","video_url":{"url":"ms://video-1","id":"vid-1"}}],"tool_calls":[{"type":"function","id":"call-1","function":{"name":"describe_media","arguments":"{\"detail\":\"full\"}"}}]}
+{"role":"tool","content":"{\"label\":\"sunset\"}","tool_call_id":"call-1"}
+{"role":"assistant","content":"TS-friendly response","tool_calls":null}
+{"role":"user","content":[
+{"role":"user","content":[{"type":"image_url","image_url":{"id":"img-missing-url"}}]}
diff --git a/packages/kosong/test/e2e/google-genai-adapter.test.ts b/packages/kosong/test/e2e/google-genai-adapter.test.ts
new file mode 100644
index 000000000..7b548d7f1
--- /dev/null
+++ b/packages/kosong/test/e2e/google-genai-adapter.test.ts
@@ -0,0 +1,201 @@
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import { GoogleGenAIChatProvider } from '#/providers/google-genai';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+import { GoogleGenAI } from '@google/genai';
+import { describe, expect, it } from 'vitest';
+
+import { createFakeProviderHarness } from './fake-provider-harness';
+
+async function collectParts(
+  streamedMessage: AsyncIterable<StreamedMessagePart>,
+): Promise<StreamedMessagePart[]> {
+  const parts: StreamedMessagePart[] = [];
+  for await (const part of streamedMessage) {
+    parts.push(part);
+  }
+  return parts;
+}
+
+const ADD_TOOL: Tool = {
+  name: 'add',
+  description: 'Add two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+const MUL_TOOL: Tool = {
+  name: 'multiply',
+  description: 'Multiply two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+describe('e2e: Google GenAI adapter bridge', () => {
+  it('sends the adapter request body, sorts tool responses, and parses streamed chunks', async () => {
+    const harness = await createFakeProviderHarness();
+    try {
+      harness.route(
+        'POST',
+        '/v1beta/models/gemini-2.5-flash:streamGenerateContent',
+        async (request, reply) => {
+          const body = request.bodyJson as Record<string, unknown>;
+          expect(request.pathname).toBe('/v1beta/models/gemini-2.5-flash:streamGenerateContent');
+          expect(request.search).toBe('?alt=sse');
+          expect(request.headers['x-goog-api-key']).toBe('test-key');
+          expect(body['generationConfig']).toEqual({});
+          expect(body['tools']).toHaveLength(2);
+          expect(body['contents']).toHaveLength(3);
+          expect(body['contents']).toEqual([
+            { role: 'user', parts: [{ text: 'Add and multiply these numbers.' }] },
+            {
+              role: 'model',
+              parts: [{ text: 'I will calculate both.' }, {}, {}],
+            },
+            {
+              role: 'user',
+              parts: [{}, {}],
+            },
+          ]);
+
+          await reply.sseLines(200, [
+            `data: ${JSON.stringify({
+              candidates: [
+                {
+                  content: {
+                    role: 'model',
+                    parts: [{ text: 'Done.' }],
+                  },
+                },
+              ],
+              usageMetadata: {
+                promptTokenCount: 30,
+                candidatesTokenCount: 4,
+                cachedContentTokenCount: 1,
+              },
+              responseId: 'resp-1',
+            })}`,
+            '',
+            `data: ${JSON.stringify({
+              candidates: [
+                {
+                  content: {
+                    role: 'model',
+                    parts: [
+                      {
+                        functionCall: {
+                          name: 'notify',
+                          id: 'call-1',
+                          args: { ok: true },
+                        },
+                        thoughtSignature: 'sig-1',
+                      },
+                    ],
+                  },
+                },
+              ],
+              usageMetadata: {
+                promptTokenCount: 30,
+                candidatesTokenCount: 9,
+                cachedContentTokenCount: 1,
+              },
+              responseId: 'resp-1',
+            })}`,
+            '',
+            '',
+          ]);
+        },
+      );
+
+      const provider = new GoogleGenAIChatProvider({
+        model: 'gemini-2.5-flash',
+        apiKey: 'test-key',
+        stream: true,
+      });
+      (provider as any)._client = new GoogleGenAI({
+        apiKey: 'test-key',
+        httpOptions: {
+          baseUrl: harness.baseUrl,
+          apiVersion: 'v1beta',
+        },
+      });
+
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Add and multiply these numbers.' }],
+          toolCalls: [],
+        },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'I will calculate both.' }],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_add',
+              function: { name: 'add', arguments: '{"a":2,"b":3}' },
+            },
+            {
+              type: 'function',
+              id: 'call_mul',
+              function: { name: 'multiply', arguments: '{"a":4,"b":5}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '20' }],
+          toolCallId: 'call_mul',
+          toolCalls: [],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '5' }],
+          toolCallId: 'call_add',
+          toolCalls: [],
+        },
+      ];
+
+      const stream = await provider.generate(
+        'You are a calculator.',
+        [ADD_TOOL, MUL_TOOL],
+        history,
+      );
+      const parts = await collectParts(stream);
+
+      expect(parts).toEqual([
+        { type: 'text', text: 'Done.' },
+        {
+          type: 'function',
+          id: 'notify_call-1',
+          function: { name: 'notify', arguments: '{"ok":true}' },
+          extras: { thought_signature_b64: 'sig-1' },
+        } satisfies ToolCall,
+      ]);
+
+      expect(stream.id).toBe('resp-1');
+      expect(stream.usage).toEqual({
+        inputOther: 29,
+        output: 9,
+        inputCacheRead: 1,
+        inputCacheCreation: 0,
+      } satisfies TokenUsage);
+
+      expect(harness.requests).toHaveLength(1);
+    } finally {
+      await harness.close();
+    }
+  });
+});
diff --git a/packages/kosong/test/e2e/google-genai-error-mapping.test.ts b/packages/kosong/test/e2e/google-genai-error-mapping.test.ts
new file mode 100644
index 000000000..2ea137875
--- /dev/null
+++ b/packages/kosong/test/e2e/google-genai-error-mapping.test.ts
@@ -0,0 +1,88 @@
+import { APIStatusError } from '#/errors';
+import type { Message } from '#/message';
+import { GoogleGenAIChatProvider } from '#/providers/google-genai';
+import type { Tool } from '#/tool';
+import { GoogleGenAI } from '@google/genai';
+import { describe, expect, it } from 'vitest';
+
+import { createFakeProviderHarness } from './fake-provider-harness';
+
+const SUM_TOOL: Tool = {
+  name: 'sum',
+  description: 'Sum two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      left: { type: 'integer' },
+      right: { type: 'integer' },
+    },
+    required: ['left', 'right'],
+  },
+};
+
+describe('e2e: Google GenAI error mapping', () => {
+  it('sends the non-stream request body and maps HTTP status errors', async () => {
+    const harness = await createFakeProviderHarness();
+    try {
+      harness.route(
+        'POST',
+        '/v1beta/models/gemini-2.5-flash:generateContent',
+        async (request, reply) => {
+          const body = request.bodyJson as Record<string, unknown>;
+
+          expect(request.pathname).toBe('/v1beta/models/gemini-2.5-flash:generateContent');
+          expect(request.search).toBe('');
+          expect(request.headers['x-goog-api-key']).toBe('test-key');
+          expect(body['generationConfig']).toEqual({});
+          expect(body['tools']).toHaveLength(1);
+          expect(body['contents']).toEqual([
+            {
+              role: 'user',
+              parts: [{ text: 'Add 7 and 11.' }],
+            },
+          ]);
+
+          await reply.json(503, {
+            error: {
+              code: 503,
+              message: 'upstream temporarily unavailable',
+              status: 'UNAVAILABLE',
+            },
+          });
+        },
+      );
+
+      const provider = new GoogleGenAIChatProvider({
+        model: 'gemini-2.5-flash',
+        apiKey: 'test-key',
+        stream: false,
+      });
+      (provider as any)._client = new GoogleGenAI({
+        apiKey: 'test-key',
+        httpOptions: {
+          baseUrl: harness.baseUrl,
+          apiVersion: 'v1beta',
+        },
+      });
+
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Add 7 and 11.' }],
+          toolCalls: [],
+        },
+      ];
+
+      const pending = provider.generate('You are a careful calculator.', [SUM_TOOL], history);
+
+      await expect(pending).rejects.toBeInstanceOf(APIStatusError);
+      await expect(pending).rejects.toMatchObject({
+        name: 'APIStatusError',
+        statusCode: 503,
+        message: expect.stringContaining('upstream temporarily unavailable'),
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+});
diff --git a/packages/kosong/test/e2e/kimi-adapter-e2e.test.ts b/packages/kosong/test/e2e/kimi-adapter-e2e.test.ts
new file mode 100644
index 000000000..796ace64b
--- /dev/null
+++ b/packages/kosong/test/e2e/kimi-adapter-e2e.test.ts
@@ -0,0 +1,235 @@
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import type { StreamedMessage } from '#/provider';
+import { KimiChatProvider } from '#/providers/kimi';
+import type { Tool } from '#/tool';
+import { describe, expect, it } from 'vitest';
+
+import { createFakeProviderHarness, type FakeProviderHarness } from './fake-provider-harness';
+
+function createProvider(baseUrl: string): KimiChatProvider {
+  return new KimiChatProvider({
+    model: 'kimi-k2-turbo-preview',
+    apiKey: 'test-key',
+    baseUrl,
+    stream: true,
+  }).withThinking('high');
+}
+
+async function withHarness<T>(fn: (harness: FakeProviderHarness) => Promise<T>): Promise<T> {
+  const harness = await createFakeProviderHarness();
+  try {
+    return await fn(harness);
+  } finally {
+    await harness.close();
+  }
+}
+
+async function collectStream(
+  provider: KimiChatProvider,
+  systemPrompt: string,
+  tools: Tool[],
+  history: Message[],
+): Promise<{ id: string | null; usage: unknown; parts: StreamedMessagePart[] }> {
+  const stream: StreamedMessage = await provider.generate(systemPrompt, tools, history);
+  const parts: StreamedMessagePart[] = [];
+  for await (const part of stream) {
+    parts.push(part);
+  }
+  return { id: stream.id, usage: stream.usage, parts };
+}
+
+const LOOKUP_TOOL: Tool = {
+  name: 'lookup_weather',
+  description: 'Look up the weather for a city.',
+  parameters: {
+    type: 'object',
+    properties: {
+      city: { type: 'string' },
+    },
+    required: ['city'],
+    additionalProperties: false,
+  },
+};
+
+function makeChunk(
+  delta: Record<string, unknown>,
+  opts?: { id?: string; finishReason?: string; usage?: Record<string, unknown> },
+): Record<string, unknown> {
+  const chunk: Record<string, unknown> = {
+    id: opts?.id ?? 'chatcmpl-kimi-1',
+    object: 'chat.completion.chunk',
+    created: 1234567890,
+    model: 'kimi-k2-turbo-preview',
+    choices: [
+      {
+        index: 0,
+        delta,
+        finish_reason: opts?.finishReason ?? null,
+      },
+    ],
+  };
+  if (opts?.usage !== undefined) {
+    chunk['choices'] = [
+      {
+        index: 0,
+        delta,
+        finish_reason: opts?.finishReason ?? null,
+        usage: opts.usage,
+      },
+    ];
+  }
+  return chunk;
+}
+
+describe('e2e: kimi adapter', () => {
+  it('sends Moonshot chat-completion requests, streams reasoning + tool-call deltas, and preserves usage', async () => {
+    await withHarness(async (harness) => {
+      let capturedRequest: Record<string, unknown> | null = null;
+
+      harness.route('POST', '/v1/chat/completions', async (request, reply) => {
+        capturedRequest = request.bodyJson as Record<string, unknown>;
+        await reply.sseJson(200, [
+          makeChunk({ reasoning_content: 'Let me think. ' }),
+          makeChunk({ content: 'All set. ' }),
+          makeChunk({
+            tool_calls: [
+              {
+                index: 0,
+                id: 'call_weather',
+                function: { name: 'lookup_weather', arguments: '{"city":"' },
+              },
+            ],
+          }),
+          makeChunk({
+            tool_calls: [{ index: 0, function: { arguments: 'Shanghai"}' } }],
+          }),
+          makeChunk(
+            {},
+            {
+              finishReason: 'tool_calls',
+              usage: {
+                prompt_tokens: 12,
+                completion_tokens: 6,
+                total_tokens: 18,
+                cached_tokens: 2,
+              },
+            },
+          ),
+        ]);
+      });
+
+      const provider = createProvider(`${harness.baseUrl}/v1`);
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Check the weather.' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'think', think: 'I should call a tool.' },
+            { type: 'text', text: 'I will look it up.' },
+          ],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_weather',
+              function: { name: 'lookup_weather', arguments: '{"city":"Shanghai"}' },
+            } satisfies ToolCall,
+          ],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: 'sunny and 26C' }],
+          toolCallId: 'call_weather',
+          toolCalls: [],
+        },
+      ];
+
+      const result = await collectStream(provider, 'You are helpful.', [LOOKUP_TOOL], history);
+      expect(capturedRequest).toMatchObject({
+        model: 'kimi-k2-turbo-preview',
+        stream: true,
+        stream_options: { include_usage: true },
+        reasoning_effort: 'high',
+        thinking: { type: 'enabled' },
+        messages: [
+          { role: 'system', content: 'You are helpful.' },
+          { role: 'user', content: 'Check the weather.' },
+          {
+            role: 'assistant',
+            content: 'I will look it up.',
+            reasoning_content: 'I should call a tool.',
+            tool_calls: [
+              {
+                type: 'function',
+                id: 'call_weather',
+                function: { name: 'lookup_weather', arguments: '{"city":"Shanghai"}' },
+              },
+            ],
+          },
+          { role: 'tool', content: 'sunny and 26C', tool_call_id: 'call_weather' },
+        ],
+      });
+
+      expect(harness.requests).toHaveLength(1);
+      expect(harness.requests[0]!.pathname).toBe('/v1/chat/completions');
+      expect(harness.requests[0]!.headers['authorization']).toBe('Bearer test-key');
+      expect(result.id).toBe('chatcmpl-kimi-1');
+      expect(result.usage).toEqual({
+        inputOther: 10,
+        output: 6,
+        inputCacheRead: 2,
+        inputCacheCreation: 0,
+      });
+      expect(result.parts).toHaveLength(4);
+      expect(result.parts[0]).toMatchObject({ type: 'think', think: 'Let me think. ' });
+      expect(result.parts[1]).toMatchObject({ type: 'text', text: 'All set. ' });
+      expect(result.parts[2]).toMatchObject({
+        type: 'function',
+        id: 'call_weather',
+        function: { name: 'lookup_weather', arguments: '{"city":"' },
+      });
+      expect(result.parts[2]).toHaveProperty('_streamIndex', 0);
+      expect(result.parts[3]).toMatchObject({
+        type: 'tool_call_part',
+        argumentsPart: 'Shanghai"}',
+      });
+      expect(result.parts[3]).toHaveProperty('index', 0);
+    });
+  });
+
+  it('propagates upstream HTTP failures as APIStatusError', async () => {
+    await withHarness(async (harness) => {
+      let capturedRequest: Record<string, unknown> | null = null;
+
+      harness.route('POST', '/v1/chat/completions', async (request, reply) => {
+        capturedRequest = request.bodyJson as Record<string, unknown>;
+        await reply.json(
+          500,
+          {
+            error: {
+              message: 'upstream unavailable',
+              type: 'server_error',
+            },
+          },
+          { 'x-should-retry': 'false' },
+        );
+      });
+
+      const provider = createProvider(`${harness.baseUrl}/v1`);
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Check the weather.' }], toolCalls: [] },
+      ];
+
+      await expect(collectStream(provider, '', [LOOKUP_TOOL], history)).rejects.toMatchObject({
+        name: 'APIStatusError',
+        statusCode: 500,
+      });
+      expect(capturedRequest).toMatchObject({
+        model: 'kimi-k2-turbo-preview',
+        stream: true,
+        stream_options: { include_usage: true },
+        reasoning_effort: 'high',
+      });
+      expect(harness.requests.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+});
diff --git a/packages/kosong/test/e2e/multi-step-agent-loop.test.ts b/packages/kosong/test/e2e/multi-step-agent-loop.test.ts
new file mode 100644
index 000000000..dcf217d28
--- /dev/null
+++ b/packages/kosong/test/e2e/multi-step-agent-loop.test.ts
@@ -0,0 +1,358 @@
+import { ScriptedEchoChatProvider } from '../fixtures/echo-provider';
+import { extractText } from '#/message';
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import type { ChatProvider, StreamedMessage, ThinkingEffort } from '#/provider';
+import { SimpleToolset, toolOk } from '../fixtures/simple-toolset';
+import type { ToolReturnValue } from '../fixtures/simple-toolset';
+import { step } from '../fixtures/step';
+import type { Tool } from '#/tool';
+import type { JsonValue } from '../fixtures/args-validator';
+import type { TokenUsage } from '#/usage';
+import { describe, expect, it } from 'vitest';
+function createMockStream(
+  parts: StreamedMessagePart[],
+  opts?: { id?: string; usage?: TokenUsage },
+): StreamedMessage {
+  return {
+    get id(): string | null {
+      return opts?.id ?? null;
+    },
+    get usage(): TokenUsage | null {
+      return opts?.usage ?? null;
+    },
+    finishReason: null,
+    rawFinishReason: null,
+    async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+      for (const part of parts) {
+        yield part;
+      }
+    },
+  };
+}
+
+/**
+ * A provider that consumes a queue of StreamedMessage instances,
+ * one per generate() call. More flexible than ScriptedEchoChatProvider
+ * when we need programmatic ToolCall objects with specific argument strings.
+ */
+class QueuedMockProvider implements ChatProvider {
+  readonly name: string = 'queued-mock';
+  readonly modelName: string = 'queued-mock';
+  readonly thinkingEffort: ThinkingEffort | null = null;
+  private readonly _queue: StreamedMessage[];
+  private _cursor: number = 0;
+
+  constructor(queue: StreamedMessage[]) {
+    this._queue = queue;
+  }
+
+  async generate(
+    _systemPrompt: string,
+    _tools: Tool[],
+    _history: Message[],
+  ): Promise<StreamedMessage> {
+    const stream = this._queue[this._cursor];
+    if (stream === undefined) {
+      throw new Error(`QueuedMockProvider exhausted at turn ${this._cursor + 1}.`);
+    }
+    this._cursor++;
+    return stream;
+  }
+
+  withThinking(_effort: ThinkingEffort): ChatProvider {
+    return this;
+  }
+}
+
+/**
+ * Simulate a full agent loop: call step() repeatedly until there are
+ * no more tool calls, appending assistant + tool messages to history.
+ */
+async function runAgentLoop(
+  provider: ChatProvider,
+  toolset: SimpleToolset,
+  systemPrompt: string = '',
+  initialHistory: Message[] = [
+    { role: 'user', content: [{ type: 'text', text: 'go' }], toolCalls: [] },
+  ],
+): Promise<{ messages: Message[]; turns: number }> {
+  const history: Message[] = [...initialHistory];
+  let turns = 0;
+  const maxTurns = 10;
+
+  while (turns < maxTurns) {
+    turns++;
+    const result = await step(provider, systemPrompt, toolset, history);
+    history.push(result.message);
+
+    if (result.toolCalls.length === 0) {
+      break;
+    }
+
+    const toolResults = await result.toolResults();
+    for (const tr of toolResults) {
+      history.push({
+        role: 'tool',
+        content: [
+          {
+            type: 'text',
+            text: typeof tr.returnValue.output === 'string' ? tr.returnValue.output : '',
+          },
+        ],
+        toolCallId: tr.toolCallId,
+        toolCalls: [],
+      });
+    }
+  }
+
+  return { messages: history, turns };
+}
+describe('e2e: multi-step agent loop', () => {
+  it('2-step loop: tool_call → result → final text', async () => {
+    const toolCall: ToolCall = {
+      type: 'function',
+      id: 'tc-1',
+      function: { name: 'search', arguments: '{"query":"vitest"}' },
+    };
+
+    const provider = new QueuedMockProvider([
+      // Turn 1: LLM returns a tool call
+      createMockStream([toolCall]),
+      // Turn 2: LLM returns final text
+      createMockStream([{ type: 'text', text: 'Found results for vitest.' }]),
+    ]);
+
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'search', description: 'Search the web', parameters: {} },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        const obj = args as Record<string, JsonValue>;
+        return toolOk({ output: `results for ${obj['query'] as string}` });
+      },
+    );
+
+    const { messages, turns } = await runAgentLoop(provider, toolset);
+
+    expect(turns).toBe(2);
+    // History: user → assistant(tool_call) → tool → assistant(text)
+    expect(messages).toHaveLength(4);
+    expect(messages[1]!.role).toBe('assistant');
+    expect(messages[1]!.toolCalls).toHaveLength(1);
+    expect(messages[2]!.role).toBe('tool');
+    expect(messages[3]!.role).toBe('assistant');
+    expect(extractText(messages[3]!)).toBe('Found results for vitest.');
+  });
+
+  it('3-step loop: tool A → tool B → final text', async () => {
+    const tcSearch: ToolCall = {
+      type: 'function',
+      id: 'tc-search',
+      function: { name: 'search', arguments: '{"query":"vitest"}' },
+    };
+    const tcRead: ToolCall = {
+      type: 'function',
+      id: 'tc-read',
+      function: { name: 'read_file', arguments: '{"path":"/docs/vitest.md"}' },
+    };
+
+    const provider = new QueuedMockProvider([
+      createMockStream([{ type: 'text', text: 'Let me search first.' }, tcSearch]),
+      createMockStream([{ type: 'text', text: 'Found a doc, reading it.' }, tcRead]),
+      createMockStream([{ type: 'text', text: 'The answer is: use vitest.' }]),
+    ]);
+
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'search', description: 'Search', parameters: {} },
+      async (): Promise<ToolReturnValue> => toolOk({ output: '/docs/vitest.md' }),
+    );
+    toolset.add(
+      { name: 'read_file', description: 'Read file', parameters: {} },
+      async (): Promise<ToolReturnValue> => toolOk({ output: 'vitest is a test runner' }),
+    );
+
+    const { messages, turns } = await runAgentLoop(provider, toolset);
+
+    expect(turns).toBe(3);
+    // user → asst(search) → tool → asst(read_file) → tool → asst(final)
+    expect(messages).toHaveLength(6);
+    expect(extractText(messages[5]!)).toBe('The answer is: use vitest.');
+  });
+
+  it('parallel tool calls: 3 tool_calls in one turn → all executed', async () => {
+    const tc1: ToolCall = {
+      type: 'function',
+      id: 'tc-a',
+      function: { name: 'fetch_url', arguments: '{"url":"https://a.com"}' },
+    };
+    const tc2: ToolCall = {
+      type: 'function',
+      id: 'tc-b',
+      function: { name: 'fetch_url', arguments: '{"url":"https://b.com"}' },
+    };
+    const tc3: ToolCall = {
+      type: 'function',
+      id: 'tc-c',
+      function: { name: 'fetch_url', arguments: '{"url":"https://c.com"}' },
+    };
+
+    const provider = new QueuedMockProvider([
+      // Turn 1: 3 parallel tool calls
+      createMockStream([tc1, tc2, tc3]),
+      // Turn 2: final text
+      createMockStream([{ type: 'text', text: 'All 3 URLs fetched.' }]),
+    ]);
+
+    const callOrder: string[] = [];
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'fetch_url', description: 'Fetch a URL', parameters: {} },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        const obj = args as Record<string, JsonValue>;
+        const url = obj['url'] as string;
+        // Vary delays to confirm parallel execution
+        const delay = url.includes('a.com') ? 30 : url.includes('b.com') ? 10 : 20;
+        await new Promise<void>((r) => setTimeout(r, delay));
+        callOrder.push(url);
+        return toolOk({ output: `content of ${url}` });
+      },
+    );
+
+    const { messages, turns } = await runAgentLoop(provider, toolset);
+
+    expect(turns).toBe(2);
+    // All 3 tool results should be present
+    const toolMessages = messages.filter((m) => m.role === 'tool');
+    expect(toolMessages).toHaveLength(3);
+
+    // b.com should finish first (10ms), c.com second (20ms), a.com last (30ms)
+    // confirming parallel execution
+    expect(callOrder[0]).toBe('https://b.com');
+    expect(callOrder[1]).toBe('https://c.com');
+    expect(callOrder[2]).toBe('https://a.com');
+  });
+
+  it('tool chain: tool A result triggers tool B call', async () => {
+    const tcList: ToolCall = {
+      type: 'function',
+      id: 'tc-list',
+      function: { name: 'list_files', arguments: '{"dir":"/src"}' },
+    };
+    const tcRead: ToolCall = {
+      type: 'function',
+      id: 'tc-read',
+      function: { name: 'read_file', arguments: '{"path":"/src/main.ts"}' },
+    };
+
+    // The provider sees history growing—tool A result is in history when
+    // turn 2 calls tool B.
+    const provider = new QueuedMockProvider([
+      createMockStream([tcList]),
+      createMockStream([tcRead]),
+      createMockStream([{ type: 'text', text: 'main.ts exports greet()' }]),
+    ]);
+
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'list_files', description: 'List', parameters: {} },
+      async (): Promise<ToolReturnValue> => toolOk({ output: 'main.ts\nutils.ts' }),
+    );
+    toolset.add(
+      { name: 'read_file', description: 'Read', parameters: {} },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        const obj = args as Record<string, JsonValue>;
+        return toolOk({ output: `content of ${obj['path'] as string}` });
+      },
+    );
+
+    const { messages, turns } = await runAgentLoop(provider, toolset);
+
+    expect(turns).toBe(3);
+    // user → asst(list) → tool(list result) → asst(read) → tool(read result) → asst(final)
+    expect(messages).toHaveLength(6);
+    expect(extractText(messages[5]!)).toBe('main.ts exports greet()');
+  });
+
+  it('text + tool_call interleaved across multiple turns', async () => {
+    const tc1: ToolCall = {
+      type: 'function',
+      id: 'tc-1',
+      function: { name: 'calc', arguments: '{"expr":"2+2"}' },
+    };
+    const tc2: ToolCall = {
+      type: 'function',
+      id: 'tc-2',
+      function: { name: 'calc', arguments: '{"expr":"4*3"}' },
+    };
+
+    const provider = new QueuedMockProvider([
+      createMockStream([{ type: 'text', text: 'Computing 2+2...' }, tc1]),
+      createMockStream([{ type: 'text', text: 'Now 4*3...' }, tc2]),
+      createMockStream([{ type: 'text', text: 'Results: 4 and 12.' }]),
+    ]);
+
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'calc', description: 'Calculate', parameters: {} },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        const obj = args as Record<string, JsonValue>;
+        const expr = obj['expr'] as string;
+        const result = expr === '2+2' ? '4' : '12';
+        return toolOk({ output: result });
+      },
+    );
+
+    const { messages, turns } = await runAgentLoop(provider, toolset);
+
+    expect(turns).toBe(3);
+    // Each assistant message should have both text content and tool calls
+    expect(messages[1]!.content).toEqual([{ type: 'text', text: 'Computing 2+2...' }]);
+    expect(messages[1]!.toolCalls).toHaveLength(1);
+    expect(messages[3]!.content).toEqual([{ type: 'text', text: 'Now 4*3...' }]);
+    expect(messages[3]!.toolCalls).toHaveLength(1);
+    expect(extractText(messages[5]!)).toBe('Results: 4 and 12.');
+  });
+
+  it('ScriptedEchoChatProvider works for multi-step loop with echo DSL', async () => {
+    const provider = new ScriptedEchoChatProvider([
+      // Turn 1: tool call via DSL
+      'tool_call: {"id":"tc-1","name":"greet","arguments":"{\\"name\\":\\"world\\"}"}',
+      // Turn 2: final text
+      'text: Hello, world!',
+    ]);
+
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'greet', description: 'Greet', parameters: {} },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        const obj = args as Record<string, JsonValue>;
+        return toolOk({ output: `Hi ${obj['name'] as string}` });
+      },
+    );
+
+    const { turns } = await runAgentLoop(provider, toolset);
+    expect(turns).toBe(2);
+  });
+
+  it('empty tool arguments (null) are handled correctly', async () => {
+    const tc: ToolCall = {
+      type: 'function',
+      id: 'tc-no-args',
+      function: { name: 'get_time', arguments: null },
+    };
+
+    const provider = new QueuedMockProvider([
+      createMockStream([tc]),
+      createMockStream([{ type: 'text', text: 'The time is 12:00.' }]),
+    ]);
+
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'get_time', description: 'Get current time', parameters: {} },
+      async (): Promise<ToolReturnValue> => toolOk({ output: '12:00' }),
+    );
+
+    const { turns } = await runAgentLoop(provider, toolset);
+    expect(turns).toBe(2);
+  });
+});
diff --git a/packages/kosong/test/e2e/openai-legacy-adapter-e2e.test.ts b/packages/kosong/test/e2e/openai-legacy-adapter-e2e.test.ts
new file mode 100644
index 000000000..6afeb983f
--- /dev/null
+++ b/packages/kosong/test/e2e/openai-legacy-adapter-e2e.test.ts
@@ -0,0 +1,229 @@
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import type { StreamedMessage } from '#/provider';
+import { OpenAILegacyChatProvider } from '#/providers/openai-legacy';
+import type { Tool } from '#/tool';
+import { describe, expect, it } from 'vitest';
+
+import { createFakeProviderHarness, type FakeProviderHarness } from './fake-provider-harness';
+
+function createProvider(baseUrl: string): OpenAILegacyChatProvider {
+  return new OpenAILegacyChatProvider({
+    model: 'gpt-4.1',
+    apiKey: 'test-key',
+    baseUrl,
+    stream: true,
+  });
+}
+
+async function withHarness<T>(fn: (harness: FakeProviderHarness) => Promise<T>): Promise<T> {
+  const harness = await createFakeProviderHarness();
+  try {
+    return await fn(harness);
+  } finally {
+    await harness.close();
+  }
+}
+
+async function collectStream(
+  provider: OpenAILegacyChatProvider,
+  systemPrompt: string,
+  tools: Tool[],
+  history: Message[],
+): Promise<{ id: string | null; usage: unknown; parts: StreamedMessagePart[] }> {
+  const stream: StreamedMessage = await provider.generate(systemPrompt, tools, history);
+  const parts: StreamedMessagePart[] = [];
+  for await (const part of stream) {
+    parts.push(part);
+  }
+  return { id: stream.id, usage: stream.usage, parts };
+}
+
+const LOOKUP_TOOL: Tool = {
+  name: 'lookup_weather',
+  description: 'Look up the weather for a city.',
+  parameters: {
+    type: 'object',
+    properties: {
+      city: { type: 'string' },
+    },
+    required: ['city'],
+    additionalProperties: false,
+  },
+};
+
+function makeChunk(
+  delta: Record<string, unknown>,
+  opts?: { id?: string; finishReason?: string; usage?: Record<string, unknown> },
+): Record<string, unknown> {
+  const chunk: Record<string, unknown> = {
+    id: opts?.id ?? 'chatcmpl-openai-legacy-1',
+    object: 'chat.completion.chunk',
+    created: 1234567890,
+    model: 'gpt-4.1',
+    choices: [
+      {
+        index: 0,
+        delta,
+        finish_reason: opts?.finishReason ?? null,
+      },
+    ],
+  };
+  if (opts?.usage !== undefined) {
+    chunk['usage'] = opts.usage;
+  }
+  return chunk;
+}
+
+describe('e2e: openai-legacy adapter', () => {
+  it('sends chat-completion requests, streams tool-call deltas, and preserves usage', async () => {
+    await withHarness(async (harness) => {
+      let capturedRequest: Record<string, unknown> | null = null;
+
+      harness.route('POST', '/v1/chat/completions', async (request, reply) => {
+        capturedRequest = request.bodyJson as Record<string, unknown>;
+        await reply.sseJson(200, [
+          makeChunk({ content: 'Checking weather. ' }),
+          makeChunk({
+            tool_calls: [
+              {
+                index: 0,
+                id: 'call_weather',
+                function: { name: 'lookup_weather', arguments: '{"city":"' },
+              },
+            ],
+          }),
+          makeChunk({
+            tool_calls: [{ index: 0, function: { arguments: 'Shanghai"}' } }],
+          }),
+          makeChunk(
+            {},
+            {
+              finishReason: 'tool_calls',
+              usage: { prompt_tokens: 12, completion_tokens: 6, total_tokens: 18 },
+            },
+          ),
+        ]);
+      });
+
+      const provider = createProvider(`${harness.baseUrl}/v1`);
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Check the weather.' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'I will look it up.' }],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_weather',
+              function: { name: 'lookup_weather', arguments: '{"city":"Shanghai"}' },
+            } satisfies ToolCall,
+          ],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: 'sunny and 26C' }],
+          toolCallId: 'call_weather',
+          toolCalls: [],
+        },
+      ];
+
+      const result = await collectStream(provider, 'You are helpful.', [LOOKUP_TOOL], history);
+      expect(capturedRequest).toMatchObject({
+        model: 'gpt-4.1',
+        stream: true,
+        stream_options: { include_usage: true },
+        messages: [
+          { role: 'system', content: 'You are helpful.' },
+          { role: 'user', content: 'Check the weather.' },
+          {
+            role: 'assistant',
+            content: 'I will look it up.',
+            tool_calls: [
+              {
+                type: 'function',
+                id: 'call_weather',
+                function: { name: 'lookup_weather', arguments: '{"city":"Shanghai"}' },
+              },
+            ],
+          },
+          { role: 'tool', content: 'sunny and 26C', tool_call_id: 'call_weather' },
+        ],
+        tools: [
+          {
+            type: 'function',
+            function: {
+              name: 'lookup_weather',
+              description: 'Look up the weather for a city.',
+              parameters: {
+                type: 'object',
+                properties: { city: { type: 'string' } },
+                required: ['city'],
+                additionalProperties: false,
+              },
+            },
+          },
+        ],
+      });
+
+      expect(harness.requests).toHaveLength(1);
+      expect(harness.requests[0]!.pathname).toBe('/v1/chat/completions');
+      expect(harness.requests[0]!.headers['authorization']).toBe('Bearer test-key');
+      expect(result.id).toBe('chatcmpl-openai-legacy-1');
+      expect(result.usage).toEqual({
+        inputOther: 12,
+        output: 6,
+        inputCacheRead: 0,
+        inputCacheCreation: 0,
+      });
+      expect(result.parts).toHaveLength(3);
+      expect(result.parts[0]).toMatchObject({ type: 'text', text: 'Checking weather. ' });
+      expect(result.parts[1]).toMatchObject({
+        type: 'function',
+        id: 'call_weather',
+        function: { name: 'lookup_weather', arguments: '{"city":"' },
+      });
+      expect(result.parts[1]).toHaveProperty('_streamIndex', 0);
+      expect(result.parts[2]).toMatchObject({
+        type: 'tool_call_part',
+        argumentsPart: 'Shanghai"}',
+      });
+      expect(result.parts[2]).toHaveProperty('index', 0);
+    });
+  });
+
+  it('propagates upstream HTTP failures as APIStatusError', async () => {
+    await withHarness(async (harness) => {
+      let capturedRequest: Record<string, unknown> | null = null;
+
+      harness.route('POST', '/v1/chat/completions', async (request, reply) => {
+        capturedRequest = request.bodyJson as Record<string, unknown>;
+        await reply.json(
+          503,
+          {
+            error: {
+              message: 'upstream unavailable',
+              type: 'server_error',
+            },
+          },
+          { 'x-should-retry': 'false' },
+        );
+      });
+
+      const provider = createProvider(`${harness.baseUrl}/v1`);
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Check the weather.' }], toolCalls: [] },
+      ];
+
+      await expect(collectStream(provider, '', [LOOKUP_TOOL], history)).rejects.toMatchObject({
+        name: 'APIStatusError',
+        statusCode: 503,
+      });
+      expect(capturedRequest).toMatchObject({
+        model: 'gpt-4.1',
+        stream: true,
+        stream_options: { include_usage: true },
+      });
+      expect(harness.requests.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+});
diff --git a/packages/kosong/test/e2e/openai-responses-adapter-e2e.test.ts b/packages/kosong/test/e2e/openai-responses-adapter-e2e.test.ts
new file mode 100644
index 000000000..ef47b312e
--- /dev/null
+++ b/packages/kosong/test/e2e/openai-responses-adapter-e2e.test.ts
@@ -0,0 +1,212 @@
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import type { StreamedMessage } from '#/provider';
+import { OpenAIResponsesChatProvider } from '#/providers/openai-responses';
+import type { Tool } from '#/tool';
+import { describe, expect, it } from 'vitest';
+
+import { createFakeProviderHarness, type FakeProviderHarness } from './fake-provider-harness';
+
+function createProvider(baseUrl: string): OpenAIResponsesChatProvider {
+  return new OpenAIResponsesChatProvider({
+    model: 'gpt-4.1',
+    apiKey: 'test-key',
+    baseUrl,
+  });
+}
+
+async function withHarness<T>(fn: (harness: FakeProviderHarness) => Promise<T>): Promise<T> {
+  const harness = await createFakeProviderHarness();
+  try {
+    return await fn(harness);
+  } finally {
+    await harness.close();
+  }
+}
+
+async function collectStream(
+  provider: OpenAIResponsesChatProvider,
+  systemPrompt: string,
+  tools: Tool[],
+  history: Message[],
+): Promise<{ id: string | null; usage: unknown; parts: StreamedMessagePart[] }> {
+  const stream: StreamedMessage = await provider.generate(systemPrompt, tools, history);
+  const parts: StreamedMessagePart[] = [];
+  for await (const part of stream) {
+    parts.push(part);
+  }
+  return { id: stream.id, usage: stream.usage, parts };
+}
+
+const LOOKUP_TOOL: Tool = {
+  name: 'lookup_weather',
+  description: 'Look up the weather for a city.',
+  parameters: {
+    type: 'object',
+    properties: {
+      city: { type: 'string' },
+    },
+    required: ['city'],
+    additionalProperties: false,
+  },
+};
+
+describe('e2e: openai-responses adapter', () => {
+  it('sends Responses API requests, streams function-call deltas, and preserves usage', async () => {
+    await withHarness(async (harness) => {
+      let capturedRequest: Record<string, unknown> | null = null;
+      const responseSnapshot = {
+        id: 'resp_openai_1',
+        object: 'response',
+        created_at: 1234567890,
+        status: 'completed',
+        model: 'gpt-4.1',
+        output: [
+          {
+            type: 'message',
+            id: 'item_msg',
+            role: 'assistant',
+            status: 'completed',
+            content: [{ type: 'output_text', text: 'All set. ', annotations: [] }],
+          },
+          {
+            type: 'function_call',
+            id: 'item_weather',
+            call_id: 'call_weather',
+            name: 'lookup_weather',
+            arguments: '{"city":"Shanghai"}',
+            status: 'completed',
+          },
+        ],
+        usage: { input_tokens: 10, output_tokens: 4, total_tokens: 14 },
+      };
+
+      harness.route('POST', '/v1/responses', async (request, reply) => {
+        capturedRequest = request.bodyJson as Record<string, unknown>;
+        await reply.json(200, responseSnapshot);
+      });
+
+      const provider = createProvider(`${harness.baseUrl}/v1`);
+      (provider as any)._stream = false;
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Check the weather.' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'I will look it up.' }],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_weather',
+              function: { name: 'lookup_weather', arguments: '{"city":"Shanghai"}' },
+            } satisfies ToolCall,
+          ],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: 'sunny and 26C' }],
+          toolCallId: 'call_weather',
+          toolCalls: [],
+        },
+      ];
+
+      const result = await collectStream(provider, 'You are helpful.', [LOOKUP_TOOL], history);
+      expect(capturedRequest).toMatchObject({
+        model: 'gpt-4.1',
+        stream: false,
+        store: false,
+        input: [
+          { role: 'developer', content: 'You are helpful.' },
+          {
+            role: 'user',
+            type: 'message',
+            content: [{ type: 'input_text', text: 'Check the weather.' }],
+          },
+          {
+            role: 'assistant',
+            type: 'message',
+            content: [{ type: 'output_text', text: 'I will look it up.', annotations: [] }],
+          },
+          {
+            type: 'function_call',
+            call_id: 'call_weather',
+            name: 'lookup_weather',
+            arguments: '{"city":"Shanghai"}',
+          },
+          {
+            type: 'function_call_output',
+            call_id: 'call_weather',
+            output: [{ type: 'input_text', text: 'sunny and 26C' }],
+          },
+        ],
+        tools: [
+          {
+            type: 'function',
+            name: 'lookup_weather',
+            description: 'Look up the weather for a city.',
+            parameters: {
+              type: 'object',
+              properties: { city: { type: 'string' } },
+              required: ['city'],
+              additionalProperties: false,
+            },
+            strict: false,
+          },
+        ],
+      });
+
+      expect(harness.requests).toHaveLength(1);
+      expect(harness.requests[0]!.pathname).toBe('/v1/responses');
+      expect(harness.requests[0]!.headers['authorization']).toBe('Bearer test-key');
+      expect(result.id).toBe('resp_openai_1');
+      expect(result.usage).toEqual({
+        inputOther: 10,
+        output: 4,
+        inputCacheRead: 0,
+        inputCacheCreation: 0,
+      });
+      expect(result.parts).toHaveLength(2);
+      expect(result.parts[0]).toMatchObject({ type: 'text', text: 'All set. ' });
+      expect(result.parts[1]).toMatchObject({
+        type: 'function',
+        id: 'call_weather',
+        function: { name: 'lookup_weather', arguments: '{"city":"Shanghai"}' },
+      });
+    });
+  });
+
+  it('propagates upstream HTTP failures as APIStatusError', async () => {
+    await withHarness(async (harness) => {
+      let capturedRequest: Record<string, unknown> | null = null;
+
+      harness.route('POST', '/v1/responses', async (request, reply) => {
+        capturedRequest = request.bodyJson as Record<string, unknown>;
+        await reply.json(
+          503,
+          {
+            error: {
+              message: 'upstream unavailable',
+              type: 'server_error',
+            },
+          },
+          { 'x-should-retry': 'false' },
+        );
+      });
+
+      const provider = createProvider(`${harness.baseUrl}/v1`);
+      (provider as any)._stream = false;
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Check the weather.' }], toolCalls: [] },
+      ];
+
+      await expect(collectStream(provider, '', [LOOKUP_TOOL], history)).rejects.toMatchObject({
+        name: 'APIStatusError',
+        statusCode: 503,
+      });
+      expect(capturedRequest).toMatchObject({
+        model: 'gpt-4.1',
+        stream: false,
+        store: false,
+      });
+      expect(harness.requests.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+});
diff --git a/packages/kosong/test/e2e/parallel-tool-calls.test.ts b/packages/kosong/test/e2e/parallel-tool-calls.test.ts
new file mode 100644
index 000000000..05e6b5272
--- /dev/null
+++ b/packages/kosong/test/e2e/parallel-tool-calls.test.ts
@@ -0,0 +1,450 @@
+import { generate } from '#/generate';
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import type { ChatProvider, StreamedMessage, ThinkingEffort } from '#/provider';
+import { SimpleToolset, toolOk } from '../fixtures/simple-toolset';
+import type { ToolReturnValue } from '../fixtures/simple-toolset';
+import { step } from '../fixtures/step';
+import type { Tool } from '#/tool';
+import type { JsonValue } from '../fixtures/args-validator';
+import type { TokenUsage } from '#/usage';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Exercises interleaved parallel tool calls end to end: index-based argument
+ * routing, deferred SimpleToolset dispatch, concurrent execution, and ordered
+ * results.
+ */
+function createMockStream(
+  parts: StreamedMessagePart[],
+  opts?: { id?: string; usage?: TokenUsage },
+): StreamedMessage {
+  return {
+    get id(): string | null {
+      return opts?.id ?? null;
+    },
+    get usage(): TokenUsage | null {
+      return opts?.usage ?? null;
+    },
+    finishReason: null,
+    rawFinishReason: null,
+    async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+      for (const part of parts) {
+        yield part;
+      }
+    },
+  };
+}
+
+function createMockProvider(stream: StreamedMessage): ChatProvider {
+  return {
+    name: 'mock',
+    modelName: 'mock-model',
+    thinkingEffort: null,
+    generate: async (
+      _systemPrompt: string,
+      _tools: Tool[],
+      _history: Message[],
+    ): Promise<StreamedMessage> => stream,
+    withThinking(_effort: ThinkingEffort): ChatProvider {
+      return this;
+    },
+  };
+}
+describe('integration: parallel tool calls through SimpleToolset', () => {
+  it('onToolCall fires after the stream drains for indexed parallel calls', async () => {
+    const parts: StreamedMessagePart[] = [
+      {
+        type: 'function',
+        id: 'tc_read_a',
+        function: { name: 'read_file', arguments: '' },
+        _streamIndex: 0,
+      },
+      { type: 'tool_call_part', argumentsPart: '{"path":"a.txt"}', index: 0 },
+      {
+        type: 'function',
+        id: 'tc_read_b',
+        function: { name: 'read_file', arguments: '' },
+        _streamIndex: 1,
+      },
+      { type: 'tool_call_part', argumentsPart: '{"path":"b.txt"}', index: 1 },
+      { type: 'text', text: 'after' },
+    ];
+
+    const stream = createMockStream(parts);
+    const provider = createMockProvider(stream);
+    const events: string[] = [];
+
+    await generate(provider, '', [], [], {
+      onMessagePart(part): void {
+        if (part.type === 'tool_call_part') {
+          events.push(`delta:${part.index}:${part.argumentsPart}`);
+        } else if (part.type === 'text') {
+          events.push(`text:${part.text}`);
+        }
+      },
+      onToolCall(toolCall): void {
+        events.push(`ready:${toolCall.id}:${toolCall.function.arguments ?? ''}`);
+      },
+    });
+
+    expect(events).toEqual([
+      'delta:0:{"path":"a.txt"}',
+      'delta:1:{"path":"b.txt"}',
+      'text:after',
+      'ready:tc_read_a:{"path":"a.txt"}',
+      'ready:tc_read_b:{"path":"b.txt"}',
+    ]);
+  });
+
+  it('three parallel tool_calls with interleaved argument deltas dispatch with correct arguments', async () => {
+    // Simulate an OpenAI-style streaming response where three tool calls
+    // are kicked off with empty arguments, then their argument deltas
+    // arrive in a heavily interleaved order.
+    const parts: StreamedMessagePart[] = [
+      // Three tool-call headers (empty arguments) in order 0, 1, 2.
+      {
+        type: 'function',
+        id: 'tc_read',
+        function: { name: 'read_file', arguments: null },
+        _streamIndex: 0,
+      },
+      {
+        type: 'function',
+        id: 'tc_write',
+        function: { name: 'write_file', arguments: null },
+        _streamIndex: 1,
+      },
+      {
+        type: 'function',
+        id: 'tc_list',
+        function: { name: 'list_dir', arguments: null },
+        _streamIndex: 2,
+      },
+      // Interleaved argument deltas. Arguments for each call, arriving
+      // in an unpredictable order.
+      { type: 'tool_call_part', argumentsPart: '{"path":', index: 0 },
+      { type: 'tool_call_part', argumentsPart: '{"path":', index: 1 },
+      { type: 'tool_call_part', argumentsPart: '{"path":', index: 2 },
+      { type: 'tool_call_part', argumentsPart: '"a.txt"', index: 0 },
+      { type: 'tool_call_part', argumentsPart: '"b.txt",', index: 1 },
+      { type: 'tool_call_part', argumentsPart: '"/tmp"', index: 2 },
+      { type: 'tool_call_part', argumentsPart: '}', index: 0 },
+      { type: 'tool_call_part', argumentsPart: '"data":"X"}', index: 1 },
+      { type: 'tool_call_part', argumentsPart: '}', index: 2 },
+    ];
+
+    const stream = createMockStream(parts);
+    const provider = createMockProvider(stream);
+
+    // Track what arguments each handler actually observed.
+    const observed: Record<string, JsonValue> = {};
+    const dispatchOrder: string[] = [];
+
+    const toolset = new SimpleToolset();
+    toolset.add(
+      {
+        name: 'read_file',
+        description: 'Read a file',
+        parameters: {
+          type: 'object',
+          properties: { path: { type: 'string' } },
+          required: ['path'],
+        },
+      },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        observed['read_file'] = args;
+        dispatchOrder.push('read_file');
+        return toolOk({ output: 'read-OK' });
+      },
+    );
+    toolset.add(
+      {
+        name: 'write_file',
+        description: 'Write a file',
+        parameters: {
+          type: 'object',
+          properties: { path: { type: 'string' }, data: { type: 'string' } },
+          required: ['path', 'data'],
+        },
+      },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        observed['write_file'] = args;
+        dispatchOrder.push('write_file');
+        return toolOk({ output: 'write-OK' });
+      },
+    );
+    toolset.add(
+      {
+        name: 'list_dir',
+        description: 'List a directory',
+        parameters: {
+          type: 'object',
+          properties: { path: { type: 'string' } },
+          required: ['path'],
+        },
+      },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        observed['list_dir'] = args;
+        dispatchOrder.push('list_dir');
+        return toolOk({ output: 'list-OK' });
+      },
+    );
+
+    const result = await step(provider, '', toolset, []);
+
+    // Three tool calls, in stream order.
+    expect(result.toolCalls).toHaveLength(3);
+    expect(result.toolCalls[0]!.function.name).toBe('read_file');
+    expect(result.toolCalls[1]!.function.name).toBe('write_file');
+    expect(result.toolCalls[2]!.function.name).toBe('list_dir');
+
+    // Fully-assembled arguments — no cross-contamination.
+    expect(result.toolCalls[0]!.function.arguments).toBe('{"path":"a.txt"}');
+    expect(result.toolCalls[1]!.function.arguments).toBe('{"path":"b.txt","data":"X"}');
+    expect(result.toolCalls[2]!.function.arguments).toBe('{"path":"/tmp"}');
+
+    // Each handler saw the correct parsed JSON arguments.
+    const toolResults = await result.toolResults();
+    expect(toolResults).toHaveLength(3);
+    expect(toolResults.every((r) => !r.returnValue.isError)).toBe(true);
+
+    expect(observed['read_file']).toEqual({ path: 'a.txt' });
+    expect(observed['write_file']).toEqual({ path: 'b.txt', data: 'X' });
+    expect(observed['list_dir']).toEqual({ path: '/tmp' });
+
+    // The tool_results are returned in the same order as toolCalls,
+    // regardless of handler completion order.
+    expect(toolResults[0]!.toolCallId).toBe('tc_read');
+    expect(toolResults[1]!.toolCallId).toBe('tc_write');
+    expect(toolResults[2]!.toolCallId).toBe('tc_list');
+
+    // `_streamIndex` must be stripped from the stored ToolCall.
+    for (const tc of result.toolCalls) {
+      expect(tc).not.toHaveProperty('_streamIndex');
+    }
+  });
+
+  it('tool handlers run concurrently — total wall time < sum of individual latencies', async () => {
+    // Three parallel tool_calls, each handler sleeps 80ms. If the
+    // handlers were serialised, the total wall time would be ~240ms.
+    // If they are dispatched concurrently (Promise.all style), the
+    // total must be close to ~80ms (with generous slack for CI jitter).
+    const parts: StreamedMessagePart[] = [
+      {
+        type: 'function',
+        id: 'tc_a',
+        function: { name: 'slow', arguments: '{"id":"a"}' },
+        _streamIndex: 0,
+      },
+      {
+        type: 'function',
+        id: 'tc_b',
+        function: { name: 'slow', arguments: '{"id":"b"}' },
+        _streamIndex: 1,
+      },
+      {
+        type: 'function',
+        id: 'tc_c',
+        function: { name: 'slow', arguments: '{"id":"c"}' },
+        _streamIndex: 2,
+      },
+    ];
+
+    const stream = createMockStream(parts);
+    const provider = createMockProvider(stream);
+
+    const toolset = new SimpleToolset();
+    const startTimes: Record<string, number> = {};
+    toolset.add(
+      {
+        name: 'slow',
+        description: 'Slow tool',
+        parameters: {
+          type: 'object',
+          properties: { id: { type: 'string' } },
+          required: ['id'],
+        },
+      },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        const id = (args as { id: string }).id;
+        startTimes[id] = Date.now();
+        await new Promise<void>((r) => setTimeout(r, 80));
+        return toolOk({ output: `done-${id}` });
+      },
+    );
+
+    const t0 = Date.now();
+    const result = await step(provider, '', toolset, []);
+    const toolResults = await result.toolResults();
+    const elapsed = Date.now() - t0;
+
+    expect(toolResults).toHaveLength(3);
+    expect(toolResults.map((r) => r.returnValue.output)).toEqual(['done-a', 'done-b', 'done-c']);
+
+    // All three handlers must have started within a small window of
+    // each other — they were dispatched concurrently, not serially.
+    const t = [startTimes['a']!, startTimes['b']!, startTimes['c']!];
+    const spread = Math.max(...t) - Math.min(...t);
+    expect(spread).toBeLessThan(50); // dispatched within 50ms of each other
+
+    // Total elapsed ≤ ~160ms (80ms handler + generous slack),
+    // NOT ~240ms (3 × 80ms serial).
+    expect(elapsed).toBeLessThan(200);
+  });
+
+  it('tool_results are returned in toolCalls order even when handlers complete out-of-order', async () => {
+    // Reverse-order completion: the last handler finishes first.
+    const parts: StreamedMessagePart[] = [
+      {
+        type: 'function',
+        id: 'tc_slow',
+        function: { name: 'sleep_tool', arguments: '{"ms":100,"tag":"slow"}' },
+        _streamIndex: 0,
+      },
+      {
+        type: 'function',
+        id: 'tc_med',
+        function: { name: 'sleep_tool', arguments: '{"ms":50,"tag":"med"}' },
+        _streamIndex: 1,
+      },
+      {
+        type: 'function',
+        id: 'tc_fast',
+        function: { name: 'sleep_tool', arguments: '{"ms":1,"tag":"fast"}' },
+        _streamIndex: 2,
+      },
+    ];
+
+    const stream = createMockStream(parts);
+    const provider = createMockProvider(stream);
+
+    const completionOrder: string[] = [];
+    const toolset = new SimpleToolset();
+    toolset.add(
+      {
+        name: 'sleep_tool',
+        description: 'Sleep then return tag',
+        parameters: {
+          type: 'object',
+          properties: {
+            ms: { type: 'integer' },
+            tag: { type: 'string' },
+          },
+          required: ['ms', 'tag'],
+        },
+      },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        const { ms, tag } = args as { ms: number; tag: string };
+        await new Promise<void>((r) => setTimeout(r, ms));
+        completionOrder.push(tag);
+        return toolOk({ output: tag });
+      },
+    );
+
+    const result = await step(provider, '', toolset, []);
+    const toolResults = await result.toolResults();
+
+    // Handlers completed fast-first, but results are returned in
+    // toolCalls order.
+    expect(completionOrder[0]).toBe('fast');
+    expect(toolResults.map((r) => r.returnValue.output)).toEqual(['slow', 'med', 'fast']);
+  });
+
+  it('one tool throws — other parallel tools still succeed', async () => {
+    const parts: StreamedMessagePart[] = [
+      {
+        type: 'function',
+        id: 'tc_ok_1',
+        function: { name: 'good', arguments: '{"i":1}' },
+        _streamIndex: 0,
+      },
+      {
+        type: 'function',
+        id: 'tc_bad',
+        function: { name: 'bad', arguments: '{}' },
+        _streamIndex: 1,
+      },
+      {
+        type: 'function',
+        id: 'tc_ok_2',
+        function: { name: 'good', arguments: '{"i":2}' },
+        _streamIndex: 2,
+      },
+    ];
+
+    const stream = createMockStream(parts);
+    const provider = createMockProvider(stream);
+
+    const toolset = new SimpleToolset();
+    toolset.add(
+      {
+        name: 'good',
+        description: 'ok',
+        parameters: { type: 'object', properties: { i: { type: 'integer' } } },
+      },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        const i = (args as { i: number }).i;
+        return toolOk({ output: `ok-${i}` });
+      },
+    );
+    toolset.add(
+      { name: 'bad', description: 'bad', parameters: { type: 'object', properties: {} } },
+      async (): Promise<ToolReturnValue> => {
+        throw new Error('tool explosion');
+      },
+    );
+
+    const result = await step(provider, '', toolset, []);
+    const toolResults = await result.toolResults();
+
+    expect(toolResults).toHaveLength(3);
+    expect(toolResults[0]!.returnValue.isError).toBe(false);
+    expect(toolResults[0]!.returnValue.output).toBe('ok-1');
+    expect(toolResults[1]!.returnValue.isError).toBe(true);
+    expect(toolResults[1]!.returnValue.message).toBe('Error running tool: tool explosion');
+    expect(toolResults[2]!.returnValue.isError).toBe(false);
+    expect(toolResults[2]!.returnValue.output).toBe('ok-2');
+  });
+
+  it('generate (direct) routes interleaved deltas by non-numeric streaming id (Responses API style)', async () => {
+    // OpenAI Responses API uses string `item_id` rather than numeric
+    // index. Verify index-based routing still works when the routing
+    // key is a string.
+    const parts: StreamedMessagePart[] = [
+      {
+        type: 'function',
+        id: 'tc_alpha',
+        function: { name: 't', arguments: null },
+        _streamIndex: 'item_alpha',
+      },
+      {
+        type: 'function',
+        id: 'tc_beta',
+        function: { name: 't', arguments: null },
+        _streamIndex: 'item_beta',
+      },
+      { type: 'tool_call_part', argumentsPart: '{"k":', index: 'item_alpha' },
+      { type: 'tool_call_part', argumentsPart: '{"k":', index: 'item_beta' },
+      { type: 'tool_call_part', argumentsPart: '"A"}', index: 'item_alpha' },
+      { type: 'tool_call_part', argumentsPart: '"B"}', index: 'item_beta' },
+    ];
+
+    const stream = createMockStream(parts);
+    const provider = createMockProvider(stream);
+
+    const seen: ToolCall[] = [];
+    const result = await generate(provider, '', [], [], {
+      onToolCall: (tc: ToolCall): void => {
+        seen.push(tc);
+      },
+    });
+
+    expect(result.message.toolCalls).toHaveLength(2);
+    expect(result.message.toolCalls[0]!.function.arguments).toBe('{"k":"A"}');
+    expect(result.message.toolCalls[1]!.function.arguments).toBe('{"k":"B"}');
+    // onToolCall fired once per fully-assembled call after stream drained.
+    expect(seen).toHaveLength(2);
+    expect(seen[0]!.id).toBe('tc_alpha');
+    expect(seen[1]!.id).toBe('tc_beta');
+  });
+});
diff --git a/packages/kosong/test/e2e/provider-error-handling.test.ts b/packages/kosong/test/e2e/provider-error-handling.test.ts
new file mode 100644
index 000000000..107e83ef5
--- /dev/null
+++ b/packages/kosong/test/e2e/provider-error-handling.test.ts
@@ -0,0 +1,333 @@
+import {
+  APIConnectionError,
+  APIEmptyResponseError,
+  APIStatusError,
+  APITimeoutError,
+  ChatProviderError,
+} from '#/errors';
+import { generate } from '#/generate';
+import type { StreamedMessagePart, ToolCall } from '#/message';
+import type { ChatProvider, StreamedMessage, ThinkingEffort } from '#/provider';
+import { SimpleToolset, toolOk } from '../fixtures/simple-toolset';
+import type { ToolReturnValue } from '../fixtures/simple-toolset';
+import { step } from '../fixtures/step';
+import type { TokenUsage } from '#/usage';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Broader provider-error coverage: timeout propagation, status-code
+ * classification, deferred dispatch after stream failures, and empty-response
+ * errors.
+ */
+function createStream(
+  parts: StreamedMessagePart[],
+  opts?: { id?: string; usage?: TokenUsage },
+): StreamedMessage {
+  return {
+    get id(): string | null {
+      return opts?.id ?? null;
+    },
+    get usage(): TokenUsage | null {
+      return opts?.usage ?? null;
+    },
+    finishReason: null,
+    rawFinishReason: null,
+    async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+      for (const part of parts) {
+        yield part;
+      }
+    },
+  };
+}
+
+function createProvider(stream: StreamedMessage): ChatProvider {
+  return {
+    name: 'mock',
+    modelName: 'mock',
+    thinkingEffort: null,
+    async generate(): Promise<StreamedMessage> {
+      return stream;
+    },
+    withThinking(_effort: ThinkingEffort): ChatProvider {
+      return this;
+    },
+  };
+}
+
+function createThrowingProvider(error: Error): ChatProvider {
+  return {
+    name: 'throwing',
+    modelName: 'throwing',
+    thinkingEffort: null,
+    async generate(): Promise<StreamedMessage> {
+      throw error;
+    },
+    withThinking(_effort: ThinkingEffort): ChatProvider {
+      return this;
+    },
+  };
+}
+
+function createMidStreamThrowingProvider(
+  partsBefore: StreamedMessagePart[],
+  error: Error,
+): ChatProvider {
+  return {
+    name: 'mid-stream-throw',
+    modelName: 'mid-stream-throw',
+    thinkingEffort: null,
+    async generate(): Promise<StreamedMessage> {
+      return {
+        get id(): string | null {
+          return null;
+        },
+        get usage(): TokenUsage | null {
+          return null;
+        },
+        finishReason: null,
+        rawFinishReason: null,
+        async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+          for (const part of partsBefore) {
+            yield part;
+          }
+          throw error;
+        },
+      };
+    },
+    withThinking(_effort: ThinkingEffort): ChatProvider {
+      return this;
+    },
+  };
+}
+describe('e2e: provider error handling (extended)', () => {
+  describe('APITimeoutError propagation', () => {
+    it('APITimeoutError from generate() propagates as APITimeoutError through step()', async () => {
+      const err = new APITimeoutError('deadline exceeded');
+      const provider = createThrowingProvider(err);
+
+      await expect(
+        step(provider, '', new SimpleToolset(), [
+          { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+        ]),
+      ).rejects.toBeInstanceOf(APITimeoutError);
+    });
+
+    it('APITimeoutError mid-stream propagates through generate()', async () => {
+      const provider = createMidStreamThrowingProvider(
+        [{ type: 'text', text: 'partial' }],
+        new APITimeoutError('stream idle timeout'),
+      );
+
+      await expect(generate(provider, '', [], [])).rejects.toBeInstanceOf(APITimeoutError);
+    });
+
+    it('APITimeoutError preserves its message across step() boundaries', async () => {
+      const err = new APITimeoutError('request timed out after 30s');
+      const provider = createThrowingProvider(err);
+
+      try {
+        await step(provider, '', new SimpleToolset(), []);
+        expect.unreachable('should have thrown');
+      } catch (error: unknown) {
+        expect(error).toBeInstanceOf(APITimeoutError);
+        expect((error as Error).message).toBe('request timed out after 30s');
+      }
+    });
+  });
+
+  describe('APIStatusError: 4xx and 5xx classification', () => {
+    const cases = [
+      { status: 400, requestId: 'req-400', label: 'bad_request' },
+      { status: 401, requestId: 'req-401', label: 'unauthorized' },
+      { status: 403, requestId: 'req-403', label: 'forbidden' },
+      { status: 404, requestId: 'req-404', label: 'not_found' },
+      { status: 413, requestId: 'req-413', label: 'payload_too_large' },
+      { status: 429, requestId: 'req-429', label: 'rate_limited' },
+      { status: 500, requestId: 'req-500', label: 'internal_server_error' },
+      { status: 502, requestId: 'req-502', label: 'bad_gateway' },
+      { status: 503, requestId: 'req-503', label: 'service_unavailable' },
+      { status: 504, requestId: 'req-504', label: 'gateway_timeout' },
+    ];
+
+    for (const { status, requestId, label } of cases) {
+      it(`${label} (${status}) propagates through step() with statusCode and requestId intact`, async () => {
+        const err = new APIStatusError(status, `HTTP ${status}`, requestId);
+        const provider = createThrowingProvider(err);
+
+        try {
+          await step(provider, '', new SimpleToolset(), []);
+          expect.unreachable('should have thrown');
+        } catch (error: unknown) {
+          expect(error).toBeInstanceOf(APIStatusError);
+          expect((error as APIStatusError).statusCode).toBe(status);
+          expect((error as APIStatusError).requestId).toBe(requestId);
+          // Base type chain must be intact.
+          expect(error).toBeInstanceOf(ChatProviderError);
+        }
+      });
+    }
+
+    it('APIStatusError with null requestId normalises correctly', async () => {
+      const err = new APIStatusError(500, 'boom');
+      expect(err.requestId).toBeNull();
+
+      const provider = createThrowingProvider(err);
+      await expect(step(provider, '', new SimpleToolset(), [])).rejects.toBeInstanceOf(
+        APIStatusError,
+      );
+    });
+  });
+
+  describe('APIConnectionError propagation', () => {
+    it('mid-stream APIConnectionError propagates through generate()', async () => {
+      const provider = createMidStreamThrowingProvider(
+        [{ type: 'text', text: 'some output' }],
+        new APIConnectionError('socket hang up'),
+      );
+
+      await expect(generate(provider, '', [], [])).rejects.toBeInstanceOf(APIConnectionError);
+    });
+
+    it('APIConnectionError thrown before any part still propagates', async () => {
+      const provider = createMidStreamThrowingProvider(
+        [],
+        new APIConnectionError('connection reset'),
+      );
+
+      await expect(generate(provider, '', [], [])).rejects.toBeInstanceOf(APIConnectionError);
+    });
+  });
+
+  describe('deferred tool dispatch under stream errors', () => {
+    it('handler does NOT fire when stream throws after a fully-formed ToolCall', async () => {
+      // The ToolCall arrives with complete arguments. Under naive
+      // (non-deferred) dispatch, the handler would run before the
+      // error. Deferred dispatch prevents that when the stream later fails.
+      let handlerRan = false;
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'side_effect', description: 'Has a side effect', parameters: {} },
+        async (): Promise<ToolReturnValue> => {
+          handlerRan = true;
+          return toolOk({ output: 'oops' });
+        },
+      );
+
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc_sfx',
+        function: { name: 'side_effect', arguments: '{}' },
+      };
+
+      const provider = createMidStreamThrowingProvider(
+        [tc, { type: 'text', text: 'more text' }],
+        new APIConnectionError('stream died after tool call header'),
+      );
+
+      await expect(step(provider, '', toolset, [])).rejects.toBeInstanceOf(APIConnectionError);
+
+      // Give microtasks a chance to run.
+      await new Promise<void>((r) => setTimeout(r, 20));
+      expect(handlerRan).toBe(false);
+    });
+
+    it('handler does NOT fire when stream throws after interleaved tool_call_part deltas', async () => {
+      let handlerRan = false;
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'search', description: '', parameters: {} },
+        async (): Promise<ToolReturnValue> => {
+          handlerRan = true;
+          return toolOk({ output: 'ok' });
+        },
+      );
+
+      const parts: StreamedMessagePart[] = [
+        {
+          type: 'function',
+          id: 'tc_search',
+          function: { name: 'search', arguments: null },
+          _streamIndex: 0,
+        },
+        { type: 'tool_call_part', argumentsPart: '{"q":', index: 0 },
+        // Stream dies before the arguments are complete.
+      ];
+
+      const provider = createMidStreamThrowingProvider(parts, new APITimeoutError('stream stuck'));
+
+      await expect(step(provider, '', toolset, [])).rejects.toBeInstanceOf(APITimeoutError);
+
+      await new Promise<void>((r) => setTimeout(r, 20));
+      expect(handlerRan).toBe(false);
+    });
+  });
+
+  describe('APIEmptyResponseError', () => {
+    it('completely empty stream -> APIEmptyResponseError from generate()', async () => {
+      const provider = createProvider(createStream([]));
+
+      await expect(generate(provider, '', [], [])).rejects.toBeInstanceOf(APIEmptyResponseError);
+    });
+
+    it('think-only response -> APIEmptyResponseError', async () => {
+      // Think content without any real text or tool calls is treated as
+      // a stream interruption / token-budget-exhausted condition.
+      const provider = createProvider(
+        createStream([{ type: 'think', think: 'thinking aloud...' }]),
+      );
+
+      await expect(generate(provider, '', [], [])).rejects.toThrow(APIEmptyResponseError);
+    });
+
+    it('text with only whitespace + think is still treated as empty', async () => {
+      const provider = createProvider(
+        createStream([
+          { type: 'think', think: 'hmm' },
+          { type: 'text', text: '   \n\t  ' },
+        ]),
+      );
+
+      await expect(generate(provider, '', [], [])).rejects.toThrow(APIEmptyResponseError);
+    });
+
+    it('text with real content passes (no APIEmptyResponseError)', async () => {
+      const provider = createProvider(
+        createStream([
+          { type: 'think', think: 'thinking' },
+          { type: 'text', text: 'actual response' },
+        ]),
+      );
+
+      const result = await generate(provider, '', [], []);
+      expect(result.message.content).toHaveLength(2);
+    });
+
+    it('empty content but non-empty toolCalls passes', async () => {
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc_only',
+        function: { name: 'no_op', arguments: '{}' },
+      };
+      const provider = createProvider(createStream([tc]));
+
+      const result = await generate(provider, '', [], []);
+      expect(result.message.content).toHaveLength(0);
+      expect(result.message.toolCalls).toHaveLength(1);
+    });
+  });
+
+  describe('non-provider errors still propagate', () => {
+    it('TypeError from generate() reaches the step() caller', async () => {
+      const provider = createThrowingProvider(new TypeError('boom'));
+      await expect(step(provider, '', new SimpleToolset(), [])).rejects.toBeInstanceOf(TypeError);
+    });
+
+    it('RangeError mid-stream reaches the generate() caller', async () => {
+      const provider = createMidStreamThrowingProvider(
+        [{ type: 'text', text: 'ok' }],
+        new RangeError('out of range'),
+      );
+      await expect(generate(provider, '', [], [])).rejects.toBeInstanceOf(RangeError);
+    });
+  });
+});
diff --git a/packages/kosong/test/e2e/provider-switching.test.ts b/packages/kosong/test/e2e/provider-switching.test.ts
new file mode 100644
index 000000000..748ccffc5
--- /dev/null
+++ b/packages/kosong/test/e2e/provider-switching.test.ts
@@ -0,0 +1,377 @@
+import { generate } from '#/generate';
+import { extractText } from '#/message';
+import type { Message, StreamedMessagePart } from '#/message';
+import type { ChatProvider, GenerateOptions, StreamedMessage, ThinkingEffort } from '#/provider';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * A configurable mock provider that tracks its own identity and config.
+ * withThinking() and withGenerationKwargs() return new instances.
+ */
+class ConfigurableMockProvider implements ChatProvider {
+  readonly name: string;
+  readonly modelName: string;
+  readonly thinkingEffort: ThinkingEffort | null;
+  private readonly _responseText: string;
+  private readonly _generationKwargs: Record<string, unknown>;
+
+  constructor(opts: {
+    name?: string;
+    modelName?: string;
+    thinkingEffort?: ThinkingEffort | null;
+    responseText?: string;
+    generationKwargs?: Record<string, unknown>;
+  }) {
+    this.name = opts.name ?? 'configurable';
+    this.modelName = opts.modelName ?? 'configurable-model';
+    this.thinkingEffort = opts.thinkingEffort ?? null;
+    this._responseText = opts.responseText ?? 'default response';
+    this._generationKwargs = opts.generationKwargs ?? {};
+  }
+
+  async generate(
+    _systemPrompt: string,
+    _tools: Tool[],
+    _history: Message[],
+  ): Promise<StreamedMessage> {
+    const text = this._responseText;
+    const effort = this.thinkingEffort;
+    return {
+      get id(): string | null {
+        return 'msg-1';
+      },
+      get usage(): TokenUsage | null {
+        return null;
+      },
+      finishReason: null,
+      rawFinishReason: null,
+      async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+        if (effort !== null && effort !== 'off') {
+          yield { type: 'think', think: `thinking at ${effort} effort` };
+        }
+        yield { type: 'text', text };
+      },
+    };
+  }
+
+  withThinking(effort: ThinkingEffort): ConfigurableMockProvider {
+    return new ConfigurableMockProvider({
+      name: this.name,
+      modelName: this.modelName,
+      thinkingEffort: effort,
+      responseText: this._responseText,
+      generationKwargs: { ...this._generationKwargs },
+    });
+  }
+
+  getKwargs(): Record<string, unknown> {
+    return { ...this._generationKwargs };
+  }
+
+  withGenerationKwargs(kwargs: Record<string, unknown>): ConfigurableMockProvider {
+    return new ConfigurableMockProvider({
+      name: this.name,
+      modelName: this.modelName,
+      thinkingEffort: this.thinkingEffort,
+      responseText: this._responseText,
+      generationKwargs: { ...this._generationKwargs, ...kwargs },
+    });
+  }
+}
+
+describe('e2e: provider switching', () => {
+  describe('withThinking()', () => {
+    it('creates a new provider with updated thinking effort', () => {
+      const original = new ConfigurableMockProvider({ thinkingEffort: null });
+      const withHigh = original.withThinking('high');
+
+      expect(original.thinkingEffort).toBeNull();
+      expect(withHigh.thinkingEffort).toBe('high');
+    });
+
+    it('original provider is not mutated by withThinking()', () => {
+      const original = new ConfigurableMockProvider({ thinkingEffort: 'low' });
+      const updated = original.withThinking('high');
+
+      expect(original.thinkingEffort).toBe('low');
+      expect(updated.thinkingEffort).toBe('high');
+
+      // Chain another
+      const updated2 = updated.withThinking('medium');
+      expect(updated.thinkingEffort).toBe('high');
+      expect(updated2.thinkingEffort).toBe('medium');
+    });
+
+    it('withThinking(off) disables thinking', async () => {
+      const withThinking = new ConfigurableMockProvider({ thinkingEffort: 'high' });
+      const noThinking = withThinking.withThinking('off');
+
+      expect(noThinking.thinkingEffort).toBe('off');
+
+      const result = await generate(noThinking, '', [], []);
+      // 'off' should not produce think parts
+      expect(result.message.content.every((p) => p.type !== 'think')).toBe(true);
+    });
+
+    it('generate() with thinking includes think parts', async () => {
+      const provider = new ConfigurableMockProvider({
+        thinkingEffort: 'high',
+        responseText: 'answer',
+      });
+
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.content).toHaveLength(2);
+      expect(result.message.content[0]!.type).toBe('think');
+      expect(result.message.content[1]!.type).toBe('text');
+      expect(extractText(result.message)).toBe('answer');
+    });
+  });
+
+  describe('withGenerationKwargs()', () => {
+    it('creates a new provider with merged kwargs', () => {
+      const original = new ConfigurableMockProvider({});
+      const updated = original.withGenerationKwargs({ temperature: 0.5 });
+
+      expect(original.getKwargs()).toEqual({});
+      expect(updated.getKwargs()).toEqual({ temperature: 0.5 });
+    });
+
+    it('does not affect original provider', () => {
+      const original = new ConfigurableMockProvider({
+        generationKwargs: { maxTokens: 100 },
+      });
+      const updated = original.withGenerationKwargs({ temperature: 0.7 });
+
+      expect(original.getKwargs()).toEqual({ maxTokens: 100 });
+      expect(updated.getKwargs()).toEqual({ maxTokens: 100, temperature: 0.7 });
+    });
+
+    it('successive withGenerationKwargs calls stack correctly', () => {
+      const p1 = new ConfigurableMockProvider({});
+      const p2 = p1.withGenerationKwargs({ temperature: 0.5 });
+      const p3 = p2.withGenerationKwargs({ maxTokens: 200 });
+      const p4 = p3.withGenerationKwargs({ temperature: 0.9 }); // override
+
+      expect(p1.getKwargs()).toEqual({});
+      expect(p2.getKwargs()).toEqual({ temperature: 0.5 });
+      expect(p3.getKwargs()).toEqual({ temperature: 0.5, maxTokens: 200 });
+      expect(p4.getKwargs()).toEqual({ temperature: 0.9, maxTokens: 200 });
+    });
+  });
+
+  describe('concurrent generate() calls on different providers', () => {
+    it('two providers can generate() concurrently without interference', async () => {
+      const providerA = new ConfigurableMockProvider({
+        name: 'provider-a',
+        responseText: 'response-A',
+      });
+      const providerB = new ConfigurableMockProvider({
+        name: 'provider-b',
+        responseText: 'response-B',
+      });
+
+      const [resultA, resultB] = await Promise.all([
+        generate(providerA, '', [], []),
+        generate(providerB, '', [], []),
+      ]);
+
+      expect(extractText(resultA.message)).toBe('response-A');
+      expect(extractText(resultB.message)).toBe('response-B');
+    });
+
+    it('same provider can handle concurrent generate() calls', async () => {
+      let callCount = 0;
+
+      const provider: ChatProvider = {
+        name: 'concurrent',
+        modelName: 'concurrent-model',
+        thinkingEffort: null,
+        async generate(
+          _systemPrompt: string,
+          _tools: Tool[],
+          _history: Message[],
+        ): Promise<StreamedMessage> {
+          const myCount = ++callCount;
+          // Simulate slight delay
+          await new Promise<void>((r) => setTimeout(r, 5));
+          return {
+            get id(): string | null {
+              return `msg-${myCount}`;
+            },
+            get usage(): TokenUsage | null {
+              return null;
+            },
+            finishReason: null,
+            rawFinishReason: null,
+            async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+              yield { type: 'text', text: `response-${myCount}` };
+            },
+          };
+        },
+        withThinking(_effort: ThinkingEffort): ChatProvider {
+          return this;
+        },
+      };
+
+      const results = await Promise.all([
+        generate(provider, '', [], []),
+        generate(provider, '', [], []),
+        generate(provider, '', [], []),
+      ]);
+
+      // Each should have a unique response
+      const texts = results.map((r) => extractText(r.message));
+      expect(texts).toHaveLength(3);
+      const uniqueTexts = new Set(texts);
+      expect(uniqueTexts.size).toBe(3);
+    });
+
+    it('original and withThinking() provider can generate() concurrently', async () => {
+      const original = new ConfigurableMockProvider({
+        thinkingEffort: null,
+        responseText: 'no-think',
+      });
+      const thinking = original.withThinking('high');
+
+      const [resultOrig, resultThink] = await Promise.all([
+        generate(original, '', [], []),
+        generate(thinking, '', [], []),
+      ]);
+
+      // Original: no think parts
+      expect(resultOrig.message.content.every((p) => p.type !== 'think')).toBe(true);
+      expect(extractText(resultOrig.message)).toBe('no-think');
+
+      // Thinking: has think parts
+      expect(resultThink.message.content.some((p) => p.type === 'think')).toBe(true);
+      expect(extractText(resultThink.message)).toBe('no-think');
+    });
+  });
+
+  describe('provider identity preservation', () => {
+    it('withThinking preserves name and modelName', () => {
+      const original = new ConfigurableMockProvider({
+        name: 'my-provider',
+        modelName: 'gpt-4o',
+      });
+      const updated = original.withThinking('medium');
+
+      expect(updated.name).toBe('my-provider');
+      expect(updated.modelName).toBe('gpt-4o');
+    });
+
+    it('withGenerationKwargs preserves name, modelName, and thinkingEffort', () => {
+      const original = new ConfigurableMockProvider({
+        name: 'my-provider',
+        modelName: 'gpt-4o',
+        thinkingEffort: 'high',
+      });
+      const updated = original.withGenerationKwargs({ temperature: 0.3 });
+
+      expect(updated.name).toBe('my-provider');
+      expect(updated.modelName).toBe('gpt-4o');
+      expect(updated.thinkingEffort).toBe('high');
+    });
+  });
+
+  describe('provider immutability', () => {
+    it('withThinking does not modify the original provider', () => {
+      const original = new ConfigurableMockProvider({
+        thinkingEffort: 'low',
+        responseText: 'original',
+      });
+
+      const originalEffort = original.thinkingEffort;
+      const _updated = original.withThinking('high');
+
+      // Original must be completely unchanged
+      expect(original.thinkingEffort).toBe(originalEffort);
+      expect(original.thinkingEffort).toBe('low');
+    });
+
+    it('chained withThinking calls do not mutate any intermediate provider', () => {
+      const p1 = new ConfigurableMockProvider({ thinkingEffort: null });
+      const p2 = p1.withThinking('low');
+      const p3 = p2.withThinking('medium');
+      const p4 = p3.withThinking('high');
+
+      expect(p1.thinkingEffort).toBeNull();
+      expect(p2.thinkingEffort).toBe('low');
+      expect(p3.thinkingEffort).toBe('medium');
+      expect(p4.thinkingEffort).toBe('high');
+    });
+
+    it('AbortSignal abort does not affect provider state for subsequent generate', async () => {
+      const provider = new ConfigurableMockProvider({
+        responseText: 'test',
+        thinkingEffort: 'low',
+      });
+
+      // First generate with an abort signal that gets aborted mid-stream
+      const controller = new AbortController();
+      let partCount = 0;
+
+      // Create a provider that yields slowly so we can abort mid-stream
+      const slowProvider: ChatProvider = {
+        name: 'slow',
+        modelName: 'slow-model',
+        thinkingEffort: provider.thinkingEffort,
+        async generate(
+          _systemPrompt: string,
+          _tools: Tool[],
+          _history: Message[],
+          _options?: GenerateOptions,
+        ): Promise<StreamedMessage> {
+          return {
+            get id(): string | null {
+              return 'msg-slow';
+            },
+            get usage(): TokenUsage | null {
+              return null;
+            },
+            finishReason: null,
+            rawFinishReason: null,
+            async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+              yield { type: 'text', text: 'part1' };
+              await new Promise<void>((r) => setTimeout(r, 5));
+              yield { type: 'text', text: 'part2' };
+              await new Promise<void>((r) => setTimeout(r, 5));
+              yield { type: 'text', text: 'part3' };
+            },
+          };
+        },
+        withThinking(_effort: ThinkingEffort): ChatProvider {
+          return this;
+        },
+      };
+
+      const abortedPromise = generate(
+        slowProvider,
+        '',
+        [],
+        [],
+        {
+          onMessagePart(_part: StreamedMessagePart): void {
+            partCount++;
+            if (partCount >= 2) {
+              controller.abort();
+            }
+          },
+        },
+        { signal: controller.signal },
+      );
+
+      await expect(abortedPromise).rejects.toThrow();
+
+      // Now do a normal generate with the same base provider
+      const result = await generate(provider, '', [], []);
+      expect(extractText(result.message)).toBe('test');
+
+      // Provider state should be unaffected
+      expect(provider.thinkingEffort).toBe('low');
+    });
+  });
+});
diff --git a/packages/kosong/test/e2e/streaming-fidelity.test.ts b/packages/kosong/test/e2e/streaming-fidelity.test.ts
new file mode 100644
index 000000000..99ee0b331
--- /dev/null
+++ b/packages/kosong/test/e2e/streaming-fidelity.test.ts
@@ -0,0 +1,419 @@
+import { generate } from '#/generate';
+import type { GenerateCallbacks } from '#/generate';
+import type { StreamedMessagePart, TextPart, ThinkPart, ToolCall } from '#/message';
+import { extractText } from '#/message';
+import { MockChatProvider } from '../fixtures/mock-provider';
+import { SimpleToolset, toolOk } from '../fixtures/simple-toolset';
+import type { ToolReturnValue } from '../fixtures/simple-toolset';
+import { step } from '../fixtures/step';
+import { describe, expect, it } from 'vitest';
+describe('e2e: streaming fidelity', () => {
+  describe('TextPart delta merging', () => {
+    it('100+ TextPart deltas merge into one text content part', async () => {
+      const count = 120;
+      const parts: StreamedMessagePart[] = [];
+      for (let i = 0; i < count; i++) {
+        parts.push({ type: 'text', text: `chunk${i} ` });
+      }
+
+      const provider = new MockChatProvider(parts);
+      const result = await generate(provider, '', [], []);
+
+      // All text chunks should be merged into a single TextPart
+      expect(result.message.content).toHaveLength(1);
+      expect(result.message.content[0]!.type).toBe('text');
+
+      const expected = Array.from({ length: count }, (_, i) => `chunk${i} `).join('');
+      expect(extractText(result.message)).toBe(expected);
+    });
+
+    it('empty text deltas do not create spurious parts', async () => {
+      const parts: StreamedMessagePart[] = [
+        { type: 'text', text: '' },
+        { type: 'text', text: 'hello' },
+        { type: 'text', text: '' },
+        { type: 'text', text: ' world' },
+        { type: 'text', text: '' },
+      ];
+
+      const provider = new MockChatProvider(parts);
+      const result = await generate(provider, '', [], []);
+
+      // Should be merged into a single text part
+      expect(result.message.content).toHaveLength(1);
+      expect(extractText(result.message)).toBe('hello world');
+    });
+  });
+
+  describe('interleaved ThinkPart + TextPart', () => {
+    it('ThinkPart then TextPart produces separate parts, not mixed', async () => {
+      const parts: StreamedMessagePart[] = [
+        { type: 'think', think: 'Let me ' },
+        { type: 'think', think: 'think about this...' },
+        { type: 'text', text: 'Here is ' },
+        { type: 'text', text: 'my answer.' },
+      ];
+
+      const provider = new MockChatProvider(parts);
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.content).toHaveLength(2);
+      expect(result.message.content[0]).toEqual({
+        type: 'think',
+        think: 'Let me think about this...',
+      });
+      expect(result.message.content[1]).toEqual({
+        type: 'text',
+        text: 'Here is my answer.',
+      });
+    });
+
+    it('alternating think-text-think-text produces 4 separate parts', async () => {
+      const parts: StreamedMessagePart[] = [
+        { type: 'think', think: 'thought-A' },
+        { type: 'text', text: 'text-A' },
+        { type: 'think', think: 'thought-B' },
+        { type: 'text', text: 'text-B' },
+      ];
+
+      const provider = new MockChatProvider(parts);
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.content).toHaveLength(4);
+      expect(result.message.content[0]).toEqual({ type: 'think', think: 'thought-A' });
+      expect(result.message.content[1]).toEqual({ type: 'text', text: 'text-A' });
+      expect(result.message.content[2]).toEqual({ type: 'think', think: 'thought-B' });
+      expect(result.message.content[3]).toEqual({ type: 'text', text: 'text-B' });
+    });
+
+    it('many ThinkPart deltas followed by many TextPart deltas are properly separated', async () => {
+      const parts: StreamedMessagePart[] = [];
+      for (let i = 0; i < 50; i++) {
+        parts.push({ type: 'think', think: `t${i} ` });
+      }
+      for (let i = 0; i < 50; i++) {
+        parts.push({ type: 'text', text: `w${i} ` });
+      }
+
+      const provider = new MockChatProvider(parts);
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.content).toHaveLength(2);
+      expect(result.message.content[0]!.type).toBe('think');
+      expect(result.message.content[1]!.type).toBe('text');
+
+      const thinkPart = result.message.content[0] as ThinkPart;
+      const textPart = result.message.content[1] as TextPart;
+      expect(thinkPart.think.split(' ').filter(Boolean)).toHaveLength(50);
+      expect(textPart.text.split(' ').filter(Boolean)).toHaveLength(50);
+    });
+  });
+
+  describe('ToolCall argument assembly from ToolCallPart deltas', () => {
+    it('single ToolCall with 10+ ToolCallPart deltas assembles arguments correctly', async () => {
+      const fullArgs = JSON.stringify({
+        query: 'a very long search query with many words to ensure streaming',
+        limit: 100,
+        offset: 0,
+        filters: { category: 'test', status: 'active' },
+      });
+
+      // Split into small chunks
+      const chunkSize = 8;
+      const parts: StreamedMessagePart[] = [
+        {
+          type: 'function',
+          id: 'tc-1',
+          function: { name: 'search', arguments: null },
+        } satisfies ToolCall,
+      ];
+
+      for (let i = 0; i < fullArgs.length; i += chunkSize) {
+        parts.push({
+          type: 'tool_call_part',
+          argumentsPart: fullArgs.slice(i, i + chunkSize),
+        });
+      }
+
+      // Add text after so the response is not empty
+      parts.push({ type: 'text', text: 'done' });
+
+      const provider = new MockChatProvider(parts);
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.toolCalls).toHaveLength(1);
+      expect(result.message.toolCalls[0]!.function.arguments).toBe(fullArgs);
+
+      // Verify JSON is parseable and complete
+      const parsed = JSON.parse(result.message.toolCalls[0]!.function.arguments!) as Record<
+        string,
+        unknown
+      >;
+      expect(parsed['query']).toBe('a very long search query with many words to ensure streaming');
+      expect(parsed['limit']).toBe(100);
+    });
+
+    it('multiple ToolCalls each with ToolCallPart deltas assemble independently', async () => {
+      const args1 = JSON.stringify({ file: 'a.ts' });
+      const args2 = JSON.stringify({ file: 'b.ts' });
+
+      const parts: StreamedMessagePart[] = [
+        // First tool call
+        {
+          type: 'function',
+          id: 'tc-a',
+          function: { name: 'read_file', arguments: null },
+        } satisfies ToolCall,
+        { type: 'tool_call_part', argumentsPart: args1.slice(0, 5) },
+        { type: 'tool_call_part', argumentsPart: args1.slice(5) },
+        // Second tool call
+        {
+          type: 'function',
+          id: 'tc-b',
+          function: { name: 'read_file', arguments: null },
+        } satisfies ToolCall,
+        { type: 'tool_call_part', argumentsPart: args2.slice(0, 5) },
+        { type: 'tool_call_part', argumentsPart: args2.slice(5) },
+        // Text to avoid empty response
+        { type: 'text', text: 'files read' },
+      ];
+
+      const provider = new MockChatProvider(parts);
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.toolCalls).toHaveLength(2);
+      expect(result.message.toolCalls[0]!.function.arguments).toBe(args1);
+      expect(result.message.toolCalls[1]!.function.arguments).toBe(args2);
+    });
+
+    it('ToolCallPart with null argumentsPart does not corrupt arguments', async () => {
+      const parts: StreamedMessagePart[] = [
+        {
+          type: 'function',
+          id: 'tc-null',
+          function: { name: 'tool_x', arguments: null },
+        } satisfies ToolCall,
+        { type: 'tool_call_part', argumentsPart: null },
+        { type: 'tool_call_part', argumentsPart: '{"key":' },
+        { type: 'tool_call_part', argumentsPart: null },
+        { type: 'tool_call_part', argumentsPart: '"val"}' },
+        { type: 'text', text: 'done' },
+      ];
+
+      const provider = new MockChatProvider(parts);
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.toolCalls).toHaveLength(1);
+      expect(result.message.toolCalls[0]!.function.arguments).toBe('{"key":"val"}');
+    });
+  });
+
+  describe('onMessagePart callback fidelity', () => {
+    it('receives raw unmerged parts as deep copies', async () => {
+      const parts: StreamedMessagePart[] = [
+        { type: 'text', text: 'chunk1' },
+        { type: 'text', text: 'chunk2' },
+        { type: 'text', text: 'chunk3' },
+      ];
+
+      const provider = new MockChatProvider(parts);
+      const receivedParts: StreamedMessagePart[] = [];
+
+      const callbacks: GenerateCallbacks = {
+        onMessagePart(part: StreamedMessagePart): void {
+          receivedParts.push(part);
+        },
+      };
+
+      const result = await generate(provider, '', [], [], callbacks);
+
+      // Callback should receive each raw part unmerged
+      expect(receivedParts).toHaveLength(3);
+      expect(receivedParts[0]).toEqual({ type: 'text', text: 'chunk1' });
+      expect(receivedParts[1]).toEqual({ type: 'text', text: 'chunk2' });
+      expect(receivedParts[2]).toEqual({ type: 'text', text: 'chunk3' });
+
+      // But the final message should be merged
+      expect(result.message.content).toHaveLength(1);
+      expect(extractText(result.message)).toBe('chunk1chunk2chunk3');
+    });
+
+    it('callback receives deep copies that are not mutated by merging', async () => {
+      const parts: StreamedMessagePart[] = [
+        { type: 'text', text: 'A' },
+        { type: 'text', text: 'B' },
+      ];
+
+      const provider = new MockChatProvider(parts);
+      const receivedParts: StreamedMessagePart[] = [];
+
+      await generate(provider, '', [], [], {
+        onMessagePart(part: StreamedMessagePart): void {
+          receivedParts.push(part);
+        },
+      });
+
+      // The first callback part should still be 'A', not 'AB'
+      // because the callback receives a deep copy
+      expect((receivedParts[0] as TextPart).text).toBe('A');
+      expect((receivedParts[1] as TextPart).text).toBe('B');
+    });
+
+    it('callback receives ToolCallPart deltas independently', async () => {
+      const parts: StreamedMessagePart[] = [
+        {
+          type: 'function',
+          id: 'tc-1',
+          function: { name: 'tool', arguments: null },
+        } satisfies ToolCall,
+        { type: 'tool_call_part', argumentsPart: '{"a":' },
+        { type: 'tool_call_part', argumentsPart: '1}' },
+        { type: 'text', text: 'done' },
+      ];
+
+      const provider = new MockChatProvider(parts);
+      const receivedParts: StreamedMessagePart[] = [];
+
+      await generate(provider, '', [], [], {
+        onMessagePart(part: StreamedMessagePart): void {
+          receivedParts.push(part);
+        },
+      });
+
+      expect(receivedParts).toHaveLength(4);
+      // Each ToolCallPart should be received separately
+      expect(receivedParts[0]!.type).toBe('function');
+      expect(receivedParts[1]).toEqual({ type: 'tool_call_part', argumentsPart: '{"a":' });
+      expect(receivedParts[2]).toEqual({ type: 'tool_call_part', argumentsPart: '1}' });
+      expect(receivedParts[3]).toEqual({ type: 'text', text: 'done' });
+    });
+  });
+
+  describe('onToolCall callback timing', () => {
+    it('fires only after ToolCall is fully assembled from parts', async () => {
+      const parts: StreamedMessagePart[] = [
+        {
+          type: 'function',
+          id: 'tc-1',
+          function: { name: 'search', arguments: null },
+        } satisfies ToolCall,
+        { type: 'tool_call_part', argumentsPart: '{"query' },
+        { type: 'tool_call_part', argumentsPart: '":"test' },
+        { type: 'tool_call_part', argumentsPart: '"}' },
+        // New text part flushes the pending ToolCall
+        { type: 'text', text: 'searching...' },
+      ];
+
+      const provider = new MockChatProvider(parts);
+      const toolCallSnapshots: string[] = [];
+
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'search', description: 'Search', parameters: {} },
+        async (): Promise<ToolReturnValue> => toolOk({ output: 'found' }),
+      );
+
+      await step(provider, '', toolset, [], {
+        onMessagePart(part: StreamedMessagePart): void {
+          // Track when onMessagePart sees the ToolCall
+          if (part.type === 'function') {
+            const tc = part;
+            toolCallSnapshots.push(`onMessagePart:args=${tc.function.arguments}`);
+          }
+        },
+      });
+
+      // The onMessagePart callback should see the ToolCall with null arguments
+      // (because it's the first delta, deep-copied before merging)
+      expect(toolCallSnapshots[0]).toBe('onMessagePart:args=null');
+    });
+
+    it('onToolCall fires for each ToolCall in multi-tool stream', async () => {
+      const parts: StreamedMessagePart[] = [
+        {
+          type: 'function',
+          id: 'tc-a',
+          function: { name: 'tool_a', arguments: '{"x":1}' },
+        } satisfies ToolCall,
+        {
+          type: 'function',
+          id: 'tc-b',
+          function: { name: 'tool_b', arguments: '{"y":2}' },
+        } satisfies ToolCall,
+        { type: 'text', text: 'done' },
+      ];
+
+      const provider = new MockChatProvider(parts);
+
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'tool_a', description: 'A', parameters: {} },
+        async (): Promise<ToolReturnValue> => toolOk({ output: 'a' }),
+      );
+      toolset.add(
+        { name: 'tool_b', description: 'B', parameters: {} },
+        async (): Promise<ToolReturnValue> => toolOk({ output: 'b' }),
+      );
+
+      const result = await step(provider, '', toolset, []);
+      const toolResults = await result.toolResults();
+
+      expect(result.toolCalls).toHaveLength(2);
+      expect(result.toolCalls[0]!.id).toBe('tc-a');
+      expect(result.toolCalls[1]!.id).toBe('tc-b');
+      expect(toolResults).toHaveLength(2);
+    });
+  });
+
+  describe('large-scale streaming', () => {
+    it('1000 TextPart deltas → single merged content', async () => {
+      const count = 1000;
+      const parts: StreamedMessagePart[] = [];
+      for (let i = 0; i < count; i++) {
+        parts.push({ type: 'text', text: 'x' });
+      }
+
+      const provider = new MockChatProvider(parts);
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.content).toHaveLength(1);
+      expect(extractText(result.message)).toBe('x'.repeat(count));
+    });
+
+    it('text + 5 tool calls with streamed args + trailing text', async () => {
+      const parts: StreamedMessagePart[] = [{ type: 'text', text: 'Planning...' }];
+
+      for (let i = 0; i < 5; i++) {
+        const args = JSON.stringify({ index: i });
+        parts.push({
+          type: 'function',
+          id: `tc-${i}`,
+          function: { name: 'task', arguments: null },
+        } satisfies ToolCall);
+        // Stream args in 3 chunks
+        const chunk = Math.ceil(args.length / 3);
+        for (let j = 0; j < args.length; j += chunk) {
+          parts.push({ type: 'tool_call_part', argumentsPart: args.slice(j, j + chunk) });
+        }
+      }
+
+      parts.push({ type: 'text', text: 'All tasks dispatched.' });
+
+      const provider = new MockChatProvider(parts);
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.content).toHaveLength(2);
+      expect(result.message.content[0]).toEqual({ type: 'text', text: 'Planning...' });
+      expect(result.message.content[1]).toEqual({ type: 'text', text: 'All tasks dispatched.' });
+      expect(result.message.toolCalls).toHaveLength(5);
+
+      for (let i = 0; i < 5; i++) {
+        expect(result.message.toolCalls[i]!.id).toBe(`tc-${i}`);
+        const parsed = JSON.parse(result.message.toolCalls[i]!.function.arguments!) as {
+          index: number;
+        };
+        expect(parsed.index).toBe(i);
+      }
+    });
+  });
+});
diff --git a/packages/kosong/test/e2e/streaming-providers.test.ts b/packages/kosong/test/e2e/streaming-providers.test.ts
new file mode 100644
index 000000000..8e1256091
--- /dev/null
+++ b/packages/kosong/test/e2e/streaming-providers.test.ts
@@ -0,0 +1,387 @@
+import { generate } from '#/generate';
+import type { GenerateCallbacks } from '#/generate';
+import type { Message, StreamedMessagePart, TextPart, ThinkPart, ToolCall } from '#/message';
+import { extractText } from '#/message';
+import type { ChatProvider, StreamedMessage, ThinkingEffort } from '#/provider';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Build a StreamedMessage from an array of parts plus metadata.
+ * Simulates what a provider adapter would produce.
+ */
+function buildStream(
+  parts: StreamedMessagePart[],
+  opts?: { id?: string; usage?: TokenUsage },
+): StreamedMessage {
+  return {
+    get id(): string | null {
+      return opts?.id ?? null;
+    },
+    get usage(): TokenUsage | null {
+      return opts?.usage ?? null;
+    },
+    finishReason: null,
+    rawFinishReason: null,
+    async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+      for (const part of parts) {
+        yield part;
+      }
+    },
+  };
+}
+
+/**
+ * A test provider that returns a single pre-built StreamedMessage.
+ */
+class SingleStreamProvider implements ChatProvider {
+  readonly name: string;
+  readonly modelName: string;
+  readonly thinkingEffort: ThinkingEffort | null = null;
+  private readonly _stream: StreamedMessage;
+
+  constructor(stream: StreamedMessage, name: string = 'test') {
+    this._stream = stream;
+    this.name = name;
+    this.modelName = name;
+  }
+
+  async generate(
+    _systemPrompt: string,
+    _tools: Tool[],
+    _history: Message[],
+  ): Promise<StreamedMessage> {
+    return this._stream;
+  }
+
+  withThinking(_effort: ThinkingEffort): ChatProvider {
+    return this;
+  }
+}
+
+describe('integration: streaming provider contracts', () => {
+  describe('synthetic Kimi-style SSE streaming', () => {
+    it('multi-chunk text + tool_call + tool_call_part + usage', async () => {
+      const usage: TokenUsage = {
+        inputOther: 100,
+        output: 50,
+        inputCacheRead: 20,
+        inputCacheCreation: 0,
+      };
+
+      // Simulate: text delta -> text delta -> tool_call -> tool_call_part -> (usage on stream)
+      const parts: StreamedMessagePart[] = [
+        { type: 'text', text: 'Hello ' },
+        { type: 'text', text: 'world!' },
+        {
+          type: 'function',
+          id: 'tc-kimi-1',
+          function: { name: 'search', arguments: null },
+        } satisfies ToolCall,
+        { type: 'tool_call_part', argumentsPart: '{"query":' },
+        { type: 'tool_call_part', argumentsPart: '"vitest"}' },
+      ];
+
+      const stream = buildStream(parts, { id: 'kimi-resp-1', usage });
+      const provider = new SingleStreamProvider(stream, 'kimi');
+
+      const receivedParts: StreamedMessagePart[] = [];
+      const callbacks: GenerateCallbacks = {
+        onMessagePart(part: StreamedMessagePart): void {
+          receivedParts.push(part);
+        },
+      };
+
+      const result = await generate(provider, 'system', [], [], callbacks);
+
+      // onMessagePart called in correct order: text, text, tool_call, part, part
+      expect(receivedParts).toHaveLength(5);
+      expect(receivedParts[0]!.type).toBe('text');
+      expect(receivedParts[1]!.type).toBe('text');
+      expect(receivedParts[2]!.type).toBe('function');
+      expect(receivedParts[3]!.type).toBe('tool_call_part');
+      expect(receivedParts[4]!.type).toBe('tool_call_part');
+
+      // Final message.content should merge text deltas
+      expect(result.message.content).toHaveLength(1);
+      expect(extractText(result.message)).toBe('Hello world!');
+
+      // ToolCall assembled correctly
+      expect(result.message.toolCalls).toHaveLength(1);
+      expect(result.message.toolCalls[0]!.function.arguments).toBe('{"query":"vitest"}');
+
+      // Usage extracted from the stream metadata
+      expect(result.usage).toEqual(usage);
+      expect(result.id).toBe('kimi-resp-1');
+    });
+
+    it('reasoning_content chunks interleave with text', async () => {
+      const parts: StreamedMessagePart[] = [
+        { type: 'think', think: 'Let me ' },
+        { type: 'think', think: 'reason about this.' },
+        { type: 'text', text: 'The answer is 42.' },
+      ];
+
+      const stream = buildStream(parts, { id: 'kimi-think-1' });
+      const provider = new SingleStreamProvider(stream, 'kimi');
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.content).toHaveLength(2);
+      expect(result.message.content[0]!.type).toBe('think');
+      expect((result.message.content[0] as ThinkPart).think).toBe('Let me reason about this.');
+      expect(result.message.content[1]!.type).toBe('text');
+      expect((result.message.content[1] as TextPart).text).toBe('The answer is 42.');
+    });
+  });
+
+  describe('Anthropic-style event streaming', () => {
+    it('message_start -> content_block_delta[text] -> thinking + signature -> tool_use', async () => {
+      // Simulate Anthropic stream events mapped to StreamedMessagePart sequence.
+      // In the real provider, events like message_start, content_block_start, etc.
+      // are converted to StreamedMessagePart by AnthropicStreamedMessage.
+      // Here we simulate the output of that conversion.
+
+      const parts: StreamedMessagePart[] = [
+        // content_block_start(text) => text with initial empty
+        { type: 'text', text: '' },
+        // content_block_delta(text_delta)
+        { type: 'text', text: 'Here is my response.' },
+        // content_block_start(thinking) => think part
+        { type: 'think', think: '' },
+        // content_block_delta(thinking_delta)
+        { type: 'think', think: 'I need to analyze this carefully.' },
+        // content_block_delta(signature_delta) => think with encrypted
+        { type: 'think', think: '', encrypted: 'sig-abc123' },
+        // content_block_start(tool_use)
+        {
+          type: 'function',
+          id: 'toolu_01',
+          function: { name: 'read_file', arguments: '' },
+        } satisfies ToolCall,
+        // content_block_delta(input_json_delta)
+        { type: 'tool_call_part', argumentsPart: '{"path":"/src/main.ts"}' },
+      ];
+
+      const usage: TokenUsage = {
+        inputOther: 200,
+        output: 100,
+        inputCacheRead: 50,
+        inputCacheCreation: 10,
+      };
+
+      const stream = buildStream(parts, { id: 'msg_anthropic_1', usage });
+      const provider = new SingleStreamProvider(stream, 'anthropic');
+      const result = await generate(provider, '', [], []);
+
+      // Text parts should merge: '' + 'Here is my response.'
+      const textParts = result.message.content.filter((p) => p.type === 'text');
+      expect(textParts).toHaveLength(1);
+      expect((textParts[0] as TextPart).text).toBe('Here is my response.');
+
+      // Think part should have encrypted set after signature_delta
+      const thinkParts = result.message.content.filter((p) => p.type === 'think');
+      expect(thinkParts).toHaveLength(1);
+      const thinkPart = thinkParts[0] as ThinkPart;
+      expect(thinkPart.think).toBe('I need to analyze this carefully.');
+      expect(thinkPart.encrypted).toBe('sig-abc123');
+
+      // ToolCall assembled
+      expect(result.message.toolCalls).toHaveLength(1);
+      expect(result.message.toolCalls[0]!.id).toBe('toolu_01');
+      expect(result.message.toolCalls[0]!.function.name).toBe('read_file');
+      expect(result.message.toolCalls[0]!.function.arguments).toBe('{"path":"/src/main.ts"}');
+    });
+
+    it('redacted_thinking yields ThinkPart with encrypted and empty think', async () => {
+      const parts: StreamedMessagePart[] = [
+        // redacted_thinking block
+        { type: 'think', think: '', encrypted: 'redacted-data-blob' },
+        // Then a normal text response
+        { type: 'text', text: 'I have processed the request.' },
+      ];
+
+      const stream = buildStream(parts);
+      const provider = new SingleStreamProvider(stream, 'anthropic');
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.content).toHaveLength(2);
+      const redacted = result.message.content[0] as ThinkPart;
+      expect(redacted.type).toBe('think');
+      expect(redacted.think).toBe('');
+      expect(redacted.encrypted).toBe('redacted-data-blob');
+    });
+
+    it('multiple content blocks in Anthropic style', async () => {
+      const parts: StreamedMessagePart[] = [
+        // First thinking block
+        { type: 'think', think: 'Step 1: analyze.' },
+        { type: 'think', think: '', encrypted: 'sig-1' },
+        // First text block
+        { type: 'text', text: 'First part.' },
+        // Second thinking block (new block, can not merge with first due to encrypted)
+        { type: 'think', think: 'Step 2: synthesize.' },
+        { type: 'think', think: '', encrypted: 'sig-2' },
+        // Second text block
+        { type: 'text', text: 'Second part.' },
+      ];
+
+      const stream = buildStream(parts);
+      const provider = new SingleStreamProvider(stream, 'anthropic');
+      const result = await generate(provider, '', [], []);
+
+      // Think blocks cannot merge once encrypted is set, so we get:
+      // think(step1 + sig), text(first), think(step2 + sig), text(second)
+      expect(result.message.content).toHaveLength(4);
+      expect(result.message.content[0]!.type).toBe('think');
+      expect((result.message.content[0] as ThinkPart).encrypted).toBe('sig-1');
+      expect(result.message.content[1]!.type).toBe('text');
+      expect(result.message.content[2]!.type).toBe('think');
+      expect((result.message.content[2] as ThinkPart).encrypted).toBe('sig-2');
+      expect(result.message.content[3]!.type).toBe('text');
+    });
+  });
+
+  describe('Google GenAI-style streaming', () => {
+    it('multi-chunk with text + functionCall + thought', async () => {
+      // Google GenAI streaming yields chunks that the GoogleGenAIStreamedMessage
+      // converts to StreamedMessagePart. Simulate the output.
+
+      const parts: StreamedMessagePart[] = [
+        // Thought chunk
+        { type: 'think', think: 'Analyzing the request...' },
+        // Text chunk
+        { type: 'text', text: 'I will help you with that.' },
+        // Function call chunk - Google format uses {name}_{id} for toolCallId
+        {
+          type: 'function',
+          id: 'search_12345',
+          function: { name: 'search', arguments: '{"query":"vitest docs"}' },
+        } satisfies ToolCall,
+      ];
+
+      const usage: TokenUsage = {
+        inputOther: 150,
+        output: 80,
+        inputCacheRead: 30,
+        inputCacheCreation: 0,
+      };
+
+      const stream = buildStream(parts, { id: 'resp-google-1', usage });
+      const provider = new SingleStreamProvider(stream, 'google_genai');
+      const result = await generate(provider, '', [], []);
+
+      // Think part
+      expect(result.message.content).toHaveLength(2);
+      expect(result.message.content[0]!.type).toBe('think');
+      expect((result.message.content[0] as ThinkPart).think).toBe('Analyzing the request...');
+
+      // Text part
+      expect(result.message.content[1]!.type).toBe('text');
+      expect((result.message.content[1] as TextPart).text).toBe('I will help you with that.');
+
+      // Function call with correct ID format
+      expect(result.message.toolCalls).toHaveLength(1);
+      const tc = result.message.toolCalls[0]!;
+      expect(tc.id).toBe('search_12345');
+      expect(tc.id).toMatch(/^search_\d+$/);
+      expect(tc.function.name).toBe('search');
+      expect(tc.function.arguments).toBe('{"query":"vitest docs"}');
+    });
+
+    it('Google function_call ID format: {name}_{id}', async () => {
+      const parts: StreamedMessagePart[] = [
+        {
+          type: 'function',
+          id: 'read_file_9876',
+          function: { name: 'read_file', arguments: '{"path":"/tmp/test.ts"}' },
+        } satisfies ToolCall,
+        { type: 'text', text: 'Reading the file.' },
+      ];
+
+      const stream = buildStream(parts);
+      const provider = new SingleStreamProvider(stream, 'google_genai');
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.toolCalls).toHaveLength(1);
+      const tc = result.message.toolCalls[0]!;
+      // Verify the ID follows the {name}_{id} pattern
+      expect(tc.id.startsWith(`${tc.function.name}_`)).toBe(true);
+    });
+
+    it('Google multiple function calls in single response', async () => {
+      const parts: StreamedMessagePart[] = [
+        { type: 'text', text: 'Fetching multiple files.' },
+        {
+          type: 'function',
+          id: 'read_file_001',
+          function: { name: 'read_file', arguments: '{"path":"a.ts"}' },
+        } satisfies ToolCall,
+        {
+          type: 'function',
+          id: 'read_file_002',
+          function: { name: 'read_file', arguments: '{"path":"b.ts"}' },
+        } satisfies ToolCall,
+        {
+          type: 'function',
+          id: 'write_file_003',
+          function: { name: 'write_file', arguments: '{"path":"c.ts","content":"x"}' },
+        } satisfies ToolCall,
+      ];
+
+      const stream = buildStream(parts);
+      const provider = new SingleStreamProvider(stream, 'google_genai');
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.toolCalls).toHaveLength(3);
+      expect(result.message.toolCalls[0]!.id).toBe('read_file_001');
+      expect(result.message.toolCalls[1]!.id).toBe('read_file_002');
+      expect(result.message.toolCalls[2]!.id).toBe('write_file_003');
+    });
+  });
+
+  describe('cross-provider edge cases', () => {
+    it('empty text deltas are merged without creating extra parts', async () => {
+      const parts: StreamedMessagePart[] = [
+        { type: 'text', text: '' },
+        { type: 'text', text: '' },
+        { type: 'text', text: 'actual content' },
+        { type: 'text', text: '' },
+      ];
+
+      const stream = buildStream(parts);
+      const provider = new SingleStreamProvider(stream);
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.content).toHaveLength(1);
+      expect(extractText(result.message)).toBe('actual content');
+    });
+
+    it('think-only response throws APIEmptyResponseError', async () => {
+      const parts: StreamedMessagePart[] = [{ type: 'think', think: 'Just thinking...' }];
+
+      const stream = buildStream(parts);
+      const provider = new SingleStreamProvider(stream);
+
+      await expect(generate(provider, '', [], [])).rejects.toThrow(/only thinking content/);
+    });
+
+    it('usage metadata is correctly passed through from stream', async () => {
+      const usage: TokenUsage = {
+        inputOther: 500,
+        output: 200,
+        inputCacheRead: 100,
+        inputCacheCreation: 50,
+      };
+
+      const parts: StreamedMessagePart[] = [{ type: 'text', text: 'response' }];
+
+      const stream = buildStream(parts, { id: 'test-id', usage });
+      const provider = new SingleStreamProvider(stream);
+      const result = await generate(provider, '', [], []);
+
+      expect(result.usage).toEqual(usage);
+      expect(result.id).toBe('test-id');
+    });
+  });
+});
diff --git a/packages/kosong/test/e2e/toolchain-bridges.test.ts b/packages/kosong/test/e2e/toolchain-bridges.test.ts
new file mode 100644
index 000000000..35ac4dd8e
--- /dev/null
+++ b/packages/kosong/test/e2e/toolchain-bridges.test.ts
@@ -0,0 +1,224 @@
+import { derefJsonSchema } from '#/providers/kimi-schema';
+import { createToolMessage, extractText } from '#/message';
+import type { Message, StreamedMessagePart } from '#/message';
+import type { ChatProvider, StreamedMessage, ThinkingEffort } from '#/provider';
+import { SimpleToolset, toolOk } from '../fixtures/simple-toolset';
+import type { ToolReturnValue } from '../fixtures/simple-toolset';
+import { step } from '../fixtures/step';
+import type { Tool } from '#/tool';
+import { createTypedTool } from '../fixtures/typed-tool';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+
+function createStream(parts: StreamedMessagePart[], opts?: { id?: string }): StreamedMessage {
+  return {
+    get id(): string | null {
+      return opts?.id ?? null;
+    },
+    get usage() {
+      return null;
+    },
+    finishReason: null,
+    rawFinishReason: null,
+    async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+      for (const part of parts) {
+        yield part;
+      }
+    },
+  };
+}
+
+class QueuedProvider implements ChatProvider {
+  readonly name: string = 'queued';
+  readonly modelName: string = 'queued-model';
+  readonly thinkingEffort: ThinkingEffort | null = null;
+  private readonly _queue: StreamedMessage[];
+  private _cursor: number = 0;
+
+  constructor(queue: StreamedMessage[]) {
+    this._queue = queue;
+  }
+
+  async generate(
+    _systemPrompt: string,
+    _tools: Tool[],
+    _history: Message[],
+  ): Promise<StreamedMessage> {
+    const stream = this._queue[this._cursor];
+    if (stream === undefined) {
+      throw new Error(`QueuedProvider exhausted at turn ${this._cursor + 1}.`);
+    }
+    this._cursor += 1;
+    return stream;
+  }
+
+  withThinking(_effort: ThinkingEffort): ChatProvider {
+    return this;
+  }
+}
+
+async function runTwoStepLoop(toolset: SimpleToolset, provider: ChatProvider) {
+  const history: Message[] = [
+    { role: 'user', content: [{ type: 'text', text: 'run the tool chain' }], toolCalls: [] },
+  ];
+
+  const first = await step(provider, '', toolset, history);
+  history.push(first.message);
+
+  const toolResults = await first.toolResults();
+  for (const toolResult of toolResults) {
+    history.push(createToolMessage(toolResult.toolCallId, toolResult.returnValue.output));
+  }
+
+  const second = await step(provider, '', toolset, history);
+  history.push(second.message);
+
+  return { first, second, toolResults, history };
+}
+
+describe('e2e: kosong toolchain bridges', () => {
+  it('typed-tool -> SimpleToolset -> step dispatches nested Zod args and completes the loop', async () => {
+    const addressTool = createTypedTool({
+      name: 'route_address',
+      description: 'Routes a package to a nested address payload',
+      params: z.object({
+        shipment: z.object({
+          id: z.string(),
+          address: z.object({
+            city: z.string(),
+            zip: z.string(),
+          }),
+        }),
+        urgent: z.boolean().optional(),
+      }),
+      handler: async (params): Promise<ToolReturnValue> => {
+        return toolOk({
+          output: `${params.shipment.id} -> ${params.shipment.address.city}:${params.shipment.address.zip}`,
+        });
+      },
+    });
+
+    expect(addressTool.tool.parameters).toMatchObject({
+      type: 'object',
+      additionalProperties: false,
+      properties: expect.objectContaining({
+        shipment: expect.any(Object),
+      }),
+    });
+
+    const provider = new QueuedProvider([
+      createStream([
+        { type: 'text', text: 'I will route the shipment.' },
+        {
+          type: 'function',
+          id: 'tc-route',
+          function: {
+            name: 'route_address',
+            arguments: JSON.stringify({
+              shipment: {
+                id: 'pkg-42',
+                address: { city: 'Shanghai', zip: '200000' },
+              },
+              urgent: true,
+            }),
+          },
+        },
+      ]),
+      createStream([{ type: 'text', text: 'Shipment routed.' }]),
+    ]);
+
+    const toolset = new SimpleToolset();
+    toolset.add(addressTool.tool, addressTool.handler);
+
+    const { first, second, toolResults } = await runTwoStepLoop(toolset, provider);
+
+    expect(extractText(first.message)).toBe('I will route the shipment.');
+    expect(first.toolCalls).toHaveLength(1);
+    expect(toolResults).toHaveLength(1);
+    expect(toolResults[0]!.toolCallId).toBe('tc-route');
+    expect(toolResults[0]!.returnValue.isError).toBe(false);
+    expect(toolResults[0]!.returnValue.output).toBe('pkg-42 -> Shanghai:200000');
+    expect(extractText(second.message)).toBe('Shipment routed.');
+  });
+
+  it('json-schema-deref -> SimpleToolset -> step validates a flattened schema and completes the loop', async () => {
+    const rawSchema: Record<string, unknown> = {
+      type: 'object',
+      $defs: {
+        address: {
+          type: 'object',
+          properties: {
+            city: { type: 'string' },
+            zip: { type: 'string' },
+          },
+          required: ['city', 'zip'],
+          additionalProperties: false,
+        },
+      },
+      properties: {
+        shipping: { $ref: '#/$defs/address' },
+        billing: { $ref: '#/$defs/address' },
+      },
+      required: ['shipping', 'billing'],
+      additionalProperties: false,
+    };
+
+    const schema = derefJsonSchema(rawSchema);
+    expect(schema).not.toHaveProperty('$defs');
+    expect(schema).toMatchObject({
+      type: 'object',
+      properties: expect.objectContaining({
+        shipping: expect.objectContaining({
+          type: 'object',
+          properties: expect.objectContaining({
+            city: { type: 'string' },
+            zip: { type: 'string' },
+          }),
+        }),
+      }),
+    });
+
+    const toolset = new SimpleToolset();
+    let receivedArgs: Record<string, unknown> | null = null;
+    toolset.add(
+      {
+        name: 'ship_package',
+        description: 'Ships a package with two addresses',
+        parameters: schema,
+      },
+      async (args): Promise<ToolReturnValue> => {
+        receivedArgs = args as Record<string, unknown>;
+        return toolOk({
+          output: `ship:${(args as Record<string, unknown>)['shipping'] !== undefined ? 'ok' : 'missing'}`,
+        });
+      },
+    );
+
+    const provider = new QueuedProvider([
+      createStream([
+        {
+          type: 'function',
+          id: 'tc-ship',
+          function: {
+            name: 'ship_package',
+            arguments: JSON.stringify({
+              shipping: { city: 'Hangzhou', zip: '310000' },
+              billing: { city: 'Shenzhen', zip: '518000' },
+            }),
+          },
+        },
+      ]),
+      createStream([{ type: 'text', text: 'Shipment booked.' }]),
+    ]);
+
+    const { first, second, toolResults } = await runTwoStepLoop(toolset, provider);
+
+    expect(first.toolCalls).toHaveLength(1);
+    expect(receivedArgs).toEqual({
+      shipping: { city: 'Hangzhou', zip: '310000' },
+      billing: { city: 'Shenzhen', zip: '518000' },
+    });
+    expect(toolResults[0]!.returnValue.output).toBe('ship:ok');
+    expect(extractText(second.message)).toBe('Shipment booked.');
+  });
+});
diff --git a/packages/kosong/test/e2e/toolset-advanced.test.ts b/packages/kosong/test/e2e/toolset-advanced.test.ts
new file mode 100644
index 000000000..1b382d052
--- /dev/null
+++ b/packages/kosong/test/e2e/toolset-advanced.test.ts
@@ -0,0 +1,419 @@
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import type { ChatProvider, StreamedMessage, ThinkingEffort } from '#/provider';
+import {
+  SimpleToolset,
+  toolOk,
+  type ToolResult,
+  type ToolReturnValue,
+} from '../fixtures/simple-toolset';
+import { step, type StepCallbacks } from '../fixtures/step';
+import type { Tool } from '#/tool';
+import type { JsonValue } from '../fixtures/args-validator';
+import type { TokenUsage } from '#/usage';
+import { describe, expect, it } from 'vitest';
+function buildStream(
+  parts: StreamedMessagePart[],
+  opts?: { id?: string; usage?: TokenUsage },
+): StreamedMessage {
+  return {
+    get id(): string | null {
+      return opts?.id ?? null;
+    },
+    get usage(): TokenUsage | null {
+      return opts?.usage ?? null;
+    },
+    finishReason: null,
+    rawFinishReason: null,
+    async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+      for (const part of parts) {
+        yield part;
+      }
+    },
+  };
+}
+
+class QueuedProvider implements ChatProvider {
+  readonly name: string = 'queued';
+  readonly modelName: string = 'queued';
+  readonly thinkingEffort: ThinkingEffort | null = null;
+  private readonly _queue: StreamedMessage[];
+  private _cursor: number = 0;
+
+  constructor(queue: StreamedMessage[]) {
+    this._queue = queue;
+  }
+
+  async generate(
+    _systemPrompt: string,
+    _tools: Tool[],
+    _history: Message[],
+  ): Promise<StreamedMessage> {
+    const stream = this._queue[this._cursor];
+    if (stream === undefined) {
+      throw new Error(`QueuedProvider exhausted at turn ${this._cursor + 1}.`);
+    }
+    this._cursor++;
+    return stream;
+  }
+
+  withThinking(_effort: ThinkingEffort): ChatProvider {
+    return this;
+  }
+}
+describe('e2e: toolset advanced', () => {
+  describe('tool argument boundaries', () => {
+    it('arguments=null -> handler receives {}', async () => {
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc-null',
+        function: { name: 'my_tool', arguments: null },
+      };
+
+      const provider = new QueuedProvider([
+        buildStream([tc]),
+        buildStream([{ type: 'text', text: 'done' }]),
+      ]);
+
+      let receivedArgs: JsonValue = undefined as unknown as JsonValue;
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'my_tool', description: 'Test tool', parameters: {} },
+        async (args: JsonValue): Promise<ToolReturnValue> => {
+          receivedArgs = args;
+          return toolOk({ output: 'ok' });
+        },
+      );
+
+      const result = await step(provider, '', toolset, [
+        { role: 'user', content: [{ type: 'text', text: 'go' }], toolCalls: [] },
+      ]);
+      const results = await result.toolResults();
+
+      // null arguments should be parsed as {} via JSON.parse('{}')
+      expect(receivedArgs).toEqual({});
+      expect(results[0]!.returnValue.isError).toBe(false);
+    });
+
+    it('arguments="" -> toolParseError', async () => {
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc-empty',
+        function: { name: 'my_tool', arguments: '' },
+      };
+
+      const provider = new QueuedProvider([
+        buildStream([tc]),
+        buildStream([{ type: 'text', text: 'done' }]),
+      ]);
+
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'my_tool', description: 'Test tool', parameters: {} },
+        async (): Promise<ToolReturnValue> => toolOk({ output: 'ok' }),
+      );
+
+      const result = await step(provider, '', toolset, [
+        { role: 'user', content: [{ type: 'text', text: 'go' }], toolCalls: [] },
+      ]);
+      const results = await result.toolResults();
+
+      // Empty string "" is not valid JSON, should produce a parse error
+      expect(results[0]!.returnValue.isError).toBe(true);
+    });
+
+    it('arguments="null" -> handler receives null', async () => {
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc-string-null',
+        function: { name: 'my_tool', arguments: 'null' },
+      };
+
+      const provider = new QueuedProvider([
+        buildStream([tc]),
+        buildStream([{ type: 'text', text: 'done' }]),
+      ]);
+
+      let receivedArgs: JsonValue = undefined as unknown as JsonValue;
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'my_tool', description: 'Test tool', parameters: {} },
+        async (args: JsonValue): Promise<ToolReturnValue> => {
+          receivedArgs = args;
+          return toolOk({ output: 'ok' });
+        },
+      );
+
+      const result = await step(provider, '', toolset, [
+        { role: 'user', content: [{ type: 'text', text: 'go' }], toolCalls: [] },
+      ]);
+      await result.toolResults();
+
+      // JSON.parse("null") === null
+      expect(receivedArgs).toBeNull();
+    });
+
+    it('arguments="[]" -> handler receives empty array', async () => {
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc-array',
+        function: { name: 'my_tool', arguments: '[]' },
+      };
+
+      const provider = new QueuedProvider([
+        buildStream([tc]),
+        buildStream([{ type: 'text', text: 'done' }]),
+      ]);
+
+      let receivedArgs: JsonValue = undefined as unknown as JsonValue;
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'my_tool', description: 'Test tool', parameters: {} },
+        async (args: JsonValue): Promise<ToolReturnValue> => {
+          receivedArgs = args;
+          return toolOk({ output: 'ok' });
+        },
+      );
+
+      const result = await step(provider, '', toolset, [
+        { role: 'user', content: [{ type: 'text', text: 'go' }], toolCalls: [] },
+      ]);
+      await result.toolResults();
+
+      // JSON.parse("[]") === []
+      expect(receivedArgs).toEqual([]);
+    });
+
+    it('arguments with unicode JSON -> correctly parsed', async () => {
+      const args = JSON.stringify({ message: 'Hello \u4E16\u754C!', emoji: '\uD83D\uDE80' });
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc-unicode',
+        function: { name: 'my_tool', arguments: args },
+      };
+
+      const provider = new QueuedProvider([
+        buildStream([tc]),
+        buildStream([{ type: 'text', text: 'done' }]),
+      ]);
+
+      let receivedArgs: JsonValue = undefined as unknown as JsonValue;
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'my_tool', description: 'Test tool', parameters: {} },
+        async (receivedArgsParam: JsonValue): Promise<ToolReturnValue> => {
+          receivedArgs = receivedArgsParam;
+          return toolOk({ output: 'ok' });
+        },
+      );
+
+      const result = await step(provider, '', toolset, [
+        { role: 'user', content: [{ type: 'text', text: 'go' }], toolCalls: [] },
+      ]);
+      await result.toolResults();
+
+      const parsed = receivedArgs as Record<string, JsonValue>;
+      expect(parsed['message']).toBe('Hello \u4E16\u754C!');
+      expect(parsed['emoji']).toBe('\uD83D\uDE80');
+    });
+  });
+  describe('concurrent tool execution order guarantees', () => {
+    it('toolResults() returns in ToolCall order, not completion order', async () => {
+      const tc1: ToolCall = {
+        type: 'function',
+        id: 'tc-slow',
+        function: { name: 'delayed', arguments: '{"delay":100,"label":"slow"}' },
+      };
+      const tc2: ToolCall = {
+        type: 'function',
+        id: 'tc-fast',
+        function: { name: 'delayed', arguments: '{"delay":10,"label":"fast"}' },
+      };
+      const tc3: ToolCall = {
+        type: 'function',
+        id: 'tc-mid',
+        function: { name: 'delayed', arguments: '{"delay":50,"label":"mid"}' },
+      };
+
+      const provider = new QueuedProvider([
+        buildStream([tc1, tc2, tc3]),
+        buildStream([{ type: 'text', text: 'done' }]),
+      ]);
+
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'delayed', description: 'Delayed tool', parameters: {} },
+        async (args: JsonValue): Promise<ToolReturnValue> => {
+          const obj = args as Record<string, JsonValue>;
+          const delay = obj['delay'] as number;
+          const label = obj['label'] as string;
+          await new Promise<void>((r) => setTimeout(r, delay));
+          return toolOk({ output: label });
+        },
+      );
+
+      const result = await step(provider, '', toolset, [
+        { role: 'user', content: [{ type: 'text', text: 'go' }], toolCalls: [] },
+      ]);
+      const results = await result.toolResults();
+
+      // Results must be in ToolCall order: slow, fast, mid
+      expect(results).toHaveLength(3);
+      expect(results[0]!.toolCallId).toBe('tc-slow');
+      expect(results[0]!.returnValue.output).toBe('slow');
+      expect(results[1]!.toolCallId).toBe('tc-fast');
+      expect(results[1]!.returnValue.output).toBe('fast');
+      expect(results[2]!.toolCallId).toBe('tc-mid');
+      expect(results[2]!.returnValue.output).toBe('mid');
+    });
+
+    it('onToolResult fires in completion order, not ToolCall order', async () => {
+      const tc1: ToolCall = {
+        type: 'function',
+        id: 'tc-slow',
+        function: { name: 'delayed', arguments: '{"delay":80,"label":"slow"}' },
+      };
+      const tc2: ToolCall = {
+        type: 'function',
+        id: 'tc-fast',
+        function: { name: 'delayed', arguments: '{"delay":10,"label":"fast"}' },
+      };
+      const tc3: ToolCall = {
+        type: 'function',
+        id: 'tc-mid',
+        function: { name: 'delayed', arguments: '{"delay":40,"label":"mid"}' },
+      };
+
+      const provider = new QueuedProvider([
+        buildStream([tc1, tc2, tc3]),
+        buildStream([{ type: 'text', text: 'done' }]),
+      ]);
+
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'delayed', description: 'Delayed tool', parameters: {} },
+        async (args: JsonValue): Promise<ToolReturnValue> => {
+          const obj = args as Record<string, JsonValue>;
+          const delay = obj['delay'] as number;
+          const label = obj['label'] as string;
+          await new Promise<void>((r) => setTimeout(r, delay));
+          return toolOk({ output: label });
+        },
+      );
+
+      const completionOrder: string[] = [];
+      const callbacks: StepCallbacks = {
+        onToolResult(result: ToolResult): void {
+          completionOrder.push(result.toolCallId);
+        },
+      };
+
+      const result = await step(
+        provider,
+        '',
+        toolset,
+        [{ role: 'user', content: [{ type: 'text', text: 'go' }], toolCalls: [] }],
+        callbacks,
+      );
+      await result.toolResults();
+
+      // onToolResult should fire in completion order: fast(10ms), mid(40ms), slow(80ms)
+      expect(completionOrder[0]).toBe('tc-fast');
+      expect(completionOrder[1]).toBe('tc-mid');
+      expect(completionOrder[2]).toBe('tc-slow');
+    });
+  });
+  describe('step() error cleanup', () => {
+    it('generate() failure does not dispatch any tool handlers', async () => {
+      // Tool dispatch is deferred until after the stream has fully drained,
+      // so a mid-stream provider failure never starts pending tool promises.
+      const errorStream: StreamedMessage = {
+        get id(): string | null {
+          return null;
+        },
+        get usage(): TokenUsage | null {
+          return null;
+        },
+        finishReason: null,
+        rawFinishReason: null,
+        async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+          yield {
+            type: 'function',
+            id: 'tc-doomed',
+            function: { name: 'slow_tool', arguments: '{}' },
+          } satisfies ToolCall;
+          yield { type: 'text', text: 'processing...' };
+          throw new Error('stream connection lost');
+        },
+      };
+
+      const errorProvider: ChatProvider = {
+        name: 'error-provider',
+        modelName: 'error-model',
+        thinkingEffort: null,
+        async generate(): Promise<StreamedMessage> {
+          return errorStream;
+        },
+        withThinking(): ChatProvider {
+          return this;
+        },
+      };
+
+      let handlerStarted = false;
+      let handlerFinished = false;
+
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'slow_tool', description: 'Slow tool', parameters: {} },
+        async (): Promise<ToolReturnValue> => {
+          handlerStarted = true;
+          await new Promise<void>((r) => setTimeout(r, 50));
+          handlerFinished = true;
+          return toolOk({ output: 'done' });
+        },
+      );
+
+      await expect(
+        step(errorProvider, '', toolset, [
+          { role: 'user', content: [{ type: 'text', text: 'go' }], toolCalls: [] },
+        ]),
+      ).rejects.toThrow('stream connection lost');
+
+      // Give any in-flight microtasks a chance to run; the handler must
+      // never have been invoked.
+      await new Promise<void>((r) => setTimeout(r, 80));
+      expect(handlerStarted).toBe(false);
+      expect(handlerFinished).toBe(false);
+    });
+
+    it('tool handler exception does not crash step()', async () => {
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc-error',
+        function: { name: 'bad_tool', arguments: '{}' },
+      };
+
+      const provider = new QueuedProvider([
+        buildStream([tc]),
+        buildStream([{ type: 'text', text: 'done' }]),
+      ]);
+
+      const toolset = new SimpleToolset();
+      toolset.add(
+        { name: 'bad_tool', description: 'Bad tool', parameters: {} },
+        async (): Promise<ToolReturnValue> => {
+          throw new Error('handler exploded');
+        },
+      );
+
+      const result = await step(provider, '', toolset, [
+        { role: 'user', content: [{ type: 'text', text: 'go' }], toolCalls: [] },
+      ]);
+      const results = await result.toolResults();
+
+      // The error should be wrapped as a toolRuntimeError
+      expect(results).toHaveLength(1);
+      expect(results[0]!.returnValue.isError).toBe(true);
+      expect(results[0]!.returnValue.message).toContain('handler exploded');
+    });
+  });
+});
diff --git a/packages/kosong/test/echo-provider.test.ts b/packages/kosong/test/echo-provider.test.ts
new file mode 100644
index 000000000..9a030f3e9
--- /dev/null
+++ b/packages/kosong/test/echo-provider.test.ts
@@ -0,0 +1,353 @@
+import { EchoChatProvider } from './fixtures/echo-provider';
+import { ChatProviderError } from '#/errors';
+import {
+  createUserMessage,
+  type AudioURLPart,
+  type ImageURLPart,
+  type Message,
+  type StreamedMessagePart,
+  type TextPart,
+  type ThinkPart,
+  type ToolCall,
+  type ToolCallPart,
+  type VideoURLPart,
+} from '#/message';
+import { describe, it, expect } from 'vitest';
+
+function userMsg(text: string): Message {
+  return createUserMessage(text);
+}
+
+describe('EchoChatProvider', () => {
+  it('streams parts from DSL', async () => {
+    const dsl = [
+      'id: echo-42',
+      'usage: {"input_other": 10, "output": 2, "input_cache_read": 3}',
+      'text: Hello,',
+      'text:  world!',
+      'think: thinking...',
+      'image_url: {"url": "https://example.com/image.png", "id": "img-1"}',
+      'audio_url: https://example.com/audio.mp3',
+      'video_url: https://example.com/video.mp4',
+      'tool_call: {"id": "call-1", "name": "search", "arguments": "{\\"q\\":\\"python\\"", "extras": {"source": "test"}}',
+      'tool_call_part: {"arguments_part": "}"}',
+    ].join('\n');
+
+    const provider = new EchoChatProvider();
+    const history: Message[] = [userMsg(dsl)];
+
+    const parts: StreamedMessagePart[] = [];
+    const stream = await provider.generate('', [], history);
+    for await (const part of stream) {
+      parts.push(part);
+    }
+
+    expect(stream.id).toBe('echo-42');
+    expect(stream.usage).toEqual({
+      inputOther: 10,
+      output: 2,
+      inputCacheRead: 3,
+      inputCacheCreation: 0,
+    });
+
+    expect(parts).toEqual([
+      { type: 'text', text: 'Hello,' } satisfies TextPart,
+      { type: 'text', text: ' world!' } satisfies TextPart,
+      { type: 'think', think: 'thinking...' } satisfies ThinkPart,
+      {
+        type: 'image_url',
+        imageUrl: { url: 'https://example.com/image.png', id: 'img-1' },
+      } satisfies ImageURLPart,
+      {
+        type: 'audio_url',
+        audioUrl: { url: 'https://example.com/audio.mp3' },
+      } satisfies AudioURLPart,
+      {
+        type: 'video_url',
+        videoUrl: { url: 'https://example.com/video.mp4' },
+      } satisfies VideoURLPart,
+      {
+        type: 'function',
+        id: 'call-1',
+        function: { name: 'search', arguments: '{"q":"python"' },
+      } satisfies ToolCall,
+      { type: 'tool_call_part', argumentsPart: '}' } satisfies ToolCallPart,
+    ]);
+  });
+
+  it('rejects non-string arguments in tool_call', async () => {
+    const dsl = 'tool_call: {"id": "call-1", "name": "search", "arguments": {"q": "python"}}';
+    const provider = new EchoChatProvider();
+
+    await expect(provider.generate('', [], [userMsg(dsl)])).rejects.toThrow(ChatProviderError);
+  });
+
+  it('requires last history message to be user', async () => {
+    const provider = new EchoChatProvider();
+    const history: Message[] = [
+      {
+        role: 'tool',
+        content: [{ type: 'text', text: 'tool output' }],
+        toolCallId: 'tc-1',
+        toolCalls: [],
+      },
+    ];
+
+    await expect(provider.generate('', [], history)).rejects.toThrow(ChatProviderError);
+  });
+
+  it('requires DSL content (not empty)', async () => {
+    const provider = new EchoChatProvider();
+    const history: Message[] = [userMsg('')];
+
+    await expect(provider.generate('', [], history)).rejects.toThrow(ChatProviderError);
+  });
+
+  it('requires at least one message in history', async () => {
+    const provider = new EchoChatProvider();
+
+    await expect(provider.generate('', [], [])).rejects.toThrow(ChatProviderError);
+  });
+
+  it('handles comments and blank lines', async () => {
+    const dsl = ['# this is a comment', '', 'text: Hello', '# another comment'].join('\n');
+
+    const provider = new EchoChatProvider();
+    const parts: StreamedMessagePart[] = [];
+    const stream = await provider.generate('', [], [userMsg(dsl)]);
+    for await (const part of stream) {
+      parts.push(part);
+    }
+
+    expect(parts).toEqual([{ type: 'text', text: 'Hello' }]);
+  });
+
+  it('handles think_encrypted DSL', async () => {
+    const dsl = 'think_encrypted: some_signature';
+    const provider = new EchoChatProvider();
+    const parts: StreamedMessagePart[] = [];
+    const stream = await provider.generate('', [], [userMsg(dsl)]);
+    for await (const part of stream) {
+      parts.push(part);
+    }
+
+    expect(parts).toEqual([
+      { type: 'think', think: '', encrypted: 'some_signature' } satisfies ThinkPart,
+    ]);
+  });
+
+  it('withThinking returns a new EchoChatProvider', () => {
+    const provider = new EchoChatProvider();
+    const newProvider = provider.withThinking('high');
+    expect(newProvider).toBeInstanceOf(EchoChatProvider);
+    expect(newProvider).not.toBe(provider);
+  });
+
+  it('throws on a DSL line without a colon separator', async () => {
+    const provider = new EchoChatProvider();
+    await expect(provider.generate('', [], [userMsg('this line has no colon')])).rejects.toThrow(
+      /Invalid echo DSL/,
+    );
+  });
+
+  it('throws on an unknown DSL kind', async () => {
+    const provider = new EchoChatProvider();
+    await expect(
+      provider.generate('', [], [userMsg('mystery_kind: some payload')]),
+    ).rejects.toThrow(/Unknown echo DSL kind/);
+  });
+
+  it('skips markdown fence lines and bare echo keyword', async () => {
+    const dsl = ['```', 'echo', 'text: actual content', '```'].join('\n');
+    const provider = new EchoChatProvider();
+    const stream = await provider.generate('', [], [userMsg(dsl)]);
+    const parts: StreamedMessagePart[] = [];
+    for await (const part of stream) parts.push(part);
+    expect(parts).toEqual([{ type: 'text', text: 'actual content' }]);
+  });
+
+  it('parseUsage throws for non-integer field', async () => {
+    const provider = new EchoChatProvider();
+    const dsl = 'usage: {"output": "not_a_number"}';
+    await expect(provider.generate('', [], [userMsg(dsl)])).rejects.toThrow(
+      /Usage field 'output' must be an integer/,
+    );
+  });
+
+  it('parseToolCall throws when id is missing', async () => {
+    const provider = new EchoChatProvider();
+    const dsl = 'tool_call: {"name": "search", "arguments": "{}"}';
+    await expect(provider.generate('', [], [userMsg(dsl)])).rejects.toThrow(
+      /tool_call requires string id and name/,
+    );
+  });
+
+  it('parseToolCall throws when name is missing', async () => {
+    const provider = new EchoChatProvider();
+    const dsl = 'tool_call: {"id": "call-1", "arguments": "{}"}';
+    await expect(provider.generate('', [], [userMsg(dsl)])).rejects.toThrow(
+      /tool_call requires string id and name/,
+    );
+  });
+
+  it('image_url DSL accepts a bare URL string (no id)', async () => {
+    const provider = new EchoChatProvider();
+    const dsl = 'image_url: https://example.com/img.png';
+    const stream = await provider.generate('', [], [userMsg(dsl)]);
+    const parts: StreamedMessagePart[] = [];
+    for await (const part of stream) parts.push(part);
+    expect(parts).toEqual([
+      {
+        type: 'image_url',
+        imageUrl: { url: 'https://example.com/img.png' },
+      } satisfies ImageURLPart,
+    ]);
+  });
+
+  it('parseMapping falls back to key=value form when payload is not JSON', async () => {
+    const provider = new EchoChatProvider();
+    // usage payload as space-separated key=value form (requires at least one part too)
+    const dsl = ['usage: input_other=10 output=2', 'text: hi'].join('\n');
+    const stream = await provider.generate('', [], [userMsg(dsl)]);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.usage).toEqual({
+      inputOther: 10,
+      output: 2,
+      inputCacheRead: 0,
+      inputCacheCreation: 0,
+    });
+  });
+
+  describe('finish_reason DSL', () => {
+    it('defaults to completed/stop when finish_reason line is omitted', async () => {
+      const provider = new EchoChatProvider();
+      const stream = await provider.generate('', [], [userMsg('text: hi')]);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.finishReason).toBe('completed');
+      expect(stream.rawFinishReason).toBe('stop');
+    });
+
+    it('maps finish_reason: stop to completed/stop', async () => {
+      const provider = new EchoChatProvider();
+      const dsl = ['text: hi', 'finish_reason: stop'].join('\n');
+      const stream = await provider.generate('', [], [userMsg(dsl)]);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.finishReason).toBe('completed');
+      expect(stream.rawFinishReason).toBe('stop');
+    });
+
+    it('maps finish_reason: length to truncated/length', async () => {
+      const provider = new EchoChatProvider();
+      const dsl = ['text: hi', 'finish_reason: length'].join('\n');
+      const stream = await provider.generate('', [], [userMsg(dsl)]);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.finishReason).toBe('truncated');
+      expect(stream.rawFinishReason).toBe('length');
+    });
+
+    it('maps finish_reason: tool_calls to tool_calls/tool_calls', async () => {
+      const provider = new EchoChatProvider();
+      const dsl = ['text: hi', 'finish_reason: tool_calls'].join('\n');
+      const stream = await provider.generate('', [], [userMsg(dsl)]);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.finishReason).toBe('tool_calls');
+      expect(stream.rawFinishReason).toBe('tool_calls');
+    });
+
+    it('maps finish_reason: content_filter to filtered/content_filter', async () => {
+      const provider = new EchoChatProvider();
+      const dsl = ['text: hi', 'finish_reason: content_filter'].join('\n');
+      const stream = await provider.generate('', [], [userMsg(dsl)]);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.finishReason).toBe('filtered');
+      expect(stream.rawFinishReason).toBe('content_filter');
+    });
+
+    it('maps unknown finish_reason string to other and preserves raw', async () => {
+      const provider = new EchoChatProvider();
+      const dsl = ['text: hi', 'finish_reason: something_weird'].join('\n');
+      const stream = await provider.generate('', [], [userMsg(dsl)]);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.finishReason).toBe('other');
+      expect(stream.rawFinishReason).toBe('something_weird');
+    });
+
+    it('maps finish_reason: null to {null, null}', async () => {
+      const provider = new EchoChatProvider();
+      const dsl = ['text: hi', 'finish_reason: null'].join('\n');
+      const stream = await provider.generate('', [], [userMsg(dsl)]);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.finishReason).toBeNull();
+      expect(stream.rawFinishReason).toBeNull();
+    });
+
+    it('maps finish_reason: none to {null, null}', async () => {
+      const provider = new EchoChatProvider();
+      const dsl = ['text: hi', 'finish_reason: none'].join('\n');
+      const stream = await provider.generate('', [], [userMsg(dsl)]);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.finishReason).toBeNull();
+      expect(stream.rawFinishReason).toBeNull();
+    });
+
+    it('maps empty finish_reason payload to {null, null}', async () => {
+      const provider = new EchoChatProvider();
+      const dsl = ['text: hi', 'finish_reason: '].join('\n');
+      const stream = await provider.generate('', [], [userMsg(dsl)]);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.finishReason).toBeNull();
+      expect(stream.rawFinishReason).toBeNull();
+    });
+
+    it('strips quotes around finish_reason payloads', async () => {
+      const provider = new EchoChatProvider();
+      const dsl = ['text: hi', 'finish_reason: "length"'].join('\n');
+      const stream = await provider.generate('', [], [userMsg(dsl)]);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.finishReason).toBe('truncated');
+      expect(stream.rawFinishReason).toBe('length');
+    });
+  });
+
+  it('generate merges tool_call arguments via mergeInPlace', async () => {
+    const dsl = [
+      'id: echo-merge-1',
+      'tool_call: {"id": "call-1", "name": "search", "arguments": "{\\"q\\":\\"py"}',
+      'tool_call_part: {"arguments_part": "thon\\"}"}',
+    ].join('\n');
+
+    const provider = new EchoChatProvider();
+    const { generate } = await import('#/generate');
+
+    const result = await generate(provider, '', [], [userMsg(dsl)]);
+
+    expect(result.message.toolCalls).toHaveLength(1);
+
+    const tc = result.message.toolCalls[0]!;
+    expect(tc.id).toBe('call-1');
+    expect(tc.function.name).toBe('search');
+    expect(tc.function.arguments).toBe('{"q":"python"}');
+  });
+});
diff --git a/packages/kosong/test/errors.test.ts b/packages/kosong/test/errors.test.ts
new file mode 100644
index 000000000..3c1cc68e0
--- /dev/null
+++ b/packages/kosong/test/errors.test.ts
@@ -0,0 +1,152 @@
+import {
+  APIConnectionError,
+  APIContextOverflowError,
+  APIEmptyResponseError,
+  APIStatusError,
+  APITimeoutError,
+  ChatProviderError,
+  normalizeAPIStatusError,
+} from '#/errors';
+import { describe, expect, it } from 'vitest';
+
+describe('ChatProviderError', () => {
+  it('is an instance of Error', () => {
+    const err = new ChatProviderError('base error');
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(ChatProviderError);
+    expect(err.message).toBe('base error');
+    expect(err.name).toBe('ChatProviderError');
+  });
+});
+
+describe('APIConnectionError', () => {
+  it('extends ChatProviderError', () => {
+    const err = new APIConnectionError('connection refused');
+    expect(err).toBeInstanceOf(ChatProviderError);
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe('APIConnectionError');
+    expect(err.message).toBe('connection refused');
+  });
+});
+
+describe('APITimeoutError', () => {
+  it('extends ChatProviderError', () => {
+    const err = new APITimeoutError('request timed out after 30s');
+    expect(err).toBeInstanceOf(ChatProviderError);
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe('APITimeoutError');
+    expect(err.message).toBe('request timed out after 30s');
+  });
+});
+
+describe('APIStatusError', () => {
+  it('extends ChatProviderError and stores status code', () => {
+    const err = new APIStatusError(429, 'rate limited', 'req-abc');
+    expect(err).toBeInstanceOf(ChatProviderError);
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe('APIStatusError');
+    expect(err.message).toBe('rate limited');
+    expect(err.statusCode).toBe(429);
+    expect(err.requestId).toBe('req-abc');
+  });
+
+  it('accepts null requestId', () => {
+    const err = new APIStatusError(500, 'server error', null);
+    expect(err.statusCode).toBe(500);
+    expect(err.requestId).toBeNull();
+  });
+
+  it('defaults requestId to null when omitted', () => {
+    const err = new APIStatusError(502, 'bad gateway');
+    expect(err.statusCode).toBe(502);
+    expect(err.requestId).toBeNull();
+  });
+});
+
+describe('APIEmptyResponseError', () => {
+  it('extends ChatProviderError', () => {
+    const err = new APIEmptyResponseError('empty response');
+    expect(err).toBeInstanceOf(ChatProviderError);
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe('APIEmptyResponseError');
+    expect(err.message).toBe('empty response');
+  });
+});
+
+describe('APIContextOverflowError', () => {
+  it('extends APIStatusError and preserves HTTP details', () => {
+    const err = new APIContextOverflowError(400, 'Context length exceeded', 'req-context');
+    expect(err).toBeInstanceOf(APIStatusError);
+    expect(err).toBeInstanceOf(ChatProviderError);
+    expect(err.name).toBe('APIContextOverflowError');
+    expect(err.statusCode).toBe(400);
+    expect(err.requestId).toBe('req-context');
+  });
+});
+
+describe('error hierarchy instanceof checks', () => {
+  it('all error types are instanceof ChatProviderError', () => {
+    const errors = [
+      new APIConnectionError('conn'),
+      new APITimeoutError('timeout'),
+      new APIStatusError(400, 'status', null),
+      new APIContextOverflowError(400, 'context length exceeded'),
+      new APIEmptyResponseError('empty'),
+    ];
+
+    for (const err of errors) {
+      expect(err).toBeInstanceOf(ChatProviderError);
+    }
+  });
+
+  it('specific types are distinguishable', () => {
+    const connErr = new APIConnectionError('conn');
+    const statusErr = new APIStatusError(400, 'status', null);
+
+    expect(connErr).not.toBeInstanceOf(APIStatusError);
+    expect(statusErr).not.toBeInstanceOf(APIConnectionError);
+  });
+
+  it('can catch with ChatProviderError and inspect subtype', () => {
+    const err: ChatProviderError = new APIStatusError(404, 'not found', 'req-123');
+
+    if (err instanceof APIStatusError) {
+      expect(err.statusCode).toBe(404);
+      expect(err.requestId).toBe('req-123');
+    } else {
+      expect.unreachable('Expected APIStatusError');
+    }
+  });
+});
+
+describe('normalizeAPIStatusError', () => {
+  it.each([
+    [400, 'Context length exceeded'],
+    [400, 'Exceeded max tokens'],
+    [413, 'Context length exceeded'],
+    [422, 'Maximum context window exceeded'],
+    [400, 'context_length_exceeded'],
+    [422, 'Too many tokens in prompt'],
+    [400, 'prompt is too long: 210000 tokens exceeds the maximum'],
+    [400, 'input token count 131072 exceeds the maximum number of tokens allowed'],
+  ])('normalizes %i "%s" to APIContextOverflowError', (statusCode, message) => {
+    const error = normalizeAPIStatusError(statusCode, message, 'req-context');
+    expect(error).toBeInstanceOf(APIContextOverflowError);
+    expect(error.statusCode).toBe(statusCode);
+    expect(error.requestId).toBe('req-context');
+  });
+
+  it.each([
+    [401, 'Context length exceeded'],
+    [500, 'Context length exceeded'],
+    [400, 'Bad request'],
+    [422, 'Invalid tool schema'],
+    [400, 'max_tokens must be less than or equal to 4096'],
+    [422, 'max_output_tokens must not exceed 8192'],
+    [400, 'max tokens must not exceed the configured output limit'],
+  ])('keeps %i "%s" as APIStatusError', (statusCode, message) => {
+    const error = normalizeAPIStatusError(statusCode, message);
+    expect(error).toBeInstanceOf(APIStatusError);
+    expect(error).not.toBeInstanceOf(APIContextOverflowError);
+  });
+});
diff --git a/packages/kosong/test/finish-reason.test.ts b/packages/kosong/test/finish-reason.test.ts
new file mode 100644
index 000000000..a9ed250ae
--- /dev/null
+++ b/packages/kosong/test/finish-reason.test.ts
@@ -0,0 +1,946 @@
+import { generate } from '#/generate';
+import type { Message, StreamedMessagePart } from '#/message';
+import { MockChatProvider } from './fixtures/mock-provider';
+import type { FinishReason } from '#/provider';
+import { AnthropicChatProvider } from '#/providers/anthropic';
+import { GoogleGenAIChatProvider, GoogleGenAIStreamedMessage } from '#/providers/google-genai';
+import { KimiChatProvider } from '#/providers/kimi';
+import { OpenAILegacyChatProvider } from '#/providers/openai-legacy';
+import { OpenAIResponsesStreamedMessage } from '#/providers/openai-responses';
+import { normalizeOpenAIFinishReason } from '#/providers/openai-common';
+import { step } from './fixtures/step';
+import { toolOk } from './fixtures/simple-toolset';
+import type { Toolset } from './fixtures/simple-toolset';
+import { describe, it, expect, vi } from 'vitest';
+const USER_MSG: Message = {
+  role: 'user',
+  content: [{ type: 'text', text: 'hi' }],
+  toolCalls: [],
+};
+
+function makeAsyncIterable<T>(events: T[]): AsyncIterable<T> {
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (const event of events) {
+        yield event;
+      }
+    },
+  };
+}
+
+const EMPTY_TOOLSET: Toolset = {
+  tools: [],
+  handle: (toolCall) => ({
+    toolCallId: toolCall.id,
+    returnValue: toolOk({ output: '' }),
+  }),
+};
+
+// =====================================================================
+// A. Normalization table coverage (direct helper tests where possible).
+// =====================================================================
+
+describe('normalizeOpenAIFinishReason (Kimi + OpenAILegacy shared helper)', () => {
+  // Covers A for Kimi + OpenAILegacy.
+  it.each<[string | null | undefined, FinishReason | null, string | null]>([
+    ['stop', 'completed', 'stop'],
+    ['tool_calls', 'tool_calls', 'tool_calls'],
+    ['function_call', 'tool_calls', 'function_call'],
+    ['length', 'truncated', 'length'],
+    ['content_filter', 'filtered', 'content_filter'],
+    ['unknown_value', 'other', 'unknown_value'],
+    ['', 'other', ''],
+    [null, null, null],
+    [undefined, null, null],
+  ])(
+    'raw %j normalizes to finishReason=%j rawFinishReason=%j',
+    (raw, expectedFinish, expectedRaw) => {
+      const result = normalizeOpenAIFinishReason(raw);
+      expect(result).toEqual({ finishReason: expectedFinish, rawFinishReason: expectedRaw });
+    },
+  );
+});
+function makeKimiStream(rawFinish: string | null | undefined): AsyncIterable<unknown> {
+  // Kimi / Chat Completions stream: emit one content chunk + a terminal
+  // chunk carrying finish_reason.
+  const chunks: Array<Record<string, unknown>> = [
+    {
+      id: 'chatcmpl-finish-1',
+      choices: [{ index: 0, delta: { content: 'hi' }, finish_reason: null }],
+    },
+    {
+      id: 'chatcmpl-finish-1',
+      choices: [{ index: 0, delta: {}, finish_reason: rawFinish ?? null }],
+    },
+  ];
+  return makeAsyncIterable(chunks);
+}
+
+function makeOpenAIChatClient(response: unknown) {
+  return {
+    chat: {
+      completions: {
+        create: vi.fn().mockResolvedValue(response),
+      },
+    },
+  };
+}
+
+function createKimiProvider(response: unknown, stream: boolean): KimiChatProvider {
+  return new KimiChatProvider({
+    model: 'kimi-k2-turbo-preview',
+    stream,
+    clientFactory: () => makeOpenAIChatClient(response) as never,
+  });
+}
+
+function createOpenAILegacyProvider(response: unknown, stream: boolean): OpenAILegacyChatProvider {
+  return new OpenAILegacyChatProvider({
+    model: 'gpt-4.1',
+    stream,
+    clientFactory: () => makeOpenAIChatClient(response) as never,
+  });
+}
+
+describe('KimiChatProvider finish reason (stream, table coverage)', () => {
+  // A + B coverage for Kimi.
+  it.each<[string, FinishReason, string]>([
+    ['stop', 'completed', 'stop'],
+    ['tool_calls', 'tool_calls', 'tool_calls'],
+    ['function_call', 'tool_calls', 'function_call'],
+    ['length', 'truncated', 'length'],
+    ['content_filter', 'filtered', 'content_filter'],
+    ['mystery', 'other', 'mystery'],
+  ])(
+    'raw stream finish_reason %j maps to %j (raw=%j)',
+    async (raw, expectedFinish, expectedRaw) => {
+      const provider = createKimiProvider(makeKimiStream(raw), true);
+
+      const stream = await provider.generate('', [], [USER_MSG]);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.finishReason).toBe(expectedFinish);
+      expect(stream.rawFinishReason).toBe(expectedRaw);
+    },
+  );
+
+  // D coverage for Kimi.
+  it('returns null finishReason when stream never emits finish_reason', async () => {
+    const chunks = [
+      {
+        id: 'chatcmpl-null',
+        choices: [{ index: 0, delta: { content: 'partial' } }],
+      },
+    ];
+    const provider = createKimiProvider(makeAsyncIterable(chunks), true);
+
+    const stream = await provider.generate('', [], [USER_MSG]);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBeNull();
+    expect(stream.rawFinishReason).toBeNull();
+  });
+
+  // C coverage for Kimi.
+  it('captures finish_reason from a non-stream response', async () => {
+    const provider = createKimiProvider(
+      {
+        id: 'chatcmpl-ns',
+        choices: [
+          {
+            index: 0,
+            message: { role: 'assistant', content: 'hi' },
+            finish_reason: 'length',
+          },
+        ],
+        usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+      },
+      false,
+    );
+
+    const stream = await provider.generate('', [], [USER_MSG]);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('truncated');
+    expect(stream.rawFinishReason).toBe('length');
+  });
+
+  // D (non-stream) coverage for Kimi.
+  it('returns null finishReason when non-stream response omits finish_reason', async () => {
+    const provider = createKimiProvider(
+      {
+        id: 'chatcmpl-ns-null',
+        choices: [
+          {
+            index: 0,
+            message: { role: 'assistant', content: 'hi' },
+            // finish_reason omitted entirely
+          },
+        ],
+      },
+      false,
+    );
+
+    const stream = await provider.generate('', [], [USER_MSG]);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBeNull();
+    expect(stream.rawFinishReason).toBeNull();
+  });
+});
+describe('OpenAILegacyChatProvider finish reason (stream + non-stream)', () => {
+  // A + B coverage for OpenAI Legacy.
+  it.each<[string, FinishReason, string]>([
+    ['stop', 'completed', 'stop'],
+    ['tool_calls', 'tool_calls', 'tool_calls'],
+    ['function_call', 'tool_calls', 'function_call'],
+    ['length', 'truncated', 'length'],
+    ['content_filter', 'filtered', 'content_filter'],
+    ['mystery', 'other', 'mystery'],
+  ])(
+    'raw stream finish_reason %j maps to %j (raw=%j)',
+    async (raw, expectedFinish, expectedRaw) => {
+      const provider = createOpenAILegacyProvider(makeKimiStream(raw), true);
+
+      const stream = await provider.generate('', [], [USER_MSG]);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.finishReason).toBe(expectedFinish);
+      expect(stream.rawFinishReason).toBe(expectedRaw);
+    },
+  );
+
+  // C coverage for OpenAI Legacy.
+  it('captures finish_reason from a non-stream response', async () => {
+    const provider = createOpenAILegacyProvider(
+      {
+        id: 'chatcmpl-ns-legacy',
+        choices: [
+          {
+            index: 0,
+            message: { role: 'assistant', content: 'hi' },
+            finish_reason: 'content_filter',
+          },
+        ],
+        usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+      },
+      false,
+    );
+
+    const stream = await provider.generate('', [], [USER_MSG]);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('filtered');
+    expect(stream.rawFinishReason).toBe('content_filter');
+  });
+
+  // D coverage for OpenAI Legacy.
+  it('returns null finishReason when stream omits finish_reason entirely', async () => {
+    const chunks = [
+      {
+        id: 'chatcmpl-null',
+        choices: [{ index: 0, delta: { content: 'hi' } }],
+      },
+    ];
+    const provider = createOpenAILegacyProvider(makeAsyncIterable(chunks), true);
+
+    const stream = await provider.generate('', [], [USER_MSG]);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBeNull();
+    expect(stream.rawFinishReason).toBeNull();
+  });
+});
+
+// =====================================================================
+// OpenAI Responses API — stream event-based capture (A + B + C + D)
+// =====================================================================
+
+describe('OpenAIResponsesStreamedMessage finish reason', () => {
+  // A: normalization table coverage via response.completed events.
+  it.each<[string, string | undefined, FinishReason | null, string | null]>([
+    ['completed', undefined, 'completed', 'completed'],
+    ['incomplete', 'max_output_tokens', 'truncated', 'max_output_tokens'],
+    ['incomplete', 'content_filter', 'filtered', 'content_filter'],
+    ['incomplete', 'other_reason', 'other', 'other_reason'],
+    ['incomplete', undefined, 'other', 'incomplete'],
+    ['failed', undefined, 'other', 'failed'],
+    ['cancelled', undefined, null, null],
+  ])(
+    'status=%j incomplete.reason=%j -> finishReason=%j rawFinishReason=%j',
+    async (status, incompleteReason, expectedFinish, expectedRaw) => {
+      const response: Record<string, unknown> = {
+        id: 'resp_mapping',
+        status,
+        usage: { input_tokens: 1, output_tokens: 1 },
+      };
+      if (incompleteReason !== undefined) {
+        response['incomplete_details'] = { reason: incompleteReason };
+      }
+      const events = [
+        { type: 'response.output_text.delta', delta: 'hi' },
+        {
+          type: status === 'incomplete' ? 'response.incomplete' : 'response.completed',
+          response,
+        },
+      ];
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.finishReason).toBe(expectedFinish);
+      expect(stream.rawFinishReason).toBe(expectedRaw);
+    },
+  );
+
+  // B: last chunk carries finish reason — already exercised above, but
+  // verify the happy path with a full response.completed event.
+  it('captures finishReason=completed from response.completed stream event', async () => {
+    const events = [
+      { type: 'response.output_text.delta', delta: 'hi' },
+      {
+        type: 'response.completed',
+        response: {
+          id: 'resp_b',
+          status: 'completed',
+          usage: { input_tokens: 1, output_tokens: 1 },
+        },
+      },
+    ];
+    const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('completed');
+    expect(stream.rawFinishReason).toBe('completed');
+  });
+
+  // Edge case: `response.incomplete` must also be recognized.
+  it('captures finishReason from response.incomplete with max_output_tokens', async () => {
+    const events = [
+      { type: 'response.output_text.delta', delta: 'par' },
+      {
+        type: 'response.incomplete',
+        response: {
+          id: 'resp_inc_mo',
+          status: 'incomplete',
+          incomplete_details: { reason: 'max_output_tokens' },
+          usage: { input_tokens: 1, output_tokens: 1 },
+        },
+      },
+    ];
+    const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('truncated');
+    expect(stream.rawFinishReason).toBe('max_output_tokens');
+  });
+
+  it('captures finishReason from response.incomplete with content_filter', async () => {
+    const events = [
+      {
+        type: 'response.incomplete',
+        response: {
+          id: 'resp_inc_cf',
+          status: 'incomplete',
+          incomplete_details: { reason: 'content_filter' },
+          usage: { input_tokens: 1, output_tokens: 1 },
+        },
+      },
+    ];
+    const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('filtered');
+    expect(stream.rawFinishReason).toBe('content_filter');
+  });
+
+  // C: non-stream capture.
+  it('captures finishReason from non-stream response top-level status', async () => {
+    const response = {
+      id: 'resp_ns',
+      status: 'incomplete',
+      incomplete_details: { reason: 'max_output_tokens' },
+      usage: { input_tokens: 2, output_tokens: 1 },
+      output: [
+        {
+          type: 'message',
+          content: [{ type: 'output_text', text: 'partial' }],
+        },
+      ],
+    };
+    const stream = new OpenAIResponsesStreamedMessage(response, false);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('truncated');
+    expect(stream.rawFinishReason).toBe('max_output_tokens');
+  });
+
+  // D: no finish signal at all.
+  it('returns null finishReason when stream has no completed/incomplete event', async () => {
+    const events = [{ type: 'response.output_text.delta', delta: 'hi' }];
+    const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBeNull();
+    expect(stream.rawFinishReason).toBeNull();
+  });
+
+  it('returns null finishReason when non-stream response omits status', async () => {
+    const response = {
+      id: 'resp_no_status',
+      usage: { input_tokens: 1, output_tokens: 1 },
+      output: [],
+    };
+    const stream = new OpenAIResponsesStreamedMessage(response, false);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBeNull();
+    expect(stream.rawFinishReason).toBeNull();
+  });
+});
+
+// =====================================================================
+// Anthropic — stream message_delta capture (A + B + C + D)
+// =====================================================================
+
+function createAnthropicStreamProvider(events: unknown[]): AnthropicChatProvider {
+  return new AnthropicChatProvider({
+    model: 'k25',
+    defaultMaxTokens: 1024,
+    stream: true,
+    clientFactory: () =>
+      ({
+        messages: {
+          stream: vi.fn().mockReturnValue(anthropicMockStream(events)),
+        },
+      }) as never,
+  });
+}
+
+function createAnthropicNonStreamProvider(response: unknown): AnthropicChatProvider {
+  return new AnthropicChatProvider({
+    model: 'k25',
+    defaultMaxTokens: 1024,
+    stream: false,
+    clientFactory: () =>
+      ({
+        messages: {
+          create: vi.fn().mockResolvedValue(response),
+        },
+      }) as never,
+  });
+}
+
+function anthropicMockStream(events: unknown[]) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (const event of events) {
+        yield event;
+      }
+    },
+  };
+}
+
+describe('AnthropicChatProvider finish reason (stream + non-stream)', () => {
+  // A coverage: every documented stop_reason value.
+  it.each<[string, FinishReason]>([
+    ['end_turn', 'completed'],
+    ['stop_sequence', 'completed'],
+    ['max_tokens', 'truncated'],
+    ['tool_use', 'tool_calls'],
+    ['pause_turn', 'paused'],
+    ['refusal', 'filtered'],
+    ['mystery_reason', 'other'],
+  ])('stream stop_reason %j maps to %j', async (raw, expectedFinish) => {
+    const events = [
+      {
+        type: 'message_start',
+        message: { id: 'msg_a', usage: { input_tokens: 1 } },
+      },
+      { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } },
+      {
+        type: 'content_block_delta',
+        index: 0,
+        delta: { type: 'text_delta', text: 'hi' },
+      },
+      // Edge case: the implementation captures `stop_reason` from
+      // `message_delta.delta.stop_reason`. Make sure the test emits
+      // exactly that shape.
+      {
+        type: 'message_delta',
+        delta: { stop_reason: raw },
+        usage: { output_tokens: 1 },
+      },
+      { type: 'message_stop' },
+    ];
+    const provider = createAnthropicStreamProvider(events);
+
+    const stream = await provider.generate('', [], [USER_MSG]);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe(expectedFinish);
+    expect(stream.rawFinishReason).toBe(raw);
+  });
+
+  // D: no stop_reason emitted.
+  it('returns null finishReason when no message_delta carries stop_reason', async () => {
+    const events = [
+      {
+        type: 'message_start',
+        message: { id: 'msg_none', usage: { input_tokens: 1 } },
+      },
+      { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } },
+      {
+        type: 'content_block_delta',
+        index: 0,
+        delta: { type: 'text_delta', text: 'hi' },
+      },
+      // message_delta without stop_reason
+      { type: 'message_delta', delta: {}, usage: { output_tokens: 1 } },
+    ];
+    const provider = createAnthropicStreamProvider(events);
+
+    const stream = await provider.generate('', [], [USER_MSG]);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBeNull();
+    expect(stream.rawFinishReason).toBeNull();
+  });
+
+  it('returns null finishReason when message_delta.delta.stop_reason is null', async () => {
+    const events = [
+      {
+        type: 'message_start',
+        message: { id: 'msg_null_sr', usage: { input_tokens: 1 } },
+      },
+      { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } },
+      {
+        type: 'content_block_delta',
+        index: 0,
+        delta: { type: 'text_delta', text: 'hi' },
+      },
+      {
+        type: 'message_delta',
+        delta: { stop_reason: null },
+        usage: { output_tokens: 1 },
+      },
+    ];
+    const provider = createAnthropicStreamProvider(events);
+
+    const stream = await provider.generate('', [], [USER_MSG]);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBeNull();
+    expect(stream.rawFinishReason).toBeNull();
+  });
+
+  // C: non-stream top-level stop_reason.
+  it('captures stop_reason from non-stream response (max_tokens -> truncated)', async () => {
+    const provider = createAnthropicNonStreamProvider({
+      id: 'msg_ns_trunc',
+      content: [{ type: 'text', text: 'part' }],
+      usage: { input_tokens: 1, output_tokens: 1 },
+      stop_reason: 'max_tokens',
+    });
+
+    const stream = await provider.generate('', [], [USER_MSG]);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('truncated');
+    expect(stream.rawFinishReason).toBe('max_tokens');
+  });
+
+  it('returns null finishReason when non-stream response omits stop_reason', async () => {
+    const provider = createAnthropicNonStreamProvider({
+      id: 'msg_ns_null',
+      content: [{ type: 'text', text: 'hi' }],
+      usage: { input_tokens: 1, output_tokens: 1 },
+      // stop_reason omitted
+    });
+
+    const stream = await provider.generate('', [], [USER_MSG]);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBeNull();
+    expect(stream.rawFinishReason).toBeNull();
+  });
+});
+
+// =====================================================================
+// Google GenAI — normalization table + stream + fallback (A-D)
+// =====================================================================
+
+function googleStreamFromChunks(chunks: Array<Record<string, unknown>>) {
+  async function* gen() {
+    for (const chunk of chunks) {
+      yield chunk;
+    }
+  }
+  return gen();
+}
+
+function createGoogleGenAIProvider(response: unknown, stream: boolean): GoogleGenAIChatProvider {
+  return new GoogleGenAIChatProvider({
+    model: 'gemini-2.5-flash',
+    stream,
+    clientFactory: () =>
+      ({
+        models: {
+          generateContentStream: vi.fn().mockResolvedValue(response),
+          generateContent: vi.fn().mockResolvedValue(response),
+        },
+      }) as never,
+  });
+}
+
+describe('GoogleGenAIStreamedMessage finish reason', () => {
+  // A: every documented raw Gemini finishReason string.
+  it.each<[string, FinishReason | null, string | null]>([
+    ['STOP', 'completed', 'STOP'],
+    ['MAX_TOKENS', 'truncated', 'MAX_TOKENS'],
+    ['SAFETY', 'filtered', 'SAFETY'],
+    ['RECITATION', 'filtered', 'RECITATION'],
+    ['BLOCKLIST', 'filtered', 'BLOCKLIST'],
+    ['PROHIBITED_CONTENT', 'filtered', 'PROHIBITED_CONTENT'],
+    ['SPII', 'filtered', 'SPII'],
+    ['IMAGE_SAFETY', 'filtered', 'IMAGE_SAFETY'],
+    ['MALFORMED_FUNCTION_CALL', 'other', 'MALFORMED_FUNCTION_CALL'],
+    ['OTHER', 'other', 'OTHER'],
+    ['LANGUAGE', 'other', 'LANGUAGE'],
+    ['UNRECOGNIZED', 'other', 'UNRECOGNIZED'],
+    ['FINISH_REASON_UNSPECIFIED', null, null],
+  ])('raw Gemini finishReason %j maps to %j (raw=%j)', async (raw, expectedFinish, expectedRaw) => {
+    const stream = new GoogleGenAIStreamedMessage(
+      googleStreamFromChunks([
+        {
+          candidates: [
+            {
+              content: { parts: [{ text: 'hi' }], role: 'model' },
+              finishReason: raw,
+            },
+          ],
+        },
+      ]),
+      true,
+    );
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe(expectedFinish);
+    expect(stream.rawFinishReason).toBe(expectedRaw);
+  });
+
+  // Case-insensitivity: lowercase `stop` still maps to `completed`.
+  it('accepts lowercase raw value and upper-cases it', async () => {
+    const stream = new GoogleGenAIStreamedMessage(
+      googleStreamFromChunks([
+        {
+          candidates: [
+            {
+              content: { parts: [{ text: 'hi' }], role: 'model' },
+              finishReason: 'stop',
+            },
+          ],
+        },
+      ]),
+      true,
+    );
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('completed');
+    expect(stream.rawFinishReason).toBe('STOP');
+  });
+
+  // Edge case: non-string raw values must fall back to null.
+  it('falls back to null when raw finishReason is a non-string object', async () => {
+    const stream = new GoogleGenAIStreamedMessage(
+      googleStreamFromChunks([
+        {
+          candidates: [
+            {
+              content: { parts: [{ text: 'hi' }], role: 'model' },
+              // The SDK may hand us an enum-like object; we must not emit
+              // `[object Object]` into rawFinishReason.
+              finishReason: { code: 'STOP' },
+            },
+          ],
+        },
+      ]),
+      true,
+    );
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBeNull();
+    expect(stream.rawFinishReason).toBeNull();
+  });
+
+  // Edge case: UNSPECIFIED chunks must not overwrite an already
+  // captured real signal.
+  it('does not overwrite a previously captured finishReason with UNSPECIFIED', async () => {
+    // First chunk emits STOP, later chunk emits UNSPECIFIED. The
+    // normalized signal must remain `completed`.
+    const stream = new GoogleGenAIStreamedMessage(
+      googleStreamFromChunks([
+        {
+          candidates: [
+            {
+              content: { parts: [{ text: 'hi' }], role: 'model' },
+              finishReason: 'STOP',
+            },
+          ],
+        },
+        {
+          candidates: [
+            {
+              content: { parts: [{ text: '!' }], role: 'model' },
+              finishReason: 'FINISH_REASON_UNSPECIFIED',
+            },
+          ],
+        },
+      ]),
+      true,
+    );
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('completed');
+    expect(stream.rawFinishReason).toBe('STOP');
+  });
+
+  // Edge case: UNSPECIFIED chunks do not *block* later real signals.
+  it('allows a later real finishReason to overwrite an earlier UNSPECIFIED', async () => {
+    const stream = new GoogleGenAIStreamedMessage(
+      googleStreamFromChunks([
+        {
+          candidates: [
+            {
+              content: { parts: [{ text: 'a' }], role: 'model' },
+              finishReason: 'FINISH_REASON_UNSPECIFIED',
+            },
+          ],
+        },
+        {
+          candidates: [
+            {
+              content: { parts: [{ text: 'b' }], role: 'model' },
+              finishReason: 'STOP',
+            },
+          ],
+        },
+      ]),
+      true,
+    );
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('completed');
+    expect(stream.rawFinishReason).toBe('STOP');
+  });
+
+  // D: stream never carries a finishReason at all.
+  it('returns null when no chunk carries finishReason', async () => {
+    const stream = new GoogleGenAIStreamedMessage(
+      googleStreamFromChunks([
+        { candidates: [{ content: { parts: [{ text: 'hi' }], role: 'model' } }] },
+      ]),
+      true,
+    );
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBeNull();
+    expect(stream.rawFinishReason).toBeNull();
+  });
+
+  // Tolerate the snake_case key some SDK builds still emit.
+  it('accepts snake_case `finish_reason` key on the candidate object', async () => {
+    const stream = new GoogleGenAIStreamedMessage(
+      googleStreamFromChunks([
+        {
+          candidates: [
+            {
+              content: { parts: [{ text: 'hi' }], role: 'model' },
+              finish_reason: 'MAX_TOKENS',
+            },
+          ],
+        },
+      ]),
+      true,
+    );
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('truncated');
+    expect(stream.rawFinishReason).toBe('MAX_TOKENS');
+  });
+});
+
+describe('GoogleGenAIChatProvider finish reason (end-to-end)', () => {
+  // B + C: end-to-end through the provider's generate() wrapper.
+  it('captures finishReason from the provider.generate stream wrapper', async () => {
+    async function* mockStream() {
+      yield {
+        candidates: [
+          {
+            content: { parts: [{ text: 'hi' }], role: 'model' },
+            finishReason: 'MAX_TOKENS',
+          },
+        ],
+        usageMetadata: { promptTokenCount: 1, candidatesTokenCount: 1 },
+      };
+    }
+    const provider = createGoogleGenAIProvider(mockStream(), true);
+
+    const stream = await provider.generate('', [], [USER_MSG]);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('truncated');
+    expect(stream.rawFinishReason).toBe('MAX_TOKENS');
+  });
+
+  it('captures finishReason from a non-stream provider.generate response', async () => {
+    const provider = createGoogleGenAIProvider(
+      {
+        candidates: [
+          {
+            content: { parts: [{ text: 'hi' }], role: 'model' },
+            finishReason: 'SAFETY',
+          },
+        ],
+        usageMetadata: { promptTokenCount: 1, candidatesTokenCount: 1 },
+      },
+      false,
+    );
+
+    const stream = await provider.generate('', [], [USER_MSG]);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('filtered');
+    expect(stream.rawFinishReason).toBe('SAFETY');
+  });
+});
+
+// =====================================================================
+// E. generate() / step() propagation via MockChatProvider.
+// =====================================================================
+
+describe('MockChatProvider finishReason defaults and propagation', () => {
+  const parts: StreamedMessagePart[] = [{ type: 'text', text: 'hi' }];
+
+  it('defaults to completed/stop when constructor options omit the field', async () => {
+    const provider = new MockChatProvider(parts);
+    const stream = await provider.generate('', [], []);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('completed');
+    expect(stream.rawFinishReason).toBe('stop');
+  });
+
+  it('accepts an explicit null finishReason override', async () => {
+    const provider = new MockChatProvider(parts, {
+      finishReason: null,
+      rawFinishReason: null,
+    });
+    const stream = await provider.generate('', [], []);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBeNull();
+    expect(stream.rawFinishReason).toBeNull();
+  });
+
+  it('propagates custom finishReason through generate()', async () => {
+    const provider = new MockChatProvider(parts, {
+      finishReason: 'truncated',
+      rawFinishReason: 'length',
+    });
+    const result = await generate(provider, '', [], [USER_MSG]);
+    expect(result.finishReason).toBe('truncated');
+    expect(result.rawFinishReason).toBe('length');
+  });
+
+  it('propagates default finishReason through generate() when not overridden', async () => {
+    const provider = new MockChatProvider(parts);
+    const result = await generate(provider, '', [], [USER_MSG]);
+    expect(result.finishReason).toBe('completed');
+    expect(result.rawFinishReason).toBe('stop');
+  });
+
+  it('propagates null finishReason through generate()', async () => {
+    const provider = new MockChatProvider(parts, {
+      finishReason: null,
+      rawFinishReason: null,
+    });
+    const result = await generate(provider, '', [], [USER_MSG]);
+    expect(result.finishReason).toBeNull();
+    expect(result.rawFinishReason).toBeNull();
+  });
+
+  it('propagates custom finishReason through step()', async () => {
+    const provider = new MockChatProvider(parts, {
+      finishReason: 'truncated',
+      rawFinishReason: 'length',
+    });
+    const result = await step(provider, '', EMPTY_TOOLSET, [USER_MSG]);
+    expect(result.finishReason).toBe('truncated');
+    expect(result.rawFinishReason).toBe('length');
+    // Make sure we also don't mutate the message propagation semantics.
+    await result.toolResults();
+  });
+
+  it('propagates default finishReason through step()', async () => {
+    const provider = new MockChatProvider(parts);
+    const result = await step(provider, '', EMPTY_TOOLSET, [USER_MSG]);
+    expect(result.finishReason).toBe('completed');
+    expect(result.rawFinishReason).toBe('stop');
+    await result.toolResults();
+  });
+
+  it('propagates null finishReason through step()', async () => {
+    const provider = new MockChatProvider(parts, {
+      finishReason: null,
+      rawFinishReason: null,
+    });
+    const result = await step(provider, '', EMPTY_TOOLSET, [USER_MSG]);
+    expect(result.finishReason).toBeNull();
+    expect(result.rawFinishReason).toBeNull();
+    await result.toolResults();
+  });
+
+  it('preserves finishReason when withThinking() is invoked', async () => {
+    const provider = new MockChatProvider(parts, {
+      finishReason: 'filtered',
+      rawFinishReason: 'content_filter',
+    });
+    const clone = provider.withThinking('high');
+    const stream = await clone.generate('', [], []);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('filtered');
+    expect(stream.rawFinishReason).toBe('content_filter');
+  });
+});
diff --git a/packages/kosong/test/fixtures/args-validator.ts b/packages/kosong/test/fixtures/args-validator.ts
new file mode 100644
index 000000000..82674a5c2
--- /dev/null
+++ b/packages/kosong/test/fixtures/args-validator.ts
@@ -0,0 +1,39 @@
+import Ajv, { type ErrorObject, type ValidateFunction } from 'ajv';
+
+/**
+ * Test-only schema validator. Kosong's e2e tests need a way to validate tool
+ * arguments inside the SimpleToolset fixture, but kosong itself no longer
+ * ships a runtime validator (the real one moved to agent-core). Fixtures
+ * stick with draft-07 since kosong's own test schemas don't exercise newer
+ * dialects.
+ */
+
+const AJV = new Ajv({ strict: false, allErrors: true });
+
+export type JsonValue = null | number | string | boolean | JsonArray | JsonObject;
+interface JsonArray extends Array<JsonValue> {}
+interface JsonObject extends Record<string, JsonValue> {}
+
+export type ArgsValidator = ValidateFunction<JsonValue>;
+
+export function compileArgsValidator(schema: Record<string, unknown>): ArgsValidator {
+  return AJV.compile(schema) as ArgsValidator;
+}
+
+export function validateArgs(validator: ArgsValidator, args: JsonValue): string | null {
+  if (validator(args)) return null;
+  const errors = validator.errors ?? [];
+  if (errors.length === 0) return 'Tool parameter validation failed';
+  return errors.map(formatError).join('; ');
+}
+
+function formatError(error: ErrorObject): string {
+  if (error.keyword === 'required' && 'missingProperty' in error.params) {
+    return `must have required property '${String(error.params['missingProperty'])}'`;
+  }
+  if (error.keyword === 'additionalProperties' && 'additionalProperty' in error.params) {
+    return `must NOT have additional property '${String(error.params['additionalProperty'])}'`;
+  }
+  const path = error.instancePath ? `${error.instancePath} ` : '';
+  return `${path}${error.message ?? 'is invalid'}`;
+}
diff --git a/packages/kosong/test/fixtures/echo-provider.ts b/packages/kosong/test/fixtures/echo-provider.ts
new file mode 100644
index 000000000..cb49f7602
--- /dev/null
+++ b/packages/kosong/test/fixtures/echo-provider.ts
@@ -0,0 +1,440 @@
+import { UNKNOWN_CAPABILITY, type ModelCapability } from '#/capability';
+import { ChatProviderError } from '#/errors';
+import type {
+  AudioURLPart,
+  ImageURLPart,
+  Message,
+  StreamedMessagePart,
+  TextPart,
+  ThinkPart,
+  ToolCall,
+  ToolCallPart,
+  VideoURLPart,
+} from '#/message';
+import { extractText } from '#/message';
+import type {
+  ChatProvider,
+  FinishReason,
+  GenerateOptions,
+  StreamedMessage,
+  ThinkingEffort,
+} from '#/provider';
+import { normalizeOpenAIFinishReason } from '#/providers/openai-common';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+
+// ---------------------------------------------------------------------------
+// DSL parser
+// ---------------------------------------------------------------------------
+
+interface ParseResult {
+  parts: StreamedMessagePart[];
+  messageId: string | null;
+  usage: TokenUsage | null;
+  finishReason: FinishReason | null;
+  rawFinishReason: string | null;
+}
+
+/**
+ * Parse an echo DSL script into streamed message parts, an optional id,
+ * optional token usage, and an optional finish_reason.
+ *
+ * The `finish_reason: <raw>` keyword sets the raw finish reason verbatim and
+ * normalizes it via {@link normalizeOpenAIFinishReason} (because the echo
+ * DSL mimics the OpenAI Chat Completions wire shape). When the keyword is
+ * absent the result defaults to `'completed'` / `'stop'` so existing
+ * fixtures keep their previous behavior.
+ */
+export function parseEchoScript(script: string): ParseResult {
+  const parts: StreamedMessagePart[] = [];
+  let messageId: string | null = null;
+  let usage: TokenUsage | null = null;
+  let finishReason: FinishReason | null = 'completed';
+  let rawFinishReason: string | null = 'stop';
+
+  const lines = script.split('\n');
+  for (const [i, rawLine] of lines.entries()) {
+    const lineno = i + 1;
+    const line = rawLine.trim();
+
+    // skip empty lines, comments, markdown fences, bare "echo" keyword
+    if (!line || line.startsWith('#') || line.startsWith('```')) continue;
+    if (line.toLowerCase() === 'echo') continue;
+
+    const sepIdx = line.indexOf(':');
+    if (sepIdx === -1) {
+      throw new ChatProviderError(`Invalid echo DSL at line ${lineno}: ${JSON.stringify(rawLine)}`);
+    }
+
+    const kind = line.slice(0, sepIdx).trim().toLowerCase();
+    let payload = line.slice(sepIdx + 1);
+    // strip at most one leading space from payload
+    if (payload.startsWith(' ')) {
+      payload = payload.slice(1);
+    }
+
+    if (kind === 'id') {
+      messageId = stripQuotes(payload.trim());
+      continue;
+    }
+    if (kind === 'usage') {
+      usage = parseUsage(payload);
+      continue;
+    }
+    if (kind === 'finish_reason') {
+      const rawValue = stripQuotes(payload.trim());
+      if (
+        rawValue === '' ||
+        rawValue.toLowerCase() === 'null' ||
+        rawValue.toLowerCase() === 'none'
+      ) {
+        finishReason = null;
+        rawFinishReason = null;
+      } else {
+        const normalized = normalizeOpenAIFinishReason(rawValue);
+        finishReason = normalized.finishReason;
+        rawFinishReason = normalized.rawFinishReason;
+      }
+      continue;
+    }
+
+    const part = parsePart(kind, payload, lineno, rawLine);
+    parts.push(part);
+  }
+
+  return { parts, messageId, usage, finishReason, rawFinishReason };
+}
+
+function parsePart(
+  kind: string,
+  payload: string,
+  lineno: number,
+  rawLine: string,
+): StreamedMessagePart {
+  switch (kind) {
+    case 'text':
+      return { type: 'text', text: stripQuotes(payload) } satisfies TextPart;
+    case 'think':
+      return { type: 'think', think: stripQuotes(payload) } satisfies ThinkPart;
+    case 'think_encrypted':
+      return { type: 'think', think: '', encrypted: stripQuotes(payload) } satisfies ThinkPart;
+    case 'image_url': {
+      const { url, id } = parseUrlPayload(payload, kind);
+      const imageUrl: ImageURLPart['imageUrl'] =
+        id !== null && id !== undefined ? { url, id } : { url };
+      return { type: 'image_url', imageUrl } satisfies ImageURLPart;
+    }
+    case 'audio_url': {
+      const { url, id } = parseUrlPayload(payload, kind);
+      const audioUrl: AudioURLPart['audioUrl'] =
+        id !== null && id !== undefined ? { url, id } : { url };
+      return { type: 'audio_url', audioUrl } satisfies AudioURLPart;
+    }
+    case 'video_url': {
+      const { url, id } = parseUrlPayload(payload, kind);
+      const videoUrl: VideoURLPart['videoUrl'] =
+        id !== null && id !== undefined ? { url, id } : { url };
+      return { type: 'video_url', videoUrl } satisfies VideoURLPart;
+    }
+    case 'tool_call':
+      return parseToolCall(payload, lineno, rawLine);
+    case 'tool_call_part':
+      return parseToolCallPart(payload);
+    default:
+      throw new ChatProviderError(
+        `Unknown echo DSL kind '${kind}' at line ${lineno}: ${JSON.stringify(rawLine)}`,
+      );
+  }
+}
+
+function parseUsage(payload: string): TokenUsage {
+  const mapping = parseMapping(payload, 'usage');
+
+  function intValue(key: string): number {
+    const value = mapping[key] ?? 0;
+    const n = Number(value);
+    if (!Number.isInteger(n)) {
+      throw new ChatProviderError(
+        `Usage field '${key}' must be an integer, got ${JSON.stringify(value)}`,
+      );
+    }
+    return n;
+  }
+
+  return {
+    inputOther: intValue('input_other'),
+    output: intValue('output'),
+    inputCacheRead: intValue('input_cache_read'),
+    inputCacheCreation: intValue('input_cache_creation'),
+  };
+}
+
+function parseUrlPayload(payload: string, kind: string): { url: string; id: string | null } {
+  const value = parseValue(payload);
+  if (typeof value === 'object' && value !== null && value !== undefined && !Array.isArray(value)) {
+    const mapping = value as Record<string, unknown>;
+    const url = mapping['url'];
+    if (typeof url !== 'string') {
+      throw new ChatProviderError(`${kind} requires a url field, got ${JSON.stringify(mapping)}`);
+    }
+    const contentId = mapping['id'];
+    if (contentId !== null && contentId !== undefined && typeof contentId !== 'string') {
+      throw new ChatProviderError(`${kind} id must be a string when provided.`);
+    }
+    return { url, id: (contentId as string | undefined) ?? null };
+  }
+  if (typeof value !== 'string') {
+    throw new ChatProviderError(
+      `${kind} expects url string or object, got ${JSON.stringify(value)}`,
+    );
+  }
+  return { url: value, id: null };
+}
+
+function parseToolCall(payload: string, lineno: number, rawLine: string): ToolCall {
+  const mapping = parseMapping(payload, 'tool_call');
+  const func =
+    typeof mapping['function'] === 'object' &&
+    mapping['function'] !== null &&
+    mapping['function'] !== undefined
+      ? (mapping['function'] as Record<string, unknown>)
+      : null;
+
+  const toolCallId = mapping['id'] as string | undefined;
+  let name = (mapping['name'] as string | undefined) ?? (func?.['name'] as string | undefined);
+  let args = mapping['arguments'] as string | null | undefined;
+
+  if (func) {
+    args ??= func['arguments'] as string | null | undefined;
+  }
+
+  if (typeof toolCallId !== 'string' || typeof name !== 'string') {
+    throw new ChatProviderError(
+      `tool_call requires string id and name at line ${lineno}: ${JSON.stringify(rawLine)}`,
+    );
+  }
+
+  if (args !== null && args !== undefined && typeof args !== 'string') {
+    throw new ChatProviderError(
+      `tool_call.arguments must be a string at line ${lineno}, got ${typeof args}`,
+    );
+  }
+
+  return {
+    type: 'function',
+    id: toolCallId,
+    function: { name, arguments: args ?? null },
+  };
+}
+
+function parseToolCallPart(payload: string): ToolCallPart {
+  const value = parseValue(payload);
+  let argumentsPart: unknown;
+
+  if (typeof value === 'object' && value !== null && value !== undefined && !Array.isArray(value)) {
+    argumentsPart = (value as Record<string, unknown>)['arguments_part'];
+  } else {
+    argumentsPart = value;
+  }
+
+  if (typeof argumentsPart === 'object' && argumentsPart !== null && argumentsPart !== undefined) {
+    argumentsPart = JSON.stringify(argumentsPart);
+  }
+
+  const result =
+    argumentsPart === null || argumentsPart === undefined || argumentsPart === ''
+      ? null
+      : argumentsPart;
+  return { type: 'tool_call_part', argumentsPart: result as string | null };
+}
+
+function parseMapping(raw: string, context: string): Record<string, unknown> {
+  raw = raw.trim();
+
+  // Try JSON first
+  try {
+    const loaded: unknown = JSON.parse(raw);
+    if (
+      typeof loaded === 'object' &&
+      loaded !== null &&
+      loaded !== undefined &&
+      !Array.isArray(loaded)
+    ) {
+      return loaded as Record<string, unknown>;
+    }
+    if (loaded !== null && loaded !== undefined) {
+      throw new ChatProviderError(
+        `${context} payload must be an object, got ${JSON.stringify(loaded)}`,
+      );
+    }
+  } catch (error) {
+    if (error instanceof ChatProviderError) throw error;
+    // not valid JSON — fall through to key=value parsing
+  }
+
+  // key=value parsing
+  const mapping: Record<string, unknown> = {};
+  const tokens = raw.replaceAll(',', ' ').split(/\s+/);
+  for (const token of tokens) {
+    if (!token) continue;
+    if (!token.includes('=')) {
+      throw new ChatProviderError(`Invalid token '${token}' in ${context} payload.`);
+    }
+    const eqIdx = token.indexOf('=');
+    const key = token.slice(0, eqIdx).trim();
+    const val = token.slice(eqIdx + 1).trim();
+    mapping[key] = parseValue(val);
+  }
+
+  if (Object.keys(mapping).length === 0) {
+    throw new ChatProviderError(`${context} payload cannot be empty.`);
+  }
+  return mapping;
+}
+
+function parseValue(raw: string): unknown {
+  raw = raw.trim();
+  if (!raw) return null;
+  const lowered = raw.toLowerCase();
+  if (lowered === 'null' || lowered === 'none') return null;
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return stripQuotes(raw);
+  }
+}
+
+function stripQuotes(value: string): string {
+  if (value.length >= 2 && value[0] === value.at(-1) && (value[0] === "'" || value[0] === '"')) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// EchoStreamedMessage
+// ---------------------------------------------------------------------------
+
+class EchoStreamedMessage implements StreamedMessage {
+  readonly id: string | null;
+  readonly usage: TokenUsage | null;
+  readonly finishReason: FinishReason | null;
+  readonly rawFinishReason: string | null;
+
+  private readonly _parts: StreamedMessagePart[];
+
+  constructor(
+    parts: StreamedMessagePart[],
+    id: string | null,
+    usage: TokenUsage | null,
+    finishReason: FinishReason | null,
+    rawFinishReason: string | null,
+  ) {
+    this._parts = parts;
+    this.id = id;
+    this.usage = usage;
+    this.finishReason = finishReason;
+    this.rawFinishReason = rawFinishReason;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+    for (const part of this._parts) {
+      yield part;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// EchoChatProvider
+// ---------------------------------------------------------------------------
+
+/**
+ * A test-only chat provider that streams parts described by a tiny DSL.
+ *
+ * The DSL lives in the text content of the last message in `history`.
+ */
+export class EchoChatProvider implements ChatProvider {
+  readonly name: string = 'echo';
+  readonly modelName: string = 'echo';
+  readonly thinkingEffort: ThinkingEffort | null = null;
+
+  async generate(
+    _systemPrompt: string,
+    _tools: Tool[],
+    history: Message[],
+    _options?: GenerateOptions,
+  ): Promise<EchoStreamedMessage> {
+    const lastMessage = history.at(-1);
+    if (lastMessage === undefined) {
+      throw new ChatProviderError('EchoChatProvider requires at least one message in history.');
+    }
+    if (lastMessage.role !== 'user') {
+      throw new ChatProviderError('EchoChatProvider expects the last history message to be user.');
+    }
+
+    const scriptText = extractText(lastMessage);
+    const { parts, messageId, usage, finishReason, rawFinishReason } = parseEchoScript(scriptText);
+    if (parts.length === 0) {
+      throw new ChatProviderError('EchoChatProvider DSL produced no streamable parts.');
+    }
+    return new EchoStreamedMessage(parts, messageId, usage, finishReason, rawFinishReason);
+  }
+
+  withThinking(_effort: ThinkingEffort): EchoChatProvider {
+    return new EchoChatProvider();
+  }
+
+  getCapability(_model?: string): ModelCapability {
+    return UNKNOWN_CAPABILITY;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ScriptedEchoChatProvider
+// ---------------------------------------------------------------------------
+
+/**
+ * A test-only chat provider that consumes a queue of echo DSL scripts
+ * per call, one per `generate()` invocation.
+ */
+export class ScriptedEchoChatProvider implements ChatProvider {
+  readonly name: string = 'scripted_echo';
+  readonly modelName: string = 'scripted_echo';
+  readonly thinkingEffort: ThinkingEffort | null = null;
+
+  private readonly _scripts: string[];
+  private _cursor: number = 0;
+
+  constructor(scripts: string[]) {
+    this._scripts = [...scripts];
+  }
+
+  async generate(
+    _systemPrompt: string,
+    _tools: Tool[],
+    _history: Message[],
+    _options?: GenerateOptions,
+  ): Promise<EchoStreamedMessage> {
+    const scriptText = this._scripts[this._cursor];
+    if (scriptText === undefined) {
+      throw new ChatProviderError(
+        `ScriptedEchoChatProvider exhausted at turn ${this._cursor + 1}.`,
+      );
+    }
+    this._cursor++;
+
+    const { parts, messageId, usage, finishReason, rawFinishReason } = parseEchoScript(scriptText);
+    if (parts.length === 0) {
+      throw new ChatProviderError('ScriptedEchoChatProvider DSL produced no streamable parts.');
+    }
+    return new EchoStreamedMessage(parts, messageId, usage, finishReason, rawFinishReason);
+  }
+
+  withThinking(_effort: ThinkingEffort): ScriptedEchoChatProvider {
+    return new ScriptedEchoChatProvider(this._scripts.slice(this._cursor));
+  }
+
+  getCapability(_model?: string): ModelCapability {
+    return UNKNOWN_CAPABILITY;
+  }
+}
diff --git a/packages/kosong/test/fixtures/mock-provider.ts b/packages/kosong/test/fixtures/mock-provider.ts
new file mode 100644
index 000000000..1f29ae223
--- /dev/null
+++ b/packages/kosong/test/fixtures/mock-provider.ts
@@ -0,0 +1,121 @@
+import { UNKNOWN_CAPABILITY, type ModelCapability } from '#/capability';
+import type { Message, StreamedMessagePart } from '#/message';
+import type {
+  ChatProvider,
+  FinishReason,
+  GenerateOptions,
+  StreamedMessage,
+  ThinkingEffort,
+} from '#/provider';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+
+/**
+ * Constructor options accepted by {@link MockChatProvider}.
+ *
+ * `finishReason` and `rawFinishReason` default to `'completed'` / `'stop'`
+ * respectively so existing test fixtures continue to satisfy the
+ * {@link StreamedMessage} contract without explicitly opting in.
+ */
+export interface MockChatProviderOptions {
+  id?: string;
+  usage?: TokenUsage;
+  modelName?: string;
+  finishReason?: FinishReason | null;
+  rawFinishReason?: string | null;
+}
+
+/**
+ * A mock chat provider for testing.
+ * Always returns the predefined message parts.
+ */
+export class MockChatProvider implements ChatProvider {
+  readonly name: string = 'mock';
+  readonly modelName: string;
+  readonly thinkingEffort: ThinkingEffort | null = null;
+
+  private readonly _parts: StreamedMessagePart[];
+  private readonly _id: string;
+  private readonly _usage: TokenUsage | null;
+  private readonly _finishReason: FinishReason | null;
+  private readonly _rawFinishReason: string | null;
+
+  constructor(parts: StreamedMessagePart[], options?: MockChatProviderOptions) {
+    this._parts = parts;
+    this._id = options?.id ?? 'mock';
+    this._usage = options?.usage ?? null;
+    this.modelName = options?.modelName ?? 'mock';
+    this._finishReason =
+      options !== undefined && 'finishReason' in options
+        ? (options.finishReason ?? null)
+        : 'completed';
+    this._rawFinishReason =
+      options !== undefined && 'rawFinishReason' in options
+        ? (options.rawFinishReason ?? null)
+        : 'stop';
+  }
+
+  async generate(
+    _systemPrompt: string,
+    _tools: Tool[],
+    _history: Message[],
+    _options?: GenerateOptions,
+  ): Promise<MockStreamedMessage> {
+    return new MockStreamedMessage(
+      this._parts,
+      this._id,
+      this._usage,
+      this._finishReason,
+      this._rawFinishReason,
+    );
+  }
+
+  getCapability(_model?: string): ModelCapability {
+    return UNKNOWN_CAPABILITY;
+  }
+
+  withThinking(_effort: ThinkingEffort): MockChatProvider {
+    const opts: MockChatProviderOptions = {
+      id: this._id,
+      modelName: this.modelName,
+      finishReason: this._finishReason,
+      rawFinishReason: this._rawFinishReason,
+    };
+    if (this._usage !== null) {
+      opts.usage = this._usage;
+    }
+    return new MockChatProvider([...this._parts], opts);
+  }
+}
+
+/**
+ * Streamed message implementation for MockChatProvider.
+ */
+class MockStreamedMessage implements StreamedMessage {
+  readonly id: string;
+  readonly usage: TokenUsage | null;
+  readonly finishReason: FinishReason | null;
+  readonly rawFinishReason: string | null;
+
+  private readonly _parts: StreamedMessagePart[];
+
+  constructor(
+    parts: StreamedMessagePart[],
+    id: string,
+    usage: TokenUsage | null,
+    finishReason: FinishReason | null,
+    rawFinishReason: string | null,
+  ) {
+    this._parts = parts;
+    this.id = id;
+    this.usage = usage;
+    this.finishReason = finishReason;
+    this.rawFinishReason = rawFinishReason;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+    for (const part of this._parts) {
+      yield part;
+    }
+  }
+}
diff --git a/packages/kosong/test/fixtures/simple-toolset.ts b/packages/kosong/test/fixtures/simple-toolset.ts
new file mode 100644
index 000000000..9fad7bcd9
--- /dev/null
+++ b/packages/kosong/test/fixtures/simple-toolset.ts
@@ -0,0 +1,189 @@
+import type { ContentPart, ToolCall } from '#/message';
+import type { Tool } from '#/tool';
+import {
+  compileArgsValidator,
+  validateArgs,
+  type ArgsValidator,
+  type JsonValue,
+} from './args-validator';
+
+/**
+ * Test-only fixtures that emulate an agent tool-runtime layer on top of
+ * kosong's wire types. These were previously exposed by `kosong/src` but
+ * have no production consumers — the real tool runtime lives in
+ * `@moonshot-ai/agent-core`. Kosong's own e2e tests still need a minimal
+ * Toolset implementation to drive `generate()` through multi-turn flows.
+ */
+
+export interface BriefDisplayBlock {
+  type: 'brief';
+  text: string;
+}
+
+export interface UnknownDisplayBlock {
+  type: string;
+  data: Record<string, unknown>;
+}
+
+export type DisplayBlock = BriefDisplayBlock | UnknownDisplayBlock;
+
+export interface ToolReturnValue {
+  isError: boolean;
+  output: string | ContentPart[];
+  message: string;
+  display: DisplayBlock[];
+}
+
+export interface ToolResult {
+  toolCallId: string;
+  returnValue: ToolReturnValue;
+}
+
+export interface Toolset {
+  readonly tools: Tool[];
+  handle(toolCall: ToolCall, options?: { signal?: AbortSignal }): Promise<ToolResult> | ToolResult;
+}
+
+function normalizeOutput(output: string | ContentPart | ContentPart[]): string | ContentPart[] {
+  if (typeof output === 'string') return output;
+  if (Array.isArray(output)) return output;
+  return [output];
+}
+
+export function toolOk(opts: {
+  output: string | ContentPart | ContentPart[];
+  message?: string;
+  brief?: string;
+}): ToolReturnValue {
+  const display: DisplayBlock[] = [];
+  if (opts.brief) display.push({ type: 'brief', text: opts.brief });
+  return {
+    isError: false,
+    output: normalizeOutput(opts.output),
+    message: opts.message ?? '',
+    display,
+  };
+}
+
+export function toolError(opts: {
+  message: string;
+  brief: string;
+  output?: string | ContentPart | ContentPart[];
+}): ToolReturnValue {
+  return {
+    isError: true,
+    output: opts.output !== undefined ? normalizeOutput(opts.output) : '',
+    message: opts.message,
+    display: [{ type: 'brief', text: opts.brief }],
+  };
+}
+
+export function toolNotFoundError(toolName: string): ToolReturnValue {
+  const message = `Tool \`${toolName}\` not found`;
+  return {
+    isError: true,
+    output: '',
+    message,
+    display: [{ type: 'brief', text: message }],
+  };
+}
+
+export function toolParseError(message: string): ToolReturnValue {
+  const toolMessage = `Error parsing JSON arguments: ${message}`;
+  return {
+    isError: true,
+    output: '',
+    message: toolMessage,
+    display: [{ type: 'brief', text: 'Invalid arguments' }],
+  };
+}
+
+export function toolValidateError(message: string): ToolReturnValue {
+  const toolMessage = `Error validating JSON arguments: ${message}`;
+  return {
+    isError: true,
+    output: '',
+    message: toolMessage,
+    display: [{ type: 'brief', text: 'Invalid arguments' }],
+  };
+}
+
+export function toolRuntimeError(message: string): ToolReturnValue {
+  const toolMessage = `Error running tool: ${message}`;
+  return {
+    isError: true,
+    output: '',
+    message: toolMessage,
+    display: [{ type: 'brief', text: 'Tool runtime error' }],
+  };
+}
+
+export type ToolHandler = (args: JsonValue) => Promise<ToolReturnValue>;
+
+interface ToolEntry {
+  tool: Tool;
+  handler: ToolHandler;
+  validator: ArgsValidator;
+}
+
+export class SimpleToolset implements Toolset {
+  private readonly toolMap: Map<string, ToolEntry> = new Map();
+
+  get tools(): Tool[] {
+    return [...this.toolMap.values()].map((entry) => entry.tool);
+  }
+
+  add(tool: Tool, handler: ToolHandler): void {
+    this.toolMap.set(tool.name, {
+      tool,
+      handler,
+      validator: compileArgsValidator(tool.parameters),
+    });
+  }
+
+  remove(name: string): void {
+    if (!this.toolMap.has(name)) {
+      throw new Error(`Tool \`${name}\` not found in the toolset.`);
+    }
+    this.toolMap.delete(name);
+  }
+
+  handle(toolCall: ToolCall, _options?: { signal?: AbortSignal }): Promise<ToolResult> {
+    const entry = this.toolMap.get(toolCall.function.name);
+    if (entry === undefined) {
+      return Promise.resolve({
+        toolCallId: toolCall.id,
+        returnValue: toolNotFoundError(toolCall.function.name),
+      });
+    }
+
+    let args: JsonValue;
+    try {
+      args = JSON.parse(toolCall.function.arguments ?? '{}') as JsonValue;
+    } catch (error: unknown) {
+      const msg = error instanceof Error ? error.message : String(error);
+      return Promise.resolve({
+        toolCallId: toolCall.id,
+        returnValue: toolParseError(msg),
+      });
+    }
+
+    const validationError = validateArgs(entry.validator, args);
+    if (validationError !== null) {
+      return Promise.resolve({
+        toolCallId: toolCall.id,
+        returnValue: toolValidateError(validationError),
+      });
+    }
+
+    return (async (): Promise<ToolResult> => {
+      try {
+        const returnValue = await entry.handler(args);
+        return { toolCallId: toolCall.id, returnValue };
+      } catch (error: unknown) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return { toolCallId: toolCall.id, returnValue: toolRuntimeError(msg) };
+      }
+    })();
+  }
+}
diff --git a/packages/kosong/test/fixtures/step.ts b/packages/kosong/test/fixtures/step.ts
new file mode 100644
index 000000000..8d4b98888
--- /dev/null
+++ b/packages/kosong/test/fixtures/step.ts
@@ -0,0 +1,154 @@
+import { generate } from '#/generate';
+import type { GenerateCallbacks, GenerateResult } from '#/generate';
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import type { ChatProvider, FinishReason, GenerateOptions } from '#/provider';
+import type { ToolResult, Toolset } from './simple-toolset';
+import type { TokenUsage } from '#/usage';
+
+export type { GenerateResult } from '#/generate';
+export { generate } from '#/generate';
+export interface StepCallbacks {
+  onMessagePart?: (part: StreamedMessagePart) => void | Promise<void>;
+  /** Sync-only callback fired when a tool result resolves. */
+  onToolResult?: (result: ToolResult) => void;
+}
+/**
+ * The result of a single agent step.
+ *
+ * A step comprises one LLM generation followed by dispatch of any tool
+ * calls the model requested. Tools are dispatched once the stream has
+ * fully drained — this guarantees `toolCall.function.arguments` is
+ * complete JSON even when a provider interleaves parallel tool call
+ * argument deltas. Call {@link toolResults} to await all pending tool
+ * executions in order.
+ */
+export interface StepResult {
+  /** Provider-assigned response identifier, or `null` if unavailable. */
+  readonly id: string | null;
+  /** The fully-assembled assistant message produced during this step. */
+  readonly message: Message;
+  /** Token usage for this step's generation, or `null` if not reported. */
+  readonly usage: TokenUsage | null;
+  /**
+   * Normalized finish reason reported by the provider, or `null` if no
+   * finish_reason was emitted.
+   */
+  readonly finishReason: FinishReason | null;
+  /**
+   * Raw provider-specific finish_reason string preserved verbatim.
+   * `null` if the provider did not emit one.
+   */
+  readonly rawFinishReason: string | null;
+  /** Tool calls emitted by the model during this step (may be empty). */
+  readonly toolCalls: ToolCall[];
+  /**
+   * Await all tool results dispatched during this step, returned in the
+   * same order as {@link toolCalls}.
+   */
+  toolResults(): Promise<ToolResult[]>;
+}
+/**
+ * Run one agent "step": generate an LLM response and dispatch any tool calls
+ * through the toolset.
+ *
+ * Tool calls are dispatched after the provider stream has fully drained,
+ * not while it is still producing parts. This guarantees each dispatched
+ * {@link ToolCall} carries complete `function.arguments` JSON even when a
+ * provider interleaves argument deltas across parallel tool calls. The
+ * dispatched promises themselves still execute concurrently; the returned
+ * {@link StepResult.toolResults} method awaits all of them in order.
+ *
+ * @param provider - The chat provider to generate from.
+ * @param systemPrompt - System-level instruction prepended to the request.
+ * @param toolset - The toolset that handles tool call dispatch.
+ * @param history - The conversation history sent as context.
+ * @param callbacks - Optional streaming and tool-result callbacks.
+ * @param options - Optional per-call settings (e.g. an {@link AbortSignal}).
+ *
+ * @throws {ChatProviderError} (and subtypes) on provider failures.
+ */
+export async function step(
+  provider: ChatProvider,
+  systemPrompt: string,
+  toolset: Toolset,
+  history: Message[],
+  callbacks?: StepCallbacks,
+  options?: GenerateOptions,
+): Promise<StepResult> {
+  const toolCalls: ToolCall[] = [];
+  const toolResultPromises = new Map<string, Promise<ToolResult>>();
+
+  async function onToolCall(toolCall: ToolCall): Promise<void> {
+    toolCalls.push(toolCall);
+
+    const handleResult = toolset.handle(toolCall);
+
+    // Normalise to a Promise regardless of whether handle() returned sync.
+    const promise: Promise<ToolResult> =
+      handleResult instanceof Promise ? handleResult : Promise.resolve(handleResult);
+
+    // When the promise resolves, fire the onToolResult callback.
+    const tracked = promise.then((result) => {
+      if (callbacks?.onToolResult !== undefined) {
+        callbacks.onToolResult(result);
+      }
+      return result;
+    });
+
+    toolResultPromises.set(toolCall.id, tracked);
+    void tracked.catch(() => {});
+  }
+
+  let result: GenerateResult;
+  try {
+    const generateCallbacks: GenerateCallbacks = { onToolCall };
+    if (callbacks?.onMessagePart !== undefined) {
+      generateCallbacks.onMessagePart = callbacks.onMessagePart;
+    }
+    result = await generate(
+      provider,
+      systemPrompt,
+      toolset.tools,
+      history,
+      generateCallbacks,
+      options,
+    );
+  } catch (error: unknown) {
+    // On provider or cancellation errors, cancel/await all pending tool
+    // result promises to avoid dangling work.
+    await cleanupPromises(toolResultPromises);
+    throw error;
+  }
+
+  return {
+    id: result.id,
+    message: result.message,
+    usage: result.usage,
+    finishReason: result.finishReason,
+    rawFinishReason: result.rawFinishReason,
+    toolCalls,
+    async toolResults(): Promise<ToolResult[]> {
+      try {
+        const results: ToolResult[] = [];
+        for (const tc of toolCalls) {
+          const promise = toolResultPromises.get(tc.id);
+          if (promise !== undefined) {
+            results.push(await promise);
+          }
+        }
+        return results;
+      } finally {
+        // Ensure no dangling promises remain.
+        await cleanupPromises(toolResultPromises);
+      }
+    },
+  };
+}
+async function cleanupPromises(promises: Map<string, Promise<ToolResult>>): Promise<void> {
+  // Await all, swallowing errors — they've already been reported or will
+  // be reported via the original rejection.
+  const values = [...promises.values()];
+  if (values.length > 0) {
+    await Promise.allSettled(values);
+  }
+}
diff --git a/packages/kosong/test/fixtures/typed-tool.ts b/packages/kosong/test/fixtures/typed-tool.ts
new file mode 100644
index 000000000..564b17f55
--- /dev/null
+++ b/packages/kosong/test/fixtures/typed-tool.ts
@@ -0,0 +1,67 @@
+import { z } from 'zod';
+
+import type { Tool } from '#/tool';
+import { compileArgsValidator, type JsonValue } from './args-validator';
+import { toolValidateError, type ToolReturnValue } from './simple-toolset';
+
+/**
+ * Configuration for a typed tool.
+ */
+export interface TypedToolConfig<TParams> {
+  /** Unique tool name used to match invocations. */
+  name: string;
+  /** Human-readable description shown to the model. */
+  description: string;
+  /** Zod schema describing the parameter shape. The JSON Schema fed to the
+   * model is generated from this schema, and incoming arguments are validated
+   * against it at runtime. */
+  params: z.ZodType<TParams>;
+  /** Handler invoked with parsed, type-checked parameters. */
+  handler: (params: TParams) => Promise<ToolReturnValue>;
+}
+
+export interface TypedTool {
+  tool: Tool;
+  handler: (args: JsonValue) => Promise<ToolReturnValue>;
+}
+
+export function createTypedTool<TParams>(config: TypedToolConfig<TParams>): TypedTool {
+  const runtimeSchema =
+    config.params instanceof z.ZodObject
+      ? (config.params.strict() as z.ZodType<TParams>)
+      : config.params;
+
+  const jsonSchema = z.toJSONSchema(runtimeSchema) as Record<string, unknown>;
+  delete jsonSchema['$schema'];
+
+  const tool: Tool = {
+    name: config.name,
+    description: config.description,
+    parameters: jsonSchema,
+  };
+
+  // Belt-and-braces meta-schema check at construction time.
+  try {
+    compileArgsValidator(tool.parameters);
+  } catch (error) {
+    throw new Error(
+      `Invalid parameters schema for tool '${tool.name}': ${(error as Error).message}`, { cause: error },
+    );
+  }
+
+  const handler = async (args: JsonValue): Promise<ToolReturnValue> => {
+    const result = runtimeSchema.safeParse(args);
+    if (!result.success) {
+      const issues = result.error.issues
+        .map((issue) => {
+          const path = issue.path.join('.');
+          return path ? `${path}: ${issue.message}` : issue.message;
+        })
+        .join('; ');
+      return toolValidateError(`Tool parameter validation failed: ${issues}`);
+    }
+    return config.handler(result.data);
+  };
+
+  return { tool, handler };
+}
diff --git a/packages/kosong/test/generate.test.ts b/packages/kosong/test/generate.test.ts
new file mode 100644
index 000000000..f945b049f
--- /dev/null
+++ b/packages/kosong/test/generate.test.ts
@@ -0,0 +1,907 @@
+import { APIEmptyResponseError } from '#/errors';
+import { generate } from '#/generate';
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import type { ChatProvider, StreamedMessage, ThinkingEffort } from '#/provider';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+import { describe, expect, it, vi } from 'vitest';
+function createMockStream(
+  parts: StreamedMessagePart[],
+  opts?: { id?: string; usage?: TokenUsage },
+): StreamedMessage {
+  return {
+    get id(): string | null {
+      return opts?.id ?? null;
+    },
+    get usage(): TokenUsage | null {
+      return opts?.usage ?? null;
+    },
+    finishReason: null,
+    rawFinishReason: null,
+    async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+      for (const part of parts) {
+        yield part;
+      }
+    },
+  };
+}
+
+function createMockProvider(stream: StreamedMessage): ChatProvider {
+  return {
+    name: 'mock',
+    modelName: 'mock-model',
+    thinkingEffort: null,
+    generate: async (
+      _systemPrompt: string,
+      _tools: Tool[],
+      _history: Message[],
+    ): Promise<StreamedMessage> => stream,
+    withThinking(_effort: ThinkingEffort): ChatProvider {
+      return this;
+    },
+  };
+}
+describe('generate()', () => {
+  it('merges consecutive TextParts and filters empty ones', async () => {
+    const stream = createMockStream([
+      { type: 'text', text: 'Hello, ' },
+      { type: 'text', text: 'world' },
+      { type: 'text', text: '!' },
+      { type: 'image_url', imageUrl: { url: 'https://example.com/image.png' } },
+      { type: 'text', text: 'Another text.' },
+      { type: 'text', text: '' },
+      {
+        type: 'function',
+        id: 'get_weather#123',
+        function: { name: 'get_weather', arguments: null },
+      },
+      { type: 'tool_call_part', argumentsPart: '{' },
+      { type: 'tool_call_part', argumentsPart: '"city":' },
+      { type: 'tool_call_part', argumentsPart: '"Beijing"' },
+      { type: 'tool_call_part', argumentsPart: '}' },
+      { type: 'tool_call_part', argumentsPart: null },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const result = await generate(provider, '', [], []);
+
+    expect(result.message.content).toEqual([
+      { type: 'text', text: 'Hello, world!' },
+      { type: 'image_url', imageUrl: { url: 'https://example.com/image.png' } },
+      { type: 'text', text: 'Another text.' },
+    ]);
+    expect(result.message.toolCalls).toEqual([
+      {
+        type: 'function',
+        id: 'get_weather#123',
+        function: { name: 'get_weather', arguments: '{"city":"Beijing"}' },
+      },
+    ]);
+  });
+
+  it('calls onMessagePart and onToolCall callbacks correctly', async () => {
+    const inputParts: StreamedMessagePart[] = [
+      { type: 'text', text: 'Hello, ' },
+      { type: 'text', text: 'world' },
+      { type: 'text', text: '!' },
+      {
+        type: 'function',
+        id: 'get_weather#123',
+        function: { name: 'get_weather', arguments: null },
+      },
+      { type: 'tool_call_part', argumentsPart: '{' },
+      { type: 'tool_call_part', argumentsPart: '"city":' },
+      { type: 'tool_call_part', argumentsPart: '"Beijing"' },
+      { type: 'tool_call_part', argumentsPart: '}' },
+      {
+        type: 'function',
+        id: 'get_time#123',
+        function: { name: 'get_time', arguments: '' },
+      },
+    ];
+    const stream = createMockStream(inputParts);
+    const provider = createMockProvider(stream);
+
+    const outputParts: StreamedMessagePart[] = [];
+    const outputToolCalls: ToolCall[] = [];
+
+    const result = await generate(provider, '', [], [], {
+      async onMessagePart(part: StreamedMessagePart): Promise<void> {
+        outputParts.push(part);
+      },
+      async onToolCall(toolCall: ToolCall): Promise<void> {
+        outputToolCalls.push(toolCall);
+      },
+    });
+
+    // Every raw part should be echoed to onMessagePart.
+    expect(outputParts).toHaveLength(inputParts.length);
+
+    // Callback parts should be copies — mutating pendingPart should not affect them.
+    // The first three TextParts merge into one in the message, but the callback
+    // should have received them individually.
+    expect(outputParts[0]).toEqual({ type: 'text', text: 'Hello, ' });
+    expect(outputParts[1]).toEqual({ type: 'text', text: 'world' });
+    expect(outputParts[2]).toEqual({ type: 'text', text: '!' });
+
+    // onToolCall should fire for each complete ToolCall.
+    expect(outputToolCalls).toEqual(result.message.toolCalls);
+  });
+
+  it('isolates nested media payloads passed to onMessagePart', async () => {
+    const stream = createMockStream([
+      { type: 'image_url', imageUrl: { url: 'https://example.com/original.png', id: 'img-1' } },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const result = await generate(provider, '', [], [], {
+      onMessagePart(part: StreamedMessagePart): void {
+        if (part.type === 'image_url') {
+          part.imageUrl.url = 'https://example.com/mutated.png';
+          part.imageUrl.id = 'img-mutated';
+        }
+      },
+    });
+
+    expect(result.message.content).toEqual([
+      { type: 'image_url', imageUrl: { url: 'https://example.com/original.png', id: 'img-1' } },
+    ]);
+  });
+
+  it('isolates nested ToolCall extras passed to callbacks', async () => {
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'tool-1',
+        function: { name: 'search', arguments: '{}' },
+        extras: {
+          metadata: { provider: 'kimi' },
+          tags: ['a', 'b'],
+        },
+      },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const result = await generate(provider, '', [], [], {
+      onMessagePart(part: StreamedMessagePart): void {
+        if (part.type === 'function') {
+          (part.extras as { metadata: { provider: string }; tags: string[] }).metadata.provider =
+            'mutated';
+          (part.extras as { metadata: { provider: string }; tags: string[] }).tags.push('c');
+        }
+      },
+    });
+
+    expect(result.message.toolCalls).toEqual([
+      {
+        type: 'function',
+        id: 'tool-1',
+        function: { name: 'search', arguments: '{}' },
+        extras: {
+          metadata: { provider: 'kimi' },
+          tags: ['a', 'b'],
+        },
+      },
+    ]);
+  });
+
+  it('throws APIEmptyResponseError on empty response', async () => {
+    const stream = createMockStream([]);
+    const provider = createMockProvider(stream);
+
+    await expect(generate(provider, '', [], [])).rejects.toThrow(APIEmptyResponseError);
+  });
+
+  it('throws APIEmptyResponseError for think-only response', async () => {
+    const stream = createMockStream([
+      { type: 'think', think: 'Deep thinking about the problem...' },
+    ]);
+    const provider = createMockProvider(stream);
+
+    await expect(generate(provider, '', [], [])).rejects.toThrow(/only thinking content/);
+  });
+
+  it('throws APIEmptyResponseError for think + empty/whitespace text', async () => {
+    const stream = createMockStream([
+      { type: 'think', think: 'Thinking...' },
+      { type: 'text', text: '  \n  ' },
+    ]);
+    const provider = createMockProvider(stream);
+
+    await expect(generate(provider, '', [], [])).rejects.toThrow(/only thinking content/);
+  });
+
+  it('succeeds for think + real text', async () => {
+    const stream = createMockStream([
+      { type: 'think', think: 'Let me think...' },
+      { type: 'text', text: 'Here is the answer.' },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const result = await generate(provider, '', [], []);
+
+    expect(result.message.content.some((p) => p.type === 'think')).toBe(true);
+    expect(result.message.content.some((p) => p.type === 'text')).toBe(true);
+  });
+
+  it('succeeds for think + tool calls (no text)', async () => {
+    const stream = createMockStream([
+      { type: 'think', think: 'I should call a tool...' },
+      {
+        type: 'function',
+        id: 'tool#1',
+        function: { name: 'read_file', arguments: '{"path": "/tmp"}' },
+      },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const result = await generate(provider, '', [], []);
+
+    expect(result.message.content.some((p) => p.type === 'think')).toBe(true);
+    expect(result.message.toolCalls.length).toBeGreaterThan(0);
+  });
+
+  it('preserves stream id and usage', async () => {
+    const usage: TokenUsage = {
+      inputOther: 100,
+      output: 50,
+      inputCacheRead: 200,
+      inputCacheCreation: 10,
+    };
+    const stream = createMockStream([{ type: 'text', text: 'hi' }], {
+      id: 'msg-123',
+      usage,
+    });
+    const provider = createMockProvider(stream);
+
+    const result = await generate(provider, '', [], []);
+
+    expect(result.id).toBe('msg-123');
+    expect(result.usage).toEqual(usage);
+  });
+
+  it('merges ThinkParts together', async () => {
+    const stream = createMockStream([
+      { type: 'think', think: 'part1 ' },
+      { type: 'think', think: 'part2' },
+      { type: 'text', text: 'answer' },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const result = await generate(provider, '', [], []);
+
+    // The two ThinkParts should be merged.
+    const thinkParts = result.message.content.filter((p) => p.type === 'think');
+    expect(thinkParts).toHaveLength(1);
+    if (thinkParts[0]!.type === 'think') {
+      expect(thinkParts[0]!.think).toBe('part1 part2');
+    }
+  });
+
+  it('flushes pending ToolCall when a new ToolCall arrives (parallel tool calls)', async () => {
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'tc-1',
+        function: { name: 'read_file', arguments: null },
+      },
+      { type: 'tool_call_part', argumentsPart: '{"path":"/a"}' },
+      {
+        type: 'function',
+        id: 'tc-2',
+        function: { name: 'read_file', arguments: null },
+      },
+      { type: 'tool_call_part', argumentsPart: '{"path":"/b"}' },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const result = await generate(provider, '', [], []);
+
+    expect(result.message.toolCalls).toEqual([
+      {
+        type: 'function',
+        id: 'tc-1',
+        function: { name: 'read_file', arguments: '{"path":"/a"}' },
+      },
+      {
+        type: 'function',
+        id: 'tc-2',
+        function: { name: 'read_file', arguments: '{"path":"/b"}' },
+      },
+    ]);
+  });
+
+  it('handles ToolCallPart accumulation into ToolCall arguments', async () => {
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'tc-1',
+        function: { name: 'search', arguments: null },
+      },
+      { type: 'tool_call_part', argumentsPart: '{"q' },
+      { type: 'tool_call_part', argumentsPart: '":"hello"}' },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const result = await generate(provider, '', [], []);
+
+    expect(result.message.toolCalls).toEqual([
+      {
+        type: 'function',
+        id: 'tc-1',
+        function: { name: 'search', arguments: '{"q":"hello"}' },
+      },
+    ]);
+  });
+
+  // When a provider streams multiple parallel tool calls, the argument
+  // deltas can arrive interleaved. `ToolCallPart.index` must route each
+  // delta to the correct ToolCall instead of falling through to the
+  // "most recent pending ToolCall" which would cross-contaminate args.
+
+  it('routes interleaved parallel ToolCallPart deltas by index', async () => {
+    // Both tool calls are opened up-front, then their argument deltas
+    // arrive interleaved (index 0 and 1 alternating).
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'tc-a',
+        function: { name: 'read_file', arguments: null },
+        _streamIndex: 0,
+      },
+      {
+        type: 'function',
+        id: 'tc-b',
+        function: { name: 'read_file', arguments: null },
+        _streamIndex: 1,
+      },
+      // Interleaved argument deltas across the two tool calls.
+      { type: 'tool_call_part', argumentsPart: '{"path":"', index: 0 },
+      { type: 'tool_call_part', argumentsPart: '{"path":"', index: 1 },
+      { type: 'tool_call_part', argumentsPart: '/a"', index: 0 },
+      { type: 'tool_call_part', argumentsPart: '/b"', index: 1 },
+      { type: 'tool_call_part', argumentsPart: '}', index: 0 },
+      { type: 'tool_call_part', argumentsPart: '}', index: 1 },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const result = await generate(provider, '', [], []);
+
+    expect(result.message.toolCalls).toEqual([
+      {
+        type: 'function',
+        id: 'tc-a',
+        function: { name: 'read_file', arguments: '{"path":"/a"}' },
+      },
+      {
+        type: 'function',
+        id: 'tc-b',
+        function: { name: 'read_file', arguments: '{"path":"/b"}' },
+      },
+    ]);
+    // _streamIndex must NOT leak into the stored ToolCall.
+    for (const tc of result.message.toolCalls) {
+      expect(tc).not.toHaveProperty('_streamIndex');
+    }
+  });
+
+  it('routes parallel ToolCallPart deltas by string index (Responses API item_id)', async () => {
+    // Responses API uses string item_ids instead of numeric indices.
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'call_a',
+        function: { name: 'read_file', arguments: null },
+        _streamIndex: 'item_abc',
+      },
+      {
+        type: 'function',
+        id: 'call_b',
+        function: { name: 'read_file', arguments: null },
+        _streamIndex: 'item_xyz',
+      },
+      { type: 'tool_call_part', argumentsPart: '{"p":"/x"}', index: 'item_xyz' },
+      { type: 'tool_call_part', argumentsPart: '{"p":"/a"}', index: 'item_abc' },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const result = await generate(provider, '', [], []);
+
+    expect(result.message.toolCalls).toEqual([
+      {
+        type: 'function',
+        id: 'call_a',
+        function: { name: 'read_file', arguments: '{"p":"/a"}' },
+      },
+      {
+        type: 'function',
+        id: 'call_b',
+        function: { name: 'read_file', arguments: '{"p":"/x"}' },
+      },
+    ]);
+  });
+
+  it('falls back to sequential merge when ToolCallPart has no index', async () => {
+    // Back-compat: providers that do not emit `index` continue to work
+    // when there is a single tool call in flight.
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'tc-1',
+        function: { name: 'search', arguments: null },
+      },
+      { type: 'tool_call_part', argumentsPart: '{"q":' },
+      { type: 'tool_call_part', argumentsPart: '"hi"}' },
+      {
+        type: 'function',
+        id: 'tc-2',
+        function: { name: 'search', arguments: null },
+      },
+      { type: 'tool_call_part', argumentsPart: '{"q":"bye"}' },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const result = await generate(provider, '', [], []);
+
+    expect(result.message.toolCalls).toEqual([
+      {
+        type: 'function',
+        id: 'tc-1',
+        function: { name: 'search', arguments: '{"q":"hi"}' },
+      },
+      {
+        type: 'function',
+        id: 'tc-2',
+        function: { name: 'search', arguments: '{"q":"bye"}' },
+      },
+    ]);
+  });
+
+  it('handles indexed deltas arriving after the pending tool call has changed', async () => {
+    // tc0 opens, receives its full arguments, then tc1 opens and becomes
+    // pending, then a late delta for tc0 arrives by index. The late
+    // delta must route back to tc0 rather than appending to tc1.
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'tc-0',
+        function: { name: 'write', arguments: null },
+        _streamIndex: 0,
+      },
+      { type: 'tool_call_part', argumentsPart: '{"a":', index: 0 },
+      { type: 'tool_call_part', argumentsPart: '1', index: 0 },
+      {
+        type: 'function',
+        id: 'tc-1',
+        function: { name: 'write', arguments: null },
+        _streamIndex: 1,
+      },
+      { type: 'tool_call_part', argumentsPart: '{"b":2}', index: 1 },
+      // Late delta for tc-0 — must be routed via the index map.
+      { type: 'tool_call_part', argumentsPart: '}', index: 0 },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const result = await generate(provider, '', [], []);
+
+    expect(result.message.toolCalls).toEqual([
+      {
+        type: 'function',
+        id: 'tc-0',
+        function: { name: 'write', arguments: '{"a":1}' },
+      },
+      {
+        type: 'function',
+        id: 'tc-1',
+        function: { name: 'write', arguments: '{"b":2}' },
+      },
+    ]);
+  });
+
+  it('onToolCall callback receives stored ToolCall without _streamIndex', async () => {
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'tc-1',
+        function: { name: 'f', arguments: null },
+        _streamIndex: 0,
+      },
+      { type: 'tool_call_part', argumentsPart: '{}', index: 0 },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const received: ToolCall[] = [];
+    await generate(provider, '', [], [], {
+      async onToolCall(tc: ToolCall): Promise<void> {
+        received.push(tc);
+      },
+    });
+
+    expect(received).toHaveLength(1);
+    expect(received[0]).toEqual({
+      type: 'function',
+      id: 'tc-1',
+      function: { name: 'f', arguments: '{}' },
+    });
+    expect(received[0]).not.toHaveProperty('_streamIndex');
+  });
+
+  // Parallel tool call streams can interleave headers and arguments:
+  //
+  //   tc0-header → tc1-header → tc0-args → tc1-args → done
+  //
+  // Previously the generate loop fired onToolCall the moment a second
+  // ToolCall header forced a flush of the first. At that point tc0's
+  // arguments had not yet been received, so any consumer that parsed
+  // `tc.function.arguments` inside the callback (e.g. step() dispatching
+  // the tool) would hit a JSON parse error on an empty/partial string.
+  //
+  // `onToolCall` must stay deferred until the stream has drained.
+
+  it('onToolCall fires only after the stream completes, with fully-assembled arguments', async () => {
+    // Pathological stream: interleaved headers and argument deltas.
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'call_a',
+        function: { name: 'tool_a', arguments: null },
+        _streamIndex: 0,
+      },
+      {
+        type: 'function',
+        id: 'call_b',
+        function: { name: 'tool_b', arguments: null },
+        _streamIndex: 1,
+      },
+      { type: 'tool_call_part', argumentsPart: '{"x":', index: 0 },
+      { type: 'tool_call_part', argumentsPart: '{"y":', index: 1 },
+      { type: 'tool_call_part', argumentsPart: '1}', index: 0 },
+      { type: 'tool_call_part', argumentsPart: '2}', index: 1 },
+    ]);
+    const provider = createMockProvider(stream);
+
+    // Capture what each callback invocation sees. Each callback must
+    // observe fully-assembled arguments.
+    const callbackSnapshots: Array<{ id: string; args: string | null }> = [];
+
+    const result = await generate(provider, '', [], [], {
+      async onToolCall(tc: ToolCall): Promise<void> {
+        callbackSnapshots.push({ id: tc.id, args: tc.function.arguments });
+      },
+    });
+
+    // Both callbacks fired, in the order the tool calls were
+    // appended to `message.toolCalls`.
+    expect(callbackSnapshots).toEqual([
+      { id: 'call_a', args: '{"x":1}' },
+      { id: 'call_b', args: '{"y":2}' },
+    ]);
+
+    // The message itself reflects the same final state.
+    expect(result.message.toolCalls).toEqual([
+      {
+        type: 'function',
+        id: 'call_a',
+        function: { name: 'tool_a', arguments: '{"x":1}' },
+      },
+      {
+        type: 'function',
+        id: 'call_b',
+        function: { name: 'tool_b', arguments: '{"y":2}' },
+      },
+    ]);
+  });
+
+  it('onToolCall observes fully-populated message.toolCalls at callback time', async () => {
+    // Stronger invariant: at the moment each onToolCall fires, every
+    // tool call in the message is already present with complete
+    // arguments. This is what step() relies on to dispatch tools
+    // without hitting partial-JSON parse errors.
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'call_a',
+        function: { name: 'tool_a', arguments: null },
+        _streamIndex: 0,
+      },
+      {
+        type: 'function',
+        id: 'call_b',
+        function: { name: 'tool_b', arguments: null },
+        _streamIndex: 1,
+      },
+      {
+        type: 'function',
+        id: 'call_c',
+        function: { name: 'tool_c', arguments: null },
+        _streamIndex: 2,
+      },
+      // Heavily interleaved argument deltas.
+      { type: 'tool_call_part', argumentsPart: '{"k":', index: 2 },
+      { type: 'tool_call_part', argumentsPart: '{"k":', index: 0 },
+      { type: 'tool_call_part', argumentsPart: '{"k":', index: 1 },
+      { type: 'tool_call_part', argumentsPart: '3}', index: 2 },
+      { type: 'tool_call_part', argumentsPart: '1}', index: 0 },
+      { type: 'tool_call_part', argumentsPart: '2}', index: 1 },
+    ]);
+    const provider = createMockProvider(stream);
+
+    // Shared state so the callback can inspect the message.
+    const state: { message: Message | null } = { message: null };
+    const observations: Array<{ id: string; totalToolCalls: number; allComplete: boolean }> = [];
+
+    const result = await generate(provider, '', [], [], {
+      async onToolCall(tc: ToolCall): Promise<void> {
+        const msg = state.message;
+        if (msg === null) {
+          // First callback: we don't have a message reference yet
+          // because `generate` hasn't returned. But the invariant we
+          // care about is that `tc.function.arguments` is complete
+          // JSON — verify that directly.
+          observations.push({
+            id: tc.id,
+            totalToolCalls: -1, // unknown — message ref not yet bound
+            allComplete: tc.function.arguments !== null && tc.function.arguments.endsWith('}'),
+          });
+          return;
+        }
+        observations.push({
+          id: tc.id,
+          totalToolCalls: msg.toolCalls.length,
+          allComplete: msg.toolCalls.every(
+            (c) => c.function.arguments !== null && c.function.arguments.endsWith('}'),
+          ),
+        });
+      },
+    });
+    state.message = result.message;
+
+    // Every callback observed well-formed, complete arguments for its
+    // own tool call.
+    for (const obs of observations) {
+      expect(obs.allComplete).toBe(true);
+    }
+    expect(observations.map((o) => o.id)).toEqual(['call_a', 'call_b', 'call_c']);
+
+    // The final assembled arguments match the index-based routing.
+    expect(result.message.toolCalls.map((tc) => tc.function.arguments)).toEqual([
+      '{"k":1}',
+      '{"k":2}',
+      '{"k":3}',
+    ]);
+  });
+
+  it('pre-aborted signal does not call provider.generate', async () => {
+    let calledGenerate = false;
+    const provider: ChatProvider = {
+      name: 'mock',
+      modelName: 'mock-model',
+      thinkingEffort: null,
+      generate: async (
+        _systemPrompt: string,
+        _tools: Tool[],
+        _history: Message[],
+      ): Promise<StreamedMessage> => {
+        calledGenerate = true;
+        return createMockStream([{ type: 'text', text: 'should not reach here' }]);
+      },
+      withThinking(_effort: ThinkingEffort): ChatProvider {
+        return this;
+      },
+    };
+
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(
+      generate(provider, '', [], [], undefined, { signal: controller.signal }),
+    ).rejects.toMatchObject({ name: 'AbortError' });
+
+    expect(calledGenerate).toBe(false);
+  });
+
+  it('signal aborted between provider.generate() and stream iteration is honored', async () => {
+    const controller = new AbortController();
+    let observedParts = 0;
+
+    const stream: StreamedMessage = {
+      get id(): string | null {
+        return null;
+      },
+      get usage(): TokenUsage | null {
+        return null;
+      },
+      finishReason: null,
+      rawFinishReason: null,
+      async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+        observedParts += 1;
+        yield { type: 'text', text: 'leaked' };
+      },
+    };
+
+    const provider: ChatProvider = {
+      name: 'mock',
+      modelName: 'mock-model',
+      thinkingEffort: null,
+      generate: async (
+        _systemPrompt: string,
+        _tools: Tool[],
+        _history: Message[],
+      ): Promise<StreamedMessage> => {
+        // Abort between provider.generate() resolving and generate() seeing
+        // its return value.
+        controller.abort();
+        return stream;
+      },
+      withThinking(_effort: ThinkingEffort): ChatProvider {
+        return this;
+      },
+    };
+
+    await expect(
+      generate(provider, '', [], [], undefined, { signal: controller.signal }),
+    ).rejects.toMatchObject({ name: 'AbortError' });
+
+    // Stream iteration must never have started.
+    expect(observedParts).toBe(0);
+  });
+
+  it('aborting in the last onMessagePart callback throws AbortError and skips onToolCall', async () => {
+    const controller = new AbortController();
+    const onToolCall = vi.fn<(toolCall: ToolCall) => Promise<void>>();
+
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'call-1',
+        function: { name: 'plus', arguments: null },
+      },
+      { type: 'tool_call_part', argumentsPart: '{"a":1}' },
+      { type: 'text', text: 'done' },
+    ]);
+    const provider = createMockProvider(stream);
+
+    await expect(
+      generate(
+        provider,
+        '',
+        [],
+        [],
+        {
+          async onMessagePart(part: StreamedMessagePart): Promise<void> {
+            if (part.type === 'text' && part.text === 'done') {
+              controller.abort();
+            }
+          },
+          onToolCall,
+        },
+        { signal: controller.signal },
+      ),
+    ).rejects.toMatchObject({ name: 'AbortError' });
+
+    expect(onToolCall).not.toHaveBeenCalled();
+  });
+
+  it('post-await abort cancels the acquired stream before throwing AbortError', async () => {
+    const controller = new AbortController();
+    const cancel = vi.fn<() => Promise<void>>().mockResolvedValue(undefined);
+
+    const stream: StreamedMessage & { cancel(): Promise<void> } = {
+      cancel,
+      get id(): string | null {
+        return null;
+      },
+      get usage(): TokenUsage | null {
+        return null;
+      },
+      finishReason: null,
+      rawFinishReason: null,
+      async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+        yield { type: 'text', text: 'leaked' };
+      },
+    };
+
+    const provider: ChatProvider = {
+      name: 'mock',
+      modelName: 'mock-model',
+      thinkingEffort: null,
+      generate: async (): Promise<StreamedMessage> => {
+        controller.abort();
+        return stream;
+      },
+      withThinking(_effort: ThinkingEffort): ChatProvider {
+        return this;
+      },
+    };
+
+    await expect(
+      generate(provider, '', [], [], undefined, { signal: controller.signal }),
+    ).rejects.toMatchObject({ name: 'AbortError' });
+
+    expect(cancel).toHaveBeenCalledTimes(1);
+  });
+
+  it('onToolCall receives tool calls in message order', async () => {
+    // Stream yields tc0-header, then its full args, then tc1-header,
+    // then its full args. The callback must see them in message order.
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'first',
+        function: { name: 'f', arguments: null },
+      },
+      { type: 'tool_call_part', argumentsPart: '{"i":1}' },
+      {
+        type: 'function',
+        id: 'second',
+        function: { name: 'g', arguments: null },
+      },
+      { type: 'tool_call_part', argumentsPart: '{"i":2}' },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const received: string[] = [];
+    await generate(provider, '', [], [], {
+      async onToolCall(tc: ToolCall): Promise<void> {
+        received.push(tc.id);
+      },
+    });
+
+    expect(received).toEqual(['first', 'second']);
+  });
+
+  describe('finishReason propagation', () => {
+    function streamWithFinish(
+      parts: StreamedMessagePart[],
+      finishReason:
+        | 'completed'
+        | 'truncated'
+        | 'tool_calls'
+        | 'filtered'
+        | 'paused'
+        | 'other'
+        | null,
+      rawFinishReason: string | null,
+    ): StreamedMessage {
+      return {
+        id: 'mock-id',
+        usage: null,
+        finishReason,
+        rawFinishReason,
+        async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+          for (const part of parts) {
+            yield part;
+          }
+        },
+      };
+    }
+
+    it('copies stream.finishReason and stream.rawFinishReason onto the generate result', async () => {
+      const stream = streamWithFinish([{ type: 'text', text: 'hello' }], 'truncated', 'length');
+      const provider = createMockProvider(stream);
+      const result = await generate(provider, '', [], []);
+      expect(result.finishReason).toBe('truncated');
+      expect(result.rawFinishReason).toBe('length');
+    });
+
+    it('copies null finishReason when the provider did not emit one', async () => {
+      const stream = streamWithFinish([{ type: 'text', text: 'hi' }], null, null);
+      const provider = createMockProvider(stream);
+      const result = await generate(provider, '', [], []);
+      expect(result.finishReason).toBeNull();
+      expect(result.rawFinishReason).toBeNull();
+    });
+
+    it('copies filtered finishReason alongside its raw value', async () => {
+      const stream = streamWithFinish(
+        [{ type: 'text', text: 'nope' }],
+        'filtered',
+        'content_filter',
+      );
+      const provider = createMockProvider(stream);
+      const result = await generate(provider, '', [], []);
+      expect(result.finishReason).toBe('filtered');
+      expect(result.rawFinishReason).toBe('content_filter');
+    });
+  });
+});
diff --git a/packages/kosong/test/google-genai.test.ts b/packages/kosong/test/google-genai.test.ts
new file mode 100644
index 000000000..e1ad47c3a
--- /dev/null
+++ b/packages/kosong/test/google-genai.test.ts
@@ -0,0 +1,1688 @@
+import {
+  APIConnectionError,
+  APIContextOverflowError,
+  APIStatusError,
+  APITimeoutError,
+  ChatProviderError,
+} from '#/errors';
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import {
+  convertGoogleGenAIError,
+  GoogleGenAIChatProvider,
+  GoogleGenAIStreamedMessage,
+  messagesToGoogleGenAIContents,
+} from '#/providers/google-genai';
+import type { Tool } from '#/tool';
+import { describe, it, expect, vi } from 'vitest';
+
+function makeGenerateContentResponse() {
+  return {
+    candidates: [
+      {
+        content: { parts: [{ text: 'Hello' }], role: 'model' },
+        finishReason: 'STOP',
+      },
+    ],
+    usageMetadata: {
+      promptTokenCount: 10,
+      candidatesTokenCount: 5,
+      totalTokenCount: 15,
+    },
+    modelVersion: 'gemini-2.5-flash',
+  };
+}
+
+function createProvider(
+  options?: Partial<{ model: string; vertexai: boolean; stream: boolean }>,
+): GoogleGenAIChatProvider {
+  return new GoogleGenAIChatProvider({
+    model: options?.model ?? 'gemini-2.5-flash',
+    apiKey: 'test-key',
+    vertexai: options?.vertexai,
+    stream: options?.stream,
+  });
+}
+
+/** Capture the request body by mocking the client's generateContentStream. */
+async function captureRequestBody(
+  provider: GoogleGenAIChatProvider,
+  systemPrompt: string,
+  tools: Tool[],
+  history: Message[],
+): Promise<Record<string, unknown>> {
+  let capturedBody: Record<string, unknown> | undefined;
+
+  const mockModels = (provider as any)._client.models as Record<string, unknown>;
+
+  async function* mockStream() {
+    yield makeGenerateContentResponse();
+  }
+
+  mockModels['generateContentStream'] = vi.fn().mockImplementation((params: unknown) => {
+    capturedBody = params as Record<string, unknown>;
+    return Promise.resolve(mockStream());
+  });
+
+  mockModels['generateContent'] = vi.fn().mockImplementation((params: unknown) => {
+    capturedBody = params as Record<string, unknown>;
+    return Promise.resolve(makeGenerateContentResponse());
+  });
+
+  const stream = await provider.generate(systemPrompt, tools, history);
+  for await (const part of stream) {
+    void part;
+  }
+
+  if (capturedBody === undefined) {
+    throw new Error('Expected provider.generate() to call a Google GenAI model endpoint');
+  }
+  return capturedBody;
+}
+
+/** Collect all parts from a StreamedMessage. */
+async function collectParts(msg: {
+  [Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart>;
+}): Promise<StreamedMessagePart[]> {
+  const parts: StreamedMessagePart[] = [];
+  for await (const part of msg) {
+    parts.push(part);
+  }
+  return parts;
+}
+
+const ADD_TOOL: Tool = {
+  name: 'add',
+  description: 'Add two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+const MUL_TOOL: Tool = {
+  name: 'multiply',
+  description: 'Multiply two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+describe('GoogleGenAIChatProvider', () => {
+  describe('message conversion', () => {
+    it('simple user message with system prompt', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hello!' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, 'You are helpful.', [], history);
+
+      expect(body['contents']).toEqual([{ parts: [{ text: 'Hello!' }], role: 'user' }]);
+      const config = body['config'] as Record<string, unknown>;
+      expect(config['system_instruction']).toBe('You are helpful.');
+    });
+
+    it('system messages in history are wrapped and emitted as user content', () => {
+      // Regression: Google GenAI's Content.role only accepts "user" or
+      // "model", so a `system` message sitting in the replay history (from
+      // session restore or cross-provider migration) would be rejected by
+      // the API. messagesToGoogleGenAIContents must transform it into a
+      // user turn wrapped in <system>...</system> tags so the information
+      // survives without provoking a 400.
+      const messages: Message[] = [
+        {
+          role: 'system',
+          content: [{ type: 'text', text: 'You are helpful.' }],
+          toolCalls: [],
+        },
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Hi' }],
+          toolCalls: [],
+        },
+      ];
+
+      const contents = messagesToGoogleGenAIContents(messages);
+
+      expect(contents).toHaveLength(2);
+      const first = contents[0] as unknown as {
+        role: string;
+        parts: Array<{ text?: string }>;
+      };
+      expect(first.role).toBe('user');
+      expect(first.parts).toHaveLength(1);
+      expect(first.parts[0]!.text).toBe('<system>You are helpful.</system>');
+      // Original user turn is untouched.
+      const second = contents[1] as unknown as {
+        role: string;
+        parts: Array<{ text?: string }>;
+      };
+      expect(second.role).toBe('user');
+      expect(second.parts[0]!.text).toBe('Hi');
+      // No emitted content carries the unsupported "system" role.
+      for (const c of contents) {
+        expect((c as unknown as { role: string }).role).not.toBe('system');
+      }
+    });
+
+    it('empty system messages in history are dropped', () => {
+      // A system message with no textual content contributes nothing; it
+      // would be pointless (and arguably confusing to models) to emit an
+      // empty <system></system> user turn, so we skip it entirely.
+      const messages: Message[] = [
+        {
+          role: 'system',
+          content: [],
+          toolCalls: [],
+        },
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Hi' }],
+          toolCalls: [],
+        },
+      ];
+
+      const contents = messagesToGoogleGenAIContents(messages);
+      expect(contents).toHaveLength(1);
+      expect((contents[0] as unknown as { role: string }).role).toBe('user');
+    });
+
+    it('multi-turn conversation with assistant mapped to model', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        { role: 'assistant', content: [{ type: 'text', text: '2+2 equals 4.' }], toolCalls: [] },
+        { role: 'user', content: [{ type: 'text', text: 'And 3+3?' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['contents']).toEqual([
+        { parts: [{ text: 'What is 2+2?' }], role: 'user' },
+        { parts: [{ text: '2+2 equals 4.' }], role: 'model' },
+        { parts: [{ text: 'And 3+3?' }], role: 'user' },
+      ]);
+    });
+
+    it('multi-turn conversation with system prompt sets system_instruction', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        { role: 'assistant', content: [{ type: 'text', text: '2+2 equals 4.' }], toolCalls: [] },
+        { role: 'user', content: [{ type: 'text', text: 'And 3+3?' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, 'You are a math tutor.', [], history);
+
+      expect(body['contents']).toEqual([
+        { parts: [{ text: 'What is 2+2?' }], role: 'user' },
+        { parts: [{ text: '2+2 equals 4.' }], role: 'model' },
+        { parts: [{ text: 'And 3+3?' }], role: 'user' },
+      ]);
+
+      const config = body['config'] as Record<string, unknown>;
+      expect(config['system_instruction']).toBe('You are a math tutor.');
+    });
+
+    it('tool definitions use parameters_json_schema', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL, MUL_TOOL], history);
+
+      const config = body['config'] as Record<string, unknown>;
+      expect(config['tools']).toEqual([
+        {
+          function_declarations: [
+            {
+              name: 'add',
+              description: 'Add two integers.',
+              parameters_json_schema: {
+                type: 'object',
+                properties: {
+                  a: { type: 'integer', description: 'First number' },
+                  b: { type: 'integer', description: 'Second number' },
+                },
+                required: ['a', 'b'],
+              },
+            },
+          ],
+        },
+        {
+          function_declarations: [
+            {
+              name: 'multiply',
+              description: 'Multiply two integers.',
+              parameters_json_schema: {
+                type: 'object',
+                properties: {
+                  a: { type: 'integer', description: 'First number' },
+                  b: { type: 'integer', description: 'Second number' },
+                },
+                required: ['a', 'b'],
+              },
+            },
+          ],
+        },
+      ]);
+    });
+
+    it('tool call and tool result packed into user Content', async () => {
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_abc123',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll add those numbers for you." }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '5' }],
+          toolCallId: 'call_abc123',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['contents']).toEqual([
+        { parts: [{ text: 'Add 2 and 3' }], role: 'user' },
+        {
+          parts: [
+            { text: "I'll add those numbers for you." },
+            { function_call: { name: 'add', args: { a: 2, b: 3 } } },
+          ],
+          role: 'model',
+        },
+        {
+          parts: [
+            {
+              function_response: {
+                name: 'add',
+                response: { output: '5' },
+                parts: [],
+              },
+            },
+          ],
+          role: 'user',
+        },
+      ]);
+    });
+
+    it('tool call with thought_signature_b64 emits thoughtSignature on outbound function_call', async () => {
+      // Round-trip: a previous turn returned a tool call with thoughtSignature
+      // (decoded into ToolCall.extras.thought_signature_b64). When we send
+      // the assistant message back, the converter must put the original
+      // signature back into the function_call part so Gemini can resume the
+      // reasoning chain.
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll add those." }],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'add_call_sig',
+              function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+              extras: { thought_signature_b64: 'dGhvdWdodF9zaWduYXR1cmVfZGF0YQ==' },
+            },
+          ],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const contents = body['contents'] as Array<{ parts: unknown[]; role: string }>;
+      const assistantParts = contents.find((c) => c.role === 'model')!.parts;
+      const fnCallPart = assistantParts.find(
+        (p) => (p as Record<string, unknown>)['function_call'] !== undefined,
+      ) as { function_call: Record<string, unknown>; thought_signature?: unknown } | undefined;
+      expect(fnCallPart).toMatchObject({
+        function_call: { name: 'add', args: { a: 2, b: 3 } },
+        thought_signature: 'dGhvdWdodF9zaWduYXR1cmVfZGF0YQ==',
+      });
+    });
+
+    it('tool message with image_url result yields function_response + inline data part', () => {
+      const messages: Message[] = [
+        {
+          role: 'assistant',
+          content: [],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'tc_001',
+              function: { name: 'fetch_image', arguments: '{}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: 'Found image:' },
+            { type: 'image_url', imageUrl: { url: 'data:image/png;base64,iVBORw0KGgo=' } },
+          ],
+          toolCalls: [],
+          toolCallId: 'tc_001',
+        },
+      ];
+
+      const contents = messagesToGoogleGenAIContents(messages);
+
+      // Should have assistant Content + one user Content with 2 parts
+      expect(contents).toHaveLength(2);
+      const userContent = contents[1] as unknown as {
+        role: string;
+        parts: Array<Record<string, unknown>>;
+      };
+      expect(userContent.role).toBe('user');
+      expect(userContent.parts.length).toBeGreaterThanOrEqual(2);
+
+      const fnResp = userContent.parts.find((p) => 'function_response' in p) as
+        | { function_response: { name: string; response: { output: string } } }
+        | undefined;
+      expect(fnResp).toMatchObject({
+        function_response: {
+          name: 'fetch_image',
+          response: { output: 'Found image:' },
+        },
+      });
+
+      const inlineData = userContent.parts.find((p) => 'inlineData' in p) as
+        | { inlineData: { mimeType: string; data: string } }
+        | undefined;
+      expect(inlineData).toMatchObject({
+        inlineData: { mimeType: 'image/png', data: 'iVBORw0KGgo=' },
+      });
+    });
+
+    it('tool message with audio_url and video_url results yields independent parts', () => {
+      const messages: Message[] = [
+        {
+          role: 'assistant',
+          content: [],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'tc_002',
+              function: { name: 'fetch_media', arguments: '{}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: 'Got audio and video:' },
+            { type: 'audio_url', audioUrl: { url: 'https://example.com/sound.mp3' } },
+            { type: 'video_url', videoUrl: { url: 'https://example.com/clip.mp4' } },
+          ],
+          toolCalls: [],
+          toolCallId: 'tc_002',
+        },
+      ];
+
+      const contents = messagesToGoogleGenAIContents(messages);
+
+      expect(contents).toHaveLength(2);
+      const userContent = contents[1] as unknown as {
+        role: string;
+        parts: Array<Record<string, unknown>>;
+      };
+      expect(userContent.role).toBe('user');
+      // function_response + audio + video
+      expect(userContent.parts).toHaveLength(3);
+
+      const fnResp = userContent.parts.find((p) => 'function_response' in p) as
+        | { function_response: { response: { output: string } } }
+        | undefined;
+      expect(fnResp).toMatchObject({
+        function_response: { response: { output: 'Got audio and video:' } },
+      });
+
+      const fileDataParts = userContent.parts.filter((p) => 'fileData' in p) as Array<{
+        fileData: { fileUri: string; mimeType: string };
+      }>;
+      expect(fileDataParts).toHaveLength(2);
+      const mimeTypes = fileDataParts.map((p) => p.fileData.mimeType).toSorted();
+      expect(mimeTypes).toEqual(['audio/mpeg', 'video/mp4']);
+    });
+
+    it('forwards video_url parts in regular messages as fileData', () => {
+      const messages: Message[] = [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'Please inspect this clip.' },
+            { type: 'video_url', videoUrl: { url: 'https://example.com/demo.mp4' } },
+          ],
+          toolCalls: [],
+        },
+      ];
+
+      const contents = messagesToGoogleGenAIContents(messages);
+
+      expect(contents).toHaveLength(1);
+      expect(contents[0]).toEqual({
+        role: 'user',
+        parts: [
+          { text: 'Please inspect this clip.' },
+          { fileData: { fileUri: 'https://example.com/demo.mp4', mimeType: 'video/mp4' } },
+        ],
+      });
+    });
+
+    it('parallel tool calls packed into single user Content', async () => {
+      const provider = createProvider();
+      // Mirror Python COMMON_CASES.parallel_tool_calls: multi-ContentPart
+      // tool results with a <system-reminder> prefix proving the provider
+      // concatenates text parts into `response.output`.
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Calculate 2+3 and 4*5' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll calculate both." }],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_add',
+              function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+            },
+            {
+              type: 'function',
+              id: 'call_mul',
+              function: { name: 'multiply', arguments: '{"a": 4, "b": 5}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          content: [
+            {
+              type: 'text',
+              text: '<system-reminder>This is a system reminder</system-reminder>',
+            },
+            { type: 'text', text: '5' },
+          ],
+          toolCallId: 'call_add',
+          toolCalls: [],
+        },
+        {
+          role: 'tool',
+          content: [
+            {
+              type: 'text',
+              text: '<system-reminder>This is a system reminder</system-reminder>',
+            },
+            { type: 'text', text: '20' },
+          ],
+          toolCallId: 'call_mul',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL, MUL_TOOL], history);
+
+      // Snapshot of the expected wire format:
+      // - exactly 3 contents in order (user, model with 2 function_calls, user with 2 function_responses bundled)
+      // - both tool results are N:1 packed into ONE user Content
+      // - text parts are concatenated into `response.output` (system-reminder + result)
+      // - functionCall / functionResponse never include an `id` field
+      expect(body['contents']).toEqual([
+        { parts: [{ text: 'Calculate 2+3 and 4*5' }], role: 'user' },
+        {
+          parts: [
+            { text: "I'll calculate both." },
+            { function_call: { name: 'add', args: { a: 2, b: 3 } } },
+            { function_call: { name: 'multiply', args: { a: 4, b: 5 } } },
+          ],
+          role: 'model',
+        },
+        {
+          parts: [
+            {
+              function_response: {
+                name: 'add',
+                response: {
+                  output: '<system-reminder>This is a system reminder</system-reminder>5',
+                },
+                parts: [],
+              },
+            },
+            {
+              function_response: {
+                name: 'multiply',
+                response: {
+                  output: '<system-reminder>This is a system reminder</system-reminder>20',
+                },
+                parts: [],
+              },
+            },
+          ],
+          role: 'user',
+        },
+      ]);
+    });
+  });
+
+  describe('vertexai message conversion', () => {
+    it('vertexai provider converts messages the same way', async () => {
+      const provider = createProvider({ vertexai: true });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hello!' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, 'You are helpful.', [], history);
+
+      expect(body['contents']).toEqual([{ parts: [{ text: 'Hello!' }], role: 'user' }]);
+      const config = body['config'] as Record<string, unknown>;
+      expect(config['system_instruction']).toBe('You are helpful.');
+    });
+  });
+
+  describe('generation kwargs', () => {
+    it('applies temperature and max_output_tokens', async () => {
+      const provider = createProvider().withGenerationKwargs({
+        temperature: 0.7,
+        max_output_tokens: 2048,
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const config = body['config'] as Record<string, unknown>;
+      expect(config['temperature']).toBe(0.7);
+      expect(config['max_output_tokens']).toBe(2048);
+    });
+  });
+
+  describe('tool name inference from tool_call_id (orphan tool messages)', () => {
+    // When a tool message arrives without a preceding assistant message
+    // carrying the tool_call (e.g. after history compaction), the provider
+    // falls back to parsing the name out of the tool_call_id. Google IDs
+    // produced by this provider have the shape "{tool_name}_{id_suffix}"
+    // where the suffix is a single non-underscored token, so stripping the
+    // first underscore truncates multi-word tool names such as
+    // `fetch_image_<id>` down to `fetch`.
+    function firstFunctionResponseName(history: Message[]): string | undefined {
+      const contents = messagesToGoogleGenAIContents(history);
+      for (const content of contents) {
+        for (const part of content.parts) {
+          if (part.function_response) return part.function_response.name;
+        }
+      }
+      return undefined;
+    }
+
+    it('preserves underscores in multi-word tool names like fetch_image', () => {
+      const history: Message[] = [
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: 'ok' }],
+          toolCallId: 'fetch_image_abc123',
+          toolCalls: [],
+        },
+      ];
+      expect(firstFunctionResponseName(history)).toBe('fetch_image');
+    });
+
+    it('preserves underscores in read_file_<id>', () => {
+      const history: Message[] = [
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: 'ok' }],
+          toolCallId: 'read_file_xyz',
+          toolCalls: [],
+        },
+      ];
+      expect(firstFunctionResponseName(history)).toBe('read_file');
+    });
+
+    it('handles single-word tool names with a trailing suffix', () => {
+      const history: Message[] = [
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: 'ok' }],
+          toolCallId: 'simple_abc',
+          toolCalls: [],
+        },
+      ];
+      expect(firstFunctionResponseName(history)).toBe('simple');
+    });
+
+    it('returns the whole id when there is no underscore to split on', () => {
+      const history: Message[] = [
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: 'ok' }],
+          toolCallId: 'bareid',
+          toolCalls: [],
+        },
+      ];
+      expect(firstFunctionResponseName(history)).toBe('bareid');
+    });
+  });
+
+  describe('no id in function_call or function_response', () => {
+    it('does not include id in function_call or function_response parts', () => {
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'Sure.' }],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_xyz',
+              function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '5' }],
+          toolCallId: 'call_xyz',
+          toolCalls: [],
+        },
+      ];
+
+      const contents = messagesToGoogleGenAIContents(history);
+
+      for (const content of contents) {
+        for (const part of content.parts) {
+          if (part.function_call) {
+            expect(part.function_call).not.toHaveProperty('id');
+          }
+          if (part.function_response) {
+            expect(part.function_response).not.toHaveProperty('id');
+          }
+        }
+      }
+    });
+  });
+
+  describe('with thinking', () => {
+    it('non-gemini-3 model uses thinking_budget', async () => {
+      const provider = createProvider({ model: 'gemini-2.5-flash' }).withThinking('high');
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const config = body['config'] as Record<string, unknown>;
+      expect(config['thinking_config']).toEqual({
+        include_thoughts: true,
+        thinking_budget: 32_000,
+      });
+    });
+
+    it('gemini-3 model uses thinking_level', async () => {
+      const provider = createProvider({ model: 'gemini-3-pro-preview' }).withThinking('high');
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const config = body['config'] as Record<string, unknown>;
+      expect(config['thinking_config']).toEqual({
+        include_thoughts: true,
+        thinking_level: 'HIGH',
+      });
+    });
+
+    it('thinking effort off for non-gemini-3 disables thinking', async () => {
+      const provider = createProvider({ model: 'gemini-2.5-flash' }).withThinking('off');
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const config = body['config'] as Record<string, unknown>;
+      expect(config['thinking_config']).toEqual({
+        include_thoughts: false,
+        thinking_budget: 0,
+      });
+    });
+
+    describe('Gemini 3 thinking effort mapping', () => {
+      async function captureThinkingConfig(
+        effort: 'off' | 'low' | 'medium' | 'high',
+      ): Promise<Record<string, unknown> | undefined> {
+        const provider = createProvider({ model: 'gemini-3-pro-preview' }).withThinking(effort);
+        const history: Message[] = [
+          { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+        ];
+        const body = await captureRequestBody(provider, '', [], history);
+        const config = body['config'] as Record<string, unknown>;
+        return config['thinking_config'] as Record<string, unknown> | undefined;
+      }
+
+      it('off minimizes thinking and hides thoughts (not just default config)', async () => {
+        const thinkingConfig = await captureThinkingConfig('off');
+        // Gemini 3 cannot be fully disabled, but we should request the lowest
+        // available level (MINIMAL) and suppress thought output.
+        expect(thinkingConfig).toEqual({
+          include_thoughts: false,
+          thinking_level: 'MINIMAL',
+        });
+      });
+
+      it('low maps to LOW', async () => {
+        const thinkingConfig = await captureThinkingConfig('low');
+        expect(thinkingConfig).toEqual({
+          include_thoughts: true,
+          thinking_level: 'LOW',
+        });
+      });
+
+      it('medium maps to MEDIUM (not HIGH)', async () => {
+        const thinkingConfig = await captureThinkingConfig('medium');
+        expect(thinkingConfig).toEqual({
+          include_thoughts: true,
+          thinking_level: 'MEDIUM',
+        });
+      });
+
+      it('high maps to HIGH', async () => {
+        const thinkingConfig = await captureThinkingConfig('high');
+        expect(thinkingConfig).toEqual({
+          include_thoughts: true,
+          thinking_level: 'HIGH',
+        });
+      });
+    });
+  });
+
+  describe('provider properties', () => {
+    it('has correct name and model', () => {
+      const provider = createProvider();
+      expect(provider.name).toBe('google_genai');
+      expect(provider.modelName).toBe('gemini-2.5-flash');
+    });
+
+    it('thinkingEffort is null by default', () => {
+      const provider = createProvider();
+      expect(provider.thinkingEffort).toBeNull();
+    });
+
+    it('thinkingEffort reflects budget for non-gemini-3', () => {
+      const provider = createProvider().withThinking('high');
+      expect(provider.thinkingEffort).toBe('high');
+    });
+
+    it('withThinking returns a new instance', () => {
+      const provider = createProvider();
+      const newProvider = provider.withThinking('high');
+      expect(newProvider).toBeInstanceOf(GoogleGenAIChatProvider);
+      expect(newProvider).not.toBe(provider);
+    });
+  });
+
+  describe('response parsing (non-stream)', () => {
+    it('yields text from non-stream response', async () => {
+      const provider = createProvider({ stream: false });
+      ((provider as any)._client.models as Record<string, unknown>)['generateContent'] = vi
+        .fn()
+        .mockResolvedValue(makeGenerateContentResponse());
+
+      const stream = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+
+      const parts = await collectParts(stream);
+
+      expect(parts).toEqual([{ type: 'text', text: 'Hello' }]);
+      expect(stream.usage).toEqual({
+        inputOther: 10,
+        output: 5,
+        inputCacheRead: 0,
+        inputCacheCreation: 0,
+      });
+    });
+  });
+
+  describe('streaming', () => {
+    it('defaults to stream mode', () => {
+      const provider = createProvider();
+      expect((provider as any)._stream).toBe(true);
+    });
+
+    it('can be set to non-stream mode', () => {
+      const provider = createProvider({ stream: false });
+      expect((provider as any)._stream).toBe(false);
+    });
+
+    it('calls generateContentStream when stream is true', async () => {
+      const provider = createProvider({ stream: true });
+      const mockModels = (provider as any)._client.models as Record<string, unknown>;
+
+      async function* mockStream() {
+        yield makeGenerateContentResponse();
+      }
+
+      const streamFn = vi.fn().mockImplementation(() => Promise.resolve(mockStream()));
+      const nonStreamFn = vi.fn();
+
+      mockModels['generateContentStream'] = streamFn;
+      mockModels['generateContent'] = nonStreamFn;
+
+      const result = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+      await collectParts(result);
+
+      expect(streamFn).toHaveBeenCalledOnce();
+      expect(nonStreamFn).not.toHaveBeenCalled();
+    });
+
+    it('calls generateContent when stream is false', async () => {
+      const provider = createProvider({ stream: false });
+      const mockModels = (provider as any)._client.models as Record<string, unknown>;
+
+      const streamFn = vi.fn();
+      const nonStreamFn = vi.fn().mockResolvedValue(makeGenerateContentResponse());
+
+      mockModels['generateContentStream'] = streamFn;
+      mockModels['generateContent'] = nonStreamFn;
+
+      const result = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+      await collectParts(result);
+
+      expect(nonStreamFn).toHaveBeenCalledOnce();
+      expect(streamFn).not.toHaveBeenCalled();
+    });
+
+    it('yields text chunks from stream', async () => {
+      async function* mockStream() {
+        yield { candidates: [{ content: { parts: [{ text: 'Hello' }] } }] };
+        yield { candidates: [{ content: { parts: [{ text: ' world' }] } }] };
+      }
+
+      const msg = new GoogleGenAIStreamedMessage(mockStream(), true);
+      const parts = await collectParts(msg);
+
+      expect(parts).toEqual([
+        { type: 'text', text: 'Hello' },
+        { type: 'text', text: ' world' },
+      ]);
+    });
+
+    it('yields think parts from stream', async () => {
+      async function* mockStream() {
+        yield {
+          candidates: [{ content: { parts: [{ text: 'thinking...', thought: true }] } }],
+        };
+        yield {
+          candidates: [{ content: { parts: [{ text: 'visible answer' }] } }],
+        };
+      }
+
+      const msg = new GoogleGenAIStreamedMessage(mockStream(), true);
+      const parts = await collectParts(msg);
+
+      expect(parts).toEqual([
+        { type: 'think', think: 'thinking...' },
+        { type: 'text', text: 'visible answer' },
+      ]);
+    });
+
+    it('yields function call from stream', async () => {
+      async function* mockStream() {
+        yield {
+          candidates: [
+            {
+              content: {
+                parts: [
+                  {
+                    functionCall: {
+                      name: 'add',
+                      id: 'call_1',
+                      args: { a: 2, b: 3 },
+                    },
+                  },
+                ],
+              },
+            },
+          ],
+        };
+      }
+
+      const msg = new GoogleGenAIStreamedMessage(mockStream(), true);
+      const parts = await collectParts(msg);
+
+      expect(parts).toEqual([
+        {
+          type: 'function',
+          id: 'add_call_1',
+          function: { name: 'add', arguments: '{"a":2,"b":3}' },
+        },
+      ]);
+    });
+
+    it('yields function call with thought signature from stream', async () => {
+      async function* mockStream() {
+        yield {
+          candidates: [
+            {
+              content: {
+                parts: [
+                  {
+                    functionCall: { name: 'search', id: 'fc_1', args: { q: 'test' } },
+                    thoughtSignature: 'sig_abc123',
+                  },
+                ],
+              },
+            },
+          ],
+        };
+      }
+
+      const msg = new GoogleGenAIStreamedMessage(mockStream(), true);
+      const parts = await collectParts(msg);
+
+      expect(parts).toEqual([
+        {
+          type: 'function',
+          id: 'search_fc_1',
+          function: { name: 'search', arguments: '{"q":"test"}' },
+          extras: { thought_signature_b64: 'sig_abc123' },
+        },
+      ]);
+    });
+
+    it('accumulates usage from last chunk', async () => {
+      async function* mockStream() {
+        yield { candidates: [{ content: { parts: [{ text: 'chunk1' }] } }] };
+        yield {
+          candidates: [{ content: { parts: [{ text: 'chunk2' }] } }],
+          usageMetadata: {
+            promptTokenCount: 20,
+            candidatesTokenCount: 10,
+            cachedContentTokenCount: 5,
+          },
+        };
+      }
+
+      const msg = new GoogleGenAIStreamedMessage(mockStream(), true);
+      await collectParts(msg);
+
+      expect(msg.usage).toEqual({
+        inputOther: 15,
+        output: 10,
+        inputCacheRead: 5,
+        inputCacheCreation: 0,
+      });
+    });
+
+    it('extracts responseId from stream chunk', async () => {
+      async function* mockStream() {
+        yield {
+          responseId: 'resp-abc',
+          candidates: [{ content: { parts: [{ text: 'hi' }] } }],
+        };
+      }
+
+      const msg = new GoogleGenAIStreamedMessage(mockStream(), true);
+      await collectParts(msg);
+
+      expect(msg.id).toBe('resp-abc');
+    });
+
+    it('handles multiple parts in a single stream chunk', async () => {
+      async function* mockStream() {
+        yield {
+          candidates: [
+            {
+              content: {
+                parts: [
+                  { text: 'thinking step', thought: true },
+                  { text: 'answer' },
+                  {
+                    functionCall: { name: 'calc', id: 'fc_1', args: { x: 1 } },
+                  },
+                ],
+              },
+            },
+          ],
+        };
+      }
+
+      const msg = new GoogleGenAIStreamedMessage(mockStream(), true);
+      const parts = await collectParts(msg);
+
+      expect(parts).toHaveLength(3);
+      expect(parts[0]).toEqual({ type: 'think', think: 'thinking step' });
+      expect(parts[1]).toEqual({ type: 'text', text: 'answer' });
+      expect(parts[2]).toMatchObject({
+        type: 'function',
+        function: { name: 'calc' },
+      });
+    });
+
+    it('yields unique ids for parallel function calls without id in same chunk', async () => {
+      async function* mockStream() {
+        yield {
+          candidates: [
+            {
+              content: {
+                parts: [
+                  {
+                    functionCall: {
+                      name: 'read_file',
+                      args: { path: '/a.txt' },
+                    },
+                  },
+                  {
+                    functionCall: {
+                      name: 'read_file',
+                      args: { path: '/b.txt' },
+                    },
+                  },
+                ],
+              },
+            },
+          ],
+        };
+      }
+
+      const msg = new GoogleGenAIStreamedMessage(mockStream(), true);
+      const parts = await collectParts(msg);
+
+      expect(parts).toHaveLength(2);
+      const ids = parts.map((p) => (p as ToolCall).id);
+      // The two tool calls must have distinct IDs
+      expect(ids[0]).not.toBe(ids[1]);
+    });
+
+    it('handles empty stream gracefully', async () => {
+      async function* mockStream() {
+        // no chunks
+      }
+
+      const msg = new GoogleGenAIStreamedMessage(mockStream(), true);
+      const parts = await collectParts(msg);
+
+      expect(parts).toEqual([]);
+      expect(msg.id).toBeNull();
+      expect(msg.usage).toBeNull();
+    });
+
+    it('handles chunk with no candidates', async () => {
+      async function* mockStream() {
+        yield { usageMetadata: { promptTokenCount: 5, candidatesTokenCount: 0 } };
+        yield { candidates: [{ content: { parts: [{ text: 'ok' }] } }] };
+      }
+
+      const msg = new GoogleGenAIStreamedMessage(mockStream(), true);
+      const parts = await collectParts(msg);
+
+      expect(parts).toEqual([{ type: 'text', text: 'ok' }]);
+    });
+
+    it('end-to-end: provider.generate returns streaming response', async () => {
+      const provider = createProvider({ stream: true });
+      const mockModels = (provider as any)._client.models as Record<string, unknown>;
+
+      async function* mockStream() {
+        yield {
+          responseId: 'resp-e2e',
+          candidates: [{ content: { parts: [{ text: 'Hello' }] } }],
+        };
+        yield {
+          candidates: [{ content: { parts: [{ text: ' World' }] } }],
+          usageMetadata: {
+            promptTokenCount: 8,
+            candidatesTokenCount: 4,
+          },
+        };
+      }
+
+      mockModels['generateContentStream'] = vi
+        .fn()
+        .mockImplementation(() => Promise.resolve(mockStream()));
+
+      const result = await provider.generate(
+        'system',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+
+      const parts = await collectParts(result);
+
+      expect(parts).toEqual([
+        { type: 'text', text: 'Hello' },
+        { type: 'text', text: ' World' },
+      ]);
+      expect(result.id).toBe('resp-e2e');
+      expect(result.usage).toEqual({
+        inputOther: 8,
+        output: 4,
+        inputCacheRead: 0,
+        inputCacheCreation: 0,
+      });
+    });
+  });
+
+  describe('tool result validation for assistant tool calls', () => {
+    it('throws on unexpected extra tool results', () => {
+      const messages: Message[] = [
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'Running tools' }],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_known',
+              function: { name: 'add', arguments: '{"a":1,"b":2}' },
+            },
+          ],
+        },
+        // A tool result that matches the assistant's known tool call
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '3' }],
+          toolCallId: 'call_known',
+          toolCalls: [],
+        },
+        // An "extra" tool result whose id is NOT in expectedToolCallIds.
+        // Previously dropped by the buggy be-tolerant branch; must now be
+        // preserved.
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '42' }],
+          toolCallId: 'call_extra_unknown',
+          toolCalls: [],
+        },
+      ];
+
+      expect(() => messagesToGoogleGenAIContents(messages)).toThrow(/Unexpected tool responses/);
+    });
+
+    it('throws on missing tool results', () => {
+      const messages: Message[] = [
+        {
+          role: 'assistant',
+          content: [],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_a',
+              function: { name: 'tool_a', arguments: '{}' },
+            },
+            {
+              type: 'function',
+              id: 'call_b',
+              function: { name: 'tool_b', arguments: '{}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: 'A' }],
+          toolCallId: 'call_a',
+          toolCalls: [],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: 'orphaned' }],
+          toolCallId: 'call_missing_elsewhere',
+          toolCalls: [],
+        },
+      ];
+
+      expect(() => messagesToGoogleGenAIContents(messages)).toThrow(/Missing tool responses/);
+    });
+
+    it('throws on duplicate tool results', () => {
+      const messages: Message[] = [
+        {
+          role: 'assistant',
+          content: [],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_a',
+              function: { name: 'tool_a', arguments: '{}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: 'A1' }],
+          toolCallId: 'call_a',
+          toolCalls: [],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: 'A2' }],
+          toolCallId: 'call_a',
+          toolCalls: [],
+        },
+      ];
+
+      expect(() => messagesToGoogleGenAIContents(messages)).toThrow(/Duplicate tool response/);
+    });
+  });
+
+  describe('abort signal handling', () => {
+    it('throws AbortError synchronously when signal is already aborted on entry', async () => {
+      const provider = createProvider({ stream: true });
+      const mockModels = (provider as any)._client.models as Record<string, unknown>;
+
+      // If the provider forwards to the SDK at all despite a pre-aborted
+      // signal, this spy will flag the regression.
+      const streamFn = vi.fn();
+      mockModels['generateContentStream'] = streamFn;
+
+      const controller = new AbortController();
+      controller.abort();
+
+      await expect(
+        provider.generate(
+          '',
+          [],
+          [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+          { signal: controller.signal },
+        ),
+      ).rejects.toMatchObject({ name: 'AbortError' });
+
+      expect(streamFn).not.toHaveBeenCalled();
+    });
+
+    it('rejects promptly if the signal aborts before the first stream response resolves', async () => {
+      const provider = createProvider({ stream: true });
+      const mockModels = (provider as unknown as { _client: { models: Record<string, unknown> } })
+        ._client.models;
+      const controller = new AbortController();
+
+      mockModels['generateContentStream'] = vi.fn().mockImplementation(
+        () =>
+          new Promise<AsyncGenerator>(() => {
+            // Intentionally never resolves: reproduces the "stuck before first
+            // chunk" window where cancellation must still win the race.
+          }),
+      );
+
+      const pending = provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+        { signal: controller.signal },
+      );
+
+      controller.abort();
+
+      const result = await Promise.race([
+        pending.then(
+          () => ({ settled: 'resolved' as const }),
+          (error: unknown) => ({ settled: 'rejected' as const, error }),
+        ),
+        new Promise<{ settled: 'timeout' }>((resolve) =>
+          setTimeout(() => {
+            resolve({ settled: 'timeout' });
+          }, 100),
+        ),
+      ]);
+
+      expect(result.settled).toBe('rejected');
+      if (result.settled === 'rejected') {
+        expect(result.error).toBeInstanceOf(DOMException);
+        expect((result.error as DOMException).name).toBe('AbortError');
+      }
+    });
+
+    it('throws AbortError at the next chunk boundary when aborted mid-stream', async () => {
+      const provider = createProvider({ stream: true });
+      const mockModels = (provider as any)._client.models as Record<string, unknown>;
+      const controller = new AbortController();
+
+      async function* mockStream() {
+        yield { candidates: [{ content: { parts: [{ text: 'chunk-1' }] } }] };
+        // Simulate the caller aborting between chunks
+        controller.abort();
+        yield { candidates: [{ content: { parts: [{ text: 'chunk-2' }] } }] };
+      }
+
+      mockModels['generateContentStream'] = vi
+        .fn()
+        .mockImplementation(() => Promise.resolve(mockStream()));
+
+      const result = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+        { signal: controller.signal },
+      );
+
+      const received: StreamedMessagePart[] = [];
+      let caught: unknown;
+      try {
+        for await (const part of result) {
+          received.push(part);
+        }
+      } catch (error) {
+        caught = error;
+      }
+
+      // The first chunk should have been yielded before the abort triggered.
+      expect(received).toEqual([{ type: 'text', text: 'chunk-1' }]);
+      // The post-abort chunk must never be observed — the second loop
+      // iteration checks the signal and throws AbortError.
+      expect(caught).toBeInstanceOf(DOMException);
+      expect((caught as DOMException).name).toBe('AbortError');
+    });
+
+    it('non-stream path throws AbortError if signal fires before iteration', async () => {
+      const provider = createProvider({ stream: false });
+      const mockModels = (provider as any)._client.models as Record<string, unknown>;
+
+      mockModels['generateContent'] = vi.fn().mockResolvedValue({
+        candidates: [{ content: { parts: [{ text: 'done' }] } }],
+        usageMetadata: { promptTokenCount: 1, candidatesTokenCount: 1 },
+      });
+
+      const controller = new AbortController();
+      const result = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+        { signal: controller.signal },
+      );
+
+      // Abort AFTER generate() resolves but BEFORE we drain the iterator.
+      controller.abort();
+
+      let caught: unknown;
+      try {
+        for await (const _ of result) {
+          // drain — but the first pre-check inside the generator should fire
+        }
+      } catch (error) {
+        caught = error;
+      }
+
+      expect(caught).toBeInstanceOf(DOMException);
+      expect((caught as DOMException).name).toBe('AbortError');
+    });
+  });
+});
+
+describe('convertGoogleGenAIError (unit)', () => {
+  it('maps a network-keyword Error to APIConnectionError', () => {
+    const result = convertGoogleGenAIError(new Error('network connection lost'));
+    expect(result).toBeInstanceOf(APIConnectionError);
+  });
+
+  it('maps a "fetch failed" TypeError to APIConnectionError', () => {
+    const result = convertGoogleGenAIError(new TypeError('fetch failed'));
+    expect(result).toBeInstanceOf(APIConnectionError);
+  });
+
+  it('maps a timeout-keyword Error to APITimeoutError (priority over network)', () => {
+    const result = convertGoogleGenAIError(new Error('connection timed out'));
+    expect(result).toBeInstanceOf(APITimeoutError);
+  });
+
+  it('extracts numeric code property as APIStatusError', () => {
+    const error = new Error('api failure');
+    (error as Error & { code: number }).code = 503;
+    const result = convertGoogleGenAIError(error);
+    expect(result).toBeInstanceOf(APIStatusError);
+    expect((result as APIStatusError).statusCode).toBe(503);
+  });
+
+  it('normalizes numeric context overflow errors', () => {
+    const error = new Error(
+      'input token count 131072 exceeds the maximum number of tokens allowed',
+    );
+    (error as Error & { code: number }).code = 422;
+    const result = convertGoogleGenAIError(error);
+    expect(result).toBeInstanceOf(APIContextOverflowError);
+    expect((result as APIContextOverflowError).statusCode).toBe(422);
+  });
+
+  it('falls through to ChatProviderError for plain Error without keywords or code', () => {
+    const result = convertGoogleGenAIError(new Error('something obscure'));
+    expect(result.constructor).toBe(ChatProviderError);
+    expect(result.message).toContain('something obscure');
+  });
+
+  it('handles non-Error values by stringifying them', () => {
+    const result = convertGoogleGenAIError('a bare string failure');
+    expect(result.constructor).toBe(ChatProviderError);
+    expect(result.message).toContain('a bare string failure');
+  });
+});
+
+describe('messagesToGoogleGenAIContents - error branches', () => {
+  it('throws when toolCall arguments is a JSON array (not object)', () => {
+    const messages: Message[] = [
+      {
+        role: 'assistant',
+        content: [{ type: 'text', text: 'hi' }],
+        toolCalls: [
+          {
+            type: 'function',
+            id: 'tc_arr',
+            function: { name: 'foo', arguments: '[1,2,3]' },
+          },
+        ],
+      },
+    ];
+    expect(() => messagesToGoogleGenAIContents(messages)).toThrow(
+      /Tool call arguments must be a JSON object/,
+    );
+  });
+
+  it('throws when tool response is missing toolCallId', () => {
+    const messages: Message[] = [
+      {
+        role: 'assistant',
+        content: [],
+        toolCalls: [
+          {
+            type: 'function',
+            id: 'tc_1',
+            function: { name: 'foo', arguments: '{}' },
+          },
+        ],
+      },
+      {
+        role: 'tool',
+        content: [{ type: 'text', text: 'result' }],
+        toolCalls: [],
+        // toolCallId missing!
+      },
+    ];
+    expect(() => messagesToGoogleGenAIContents(messages)).toThrow(
+      /Tool response is missing `toolCallId`/,
+    );
+  });
+
+  it('throws on duplicate tool responses for same id', () => {
+    const messages: Message[] = [
+      {
+        role: 'assistant',
+        content: [],
+        toolCalls: [
+          {
+            type: 'function',
+            id: 'tc_dup',
+            function: { name: 'foo', arguments: '{}' },
+          },
+        ],
+      },
+      {
+        role: 'tool',
+        content: [{ type: 'text', text: 'r1' }],
+        toolCallId: 'tc_dup',
+        toolCalls: [],
+      },
+      {
+        role: 'tool',
+        content: [{ type: 'text', text: 'r2' }],
+        toolCallId: 'tc_dup',
+        toolCalls: [],
+      },
+    ];
+    expect(() => messagesToGoogleGenAIContents(messages)).toThrow(/Duplicate tool response/);
+  });
+
+  it('throws when expected tool response is missing', () => {
+    const messages: Message[] = [
+      {
+        role: 'assistant',
+        content: [],
+        toolCalls: [
+          {
+            type: 'function',
+            id: 'tc_expected',
+            function: { name: 'foo', arguments: '{}' },
+          },
+          {
+            type: 'function',
+            id: 'tc_missing',
+            function: { name: 'bar', arguments: '{}' },
+          },
+        ],
+      },
+      {
+        role: 'tool',
+        content: [{ type: 'text', text: 'only one' }],
+        toolCallId: 'tc_expected',
+        toolCalls: [],
+      },
+    ];
+    expect(() => messagesToGoogleGenAIContents(messages)).toThrow(/Missing tool responses for ids/);
+  });
+
+  it('throws on unexpected tool response for unknown id', () => {
+    const messages: Message[] = [
+      {
+        role: 'assistant',
+        content: [],
+        toolCalls: [
+          {
+            type: 'function',
+            id: 'tc_known',
+            function: { name: 'foo', arguments: '{}' },
+          },
+        ],
+      },
+      {
+        role: 'tool',
+        content: [{ type: 'text', text: 'r' }],
+        toolCallId: 'tc_known',
+        toolCalls: [],
+      },
+      {
+        role: 'tool',
+        content: [{ type: 'text', text: 'stray' }],
+        toolCallId: 'tc_unexpected',
+        toolCalls: [],
+      },
+    ];
+    expect(() => messagesToGoogleGenAIContents(messages)).toThrow(/Unexpected tool responses/);
+  });
+});
+
+describe('messagesToGoogleGenAIContents - extra branches', () => {
+  it('throws when assistant tool_call has malformed JSON arguments', () => {
+    const messages: Message[] = [
+      {
+        role: 'assistant',
+        content: [{ type: 'text', text: 'hi' }],
+        toolCalls: [
+          {
+            type: 'function',
+            id: 'tc_bad',
+            function: { name: 'foo', arguments: 'not valid {json' },
+          },
+        ],
+      },
+    ];
+    // Provider rejects malformed JSON arguments rather than silently sending
+    // garbage to Gemini.
+    expect(() => messagesToGoogleGenAIContents(messages)).toThrow(/Tool call arguments/);
+  });
+
+  it('media URL with png extension picks image/png mime type', async () => {
+    const provider = createProvider();
+    const history: Message[] = [
+      {
+        role: 'user',
+        content: [{ type: 'image_url', imageUrl: { url: 'https://example.com/photo.png' } }],
+        toolCalls: [],
+      },
+    ];
+    const body = await captureRequestBody(provider, '', [], history);
+    const contents = body['contents'] as Array<{ parts: Array<Record<string, unknown>> }>;
+    const fileData = contents[0]!.parts[0]!['fileData'] as { mimeType: string };
+    expect(fileData.mimeType).toBe('image/png');
+  });
+
+  it('media URL with jpg extension picks image/jpeg mime type', async () => {
+    const provider = createProvider();
+    const history: Message[] = [
+      {
+        role: 'user',
+        content: [{ type: 'image_url', imageUrl: { url: 'https://example.com/photo.jpg' } }],
+        toolCalls: [],
+      },
+    ];
+    const body = await captureRequestBody(provider, '', [], history);
+    const contents = body['contents'] as Array<{ parts: Array<Record<string, unknown>> }>;
+    const fileData = contents[0]!.parts[0]!['fileData'] as { mimeType: string };
+    expect(fileData.mimeType).toBe('image/jpeg');
+  });
+
+  it('media URL with mp3 extension picks audio/mpeg mime type', async () => {
+    const provider = createProvider();
+    const history: Message[] = [
+      {
+        role: 'user',
+        content: [{ type: 'audio_url', audioUrl: { url: 'https://example.com/song.mp3' } }],
+        toolCalls: [],
+      },
+    ];
+    const body = await captureRequestBody(provider, '', [], history);
+    const contents = body['contents'] as Array<{ parts: Array<Record<string, unknown>> }>;
+    const fileData = contents[0]!.parts[0]!['fileData'] as { mimeType: string };
+    expect(fileData.mimeType).toBe('audio/mpeg');
+  });
+
+  it('data: URL without comma falls back to file data with full URL', async () => {
+    const provider = createProvider();
+    const history: Message[] = [
+      {
+        role: 'user',
+        content: [{ type: 'image_url', imageUrl: { url: 'data:image/png' } }],
+        toolCalls: [],
+      },
+    ];
+    const body = await captureRequestBody(provider, '', [], history);
+    const contents = body['contents'] as Array<{ parts: Array<Record<string, unknown>> }>;
+    expect(contents[0]!.parts[0]).toMatchObject({
+      fileData: { fileUri: 'data:image/png' },
+    });
+  });
+});
diff --git a/packages/kosong/test/kimi-files.test.ts b/packages/kosong/test/kimi-files.test.ts
new file mode 100644
index 000000000..ede39f74a
--- /dev/null
+++ b/packages/kosong/test/kimi-files.test.ts
@@ -0,0 +1,200 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { KimiChatProvider } from '#/providers/kimi';
+import { KimiFiles } from '#/providers/kimi-files';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+function createProvider(): KimiChatProvider {
+  return new KimiChatProvider({
+    model: 'kimi-k2-turbo-preview',
+    apiKey: 'test-key',
+  });
+}
+
+describe('KimiFiles', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kimi-files-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('exposure on KimiChatProvider', () => {
+    it('exposes files property returning a KimiFiles instance', () => {
+      const provider = createProvider();
+      const files = provider.files;
+      expect(files).toBeInstanceOf(KimiFiles);
+      expect(typeof files.uploadVideo).toBe('function');
+    });
+
+    it('memoizes the files property', () => {
+      const provider = createProvider();
+      const a = provider.files;
+      const b = provider.files;
+      expect(a).toBe(b);
+    });
+  });
+
+  describe('uploadVideo from a file path', () => {
+    it('uploads the file and returns a VideoURLPart', async () => {
+      const provider = createProvider();
+
+      const videoPath = path.join(tmpDir, 'video.mp4');
+      fs.writeFileSync(videoPath, Buffer.from([0, 1, 2, 3, 4]));
+
+      let captured: unknown;
+      const mockCreate = vi.fn().mockImplementation((params: unknown) => {
+        captured = params;
+        return Promise.resolve({
+          id: 'file_abc123',
+          object: 'file',
+          bytes: 5,
+          created_at: 1,
+          filename: 'video.mp4',
+          purpose: 'video',
+        });
+      });
+      provider.files['_client']!.files.create = mockCreate as never;
+
+      const part = await provider.files.uploadVideo(videoPath);
+
+      expect(mockCreate).toHaveBeenCalledOnce();
+      const call = captured as { file: File; purpose: string };
+      expect(call.purpose).toBe('video');
+      expect(call.file).toBeInstanceOf(File);
+
+      expect(part.type).toBe('video_url');
+      expect(part.videoUrl.url).toBe('ms://file_abc123');
+      expect(part.videoUrl.id).toBe('file_abc123');
+    });
+
+    it('throws when the file does not exist', async () => {
+      const provider = createProvider();
+      const missing = path.join(tmpDir, 'does-not-exist.mp4');
+      await expect(provider.files.uploadVideo(missing)).rejects.toThrow();
+    });
+
+    it('rejects a non-video file path (e.g. .txt)', async () => {
+      const provider = createProvider();
+      const notVideo = path.join(tmpDir, 'note.txt');
+      fs.writeFileSync(notVideo, 'hello');
+
+      const mockCreate = vi.fn();
+      provider.files['_client']!.files.create = mockCreate as never;
+
+      await expect(provider.files.uploadVideo(notVideo)).rejects.toThrow(/video/i);
+      expect(mockCreate).not.toHaveBeenCalled();
+    });
+
+    it('rejects a file with no extension', async () => {
+      const provider = createProvider();
+      const noExt = path.join(tmpDir, 'mystery');
+      fs.writeFileSync(noExt, 'hello');
+
+      const mockCreate = vi.fn();
+      provider.files['_client']!.files.create = mockCreate as never;
+
+      await expect(provider.files.uploadVideo(noExt)).rejects.toThrow(/video/i);
+      expect(mockCreate).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      ['clip.mp4', 'video/mp4'],
+      ['clip.webm', 'video/webm'],
+      ['clip.mov', 'video/quicktime'],
+    ])('accepts %s and infers %s', async (filename, expectedMime) => {
+      const provider = createProvider();
+      const videoPath = path.join(tmpDir, filename);
+      fs.writeFileSync(videoPath, Buffer.from([0, 1, 2, 3]));
+
+      let captured: unknown;
+      provider.files['_client']!.files.create = vi.fn().mockImplementation((params: unknown) => {
+        captured = params;
+        return Promise.resolve({
+          id: 'file_ext_ok',
+          object: 'file',
+          bytes: 4,
+          created_at: 1,
+          filename,
+          purpose: 'video',
+        });
+      }) as never;
+
+      const part = await provider.files.uploadVideo(videoPath);
+      expect(part.videoUrl.id).toBe('file_ext_ok');
+      const call = captured as { file: File };
+      expect(call.file.type).toBe(expectedMime);
+    });
+  });
+
+  describe('uploadVideo from a Buffer', () => {
+    it('passes request-scoped auth to the client factory', async () => {
+      const auths: unknown[] = [];
+      const client = {
+        files: {
+          create: vi.fn().mockResolvedValue({ id: 'file_auth' }),
+        },
+      };
+      const files = new KimiFiles({
+        baseUrl: 'https://api.example/v1',
+        clientFactory: (auth) => {
+          auths.push(auth);
+          return client as never;
+        },
+      });
+
+      await files.uploadVideo(
+        { data: Buffer.from([1, 2, 3]), mimeType: 'video/mp4' },
+        { auth: { apiKey: 'request-token' } },
+      );
+
+      expect(auths).toEqual([{ apiKey: 'request-token' }]);
+      expect(client.files.create).toHaveBeenCalledOnce();
+    });
+
+    it('uploads raw bytes and returns a VideoURLPart', async () => {
+      const provider = createProvider();
+      const bytes = Buffer.from([10, 20, 30, 40]);
+
+      let captured: unknown;
+      provider.files['_client']!.files.create = vi.fn().mockImplementation((params: unknown) => {
+        captured = params;
+        return Promise.resolve({
+          id: 'file_buf_456',
+          object: 'file',
+          bytes: bytes.length,
+          created_at: 1,
+          filename: 'upload.mp4',
+          purpose: 'video',
+        });
+      }) as never;
+
+      const part = await provider.files.uploadVideo({
+        data: bytes,
+        mimeType: 'video/mp4',
+      });
+
+      const call = captured as { file: File; purpose: string };
+      expect(call.purpose).toBe('video');
+      expect(call.file).toBeInstanceOf(File);
+      expect(part.type).toBe('video_url');
+      expect(part.videoUrl.url).toBe('ms://file_buf_456');
+      expect(part.videoUrl.id).toBe('file_buf_456');
+    });
+
+    it('rejects a non-video mime type', async () => {
+      const provider = createProvider();
+      await expect(
+        provider.files.uploadVideo({
+          data: Buffer.from([1, 2, 3]),
+          mimeType: 'image/png',
+        }),
+      ).rejects.toThrow(/video/i);
+    });
+  });
+});
diff --git a/packages/kosong/test/kimi.test.ts b/packages/kosong/test/kimi.test.ts
new file mode 100644
index 000000000..9c5ea952d
--- /dev/null
+++ b/packages/kosong/test/kimi.test.ts
@@ -0,0 +1,1469 @@
+import { generate } from '#/generate';
+import type { ContentPart, Message, ToolCall } from '#/message';
+import { extractUsageFromChunk, KimiChatProvider } from '#/providers/kimi';
+import { extractUsage } from '#/providers/openai-common';
+import type { Tool } from '#/tool';
+import { describe, it, expect, vi } from 'vitest';
+
+function makeChatCompletionResponse(model: string = 'test-model') {
+  return {
+    id: 'chatcmpl-test123',
+    object: 'chat.completion',
+    created: 1234567890,
+    model,
+    choices: [
+      {
+        index: 0,
+        message: { role: 'assistant', content: 'Hello' },
+        finish_reason: 'stop',
+      },
+    ],
+    usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+  };
+}
+
+function createProvider(stream: boolean = false): KimiChatProvider {
+  return new KimiChatProvider({
+    model: 'kimi-k2-turbo-preview',
+    apiKey: 'test-key',
+    stream,
+  });
+}
+
+type KimiGenerationState = {
+  max_tokens?: number | undefined;
+  temperature?: number | undefined;
+  reasoning_effort?: string | undefined;
+  prompt_cache_key?: string | undefined;
+  extra_body?: Record<string, unknown> | undefined;
+};
+
+function getGenerationState(provider: KimiChatProvider): KimiGenerationState {
+  return Reflect.get(provider, '_generationKwargs') as KimiGenerationState;
+}
+
+/** Capture the request body sent to OpenAI by mocking the client. */
+async function captureRequestBody(
+  provider: KimiChatProvider,
+  systemPrompt: string,
+  tools: Tool[],
+  history: Message[],
+): Promise<Record<string, unknown>> {
+  let capturedBody: Record<string, unknown> | undefined;
+
+  (provider as any)._client.chat.completions.create = vi
+    .fn()
+    .mockImplementation((params: unknown) => {
+      capturedBody = params as Record<string, unknown>;
+      return Promise.resolve(makeChatCompletionResponse('kimi-k2'));
+    });
+
+  const stream = await provider.generate(systemPrompt, tools, history);
+  for await (const part of stream) {
+    void part;
+  }
+
+  if (capturedBody === undefined) {
+    throw new Error('Expected provider.generate() to call chat.completions.create');
+  }
+  return capturedBody;
+}
+
+const ADD_TOOL: Tool = {
+  name: 'add',
+  description: 'Add two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+const MUL_TOOL: Tool = {
+  name: 'multiply',
+  description: 'Multiply two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+const BUILTIN_TOOL: Tool = {
+  name: '$web_search',
+  description: 'Search the web',
+  parameters: { type: 'object', properties: {} },
+};
+
+const JETBRAINS_ENUM_ONLY_TOOL: Tool = {
+  name: 'replace_text',
+  description: 'Replace text in a file.',
+  parameters: {
+    type: 'object',
+    properties: {
+      truncateMode: { enum: ['none', 'start', 'end'] },
+      startLine: { minimum: 1 },
+      externalHint: { description: 'Optional vendor-specific hint.' },
+      replacement: { type: 'string' },
+    },
+    required: ['replacement'],
+  },
+};
+
+const REF_ENUM_ONLY_TOOL: Tool = {
+  name: 'choose_mode',
+  description: 'Choose a mode.',
+  parameters: {
+    type: 'object',
+    properties: {
+      mode: { $ref: '#/definitions/Mode' },
+      tuple: {
+        prefixItems: [{ enum: ['left', 'right'] }],
+      },
+    },
+    definitions: {
+      Mode: { enum: ['fast', 'safe'] },
+    },
+  },
+};
+
+describe('KimiChatProvider', () => {
+  describe('message conversion', () => {
+    it('simple user message with system prompt', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hello!' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, 'You are helpful.', [], history);
+
+      expect(body['messages']).toEqual([
+        { role: 'system', content: 'You are helpful.' },
+        { role: 'user', content: 'Hello!' },
+      ]);
+    });
+
+    it('multi-turn conversation', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        { role: 'assistant', content: [{ type: 'text', text: '2+2 equals 4.' }], toolCalls: [] },
+        { role: 'user', content: [{ type: 'text', text: 'And 3+3?' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['messages']).toEqual([
+        { role: 'user', content: 'What is 2+2?' },
+        { role: 'assistant', content: '2+2 equals 4.' },
+        { role: 'user', content: 'And 3+3?' },
+      ]);
+    });
+
+    it('multi-turn with system prompt', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        { role: 'assistant', content: [{ type: 'text', text: '2+2 equals 4.' }], toolCalls: [] },
+        { role: 'user', content: [{ type: 'text', text: 'And 3+3?' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, 'You are a math tutor.', [], history);
+
+      expect(body['messages']).toEqual([
+        { role: 'system', content: 'You are a math tutor.' },
+        { role: 'user', content: 'What is 2+2?' },
+        { role: 'assistant', content: '2+2 equals 4.' },
+        { role: 'user', content: 'And 3+3?' },
+      ]);
+    });
+
+    it('image url content', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: "What's in this image?" },
+            { type: 'image_url', imageUrl: { url: 'https://example.com/image.png' } },
+          ] satisfies ContentPart[],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['messages']).toEqual([
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: "What's in this image?" },
+            { type: 'image_url', image_url: { url: 'https://example.com/image.png' } },
+          ],
+        },
+      ]);
+    });
+
+    it('tool definitions', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL, MUL_TOOL], history);
+
+      expect(body['tools']).toEqual([
+        {
+          type: 'function',
+          function: {
+            name: 'add',
+            description: 'Add two integers.',
+            parameters: {
+              type: 'object',
+              properties: {
+                a: { type: 'integer', description: 'First number' },
+                b: { type: 'integer', description: 'Second number' },
+              },
+              required: ['a', 'b'],
+            },
+          },
+        },
+        {
+          type: 'function',
+          function: {
+            name: 'multiply',
+            description: 'Multiply two integers.',
+            parameters: {
+              type: 'object',
+              properties: {
+                a: { type: 'integer', description: 'First number' },
+                b: { type: 'integer', description: 'Second number' },
+              },
+              required: ['a', 'b'],
+            },
+          },
+        },
+      ]);
+    });
+
+    it('adds Kimi-only types to JetBrains-like enum-only tool parameters without mutation', async () => {
+      const provider = createProvider();
+      const originalParameters = structuredClone(JETBRAINS_ENUM_ONLY_TOOL.parameters);
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Replace the selected range' }],
+          toolCalls: [],
+        },
+      ];
+
+      const body = await captureRequestBody(provider, '', [JETBRAINS_ENUM_ONLY_TOOL], history);
+
+      expect(body['tools']).toEqual([
+        {
+          type: 'function',
+          function: {
+            name: 'replace_text',
+            description: 'Replace text in a file.',
+            parameters: {
+              type: 'object',
+              properties: {
+                truncateMode: { enum: ['none', 'start', 'end'], type: 'string' },
+                startLine: { minimum: 1, type: 'number' },
+                externalHint: { description: 'Optional vendor-specific hint.', type: 'string' },
+                replacement: { type: 'string' },
+              },
+              required: ['replacement'],
+            },
+          },
+        },
+      ]);
+      expect(JETBRAINS_ENUM_ONLY_TOOL.parameters).toEqual(originalParameters);
+    });
+
+    it('dereferences draft-7 definitions and normalizes referenced enum-only schemas for Kimi', async () => {
+      const provider = createProvider();
+      const originalParameters = structuredClone(REF_ENUM_ONLY_TOOL.parameters);
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Choose fast mode' }],
+          toolCalls: [],
+        },
+      ];
+
+      const body = await captureRequestBody(provider, '', [REF_ENUM_ONLY_TOOL], history);
+
+      expect(body['tools']).toEqual([
+        {
+          type: 'function',
+          function: {
+            name: 'choose_mode',
+            description: 'Choose a mode.',
+            parameters: {
+              type: 'object',
+              properties: {
+                mode: { enum: ['fast', 'safe'], type: 'string' },
+                tuple: {
+                  type: 'array',
+                  prefixItems: [{ enum: ['left', 'right'], type: 'string' }],
+                },
+              },
+            },
+          },
+        },
+      ]);
+      expect(REF_ENUM_ONLY_TOOL.parameters).toEqual(originalParameters);
+    });
+
+    it('tool call and tool result', async () => {
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_abc123',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll add those numbers for you." }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '5' }],
+          toolCallId: 'call_abc123',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['messages']).toEqual([
+        { role: 'user', content: 'Add 2 and 3' },
+        {
+          role: 'assistant',
+          content: "I'll add those numbers for you.",
+          tool_calls: [
+            {
+              type: 'function',
+              id: 'call_abc123',
+              function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+            },
+          ],
+        },
+        { role: 'tool', content: '5', tool_call_id: 'call_abc123' },
+      ]);
+    });
+
+    it('tool call with image result', async () => {
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_abc123',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll add those numbers for you." }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: '5' },
+            { type: 'image_url', imageUrl: { url: 'https://example.com/image.png' } },
+          ] satisfies ContentPart[],
+          toolCallId: 'call_abc123',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect((body['messages'] as unknown[])[2]).toEqual({
+        role: 'tool',
+        content: [
+          { type: 'text', text: '5' },
+          { type: 'image_url', image_url: { url: 'https://example.com/image.png' } },
+        ],
+        tool_call_id: 'call_abc123',
+      });
+    });
+
+    it('parallel tool calls', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Calculate 2+3 and 4*5' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll calculate both." }],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_add',
+              function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+            },
+            {
+              type: 'function',
+              id: 'call_mul',
+              function: { name: 'multiply', arguments: '{"a": 4, "b": 5}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: '<system-reminder>This is a system reminder</system-reminder>' },
+            { type: 'text', text: '5' },
+          ],
+          toolCallId: 'call_add',
+          toolCalls: [],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: '<system-reminder>This is a system reminder</system-reminder>' },
+            { type: 'text', text: '20' },
+          ],
+          toolCallId: 'call_mul',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL, MUL_TOOL], history);
+
+      // Snapshot of the expected wire format:
+      // - 4 messages in order
+      // - user / assistant use compressed string content
+      // - both tool messages preserve multi-part content arrays
+      expect(body['messages']).toEqual([
+        { role: 'user', content: 'Calculate 2+3 and 4*5' },
+        {
+          role: 'assistant',
+          content: "I'll calculate both.",
+          tool_calls: [
+            {
+              type: 'function',
+              id: 'call_add',
+              function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+            },
+            {
+              type: 'function',
+              id: 'call_mul',
+              function: { name: 'multiply', arguments: '{"a": 4, "b": 5}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          content: [
+            {
+              type: 'text',
+              text: '<system-reminder>This is a system reminder</system-reminder>',
+            },
+            { type: 'text', text: '5' },
+          ],
+          tool_call_id: 'call_add',
+        },
+        {
+          role: 'tool',
+          content: [
+            {
+              type: 'text',
+              text: '<system-reminder>This is a system reminder</system-reminder>',
+            },
+            { type: 'text', text: '20' },
+          ],
+          tool_call_id: 'call_mul',
+        },
+      ]);
+      expect(body['tools']).toHaveLength(2);
+    });
+
+    it('builtin tool ($web_search)', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Search for something' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [BUILTIN_TOOL], history);
+
+      expect(body['tools']).toEqual([
+        {
+          type: 'builtin_function',
+          function: { name: '$web_search' },
+        },
+      ]);
+    });
+
+    it('assistant with reasoning content', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'think', think: 'Let me think...' },
+            { type: 'text', text: 'The answer is 4.' },
+          ],
+          toolCalls: [],
+        },
+        { role: 'user', content: [{ type: 'text', text: 'Thanks!' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      // Snapshot of the expected wire format.
+      // Kimi injects ThinkPart as `reasoning_content` field on the
+      // assistant message (Moonshot API extension).
+      expect(body['messages']).toEqual([
+        { role: 'user', content: 'What is 2+2?' },
+        {
+          role: 'assistant',
+          content: 'The answer is 4.',
+          reasoning_content: 'Let me think...',
+        },
+        { role: 'user', content: 'Thanks!' },
+      ]);
+    });
+  });
+
+  describe('generation kwargs', () => {
+    it('applies temperature and normalizes legacy max_tokens to max_completion_tokens', async () => {
+      const provider = createProvider().withGenerationKwargs({
+        temperature: 0.7,
+        max_tokens: 2048,
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['temperature']).toBe(0.7);
+      // `max_tokens` is the legacy alias; the provider rewrites it on the wire
+      // so reasoning models do not interpret it as a thinking-budget cap.
+      expect(body['max_completion_tokens']).toBe(2048);
+      expect(body['max_tokens']).toBeUndefined();
+    });
+
+    it('sends no completion-token cap by default — upstream is responsible for clamping', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['max_tokens']).toBeUndefined();
+      expect(body['max_completion_tokens']).toBeUndefined();
+    });
+
+    it('forwards max_completion_tokens verbatim', async () => {
+      const provider = createProvider().withGenerationKwargs({
+        max_completion_tokens: 2048,
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['max_completion_tokens']).toBe(2048);
+      expect(body['max_tokens']).toBeUndefined();
+    });
+
+    it('prefers max_completion_tokens when both fields are set', async () => {
+      const provider = createProvider().withGenerationKwargs({
+        max_completion_tokens: 2048,
+        max_tokens: 4096,
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['max_completion_tokens']).toBe(2048);
+      expect(body['max_tokens']).toBeUndefined();
+    });
+
+    it('withMaxCompletionTokens sets max_completion_tokens on the cloned provider', async () => {
+      const provider = createProvider().withMaxCompletionTokens(1024);
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['max_completion_tokens']).toBe(1024);
+      expect(body['max_tokens']).toBeUndefined();
+    });
+
+    it('passes constructor generation kwargs into the request body', async () => {
+      const provider = new KimiChatProvider({
+        model: 'kimi-k2-turbo-preview',
+        apiKey: 'test-key',
+        stream: false,
+        generationKwargs: { prompt_cache_key: 'session-test' },
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['prompt_cache_key']).toBe('session-test');
+    });
+
+    it('combines thinking and max_tokens in internal state', () => {
+      const provider = createProvider()
+        .withThinking('high')
+        .withGenerationKwargs({ max_tokens: 512 });
+
+      expect(getGenerationState(provider)).toEqual({
+        reasoning_effort: 'high',
+        extra_body: {
+          thinking: { type: 'enabled' },
+        },
+        max_tokens: 512,
+      });
+    });
+
+    it('keeps the same internal state regardless of withThinking/withGenerationKwargs order', () => {
+      const thinkingThenKwargs = getGenerationState(
+        createProvider().withThinking('high').withGenerationKwargs({ max_tokens: 512 }),
+      );
+      const kwargsThenThinking = getGenerationState(
+        createProvider().withGenerationKwargs({ max_tokens: 512 }).withThinking('high'),
+      );
+
+      expect(kwargsThenThinking).toEqual(thinkingThenKwargs);
+    });
+
+    it('shallow-merges repeated withGenerationKwargs calls and replaces extra_body wholesale', () => {
+      const provider = createProvider()
+        .withGenerationKwargs({
+          temperature: 0.1,
+          extra_body: { first: true },
+        })
+        .withGenerationKwargs({
+          max_tokens: 512,
+          extra_body: { second: true },
+        });
+
+      expect(getGenerationState(provider)).toEqual({
+        temperature: 0.1,
+        max_tokens: 512,
+        extra_body: { second: true },
+      });
+    });
+  });
+
+  describe('with thinking', () => {
+    it('hoists thinking to the top level and sets reasoning_effort for high', async () => {
+      const provider = createProvider().withThinking('high');
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['reasoning_effort']).toBe('high');
+      expect(body['thinking']).toEqual({ type: 'enabled' });
+      expect(body['extra_body']).toBeUndefined();
+    });
+
+    it('hoists thinking disabled and clears reasoning_effort for off', async () => {
+      const provider = createProvider().withThinking('off');
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['reasoning_effort']).toBeUndefined();
+      expect(body['thinking']).toEqual({ type: 'disabled' });
+      expect(body['extra_body']).toBeUndefined();
+    });
+
+    it('thinkingEffort property reflects current state', () => {
+      const provider = createProvider();
+      expect(provider.thinkingEffort).toBeNull();
+
+      const withHigh = provider.withThinking('high');
+      expect(withHigh.thinkingEffort).toBe('high');
+
+      const withLow = provider.withThinking('low');
+      expect(withLow.thinkingEffort).toBe('low');
+    });
+
+    it('replaces the previous thinking effort when called again', () => {
+      const provider = createProvider().withThinking('high').withThinking('off');
+
+      expect(getGenerationState(provider)).toEqual({
+        reasoning_effort: undefined,
+        extra_body: {
+          thinking: { type: 'disabled' },
+        },
+      });
+    });
+  });
+
+  describe('provider properties', () => {
+    it('has correct name and model', () => {
+      const provider = createProvider();
+      expect(provider.name).toBe('kimi');
+      expect(provider.modelName).toBe('kimi-k2-turbo-preview');
+    });
+
+    it('throws during generation when no constructor or request API key is provided', async () => {
+      // Save and clear env var
+      const saved = process.env['KIMI_API_KEY'];
+      delete process.env['KIMI_API_KEY'];
+      try {
+        const provider = new KimiChatProvider({ model: 'test' });
+        await expect(provider.generate('', [], [])).rejects.toThrow(/options\.auth\.apiKey/);
+      } finally {
+        if (saved !== undefined) {
+          process.env['KIMI_API_KEY'] = saved;
+        }
+      }
+    });
+
+    it('passes request-scoped auth to the client factory', async () => {
+      const auths: unknown[] = [];
+      const client = {
+        chat: {
+          completions: {
+            create: vi.fn().mockResolvedValue(makeChatCompletionResponse('kimi-k2')),
+          },
+        },
+      };
+      const provider = new KimiChatProvider({
+        model: 'test',
+        stream: false,
+        clientFactory: (auth) => {
+          auths.push(auth);
+          return client as never;
+        },
+      });
+
+      const stream = await provider.generate('', [], [], {
+        auth: { apiKey: 'request-token' },
+      });
+      for await (const part of stream) {
+        void part;
+      }
+
+      expect(auths).toEqual([{ apiKey: 'request-token' }]);
+      expect(client.chat.completions.create).toHaveBeenCalledOnce();
+    });
+
+    it('withThinking returns a new instance', () => {
+      const provider = createProvider();
+      const newProvider = provider.withThinking('high');
+      expect(newProvider).toBeInstanceOf(KimiChatProvider);
+      expect(newProvider).not.toBe(provider);
+    });
+
+    it('withGenerationKwargs returns a new instance', () => {
+      const provider = createProvider();
+      const newProvider = provider.withGenerationKwargs({ temperature: 0.5 });
+      expect(newProvider).toBeInstanceOf(KimiChatProvider);
+      expect(newProvider).not.toBe(provider);
+    });
+
+    it('withGenerationKwargs does not mutate the original', () => {
+      const provider = createProvider();
+      const newProvider = provider.withGenerationKwargs({ temperature: 0.5 });
+      expect(getGenerationState(provider)).toEqual({});
+      expect(getGenerationState(newProvider)).toEqual({ temperature: 0.5 });
+    });
+  });
+
+  describe('clone client sharing', () => {
+    // The original and clone MUST share the underlying OpenAI client.
+    // The dynamic completion budget path (KosongLLM.chatOnce) clones the
+    // provider on every step. If a future change introduces a retry path
+    // that replaces `clone._client` and closes the previous one, the
+    // original instance's `_client` would become a dangling reference to
+    // a closed socket. Lock in the invariant here.
+    function getInternalClient(provider: KimiChatProvider): unknown {
+      return Reflect.get(provider, '_client');
+    }
+
+    it('withGenerationKwargs clone shares the same OpenAI client as the original', () => {
+      const original = createProvider();
+      const clone = original.withGenerationKwargs({ max_completion_tokens: 1024 });
+      expect(getInternalClient(clone)).not.toBeUndefined();
+      expect(Object.is(getInternalClient(clone), getInternalClient(original))).toBe(true);
+    });
+
+    it('withMaxCompletionTokens clone shares the same OpenAI client as the original', () => {
+      const original = createProvider();
+      const clone = original.withMaxCompletionTokens(2048);
+      expect(getInternalClient(clone)).not.toBeUndefined();
+      expect(Object.is(getInternalClient(clone), getInternalClient(original))).toBe(true);
+    });
+
+    it('withThinking clone shares the same OpenAI client as the original', () => {
+      const original = createProvider();
+      const clone = original.withThinking('high');
+      expect(getInternalClient(clone)).not.toBeUndefined();
+      expect(Object.is(getInternalClient(clone), getInternalClient(original))).toBe(true);
+    });
+  });
+
+  describe('non-stream response parsing', () => {
+    it('yields text content from non-stream response', async () => {
+      const provider = createProvider();
+      (provider as any)._client.chat.completions.create = vi.fn().mockResolvedValue({
+        id: 'chatcmpl-123',
+        choices: [{ message: { role: 'assistant', content: 'Hello world' } }],
+        usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+      });
+
+      const stream = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+
+      const parts = [];
+      for await (const part of stream) {
+        parts.push(part);
+      }
+
+      expect(parts).toEqual([{ type: 'text', text: 'Hello world' }]);
+      expect(stream.id).toBe('chatcmpl-123');
+      expect(stream.usage).toEqual({
+        inputOther: 10,
+        output: 5,
+        inputCacheRead: 0,
+        inputCacheCreation: 0,
+      });
+    });
+
+    it('yields reasoning_content as ThinkPart', async () => {
+      const provider = createProvider();
+      (provider as any)._client.chat.completions.create = vi.fn().mockResolvedValue({
+        id: 'chatcmpl-123',
+        choices: [
+          {
+            message: {
+              role: 'assistant',
+              content: 'The answer is 4.',
+              reasoning_content: 'Let me think about this...',
+            },
+          },
+        ],
+        usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+      });
+
+      const stream = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] }],
+      );
+
+      const parts = [];
+      for await (const part of stream) {
+        parts.push(part);
+      }
+
+      expect(parts).toEqual([
+        { type: 'think', think: 'Let me think about this...' },
+        { type: 'text', text: 'The answer is 4.' },
+      ]);
+    });
+  });
+
+  describe('streaming tool call routing', () => {
+    interface MockToolCallDelta {
+      index: number;
+      id?: string;
+      function?: { name?: string; arguments?: string };
+    }
+
+    function makeChunk(
+      toolCalls: MockToolCallDelta[],
+      opts?: { finishReason?: string; usage?: boolean },
+    ): Record<string, unknown> {
+      const chunk: Record<string, unknown> = {
+        id: 'chatcmpl-kimi-stream',
+        object: 'chat.completion.chunk',
+        created: 1234567890,
+        model: 'kimi-k2-turbo-preview',
+        choices: [
+          {
+            index: 0,
+            delta: { tool_calls: toolCalls },
+            finish_reason: opts?.finishReason ?? null,
+          },
+        ],
+      };
+      if (opts?.usage) {
+        chunk['usage'] = { prompt_tokens: 10, completion_tokens: 20, total_tokens: 30 };
+      }
+      return chunk;
+    }
+
+    async function* mockStream(
+      chunks: Record<string, unknown>[],
+    ): AsyncIterable<Record<string, unknown>> {
+      for (const chunk of chunks) {
+        yield chunk;
+      }
+    }
+
+    it('buffers indexed argument deltas until the real tool name arrives', async () => {
+      const provider = createProvider(true);
+
+      const chunks = [
+        makeChunk([{ index: 0, id: 'call_delayed', function: { name: '', arguments: '' } }]),
+        makeChunk([{ index: 0, function: { arguments: '{"a' } }]),
+        makeChunk([{ index: 0, function: { name: 'foo' } }]),
+        makeChunk([{ index: 0, function: { arguments: '":1}' } }]),
+        makeChunk([], { finishReason: 'tool_calls', usage: true }),
+      ];
+
+      (
+        provider as unknown as { _client: { chat: { completions: { create: unknown } } } }
+      )._client.chat.completions.create = vi.fn().mockResolvedValue(mockStream(chunks));
+
+      const result = await generate(
+        provider,
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'do it' }], toolCalls: [] }],
+      );
+
+      expect(result.message.toolCalls).toEqual([
+        {
+          type: 'function',
+          id: 'call_delayed',
+          function: { name: 'foo', arguments: '{"a":1}' },
+        },
+      ]);
+    });
+
+    it('marks sequential indexed tool calls ready at merge boundaries', async () => {
+      const provider = createProvider(true);
+
+      const chunks = [
+        makeChunk([{ index: 0, id: 'call_a', function: { name: 'read_file', arguments: '' } }]),
+        makeChunk([{ index: 0, function: { arguments: '{"path":"a.txt"}' } }]),
+        makeChunk([{ index: 1, id: 'call_b', function: { name: 'read_file', arguments: '' } }]),
+        makeChunk([{ index: 1, function: { arguments: '{"path":"b.txt"}' } }]),
+        makeChunk([], { finishReason: 'tool_calls', usage: true }),
+      ];
+
+      (
+        provider as unknown as { _client: { chat: { completions: { create: unknown } } } }
+      )._client.chat.completions.create = vi.fn().mockResolvedValue(mockStream(chunks));
+
+      const events: string[] = [];
+      await generate(
+        provider,
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'read files' }], toolCalls: [] }],
+        {
+          onMessagePart(part): void {
+            if (part.type === 'tool_call_part') {
+              events.push(`delta:${part.index}:${part.argumentsPart}`);
+            }
+          },
+          onToolCall(toolCall): void {
+            events.push(`ready:${toolCall.id}:${toolCall.function.arguments ?? ''}`);
+          },
+        },
+      );
+
+      // onToolCall fires after stream drains, in final order.
+      expect(events).toEqual([
+        'delta:0:{"path":"a.txt"}',
+        'delta:1:{"path":"b.txt"}',
+        'ready:call_a:{"path":"a.txt"}',
+        'ready:call_b:{"path":"b.txt"}',
+      ]);
+    });
+
+    it('handles non-indexed tool_call delta with concrete name (emit ToolCall directly)', async () => {
+      const provider = createProvider(true);
+
+      // Some OpenAI-compatible servers emit tool_calls without an `index`
+      // field. The provider must still emit a complete ToolCall with either
+      // the delta's id or a generated UUID.
+      const chunks = [
+        {
+          id: 'chatcmpl-noindex',
+          choices: [
+            {
+              index: 0,
+              delta: {
+                tool_calls: [
+                  {
+                    // No index!
+                    id: 'call_noidx',
+                    function: { name: 'foo', arguments: '{"a":1}' },
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ];
+
+      (
+        provider as unknown as { _client: { chat: { completions: { create: unknown } } } }
+      )._client.chat.completions.create = vi.fn().mockResolvedValue(mockStream(chunks));
+
+      const result = await generate(
+        provider,
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'do it' }], toolCalls: [] }],
+      );
+
+      expect(result.message.toolCalls).toEqual([
+        {
+          type: 'function',
+          id: 'call_noidx',
+          function: { name: 'foo', arguments: '{"a":1}' },
+        },
+      ]);
+    });
+
+    it('handles non-indexed tool_call delta with arguments only (emit ToolCallPart)', async () => {
+      const provider = createProvider(true);
+
+      // A pure arguments-only delta without an index — no concrete name yet.
+      // The provider should emit a free-standing ToolCallPart to keep the
+      // generate reducer fed with argument fragments.
+      const chunks = [
+        {
+          id: 'chatcmpl-argonly',
+          choices: [
+            {
+              index: 0,
+              delta: {
+                tool_calls: [
+                  {
+                    function: { name: 'foo' }, // first chunk with name (no index, concrete)
+                  },
+                ],
+              },
+            },
+            {
+              id: 'chatcmpl-argonly',
+              choices: [
+                {
+                  index: 0,
+                  delta: {
+                    tool_calls: [
+                      {
+                        // no index, arguments-only
+                        function: { arguments: '{"x":1}' },
+                      },
+                    ],
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      ];
+      void chunks;
+      // Single-chunk simpler test: non-indexed arg-only is a rare but real
+      // wire shape from some OpenAI-compatible servers.
+      const singleChunk = {
+        id: 'chatcmpl-argonly',
+        choices: [
+          {
+            index: 0,
+            delta: {
+              tool_calls: [{ function: { arguments: '{"x":1}' } }],
+            },
+          },
+        ],
+      };
+
+      (
+        provider as unknown as { _client: { chat: { completions: { create: unknown } } } }
+      )._client.chat.completions.create = vi.fn().mockResolvedValue(mockStream([singleChunk]));
+
+      // generate() uses the reducer which expects a ToolCall header before
+      // accumulating arguments. A pure arg-only without a prior header is
+      // dropped as "orphan", so verify the raw stream yield instead.
+      const stream = await provider.generate('', [], []);
+      const parts: Array<Record<string, unknown>> = [];
+      for await (const p of stream) {
+        parts.push(p as unknown as Record<string, unknown>);
+      }
+      expect(parts).toEqual([{ type: 'tool_call_part', argumentsPart: '{"x":1}' }]);
+    });
+
+    it('non-stream response with tool_calls yields ToolCall parts', async () => {
+      const provider = createProvider(false);
+      (provider as any)._client.chat.completions.create = vi.fn().mockResolvedValue({
+        id: 'chatcmpl-nonstream',
+        choices: [
+          {
+            message: {
+              role: 'assistant',
+              content: null,
+              tool_calls: [
+                {
+                  id: 'call_ns_a',
+                  type: 'function',
+                  function: { name: 'lookup', arguments: '{"q":"hi"}' },
+                },
+              ],
+            },
+          },
+        ],
+        usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+      });
+
+      const stream = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] }],
+      );
+      const parts: Array<Record<string, unknown>> = [];
+      for await (const p of stream) parts.push(p as unknown as Record<string, unknown>);
+
+      const toolCall = parts.find((p) => p['type'] === 'function');
+      expect(toolCall).toMatchObject({
+        type: 'function',
+        id: 'call_ns_a',
+        function: { name: 'lookup', arguments: '{"q":"hi"}' },
+      });
+    });
+
+    it('non-stream response generates UUID when tool_call has no id', async () => {
+      const provider = createProvider(false);
+      (provider as any)._client.chat.completions.create = vi.fn().mockResolvedValue({
+        id: 'chatcmpl-uuid',
+        choices: [
+          {
+            message: {
+              role: 'assistant',
+              content: null,
+              tool_calls: [
+                {
+                  type: 'function',
+                  function: { name: 'lookup', arguments: '{}' },
+                },
+              ],
+            },
+          },
+        ],
+      });
+
+      const stream = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] }],
+      );
+      const parts: Array<Record<string, unknown>> = [];
+      for await (const p of stream) parts.push(p as unknown as Record<string, unknown>);
+
+      const toolCall = parts.find((p) => p['type'] === 'function');
+      expect(toolCall).toMatchObject({
+        type: 'function',
+        id: expect.stringMatching(/.+/),
+      });
+    });
+  });
+
+  describe('provider property accessors', () => {
+    it('modelParameters returns combined config', () => {
+      const provider = createProvider().withGenerationKwargs({ temperature: 0.5 });
+      const params = provider.modelParameters;
+      expect(params).toMatchObject({
+        model: 'kimi-k2-turbo-preview',
+        temperature: 0.5,
+        baseUrl: expect.any(String),
+      });
+    });
+  });
+
+  describe('withThinking medium', () => {
+    it('maps medium -> reasoning_effort=medium', () => {
+      const provider = createProvider().withThinking('medium');
+      expect(provider.thinkingEffort).toBe('medium');
+    });
+  });
+
+  describe('withExtraBody', () => {
+    it('forwards thinking.keep verbatim, hoisted to the request top level', async () => {
+      const provider = createProvider().withExtraBody({ thinking: { keep: 'all' } });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['thinking']).toEqual({ keep: 'all' });
+      expect(body['extra_body']).toBeUndefined();
+    });
+
+    it('field-merges thinking when called after withThinking', async () => {
+      const provider = createProvider()
+        .withThinking('high')
+        .withExtraBody({ thinking: { keep: 'all' } });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['reasoning_effort']).toBe('high');
+      expect(body['thinking']).toEqual({ type: 'enabled', keep: 'all' });
+      expect(body['extra_body']).toBeUndefined();
+    });
+
+    it('uses last-writer-wins for top-level keys other than thinking', () => {
+      const provider = createProvider()
+        .withExtraBody({ foo: 1, thinking: { type: 'enabled' } })
+        .withExtraBody({ foo: 2 });
+
+      expect(getGenerationState(provider).extra_body).toEqual({
+        foo: 2,
+        thinking: { type: 'enabled' },
+      });
+    });
+
+    it('merges thinking when withExtraBody runs before withThinking', () => {
+      const provider = createProvider()
+        .withExtraBody({ thinking: { keep: 'all' } })
+        .withThinking('high');
+
+      expect(getGenerationState(provider).extra_body).toEqual({
+        thinking: { type: 'enabled', keep: 'all' },
+      });
+    });
+
+    it('does not block subsequent withThinking when seeded with an empty thinking patch', async () => {
+      const provider = createProvider()
+        .withExtraBody({ thinking: {} })
+        .withThinking('high');
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['thinking']).toEqual({ type: 'enabled' });
+    });
+
+    it('treats empty thinking patch as noop, preserving prior withThinking', async () => {
+      const provider = createProvider().withThinking('high').withExtraBody({ thinking: {} });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['thinking']).toEqual({ type: 'enabled' });
+    });
+  });
+
+  describe('assistant tool call content omission', () => {
+    const toolCall: ToolCall = {
+      type: 'function',
+      id: 'call_xyz',
+      function: { name: 'add', arguments: '{}' },
+    };
+
+    it('omits content when assistant tool call content is empty', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add' }], toolCalls: [] },
+        { role: 'assistant', content: [], toolCalls: [toolCall] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      const assistantMessage = (body['messages'] as Record<string, unknown>[])[1];
+
+      expect(assistantMessage).toEqual({
+        role: 'assistant',
+        tool_calls: [
+          {
+            type: 'function',
+            id: 'call_xyz',
+            function: { name: 'add', arguments: '{}' },
+          },
+        ],
+      });
+    });
+
+    it('omits content when assistant tool call content is whitespace-only', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: '   \n  ' }],
+          toolCalls: [toolCall],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      const assistantMessage = (body['messages'] as Record<string, unknown>[])[1];
+
+      expect(assistantMessage).toEqual({
+        role: 'assistant',
+        tool_calls: [
+          {
+            type: 'function',
+            id: 'call_xyz',
+            function: { name: 'add', arguments: '{}' },
+          },
+        ],
+      });
+    });
+
+    it('keeps real assistant content alongside tool calls', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll add those." }],
+          toolCalls: [toolCall],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      const assistantMessage = (body['messages'] as Record<string, unknown>[])[1];
+
+      expect(assistantMessage).toEqual({
+        role: 'assistant',
+        content: "I'll add those.",
+        tool_calls: [
+          {
+            type: 'function',
+            id: 'call_xyz',
+            function: { name: 'add', arguments: '{}' },
+          },
+        ],
+      });
+    });
+
+    it('keeps whitespace-only assistant content when there are no tool calls', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'assistant', content: [{ type: 'text', text: '   \n  ' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['messages']).toEqual([{ role: 'assistant', content: '   \n  ' }]);
+    });
+  });
+});
+
+describe('extractUsageFromChunk', () => {
+  it('extracts top-level usage', () => {
+    const chunk = {
+      id: 'test',
+      choices: [],
+      usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+    };
+    const usage = extractUsageFromChunk(chunk);
+    expect(usage).toEqual({ prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 });
+  });
+
+  it('extracts choices[0].usage (Moonshot proprietary)', () => {
+    const chunk = {
+      id: 'chatcmpl-6970b5d02fa474c1767e8767',
+      object: 'chat.completion.chunk',
+      created: 1768994256,
+      model: 'kimi-k2-turbo-preview',
+      choices: [
+        {
+          index: 0,
+          delta: {},
+          finish_reason: 'stop',
+          usage: {
+            prompt_tokens: 8,
+            completion_tokens: 11,
+            total_tokens: 19,
+            cached_tokens: 8,
+          },
+        },
+      ],
+      system_fingerprint: 'fpv0_10a6da87',
+    };
+
+    const rawUsage = extractUsageFromChunk(chunk);
+    expect(rawUsage).toEqual({
+      prompt_tokens: 8,
+      completion_tokens: 11,
+      total_tokens: 19,
+      cached_tokens: 8,
+    });
+
+    // Also verify extractUsage converts it to TokenUsage correctly
+    const tokenUsage = extractUsage(rawUsage);
+    expect(tokenUsage).toEqual({
+      inputOther: 0, // 8 - 8 (cached)
+      output: 11,
+      inputCacheRead: 8,
+      inputCacheCreation: 0,
+    });
+  });
+
+  it('returns null when no usage is present', () => {
+    const chunk = {
+      id: 'test',
+      choices: [{ index: 0, delta: { content: 'hello' } }],
+    };
+    expect(extractUsageFromChunk(chunk)).toBeNull();
+  });
+
+  it('returns null when choices is empty', () => {
+    const chunk = { id: 'test', choices: [] };
+    expect(extractUsageFromChunk(chunk)).toBeNull();
+  });
+});
+
+describe('extractUsage', () => {
+  it('extracts basic usage', () => {
+    const usage = extractUsage({
+      prompt_tokens: 10,
+      completion_tokens: 5,
+      total_tokens: 15,
+    });
+    expect(usage).toEqual({
+      inputOther: 10,
+      output: 5,
+      inputCacheRead: 0,
+      inputCacheCreation: 0,
+    });
+  });
+
+  it('extracts usage with Moonshot cached_tokens', () => {
+    const usage = extractUsage({
+      prompt_tokens: 100,
+      completion_tokens: 20,
+      total_tokens: 120,
+      cached_tokens: 60,
+    });
+    expect(usage).toEqual({
+      inputOther: 40,
+      output: 20,
+      inputCacheRead: 60,
+      inputCacheCreation: 0,
+    });
+  });
+
+  it('extracts usage with OpenAI prompt_tokens_details', () => {
+    const usage = extractUsage({
+      prompt_tokens: 100,
+      completion_tokens: 20,
+      total_tokens: 120,
+      prompt_tokens_details: { cached_tokens: 50 },
+    });
+    expect(usage).toEqual({
+      inputOther: 50,
+      output: 20,
+      inputCacheRead: 50,
+      inputCacheCreation: 0,
+    });
+  });
+
+  it('returns null for null/undefined', () => {
+    const undef: unknown = undefined;
+    expect(extractUsage(null)).toBeNull();
+    expect(extractUsage(undef)).toBeNull();
+  });
+});
diff --git a/packages/kosong/test/message.test.ts b/packages/kosong/test/message.test.ts
new file mode 100644
index 000000000..240a62a25
--- /dev/null
+++ b/packages/kosong/test/message.test.ts
@@ -0,0 +1,424 @@
+import type {
+  AudioURLPart,
+  ContentPart,
+  ImageURLPart,
+  Message,
+  StreamedMessagePart,
+  TextPart,
+  ThinkPart,
+  ToolCall,
+  ToolCallPart,
+  VideoURLPart,
+} from '#/message';
+import {
+  createAssistantMessage,
+  createToolMessage,
+  createUserMessage,
+  extractText,
+  getTextContent,
+  isContentPart,
+  isToolCall,
+  isToolCallPart,
+  mergeInPlace,
+} from '#/message';
+import { describe, expect, it } from 'vitest';
+describe('createUserMessage', () => {
+  it('creates a user message with single text part', () => {
+    const msg = createUserMessage('hello');
+    expect(msg.role).toBe('user');
+    expect(msg.content).toHaveLength(1);
+    expect(msg.content[0]).toEqual({ type: 'text', text: 'hello' });
+  });
+});
+
+describe('createAssistantMessage', () => {
+  it('creates an assistant message from content parts', () => {
+    const parts: ContentPart[] = [
+      { type: 'text', text: 'hello' },
+      { type: 'text', text: ' world' },
+    ];
+    const msg = createAssistantMessage(parts);
+    expect(msg.role).toBe('assistant');
+    expect(msg.content).toHaveLength(2);
+    expect(msg.toolCalls).toEqual([]);
+  });
+
+  it('includes toolCalls when provided', () => {
+    const tc: ToolCall = {
+      type: 'function',
+      id: 'call-1',
+      function: { name: 'search', arguments: '{"q":"ts"}' },
+    };
+    const msg = createAssistantMessage([{ type: 'text', text: 'ok' }], [tc]);
+    expect(msg.toolCalls).toHaveLength(1);
+    expect(msg.toolCalls[0]!.function.name).toBe('search');
+  });
+
+  it('defaults toolCalls to empty array when not provided', () => {
+    const msg = createAssistantMessage([{ type: 'text', text: 'test' }]);
+    expect(msg.toolCalls).toEqual([]);
+  });
+});
+
+describe('createToolMessage', () => {
+  it('creates a tool message from a string', () => {
+    const msg = createToolMessage('call-1', 'result data');
+    expect(msg.role).toBe('tool');
+    expect(msg.toolCallId).toBe('call-1');
+    expect(msg.content).toHaveLength(1);
+    expect(msg.content[0]).toEqual({ type: 'text', text: 'result data' });
+  });
+
+  it('creates a tool message from ContentPart array', () => {
+    const parts: ContentPart[] = [
+      { type: 'text', text: 'line1' },
+      { type: 'text', text: 'line2' },
+    ];
+    const msg = createToolMessage('call-2', parts);
+    expect(msg.role).toBe('tool');
+    expect(msg.content).toHaveLength(2);
+    expect(msg.content[0]).toEqual({ type: 'text', text: 'line1' });
+  });
+});
+describe('extractText', () => {
+  it('extracts text from a message with a single text part', () => {
+    const msg = createUserMessage('hello world');
+    expect(extractText(msg)).toBe('hello world');
+  });
+
+  it('concatenates multiple text parts with default separator', () => {
+    const msg: Message = {
+      role: 'assistant',
+      content: [
+        { type: 'text', text: 'Hello' },
+        { type: 'text', text: ' world' },
+      ],
+      toolCalls: [],
+    };
+    expect(extractText(msg)).toBe('Hello world');
+  });
+
+  it('uses custom separator', () => {
+    const msg: Message = {
+      role: 'assistant',
+      content: [
+        { type: 'text', text: 'line1' },
+        { type: 'text', text: 'line2' },
+      ],
+      toolCalls: [],
+    };
+    expect(extractText(msg, '\n')).toBe('line1\nline2');
+  });
+
+  it('ignores non-text parts', () => {
+    const msg: Message = {
+      role: 'assistant',
+      content: [
+        { type: 'think', think: 'thinking...' },
+        { type: 'text', text: 'visible' },
+      ],
+      toolCalls: [],
+    };
+    expect(extractText(msg)).toBe('visible');
+  });
+
+  it('returns empty string for message with no text parts', () => {
+    const msg: Message = {
+      role: 'assistant',
+      content: [{ type: 'think', think: 'thinking only' }],
+      toolCalls: [],
+    };
+    expect(extractText(msg)).toBe('');
+  });
+
+  it('returns empty string for message with empty content', () => {
+    const msg: Message = { role: 'assistant', content: [], toolCalls: [] };
+    expect(extractText(msg)).toBe('');
+  });
+});
+
+describe('getTextContent (deprecated alias)', () => {
+  it('works the same as extractText', () => {
+    const msg = createUserMessage('test');
+    expect(getTextContent(msg)).toBe(extractText(msg));
+  });
+});
+describe('ContentPart type narrowing', () => {
+  it('narrows TextPart correctly', () => {
+    const part: ContentPart = { type: 'text', text: 'hello' };
+    if (part.type === 'text') {
+      const textPart: TextPart = part;
+      expect(textPart.text).toBe('hello');
+    }
+  });
+
+  it('narrows ThinkPart correctly', () => {
+    const part: ContentPart = { type: 'think', think: 'reasoning' };
+    if (part.type === 'think') {
+      const thinkPart: ThinkPart = part;
+      expect(thinkPart.think).toBe('reasoning');
+    }
+  });
+
+  it('narrows ThinkPart with encrypted field', () => {
+    const part: ContentPart = { type: 'think', think: '', encrypted: 'enc-data' };
+    if (part.type === 'think') {
+      expect(part.encrypted).toBe('enc-data');
+    }
+  });
+
+  it('narrows ImageURLPart correctly', () => {
+    const part: ContentPart = {
+      type: 'image_url',
+      imageUrl: { url: 'https://example.com/img.png' },
+    };
+    if (part.type === 'image_url') {
+      const imgPart: ImageURLPart = part;
+      expect(imgPart.imageUrl.url).toBe('https://example.com/img.png');
+    }
+  });
+
+  it('narrows ImageURLPart with optional id', () => {
+    const part: ContentPart = {
+      type: 'image_url',
+      imageUrl: { url: 'https://example.com/img.png', id: 'img-1' },
+    };
+    if (part.type === 'image_url') {
+      expect(part.imageUrl.id).toBe('img-1');
+    }
+  });
+
+  it('narrows AudioURLPart correctly', () => {
+    const part: ContentPart = {
+      type: 'audio_url',
+      audioUrl: { url: 'https://example.com/audio.mp3' },
+    };
+    if (part.type === 'audio_url') {
+      const audioPart: AudioURLPart = part;
+      expect(audioPart.audioUrl.url).toBe('https://example.com/audio.mp3');
+    }
+  });
+
+  it('narrows VideoURLPart correctly', () => {
+    const part: ContentPart = {
+      type: 'video_url',
+      videoUrl: { url: 'https://example.com/video.mp4', id: 'vid-1' },
+    };
+    if (part.type === 'video_url') {
+      const videoPart: VideoURLPart = part;
+      expect(videoPart.videoUrl.url).toBe('https://example.com/video.mp4');
+      expect(videoPart.videoUrl.id).toBe('vid-1');
+    }
+  });
+});
+describe('type guards', () => {
+  it('isContentPart returns true for text', () => {
+    const part: StreamedMessagePart = { type: 'text', text: 'hi' };
+    expect(isContentPart(part)).toBe(true);
+  });
+
+  it('isContentPart returns true for think', () => {
+    const part: StreamedMessagePart = { type: 'think', think: 'hmm' };
+    expect(isContentPart(part)).toBe(true);
+  });
+
+  it('isContentPart returns true for image_url', () => {
+    const part: StreamedMessagePart = {
+      type: 'image_url',
+      imageUrl: { url: 'http://img' },
+    };
+    expect(isContentPart(part)).toBe(true);
+  });
+
+  it('isContentPart returns true for audio_url', () => {
+    const part: StreamedMessagePart = {
+      type: 'audio_url',
+      audioUrl: { url: 'http://audio' },
+    };
+    expect(isContentPart(part)).toBe(true);
+  });
+
+  it('isContentPart returns true for video_url', () => {
+    const part: StreamedMessagePart = {
+      type: 'video_url',
+      videoUrl: { url: 'http://video' },
+    };
+    expect(isContentPart(part)).toBe(true);
+  });
+
+  it('isContentPart returns false for tool call', () => {
+    const part: StreamedMessagePart = {
+      type: 'function',
+      id: 'c1',
+      function: { name: 'f', arguments: null },
+    };
+    expect(isContentPart(part)).toBe(false);
+  });
+
+  it('isContentPart returns false for tool call part', () => {
+    const part: StreamedMessagePart = { type: 'tool_call_part', argumentsPart: 'x' };
+    expect(isContentPart(part)).toBe(false);
+  });
+
+  it('isToolCall returns true for function type', () => {
+    const part: StreamedMessagePart = {
+      type: 'function',
+      id: 'c1',
+      function: { name: 'f', arguments: null },
+    };
+    expect(isToolCall(part)).toBe(true);
+  });
+
+  it('isToolCall returns false for content parts', () => {
+    const part: StreamedMessagePart = { type: 'text', text: 'hi' };
+    expect(isToolCall(part)).toBe(false);
+  });
+
+  it('isToolCallPart returns true for tool_call_part', () => {
+    const part: StreamedMessagePart = { type: 'tool_call_part', argumentsPart: 'abc' };
+    expect(isToolCallPart(part)).toBe(true);
+  });
+
+  it('isToolCallPart returns false for other types', () => {
+    const part: StreamedMessagePart = { type: 'text', text: 'hi' };
+    expect(isToolCallPart(part)).toBe(false);
+  });
+});
+describe('mergeInPlace', () => {
+  it('merges TextPart + TextPart', () => {
+    const target: TextPart = { type: 'text', text: 'hello' };
+    const source: TextPart = { type: 'text', text: ' world' };
+    expect(mergeInPlace(target, source)).toBe(true);
+    expect(target.text).toBe('hello world');
+  });
+
+  it('merges ThinkPart + ThinkPart', () => {
+    const target: ThinkPart = { type: 'think', think: 'step1' };
+    const source: ThinkPart = { type: 'think', think: ' step2' };
+    expect(mergeInPlace(target, source)).toBe(true);
+    expect(target.think).toBe('step1 step2');
+  });
+
+  it('merges ThinkPart + ThinkPart with source encrypted', () => {
+    const target: ThinkPart = { type: 'think', think: 'thought' };
+    const source: ThinkPart = { type: 'think', think: '', encrypted: 'sig-123' };
+    expect(mergeInPlace(target, source)).toBe(true);
+    expect(target.think).toBe('thought');
+    expect(target.encrypted).toBe('sig-123');
+  });
+
+  it('refuses ThinkPart merge when target already encrypted', () => {
+    const target: ThinkPart = { type: 'think', think: 'done', encrypted: 'sig-old' };
+    const source: ThinkPart = { type: 'think', think: ' more' };
+    expect(mergeInPlace(target, source)).toBe(false);
+    expect(target.think).toBe('done');
+  });
+
+  it('merges ToolCall + ToolCallPart (null -> part)', () => {
+    const target: ToolCall = {
+      type: 'function',
+      id: 'c1',
+      function: { name: 'f', arguments: null },
+    };
+    const source: ToolCallPart = { type: 'tool_call_part', argumentsPart: '{"a":' };
+    expect(mergeInPlace(target, source)).toBe(true);
+    expect(target.function.arguments).toBe('{"a":');
+  });
+
+  it('merges ToolCall + ToolCallPart (append)', () => {
+    const target: ToolCall = {
+      type: 'function',
+      id: 'c1',
+      function: { name: 'f', arguments: '{"a":' },
+    };
+    const source: ToolCallPart = { type: 'tool_call_part', argumentsPart: '1}' };
+    expect(mergeInPlace(target, source)).toBe(true);
+    expect(target.function.arguments).toBe('{"a":1}');
+  });
+
+  it('merges ToolCall + ToolCallPart with null argumentsPart (no-op)', () => {
+    const target: ToolCall = {
+      type: 'function',
+      id: 'c1',
+      function: { name: 'f', arguments: '{"x":1}' },
+    };
+    const source: ToolCallPart = { type: 'tool_call_part', argumentsPart: null };
+    expect(mergeInPlace(target, source)).toBe(true);
+    expect(target.function.arguments).toBe('{"x":1}');
+  });
+
+  it('returns false for TextPart + ThinkPart', () => {
+    const target: TextPart = { type: 'text', text: 'hi' };
+    const source: ThinkPart = { type: 'think', think: 'nope' };
+    expect(mergeInPlace(target, source)).toBe(false);
+  });
+
+  it('returns false for ThinkPart + TextPart', () => {
+    const target: ThinkPart = { type: 'think', think: 'hi' };
+    const source: TextPart = { type: 'text', text: 'nope' };
+    expect(mergeInPlace(target, source)).toBe(false);
+  });
+
+  it('returns false for TextPart + ToolCallPart', () => {
+    const target: TextPart = { type: 'text', text: 'hi' };
+    const source: ToolCallPart = { type: 'tool_call_part', argumentsPart: 'x' };
+    expect(mergeInPlace(target, source)).toBe(false);
+  });
+
+  it('returns false for ToolCall + TextPart', () => {
+    const target: ToolCall = {
+      type: 'function',
+      id: 'c1',
+      function: { name: 'f', arguments: null },
+    };
+    const source: TextPart = { type: 'text', text: 'x' };
+    expect(mergeInPlace(target, source)).toBe(false);
+  });
+});
+describe('Message optional fields', () => {
+  it('message can have name field', () => {
+    const msg: Message = {
+      role: 'system',
+      name: 'system-prompt',
+      content: [{ type: 'text', text: 'You are helpful.' }],
+      toolCalls: [],
+    };
+    expect(msg.name).toBe('system-prompt');
+  });
+
+  it('message can have toolCalls', () => {
+    const msg: Message = {
+      role: 'assistant',
+      content: [],
+      toolCalls: [
+        {
+          type: 'function',
+          id: 'call-1',
+          function: { name: 'search', arguments: '{"q":"test"}' },
+        },
+      ],
+    };
+    expect(msg.toolCalls).toHaveLength(1);
+    expect(msg.toolCalls[0]!.function.name).toBe('search');
+  });
+
+  it('message can have partial flag', () => {
+    const msg: Message = {
+      role: 'assistant',
+      content: [{ type: 'text', text: 'partial...' }],
+      toolCalls: [],
+      partial: true,
+    };
+    expect(msg.partial).toBe(true);
+  });
+
+  it('ToolCall can have extras', () => {
+    const tc: ToolCall = {
+      type: 'function',
+      id: 'call-1',
+      function: { name: 'search', arguments: '{}' },
+      extras: { provider_id: 'anthropic-123' },
+    };
+    expect(tc.extras).toEqual({ provider_id: 'anthropic-123' });
+  });
+});
diff --git a/packages/kosong/test/openai-common-errors.test.ts b/packages/kosong/test/openai-common-errors.test.ts
new file mode 100644
index 000000000..3d07a52e2
--- /dev/null
+++ b/packages/kosong/test/openai-common-errors.test.ts
@@ -0,0 +1,319 @@
+import {
+  APIConnectionError,
+  APIContextOverflowError,
+  APIStatusError,
+  APITimeoutError,
+  ChatProviderError,
+} from '#/errors';
+import type { ContentPart } from '#/message';
+import {
+  convertContentPart,
+  convertOpenAIError,
+  reasoningEffortToThinkingEffort,
+  thinkingEffortToReasoningEffort,
+} from '#/providers/openai-common';
+import { OpenAILegacyChatProvider, OpenAILegacyStreamedMessage } from '#/providers/openai-legacy';
+import {
+  APIError as OpenAIAPIError,
+  APIConnectionError as OpenAIConnectionError,
+  APIConnectionTimeoutError as OpenAITimeoutError,
+  APIUserAbortError as OpenAIUserAbortError,
+} from 'openai';
+import { describe, it, expect } from 'vitest';
+describe('OpenAI client creation', () => {
+  it('does not inject max_retries into OpenAI client', () => {
+    // The OpenAI constructor is called with apiKey and baseURL only —
+    // we verify that the provider does not set max_retries.
+    const provider = new OpenAILegacyChatProvider({
+      model: 'gpt-4.1',
+      apiKey: 'test-key',
+      baseUrl: 'https://example.com/v1',
+    });
+
+    const client = (provider as any)._client as Record<string, unknown>;
+    expect((client as unknown as Record<string, unknown>)['maxRetries']).not.toBe(0);
+  });
+});
+describe('convertOpenAIError: base APIError mapping', () => {
+  const cases: Array<{ message: string; expectedType: typeof ChatProviderError; id: string }> = [
+    {
+      message: 'Network connection lost.',
+      expectedType: APIConnectionError,
+      id: 'network_connection_lost',
+    },
+    { message: 'Connection error.', expectedType: APIConnectionError, id: 'connection_error' },
+    { message: 'network error', expectedType: APIConnectionError, id: 'network_error' },
+    { message: 'disconnected from server', expectedType: APIConnectionError, id: 'disconnected' },
+    {
+      message: 'connection reset by peer',
+      expectedType: APIConnectionError,
+      id: 'connection_reset_by_peer',
+    },
+    {
+      message: 'connection closed unexpectedly',
+      expectedType: APIConnectionError,
+      id: 'connection_closed_unexpectedly',
+    },
+    { message: 'Request timed out.', expectedType: APITimeoutError, id: 'request_timed_out' },
+    { message: 'timed out', expectedType: APITimeoutError, id: 'timed_out' },
+    // Timeout must take priority over network when both patterns match.
+    {
+      message: 'connection timed out',
+      expectedType: APITimeoutError,
+      id: 'connection_timed_out_timeout_priority',
+    },
+    {
+      message: 'Something completely unrelated',
+      expectedType: ChatProviderError,
+      id: 'unrelated_error',
+    },
+    {
+      message: 'Internal server error',
+      expectedType: ChatProviderError,
+      id: 'internal_server_error',
+    },
+    // Bare "reset"/"closed" must NOT match — they are too broad
+    {
+      message: 'Your session has been reset',
+      expectedType: ChatProviderError,
+      id: 'bare_reset_no_match',
+    },
+    {
+      message: 'Stream closed by server due to policy violation',
+      expectedType: ChatProviderError,
+      id: 'bare_closed_no_match',
+    },
+  ];
+
+  for (const { message, expectedType, id } of cases) {
+    it(`classifies "${id}": ${message}`, () => {
+      // Base APIError with no status and no body (transport-layer failure)
+      const err = new OpenAIAPIError(undefined, undefined, message, undefined);
+      const result = convertOpenAIError(err);
+      expect(result).toBeInstanceOf(expectedType);
+    });
+  }
+});
+describe('convertOpenAIError: existing provider errors', () => {
+  it('preserves an existing ChatProviderError instance', () => {
+    const err = new APIStatusError(401, 'Unauthorized', 'req-401');
+
+    expect(convertOpenAIError(err)).toBe(err);
+  });
+});
+describe('convertOpenAIError: context overflow', () => {
+  it('normalizes context overflow status errors', () => {
+    const err = new OpenAIAPIError(413, undefined, 'Context length exceeded', undefined);
+    const result = convertOpenAIError(err);
+    expect(result).toBeInstanceOf(APIContextOverflowError);
+    expect((result as APIContextOverflowError).statusCode).toBe(413);
+  });
+});
+describe('convertOpenAIError: subclass errors still match first', () => {
+  it('APIConnectionError matches its own case', () => {
+    const connErr = new OpenAIConnectionError({ message: 'Connection error.' });
+    const result = convertOpenAIError(connErr);
+    expect(result).toBeInstanceOf(APIConnectionError);
+  });
+
+  it('APIConnectionTimeoutError matches as timeout', () => {
+    const timeoutErr = new OpenAITimeoutError({ message: 'Request timed out.' });
+    const result = convertOpenAIError(timeoutErr);
+    expect(result).toBeInstanceOf(APITimeoutError);
+  });
+});
+describe('convertOpenAIError: APIError with body skips heuristic', () => {
+  it('does not heuristically reclassify when error has a body', () => {
+    // SSE error events carry a body — they must NOT be reclassified
+    // even if the message contains network keywords.
+    const err = new OpenAIAPIError(
+      undefined,
+      { error: { message: 'Connection limit exceeded', type: 'server_error' } },
+      'Connection limit exceeded',
+      undefined,
+    );
+    const result = convertOpenAIError(err);
+    // Should NOT be APIConnectionError despite "Connection" in message
+    expect(result.constructor).toBe(ChatProviderError);
+  });
+});
+describe('convertOpenAIError: subclass errors fall through', () => {
+  it('APIUserAbortError is not heuristically reclassified', () => {
+    // APIUserAbortError is a subclass of APIError (not exact APIError),
+    // so the heuristic branch should not apply even with network keywords.
+    const err = new OpenAIUserAbortError({ message: 'connection aborted by user' });
+    const result = convertOpenAIError(err);
+    // Should fall through to generic handling, not become APIConnectionError
+    expect(result.constructor).toBe(ChatProviderError);
+  });
+});
+describe('OpenAI streaming error propagation', () => {
+  it('base APIError("Network connection lost.") during streaming becomes APIConnectionError', async () => {
+    // Simulates: streaming for ~33 minutes, then SSE connection drops
+    // and the SDK raises openai.APIError("Network connection lost.")
+    async function* failingStream(): AsyncGenerator<never> {
+      throw new OpenAIAPIError(undefined, undefined, 'Network connection lost.', undefined);
+      // Make this an async generator (unreachable)
+      yield undefined as never;
+    }
+
+    const msg = new OpenAILegacyStreamedMessage(
+      failingStream() as AsyncIterable<never>,
+      true,
+      undefined,
+    );
+
+    await expect(async () => {
+      for await (const _ of msg) {
+        void _;
+      }
+    }).rejects.toThrow(APIConnectionError);
+
+    // Verify the message is preserved
+    await expect(async () => {
+      async function* failingStream2(): AsyncGenerator<never> {
+        throw new OpenAIAPIError(undefined, undefined, 'Network connection lost.', undefined);
+        yield undefined as never;
+      }
+      const msg2 = new OpenAILegacyStreamedMessage(
+        failingStream2() as AsyncIterable<never>,
+        true,
+        undefined,
+      );
+      for await (const _ of msg2) {
+        void _;
+      }
+    }).rejects.toThrow(/Network connection lost/);
+  });
+});
+describe('convertContentPart', () => {
+  it('converts TextPart to OpenAI text content part', () => {
+    expect(convertContentPart({ type: 'text', text: 'hi' })).toEqual({
+      type: 'text',
+      text: 'hi',
+    });
+  });
+
+  it('returns null for ThinkPart (handled separately as reasoning_content)', () => {
+    expect(convertContentPart({ type: 'think', think: 'reasoning' })).toBeNull();
+  });
+
+  it('converts ImageURLPart without id', () => {
+    expect(
+      convertContentPart({ type: 'image_url', imageUrl: { url: 'https://ex/img.png' } }),
+    ).toEqual({ type: 'image_url', image_url: { url: 'https://ex/img.png' } });
+  });
+
+  it('converts ImageURLPart with id', () => {
+    expect(
+      convertContentPart({
+        type: 'image_url',
+        imageUrl: { url: 'https://ex/img.png', id: 'img-1' },
+      }),
+    ).toEqual({ type: 'image_url', image_url: { url: 'https://ex/img.png', id: 'img-1' } });
+  });
+
+  it('converts AudioURLPart without id', () => {
+    expect(
+      convertContentPart({ type: 'audio_url', audioUrl: { url: 'https://ex/a.mp3' } }),
+    ).toEqual({ type: 'audio_url', audio_url: { url: 'https://ex/a.mp3' } });
+  });
+
+  it('converts AudioURLPart with id', () => {
+    expect(
+      convertContentPart({
+        type: 'audio_url',
+        audioUrl: { url: 'https://ex/a.mp3', id: 'a-1' },
+      }),
+    ).toEqual({ type: 'audio_url', audio_url: { url: 'https://ex/a.mp3', id: 'a-1' } });
+  });
+
+  it('converts VideoURLPart without id', () => {
+    expect(
+      convertContentPart({ type: 'video_url', videoUrl: { url: 'https://ex/v.mp4' } }),
+    ).toEqual({ type: 'video_url', video_url: { url: 'https://ex/v.mp4' } });
+  });
+
+  it('converts VideoURLPart with id', () => {
+    expect(
+      convertContentPart({
+        type: 'video_url',
+        videoUrl: { url: 'https://ex/v.mp4', id: 'v-1' },
+      }),
+    ).toEqual({ type: 'video_url', video_url: { url: 'https://ex/v.mp4', id: 'v-1' } });
+  });
+
+  it('throws on unknown content part type', () => {
+    // Force an invalid type to exercise the defensive branch.
+    const bogus = { type: 'bogus', text: 'x' } as unknown as ContentPart;
+    expect(() => convertContentPart(bogus)).toThrow(/Unknown content part type/);
+  });
+});
+describe('thinkingEffortToReasoningEffort', () => {
+  it('maps off -> undefined', () => {
+    expect(thinkingEffortToReasoningEffort('off')).toBeUndefined();
+  });
+  it('maps low -> "low"', () => {
+    expect(thinkingEffortToReasoningEffort('low')).toBe('low');
+  });
+  it('maps medium -> "medium"', () => {
+    expect(thinkingEffortToReasoningEffort('medium')).toBe('medium');
+  });
+  it('maps high -> "high"', () => {
+    expect(thinkingEffortToReasoningEffort('high')).toBe('high');
+  });
+  it('maps xhigh -> "xhigh"', () => {
+    expect(thinkingEffortToReasoningEffort('xhigh')).toBe('xhigh');
+  });
+  it('maps max -> "xhigh"', () => {
+    expect(thinkingEffortToReasoningEffort('max')).toBe('xhigh');
+  });
+  it('throws on unknown effort', () => {
+    expect(() => thinkingEffortToReasoningEffort('extreme' as never)).toThrow(
+      /Unknown thinking effort/,
+    );
+  });
+});
+describe('reasoningEffortToThinkingEffort', () => {
+  it('returns null for undefined', () => {
+    const effort: string | undefined = undefined;
+    expect(reasoningEffortToThinkingEffort(effort)).toBeNull();
+  });
+  it('maps "low" -> low', () => {
+    expect(reasoningEffortToThinkingEffort('low')).toBe('low');
+  });
+  it('maps "minimal" -> low (alias)', () => {
+    expect(reasoningEffortToThinkingEffort('minimal')).toBe('low');
+  });
+  it('maps "medium" -> medium', () => {
+    expect(reasoningEffortToThinkingEffort('medium')).toBe('medium');
+  });
+  it('maps "high" -> high', () => {
+    expect(reasoningEffortToThinkingEffort('high')).toBe('high');
+  });
+  it('maps "xhigh" -> xhigh', () => {
+    expect(reasoningEffortToThinkingEffort('xhigh')).toBe('xhigh');
+  });
+  it('maps "max" -> xhigh (alias)', () => {
+    expect(reasoningEffortToThinkingEffort('max')).toBe('xhigh');
+  });
+  it('maps "none" -> off', () => {
+    expect(reasoningEffortToThinkingEffort('none')).toBe('off');
+  });
+  it('unknown values fall back to off', () => {
+    expect(reasoningEffortToThinkingEffort('ultra')).toBe('off');
+  });
+});
+describe('convertOpenAIError: non-Error values', () => {
+  it('wraps a plain string as ChatProviderError', () => {
+    const result = convertOpenAIError('something went sideways');
+    expect(result.constructor).toBe(ChatProviderError);
+    expect(result.message).toContain('something went sideways');
+  });
+
+  it('wraps a plain Error as ChatProviderError', () => {
+    const result = convertOpenAIError(new Error('plain error'));
+    expect(result.constructor).toBe(ChatProviderError);
+    expect(result.message).toContain('plain error');
+  });
+});
diff --git a/packages/kosong/test/openai-legacy.test.ts b/packages/kosong/test/openai-legacy.test.ts
new file mode 100644
index 000000000..1738c6a43
--- /dev/null
+++ b/packages/kosong/test/openai-legacy.test.ts
@@ -0,0 +1,1218 @@
+import { generate } from '#/generate';
+import type { ContentPart, Message, StreamedMessagePart, ToolCall } from '#/message';
+import { OpenAILegacyChatProvider } from '#/providers/openai-legacy';
+import type { Tool } from '#/tool';
+import { describe, it, expect, vi } from 'vitest';
+
+function makeChatCompletionResponse(model: string = 'test-model') {
+  return {
+    id: 'chatcmpl-test123',
+    object: 'chat.completion',
+    created: 1234567890,
+    model,
+    choices: [
+      {
+        index: 0,
+        message: { role: 'assistant', content: 'Hello' },
+        finish_reason: 'stop',
+      },
+    ],
+    usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+  };
+}
+
+function createProvider(
+  options?: Partial<{
+    stream: boolean;
+    reasoningKey: string;
+    model: string;
+  }>,
+): OpenAILegacyChatProvider {
+  return new OpenAILegacyChatProvider({
+    model: options?.model ?? 'gpt-4.1',
+    apiKey: 'test-key',
+    stream: options?.stream ?? false,
+    reasoningKey: options?.reasoningKey,
+  });
+}
+
+/** Capture the request body sent to OpenAI by mocking the client. */
+async function captureRequestBody(
+  provider: OpenAILegacyChatProvider,
+  systemPrompt: string,
+  tools: Tool[],
+  history: Message[],
+): Promise<Record<string, unknown>> {
+  let capturedBody: Record<string, unknown> | undefined;
+
+  (provider as any)._client.chat.completions.create = vi
+    .fn()
+    .mockImplementation((params: unknown) => {
+      capturedBody = params as Record<string, unknown>;
+      return Promise.resolve(makeChatCompletionResponse());
+    });
+
+  const stream = await provider.generate(systemPrompt, tools, history);
+  for await (const part of stream) {
+    void part;
+  }
+
+  if (capturedBody === undefined) {
+    throw new Error('Expected provider.generate() to call chat.completions.create');
+  }
+  return capturedBody;
+}
+
+const ADD_TOOL: Tool = {
+  name: 'add',
+  description: 'Add two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+const MUL_TOOL: Tool = {
+  name: 'multiply',
+  description: 'Multiply two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+describe('OpenAILegacyChatProvider', () => {
+  describe('message conversion (COMMON_CASES)', () => {
+    it('simple user message with system prompt', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hello!' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, 'You are helpful.', [], history);
+
+      expect(body['messages']).toEqual([
+        { role: 'system', content: 'You are helpful.' },
+        { role: 'user', content: 'Hello!' },
+      ]);
+      expect(body['tools']).toBeUndefined();
+    });
+
+    it('multi-turn conversation', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        { role: 'assistant', content: [{ type: 'text', text: '2+2 equals 4.' }], toolCalls: [] },
+        { role: 'user', content: [{ type: 'text', text: 'And 3+3?' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['messages']).toEqual([
+        { role: 'user', content: 'What is 2+2?' },
+        { role: 'assistant', content: '2+2 equals 4.' },
+        { role: 'user', content: 'And 3+3?' },
+      ]);
+    });
+
+    it('multi-turn with system prompt', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        { role: 'assistant', content: [{ type: 'text', text: '2+2 equals 4.' }], toolCalls: [] },
+        { role: 'user', content: [{ type: 'text', text: 'And 3+3?' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, 'You are a math tutor.', [], history);
+
+      expect(body['messages']).toEqual([
+        { role: 'system', content: 'You are a math tutor.' },
+        { role: 'user', content: 'What is 2+2?' },
+        { role: 'assistant', content: '2+2 equals 4.' },
+        { role: 'user', content: 'And 3+3?' },
+      ]);
+    });
+
+    it('image url content', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: "What's in this image?" },
+            { type: 'image_url', imageUrl: { url: 'https://example.com/image.png' } },
+          ] satisfies ContentPart[],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['messages']).toEqual([
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: "What's in this image?" },
+            { type: 'image_url', image_url: { url: 'https://example.com/image.png' } },
+          ],
+        },
+      ]);
+    });
+
+    it('tool definitions', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL, MUL_TOOL], history);
+
+      expect(body['tools']).toEqual([
+        {
+          type: 'function',
+          function: {
+            name: 'add',
+            description: 'Add two integers.',
+            parameters: {
+              type: 'object',
+              properties: {
+                a: { type: 'integer', description: 'First number' },
+                b: { type: 'integer', description: 'Second number' },
+              },
+              required: ['a', 'b'],
+            },
+          },
+        },
+        {
+          type: 'function',
+          function: {
+            name: 'multiply',
+            description: 'Multiply two integers.',
+            parameters: {
+              type: 'object',
+              properties: {
+                a: { type: 'integer', description: 'First number' },
+                b: { type: 'integer', description: 'Second number' },
+              },
+              required: ['a', 'b'],
+            },
+          },
+        },
+      ]);
+    });
+
+    it('tool call and tool result', async () => {
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_abc123',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll add those numbers for you." }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '5' }],
+          toolCallId: 'call_abc123',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['messages']).toEqual([
+        { role: 'user', content: 'Add 2 and 3' },
+        {
+          role: 'assistant',
+          content: "I'll add those numbers for you.",
+          tool_calls: [
+            {
+              type: 'function',
+              id: 'call_abc123',
+              function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+            },
+          ],
+        },
+        { role: 'tool', content: '5', tool_call_id: 'call_abc123' },
+      ]);
+    });
+
+    it('tool call with image result flattens to text to satisfy API constraints', async () => {
+      // OpenAI Chat Completions `tool` messages only accept text content.
+      // Even when toolMessageConversion is unset, a tool result containing
+      // image_url / audio_url / video_url parts must not be serialized as a
+      // multimodal array — the API would reject the request with a 400.
+      // The provider is expected to force `extract_text` in that case.
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_abc123',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll add those numbers for you." }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: '5' },
+            { type: 'image_url', imageUrl: { url: 'https://example.com/image.png' } },
+          ] satisfies ContentPart[],
+          toolCallId: 'call_abc123',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const toolMsg = (body['messages'] as Record<string, unknown>[])[2]!;
+      expect(toolMsg['role']).toBe('tool');
+      expect(toolMsg['tool_call_id']).toBe('call_abc123');
+      // Content must be a plain string, not a content-part array.
+      expect(typeof toolMsg['content']).toBe('string');
+      // The text segment must survive; the image must not appear as a
+      // structured image_url part anywhere in the serialized content.
+      expect(toolMsg['content']).toContain('5');
+      expect(Array.isArray(toolMsg['content'])).toBe(false);
+    });
+
+    it('parallel tool calls', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Calculate 2+3 and 4*5' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll calculate both." }],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_add',
+              function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+            },
+            {
+              type: 'function',
+              id: 'call_mul',
+              function: { name: 'multiply', arguments: '{"a": 4, "b": 5}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: '<system-reminder>This is a system reminder</system-reminder>' },
+            { type: 'text', text: '5' },
+          ],
+          toolCallId: 'call_add',
+          toolCalls: [],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: '<system-reminder>This is a system reminder</system-reminder>' },
+            { type: 'text', text: '20' },
+          ],
+          toolCallId: 'call_mul',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL, MUL_TOOL], history);
+
+      // Snapshot of the expected wire format:
+      // - 4 messages in order: user, assistant (with 2 tool_calls), tool (call_add), tool (call_mul)
+      // - user / assistant use compressed string content (single-TextPart compression)
+      // - both tool messages preserve multi-part content arrays (not compressed)
+      // - tools array preserved
+      expect(body['messages']).toEqual([
+        { role: 'user', content: 'Calculate 2+3 and 4*5' },
+        {
+          role: 'assistant',
+          content: "I'll calculate both.",
+          tool_calls: [
+            {
+              type: 'function',
+              id: 'call_add',
+              function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+            },
+            {
+              type: 'function',
+              id: 'call_mul',
+              function: { name: 'multiply', arguments: '{"a": 4, "b": 5}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          content: [
+            {
+              type: 'text',
+              text: '<system-reminder>This is a system reminder</system-reminder>',
+            },
+            { type: 'text', text: '5' },
+          ],
+          tool_call_id: 'call_add',
+        },
+        {
+          role: 'tool',
+          content: [
+            {
+              type: 'text',
+              text: '<system-reminder>This is a system reminder</system-reminder>',
+            },
+            { type: 'text', text: '20' },
+          ],
+          tool_call_id: 'call_mul',
+        },
+      ]);
+      expect(body['tools']).toHaveLength(2);
+    });
+  });
+
+  describe('reasoning content', () => {
+    it('converts ThinkPart to configured reasoning key', async () => {
+      const provider = createProvider({ reasoningKey: 'reasoning_content' });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'think', think: 'Thinking...' },
+            { type: 'text', text: '4.' },
+          ],
+          toolCalls: [],
+        },
+        { role: 'user', content: [{ type: 'text', text: 'Thanks!' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['messages']).toEqual([
+        { role: 'user', content: 'What is 2+2?' },
+        {
+          role: 'assistant',
+          content: '4.',
+          reasoning_content: 'Thinking...',
+        },
+        { role: 'user', content: 'Thanks!' },
+      ]);
+    });
+  });
+
+  describe('generation kwargs', () => {
+    it('applies temperature and max_tokens', async () => {
+      const provider = createProvider().withGenerationKwargs({
+        temperature: 0.7,
+        max_tokens: 2048,
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['temperature']).toBe(0.7);
+      expect(body['max_tokens']).toBe(2048);
+    });
+  });
+
+  describe('maxTokens option', () => {
+    it('wires OpenAILegacyOptions.maxTokens into the request body as max_tokens', async () => {
+      const provider = new OpenAILegacyChatProvider({
+        model: 'gpt-4.1',
+        apiKey: 'test-key',
+        stream: false,
+        maxTokens: 1024,
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      expect(body['max_tokens']).toBe(1024);
+    });
+
+    it('does not inject max_tokens when maxTokens option is omitted', async () => {
+      const provider = new OpenAILegacyChatProvider({
+        model: 'gpt-4.1',
+        apiKey: 'test-key',
+        stream: false,
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      expect(body['max_tokens']).toBeUndefined();
+    });
+
+    it('exposes max_tokens via modelParameters', () => {
+      const provider = new OpenAILegacyChatProvider({
+        model: 'gpt-4.1',
+        apiKey: 'test-key',
+        maxTokens: 2048,
+      });
+      expect(provider.modelParameters['max_tokens']).toBe(2048);
+    });
+  });
+
+  describe('toolMessageConversion option', () => {
+    it('flattens tool message content to a string when set to extract_text', async () => {
+      const provider = new OpenAILegacyChatProvider({
+        model: 'gpt-4.1',
+        apiKey: 'test-key',
+        stream: false,
+        toolMessageConversion: 'extract_text',
+      });
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_abc123',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll add them." }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: 'part-1' },
+            { type: 'text', text: 'part-2' },
+          ],
+          toolCallId: 'call_abc123',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      const messages = body['messages'] as Record<string, unknown>[];
+      const toolMsg = messages[2]!;
+      expect(toolMsg['role']).toBe('tool');
+      // With extract_text, content must be a plain string (concatenated text),
+      // not an array of content parts.
+      expect(typeof toolMsg['content']).toBe('string');
+      expect(toolMsg['content']).toBe('part-1part-2');
+    });
+
+    it('forces string content when tool result contains audio_url even with default conversion', async () => {
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_audio',
+        function: { name: 'fetch_audio', arguments: '{}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Play it' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'ok' }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: 'audio result' },
+            { type: 'audio_url', audioUrl: { url: 'https://example.com/a.mp3' } },
+          ] satisfies ContentPart[],
+          toolCallId: 'call_audio',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      const toolMsg = (body['messages'] as Record<string, unknown>[])[2]!;
+      expect(typeof toolMsg['content']).toBe('string');
+    });
+
+    it('forces string content when tool result contains video_url even with default conversion', async () => {
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_video',
+        function: { name: 'fetch_video', arguments: '{}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Show it' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'ok' }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: 'video result' },
+            { type: 'video_url', videoUrl: { url: 'https://example.com/v.mp4' } },
+          ] satisfies ContentPart[],
+          toolCallId: 'call_video',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      const toolMsg = (body['messages'] as Record<string, unknown>[])[2]!;
+      expect(typeof toolMsg['content']).toBe('string');
+    });
+
+    it('keeps default text-only tool message as plain string', async () => {
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_text',
+        function: { name: 'add', arguments: '{"a":1,"b":2}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 1 2' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'ok' }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '3' }],
+          toolCallId: 'call_text',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      const toolMsg = (body['messages'] as Record<string, unknown>[])[2]!;
+      // Single-text tool result with default conversion stays as a plain string.
+      expect(toolMsg['content']).toBe('3');
+    });
+
+    it('preserves default tool message content as array when option is omitted', async () => {
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_abc123',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll add them." }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: 'part-1' },
+            { type: 'text', text: 'part-2' },
+          ],
+          toolCallId: 'call_abc123',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      const messages = body['messages'] as Record<string, unknown>[];
+      const toolMsg = messages[2]!;
+      // Default behavior: two text parts stay as a content-part array.
+      expect(Array.isArray(toolMsg['content'])).toBe(true);
+    });
+  });
+
+  describe('with thinking', () => {
+    it('.withThinking("high") sets reasoning_effort', async () => {
+      const provider = createProvider().withThinking('high');
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['reasoning_effort']).toBe('high');
+    });
+  });
+
+  describe('auto reasoning_effort', () => {
+    it('auto-injects reasoning_effort when history has ThinkPart and reasoningKey is set', async () => {
+      const provider = createProvider({
+        model: 'kimi-k2.5',
+        reasoningKey: 'reasoning_content',
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hello' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'think', think: 'Let me think...' },
+            { type: 'text', text: 'Hi!' },
+          ],
+          toolCalls: [],
+        },
+        { role: 'user', content: [{ type: 'text', text: 'How are you?' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      // reasoning_effort should be auto-set because history contains ThinkPart
+      expect(body['reasoning_effort']).toBe('medium');
+      // reasoning_content should still be present in the message
+      const messages = body['messages'] as Record<string, unknown>[];
+      expect(messages[1]!['reasoning_content']).toBe('Let me think...');
+    });
+
+    it('does not auto-inject reasoning_effort when history has no ThinkPart', async () => {
+      const provider = createProvider({
+        model: 'kimi-k2.5',
+        reasoningKey: 'reasoning_content',
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hello' }], toolCalls: [] },
+        { role: 'assistant', content: [{ type: 'text', text: 'Hi!' }], toolCalls: [] },
+        { role: 'user', content: [{ type: 'text', text: 'How are you?' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['reasoning_effort']).toBeUndefined();
+    });
+
+    it('does not auto-inject reasoning_effort when reasoningKey is not set', async () => {
+      // No reasoningKey configured
+      const provider = createProvider({ model: 'some-model' });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hello' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'think', think: 'Thinking...' },
+            { type: 'text', text: 'Hi!' },
+          ],
+          toolCalls: [],
+        },
+        { role: 'user', content: [{ type: 'text', text: 'How are you?' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['reasoning_effort']).toBeUndefined();
+    });
+  });
+
+  // OpenAI Chat Completions streams parallel tool calls with interleaved
+  // argument deltas. Each delta carries `index` to identify the owning
+  // tool call. The provider must preserve `index` on the yielded
+  // ToolCallPart (and `_streamIndex` on the ToolCall header) so that
+  // generate() can route deltas correctly.
+
+  interface MockToolCallDelta {
+    index: number;
+    id?: string;
+    function?: { name?: string; arguments?: string };
+  }
+
+  function makeChunk(
+    toolCalls: MockToolCallDelta[],
+    opts?: { finishReason?: string; usage?: boolean },
+  ): Record<string, unknown> {
+    const chunk: Record<string, unknown> = {
+      id: 'chatcmpl-parallel',
+      object: 'chat.completion.chunk',
+      created: 1234567890,
+      model: 'gpt-4.1',
+      choices: [
+        {
+          index: 0,
+          delta: { tool_calls: toolCalls },
+          finish_reason: opts?.finishReason ?? null,
+        },
+      ],
+    };
+    if (opts?.usage) {
+      chunk['usage'] = { prompt_tokens: 10, completion_tokens: 20, total_tokens: 30 };
+    }
+    return chunk;
+  }
+
+  async function* mockStream(
+    chunks: Record<string, unknown>[],
+  ): AsyncIterable<Record<string, unknown>> {
+    for (const c of chunks) {
+      yield c;
+    }
+  }
+
+  it('routes interleaved parallel tool_call arguments by streaming index', async () => {
+    const provider = new OpenAILegacyChatProvider({
+      model: 'gpt-4.1',
+      apiKey: 'test-key',
+      stream: true,
+    });
+
+    // Interleave argument deltas across index 0 and 1. In the real
+    // pre-fix code these deltas would all pile onto whichever tool call
+    // was "most recently pending", corrupting both sets of arguments.
+    const chunks = [
+      makeChunk([{ index: 0, id: 'call_a', function: { name: 'read_file', arguments: '' } }]),
+      makeChunk([{ index: 1, id: 'call_b', function: { name: 'write_file', arguments: '' } }]),
+      makeChunk([{ index: 0, function: { arguments: '{"path":"' } }]),
+      makeChunk([{ index: 1, function: { arguments: '{"path":"' } }]),
+      makeChunk([{ index: 0, function: { arguments: '/a.txt"' } }]),
+      makeChunk([{ index: 1, function: { arguments: '/b.txt","content":"hi"' } }]),
+      makeChunk([{ index: 0, function: { arguments: '}' } }]),
+      makeChunk([{ index: 1, function: { arguments: '}' } }]),
+      makeChunk([], { finishReason: 'tool_calls', usage: true }),
+    ];
+
+    (
+      provider as unknown as { _client: { chat: { completions: { create: unknown } } } }
+    )._client.chat.completions.create = vi.fn().mockResolvedValue(mockStream(chunks));
+
+    const result = await generate(
+      provider,
+      '',
+      [],
+      [{ role: 'user', content: [{ type: 'text', text: 'do it' }], toolCalls: [] }],
+    );
+
+    expect(result.message.toolCalls).toEqual([
+      {
+        type: 'function',
+        id: 'call_a',
+        function: { name: 'read_file', arguments: '{"path":"/a.txt"}' },
+      },
+      {
+        type: 'function',
+        id: 'call_b',
+        function: { name: 'write_file', arguments: '{"path":"/b.txt","content":"hi"}' },
+      },
+    ]);
+
+    // _streamIndex must not leak into the stored ToolCall shape.
+    for (const tc of result.message.toolCalls) {
+      expect(tc).not.toHaveProperty('_streamIndex');
+    }
+  });
+
+  it('does not early-ready indexed OpenAI tool calls at merge boundaries', async () => {
+    const provider = new OpenAILegacyChatProvider({
+      model: 'gpt-4.1',
+      apiKey: 'test-key',
+      stream: true,
+    });
+
+    // OpenAI Chat Completions can legally send a later delta for an earlier
+    // tool_call.index after another indexed tool call has started. A provider
+    // without an explicit done signal must not mark index 0 ready merely
+    // because its current arguments happen to parse at that boundary.
+    const chunks = [
+      makeChunk([{ index: 0, id: 'call_a', function: { name: 'read_file', arguments: '' } }]),
+      makeChunk([{ index: 0, function: { arguments: '{"path":"a.txt"}' } }]),
+      makeChunk([{ index: 1, id: 'call_b', function: { name: 'read_file', arguments: '' } }]),
+      makeChunk([{ index: 0, function: { arguments: ' ' } }]),
+      makeChunk([{ index: 1, function: { arguments: '{"path":"b.txt"}' } }]),
+      makeChunk([], { finishReason: 'tool_calls', usage: true }),
+    ];
+
+    (
+      provider as unknown as { _client: { chat: { completions: { create: unknown } } } }
+    )._client.chat.completions.create = vi.fn().mockResolvedValue(mockStream(chunks));
+
+    const events: string[] = [];
+    const result = await generate(
+      provider,
+      '',
+      [],
+      [{ role: 'user', content: [{ type: 'text', text: 'do it' }], toolCalls: [] }],
+      {
+        onMessagePart(part: StreamedMessagePart): void {
+          if (part.type === 'tool_call_part') {
+            events.push(`part:${part.index}:${part.argumentsPart}`);
+          }
+        },
+        onToolCall(toolCall: ToolCall): void {
+          events.push(`ready:${toolCall.id}:${toolCall.function.arguments ?? ''}`);
+        },
+      },
+    );
+
+    // onToolCall fires after stream drains, in final order.
+    expect(events).toEqual([
+      'part:0:{"path":"a.txt"}',
+      'part:0: ',
+      'part:1:{"path":"b.txt"}',
+      'ready:call_a:{"path":"a.txt"} ',
+      'ready:call_b:{"path":"b.txt"}',
+    ]);
+    expect(result.message.toolCalls).toEqual([
+      {
+        type: 'function',
+        id: 'call_a',
+        function: { name: 'read_file', arguments: '{"path":"a.txt"} ' },
+      },
+      {
+        type: 'function',
+        id: 'call_b',
+        function: { name: 'read_file', arguments: '{"path":"b.txt"}' },
+      },
+    ]);
+  });
+
+  it('preserves index on ToolCallPart when streaming single tool call', async () => {
+    // Single-tool-call path: verify `index` is present on yielded parts
+    // so generate() can still use the map-based routing if it chooses.
+    const provider = new OpenAILegacyChatProvider({
+      model: 'gpt-4.1',
+      apiKey: 'test-key',
+      stream: true,
+    });
+
+    const chunks = [
+      makeChunk([{ index: 0, id: 'call_x', function: { name: 'f', arguments: '' } }]),
+      makeChunk([{ index: 0, function: { arguments: '{"a":' } }]),
+      makeChunk([{ index: 0, function: { arguments: '1}' } }]),
+      makeChunk([], { finishReason: 'tool_calls', usage: true }),
+    ];
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (provider as any)._client.chat.completions.create = vi
+      .fn()
+      .mockResolvedValue(mockStream(chunks));
+
+    const stream = await provider.generate(
+      '',
+      [],
+      [{ role: 'user', content: [{ type: 'text', text: 'x' }], toolCalls: [] }],
+    );
+
+    const parts: StreamedMessagePart[] = [];
+    for await (const part of stream) {
+      parts.push(part);
+    }
+
+    const header = parts.find((p) => p.type === 'function') as
+      | (ToolCall & { _streamIndex?: number | string })
+      | undefined;
+    expect(header).toMatchObject({ _streamIndex: 0 });
+
+    const partDeltas = parts.filter((p) => p.type === 'tool_call_part');
+    expect(partDeltas.length).toBeGreaterThan(0);
+    for (const p of partDeltas) {
+      expect((p as { index?: number | string }).index).toBe(0);
+    }
+  });
+
+  it('buffers indexed argument deltas until the real tool name arrives', async () => {
+    const provider = new OpenAILegacyChatProvider({
+      model: 'gpt-4.1',
+      apiKey: 'test-key',
+      stream: true,
+    });
+
+    const chunks = [
+      makeChunk([{ index: 0, id: 'call_delayed', function: { name: '', arguments: '' } }]),
+      makeChunk([{ index: 0, function: { arguments: '{"a' } }]),
+      makeChunk([{ index: 0, function: { name: 'foo' } }]),
+      makeChunk([{ index: 0, function: { arguments: '":1}' } }]),
+      makeChunk([], { finishReason: 'tool_calls', usage: true }),
+    ];
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (provider as any)._client.chat.completions.create = vi
+      .fn()
+      .mockResolvedValue(mockStream(chunks));
+
+    const result = await generate(
+      provider,
+      '',
+      [],
+      [{ role: 'user', content: [{ type: 'text', text: 'do it' }], toolCalls: [] }],
+    );
+
+    expect(result.message.toolCalls).toEqual([
+      {
+        type: 'function',
+        id: 'call_delayed',
+        function: { name: 'foo', arguments: '{"a":1}' },
+      },
+    ]);
+  });
+});
+
+describe('OpenAILegacyChatProvider — non-stream response parsing', () => {
+  function makeNonStreamResponse(message: Record<string, unknown>): Record<string, unknown> {
+    return {
+      id: 'chatcmpl-test123',
+      object: 'chat.completion',
+      created: 1234567890,
+      model: 'gpt-4.1',
+      choices: [{ index: 0, message, finish_reason: 'stop' }],
+      usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+    };
+  }
+
+  async function collectFromMockedResponse(
+    provider: OpenAILegacyChatProvider,
+    response: Record<string, unknown>,
+  ): Promise<StreamedMessagePart[]> {
+    (provider as any)._client.chat.completions.create = vi.fn().mockResolvedValue(response);
+
+    const stream = await provider.generate(
+      '',
+      [],
+      [{ role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] }],
+    );
+    const parts: StreamedMessagePart[] = [];
+    for await (const part of stream) parts.push(part);
+    return parts;
+  }
+
+  it('yields ThinkPart from non-stream response when reasoningKey content is present', async () => {
+    const provider = new OpenAILegacyChatProvider({
+      model: 'deepseek-reasoner',
+      apiKey: 'test-key',
+      stream: false,
+      reasoningKey: 'reasoning_content',
+    });
+
+    const parts = await collectFromMockedResponse(
+      provider,
+      makeNonStreamResponse({
+        role: 'assistant',
+        content: 'Final answer',
+        reasoning_content: 'Some thinking here.',
+      }),
+    );
+
+    expect(parts).toEqual([
+      { type: 'think', think: 'Some thinking here.' },
+      { type: 'text', text: 'Final answer' },
+    ]);
+  });
+
+  it('non-stream response yields ToolCall parts when tool_calls present', async () => {
+    const provider = new OpenAILegacyChatProvider({
+      model: 'gpt-4.1',
+      apiKey: 'test-key',
+      stream: false,
+    });
+
+    const parts = await collectFromMockedResponse(
+      provider,
+      makeNonStreamResponse({
+        role: 'assistant',
+        content: null,
+        tool_calls: [
+          {
+            id: 'call_x',
+            type: 'function',
+            function: { name: 'lookup', arguments: '{"q":"hi"}' },
+          },
+        ],
+      }),
+    );
+
+    const toolCall = parts.find((p) => p.type === 'function');
+    expect(toolCall).toMatchObject({
+      type: 'function',
+      id: 'call_x',
+      function: { name: 'lookup', arguments: '{"q":"hi"}' },
+    });
+  });
+
+  it('non-stream response generates a fresh ID when tool_call has no id', async () => {
+    const provider = new OpenAILegacyChatProvider({
+      model: 'gpt-4.1',
+      apiKey: 'test-key',
+      stream: false,
+    });
+
+    const parts = await collectFromMockedResponse(
+      provider,
+      makeNonStreamResponse({
+        role: 'assistant',
+        content: null,
+        tool_calls: [
+          {
+            type: 'function',
+            function: { name: 'lookup', arguments: '{}' },
+          },
+        ],
+      }),
+    );
+
+    const toolCall = parts.find((p) => p.type === 'function');
+    expect(toolCall).toMatchObject({
+      type: 'function',
+      id: expect.stringMatching(/.+/),
+    });
+  });
+
+  it('non-stream response yields reasoning_content as ThinkPart', async () => {
+    const provider = new OpenAILegacyChatProvider({
+      model: 'deepseek-reasoner',
+      apiKey: 'test-key',
+      stream: false,
+      reasoningKey: 'reasoning_content',
+    });
+
+    const parts = await collectFromMockedResponse(
+      provider,
+      makeNonStreamResponse({
+        role: 'assistant',
+        content: 'Final answer',
+        reasoning_content: 'Let me think step by step',
+      }),
+    );
+
+    expect(parts).toEqual([
+      { type: 'think', think: 'Let me think step by step' },
+      { type: 'text', text: 'Final answer' },
+    ]);
+  });
+});
+
+describe('OpenAILegacyChatProvider — non-indexed streaming tool_calls', () => {
+  async function* mockStream(
+    chunks: Record<string, unknown>[],
+  ): AsyncIterable<Record<string, unknown>> {
+    for (const c of chunks) yield c;
+  }
+
+  it('handles non-indexed tool_call delta with concrete name', async () => {
+    const provider = new OpenAILegacyChatProvider({
+      model: 'gpt-4.1',
+      apiKey: 'test-key',
+      stream: true,
+    });
+
+    const chunks = [
+      {
+        id: 'chatcmpl-noidx',
+        choices: [
+          {
+            index: 0,
+            delta: {
+              tool_calls: [
+                {
+                  id: 'call_noidx',
+                  function: { name: 'foo', arguments: '{"a":1}' },
+                  // No index!
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ];
+
+    (
+      provider as unknown as { _client: { chat: { completions: { create: unknown } } } }
+    )._client.chat.completions.create = vi.fn().mockResolvedValue(mockStream(chunks));
+
+    const result = await generate(
+      provider,
+      '',
+      [],
+      [{ role: 'user', content: [{ type: 'text', text: 'do' }], toolCalls: [] }],
+    );
+
+    expect(result.message.toolCalls).toEqual([
+      {
+        type: 'function',
+        id: 'call_noidx',
+        function: { name: 'foo', arguments: '{"a":1}' },
+      },
+    ]);
+  });
+
+  it('handles non-indexed tool_call delta with arguments only emits tool_call_part', async () => {
+    const provider = new OpenAILegacyChatProvider({
+      model: 'gpt-4.1',
+      apiKey: 'test-key',
+      stream: true,
+    });
+
+    const chunks = [
+      {
+        id: 'chatcmpl-argonly',
+        choices: [
+          {
+            index: 0,
+            delta: {
+              tool_calls: [{ function: { arguments: '{"x":1}' } }],
+            },
+          },
+        ],
+      },
+    ];
+
+    (
+      provider as unknown as { _client: { chat: { completions: { create: unknown } } } }
+    )._client.chat.completions.create = vi.fn().mockResolvedValue(mockStream(chunks));
+
+    const stream = await provider.generate('', [], []);
+    const parts: Array<Record<string, unknown>> = [];
+    for await (const p of stream) parts.push(p as unknown as Record<string, unknown>);
+
+    expect(parts).toEqual([{ type: 'tool_call_part', argumentsPart: '{"x":1}' }]);
+  });
+
+  it('handles tool_call delta with no function field (early return)', async () => {
+    const provider = new OpenAILegacyChatProvider({
+      model: 'gpt-4.1',
+      apiKey: 'test-key',
+      stream: true,
+    });
+
+    const chunks = [
+      {
+        id: 'chatcmpl-nofn',
+        choices: [
+          {
+            index: 0,
+            delta: {
+              tool_calls: [{ index: 0 }], // no function field
+            },
+          },
+        ],
+      },
+    ];
+
+    (
+      provider as unknown as { _client: { chat: { completions: { create: unknown } } } }
+    )._client.chat.completions.create = vi.fn().mockResolvedValue(mockStream(chunks));
+
+    const stream = await provider.generate('', [], []);
+    const parts: Array<Record<string, unknown>> = [];
+    for await (const p of stream) parts.push(p as unknown as Record<string, unknown>);
+
+    // No parts yielded — the tool_call without function is silently ignored.
+    expect(parts).toEqual([]);
+  });
+
+  it('handles tool_call delta with null function field (early return)', async () => {
+    const provider = new OpenAILegacyChatProvider({
+      model: 'gpt-4.1',
+      apiKey: 'test-key',
+      stream: true,
+    });
+
+    const chunks = [
+      {
+        id: 'chatcmpl-nullfn',
+        choices: [
+          {
+            index: 0,
+            delta: {
+              tool_calls: [{ index: 0, function: null }],
+            },
+          },
+        ],
+      },
+    ];
+
+    (
+      provider as unknown as { _client: { chat: { completions: { create: unknown } } } }
+    )._client.chat.completions.create = vi.fn().mockResolvedValue(mockStream(chunks));
+
+    const stream = await provider.generate('', [], []);
+    const parts: Array<Record<string, unknown>> = [];
+    for await (const p of stream) parts.push(p as unknown as Record<string, unknown>);
+
+    expect(parts).toEqual([]);
+  });
+});
diff --git a/packages/kosong/test/openai-responses.test.ts b/packages/kosong/test/openai-responses.test.ts
new file mode 100644
index 000000000..1a533deb1
--- /dev/null
+++ b/packages/kosong/test/openai-responses.test.ts
@@ -0,0 +1,1709 @@
+import { ChatProviderError } from '#/errors';
+import { generate } from '#/generate';
+import type { ContentPart, Message, StreamedMessagePart, ToolCall } from '#/message';
+import {
+  OpenAIResponsesChatProvider,
+  OpenAIResponsesStreamedMessage,
+} from '#/providers/openai-responses';
+import type { Tool } from '#/tool';
+import { describe, it, expect, vi } from 'vitest';
+
+function makeResponsesAPIResponse() {
+  return {
+    id: 'resp_test123',
+    object: 'response',
+    created_at: 1234567890,
+    status: 'completed',
+    model: 'gpt-4.1',
+    output: [
+      {
+        type: 'message',
+        id: 'msg_test',
+        role: 'assistant',
+        content: [{ type: 'output_text', text: 'Hello', annotations: [] }],
+      },
+    ],
+    usage: { input_tokens: 10, output_tokens: 5, total_tokens: 15 },
+  };
+}
+
+function createProvider(): OpenAIResponsesChatProvider {
+  return new OpenAIResponsesChatProvider({
+    model: 'gpt-4.1',
+    apiKey: 'test-key',
+  });
+}
+
+/** Capture the request body sent to the Responses API by mocking the client. */
+async function captureRequestBody(
+  provider: OpenAIResponsesChatProvider,
+  systemPrompt: string,
+  tools: Tool[],
+  history: Message[],
+): Promise<Record<string, unknown>> {
+  let capturedBody: Record<string, unknown> | undefined;
+
+  (provider as any)._stream = false;
+
+  ((provider as any)._client.responses as unknown as Record<string, unknown>)['create'] = vi
+    .fn()
+    .mockImplementation((params: unknown) => {
+      capturedBody = params as Record<string, unknown>;
+      return Promise.resolve(makeResponsesAPIResponse());
+    });
+
+  const stream = await provider.generate(systemPrompt, tools, history);
+  for await (const part of stream) {
+    void part;
+  }
+
+  if (capturedBody === undefined) {
+    throw new Error('Expected provider.generate() to call responses.create');
+  }
+  return capturedBody;
+}
+
+const ADD_TOOL: Tool = {
+  name: 'add',
+  description: 'Add two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+const MUL_TOOL: Tool = {
+  name: 'multiply',
+  description: 'Multiply two integers.',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'integer', description: 'First number' },
+      b: { type: 'integer', description: 'Second number' },
+    },
+    required: ['a', 'b'],
+  },
+};
+
+describe('OpenAIResponsesChatProvider', () => {
+  describe('message conversion', () => {
+    it('simple user message with system prompt', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hello!' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, 'You are helpful.', [], history);
+
+      expect(body['input']).toEqual([
+        // gpt-4.1 is an OpenAI model -> developer role
+        { role: 'developer', content: 'You are helpful.' },
+        {
+          content: [{ type: 'input_text', text: 'Hello!' }],
+          role: 'user',
+          type: 'message',
+        },
+      ]);
+      expect(body['tools']).toEqual([]);
+    });
+
+    it('multi-turn conversation', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        { role: 'assistant', content: [{ type: 'text', text: '2+2 equals 4.' }], toolCalls: [] },
+        { role: 'user', content: [{ type: 'text', text: 'And 3+3?' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['input']).toEqual([
+        {
+          content: [{ type: 'input_text', text: 'What is 2+2?' }],
+          role: 'user',
+          type: 'message',
+        },
+        {
+          content: [{ type: 'output_text', text: '2+2 equals 4.', annotations: [] }],
+          role: 'assistant',
+          type: 'message',
+        },
+        {
+          content: [{ type: 'input_text', text: 'And 3+3?' }],
+          role: 'user',
+          type: 'message',
+        },
+      ]);
+    });
+
+    it('multi-turn with system prompt', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        { role: 'assistant', content: [{ type: 'text', text: '2+2 equals 4.' }], toolCalls: [] },
+        { role: 'user', content: [{ type: 'text', text: 'And 3+3?' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, 'You are a math tutor.', [], history);
+
+      expect(body['input']).toEqual([
+        { role: 'developer', content: 'You are a math tutor.' },
+        {
+          content: [{ type: 'input_text', text: 'What is 2+2?' }],
+          role: 'user',
+          type: 'message',
+        },
+        {
+          content: [{ type: 'output_text', text: '2+2 equals 4.', annotations: [] }],
+          role: 'assistant',
+          type: 'message',
+        },
+        {
+          content: [{ type: 'input_text', text: 'And 3+3?' }],
+          role: 'user',
+          type: 'message',
+        },
+      ]);
+    });
+
+    it('image url in user message is encoded as input_image', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: "What's in this image?" },
+            { type: 'image_url', imageUrl: { url: 'https://example.com/image.png' } },
+          ],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['input']).toEqual([
+        {
+          content: [
+            { type: 'input_text', text: "What's in this image?" },
+            {
+              type: 'input_image',
+              detail: 'auto',
+              image_url: 'https://example.com/image.png',
+            },
+          ],
+          role: 'user',
+          type: 'message',
+        },
+      ]);
+    });
+
+    it('OpenAI model name with date suffix matches the partial-prefix branch', async () => {
+      // gpt-4.1-2025-04-14 should be recognized as gpt-4.1, mapping system → developer.
+      const provider = new OpenAIResponsesChatProvider({
+        model: 'gpt-4.1-2025-04-14',
+        apiKey: 'test-key',
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, 'You are helpful.', [], history);
+
+      expect(body['input']).toEqual([
+        { role: 'developer', content: 'You are helpful.' },
+        {
+          content: [{ type: 'input_text', text: 'hi' }],
+          role: 'user',
+          type: 'message',
+        },
+      ]);
+    });
+
+    it('non-OpenAI model name keeps system role unchanged', async () => {
+      const provider = new OpenAIResponsesChatProvider({
+        model: 'some-other-model',
+        apiKey: 'test-key',
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, 'You are helpful.', [], history);
+
+      const input = body['input'] as Array<Record<string, unknown>>;
+      expect(input[0]).toEqual({ role: 'system', content: 'You are helpful.' });
+    });
+
+    it('user message with audio_url data URL (mp3) is encoded as input_file with base64', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'Listen' },
+            { type: 'audio_url', audioUrl: { url: 'data:audio/mp3;base64,QUJD' } },
+          ],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const input = body['input'] as Array<{ content: unknown[] }>;
+      expect(input[0]!.content).toEqual([
+        { type: 'input_text', text: 'Listen' },
+        { type: 'input_file', file_data: 'QUJD', filename: 'inline.mp3' },
+      ]);
+    });
+
+    it('user message with audio_url data URL (wav) is encoded as input_file with wav extension', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [{ type: 'audio_url', audioUrl: { url: 'data:audio/wav;base64,V0FW' } }],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const input = body['input'] as Array<{ content: unknown[] }>;
+      expect(input[0]!.content).toEqual([
+        { type: 'input_file', file_data: 'V0FW', filename: 'inline.wav' },
+      ]);
+    });
+
+    it('user message with audio_url https URL is encoded as input_file with file_url', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [{ type: 'audio_url', audioUrl: { url: 'https://example.com/speech.mp3' } }],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const input = body['input'] as Array<{ content: unknown[] }>;
+      expect(input[0]!.content).toEqual([
+        { type: 'input_file', file_url: 'https://example.com/speech.mp3' },
+      ]);
+    });
+
+    it('user message with unsupported audio_url format drops the audio part silently', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'Bare text' },
+            { type: 'audio_url', audioUrl: { url: 'data:audio/ogg;base64,T0dH' } },
+          ],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const input = body['input'] as Array<{ content: unknown[] }>;
+      // Only the text part survives; the unsupported ogg audio is dropped.
+      expect(input[0]!.content).toEqual([{ type: 'input_text', text: 'Bare text' }]);
+    });
+
+    it('multiple consecutive ThinkParts with the same encrypted value aggregate into one reasoning item with multiple summaries', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Q' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'think', think: 'first thought', encrypted: 'enc_shared' },
+            { type: 'think', think: 'second thought', encrypted: 'enc_shared' },
+            { type: 'think', think: 'third thought', encrypted: 'enc_shared' },
+            { type: 'text', text: 'answer' },
+          ],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const input = body['input'] as Array<Record<string, unknown>>;
+      // After the user message, expect a SINGLE reasoning item with 3 summary_text entries.
+      const reasoningItems = input.filter((item) => item['type'] === 'reasoning');
+      expect(reasoningItems).toHaveLength(1);
+      expect(reasoningItems[0]).toEqual({
+        type: 'reasoning',
+        encrypted_content: 'enc_shared',
+        summary: [
+          { type: 'summary_text', text: 'first thought' },
+          { type: 'summary_text', text: 'second thought' },
+          { type: 'summary_text', text: 'third thought' },
+        ],
+      });
+    });
+
+    it('consecutive ThinkParts with different encrypted values produce separate reasoning items', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Q' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'think', think: 'a', encrypted: 'enc_1' },
+            { type: 'think', think: 'b', encrypted: 'enc_2' },
+            { type: 'text', text: 'done' },
+          ],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const input = body['input'] as Array<Record<string, unknown>>;
+      const reasoningItems = input.filter((item) => item['type'] === 'reasoning');
+      expect(reasoningItems).toHaveLength(2);
+      expect(reasoningItems[0]).toMatchObject({ encrypted_content: 'enc_1' });
+      expect(reasoningItems[1]).toMatchObject({ encrypted_content: 'enc_2' });
+    });
+
+    it('toolMessageConversion=extract_text flattens tool result content to a plain string', async () => {
+      const provider = new OpenAIResponsesChatProvider({
+        model: 'gpt-4.1',
+        apiKey: 'test-key',
+        toolMessageConversion: 'extract_text',
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Q' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_x',
+              function: { name: 'lookup', arguments: '{}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: 'header' },
+            { type: 'text', text: 'body' },
+          ],
+          toolCallId: 'call_x',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const input = body['input'] as Array<Record<string, unknown>>;
+      const fnOutput = input.find((item) => item['type'] === 'function_call_output');
+      expect(fnOutput).toMatchObject({
+        output: expect.stringContaining('header'),
+      });
+      expect(fnOutput).toMatchObject({
+        output: expect.stringContaining('body'),
+      });
+    });
+
+    it('parallel tool calls produce multiple function_call and function_call_output items', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'Calculate 2+3 and 4*5' }],
+          toolCalls: [],
+        },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll calculate both." }],
+          toolCalls: [
+            {
+              type: 'function',
+              id: 'call_add',
+              function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+            },
+            {
+              type: 'function',
+              id: 'call_mul',
+              function: { name: 'multiply', arguments: '{"a": 4, "b": 5}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          content: [
+            {
+              type: 'text',
+              text: '<system-reminder>This is a system reminder</system-reminder>',
+            },
+            { type: 'text', text: '5' },
+          ],
+          toolCallId: 'call_add',
+          toolCalls: [],
+        },
+        {
+          role: 'tool',
+          content: [
+            {
+              type: 'text',
+              text: '<system-reminder>This is a system reminder</system-reminder>',
+            },
+            { type: 'text', text: '20' },
+          ],
+          toolCallId: 'call_mul',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL, MUL_TOOL], history);
+
+      // Snapshot of the expected wire format:
+      // Responses API uses a flat `input[]` array with 6 items:
+      //  [0] user message, [1] assistant text message,
+      //  [2..3] function_call items (NOT bundled into assistant message),
+      //  [4..5] function_call_output items (separate per tool result).
+      // function_call items carry `call_id` (not `id`).
+      expect(body['input']).toEqual([
+        {
+          content: [{ type: 'input_text', text: 'Calculate 2+3 and 4*5' }],
+          role: 'user',
+          type: 'message',
+        },
+        {
+          content: [{ type: 'output_text', text: "I'll calculate both.", annotations: [] }],
+          role: 'assistant',
+          type: 'message',
+        },
+        {
+          arguments: '{"a": 2, "b": 3}',
+          call_id: 'call_add',
+          name: 'add',
+          type: 'function_call',
+        },
+        {
+          arguments: '{"a": 4, "b": 5}',
+          call_id: 'call_mul',
+          name: 'multiply',
+          type: 'function_call',
+        },
+        {
+          call_id: 'call_add',
+          output: [
+            {
+              type: 'input_text',
+              text: '<system-reminder>This is a system reminder</system-reminder>',
+            },
+            { type: 'input_text', text: '5' },
+          ],
+          type: 'function_call_output',
+        },
+        {
+          call_id: 'call_mul',
+          output: [
+            {
+              type: 'input_text',
+              text: '<system-reminder>This is a system reminder</system-reminder>',
+            },
+            { type: 'input_text', text: '20' },
+          ],
+          type: 'function_call_output',
+        },
+      ]);
+      expect(body['tools']).toHaveLength(2);
+    });
+
+    it('tool definitions include strict: false', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [ADD_TOOL, MUL_TOOL], history);
+
+      expect(body['tools']).toEqual([
+        {
+          type: 'function',
+          name: 'add',
+          description: 'Add two integers.',
+          parameters: {
+            type: 'object',
+            properties: {
+              a: { type: 'integer', description: 'First number' },
+              b: { type: 'integer', description: 'Second number' },
+            },
+            required: ['a', 'b'],
+          },
+          strict: false,
+        },
+        {
+          type: 'function',
+          name: 'multiply',
+          description: 'Multiply two integers.',
+          parameters: {
+            type: 'object',
+            properties: {
+              a: { type: 'integer', description: 'First number' },
+              b: { type: 'integer', description: 'Second number' },
+            },
+            required: ['a', 'b'],
+          },
+          strict: false,
+        },
+      ]);
+    });
+
+    it('tool call and tool result', async () => {
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_abc123',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll add those numbers for you." }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [{ type: 'text', text: '5' }],
+          toolCallId: 'call_abc123',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const input = body['input'] as unknown[];
+      // user message
+      expect(input[0]).toEqual({
+        content: [{ type: 'input_text', text: 'Add 2 and 3' }],
+        role: 'user',
+        type: 'message',
+      });
+      // assistant message
+      expect(input[1]).toEqual({
+        content: [
+          {
+            type: 'output_text',
+            text: "I'll add those numbers for you.",
+            annotations: [],
+          },
+        ],
+        role: 'assistant',
+        type: 'message',
+      });
+      // function_call
+      expect(input[2]).toEqual({
+        arguments: '{"a": 2, "b": 3}',
+        call_id: 'call_abc123',
+        name: 'add',
+        type: 'function_call',
+      });
+      // function_call_output
+      expect(input[3]).toEqual({
+        call_id: 'call_abc123',
+        output: [{ type: 'input_text', text: '5' }],
+        type: 'function_call_output',
+      });
+    });
+
+    it('assistant with reasoning (ThinkPart with encrypted)', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'think', think: 'Thinking...', encrypted: 'enc_abc' },
+            { type: 'text', text: '4.' },
+          ],
+          toolCalls: [],
+        },
+        { role: 'user', content: [{ type: 'text', text: 'Thanks!' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      // Snapshot of the expected wire format:
+      // 4 flat input items — ThinkPart with encrypted becomes a standalone
+      // `reasoning` item between the user and assistant message items.
+      expect(body['input']).toEqual([
+        {
+          content: [{ type: 'input_text', text: 'What is 2+2?' }],
+          role: 'user',
+          type: 'message',
+        },
+        {
+          summary: [{ type: 'summary_text', text: 'Thinking...' }],
+          type: 'reasoning',
+          encrypted_content: 'enc_abc',
+        },
+        {
+          content: [{ type: 'output_text', text: '4.', annotations: [] }],
+          role: 'assistant',
+          type: 'message',
+        },
+        {
+          content: [{ type: 'input_text', text: 'Thanks!' }],
+          role: 'user',
+          type: 'message',
+        },
+      ]);
+    });
+
+    it('audio url in tool result is encoded as input_file', async () => {
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_audio',
+        function: { name: 'tts', arguments: '{"text":"hi"}' },
+      };
+      const dataUrl = 'data:audio/mp3;base64,QUJD';
+      const httpsUrl = 'https://example.com/speech.wav';
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Say hi' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: 'done' },
+            { type: 'audio_url', audioUrl: { url: dataUrl } },
+            { type: 'audio_url', audioUrl: { url: httpsUrl } },
+          ] satisfies ContentPart[],
+          toolCallId: 'call_audio',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const input = body['input'] as unknown[];
+      // Locate the function_call_output item.
+      const functionCallOutput = input.find(
+        (item) => (item as Record<string, unknown>)['type'] === 'function_call_output',
+      ) as Record<string, unknown> | undefined;
+      expect(functionCallOutput).toMatchObject({
+        output: [
+          { type: 'input_text', text: 'done' },
+          { type: 'input_file', file_data: 'QUJD', filename: 'inline.mp3' },
+          { type: 'input_file', file_url: httpsUrl },
+        ],
+      });
+    });
+
+    it('image url in tool result', async () => {
+      const provider = createProvider();
+      const toolCall: ToolCall = {
+        type: 'function',
+        id: 'call_abc123',
+        function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+      };
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] },
+        {
+          role: 'assistant',
+          content: [{ type: 'text', text: "I'll add those numbers for you." }],
+          toolCalls: [toolCall],
+        },
+        {
+          role: 'tool',
+          content: [
+            { type: 'text', text: '5' },
+            { type: 'image_url', imageUrl: { url: 'https://example.com/image.png' } },
+          ] satisfies ContentPart[],
+          toolCallId: 'call_abc123',
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const input = body['input'] as unknown[];
+      expect(input[3]).toEqual({
+        call_id: 'call_abc123',
+        output: [
+          { type: 'input_text', text: '5' },
+          { type: 'input_image', image_url: 'https://example.com/image.png' },
+        ],
+        type: 'function_call_output',
+      });
+    });
+  });
+
+  describe('generation kwargs', () => {
+    it('applies temperature and max_output_tokens', async () => {
+      const provider = createProvider().withGenerationKwargs({
+        temperature: 0.7,
+        max_output_tokens: 2048,
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['temperature']).toBe(0.7);
+      expect(body['max_output_tokens']).toBe(2048);
+    });
+  });
+
+  describe('reasoning configuration', () => {
+    it('omits reasoning by default', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['reasoning']).toBeUndefined();
+      expect(body['include']).toBeUndefined();
+    });
+
+    it('with_thinking("off") omits reasoning', async () => {
+      const provider = createProvider().withThinking('off');
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['reasoning']).toBeUndefined();
+      expect(body['include']).toBeUndefined();
+    });
+
+    it('with_thinking("low") sends reasoning with effort=low', async () => {
+      const provider = createProvider().withThinking('low');
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['reasoning']).toEqual({ effort: 'low', summary: 'auto' });
+      expect(body['include']).toEqual(['reasoning.encrypted_content']);
+    });
+
+    it('with_thinking("high") sends reasoning with effort=high', async () => {
+      const provider = createProvider().withThinking('high');
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['reasoning']).toEqual({ effort: 'high', summary: 'auto' });
+      expect(body['include']).toEqual(['reasoning.encrypted_content']);
+    });
+
+    it('with_thinking("xhigh") on gpt-5.1-codex-max passes xhigh through to the wire', async () => {
+      const provider = new OpenAIResponsesChatProvider({
+        model: 'gpt-5.1-codex-max',
+        apiKey: 'test-key',
+      }).withThinking('xhigh');
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect(body['reasoning']).toEqual({ effort: 'xhigh', summary: 'auto' });
+    });
+
+    it('with_thinking("max") on gpt-5.1-codex-max clamps up to xhigh on the wire', async () => {
+      // Regression guard: "max" used to fall back to "high"; for OpenAI it
+      // must clamp up to their highest supported level, xhigh.
+      const provider = new OpenAIResponsesChatProvider({
+        model: 'gpt-5.1-codex-max',
+        apiKey: 'test-key',
+      }).withThinking('max');
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'Think' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      expect((body['reasoning'] as Record<string, unknown>)['effort']).toBe('xhigh');
+    });
+  });
+
+  describe('provider properties', () => {
+    it('has correct name and model', () => {
+      const provider = createProvider();
+      expect(provider.name).toBe('openai-responses');
+      expect(provider.modelName).toBe('gpt-4.1');
+    });
+
+    it('thinkingEffort is null by default', () => {
+      const provider = createProvider();
+      expect(provider.thinkingEffort).toBeNull();
+    });
+
+    it('thinkingEffort reflects withThinking', () => {
+      const provider = createProvider();
+      expect(provider.withThinking('high').thinkingEffort).toBe('high');
+      expect(provider.withThinking('low').thinkingEffort).toBe('low');
+    });
+
+    it('withThinking returns a new instance', () => {
+      const provider = createProvider();
+      const newProvider = provider.withThinking('high');
+      expect(newProvider).toBeInstanceOf(OpenAIResponsesChatProvider);
+      expect(newProvider).not.toBe(provider);
+    });
+
+    it('throws a clear error when the SDK client lacks Responses API support', async () => {
+      const provider = createProvider();
+      (provider as unknown as { _client: Record<string, unknown> })._client = {};
+
+      await expect(
+        provider.generate(
+          '',
+          [],
+          [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+        ),
+      ).rejects.toThrow(
+        'OpenAI SDK version does not support Responses API. Upgrade to >=4.x with responses support.',
+      );
+    });
+  });
+
+  describe('response parsing', () => {
+    it('yields text from non-stream response', async () => {
+      const provider = createProvider();
+      (provider as any)._stream = false;
+      ((provider as any)._client.responses as unknown as Record<string, unknown>)['create'] = vi
+        .fn()
+        .mockResolvedValue(makeResponsesAPIResponse());
+
+      const stream = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+
+      const parts = [];
+      for await (const part of stream) {
+        parts.push(part);
+      }
+
+      expect(parts).toEqual([{ type: 'text', text: 'Hello' }]);
+      expect(stream.id).toBe('resp_test123');
+      expect(stream.usage).toEqual({
+        inputOther: 10,
+        output: 5,
+        inputCacheRead: 0,
+        inputCacheCreation: 0,
+      });
+    });
+
+    it('yields ToolCall from non-stream response with function_call output item', async () => {
+      const provider = createProvider();
+      (provider as any)._stream = false;
+      ((provider as any)._client.responses as unknown as Record<string, unknown>)['create'] = vi
+        .fn()
+        .mockResolvedValue({
+          id: 'resp_fn',
+          object: 'response',
+          status: 'completed',
+          output: [
+            {
+              type: 'function_call',
+              call_id: 'call_xyz',
+              name: 'lookup',
+              arguments: '{"q":"hi"}',
+            },
+          ],
+          usage: { input_tokens: 5, output_tokens: 3, total_tokens: 8 },
+        });
+
+      const stream = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+      const parts: StreamedMessagePart[] = [];
+      for await (const p of stream) parts.push(p);
+
+      expect(parts).toEqual([
+        {
+          type: 'function',
+          id: 'call_xyz',
+          function: { name: 'lookup', arguments: '{"q":"hi"}' },
+        },
+      ]);
+    });
+
+    it('non-stream function_call generates UUID when call_id is missing', async () => {
+      const provider = createProvider();
+      (provider as any)._stream = false;
+      ((provider as any)._client.responses as unknown as Record<string, unknown>)['create'] = vi
+        .fn()
+        .mockResolvedValue({
+          id: 'resp_no_call_id',
+          output: [
+            {
+              type: 'function_call',
+              name: 'lookup',
+              arguments: '{}',
+            },
+          ],
+          usage: { input_tokens: 5, output_tokens: 3, total_tokens: 8 },
+        });
+
+      const stream = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+      const parts: StreamedMessagePart[] = [];
+      for await (const p of stream) parts.push(p);
+
+      const toolCall = parts.find((p) => p.type === 'function');
+      expect(toolCall).toMatchObject({
+        type: 'function',
+        id: expect.stringMatching(/.+/),
+      });
+    });
+
+    it('yields ThinkPart from non-stream response with reasoning output item (with encrypted_content)', async () => {
+      const provider = createProvider();
+      (provider as any)._stream = false;
+      ((provider as any)._client.responses as unknown as Record<string, unknown>)['create'] = vi
+        .fn()
+        .mockResolvedValue({
+          id: 'resp_reason',
+          object: 'response',
+          status: 'completed',
+          output: [
+            {
+              type: 'reasoning',
+              encrypted_content: 'enc_token_abc',
+              summary: [
+                { type: 'summary_text', text: 'Step 1' },
+                { type: 'summary_text', text: 'Step 2' },
+              ],
+            },
+            {
+              type: 'message',
+              role: 'assistant',
+              content: [{ type: 'output_text', text: 'done', annotations: [] }],
+            },
+          ],
+          usage: { input_tokens: 5, output_tokens: 3, total_tokens: 8 },
+        });
+
+      const stream = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+      const parts: StreamedMessagePart[] = [];
+      for await (const p of stream) parts.push(p);
+
+      expect(parts).toEqual([
+        { type: 'think', think: 'Step 1', encrypted: 'enc_token_abc' },
+        { type: 'think', think: 'Step 2', encrypted: 'enc_token_abc' },
+        { type: 'text', text: 'done' },
+      ]);
+    });
+
+    it('non-stream reasoning without encrypted_content yields ThinkPart without encrypted field', async () => {
+      const provider = createProvider();
+      (provider as any)._stream = false;
+      ((provider as any)._client.responses as unknown as Record<string, unknown>)['create'] = vi
+        .fn()
+        .mockResolvedValue({
+          id: 'resp_reason2',
+          output: [
+            {
+              type: 'reasoning',
+              summary: [{ type: 'summary_text', text: 'Thinking...' }],
+            },
+          ],
+          usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+        });
+
+      const stream = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+      const parts: StreamedMessagePart[] = [];
+      for await (const p of stream) parts.push(p);
+
+      expect(parts).toEqual([{ type: 'think', think: 'Thinking...' }]);
+    });
+  });
+
+  describe('provider property accessors', () => {
+    it('modelName returns configured model', () => {
+      const provider = new OpenAIResponsesChatProvider({
+        model: 'gpt-5-codex',
+        apiKey: 'test-key',
+      });
+      expect(provider.modelName).toBe('gpt-5-codex');
+    });
+
+    it('modelParameters returns model + baseUrl + generationKwargs', () => {
+      const provider = new OpenAIResponsesChatProvider({
+        model: 'gpt-4.1',
+        apiKey: 'test-key',
+        maxOutputTokens: 2048,
+      });
+      const params = provider.modelParameters;
+      expect(params).toMatchObject({
+        model: 'gpt-4.1',
+        max_output_tokens: 2048,
+        baseUrl: expect.any(String),
+      });
+    });
+
+    it('maxOutputTokens constructor option is wired into generationKwargs', async () => {
+      const provider = new OpenAIResponsesChatProvider({
+        model: 'gpt-4.1',
+        apiKey: 'test-key',
+        maxOutputTokens: 512,
+      });
+      const history: Message[] = [
+        { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+      expect(body['max_output_tokens']).toBe(512);
+    });
+
+    it('video_url in user content is silently skipped (Responses API has no video representation)', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'Watch this:' },
+            { type: 'video_url', videoUrl: { url: 'https://example.com/clip.mp4' } },
+          ],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      // Only the text part survives; video is dropped.
+      const input = body['input'] as Array<{ content: unknown[] }>;
+      expect(input[0]!.content).toEqual([{ type: 'input_text', text: 'Watch this:' }]);
+    });
+
+    it('audio_url with unsupported scheme is silently dropped from user content', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'Hear:' },
+            { type: 'audio_url', audioUrl: { url: 'file:///path/to/audio.mp3' } },
+          ],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const input = body['input'] as Array<{ content: unknown[] }>;
+      // file:// URL is unsupported → drop
+      expect(input[0]!.content).toEqual([{ type: 'input_text', text: 'Hear:' }]);
+    });
+
+    it('audio_url data URL with unknown subtype is silently dropped', async () => {
+      const provider = createProvider();
+      const history: Message[] = [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'OGG:' },
+            { type: 'audio_url', audioUrl: { url: 'data:audio/ogg;base64,T0dH' } },
+          ],
+          toolCalls: [],
+        },
+      ];
+      const body = await captureRequestBody(provider, '', [], history);
+
+      const input = body['input'] as Array<{ content: unknown[] }>;
+      // ogg subtype is not mp3/wav → drop
+      expect(input[0]!.content).toEqual([{ type: 'input_text', text: 'OGG:' }]);
+    });
+  });
+
+  describe('streaming', () => {
+    it('generate sends stream: true and returns streaming parts', async () => {
+      const provider = createProvider();
+
+      // The provider has _stream = true by default; mock create to return an async iterable
+      const events = [
+        { type: 'response.output_text.delta', delta: 'Hello' },
+        { type: 'response.output_text.delta', delta: ' world' },
+        {
+          type: 'response.completed',
+          response: {
+            id: 'resp_stream_1',
+            usage: {
+              input_tokens: 20,
+              output_tokens: 10,
+              input_tokens_details: { cached_tokens: 5 },
+            },
+          },
+        },
+      ];
+
+      let capturedParams: Record<string, unknown> | undefined;
+      ((provider as any)._client.responses as unknown as Record<string, unknown>)['create'] = vi
+        .fn()
+        .mockImplementation((params: unknown) => {
+          capturedParams = params as Record<string, unknown>;
+          return Promise.resolve(makeAsyncIterable(events));
+        });
+
+      const stream = await provider.generate(
+        '',
+        [],
+        [{ role: 'user', content: [{ type: 'text', text: 'Hi' }], toolCalls: [] }],
+      );
+
+      const parts: StreamedMessagePart[] = [];
+      for await (const part of stream) {
+        parts.push(part);
+      }
+
+      // Verify stream: true was sent
+      expect(capturedParams!['stream']).toBe(true);
+
+      expect(parts).toEqual([
+        { type: 'text', text: 'Hello' },
+        { type: 'text', text: ' world' },
+      ]);
+
+      expect(stream.usage).toEqual({
+        inputOther: 15,
+        output: 10,
+        inputCacheRead: 5,
+        inputCacheCreation: 0,
+      });
+    });
+
+    it('streams tool call with arguments delta', async () => {
+      const events = [
+        {
+          type: 'response.output_item.added',
+          item: {
+            id: 'item_123',
+            type: 'function_call',
+            call_id: 'call_123',
+            name: 'add',
+            arguments: '',
+          },
+        },
+        { type: 'response.function_call_arguments.delta', item_id: 'item_123', delta: '{"a":' },
+        {
+          type: 'response.function_call_arguments.delta',
+          item_id: 'item_123',
+          delta: ' 2, "b": 3}',
+        },
+        {
+          type: 'response.function_call_arguments.done',
+          item_id: 'item_123',
+          name: 'add',
+          arguments: '{"a": 2, "b": 3}',
+        },
+        {
+          type: 'response.completed',
+          response: { id: 'resp_tc', usage: { input_tokens: 5, output_tokens: 3 } },
+        },
+      ];
+
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+
+      const parts: StreamedMessagePart[] = [];
+      for await (const part of stream) {
+        parts.push(part);
+      }
+
+      // The Responses adapter absorbs `function_call_arguments.done` and
+      // `output_item.done` for function_call items — generate.ts infers
+      // completion from merge boundaries and stream end.
+      expect(parts).toEqual([
+        {
+          type: 'function',
+          id: 'call_123',
+          function: { name: 'add', arguments: '' },
+          _streamIndex: 'item_123',
+        },
+        { type: 'tool_call_part', argumentsPart: '{"a":', index: 'item_123' },
+        { type: 'tool_call_part', argumentsPart: ' 2, "b": 3}', index: 'item_123' },
+      ]);
+
+      expect(stream.usage).toEqual({
+        inputOther: 5,
+        output: 3,
+        inputCacheRead: 0,
+        inputCacheCreation: 0,
+      });
+    });
+
+    it('uses final arguments from function_call_arguments.done when no deltas are emitted', async () => {
+      const provider = createProvider();
+      const events = [
+        {
+          type: 'response.output_item.added',
+          item: {
+            id: 'item_done_only',
+            type: 'function_call',
+            call_id: 'call_done_only',
+            name: 'add',
+            arguments: '',
+          },
+        },
+        {
+          type: 'response.function_call_arguments.done',
+          item_id: 'item_done_only',
+          output_index: 0,
+          name: 'add',
+          arguments: '{"a": 2, "b": 3}',
+        },
+        {
+          type: 'response.completed',
+          response: { id: 'resp_done_only', usage: { input_tokens: 5, output_tokens: 3 } },
+        },
+      ];
+
+      ((provider as any)._client.responses as unknown as Record<string, unknown>)['create'] = vi
+        .fn()
+        .mockResolvedValue(makeAsyncIterable(events));
+
+      const result = await generate(
+        provider,
+        '',
+        [ADD_TOOL],
+        [{ role: 'user', content: [{ type: 'text', text: 'Add 2 and 3' }], toolCalls: [] }],
+      );
+
+      expect(result.message.toolCalls).toEqual([
+        {
+          type: 'function',
+          id: 'call_done_only',
+          function: { name: 'add', arguments: '{"a": 2, "b": 3}' },
+          extras: undefined,
+        },
+      ]);
+    });
+
+    it('rejects function_call_arguments.done when it disagrees with streamed deltas', async () => {
+      const events = [
+        {
+          type: 'response.output_item.added',
+          item: {
+            id: 'item_mismatch',
+            type: 'function_call',
+            call_id: 'call_mismatch',
+            name: 'add',
+            arguments: '',
+          },
+        },
+        {
+          type: 'response.function_call_arguments.delta',
+          item_id: 'item_mismatch',
+          output_index: 0,
+          delta: '{"a": 1}',
+        },
+        {
+          type: 'response.function_call_arguments.done',
+          item_id: 'item_mismatch',
+          output_index: 0,
+          name: 'add',
+          arguments: '{"a": 2}',
+        },
+      ];
+
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+
+      await expect(collectStreamParts(stream)).rejects.toThrow(
+        /final function-call arguments.*do not match/,
+      );
+    });
+
+    it('streams reasoning with encrypted_content', async () => {
+      const events = [
+        { type: 'response.reasoning_summary_part.added' },
+        { type: 'response.reasoning_summary_text.delta', delta: 'Thinking about' },
+        { type: 'response.reasoning_summary_text.delta', delta: ' the answer...' },
+        {
+          type: 'response.output_item.done',
+          item: {
+            type: 'reasoning',
+            id: 'rs_1',
+            encrypted_content: 'enc_xyz',
+            summary: [{ type: 'summary_text', text: 'Thinking about the answer...' }],
+          },
+        },
+        { type: 'response.output_text.delta', delta: '42' },
+        {
+          type: 'response.completed',
+          response: { id: 'resp_r', usage: { input_tokens: 8, output_tokens: 4 } },
+        },
+      ];
+
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+
+      const parts: StreamedMessagePart[] = [];
+      for await (const part of stream) {
+        parts.push(part);
+      }
+
+      expect(parts).toEqual([
+        { type: 'think', think: '' },
+        { type: 'think', think: 'Thinking about' },
+        { type: 'think', think: ' the answer...' },
+        { type: 'think', think: '', encrypted: 'enc_xyz' },
+        { type: 'text', text: '42' },
+      ]);
+    });
+
+    it('stream.id is response.id, not output item id (tool call)', async () => {
+      // Regression: previously `output_item.added` / `output_item.done`
+      // overwrote `_id` with the item id (or undefined for tool-call items
+      // that have no `item.id`), clobbering the real `response.id`.
+      const events = [
+        { type: 'response.created', response: { id: 'resp_001' } },
+        {
+          type: 'response.output_item.added',
+          item: {
+            type: 'function_call',
+            id: 'item_a',
+            call_id: 'call_a',
+            name: 'tool_a',
+            arguments: '',
+          },
+        },
+        { type: 'response.function_call_arguments.delta', item_id: 'item_a', delta: '{}' },
+        {
+          type: 'response.output_item.done',
+          item: { type: 'function_call', id: 'item_a' },
+        },
+        {
+          type: 'response.completed',
+          response: { id: 'resp_001', usage: { input_tokens: 10, output_tokens: 5 } },
+        },
+      ];
+
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+      for await (const _ of stream) {
+        void _;
+      }
+
+      expect(stream.id).toBe('resp_001');
+    });
+
+    it('stream.id stays as response.id across multiple output items', async () => {
+      const events = [
+        { type: 'response.in_progress', response: { id: 'resp_multi' } },
+        {
+          type: 'response.output_item.added',
+          item: {
+            type: 'function_call',
+            id: 'item_1',
+            call_id: 'call_1',
+            name: 'tool_1',
+            arguments: '',
+          },
+        },
+        { type: 'response.function_call_arguments.delta', item_id: 'item_1', delta: '{}' },
+        {
+          type: 'response.output_item.done',
+          item: { type: 'function_call', id: 'item_1' },
+        },
+        {
+          type: 'response.output_item.added',
+          item: {
+            type: 'function_call',
+            id: 'item_2',
+            call_id: 'call_2',
+            name: 'tool_2',
+            arguments: '',
+          },
+        },
+        { type: 'response.function_call_arguments.delta', item_id: 'item_2', delta: '{}' },
+        {
+          type: 'response.output_item.done',
+          item: { type: 'function_call', id: 'item_2' },
+        },
+        {
+          type: 'response.completed',
+          response: { id: 'resp_multi', usage: { input_tokens: 1, output_tokens: 1 } },
+        },
+      ];
+
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+      for await (const _ of stream) {
+        void _;
+      }
+
+      expect(stream.id).toBe('resp_multi');
+    });
+
+    it('stream.id is set from response.created even if tool-call items lack id', async () => {
+      // Some providers emit `output_item.added` without an `item.id` for
+      // function_call items. Before the fix, this would set `_id` to
+      // undefined, erasing the real response id captured earlier.
+      const events = [
+        { type: 'response.created', response: { id: 'resp_no_item_id' } },
+        {
+          type: 'response.output_item.added',
+          item: {
+            type: 'function_call',
+            call_id: 'call_x',
+            name: 'tool_x',
+            arguments: '',
+          },
+        },
+        { type: 'response.function_call_arguments.delta', delta: '{}' },
+        {
+          type: 'response.completed',
+          response: {
+            id: 'resp_no_item_id',
+            usage: { input_tokens: 2, output_tokens: 1 },
+          },
+        },
+      ];
+
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+      for await (const _ of stream) {
+        void _;
+      }
+
+      expect(stream.id).toBe('resp_no_item_id');
+    });
+
+    it('captures response.id from response.created chunk (before response.completed)', async () => {
+      const events = [
+        {
+          type: 'response.created',
+          response: { id: 'resp_created_id', status: 'in_progress' },
+        },
+        { type: 'response.output_text.delta', delta: 'hi' },
+        {
+          type: 'response.completed',
+          response: { id: 'resp_final_id', usage: { input_tokens: 1, output_tokens: 1 } },
+        },
+      ];
+
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+      // Mid-stream: id should be 'resp_created_id' after the first chunk is consumed.
+      // We can't easily inspect mid-stream so we check the final id only:
+      // the response.completed event refines the id to 'resp_final_id'.
+      for await (const _ of stream) {
+        void _;
+      }
+      expect(stream.id).toBe('resp_final_id');
+    });
+
+    it('captures response.id from response.in_progress chunk', async () => {
+      const events = [
+        {
+          type: 'response.in_progress',
+          response: { id: 'resp_in_progress' },
+        },
+        { type: 'response.output_text.delta', delta: 'x' },
+      ];
+
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+      for await (const _ of stream) {
+        void _;
+      }
+      // No response.completed → id falls back to the in_progress id.
+      expect(stream.id).toBe('resp_in_progress');
+    });
+
+    it('yields ThinkPart from response.output_item.done reasoning item (with encrypted_content)', async () => {
+      const events = [
+        {
+          type: 'response.output_item.done',
+          item: {
+            type: 'reasoning',
+            id: 'reasoning_item_1',
+            encrypted_content: 'enc_done',
+          },
+        },
+      ];
+
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+      const parts: StreamedMessagePart[] = [];
+      for await (const p of stream) parts.push(p);
+
+      expect(parts).toEqual([{ type: 'think', think: '', encrypted: 'enc_done' }]);
+    });
+
+    it('yields ThinkPart from response.output_item.done reasoning item without encrypted_content', async () => {
+      const events = [
+        {
+          type: 'response.output_item.done',
+          item: { type: 'reasoning', id: 'reasoning_item_2' },
+        },
+      ];
+
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+      const parts: StreamedMessagePart[] = [];
+      for await (const p of stream) parts.push(p);
+
+      expect(parts).toEqual([{ type: 'think', think: '' }]);
+    });
+
+    it('yields ThinkPart from response.reasoning_summary_part.added and .delta events', async () => {
+      const events = [
+        { type: 'response.reasoning_summary_part.added' },
+        { type: 'response.reasoning_summary_text.delta', delta: 'Thinking about' },
+        { type: 'response.reasoning_summary_text.delta', delta: ' the answer' },
+      ];
+
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+      const parts: StreamedMessagePart[] = [];
+      for await (const p of stream) parts.push(p);
+
+      expect(parts).toEqual([
+        { type: 'think', think: '' },
+        { type: 'think', think: 'Thinking about' },
+        { type: 'think', think: ' the answer' },
+      ]);
+    });
+
+    it('ignores output_item.added for non-function_call items (e.g. message items)', async () => {
+      const events = [
+        {
+          type: 'response.output_item.added',
+          item: { type: 'message', id: 'msg_item_1' },
+        },
+        { type: 'response.output_text.delta', delta: 'hi' },
+      ];
+
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+      const parts: StreamedMessagePart[] = [];
+      for await (const p of stream) parts.push(p);
+
+      // Only the text delta should be yielded; the message output_item.added is ignored.
+      expect(parts).toEqual([{ type: 'text', text: 'hi' }]);
+    });
+
+    it('ignores unknown stream event types and continues with known events', async () => {
+      const stream = new OpenAIResponsesStreamedMessage(
+        makeAsyncIterable([
+          { type: 'response.future_event', payload: { value: 1 } },
+          { type: 'response.output_text.delta', delta: 'hi' },
+        ]),
+        true,
+      );
+
+      await expect(collectStreamParts(stream)).resolves.toEqual([{ type: 'text', text: 'hi' }]);
+    });
+
+    it('throws on OpenAI Responses error events after preserving prior parts', async () => {
+      const events = [
+        { type: 'response.output_text.delta', delta: 'partial' },
+        {
+          type: 'error',
+          code: 'server_error',
+          message: 'upstream failed',
+          param: null,
+        },
+      ];
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+
+      const parts: StreamedMessagePart[] = [];
+      let caughtError: Error | undefined;
+      try {
+        for await (const part of stream) {
+          parts.push(part);
+        }
+      } catch (error) {
+        caughtError = error as Error;
+      }
+
+      expect(parts).toEqual([{ type: 'text', text: 'partial' }]);
+      expect(caughtError).toBeInstanceOf(ChatProviderError);
+      expect(caughtError?.message).toMatch(/server_error.*upstream failed/);
+    });
+
+    it('throws on response.failed events with response error details', async () => {
+      const events = [
+        {
+          type: 'response.failed',
+          response: {
+            id: 'resp_failed',
+            status: 'failed',
+            error: { code: 'rate_limit_exceeded', message: 'too many requests' },
+          },
+        },
+      ];
+      const stream = new OpenAIResponsesStreamedMessage(makeAsyncIterable(events), true);
+
+      await expect(collectStreamParts(stream)).rejects.toThrow(
+        /rate_limit_exceeded.*too many/,
+      );
+    });
+
+    it('throws when a known stream event is missing a required field', async () => {
+      const stream = new OpenAIResponsesStreamedMessage(
+        makeAsyncIterable([{ type: 'response.output_text.delta' }]),
+        true,
+      );
+
+      await expect(collectStreamParts(stream)).rejects.toThrow(
+        /response\.output_text\.delta\.delta/,
+      );
+    });
+
+    it('converts errors during streaming', async () => {
+      const { APIError } = await import('openai');
+
+      async function* failingStream(): AsyncIterable<Record<string, unknown>> {
+        yield { type: 'response.output_text.delta', delta: 'partial' };
+        throw new APIError(
+          500,
+          { message: 'Internal Server Error' },
+          'server error',
+          new Headers(),
+        );
+      }
+
+      const stream = new OpenAIResponsesStreamedMessage(failingStream(), true);
+
+      const parts: StreamedMessagePart[] = [];
+      let caughtError: Error | undefined;
+      try {
+        for await (const part of stream) {
+          parts.push(part);
+        }
+      } catch (error) {
+        caughtError = error as Error;
+      }
+
+      expect(parts).toEqual([{ type: 'text', text: 'partial' }]);
+      expect(caughtError).toMatchObject({ name: 'APIStatusError' });
+    });
+  });
+});
+
+async function collectStreamParts(
+  stream: OpenAIResponsesStreamedMessage,
+): Promise<StreamedMessagePart[]> {
+  const parts: StreamedMessagePart[] = [];
+  for await (const part of stream) {
+    parts.push(part);
+  }
+  return parts;
+}
+
+function makeAsyncIterable(
+  events: Record<string, unknown>[],
+): AsyncIterable<Record<string, unknown>> {
+  return {
+    [Symbol.asyncIterator](): AsyncIterator<Record<string, unknown>> {
+      let index = 0;
+      return {
+        next(): Promise<IteratorResult<Record<string, unknown>>> {
+          if (index < events.length) {
+            return Promise.resolve({ value: events[index++]!, done: false });
+          }
+          return Promise.resolve({
+            value: undefined as unknown as Record<string, unknown>,
+            done: true,
+          });
+        },
+      };
+    },
+  };
+}
diff --git a/packages/kosong/test/provider.test.ts b/packages/kosong/test/provider.test.ts
new file mode 100644
index 000000000..04aef7f4b
--- /dev/null
+++ b/packages/kosong/test/provider.test.ts
@@ -0,0 +1,103 @@
+import type { StreamedMessagePart, TextPart } from '#/message';
+import { MockChatProvider } from './fixtures/mock-provider';
+import { describe, it, expect } from 'vitest';
+
+describe('MockChatProvider', () => {
+  it('streams predefined parts', async () => {
+    const inputParts: StreamedMessagePart[] = [
+      { type: 'text', text: 'Hello, world!' } satisfies TextPart,
+    ];
+
+    const provider = new MockChatProvider(inputParts);
+    const stream = await provider.generate('', [], []);
+
+    const outputParts: StreamedMessagePart[] = [];
+    for await (const part of stream) {
+      outputParts.push(part);
+    }
+
+    expect(outputParts).toEqual(inputParts);
+  });
+
+  it('returns the same parts on multiple calls', async () => {
+    const inputParts: StreamedMessagePart[] = [
+      { type: 'text', text: 'Hello' } satisfies TextPart,
+      { type: 'text', text: ', world!' } satisfies TextPart,
+    ];
+
+    const provider = new MockChatProvider(inputParts);
+
+    // First call
+    const parts1: StreamedMessagePart[] = [];
+    for await (const part of await provider.generate('', [], [])) {
+      parts1.push(part);
+    }
+
+    // Second call
+    const parts2: StreamedMessagePart[] = [];
+    for await (const part of await provider.generate('', [], [])) {
+      parts2.push(part);
+    }
+
+    expect(parts1).toEqual(inputParts);
+    expect(parts2).toEqual(inputParts);
+  });
+
+  it('has correct default properties', () => {
+    const provider = new MockChatProvider([]);
+    expect(provider.name).toBe('mock');
+    expect(provider.modelName).toBe('mock');
+    expect(provider.thinkingEffort).toBeNull();
+  });
+
+  it('returns correct id and usage from stream', async () => {
+    const provider = new MockChatProvider([{ type: 'text', text: 'hi' }], {
+      id: 'test-id',
+      usage: { inputOther: 10, output: 5, inputCacheRead: 3, inputCacheCreation: 0 },
+    });
+
+    const stream = await provider.generate('', [], []);
+    // consume stream
+    for await (const _ of stream) {
+      void _;
+    }
+
+    expect(stream.id).toBe('test-id');
+    expect(stream.usage).toEqual({
+      inputOther: 10,
+      output: 5,
+      inputCacheRead: 3,
+      inputCacheCreation: 0,
+    });
+  });
+
+  it('withThinking returns a new provider', () => {
+    const provider = new MockChatProvider([{ type: 'text', text: 'hi' }]);
+    const newProvider = provider.withThinking('high');
+    expect(newProvider).toBeInstanceOf(MockChatProvider);
+    expect(newProvider).not.toBe(provider);
+  });
+
+  it('defaults finishReason to completed and rawFinishReason to stop', async () => {
+    const provider = new MockChatProvider([{ type: 'text', text: 'hi' }]);
+    const stream = await provider.generate('', [], []);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('completed');
+    expect(stream.rawFinishReason).toBe('stop');
+  });
+
+  it('honors explicit finishReason and rawFinishReason options', async () => {
+    const provider = new MockChatProvider([{ type: 'text', text: 'hi' }], {
+      finishReason: 'truncated',
+      rawFinishReason: 'length',
+    });
+    const stream = await provider.generate('', [], []);
+    for await (const _ of stream) {
+      void _;
+    }
+    expect(stream.finishReason).toBe('truncated');
+    expect(stream.rawFinishReason).toBe('length');
+  });
+});
diff --git a/packages/kosong/test/providers/kimi-schema.test.ts b/packages/kosong/test/providers/kimi-schema.test.ts
new file mode 100644
index 000000000..c257ecf34
--- /dev/null
+++ b/packages/kosong/test/providers/kimi-schema.test.ts
@@ -0,0 +1,721 @@
+import { derefJsonSchema, normalizeKimiToolSchema } from '#/providers/kimi-schema';
+import { describe, expect, it } from 'vitest';
+
+describe('derefJsonSchema', () => {
+  it('returns schema unchanged when there are no $ref', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'number' },
+      },
+      required: ['name'],
+    };
+
+    const result = derefJsonSchema(schema);
+
+    expect(result).toEqual({
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'number' },
+      },
+      required: ['name'],
+    });
+  });
+
+  it('resolves a simple $ref from $defs', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        address: { $ref: '#/$defs/Address' },
+      },
+      $defs: {
+        Address: {
+          type: 'object',
+          properties: {
+            street: { type: 'string' },
+            city: { type: 'string' },
+          },
+        },
+      },
+    };
+
+    const result = derefJsonSchema(schema);
+
+    expect(result).toEqual({
+      type: 'object',
+      properties: {
+        address: {
+          type: 'object',
+          properties: {
+            street: { type: 'string' },
+            city: { type: 'string' },
+          },
+        },
+      },
+    });
+    // $defs should be removed from the result.
+    expect(result['$defs']).toBeUndefined();
+  });
+
+  it('preserves sibling keywords alongside $ref (e.g. description)', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        user: {
+          $ref: '#/$defs/User',
+          description: 'Custom description on the ref site',
+        },
+      },
+      $defs: {
+        User: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+          },
+        },
+      },
+    };
+
+    const result = derefJsonSchema(schema);
+
+    const user = (result['properties'] as Record<string, Record<string, unknown>>)['user']!;
+    // Resolved definition fields are present.
+    expect(user['type']).toBe('object');
+    expect(user['properties']).toEqual({ name: { type: 'string' } });
+    // Local sibling "description" is preserved.
+    expect(user['description']).toBe('Custom description on the ref site');
+  });
+
+  it('local sibling fields override same-named fields from $defs', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        field: {
+          $ref: '#/$defs/Widget',
+          // Local override must win over the def's description.
+          description: 'local override wins',
+        },
+      },
+      $defs: {
+        Widget: {
+          type: 'string',
+          description: 'description from $defs',
+          default: 'hello',
+        },
+      },
+    };
+
+    const result = derefJsonSchema(schema);
+
+    const field = (result['properties'] as Record<string, Record<string, unknown>>)['field']!;
+    expect(field['type']).toBe('string');
+    // Local sibling wins.
+    expect(field['description']).toBe('local override wins');
+    // Non-overlapping def fields still flow through.
+    expect(field['default']).toBe('hello');
+  });
+
+  it('preserves sibling $ref keywords that themselves contain $ref (recursively resolved)', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        entry: {
+          $ref: '#/$defs/Wrapper',
+          extra: { $ref: '#/$defs/Inner' },
+        },
+      },
+      $defs: {
+        Wrapper: {
+          type: 'object',
+          properties: { a: { type: 'number' } },
+        },
+        Inner: {
+          type: 'object',
+          properties: { b: { type: 'boolean' } },
+        },
+      },
+    };
+
+    const result = derefJsonSchema(schema);
+
+    const entry = (result['properties'] as Record<string, Record<string, unknown>>)['entry']!;
+    expect(entry['type']).toBe('object');
+    expect(entry['properties']).toEqual({ a: { type: 'number' } });
+    // Sibling `extra` must have been recursively resolved (not left as a $ref).
+    expect(entry['extra']).toEqual({
+      type: 'object',
+      properties: { b: { type: 'boolean' } },
+    });
+  });
+
+  it('preserves $defs when cyclic refs remain unresolved', () => {
+    // A references B, B references A — classic cycle. resolveNode() leaves
+    // a `#/$defs/...` pointer on at least one side; the validator will need
+    // $defs to stay around to resolve those dangling pointers.
+    const schema = {
+      type: 'object',
+      properties: {
+        a: { $ref: '#/$defs/A' },
+      },
+      $defs: {
+        A: {
+          type: 'object',
+          properties: {
+            next: { $ref: '#/$defs/B' },
+          },
+        },
+        B: {
+          type: 'object',
+          properties: {
+            back: { $ref: '#/$defs/A' },
+          },
+        },
+      },
+    };
+
+    const result = derefJsonSchema(schema);
+
+    expect(result).toMatchObject({
+      $defs: {
+        A: expect.any(Object),
+        B: expect.any(Object),
+      },
+    });
+
+    // Walk the result and confirm at least one remaining $ref points at $defs —
+    // i.e. the output is internally consistent, not dangling.
+    const jsonText = JSON.stringify(result);
+    expect(jsonText).toContain('"$ref":"#/$defs/');
+  });
+
+  it('still deletes $defs when there are no cyclic refs', () => {
+    // Sanity: a non-cyclic schema with $defs should have its $defs removed
+    // after dereferencing (existing behavior must not regress).
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { $ref: '#/$defs/Name' },
+      },
+      $defs: {
+        Name: { type: 'string' },
+      },
+    };
+
+    const result = derefJsonSchema(schema);
+    expect(result['$defs']).toBeUndefined();
+    expect(result['properties']).toEqual({ name: { type: 'string' } });
+  });
+
+  it('resolves nested $ref from $defs', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        person: { $ref: '#/$defs/Person' },
+      },
+      $defs: {
+        Person: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            address: { $ref: '#/$defs/Address' },
+          },
+        },
+        Address: {
+          type: 'object',
+          properties: {
+            street: { type: 'string' },
+            city: { type: 'string' },
+          },
+        },
+      },
+    };
+
+    const result = derefJsonSchema(schema);
+
+    expect(result).toEqual({
+      type: 'object',
+      properties: {
+        person: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            address: {
+              type: 'object',
+              properties: {
+                street: { type: 'string' },
+                city: { type: 'string' },
+              },
+            },
+          },
+        },
+      },
+    });
+    expect(result['$defs']).toBeUndefined();
+  });
+
+  it('resolves a local $ref from draft-7 definitions', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        mode: { $ref: '#/definitions/Mode' },
+      },
+      definitions: {
+        Mode: { enum: ['fast', 'safe'] },
+      },
+    };
+
+    const result = derefJsonSchema(schema);
+
+    expect(result).toEqual({
+      type: 'object',
+      properties: {
+        mode: { enum: ['fast', 'safe'] },
+      },
+    });
+    expect(result['definitions']).toBeUndefined();
+  });
+});
+
+describe('normalizeKimiToolSchema', () => {
+  it.each([
+    {
+      name: 'string enum',
+      property: { enum: ['none', 'start', 'end'] },
+      expectedType: 'string',
+    },
+    {
+      name: 'integer enum',
+      property: { enum: [1, 2, 3] },
+      expectedType: 'integer',
+    },
+    {
+      name: 'mixed integer and float enum collapses to number',
+      property: { enum: [1.5, 2] },
+      expectedType: 'number',
+    },
+    {
+      name: 'boolean enum',
+      property: { enum: [true, false] },
+      expectedType: 'boolean',
+    },
+    {
+      name: 'single boolean enum',
+      property: { enum: [true] },
+      expectedType: 'boolean',
+    },
+    {
+      name: 'null-only enum',
+      property: { enum: [null] },
+      expectedType: 'null',
+    },
+    {
+      name: 'string const',
+      property: { const: 'event' },
+      expectedType: 'string',
+    },
+    {
+      name: 'integer const',
+      property: { const: 3 },
+      expectedType: 'integer',
+    },
+    {
+      name: 'number const',
+      property: { const: 1.25 },
+      expectedType: 'number',
+    },
+    {
+      name: 'boolean const',
+      property: { const: true },
+      expectedType: 'boolean',
+    },
+  ])(
+    'infers $name property type without mutating the original schema',
+    ({ property, expectedType }) => {
+      const schema = {
+        type: 'object',
+        properties: {
+          target: property,
+        },
+      };
+      const original = structuredClone(schema);
+
+      const result = normalizeKimiToolSchema(schema);
+
+      expect(result).toEqual({
+        type: 'object',
+        properties: {
+          target: { ...property, type: expectedType },
+        },
+      });
+      expect(schema).toEqual(original);
+      expect(result).not.toBe(schema);
+    },
+  );
+
+  it('leaves explicitly typed enum properties untouched', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        explicit: { type: 'string', enum: ['already-typed'] },
+      },
+    };
+
+    const result = normalizeKimiToolSchema(schema);
+
+    expect(result).toEqual({
+      type: 'object',
+      properties: {
+        explicit: { type: 'string', enum: ['already-typed'] },
+      },
+    });
+  });
+
+  it('infers object and array property types from container enum/const values', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        object_enum: { enum: [{ a: 1 }, { a: 2 }] },
+        array_enum: { enum: [[1, 2], [3]] },
+        object_const: { const: { kind: 'default' } },
+        array_const: { const: [] },
+      },
+    };
+
+    const result = normalizeKimiToolSchema(schema);
+
+    expect(result).toEqual({
+      type: 'object',
+      properties: {
+        object_enum: { enum: [{ a: 1 }, { a: 2 }], type: 'object' },
+        array_enum: { enum: [[1, 2], [3]], type: 'array' },
+        object_const: { const: { kind: 'default' }, type: 'object' },
+        array_const: { const: [], type: 'array' },
+      },
+    });
+  });
+
+  it('fails fast for mixed enum types instead of emitting an unsupported Kimi type array', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        mixedEnum: { enum: ['auto', 1] },
+      },
+    };
+    const original = structuredClone(schema);
+
+    expect(() => normalizeKimiToolSchema(schema)).toThrow(
+      /Mixed JSON Schema enum or const types are not supported/,
+    );
+    expect(schema).toEqual(original);
+  });
+
+  it('infers object and array structure recursively', () => {
+    const schema = {
+      properties: {
+        filters: {
+          properties: {
+            language: { enum: ['typescript', 'python'] },
+            tags: {
+              items: { enum: ['bug', 'feature'] },
+            },
+          },
+          required: ['language'],
+        },
+        edits: {
+          items: {
+            properties: {
+              path: { const: 'src/index.ts' },
+              lineNumbers: {
+                items: { const: 42 },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const result = normalizeKimiToolSchema(schema);
+
+    expect(result).toEqual({
+      properties: {
+        filters: {
+          type: 'object',
+          properties: {
+            language: { enum: ['typescript', 'python'], type: 'string' },
+            tags: {
+              type: 'array',
+              items: { enum: ['bug', 'feature'], type: 'string' },
+            },
+          },
+          required: ['language'],
+        },
+        edits: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              path: { const: 'src/index.ts', type: 'string' },
+              lineNumbers: {
+                type: 'array',
+                items: { const: 42, type: 'integer' },
+              },
+            },
+          },
+        },
+      },
+    });
+  });
+
+  it('uses structural hints before falling back to string on nested typeless schemas', () => {
+    const schema = {
+      properties: {
+        path: { pattern: '^src/' },
+        limit: { minimum: 1 },
+        freeform: { description: 'Unconstrained external MCP field.' },
+        empty: {},
+      },
+    };
+
+    const result = normalizeKimiToolSchema(schema);
+
+    expect(result).toEqual({
+      properties: {
+        path: { pattern: '^src/', type: 'string' },
+        limit: { minimum: 1, type: 'number' },
+        freeform: { description: 'Unconstrained external MCP field.', type: 'string' },
+        empty: { type: 'string' },
+      },
+    });
+  });
+
+  it('does not default the root schema itself to string', () => {
+    expect(normalizeKimiToolSchema({})).toEqual({});
+  });
+
+  it('dereferences and normalizes local definition buckets', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        mode: { $ref: '#/$defs/Mode' },
+        retryCount: { $ref: '#/definitions/RetryCount' },
+      },
+      $defs: {
+        Mode: { enum: ['fast', 'safe'] },
+      },
+      definitions: {
+        RetryCount: { const: 3 },
+      },
+    };
+
+    const result = normalizeKimiToolSchema(schema);
+
+    expect(result).toEqual({
+      type: 'object',
+      properties: {
+        mode: { enum: ['fast', 'safe'], type: 'string' },
+        retryCount: { const: 3, type: 'integer' },
+      },
+    });
+  });
+
+  it('normalizes nested child schema positions', () => {
+    const thenKeyword = ['th', 'en'].join('');
+    const schema = {
+      properties: {
+        labels: {
+          patternProperties: {
+            '^x-': { enum: ['yes', 'no'] },
+          },
+          propertyNames: { pattern: '^x-' },
+          additionalProperties: { const: false },
+        },
+        tuple: {
+          prefixItems: [{ enum: ['left', 'right'] }, { const: 2 }],
+          contains: { enum: ['needle'] },
+        },
+        conditional: {
+          if: { properties: { kind: { const: 'file' } } },
+          [thenKeyword]: { properties: { path: { pattern: '^src/' } } },
+          else: { properties: { url: { format: 'uri' } } },
+          not: { properties: { blocked: { const: true } } },
+        },
+      },
+    };
+
+    const result = normalizeKimiToolSchema(schema);
+
+    expect(result).toEqual({
+      properties: {
+        labels: {
+          type: 'object',
+          patternProperties: {
+            '^x-': { enum: ['yes', 'no'], type: 'string' },
+          },
+          propertyNames: { pattern: '^x-', type: 'string' },
+          additionalProperties: { const: false, type: 'boolean' },
+        },
+        tuple: {
+          type: 'array',
+          prefixItems: [
+            { enum: ['left', 'right'], type: 'string' },
+            { const: 2, type: 'integer' },
+          ],
+          contains: { enum: ['needle'], type: 'string' },
+        },
+        conditional: {
+          if: {
+            type: 'object',
+            properties: { kind: { const: 'file', type: 'string' } },
+          },
+          [thenKeyword]: {
+            type: 'object',
+            properties: { path: { pattern: '^src/', type: 'string' } },
+          },
+          else: {
+            type: 'object',
+            properties: { url: { format: 'uri', type: 'string' } },
+          },
+          not: {
+            type: 'object',
+            properties: { blocked: { const: true, type: 'boolean' } },
+          },
+        },
+      },
+    });
+  });
+
+  it('infers parent types from every walked child-schema keyword', () => {
+    const schema = {
+      properties: {
+        dependentSchemasOnly: {
+          dependentSchemas: {
+            kind: {
+              properties: {
+                value: { enum: ['file', 'url'] },
+              },
+            },
+          },
+        },
+        dependenciesOnly: {
+          dependencies: {
+            kind: {
+              properties: {
+                enabled: { const: true },
+              },
+            },
+          },
+        },
+        unevaluatedPropertiesOnly: {
+          unevaluatedProperties: { enum: ['allowed'] },
+        },
+        additionalItemsOnly: {
+          additionalItems: { const: 1 },
+        },
+        unevaluatedItemsOnly: {
+          unevaluatedItems: { const: 2 },
+        },
+        contentSchemaOnly: {
+          contentSchema: {
+            properties: {
+              decoded: { enum: ['payload'] },
+            },
+          },
+        },
+      },
+    };
+
+    const result = normalizeKimiToolSchema(schema);
+
+    expect(result).toEqual({
+      properties: {
+        dependentSchemasOnly: {
+          type: 'object',
+          dependentSchemas: {
+            kind: {
+              type: 'object',
+              properties: {
+                value: { enum: ['file', 'url'], type: 'string' },
+              },
+            },
+          },
+        },
+        dependenciesOnly: {
+          type: 'object',
+          dependencies: {
+            kind: {
+              type: 'object',
+              properties: {
+                enabled: { const: true, type: 'boolean' },
+              },
+            },
+          },
+        },
+        unevaluatedPropertiesOnly: {
+          type: 'object',
+          unevaluatedProperties: { enum: ['allowed'], type: 'string' },
+        },
+        additionalItemsOnly: {
+          type: 'array',
+          additionalItems: { const: 1, type: 'integer' },
+        },
+        unevaluatedItemsOnly: {
+          type: 'array',
+          unevaluatedItems: { const: 2, type: 'integer' },
+        },
+        contentSchemaOnly: {
+          type: 'string',
+          contentSchema: {
+            type: 'object',
+            properties: {
+              decoded: { enum: ['payload'], type: 'string' },
+            },
+          },
+        },
+      },
+    });
+  });
+
+  it('preserves combinators while normalizing their schema branches', () => {
+    const schema = {
+      anyOf: [{ enum: ['auto', 'manual'] }, { const: false }],
+      oneOf: [
+        {
+          properties: {
+            strategy: { enum: ['replace', 'insert'] },
+          },
+        },
+      ],
+      allOf: [
+        {
+          items: { const: 1 },
+        },
+      ],
+    };
+
+    const result = normalizeKimiToolSchema(schema);
+
+    expect(result).toEqual({
+      anyOf: [
+        { enum: ['auto', 'manual'], type: 'string' },
+        { const: false, type: 'boolean' },
+      ],
+      oneOf: [
+        {
+          type: 'object',
+          properties: {
+            strategy: { enum: ['replace', 'insert'], type: 'string' },
+          },
+        },
+      ],
+      allOf: [
+        {
+          type: 'array',
+          items: { const: 1, type: 'integer' },
+        },
+      ],
+    });
+    expect(result).not.toHaveProperty('type');
+  });
+});
diff --git a/packages/kosong/test/regression.test.ts b/packages/kosong/test/regression.test.ts
new file mode 100644
index 000000000..558e4ecfc
--- /dev/null
+++ b/packages/kosong/test/regression.test.ts
@@ -0,0 +1,106 @@
+import { generate } from '#/generate';
+import type { Message, StreamedMessagePart } from '#/message';
+import { createAssistantMessage, createUserMessage } from '#/message';
+import type { ChatProvider, GenerateOptions, StreamedMessage, ThinkingEffort } from '#/provider';
+import type { Tool } from '#/tool';
+import type { TokenUsage } from '#/usage';
+import { describe, expect, it } from 'vitest';
+
+function createMockStream(
+  parts: StreamedMessagePart[],
+  opts?: { id?: string; usage?: TokenUsage },
+): StreamedMessage {
+  return {
+    get id(): string | null {
+      return opts?.id ?? null;
+    },
+    get usage(): TokenUsage | null {
+      return opts?.usage ?? null;
+    },
+    finishReason: null,
+    rawFinishReason: null,
+    async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+      for (const part of parts) {
+        yield part;
+      }
+    },
+  };
+}
+
+function createMockProvider(stream: StreamedMessage): ChatProvider {
+  return {
+    name: 'mock',
+    modelName: 'mock-model',
+    thinkingEffort: null,
+    generate: async (
+      _systemPrompt: string,
+      _tools: Tool[],
+      _history: Message[],
+      _options?: GenerateOptions,
+    ): Promise<StreamedMessage> => stream,
+    withThinking(_effort: ThinkingEffort): ChatProvider {
+      return this;
+    },
+  };
+}
+
+describe('regression', () => {
+  describe('empty text parts', () => {
+    it('standalone empty TextPart is kept in content', async () => {
+      const stream = createMockStream([
+        { type: 'text', text: 'before' },
+        { type: 'image_url', imageUrl: { url: 'https://example.com/img.png' } },
+        { type: 'text', text: '' },
+      ]);
+      const provider = createMockProvider(stream);
+
+      const result = await generate(provider, '', [], []);
+
+      expect(result.message.content).toEqual([
+        { type: 'text', text: 'before' },
+        { type: 'image_url', imageUrl: { url: 'https://example.com/img.png' } },
+        { type: 'text', text: '' },
+      ]);
+    });
+  });
+
+  describe('toolCalls defaults', () => {
+    it('createUserMessage has toolCalls as empty array (not undefined)', () => {
+      const msg = createUserMessage('hello');
+      expect(msg.toolCalls).toEqual([]);
+    });
+
+    it('createAssistantMessage without toolCalls has empty array', () => {
+      const msg = createAssistantMessage([{ type: 'text', text: 'test' }]);
+      expect(msg.toolCalls).toEqual([]);
+    });
+
+    it('createAssistantMessage with explicit toolCalls preserves them', () => {
+      const msg = createAssistantMessage(
+        [{ type: 'text', text: 'test' }],
+        [
+          {
+            type: 'function',
+            id: 'call-1',
+            function: { name: 'search', arguments: '{}' },
+          },
+        ],
+      );
+      expect(msg.toolCalls).toEqual([
+        {
+          type: 'function',
+          id: 'call-1',
+          function: { name: 'search', arguments: '{}' },
+        },
+      ]);
+    });
+
+    it('generate() result message has toolCalls as empty array when no tools called', async () => {
+      const stream = createMockStream([{ type: 'text', text: 'hi' }]);
+      const provider = createMockProvider(stream);
+
+      const result = await generate(provider, '', [], []);
+      expect(result.message.toolCalls).toEqual([]);
+    });
+  });
+});
diff --git a/packages/kosong/test/scripted-echo-provider.test.ts b/packages/kosong/test/scripted-echo-provider.test.ts
new file mode 100644
index 000000000..b5d1d8045
--- /dev/null
+++ b/packages/kosong/test/scripted-echo-provider.test.ts
@@ -0,0 +1,183 @@
+import { ScriptedEchoChatProvider } from './fixtures/echo-provider';
+import { ChatProviderError } from '#/errors';
+import type {
+  AudioURLPart,
+  StreamedMessagePart,
+  TextPart,
+  ToolCall,
+  ToolCallPart,
+  VideoURLPart,
+} from '#/message';
+import { describe, it, expect } from 'vitest';
+
+describe('ScriptedEchoChatProvider', () => {
+  it('streams parts from first and second scripts', async () => {
+    const dsl = [
+      'id: scripted-1',
+      'usage: {"input_other": 4, "output": 1, "input_cache_read": 2}',
+      'text: Hello,',
+      'text:  world!',
+      'think: thinking...',
+      'image_url: {"url": "https://example.com/image.png", "id": "img-1"}',
+      'audio_url: https://example.com/audio.mp3',
+      'video_url: https://example.com/video.mp4',
+      'tool_call: {"id": "call-1", "name": "search", "arguments": "{\\"q\\":\\"python\\"", "extras": {"source": "test"}}',
+      'tool_call_part: {"arguments_part": "}"}',
+    ].join('\n');
+
+    const secondDsl = ['id: scripted-2', 'text: second turn'].join('\n');
+
+    const provider = new ScriptedEchoChatProvider([dsl, secondDsl]);
+
+    // First call
+    const parts: StreamedMessagePart[] = [];
+    const stream = await provider.generate('', [], []);
+    for await (const part of stream) {
+      parts.push(part);
+    }
+
+    expect(stream.id).toBe('scripted-1');
+    expect(stream.usage).toEqual({
+      inputOther: 4,
+      output: 1,
+      inputCacheRead: 2,
+      inputCacheCreation: 0,
+    });
+    expect(parts).toEqual([
+      { type: 'text', text: 'Hello,' } satisfies TextPart,
+      { type: 'text', text: ' world!' } satisfies TextPart,
+      { type: 'think', think: 'thinking...' },
+      {
+        type: 'image_url',
+        imageUrl: { url: 'https://example.com/image.png', id: 'img-1' },
+      },
+      {
+        type: 'audio_url',
+        audioUrl: { url: 'https://example.com/audio.mp3' },
+      } satisfies AudioURLPart,
+      {
+        type: 'video_url',
+        videoUrl: { url: 'https://example.com/video.mp4' },
+      } satisfies VideoURLPart,
+      {
+        type: 'function',
+        id: 'call-1',
+        function: { name: 'search', arguments: '{"q":"python"' },
+      } satisfies ToolCall,
+      { type: 'tool_call_part', argumentsPart: '}' } satisfies ToolCallPart,
+    ]);
+
+    // Second call
+    const secondStream = await provider.generate('', [], []);
+    const secondParts: StreamedMessagePart[] = [];
+    for await (const part of secondStream) {
+      secondParts.push(part);
+    }
+
+    expect(secondStream.id).toBe('scripted-2');
+    expect(secondStream.usage).toBeNull();
+    expect(secondParts).toEqual([{ type: 'text', text: 'second turn' }]);
+  });
+
+  it('throws when scripts are exhausted', async () => {
+    const provider = new ScriptedEchoChatProvider(['text: only once']);
+
+    await provider.generate('', [], []);
+
+    await expect(provider.generate('', [], [])).rejects.toThrow(ChatProviderError);
+  });
+
+  it('rejects non-string arguments in tool_call', async () => {
+    const dsl = 'tool_call: {"id": "call-1", "name": "search", "arguments": {"q": "python"}}';
+    const provider = new ScriptedEchoChatProvider([dsl]);
+
+    await expect(provider.generate('', [], [])).rejects.toThrow(ChatProviderError);
+  });
+
+  it('rejects empty DSL content', async () => {
+    const provider = new ScriptedEchoChatProvider(['# comment only\n```']);
+
+    await expect(provider.generate('', [], [])).rejects.toThrow(ChatProviderError);
+  });
+
+  it('has correct default properties', () => {
+    const provider = new ScriptedEchoChatProvider([]);
+    expect(provider.name).toBe('scripted_echo');
+    expect(provider.modelName).toBe('scripted_echo');
+    expect(provider.thinkingEffort).toBeNull();
+  });
+
+  it('withThinking returns a new provider with remaining scripts', async () => {
+    const provider = new ScriptedEchoChatProvider(['text: first', 'text: second']);
+
+    // consume first script
+    await provider.generate('', [], []);
+
+    const newProvider = provider.withThinking('high');
+    expect(newProvider).toBeInstanceOf(ScriptedEchoChatProvider);
+    expect(newProvider).not.toBe(provider);
+
+    // new provider should have only the remaining script
+    const stream = await newProvider.generate('', [], []);
+    const parts: StreamedMessagePart[] = [];
+    for await (const part of stream) {
+      parts.push(part);
+    }
+    expect(parts).toEqual([{ type: 'text', text: 'second' }]);
+  });
+
+  it('exposes per-script finish_reason values across sequential generate() calls', async () => {
+    // Each script carries a different DSL finish_reason and the returned
+    // stream must expose the right normalized + raw pair.
+    const scripts = [
+      ['id: scripted-fr-1', 'text: turn-1', 'finish_reason: stop'].join('\n'),
+      ['id: scripted-fr-2', 'text: turn-2', 'finish_reason: length'].join('\n'),
+      ['id: scripted-fr-3', 'text: turn-3', 'finish_reason: tool_calls'].join('\n'),
+      ['id: scripted-fr-4', 'text: turn-4', 'finish_reason: null'].join('\n'),
+      ['id: scripted-fr-5', 'text: turn-5'].join('\n'), // default
+    ];
+    const provider = new ScriptedEchoChatProvider(scripts);
+
+    const expected: Array<{
+      finishReason: 'completed' | 'tool_calls' | 'truncated' | null;
+      rawFinishReason: string | null;
+    }> = [
+      { finishReason: 'completed', rawFinishReason: 'stop' },
+      { finishReason: 'truncated', rawFinishReason: 'length' },
+      { finishReason: 'tool_calls', rawFinishReason: 'tool_calls' },
+      { finishReason: null, rawFinishReason: null },
+      { finishReason: 'completed', rawFinishReason: 'stop' },
+    ];
+
+    for (const exp of expected) {
+      const stream = await provider.generate('', [], []);
+      for await (const _ of stream) {
+        void _;
+      }
+      expect({
+        finishReason: stream.finishReason,
+        rawFinishReason: stream.rawFinishReason,
+      }).toEqual(exp);
+    }
+  });
+
+  it('generate merges tool_call arguments via mergeInPlace', async () => {
+    const dsl = [
+      'id: scripted-merge-1',
+      'tool_call: {"id": "call-1", "name": "search", "arguments": "{\\"q\\":\\"py"}',
+      'tool_call_part: {"arguments_part": "thon\\"}"}',
+    ].join('\n');
+
+    const provider = new ScriptedEchoChatProvider([dsl]);
+    const { generate } = await import('#/generate');
+
+    const result = await generate(provider, '', [], []);
+
+    expect(result.message.toolCalls).toHaveLength(1);
+
+    const tc = result.message.toolCalls[0]!;
+    expect(tc.id).toBe('call-1');
+    expect(tc.function.name).toBe('search');
+    expect(tc.function.arguments).toBe('{"q":"python"}');
+  });
+});
diff --git a/packages/kosong/test/simple-toolset.test.ts b/packages/kosong/test/simple-toolset.test.ts
new file mode 100644
index 000000000..9eca86e69
--- /dev/null
+++ b/packages/kosong/test/simple-toolset.test.ts
@@ -0,0 +1,278 @@
+import type { ToolCall } from '#/message';
+import type { JsonValue } from './fixtures/args-validator';
+import { SimpleToolset, toolOk } from './fixtures/simple-toolset';
+import type { ToolReturnValue } from './fixtures/simple-toolset';
+import { describe, expect, it } from 'vitest';
+function makeToolCall(id: string, name: string, args: string | null): ToolCall {
+  return {
+    type: 'function',
+    id,
+    function: { name, arguments: args },
+  };
+}
+describe('SimpleToolset', () => {
+  it('handle() invokes the registered handler and returns ToolResult', async () => {
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'plus', description: 'Add two numbers', parameters: {} },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        const obj = args as Record<string, JsonValue>;
+        const a = obj['a'] as number;
+        const b = obj['b'] as number;
+        return toolOk({ output: String(a + b) });
+      },
+    );
+
+    const tc = makeToolCall('1', 'plus', '{"a": 1, "b": 2}');
+    const result = await toolset.handle(tc);
+
+    expect(result.toolCallId).toBe('1');
+    expect(result.returnValue.isError).toBe(false);
+    expect(result.returnValue.output).toBe('3');
+  });
+
+  it('handle() returns toolNotFoundError for unknown tool', async () => {
+    const toolset = new SimpleToolset();
+
+    const tc = makeToolCall('1', 'not_found', null);
+    const result = await toolset.handle(tc);
+
+    expect(result.toolCallId).toBe('1');
+    expect(result.returnValue.isError).toBe(true);
+    expect(result.returnValue.message).toContain('not_found');
+  });
+
+  it('handle() returns toolParseError on invalid JSON', async () => {
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'test', description: 'test', parameters: {} },
+      async (): Promise<ToolReturnValue> => toolOk({ output: 'ok' }),
+    );
+
+    const tc = makeToolCall('1', 'test', '{invalid json}');
+    const result = await toolset.handle(tc);
+
+    expect(result.toolCallId).toBe('1');
+    expect(result.returnValue.isError).toBe(true);
+    expect(result.returnValue.message).toContain('Error parsing JSON arguments:');
+    expect(result.returnValue.display).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ type: 'brief', text: 'Invalid arguments' }),
+      ]),
+    );
+  });
+
+  it('handle() returns toolRuntimeError when handler throws', async () => {
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'explode', description: 'Throws', parameters: {} },
+      async (): Promise<ToolReturnValue> => {
+        throw new Error('boom');
+      },
+    );
+
+    const tc = makeToolCall('1', 'explode', '{}');
+    const result = await toolset.handle(tc);
+
+    expect(result.toolCallId).toBe('1');
+    expect(result.returnValue.isError).toBe(true);
+    expect(result.returnValue.message).toBe('Error running tool: boom');
+    expect(result.returnValue.display).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ type: 'brief', text: 'Tool runtime error' }),
+      ]),
+    );
+  });
+
+  it('handle() resolves to toolRuntimeError when the handler throws synchronously', async () => {
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'explode_sync', description: 'Throws synchronously', parameters: {} },
+      (): Promise<ToolReturnValue> => {
+        throw new Error('boom');
+      },
+    );
+
+    await expect(toolset.handle(makeToolCall('1', 'explode_sync', '{}'))).resolves.toMatchObject({
+      toolCallId: '1',
+      returnValue: expect.objectContaining({
+        isError: true,
+        message: expect.stringContaining('boom'),
+      }),
+    });
+  });
+
+  it('handle() resolves to toolRuntimeError when the handler returns Promise.reject()', async () => {
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'explode_reject', description: 'Rejects', parameters: {} },
+      async (): Promise<ToolReturnValue> => {
+        throw new Error('boom reject');
+      },
+    );
+
+    await expect(toolset.handle(makeToolCall('1', 'explode_reject', '{}'))).resolves.toMatchObject({
+      toolCallId: '1',
+      returnValue: expect.objectContaining({
+        isError: true,
+        message: expect.stringContaining('boom reject'),
+      }),
+    });
+  });
+
+  it('handle() returns toolValidateError when arguments do not satisfy parameters schema', async () => {
+    const toolset = new SimpleToolset();
+    let handlerCalled = false;
+    toolset.add(
+      {
+        name: 'needs_x',
+        description: 'Requires x',
+        parameters: {
+          type: 'object',
+          properties: {
+            x: { type: 'string' },
+          },
+          required: ['x'],
+        },
+      },
+      async (): Promise<ToolReturnValue> => {
+        handlerCalled = true;
+        return toolOk({ output: 'ok' });
+      },
+    );
+
+    const result = await toolset.handle(makeToolCall('1', 'needs_x', '{}'));
+
+    expect(result.toolCallId).toBe('1');
+    expect(result.returnValue.isError).toBe(true);
+    expect(result.returnValue.message).toContain('Error validating JSON arguments:');
+    expect(result.returnValue.message).toContain('x');
+    expect(result.returnValue.display).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ type: 'brief', text: 'Invalid arguments' }),
+      ]),
+    );
+    expect(handlerCalled).toBe(false);
+  });
+
+  it('add() and remove() manage tools', () => {
+    const toolset = new SimpleToolset();
+
+    expect(toolset.tools).toHaveLength(0);
+
+    toolset.add(
+      { name: 'a', description: 'tool a', parameters: {} },
+      async (): Promise<ToolReturnValue> => toolOk({ output: '' }),
+    );
+    toolset.add(
+      { name: 'b', description: 'tool b', parameters: {} },
+      async (): Promise<ToolReturnValue> => toolOk({ output: '' }),
+    );
+
+    expect(toolset.tools).toHaveLength(2);
+    expect(toolset.tools.map((t) => t.name)).toEqual(['a', 'b']);
+
+    toolset.remove('a');
+    expect(toolset.tools).toHaveLength(1);
+    expect(toolset.tools[0]!.name).toBe('b');
+  });
+
+  it('add() overwrites existing tool with same name', async () => {
+    const toolset = new SimpleToolset();
+
+    toolset.add(
+      { name: 'tool', description: 'v1', parameters: {} },
+      async (): Promise<ToolReturnValue> => toolOk({ output: 'v1' }),
+    );
+    toolset.add(
+      { name: 'tool', description: 'v2', parameters: {} },
+      async (): Promise<ToolReturnValue> => toolOk({ output: 'v2' }),
+    );
+
+    expect(toolset.tools).toHaveLength(1);
+    expect(toolset.tools[0]!.description).toBe('v2');
+
+    const tc = makeToolCall('1', 'tool', '{}');
+    const result = await toolset.handle(tc);
+    expect(result.returnValue.output).toBe('v2');
+  });
+
+  it('handle() uses empty object when arguments is null', async () => {
+    const toolset = new SimpleToolset();
+    let receivedArgs: JsonValue = null;
+    toolset.add(
+      { name: 'tool', description: 'test', parameters: {} },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        receivedArgs = args;
+        return toolOk({ output: 'ok' });
+      },
+    );
+
+    const tc = makeToolCall('1', 'tool', null);
+    await toolset.handle(tc);
+
+    expect(receivedArgs).toEqual({});
+  });
+
+  it('remove() throws for non-existent tool', () => {
+    const toolset = new SimpleToolset();
+    expect(() => {
+      toolset.remove('does-not-exist');
+    }).toThrow('Tool `does-not-exist` not found in the toolset.');
+  });
+
+  it('validation error message uses "must NOT have additional property" for additionalProperties: false', async () => {
+    const toolset = new SimpleToolset();
+    toolset.add(
+      {
+        name: 'strict_tool',
+        description: 'rejects unknown keys',
+        parameters: {
+          type: 'object',
+          properties: {
+            x: { type: 'string' },
+          },
+          required: ['x'],
+          additionalProperties: false,
+        },
+      },
+      async (): Promise<ToolReturnValue> => toolOk({ output: 'ok' }),
+    );
+
+    const result = await toolset.handle(makeToolCall('1', 'strict_tool', '{"x":"a","extra":1}'));
+    expect(result.returnValue.isError).toBe(true);
+    expect(result.returnValue.message).toContain("must NOT have additional property 'extra'");
+  });
+
+  it('validation error message includes instancePath for nested field errors', async () => {
+    const toolset = new SimpleToolset();
+    toolset.add(
+      {
+        name: 'nested_tool',
+        description: 'expects nested object',
+        parameters: {
+          type: 'object',
+          properties: {
+            user: {
+              type: 'object',
+              properties: {
+                age: { type: 'integer' },
+              },
+              required: ['age'],
+            },
+          },
+          required: ['user'],
+        },
+      },
+      async (): Promise<ToolReturnValue> => toolOk({ output: 'ok' }),
+    );
+
+    // Pass age as string, triggering a type error on the nested path.
+    const result = await toolset.handle(
+      makeToolCall('1', 'nested_tool', '{"user":{"age":"not a number"}}'),
+    );
+    expect(result.returnValue.isError).toBe(true);
+    // Error message should mention the instance path `/user/age`.
+    expect(result.returnValue.message).toContain('/user/age');
+  });
+});
diff --git a/packages/kosong/test/step.test.ts b/packages/kosong/test/step.test.ts
new file mode 100644
index 000000000..dac532fd0
--- /dev/null
+++ b/packages/kosong/test/step.test.ts
@@ -0,0 +1,516 @@
+import { ChatProviderError } from '#/errors';
+import type { Message, StreamedMessagePart, ToolCall } from '#/message';
+import type { ChatProvider, StreamedMessage, ThinkingEffort } from '#/provider';
+import { step } from './fixtures/step';
+import type { Tool } from '#/tool';
+import { toolOk } from './fixtures/simple-toolset';
+import type { ToolResult, Toolset } from './fixtures/simple-toolset';
+import type { TokenUsage } from '#/usage';
+import { describe, expect, it } from 'vitest';
+function createMockStream(
+  parts: StreamedMessagePart[],
+  opts?: { id?: string; usage?: TokenUsage },
+): StreamedMessage {
+  return {
+    get id(): string | null {
+      return opts?.id ?? null;
+    },
+    get usage(): TokenUsage | null {
+      return opts?.usage ?? null;
+    },
+    finishReason: null,
+    rawFinishReason: null,
+    async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+      for (const part of parts) {
+        yield part;
+      }
+    },
+  };
+}
+
+function createMockProvider(stream: StreamedMessage): ChatProvider {
+  return {
+    name: 'mock',
+    modelName: 'mock-model',
+    thinkingEffort: null,
+    generate(_systemPrompt: string, _tools: Tool[], _history: Message[]): Promise<StreamedMessage> {
+      return Promise.resolve(stream);
+    },
+    withThinking(_effort: ThinkingEffort): ChatProvider {
+      return this;
+    },
+  };
+}
+
+/**
+ * Create a mock toolset that returns a simple success result for any tool call.
+ */
+function createSimpleMockToolset(
+  handler?: (toolCall: ToolCall) => Promise<ToolResult> | ToolResult,
+): Toolset {
+  return {
+    tools: [
+      {
+        name: 'plus',
+        description: 'Add two numbers',
+        parameters: {
+          type: 'object',
+          properties: {
+            a: { type: 'integer' },
+            b: { type: 'integer' },
+          },
+        },
+      },
+    ],
+    handle:
+      handler ??
+      ((toolCall: ToolCall): ToolResult => ({
+        toolCallId: toolCall.id,
+        returnValue: toolOk({ output: 'mock-result' }),
+      })),
+  };
+}
+describe('step()', () => {
+  it('returns a StepResult with message, toolCalls, and toolResults', async () => {
+    const plusToolCall: ToolCall = {
+      type: 'function',
+      id: 'plus#123',
+      function: { name: 'plus', arguments: '{"a": 1, "b": 2}' },
+    };
+    const stream = createMockStream([{ type: 'text', text: 'Hello, world!' }, plusToolCall]);
+    const provider = createMockProvider(stream);
+
+    const toolset = createSimpleMockToolset(
+      (toolCall: ToolCall): ToolResult => ({
+        toolCallId: toolCall.id,
+        returnValue: toolOk({ output: '3' }),
+      }),
+    );
+
+    const result = await step(provider, '', toolset, []);
+
+    expect(result.message.content).toEqual([{ type: 'text', text: 'Hello, world!' }]);
+    expect(result.toolCalls).toHaveLength(1);
+    expect(result.toolCalls[0]).toEqual(plusToolCall);
+
+    const toolResults = await result.toolResults();
+    expect(toolResults).toHaveLength(1);
+    expect(toolResults[0]!.toolCallId).toBe('plus#123');
+    expect(toolResults[0]!.returnValue.output).toBe('3');
+  });
+
+  it('fires onMessagePart and onToolResult callbacks', async () => {
+    const plusToolCall: ToolCall = {
+      type: 'function',
+      id: 'plus#123',
+      function: { name: 'plus', arguments: '{"a": 1, "b": 2}' },
+    };
+    const stream = createMockStream([{ type: 'text', text: 'Hello, world!' }, plusToolCall]);
+    const provider = createMockProvider(stream);
+
+    const toolset = createSimpleMockToolset(
+      (toolCall: ToolCall): ToolResult => ({
+        toolCallId: toolCall.id,
+        returnValue: toolOk({ output: '3' }),
+      }),
+    );
+
+    const outputParts: StreamedMessagePart[] = [];
+    const collectedToolResults: ToolResult[] = [];
+
+    const stepResult = await step(provider, '', toolset, [], {
+      onMessagePart(part: StreamedMessagePart): void {
+        outputParts.push(part);
+      },
+      onToolResult(toolResult: ToolResult): void {
+        collectedToolResults.push(toolResult);
+      },
+    });
+
+    // onMessagePart should receive each raw streamed part.
+    expect(outputParts).toHaveLength(2);
+    expect(outputParts[0]).toEqual({ type: 'text', text: 'Hello, world!' });
+
+    // Await results so onToolResult fires.
+    const toolResults = await stepResult.toolResults();
+
+    expect(toolResults).toHaveLength(1);
+    expect(collectedToolResults).toHaveLength(1);
+    expect(collectedToolResults[0]!.toolCallId).toBe('plus#123');
+  });
+
+  it('returns empty toolResults when no tool calls', async () => {
+    const stream = createMockStream([{ type: 'text', text: 'No tools needed.' }]);
+    const provider = createMockProvider(stream);
+    const toolset = createSimpleMockToolset();
+
+    const stepResult = await step(provider, '', toolset, []);
+    const toolResults = await stepResult.toolResults();
+
+    expect(stepResult.toolCalls).toHaveLength(0);
+    expect(toolResults).toHaveLength(0);
+  });
+
+  it('preserves stream id and usage', async () => {
+    const usage: TokenUsage = {
+      inputOther: 100,
+      output: 50,
+      inputCacheRead: 200,
+      inputCacheCreation: 10,
+    };
+    const stream = createMockStream([{ type: 'text', text: 'hi' }], {
+      id: 'msg-123',
+      usage,
+    });
+    const provider = createMockProvider(stream);
+    const toolset = createSimpleMockToolset();
+
+    const stepResult = await step(provider, '', toolset, []);
+
+    expect(stepResult.id).toBe('msg-123');
+    expect(stepResult.usage).toEqual(usage);
+  });
+
+  it('handles multiple tool calls', async () => {
+    const tc1: ToolCall = {
+      type: 'function',
+      id: 'call-1',
+      function: { name: 'plus', arguments: '{"a":1,"b":2}' },
+    };
+    const tc2: ToolCall = {
+      type: 'function',
+      id: 'call-2',
+      function: { name: 'plus', arguments: '{"a":3,"b":4}' },
+    };
+    const stream = createMockStream([tc1, tc2]);
+    const provider = createMockProvider(stream);
+
+    const toolset = createSimpleMockToolset(
+      (toolCall: ToolCall): ToolResult => ({
+        toolCallId: toolCall.id,
+        returnValue: toolOk({ output: `result-${toolCall.id}` }),
+      }),
+    );
+
+    const stepResult = await step(provider, '', toolset, []);
+    const toolResults = await stepResult.toolResults();
+
+    expect(stepResult.toolCalls).toHaveLength(2);
+    expect(toolResults).toHaveLength(2);
+    expect(toolResults[0]!.toolCallId).toBe('call-1');
+    expect(toolResults[1]!.toolCallId).toBe('call-2');
+  });
+  it('does not dispatch tool calls when provider throws mid-stream', async () => {
+    // With deferred dispatch, onToolCall only fires *after* the stream
+    // has drained. A mid-stream provider error therefore leaves zero
+    // pending tool futures — toolset.handle must never be called.
+    //
+    // This is the desired behaviour for parallel tool call streams
+    // where arguments can interleave; dispatching eagerly would hand
+    // tools half-parsed JSON. See generate.test.ts for the full
+    // rationale.
+    let toolHandleCalls = 0;
+
+    const tc1: ToolCall = {
+      type: 'function',
+      id: 'call-first',
+      function: { name: 'slow', arguments: '{}' },
+    };
+    const tc2: ToolCall = {
+      type: 'function',
+      id: 'call-second',
+      function: { name: 'slow', arguments: '{}' },
+    };
+
+    const throwingStream: StreamedMessage = {
+      get id(): string | null {
+        return null;
+      },
+      get usage(): TokenUsage | null {
+        return null;
+      },
+      finishReason: null,
+      rawFinishReason: null,
+      async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+        yield tc1;
+        yield tc2;
+        throw new ChatProviderError('provider blew up mid-stream');
+      },
+    };
+
+    const provider: ChatProvider = {
+      name: 'mock-throwing',
+      modelName: 'mock-model',
+      thinkingEffort: null,
+      generate(): Promise<StreamedMessage> {
+        return Promise.resolve(throwingStream);
+      },
+      withThinking(_effort: ThinkingEffort): ChatProvider {
+        return this;
+      },
+    };
+
+    const toolset: Toolset = {
+      tools: [],
+      handle(toolCall: ToolCall): Promise<ToolResult> {
+        toolHandleCalls++;
+        return Promise.resolve({
+          toolCallId: toolCall.id,
+          returnValue: toolOk({ output: 'should-never-run' }),
+        });
+      },
+    };
+
+    await expect(step(provider, '', toolset, [])).rejects.toThrow(ChatProviderError);
+
+    // No tools were dispatched because onToolCall is deferred until
+    // after the stream completes successfully.
+    expect(toolHandleCalls).toBe(0);
+  });
+
+  it('mid-stream provider error does not leak unhandled rejections', async () => {
+    const tc1: ToolCall = {
+      type: 'function',
+      id: 'call-rejected',
+      function: { name: 'boom', arguments: '{}' },
+    };
+    const tc2: ToolCall = {
+      type: 'function',
+      id: 'call-next',
+      function: { name: 'boom', arguments: '{}' },
+    };
+
+    const throwingStream: StreamedMessage = {
+      get id(): string | null {
+        return null;
+      },
+      get usage(): TokenUsage | null {
+        return null;
+      },
+      finishReason: null,
+      rawFinishReason: null,
+      async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+        yield tc1;
+        yield tc2;
+        throw new ChatProviderError('kaboom');
+      },
+    };
+
+    const provider: ChatProvider = {
+      name: 'mock-throwing',
+      modelName: 'mock-model',
+      thinkingEffort: null,
+      generate(): Promise<StreamedMessage> {
+        return Promise.resolve(throwingStream);
+      },
+      withThinking(_effort: ThinkingEffort): ChatProvider {
+        return this;
+      },
+    };
+
+    // Toolset whose handle() returns a rejecting promise. With deferred
+    // dispatch, handle() is never even invoked on a mid-stream error,
+    // so this never produces a rejected promise. The listener check
+    // below still guards against any future regression where step()
+    // accidentally drops a reference to a rejected promise.
+    const toolset: Toolset = {
+      tools: [],
+      handle(): Promise<ToolResult> {
+        return Promise.reject(new Error('tool failed'));
+      },
+    };
+
+    const unhandled: unknown[] = [];
+    const listener = (reason: unknown): void => {
+      unhandled.push(reason);
+    };
+    process.on('unhandledRejection', listener);
+    try {
+      await expect(step(provider, '', toolset, [])).rejects.toThrow(ChatProviderError);
+      // Give the event loop a few ticks for any unhandled rejections to fire.
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, 10);
+      });
+    } finally {
+      process.off('unhandledRejection', listener);
+    }
+
+    expect(unhandled).toEqual([]);
+  });
+
+  it('does not emit unhandledRejection when toolResults() is not awaited', async () => {
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'call-rejected',
+        function: { name: 'plus', arguments: '{"a":1,"b":2}' },
+      },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const toolset: Toolset = {
+      tools: [],
+      handle(): Promise<ToolResult> {
+        return Promise.reject(new Error('tool failed'));
+      },
+    };
+
+    const unhandled: unknown[] = [];
+    const listener = (reason: unknown): void => {
+      unhandled.push(reason);
+    };
+
+    process.on('unhandledRejection', listener);
+    try {
+      await step(provider, '', toolset, []);
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, 100);
+      });
+    } finally {
+      process.off('unhandledRejection', listener);
+    }
+
+    expect(unhandled).toEqual([]);
+  });
+
+  it('dispatches tool calls after the stream completes (deferred dispatch)', async () => {
+    // Positive regression: with interleaved parallel tool call streams,
+    // step() must still dispatch every tool exactly once, and each
+    // toolset.handle() invocation must receive fully-assembled
+    // arguments.
+    const seenArgs: Array<{ id: string; args: string | null }> = [];
+
+    const stream = createMockStream([
+      {
+        type: 'function',
+        id: 'tc-a',
+        function: { name: 'plus', arguments: null },
+        _streamIndex: 0,
+      },
+      {
+        type: 'function',
+        id: 'tc-b',
+        function: { name: 'plus', arguments: null },
+        _streamIndex: 1,
+      },
+      { type: 'tool_call_part', argumentsPart: '{"a":1,', index: 0 },
+      { type: 'tool_call_part', argumentsPart: '{"a":3,', index: 1 },
+      { type: 'tool_call_part', argumentsPart: '"b":2}', index: 0 },
+      { type: 'tool_call_part', argumentsPart: '"b":4}', index: 1 },
+    ]);
+    const provider = createMockProvider(stream);
+
+    const toolset: Toolset = {
+      tools: [],
+      handle(toolCall: ToolCall): Promise<ToolResult> {
+        seenArgs.push({ id: toolCall.id, args: toolCall.function.arguments });
+        return Promise.resolve({
+          toolCallId: toolCall.id,
+          returnValue: toolOk({ output: `ok-${toolCall.id}` }),
+        });
+      },
+    };
+
+    const stepResult = await step(provider, '', toolset, []);
+    const toolResults = await stepResult.toolResults();
+
+    // Every handle() invocation saw the fully-assembled arguments for
+    // its own tool call — no partial JSON.
+    expect(seenArgs).toEqual([
+      { id: 'tc-a', args: '{"a":1,"b":2}' },
+      { id: 'tc-b', args: '{"a":3,"b":4}' },
+    ]);
+    expect(toolResults).toHaveLength(2);
+    expect(toolResults[0]!.toolCallId).toBe('tc-a');
+    expect(toolResults[1]!.toolCallId).toBe('tc-b');
+  });
+
+  it('handles sync toolset.handle() return', async () => {
+    const tc: ToolCall = {
+      type: 'function',
+      id: 'call-sync',
+      function: { name: 'plus', arguments: '{}' },
+    };
+    const stream = createMockStream([tc]);
+    const provider = createMockProvider(stream);
+
+    // Toolset that returns a sync ToolResult (not a Promise).
+    const toolset: Toolset = {
+      tools: [],
+      handle(toolCall: ToolCall): ToolResult {
+        return {
+          toolCallId: toolCall.id,
+          returnValue: toolOk({ output: 'sync-result' }),
+        };
+      },
+    };
+
+    const stepResult = await step(provider, '', toolset, []);
+    const toolResults = await stepResult.toolResults();
+
+    expect(toolResults).toHaveLength(1);
+    expect(toolResults[0]!.returnValue.output).toBe('sync-result');
+  });
+
+  describe('finishReason propagation', () => {
+    function streamWithFinish(
+      parts: StreamedMessagePart[],
+      finishReason:
+        | 'completed'
+        | 'truncated'
+        | 'tool_calls'
+        | 'filtered'
+        | 'paused'
+        | 'other'
+        | null,
+      rawFinishReason: string | null,
+    ): StreamedMessage {
+      return {
+        id: 'mock',
+        usage: null,
+        finishReason,
+        rawFinishReason,
+        async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+          for (const part of parts) {
+            yield part;
+          }
+        },
+      };
+    }
+
+    it('copies stream.finishReason onto the StepResult', async () => {
+      const stream = streamWithFinish([{ type: 'text', text: 'hi' }], 'truncated', 'length');
+      const provider = createMockProvider(stream);
+      const toolset = createSimpleMockToolset();
+      const result = await step(provider, '', toolset, []);
+      expect(result.finishReason).toBe('truncated');
+      expect(result.rawFinishReason).toBe('length');
+      await result.toolResults();
+    });
+
+    it('copies null finishReason onto the StepResult', async () => {
+      const stream = streamWithFinish([{ type: 'text', text: 'hi' }], null, null);
+      const provider = createMockProvider(stream);
+      const toolset = createSimpleMockToolset();
+      const result = await step(provider, '', toolset, []);
+      expect(result.finishReason).toBeNull();
+      expect(result.rawFinishReason).toBeNull();
+      await result.toolResults();
+    });
+
+    it('propagates tool_calls finishReason when the model requested tools', async () => {
+      const tc: ToolCall = {
+        type: 'function',
+        id: 'tc-propagate',
+        function: { name: 'plus', arguments: '{"a":1,"b":2}' },
+      };
+      const stream = streamWithFinish([tc], 'tool_calls', 'tool_calls');
+      const provider = createMockProvider(stream);
+      const toolset = createSimpleMockToolset();
+      const result = await step(provider, '', toolset, []);
+      expect(result.finishReason).toBe('tool_calls');
+      expect(result.rawFinishReason).toBe('tool_calls');
+      await result.toolResults();
+    });
+  });
+});
diff --git a/packages/kosong/test/stress.test.ts b/packages/kosong/test/stress.test.ts
new file mode 100644
index 000000000..64011046c
--- /dev/null
+++ b/packages/kosong/test/stress.test.ts
@@ -0,0 +1,364 @@
+import { APIEmptyResponseError } from '#/errors';
+import { generate } from '#/generate';
+import type { Message, StreamedMessagePart, ThinkPart, ToolCall } from '#/message';
+import { mergeInPlace } from '#/message';
+import { MockChatProvider } from './fixtures/mock-provider';
+import type { ChatProvider, StreamedMessage, ThinkingEffort } from '#/provider';
+import { SimpleToolset, toolOk } from './fixtures/simple-toolset';
+import type { ToolReturnValue } from './fixtures/simple-toolset';
+import { step } from './fixtures/step';
+import type { Tool } from '#/tool';
+import type { JsonValue } from './fixtures/args-validator';
+import type { TokenUsage } from '#/usage';
+import { describe, expect, it } from 'vitest';
+function createMockStream(
+  parts: StreamedMessagePart[],
+  opts?: { id?: string; usage?: TokenUsage },
+): StreamedMessage {
+  return {
+    get id(): string | null {
+      return opts?.id ?? null;
+    },
+    get usage(): TokenUsage | null {
+      return opts?.usage ?? null;
+    },
+    finishReason: null,
+    rawFinishReason: null,
+    async *[Symbol.asyncIterator](): AsyncIterator<StreamedMessagePart> {
+      for (const part of parts) {
+        yield part;
+      }
+    },
+  };
+}
+
+function createMockProvider(stream: StreamedMessage): ChatProvider {
+  return {
+    name: 'mock',
+    modelName: 'mock-model',
+    thinkingEffort: null,
+    generate: async (
+      _systemPrompt: string,
+      _tools: Tool[],
+      _history: Message[],
+    ): Promise<StreamedMessage> => stream,
+    withThinking(_effort: ThinkingEffort): ChatProvider {
+      return this;
+    },
+  };
+}
+describe('stress: empty stream', () => {
+  it('MockChatProvider with empty parts throws APIEmptyResponseError', async () => {
+    const provider = new MockChatProvider([]);
+    await expect(generate(provider, '', [], [])).rejects.toThrow(APIEmptyResponseError);
+  });
+
+  it('empty parts via inline mock also throws APIEmptyResponseError', async () => {
+    const stream = createMockStream([]);
+    const provider = createMockProvider(stream);
+    await expect(generate(provider, '', [], [])).rejects.toThrow(APIEmptyResponseError);
+  });
+});
+
+describe('stress: large ToolCall arguments (10KB)', () => {
+  it('assembles 10KB arguments from multiple ToolCallPart increments correctly', async () => {
+    // Build a 10KB JSON string
+    const largeValue = 'x'.repeat(10 * 1024);
+    const fullArgs = JSON.stringify({ data: largeValue });
+
+    // Split into ~100-byte chunks to simulate streaming
+    const chunkSize = 100;
+    const chunks: string[] = [];
+    for (let i = 0; i < fullArgs.length; i += chunkSize) {
+      chunks.push(fullArgs.slice(i, i + chunkSize));
+    }
+
+    const parts: StreamedMessagePart[] = [
+      {
+        type: 'function',
+        id: 'large-tc-1',
+        function: { name: 'big_tool', arguments: null },
+      },
+      ...chunks.map(
+        (chunk): StreamedMessagePart => ({
+          type: 'tool_call_part',
+          argumentsPart: chunk,
+        }),
+      ),
+      // Also include a text part so the response is not empty
+      { type: 'text', text: 'done' },
+    ];
+
+    const provider = new MockChatProvider(parts);
+    const result = await generate(provider, '', [], []);
+
+    expect(result.message.toolCalls).toHaveLength(1);
+    expect(result.message.toolCalls[0]!.function.arguments).toBe(fullArgs);
+    expect(result.message.toolCalls[0]!.function.arguments!.length).toBe(fullArgs.length);
+
+    // Verify the JSON is parseable and correct
+    const parsed = JSON.parse(result.message.toolCalls[0]!.function.arguments!) as {
+      data: string;
+    };
+    expect(parsed.data).toBe(largeValue);
+  });
+});
+
+describe('stress: concurrent tool dispatch', () => {
+  it('step() dispatches 3 ToolCalls concurrently and returns results in call order', async () => {
+    const tc1: ToolCall = {
+      type: 'function',
+      id: 'call-1',
+      function: { name: 'slow_tool', arguments: '{"delay": 1}' },
+    };
+    const tc2: ToolCall = {
+      type: 'function',
+      id: 'call-2',
+      function: { name: 'slow_tool', arguments: '{"delay": 2}' },
+    };
+    const tc3: ToolCall = {
+      type: 'function',
+      id: 'call-3',
+      function: { name: 'slow_tool', arguments: '{"delay": 3}' },
+    };
+
+    const stream = createMockStream([tc1, tc2, tc3]);
+    const provider = createMockProvider(stream);
+
+    // Track completion order
+    const completionOrder: string[] = [];
+
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'slow_tool', description: 'Simulates varying latency', parameters: {} },
+      async (args: JsonValue): Promise<ToolReturnValue> => {
+        const obj = args as Record<string, JsonValue>;
+        const delay = obj['delay'] as number;
+        // Reverse delay order: call-3 finishes first, call-1 finishes last
+        await new Promise<void>((resolve) => setTimeout(resolve, (4 - delay) * 10));
+        completionOrder.push(`call-${delay}`);
+        return toolOk({ output: `result-${delay}` });
+      },
+    );
+
+    const result = await step(provider, '', toolset, []);
+
+    expect(result.toolCalls).toHaveLength(3);
+
+    const toolResults = await result.toolResults();
+
+    // Results must be in call order (call-1, call-2, call-3), not completion order
+    expect(toolResults).toHaveLength(3);
+    expect(toolResults[0]!.toolCallId).toBe('call-1');
+    expect(toolResults[1]!.toolCallId).toBe('call-2');
+    expect(toolResults[2]!.toolCallId).toBe('call-3');
+
+    expect(toolResults[0]!.returnValue.output).toBe('result-1');
+    expect(toolResults[1]!.returnValue.output).toBe('result-2');
+    expect(toolResults[2]!.returnValue.output).toBe('result-3');
+
+    // Verify they actually ran concurrently (call-3 should have finished first)
+    expect(completionOrder[0]).toBe('call-3');
+    expect(completionOrder[1]).toBe('call-2');
+    expect(completionOrder[2]).toBe('call-1');
+  });
+});
+
+describe('stress: tool handler throws exception', () => {
+  it('step() does not crash when a tool handler throws; toolResults includes toolRuntimeError', async () => {
+    const tc: ToolCall = {
+      type: 'function',
+      id: 'crash-call',
+      function: { name: 'crasher', arguments: '{}' },
+    };
+
+    const stream = createMockStream([{ type: 'text', text: 'calling tool' }, tc]);
+    const provider = createMockProvider(stream);
+
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'crasher', description: 'Always throws', parameters: {} },
+      async (): Promise<ToolReturnValue> => {
+        throw new Error('catastrophic failure');
+      },
+    );
+
+    // step() itself should not throw
+    const result = await step(provider, '', toolset, []);
+    expect(result.toolCalls).toHaveLength(1);
+
+    // toolResults() should contain the runtime error, not re-throw
+    const toolResults = await result.toolResults();
+    expect(toolResults).toHaveLength(1);
+    expect(toolResults[0]!.returnValue.isError).toBe(true);
+    expect(toolResults[0]!.returnValue.message).toBe('Error running tool: catastrophic failure');
+    expect(toolResults[0]!.returnValue.display).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ type: 'brief', text: 'Tool runtime error' }),
+      ]),
+    );
+  });
+
+  it('multiple tools where one throws do not affect the other', async () => {
+    const tc1: ToolCall = {
+      type: 'function',
+      id: 'ok-call',
+      function: { name: 'good_tool', arguments: '{}' },
+    };
+    const tc2: ToolCall = {
+      type: 'function',
+      id: 'bad-call',
+      function: { name: 'bad_tool', arguments: '{}' },
+    };
+
+    const stream = createMockStream([tc1, tc2]);
+    const provider = createMockProvider(stream);
+
+    const toolset = new SimpleToolset();
+    toolset.add(
+      { name: 'good_tool', description: 'Works fine', parameters: {} },
+      async (): Promise<ToolReturnValue> => toolOk({ output: 'success' }),
+    );
+    toolset.add(
+      { name: 'bad_tool', description: 'Throws', parameters: {} },
+      async (): Promise<ToolReturnValue> => {
+        throw new Error('tool explosion');
+      },
+    );
+
+    const result = await step(provider, '', toolset, []);
+    const toolResults = await result.toolResults();
+
+    expect(toolResults).toHaveLength(2);
+    // First tool succeeded
+    expect(toolResults[0]!.returnValue.isError).toBe(false);
+    expect(toolResults[0]!.returnValue.output).toBe('success');
+    // Second tool errored
+    expect(toolResults[1]!.returnValue.isError).toBe(true);
+    expect(toolResults[1]!.returnValue.message).toBe('Error running tool: tool explosion');
+  });
+});
+
+describe('stress: mergeInPlace edge cases', () => {
+  it('ThinkPart(encrypted="sig") + ThinkPart refuses to merge', () => {
+    const target: ThinkPart = { type: 'think', think: 'done thinking', encrypted: 'sig' };
+    const source: ThinkPart = { type: 'think', think: ' more thoughts' };
+
+    const merged = mergeInPlace(target, source);
+
+    expect(merged).toBe(false);
+    // Target should remain unchanged
+    expect(target.think).toBe('done thinking');
+    expect(target.encrypted).toBe('sig');
+  });
+
+  it('ThinkPart + ThinkPart(encrypted) sets encrypted on merge', () => {
+    const target: ThinkPart = { type: 'think', think: 'initial' };
+    const source: ThinkPart = { type: 'think', think: '', encrypted: 'new-sig' };
+
+    const merged = mergeInPlace(target, source);
+
+    expect(merged).toBe(true);
+    expect(target.think).toBe('initial');
+    expect(target.encrypted).toBe('new-sig');
+  });
+
+  it('ThinkPart(encrypted) + ThinkPart(encrypted) refuses to merge', () => {
+    const target: ThinkPart = { type: 'think', think: 'a', encrypted: 'sig-1' };
+    const source: ThinkPart = { type: 'think', think: 'b', encrypted: 'sig-2' };
+
+    const merged = mergeInPlace(target, source);
+
+    expect(merged).toBe(false);
+    expect(target.think).toBe('a');
+    expect(target.encrypted).toBe('sig-1');
+  });
+});
+
+describe('stress: consecutive different type parts', () => {
+  it('TextPart -> ThinkPart -> ToolCall -> ToolCallPart -> TextPart merges correctly', async () => {
+    const parts: StreamedMessagePart[] = [
+      { type: 'text', text: 'Hello ' },
+      { type: 'text', text: 'world' }, // should merge with previous text
+      { type: 'think', think: 'Let me think...' },
+      { type: 'think', think: ' more thinking' }, // should merge with previous think
+      {
+        type: 'function',
+        id: 'tc-1',
+        function: { name: 'search', arguments: null },
+      },
+      { type: 'tool_call_part', argumentsPart: '{"q":' }, // merges into ToolCall
+      { type: 'tool_call_part', argumentsPart: '"test"}' }, // merges into ToolCall
+      { type: 'text', text: 'After tool call' }, // new text part, cannot merge with ToolCall
+    ];
+
+    const provider = new MockChatProvider(parts);
+    const result = await generate(provider, '', [], []);
+
+    // Verify content parts
+    expect(result.message.content).toHaveLength(3);
+
+    // First: merged text "Hello world"
+    expect(result.message.content[0]).toEqual({ type: 'text', text: 'Hello world' });
+
+    // Second: merged think "Let me think... more thinking"
+    expect(result.message.content[1]).toEqual({
+      type: 'think',
+      think: 'Let me think... more thinking',
+    });
+
+    // Third: "After tool call" text
+    expect(result.message.content[2]).toEqual({ type: 'text', text: 'After tool call' });
+
+    // Verify tool calls
+    expect(result.message.toolCalls).toHaveLength(1);
+    expect(result.message.toolCalls[0]).toEqual({
+      type: 'function',
+      id: 'tc-1',
+      function: { name: 'search', arguments: '{"q":"test"}' },
+    });
+  });
+
+  it('interleaved: text -> think -> text -> think produces 4 separate parts', async () => {
+    const parts: StreamedMessagePart[] = [
+      { type: 'text', text: 'A' },
+      { type: 'think', think: 'B' },
+      { type: 'text', text: 'C' },
+      { type: 'think', think: 'D' },
+    ];
+
+    const provider = new MockChatProvider(parts);
+    const result = await generate(provider, '', [], []);
+
+    // Each type switch should produce a new part (no merging across types)
+    expect(result.message.content).toHaveLength(4);
+    expect(result.message.content[0]).toEqual({ type: 'text', text: 'A' });
+    expect(result.message.content[1]).toEqual({ type: 'think', think: 'B' });
+    expect(result.message.content[2]).toEqual({ type: 'text', text: 'C' });
+    expect(result.message.content[3]).toEqual({ type: 'think', think: 'D' });
+  });
+
+  it('multiple ToolCalls without ToolCallParts are separate', async () => {
+    const parts: StreamedMessagePart[] = [
+      { type: 'text', text: 'Calling tools' },
+      {
+        type: 'function',
+        id: 'tc-1',
+        function: { name: 'tool_a', arguments: '{"x":1}' },
+      },
+      {
+        type: 'function',
+        id: 'tc-2',
+        function: { name: 'tool_b', arguments: '{"y":2}' },
+      },
+    ];
+
+    const provider = new MockChatProvider(parts);
+    const result = await generate(provider, '', [], []);
+
+    expect(result.message.content).toHaveLength(1);
+    expect(result.message.toolCalls).toHaveLength(2);
+    expect(result.message.toolCalls[0]!.id).toBe('tc-1');
+    expect(result.message.toolCalls[1]!.id).toBe('tc-2');
+  });
+});
diff --git a/packages/kosong/test/tool-message-conversion.test.ts b/packages/kosong/test/tool-message-conversion.test.ts
new file mode 100644
index 000000000..7ea544924
--- /dev/null
+++ b/packages/kosong/test/tool-message-conversion.test.ts
@@ -0,0 +1,82 @@
+import type { Message } from '#/message';
+import { convertToolMessageContent } from '#/providers/openai-common';
+import { describe, expect, test } from 'vitest';
+
+describe('convertToolMessageContent', () => {
+  test('extract_text merges multiple text parts into a single string', () => {
+    const msg: Message = {
+      role: 'tool',
+      content: [
+        { type: 'text', text: 'Result: ' },
+        { type: 'text', text: '42' },
+      ],
+      toolCalls: [],
+      toolCallId: 'tc_001',
+    };
+    const result = convertToolMessageContent(msg, 'extract_text');
+    expect(typeof result).toBe('string');
+    expect(result).toBe('Result: 42');
+  });
+
+  test('extract_text returns empty string for empty content', () => {
+    const msg: Message = {
+      role: 'tool',
+      content: [],
+      toolCalls: [],
+      toolCallId: 'tc_002',
+    };
+    const result = convertToolMessageContent(msg, 'extract_text');
+    expect(result).toBe('');
+  });
+
+  test('extract_text skips non-text content parts', () => {
+    const msg: Message = {
+      role: 'tool',
+      content: [
+        { type: 'text', text: 'Before' },
+        { type: 'image_url', imageUrl: { url: 'data:image/png;base64,xxx' } },
+        { type: 'text', text: 'After' },
+      ],
+      toolCalls: [],
+      toolCallId: 'tc_003',
+    };
+    const result = convertToolMessageContent(msg, 'extract_text');
+    expect(result).toBe('BeforeAfter');
+  });
+
+  test('null conversion returns an array of OpenAI content parts', () => {
+    const msg: Message = {
+      role: 'tool',
+      content: [
+        { type: 'text', text: 'hello' },
+        { type: 'text', text: 'world' },
+      ],
+      toolCalls: [],
+      toolCallId: 'tc_004',
+    };
+    const result = convertToolMessageContent(msg, null);
+    expect(Array.isArray(result)).toBe(true);
+    expect(result).toHaveLength(2);
+    if (Array.isArray(result)) {
+      expect(result[0]).toMatchObject({ type: 'text', text: 'hello' });
+      expect(result[1]).toMatchObject({ type: 'text', text: 'world' });
+    }
+  });
+
+  test('null conversion filters out ThinkPart (returns null from convertContentPart)', () => {
+    const msg: Message = {
+      role: 'tool',
+      content: [
+        { type: 'text', text: 'visible' },
+        { type: 'think', think: 'hidden reasoning' },
+      ],
+      toolCalls: [],
+      toolCallId: 'tc_005',
+    };
+    const result = convertToolMessageContent(msg, null);
+    if (Array.isArray(result)) {
+      expect(result).toHaveLength(1);
+      expect(result[0]).toMatchObject({ type: 'text', text: 'visible' });
+    }
+  });
+});
diff --git a/packages/kosong/test/type-safety-negative.ts b/packages/kosong/test/type-safety-negative.ts
new file mode 100644
index 000000000..9907efdac
--- /dev/null
+++ b/packages/kosong/test/type-safety-negative.ts
@@ -0,0 +1,79 @@
+/**
+ * Negative type-safety checks.
+ *
+ * Each @ts-expect-error below marks code that MUST be rejected by tsc.
+ * If tsc does NOT reject it, the @ts-expect-error itself becomes an error
+ * ("Unused '@ts-expect-error' directive"), proving the type system has a gap.
+ *
+ * Run: pnpm exec tsc --noEmit -p tsconfig.type-negative.json
+ */
+
+import type { Message, ToolCall, StreamedMessagePart, TextPart } from '#/message';
+// Assigning `undefined` to an optional property should be rejected
+// when exactOptionalPropertyTypes is enabled.
+
+// @ts-expect-error — toolCallId is optional but not `| undefined`
+const msg1: Message = {
+  role: 'user',
+  content: [{ type: 'text', text: 'hi' }],
+  toolCallId: undefined,
+};
+
+// @ts-expect-error — toolCalls is required ToolCall[] and cannot be undefined
+const msg2: Message = {
+  role: 'assistant',
+  content: [],
+  toolCalls: undefined,
+};
+
+// @ts-expect-error — name is optional but not `| undefined`
+const msg3: Message = {
+  role: 'user',
+  content: [{ type: 'text', text: 'hi' }],
+  name: undefined,
+};
+
+// @ts-expect-error — partial is optional but not `| undefined`
+const msg4: Message = {
+  role: 'assistant',
+  content: [],
+  partial: undefined,
+};
+
+// @ts-expect-error — extras on ToolCall is optional but not `| undefined`
+const tc1: ToolCall = {
+  type: 'function',
+  id: 'call-1',
+  function: { name: 'test', arguments: null },
+  extras: undefined,
+};
+// Accessing a property from the wrong variant should fail.
+
+const textPart: TextPart = { type: 'text', text: 'hello' };
+
+// @ts-expect-error — TextPart does not have 'think' property
+const _badAccess1: string = textPart.think;
+
+// @ts-expect-error — TextPart does not have 'imageUrl' property
+const _badAccess2: string = textPart.imageUrl;
+const msg5: Message = {
+  // @ts-expect-error — 'invalid' is not a valid Role
+  role: 'invalid',
+  content: [],
+};
+const badPart: StreamedMessagePart = {
+  // @ts-expect-error — 'unknown_type' is not a valid part type
+  type: 'unknown_type',
+  text: 'hello',
+};
+
+// Suppress "unused variable" warnings — these variables exist only for type checking.
+void msg1;
+void msg2;
+void msg3;
+void msg4;
+void tc1;
+void _badAccess1;
+void _badAccess2;
+void msg5;
+void badPart;
diff --git a/packages/kosong/test/type-safety.test.ts b/packages/kosong/test/type-safety.test.ts
new file mode 100644
index 000000000..c6a8215a9
--- /dev/null
+++ b/packages/kosong/test/type-safety.test.ts
@@ -0,0 +1,164 @@
+import type {
+  AudioURLPart,
+  ImageURLPart,
+  StreamedMessagePart,
+  TextPart,
+  ThinkPart,
+  ToolCall,
+  ToolCallPart,
+  VideoURLPart,
+} from '#/message';
+import { describe, expect, it } from 'vitest';
+/**
+ * This function exercises TypeScript's discriminated-union narrowing.
+ * If the type system is correct, every branch accesses only properties
+ * that exist on the narrowed type — no casts, no `any`.
+ */
+function processPartSafely(part: StreamedMessagePart): string {
+  switch (part.type) {
+    case 'text':
+      return part.text; // TextPart.text -> string
+    case 'think':
+      return part.think; // ThinkPart.think -> string
+    case 'image_url':
+      return part.imageUrl.url; // ImageURLPart.imageUrl.url -> string
+    case 'audio_url':
+      return part.audioUrl.url; // AudioURLPart.audioUrl.url -> string
+    case 'video_url':
+      return part.videoUrl.url; // VideoURLPart.videoUrl.url -> string
+    case 'function':
+      return part.function.name; // ToolCall.function.name -> string
+    case 'tool_call_part':
+      return part.argumentsPart ?? ''; // ToolCallPart.argumentsPart -> string | null
+    default: {
+      const _exhaustive: never = part;
+      throw new Error(`Unknown part type: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+
+describe('StreamedMessagePart discriminated union narrowing', () => {
+  it('narrows TextPart via switch', () => {
+    const part: StreamedMessagePart = { type: 'text', text: 'hello' };
+    expect(processPartSafely(part)).toBe('hello');
+  });
+
+  it('narrows ThinkPart via switch', () => {
+    const part: StreamedMessagePart = { type: 'think', think: 'reasoning...' };
+    expect(processPartSafely(part)).toBe('reasoning...');
+  });
+
+  it('narrows ImageURLPart via switch', () => {
+    const part: StreamedMessagePart = {
+      type: 'image_url',
+      imageUrl: { url: 'https://example.com/img.png' },
+    };
+    expect(processPartSafely(part)).toBe('https://example.com/img.png');
+  });
+
+  it('narrows AudioURLPart via switch', () => {
+    const part: StreamedMessagePart = {
+      type: 'audio_url',
+      audioUrl: { url: 'https://example.com/audio.mp3' },
+    };
+    expect(processPartSafely(part)).toBe('https://example.com/audio.mp3');
+  });
+
+  it('narrows VideoURLPart via switch', () => {
+    const part: StreamedMessagePart = {
+      type: 'video_url',
+      videoUrl: { url: 'https://example.com/video.mp4' },
+    };
+    expect(processPartSafely(part)).toBe('https://example.com/video.mp4');
+  });
+
+  it('narrows ToolCall via switch', () => {
+    const part: StreamedMessagePart = {
+      type: 'function',
+      id: 'call-1',
+      function: { name: 'search', arguments: '{"q":"test"}' },
+    };
+    expect(processPartSafely(part)).toBe('search');
+  });
+
+  it('narrows ToolCallPart via switch (non-null)', () => {
+    const part: StreamedMessagePart = {
+      type: 'tool_call_part',
+      argumentsPart: '{"key":"value"}',
+    };
+    expect(processPartSafely(part)).toBe('{"key":"value"}');
+  });
+
+  it('narrows ToolCallPart via switch (null argumentsPart)', () => {
+    const part: StreamedMessagePart = {
+      type: 'tool_call_part',
+      argumentsPart: null,
+    };
+    expect(processPartSafely(part)).toBe('');
+  });
+});
+describe('exhaustiveness check', () => {
+  it('switch covers all discriminants — never type reached', () => {
+    // If StreamedMessagePart gains a new variant and processPartSafely
+    // does not handle it, TypeScript will report:
+    //   "Function lacks ending return statement and return type does
+    //    not include 'undefined'."
+    // This is a compile-time guarantee, not a runtime one.
+    // We simply verify the function returns a string for every current variant.
+    const allParts: StreamedMessagePart[] = [
+      { type: 'text', text: 'a' },
+      { type: 'think', think: 'b' },
+      { type: 'image_url', imageUrl: { url: 'c' } },
+      { type: 'audio_url', audioUrl: { url: 'd' } },
+      { type: 'video_url', videoUrl: { url: 'e' } },
+      { type: 'function', id: 'f', function: { name: 'g', arguments: null } },
+      { type: 'tool_call_part', argumentsPart: 'h' },
+    ];
+    for (const part of allParts) {
+      expect(typeof processPartSafely(part)).toBe('string');
+    }
+  });
+});
+describe('type assignability', () => {
+  it('TextPart is assignable to StreamedMessagePart', () => {
+    const text: TextPart = { type: 'text', text: 'x' };
+    const _part: StreamedMessagePart = text;
+    expect(_part.type).toBe('text');
+  });
+
+  it('ThinkPart is assignable to StreamedMessagePart', () => {
+    const think: ThinkPart = { type: 'think', think: 'x' };
+    const _part: StreamedMessagePart = think;
+    expect(_part.type).toBe('think');
+  });
+
+  it('ImageURLPart is assignable to StreamedMessagePart', () => {
+    const img: ImageURLPart = { type: 'image_url', imageUrl: { url: 'x' } };
+    const _part: StreamedMessagePart = img;
+    expect(_part.type).toBe('image_url');
+  });
+
+  it('AudioURLPart is assignable to StreamedMessagePart', () => {
+    const audio: AudioURLPart = { type: 'audio_url', audioUrl: { url: 'x' } };
+    const _part: StreamedMessagePart = audio;
+    expect(_part.type).toBe('audio_url');
+  });
+
+  it('VideoURLPart is assignable to StreamedMessagePart', () => {
+    const video: VideoURLPart = { type: 'video_url', videoUrl: { url: 'x' } };
+    const _part: StreamedMessagePart = video;
+    expect(_part.type).toBe('video_url');
+  });
+
+  it('ToolCall is assignable to StreamedMessagePart', () => {
+    const tc: ToolCall = { type: 'function', id: 'c', function: { name: 'f', arguments: null } };
+    const _part: StreamedMessagePart = tc;
+    expect(_part.type).toBe('function');
+  });
+
+  it('ToolCallPart is assignable to StreamedMessagePart', () => {
+    const tcp: ToolCallPart = { type: 'tool_call_part', argumentsPart: null };
+    const _part: StreamedMessagePart = tcp;
+    expect(_part.type).toBe('tool_call_part');
+  });
+});
diff --git a/packages/kosong/test/typed-tool.test.ts b/packages/kosong/test/typed-tool.test.ts
new file mode 100644
index 000000000..15f054da9
--- /dev/null
+++ b/packages/kosong/test/typed-tool.test.ts
@@ -0,0 +1,154 @@
+import { SimpleToolset, toolError, toolOk } from './fixtures/simple-toolset';
+import type { ToolReturnValue } from './fixtures/simple-toolset';
+import { createTypedTool } from './fixtures/typed-tool';
+import { describe, expect, test } from 'vitest';
+import { z } from 'zod';
+
+describe('createTypedTool', () => {
+  test('creates a tool with zod schema and typed handler', async () => {
+    const addTool = createTypedTool({
+      name: 'add',
+      description: 'Adds two numbers',
+      params: z.object({
+        a: z.number().describe('First number'),
+        b: z.number().describe('Second number'),
+      }),
+      handler: async (params): Promise<ToolReturnValue> => {
+        // params is typed as { a: number; b: number }
+        return toolOk({ output: String(params.a + params.b) });
+      },
+    });
+
+    expect(addTool.tool.name).toBe('add');
+    expect(addTool.tool.description).toBe('Adds two numbers');
+    expect(addTool.tool.parameters).toMatchObject({
+      type: 'object',
+      properties: expect.objectContaining({
+        a: expect.any(Object),
+        b: expect.any(Object),
+      }),
+    });
+
+    const result = await addTool.handler({ a: 2, b: 3 } as never);
+    expect(result.isError).toBe(false);
+    expect(result.output).toBe('5');
+  });
+
+  test('returns toolValidateError for missing required fields', async () => {
+    const tool = createTypedTool({
+      name: 'greet',
+      description: 'Greets a user',
+      params: z.object({
+        name: z.string(),
+      }),
+      handler: async (params) => toolOk({ output: `Hello, ${params.name}` }),
+    });
+
+    // Pass invalid args (missing 'name')
+    const result = await tool.handler({} as never);
+    expect(result.isError).toBe(true);
+    expect(result.message).toContain('name');
+  });
+
+  test('returns toolValidateError for wrong type', async () => {
+    const tool = createTypedTool({
+      name: 'multiply',
+      description: 'Multiplies two numbers',
+      params: z.object({
+        a: z.number(),
+        b: z.number(),
+      }),
+      handler: async (params) => toolOk({ output: String(params.a * params.b) }),
+    });
+
+    // Pass string where number expected
+    const result = await tool.handler({ a: '2', b: 3 } as never);
+    expect(result.isError).toBe(true);
+  });
+
+  test('returns toolValidateError for unknown keys to match exported schema', async () => {
+    const tool = createTypedTool({
+      name: 'strict_number',
+      description: 'Accepts only x',
+      params: z.object({
+        x: z.number(),
+      }),
+      handler: async (params) => toolOk({ output: String(params.x) }),
+    });
+
+    expect(tool.tool.parameters).toMatchObject({
+      type: 'object',
+      additionalProperties: false,
+    });
+
+    const result = await tool.handler({ x: 1, extra: 2 } as never);
+    expect(result.isError).toBe(true);
+    expect(result.message).toContain('extra');
+  });
+
+  test('integrates with SimpleToolset', async () => {
+    const echoTool = createTypedTool({
+      name: 'echo',
+      description: 'Echoes the input',
+      params: z.object({ text: z.string() }),
+      handler: async (params) => toolOk({ output: params.text }),
+    });
+
+    const toolset = new SimpleToolset();
+    toolset.add(echoTool.tool, echoTool.handler);
+
+    const result = await toolset.handle({
+      type: 'function',
+      id: 'tc_001',
+      function: { name: 'echo', arguments: JSON.stringify({ text: 'hello' }) },
+    });
+
+    expect(result.returnValue.isError).toBe(false);
+    expect(result.returnValue.output).toBe('hello');
+  });
+
+  test('supports nested zod schemas', async () => {
+    const tool = createTypedTool({
+      name: 'process',
+      description: 'Processes a complex object',
+      params: z.object({
+        user: z.object({
+          name: z.string(),
+          age: z.number().optional(),
+        }),
+        tags: z.array(z.string()),
+      }),
+      handler: async (params) =>
+        toolOk({
+          output: `${params.user.name} has ${params.tags.length} tags`,
+        }),
+    });
+
+    const result = await tool.handler({
+      user: { name: 'Alice', age: 30 },
+      tags: ['a', 'b', 'c'],
+    } as never);
+    expect(result.isError).toBe(false);
+    expect(result.output).toBe('Alice has 3 tags');
+  });
+
+  test('handler errors are caught and returned as tool errors', async () => {
+    // Note: createTypedTool's handler does NOT catch user errors;
+    // SimpleToolset.handle catches them. We test that the user can also
+    // return toolError manually if they want.
+    const tool2 = createTypedTool({
+      name: 'safe',
+      description: 'Returns error',
+      params: z.object({ x: z.number() }),
+      handler: async (params) =>
+        toolError({
+          message: `failed for x=${params.x}`,
+          brief: 'fail',
+        }),
+    });
+
+    const result = await tool2.handler({ x: 5 } as never);
+    expect(result.isError).toBe(true);
+    expect(result.message).toContain('failed for x=5');
+  });
+});
diff --git a/packages/kosong/test/usage.test.ts b/packages/kosong/test/usage.test.ts
new file mode 100644
index 000000000..d00da5ecd
--- /dev/null
+++ b/packages/kosong/test/usage.test.ts
@@ -0,0 +1,78 @@
+import type { TokenUsage } from '#/usage';
+import { addUsage, emptyUsage, grandTotal, inputTotal } from '#/usage';
+import { describe, expect, it } from 'vitest';
+
+describe('emptyUsage', () => {
+  it('returns all zeros', () => {
+    const usage = emptyUsage();
+    expect(usage.inputOther).toBe(0);
+    expect(usage.output).toBe(0);
+    expect(usage.inputCacheRead).toBe(0);
+    expect(usage.inputCacheCreation).toBe(0);
+  });
+});
+
+describe('inputTotal', () => {
+  it('sums all input fields', () => {
+    const usage: TokenUsage = {
+      inputOther: 100,
+      output: 50,
+      inputCacheRead: 200,
+      inputCacheCreation: 30,
+    };
+    expect(inputTotal(usage)).toBe(330);
+  });
+
+  it('returns 0 for empty usage', () => {
+    expect(inputTotal(emptyUsage())).toBe(0);
+  });
+});
+
+describe('grandTotal', () => {
+  it('sums input total and output', () => {
+    const usage: TokenUsage = {
+      inputOther: 100,
+      output: 50,
+      inputCacheRead: 200,
+      inputCacheCreation: 30,
+    };
+    expect(grandTotal(usage)).toBe(380);
+  });
+
+  it('returns 0 for empty usage', () => {
+    expect(grandTotal(emptyUsage())).toBe(0);
+  });
+});
+
+describe('addUsage', () => {
+  it('sums two usage values', () => {
+    const a: TokenUsage = {
+      inputOther: 10,
+      output: 20,
+      inputCacheRead: 30,
+      inputCacheCreation: 40,
+    };
+    const b: TokenUsage = {
+      inputOther: 5,
+      output: 15,
+      inputCacheRead: 25,
+      inputCacheCreation: 35,
+    };
+    const result = addUsage(a, b);
+    expect(result.inputOther).toBe(15);
+    expect(result.output).toBe(35);
+    expect(result.inputCacheRead).toBe(55);
+    expect(result.inputCacheCreation).toBe(75);
+  });
+
+  it('adding empty usage returns the other', () => {
+    const usage: TokenUsage = {
+      inputOther: 100,
+      output: 200,
+      inputCacheRead: 300,
+      inputCacheCreation: 400,
+    };
+    const result = addUsage(usage, emptyUsage());
+    expect(result).toEqual(usage);
+  });
+});
diff --git a/packages/kosong/tsconfig.json b/packages/kosong/tsconfig.json
new file mode 100644
index 000000000..fd6ddf1b9
--- /dev/null
+++ b/packages/kosong/tsconfig.json
@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {},
+  "include": ["src", "test"],
+  "exclude": ["test/type-safety-negative.ts"]
+}
diff --git a/packages/kosong/tsconfig.type-negative.json b/packages/kosong/tsconfig.type-negative.json
new file mode 100644
index 000000000..f0b5d6b80
--- /dev/null
+++ b/packages/kosong/tsconfig.type-negative.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts", "test/type-safety-negative.ts"]
+}
diff --git a/packages/kosong/tsdown.config.ts b/packages/kosong/tsdown.config.ts
new file mode 100644
index 000000000..00783406f
--- /dev/null
+++ b/packages/kosong/tsdown.config.ts
@@ -0,0 +1,17 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: [
+    './src/index.ts',
+    './src/providers/kimi.ts',
+    './src/providers/openai-legacy.ts',
+    './src/providers/openai-responses.ts',
+    './src/providers/anthropic.ts',
+    './src/providers/google-genai.ts',
+    './src/providers/openai-common.ts',
+  ],
+  format: ['esm'],
+  dts: true,
+  outDir: 'dist',
+  clean: true,
+});
diff --git a/packages/kosong/vitest.config.ts b/packages/kosong/vitest.config.ts
new file mode 100644
index 000000000..d28607af8
--- /dev/null
+++ b/packages/kosong/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    name: 'kosong',
+    include: ['test/**/*.test.ts'],
+  },
+});
diff --git a/packages/migration-legacy/package.json b/packages/migration-legacy/package.json
new file mode 100644
index 000000000..a54dd8313
--- /dev/null
+++ b/packages/migration-legacy/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@moonshot-ai/migration-legacy",
+  "version": "0.1.1",
+  "description": "Migrate kimi-cli (~/.kimi/) data into kimi-code (~/.kimi-code/).",
+  "license": "MIT",
+  "type": "module",
+  "private": true,
+  "files": [
+    "dist"
+  ],
+  "imports": {
+    "#/*": [
+      "./src/*.ts",
+      "./src/*/index.ts"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@moonshot-ai/agent-core": "workspace:^",
+    "smol-toml": "^1.6.1",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@moonshot-ai/kaos": "workspace:^"
+  }
+}
diff --git a/packages/migration-legacy/src/atomic-write.ts b/packages/migration-legacy/src/atomic-write.ts
new file mode 100644
index 000000000..d2d76689e
--- /dev/null
+++ b/packages/migration-legacy/src/atomic-write.ts
@@ -0,0 +1,19 @@
+import { chmod, rename, writeFile } from 'node:fs/promises';
+
+/**
+ * Write atomically: write to a temp sibling then rename over the target.
+ *
+ * A crashed or interrupted write leaves the temp file behind but never a
+ * partially-written target — `rename` is atomic on POSIX. Use this for any
+ * write that overwrites an existing user-owned file.
+ */
+export async function atomicWrite(path: string, data: string): Promise<void> {
+  const tmp = `${path}.${process.pid}.tmp`;
+  // Migrated config/MCP files can carry provider API keys. Create them
+  // private (0600) so they are never group/world-readable, even when the
+  // target home directory itself has permissive permissions. `chmod` covers
+  // the case where a stale temp file from a crashed run already exists.
+  await writeFile(tmp, data, { encoding: 'utf-8', mode: 0o600 });
+  await chmod(tmp, 0o600);
+  await rename(tmp, path);
+}
diff --git a/packages/migration-legacy/src/detect.ts b/packages/migration-legacy/src/detect.ts
new file mode 100644
index 000000000..ec2a9ac46
--- /dev/null
+++ b/packages/migration-legacy/src/detect.ts
@@ -0,0 +1,132 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { OldKimiJsonSchema, OldSessionStateSchema } from './kimi-cli-schema.js';
+import {
+  sourceConfigToml,
+  sourceMcpJson,
+  sourceCredentialsDir,
+  sourceUserHistoryDir,
+  sourcePluginsDir,
+  sourceMcpOauthDir,
+  sourceSessionsDir,
+  sourceKimiJson,
+} from './paths.js';
+import type { MigrationPlan, SessionEntry, WorkDirEntry } from './types.js';
+import { classifySessionDir } from './sessions/classify.js';
+import { oldMd5BucketName } from './sessions/workdir-bucket.js';
+
+const MD5_HEX_RE = /^[0-9a-f]{32}$/;
+
+interface WorkdirMeta {
+  readonly path: string;
+  readonly kaos: string;
+}
+
+export async function detectMigration(opts: { sourcePath: string }): Promise<MigrationPlan> {
+  const src = opts.sourcePath;
+
+  const hasConfig = existsSync(sourceConfigToml(src));
+  const hasMcp = existsSync(sourceMcpJson(src));
+  const hasUserHistory = existsSync(sourceUserHistoryDir(src));
+
+  const oauthCredentials = await listDirSafe(sourceCredentialsDir(src), (n) =>
+    n.endsWith('.json'),
+  );
+  const detectedPlugins = await listDirSafe(sourcePluginsDir(src), () => true);
+  const detectedMcpOauthServers = await listDirSafe(sourceMcpOauthDir(src), () => true);
+
+  // Reverse-lookup workdir from kimi.json
+  const workdirMap = new Map<string, WorkdirMeta>();
+  try {
+    const text = await readFile(sourceKimiJson(src), 'utf-8');
+    const parsed = OldKimiJsonSchema.parse(JSON.parse(text));
+    for (const wd of parsed.work_dirs) {
+      workdirMap.set(oldMd5BucketName(wd.path), { path: wd.path, kaos: wd.kaos });
+    }
+  } catch {
+    // no kimi.json or unparseable — sessions list will be empty
+  }
+
+  const workdirs: WorkDirEntry[] = [];
+  let totalSessions = 0;
+
+  try {
+    const sessionsRoot = sourceSessionsDir(src);
+    const bucketNames = await readdir(sessionsRoot);
+    for (const bucketName of bucketNames) {
+      // Skip non-local-kaos buckets (`<kaos>_<md5>`) and unknown formats.
+      if (!MD5_HEX_RE.test(bucketName)) continue;
+      const wd = workdirMap.get(bucketName);
+      if (wd === undefined) continue;
+      if (wd.kaos !== 'local') continue;
+
+      const bucketPath = join(sessionsRoot, bucketName);
+      let uuids: string[];
+      try {
+        uuids = await readdir(bucketPath);
+      } catch {
+        continue;
+      }
+
+      const sessions: SessionEntry[] = [];
+      for (const uuid of uuids) {
+        const sessionDir = join(bucketPath, uuid);
+        const cls = await classifySessionDir(sessionDir);
+        if (cls !== 'real') continue;
+        const wireMtime = await readWireMtime(sessionDir);
+        sessions.push({ uuid, oldDir: sessionDir, wireMtime });
+        totalSessions++;
+      }
+
+      if (sessions.length > 0) {
+        workdirs.push({ oldHashDir: bucketPath, workdirPath: wd.path, sessions });
+      }
+    }
+  } catch {
+    // sessions dir missing — leave workdirs empty
+  }
+
+  return {
+    sourceHome: src,
+    hasConfig,
+    hasMcp,
+    hasUserHistory,
+    oauthCredentials,
+    workdirs,
+    detectedPlugins,
+    detectedMcpOauthServers,
+    totalSessions,
+  };
+}
+
+async function listDirSafe(
+  dir: string,
+  filter: (name: string) => boolean,
+): Promise<string[]> {
+  try {
+    const names = await readdir(dir);
+    return names.filter(filter);
+  } catch {
+    return [];
+  }
+}
+
+async function readWireMtime(sessionDir: string): Promise<number> {
+  try {
+    const text = await readFile(join(sessionDir, 'state.json'), 'utf-8');
+    const parsed = OldSessionStateSchema.parse(JSON.parse(text));
+    if (parsed.wire_mtime !== null && parsed.wire_mtime !== undefined) {
+      return parsed.wire_mtime * 1000;
+    }
+  } catch {
+    // fall through to wire.jsonl mtime
+  }
+  try {
+    const st = await stat(join(sessionDir, 'wire.jsonl'));
+    return st.mtimeMs;
+  } catch {
+    return 0;
+  }
+}
diff --git a/packages/migration-legacy/src/index.ts b/packages/migration-legacy/src/index.ts
new file mode 100644
index 000000000..5130c2ee5
--- /dev/null
+++ b/packages/migration-legacy/src/index.ts
@@ -0,0 +1,12 @@
+// Public API surface for the kimi-cli → kimi-code migration tool.
+
+export * from './types.js';
+export { detectMigration } from './detect.js';
+export { runMigration, type RunMigrationInput } from './run-migration.js';
+export {
+  resolveMigrationScope,
+  type MigrationPromptResult,
+  type AnyChoice,
+  type Prompt1Choice,
+  type Prompt2Choice,
+} from './prompt.js';
diff --git a/packages/migration-legacy/src/kimi-cli-schema.ts b/packages/migration-legacy/src/kimi-cli-schema.ts
new file mode 100644
index 000000000..7c46bc366
--- /dev/null
+++ b/packages/migration-legacy/src/kimi-cli-schema.ts
@@ -0,0 +1,45 @@
+import { z } from 'zod';
+
+// Mirrors kimi-cli's `Metadata` pydantic model (metadata.py:43–49).
+export const OldWorkDirMetaSchema = z.object({
+  path: z.string(),
+  kaos: z.string().default('local'),
+  last_session_id: z.string().nullable().optional(),
+});
+
+export const OldKimiJsonSchema = z.object({
+  work_dirs: z.array(OldWorkDirMetaSchema).default([]),
+});
+
+// Mirrors kimi-cli's `SessionState` (session_state.py:28–45).
+// We use `.passthrough()` because old persisted state may carry extra
+// fields from newer kimi-cli versions; we only consume a known subset.
+export const OldSessionStateSchema = z
+  .object({
+    version: z.number().optional(),
+    approval: z
+      .object({
+        yolo: z.boolean().optional(),
+        afk: z.boolean().optional(),
+        auto_approve_actions: z.array(z.string()).optional(),
+      })
+      .partial()
+      .optional(),
+    additional_dirs: z.array(z.string()).optional(),
+    custom_title: z.string().nullable().optional(),
+    title_generated: z.boolean().optional(),
+    title_generate_attempts: z.number().optional(),
+    plan_mode: z.boolean().optional(),
+    plan_session_id: z.string().nullable().optional(),
+    plan_slug: z.string().nullable().optional(),
+    wire_mtime: z.number().nullable().optional(),
+    archived: z.boolean().optional(),
+    archived_at: z.number().nullable().optional(),
+    auto_archive_exempt: z.boolean().optional(),
+    todos: z.array(z.unknown()).optional(),
+  })
+  .passthrough();
+
+export type OldKimiJson = z.infer<typeof OldKimiJsonSchema>;
+export type OldWorkDirMeta = z.infer<typeof OldWorkDirMetaSchema>;
+export type OldSessionState = z.infer<typeof OldSessionStateSchema>;
diff --git a/packages/migration-legacy/src/marker.ts b/packages/migration-legacy/src/marker.ts
new file mode 100644
index 000000000..611bd305b
--- /dev/null
+++ b/packages/migration-legacy/src/marker.ts
@@ -0,0 +1,82 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { migratedMarker } from './paths.js';
+
+export interface MarkerRun {
+  readonly startedAt: string;
+  readonly completedAt: string;
+  readonly migratorVersion: string;
+  readonly summary: Record<string, unknown>;
+}
+
+export interface MarkerData {
+  readonly version: 1;
+  readonly first_migrated_at: string;
+  readonly last_migrated_at: string;
+  readonly migrator_version: string;
+  readonly target_path: string;
+  readonly runs: readonly MarkerRun[];
+}
+
+export async function readMarker(sourceHome: string): Promise<MarkerData | undefined> {
+  try {
+    const text = await readFile(migratedMarker(sourceHome), 'utf-8');
+    const parsed = JSON.parse(text) as Partial<MarkerData>;
+    if (parsed.version !== 1) return undefined;
+    // A partially-written or hand-edited marker may keep `version` but lack a
+    // valid `runs` array; treating it as absent avoids `appendMarkerRun`
+    // throwing on `[...existing.runs, run]` and aborting a healthy rerun.
+    if (!Array.isArray(parsed.runs)) return undefined;
+    return parsed as MarkerData;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function writeMarker(
+  sourceHome: string,
+  run: MarkerRun & { readonly targetPath: string },
+): Promise<void> {
+  const data: MarkerData = {
+    version: 1,
+    first_migrated_at: run.startedAt,
+    last_migrated_at: run.completedAt,
+    migrator_version: run.migratorVersion,
+    target_path: run.targetPath,
+    runs: [
+      {
+        startedAt: run.startedAt,
+        completedAt: run.completedAt,
+        migratorVersion: run.migratorVersion,
+        summary: run.summary,
+      },
+    ],
+  };
+  await writeFile(migratedMarker(sourceHome), JSON.stringify(data, null, 2), 'utf-8');
+}
+
+export async function appendMarkerRun(
+  sourceHome: string,
+  run: MarkerRun & { readonly targetPath: string },
+): Promise<void> {
+  const existing = await readMarker(sourceHome);
+  if (existing === undefined) throw new Error('appendMarkerRun: no existing marker');
+  const updated: MarkerData = {
+    ...existing,
+    last_migrated_at: run.completedAt,
+    migrator_version: run.migratorVersion,
+    // Record the latest run's target so a rerun to a different KIMI_CODE_HOME
+    // updates the marker — otherwise `detectPendingMigration` keeps prompting
+    // for the new target even though it was just migrated.
+    target_path: run.targetPath,
+    runs: [
+      ...existing.runs,
+      {
+        startedAt: run.startedAt,
+        completedAt: run.completedAt,
+        migratorVersion: run.migratorVersion,
+        summary: run.summary,
+      },
+    ],
+  };
+  await writeFile(migratedMarker(sourceHome), JSON.stringify(updated, null, 2), 'utf-8');
+}
diff --git a/packages/migration-legacy/src/migration-errors-log.ts b/packages/migration-legacy/src/migration-errors-log.ts
new file mode 100644
index 000000000..b1b672761
--- /dev/null
+++ b/packages/migration-legacy/src/migration-errors-log.ts
@@ -0,0 +1,98 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+import { migrationErrorsLogFile } from './paths.js';
+
+export interface MigrationFailureEntry {
+  readonly sourcePath: string;
+  readonly reason: string;
+}
+
+export interface MigrationErrorsLogInput {
+  readonly startedAt: string;
+  readonly failures: readonly MigrationFailureEntry[];
+}
+
+/**
+ * Append this run's outcome to `<targetHome>/migration-errors.log` — an
+ * append-only cross-run diagnostic record.
+ *
+ * Each call contributes one block prefixed by a timestamped header. A run
+ * with failures appends per-session diagnostics (source path, reason, and a
+ * `context.jsonl` line-count + role histogram). A run with no failures
+ * appends a one-line `no failures.` marker — the file therefore captures the
+ * complete history of every migration attempt, so a single log shared by a
+ * user covers all retries.
+ *
+ * Best-effort: a finished migration must not be turned into a failure by a
+ * log write error, so all I/O is guarded.
+ */
+export async function writeMigrationErrorsLog(
+  targetHome: string,
+  input: MigrationErrorsLogInput,
+): Promise<void> {
+  const lines: string[] = [`===== migration run @ ${input.startedAt} =====`];
+
+  if (input.failures.length === 0) {
+    lines.push('no failures.', '');
+  } else {
+    lines.push(`${input.failures.length} session(s) failed to migrate.`, '');
+    let index = 0;
+    for (const failure of input.failures) {
+      index += 1;
+      lines.push(
+        `[${index}] ${basename(failure.sourcePath)}`,
+        `  source: ${failure.sourcePath}`,
+        `  reason: ${failure.reason}`,
+        `  ${await describeContext(failure.sourcePath)}`,
+        '',
+      );
+    }
+  }
+
+  try {
+    await mkdir(targetHome, { recursive: true, mode: 0o700 });
+    // POSIX `O_APPEND` makes a single `appendFile` atomic — concurrent runs
+    // would still produce well-formed blocks. `mode` only applies when the
+    // file is created; an existing log keeps its prior 0600.
+    await appendFile(migrationErrorsLogFile(targetHome), lines.join('\n'), {
+      mode: 0o600,
+    });
+  } catch {
+    // Best-effort — see the doc comment above.
+  }
+}
+
+/**
+ * One-line `context.jsonl` summary for a failed session: line count plus a
+ * role histogram. The histogram is the key diagnostic — it tells a genuine
+ * write failure from a session whose context held only markers.
+ */
+async function describeContext(sessionDir: string): Promise<string> {
+  let text: string;
+  try {
+    text = await readFile(join(sessionDir, 'context.jsonl'), 'utf-8');
+  } catch {
+    return 'context.jsonl: unreadable';
+  }
+  const lines = text.split(/\r?\n/).filter((line) => line.trim() !== '');
+  const roleCounts = new Map<string, number>();
+  for (const line of lines) {
+    let role = '<unparseable>';
+    try {
+      const parsed: unknown = JSON.parse(line);
+      if (typeof parsed === 'object' && parsed !== null) {
+        const raw = (parsed as Record<string, unknown>)['role'];
+        role = typeof raw === 'string' ? raw : '<no-role>';
+      }
+    } catch {
+      // role stays '<unparseable>'
+    }
+    roleCounts.set(role, (roleCounts.get(role) ?? 0) + 1);
+  }
+  const histogram = [...roleCounts.entries()]
+    .toSorted((a, b) => b[1] - a[1])
+    .map(([role, count]) => `${role}=${count}`)
+    .join(' ');
+  return `context.jsonl: ${lines.length} lines${histogram === '' ? '' : ` - ${histogram}`}`;
+}
diff --git a/packages/migration-legacy/src/paths.ts b/packages/migration-legacy/src/paths.ts
new file mode 100644
index 000000000..37f785f8c
--- /dev/null
+++ b/packages/migration-legacy/src/paths.ts
@@ -0,0 +1,31 @@
+import { join } from 'node:path';
+
+// Source (~/.kimi/) paths
+export const sourceCredentialsDir = (src: string): string => join(src, 'credentials');
+export const sourceSessionsDir = (src: string): string => join(src, 'sessions');
+export const sourceUserHistoryDir = (src: string): string => join(src, 'user-history');
+export const sourceKimiJson = (src: string): string => join(src, 'kimi.json');
+export const sourceConfigToml = (src: string): string => join(src, 'config.toml');
+export const sourceMcpJson = (src: string): string => join(src, 'mcp.json');
+export const sourceMcpOauthDir = (src: string): string => join(src, 'mcp-oauth');
+export const sourcePluginsDir = (src: string): string => join(src, 'plugins');
+export const migratedMarker = (src: string): string => join(src, '.migrated-to-kimi-code');
+
+// Target (~/.kimi-code/) paths
+export const targetSessionsDir = (tgt: string): string => join(tgt, 'sessions');
+export const targetUserHistoryDir = (tgt: string): string => join(tgt, 'user-history');
+export const targetConfigFile = (tgt: string): string => join(tgt, 'config.toml');
+export const targetTuiFile = (tgt: string): string => join(tgt, 'tui.toml');
+export const targetMcpFile = (tgt: string): string => join(tgt, 'mcp.json');
+export const targetSessionIndex = (tgt: string): string => join(tgt, 'session_index.jsonl');
+export const migrationReportFile = (tgt: string): string => join(tgt, 'migration-report.json');
+export const migrationErrorsLogFile = (tgt: string): string => join(tgt, 'migration-errors.log');
+export const skipMarker = (tgt: string): string => join(tgt, '.skip-migration-from-kimi-cli');
+
+// Sibling fallback paths used when target file conflicts with user-modified content
+export const siblingConfigToml = (tgt: string): string =>
+  join(tgt, 'config.migrated-from-kimi-cli.toml');
+export const siblingTuiToml = (tgt: string): string =>
+  join(tgt, 'tui.migrated-from-kimi-cli.toml');
+export const siblingMcpJson = (tgt: string): string =>
+  join(tgt, 'mcp.migrated-from-kimi-cli.json');
diff --git a/packages/migration-legacy/src/prompt.ts b/packages/migration-legacy/src/prompt.ts
new file mode 100644
index 000000000..0b740babc
--- /dev/null
+++ b/packages/migration-legacy/src/prompt.ts
@@ -0,0 +1,48 @@
+/**
+ * First-launch migration prompt: pure decision mapping + prompter contract.
+ *
+ * This module owns the *decision tree* a user walks through when kimi-code
+ * detects a legacy `~/.kimi/` install on first launch. It is deliberately
+ * decoupled from any rendering: the renderer (pi-tui modal / readline / etc.)
+ * gathers the two logical choices and feeds them to `resolveMigrationScope`,
+ * which maps them into a `MigrationScope` (or a short-circuit decision).
+ *
+ * Two-layer prompt:
+ *   Prompt 1: now | later | never
+ *   Prompt 2 (only if "now"): config-only | all-sessions
+ *
+ * The host renders the questions (pi-tui migration screen); the package only
+ * owns the decision logic.
+ */
+import type { MigrationScope } from './types.js';
+
+export type Prompt1Choice = 'now' | 'later' | 'never';
+export type Prompt2Choice = 'config-only' | 'all-sessions';
+export type AnyChoice = Prompt1Choice | Prompt2Choice;
+
+export interface MigrationPromptResult {
+  readonly decision: 'now' | 'later' | 'never';
+  readonly scope?: MigrationScope;
+}
+
+/**
+ * Map the user's prompt choices into a migration decision + scope. Pure;
+ * production logic (not a simulation).
+ */
+export function resolveMigrationScope(
+  choices: readonly AnyChoice[],
+): MigrationPromptResult {
+  const [c1, c2] = choices;
+  if (c1 === 'later') return { decision: 'later' };
+  if (c1 === 'never') return { decision: 'never' };
+  // c1 === 'now'
+  return {
+    decision: 'now',
+    scope: {
+      config: true,
+      mcp: true,
+      userHistory: true,
+      sessions: c2 === 'all-sessions',
+    },
+  };
+}
diff --git a/packages/migration-legacy/src/report.ts b/packages/migration-legacy/src/report.ts
new file mode 100644
index 000000000..a5f311ea8
--- /dev/null
+++ b/packages/migration-legacy/src/report.ts
@@ -0,0 +1,17 @@
+import { mkdir } from 'node:fs/promises';
+import { atomicWrite } from './atomic-write.js';
+import { migrationReportFile } from './paths.js';
+import type { MigrationReport } from './types.js';
+
+/**
+ * Writes the migration report as pretty-printed JSON to
+ * `<targetHome>/migration-report.json`. Creates the target directory with
+ * mode 0700 if it does not yet exist.
+ */
+export async function writeReport(
+  targetHome: string,
+  report: MigrationReport,
+): Promise<void> {
+  await mkdir(targetHome, { recursive: true, mode: 0o700 });
+  await atomicWrite(migrationReportFile(targetHome), JSON.stringify(report, null, 2));
+}
diff --git a/packages/migration-legacy/src/run-migration.ts b/packages/migration-legacy/src/run-migration.ts
new file mode 100644
index 000000000..412ec3ff7
--- /dev/null
+++ b/packages/migration-legacy/src/run-migration.ts
@@ -0,0 +1,161 @@
+import type {
+  MigrationPlan,
+  MigrationReport,
+  MigrationScope,
+  SessionsSummary,
+} from './types.js';
+import { migrateConfigStep } from './steps/config.js';
+import { migrateMcpStep } from './steps/mcp.js';
+import { migrateUserHistoryStep } from './steps/user-history.js';
+import { migrateSessionsStep } from './sessions/index.js';
+import { writeReport } from './report.js';
+import { writeMigrationErrorsLog } from './migration-errors-log.js';
+import { appendMarkerRun, readMarker, writeMarker } from './marker.js';
+
+const DEFAULT_MIGRATOR_VERSION = '0.1.1';
+
+const CONFIG_CONFLICT_NOTICE =
+  'Your existing config.toml could not be parsed; migrated copy saved to ~/.kimi-code/config.migrated-from-kimi-cli.toml — please review and merge manually.';
+
+const TUI_CONFLICT_NOTICE =
+  'Your existing tui.toml had user modifications; migrated copy saved to ~/.kimi-code/tui.migrated-from-kimi-cli.toml — please review and merge manually.';
+
+export interface RunMigrationInput {
+  readonly plan: MigrationPlan;
+  readonly scope: MigrationScope;
+  readonly source: string;
+  readonly target: string;
+  readonly migratorVersion?: string;
+  readonly onProgress?: (msg: string) => void;
+  readonly onSessionProgress?: (done: number, total: number) => void;
+}
+
+export async function runMigration(input: RunMigrationInput): Promise<MigrationReport> {
+  const startedAt = new Date().toISOString();
+  const version = input.migratorVersion ?? DEFAULT_MIGRATOR_VERSION;
+  const log = (m: string): void => {
+    input.onProgress?.(m);
+  };
+
+  const config = input.scope.config
+    ? await migrateConfigStep({ sourceHome: input.source, targetHome: input.target })
+    : {
+        migrated: false,
+        tuiExtracted: false,
+        droppedProviders: [],
+        droppedModels: [],
+        droppedKeys: [],
+        configConflicts: [],
+        wroteSiblingDueToConflict: false,
+        wroteTuiSibling: false,
+        migratedHooks: 0,
+        droppedHooks: 0,
+        siblingContents: { providers: [], models: [], hooks: 0 },
+      };
+  log('config done');
+
+  const mcp = input.scope.mcp
+    ? await migrateMcpStep({ sourceHome: input.source, targetHome: input.target })
+    : { mergedServers: [], keptNewForConflicts: [], droppedServers: [], wroteSiblingDueToConflict: false };
+  log('mcp done');
+
+  const userHistory = input.scope.userHistory
+    ? await migrateUserHistoryStep({ sourceHome: input.source, targetHome: input.target })
+    : { copied: 0, skippedExisting: 0 };
+  log('user-history done');
+
+  const sessions: SessionsSummary = input.scope.sessions
+    ? await migrateSessionsStep({
+        sourceHome: input.source,
+        targetHome: input.target,
+        onSessionProgress: input.onSessionProgress,
+      })
+    : emptyConfigOnlySessions();
+  log('sessions done');
+
+  const completedAt = new Date().toISOString();
+
+  const report: MigrationReport = {
+    startedAt,
+    completedAt,
+    migratorVersion: version,
+    source: input.source,
+    target: input.target,
+    summary: {
+      config,
+      mcp,
+      userHistory,
+      sessions,
+    },
+    notices: {
+      mcpOauthServersRequiringReauth: input.plan.detectedMcpOauthServers,
+      oauthLoginsRequiringRelogin: input.plan.oauthCredentials,
+      detectedPlugins: input.plan.detectedPlugins,
+      configConflictNotice: config.wroteSiblingDueToConflict ? CONFIG_CONFLICT_NOTICE : null,
+      tuiConflictNotice: config.wroteTuiSibling ? TUI_CONFLICT_NOTICE : null,
+    },
+  };
+
+  await writeReport(input.target, report);
+
+  // Append this run's outcome (per-session diagnostics on failure, a marker
+  // on success) to `migration-errors.log` — append-only cross-run record so a
+  // user can share one log covering every retry attempt.
+  await writeMigrationErrorsLog(input.target, {
+    startedAt,
+    failures: sessions.sessionsFailed,
+  });
+
+  const markerSummary: Record<string, unknown> = {
+    config,
+    mcp,
+    userHistory,
+    sessions,
+  };
+
+  // Marker persistence is best-effort: the data migration and the target
+  // report are already complete, so a marker write failure (e.g. a read-only
+  // legacy home) must not turn a finished migration into a reported failure.
+  // The only consequence is that detection re-prompts on a later launch.
+  try {
+    const existingMarker = await readMarker(input.source);
+    if (existingMarker === undefined) {
+      await writeMarker(input.source, {
+        startedAt,
+        completedAt,
+        migratorVersion: version,
+        summary: markerSummary,
+        targetPath: input.target,
+      });
+    } else {
+      await appendMarkerRun(input.source, {
+        startedAt,
+        completedAt,
+        migratorVersion: version,
+        summary: markerSummary,
+        targetPath: input.target,
+      });
+    }
+  } catch {
+    // best-effort — see comment above
+  }
+
+  return report;
+}
+
+function emptyConfigOnlySessions(): SessionsSummary {
+  return {
+    scope: 'config-only',
+    bucketsScanned: 0,
+    bucketsSkippedNonlocalKaos: 0,
+    bucketsSkippedNoWorkdirFound: 0,
+    sessionsAttempted: 0,
+    sessionsMigrated: 0,
+    sessionsAlreadyMigrated: 0,
+    sessionsSkippedPlaceholder: 0,
+    sessionsSkippedEmpty: 0,
+    sessionsSkippedMalformed: 0,
+    sessionsFailed: [],
+    sessionsConflicts: [],
+  };
+}
diff --git a/packages/migration-legacy/src/session-index.ts b/packages/migration-legacy/src/session-index.ts
new file mode 100644
index 000000000..1d11225ab
--- /dev/null
+++ b/packages/migration-legacy/src/session-index.ts
@@ -0,0 +1,62 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { targetSessionIndex } from './paths.js';
+
+export interface SessionIndexEntry {
+  readonly sessionId: string;
+  readonly sessionDir: string;
+  readonly workDir: string;
+}
+
+export async function appendSessionIndexEntry(
+  targetHome: string,
+  entry: SessionIndexEntry,
+): Promise<void> {
+  const path = targetSessionIndex(targetHome);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await appendFile(path, JSON.stringify(entry) + '\n', 'utf-8');
+}
+
+/**
+ * Idempotently ensure `entry` is present in `session_index.jsonl`.
+ *
+ * Appends the entry only when no existing line carries the same `sessionId`.
+ * Used for the `already-migrated` re-run path: if a prior run wrote the session
+ * directory but crashed before appending its index entry, this self-heals the
+ * index on a subsequent run instead of leaving the session permanently
+ * unreachable by id.
+ */
+export async function ensureSessionIndexEntry(
+  targetHome: string,
+  entry: SessionIndexEntry,
+): Promise<void> {
+  const path = targetSessionIndex(targetHome);
+  if (await hasSessionIndexEntry(path, entry.sessionId)) return;
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await appendFile(path, JSON.stringify(entry) + '\n', 'utf-8');
+}
+
+async function hasSessionIndexEntry(path: string, sessionId: string): Promise<boolean> {
+  let text: string;
+  try {
+    text = await readFile(path, 'utf-8');
+  } catch {
+    return false;
+  }
+  for (const line of text.split(/\r?\n/)) {
+    if (line.length === 0) continue;
+    try {
+      const parsed: unknown = JSON.parse(line);
+      if (
+        parsed !== null &&
+        typeof parsed === 'object' &&
+        (parsed as { sessionId?: unknown }).sessionId === sessionId
+      ) {
+        return true;
+      }
+    } catch {
+      // Skip malformed lines — treat them as absent entries.
+    }
+  }
+  return false;
+}
diff --git a/packages/migration-legacy/src/sessions/classify.ts b/packages/migration-legacy/src/sessions/classify.ts
new file mode 100644
index 000000000..fbdf3e74f
--- /dev/null
+++ b/packages/migration-legacy/src/sessions/classify.ts
@@ -0,0 +1,44 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { analyzeContextContent } from './translator.js';
+
+export type SessionClass = 'placeholder' | 'empty' | 'malformed' | 'real';
+
+export async function classifySessionDir(sessionDir: string): Promise<SessionClass> {
+  let entries: string[];
+  try {
+    entries = await readdir(sessionDir);
+  } catch {
+    return 'malformed';
+  }
+  if (entries.length === 0) return 'empty';
+  if (entries.length === 1 && entries[0] === 'test') return 'placeholder';
+  // `migrateOneSession` hard-fails without `context.jsonl`, so a dir lacking it
+  // is not migratable. Classify as `malformed` so it is surfaced in the
+  // skipped-malformed counter rather than entering the migration pipeline.
+  if (!entries.includes('context.jsonl')) return 'malformed';
+
+  // Inspect the context payload to distinguish three cases:
+  //  - real:    has user/assistant/tool rows → migratable.
+  //  - empty:   parses but only carries markers (`_system_prompt` etc.) or is
+  //             blank → an unused session, or one the user cleared/reverted
+  //             in kimi-cli. Reported as skipped, never enters the pipeline.
+  //  - corrupt: every non-blank line failed to parse → a real data problem
+  //             (truncated write, disk error). Route through `'real'` so the
+  //             migration step can run, fail with a diagnostic reason, and
+  //             surface it via `sessionsFailed` + `migration-errors.log` —
+  //             classify-level `'malformed'` would silently absorb it into
+  //             `sessionsSkippedMalformed`, which the result screen does not
+  //             render and the error log does not include.
+  let contextText: string;
+  try {
+    contextText = await readFile(join(sessionDir, 'context.jsonl'), 'utf-8');
+  } catch {
+    // Listed by `readdir` but unreadable — treat as malformed, not migratable.
+    return 'malformed';
+  }
+  const content = analyzeContextContent(contextText.split(/\r?\n/));
+  if (content === 'real' || content === 'corrupt') return 'real';
+  return 'empty';
+}
diff --git a/packages/migration-legacy/src/sessions/close-tool-calls.ts b/packages/migration-legacy/src/sessions/close-tool-calls.ts
new file mode 100644
index 000000000..f59b67cc2
--- /dev/null
+++ b/packages/migration-legacy/src/sessions/close-tool-calls.ts
@@ -0,0 +1,47 @@
+import type { NormalizedMessage } from './translator.js';
+
+const PLACEHOLDER_TEXT = '[tool result unavailable — session imported from kimi-cli]';
+
+/**
+ * Close dangling tool calls so no messages are dropped on resume.
+ *
+ * kimi-core's context module defers messages while a tool exchange is open
+ * (i.e. an assistant message has `toolCalls` whose ids are not all satisfied
+ * by later `tool` messages) and only flushes once every pending tool-result
+ * id is satisfied. A kimi-cli session interrupted mid-tool-call therefore
+ * never closes that exchange, and every subsequent message is silently
+ * dropped from history.
+ *
+ * For each assistant `toolCall.id` with no matching `role:'tool'` message
+ * anywhere in the list, this synthesizes a placeholder tool result and
+ * inserts it immediately after the assistant message — before any later
+ * real message — so the exchange closes in place and ordering is preserved.
+ */
+export function closeDanglingToolCalls(
+  messages: readonly NormalizedMessage[],
+): NormalizedMessage[] {
+  const satisfied = new Set<string>();
+  for (const msg of messages) {
+    if (msg.role === 'tool' && msg.toolCallId !== undefined && msg.toolCallId !== '') {
+      satisfied.add(msg.toolCallId);
+    }
+  }
+
+  const out: NormalizedMessage[] = [];
+  for (const msg of messages) {
+    out.push(msg);
+    if (msg.role !== 'assistant') continue;
+    for (const call of msg.toolCalls) {
+      if (call.id === '' || satisfied.has(call.id)) continue;
+      out.push({
+        role: 'tool',
+        toolCallId: call.id,
+        content: [{ type: 'text', text: PLACEHOLDER_TEXT }],
+        toolCalls: [],
+      });
+      // Guard against an assistant message that lists the same call id twice.
+      satisfied.add(call.id);
+    }
+  }
+  return out;
+}
diff --git a/packages/migration-legacy/src/sessions/content-part.ts b/packages/migration-legacy/src/sessions/content-part.ts
new file mode 100644
index 000000000..d86c7ebbb
--- /dev/null
+++ b/packages/migration-legacy/src/sessions/content-part.ts
@@ -0,0 +1,81 @@
+import { existsSync } from 'node:fs';
+
+export type NormalizedContentPart =
+  | { readonly type: 'text'; readonly text: string }
+  | { readonly type: 'think'; readonly think: string; readonly encrypted?: string }
+  | { readonly type: 'image_url'; readonly imageUrl: { readonly url: string; readonly id?: string } }
+  | { readonly type: 'audio_url'; readonly audioUrl: { readonly url: string; readonly id?: string } }
+  | { readonly type: 'video_url'; readonly videoUrl: { readonly url: string; readonly id?: string } };
+
+export function normalizeContentPart(part: unknown): NormalizedContentPart {
+  if (typeof part !== 'object' || part === null) {
+    return { type: 'text', text: `[unsupported content: ${JSON.stringify(part)}]` };
+  }
+  const p = part as Record<string, unknown>;
+
+  switch (p['type']) {
+    case 'text':
+      return { type: 'text', text: coerceToString(p['text']) };
+
+    case 'think': {
+      const encrypted = p['encrypted'];
+      const think = coerceToString(p['think']);
+      if (typeof encrypted === 'string' && encrypted.length > 0) {
+        return { type: 'think', think, encrypted };
+      }
+      return { type: 'think', think };
+    }
+
+    case 'image':
+      return convertMediaPart('image', 'image_url', 'imageUrl', p);
+    case 'audio':
+      return convertMediaPart('audio', 'audio_url', 'audioUrl', p);
+    case 'video':
+      return convertMediaPart('video', 'video_url', 'videoUrl', p);
+
+    default:
+      return { type: 'text', text: `[unsupported content: ${JSON.stringify(part)}]` };
+  }
+}
+
+/** Safely coerce an unknown value to string for text fields. Avoids
+ * `[object Object]` from accidental object stringification — those become
+ * JSON instead. Strings pass through unchanged; null/undefined → ''. */
+function coerceToString(v: unknown): string {
+  if (typeof v === 'string') return v;
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'number' || typeof v === 'boolean' || typeof v === 'bigint') {
+    return String(v);
+  }
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return '';
+  }
+}
+
+function convertMediaPart(
+  kind: 'image' | 'audio' | 'video',
+  newType: 'image_url' | 'audio_url' | 'video_url',
+  _fieldName: 'imageUrl' | 'audioUrl' | 'videoUrl',
+  p: Record<string, unknown>,
+): NormalizedContentPart {
+  const url = p['url'];
+  if (typeof url !== 'string' || url.length === 0) {
+    return { type: 'text', text: `[${kind} missing url]` };
+  }
+  // If url is a local file path (no scheme) and file is gone, mark expired.
+  if (!/^[a-z]+:\/\//i.test(url) && url.startsWith('/') && !existsSync(url)) {
+    return { type: 'text', text: `[${kind} expired]` };
+  }
+  const id = typeof p['id'] === 'string' ? p['id'] : undefined;
+  const obj = id === undefined ? { url } : { url, id };
+  switch (newType) {
+    case 'image_url':
+      return { type: 'image_url', imageUrl: obj };
+    case 'audio_url':
+      return { type: 'audio_url', audioUrl: obj };
+    case 'video_url':
+      return { type: 'video_url', videoUrl: obj };
+  }
+}
diff --git a/packages/migration-legacy/src/sessions/index.ts b/packages/migration-legacy/src/sessions/index.ts
new file mode 100644
index 000000000..606739e85
--- /dev/null
+++ b/packages/migration-legacy/src/sessions/index.ts
@@ -0,0 +1,268 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { OldKimiJsonSchema, OldSessionStateSchema } from '../kimi-cli-schema.js';
+import { ensureSessionIndexEntry } from '../session-index.js';
+import { sourceKimiJson, sourceSessionsDir } from '../paths.js';
+import type { SessionsSummary } from '../types.js';
+import { classifySessionDir } from './classify.js';
+import { migrateOneSession } from './migrate-one.js';
+import { oldMd5BucketName } from './workdir-bucket.js';
+
+export interface SessionsStepInput {
+  readonly sourceHome: string;
+  readonly targetHome: string;
+  /** Invoked after each session is processed, with the running count and total. */
+  readonly onSessionProgress?: (done: number, total: number) => void;
+}
+
+interface WorkdirMeta {
+  readonly path: string;
+  readonly kaos: string;
+}
+
+interface SessionCandidate {
+  readonly sourceSessionDir: string;
+  readonly oldSessionUuid: string;
+  readonly workdirPath: string;
+  readonly wireMtime: number;
+}
+
+const MD5_HEX_RE = /^[0-9a-f]{32}$/;
+
+export async function migrateSessionsStep(
+  input: SessionsStepInput,
+): Promise<SessionsSummary> {
+  const workdirs = await loadWorkdirs(input.sourceHome);
+  const md5ToWorkdir = new Map<string, WorkdirMeta>();
+  for (const wd of workdirs) {
+    md5ToWorkdir.set(oldMd5BucketName(wd.path), { path: wd.path, kaos: wd.kaos });
+  }
+
+  let bucketsScanned = 0;
+  let bucketsSkippedNonlocalKaos = 0;
+  let bucketsSkippedNoWorkdirFound = 0;
+  let sessionsSkippedPlaceholder = 0;
+  let sessionsSkippedEmpty = 0;
+  let sessionsSkippedMalformed = 0;
+  const sessionsFailed: Array<{ sourcePath: string; reason: string }> = [];
+  const sessionsConflicts: Array<{ sourcePath: string; targetPath: string }> = [];
+
+  const sessionsDir = sourceSessionsDir(input.sourceHome);
+  let bucketDirs: string[];
+  try {
+    bucketDirs = await readdir(sessionsDir);
+  } catch {
+    return emptySummary();
+  }
+
+  const candidates: SessionCandidate[] = [];
+
+  for (const bucketName of bucketDirs) {
+    bucketsScanned++;
+    const workdir = resolveBucket(bucketName, md5ToWorkdir);
+    if (workdir.kind === 'nonlocal-kaos') {
+      bucketsSkippedNonlocalKaos++;
+      continue;
+    }
+    if (workdir.kind === 'no-workdir-found') {
+      bucketsSkippedNoWorkdirFound++;
+      continue;
+    }
+    // workdir.kind === 'local'
+    const bucketPath = join(sessionsDir, bucketName);
+    let sessionUuids: string[];
+    try {
+      sessionUuids = await readdir(bucketPath);
+    } catch {
+      continue;
+    }
+    for (const uuid of sessionUuids) {
+      const sessionDir = join(bucketPath, uuid);
+      const cls = await classifySessionDir(sessionDir);
+      if (cls === 'placeholder') {
+        sessionsSkippedPlaceholder++;
+        continue;
+      }
+      if (cls === 'empty') {
+        sessionsSkippedEmpty++;
+        continue;
+      }
+      if (cls === 'malformed') {
+        sessionsSkippedMalformed++;
+        continue;
+      }
+      const wireMtime = await readWireMtime(sessionDir);
+      candidates.push({
+        sourceSessionDir: sessionDir,
+        oldSessionUuid: uuid,
+        workdirPath: workdir.path,
+        wireMtime,
+      });
+    }
+  }
+
+  // Stable, deterministic order so progress events emit "newest first" — the
+  // user sees their most recent work move across the counter first.
+  candidates.sort((a, b) => b.wireMtime - a.wireMtime);
+
+  let migrated = 0;
+  let alreadyMigrated = 0;
+  let processedCount = 0;
+  for (const c of candidates) {
+    const result = await migrateOneSession({
+      sourceSessionDir: c.sourceSessionDir,
+      oldSessionUuid: c.oldSessionUuid,
+      workdirPath: c.workdirPath,
+      targetHome: input.targetHome,
+    });
+    processedCount += 1;
+    input.onSessionProgress?.(processedCount, candidates.length);
+    if (result.outcome === 'migrated') {
+      try {
+        // `ensureSessionIndexEntry` is idempotent — if a stale index line for
+        // this session survived a deleted target dir, re-migrating it must not
+        // append a second line for the same id.
+        await ensureSessionIndexEntry(input.targetHome, {
+          sessionId: `ses_${c.oldSessionUuid}`,
+          sessionDir: result.targetDir,
+          workDir: c.workdirPath,
+        });
+        migrated++;
+      } catch (error) {
+        // The session dir is written, but resume-by-id needs the index entry —
+        // without it the session is unopenable. Record it as failed so the run
+        // summary is honest; one bad index write must not abort the batch.
+        sessionsFailed.push({
+          sourcePath: c.sourceSessionDir,
+          reason: `session migrated but index append failed: ${String(error)}`,
+        });
+      }
+    } else if (result.outcome === 'already-migrated') {
+      // The session dir exists from a prior run, but that run may have crashed
+      // before appending the index entry. `ensureSessionIndexEntry` is
+      // idempotent — it adds the entry only when absent — so a rerun
+      // self-heals an index that is missing this session.
+      try {
+        await ensureSessionIndexEntry(input.targetHome, {
+          sessionId: `ses_${c.oldSessionUuid}`,
+          sessionDir: result.targetDir,
+          workDir: c.workdirPath,
+        });
+        alreadyMigrated++;
+      } catch (error) {
+        // The index entry is genuinely missing and could not be added — the
+        // session stays unreachable by id, so record it as failed.
+        sessionsFailed.push({
+          sourcePath: c.sourceSessionDir,
+          reason: `session already migrated but index entry could not be ensured: ${String(error)}`,
+        });
+      }
+    } else if (result.outcome === 'conflict') {
+      sessionsConflicts.push({
+        sourcePath: c.sourceSessionDir,
+        targetPath: result.targetDir,
+      });
+    } else if (result.outcome === 'empty') {
+      // No migratable conversation (empty or user-cleared session). Counted
+      // as skipped, not failed — `classifySessionDir` usually catches these
+      // before they become candidates, but a translator/classifier edge can
+      // still land one here.
+      sessionsSkippedEmpty++;
+    } else {
+      sessionsFailed.push({
+        sourcePath: c.sourceSessionDir,
+        reason: result.reason,
+      });
+    }
+  }
+
+  return {
+    scope: 'all',
+    bucketsScanned,
+    bucketsSkippedNonlocalKaos,
+    bucketsSkippedNoWorkdirFound,
+    sessionsAttempted: candidates.length,
+    sessionsMigrated: migrated,
+    sessionsAlreadyMigrated: alreadyMigrated,
+    sessionsSkippedPlaceholder,
+    sessionsSkippedEmpty,
+    sessionsSkippedMalformed,
+    sessionsFailed,
+    sessionsConflicts,
+  };
+}
+
+type BucketResolution =
+  | { readonly kind: 'local'; readonly path: string }
+  | { readonly kind: 'nonlocal-kaos' }
+  | { readonly kind: 'no-workdir-found' };
+
+function resolveBucket(
+  bucketName: string,
+  md5ToWorkdir: ReadonlyMap<string, WorkdirMeta>,
+): BucketResolution {
+  // Pure md5 hex (32 chars) → look up directly.
+  if (MD5_HEX_RE.test(bucketName)) {
+    const meta = md5ToWorkdir.get(bucketName);
+    if (meta === undefined) {
+      return { kind: 'no-workdir-found' };
+    }
+    if (meta.kaos !== 'local') {
+      return { kind: 'nonlocal-kaos' };
+    }
+    return { kind: 'local', path: meta.path };
+  }
+  // Non-local pattern: `<kaos>_<md5>`. Use the last `_` so kaos names that
+  // contain underscores still resolve.
+  const idx = bucketName.lastIndexOf('_');
+  if (idx > 0 && MD5_HEX_RE.test(bucketName.slice(idx + 1))) {
+    return { kind: 'nonlocal-kaos' };
+  }
+  return { kind: 'no-workdir-found' };
+}
+
+async function loadWorkdirs(sourceHome: string): Promise<WorkdirMeta[]> {
+  try {
+    const text = await readFile(sourceKimiJson(sourceHome), 'utf-8');
+    const parsed = OldKimiJsonSchema.parse(JSON.parse(text));
+    return parsed.work_dirs.map((w) => ({ path: w.path, kaos: w.kaos }));
+  } catch {
+    return [];
+  }
+}
+
+async function readWireMtime(sessionDir: string): Promise<number> {
+  try {
+    const text = await readFile(join(sessionDir, 'state.json'), 'utf-8');
+    const parsed = OldSessionStateSchema.parse(JSON.parse(text));
+    if (parsed.wire_mtime !== null && parsed.wire_mtime !== undefined) {
+      return parsed.wire_mtime * 1000;
+    }
+  } catch {
+    // fall through to wire.jsonl mtime
+  }
+  try {
+    const st = await stat(join(sessionDir, 'wire.jsonl'));
+    return st.mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+function emptySummary(): SessionsSummary {
+  return {
+    scope: 'all',
+    bucketsScanned: 0,
+    bucketsSkippedNonlocalKaos: 0,
+    bucketsSkippedNoWorkdirFound: 0,
+    sessionsAttempted: 0,
+    sessionsMigrated: 0,
+    sessionsAlreadyMigrated: 0,
+    sessionsSkippedPlaceholder: 0,
+    sessionsSkippedEmpty: 0,
+    sessionsSkippedMalformed: 0,
+    sessionsFailed: [],
+    sessionsConflicts: [],
+  };
+}
diff --git a/packages/migration-legacy/src/sessions/migrate-one.ts b/packages/migration-legacy/src/sessions/migrate-one.ts
new file mode 100644
index 000000000..4ad6735c8
--- /dev/null
+++ b/packages/migration-legacy/src/sessions/migrate-one.ts
@@ -0,0 +1,215 @@
+import { existsSync } from 'node:fs';
+import { readFile, mkdir, rm, stat, utimes } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { OldSessionStateSchema, type OldSessionState } from '../kimi-cli-schema.js';
+import { targetSessionsDir } from '../paths.js';
+import { computeWorkdirBucket } from './workdir-bucket.js';
+import { closeDanglingToolCalls } from './close-tool-calls.js';
+import {
+  analyzeContextContent,
+  translateContextLines,
+  type NormalizedMessage,
+} from './translator.js';
+import { writeMainAgentWire } from './wire-writer.js';
+import { writeSessionState } from './state-writer.js';
+
+export type MigrateOneResult =
+  | { readonly outcome: 'migrated'; readonly targetDir: string }
+  | { readonly outcome: 'already-migrated'; readonly targetDir: string }
+  | { readonly outcome: 'conflict'; readonly targetDir: string }
+  | { readonly outcome: 'empty' }
+  | { readonly outcome: 'failed'; readonly reason: string };
+
+export interface MigrateOneInput {
+  readonly sourceSessionDir: string;
+  readonly oldSessionUuid: string;
+  readonly workdirPath: string;
+  readonly targetHome: string;
+}
+
+export async function migrateOneSession(input: MigrateOneInput): Promise<MigrateOneResult> {
+  const bucket = computeWorkdirBucket(input.workdirPath);
+  const targetDir = join(targetSessionsDir(input.targetHome), bucket, `ses_${input.oldSessionUuid}`);
+
+  if (existsSync(targetDir)) {
+    const cls = await classifyExistingTarget(targetDir);
+    // A dir we wrote ourselves on a previous run — idempotent re-run.
+    if (cls === 'imported') {
+      return { outcome: 'already-migrated', targetDir };
+    }
+    // A real, unrelated kimi-code session occupies the path — a true conflict.
+    if (cls === 'foreign') {
+      return { outcome: 'conflict', targetDir };
+    }
+    // 'debris': `state.json` is absent or corrupt — a prior migration was
+    // killed mid-write. Treat it as stale and re-migrate, rather than
+    // stranding this session under a permanent conflict on every future run.
+    await rm(targetDir, { recursive: true, force: true });
+  }
+
+  let oldState: Partial<OldSessionState> = {};
+  try {
+    const stateText = await readFile(join(input.sourceSessionDir, 'state.json'), 'utf-8');
+    oldState = OldSessionStateSchema.parse(JSON.parse(stateText));
+  } catch {
+    // missing or corrupt state — proceed with defaults
+  }
+
+  let messages: NormalizedMessage[] = [];
+  let lastUserPrompt = '';
+  let contextLines: readonly string[] = [];
+  try {
+    const contextText = await readFile(join(input.sourceSessionDir, 'context.jsonl'), 'utf-8');
+    contextLines = contextText.split(/\r?\n/);
+    messages = closeDanglingToolCalls(translateContextLines(contextLines));
+    lastUserPrompt = extractLastUserText(messages);
+  } catch {
+    return { outcome: 'failed', reason: 'cannot read context.jsonl' };
+  }
+
+  if (messages.length === 0) {
+    // No `user`/`assistant`/`tool` rows survived translation. Re-analyze the
+    // raw lines to tell a genuinely empty/cleared session apart from one
+    // whose every line failed to parse — the latter is a real data problem
+    // and must show up in `migration-errors.log`, not get silently lumped in
+    // with skipped-empty. `classifySessionDir` normally catches both ahead
+    // of time; this stays as a defense-in-depth safety net.
+    if (analyzeContextContent(contextLines) === 'corrupt') {
+      return {
+        outcome: 'failed',
+        reason: 'context.jsonl is corrupt: no parseable JSON lines',
+      };
+    }
+    return { outcome: 'empty' };
+  }
+
+  const wireMtimeS = oldState.wire_mtime ?? null;
+  let createdAtMs: number;
+  if (wireMtimeS !== null && wireMtimeS !== undefined) {
+    createdAtMs = Math.floor(wireMtimeS * 1000);
+  } else {
+    // No recorded `wire_mtime`: fall back to the source `wire.jsonl` mtime —
+    // the SAME signal `migrateSessionsStep`/detection rank recency by — so
+    // post-migration `SessionStore.list()` ordering matches the detected
+    // "most recent" order. `Date.now()` would stamp every such session with
+    // the migration time and break resume ordering.
+    try {
+      createdAtMs = Math.floor(
+        (await stat(join(input.sourceSessionDir, 'wire.jsonl'))).mtimeMs,
+      );
+    } catch {
+      createdAtMs = Date.now();
+    }
+  }
+
+  let wireProtocolFromOld: string | null = null;
+  try {
+    const oldWire = await readFile(join(input.sourceSessionDir, 'wire.jsonl'), 'utf-8');
+    const firstLine = oldWire.split(/\r?\n/)[0];
+    if (firstLine !== undefined && firstLine.length > 0) {
+      const parsed: unknown = JSON.parse(firstLine);
+      if (
+        parsed !== null &&
+        typeof parsed === 'object' &&
+        typeof (parsed as { protocol_version?: unknown }).protocol_version === 'string'
+      ) {
+        wireProtocolFromOld = (parsed as { protocol_version: string }).protocol_version;
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  try {
+    await mkdir(targetDir, { recursive: true, mode: 0o700 });
+    await writeMainAgentWire(targetDir, { createdAtMs, messages });
+    await writeSessionState(targetDir, {
+      oldState,
+      lastUserPrompt,
+      sourcePath: input.sourceSessionDir,
+      oldSessionUuid: input.oldSessionUuid,
+      wireProtocolFromOld,
+      createdAtMs,
+    });
+  } catch (error) {
+    // A partially-written targetDir would trip the conflict guard on re-run
+    // and strand this session forever. Clean it up and report a soft failure
+    // so the migration loop continues.
+    await rm(targetDir, { recursive: true, force: true }).catch(() => {});
+    const reason = error instanceof Error ? error.message : String(error);
+    return { outcome: 'failed', reason };
+  }
+
+  // kimi-core's `SessionStore.list()` ranks sessions by the *filesystem*
+  // mtimes of `state.json` / `wire.jsonl` / the session dir — not by the
+  // `updatedAt` field. Writing newest-first would otherwise make the newest
+  // original session the oldest by mtime, inverting `--continue` ordering.
+  // Stamp the artifacts with the session's original timestamp so `list()`
+  // reflects true recency. A utimes failure must never abort the session;
+  // it only leaves ordering slightly off.
+  await applyOriginalMtime(targetDir, createdAtMs);
+
+  return { outcome: 'migrated', targetDir };
+}
+
+/**
+ * Set the filesystem mtime of the migrated session artifacts to the session's
+ * original timestamp. The session directory is stamped LAST, since writing
+ * files into it bumps the directory mtime.
+ */
+async function applyOriginalMtime(targetDir: string, createdAtMs: number): Promise<void> {
+  const stamp = new Date(createdAtMs);
+  try {
+    await utimes(join(targetDir, 'agents', 'main', 'wire.jsonl'), stamp, stamp);
+    await utimes(join(targetDir, 'state.json'), stamp, stamp);
+    await utimes(targetDir, stamp, stamp);
+  } catch {
+    // Non-fatal: ordering may be slightly off, but the migration succeeded.
+  }
+}
+
+type ExistingTarget = 'imported' | 'foreign' | 'debris';
+
+/**
+ * Classify an existing `targetDir`:
+ *  - `imported`: a complete dir written by a previous run of this migrator.
+ *  - `foreign`:  a real, unrelated kimi-code session occupying the path.
+ *  - `debris`:   no `state.json`, or a corrupt/unparseable one — a prior
+ *                migration was killed mid-write; safe to delete and re-migrate.
+ */
+async function classifyExistingTarget(targetDir: string): Promise<ExistingTarget> {
+  let text: string;
+  try {
+    text = await readFile(join(targetDir, 'state.json'), 'utf-8');
+  } catch {
+    return 'debris'; // no state.json at all
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return 'debris'; // corrupt / half-written state.json
+  }
+  if (typeof parsed !== 'object' || parsed === null) return 'debris';
+  const custom = (parsed as { custom?: unknown }).custom;
+  if (
+    typeof custom === 'object' &&
+    custom !== null &&
+    (custom as { imported_from_kimi_cli?: unknown }).imported_from_kimi_cli === true
+  ) {
+    return 'imported';
+  }
+  return 'foreign';
+}
+
+function extractLastUserText(messages: readonly NormalizedMessage[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m === undefined) continue;
+    if (m.role !== 'user') continue;
+    const textPart = m.content.find((p) => p.type === 'text');
+    if (textPart && textPart.type === 'text') return textPart.text;
+  }
+  return '';
+}
diff --git a/packages/migration-legacy/src/sessions/state-writer.ts b/packages/migration-legacy/src/sessions/state-writer.ts
new file mode 100644
index 000000000..12c849b9c
--- /dev/null
+++ b/packages/migration-legacy/src/sessions/state-writer.ts
@@ -0,0 +1,59 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { OldSessionState } from '../kimi-cli-schema.js';
+
+export interface StateWriteInput {
+  readonly oldState: Partial<OldSessionState>;
+  readonly lastUserPrompt: string;
+  readonly sourcePath: string;
+  readonly oldSessionUuid: string;
+  readonly wireProtocolFromOld: string | null;
+  readonly createdAtMs: number;
+}
+
+export async function writeSessionState(sessionDir: string, input: StateWriteInput): Promise<void> {
+  await mkdir(sessionDir, { recursive: true, mode: 0o700 });
+
+  const customTitle = input.oldState.custom_title ?? null;
+  const isCustomTitle =
+    customTitle !== null && customTitle.length > 0 && !input.oldState.title_generated;
+  const fallbackTitle = input.lastUserPrompt.slice(0, 50).trim();
+  const candidateTitle = customTitle ?? fallbackTitle;
+  const finalTitle = candidateTitle.length > 0 ? candidateTitle : 'Imported session';
+
+  const wireMtimeS = input.oldState.wire_mtime ?? null;
+  const updatedAt =
+    wireMtimeS !== null && wireMtimeS !== undefined
+      ? new Date(wireMtimeS * 1000).toISOString()
+      : new Date(input.createdAtMs).toISOString();
+
+  const meta = {
+    createdAt: new Date(input.createdAtMs).toISOString(),
+    updatedAt,
+    title: finalTitle,
+    isCustomTitle,
+    lastPrompt: input.lastUserPrompt.slice(0, 200),
+    agents: {
+      main: {
+        // kimi-core's `Session.resume()` treats `agents.main.homedir` as the
+        // agent's *record directory* — where it reads `wire.jsonl`. The
+        // migrator writes the translated history to
+        // `<sessionDir>/agents/main/wire.jsonl`, so this must point there,
+        // NOT at the user's project workdir.
+        homedir: join(sessionDir, 'agents', 'main'),
+        type: 'main',
+        parentAgentId: null,
+      },
+    },
+    custom: {
+      imported_from_kimi_cli: true,
+      kimi_cli_source_path: input.sourcePath,
+      kimi_cli_session_id: input.oldSessionUuid,
+      kimi_cli_wire_protocol: input.wireProtocolFromOld,
+      imported_at: new Date().toISOString(),
+      archived: input.oldState.archived ?? false,
+    },
+  };
+
+  await writeFile(join(sessionDir, 'state.json'), JSON.stringify(meta, null, 2), 'utf-8');
+}
diff --git a/packages/migration-legacy/src/sessions/translator.ts b/packages/migration-legacy/src/sessions/translator.ts
new file mode 100644
index 000000000..499180b94
--- /dev/null
+++ b/packages/migration-legacy/src/sessions/translator.ts
@@ -0,0 +1,171 @@
+import { normalizeContentPart, type NormalizedContentPart } from './content-part.js';
+
+export interface NormalizedMessage {
+  readonly role: 'user' | 'assistant' | 'tool';
+  readonly content: readonly NormalizedContentPart[];
+  readonly toolCalls: ReadonlyArray<{
+    readonly type: 'function';
+    readonly id: string;
+    readonly function: { readonly name: string; readonly arguments: string };
+  }>;
+  readonly toolCallId?: string;
+}
+
+const DROPPED_ROLES = new Set(['_system_prompt', '_checkpoint', '_usage']);
+
+// The roles `translateContextLines` keeps — the inverse of the markers it
+// drops. A context with none of these has no migratable conversation.
+const USABLE_ROLES: ReadonlySet<string> = new Set(['user', 'assistant', 'tool']);
+
+/**
+ * The three meaningful outcomes for a session's `context.jsonl`.
+ *
+ *  - `'real'`    — has at least one `user` / `assistant` / `tool` row →
+ *                  migratable conversation.
+ *  - `'empty'`   — parses, but only carries markers (`_system_prompt`,
+ *                  `_checkpoint`, `_usage`) or is genuinely blank → an unused
+ *                  session, or one the user cleared in kimi-cli.
+ *  - `'corrupt'` — every non-blank line failed to parse → disk damage,
+ *                  truncated write, etc. Must NOT be conflated with `empty`
+ *                  or its data problem disappears into the skip count.
+ */
+export type ContextContent = 'real' | 'empty' | 'corrupt';
+
+/**
+ * Classify a `context.jsonl`'s payload by scanning its lines. Distinguishes a
+ * cleared/empty session from a corrupt one — the latter is a data problem
+ * users need visibility into. Early-exits on the first usable row.
+ */
+export function analyzeContextContent(lines: readonly string[]): ContextContent {
+  let hadParseableLine = false;
+  let hadAnyNonBlank = false;
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (line === '') continue;
+    hadAnyNonBlank = true;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (typeof parsed !== 'object' || parsed === null) continue;
+    hadParseableLine = true;
+    const role = (parsed as Record<string, unknown>)['role'];
+    if (typeof role === 'string' && USABLE_ROLES.has(role)) return 'real';
+  }
+  if (hadAnyNonBlank && !hadParseableLine) return 'corrupt';
+  return 'empty';
+}
+
+/**
+ * Convenience wrapper: `true` iff the context has at least one translatable
+ * message. Equivalent to `analyzeContextContent(...) === 'real'`.
+ */
+export function containsUsableMessage(lines: readonly string[]): boolean {
+  return analyzeContextContent(lines) === 'real';
+}
+
+export function translateContextLines(lines: readonly string[]): NormalizedMessage[] {
+  const out: NormalizedMessage[] = [];
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (line === '') continue;
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (typeof parsed !== 'object' || parsed === null) continue;
+
+    const obj = parsed as Record<string, unknown>;
+    const role = obj['role'];
+    if (typeof role !== 'string') continue;
+    if (DROPPED_ROLES.has(role)) continue;
+
+    if (role === 'user') {
+      out.push(buildUser(obj));
+    } else if (role === 'assistant') {
+      out.push(buildAssistant(obj));
+    } else if (role === 'tool') {
+      out.push(buildTool(obj));
+    }
+    // else: unknown role, skip
+  }
+  return out;
+}
+
+function normalizeContent(raw: unknown): NormalizedContentPart[] {
+  // A legacy row may legitimately omit `content` (e.g. an assistant message
+  // that only carries tool calls). kimi's message shape allows `content: []`;
+  // stringifying nullish here would emit a phantom text part holding `""`.
+  if (raw === null || raw === undefined) {
+    return [];
+  }
+  if (typeof raw === 'string') {
+    return [{ type: 'text', text: raw }];
+  }
+  if (Array.isArray(raw)) {
+    return raw.map(normalizeContentPart);
+  }
+  // Fallback: stringify any other scalar/object shape into a text part.
+  return [{ type: 'text', text: JSON.stringify(raw) }];
+}
+
+function buildUser(obj: Record<string, unknown>): NormalizedMessage {
+  return {
+    role: 'user',
+    content: normalizeContent(obj['content']),
+    toolCalls: [],
+  };
+}
+
+function buildAssistant(obj: Record<string, unknown>): NormalizedMessage {
+  const toolCalls = Array.isArray(obj['tool_calls'])
+    ? (obj['tool_calls'] as unknown[]).map(parseToolCall).filter(isNonNull)
+    : [];
+  return {
+    role: 'assistant',
+    content: normalizeContent(obj['content']),
+    toolCalls,
+  };
+}
+
+function buildTool(obj: Record<string, unknown>): NormalizedMessage {
+  const toolCallId = typeof obj['tool_call_id'] === 'string' ? obj['tool_call_id'] : '';
+  return {
+    role: 'tool',
+    content: normalizeContent(obj['content']),
+    toolCalls: [],
+    toolCallId,
+  };
+}
+
+interface RawToolCall {
+  readonly type: 'function';
+  readonly id: string;
+  readonly function: { readonly name: string; readonly arguments: string };
+}
+
+function parseToolCall(raw: unknown): RawToolCall | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const r = raw as Record<string, unknown>;
+  if (r['type'] !== 'function') return undefined;
+  if (typeof r['id'] !== 'string') return undefined;
+  const fn = r['function'];
+  if (typeof fn !== 'object' || fn === null) return undefined;
+  const f = fn as Record<string, unknown>;
+  if (typeof f['name'] !== 'string') return undefined;
+  const args = typeof f['arguments'] === 'string' ? f['arguments'] : '';
+  return {
+    type: 'function',
+    id: r['id'],
+    function: { name: f['name'], arguments: args },
+  };
+}
+
+function isNonNull<T>(x: T | undefined): x is T {
+  return x !== undefined;
+}
diff --git a/packages/migration-legacy/src/sessions/wire-writer.ts b/packages/migration-legacy/src/sessions/wire-writer.ts
new file mode 100644
index 000000000..dc7b1d482
--- /dev/null
+++ b/packages/migration-legacy/src/sessions/wire-writer.ts
@@ -0,0 +1,26 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { NormalizedMessage } from './translator.js';
+
+export const WIRE_PROTOCOL_VERSION = '1.0';
+
+export interface WireWriteInput {
+  readonly createdAtMs: number;
+  readonly messages: readonly NormalizedMessage[];
+}
+
+export async function writeMainAgentWire(sessionDir: string, input: WireWriteInput): Promise<void> {
+  const wireDir = join(sessionDir, 'agents', 'main');
+  await mkdir(wireDir, { recursive: true, mode: 0o700 });
+
+  const metadata = {
+    type: 'metadata',
+    protocol_version: WIRE_PROTOCOL_VERSION,
+    created_at: input.createdAtMs,
+  };
+  const lines: string[] = [JSON.stringify(metadata)];
+  for (const msg of input.messages) {
+    lines.push(JSON.stringify({ type: 'context.append_message', message: msg }));
+  }
+  await writeFile(join(wireDir, 'wire.jsonl'), lines.join('\n') + '\n', 'utf-8');
+}
diff --git a/packages/migration-legacy/src/sessions/workdir-bucket.ts b/packages/migration-legacy/src/sessions/workdir-bucket.ts
new file mode 100644
index 000000000..7a8222a7a
--- /dev/null
+++ b/packages/migration-legacy/src/sessions/workdir-bucket.ts
@@ -0,0 +1,51 @@
+import { basename, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+
+const WORKDIR_KEY_PREFIX = 'wd_';
+const HASH_LENGTH = 12;
+
+/**
+ * Compute the v2 bucket directory name `wd_<slug>_<hash12>` for a workdir
+ * path. Hash function and slug rules mirror
+ * `packages/kimi-core/src/utils/workdir-slug.ts` and
+ * `packages/kimi-core/src/harness/session-manager/workdir-key.ts:13–18`.
+ *
+ * IMPORTANT: agent-core's `encodeWorkDirKey` runs `resolve()` on the workdir
+ * before hashing/slugifying, and the session picker locates sessions purely
+ * by `readdir(encodeWorkDirKey(...))` — it never consults `session_index.jsonl`.
+ * We MUST apply the same `resolve()` here or migrated sessions become
+ * invisible in the picker.
+ *
+ * TODO: The canonical slugifier is `slugifyWorkDirName` in
+ * `@moonshot-ai/agent-core` (file: `src/utils/workdir-slug.ts`). It is not part
+ * of that package's public export surface today. When/if it becomes public,
+ * delete the local duplicate below and import it from agent-core directly so
+ * buckets stay byte-identical between the running app and this migrator.
+ */
+export function computeWorkdirBucket(workdirPath: string): string {
+  const normalized = resolve(workdirPath);
+  const hash12 = createHash('sha256').update(normalized).digest('hex').slice(0, HASH_LENGTH);
+  const slug = slugifyWorkDirName(basename(normalized));
+  return `${WORKDIR_KEY_PREFIX}${slug}_${hash12}`;
+}
+
+/** Returns the md5 hex of the workdir path; used to reverse-look-up old buckets. */
+export function oldMd5BucketName(workdirPath: string): string {
+  return createHash('md5').update(workdirPath).digest('hex');
+}
+
+const MAX_WORKDIR_SLUG_LENGTH = 40;
+
+/**
+ * Local copy of kimi-core's `slugifyWorkDirName`. Keep byte-identical to the
+ * canonical implementation in `packages/kimi-core/src/utils/workdir-slug.ts`.
+ */
+function slugifyWorkDirName(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9._-]+/g, '-')
+    .replaceAll(/^-+|-+$/g, '')
+    .slice(0, MAX_WORKDIR_SLUG_LENGTH)
+    .replaceAll(/^-+|-+$/g, '');
+  return slug === '' || slug === '.' || slug === '..' ? 'workspace' : slug;
+}
diff --git a/packages/migration-legacy/src/steps/config.ts b/packages/migration-legacy/src/steps/config.ts
new file mode 100644
index 000000000..29c2b6463
--- /dev/null
+++ b/packages/migration-legacy/src/steps/config.ts
@@ -0,0 +1,435 @@
+import { readFile, mkdir } from 'node:fs/promises';
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+import {
+  HookDefSchema,
+  KimiConfigSchema,
+  ModelAliasSchema,
+  ProviderConfigSchema,
+  transformTomlData,
+} from '@moonshot-ai/agent-core';
+import { atomicWrite } from '../atomic-write.js';
+import { DEFAULT_CONFIG_FILE_TEXT, isTuiStubOrMissing } from '../stub-detect.js';
+import {
+  sourceConfigToml,
+  targetConfigFile,
+  targetTuiFile,
+  siblingConfigToml,
+  siblingTuiToml,
+} from '../paths.js';
+
+// `theme` / `default_editor` belong in tui.toml, not config.toml.
+const TUI_TOP_LEVEL_KEYS = new Set(['theme', 'default_editor']);
+
+// kimi-code's tui.toml `theme` enum (mirrors apps/kimi-code TuiThemeSchema).
+// A legacy theme outside this set would fail loadTuiConfig()'s whole-file
+// validation, taking the migrated editor command down with it — so drop it.
+const TUI_THEMES: ReadonlySet<string> = new Set(['dark', 'light', 'auto']);
+
+function camelToSnake(s: string): string {
+  return s.replaceAll(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+
+// The config.toml top-level keys kimi-code understands, derived from the live
+// KimiConfigSchema so the set tracks kimi-code automatically. `raw` is internal
+// — never migrate it. `providers` / `models` / `hooks` are filtered per-entry,
+// not via this set.
+const SUPPORTED_TOP_LEVEL_KEYS: ReadonlySet<string> = new Set(
+  Object.keys(KimiConfigSchema.shape)
+    .filter((k) => k !== 'raw' && k !== 'providers' && k !== 'models' && k !== 'hooks')
+    .map(camelToSnake),
+);
+
+export interface ConfigStepInput {
+  readonly sourceHome: string;
+  readonly targetHome: string;
+}
+
+export interface ConfigStepResult {
+  readonly migrated: boolean;
+  readonly tuiExtracted: boolean;
+  readonly droppedProviders: readonly string[];
+  readonly droppedModels: readonly string[];
+  /** Top-level keys dropped because kimi-code's config schema lacks them. */
+  readonly droppedKeys: readonly string[];
+  /**
+   * Keys/sections the existing target config and the kimi-cli config both set
+   * to a different value — the target's value was kept.
+   */
+  readonly configConflicts: readonly string[];
+  /** A `config.toml` conflict forced a `config.migrated-from-kimi-cli.toml` sibling. */
+  readonly wroteSiblingDueToConflict: boolean;
+  /** A `tui.toml` conflict forced a `tui.migrated-from-kimi-cli.toml` sibling. */
+  readonly wroteTuiSibling: boolean;
+  /** Count of kimi-cli hook entries written into the LIVE target config. */
+  readonly migratedHooks: number;
+  /** Count of kimi-cli hook entries dropped because kimi-code's schema rejects them. */
+  readonly droppedHooks: number;
+  /**
+   * When sibling mode kicks in (`wroteSiblingDueToConflict === true`), the
+   * content that landed in `config.migrated-from-kimi-cli.toml` instead of
+   * the live `config.toml`. Surfaced by the result screen so the user knows
+   * what they need to merge by hand. Empty in `overwrite` / `merge` modes.
+   */
+  readonly siblingContents: {
+    readonly providers: readonly string[];
+    readonly models: readonly string[];
+    readonly hooks: number;
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function emptyResult(): ConfigStepResult {
+  return {
+    migrated: false,
+    tuiExtracted: false,
+    droppedProviders: [],
+    droppedModels: [],
+    droppedKeys: [],
+    configConflicts: [],
+    wroteSiblingDueToConflict: false,
+    wroteTuiSibling: false,
+    migratedHooks: 0,
+    droppedHooks: 0,
+    siblingContents: { providers: [], models: [], hooks: 0 },
+  };
+}
+
+/** True when the kimi-cli provider entry validates against kimi-code's schema. */
+function providerIsSupported(prov: Record<string, unknown>): boolean {
+  const transformed = transformTomlData({ providers: { x: prov } });
+  const entry = isRecord(transformed['providers']) ? transformed['providers']['x'] : undefined;
+  return ProviderConfigSchema.safeParse(entry).success;
+}
+
+/** True when the kimi-cli model entry validates against kimi-code's schema. */
+function modelIsSupported(mod: Record<string, unknown>): boolean {
+  const transformed = transformTomlData({ models: { x: mod } });
+  const entry = isRecord(transformed['models']) ? transformed['models']['x'] : undefined;
+  return ModelAliasSchema.safeParse(entry).success;
+}
+
+/** Order-insensitive deep-equality key, so re-ordered tables are not conflicts. */
+function stableKey(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableKey).join(',')}]`;
+  if (isRecord(value)) {
+    return `{${Object.keys(value)
+      .toSorted()
+      .map((k) => `${JSON.stringify(k)}:${stableKey(value[k])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  return stableKey(a) === stableKey(b);
+}
+
+/**
+ * Additively merge the kimi-cli config into the existing target config: add
+ * keys/providers/models the target lacks, keep the target's value on a real
+ * conflict, and record those conflicts. A target value is never overwritten.
+ */
+function mergeConfig(
+  target: Record<string, unknown>,
+  migrated: Record<string, unknown>,
+): { merged: Record<string, unknown>; conflicts: string[] } {
+  const merged: Record<string, unknown> = { ...target };
+  const conflicts: string[] = [];
+  for (const [key, value] of Object.entries(migrated)) {
+    if ((key === 'providers' || key === 'models') && isRecord(value)) {
+      const section: Record<string, unknown> = isRecord(merged[key]) ? { ...merged[key] } : {};
+      for (const [name, entry] of Object.entries(value)) {
+        if (section[name] === undefined) {
+          section[name] = entry;
+        } else if (!deepEqual(section[name], entry)) {
+          conflicts.push(`${key}.${name}`);
+        }
+      }
+      merged[key] = section;
+      continue;
+    }
+    if (merged[key] === undefined) {
+      merged[key] = value;
+    } else if (!deepEqual(merged[key], value)) {
+      conflicts.push(key);
+    }
+  }
+  return { merged, conflicts };
+}
+
+export async function migrateConfigStep(input: ConfigStepInput): Promise<ConfigStepResult> {
+  let oldText: string;
+  try {
+    oldText = await readFile(sourceConfigToml(input.sourceHome), 'utf-8');
+  } catch {
+    return emptyResult();
+  }
+
+  let parsedRaw: unknown;
+  try {
+    parsedRaw = parseToml(oldText);
+  } catch {
+    // Malformed legacy config.toml: skip config migration rather than aborting
+    // the whole run. sessions/MCP/history still migrate.
+    return emptyResult();
+  }
+  const parsed: Record<string, unknown> = isRecord(parsedRaw) ? parsedRaw : {};
+
+  // Decide how the target config.toml is handled: a missing or pristine-stub
+  // target is overwritten; a parseable user config is merged into; an
+  // unparseable target falls back to a side file (it cannot be merged).
+  const configPath = targetConfigFile(input.targetHome);
+  let targetText: string | undefined;
+  try {
+    targetText = await readFile(configPath, 'utf-8');
+  } catch {
+    targetText = undefined;
+  }
+  let targetMode: 'overwrite' | 'merge' | 'sibling';
+  let targetParsed: Record<string, unknown> = {};
+  if (targetText === undefined || targetText === DEFAULT_CONFIG_FILE_TEXT) {
+    targetMode = 'overwrite';
+  } else {
+    try {
+      const tp: unknown = parseToml(targetText);
+      targetParsed = isRecord(tp) ? tp : {};
+      targetMode = 'merge';
+    } catch {
+      targetMode = 'sibling';
+    }
+  }
+
+  // Provider names available to migrated models: those kept by this run, plus
+  // any already present in the target config being merged into.
+  const availableProviderNames = new Set<string>(
+    isRecord(targetParsed['providers']) ? Object.keys(targetParsed['providers']) : [],
+  );
+
+  // Model alias names already present in the target config being merged into —
+  // a migrated `default_model` may legitimately point at one of these.
+  const availableModelNames = new Set<string>(
+    isRecord(targetParsed['models']) ? Object.keys(targetParsed['models']) : [],
+  );
+
+  // 1) Providers — keep only those kimi-code's schema accepts.
+  const droppedProviders: string[] = [];
+  const keptProviders: Record<string, Record<string, unknown>> = {};
+  if (isRecord(parsed['providers'])) {
+    for (const [name, prov] of Object.entries(parsed['providers'])) {
+      if (isRecord(prov) && providerIsSupported(prov)) {
+        keptProviders[name] = prov;
+      } else {
+        droppedProviders.push(name);
+      }
+    }
+  }
+
+  // Provider names the merge resolves to a DIFFERENT entry than the kimi-cli
+  // one: the target already defines a same-named provider with other settings,
+  // so `mergeConfig` keeps the target's. A migrated model bound to such a name
+  // would silently run against the target's endpoint/credentials, not the
+  // legacy ones it was configured for — so treat the name as unavailable.
+  const targetProviders: Record<string, unknown> = isRecord(targetParsed['providers'])
+    ? targetParsed['providers']
+    : {};
+  const conflictedProviderNames = new Set<string>();
+  for (const [name, prov] of Object.entries(keptProviders)) {
+    const targetProv = targetProviders[name];
+    if (targetProv !== undefined && !deepEqual(targetProv, prov)) {
+      conflictedProviderNames.add(name);
+    }
+  }
+
+  // 2) Models — keep only those kimi-code's schema accepts, and not those
+  //    whose provider was dropped as unsupported (they could never resolve).
+  const droppedModels: string[] = [];
+  const keptModels: Record<string, Record<string, unknown>> = {};
+  if (isRecord(parsed['models'])) {
+    for (const [name, mod] of Object.entries(parsed['models'])) {
+      if (!isRecord(mod) || !modelIsSupported(mod)) {
+        droppedModels.push(name);
+        continue;
+      }
+      // `modelIsSupported` guarantees `provider` is a string. Keep the model
+      // only if that provider is available — kept by this run or already in
+      // the target config — and is not a name whose merged entry will differ
+      // from the legacy provider this model was configured against.
+      const provider = mod['provider'];
+      if (
+        typeof provider !== 'string' ||
+        (keptProviders[provider] === undefined && !availableProviderNames.has(provider)) ||
+        conflictedProviderNames.has(provider)
+      ) {
+        droppedModels.push(name);
+        continue;
+      }
+      keptModels[name] = mod;
+    }
+  }
+
+  // 2b) Hooks — keep only entries kimi-code's HookDefSchema accepts. kimi-cli
+  //     and kimi-code share an identical hook shape, so a valid legacy hook
+  //     passes straight through; the per-entry filter only guards against
+  //     future schema drift (an event type / field kimi-code does not know).
+  //     Hook fields are all single lowercase words, so — unlike providers /
+  //     models — no `transformTomlData` snake→camel pass is needed first.
+  let droppedHooks = 0;
+  const keptHooks: unknown[] = [];
+  if (Array.isArray(parsed['hooks'])) {
+    for (const entry of parsed['hooks']) {
+      if (HookDefSchema.safeParse(entry).success) {
+        keptHooks.push(entry);
+      } else {
+        droppedHooks++;
+      }
+    }
+  }
+
+  // 3) Split out the keys that belong in tui.toml.
+  const tuiEditor: Record<string, unknown> = {};
+  const tuiOut: Record<string, unknown> = {
+    editor: tuiEditor,
+    notifications: { enabled: true, notification_condition: 'unfocused' },
+  };
+  const themeVal = parsed['theme'];
+  if (typeof themeVal === 'string' && TUI_THEMES.has(themeVal)) {
+    tuiOut['theme'] = themeVal;
+  }
+  const editorVal = parsed['default_editor'];
+  if (typeof editorVal === 'string') {
+    tuiEditor['command'] = editorVal;
+  }
+
+  // 4) Build the migrated top-level — only keys kimi-code's schema supports.
+  const droppedKeys: string[] = [];
+  const migratedTop: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(parsed)) {
+    if (k === 'providers' || k === 'models' || k === 'hooks') continue;
+    if (TUI_TOP_LEVEL_KEYS.has(k)) continue;
+    if (k === 'default_yolo') {
+      // kimi-cli's `default_yolo` is kimi-code's `yolo`.
+      if (v === true) migratedTop['yolo'] = true;
+      continue;
+    }
+    if (!SUPPORTED_TOP_LEVEL_KEYS.has(k)) {
+      droppedKeys.push(k);
+      continue;
+    }
+    // Drop default_model unless it points at a model that will exist in the
+    // written config — one kept from kimi-cli, or already in the target being
+    // merged into. A dangling alias (dropped, stale, or never present) would
+    // fail the next session-create.
+    if (
+      k === 'default_model' &&
+      typeof v === 'string' &&
+      keptModels[v] === undefined &&
+      !availableModelNames.has(v)
+    ) {
+      continue;
+    }
+    migratedTop[k] = v;
+  }
+  if (Object.keys(keptProviders).length > 0) migratedTop['providers'] = keptProviders;
+  if (Object.keys(keptModels).length > 0) migratedTop['models'] = keptModels;
+  if (keptHooks.length > 0) migratedTop['hooks'] = keptHooks;
+
+  // 4b) Drop any supported top-level key whose VALUE kimi-code's config
+  //     schema rejects (e.g. `telemetry = "false"`, `extra_skill_dirs = "/tmp"`).
+  //     Providers/models are already validated per-entry above, so schema
+  //     failures here can only come from plain top-level keys.
+  for (;;) {
+    const result = KimiConfigSchema.safeParse(transformTomlData(migratedTop));
+    if (result.success) break;
+    const badKeys = new Set<string>();
+    for (const issue of result.error.issues) {
+      const top = issue.path[0];
+      if (typeof top === 'string' && top !== 'providers' && top !== 'models') {
+        badKeys.add(camelToSnake(top));
+      }
+    }
+    if (badKeys.size === 0) break; // cannot attribute — stop rather than loop
+    for (const k of badKeys) {
+      if (k in migratedTop) {
+        delete migratedTop[k];
+        droppedKeys.push(k);
+      }
+    }
+  }
+
+  // 5) Write config.toml per the target mode.
+  await mkdir(input.targetHome, { recursive: true, mode: 0o700 });
+  let wroteConfigSibling = false;
+  let configConflicts: readonly string[] = [];
+  if (targetMode === 'sibling') {
+    await atomicWrite(siblingConfigToml(input.targetHome), stringifyToml(migratedTop));
+    wroteConfigSibling = true;
+  } else if (targetMode === 'merge') {
+    const { merged, conflicts } = mergeConfig(targetParsed, migratedTop);
+    configConflicts = conflicts;
+    await atomicWrite(configPath, stringifyToml(merged));
+  } else {
+    await atomicWrite(configPath, stringifyToml(migratedTop));
+  }
+
+  // 6) Write tui.toml (or a sibling if the target tui.toml is user-modified).
+  const tuiPath = targetTuiFile(input.targetHome);
+  const canOverwriteTui = await isTuiStubOrMissing(tuiPath);
+  const renderedTui = stringifyToml(tuiOut);
+  const hasThemeExtracted = tuiOut['theme'] !== undefined;
+  const hasEditorExtracted = tuiEditor['command'] !== undefined;
+  let wroteTuiSibling = false;
+  let tuiExtracted = false;
+  if (hasThemeExtracted || hasEditorExtracted) {
+    if (canOverwriteTui) {
+      await atomicWrite(tuiPath, renderedTui);
+    } else {
+      await atomicWrite(siblingTuiToml(input.targetHome), renderedTui);
+      wroteTuiSibling = true;
+    }
+    tuiExtracted = true;
+  }
+
+  // `migratedHooks` counts hooks the runtime will actually see — i.e. hooks
+  // we wrote into the LIVE `config.toml`. That happens only when:
+  //  - overwrite mode (target was missing / pristine stub, we wrote fresh), or
+  //  - merge mode AND the target had no `hooks` key (mergeConfig added ours).
+  // In merge mode where target already declares `hooks` (any value: empty,
+  // identical, different, or even non-array invalid), `mergeConfig` keeps
+  // the target's value, so the source hooks never land in the live config.
+  // In sibling mode the source hooks land in `config.migrated-from-kimi-cli.toml`,
+  // which the runtime never reads — they're accounted for via `siblingContents`,
+  // not `migratedHooks`.
+  const hooksLandedInLiveConfig =
+    keptHooks.length > 0 &&
+    (targetMode === 'overwrite' ||
+      (targetMode === 'merge' && targetParsed['hooks'] === undefined));
+  const migratedHooks = hooksLandedInLiveConfig ? keptHooks.length : 0;
+
+  // In sibling mode, enumerate what landed in the sibling file so the result
+  // screen can tell the user exactly what is awaiting manual merge.
+  const siblingContents =
+    targetMode === 'sibling'
+      ? {
+          providers: Object.keys(keptProviders),
+          models: Object.keys(keptModels),
+          hooks: keptHooks.length,
+        }
+      : { providers: [] as string[], models: [] as string[], hooks: 0 };
+
+  return {
+    migrated: true,
+    tuiExtracted,
+    droppedProviders,
+    droppedModels,
+    droppedKeys,
+    configConflicts,
+    wroteSiblingDueToConflict: wroteConfigSibling,
+    wroteTuiSibling,
+    migratedHooks,
+    droppedHooks,
+    siblingContents,
+  };
+}
diff --git a/packages/migration-legacy/src/steps/mcp.ts b/packages/migration-legacy/src/steps/mcp.ts
new file mode 100644
index 000000000..f75e557de
--- /dev/null
+++ b/packages/migration-legacy/src/steps/mcp.ts
@@ -0,0 +1,102 @@
+import { readFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { McpServerConfigSchema } from '@moonshot-ai/agent-core';
+import { atomicWrite } from '../atomic-write.js';
+import { siblingMcpJson, sourceMcpJson, targetMcpFile } from '../paths.js';
+
+export interface McpStepInput {
+  readonly sourceHome: string;
+  readonly targetHome: string;
+}
+
+export interface McpStepResult {
+  readonly mergedServers: readonly string[];
+  readonly keptNewForConflicts: readonly string[];
+  /** Source servers dropped because kimi-code's MCP schema rejects them. */
+  readonly droppedServers: readonly string[];
+  /** Target `mcp.json` existed but was unparseable; output went to a sibling. */
+  readonly wroteSiblingDueToConflict: boolean;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export async function migrateMcpStep(input: McpStepInput): Promise<McpStepResult> {
+  let sourceText: string;
+  try {
+    sourceText = await readFile(sourceMcpJson(input.sourceHome), 'utf-8');
+  } catch {
+    return { mergedServers: [], keptNewForConflicts: [], droppedServers: [], wroteSiblingDueToConflict: false };
+  }
+
+  let sourceJson: unknown;
+  try {
+    sourceJson = JSON.parse(sourceText);
+  } catch {
+    return { mergedServers: [], keptNewForConflicts: [], droppedServers: [], wroteSiblingDueToConflict: false };
+  }
+  const srcServers: Record<string, unknown> = {};
+  if (isRecord(sourceJson)) {
+    const raw = sourceJson['mcpServers'];
+    if (isRecord(raw)) {
+      for (const [name, srv] of Object.entries(raw)) {
+        srcServers[name] = srv;
+      }
+    }
+  }
+
+  const mergedTargetServers: Record<string, unknown> = {};
+  let targetText: string | undefined;
+  try {
+    targetText = await readFile(targetMcpFile(input.targetHome), 'utf-8');
+  } catch {
+    targetText = undefined; // absent — start fresh
+  }
+  let targetUnparseable = false;
+  if (targetText !== undefined) {
+    try {
+      const parsed: unknown = JSON.parse(targetText);
+      if (isRecord(parsed)) {
+        const raw = parsed['mcpServers'];
+        if (isRecord(raw)) {
+          for (const [name, srv] of Object.entries(raw)) {
+            mergedTargetServers[name] = srv;
+          }
+        }
+      }
+    } catch {
+      // The target mcp.json exists but is malformed. Overwriting it would
+      // silently destroy the user's existing servers — write the migrated
+      // servers to a sibling and leave the original untouched.
+      targetUnparseable = true;
+    }
+  }
+
+  const mergedServers: string[] = [];
+  const keptNewForConflicts: string[] = [];
+  const droppedServers: string[] = [];
+
+  for (const [name, srv] of Object.entries(srcServers)) {
+    // A server kimi-code's MCP schema rejects would break every session
+    // (resolveSessionMcpConfig parses all entries on create/resume) — drop it.
+    if (!McpServerConfigSchema.safeParse(srv).success) {
+      droppedServers.push(name);
+      continue;
+    }
+    if (Object.prototype.hasOwnProperty.call(mergedTargetServers, name)) {
+      keptNewForConflicts.push(name);
+    } else {
+      mergedTargetServers[name] = srv;
+      mergedServers.push(name);
+    }
+  }
+
+  const outPath = targetUnparseable
+    ? siblingMcpJson(input.targetHome)
+    : targetMcpFile(input.targetHome);
+  await mkdir(dirname(outPath), { recursive: true, mode: 0o700 });
+  await atomicWrite(outPath, JSON.stringify({ mcpServers: mergedTargetServers }, null, 2));
+
+  return { mergedServers, keptNewForConflicts, droppedServers, wroteSiblingDueToConflict: targetUnparseable };
+}
diff --git a/packages/migration-legacy/src/steps/user-history.ts b/packages/migration-legacy/src/steps/user-history.ts
new file mode 100644
index 000000000..552f13286
--- /dev/null
+++ b/packages/migration-legacy/src/steps/user-history.ts
@@ -0,0 +1,62 @@
+import { copyFile, mkdir, readdir, rename, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import type { Stats } from 'node:fs';
+import { join } from 'node:path';
+import { sourceUserHistoryDir, targetUserHistoryDir } from '../paths.js';
+
+export interface UserHistoryStepInput {
+  readonly sourceHome: string;
+  readonly targetHome: string;
+}
+
+export interface UserHistoryStepResult {
+  readonly copied: number;
+  readonly skippedExisting: number;
+}
+
+export async function migrateUserHistoryStep(
+  input: UserHistoryStepInput,
+): Promise<UserHistoryStepResult> {
+  const srcDir = sourceUserHistoryDir(input.sourceHome);
+  const tgtDir = targetUserHistoryDir(input.targetHome);
+
+  let entries: string[];
+  try {
+    entries = await readdir(srcDir);
+  } catch {
+    return { copied: 0, skippedExisting: 0 };
+  }
+
+  let copied = 0;
+  let skippedExisting = 0;
+  let targetDirReady = false;
+  for (const name of entries) {
+    const srcPath = join(srcDir, name);
+    const tgtPath = join(tgtDir, name);
+    let st: Stats;
+    try {
+      st = await stat(srcPath);
+    } catch {
+      continue;
+    }
+    if (!st.isFile()) continue;
+    if (existsSync(tgtPath)) {
+      skippedExisting++;
+      continue;
+    }
+    // Create the target dir only once there is a file to put in it — touching
+    // it earlier aborts the whole migration if the path is blocked.
+    if (!targetDirReady) {
+      await mkdir(tgtDir, { recursive: true, mode: 0o700 });
+      targetDirReady = true;
+    }
+    // Copy atomically: a crash mid-copy leaves only the temp file, never a
+    // truncated final file that the next run would skip as complete.
+    const tmpPath = `${tgtPath}.${process.pid}.tmp`;
+    await copyFile(srcPath, tmpPath);
+    await rename(tmpPath, tgtPath);
+    copied++;
+  }
+
+  return { copied, skippedExisting };
+}
diff --git a/packages/migration-legacy/src/stub-detect.ts b/packages/migration-legacy/src/stub-detect.ts
new file mode 100644
index 000000000..8ba3a1f4f
--- /dev/null
+++ b/packages/migration-legacy/src/stub-detect.ts
@@ -0,0 +1,68 @@
+import { readFile } from 'node:fs/promises';
+import { parse as parseToml } from 'smol-toml';
+
+// Verbatim from packages/kimi-core/src/harness/configs/toml.ts:42
+export const DEFAULT_CONFIG_FILE_TEXT =
+  '# ~/.kimi-code/config.toml\n' +
+  '# Runtime settings for Kimi Code.\n' +
+  '# This file starts empty so built-in defaults can apply.\n' +
+  '# Login will populate managed Kimi provider and model entries.\n';
+
+// Verbatim from apps/kimi-code/src/tui/config.ts:renderTuiConfig(DEFAULT_TUI_CONFIG)
+export const DEFAULT_TUI_RENDER =
+  '# ~/.kimi-code/tui.toml\n' +
+  '# Terminal UI preferences for kimi-code.\n' +
+  '# Agent/runtime settings stay in ~/.kimi-code/config.toml.\n' +
+  '\n' +
+  'theme = "auto" # "auto" | "dark" | "light"\n' +
+  '\n' +
+  '[editor]\n' +
+  'command = "" # Empty uses $VISUAL / $EDITOR\n' +
+  '\n' +
+  '[notifications]\n' +
+  'enabled = true # true | false\n' +
+  'notification_condition = "unfocused" # "unfocused" | "always"\n';
+
+export async function isConfigStubOrMissing(configPath: string): Promise<boolean> {
+  let text: string;
+  try {
+    text = await readFile(configPath, 'utf-8');
+  } catch {
+    return true; // missing = ok to overwrite
+  }
+  return text === DEFAULT_CONFIG_FILE_TEXT;
+}
+
+export async function isTuiStubOrMissing(tuiPath: string): Promise<boolean> {
+  let text: string;
+  try {
+    text = await readFile(tuiPath, 'utf-8');
+  } catch {
+    return true;
+  }
+  if (text === DEFAULT_TUI_RENDER) return true;
+
+  // Fallback: parse and compare fields semantically
+  try {
+    const parsed = parseToml(text) as Record<string, unknown>;
+    const theme = parsed['theme'];
+    const editor = parsed['editor'] as Record<string, unknown> | undefined;
+    const notifications = parsed['notifications'] as Record<string, unknown> | undefined;
+
+    const themeOk = theme === undefined || theme === 'auto';
+    const editorOk =
+      editor === undefined || editor['command'] === undefined || editor['command'] === '';
+    const notifEnabledOk =
+      notifications === undefined ||
+      notifications['enabled'] === undefined ||
+      notifications['enabled'] === true;
+    const notifCondOk =
+      notifications === undefined ||
+      notifications['notification_condition'] === undefined ||
+      notifications['notification_condition'] === 'unfocused';
+
+    return themeOk && editorOk && notifEnabledOk && notifCondOk;
+  } catch {
+    return false; // unparseable = treat as user-modified, do not overwrite
+  }
+}
diff --git a/packages/migration-legacy/src/types.ts b/packages/migration-legacy/src/types.ts
new file mode 100644
index 000000000..bee222efe
--- /dev/null
+++ b/packages/migration-legacy/src/types.ts
@@ -0,0 +1,133 @@
+/**
+ * Plan describing the contents detected under the source `~/.kimi/` directory.
+ * Produced by detect(); consumed by runMigration().
+ */
+export interface MigrationPlan {
+  readonly sourceHome: string;
+  readonly hasConfig: boolean;
+  readonly hasMcp: boolean;
+  readonly hasUserHistory: boolean;
+  readonly oauthCredentials: readonly string[]; // basenames found under credentials/
+  readonly workdirs: readonly WorkDirEntry[];
+  readonly detectedPlugins: readonly string[];
+  readonly detectedMcpOauthServers: readonly string[];
+  readonly totalSessions: number; // sum across workdirs (real, post-classify)
+}
+
+/**
+ * One workdir bucket (`~/.kimi/sessions/<md5>/`) with reverse-looked-up
+ * path from `~/.kimi/kimi.json`. Buckets with kaos != 'local' or no
+ * workdir found are excluded from this list (they appear in counters).
+ */
+export interface WorkDirEntry {
+  readonly oldHashDir: string; // absolute path to ~/.kimi/sessions/<md5>/
+  readonly workdirPath: string; // resolved absolute filesystem path
+  readonly sessions: readonly SessionEntry[];
+}
+
+export interface SessionEntry {
+  readonly uuid: string;
+  readonly oldDir: string; // absolute path
+  readonly wireMtime: number; // unix-ms, for "recent" sort; 0 if unknown
+}
+
+/**
+ * User-driven knobs for what gets migrated. `sessions: true` migrates every
+ * real local session; `false` skips the sessions step entirely.
+ */
+export interface MigrationScope {
+  readonly config: boolean;
+  readonly mcp: boolean;
+  readonly userHistory: boolean;
+  readonly sessions: boolean;
+}
+
+/**
+ * Output of a runMigration() call. Serialized verbatim to
+ * `~/.kimi-code/migration-report.json` and surfaced in the terminal summary.
+ */
+export interface MigrationReport {
+  readonly startedAt: string;
+  readonly completedAt: string;
+  readonly migratorVersion: string;
+  readonly source: string;
+  readonly target: string;
+  readonly summary: MigrationSummary;
+  readonly notices: MigrationNotices;
+}
+
+export interface MigrationSummary {
+  readonly config: {
+    readonly migrated: boolean;
+    readonly tuiExtracted: boolean;
+    readonly droppedProviders: readonly string[];
+    readonly droppedModels: readonly string[];
+    /** Top-level keys dropped because kimi-code's config schema lacks them. */
+    readonly droppedKeys: readonly string[];
+    /**
+     * Keys/sections where the existing target config and the kimi-cli config
+     * both set a different value — the target's value was kept.
+     */
+    readonly configConflicts: readonly string[];
+    /** A `config.toml` conflict forced a `config.migrated-from-kimi-cli.toml` sibling. */
+    readonly wroteSiblingDueToConflict: boolean;
+    /** A `tui.toml` conflict forced a `tui.migrated-from-kimi-cli.toml` sibling. */
+    readonly wroteTuiSibling: boolean;
+    /** Count of kimi-cli hook entries written into the LIVE target config. */
+    readonly migratedHooks: number;
+    /** Count of kimi-cli hook entries dropped because kimi-code's schema rejects them. */
+    readonly droppedHooks: number;
+    /**
+     * When `wroteSiblingDueToConflict` is true, what landed in
+     * `config.migrated-from-kimi-cli.toml` instead of the live `config.toml`.
+     * The result screen surfaces these so the user knows what needs manual
+     * merging. Empty in `overwrite` / `merge` modes.
+     */
+    readonly siblingContents: {
+      readonly providers: readonly string[];
+      readonly models: readonly string[];
+      readonly hooks: number;
+    };
+  };
+  readonly mcp: {
+    readonly mergedServers: readonly string[];
+    readonly keptNewForConflicts: readonly string[];
+    /** Source servers dropped because kimi-code's MCP schema rejects them. */
+    readonly droppedServers: readonly string[];
+    /** Target `mcp.json` was unparseable; merged servers went to a sibling. */
+    readonly wroteSiblingDueToConflict: boolean;
+  };
+  readonly userHistory: { readonly copied: number; readonly skippedExisting: number };
+  readonly sessions: SessionsSummary;
+}
+
+export interface SessionsSummary {
+  readonly scope: 'all' | 'config-only';
+  readonly bucketsScanned: number;
+  readonly bucketsSkippedNonlocalKaos: number;
+  readonly bucketsSkippedNoWorkdirFound: number;
+  readonly sessionsAttempted: number;
+  readonly sessionsMigrated: number;
+  /** Sessions already imported by a previous run (idempotent re-run). */
+  readonly sessionsAlreadyMigrated: number;
+  readonly sessionsSkippedPlaceholder: number;
+  readonly sessionsSkippedEmpty: number;
+  readonly sessionsSkippedMalformed: number;
+  readonly sessionsFailed: ReadonlyArray<{ readonly sourcePath: string; readonly reason: string }>;
+  readonly sessionsConflicts: ReadonlyArray<{ readonly sourcePath: string; readonly targetPath: string }>;
+}
+
+export interface MigrationNotices {
+  readonly mcpOauthServersRequiringReauth: readonly string[];
+  /**
+   * Basenames of kimi-cli OAuth logins (`~/.kimi/credentials/<name>.json`)
+   * found at detection time. OAuth credentials are deliberately NOT migrated:
+   * refresh tokens rotate server-side, so a copied credential breaks login for
+   * whichever install refreshes second. The user must run `/login` in
+   * kimi-code instead. Empty when the legacy install had no OAuth login.
+   */
+  readonly oauthLoginsRequiringRelogin: readonly string[];
+  readonly detectedPlugins: readonly string[];
+  readonly configConflictNotice: string | null;
+  readonly tuiConflictNotice: string | null;
+}
diff --git a/packages/migration-legacy/test/.gitkeep b/packages/migration-legacy/test/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/packages/migration-legacy/test/atomic-write.test.ts b/packages/migration-legacy/test/atomic-write.test.ts
new file mode 100644
index 000000000..95f423d53
--- /dev/null
+++ b/packages/migration-legacy/test/atomic-write.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { atomicWrite } from '../src/atomic-write.js';
+
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'atomic-write-'));
+});
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('atomicWrite', () => {
+  it('writes the target file with private 0600 permissions', async () => {
+    // Migrated config files carry provider API keys — they must not be
+    // group/world-readable regardless of the target directory's mode.
+    const path = join(dir, 'config.toml');
+    await atomicWrite(path, 'api_key = "secret"\n');
+    expect(await readFile(path, 'utf-8')).toBe('api_key = "secret"\n');
+    expect((await stat(path)).mode & 0o777).toBe(0o600);
+  });
+});
diff --git a/packages/migration-legacy/test/detect.test.ts b/packages/migration-legacy/test/detect.test.ts
new file mode 100644
index 000000000..9cdcf0e36
--- /dev/null
+++ b/packages/migration-legacy/test/detect.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { detectMigration } from '../src/detect.js';
+
+let src: string;
+beforeEach(async () => {
+  src = await mkdtemp(join(tmpdir(), 'detect-'));
+});
+afterEach(async () => {
+  await rm(src, { recursive: true, force: true });
+});
+
+describe('detectMigration', () => {
+  it('returns empty totals when source dir is empty', async () => {
+    const plan = await detectMigration({ sourcePath: src });
+    expect(plan.hasConfig).toBe(false);
+    expect(plan.hasMcp).toBe(false);
+    expect(plan.totalSessions).toBe(0);
+  });
+
+  it('detects config/mcp/credentials/user-history/plugins/mcp-oauth presence', async () => {
+    await writeFile(join(src, 'config.toml'), '');
+    await writeFile(join(src, 'mcp.json'), '{"mcpServers":{}}');
+    await mkdir(join(src, 'credentials'), { recursive: true });
+    await writeFile(join(src, 'credentials', 'kimi-code.json'), '{}');
+    await mkdir(join(src, 'user-history'), { recursive: true });
+    await mkdir(join(src, 'plugins', 'p1'), { recursive: true });
+    await mkdir(join(src, 'mcp-oauth'), { recursive: true });
+    await writeFile(join(src, 'mcp-oauth', 'server-1'), '');
+
+    const plan = await detectMigration({ sourcePath: src });
+    expect(plan.hasConfig).toBe(true);
+    expect(plan.hasMcp).toBe(true);
+    expect(plan.hasUserHistory).toBe(true);
+    expect(plan.oauthCredentials).toEqual(['kimi-code.json']);
+    expect(plan.detectedPlugins).toEqual(['p1']);
+    expect(plan.detectedMcpOauthServers).toContain('server-1');
+  });
+
+});
diff --git a/packages/migration-legacy/test/fixtures/archived/context.jsonl b/packages/migration-legacy/test/fixtures/archived/context.jsonl
new file mode 100644
index 000000000..12f9ddabc
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/archived/context.jsonl
@@ -0,0 +1,10 @@
+{"role":"_system_prompt","content":"You are an AI agent. (system prompt elided in fixture)"}
+{"role": "_checkpoint", "id": 0}
+{"role":"user","content":"You are a code translation assistant.\n\nTask:\n- Read the file `sample.js` in the current working directory.\n- Translate it into idiomatic Python 3.\n- Write the translated code to `translated.py` in the current working directory.\n\nRules:\n- You must read the file from disk; do not guess its contents.\n- Preserve behavior and output.\n- Write only Python code in translated.py (no Markdown).\n- Overwrite translated.py if it already exists.\n- After writing, reply with a single short ASCII confirmation se... [truncated]"}
+{"role": "_checkpoint", "id": 1}
+{"role":"user","content":"<system-reminder>\nYou are running in non-interactive mode. The user cannot answer questions or provide feedback during execution.\n- Do NOT call AskUserQuestion. If you need to make a decision, make your best judgment and proceed.\n- For EnterPlanMode / ExitPlanMode, they will be auto-approved. You can use them normally but expect no user feedback.\n</system-reminder>"}
+{"role": "_usage", "token_count": 18}
+{"role":"assistant","content":[],"tool_calls":[{"type":"function","id":"ReadFile:0","function":{"name":"ReadFile","arguments":"{\"path\": \"sample.js\"}"}}]}
+{"role": "_usage", "token_count": 21}
+{"role":"tool","content":[{"type":"text","text":"<system>10 lines read from file starting from line 1. End of file reached.</system>"},{"type":"text","text":"     1\tfunction add(a, b) {\n     2\t  return a + b;\n     3\t}\n     4\t\n     5\tfunction main() {\n     6\t  const result = add(2, 3);\n     7\t  console.log(`2 + 3 = ${result}`);\n     8\t}\n     9\t\n    10\tmain();\n"}],"tool_call_id":"ReadFile:0"}
+{"role": "_checkpoint", "id": 2}
diff --git a/packages/migration-legacy/test/fixtures/archived/state.json b/packages/migration-legacy/test/fixtures/archived/state.json
new file mode 100644
index 000000000..c42c42adc
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/archived/state.json
@@ -0,0 +1,19 @@
+{
+  "version": 1,
+  "approval": {
+    "yolo": false,
+    "auto_approve_actions": []
+  },
+  "additional_dirs": [],
+  "custom_title": "You are a code translation assistant. Task: [...]",
+  "title_generated": false,
+  "title_generate_attempts": 0,
+  "plan_mode": false,
+  "plan_session_id": null,
+  "plan_slug": null,
+  "wire_mtime": null,
+  "archived": true,
+  "archived_at": 1777355100.904803,
+  "auto_archive_exempt": false,
+  "todos": []
+}
\ No newline at end of file
diff --git a/packages/migration-legacy/test/fixtures/archived/wire.jsonl b/packages/migration-legacy/test/fixtures/archived/wire.jsonl
new file mode 100644
index 000000000..6ccdadb8d
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/archived/wire.jsonl
@@ -0,0 +1,10 @@
+{"type": "metadata", "protocol_version": "1.8"}
+{"timestamp": 1775104348.646295, "message": {"type": "TurnBegin", "payload": {"user_input": "You are a code translation assistant.\n\nTask:\n- Read the file `sample.js` in the current working directory.\n- Translate it into idiomatic Python 3.\n- Write the translated code to `translated.py` in the current working directory.\n\nRules:\n- You must read the file from disk; do not guess its contents.\n- Preserve behavior and output.\n- Write only Python code in translated.py (no Markdown).\n- Overwrite translated.py if it already exists.\n- After writing, reply with a single short ASCII confirmation sentence."}}}
+{"timestamp": 1775104348.647011, "message": {"type": "StepBegin", "payload": {"n": 1}}}
+{"timestamp": 1775104348.648344, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "ReadFile:0", "function": {"name": "ReadFile", "arguments": "{\"path\": \"sample.js\"}"}, "extras": null}}}
+{"timestamp": 1775104348.648656, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.00018, "context_tokens": 18, "max_context_tokens": 100000, "token_usage": {"input_other": 18, "output": 3, "input_cache_read": 0, "input_cache_creation": 0}, "message_id": "scripted-1", "plan_mode": false, "mcp_status": null}}}
+{"timestamp": 1775104348.649458, "message": {"type": "ToolResult", "payload": {"tool_call_id": "ReadFile:0", "return_value": {"is_error": false, "output": "     1\tfunction add(a, b) {\n     2\t  return a + b;\n     3\t}\n     4\t\n     5\tfunction main() {\n     6\t  const result = add(2, 3);\n     7\t  console.log(`2 + 3 = ${result}`);\n     8\t}\n     9\t\n    10\tmain();\n", "message": "10 lines read from file starting from line 1. End of file reached.", "display": [], "extras": null}}}}
+{"timestamp": 1775104348.650262, "message": {"type": "StepBegin", "payload": {"n": 2}}}
+{"timestamp": 1775104348.6512299, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "WriteFile:1", "function": {"name": "WriteFile", "arguments": "{\"path\": \"translated.py\", \"content\": \"def add(a, b):\\n    return a + b\\n\\ndef main():\\n    result = add(2, 3)\\n    print(f\\\"2 + 3 = {result}\\\")\\n\\nif __name__ == \\\"__main__\\\":\\n    main()\\n\", \"mode\": \"overwrite\"}"}, "extras": null}}}
+{"timestamp": 1775104348.65151, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.00022, "context_tokens": 22, "max_context_tokens": 100000, "token_usage": {"input_other": 22, "output": 4, "input_cache_read": 0, "input_cache_creation": 0}, "message_id": "scripted-2", "plan_mode": false, "mcp_status": null}}}
+{"timestamp": 1775104348.6518762, "message": {"type": "ToolResult", "payload": {"tool_call_id": "WriteFile:1", "return_value": {"is_error": false, "output": "", "message": "File successfully overwritten. Current size: 138 bytes.", "display": [{"type": "diff", "path": "/private/var/folders/12/g67l4jvx6cz1_w9jct2_qzrw0000gn/T/tmpkug6yytj/translated.py", "old_text": "", "new_text": "def add(a, b):\n    return a + b\n\ndef main():\n    result = add(2, 3)\n    print(f\"2 + 3 = {result}\")\n\nif __name__ == \"__main__\":\n    main()", "old_start": 1, "new_start": 1, "is_summary": false}], "extras": null}}}}
diff --git a/packages/migration-legacy/test/fixtures/broken-state-json/context.jsonl b/packages/migration-legacy/test/fixtures/broken-state-json/context.jsonl
new file mode 100644
index 000000000..68089f19c
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/broken-state-json/context.jsonl
@@ -0,0 +1,5 @@
+{"role":"_system_prompt","content":"You are ..."}
+{"role":"_checkpoint","id":0}
+{"role":"user","content":"hi"}
+{"role":"_usage","token_count":9133}
+{"role":"assistant","content":[{"type":"text","text":"Hello! How can I help?"}]}
diff --git a/packages/migration-legacy/test/fixtures/broken-state-json/state.json b/packages/migration-legacy/test/fixtures/broken-state-json/state.json
new file mode 100644
index 000000000..81750b96f
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/broken-state-json/state.json
@@ -0,0 +1 @@
+{
\ No newline at end of file
diff --git a/packages/migration-legacy/test/fixtures/broken-state-json/wire.jsonl b/packages/migration-legacy/test/fixtures/broken-state-json/wire.jsonl
new file mode 100644
index 000000000..200e71f95
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/broken-state-json/wire.jsonl
@@ -0,0 +1 @@
+{"type": "metadata", "protocol_version": "1.10"}
diff --git a/packages/migration-legacy/test/fixtures/large-100msgs/context.jsonl b/packages/migration-legacy/test/fixtures/large-100msgs/context.jsonl
new file mode 100644
index 000000000..8fbc685e9
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/large-100msgs/context.jsonl
@@ -0,0 +1,130 @@
+{"role": "_system_prompt", "content": "You are an AI agent. (system prompt elided in fixture)"}
+{"role": "_checkpoint", "id": 0}
+{"role": "user", "content": "请帮我探索一下当前这个仓库的整体结构，了解它的主要模块和功能。看完之后请写一份简短的小报告，列出你认为最重要的几个模块、它们的职责，以及彼此之间的依赖关系。报告控制在一页之内，便于团队成员快速了解项目。"}
+{"role": "_checkpoint", "id": 1}
+{"role": "_usage", "token_count": 12561}
+{"role": "assistant", "content": [{"type": "think", "think": "用户想要我读取 example-task skill 的 SKILL.md 文件，但他们已经在 prompt 中提供了完整的 skill 内容。不过我需要了解这个 skill 的更多细节，特别是 references/prompt-patterns.md 文件。\n\n用户似乎在向我介绍这个 skill，让我熟悉它的用法。我应该先检查一下这个 skill 目录的结构，看看是否有其他有用的资源文件。\n\n让我先了解一下这个 skill 的完整结构，以便以后需要时可以使用它。", "encrypted": null}, {"type": "text", "text": "我来熟悉一下 `example-task` skill 的完整结构和资源。"}], "tool_calls": [{"type": "function", "id": "tool_3mtoDjRlqenM0GDSjv9xRzLS", "function": {"name": "Glob", "arguments": "{\"pattern\": \".agents/skills/example-task/**/*\"}"}}]}
+{"role": "_usage", "token_count": 12694}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Found 5 matches for pattern `.agents/skills/example-task/**/*`.</system>"}, {"type": "text", "text": ".agents/skills/example-task/SKILL.md\n.agents/skills/example-task/references\n.agents/skills/example-task/references/prompt-patterns.md\n.agents/skills/example-task/scripts\n.agents/skills/example-task/scripts/inspect_session.py"}], "tool_call_id": "tool_3mtoDjRlqenM0GDSjv9xRzLS"}
+{"role": "_checkpoint", "id": 2}
+{"role": "_usage", "token_count": 12794}
+{"role": "assistant", "content": [{"type": "think", "think": "让我读取 references/prompt-patterns.md 和 scripts/inspect_session.py 来了解完整的 skill 资源。", "encrypted": null}], "tool_calls": [{"type": "function", "id": "tool_nqkbedqxXK1aX9zAWWNEhzmM", "function": {"name": "ReadFile", "arguments": "{\"path\": \".agents/skills/example-task/references/prompt-patterns.md\"}"}}, {"type": "function", "id": "tool_300OLXjS5RZxFz9LvWJP6QyJ", "function": {"name": "ReadFile", "arguments": "{\"path\": \".agents/skills/example-task/scripts/inspect_session.py\"}"}}]}
+{"role": "_usage", "token_count": 12872}
+{"role": "tool", "content": [{"type": "text", "text": "<system>85 lines read from file starting from line 1. End of file reached.</system>"}, {"type": "text", "text": "     1\t# Prompt 模板\n     2\t\n     3\t以下模板作为脚手架使用。运行前替换占位符。\n     4\t\n     5\t## 单轮还是多轮\n     6\t\n     7\t满足以下任一条件时使用多轮：\n     8\t\n     9\t- 功能有状态\n    10\t- 功能依赖时序或并发\n    11\t- 功能需要审批、清理或恢复\n    12\t- session 产物本身是证据的一部分\n    13\t- 工具接口可能近期发生过变化\n    14\t\n    15\t仅对无状态的窄范围检查使用单轮。\n    16\t\n    17\t## 变量\n    18\t\n    19\t起草 prompt 前填写以下字段：\n    20\t\n    21\t- `<feature>` — 被测功能名称\n    22\t- `<goal>` — 当前场景的目标\n    23\t- `<source_paths>` — 需要阅读的源码路径\n    24\t- `<constraints>` — 执行约束\n    25\t- `<success_signals>` — 成功信号\n    26\t- `<fai... [truncated]"}], "tool_call_id": "tool_nqkbedqxXK1aX9zAWWNEhzmM"}
+{"role": "tool", "content": [{"type": "text", "text": "<system>321 lines read from file starting from line 1. End of file reached.</system>"}, {"type": "text", "text": "     1\t#!/usr/bin/env python3\n     2\t\"\"\"Locate and summarize a Kimi CLI session for smoke-test review.\"\"\"\n     3\t\n     4\tfrom __future__ import annotations\n     5\t\n     6\timport argparse\n     7\timport json\n     8\timport sys\n     9\tfrom collections import Counter\n    10\tfrom pathlib import Path\n    11\tfrom typing import Any\n    12\t\n    13\t\n    14\tdef parse_args() -> argparse.Namespace:\n    15\t    parser = argparse.ArgumentParser(\n    16\t        description=\"Locate and summarize a Kimi CLI session... [truncated]"}], "tool_call_id": "tool_300OLXjS5RZxFz9LvWJP6QyJ"}
+{"role": "_checkpoint", "id": 3}
+{"role": "_usage", "token_count": 17406}
+{"role": "assistant", "content": [{"type": "think", "think": "好的，我现在已经完整了解了 `example-task` skill 的内容。这个 skill 提供了：\n\n1. **SKILL.md** - 主文档，描述了如何针对 the example CLI 的新增或变更功能进行端到端冒烟测试的完整流程\n2. **references/prompt-patterns.md** - 可复用的 prompt 模板\n3. **scripts/inspect_session.py** - 用于检查和分析 session 产物的脚本\n\n用户似乎是在测试我是否能正确读取和使用这个 skill。既然用户已经在 prompt 中提供了完整的 skill 内容，我应该：\n1. 确认我已经理解了 skill 的内容\n2. 询问用户是否有具体的功能需要我使用这个 skill 来进行冒烟测试\n\n或者，用户可能是想了解这个 skill 的用法。让我给出一个总结并询问用户的具体需求。", "encrypted": null}, {"type": "text", "text": "我已完整阅读 `example-task` skill。这是一个用于对 the example CLI 进行端到端冒烟测试的系统化流程。\n\n## Skill 要点总结\n\n**核心流程：**\n1. **确定测试范围** - 从 `git diff` 推断功能边界\n2. **读取事实来源** - 文档、代码、agent prompt、测试\n3. **制定最小测试计划** - 正常路径、边界条件、中断/清理\n4. **多轮执行** - 探索→执行→观察→清理\n5. **非交互模式运行** - 使用 `--print --work-dir /tmp/...`\n6. **检查产物** - `context.jsonl`, `wire.jsonl`, 后台任务等\n7. **问题探查** - 并行多路追踪根因\n\n**可用资源：**\n- `references/prompt-patterns.md` - 探索/执行/观察/复盘 prompt 模板\n- `scripts/inspect_session.py` - Session 产物分析工具\n\n---\n\n**你想让我使用这个 skill 来测试... [truncated]"}]}
+{"role": "_usage", "token_count": 17840}
+{"role": "_checkpoint", "id": 4}
+{"role": "user", "content": "请基于 README 和主要源代码目录，给出一份简短的探索清单"}
+{"role": "_checkpoint", "id": 5}
+{"role": "_usage", "token_count": 17574}
+{"role": "assistant", "content": [{"type": "think", "think": "用户想让我直接使用 `git diff main --name-only` 来查看当前分支相对于 main 分支的变更，然后基于这些变更进行冒烟测试。\n\n让我先执行这个命令看看有哪些文件变更。", "encrypted": null}], "tool_calls": [{"type": "function", "id": "tool_jOGB6wicU1PmefwL15U57RUT", "function": {"name": "Shell", "arguments": "{\"command\": \"git diff main --name-only && echo \\\"---\\\" && git diff main --stat\"}"}}]}
+{"role": "_usage", "token_count": 17650}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": ".agents/skills/example-task/SKILL.md\n.agents/skills/example-task/references/prompt-patterns.md\n.agents/skills/example-task/scripts/inspect_session.py\nCHANGELOG.md\nfeature-overview.md\ndocs/en/configuration/data-locations.md\ndocs/en/customization/wire-mode.md\ndocs/en/guides/interaction.md\ndocs/en/guides/sessions.md\ndocs/en/reference/keyboard.md\ndocs/en/reference/kimi-command.md\ndocs/en/reference/kimi-info.md\ndocs/en/reference/kimi-vis.md\ndocs/en/release-notes/changelog.md\ndoc... [truncated]"}], "tool_call_id": "tool_jOGB6wicU1PmefwL15U57RUT"}
+{"role": "_checkpoint", "id": 6}
+{"role": "_usage", "token_count": 20413}
+{"role": "assistant", "content": [{"type": "think", "think": "从 git diff 的输出来看，这是一个非常大的变更集，主要涉及以下几个核心功能：\n\n1. **后台任务系统 (background/)** - 全新模块\n   - `src/example_pkg/background/` - 后台任务管理核心\n   - `src/example_pkg/tools/background/` - 后台任务工具\n\n2. **通知系统 (notifications/)** - 全新模块\n   - `src/example_pkg/notifications/` - 通知管理\n\n3. **Shell UI 重构** - 大规模重构\n   - `src/example_pkg/ui/shell/` - Shell UI 组件重构\n   - 移除了大量旧代码（placeholders, echo 等）\n\n4. **Wire 协议更新**\n   - `src/example_pkg/wire/types.py` 和 `protocol.py`\n\n5. **动态注入 (dynamic_injection.py)**\n   - 更新\n\n6. **测试覆盖**\n   - 大量新增测试\n\n这是一个... [truncated]", "encrypted": null}, {"type": "text", "text": "根据 git diff 输出，这是一个大规模功能变更，主要涉及：\n\n1. **后台任务系统** (`src/example_pkg/background/`) - 全新模块\n2. **通知系统** (`src/example_pkg/notifications/`) - 全新模块  \n3. **后台任务工具** (`src/example_pkg/tools/background/`) - 新工具\n4. **Shell UI 重构** (`src/example_pkg/ui/shell/`) - 大量重构\n5. **Wire 协议更新** (`src/example_pkg/wire/types.py`)\n6. **动态注入更新** (`src/example_pkg/soul/dynamic_injection.py`)\n\n让我开始冒烟测试流程，首先读取事实来源："}], "tool_calls": [{"type": "function", "id": "tool_TB9CacXCzJ8B11tzzOneV7MK", "function": {"name": "ReadFile", "arguments": "{\"path\": \"feature-overview.md\"}"}}, {"type": "function", "id": "tool_7tKhkdZsBAFotRMTFs0BmgM6", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/background/manager.py\"}"}}, {"type": "function", "id": "tool_DR5VfRHgGe7WZ1dXKSA5Yowh", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/background/models.py\"}"}}, {"type": "function", "id": "tool_XZXYciY6FY2Tl4SHwuh7Elhl", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/tools/background/__init__.py\"}"}}]}
+{"role": "_usage", "token_count": 20959}
+{"role": "tool", "content": [{"type": "text", "text": "<system>353 lines read from file starting from line 1. End of file reached.</system>"}, {"type": "text", "text": "     1\t# 后台任务实现说明\n     2\t\n     3\t这份文档是给后续开发者快速理解当前 background task / notification 实现用的内部说明，不是用户文档。\n     4\t\n     5\t## 一句话结论\n     6\t\n     7\t当前实现已经不再把 background task completion 建模成 `dynamic injection` 的一个特例。\n     8\t\n     9\t现在的结构是：\n    10\t\n    11\t- `Shell(run_in_background=true)` 负责启动后台任务\n    12\t- `TaskList` / `TaskOutput` / `TaskStop` 负责最小控制面\n    13\t- `BackgroundTaskManager` 负责 task 生命周期\n    14\t- `NotificationManager` 负责通用 notification 基建\n    15\t- `task notification` 只是 notification 基建里的一个 type\n  ... [truncated]"}], "tool_call_id": "tool_TB9CacXCzJ8B11tzzOneV7MK"}
+{"role": "tool", "content": [{"type": "text", "text": "<system>358 lines read from file starting from line 1. End of file reached.</system>"}, {"type": "text", "text": "     1\tfrom __future__ import annotations\n     2\t\n     3\timport asyncio\n     4\timport os\n     5\timport signal\n     6\timport subprocess\n     7\timport sys\n     8\timport time\n     9\tfrom pathlib import Path\n    10\t\n    11\tfrom kaos.local import local_kaos\n    12\t\n    13\tfrom example_pkg.config import BackgroundConfig\n    14\tfrom example_pkg.notifications import NotificationEvent, NotificationManager\n    15\tfrom example_pkg.session import Session\n    16\tfrom example_pkg.utils.logging import logger\n    17\t\n    1... [truncated]"}], "tool_call_id": "tool_7tKhkdZsBAFotRMTFs0BmgM6"}
+{"role": "tool", "content": [{"type": "text", "text": "<system>89 lines read from file starting from line 1. End of file reached.</system>"}, {"type": "text", "text": "     1\tfrom __future__ import annotations\n     2\t\n     3\timport time\n     4\tfrom typing import Literal\n     5\t\n     6\tfrom pydantic import BaseModel, ConfigDict, Field\n     7\t\n     8\ttype TaskKind = Literal[\"bash\", \"agent\"]\n     9\ttype TaskStatus = Literal[\"created\", \"starting\", \"running\", \"completed\", \"failed\", \"killed\", \"lost\"]\n    10\ttype TaskOwnerRole = Literal[\"root\", \"fixed_subagent\", \"dynamic_subagent\"]\n    11\t\n    12\tTERMINAL_TASK_STATUSES: tuple[TaskStatus, ...] = (\"completed\", \"failed\"... [truncated]"}], "tool_call_id": "tool_DR5VfRHgGe7WZ1dXKSA5Yowh"}
+{"role": "tool", "content": [{"type": "text", "text": "<system>235 lines read from file starting from line 1. End of file reached.</system>"}, {"type": "text", "text": "     1\timport time\n     2\tfrom pathlib import Path\n     3\tfrom typing import override\n     4\t\n     5\tfrom kosong.tooling import CallableTool2, ToolError, ToolReturnValue\n     6\tfrom pydantic import BaseModel, Field\n     7\t\n     8\tfrom example_pkg.background import format_task, format_task_list, list_task_views\n     9\tfrom example_pkg.soul.agent import Runtime\n    10\tfrom example_pkg.soul.approval import Approval\n    11\tfrom example_pkg.tools.display import BackgroundTaskDisplayBlock\n    12\tfrom example_pkg.too... [truncated]"}], "tool_call_id": "tool_XZXYciY6FY2Tl4SHwuh7Elhl"}
+{"role": "_checkpoint", "id": 7}
+{"role": "_usage", "token_count": 31766}
+{"role": "assistant", "content": [{"type": "think", "think": "好的，我已经读取了关键的事实来源。现在让我继续读取其他重要文件来理解完整的功能边界：\n\n1. Shell 工具的后台模式支持\n2. Notification 系统\n3. Wire 协议更新\n4. KimiSoul 中的 notification 集成\n\n让我继续读取这些文件。", "encrypted": null}], "tool_calls": [{"type": "function", "id": "tool_4vAGVbvQFNnyAFHtAkgnKwUu", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/tools/shell/__init__.py\"}"}}, {"type": "function", "id": "tool_YRsRNEO743zdY5vBEYPYv5QJ", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/notifications/manager.py\"}"}}, {"type": "function", "id": "tool_Zi0gi1gBQijIF8lEEx1RiSPz", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/wire/types.py\"}"}}, {"type": "function", "id": "tool_SorRMdJIzuUdPESVPYIbDqQU", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/soul/kimisoul.py\", \"n_lines\": 150}"}}]}
+{"role": "_usage", "token_count": 31930}
+{"role": "tool", "content": [{"type": "text", "text": "<system>216 lines read from file starting from line 1. End of file reached.</system>"}, {"type": "text", "text": "     1\timport asyncio\n     2\tfrom collections.abc import Callable\n     3\tfrom pathlib import Path\n     4\tfrom typing import Self, override\n     5\t\n     6\timport kaos\n     7\tfrom kaos import AsyncReadable\n     8\tfrom kosong.tooling import CallableTool2, ToolReturnValue\n     9\tfrom pydantic import BaseModel, Field, model_validator\n    10\t\n    11\tfrom example_pkg.background import TaskView, format_task\n    12\tfrom example_pkg.soul.agent import Runtime\n    13\tfrom example_pkg.soul.approval import Approval\n  ... [truncated]"}], "tool_call_id": "tool_4vAGVbvQFNnyAFHtAkgnKwUu"}
+{"role": "tool", "content": [{"type": "text", "text": "<system>105 lines read from file starting from line 1. End of file reached.</system>"}, {"type": "text", "text": "     1\tfrom __future__ import annotations\n     2\t\n     3\timport time\n     4\timport uuid\n     5\tfrom pathlib import Path\n     6\t\n     7\tfrom example_pkg.config import NotificationConfig\n     8\t\n     9\tfrom .models import (\n    10\t    NotificationDelivery,\n    11\t    NotificationEvent,\n    12\t    NotificationSink,\n    13\t    NotificationSinkState,\n    14\t    NotificationView,\n    15\t)\n    16\tfrom .store import NotificationStore\n    17\t\n    18\t\n    19\tclass NotificationManager:\n    20\t    def __init__... [truncated]"}], "tool_call_id": "tool_YRsRNEO743zdY5vBEYPYv5QJ"}
+{"role": "tool", "content": [{"type": "text", "text": "<system>515 lines read from file starting from line 1. End of file reached.</system>"}, {"type": "text", "text": "     1\tfrom __future__ import annotations\n     2\t\n     3\timport asyncio\n     4\tfrom typing import Any, Literal, TypeGuard, cast\n     5\t\n     6\tfrom kosong.chat_provider import TokenUsage\n     7\tfrom kosong.message import (\n     8\t    AudioURLPart,\n     9\t    ContentPart,\n    10\t    ImageURLPart,\n    11\t    TextPart,\n    12\t    ThinkPart,\n    13\t    ToolCall,\n    14\t    ToolCallPart,\n    15\t    VideoURLPart,\n    16\t)\n    17\tfrom kosong.tooling import (\n    18\t    BriefDisplayBlock,\n    19\t    Dis... [truncated]"}], "tool_call_id": "tool_Zi0gi1gBQijIF8lEEx1RiSPz"}
+{"role": "tool", "content": [{"type": "text", "text": "<system>150 lines read from file starting from line 1.</system>"}, {"type": "text", "text": "     1\tfrom __future__ import annotations\n     2\t\n     3\timport asyncio\n     4\tfrom collections.abc import Awaitable, Callable, Sequence\n     5\tfrom contextlib import suppress\n     6\tfrom dataclasses import dataclass\n     7\tfrom functools import partial\n     8\tfrom pathlib import Path\n     9\tfrom typing import TYPE_CHECKING, Any, Literal\n    10\t\n    11\timport kosong\n    12\timport tenacity\n    13\tfrom kosong import StepResult\n    14\tfrom kosong.chat_provider import (\n    15\t    APIConnectionError... [truncated]"}], "tool_call_id": "tool_SorRMdJIzuUdPESVPYIbDqQU"}
+{"role": "_checkpoint", "id": 8}
+{"role": "_usage", "token_count": 41782}
+{"role": "assistant", "content": [{"type": "think", "think": "我已经获取了足够的背景信息。让我继续读取 KimiSoul 中 notification 相关的代码，以及相关的测试来理解完整的功能边界。", "encrypted": null}], "tool_calls": [{"type": "function", "id": "tool_okFY9oLifSxqJb8egNPac0MS", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/soul/kimisoul.py\", \"line_offset\": 200, \"n_lines\": 200}"}}, {"type": "function", "id": "tool_CcxVl6nzWr4TfMaivaLiZxsz", "function": {"name": "Grep", "arguments": "{\"pattern\": \"def _step|notification|claim|publish\", \"path\": \"src/example_pkg/soul/kimisoul.py\", \"output_mode\": \"content\", \"-n\": true}"}}]}
+{"role": "_usage", "token_count": 41903}
+{"role": "tool", "content": [{"type": "text", "text": "<system>200 lines read from file starting from line 200.</system>"}, {"type": "text", "text": "   200\t\n   201\t        def path_getter() -> Path | None:\n   202\t            return self.get_plan_file_path()\n   203\t\n   204\t        # WriteFile gets both checker and path_getter (for plan file auto-approve)\n   205\t        from example_pkg.tools.file.write import WriteFile\n   206\t\n   207\t        write_tool = self._agent.toolset.find(\"WriteFile\")\n   208\t        if isinstance(write_tool, WriteFile):\n   209\t            write_tool.bind_plan_mode(checker, path_getter)\n   210\t\n   211\t        # ExitPlanMod... [truncated]"}], "tool_call_id": "tool_okFY9oLifSxqJb8egNPac0MS"}
+{"role": "tool", "content": "26:from example_pkg.notifications import build_notification_message, extract_notification_ids\n147:            self._runtime.notifications.ack_ids(\"llm\", extract_notification_ids(context.history))\n626:    async def _step(self) -> StepOutcome | None:\n634:            notifications = self._runtime.notifications.claim_for_sink(\"llm\", limit=4)\n635:            if notifications:\n637:                    build_notification_message(view, self._runtime) for view in notifications\n640:                self._runti... [truncated]", "tool_call_id": "tool_CcxVl6nzWr4TfMaivaLiZxsz"}
+{"role": "_checkpoint", "id": 9}
+{"role": "_usage", "token_count": 44266}
+{"role": "assistant", "content": [{"type": "think", "think": "现在我对功能有了完整的理解。让我总结一下测试范围：\n\n**功能边界：**\n1. **后台任务系统** - 创建、监控、停止、输出获取\n2. **通知系统** - 发布、消费、去重、确认\n3. **集成点** - Shell 后台模式、TaskList/TaskOutput/TaskStop 工具、Wire 通知事件、LLM 通知消息\n\n**用户可感知的行为变化：**\n1. Shell 工具新增 `run_in_background` 和 `description` 参数\n2. 新增 TaskList/TaskOutput/TaskStop 工具\n3. 后台任务完成后自动发送通知到 LLM context 和 Wire\n4. 通知通过独立的 `<notification>` 消息进入 context\n5. Wire 协议新增 `Notification` 事件类型\n\n**测试计划：**\n1. **正常路径** - 启动后台任务，等待完成，验证通知\n2. **边界条件** - 超时处理、重复停止、无效 task_id\n3. **中断/清理** - 主动停止任务、任务丢失恢复\n\n让我开始制定... [truncated]", "encrypted": null}, {"type": "text", "text": "现在我对功能有了完整理解。让我制定测试计划：\n\n## 功能边界总结\n\n**主要变更：**\n1. **后台任务系统** (`background/`) - 全新模块，支持后台 bash 任务\n2. **通知系统** (`notifications/`) - 独立基建，支持多 sink (llm/wire/shell)\n3. **新工具** - `TaskList` / `TaskOutput` / `TaskStop`\n4. **Shell 工具更新** - 新增 `run_in_background` + `description` 参数\n5. **Wire 协议** - 新增 `Notification` 事件类型\n6. **KimiSoul 集成** - 自动 claim/ack notification，compaction 后恢复活跃任务快照\n\n**测试范围：**\n- 后台任务生命周期（创建→运行→完成→通知）\n- 任务控制工具（List/Output/Stop）\n- 通知系统（去重、claim/ack、多 sink）\n- 集成点（Shell 后台模式、Wire 事件、LLM ... [truncated]"}], "tool_calls": [{"type": "function", "id": "tool_y3SXWWQIUysddnYoklaWhUeE", "function": {"name": "SetTodoList", "arguments": "{\"todos\": [{\"title\": \"准备测试环境（创建隔离 work-dir）\", \"status\": \"in_progress\"}, {\"title\": \"探索轮：验证工具可用性和接口\", \"status\": \"pending\"}, {\"title\": \"执行轮1：正常路径 - 后台任务生命周期\", \"status\": \"pending\"}, {\"title\": \"执行轮2：边界条件 - 超时和停止\", \"status\": \"pending\"}, {\"title\": \"执行轮3：中断场景 - TaskStop 和恢复\", \"status\": \"pending\"}, {\"title\": \"观察轮：检查 session 产物\", \"status\": \"pending\"}, {\"title\": \"汇报结论\", \"status\": \"pending\"}]}"}}, {"type": "function", "id": "tool_BH2zd6kVzHhV4pIjKLSmrUeB", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"$(mktemp -d /tmp/kimi-smoke-XXXXXX)\\\"\\necho \\\"SMOKE_DIR=$SMOKE_DIR\\\"\\n# 验证 CLI 可运行\\nuv run python -m example_pkg.cli --help 2>&1 | head -20\"}"}}]}
+{"role": "_usage", "token_count": 44961}
+{"role": "tool", "content": "<system>Todo list updated</system>", "tool_call_id": "tool_y3SXWWQIUysddnYoklaWhUeE"}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "SMOKE_DIR=/tmp/kimi-smoke-a2i1xj\n                                                                                \n Usage: python -m example_pkg.cli [OPTIONS] COMMAND [ARGS]...                      \n                                                                                \n The Starting Point for Next-Gen Agents                                                     \n                                                                                \n╭─ Options ───────────────────────────────────────────────────... [truncated]"}], "tool_call_id": "tool_BH2zd6kVzHhV4pIjKLSmrUeB"}
+{"role": "_checkpoint", "id": 10}
+{"role": "_usage", "token_count": 45188}
+{"role": "assistant", "content": [{"type": "think", "think": "环境准备好了，现在让我开始第一轮探索测试，验证工具可用性。", "encrypted": null}], "tool_calls": [{"type": "function", "id": "tool_mj72EeaBIxBi3NOVwE3tjxBc", "function": {"name": "SetTodoList", "arguments": "{\"todos\": [{\"title\": \"准备测试环境（创建隔离 work-dir）\", \"status\": \"done\"}, {\"title\": \"探索轮：验证工具可用性和接口\", \"status\": \"in_progress\"}, {\"title\": \"执行轮1：正常路径 - 后台任务生命周期\", \"status\": \"pending\"}, {\"title\": \"执行轮2：边界条件 - 超时和停止\", \"status\": \"pending\"}, {\"title\": \"执行轮3：中断场景 - TaskStop 和恢复\", \"status\": \"pending\"}, {\"title\": \"观察轮：检查 session 产物\", \"status\": \"pending\"}, {\"title\": \"汇报结论\", \"status\": \"pending\"}]}"}}, {"type": "function", "id": "tool_ocohNUErNzzNQnYsibl670ms", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\n\\n# 探索轮：验证后台任务相关工具是否可用\\nuv run python -m example_pkg.cli \\\\\\n  --print \\\\\\n  --prompt \\\"请列出你当前所有可用的工具，特别关注：\\n1. 是否有 TaskList、TaskOutput、TaskStop 这三个工具？\\n2. Shell 工具是否支持 run_in_background 参数？\\n3. 简单描述这些工具的功能。\\\" \\\\\\n  --work-dir \\\"$SMOKE_DIR\\\" 2>&1\\necho \\\"exit_code=$?\\\"\", \"timeout\": 120}"}}]}
+{"role": "_usage", "token_count": 45508}
+{"role": "tool", "content": "<system>Todo list updated</system>", "tool_call_id": "tool_mj72EeaBIxBi3NOVwE3tjxBc"}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "请列出你当前所有可用的工具，特别关注：\n1. 是否有 TaskList、TaskOutput、TaskStop 这三个工具？\n2. Shell 工具是否支持 run_in_background 参数？\n3. 简单描述这些工具的功能。\nTurnBegin(\n    user_input='请列出你当前所有可用的工具，特别关注：\\n1. 是否有 \nTaskList、TaskOutput、TaskStop 这三个工具？\\n2. Shell 工具是否支持 \nrun_in_background 参数？\\n3. 简单描述这些工具的功能。'\n)\nStepBegin(n=1)\nThinkPart(\n    type='think',\n    think='用户询问我当前可用的工具列表，特别关注三个问题：\\n1. 是否有 \nTaskList、TaskOutput、TaskStop 这三个工具？\\n2. Shell 工具是否支持 \nrun_in_background 参数？\\n3. \n简单描述这些工具的功能。\\n\\n我需要查看我的工具列表。从 system \n提示中，我可以看到我有以下工具：\\n- Tas... [truncated]"}], "tool_call_id": "tool_ocohNUErNzzNQnYsibl670ms"}
+{"role": "_checkpoint", "id": 11}
+{"role": "_usage", "token_count": 46471}
+{"role": "assistant", "content": [{"type": "think", "think": "探索轮成功，工具都已正确加载。现在进入执行轮1：测试正常路径 - 启动后台任务，等待完成，验证通知。", "encrypted": null}, {"type": "text", "text": "探索轮成功！工具都已正确加载。现在执行第一轮测试："}], "tool_calls": [{"type": "function", "id": "tool_bpOwCgVz6wYah52SnaJB39ZW", "function": {"name": "SetTodoList", "arguments": "{\"todos\": [{\"title\": \"准备测试环境（创建隔离 work-dir）\", \"status\": \"done\"}, {\"title\": \"探索轮：验证工具可用性和接口\", \"status\": \"done\"}, {\"title\": \"执行轮1：正常路径 - 后台任务生命周期\", \"status\": \"in_progress\"}, {\"title\": \"执行轮2：边界条件 - 超时和停止\", \"status\": \"pending\"}, {\"title\": \"执行轮3：中断场景 - TaskStop 和恢复\", \"status\": \"pending\"}, {\"title\": \"观察轮：检查 session 产物\", \"status\": \"pending\"}, {\"title\": \"汇报结论\", \"status\": \"pending\"}]}"}}, {"type": "function", "id": "tool_HejoTo6Izmlets9y9hN9u1pZ", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\n\\n# 执行轮1：正常路径 - 启动一个短生命周期的后台任务，验证生命周期完整\\nuv run python -m example_pkg.cli \\\\\\n  --print \\\\\\n  --prompt \\\"请执行以下测试：\\n\\n1. 使用 Shell 工具启动一个后台任务：\\n   - 命令: echo 'hello from background' && sleep 2 && echo 'task done'\\n   - run_in_background: true\\n   - description: '测试后台任务生命周期'\\n   - timeout: 30\\n\\n2. 记录返回的 task_id\\n\\n3. 使用 TaskList 查看当前活跃任务\\n\\n4. 使用 TaskOutput 获取任务输出（block=true, timeout=10）\\n\\n请报告：task_id、任务状态、输出内容。\\\" \\\\\\n  --work-dir \\\"$SMOKE_DIR\\\" 2>&... [truncated]"}}]}
+{"role": "_usage", "token_count": 46902}
+{"role": "tool", "content": "<system>Todo list updated</system>", "tool_call_id": "tool_bpOwCgVz6wYah52SnaJB39ZW"}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "请执行以下测试：\n\n1. 使用 Shell 工具启动一个后台任务：\n   - 命令: echo 'hello from background' && sleep 2 && echo 'task done'\n   - run_in_background: true\n   - description: '测试后台任务生命周期'\n   - timeout: 30\n\n2. 记录返回的 task_id\n\n3. 使用 TaskList 查看当前活跃任务\n\n4. 使用 TaskOutput 获取任务输出（block=true, timeout=10）\n\n请报告：task_id、任务状态、输出内容。\nTurnBegin(\n    user_input=\"请执行以下测试：\\n\\n1. 使用 Shell 工具启动一个后台任务：\\n   - \n命令: echo 'hello from background' && sleep 2 && echo 'task done'\\n   - \nrun_in_background: true\\n   - description: '测试后台任务生命周期'\\n   - t... [truncated]"}], "tool_call_id": "tool_HejoTo6Izmlets9y9hN9u1pZ"}
+{"role": "_checkpoint", "id": 12}
+{"role": "_usage", "token_count": 48881}
+{"role": "assistant", "content": [{"type": "think", "think": "第一轮测试成功！关键验证点：\n1. ✅ Shell 后台任务启动成功，返回 task_id\n2. ✅ TaskList 正确工作\n3. ✅ TaskOutput 正确工作，block=true 等待完成\n4. ✅ Notification 事件正确发送（Wire 中可见 Notification 事件）\n\n现在进行第二轮：边界条件 - 测试超时和停止功能。", "encrypted": null}, {"type": "text", "text": "第一轮成功！所有核心功能正常工作。现在测试边界条件："}], "tool_calls": [{"type": "function", "id": "tool_3tueNNJt54oG2X47QK4PLnTj", "function": {"name": "SetTodoList", "arguments": "{\"todos\": [{\"title\": \"准备测试环境（创建隔离 work-dir）\", \"status\": \"done\"}, {\"title\": \"探索轮：验证工具可用性和接口\", \"status\": \"done\"}, {\"title\": \"执行轮1：正常路径 - 后台任务生命周期\", \"status\": \"done\"}, {\"title\": \"执行轮2：边界条件 - 超时和停止\", \"status\": \"in_progress\"}, {\"title\": \"执行轮3：中断场景 - TaskStop 和恢复\", \"status\": \"pending\"}, {\"title\": \"观察轮：检查 session 产物\", \"status\": \"pending\"}, {\"title\": \"汇报结论\", \"status\": \"pending\"}]}"}}, {"type": "function", "id": "tool_NT90qPui3vOOBqIjmTgvYe9Q", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\n\\n# 执行轮2：边界条件 - 超时处理和停止\\nuv run python -m example_pkg.cli \\\\\\n  --print \\\\\\n  --prompt \\\"请执行以下边界条件测试：\\n\\n1. 启动一个长时间运行的后台任务（会被停止）：\\n   - 命令: for i in 1 2 3 4 5; do echo \\\\\\\"line \\\\$i\\\\\\\"; sleep 5; done\\n   - run_in_background: true\\n   - description: '测试停止功能'\\n   - timeout: 60\\n\\n2. 使用 TaskList 确认任务在运行中\\n\\n3. 等待 3 秒后，使用 TaskStop 停止该任务\\n\\n4. 使用 TaskOutput 获取任务最终状态和输出\\n\\n请报告：task_id、停止前后的状态、输出内容、是否有正确通知。\\\" \\\\\\n  --work-dir \\\"$SMOKE_DIR\\\" 2>&1\\necho \\\"... [truncated]"}}]}
+{"role": "_usage", "token_count": 49372}
+{"role": "tool", "content": "<system>Todo list updated</system>", "tool_call_id": "tool_3tueNNJt54oG2X47QK4PLnTj"}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "请执行以下边界条件测试：\n\n1. 启动一个长时间运行的后台任务（会被停止）：\n   - 命令: for i in 1 2 3 4 5; do echo \"line $i\"; sleep 5; done\n   - run_in_background: true\n   - description: '测试停止功能'\n   - timeout: 60\n\n2. 使用 TaskList 确认任务在运行中\n\n3. 等待 3 秒后，使用 TaskStop 停止该任务\n\n4. 使用 TaskOutput 获取任务最终状态和输出\n\n请报告：task_id、停止前后的状态、输出内容、是否有正确通知。\nTurnBegin(\n    user_input='请执行以下边界条件测试：\\n\\n1. \n启动一个长时间运行的后台任务（会被停止）：\\n   - 命令: for i in 1 2 3 4 5; do \necho \"line $i\"; sleep 5; done\\n   - run_in_background: true\\n   - description: \n\\'测试停止功能\\'\\n   - timeou... [truncated]"}], "tool_call_id": "tool_NT90qPui3vOOBqIjmTgvYe9Q"}
+{"role": "_checkpoint", "id": 13}
+{"role": "_usage", "token_count": 52396}
+{"role": "assistant", "content": [{"type": "think", "think": "第二轮也成功！测试了停止功能，验证了：\n1. ✅ TaskStop 成功停止任务\n2. ✅ 通知正确发送 (task.killed)\n3. ✅ exit_code 正确 (-15 = SIGTERM)\n4. ✅ 输出正确捕获\n\n现在进行第三轮测试：测试超时处理。", "encrypted": null}, {"type": "text", "text": "第二轮成功！停止功能完全正常。现在测试超时场景："}], "tool_calls": [{"type": "function", "id": "tool_TS5JUSZELJoTVcos6rp90ZUT", "function": {"name": "SetTodoList", "arguments": "{\"todos\": [{\"title\": \"准备测试环境（创建隔离 work-dir）\", \"status\": \"done\"}, {\"title\": \"探索轮：验证工具可用性和接口\", \"status\": \"done\"}, {\"title\": \"执行轮1：正常路径 - 后台任务生命周期\", \"status\": \"done\"}, {\"title\": \"执行轮2：边界条件 - 超时和停止\", \"status\": \"done\"}, {\"title\": \"执行轮3：超时场景测试\", \"status\": \"in_progress\"}, {\"title\": \"观察轮：检查 session 产物\", \"status\": \"pending\"}, {\"title\": \"汇报结论\", \"status\": \"pending\"}]}"}}, {"type": "function", "id": "tool_J3cQ5m3qyTep0zNLWhZR3OGg", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\n\\n# 执行轮3：测试超时处理\\nuv run python -m example_pkg.cli \\\\\\n  --print \\\\\\n  --prompt \\\"请测试后台任务超时功能：\\n\\n1. 启动一个会超时的后台任务：\\n   - 命令: sleep 300\\n   - run_in_background: true\\n   - description: '测试超时处理'\\n   - timeout: 3  （设置为3秒，确保会超时）\\n\\n2. 使用 TaskOutput 阻塞等待任务结束（block=true, timeout=15）\\n\\n3. 检查任务最终状态是否为 timeout\\n\\n请报告：task_id、最终状态、exit_code、是否有 timeout 通知。\\\" \\\\\\n  --work-dir \\\"$SMOKE_DIR\\\" 2>&1\\necho \\\"exit_code=$?\\\"\", \"timeout\": 180}"}}]}
+{"role": "_usage", "token_count": 52834}
+{"role": "tool", "content": "<system>Todo list updated</system>", "tool_call_id": "tool_TS5JUSZELJoTVcos6rp90ZUT"}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "请测试后台任务超时功能：\n\n1. 启动一个会超时的后台任务：\n   - 命令: sleep 300\n   - run_in_background: true\n   - description: '测试超时处理'\n   - timeout: 3  （设置为3秒，确保会超时）\n\n2. 使用 TaskOutput 阻塞等待任务结束（block=true, timeout=15）\n\n3. 检查任务最终状态是否为 timeout\n\n请报告：task_id、最终状态、exit_code、是否有 timeout 通知。\nTurnBegin(\n    user_input=\"请测试后台任务超时功能：\\n\\n1. 启动一个会超时的后台任务：\\n   - \n命令: sleep 300\\n   - run_in_background: true\\n   - description: \n'测试超时处理'\\n   - timeout: 3  （设置为3秒，确保会超时）\\n\\n2. 使用 TaskOutput\n阻塞等待任务结束（block=true, timeout=15）\\n\\n3. 检查任务最终状态是否为 \n... [truncated]"}], "tool_call_id": "tool_J3cQ5m3qyTep0zNLWhZR3OGg"}
+{"role": "_checkpoint", "id": 14}
+{"role": "_usage", "token_count": 54774}
+{"role": "assistant", "content": [{"type": "think", "think": "第三轮也成功！测试了超时处理：\n1. ✅ 任务正确超时\n2. ✅ 状态为 failed，timed_out=true\n3. ✅ 通知正确发送 (task.timed_out)\n4. ✅ exit_code 正确 (-15)\n\n现在进入观察轮，检查 session 产物，验证 notification 是否正确写入 context 等。", "encrypted": null}, {"type": "text", "text": "第三轮成功！超时处理完全正常。现在进入观察轮，检查 session 产物："}], "tool_calls": [{"type": "function", "id": "tool_n7Bz3OSHPlOZnL3ghEe8Rciw", "function": {"name": "SetTodoList", "arguments": "{\"todos\": [{\"title\": \"准备测试环境（创建隔离 work-dir）\", \"status\": \"done\"}, {\"title\": \"探索轮：验证工具可用性和接口\", \"status\": \"done\"}, {\"title\": \"执行轮1：正常路径 - 后台任务生命周期\", \"status\": \"done\"}, {\"title\": \"执行轮2：边界条件 - 超时和停止\", \"status\": \"done\"}, {\"title\": \"执行轮3：超时场景测试\", \"status\": \"done\"}, {\"title\": \"观察轮：检查 session 产物\", \"status\": \"in_progress\"}, {\"title\": \"汇报结论\", \"status\": \"pending\"}]}"}}, {"type": "function", "id": "tool_3s3qLBo5c7kA1pqbpX36YbVo", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\n\\n# 查找 session 目录\\necho \\\"=== Session 定位 ===\\\"\\nSESSION_ID=$(echo -n \\\"$SMOKE_DIR\\\" | md5)\\necho \\\"Work dir: $SMOKE_DIR\\\"\\necho \\\"Session ID (md5): $SESSION_ID\\\"\\nSESSION_DIR=\\\"$HOME/.kimi/sessions/$SESSION_ID\\\"\\necho \\\"Session dir: $SESSION_DIR\\\"\\n\\n# 检查 session 目录是否存在\\nif [ -d \\\"$SESSION_DIR\\\" ]; then\\n    echo \\\"Session exists: YES\\\"\\n    ls -la \\\"$SESSION_DIR\\\"\\nelse\\n    echo \\\"Session exists: NO\\\"\\n    # 尝试找到最新的 session\\n    echo \\\"Finding... [truncated]"}}]}
+{"role": "_usage", "token_count": 55220}
+{"role": "tool", "content": "<system>Todo list updated</system>", "tool_call_id": "tool_n7Bz3OSHPlOZnL3ghEe8Rciw"}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "=== Session 定位 ===\nWork dir: /tmp/kimi-smoke-a2i1xj\nSession ID (md5): d1c3750c0cc0757aeac04ad5a7d6b8cf\nSession dir: /Users/example/proj/.kimi/sessions/d1c3750c0cc0757aeac04ad5a7d6b8cf\nSession exists: YES\ntotal 0\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:59 .\ndrwxr-xr-x@ 1722 user      staff  55104  3月 17 12:58 ..\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:58 0e1d3b94-dae2-4dfb-b36d-717397f4d2f6\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:59 228b54e2-5b5d-4675-94f2-ec56e42cdbae\nd... [truncated]"}], "tool_call_id": "tool_3s3qLBo5c7kA1pqbpX36YbVo"}
+{"role": "_checkpoint", "id": 15}
+{"role": "_usage", "token_count": 55629}
+{"role": "assistant", "content": [{"type": "think", "think": "找到了 session 目录，下面有多个子目录（每次运行 CLI 会创建一个新的子 session）。让我使用 inspect_session.py 来检查最新的 session。", "encrypted": null}], "tool_calls": [{"type": "function", "id": "tool_4Zcuo5i4xl2NEz1Y1EZ1IvSn", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\n\\n# 使用 inspect_session.py 检查最新的 session\\necho \\\"=== 使用 inspect_session.py 检查 ===\\\"\\nuv run python .agents/skills/example-task/scripts/inspect_session.py --share-dir ~/.kimi 2>&1\"}"}}]}
+{"role": "_usage", "token_count": 55748}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "=== 使用 inspect_session.py 检查 ===\nSession dir: /Users/example/proj/.kimi/sessions/6a7967e2a97cd71a62b8375c5ae461ba/ef00f9f9-a470-4e50-b279-59429da67d27\n\n== Files ==\ncontext.jsonl (209039 bytes)\nstate.json (188 bytes)\nwire.jsonl (197310 bytes)\n\n== Context ==\n/Users/example/proj/.kimi/sessions/6a7967e2a97cd71a62b8375c5ae461ba/ef00f9f9-a470-4e50-b279-59429da67d27/context.jsonl\nrecords: 85\nroles: _checkpoint=16, _system_prompt=1, _usage=27, assistant=13, tool=26, user=2\n[74] role=assistant | tools=SetTodoLis... [truncated]"}], "tool_call_id": "tool_4Zcuo5i4xl2NEz1Y1EZ1IvSn"}
+{"role": "_checkpoint", "id": 16}
+{"role": "_usage", "token_count": 56937}
+{"role": "assistant", "content": [{"type": "think", "think": "这个 session 不是我刚才测试的那个。让我直接检查正确的 session 目录（d1c3750c0cc0757aeac04ad5a7d6b8cf），里面有多个子目录，对应三次测试运行。", "encrypted": null}], "tool_calls": [{"type": "function", "id": "tool_DmwmxRwjKGDXt1PTAyVbYAdM", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\nSESSION_ID=$(echo -n \\\"$SMOKE_DIR\\\" | md5)\\nSESSION_DIR=\\\"$HOME/.kimi/sessions/$SESSION_ID\\\"\\n\\necho \\\"=== 检查正确的 session 目录 ===\\\"\\necho \\\"Session dir: $SESSION_DIR\\\"\\necho \\\"\\\"\\necho \\\"=== 子目录列表 ===\\\"\\nls -la \\\"$SESSION_DIR\\\"\\n\\n# 检查每个子目录的 wire.jsonl 中的 Notification 事件\\necho \\\"\\\"\\necho \\\"=== 检查 Notification 事件 ===\\\"\\nfor subdir in \\\"$SESSION_DIR\\\"/*; do\\n    if [ -d \\\"$subdir\\\" ] && [ -f \\\"$subdir/wire.jsonl\\\" ]; then\\n        subname=$(basename... [truncated]"}}]}
+{"role": "_usage", "token_count": 57235}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "=== 检查正确的 session 目录 ===\nSession dir: /Users/example/proj/.kimi/sessions/d1c3750c0cc0757aeac04ad5a7d6b8cf\n\n=== 子目录列表 ===\ntotal 0\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:59 .\ndrwxr-xr-x@ 1722 user      staff  55104  3月 17 12:58 ..\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:58 0e1d3b94-dae2-4dfb-b36d-717397f4d2f6\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:59 228b54e2-5b5d-4675-94f2-ec56e42cdbae\ndrwxr-xr-x@    6 user      staff    192  3月 17 13:00 be8228d5-1c57-43dc-9f23-9e7dba2... [truncated]"}], "tool_call_id": "tool_DmwmxRwjKGDXt1PTAyVbYAdM"}
+{"role": "_checkpoint", "id": 17}
+{"role": "_usage", "token_count": 57722}
+{"role": "assistant", "content": [{"type": "think", "think": "奇怪，没有找到 Notification 事件。可能 Notification 事件格式不一样，让我直接查看 wire.jsonl 文件内容，搜索 notification。", "encrypted": null}], "tool_calls": [{"type": "function", "id": "tool_97R6Gz8LI01cAOsQDuv9nbwm", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\nSESSION_ID=$(echo -n \\\"$SMOKE_DIR\\\" | md5)\\nSESSION_DIR=\\\"$HOME/.kimi/sessions/$SESSION_ID\\\"\\n\\n# 直接查看每个子目录的 wire.jsonl 内容\\necho \\\"=== 查看 wire.jsonl 中的通知相关内容 ===\\\"\\nfor subdir in \\\"$SESSION_DIR\\\"/*; do\\n    if [ -d \\\"$subdir\\\" ] && [ -f \\\"$subdir/wire.jsonl\\\" ]; then\\n        subname=$(basename \\\"$subdir\\\")\\n        echo \\\"\\\"\\n        echo \\\"--- Sub-session: $subname ---\\\"\\n        # 查找包含 notification 的行\\n        grep -i \\\"notification\\\\|task\\\\.... [truncated]"}}]}
+{"role": "_usage", "token_count": 57964}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "=== 查看 wire.jsonl 中的通知相关内容 ===\n\n--- Sub-session: 0e1d3b94-dae2-4dfb-b36d-717397f4d2f6 ---\n{\"timestamp\": 1773723525.133148, \"message\": {\"type\": \"ToolResult\", \"payload\": {\"tool_call_id\": \"tool_KviOIHcT5WgvrVhhHtEzsDNR\", \"return_value\": {\"is_error\": false, \"output\": \"task_id: b83rhswvs\\nkind: bash\\nstatus: starting\\ndescription: 测试后台任务生命周期\\ncommand: echo 'hello from background' && sleep 2 && echo 'task done'\\nautomatic_notification: true\\nnext_step: You will be automatically notified when it comple... [truncated]"}], "tool_call_id": "tool_97R6Gz8LI01cAOsQDuv9nbwm"}
+{"role": "_checkpoint", "id": 18}
+{"role": "_usage", "token_count": 60288}
+{"role": "assistant", "content": [{"type": "think", "think": "我找到了所有的 Notification 事件：\n1. `0e1d3b94-dae2-4dfb-b36d-717397f4d2f6` - task.completed (b83rhswvs)\n2. `228b54e2-5b5d-4675-94f2-ec56e42cdbae` - task.killed (bp6amsrcu)\n3. `be8228d5-1c57-43dc-9f23-9e7dba209a1a` - task.timed_out (b4c3d8fta)\n\n现在让我检查 context.jsonl 中是否有 notification 消息，以及 task 目录结构。", "encrypted": null}, {"type": "text", "text": "找到了所有 Notification 事件！现在检查 context.jsonl 和 task 目录："}], "tool_calls": [{"type": "function", "id": "tool_74k2gxGVF3RSOhTaEhnnvPzk", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\nSESSION_ID=$(echo -n \\\"$SMOKE_DIR\\\" | md5)\\nSESSION_DIR=\\\"$HOME/.kimi/sessions/$SESSION_ID\\\"\\n\\n# 检查 context.jsonl 中的 notification 消息\\necho \\\"=== 检查 context.jsonl 中的 notification 消息 ===\\\"\\nfor subdir in \\\"$SESSION_DIR\\\"/*; do\\n    if [ -d \\\"$subdir\\\" ] && [ -f \\\"$subdir/context.jsonl\\\" ]; then\\n        subname=$(basename \\\"$subdir\\\")\\n        count=$(grep -c '\\\"role\\\":\\\"notification\\\"' \\\"$subdir/context.jsonl\\\" 2>/dev/null || echo \\\"0\\\")\\n      ... [truncated]"}}]}
+{"role": "_usage", "token_count": 60769}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "=== 检查 context.jsonl 中的 notification 消息 ===\nSub-session 0e1d3b94-dae2-4dfb-b36d-717397f4d2f6: notification messages = 0\n0\n/bin/bash: line 11: [: 0\n0: integer expression expected\nSub-session 228b54e2-5b5d-4675-94f2-ec56e42cdbae: notification messages = 0\n0\n/bin/bash: line 11: [: 0\n0: integer expression expected\nSub-session be8228d5-1c57-43dc-9f23-9e7dba209a1a: notification messages = 0\n0\n/bin/bash: line 11: [: 0\n0: integer expression expected\nSub-session ea3920e8-2a4b-4e38-be51-c500aab582ab: noti... [truncated]"}], "tool_call_id": "tool_74k2gxGVF3RSOhTaEhnnvPzk"}
+{"role": "_checkpoint", "id": 19}
+{"role": "_usage", "token_count": 61388}
+{"role": "assistant", "content": [{"type": "think", "think": "找到了 task 目录。现在让我检查 task 目录的内容，以及 notification 持久化目录。", "encrypted": null}], "tool_calls": [{"type": "function", "id": "tool_doClKbqjLQAuMtimAxF3mufI", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\nSESSION_ID=$(echo -n \\\"$SMOKE_DIR\\\" | md5)\\nSESSION_DIR=\\\"$HOME/.kimi/sessions/$SESSION_ID\\\"\\n\\n# 检查 task 目录内容\\necho \\\"=== 检查第一个 task 的目录结构 ===\\\"\\nTASK_DIR=\\\"$SESSION_DIR/0e1d3b94-dae2-4dfb-b36d-717397f4d2f6/tasks/b83rhswvs\\\"\\nls -la \\\"$TASK_DIR\\\"\\n\\necho \\\"\\\"\\necho \\\"=== spec.json ===\\\"\\ncat \\\"$TASK_DIR/spec.json\\\"\\n\\necho \\\"\\\"\\necho \\\"=== runtime.json ===\\\"\\ncat \\\"$TASK_DIR/runtime.json\\\"\\n\\necho \\\"\\\"\\necho \\\"=== output.log ===\\\"\\ncat \\\"$TASK_... [truncated]"}}]}
+{"role": "_usage", "token_count": 61699}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "=== 检查第一个 task 的目录结构 ===\ntotal 40\ndrwxr-xr-x@ 7 user      staff  224  3月 17 12:58 .\ndrwxr-xr-x@ 3 user      staff   96  3月 17 12:58 ..\n-rw-------@ 1 user      staff   72  3月 17 12:58 consumer.json\n-rw-------@ 1 user      staff   72  3月 17 12:58 control.json\n-rw-r--r--@ 1 user      staff   32  3月 17 12:58 output.log\n-rw-------@ 1 user      staff  331  3月 17 12:58 runtime.json\n-rw-------@ 1 user      staff  481  3月 17 12:58 spec.json\n\n=== spec.json ===\n{\n  \"version\": 1,\n  \"id\": \"b83rhswvs\",\n  \"kin... [truncated]"}], "tool_call_id": "tool_doClKbqjLQAuMtimAxF3mufI"}
+{"role": "_checkpoint", "id": 20}
+{"role": "_usage", "token_count": 62379}
+{"role": "assistant", "content": [{"type": "think", "think": "所有验证都通过了：\n1. task 目录结构正确\n2. spec.json 包含正确的 task 信息\n3. runtime.json 包含正确的状态信息\n4. output.log 包含正确的输出\n5. notification 持久化正确\n\n现在让我检查 notification 目录的内容。", "encrypted": null}], "tool_calls": [{"type": "function", "id": "tool_7SICneqn0eGcgCADXOFuo2yj", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\nSESSION_ID=$(echo -n \\\"$SMOKE_DIR\\\" | md5)\\nSESSION_DIR=\\\"$HOME/.kimi/sessions/$SESSION_ID\\\"\\n\\n# 检查 notification 目录内容\\necho \\\"=== 检查 notification 持久化内容 ===\\\"\\nNOTIF_DIR=\\\"$SESSION_DIR/0e1d3b94-dae2-4dfb-b36d-717397f4d2f6/notifications/n495ae5fb\\\"\\necho \\\"Notification: n495ae5fb (task.completed)\\\"\\nls -la \\\"$NOTIF_DIR\\\"\\n\\necho \\\"\\\"\\necho \\\"=== event.json ===\\\"\\ncat \\\"$NOTIF_DIR/event.json\\\" | head -30\\n\\necho \\\"\\\"\\necho \\\"=== delivery.json ===\\... [truncated]"}}]}
+{"role": "_usage", "token_count": 62644}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "=== 检查 notification 持久化内容 ===\nNotification: n495ae5fb (task.completed)\ntotal 16\ndrwxr-xr-x@ 4 user      staff  128  3月 17 12:58 .\ndrwxr-xr-x@ 3 user      staff   96  3月 17 12:58 ..\n-rw-------@ 1 user      staff  332  3月 17 12:58 delivery.json\n-rw-------@ 1 user      staff  790  3月 17 12:58 event.json\n\n=== event.json ===\n{\n  \"version\": 1,\n  \"id\": \"n495ae5fb\",\n  \"category\": \"task\",\n  \"type\": \"task.completed\",\n  \"source_kind\": \"background_task\",\n  \"source_id\": \"b83rhswvs\",\n  \"title\": \"Background ta... [truncated]"}], "tool_call_id": "tool_7SICneqn0eGcgCADXOFuo2yj"}
+{"role": "_checkpoint", "id": 21}
+{"role": "_usage", "token_count": 63162}
+{"role": "assistant", "content": [{"type": "think", "think": "所有验证都通过了！现在让我总结冒烟测试的结果。", "encrypted": null}, {"type": "text", "text": "所有验证完成！现在更新 todo 并汇报结论："}], "tool_calls": [{"type": "function", "id": "tool_CcJKFj7faabalZQ9X1gPrTbr", "function": {"name": "SetTodoList", "arguments": "{\"todos\": [{\"title\": \"准备测试环境（创建隔离 work-dir）\", \"status\": \"done\"}, {\"title\": \"探索轮：验证工具可用性和接口\", \"status\": \"done\"}, {\"title\": \"执行轮1：正常路径 - 后台任务生命周期\", \"status\": \"done\"}, {\"title\": \"执行轮2：边界条件 - 超时和停止\", \"status\": \"done\"}, {\"title\": \"执行轮3：超时场景测试\", \"status\": \"done\"}, {\"title\": \"观察轮：检查 session 产物\", \"status\": \"done\"}, {\"title\": \"汇报结论\", \"status\": \"done\"}]}"}}]}
+{"role": "_usage", "token_count": 63336}
+{"role": "tool", "content": "<system>Todo list updated</system>", "tool_call_id": "tool_CcJKFj7faabalZQ9X1gPrTbr"}
+{"role": "_checkpoint", "id": 22}
+{"role": "_usage", "token_count": 63363}
+{"role": "assistant", "content": [{"type": "think", "think": "所有测试完成。现在整理完整的测试报告。", "encrypted": null}, {"type": "text", "text": "---\n\n## 冒烟测试报告\n\n### 测试范围\n**后台任务系统 + 通知系统** - 本次变更新增的核心功能\n\n### 已确认的行为 ✅\n\n| 功能 | 验证结果 |\n|------|----------|\n| **Shell 后台模式** | `run_in_background=true` + `description` 参数正常工作 |\n| **TaskList** | 正确列出活跃/全部任务，显示 task_id/kind/status/description |\n| **TaskOutput** | `block=true/false` 模式工作正常，返回完整任务状态和输出 |\n| **TaskStop** | 成功发送 SIGTERM 停止任务，支持自定义 reason |\n| **任务超时** | timeout 参数正确终止超时任务，exit_code=-15 |\n| **Wire Notification** | `Notification` 事件正确发送，包含完整 payload |\n| **Notification 持久化** | event.json + d... [truncated]"}]}
+{"role": "_usage", "token_count": 64014}
+{"role": "_checkpoint", "id": 23}
+{"role": "user", "content": "source /Users/example/proj/example-project/.venv/bin/activate"}
+{"role": "_checkpoint", "id": 24}
+{"role": "_usage", "token_count": 62754}
+{"role": "assistant", "content": [{"type": "think", "think": "用户只是在执行激活虚拟环境的命令，这是一个 shell 命令。我应该执行它并确认环境已激活。", "encrypted": null}], "tool_calls": [{"type": "function", "id": "tool_oKHd9KBRZQ3pT7x7XgOWhcMJ", "function": {"name": "Shell", "arguments": "{\"command\": \"source /Users/example/proj/example-project/.venv/bin/activate && echo \\\"Virtual environment activated\\\" && which python && python --version\"}"}}]}
+{"role": "_usage", "token_count": 62828}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "Virtual environment activated\n/Users/example/proj/example-project/.venv/bin/python\nPython 3.14.2\n"}], "tool_call_id": "tool_oKHd9KBRZQ3pT7x7XgOWhcMJ"}
+{"role": "_checkpoint", "id": 25}
diff --git a/packages/migration-legacy/test/fixtures/large-100msgs/state.json b/packages/migration-legacy/test/fixtures/large-100msgs/state.json
new file mode 100644
index 000000000..da47fd690
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/large-100msgs/state.json
@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "approval": {
+    "yolo": false,
+    "auto_approve_actions": [
+      "run command"
+    ]
+  },
+  "dynamic_subagents": [],
+  "additional_dirs": [],
+  "plan_mode": false
+}
\ No newline at end of file
diff --git a/packages/migration-legacy/test/fixtures/large-100msgs/wire.jsonl b/packages/migration-legacy/test/fixtures/large-100msgs/wire.jsonl
new file mode 100644
index 000000000..57b952325
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/large-100msgs/wire.jsonl
@@ -0,0 +1,130 @@
+{"type": "metadata", "protocol_version": "1.4"}
+{"timestamp": 1773723366.1124082, "message": {"type": "TurnBegin", "payload": {"user_input": "请帮我探索一下当前这个仓库的整体结构，了解它的主要模块和功能。看完之后请写一份简短的小报告，列出你认为最重要的几个模块、它们的职责，以及彼此之间的依赖关系。报告控制在一页之内，便于团队成员快速了解项目。"}}}
+{"timestamp": 1773723366.114381, "message": {"type": "StepBegin", "payload": {"n": 1}}}
+{"timestamp": 1773723371.727005, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "用户想要我读取 example-task skill 的 SKILL.md 文件，但他们已经在 prompt 中提供了完整的 skill 内容。不过我需要了解这个 skill 的更多细节，特别是 references/prompt-patterns.md 文件。\n\n用户似乎在向我介绍这个 skill，让我熟悉它的用法。我应该先检查一下这个 skill 目录的结构，看看是否有其他有用的资源文件。\n\n让我先了解一下这个 skill 的完整结构，以便以后需要时可以使用它。", "encrypted": null}}}
+{"timestamp": 1773723372.692799, "message": {"type": "ContentPart", "payload": {"type": "text", "text": "我来熟悉一下 `example-task` skill 的完整结构和资源。"}}}
+{"timestamp": 1773723372.700783, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_3mtoDjRlqenM0GDSjv9xRzLS", "function": {"name": "Glob", "arguments": "{\"pattern\": \".agents/skills/example-task/**/*\"}"}, "extras": null}}}
+{"timestamp": 1773723372.701451, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.047916412353515625, "context_tokens": 12561, "max_context_tokens": 262144, "token_usage": {"input_other": 11025, "output": 133, "input_cache_read": 1536, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0001", "plan_mode": false}}}
+{"timestamp": 1773723372.7029371, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_3mtoDjRlqenM0GDSjv9xRzLS", "return_value": {"is_error": false, "output": ".agents/skills/example-task/SKILL.md\n.agents/skills/example-task/references\n.agents/skills/example-task/references/prompt-patterns.md\n.agents/skills/example-task/scripts\n.agents/skills/example-task/scripts/inspect_session.py", "message": "Found 5 matches for pattern `.agents/skills/example-task/**/*`.", "display": [], "extras": null}}}}
+{"timestamp": 1773723372.704417, "message": {"type": "StepBegin", "payload": {"n": 2}}}
+{"timestamp": 1773723375.024239, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "让我读取 references/prompt-patterns.md 和 scripts/inspect_session.py 来了解完整的 skill 资源。", "encrypted": null}}}
+{"timestamp": 1773723375.661128, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_nqkbedqxXK1aX9zAWWNEhzmM", "function": {"name": "ReadFile", "arguments": "{\"path\": \".agents/skills/example-task/references/prompt-patterns.md\"}"}, "extras": null}}}
+{"timestamp": 1773723375.668145, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_300OLXjS5RZxFz9LvWJP6QyJ", "function": {"name": "ReadFile", "arguments": "{\"path\": \".agents/skills/example-task/scripts/inspect_session.py"}, "extras": null}}}
+{"timestamp": 1773723375.670088, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_nqkbedqxXK1aX9zAWWNEhzmM", "return_value": {"is_error": false, "output": "     1\t# Prompt 模板\n     2\t\n     3\t以下模板作为脚手架使用。运行前替换占位符。\n     4\t\n     5\t## 单轮还是多轮\n     6\t\n     7\t满足以下任一条件时使用多轮：\n     8\t\n     9\t- 功能有状态\n    10\t- 功能依赖时序或并发\n    11\t- 功能需要审批、清理或恢复\n    12\t- session 产物本身是证据的一部分\n    13\t- 工具接口可能近期发生过变化\n    14\t\n    15\t仅对无状态的窄范围检查使用单轮。\n    16\t\n    17\t## 变量\n    18\t\n    19\t起草 prompt 前填写以下字段：\n    20\t\n    21\t- `<feature>` — 被测功能名称\n    22\t- `<goal>` — 当前场景的目标\n    23\t- `<source_paths>` — 需要阅读的源码路径\n    24\t- `<constraints>` — 执行约束\n    25\t- `<success_signals>` — 成功信号\n    26\t- `<failure_signals>` — 失败信号\n    27\t- `<artifact_paths>` — 需要检查的产物路径\n    28\t- `<session_dir>` — session 目录路径\n    29\t\n    30\t## 探索 prompt\n    31\t\n    32\t```text\n    33\t我要验证 <feature>。\n    34\t\n    35\t先阅读这些文件并只总结当前真实对外接口，不要假设旧文档、旧 prompt 或旧 tool 名称仍然正确：\n    36\t<source_paths>\n    37\t\n    38\t然后给我一个最小 smoke test 计划，只包含：\n    39\t1. happy path\n    40\t2. 一个边界/异常场景\n    41\t3. 一个清理、恢复或中断场景\n    42\t\n    43\t每个场景都写清楚目标、预期信号和要检查的产物。\n    44\t```\n    45\t\n    46\t## 执行 prompt\n    47\t\n    48\t```text\n    49\t在当前 session 里只执行这个场景：<goal>\n    50\t\n    51\t约束：\n    52\t<constraints>\n    53\t\n    54\t执行前先复述你将使用的工具或命令。执行时记录关键 task id、输出片段、文件路径和任何需要后续复盘的标识符。不要扩展到其他场景。\n    55\t```\n    56\t\n    57\t## 观察 prompt\n    58\t\n    59\t```text\n    60\t现在不要继续跑新的测试。\n    61\t\n    62\t只读取并总结这次运行已经产生的状态和文件：\n    63\t<artifact_paths>\n    64\t\n    65\t请明确指出哪些证据支持了预期，哪些证据反驳了预期，哪些地方仍然不确定。\n    66\t```\n    67\t\n    68\t## 复盘 prompt\n    69\t\n    70\t```text\n    71\t请根据这个 session 目录复盘整个 smoke test：\n    72\t<session_dir>\n    73\t\n    74\t重点阅读 context.jsonl、wire.jsonl 和相关运行产物。输出：\n    75\t1. 实际执行流程\n    76\t2. 关键 tool 调用与结果\n    77\t3. 与预期不一致的点\n    78\t4. 最小复现步骤\n    79\t```\n    80\t\n    81\t## 兼容性校验 prompt\n    82\t\n    83\t```text\n    84\t在运行 smoke test 之前，先从提供的文档或代码中复述当前真实可用的工具及其准确名称。不要臆造旧版工具名。如果任务涉及状态或时序，将工作拆分为多轮而非一次性长回复。\n    85\t```\n", "message": "85 lines read from file starting from line 1. End of file reached.", "display": [], "extras": null}}}}
+{"timestamp": 1773723375.765281, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "\"}"}}}
+{"timestamp": 1773723375.76655, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.04880523681640625, "context_tokens": 12794, "max_context_tokens": 262144, "token_usage": {"input_other": 250, "output": 78, "input_cache_read": 12544, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0002", "plan_mode": false}}}
+{"timestamp": 1773723375.791561, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_300OLXjS5RZxFz9LvWJP6QyJ", "return_value": {"is_error": false, "output": "     1\t#!/usr/bin/env python3\n     2\t\"\"\"Locate and summarize a Kimi CLI session for smoke-test review.\"\"\"\n     3\t\n     4\tfrom __future__ import annotations\n     5\t\n     6\timport argparse\n     7\timport json\n     8\timport sys\n     9\tfrom collections import Counter\n    10\tfrom pathlib import Path\n    11\tfrom typing import Any\n    12\t\n    13\t\n    14\tdef parse_args() -> argparse.Namespace:\n    15\t    parser = argparse.ArgumentParser(\n    16\t        description=\"Locate and summarize a Kimi CLI session for smoke-test review.\"\n    17\t    )\n    18\t    parser.add_argument(\"--share-dir\", type=Path, help=\"Share dir that contains sessions/\")\n    19\t    parser.add_argument(\"--session-dir\", type=Path, help=\"Explicit session directory to inspect\")\n    20\t    parser.add_argument(\"--tail-lines\", type=int, default=12, help=\"How many recent records to show\")\n    21\t    parser.add_argument(\n    22\t        \"--max-text\",\n    23\t        type=int,\n    24\t        default=220,\n    25\t        help=\"Maximum characters to show for any text preview\",\n    26\t    )\n    27\t    return parser.parse_args()\n    28\t\n    29\t\n    30\tdef truncate(text: str, max_text: int) -> str:\n    31\t    text = \" \".join(text.split())\n    32\t    if len(text) <= max_text:\n    33\t        return text\n    34\t    return text[: max_text - 3] + \"...\"\n    35\t\n    36\t\n    37\tdef extract_text(content: Any) -> str:\n    38\t    if isinstance(content, str):\n    39\t        return content\n    40\t    if isinstance(content, list):\n    41\t        parts: list[str] = []\n    42\t        for item in content:\n    43\t            if not isinstance(item, dict):\n    44\t                parts.append(str(item))\n    45\t                continue\n    46\t            kind = item.get(\"type\")\n    47\t            if kind == \"text\" and isinstance(item.get(\"text\"), str):\n    48\t                parts.append(item[\"text\"])\n    49\t            elif kind == \"think\" and isinstance(item.get(\"think\"), str):\n    50\t                parts.append(item[\"think\"])\n    51\t            elif kind == \"shell\" and isinstance(item.get(\"command\"), str):\n    52\t                parts.append(item[\"command\"])\n    53\t            else:\n    54\t                parts.append(json.dumps(item, ensure_ascii=False))\n    55\t        return \" \".join(parts)\n    56\t    return json.dumps(content, ensure_ascii=False)\n    57\t\n    58\t\n    59\tdef load_json(path: Path) -> dict[str, Any] | None:\n    60\t    if not path.exists():\n    61\t        return None\n    62\t    try:\n    63\t        return json.loads(path.read_text())\n    64\t    except Exception:\n    65\t        return None\n    66\t\n    67\t\n    68\tdef iter_jsonl(path: Path) -> list[dict[str, Any]]:\n    69\t    records: list[dict[str, Any]] = []\n    70\t    if not path.exists():\n    71\t        return records\n    72\t    with path.open() as f:\n    73\t        for line in f:\n    74\t            line = line.strip()\n    75\t            if not line:\n    76\t                continue\n    77\t            try:\n    78\t                obj = json.loads(line)\n    79\t            except json.JSONDecodeError:\n    80\t                obj = {\"_raw\": line}\n    81\t            records.append(obj)\n    82\t    return records\n    83\t\n    84\t\n    85\tdef find_latest_session(share_dir: Path) -> Path:\n    86\t    sessions_root = share_dir / \"sessions\"\n    87\t    if not sessions_root.exists():\n    88\t        raise FileNotFoundError(f\"sessions directory not found: {sessions_root}\")\n    89\t\n    90\t    candidates: list[tuple[float, Path]] = []\n    91\t    for path in sessions_root.glob(\"*/*\"):\n    92\t        if not path.is_dir():\n    93\t            continue\n    94\t        context_path = path / \"context.jsonl\"\n    95\t        wire_path = path / \"wire.jsonl\"\n    96\t        if context_path.exists():\n    97\t            mtime = context_path.stat().st_mtime\n    98\t        elif wire_path.exists():\n    99\t            mtime = wire_path.stat().st_mtime\n   100\t        else:\n   101\t            mtime = path.stat().st_mtime\n   102\t        candidates.append((mtime, path))\n   103\t\n   104\t    if not candidates:\n   105\t        raise FileNotFoundError(f\"no session directories found under: {sessions_root}\")\n   106\t\n   107\t    candidates.sort(key=lambda item: item[0], reverse=True)\n   108\t    return candidates[0][1]\n   109\t\n   110\t\n   111\tdef print_header(title: str) -> None:\n   112\t    print()\n   113\t    print(f\"== {title} ==\")\n   114\t\n   115\t\n   116\tdef summarize_context_record(record: dict[str, Any], max_text: int) -> str:\n   117\t    if \"_raw\" in record:\n   118\t        return truncate(record[\"_raw\"], max_text)\n   119\t\n   120\t    role = record.get(\"role\", \"<unknown>\")\n   121\t    if role == \"_system_prompt\":\n   122\t        return \"role=_system_prompt\"\n   123\t    if role == \"_checkpoint\":\n   124\t        return f\"role=_checkpoint id={record.get('id')}\"\n   125\t    if role == \"_usage\":\n   126\t        return f\"role=_usage token_count={record.get('token_count')}\"\n   127\t\n   128\t    text = truncate(extract_text(record.get(\"content\")), max_text)\n   129\t\n   130\t    if role == \"assistant\":\n   131\t        tool_calls = record.get(\"tool_calls\") or []\n   132\t        tool_names = [\n   133\t            call.get(\"function\", {}).get(\"name\")\n   134\t            for call in tool_calls\n   135\t            if isinstance(call, dict) and isinstance(call.get(\"function\"), dict)\n   136\t        ]\n   137\t        parts: list[str] = [f\"role={role}\"]\n   138\t        if tool_names:\n   139\t            parts.append(\"tools=\" + \",\".join(name for name in tool_names if name))\n   140\t        if text:\n   141\t            parts.append(f\"text={text}\")\n   142\t        return \" | \".join(parts)\n   143\t\n   144\t    if role == \"tool\":\n   145\t        parts = [f\"role={role}\"]\n   146\t        if record.get(\"tool_call_id\"):\n   147\t            parts.append(f\"tool_call_id={record['tool_call_id']}\")\n   148\t        if text:\n   149\t            parts.append(f\"text={text}\")\n   150\t        return \" | \".join(parts)\n   151\t\n   152\t    if text:\n   153\t        return f\"role={role} | text={text}\"\n   154\t    return f\"role={role}\"\n   155\t\n   156\t\n   157\tdef summarize_wire_record(record: dict[str, Any], max_text: int) -> str:\n   158\t    if \"_raw\" in record:\n   159\t        return truncate(record[\"_raw\"], max_text)\n   160\t\n   161\t    message = record.get(\"message\")\n   162\t    if not isinstance(message, dict):\n   163\t        return truncate(json.dumps(record, ensure_ascii=False), max_text)\n   164\t\n   165\t    message_type = message.get(\"type\", \"<unknown>\")\n   166\t    payload = message.get(\"payload\", {})\n   167\t    parts = [f\"type={message_type}\"]\n   168\t\n   169\t    if message_type == \"StepBegin\":\n   170\t        parts.append(f\"n={payload.get('n')}\")\n   171\t    elif message_type == \"ContentPart\":\n   172\t        part_type = payload.get(\"type\")\n   173\t        parts.append(f\"part={part_type}\")\n   174\t        if part_type in {\"text\", \"think\"}:\n   175\t            parts.append(\"text=\" + truncate(payload.get(\"text\") or payload.get(\"think\") or \"\", max_text))\n   176\t    elif message_type == \"ToolCall\":\n   177\t        function = payload.get(\"function\", {})\n   178\t        if isinstance(function, dict):\n   179\t            parts.append(f\"tool={function.get('name')}\")\n   180\t    elif message_type == \"ApprovalRequest\":\n   181\t        parts.append(f\"action={payload.get('action')}\")\n   182\t        if payload.get(\"description\"):\n   183\t            parts.append(\"desc=\" + truncate(str(payload[\"description\"]), max_text))\n   184\t    elif message_type == \"TurnBegin\":\n   185\t        user_input = payload.get(\"user_input\") or []\n   186\t        parts.append(f\"user_parts={len(user_input)}\")\n   187\t    elif message_type == \"StatusUpdate\":\n   188\t        parts.append(f\"context_tokens={payload.get('context_tokens')}\")\n   189\t\n   190\t    return \" | \".join(parts)\n   191\t\n   192\t\n   193\tdef print_jsonl_summary(title: str, path: Path, tail_lines: int, max_text: int) -> None:\n   194\t    if not path.exists():\n   195\t        print_header(title)\n   196\t        print(\"missing\")\n   197\t        return\n   198\t\n   199\t    records = iter_jsonl(path)\n   200\t    print_header(title)\n   201\t    print(path)\n   202\t    print(f\"records: {len(records)}\")\n   203\t\n   204\t    if path.name == \"context.jsonl\":\n   205\t        counter = Counter(record.get(\"role\", \"<raw>\") for record in records)\n   206\t        print(\"roles:\", \", \".join(f\"{key}={value}\" for key, value in sorted(counter.items())))\n   207\t        tail = records[-tail_lines:]\n   208\t        for idx, record in enumerate(tail, start=max(1, len(records) - len(tail) + 1)):\n   209\t            print(f\"[{idx}] {summarize_context_record(record, max_text)}\")\n   210\t    else:\n   211\t        counter = Counter(\n   212\t            record.get(\"message\", {}).get(\"type\", \"<raw>\")\n   213\t            if isinstance(record.get(\"message\"), dict)\n   214\t            else \"<raw>\"\n   215\t            for record in records\n   216\t        )\n   217\t        print(\"types:\", \", \".join(f\"{key}={value}\" for key, value in sorted(counter.items())))\n   218\t        tail = records[-tail_lines:]\n   219\t        for idx, record in enumerate(tail, start=max(1, len(records) - len(tail) + 1)):\n   220\t            print(f\"[{idx}] {summarize_wire_record(record, max_text)}\")\n   221\t\n   222\t\n   223\tdef print_file_inventory(session_dir: Path) -> None:\n   224\t    print_header(\"Files\")\n   225\t    for path in sorted(session_dir.rglob(\"*\")):\n   226\t        if path.is_dir():\n   227\t            continue\n   228\t        relative = path.relative_to(session_dir)\n   229\t        size = path.stat().st_size\n   230\t        print(f\"{relative} ({size} bytes)\")\n   231\t\n   232\t\n   233\tdef tail_text_file(path: Path, tail_lines: int, max_text: int) -> list[str]:\n   234\t    if not path.exists():\n   235\t        return []\n   236\t    lines = path.read_text(errors=\"replace\").splitlines()\n   237\t    return [truncate(line, max_text) for line in lines[-tail_lines:]]\n   238\t\n   239\t\n   240\tdef print_task_summary(session_dir: Path, tail_lines: int, max_text: int) -> None:\n   241\t    tasks_dir = session_dir / \"tasks\"\n   242\t    if not tasks_dir.exists():\n   243\t        return\n   244\t\n   245\t    task_dirs = sorted(path for path in tasks_dir.iterdir() if path.is_dir())\n   246\t    if not task_dirs:\n   247\t        return\n   248\t\n   249\t    print_header(\"Background Tasks\")\n   250\t    for task_dir in task_dirs:\n   251\t        spec = load_json(task_dir / \"spec.json\") or {}\n   252\t        runtime = load_json(task_dir / \"runtime.json\") or {}\n   253\t        control = load_json(task_dir / \"control.json\") or {}\n   254\t        consumer = load_json(task_dir / \"consumer.json\") or {}\n   255\t        print(f\"task_id: {task_dir.name}\")\n   256\t        print(f\"  description: {spec.get('description')}\")\n   257\t        print(f\"  kind: {spec.get('kind')}\")\n   258\t        print(f\"  status: {runtime.get('status')}\")\n   259\t        if runtime.get(\"exit_code\") is not None:\n   260\t            print(f\"  exit_code: {runtime.get('exit_code')}\")\n   261\t        if spec.get(\"cwd\"):\n   262\t            print(f\"  cwd: {spec.get('cwd')}\")\n   263\t        if spec.get(\"timeout_s\") is not None:\n   264\t            print(f\"  timeout_s: {spec.get('timeout_s')}\")\n   265\t        for key in (\n   266\t            \"created_at\",\n   267\t            \"started_at\",\n   268\t            \"finished_at\",\n   269\t            \"heartbeat_at\",\n   270\t            \"failure_reason\",\n   271\t            \"worker_pid\",\n   272\t            \"child_pid\",\n   273\t        ):\n   274\t            value = runtime.get(key)\n   275\t            if value is not None:\n   276\t                print(f\"  {key}: {value}\")\n   277\t        for key in (\"kill_requested_at\", \"kill_reason\"):\n   278\t            value = control.get(key)\n   279\t            if value is not None:\n   280\t                print(f\"  {key}: {value}\")\n   281\t        for key in (\"last_read_offset\", \"last_viewed_at\"):\n   282\t            value = consumer.get(key)\n   283\t            if value is not None:\n   284\t                print(f\"  {key}: {value}\")\n   285\t        output_path = task_dir / \"output.log\"\n   286\t        if output_path.exists():\n   287\t            print(f\"  output_log: {output_path}\")\n   288\t            for line in tail_text_file(output_path, tail_lines, max_text):\n   289\t                print(f\"    {line}\")\n   290\t        print()\n   291\t\n   292\t\n   293\tdef main() -> int:\n   294\t    args = parse_args()\n   295\t\n   296\t    try:\n   297\t        if args.session_dir:\n   298\t            session_dir = args.session_dir.expanduser().resolve()\n   299\t        elif args.share_dir:\n   300\t            session_dir = find_latest_session(args.share_dir.expanduser().resolve())\n   301\t        else:\n   302\t            print(\"error: pass --session-dir or --share-dir\", file=sys.stderr)\n   303\t            return 1\n   304\t    except FileNotFoundError as exc:\n   305\t        print(f\"error: {exc}\", file=sys.stderr)\n   306\t        return 1\n   307\t\n   308\t    if not session_dir.is_dir():\n   309\t        print(f\"error: session directory does not exist: {session_dir}\", file=sys.stderr)\n   310\t        return 1\n   311\t\n   312\t    print(f\"Session dir: {session_dir}\")\n   313\t    print_file_inventory(session_dir)\n   314\t    print_jsonl_summary(\"Context\", session_dir / \"context.jsonl\", args.tail_lines, args.max_text)\n   315\t    print_jsonl_summary(\"Wire\", session_dir / \"wire.jsonl\", args.tail_lines, args.max_text)\n   316\t    print_task_summary(session_dir, args.tail_lines, args.max_text)\n   317\t    return 0\n   318\t\n   319\t\n   320\tif __name__ == \"__main__\":\n   321\t    raise SystemExit(main())\n", "message": "321 lines read from file starting from line 1. End of file reached.", "display": [], "extras": null}}}}
+{"timestamp": 1773723375.79423, "message": {"type": "StepBegin", "payload": {"n": 3}}}
+{"timestamp": 1773723381.902557, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "好的，我现在已经完整了解了 `example-task` skill 的内容。这个 skill 提供了：\n\n1. **SKILL.md** - 主文档，描述了如何针对 the example CLI 的新增或变更功能进行端到端冒烟测试的完整流程\n2. **references/prompt-patterns.md** - 可复用的 prompt 模板\n3. **scripts/inspect_session.py** - 用于检查和分析 session 产物的脚本\n\n用户似乎是在测试我是否能正确读取和使用这个 skill。既然用户已经在 prompt 中提供了完整的 skill 内容，我应该：\n1. 确认我已经理解了 skill 的内容\n2. 询问用户是否有具体的功能需要我使用这个 skill 来进行冒烟测试\n\n或者，用户可能是想了解这个 skill 的用法。让我给出一个总结并询问用户的具体需求。", "encrypted": null}}}
+{"timestamp": 1773723389.361583, "message": {"type": "ContentPart", "payload": {"type": "text", "text": "我已完整阅读 `example-task` skill。这是一个用于对 the example CLI 进行端到端冒烟测试的系统化流程。\n\n## Skill 要点总结\n\n**核心流程：**\n1. **确定测试范围** - 从 `git diff` 推断功能边界\n2. **读取事实来源** - 文档、代码、agent prompt、测试\n3. **制定最小测试计划** - 正常路径、边界条件、中断/清理\n4. **多轮执行** - 探索→执行→观察→清理\n5. **非交互模式运行** - 使用 `--print --work-dir /tmp/...`\n6. **检查产物** - `context.jsonl`, `wire.jsonl`, 后台任务等\n7. **问题探查** - 并行多路追踪根因\n\n**可用资源：**\n- `references/prompt-patterns.md` - 探索/执行/观察/复盘 prompt 模板\n- `scripts/inspect_session.py` - Session 产物分析工具\n\n---\n\n**你想让我使用这个 skill 来测试哪个功能？**\n\n请提供：\n- 目标功能/变更范围（或直接使用 `git diff main --name-only` 的输出）\n- 是否有特定的测试重点或已知风险点"}}}
+{"timestamp": 1773723389.363364, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.06639862060546875, "context_tokens": 17406, "max_context_tokens": 262144, "token_usage": {"input_other": 4862, "output": 434, "input_cache_read": 12544, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0003", "plan_mode": false}}}
+{"timestamp": 1773723389.364855, "message": {"type": "TurnEnd", "payload": {}}}
+{"timestamp": 1773723422.989559, "message": {"type": "TurnBegin", "payload": {"user_input": [{"type": "text", "text": "请基于 README 和主要源代码目录，给出一份简短的探索清单"}]}}}
+{"timestamp": 1773723422.991471, "message": {"type": "StepBegin", "payload": {"n": 1}}}
+{"timestamp": 1773723426.128673, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "用户想让我直接使用 `git diff main --name-only` 来查看当前分支相对于 main 分支的变更，然后基于这些变更进行冒烟测试。\n\n让我先执行这个命令看看有哪些文件变更。", "encrypted": null}}}
+{"timestamp": 1773723426.525323, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_jOGB6wicU1PmefwL15U57RUT", "function": {"name": "Shell", "arguments": "{\"command\": \"git diff main --name-only && echo \\\"---\\\" && git diff main --stat\"}"}, "extras": null}}}
+{"timestamp": 1773723426.525938, "message": {"type": "ApprovalRequest", "payload": {"id": "49dad4f7-145e-4c43-8b14-7258309f3a86", "tool_call_id": "tool_jOGB6wicU1PmefwL15U57RUT", "sender": "Shell", "action": "run command", "description": "Run command `git diff main --name-only && echo \"---\" && git diff main --stat`", "display": [{"type": "shell", "language": "bash", "command": "git diff main --name-only && echo \"---\" && git diff main --stat"}]}}}
+{"timestamp": 1773723426.526326, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.06703948974609375, "context_tokens": 17574, "max_context_tokens": 262144, "token_usage": {"input_other": 5030, "output": 76, "input_cache_read": 12544, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0004", "plan_mode": false}}}
+{"timestamp": 1773723431.325023, "message": {"type": "ApprovalResponse", "payload": {"request_id": "49dad4f7-145e-4c43-8b14-7258309f3a86", "response": "approve_for_session"}}}
+{"timestamp": 1773723431.40901, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_jOGB6wicU1PmefwL15U57RUT", "return_value": {"is_error": false, "output": ".agents/skills/example-task/SKILL.md\n.agents/skills/example-task/references/prompt-patterns.md\n.agents/skills/example-task/scripts/inspect_session.py\nCHANGELOG.md\nfeature-overview.md\ndocs/en/configuration/data-locations.md\ndocs/en/customization/wire-mode.md\ndocs/en/guides/interaction.md\ndocs/en/guides/sessions.md\ndocs/en/reference/keyboard.md\ndocs/en/reference/kimi-command.md\ndocs/en/reference/kimi-info.md\ndocs/en/reference/kimi-vis.md\ndocs/en/release-notes/changelog.md\ndocs/zh/configuration/data-locations.md\ndocs/zh/customization/wire-mode.md\ndocs/zh/guides/interaction.md\ndocs/zh/guides/sessions.md\ndocs/zh/reference/keyboard.md\ndocs/zh/reference/kimi-command.md\ndocs/zh/reference/kimi-info.md\ndocs/zh/reference/kimi-vis.md\ndocs/zh/release-notes/changelog.md\npackages/kimi-code/pyproject.toml\npyproject.toml\nsrc/example_pkg/acp/session.py\nsrc/example_pkg/agents/default/agent.yaml\nsrc/example_pkg/agents/default/system.md\nsrc/example_pkg/agents/okabe/agent.yaml\nsrc/example_pkg/app.py\nsrc/example_pkg/background/__init__.py\nsrc/example_pkg/background/ids.py\nsrc/example_pkg/background/manager.py\nsrc/example_pkg/background/models.py\nsrc/example_pkg/background/store.py\nsrc/example_pkg/background/summary.py\nsrc/example_pkg/background/worker.py\nsrc/example_pkg/cli/__init__.py\nsrc/example_pkg/config.py\nsrc/example_pkg/notifications/__init__.py\nsrc/example_pkg/notifications/llm.py\nsrc/example_pkg/notifications/manager.py\nsrc/example_pkg/notifications/models.py\nsrc/example_pkg/notifications/notifier.py\nsrc/example_pkg/notifications/store.py\nsrc/example_pkg/notifications/wire.py\nsrc/example_pkg/soul/__init__.py\nsrc/example_pkg/soul/agent.py\nsrc/example_pkg/soul/dynamic_injection.py\nsrc/example_pkg/soul/kimisoul.py\nsrc/example_pkg/soul/message.py\nsrc/example_pkg/tools/__init__.py\nsrc/example_pkg/tools/background/__init__.py\nsrc/example_pkg/tools/background/list.md\nsrc/example_pkg/tools/background/output.md\nsrc/example_pkg/tools/background/stop.md\nsrc/example_pkg/tools/display.py\nsrc/example_pkg/tools/shell/__init__.py\nsrc/example_pkg/tools/shell/bash.md\nsrc/example_pkg/tools/shell/powershell.md\nsrc/example_pkg/ui/shell/__init__.py\nsrc/example_pkg/ui/shell/console.py\nsrc/example_pkg/ui/shell/echo.py\nsrc/example_pkg/ui/shell/placeholders.py\nsrc/example_pkg/ui/shell/prompt.py\nsrc/example_pkg/ui/shell/replay.py\nsrc/example_pkg/ui/shell/visualize.py\nsrc/example_pkg/utils/export.py\nsrc/example_pkg/web/app.py\nsrc/example_pkg/wire/protocol.py\nsrc/example_pkg/wire/types.py\ntests/background/test_manager.py\ntests/background/test_store.py\ntests/background/test_worker.py\ntests/conftest.py\ntests/core/test_config.py\ntests/core/test_default_agent.py\ntests/core/test_kimisoul_ralph_loop.py\ntests/core/test_kimisoul_retry_recovery.py\ntests/core/test_kimisoul_steer.py\ntests/core/test_normalize_history.py\ntests/core/test_notifications.py\ntests/core/test_wire_message.py\ntests/core/test_wire_server_steer.py\ntests/core/test_write_file_plan_mode.py\ntests/e2e/__init__.py\ntests/e2e/shell_pty_helpers.py\ntests/e2e/test_basic_e2e.py\ntests/e2e/test_media_e2e.py\ntests/e2e/test_shell_pty_e2e.py\ntests/notifications/test_notification_manager.py\ntests/tools/test_background_tools.py\ntests/tools/test_shell_bash.py\ntests/tools/test_tool_descriptions.py\ntests/tools/test_tool_schemas.py\ntests/ui_and_conv/test_export_import.py\ntests/ui_and_conv/test_live_view_notifications.py\ntests/ui_and_conv/test_prompt_clipboard.py\ntests/ui_and_conv/test_prompt_external_editor.py\ntests/ui_and_conv/test_prompt_history.py\ntests/ui_and_conv/test_prompt_placeholders.py\ntests/ui_and_conv/test_prompt_tips.py\ntests/ui_and_conv/test_replay.py\ntests/ui_and_conv/test_sanitize_surrogates.py\ntests/ui_and_conv/test_shell_prompt_echo.py\ntests/ui_and_conv/test_shell_run_placeholders.py\ntests/ui_and_conv/test_slash_completer.py\ntests/ui_and_conv/test_visualize_running_prompt.py\ntests_e2e/test_wire_protocol.py\ntests_e2e/test_wire_sessions.py\nuv.lock\nweb/src/hooks/useSessionStream.ts\nweb/src/hooks/wireTypes.ts\n---\n .agents/skills/example-task/SKILL.md         |  185 ++++\n .../references/prompt-patterns.md                  |   85 ++\n .../example-task/scripts/inspect_session.py  |  321 +++++++\n CHANGELOG.md                                       |   16 -\n feature-overview.md                            |  353 +++++++\n docs/en/configuration/data-locations.md            |    6 -\n docs/en/customization/wire-mode.md                 |   24 +-\n docs/en/guides/interaction.md                      |   14 +-\n docs/en/guides/sessions.md                         |    1 -\n docs/en/reference/keyboard.md                      |    8 +-\n docs/en/reference/kimi-command.md                  |   18 -\n docs/en/reference/kimi-info.md                     |    6 +-\n docs/en/reference/kimi-vis.md                      |   13 -\n docs/en/release-notes/changelog.md                 |   16 -\n docs/zh/configuration/data-locations.md            |    6 -\n docs/zh/customization/wire-mode.md                 |   24 +-\n docs/zh/guides/interaction.md                      |   14 +-\n docs/zh/guides/sessions.md                         |    1 -\n docs/zh/reference/keyboard.md                      |    8 +-\n docs/zh/reference/kimi-command.md                  |   18 -\n docs/zh/reference/kimi-info.md                     |    6 +-\n docs/zh/reference/kimi-vis.md                      |   13 -\n docs/zh/release-notes/changelog.md                 |   16 -\n packages/kimi-code/pyproject.toml                  |    4 +-\n pyproject.toml                                     |    2 +-\n src/example_pkg/acp/session.py                        |    3 -\n src/example_pkg/agents/default/agent.yaml             |    3 +\n src/example_pkg/agents/default/system.md              |    2 +\n src/example_pkg/agents/okabe/agent.yaml               |    3 +\n src/example_pkg/app.py                                |    2 +\n src/example_pkg/background/__init__.py                |   36 +\n src/example_pkg/background/ids.py                     |   17 +\n src/example_pkg/background/manager.py                 |  358 +++++++\n src/example_pkg/background/models.py                  |   89 ++\n src/example_pkg/background/store.py                   |  187 ++++\n src/example_pkg/background/summary.py                 |   61 ++\n src/example_pkg/background/worker.py                  |  204 ++++\n src/example_pkg/cli/__init__.py                       |   26 +\n src/example_pkg/config.py                             |   25 +\n src/example_pkg/notifications/__init__.py             |   33 +\n src/example_pkg/notifications/llm.py                  |   78 ++\n src/example_pkg/notifications/manager.py              |  105 ++\n src/example_pkg/notifications/models.py               |   50 +\n src/example_pkg/notifications/notifier.py             |   36 +\n src/example_pkg/notifications/store.py                |   89 ++\n src/example_pkg/notifications/wire.py                 |   21 +\n src/example_pkg/soul/__init__.py                      |   28 +\n src/example_pkg/soul/agent.py                         |   24 +-\n src/example_pkg/soul/dynamic_injection.py             |   10 +-\n src/example_pkg/soul/kimisoul.py                      |  100 +-\n src/example_pkg/soul/message.py                       |   12 -\n src/example_pkg/tools/__init__.py                     |   15 +\n src/example_pkg/tools/background/__init__.py          |  235 +++++\n src/example_pkg/tools/background/list.md              |   10 +\n src/example_pkg/tools/background/output.md            |    9 +\n src/example_pkg/tools/background/stop.md              |    8 +\n src/example_pkg/tools/display.py                      |   10 +\n src/example_pkg/tools/shell/__init__.py               |  101 +-\n src/example_pkg/tools/shell/bash.md                   |    4 +\n src/example_pkg/tools/shell/powershell.md             |    4 +\n src/example_pkg/ui/shell/__init__.py                  |   60 +-\n src/example_pkg/ui/shell/console.py                   |    5 +-\n src/example_pkg/ui/shell/echo.py                      |   17 -\n src/example_pkg/ui/shell/placeholders.py              |  530 ----------\n src/example_pkg/ui/shell/prompt.py                    | 1011 +++++---------------\n src/example_pkg/ui/shell/replay.py                    |   47 +-\n src/example_pkg/ui/shell/visualize.py                 |  383 ++------\n src/example_pkg/utils/export.py                       |   15 +-\n src/example_pkg/web/app.py                            |    3 +-\n src/example_pkg/wire/protocol.py                      |    2 +-\n src/example_pkg/wire/types.py                         |   32 +-\n tests/background/test_manager.py                   |  275 ++++++\n tests/background/test_store.py                     |   92 ++\n tests/background/test_worker.py                    |  130 +++\n tests/conftest.py                                  |   37 +-\n tests/core/test_config.py                          |   13 +\n tests/core/test_default_agent.py                   |  119 ++-\n tests/core/test_kimisoul_ralph_loop.py             |    3 +\n tests/core/test_kimisoul_retry_recovery.py         |    3 +\n tests/core/test_kimisoul_steer.py                  |  472 ---------\n tests/core/test_normalize_history.py               |   12 +\n tests/core/test_notifications.py                   |  235 +++++\n tests/core/test_wire_message.py                    |   76 +-\n tests/core/test_wire_server_steer.py               |   75 --\n tests/core/test_write_file_plan_mode.py            |   11 +-\n tests/e2e/__init__.py                              |    1 -\n tests/e2e/shell_pty_helpers.py                     |  371 -------\n tests/e2e/test_basic_e2e.py                        |   12 +-\n tests/e2e/test_media_e2e.py                        |   31 +-\n tests/e2e/test_shell_pty_e2e.py                    |  499 ----------\n tests/notifications/test_notification_manager.py   |   86 ++\n tests/tools/test_background_tools.py               |  205 ++++\n tests/tools/test_shell_bash.py                     |   58 +-\n tests/tools/test_tool_descriptions.py              |   53 +\n tests/tools/test_tool_schemas.py                   |   82 +-\n tests/ui_and_conv/test_export_import.py            |   83 +-\n tests/ui_and_conv/test_live_view_notifications.py  |   56 ++\n tests/ui_and_conv/test_prompt_clipboard.py         |   78 +-\n tests/ui_and_conv/test_prompt_external_editor.py   |   84 --\n tests/ui_and_conv/test_prompt_history.py           |   66 --\n tests/ui_and_conv/test_prompt_placeholders.py      |  189 ----\n tests/ui_and_conv/test_prompt_tips.py              |  212 +---\n tests/ui_and_conv/test_replay.py                   |  169 ----\n tests/ui_and_conv/test_sanitize_surrogates.py      |   16 +-\n tests/ui_and_conv/test_shell_prompt_echo.py        |  154 ---\n tests/ui_and_conv/test_shell_run_placeholders.py   |  224 -----\n tests/ui_and_conv/test_slash_completer.py          |  123 +--\n tests/ui_and_conv/test_visualize_running_prompt.py |  335 -------\n tests_e2e/test_wire_protocol.py                    |    6 +-\n tests_e2e/test_wire_sessions.py                    |   40 +-\n uv.lock                                            |    4 +-\n web/src/hooks/useSessionStream.ts                  |    2 +-\n web/src/hooks/wireTypes.ts                         |   10 +-\n 113 files changed, 4787 insertions(+), 5296 deletions(-)\n", "message": "Command executed successfully.", "display": [], "extras": null}}}}
+{"timestamp": 1773723431.4108758, "message": {"type": "StepBegin", "payload": {"n": 2}}}
+{"timestamp": 1773723442.2125728, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "从 git diff 的输出来看，这是一个非常大的变更集，主要涉及以下几个核心功能：\n\n1. **后台任务系统 (background/)** - 全新模块\n   - `src/example_pkg/background/` - 后台任务管理核心\n   - `src/example_pkg/tools/background/` - 后台任务工具\n\n2. **通知系统 (notifications/)** - 全新模块\n   - `src/example_pkg/notifications/` - 通知管理\n\n3. **Shell UI 重构** - 大规模重构\n   - `src/example_pkg/ui/shell/` - Shell UI 组件重构\n   - 移除了大量旧代码（placeholders, echo 等）\n\n4. **Wire 协议更新**\n   - `src/example_pkg/wire/types.py` 和 `protocol.py`\n\n5. **动态注入 (dynamic_injection.py)**\n   - 更新\n\n6. **测试覆盖**\n   - 大量新增测试\n\n这是一个大版本功能变更，需要仔细规划冒烟测试。我需要先读取关键的事实来源来理解这些功能的实际接口。\n\n让我制定一个测试计划：\n1. 后台任务生命周期（创建、监控、停止、输出获取）\n2. 通知系统（接收、展示、管理）\n3. Shell UI 核心交互（prompt、replay、visualize）\n4. 工具链集成（background 工具、shell 工具）\n\n\n5. 现在从核心模块开始，检查后台任务和通知系统的具体实现", "encrypted": null}}}
+{"timestamp": 1773723447.107625, "message": {"type": "ContentPart", "payload": {"type": "text", "text": "根据 git diff 输出，这是一个大规模功能变更，主要涉及：\n\n1. **后台任务系统** (`src/example_pkg/background/`) - 全新模块\n2. **通知系统** (`src/example_pkg/notifications/`) - 全新模块  \n3. **后台任务工具** (`src/example_pkg/tools/background/`) - 新工具\n4. **Shell UI 重构** (`src/example_pkg/ui/shell/`) - 大量重构\n5. **Wire 协议更新** (`src/example_pkg/wire/types.py`)\n6. **动态注入更新** (`src/example_pkg/soul/dynamic_injection.py`)\n\n让我开始冒烟测试流程，首先读取事实来源："}}}
+{"timestamp": 1773723447.612225, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_TB9CacXCzJ8B11tzzOneV7MK", "function": {"name": "ReadFile", "arguments": "{\"path\": \"feature-overview.md\"}"}, "extras": null}}}
+{"timestamp": 1773723447.643475, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_7tKhkdZsBAFotRMTFs0BmgM6", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/background/manager.py"}, "extras": null}}}
+{"timestamp": 1773723447.644057, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_TB9CacXCzJ8B11tzzOneV7MK", "return_value": {"is_error": false, "output": "     1\t# 后台任务实现说明\n     2\t\n     3\t这份文档是给后续开发者快速理解当前 background task / notification 实现用的内部说明，不是用户文档。\n     4\t\n     5\t## 一句话结论\n     6\t\n     7\t当前实现已经不再把 background task completion 建模成 `dynamic injection` 的一个特例。\n     8\t\n     9\t现在的结构是：\n    10\t\n    11\t- `Shell(run_in_background=true)` 负责启动后台任务\n    12\t- `TaskList` / `TaskOutput` / `TaskStop` 负责最小控制面\n    13\t- `BackgroundTaskManager` 负责 task 生命周期\n    14\t- `NotificationManager` 负责通用 notification 基建\n    15\t- `task notification` 只是 notification 基建里的一个 type\n    16\t- notification 会同时走：\n    17\t  - `llm` sink：进入模型上下文\n    18\t  - `wire` sink：给其他 UI / client\n    19\t  - `shell` sink：给 shell idle toast\n    20\t\n    21\t这意味着 background task 已经不再拥有自己私有的“通知系统”，而是变成了 Notification 基建的一个 producer。\n    22\t\n    23\t## 当前模型接口\n    24\t\n    25\t### 1. `Shell`\n    26\t\n    27\t`Shell` 的后台模式仍然是：\n    28\t\n    29\t- `run_in_background: bool`\n    30\t- `description: str`\n    31\t\n    32\t当 `run_in_background=true` 时：\n    33\t\n    34\t1. 正常走审批\n    35\t2. 创建后台 bash task\n    36\t3. 立即返回 `task_id`\n    37\t4. 明确告诉模型：\n    38\t   - 系统会自动通知完成状态\n    39\t   - 需要重新枚举当前活跃 task 时用 `TaskList`\n    40\t   - 需要主动查看时用 `TaskOutput`\n    41\t   - 只有需要取消时才用 `TaskStop`\n    42\t\n    43\t### 2. `TaskList`\n    44\t\n    45\t`TaskList` 是 read-only 的通用枚举工具：\n    46\t\n    47\t- `active_only: bool = true`\n    48\t- `limit: int = 20`\n    49\t\n    50\t它的主要用途不是替代自动通知，而是：\n    51\t\n    52\t- 在 context compaction 之后重新枚举活跃 task\n    53\t- 在模型不再确信当前有哪些 task 时恢复外部状态\n    54\t\n    55\t### 3. `TaskOutput`\n    56\t\n    57\t`TaskOutput` 仍然是统一读取工具：\n    58\t\n    59\t- `task_id`\n    60\t- `block: bool`\n    61\t- `timeout`\n    62\t\n    63\t语义：\n    64\t\n    65\t- `block=false`：立即返回当前状态和最近输出\n    66\t- `block=true`：等待终态或超时后返回\n    67\t\n    68\t### 4. `TaskStop`\n    69\t\n    70\t`TaskStop` 是统一停止工具：\n    71\t\n    72\t- `task_id`\n    73\t- `reason`\n    74\t\n    75\t它是 generic task control，不是 bash 专属 kill。\n    76\t\n    77\t## Notification 基建\n    78\t\n    79\t这次实现里最重要的变化，不是 task 工具，而是 notification 的抽象边界。\n    80\t\n    81\t### 设计原则\n    82\t\n    83\tnotification 现在被定义成：\n    84\t\n    85\t- 持久化的系统事件\n    86\t- 生产者无关\n    87\t- 消费者无关\n    88\t- 可恢复、可去重、可多 sink 投递\n    89\t\n    90\t因此它不再挂在 `background/` 或 `dynamic injection` 下，而是独立成顶层能力：\n    91\t\n    92\t- `src/example_pkg/notifications/models.py`\n    93\t- `src/example_pkg/notifications/store.py`\n    94\t- `src/example_pkg/notifications/manager.py`\n    95\t- `src/example_pkg/notifications/llm.py`\n    96\t- `src/example_pkg/notifications/wire.py`\n    97\t- `src/example_pkg/notifications/notifier.py`\n    98\t\n    99\t### Notification 数据模型\n   100\t\n   101\t核心 envelope：\n   102\t\n   103\t- `id`\n   104\t- `category`\n   105\t- `type`\n   106\t- `source_kind`\n   107\t- `source_id`\n   108\t- `title`\n   109\t- `body`\n   110\t- `severity`\n   111\t- `created_at`\n   112\t- `payload`\n   113\t- `targets`\n   114\t- `dedupe_key`\n   115\t\n   116\t首版 sink：\n   117\t\n   118\t- `llm`\n   119\t- `wire`\n   120\t- `shell`\n   121\t\n   122\tdelivery 状态按 sink 单独跟踪：\n   123\t\n   124\t- `pending`\n   125\t- `claimed`\n   126\t- `acked`\n   127\t\n   128\t### session 持久化\n   129\t\n   130\tnotification 单独落盘，不再复用 task consumer state：\n   131\t\n   132\t```text\n   133\t<session_dir>/notifications/<notification_id>/\n   134\t  event.json\n   135\t  delivery.json\n   136\t```\n   137\t\n   138\t这样 background task、future background agent、system notification 都能共用同一个基建。\n   139\t\n   140\t## background task 作为 producer\n   141\t\n   142\t### task 目录\n   143\t\n   144\ttask 目录本身仍然保留：\n   145\t\n   146\t```text\n   147\t<session_dir>/tasks/<task_id>/\n   148\t  spec.json\n   149\t  runtime.json\n   150\t  control.json\n   151\t  consumer.json\n   152\t  output.log\n   153\t```\n   154\t\n   155\t其中：\n   156\t\n   157\t- `consumer.json` 现在只保留 `TaskOutput` 的读偏移和时间\n   158\t- notification 是否消费，已经完全搬出 task 目录\n   159\t\n   160\t### task -> notification 映射\n   161\t\n   162\t`BackgroundTaskManager.publish_terminal_notifications()` 会扫描终态 task，并发布：\n   163\t\n   164\t- `task.completed`\n   165\t- `task.failed`\n   166\t- `task.killed`\n   167\t- `task.lost`\n   168\t\n   169\t其 `source_kind` 固定为：\n   170\t\n   171\t- `background_task`\n   172\t\n   173\t去重依赖：\n   174\t\n   175\t- `dedupe_key = background_task:<task_id>:<status>`\n   176\t\n   177\t这保证了：\n   178\t\n   179\t- 同一个终态不会重复发 notification\n   180\t- `recover()` 之后补发 `task.lost` 也不会和别的状态混淆\n   181\t\n   182\t## LLM sink\n   183\t\n   184\tbackground notification 不再通过 `DynamicInjectionProvider` 注入。\n   185\t\n   186\t当前做法是：\n   187\t\n   188\t1. `KimiSoul._step()` 在每次 step 前先触发 `publish_terminal_notifications()`\n   189\t2. 从 `NotificationManager.claim_for_sink(\"llm\")` 拉取待投递 notification\n   190\t3. 转成独立 `<notification ...>` message append 到 context\n   191\t4. append 成功后 ack\n   192\t\n   193\ttask 类型的 notification 会在 `llm` bridge 中追加 task 细节和 `output tail`，因此模型仍然能看到：\n   194\t\n   195\t- task id\n   196\t- task type\n   197\t- description\n   198\t- status\n   199\t- exit code\n   200\t- failure reason\n   201\t- 输出尾部\n   202\t\n   203\t一个典型的模型可见消息形态是：\n   204\t\n   205\t```text\n   206\t<notification id=\"...\" category=\"task\" type=\"task.completed\" ...>\n   207\tTitle: Background task completed: run tests\n   208\tSeverity: success\n   209\tTask ID: babc1234\n   210\tStatus: completed\n   211\tDescription: run tests\n   212\t<task-notification>\n   213\t...\n   214\t</task-notification>\n   215\t</notification>\n   216\t```\n   217\t\n   218\t### 为什么这比 dynamic injection 更对\n   219\t\n   220\t因为这里 notification 是：\n   221\t\n   222\t- 独立消息\n   223\t- 独立 lifecycle\n   224\t- 独立 ack\n   225\t\n   226\t而不再只是“step 前补一段 reminder 文本”。\n   227\t\n   228\t## wire sink\n   229\t\n   230\tnotification 现在已经进入 wire 协议层。\n   231\t\n   232\t`src/example_pkg/wire/types.py` 新增了通用 `Notification` wire event，而不是 task 专属 event。\n   233\t\n   234\t字段包括：\n   235\t\n   236\t- `id`\n   237\t- `category`\n   238\t- `type`\n   239\t- `source_kind`\n   240\t- `source_id`\n   241\t- `title`\n   242\t- `body`\n   243\t- `severity`\n   244\t- `created_at`\n   245\t- `payload`\n   246\t\n   247\t这意味着：\n   248\t\n   249\t- shell 以外的 UI 可以直接复用 notification\n   250\t- future kimi web / ACP / IDE 不需要理解 background task 内部目录结构\n   251\t- task notification 只是 `Notification(category=\"task\", type=\"task.*\")`\n   252\t\n   253\t`run_soul()` 现在会启动一个 notification pump：\n   254\t\n   255\t1. 周期性触发 `publish_terminal_notifications()`\n   256\t2. 从 `claim_for_sink(\"wire\")` 拉 notification\n   257\t3. 转成 wire `Notification`\n   258\t4. 发送到当前 wire\n   259\t5. ack `wire` sink\n   260\t\n   261\t## compaction 与活跃 task\n   262\t\n   263\t仅靠 conversation history 不能保证 compaction 后模型还记得当前活跃 task。\n   264\t\n   265\t原因是：\n   266\t\n   267\t- task 的真相源在 task store，不在 conversation memory\n   268\t- compaction 只会保留总结和最近少量消息\n   269\t- 如果“启动 task”那条工具结果被压缩掉，模型可能忘记当前仍在运行的 task\n   270\t\n   271\t所以现在除了 `TaskList` 工具之外，还补了一层自动恢复：\n   272\t\n   273\t1. `compact_context()` 完成后\n   274\t2. root agent 会从 task store 重新读取当前非终态 task\n   275\t3. 生成一个 `<active-background-tasks>` 快照\n   276\t4. 作为独立消息追加到 compacted context 之后\n   277\t\n   278\t这保证了：\n   279\t\n   280\t- compaction 后模型立刻重新看到当前活跃 task\n   281\t- 如果之后再次不确定，也可以显式调用 `TaskList`\n   282\t\n   283\t## shell sink\n   284\t\n   285\tshell idle 状态下没有活动的 `run_soul()` / wire turn，所以仍然需要本地 watcher。\n   286\t\n   287\t但 watcher 已经从 background-specific 逻辑改成了 generic notification watcher：\n   288\t\n   289\t- `NotificationWatcher(sink=\"shell\")`\n   290\t\n   291\t它做的事是：\n   292\t\n   293\t1. 周期性发布 background terminal notifications\n   294\t2. claim `shell` sink\n   295\t3. toast\n   296\t4. ack\n   297\t\n   298\t所以 shell 现在消费的是 notification 基建，而不是直接扫 task consumer 状态。\n   299\t\n   300\t## 与 CodeAgent 的关系\n   301\t\n   302\t### 当前已经对齐的点\n   303\t\n   304\t- `Shell(background)` + 自动通知 + `TaskList` + `TaskOutput` + `TaskStop`\n   305\t- 输出直写文件，而不是长时间 pipe 托管\n   306\t- task notification 被建模成独立系统事件，而不是 bash 私有逻辑\n   307\t- notification 有统一基建，task 只是其中一种 type\n   308\t\n   309\t### 当前仍然与 CodeAgent 不同的点\n   310\t\n   311\t- Kimi 仍然以 session 磁盘状态为真相源，不是进程内 `AppState`\n   312\t- `llm` notification 目前是独立 `<notification>` message，不是 CodeAgent 那种专门 attachment 协议\n   313\t- shell idle toast 仍然有本地 watcher，因为 shell 在 idle 时没有活跃 wire turn\n   314\t- 还没有前台任务 `Ctrl+B` 后台化 / 自动后台化\n   315\t\n   316\t这些差异是刻意保留的，不是遗漏。\n   317\t\n   318\t## 当前关键模块\n   319\t\n   320\t| 模块 | 作用 |\n   321\t|------|------|\n   322\t| `src/example_pkg/tools/shell/__init__.py` | `Shell` 后台启动入口 |\n   323\t| `src/example_pkg/tools/background/__init__.py` | `TaskList` / `TaskOutput` / `TaskStop` |\n   324\t| `src/example_pkg/background/manager.py` | task 控制面与 task notification producer |\n   325\t| `src/example_pkg/background/store.py` | task 持久化 |\n   326\t| `src/example_pkg/background/worker.py` | detached worker |\n   327\t| `src/example_pkg/notifications/manager.py` | notification core |\n   328\t| `src/example_pkg/notifications/llm.py` | notification -> context message |\n   329\t| `src/example_pkg/notifications/wire.py` | notification -> wire event |\n   330\t| `src/example_pkg/notifications/notifier.py` | generic watcher |\n   331\t| `src/example_pkg/soul/kimisoul.py` | `llm` sink 投递 |\n   332\t| `src/example_pkg/soul/__init__.py` | `wire` sink pump |\n   333\t\n   334\t## 测试关注点\n   335\t\n   336\t当前实现至少应该持续覆盖以下几类测试：\n   337\t\n   338\t1. notification core 的 dedupe / claim / ack / recover\n   339\t2. background terminal task 会正确发布 notification\n   340\t3. `KimiSoul` 会把 `llm` sink notification 作为独立消息写入 context\n   341\t4. notification message 不会被 `normalize_history()` 合并进普通 user message\n   342\t5. wire sink 会发出标准 `Notification` event\n   343\t6. compaction 后会重新插入当前活跃 task 快照\n   344\t7. `TaskList` / `TaskOutput` / `TaskStop` / `Shell(background)` 的既有契约不回退\n   345\t7. `recover()` 会把 stale task 修成 `lost`，并能后续发布 `task.lost`\n   346\t\n   347\t## 后续最值得做的事\n   348\t\n   349\t如果后面继续往前推，优先级最高的是：\n   350\t\n   351\t1. 给 notification 增加更正式的 UI backlog / replay 机制\n   352\t2. 把 future background agent 直接接成 notification 的第二个 producer\n   353\t3. 再评估是否需要把 `<notification>` 升级成更正式的 attachment 协议\n", "message": "353 lines read from file starting from line 1. End of file reached.", "display": [], "extras": null}}}}
+{"timestamp": 1773723448.2356732, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "\"}"}}}
+{"timestamp": 1773723448.2669141, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_DR5VfRHgGe7WZ1dXKSA5Yowh", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/background/models.py"}, "extras": null}}}
+{"timestamp": 1773723448.2674959, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_7tKhkdZsBAFotRMTFs0BmgM6", "return_value": {"is_error": false, "output": "     1\tfrom __future__ import annotations\n     2\t\n     3\timport asyncio\n     4\timport os\n     5\timport signal\n     6\timport subprocess\n     7\timport sys\n     8\timport time\n     9\tfrom pathlib import Path\n    10\t\n    11\tfrom kaos.local import local_kaos\n    12\t\n    13\tfrom example_pkg.config import BackgroundConfig\n    14\tfrom example_pkg.notifications import NotificationEvent, NotificationManager\n    15\tfrom example_pkg.session import Session\n    16\tfrom example_pkg.utils.logging import logger\n    17\t\n    18\tfrom .ids import generate_task_id\n    19\tfrom .models import (\n    20\t    TaskOutputChunk,\n    21\t    TaskRuntime,\n    22\t    TaskSpec,\n    23\t    TaskStatus,\n    24\t    TaskView,\n    25\t    is_terminal_status,\n    26\t)\n    27\tfrom .store import BackgroundTaskStore\n    28\t\n    29\t\n    30\tclass BackgroundTaskManager:\n    31\t    def __init__(\n    32\t        self,\n    33\t        session: Session,\n    34\t        config: BackgroundConfig,\n    35\t        *,\n    36\t        notifications: NotificationManager,\n    37\t        owner_role: str = \"root\",\n    38\t    ) -> None:\n    39\t        self._session = session\n    40\t        self._config = config\n    41\t        self._notifications = notifications\n    42\t        self._owner_role = owner_role\n    43\t        self._store = BackgroundTaskStore(session.context_file.parent / \"tasks\")\n    44\t\n    45\t    @property\n    46\t    def store(self) -> BackgroundTaskStore:\n    47\t        return self._store\n    48\t\n    49\t    @property\n    50\t    def role(self) -> str:\n    51\t        return self._owner_role\n    52\t\n    53\t    def copy_for_role(self, role: str) -> BackgroundTaskManager:\n    54\t        return BackgroundTaskManager(\n    55\t            self._session,\n    56\t            self._config,\n    57\t            notifications=self._notifications,\n    58\t            owner_role=role,\n    59\t        )\n    60\t\n    61\t    def _ensure_root(self) -> None:\n    62\t        if self._owner_role != \"root\":\n    63\t            raise RuntimeError(\"Background tasks are only supported from the root agent.\")\n    64\t\n    65\t    def _ensure_local_backend(self) -> None:\n    66\t        if self._session.work_dir_meta.kaos != local_kaos.name:\n    67\t            raise RuntimeError(\"Background tasks are only supported on local sessions.\")\n    68\t\n    69\t    def _active_task_count(self) -> int:\n    70\t        return sum(\n    71\t            1 for view in self._store.list_views() if not is_terminal_status(view.runtime.status)\n    72\t        )\n    73\t\n    74\t    def _worker_command(self, task_dir: Path) -> list[str]:\n    75\t        if getattr(sys, \"frozen\", False):\n    76\t            return [\n    77\t                sys.executable,\n    78\t                \"__background-task-worker\",\n    79\t                \"--task-dir\",\n    80\t                str(task_dir),\n    81\t                \"--heartbeat-interval-ms\",\n    82\t                str(self._config.worker_heartbeat_interval_ms),\n    83\t                \"--control-poll-interval-ms\",\n    84\t                str(self._config.wait_poll_interval_ms),\n    85\t                \"--kill-grace-period-ms\",\n    86\t                str(self._config.kill_grace_period_ms),\n    87\t            ]\n    88\t        return [\n    89\t            sys.executable,\n    90\t            \"-m\",\n    91\t            \"example_pkg.cli\",\n    92\t            \"__background-task-worker\",\n    93\t            \"--task-dir\",\n    94\t            str(task_dir),\n    95\t            \"--heartbeat-interval-ms\",\n    96\t            str(self._config.worker_heartbeat_interval_ms),\n    97\t            \"--control-poll-interval-ms\",\n    98\t            str(self._config.wait_poll_interval_ms),\n    99\t            \"--kill-grace-period-ms\",\n   100\t            str(self._config.kill_grace_period_ms),\n   101\t        ]\n   102\t\n   103\t    def _launch_worker(self, task_dir: Path) -> int:\n   104\t        kwargs: dict[str, object] = {\n   105\t            \"stdin\": subprocess.DEVNULL,\n   106\t            \"stdout\": subprocess.DEVNULL,\n   107\t            \"stderr\": subprocess.DEVNULL,\n   108\t            \"cwd\": str(task_dir),\n   109\t        }\n   110\t        if os.name == \"nt\":\n   111\t            kwargs[\"creationflags\"] = getattr(subprocess, \"CREATE_NEW_PROCESS_GROUP\", 0)\n   112\t        else:\n   113\t            kwargs[\"start_new_session\"] = True\n   114\t\n   115\t        process = subprocess.Popen(self._worker_command(task_dir), **kwargs)\n   116\t        return process.pid\n   117\t\n   118\t    def create_bash_task(\n   119\t        self,\n   120\t        *,\n   121\t        command: str,\n   122\t        description: str,\n   123\t        timeout_s: int,\n   124\t        tool_call_id: str,\n   125\t        shell_name: str,\n   126\t        shell_path: str,\n   127\t        cwd: str,\n   128\t    ) -> TaskView:\n   129\t        self._ensure_root()\n   130\t        self._ensure_local_backend()\n   131\t\n   132\t        if self._active_task_count() >= self._config.max_running_tasks:\n   133\t            raise RuntimeError(\"Too many background tasks are already running.\")\n   134\t\n   135\t        task_id = generate_task_id(\"bash\")\n   136\t        spec = TaskSpec(\n   137\t            id=task_id,\n   138\t            kind=\"bash\",\n   139\t            session_id=self._session.id,\n   140\t            description=description,\n   141\t            tool_call_id=tool_call_id,\n   142\t            owner_role=\"root\",\n   143\t            command=command,\n   144\t            shell_name=shell_name,\n   145\t            shell_path=shell_path,\n   146\t            cwd=cwd,\n   147\t            timeout_s=timeout_s,\n   148\t        )\n   149\t        self._store.create_task(spec)\n   150\t\n   151\t        runtime = self._store.read_runtime(task_id)\n   152\t        task_dir = self._store.task_dir(task_id)\n   153\t        try:\n   154\t            worker_pid = self._launch_worker(task_dir)\n   155\t        except Exception as exc:\n   156\t            runtime.status = \"failed\"\n   157\t            runtime.failure_reason = f\"Failed to launch worker: {exc}\"\n   158\t            runtime.finished_at = time.time()\n   159\t            runtime.updated_at = runtime.finished_at\n   160\t            self._store.write_runtime(task_id, runtime)\n   161\t            raise\n   162\t\n   163\t        runtime = self._store.read_runtime(task_id)\n   164\t        if runtime.finished_at is None and (\n   165\t            runtime.status == \"created\"\n   166\t            or (runtime.status == \"starting\" and runtime.worker_pid is None)\n   167\t        ):\n   168\t            runtime.status = \"starting\"\n   169\t            runtime.worker_pid = worker_pid\n   170\t            runtime.updated_at = time.time()\n   171\t            self._store.write_runtime(task_id, runtime)\n   172\t        return self._store.merged_view(task_id)\n   173\t\n   174\t    def list_tasks(\n   175\t        self,\n   176\t        *,\n   177\t        status: TaskStatus | None = None,\n   178\t        limit: int = 20,\n   179\t    ) -> list[TaskView]:\n   180\t        tasks = self._store.list_views()\n   181\t        if status is not None:\n   182\t            tasks = [task for task in tasks if task.runtime.status == status]\n   183\t        return tasks[:limit]\n   184\t\n   185\t    def get_task(self, task_id: str) -> TaskView | None:\n   186\t        try:\n   187\t            return self._store.merged_view(task_id)\n   188\t        except FileNotFoundError:\n   189\t            return None\n   190\t\n   191\t    def read_output(\n   192\t        self,\n   193\t        task_id: str,\n   194\t        *,\n   195\t        offset: int = 0,\n   196\t        max_bytes: int | None = None,\n   197\t    ) -> TaskOutputChunk:\n   198\t        view = self._store.merged_view(task_id)\n   199\t        return self._store.read_output(\n   200\t            task_id,\n   201\t            offset,\n   202\t            max_bytes or self._config.read_max_bytes,\n   203\t            status=view.runtime.status,\n   204\t        )\n   205\t\n   206\t    async def wait(self, task_id: str, *, timeout_s: int = 30) -> TaskView:\n   207\t        end_time = time.monotonic() + timeout_s\n   208\t        while True:\n   209\t            view = self._store.merged_view(task_id)\n   210\t            if is_terminal_status(view.runtime.status):\n   211\t                return view\n   212\t            if time.monotonic() >= end_time:\n   213\t                return view\n   214\t            await asyncio.sleep(self._config.wait_poll_interval_ms / 1000)\n   215\t\n   216\t    def _best_effort_kill(self, runtime: TaskRuntime) -> None:\n   217\t        try:\n   218\t            if os.name == \"nt\":\n   219\t                pid = runtime.child_pid or runtime.worker_pid\n   220\t                if pid is None:\n   221\t                    return\n   222\t                subprocess.run(\n   223\t                    [\"taskkill\", \"/PID\", str(pid), \"/T\", \"/F\"],\n   224\t                    stdout=subprocess.DEVNULL,\n   225\t                    stderr=subprocess.DEVNULL,\n   226\t                    check=False,\n   227\t                )\n   228\t                return\n   229\t\n   230\t            if runtime.child_pgid is not None:\n   231\t                os.killpg(runtime.child_pgid, signal.SIGTERM)\n   232\t                return\n   233\t            if runtime.child_pid is not None:\n   234\t                os.kill(runtime.child_pid, signal.SIGTERM)\n   235\t        except ProcessLookupError:\n   236\t            pass\n   237\t        except Exception:\n   238\t            logger.exception(\"Failed to send best-effort kill signal\")\n   239\t\n   240\t    def kill(self, task_id: str, *, reason: str = \"Killed by user\") -> TaskView:\n   241\t        self._ensure_root()\n   242\t        view = self._store.merged_view(task_id)\n   243\t        if is_terminal_status(view.runtime.status):\n   244\t            return view\n   245\t\n   246\t        control = view.control.model_copy(\n   247\t            update={\n   248\t                \"kill_requested_at\": time.time(),\n   249\t                \"kill_reason\": reason,\n   250\t                \"force\": False,\n   251\t            }\n   252\t        )\n   253\t        self._store.write_control(task_id, control)\n   254\t        self._best_effort_kill(view.runtime)\n   255\t        return self._store.merged_view(task_id)\n   256\t\n   257\t    def recover(self) -> None:\n   258\t        now = time.time()\n   259\t        stale_after = self._config.worker_stale_after_ms / 1000\n   260\t        for view in self._store.list_views():\n   261\t            if is_terminal_status(view.runtime.status):\n   262\t                continue\n   263\t            last_progress_at = (\n   264\t                view.runtime.heartbeat_at\n   265\t                or view.runtime.started_at\n   266\t                or view.runtime.updated_at\n   267\t                or view.spec.created_at\n   268\t            )\n   269\t            if now - last_progress_at <= stale_after:\n   270\t                continue\n   271\t\n   272\t            runtime = view.runtime.model_copy()\n   273\t            runtime.finished_at = now\n   274\t            runtime.updated_at = now\n   275\t            if view.control.kill_requested_at is not None:\n   276\t                runtime.status = \"killed\"\n   277\t                runtime.interrupted = True\n   278\t                runtime.failure_reason = view.control.kill_reason or \"Killed during recovery\"\n   279\t            else:\n   280\t                runtime.status = \"lost\"\n   281\t                runtime.failure_reason = (\n   282\t                    \"Background worker never heartbeat after startup\"\n   283\t                    if view.runtime.heartbeat_at is None\n   284\t                    else \"Background worker heartbeat expired\"\n   285\t                )\n   286\t            self._store.write_runtime(view.spec.id, runtime)\n   287\t\n   288\t    def reconcile(self, *, limit: int | None = None) -> list[str]:\n   289\t        self.recover()\n   290\t        return self.publish_terminal_notifications(limit=limit)\n   291\t\n   292\t    def publish_terminal_notifications(self, *, limit: int | None = None) -> list[str]:\n   293\t        published: list[str] = []\n   294\t        for view in self._store.list_views():\n   295\t            if not is_terminal_status(view.runtime.status):\n   296\t                continue\n   297\t\n   298\t            status = view.runtime.status\n   299\t            terminal_reason = \"timed_out\" if view.runtime.timed_out else status\n   300\t            match terminal_reason:\n   301\t                case \"completed\":\n   302\t                    severity = \"success\"\n   303\t                    title = f\"Background task completed: {view.spec.description}\"\n   304\t                case \"timed_out\":\n   305\t                    severity = \"error\"\n   306\t                    title = f\"Background task timed out: {view.spec.description}\"\n   307\t                case \"failed\":\n   308\t                    severity = \"error\"\n   309\t                    title = f\"Background task failed: {view.spec.description}\"\n   310\t                case \"killed\":\n   311\t                    severity = \"warning\"\n   312\t                    title = f\"Background task stopped: {view.spec.description}\"\n   313\t                case \"lost\":\n   314\t                    severity = \"warning\"\n   315\t                    title = f\"Background task lost: {view.spec.description}\"\n   316\t                case _:\n   317\t                    severity = \"info\"\n   318\t                    title = f\"Background task updated: {view.spec.description}\"\n   319\t\n   320\t            body_lines = [\n   321\t                f\"Task ID: {view.spec.id}\",\n   322\t                f\"Status: {status}\",\n   323\t                f\"Description: {view.spec.description}\",\n   324\t            ]\n   325\t            if terminal_reason != status:\n   326\t                body_lines.append(f\"Terminal reason: {terminal_reason}\")\n   327\t            if view.runtime.exit_code is not None:\n   328\t                body_lines.append(f\"Exit code: {view.runtime.exit_code}\")\n   329\t            if view.runtime.failure_reason:\n   330\t                body_lines.append(f\"Failure reason: {view.runtime.failure_reason}\")\n   331\t\n   332\t            event = NotificationEvent(\n   333\t                id=self._notifications.new_id(),\n   334\t                category=\"task\",\n   335\t                type=f\"task.{terminal_reason}\",\n   336\t                source_kind=\"background_task\",\n   337\t                source_id=view.spec.id,\n   338\t                title=title,\n   339\t                body=\"\\n\".join(body_lines),\n   340\t                severity=severity,\n   341\t                payload={\n   342\t                    \"task_id\": view.spec.id,\n   343\t                    \"task_kind\": view.spec.kind,\n   344\t                    \"status\": status,\n   345\t                    \"description\": view.spec.description,\n   346\t                    \"exit_code\": view.runtime.exit_code,\n   347\t                    \"interrupted\": view.runtime.interrupted,\n   348\t                    \"timed_out\": view.runtime.timed_out,\n   349\t                    \"terminal_reason\": terminal_reason,\n   350\t                    \"failure_reason\": view.runtime.failure_reason,\n   351\t                },\n   352\t                dedupe_key=f\"background_task:{view.spec.id}:{terminal_reason}\",\n   353\t            )\n   354\t            notification = self._notifications.publish(event)\n   355\t            published.append(notification.event.id)\n   356\t            if limit is not None and len(published) >= limit:\n   357\t                break\n   358\t        return published\n", "message": "358 lines read from file starting from line 1. End of file reached.", "display": [], "extras": null}}}}
+{"timestamp": 1773723448.970144, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "\"}"}}}
+{"timestamp": 1773723448.97965, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_XZXYciY6FY2Tl4SHwuh7Elhl", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/tools/background/__init__."}, "extras": null}}}
+{"timestamp": 1773723448.980173, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_DR5VfRHgGe7WZ1dXKSA5Yowh", "return_value": {"is_error": false, "output": "     1\tfrom __future__ import annotations\n     2\t\n     3\timport time\n     4\tfrom typing import Literal\n     5\t\n     6\tfrom pydantic import BaseModel, ConfigDict, Field\n     7\t\n     8\ttype TaskKind = Literal[\"bash\", \"agent\"]\n     9\ttype TaskStatus = Literal[\"created\", \"starting\", \"running\", \"completed\", \"failed\", \"killed\", \"lost\"]\n    10\ttype TaskOwnerRole = Literal[\"root\", \"fixed_subagent\", \"dynamic_subagent\"]\n    11\t\n    12\tTERMINAL_TASK_STATUSES: tuple[TaskStatus, ...] = (\"completed\", \"failed\", \"killed\", \"lost\")\n    13\t\n    14\t\n    15\tdef is_terminal_status(status: TaskStatus) -> bool:\n    16\t    return status in TERMINAL_TASK_STATUSES\n    17\t\n    18\t\n    19\tclass TaskSpec(BaseModel):\n    20\t    model_config = ConfigDict(extra=\"ignore\")\n    21\t\n    22\t    version: int = 1\n    23\t    id: str\n    24\t    kind: TaskKind\n    25\t    session_id: str\n    26\t    description: str\n    27\t    tool_call_id: str\n    28\t    owner_role: TaskOwnerRole = \"root\"\n    29\t    created_at: float = Field(default_factory=time.time)\n    30\t\n    31\t    # Bash-specific fields for V1. Future task types can use kind_payload.\n    32\t    command: str | None = None\n    33\t    shell_name: str | None = None\n    34\t    shell_path: str | None = None\n    35\t    cwd: str | None = None\n    36\t    timeout_s: int | None = None\n    37\t    kind_payload: dict[str, str] | None = None\n    38\t\n    39\t\n    40\tclass TaskRuntime(BaseModel):\n    41\t    model_config = ConfigDict(extra=\"ignore\")\n    42\t\n    43\t    status: TaskStatus = \"created\"\n    44\t    worker_pid: int | None = None\n    45\t    child_pid: int | None = None\n    46\t    child_pgid: int | None = None\n    47\t    started_at: float | None = None\n    48\t    heartbeat_at: float | None = None\n    49\t    updated_at: float = Field(default_factory=time.time)\n    50\t    finished_at: float | None = None\n    51\t    exit_code: int | None = None\n    52\t    interrupted: bool = False\n    53\t    timed_out: bool = False\n    54\t    failure_reason: str | None = None\n    55\t\n    56\t\n    57\tclass TaskControl(BaseModel):\n    58\t    model_config = ConfigDict(extra=\"ignore\")\n    59\t\n    60\t    kill_requested_at: float | None = None\n    61\t    kill_reason: str | None = None\n    62\t    force: bool = False\n    63\t\n    64\t\n    65\tclass TaskConsumerState(BaseModel):\n    66\t    model_config = ConfigDict(extra=\"ignore\")\n    67\t\n    68\t    last_seen_output_size: int = 0\n    69\t    last_viewed_at: float | None = None\n    70\t\n    71\t\n    72\tclass TaskView(BaseModel):\n    73\t    model_config = ConfigDict(extra=\"ignore\")\n    74\t\n    75\t    spec: TaskSpec\n    76\t    runtime: TaskRuntime\n    77\t    control: TaskControl\n    78\t    consumer: TaskConsumerState\n    79\t\n    80\t\n    81\tclass TaskOutputChunk(BaseModel):\n    82\t    model_config = ConfigDict(extra=\"ignore\")\n    83\t\n    84\t    task_id: str\n    85\t    offset: int\n    86\t    next_offset: int\n    87\t    text: str\n    88\t    eof: bool\n    89\t    status: TaskStatus\n", "message": "89 lines read from file starting from line 1. End of file reached.", "display": [], "extras": null}}}}
+{"timestamp": 1773723449.108624, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "py\"}"}}}
+{"timestamp": 1773723449.109539, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.07786941528320312, "context_tokens": 20413, "max_context_tokens": 262144, "token_usage": {"input_other": 3005, "output": 546, "input_cache_read": 17408, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0005", "plan_mode": false}}}
+{"timestamp": 1773723449.120484, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_XZXYciY6FY2Tl4SHwuh7Elhl", "return_value": {"is_error": false, "output": "     1\timport time\n     2\tfrom pathlib import Path\n     3\tfrom typing import override\n     4\t\n     5\tfrom kosong.tooling import CallableTool2, ToolError, ToolReturnValue\n     6\tfrom pydantic import BaseModel, Field\n     7\t\n     8\tfrom example_pkg.background import format_task, format_task_list, list_task_views\n     9\tfrom example_pkg.soul.agent import Runtime\n    10\tfrom example_pkg.soul.approval import Approval\n    11\tfrom example_pkg.tools.display import BackgroundTaskDisplayBlock\n    12\tfrom example_pkg.tools.utils import ToolRejectedError, load_desc\n    13\t\n    14\t\n    15\tdef _ensure_root(runtime: Runtime) -> ToolError | None:\n    16\t    if runtime.role != \"root\":\n    17\t        return ToolError(\n    18\t            message=\"Background tasks can only be managed by the root agent.\",\n    19\t            brief=\"Background task unavailable\",\n    20\t        )\n    21\t    return None\n    22\t\n    23\t\n    24\tdef _task_display(runtime: Runtime, task_id: str) -> BackgroundTaskDisplayBlock:\n    25\t    view = runtime.background_tasks.store.merged_view(task_id)\n    26\t    return BackgroundTaskDisplayBlock(\n    27\t        task_id=view.spec.id,\n    28\t        kind=view.spec.kind,\n    29\t        status=view.runtime.status,\n    30\t        description=view.spec.description,\n    31\t    )\n    32\t\n    33\t\n    34\tdef _format_task_output(view, *, retrieval_status: str, output: str) -> str:\n    35\t    terminal_reason = \"timed_out\" if view.runtime.timed_out else view.runtime.status\n    36\t    lines = [\n    37\t        f\"retrieval_status: {retrieval_status}\",\n    38\t        f\"task_id: {view.spec.id}\",\n    39\t        f\"kind: {view.spec.kind}\",\n    40\t        f\"status: {view.runtime.status}\",\n    41\t        f\"description: {view.spec.description}\",\n    42\t    ]\n    43\t    if view.spec.command:\n    44\t        lines.append(f\"command: {view.spec.command}\")\n    45\t    lines.extend(\n    46\t        [\n    47\t            f\"interrupted: {str(view.runtime.interrupted).lower()}\",\n    48\t            f\"timed_out: {str(view.runtime.timed_out).lower()}\",\n    49\t            f\"terminal_reason: {terminal_reason}\",\n    50\t        ]\n    51\t    )\n    52\t    if view.runtime.exit_code is not None:\n    53\t        lines.append(f\"exit_code: {view.runtime.exit_code}\")\n    54\t    if view.runtime.failure_reason:\n    55\t        lines.append(f\"reason: {view.runtime.failure_reason}\")\n    56\t    return \"\\n\".join(\n    57\t        lines\n    58\t        + [\n    59\t            \"\",\n    60\t            output or \"[no output available]\",\n    61\t        ]\n    62\t    )\n    63\t\n    64\t\n    65\tclass TaskOutputParams(BaseModel):\n    66\t    task_id: str = Field(description=\"The background task ID to inspect.\")\n    67\t    block: bool = Field(\n    68\t        default=True,\n    69\t        description=\"Whether to wait for the task to finish before returning.\",\n    70\t    )\n    71\t    timeout: int = Field(\n    72\t        default=30,\n    73\t        ge=0,\n    74\t        le=3600,\n    75\t        description=\"Maximum number of seconds to wait when block=true.\",\n    76\t    )\n    77\t\n    78\t\n    79\tclass TaskStopParams(BaseModel):\n    80\t    task_id: str = Field(description=\"The background task ID to stop.\")\n    81\t    reason: str = Field(\n    82\t        default=\"Stopped by TaskStop\",\n    83\t        description=\"Short reason recorded when the task is stopped.\",\n    84\t    )\n    85\t\n    86\t\n    87\tclass TaskListParams(BaseModel):\n    88\t    active_only: bool = Field(\n    89\t        default=True,\n    90\t        description=\"Whether to list only non-terminal background tasks.\",\n    91\t    )\n    92\t    limit: int = Field(\n    93\t        default=20,\n    94\t        ge=1,\n    95\t        le=100,\n    96\t        description=\"Maximum number of tasks to return.\",\n    97\t    )\n    98\t\n    99\t\n   100\tclass TaskList(CallableTool2[TaskListParams]):\n   101\t    name: str = \"TaskList\"\n   102\t    description: str = load_desc(Path(__file__).parent / \"list.md\")\n   103\t    params: type[TaskListParams] = TaskListParams\n   104\t\n   105\t    def __init__(self, runtime: Runtime):\n   106\t        super().__init__()\n   107\t        self._runtime = runtime\n   108\t\n   109\t    @override\n   110\t    async def __call__(self, params: TaskListParams) -> ToolReturnValue:\n   111\t        if err := _ensure_root(self._runtime):\n   112\t            return err\n   113\t\n   114\t        views = list_task_views(\n   115\t            self._runtime.background_tasks,\n   116\t            active_only=params.active_only,\n   117\t            limit=params.limit,\n   118\t        )\n   119\t        display = [\n   120\t            BackgroundTaskDisplayBlock(\n   121\t                task_id=view.spec.id,\n   122\t                kind=view.spec.kind,\n   123\t                status=view.runtime.status,\n   124\t                description=view.spec.description,\n   125\t            )\n   126\t            for view in views\n   127\t        ]\n   128\t        return ToolReturnValue(\n   129\t            is_error=False,\n   130\t            output=format_task_list(views, active_only=params.active_only),\n   131\t            message=\"Task list retrieved.\",\n   132\t            display=display,\n   133\t        )\n   134\t\n   135\t\n   136\tclass TaskOutput(CallableTool2[TaskOutputParams]):\n   137\t    name: str = \"TaskOutput\"\n   138\t    description: str = load_desc(Path(__file__).parent / \"output.md\")\n   139\t    params: type[TaskOutputParams] = TaskOutputParams\n   140\t\n   141\t    def __init__(self, runtime: Runtime):\n   142\t        super().__init__()\n   143\t        self._runtime = runtime\n   144\t\n   145\t    @override\n   146\t    async def __call__(self, params: TaskOutputParams) -> ToolReturnValue:\n   147\t        if err := _ensure_root(self._runtime):\n   148\t            return err\n   149\t\n   150\t        view = self._runtime.background_tasks.get_task(params.task_id)\n   151\t        if view is None:\n   152\t            return ToolError(message=f\"Task not found: {params.task_id}\", brief=\"Task not found\")\n   153\t\n   154\t        if params.block:\n   155\t            view = await self._runtime.background_tasks.wait(\n   156\t                params.task_id,\n   157\t                timeout_s=params.timeout,\n   158\t            )\n   159\t            retrieval_status = (\n   160\t                \"success\"\n   161\t                if view.runtime.status in {\"completed\", \"failed\", \"killed\", \"lost\"}\n   162\t                else \"timeout\"\n   163\t            )\n   164\t        else:\n   165\t            retrieval_status = (\n   166\t                \"success\"\n   167\t                if view.runtime.status in {\"completed\", \"failed\", \"killed\", \"lost\"}\n   168\t                else \"not_ready\"\n   169\t            )\n   170\t\n   171\t        output = self._runtime.background_tasks.store.tail_output(\n   172\t            params.task_id,\n   173\t            max_bytes=self._runtime.config.background.read_max_bytes,\n   174\t            max_lines=self._runtime.config.background.notification_tail_lines,\n   175\t        )\n   176\t        consumer = view.consumer.model_copy(\n   177\t            update={\n   178\t                \"last_seen_output_size\": self._runtime.background_tasks.store.output_path(\n   179\t                    params.task_id\n   180\t                ).stat().st_size,\n   181\t                \"last_viewed_at\": time.time(),\n   182\t            }\n   183\t        )\n   184\t        self._runtime.background_tasks.store.write_consumer(params.task_id, consumer)\n   185\t\n   186\t        return ToolReturnValue(\n   187\t            is_error=False,\n   188\t            output=_format_task_output(view, retrieval_status=retrieval_status, output=output),\n   189\t            message=\"Task output retrieved.\",\n   190\t            display=[_task_display(self._runtime, params.task_id)],\n   191\t        )\n   192\t\n   193\t\n   194\tclass TaskStop(CallableTool2[TaskStopParams]):\n   195\t    name: str = \"TaskStop\"\n   196\t    description: str = load_desc(Path(__file__).parent / \"stop.md\")\n   197\t    params: type[TaskStopParams] = TaskStopParams\n   198\t\n   199\t    def __init__(self, runtime: Runtime, approval: Approval):\n   200\t        super().__init__()\n   201\t        self._runtime = runtime\n   202\t        self._approval = approval\n   203\t\n   204\t    @override\n   205\t    async def __call__(self, params: TaskStopParams) -> ToolReturnValue:\n   206\t        if err := _ensure_root(self._runtime):\n   207\t            return err\n   208\t        if self._runtime.session.state.plan_mode:\n   209\t            return ToolError(\n   210\t                message=\"TaskStop is not available in plan mode.\",\n   211\t                brief=\"Blocked in plan mode\",\n   212\t            )\n   213\t\n   214\t        view = self._runtime.background_tasks.get_task(params.task_id)\n   215\t        if view is None:\n   216\t            return ToolError(message=f\"Task not found: {params.task_id}\", brief=\"Task not found\")\n   217\t\n   218\t        if not await self._approval.request(\n   219\t            self.name,\n   220\t            \"stop background task\",\n   221\t            f\"Stop background task `{params.task_id}`\",\n   222\t            display=[_task_display(self._runtime, params.task_id)],\n   223\t        ):\n   224\t            return ToolRejectedError()\n   225\t\n   226\t        view = self._runtime.background_tasks.kill(\n   227\t            params.task_id,\n   228\t            reason=params.reason.strip() or \"Stopped by TaskStop\",\n   229\t        )\n   230\t        return ToolReturnValue(\n   231\t            is_error=False,\n   232\t            output=format_task(view, include_command=True),\n   233\t            message=\"Task stop requested.\",\n   234\t            display=[_task_display(self._runtime, params.task_id)],\n   235\t        )\n", "message": "235 lines read from file starting from line 1. End of file reached.", "display": [], "extras": null}}}}
+{"timestamp": 1773723449.122577, "message": {"type": "StepBegin", "payload": {"n": 3}}}
+{"timestamp": 1773723452.898418, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "好的，我已经读取了关键的事实来源。现在让我继续读取其他重要文件来理解完整的功能边界：\n\n1. Shell 工具的后台模式支持\n2. Notification 系统\n3. Wire 协议更新\n4. KimiSoul 中的 notification 集成\n\n让我继续读取这些文件。", "encrypted": null}}}
+{"timestamp": 1773723453.859943, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_4vAGVbvQFNnyAFHtAkgnKwUu", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/tools/shell/__init__.py\"}"}, "extras": null}}}
+{"timestamp": 1773723453.8748102, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_YRsRNEO743zdY5vBEYPYv5QJ", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/notifications/manager.py"}, "extras": null}}}
+{"timestamp": 1773723453.875499, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_4vAGVbvQFNnyAFHtAkgnKwUu", "return_value": {"is_error": false, "output": "     1\timport asyncio\n     2\tfrom collections.abc import Callable\n     3\tfrom pathlib import Path\n     4\tfrom typing import Self, override\n     5\t\n     6\timport kaos\n     7\tfrom kaos import AsyncReadable\n     8\tfrom kosong.tooling import CallableTool2, ToolReturnValue\n     9\tfrom pydantic import BaseModel, Field, model_validator\n    10\t\n    11\tfrom example_pkg.background import TaskView, format_task\n    12\tfrom example_pkg.soul.agent import Runtime\n    13\tfrom example_pkg.soul.approval import Approval\n    14\tfrom example_pkg.soul.toolset import get_current_tool_call_or_none\n    15\tfrom example_pkg.tools.display import BackgroundTaskDisplayBlock, ShellDisplayBlock\n    16\tfrom example_pkg.tools.utils import ToolRejectedError, ToolResultBuilder, load_desc\n    17\tfrom example_pkg.utils.environment import Environment\n    18\tfrom example_pkg.utils.subprocess_env import get_clean_env\n    19\t\n    20\tMAX_TIMEOUT = 24 * 60 * 60\n    21\t\n    22\t\n    23\tclass Params(BaseModel):\n    24\t    command: str = Field(description=\"The bash command to execute.\")\n    25\t    timeout: int = Field(\n    26\t        description=(\n    27\t            \"The timeout in seconds for the command to execute. \"\n    28\t            \"If the command takes longer than this, it will be killed.\"\n    29\t        ),\n    30\t        default=60,\n    31\t        ge=1,\n    32\t        le=MAX_TIMEOUT,\n    33\t    )\n    34\t    run_in_background: bool = Field(\n    35\t        default=False,\n    36\t        description=\"Whether to run the command as a background task.\",\n    37\t    )\n    38\t    description: str = Field(\n    39\t        default=\"\",\n    40\t        description=(\n    41\t            \"A short description for the background task. Required when run_in_background=true.\"\n    42\t        ),\n    43\t    )\n    44\t\n    45\t    @model_validator(mode=\"after\")\n    46\t    def _validate_background_fields(self) -> Self:\n    47\t        if self.run_in_background and not self.description.strip():\n    48\t            raise ValueError(\"description is required when run_in_background is true\")\n    49\t        return self\n    50\t\n    51\t\n    52\tclass Shell(CallableTool2[Params]):\n    53\t    name: str = \"Shell\"\n    54\t    params: type[Params] = Params\n    55\t\n    56\t    def __init__(self, approval: Approval, environment: Environment, runtime: Runtime):\n    57\t        is_powershell = environment.shell_name == \"Windows PowerShell\"\n    58\t        super().__init__(\n    59\t            description=load_desc(\n    60\t                Path(__file__).parent / (\"powershell.md\" if is_powershell else \"bash.md\"),\n    61\t                {\"SHELL\": f\"{environment.shell_name} (`{environment.shell_path}`)\"},\n    62\t            )\n    63\t        )\n    64\t        self._approval = approval\n    65\t        self._is_powershell = is_powershell\n    66\t        self._shell_path = environment.shell_path\n    67\t        self._runtime = runtime\n    68\t\n    69\t    @override\n    70\t    async def __call__(self, params: Params) -> ToolReturnValue:\n    71\t        builder = ToolResultBuilder()\n    72\t\n    73\t        if not params.command:\n    74\t            return builder.error(\"Command cannot be empty.\", brief=\"Empty command\")\n    75\t\n    76\t        if self._runtime.session.state.plan_mode:\n    77\t            return builder.error(\n    78\t                \"Shell is not available in plan mode.\",\n    79\t                brief=\"Blocked in plan mode\",\n    80\t            )\n    81\t\n    82\t        if params.run_in_background:\n    83\t            return await self._run_in_background(params)\n    84\t\n    85\t        if not await self._approval.request(\n    86\t            self.name,\n    87\t            \"run command\",\n    88\t            f\"Run command `{params.command}`\",\n    89\t            display=[\n    90\t                ShellDisplayBlock(\n    91\t                    language=\"powershell\" if self._is_powershell else \"bash\",\n    92\t                    command=params.command,\n    93\t                )\n    94\t            ],\n    95\t        ):\n    96\t            return ToolRejectedError()\n    97\t\n    98\t        def stdout_cb(line: bytes):\n    99\t            line_str = line.decode(encoding=\"utf-8\", errors=\"replace\")\n   100\t            builder.write(line_str)\n   101\t\n   102\t        def stderr_cb(line: bytes):\n   103\t            line_str = line.decode(encoding=\"utf-8\", errors=\"replace\")\n   104\t            builder.write(line_str)\n   105\t\n   106\t        try:\n   107\t            exitcode = await self._run_shell_command(\n   108\t                params.command, stdout_cb, stderr_cb, params.timeout\n   109\t            )\n   110\t\n   111\t            if exitcode == 0:\n   112\t                return builder.ok(\"Command executed successfully.\")\n   113\t            else:\n   114\t                return builder.error(\n   115\t                    f\"Command failed with exit code: {exitcode}.\",\n   116\t                    brief=f\"Failed with exit code: {exitcode}\",\n   117\t                )\n   118\t        except TimeoutError:\n   119\t            return builder.error(\n   120\t                f\"Command killed by timeout ({params.timeout}s)\",\n   121\t                brief=f\"Killed by timeout ({params.timeout}s)\",\n   122\t            )\n   123\t\n   124\t    async def _run_in_background(self, params: Params) -> ToolReturnValue:\n   125\t        tool_call = get_current_tool_call_or_none()\n   126\t        assert tool_call is not None, \"Background shell requires a tool call context\"\n   127\t\n   128\t        if not await self._approval.request(\n   129\t            self.name,\n   130\t            \"run background command\",\n   131\t            f\"Run background command `{params.command}`\",\n   132\t            display=[\n   133\t                ShellDisplayBlock(\n   134\t                    language=\"powershell\" if self._is_powershell else \"bash\",\n   135\t                    command=params.command,\n   136\t                )\n   137\t            ],\n   138\t        ):\n   139\t            return ToolRejectedError()\n   140\t\n   141\t        try:\n   142\t            view = self._runtime.background_tasks.create_bash_task(\n   143\t                command=params.command,\n   144\t                description=params.description.strip(),\n   145\t                timeout_s=params.timeout,\n   146\t                tool_call_id=tool_call.id,\n   147\t                shell_name=\"Windows PowerShell\" if self._is_powershell else \"bash\",\n   148\t                shell_path=str(self._shell_path),\n   149\t                cwd=str(self._runtime.session.work_dir),\n   150\t            )\n   151\t        except Exception as exc:\n   152\t            builder = ToolResultBuilder()\n   153\t            return builder.error(f\"Failed to start background task: {exc}\", brief=\"Start failed\")\n   154\t\n   155\t        return self._background_ok(view)\n   156\t\n   157\t    def _background_ok(self, view: TaskView) -> ToolReturnValue:\n   158\t        builder = ToolResultBuilder()\n   159\t        builder.write(\n   160\t            \"\\n\".join(\n   161\t                [\n   162\t                    format_task(view, include_command=True),\n   163\t                    \"automatic_notification: true\",\n   164\t                    \"next_step: You will be automatically notified when it completes.\",\n   165\t                    (\n   166\t                        \"next_step: Use TaskOutput with this task_id \"\n   167\t                        \"if you need progress or want to wait.\"\n   168\t                    ),\n   169\t                    \"next_step: Use TaskStop only if the task must be cancelled.\",\n   170\t                ]\n   171\t            )\n   172\t        )\n   173\t        builder.display(\n   174\t            BackgroundTaskDisplayBlock(\n   175\t                task_id=view.spec.id,\n   176\t                kind=view.spec.kind,\n   177\t                status=view.runtime.status,\n   178\t                description=view.spec.description,\n   179\t            )\n   180\t        )\n   181\t        return builder.ok(\"Background task started\", brief=f\"Started {view.spec.id}\")\n   182\t\n   183\t    async def _run_shell_command(\n   184\t        self,\n   185\t        command: str,\n   186\t        stdout_cb: Callable[[bytes], None],\n   187\t        stderr_cb: Callable[[bytes], None],\n   188\t        timeout: int,\n   189\t    ) -> int:\n   190\t        async def _read_stream(stream: AsyncReadable, cb: Callable[[bytes], None]):\n   191\t            while True:\n   192\t                line = await stream.readline()\n   193\t                if line:\n   194\t                    cb(line)\n   195\t                else:\n   196\t                    break\n   197\t\n   198\t        process = await kaos.exec(*self._shell_args(command), env=get_clean_env())\n   199\t\n   200\t        try:\n   201\t            await asyncio.wait_for(\n   202\t                asyncio.gather(\n   203\t                    _read_stream(process.stdout, stdout_cb),\n   204\t                    _read_stream(process.stderr, stderr_cb),\n   205\t                ),\n   206\t                timeout,\n   207\t            )\n   208\t            return await process.wait()\n   209\t        except TimeoutError:\n   210\t            await process.kill()\n   211\t            raise\n   212\t\n   213\t    def _shell_args(self, command: str) -> tuple[str, ...]:\n   214\t        if self._is_powershell:\n   215\t            return (str(self._shell_path), \"-command\", command)\n   216\t        return (str(self._shell_path), \"-c\", command)\n", "message": "216 lines read from file starting from line 1. End of file reached.", "display": [], "extras": null}}}}
+{"timestamp": 1773723454.390254, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "\"}"}}}
+{"timestamp": 1773723454.399585, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_Zi0gi1gBQijIF8lEEx1RiSPz", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/wire/types.py"}, "extras": null}}}
+{"timestamp": 1773723454.4001331, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_YRsRNEO743zdY5vBEYPYv5QJ", "return_value": {"is_error": false, "output": "     1\tfrom __future__ import annotations\n     2\t\n     3\timport time\n     4\timport uuid\n     5\tfrom pathlib import Path\n     6\t\n     7\tfrom example_pkg.config import NotificationConfig\n     8\t\n     9\tfrom .models import (\n    10\t    NotificationDelivery,\n    11\t    NotificationEvent,\n    12\t    NotificationSink,\n    13\t    NotificationSinkState,\n    14\t    NotificationView,\n    15\t)\n    16\tfrom .store import NotificationStore\n    17\t\n    18\t\n    19\tclass NotificationManager:\n    20\t    def __init__(self, root: Path, config: NotificationConfig) -> None:\n    21\t        self._config = config\n    22\t        self._store = NotificationStore(root)\n    23\t\n    24\t    @property\n    25\t    def store(self) -> NotificationStore:\n    26\t        return self._store\n    27\t\n    28\t    def new_id(self) -> str:\n    29\t        return f\"n{uuid.uuid4().hex[:8]}\"\n    30\t\n    31\t    def _initial_delivery(self, event: NotificationEvent) -> NotificationDelivery:\n    32\t        return NotificationDelivery(\n    33\t            sinks={sink: NotificationSinkState() for sink in event.targets}\n    34\t        )\n    35\t\n    36\t    def find_by_dedupe_key(self, dedupe_key: str) -> NotificationView | None:\n    37\t        for view in self._store.list_views():\n    38\t            if view.event.dedupe_key == dedupe_key:\n    39\t                return view\n    40\t        return None\n    41\t\n    42\t    def publish(self, event: NotificationEvent) -> NotificationView:\n    43\t        if event.dedupe_key:\n    44\t            existing = self.find_by_dedupe_key(event.dedupe_key)\n    45\t            if existing is not None:\n    46\t                return existing\n    47\t        delivery = self._initial_delivery(event)\n    48\t        self._store.create_notification(event, delivery)\n    49\t        return NotificationView(event=event, delivery=delivery)\n    50\t\n    51\t    def recover(self) -> None:\n    52\t        now = time.time()\n    53\t        stale_after = self._config.claim_stale_after_ms / 1000\n    54\t        for view in self._store.list_views():\n    55\t            updated = False\n    56\t            delivery = view.delivery.model_copy(deep=True)\n    57\t            for sink_state in delivery.sinks.values():\n    58\t                if sink_state.status != \"claimed\" or sink_state.claimed_at is None:\n    59\t                    continue\n    60\t                if now - sink_state.claimed_at <= stale_after:\n    61\t                    continue\n    62\t                sink_state.status = \"pending\"\n    63\t                sink_state.claimed_at = None\n    64\t                updated = True\n    65\t            if updated:\n    66\t                self._store.write_delivery(view.event.id, delivery)\n    67\t\n    68\t    def claim_for_sink(self, sink: NotificationSink, *, limit: int = 8) -> list[NotificationView]:\n    69\t        self.recover()\n    70\t        claimed: list[NotificationView] = []\n    71\t        now = time.time()\n    72\t        for view in reversed(self._store.list_views()):\n    73\t            sink_state = view.delivery.sinks.get(sink)\n    74\t            if sink_state is None or sink_state.status == \"acked\":\n    75\t                continue\n    76\t            if sink_state.status == \"claimed\":\n    77\t                continue\n    78\t            delivery = view.delivery.model_copy(deep=True)\n    79\t            target_state = delivery.sinks[sink]\n    80\t            target_state.status = \"claimed\"\n    81\t            target_state.claimed_at = now\n    82\t            self._store.write_delivery(view.event.id, delivery)\n    83\t            claimed.append(NotificationView(event=view.event, delivery=delivery))\n    84\t            if len(claimed) >= limit:\n    85\t                break\n    86\t        return claimed\n    87\t\n    88\t    def ack(self, sink: NotificationSink, notification_id: str) -> NotificationView:\n    89\t        view = self._store.merged_view(notification_id)\n    90\t        delivery = view.delivery.model_copy(deep=True)\n    91\t        sink_state = delivery.sinks.get(sink)\n    92\t        if sink_state is None:\n    93\t            return view\n    94\t        sink_state.status = \"acked\"\n    95\t        sink_state.acked_at = time.time()\n    96\t        sink_state.claimed_at = None\n    97\t        self._store.write_delivery(notification_id, delivery)\n    98\t        return NotificationView(event=view.event, delivery=delivery)\n    99\t\n   100\t    def ack_ids(self, sink: NotificationSink, notification_ids: set[str]) -> None:\n   101\t        for notification_id in notification_ids:\n   102\t            try:\n   103\t                self.ack(sink, notification_id)\n   104\t            except FileNotFoundError:\n   105\t                continue\n", "message": "105 lines read from file starting from line 1. End of file reached.", "display": [], "extras": null}}}}
+{"timestamp": 1773723454.981337, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "\"}"}}}
+{"timestamp": 1773723455.023919, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_SorRMdJIzuUdPESVPYIbDqQU", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/soul/kimisoul.py"}, "extras": null}}}
+{"timestamp": 1773723455.024417, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_Zi0gi1gBQijIF8lEEx1RiSPz", "return_value": {"is_error": false, "output": "     1\tfrom __future__ import annotations\n     2\t\n     3\timport asyncio\n     4\tfrom typing import Any, Literal, TypeGuard, cast\n     5\t\n     6\tfrom kosong.chat_provider import TokenUsage\n     7\tfrom kosong.message import (\n     8\t    AudioURLPart,\n     9\t    ContentPart,\n    10\t    ImageURLPart,\n    11\t    TextPart,\n    12\t    ThinkPart,\n    13\t    ToolCall,\n    14\t    ToolCallPart,\n    15\t    VideoURLPart,\n    16\t)\n    17\tfrom kosong.tooling import (\n    18\t    BriefDisplayBlock,\n    19\t    DisplayBlock,\n    20\t    ToolResult,\n    21\t    ToolReturnValue,\n    22\t    UnknownDisplayBlock,\n    23\t)\n    24\tfrom kosong.utils.typing import JsonType\n    25\tfrom pydantic import BaseModel, Field, field_serializer, field_validator\n    26\t\n    27\tfrom example_pkg.tools.display import (\n    28\t    BackgroundTaskDisplayBlock,\n    29\t    DiffDisplayBlock,\n    30\t    ShellDisplayBlock,\n    31\t    TodoDisplayBlock,\n    32\t    TodoDisplayItem,\n    33\t)\n    34\tfrom example_pkg.utils.typing import flatten_union\n    35\t\n    36\t\n    37\tclass TurnBegin(BaseModel):\n    38\t    \"\"\"\n    39\t    Indicates the beginning of a new agent turn.\n    40\t    This event must be sent before any other event in the turn.\n    41\t    \"\"\"\n    42\t\n    43\t    user_input: str | list[ContentPart]\n    44\t\n    45\t\n    46\tclass TurnEnd(BaseModel):\n    47\t    \"\"\"\n    48\t    Indicates the end of the current agent turn.\n    49\t    This event must be sent after all other events in the turn.\n    50\t    If the turn is interrupted, this event may be omitted.\n    51\t    \"\"\"\n    52\t\n    53\t    pass\n    54\t\n    55\t\n    56\tclass StepBegin(BaseModel):\n    57\t    \"\"\"\n    58\t    Indicates the beginning of a new agent step.\n    59\t    This event must be sent before any other event in the step.\n    60\t    \"\"\"\n    61\t\n    62\t    n: int\n    63\t    \"\"\"The step number.\"\"\"\n    64\t\n    65\t\n    66\tclass StepInterrupted(BaseModel):\n    67\t    \"\"\"Indicates the current step was interrupted, either by user intervention or an error.\"\"\"\n    68\t\n    69\t    pass\n    70\t\n    71\t\n    72\tclass CompactionBegin(BaseModel):\n    73\t    \"\"\"\n    74\t    Indicates that a compaction just began.\n    75\t    This event must be sent during a step, which means, between `StepBegin` and the next\n    76\t    `StepBegin` or `StepInterrupted`. And, there must be a `CompactionEnd` directly following\n    77\t    this event.\n    78\t    \"\"\"\n    79\t\n    80\t    pass\n    81\t\n    82\t\n    83\tclass CompactionEnd(BaseModel):\n    84\t    \"\"\"\n    85\t    Indicates that a compaction just ended.\n    86\t    This event must be sent directly after a `CompactionBegin` event.\n    87\t    \"\"\"\n    88\t\n    89\t    pass\n    90\t\n    91\t\n    92\tclass MCPLoadingBegin(BaseModel):\n    93\t    \"\"\"Indicates that MCP tool loading is in progress.\"\"\"\n    94\t\n    95\t    pass\n    96\t\n    97\t\n    98\tclass MCPLoadingEnd(BaseModel):\n    99\t    \"\"\"Indicates that MCP tool loading has finished.\"\"\"\n   100\t\n   101\t    pass\n   102\t\n   103\t\n   104\tclass StatusUpdate(BaseModel):\n   105\t    \"\"\"\n   106\t    An update on the current status of the soul.\n   107\t    None fields indicate no change from the previous status.\n   108\t    \"\"\"\n   109\t\n   110\t    context_usage: float | None = None\n   111\t    \"\"\"The usage of the context, in percentage.\"\"\"\n   112\t    context_tokens: int | None = None\n   113\t    \"\"\"The number of tokens currently in the context.\"\"\"\n   114\t    max_context_tokens: int | None = None\n   115\t    \"\"\"The maximum number of tokens the context can hold.\"\"\"\n   116\t    token_usage: TokenUsage | None = None\n   117\t    \"\"\"The token usage statistics of the current step.\"\"\"\n   118\t    message_id: str | None = None\n   119\t    \"\"\"The message ID of the current step.\"\"\"\n   120\t    plan_mode: bool | None = None\n   121\t    \"\"\"Whether plan mode (read-only) is active. None means no change.\"\"\"\n   122\t\n   123\t\n   124\tclass Notification(BaseModel):\n   125\t    \"\"\"A generic system notification for UI and client consumption.\"\"\"\n   126\t\n   127\t    id: str\n   128\t    category: str\n   129\t    type: str\n   130\t    source_kind: str\n   131\t    source_id: str\n   132\t    title: str\n   133\t    body: str\n   134\t    severity: str\n   135\t    created_at: float\n   136\t    payload: dict[str, JsonType] = Field(default_factory=dict)\n   137\t\n   138\t\n   139\tclass SubagentEvent(BaseModel):\n   140\t    \"\"\"\n   141\t    An event from a subagent.\n   142\t    \"\"\"\n   143\t\n   144\t    task_tool_call_id: str\n   145\t    \"\"\"The ID of the task tool call associated with this subagent.\"\"\"\n   146\t    event: Event\n   147\t    \"\"\"The event from the subagent.\"\"\"\n   148\t    # TODO: maybe restrict the event types? to exclude approval request, etc.\n   149\t\n   150\t    @field_serializer(\"event\", when_used=\"json\")\n   151\t    def _serialize_event(self, event: Event) -> dict[str, Any]:\n   152\t        envelope = WireMessageEnvelope.from_wire_message(event)\n   153\t        return envelope.model_dump(mode=\"json\")\n   154\t\n   155\t    @field_validator(\"event\", mode=\"before\")\n   156\t    @classmethod\n   157\t    def _validate_event(cls, value: Any) -> Event:\n   158\t        if is_wire_message(value):\n   159\t            if is_event(value):\n   160\t                return value\n   161\t            raise ValueError(\"SubagentEvent event must be an Event\")\n   162\t\n   163\t        if not isinstance(value, dict):\n   164\t            raise ValueError(\"SubagentEvent event must be a dict\")\n   165\t        event_type = cast(dict[str, Any], value).get(\"type\")\n   166\t        event_payload = cast(dict[str, Any], value).get(\"payload\")\n   167\t        envelope = WireMessageEnvelope.model_validate(\n   168\t            {\"type\": event_type, \"payload\": event_payload}\n   169\t        )\n   170\t        event = envelope.to_wire_message()\n   171\t        if not is_event(event):\n   172\t            raise ValueError(\"SubagentEvent event must be an Event\")\n   173\t        return event\n   174\t\n   175\t\n   176\tclass ApprovalResponse(BaseModel):\n   177\t    \"\"\"\n   178\t    Indicates that an approval request has been resolved.\n   179\t    \"\"\"\n   180\t\n   181\t    type Kind = Literal[\"approve\", \"approve_for_session\", \"reject\"]\n   182\t\n   183\t    request_id: str\n   184\t    \"\"\"The ID of the resolved approval request.\"\"\"\n   185\t    response: Kind\n   186\t    \"\"\"The response to the approval request.\"\"\"\n   187\t\n   188\t\n   189\tclass ApprovalRequest(BaseModel):\n   190\t    \"\"\"\n   191\t    A request for user approval before proceeding with an action.\n   192\t    \"\"\"\n   193\t\n   194\t    id: str\n   195\t    tool_call_id: str\n   196\t    sender: str\n   197\t    action: str\n   198\t    description: str\n   199\t    display: list[DisplayBlock] = Field(default_factory=list[DisplayBlock])\n   200\t    \"\"\"Defaults to an empty list for backwards-compatible wire.jsonl loading.\"\"\"\n   201\t\n   202\t    # Note that the above fields are just a copy of `example_pkg.soul.approval.Request`, but\n   203\t    # we cannot directly use that class here because we want to avoid dependency from Wire\n   204\t    # to Soul.\n   205\t\n   206\t    def __init__(self, **kwargs: Any) -> None:\n   207\t        super().__init__(**kwargs)\n   208\t        self._future: asyncio.Future[ApprovalResponse.Kind] | None = None\n   209\t\n   210\t    def _get_future(self) -> asyncio.Future[ApprovalResponse.Kind]:\n   211\t        if self._future is None:\n   212\t            self._future = asyncio.get_event_loop().create_future()\n   213\t        return self._future\n   214\t\n   215\t    async def wait(self) -> ApprovalResponse.Kind:\n   216\t        \"\"\"\n   217\t        Wait for the request to be resolved or cancelled.\n   218\t\n   219\t        Returns:\n   220\t            ApprovalResponse.Kind: The response to the approval request.\n   221\t        \"\"\"\n   222\t        return await self._get_future()\n   223\t\n   224\t    def resolve(self, response: ApprovalResponse.Kind) -> None:\n   225\t        \"\"\"\n   226\t        Resolve the approval request with the given response.\n   227\t        This will cause the `wait()` method to return the response.\n   228\t        \"\"\"\n   229\t        future = self._get_future()\n   230\t        if not future.done():\n   231\t            future.set_result(response)\n   232\t\n   233\t    @property\n   234\t    def resolved(self) -> bool:\n   235\t        \"\"\"Whether the request is resolved.\"\"\"\n   236\t        return self._future is not None and self._future.done()\n   237\t\n   238\t\n   239\tclass QuestionOption(BaseModel):\n   240\t    \"\"\"A single option for a question.\"\"\"\n   241\t\n   242\t    label: str\n   243\t    \"\"\"The display text for this option.\"\"\"\n   244\t    description: str = \"\"\n   245\t    \"\"\"Explanation of what this option means.\"\"\"\n   246\t\n   247\t\n   248\tclass QuestionItem(BaseModel):\n   249\t    \"\"\"A single question to ask the user.\"\"\"\n   250\t\n   251\t    question: str\n   252\t    \"\"\"The complete question text.\"\"\"\n   253\t    header: str = \"\"\n   254\t    \"\"\"Short label displayed as a tag (max 12 chars).\"\"\"\n   255\t    options: list[QuestionOption]\n   256\t    \"\"\"The available choices for this question (2-4 options).\"\"\"\n   257\t    multi_select: bool = False\n   258\t    \"\"\"Whether multiple options can be selected.\"\"\"\n   259\t    body: str = \"\"\n   260\t    \"\"\"Optional body content (markdown) displayed above options.\"\"\"\n   261\t    other_label: str = \"\"\n   262\t    \"\"\"Custom label for the synthetic 'Other' free-text option. Empty uses default.\"\"\"\n   263\t    other_description: str = \"\"\n   264\t    \"\"\"Custom description for the synthetic 'Other' option. Empty uses default.\"\"\"\n   265\t\n   266\t\n   267\tclass QuestionResponse(BaseModel):\n   268\t    \"\"\"Response to a question request.\"\"\"\n   269\t\n   270\t    request_id: str\n   271\t    \"\"\"The ID of the resolved question request.\"\"\"\n   272\t    answers: dict[str, str]\n   273\t    \"\"\"Mapping from question text to selected option label(s). Multi-select answers are\n   274\t    comma-separated.\"\"\"\n   275\t\n   276\t\n   277\tclass QuestionNotSupported(Exception):\n   278\t    \"\"\"Raised when the connected client does not support interactive questions.\"\"\"\n   279\t\n   280\t\n   281\tclass QuestionRequest(BaseModel):\n   282\t    \"\"\"\n   283\t    A request to ask the user structured questions during execution.\n   284\t    \"\"\"\n   285\t\n   286\t    id: str\n   287\t    \"\"\"The unique request ID.\"\"\"\n   288\t    tool_call_id: str\n   289\t    \"\"\"The ID of the tool call that initiated this question.\"\"\"\n   290\t    questions: list[QuestionItem]\n   291\t    \"\"\"The questions to ask the user (1-4 questions).\"\"\"\n   292\t\n   293\t    def __init__(self, **kwargs: Any) -> None:\n   294\t        super().__init__(**kwargs)\n   295\t        self._future: asyncio.Future[dict[str, str]] | None = None\n   296\t\n   297\t    def _get_future(self) -> asyncio.Future[dict[str, str]]:\n   298\t        if self._future is None:\n   299\t            self._future = asyncio.get_event_loop().create_future()\n   300\t        return self._future\n   301\t\n   302\t    async def wait(self) -> dict[str, str]:\n   303\t        \"\"\"\n   304\t        Wait for the question to be answered.\n   305\t\n   306\t        Returns:\n   307\t            dict[str, str]: Mapping from question text to answer.\n   308\t        \"\"\"\n   309\t        return await self._get_future()\n   310\t\n   311\t    def resolve(self, answers: dict[str, str]) -> None:\n   312\t        \"\"\"\n   313\t        Resolve the question request with the given answers.\n   314\t        This will cause the `wait()` method to return the answers.\n   315\t        \"\"\"\n   316\t        future = self._get_future()\n   317\t        if not future.done():\n   318\t            future.set_result(answers)\n   319\t\n   320\t    def set_exception(self, exc: BaseException) -> None:\n   321\t        \"\"\"Resolve the question request with an exception.\"\"\"\n   322\t        future = self._get_future()\n   323\t        if not future.done():\n   324\t            future.set_exception(exc)\n   325\t\n   326\t    @property\n   327\t    def resolved(self) -> bool:\n   328\t        \"\"\"Whether the question request is resolved.\"\"\"\n   329\t        return self._future is not None and self._future.done()\n   330\t\n   331\t\n   332\tclass ToolCallRequest(BaseModel):\n   333\t    \"\"\"\n   334\t    A tool call request routed to the Wire client for execution.\n   335\t    \"\"\"\n   336\t\n   337\t    id: str\n   338\t    \"\"\"The ID of the tool call.\"\"\"\n   339\t    name: str\n   340\t    \"\"\"The name of the tool to call.\"\"\"\n   341\t    arguments: str | None\n   342\t    \"\"\"Arguments of the tool call in JSON string format.\"\"\"\n   343\t\n   344\t    def __init__(self, **kwargs: Any) -> None:\n   345\t        super().__init__(**kwargs)\n   346\t        self._future: asyncio.Future[ToolReturnValue] | None = None\n   347\t\n   348\t    def _get_future(self) -> asyncio.Future[ToolReturnValue]:\n   349\t        if self._future is None:\n   350\t            self._future = asyncio.get_event_loop().create_future()\n   351\t        return self._future\n   352\t\n   353\t    @staticmethod\n   354\t    def from_tool_call(tool_call: ToolCall) -> ToolCallRequest:\n   355\t        return ToolCallRequest(\n   356\t            id=tool_call.id,\n   357\t            name=tool_call.function.name,\n   358\t            arguments=tool_call.function.arguments,\n   359\t        )\n   360\t\n   361\t    async def wait(self) -> ToolReturnValue:\n   362\t        \"\"\"\n   363\t        Wait for the tool call to be resolved or cancelled.\n   364\t\n   365\t        Returns:\n   366\t            ToolReturnValue: The tool execution result.\n   367\t        \"\"\"\n   368\t        return await self._get_future()\n   369\t\n   370\t    def resolve(self, result: ToolReturnValue) -> None:\n   371\t        \"\"\"\n   372\t        Resolve the tool call with the given result.\n   373\t        This will cause the `wait()` method to return the result.\n   374\t        \"\"\"\n   375\t        future = self._get_future()\n   376\t        if not future.done():\n   377\t            future.set_result(result)\n   378\t\n   379\t    @property\n   380\t    def resolved(self) -> bool:\n   381\t        \"\"\"Whether the tool call is resolved.\"\"\"\n   382\t        return self._future is not None and self._future.done()\n   383\t\n   384\t\n   385\ttype Event = (\n   386\t    TurnBegin\n   387\t    | TurnEnd\n   388\t    | StepBegin\n   389\t    | StepInterrupted\n   390\t    | CompactionBegin\n   391\t    | CompactionEnd\n   392\t    | MCPLoadingBegin\n   393\t    | MCPLoadingEnd\n   394\t    | StatusUpdate\n   395\t    | Notification\n   396\t    | ContentPart\n   397\t    | ToolCall\n   398\t    | ToolCallPart\n   399\t    | ToolResult\n   400\t    | ApprovalResponse\n   401\t    | SubagentEvent\n   402\t)\n   403\t\"\"\"Any event, including control flow and content/tooling events.\"\"\"\n   404\t\n   405\t\n   406\ttype Request = ApprovalRequest | ToolCallRequest | QuestionRequest\n   407\t\"\"\"Any request. Request is a message that expects a response.\"\"\"\n   408\t\n   409\ttype WireMessage = Event | Request\n   410\t\"\"\"Any message sent over the `Wire`.\"\"\"\n   411\t\n   412\t\n   413\t_EVENT_TYPES = cast(tuple[type[Event], ...], flatten_union(Event))\n   414\t_REQUEST_TYPES = cast(tuple[type[Request], ...], flatten_union(Request))\n   415\t_WIRE_MESSAGE_TYPES = cast(tuple[type[WireMessage], ...], flatten_union(WireMessage))\n   416\t\n   417\t\n   418\tdef is_event(msg: Any) -> TypeGuard[Event]:\n   419\t    \"\"\"Check if the message is an Event.\"\"\"\n   420\t    return isinstance(msg, _EVENT_TYPES)\n   421\t\n   422\t\n   423\tdef is_request(msg: Any) -> TypeGuard[Request]:\n   424\t    \"\"\"Check if the message is a Request.\"\"\"\n   425\t    return isinstance(msg, _REQUEST_TYPES)\n   426\t\n   427\t\n   428\tdef is_wire_message(msg: Any) -> TypeGuard[WireMessage]:\n   429\t    \"\"\"Check if the message is a WireMessage.\"\"\"\n   430\t    return isinstance(msg, _WIRE_MESSAGE_TYPES)\n   431\t\n   432\t\n   433\t_NAME_TO_WIRE_MESSAGE_TYPE: dict[str, type[WireMessage]] = {\n   434\t    cls.__name__: cls for cls in _WIRE_MESSAGE_TYPES\n   435\t}\n   436\t# for backwards compatibility with Wire v1\n   437\t_NAME_TO_WIRE_MESSAGE_TYPE[\"ApprovalRequestResolved\"] = ApprovalResponse\n   438\t\n   439\t\n   440\tclass WireMessageEnvelope(BaseModel):\n   441\t    type: str\n   442\t    payload: dict[str, JsonType]\n   443\t\n   444\t    @classmethod\n   445\t    def from_wire_message(cls, msg: WireMessage) -> WireMessageEnvelope:\n   446\t        typename: str | None = None\n   447\t        for name, typ in _NAME_TO_WIRE_MESSAGE_TYPE.items():\n   448\t            if issubclass(type(msg), typ):\n   449\t                typename = name\n   450\t                break\n   451\t        assert typename is not None, f\"Unknown wire message type: {type(msg)}\"\n   452\t        return cls(\n   453\t            type=typename,\n   454\t            payload=msg.model_dump(mode=\"json\"),\n   455\t        )\n   456\t\n   457\t    def to_wire_message(self) -> WireMessage:\n   458\t        \"\"\"\n   459\t        Convert the envelope back into a `WireMessage`.\n   460\t\n   461\t        Raises:\n   462\t            ValueError: If the message type is unknown or the payload is invalid.\n   463\t        \"\"\"\n   464\t        msg_type = _NAME_TO_WIRE_MESSAGE_TYPE.get(self.type)\n   465\t        if msg_type is None:\n   466\t            raise ValueError(f\"Unknown wire message type: {self.type}\")\n   467\t        return msg_type.model_validate(self.payload)\n   468\t\n   469\t\n   470\t__all__ = [\n   471\t    # `WireMessage` variants\n   472\t    \"TurnBegin\",\n   473\t    \"StepBegin\",\n   474\t    \"StepInterrupted\",\n   475\t    \"CompactionBegin\",\n   476\t    \"CompactionEnd\",\n   477\t    \"MCPLoadingBegin\",\n   478\t    \"MCPLoadingEnd\",\n   479\t    \"StatusUpdate\",\n   480\t    \"Notification\",\n   481\t    \"ContentPart\",\n   482\t    \"ToolCall\",\n   483\t    \"ToolCallPart\",\n   484\t    \"ToolResult\",\n   485\t    \"ApprovalResponse\",\n   486\t    \"SubagentEvent\",\n   487\t    \"ApprovalRequest\",\n   488\t    \"ToolCallRequest\",\n   489\t    \"QuestionOption\",\n   490\t    \"QuestionItem\",\n   491\t    \"QuestionResponse\",\n   492\t    \"QuestionRequest\",\n   493\t    \"QuestionNotSupported\",\n   494\t    # helpers\n   495\t    \"WireMessageEnvelope\",\n   496\t    # `StatusUpdate`-related\n   497\t    \"TokenUsage\",\n   498\t    # `ContentPart` types\n   499\t    \"TextPart\",\n   500\t    \"ThinkPart\",\n   501\t    \"ImageURLPart\",\n   502\t    \"AudioURLPart\",\n   503\t    \"VideoURLPart\",\n   504\t    # `ToolResult`-related\n   505\t    \"ToolReturnValue\",\n   506\t    # `DisplayBlock` types\n   507\t    \"DisplayBlock\",\n   508\t    \"UnknownDisplayBlock\",\n   509\t    \"BriefDisplayBlock\",\n   510\t    \"DiffDisplayBlock\",\n   511\t    \"TodoDisplayBlock\",\n   512\t    \"TodoDisplayItem\",\n   513\t    \"ShellDisplayBlock\",\n   514\t    \"BackgroundTaskDisplayBlock\",\n   515\t]\n", "message": "515 lines read from file starting from line 1. End of file reached.", "display": [], "extras": null}}}}
+{"timestamp": 1773723455.2285829, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "\", \"n_lines\": 150}"}}}
+{"timestamp": 1773723455.229769, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.12117767333984375, "context_tokens": 31766, "max_context_tokens": 262144, "token_usage": {"input_other": 11542, "output": 164, "input_cache_read": 20224, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0006", "plan_mode": false}}}
+{"timestamp": 1773723455.2449121, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_SorRMdJIzuUdPESVPYIbDqQU", "return_value": {"is_error": false, "output": "     1\tfrom __future__ import annotations\n     2\t\n     3\timport asyncio\n     4\tfrom collections.abc import Awaitable, Callable, Sequence\n     5\tfrom contextlib import suppress\n     6\tfrom dataclasses import dataclass\n     7\tfrom functools import partial\n     8\tfrom pathlib import Path\n     9\tfrom typing import TYPE_CHECKING, Any, Literal\n    10\t\n    11\timport kosong\n    12\timport tenacity\n    13\tfrom kosong import StepResult\n    14\tfrom kosong.chat_provider import (\n    15\t    APIConnectionError,\n    16\t    APIEmptyResponseError,\n    17\t    APIStatusError,\n    18\t    APITimeoutError,\n    19\t    RetryableChatProvider,\n    20\t)\n    21\tfrom kosong.message import Message, ToolCall\n    22\tfrom tenacity import RetryCallState, retry_if_exception, stop_after_attempt, wait_exponential_jitter\n    23\t\n    24\tfrom example_pkg.background import build_active_task_snapshot\n    25\tfrom example_pkg.llm import ModelCapability\n    26\tfrom example_pkg.notifications import build_notification_message, extract_notification_ids\n    27\tfrom example_pkg.skill import Skill, read_skill_text\n    28\tfrom example_pkg.skill.flow import Flow, FlowEdge, FlowNode, parse_choice\n    29\tfrom example_pkg.soul import (\n    30\t    LLMNotSet,\n    31\t    LLMNotSupported,\n    32\t    MaxStepsReached,\n    33\t    Soul,\n    34\t    StatusSnapshot,\n    35\t    wire_send,\n    36\t)\n    37\tfrom example_pkg.soul.agent import Agent, Runtime\n    38\tfrom example_pkg.soul.compaction import (\n    39\t    CompactionResult,\n    40\t    SimpleCompaction,\n    41\t    estimate_text_tokens,\n    42\t    should_auto_compact,\n    43\t)\n    44\tfrom example_pkg.soul.context import Context\n    45\tfrom example_pkg.soul.dynamic_injection import (\n    46\t    DynamicInjection,\n    47\t    DynamicInjectionProvider,\n    48\t    normalize_history,\n    49\t)\n    50\tfrom example_pkg.soul.dynamic_injections.plan_mode import PlanModeInjectionProvider\n    51\tfrom example_pkg.soul.message import check_message, system, tool_result_to_message\n    52\tfrom example_pkg.soul.slash import registry as soul_slash_registry\n    53\tfrom example_pkg.soul.toolset import KimiToolset\n    54\tfrom example_pkg.tools.dmail import NAME as SendDMail_NAME\n    55\tfrom example_pkg.tools.utils import ToolRejectedError\n    56\tfrom example_pkg.utils.logging import logger\n    57\tfrom example_pkg.utils.slashcmd import SlashCommand, parse_slash_command_call\n    58\tfrom example_pkg.wire.file import WireFile\n    59\tfrom example_pkg.wire.types import (\n    60\t    ApprovalRequest,\n    61\t    ApprovalResponse,\n    62\t    CompactionBegin,\n    63\t    CompactionEnd,\n    64\t    ContentPart,\n    65\t    MCPLoadingBegin,\n    66\t    MCPLoadingEnd,\n    67\t    StatusUpdate,\n    68\t    StepBegin,\n    69\t    StepInterrupted,\n    70\t    TextPart,\n    71\t    ToolResult,\n    72\t    TurnBegin,\n    73\t    TurnEnd,\n    74\t)\n    75\t\n    76\tif TYPE_CHECKING:\n    77\t\n    78\t    def type_check(soul: KimiSoul):\n    79\t        _: Soul = soul\n    80\t\n    81\t\n    82\tSKILL_COMMAND_PREFIX = \"skill:\"\n    83\tFLOW_COMMAND_PREFIX = \"flow:\"\n    84\tDEFAULT_MAX_FLOW_MOVES = 1000\n    85\t\n    86\t\n    87\ttype StepStopReason = Literal[\"no_tool_calls\", \"tool_rejected\"]\n    88\t\n    89\t\n    90\t@dataclass(frozen=True, slots=True)\n    91\tclass StepOutcome:\n    92\t    stop_reason: StepStopReason\n    93\t    assistant_message: Message\n    94\t\n    95\t\n    96\ttype TurnStopReason = StepStopReason\n    97\t\n    98\t\n    99\t@dataclass(frozen=True, slots=True)\n   100\tclass TurnOutcome:\n   101\t    stop_reason: TurnStopReason\n   102\t    final_message: Message | None\n   103\t    step_count: int\n   104\t\n   105\t\n   106\tclass KimiSoul:\n   107\t    \"\"\"The soul of the example CLI.\"\"\"\n   108\t\n   109\t    def __init__(\n   110\t        self,\n   111\t        agent: Agent,\n   112\t        *,\n   113\t        context: Context,\n   114\t    ):\n   115\t        \"\"\"\n   116\t        Initialize the soul.\n   117\t\n   118\t        Args:\n   119\t            agent (Agent): The agent to run.\n   120\t            context (Context): The context of the agent.\n   121\t        \"\"\"\n   122\t        self._agent = agent\n   123\t        self._runtime = agent.runtime\n   124\t        self._denwa_renji = agent.runtime.denwa_renji\n   125\t        self._approval = agent.runtime.approval\n   126\t        self._context = context\n   127\t        self._loop_control = agent.runtime.config.loop_control\n   128\t        self._compaction = SimpleCompaction()  # TODO: maybe configurable and composable\n   129\t\n   130\t        for tool in agent.toolset.tools:\n   131\t            if tool.name == SendDMail_NAME:\n   132\t                self._checkpoint_with_user_message = True\n   133\t                break\n   134\t        else:\n   135\t            self._checkpoint_with_user_message = False\n   136\t\n   137\t        self._steer_queue: asyncio.Queue[str | list[ContentPart]] = asyncio.Queue()\n   138\t        self._plan_mode: bool = self._runtime.session.state.plan_mode\n   139\t        self._plan_session_id: str | None = None\n   140\t        self._pending_plan_activation_injection: bool = False\n   141\t        if self._plan_mode:\n   142\t            self._ensure_plan_session_id()\n   143\t        self._injection_providers: list[DynamicInjectionProvider] = [\n   144\t            PlanModeInjectionProvider(),\n   145\t        ]\n   146\t        if self._runtime.role == \"root\":\n   147\t            self._runtime.notifications.ack_ids(\"llm\", extract_notification_ids(context.history))\n   148\t\n   149\t        # Bind plan mode state to tools that support it\n   150\t        self._bind_plan_mode_tools()\n", "message": "150 lines read from file starting from line 1.", "display": [], "extras": null}}}}
+{"timestamp": 1773723455.248815, "message": {"type": "StepBegin", "payload": {"n": 4}}}
+{"timestamp": 1773723458.644604, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "我已经获取了足够的背景信息。让我继续读取 KimiSoul 中 notification 相关的代码，以及相关的测试来理解完整的功能边界。", "encrypted": null}}}
+{"timestamp": 1773723459.371076, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_okFY9oLifSxqJb8egNPac0MS", "function": {"name": "ReadFile", "arguments": "{\"path\": \"src/example_pkg/soul/kimisoul.py\", \"line_offset\": 200, \"n_lines\": 200}"}, "extras": null}}}
+{"timestamp": 1773723459.396414, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_CcxVl6nzWr4TfMaivaLiZxsz", "function": {"name": "Grep", "arguments": "{\"pattern\": \"def _"}, "extras": null}}}
+{"timestamp": 1773723459.3969622, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_okFY9oLifSxqJb8egNPac0MS", "return_value": {"is_error": false, "output": "   200\t\n   201\t        def path_getter() -> Path | None:\n   202\t            return self.get_plan_file_path()\n   203\t\n   204\t        # WriteFile gets both checker and path_getter (for plan file auto-approve)\n   205\t        from example_pkg.tools.file.write import WriteFile\n   206\t\n   207\t        write_tool = self._agent.toolset.find(\"WriteFile\")\n   208\t        if isinstance(write_tool, WriteFile):\n   209\t            write_tool.bind_plan_mode(checker, path_getter)\n   210\t\n   211\t        # ExitPlanMode has a special bind() method\n   212\t        from example_pkg.tools.plan import ExitPlanMode\n   213\t\n   214\t        exit_tool = self._agent.toolset.find(\"ExitPlanMode\")\n   215\t        if isinstance(exit_tool, ExitPlanMode):\n   216\t            exit_tool.bind(self.toggle_plan_mode, path_getter, checker)\n   217\t\n   218\t        # EnterPlanMode has a special bind() with yolo_checker\n   219\t        from example_pkg.tools.plan.enter import EnterPlanMode\n   220\t\n   221\t        enter_tool = self._agent.toolset.find(\"EnterPlanMode\")\n   222\t        if isinstance(enter_tool, EnterPlanMode):\n   223\t\n   224\t            def yolo_checker() -> bool:\n   225\t                return self._approval.is_yolo()\n   226\t\n   227\t            enter_tool.bind(self.toggle_plan_mode, path_getter, checker, yolo_checker)\n   228\t\n   229\t        # AskUserQuestion gets plan mode checker for dynamic description\n   230\t        from example_pkg.tools.ask_user import AskUserQuestion\n   231\t\n   232\t        ask_tool = self._agent.toolset.find(\"AskUserQuestion\")\n   233\t        if isinstance(ask_tool, AskUserQuestion):\n   234\t            ask_tool.bind_plan_mode(checker)\n   235\t\n   236\t    def _ensure_plan_session_id(self) -> None:\n   237\t        \"\"\"Allocate a stable plan session ID on first activation.\"\"\"\n   238\t        if self._plan_session_id is None:\n   239\t            import uuid\n   240\t\n   241\t            self._plan_session_id = uuid.uuid4().hex\n   242\t\n   243\t    def _set_plan_mode(self, enabled: bool, *, source: Literal[\"manual\", \"tool\"]) -> bool:\n   244\t        \"\"\"Update plan mode state for either manual or tool-driven toggles.\"\"\"\n   245\t        if enabled == self._plan_mode:\n   246\t            return self._plan_mode\n   247\t        self._plan_mode = enabled\n   248\t        if enabled:\n   249\t            self._ensure_plan_session_id()\n   250\t            self._pending_plan_activation_injection = source == \"manual\"\n   251\t        else:\n   252\t            self._pending_plan_activation_injection = False\n   253\t        # Persist plan mode to session state so it survives process restarts\n   254\t        self._runtime.session.state.plan_mode = self._plan_mode\n   255\t        self._runtime.session.save_state()\n   256\t        return self._plan_mode\n   257\t\n   258\t    def get_plan_file_path(self) -> Path | None:\n   259\t        \"\"\"Get the plan file path for the current session.\"\"\"\n   260\t        if self._plan_session_id is None:\n   261\t            return None\n   262\t        from example_pkg.tools.plan.heroes import get_plan_file_path\n   263\t\n   264\t        return get_plan_file_path(self._plan_session_id)\n   265\t\n   266\t    def read_current_plan(self) -> str | None:\n   267\t        \"\"\"Read the current plan file content.\"\"\"\n   268\t        if self._plan_session_id is None:\n   269\t            return None\n   270\t        from example_pkg.tools.plan.heroes import read_plan_file\n   271\t\n   272\t        return read_plan_file(self._plan_session_id)\n   273\t\n   274\t    def clear_current_plan(self) -> None:\n   275\t        \"\"\"Delete the current plan file.\"\"\"\n   276\t        path = self.get_plan_file_path()\n   277\t        if path and path.exists():\n   278\t            path.unlink()\n   279\t\n   280\t    async def toggle_plan_mode(self) -> bool:\n   281\t        \"\"\"Toggle plan mode on/off. Returns the new state.\n   282\t\n   283\t        Tools are not hidden/unhidden — instead, each tool checks plan mode\n   284\t        state at call time and rejects if blocked.\n   285\t        Periodic reminders are handled by the dynamic injection system.\n   286\t        \"\"\"\n   287\t        return self._set_plan_mode(not self._plan_mode, source=\"tool\")\n   288\t\n   289\t    async def toggle_plan_mode_from_manual(self) -> bool:\n   290\t        \"\"\"Toggle plan mode from UI/manual entry points (slash command, keybinding).\"\"\"\n   291\t        return self._set_plan_mode(not self._plan_mode, source=\"manual\")\n   292\t\n   293\t    async def set_plan_mode_from_manual(self, enabled: bool) -> bool:\n   294\t        \"\"\"Set plan mode to a specific state from UI/manual entry points.\n   295\t\n   296\t        Unlike toggle, this accepts the desired state directly, avoiding\n   297\t        race conditions when the caller already knows the target value.\n   298\t        \"\"\"\n   299\t        return self._set_plan_mode(enabled, source=\"manual\")\n   300\t\n   301\t    def consume_pending_plan_activation_injection(self) -> bool:\n   302\t        \"\"\"Consume the next-step activation reminder scheduled by a manual toggle.\"\"\"\n   303\t        if not self._plan_mode or not self._pending_plan_activation_injection:\n   304\t            return False\n   305\t        self._pending_plan_activation_injection = False\n   306\t        return True\n   307\t\n   308\t    @property\n   309\t    def thinking(self) -> bool | None:\n   310\t        \"\"\"Whether thinking mode is enabled.\"\"\"\n   311\t        if self._runtime.llm is None:\n   312\t            return None\n   313\t        if thinking_effort := self._runtime.llm.chat_provider.thinking_effort:\n   314\t            return thinking_effort != \"off\"\n   315\t        return None\n   316\t\n   317\t    @property\n   318\t    def status(self) -> StatusSnapshot:\n   319\t        token_count = self._context.token_count\n   320\t        max_size = self._runtime.llm.max_context_size if self._runtime.llm is not None else 0\n   321\t        return StatusSnapshot(\n   322\t            context_usage=self._context_usage,\n   323\t            yolo_enabled=self._approval.is_yolo(),\n   324\t            plan_mode=self._plan_mode,\n   325\t            context_tokens=token_count,\n   326\t            max_context_tokens=max_size,\n   327\t        )\n   328\t\n   329\t    @property\n   330\t    def agent(self) -> Agent:\n   331\t        return self._agent\n   332\t\n   333\t    @property\n   334\t    def runtime(self) -> Runtime:\n   335\t        return self._runtime\n   336\t\n   337\t    @property\n   338\t    def context(self) -> Context:\n   339\t        return self._context\n   340\t\n   341\t    @property\n   342\t    def _context_usage(self) -> float:\n   343\t        if self._runtime.llm is not None:\n   344\t            return self._context.token_count / self._runtime.llm.max_context_size\n   345\t        return 0.0\n   346\t\n   347\t    @property\n   348\t    def wire_file(self) -> WireFile:\n   349\t        return self._runtime.session.wire_file\n   350\t\n   351\t    async def _checkpoint(self):\n   352\t        await self._context.checkpoint(self._checkpoint_with_user_message)\n   353\t\n   354\t    def steer(self, content: str | list[ContentPart]) -> None:\n   355\t        \"\"\"Queue a steer message for injection into the current turn.\"\"\"\n   356\t        self._steer_queue.put_nowait(content)\n   357\t\n   358\t    async def _consume_pending_steers(self) -> bool:\n   359\t        \"\"\"Drain the steer queue and inject as synthetic tool results.\n   360\t\n   361\t        Returns True if any steers were consumed.\n   362\t        \"\"\"\n   363\t        consumed = False\n   364\t        while not self._steer_queue.empty():\n   365\t            content = self._steer_queue.get_nowait()\n   366\t            await self._inject_steer(content)\n   367\t            consumed = True\n   368\t        return consumed\n   369\t\n   370\t    async def _inject_steer(self, content: str | list[ContentPart]) -> None:\n   371\t        \"\"\"Inject a single steer as a synthetic ``_steer`` tool_call + tool result pair.\"\"\"\n   372\t        from uuid import uuid4\n   373\t\n   374\t        steer_id = f\"steer_{uuid4().hex[:8]}\"\n   375\t        text = (\n   376\t            content\n   377\t            if isinstance(content, str)\n   378\t            else Message(role=\"user\", content=content).extract_text(\" \")\n   379\t        )\n   380\t        await self._context.append_message(\n   381\t            [\n   382\t                Message(\n   383\t                    role=\"assistant\",\n   384\t                    content=[],\n   385\t                    tool_calls=[\n   386\t                        ToolCall(\n   387\t                            id=steer_id,\n   388\t                            function=ToolCall.FunctionBody(name=\"_steer\", arguments=None),\n   389\t                        )\n   390\t                    ],\n   391\t                ),\n   392\t                Message(\n   393\t                    role=\"tool\",\n   394\t                    content=[system(f\"The user has sent a real-time instruction:\\n\\n{text}\")],\n   395\t                    tool_call_id=steer_id,\n   396\t                ),\n   397\t            ]\n   398\t        )\n   399\t\n", "message": "200 lines read from file starting from line 200.", "display": [], "extras": null}}}}
+{"timestamp": 1773723460.340662, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "step|notification|claim|publish\", \"path\": \"src/example_pkg/soul/kimisoul.py\", \"output_mode\": \"content\", \"-n\": true}"}}}
+{"timestamp": 1773723460.343477, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_CcxVl6nzWr4TfMaivaLiZxsz", "return_value": {"is_error": false, "output": "26:from example_pkg.notifications import build_notification_message, extract_notification_ids\n147:            self._runtime.notifications.ack_ids(\"llm\", extract_notification_ids(context.history))\n626:    async def _step(self) -> StepOutcome | None:\n634:            notifications = self._runtime.notifications.claim_for_sink(\"llm\", limit=4)\n635:            if notifications:\n637:                    build_notification_message(view, self._runtime) for view in notifications\n640:                self._runtime.notifications.ack_ids(\n641:                    \"llm\", {view.event.id for view in notifications}\n", "message": "", "display": [], "extras": null}}}}
+{"timestamp": 1773723460.344036, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.15938568115234375, "context_tokens": 41782, "max_context_tokens": 262144, "token_usage": {"input_other": 10038, "output": 121, "input_cache_read": 31744, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0007", "plan_mode": false}}}
+{"timestamp": 1773723460.34506, "message": {"type": "StepBegin", "payload": {"n": 5}}}
+{"timestamp": 1773723468.0745978, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "现在我对功能有了完整的理解。让我总结一下测试范围：\n\n**功能边界：**\n1. **后台任务系统** - 创建、监控、停止、输出获取\n2. **通知系统** - 发布、消费、去重、确认\n3. **集成点** - Shell 后台模式、TaskList/TaskOutput/TaskStop 工具、Wire 通知事件、LLM 通知消息\n\n**用户可感知的行为变化：**\n1. Shell 工具新增 `run_in_background` 和 `description` 参数\n2. 新增 TaskList/TaskOutput/TaskStop 工具\n3. 后台任务完成后自动发送通知到 LLM context 和 Wire\n4. 通知通过独立的 `<notification>` 消息进入 context\n5. Wire 协议新增 `Notification` 事件类型\n\n**测试计划：**\n1. **正常路径** - 启动后台任务，等待完成，验证通知\n2. **边界条件** - 超时处理、重复停止、无效 task_id\n3. **中断/清理** - 主动停止任务、任务丢失恢复\n\n让我开始制定最小测试计划并执行。", "encrypted": null}}}
+{"timestamp": 1773723473.821217, "message": {"type": "ContentPart", "payload": {"type": "text", "text": "现在我对功能有了完整理解。让我制定测试计划：\n\n## 功能边界总结\n\n**主要变更：**\n1. **后台任务系统** (`background/`) - 全新模块，支持后台 bash 任务\n2. **通知系统** (`notifications/`) - 独立基建，支持多 sink (llm/wire/shell)\n3. **新工具** - `TaskList` / `TaskOutput` / `TaskStop`\n4. **Shell 工具更新** - 新增 `run_in_background` + `description` 参数\n5. **Wire 协议** - 新增 `Notification` 事件类型\n6. **KimiSoul 集成** - 自动 claim/ack notification，compaction 后恢复活跃任务快照\n\n**测试范围：**\n- 后台任务生命周期（创建→运行→完成→通知）\n- 任务控制工具（List/Output/Stop）\n- 通知系统（去重、claim/ack、多 sink）\n- 集成点（Shell 后台模式、Wire 事件、LLM 消息）\n\n---\n\n## 开始冒烟测试"}}}
+{"timestamp": 1773723477.409677, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_y3SXWWQIUysddnYoklaWhUeE", "function": {"name": "SetTodoList", "arguments": "{\"todos\": [{\"title\": \"准备测试环境（创建隔离 work-dir）\", \"status\": \"in_progress\"}, {\"title\": \"探索轮：验证工具可用性和接口\", \"status\": \"pending\"}, {\"title\": \"执行轮1：正常路径 - 后台任务生命周期\", \"status\": \"pending\"}, {\"title\": \"执行轮2：边界条件 - 超时和停止\", \"status\": \"pending\"}, {\"title\": \"执行轮3：中断场景 - TaskStop 和恢复\", \"status\": \"pending\"}, {\"title\": \"观察轮：检查 session 产物\", \"status\": \"pending\"}, {\"title\": \"汇报结论\", \"status\": \"pending\"}]}"}, "extras": null}}}
+{"timestamp": 1773723477.4152231, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_BH2zd6kVzHhV4pIjKLSmrUeB", "function": {"name": "Shell", "arguments": ""}, "extras": null}}}
+{"timestamp": 1773723477.4158258, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_y3SXWWQIUysddnYoklaWhUeE", "return_value": {"is_error": false, "output": "", "message": "Todo list updated", "display": [{"type": "todo", "items": [{"title": "准备测试环境（创建隔离 work-dir）", "status": "in_progress"}, {"title": "探索轮：验证工具可用性和接口", "status": "pending"}, {"title": "执行轮1：正常路径 - 后台任务生命周期", "status": "pending"}, {"title": "执行轮2：边界条件 - 超时和停止", "status": "pending"}, {"title": "执行轮3：中断场景 - TaskStop 和恢复", "status": "pending"}, {"title": "观察轮：检查 session 产物", "status": "pending"}, {"title": "汇报结论", "status": "pending"}]}], "extras": null}}}}
+{"timestamp": 1773723478.966131, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "{\"command\": \"SMOKE_DIR=\\\"$(mktemp -d /tmp/kimi-smoke-XXXXXX)\\\"\\necho \\\"SMOKE_DIR=$SMOKE_DIR\\\"\\n# 验证 CLI 可运行\\nuv run python -m example_pkg.cli --help 2>&1 | head -20\"}"}}}
+{"timestamp": 1773723478.966906, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.16886138916015625, "context_tokens": 44266, "max_context_tokens": 262144, "token_usage": {"input_other": 2538, "output": 695, "input_cache_read": 41728, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0008", "plan_mode": false}}}
+{"timestamp": 1773723479.278039, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_BH2zd6kVzHhV4pIjKLSmrUeB", "return_value": {"is_error": false, "output": "SMOKE_DIR=/tmp/kimi-smoke-a2i1xj\n                                                                                \n Usage: python -m example_pkg.cli [OPTIONS] COMMAND [ARGS]...                      \n                                                                                \n The Starting Point for Next-Gen Agents                                                     \n                                                                                \n╭─ Options ────────────────────────────────────────────────────────────────────╮\n│ --version         -V                                       Show version and  │\n│                                                            exit.             │\n│ --verbose                                                  Print verbose     │\n│                                                            information.      │\n│                                                            Default: no.      │\n│ --debug                                                    Log debug         │\n│                                                            information.      │\n│                                                            Default: no.      │\n│ --work-dir        -w                      DIRECTORY        Working directory │\n│                                                            for the agent.    │\n│                                                            Default: current  │\n│                                                            directory.        │\n│ --add-dir                                 DIRECTORY        Add an additional │\n│                                                            directory to the  │\n", "message": "Command executed successfully.", "display": [], "extras": null}}}}
+{"timestamp": 1773723479.279804, "message": {"type": "StepBegin", "payload": {"n": 6}}}
+{"timestamp": 1773723481.4476092, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "环境准备好了，现在让我开始第一轮探索测试，验证工具可用性。", "encrypted": null}}}
+{"timestamp": 1773723484.9596741, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_mj72EeaBIxBi3NOVwE3tjxBc", "function": {"name": "SetTodoList", "arguments": "{\"todos\": [{\"title\": \"准备测试环境（创建隔离 work-dir）\", \"status\": \"done\"}, {\"title\": \"探索轮：验证工具可用性和接口\", \"status\": \"in_progress\"}, {\"title\": \"执行轮1：正常路径 - 后台任务生命周期\", \"status\": \"pending\"}, {\"title\": \"执行轮2：边界条件 - 超时和停止\", \"status\": \"pending\"}, {\"title\": \"执行轮3：中断场景 - TaskStop 和恢复\", \"status\": \"pending\"}, {\"title\": \"观察轮：检查 session 产物\", \"status\": \"pending\"}, {\"title\": \"汇报结论\", \"status\": \"pending\"}]}"}, "extras": null}}}
+{"timestamp": 1773723484.963279, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_ocohNUErNzzNQnYsibl670ms", "function": {"name": "Shell", "arguments": ""}, "extras": null}}}
+{"timestamp": 1773723484.9638138, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_mj72EeaBIxBi3NOVwE3tjxBc", "return_value": {"is_error": false, "output": "", "message": "Todo list updated", "display": [{"type": "todo", "items": [{"title": "准备测试环境（创建隔离 work-dir）", "status": "done"}, {"title": "探索轮：验证工具可用性和接口", "status": "in_progress"}, {"title": "执行轮1：正常路径 - 后台任务生命周期", "status": "pending"}, {"title": "执行轮2：边界条件 - 超时和停止", "status": "pending"}, {"title": "执行轮3：中断场景 - TaskStop 和恢复", "status": "pending"}, {"title": "观察轮：检查 session 产物", "status": "pending"}, {"title": "汇报结论", "status": "pending"}]}], "extras": null}}}}
+{"timestamp": 1773723488.377907, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\n\\n# 探索轮：验证后台任务相关工具是否可用\\nuv run python -m example_pkg.cli \\\\\\n  --print \\\\\\n  --prompt \\\"请列出你当前所有可用的工具，特别关注：\\n1. 是否有 TaskList、TaskOutput、TaskStop 这三个工具？\\n2. Shell 工具是否支持 run_in_background 参数？\\n3. 简单描述这些工具的功能。\\\" \\\\\\n  --work-dir \\\"$SMOKE_DIR\\\" 2>&1\\necho \\\"exit_code=$?\\\"\", \"timeout\": 120}"}}}
+{"timestamp": 1773723488.379134, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.1723785400390625, "context_tokens": 45188, "max_context_tokens": 262144, "token_usage": {"input_other": 1156, "output": 320, "input_cache_read": 44032, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0009", "plan_mode": false}}}
+{"timestamp": 1773723507.7400808, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_ocohNUErNzzNQnYsibl670ms", "return_value": {"is_error": false, "output": "请列出你当前所有可用的工具，特别关注：\n1. 是否有 TaskList、TaskOutput、TaskStop 这三个工具？\n2. Shell 工具是否支持 run_in_background 参数？\n3. 简单描述这些工具的功能。\nTurnBegin(\n    user_input='请列出你当前所有可用的工具，特别关注：\\n1. 是否有 \nTaskList、TaskOutput、TaskStop 这三个工具？\\n2. Shell 工具是否支持 \nrun_in_background 参数？\\n3. 简单描述这些工具的功能。'\n)\nStepBegin(n=1)\nThinkPart(\n    type='think',\n    think='用户询问我当前可用的工具列表，特别关注三个问题：\\n1. 是否有 \nTaskList、TaskOutput、TaskStop 这三个工具？\\n2. Shell 工具是否支持 \nrun_in_background 参数？\\n3. \n简单描述这些工具的功能。\\n\\n我需要查看我的工具列表。从 system \n提示中，我可以看到我有以下工具：\\n- Task\\n- AskUserQuestion\\n- SetTodoList\\n- \nShell\\n- TaskList\\n- TaskOutput\\n- TaskStop\\n- ReadFile\\n- ReadMediaFile\\n- \nGlob\\n- Grep\\n- WriteFile\\n- StrReplaceFile\\n- SearchWeb\\n- FetchURL\\n- \nExitPlanMode\\n- EnterPlanMode\\n\\n让我逐一确认并回答用户的问题。',\n    encrypted=None\n)\nTextPart(\n    type='text',\n    text='根据我的系统配置，以下是当前可用的工具列表：\\n\\n## 1. \nTaskList、TaskOutput、TaskStop 是否存在？\\n\\n**是的，这三个工具都存在：**\\n\\n| \n工具名 | 功能 |\\n|--------|------|\\n| `TaskList` | 列出当前会话中的后台任务 |\\n|\n`TaskOutput` | 获取正在运行或已完成的后台任务的输出 |\\n| `TaskStop` | \n停止一个正在运行的后台任务 |\\n\\n## 2. Shell 工具是否支持 run_in_background \n参数？\\n\\n**是的，支持。** `Shell` 工具有一个 `run_in_background` \n参数（布尔值，默认 `false`），用于将命令作为后台任务执行。\\n\\n## 3. \n所有可用工具的简要描述\\n\\n| 工具名 | 功能描述 |\\n|--------|----------|\\n| \n**Task** | 生成子代理执行特定任务，支持并行多任务处理 |\\n| **AskUserQuestion** |\n向用户提出结构化问题，收集偏好或解决歧义 |\\n| **SetTodoList** | \n更新待办事项列表，跟踪任务进度 |\\n| **Shell** | 执行 bash \n命令，支持文件操作、脚本运行、系统信息等 |\\n| **TaskList** | \n列出后台任务，查看哪些任务仍在运行 |\\n| **TaskOutput** | \n获取后台任务的输出，可阻塞等待完成 |\\n| **TaskStop** | 终止正在运行的后台任务 \n|\\n| **ReadFile** | 读取文本文件内容，支持指定行范围 |\\n| **ReadMediaFile** | \n读取图片或视频文件（支持 ≤100MB） |\\n| **Glob** | 使用 glob 模式查找文件/目录 \n|\\n| **Grep** | 基于 ripgrep 的文本搜索工具 |\\n| **WriteFile** | \n写入内容到文件（覆盖或追加模式） |\\n| **StrReplaceFile** | \n在文件中替换指定字符串 |\\n| **SearchWeb** | 在互联网上搜索信息 |\\n| **FetchURL**\n| 获取网页内容并提取主要文本 |\\n| **ExitPlanMode** | \n退出计划模式，请求用户批准计划 |\\n| **EnterPlanMode** | \n进入计划模式（用于复杂架构决策） |'\n)\nStatusUpdate(\n    context_usage=0.030162811279296875,\n    context_tokens=7907,\n    max_context_tokens=262144,\n    token_usage=TokenUsage(\n        input_other=2531,\n        output=607,\n        input_cache_read=5376,\n        input_cache_creation=0\n    ),\n    message_id='chatcmpl-fixture-0010',\n    plan_mode=False\n)\nTurnEnd()\nexit_code=0\n", "message": "Command executed successfully.", "display": [], "extras": null}}}}
+{"timestamp": 1773723507.742814, "message": {"type": "StepBegin", "payload": {"n": 7}}}
+{"timestamp": 1773723510.3311732, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "探索轮成功，工具都已正确加载。现在进入执行轮1：测试正常路径 - 启动后台任务，等待完成，验证通知。", "encrypted": null}}}
+{"timestamp": 1773723510.911253, "message": {"type": "ContentPart", "payload": {"type": "text", "text": "探索轮成功！工具都已正确加载。现在执行第一轮测试："}}}
+{"timestamp": 1773723514.418436, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_bpOwCgVz6wYah52SnaJB39ZW", "function": {"name": "SetTodoList", "arguments": "{\"todos\": [{\"title\": \"准备测试环境（创建隔离 work-dir）\", \"status\": \"done\"}, {\"title\": \"探索轮：验证工具可用性和接口\", \"status\": \"done\"}, {\"title\": \"执行轮1：正常路径 - 后台任务生命周期\", \"status\": \"in_progress\"}, {\"title\": \"执行轮2：边界条件 - 超时和停止\", \"status\": \"pending\"}, {\"title\": \"执行轮3：中断场景 - TaskStop 和恢复\", \"status\": \"pending\"}, {\"title\": \"观察轮：检查 session 产物\", \"status\": \"pending\"}, {\"title\": \"汇报结论\", \"status\": \"pending\"}]}"}, "extras": null}}}
+{"timestamp": 1773723514.4222221, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_HejoTo6Izmlets9y9hN9u1pZ", "function": {"name": "Shell", "arguments": ""}, "extras": null}}}
+{"timestamp": 1773723514.4225678, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_bpOwCgVz6wYah52SnaJB39ZW", "return_value": {"is_error": false, "output": "", "message": "Todo list updated", "display": [{"type": "todo", "items": [{"title": "准备测试环境（创建隔离 work-dir）", "status": "done"}, {"title": "探索轮：验证工具可用性和接口", "status": "done"}, {"title": "执行轮1：正常路径 - 后台任务生命周期", "status": "in_progress"}, {"title": "执行轮2：边界条件 - 超时和停止", "status": "pending"}, {"title": "执行轮3：中断场景 - TaskStop 和恢复", "status": "pending"}, {"title": "观察轮：检查 session 产物", "status": "pending"}, {"title": "汇报结论", "status": "pending"}]}], "extras": null}}}}
+{"timestamp": 1773723520.176416, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\n\\n# 执行轮1：正常路径 - 启动一个短生命周期的后台任务，验证生命周期完整\\nuv run python -m example_pkg.cli \\\\\\n  --print \\\\\\n  --prompt \\\"请执行以下测试：\\n\\n1. 使用 Shell 工具启动一个后台任务：\\n   - 命令: echo 'hello from background' && sleep 2 && echo 'task done'\\n   - run_in_background: true\\n   - description: '测试后台任务生命周期'\\n   - timeout: 30\\n\\n2. 记录返回的 task_id\\n\\n3. 使用 TaskList 查看当前活跃任务\\n\\n4. 使用 TaskOutput 获取任务输出（block=true, timeout=10）\\n\\n请报告：task_id、任务状态、输出内容。\\\" \\\\\\n  --work-dir \\\"$SMOKE_DIR\\\" 2>&1\\necho \\\"exit_code=$?\\\"\", \"timeout\": 120}"}}}
+{"timestamp": 1773723520.177415, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.17727279663085938, "context_tokens": 46471, "max_context_tokens": 262144, "token_usage": {"input_other": 1415, "output": 431, "input_cache_read": 45056, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0011", "plan_mode": false}}}
+{"timestamp": 1773723537.191541, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_HejoTo6Izmlets9y9hN9u1pZ", "return_value": {"is_error": false, "output": "请执行以下测试：\n\n1. 使用 Shell 工具启动一个后台任务：\n   - 命令: echo 'hello from background' && sleep 2 && echo 'task done'\n   - run_in_background: true\n   - description: '测试后台任务生命周期'\n   - timeout: 30\n\n2. 记录返回的 task_id\n\n3. 使用 TaskList 查看当前活跃任务\n\n4. 使用 TaskOutput 获取任务输出（block=true, timeout=10）\n\n请报告：task_id、任务状态、输出内容。\nTurnBegin(\n    user_input=\"请执行以下测试：\\n\\n1. 使用 Shell 工具启动一个后台任务：\\n   - \n命令: echo 'hello from background' && sleep 2 && echo 'task done'\\n   - \nrun_in_background: true\\n   - description: '测试后台任务生命周期'\\n   - timeout:\n30\\n\\n2. 记录返回的 task_id\\n\\n3. 使用 TaskList 查看当前活跃任务\\n\\n4. 使用 \nTaskOutput 获取任务输出（block=true, \ntimeout=10）\\n\\n请报告：task_id、任务状态、输出内容。\"\n)\nStepBegin(n=1)\nThinkPart(\n    type='think',\n    think='用户要求我执行一个测试，涉及后台任务的完整生命周期：\\n1. \n启动一个后台任务\\n2. 记录 task_id\\n3. 使用 TaskList 查看活跃任务\\n4. 使用 \nTaskOutput 获取任务输出\\n\\n让我按步骤执行。',\n    encrypted=None\n)\nToolCall(\n    type='function',\n    id='tool_KviOIHcT5WgvrVhhHtEzsDNR',\n    function=FunctionBody(\n        name='Shell',\n        arguments='{\"command\": \"echo \\'hello from background\\' && sleep 2 && \necho \\'task done\\'\", \"run_in_background\": true, \"description\": \n\"测试后台任务生命周期\", \"timeout\": 30}'\n    ),\n    extras=None\n)\nToolResult(\n    tool_call_id='tool_KviOIHcT5WgvrVhhHtEzsDNR',\n    return_value=ToolReturnValue(\n        is_error=False,\n        output=\"task_id: b83rhswvs\\nkind: bash\\nstatus: starting\\ndescription: \n测试后台任务生命周期\\ncommand: echo 'hello from background' && sleep 2 && echo \n'task done'\\nautomatic_notification: true\\nnext_step: You will be automatically \nnotified when it completes.\\nnext_step: Use TaskOutput with this task_id if you \nneed progress or want to wait.\\nnext_step: Use TaskStop only if the task must be\ncancelled.\",\n        message='Background task started.',\n        display=[\n            BriefDisplayBlock(type='brief', text='Started b83rhswvs'),\n            BackgroundTaskDisplayBlock(\n                type='background_task',\n                task_id='b83rhswvs',\n                kind='bash',\n                status='starting',\n                description='测试后台任务生命周期'\n            )\n        ],\n        extras=None\n    )\n)\nStatusUpdate(\n    context_usage=0.030414581298828125,\n    context_tokens=7973,\n    max_context_tokens=262144,\n    token_usage=TokenUsage(\n        input_other=1317,\n        output=109,\n        input_cache_read=6656,\n        input_cache_creation=0\n    ),\n    message_id='chatcmpl-fixture-0012',\n    plan_mode=False\n)\nStepBegin(n=2)\nThinkPart(\n    type='think',\n    think='好的，任务已启动，task_id 是 `b83rhswvs`。现在让我使用 TaskList \n查看当前活跃任务，然后使用 TaskOutput 获取任务输出。',\n    encrypted=None\n)\nTextPart(\n    type='text',\n    text='任务已启动，task_id: `b83rhswvs`。现在查看活跃任务列表和任务输出：'\n)\nToolCall(\n    type='function',\n    id='tool_J1FgGmubhrAgJB2pNF4cmH0m',\n    function=FunctionBody(name='TaskList', arguments=''),\n    extras=None\n)\nNotification(\n    id='n495ae5fb',\n    category='task',\n    type='task.completed',\n    source_kind='background_task',\n    source_id='b83rhswvs',\n    title='Background task completed: 测试后台任务生命周期',\n    body='Task ID: b83rhswvs\\nStatus: completed\\nDescription: \n测试后台任务生命周期\\nExit code: 0',\n    severity='success',\n    created_at=1773723528.22152,\n    payload={\n        'task_id': 'b83rhswvs',\n        'task_kind': 'bash',\n        'status': 'completed',\n        'description': '测试后台任务生命周期',\n        'exit_code': 0,\n        'interrupted': False,\n        'timed_out': False,\n        'terminal_reason': 'completed',\n        'failure_reason': None\n    }\n)\nToolCallPart(arguments_part='{\"active_only\": true}')\nToolCall(\n    type='function',\n    id='tool_eTooGsF9kKi4dnewTjDMoROT',\n    function=FunctionBody(name='TaskOutput', arguments='{\"'),\n    extras=None\n)\nToolResult(\n    tool_call_id='tool_J1FgGmubhrAgJB2pNF4cmH0m',\n    return_value=ToolReturnValue(\n        is_error=False,\n        output='active_background_tasks: 0\\n[no tasks]',\n        message='Task list retrieved.',\n        display=[],\n        extras=None\n    )\n)\nToolCallPart(\n    arguments_part='task_id\": \"b83rhswvs\", \"block\": true, \"timeout\": 10}'\n)\nToolResult(\n    tool_call_id='tool_eTooGsF9kKi4dnewTjDMoROT',\n    return_value=ToolReturnValue(\n        is_error=False,\n        output=\"retrieval_status: success\\ntask_id: b83rhswvs\\nkind: \nbash\\nstatus: completed\\ndescription: 测试后台任务生命周期\\ncommand: echo 'hello\nfrom background' && sleep 2 && echo 'task done'\\ninterrupted: false\\ntimed_out: \nfalse\\nterminal_reason: completed\\nexit_code: 0\\n\\nhello from background\\ntask \ndone\",\n        message='Task output retrieved.',\n        display=[\n            BackgroundTaskDisplayBlock(\n                type='background_task',\n                task_id='b83rhswvs',\n                kind='bash',\n                status='completed',\n                description='测试后台任务生命周期'\n            )\n        ],\n        extras=None\n    )\n)\nStatusUpdate(\n    context_usage=0.031284332275390625,\n    context_tokens=8201,\n    max_context_tokens=262144,\n    token_usage=TokenUsage(\n        input_other=265,\n        output=108,\n        input_cache_read=7936,\n        input_cache_creation=0\n    ),\n    message_id='chatcmpl-fixture-0013',\n    plan_mode=False\n)\nStepBegin(n=3)\nThinkPart(\n    type='think',\n    think='测试已完成。让我总结一下结果：\\n\\n1. task_id: `b83rhswvs`\\n2. \n任务状态: `completed` (已完成)\\n3. 输出内容: \\n   ```\\n   hello from \nbackground\\n   task done\\n   ```\\n\\nTaskList 显示活跃任务为 \n0，说明任务已经完成。TaskOutput 成功获取了输出，exit_code 为 0 \n表示成功执行。同时系统也发送了自动通知。',\n    encrypted=None\n)\nTextPart(\n    type='text',\n    text='## 测试报告\\n\\n| 项目 | 结果 |\\n|------|------|\\n| **task_id** | \n`b83rhswvs` |\\n| **任务状态** | `completed` (已完成) |\\n| **退出码** | `0` \n(成功) |\\n| **输出内容** | `hello from background`<br>`task done` |\\n\\n### \n测试说明\\n\\n1. **后台任务启动成功** - 返回了 task_id `b83rhswks`\\n2. **TaskList \n正确** - 显示活跃任务为 0（因为任务很快完成）\\n3. **TaskOutput 获取成功** - \nblock=true 等待任务完成后返回完整输出\\n4. **自动通知** - \n系统也自动发送了任务完成的通知'\n)\nStatusUpdate(\n    context_usage=0.03272247314453125,\n    context_tokens=8578,\n    max_context_tokens=262144,\n    token_usage=TokenUsage(\n        input_other=386,\n        output=253,\n        input_cache_read=8192,\n        input_cache_creation=0\n    ),\n    message_id='chatcmpl-fixture-0014',\n    plan_mode=False\n)\nTurnEnd()\nexit_code=0\n", "message": "Command executed successfully.", "display": [], "extras": null}}}}
+{"timestamp": 1773723537.194179, "message": {"type": "StepBegin", "payload": {"n": 8}}}
+{"timestamp": 1773723541.224998, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "第一轮测试成功！关键验证点：\n1. ✅ Shell 后台任务启动成功，返回 task_id\n2. ✅ TaskList 正确工作\n3. ✅ TaskOutput 正确工作，block=true 等待完成\n4. ✅ Notification 事件正确发送（Wire 中可见 Notification 事件）\n\n现在进行第二轮：边界条件 - 测试超时和停止功能。", "encrypted": null}}}
+{"timestamp": 1773723541.75409, "message": {"type": "ContentPart", "payload": {"type": "text", "text": "第一轮成功！所有核心功能正常工作。现在测试边界条件："}}}
+{"timestamp": 1773723545.2981892, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_3tueNNJt54oG2X47QK4PLnTj", "function": {"name": "SetTodoList", "arguments": "{\"todos\": [{\"title\": \"准备测试环境（创建隔离 work-dir）\", \"status\": \"done\"}, {\"title\": \"探索轮：验证工具可用性和接口\", \"status\": \"done\"}, {\"title\": \"执行轮1：正常路径 - 后台任务生命周期\", \"status\": \"done\"}, {\"title\": \"执行轮2：边界条件 - 超时和停止\", \"status\": \"in_progress\"}, {\"title\": \"执行轮3：中断场景 - TaskStop 和恢复\", \"status\": \"pending\"}, {\"title\": \"观察轮：检查 session 产物\", \"status\": \"pending\"}, {\"title\": \"汇报结论\", \"status\": \"pending\"}]}"}, "extras": null}}}
+{"timestamp": 1773723545.303165, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_NT90qPui3vOOBqIjmTgvYe9Q", "function": {"name": "Shell", "arguments": ""}, "extras": null}}}
+{"timestamp": 1773723545.303835, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_3tueNNJt54oG2X47QK4PLnTj", "return_value": {"is_error": false, "output": "", "message": "Todo list updated", "display": [{"type": "todo", "items": [{"title": "准备测试环境（创建隔离 work-dir）", "status": "done"}, {"title": "探索轮：验证工具可用性和接口", "status": "done"}, {"title": "执行轮1：正常路径 - 后台任务生命周期", "status": "done"}, {"title": "执行轮2：边界条件 - 超时和停止", "status": "in_progress"}, {"title": "执行轮3：中断场景 - TaskStop 和恢复", "status": "pending"}, {"title": "观察轮：检查 session 产物", "status": "pending"}, {"title": "汇报结论", "status": "pending"}]}], "extras": null}}}}
+{"timestamp": 1773723551.34051, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\n\\n# 执行轮2：边界条件 - 超时处理和停止\\nuv run python -m example_pkg.cli \\\\\\n  --print \\\\\\n  --prompt \\\"请执行以下边界条件测试：\\n\\n1. 启动一个长时间运行的后台任务（会被停止）：\\n   - 命令: for i in 1 2 3 4 5; do echo \\\\\\\"line \\\\$i\\\\\\\"; sleep 5; done\\n   - run_in_background: true\\n   - description: '测试停止功能'\\n   - timeout: 60\\n\\n2. 使用 TaskList 确认任务在运行中\\n\\n3. 等待 3 秒后，使用 TaskStop 停止该任务\\n\\n4. 使用 TaskOutput 获取任务最终状态和输出\\n\\n请报告：task_id、停止前后的状态、输出内容、是否有正确通知。\\\" \\\\\\n  --work-dir \\\"$SMOKE_DIR\\\" 2>&1\\necho \\\"exit_code=$?\\\"\", \"timeout\": 180}"}}}
+{"timestamp": 1773723551.34149, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.18646621704101562, "context_tokens": 48881, "max_context_tokens": 262144, "token_usage": {"input_other": 2545, "output": 491, "input_cache_read": 46336, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0015", "plan_mode": false}}}
+{"timestamp": 1773723578.760308, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_NT90qPui3vOOBqIjmTgvYe9Q", "return_value": {"is_error": false, "output": "请执行以下边界条件测试：\n\n1. 启动一个长时间运行的后台任务（会被停止）：\n   - 命令: for i in 1 2 3 4 5; do echo \"line $i\"; sleep 5; done\n   - run_in_background: true\n   - description: '测试停止功能'\n   - timeout: 60\n\n2. 使用 TaskList 确认任务在运行中\n\n3. 等待 3 秒后，使用 TaskStop 停止该任务\n\n4. 使用 TaskOutput 获取任务最终状态和输出\n\n请报告：task_id、停止前后的状态、输出内容、是否有正确通知。\nTurnBegin(\n    user_input='请执行以下边界条件测试：\\n\\n1. \n启动一个长时间运行的后台任务（会被停止）：\\n   - 命令: for i in 1 2 3 4 5; do \necho \"line $i\"; sleep 5; done\\n   - run_in_background: true\\n   - description: \n\\'测试停止功能\\'\\n   - timeout: 60\\n\\n2. 使用 TaskList 确认任务在运行中\\n\\n3. \n等待 3 秒后，使用 TaskStop 停止该任务\\n\\n4. 使用 TaskOutput \n获取任务最终状态和输出\\n\\n请报告：task_id、停止前后的状态、输出内容、是否有正确\n通知。'\n)\nStepBegin(n=1)\nThinkPart(\n    type='think',\n    think='用户要求进行一系列边界条件测试，涉及后台任务的管理。让我按步骤执行：\\\nn\\n1. 启动一个长时间运行的后台任务\\n2. 使用 TaskList 确认任务在运行中\\n3. 等待 3\n秒后停止任务\\n4. 获取任务最终状态和输出\\n\\n让我开始执行这些步骤。',\n    encrypted=None\n)\nTextPart(type='text', text='我将按步骤执行边界条件测试。')\nToolCall(\n    type='function',\n    id='tool_OEOMu8djKawiijYlSfgG0YRm',\n    function=FunctionBody(\n        name='Shell',\n        arguments='{\"command\": \"for i in 1 2 3 4 5; do echo \\\\\"line $i\\\\\"; sleep\n5; done\", \"run_in_background\": true, \"description\": \"测试停止功能\", \"timeout\": \n60}'\n    ),\n    extras=None\n)\nToolResult(\n    tool_call_id='tool_OEOMu8djKawiijYlSfgG0YRm',\n    return_value=ToolReturnValue(\n        is_error=False,\n        output='task_id: bp6amsrcu\\nkind: bash\\nstatus: starting\\ndescription: \n测试停止功能\\ncommand: for i in 1 2 3 4 5; do echo \"line $i\"; sleep 5; \ndone\\nautomatic_notification: true\\nnext_step: You will be automatically \nnotified when it completes.\\nnext_step: Use TaskOutput with this task_id if you \nneed progress or want to wait.\\nnext_step: Use TaskStop only if the task must be\ncancelled.',\n        message='Background task started.',\n        display=[\n            BriefDisplayBlock(type='brief', text='Started bp6amsrcu'),\n            BackgroundTaskDisplayBlock(\n                type='background_task',\n                task_id='bp6amsrcu',\n                kind='bash',\n                status='starting',\n                description='测试停止功能'\n            )\n        ],\n        extras=None\n    )\n)\nStatusUpdate(\n    context_usage=0.0305023193359375,\n    context_tokens=7996,\n    max_context_tokens=262144,\n    token_usage=TokenUsage(\n        input_other=1340,\n        output=138,\n        input_cache_read=6656,\n        input_cache_creation=0\n    ),\n    message_id='chatcmpl-fixture-0016',\n    plan_mode=False\n)\nStepBegin(n=2)\nThinkPart(\n    type='think',\n    think='任务已启动，task_id 是 bp6amsrcu。现在使用 TaskList \n确认任务在运行中。',\n    encrypted=None\n)\nToolCall(\n    type='function',\n    id='tool_UNLvdE2gm448bWqkhFMg6cHs',\n    function=FunctionBody(name='TaskList', arguments='{\"active_only\": true}'),\n    extras=None\n)\nToolResult(\n    tool_call_id='tool_UNLvdE2gm448bWqkhFMg6cHs',\n    return_value=ToolReturnValue(\n        is_error=False,\n        output='active_background_tasks: 1\\n\\n[1]\\ntask_id: bp6amsrcu\\nkind: \nbash\\nstatus: running\\ndescription: 测试停止功能\\ncommand: for i in 1 2 3 4 5; \ndo echo \"line $i\"; sleep 5; done',\n        message='Task list retrieved.',\n        display=[\n            BackgroundTaskDisplayBlock(\n                type='background_task',\n                task_id='bp6amsrcu',\n                kind='bash',\n                status='running',\n                description='测试停止功能'\n            )\n        ],\n        extras=None\n    )\n)\nStatusUpdate(\n    context_usage=0.031520843505859375,\n    context_tokens=8263,\n    max_context_tokens=262144,\n    token_usage=TokenUsage(\n        input_other=327,\n        output=43,\n        input_cache_read=7936,\n        input_cache_creation=0\n    ),\n    message_id='chatcmpl-fixture-0017',\n    plan_mode=False\n)\nStepBegin(n=3)\nThinkPart(\n    type='think',\n    think='任务状态是 running，确认在运行中。现在等待 3 秒后停止任务。',\n    encrypted=None\n)\nToolCall(\n    type='function',\n    id='tool_palQ1dKuOPHKgj4z3QBJYv4q',\n    function=FunctionBody(\n        name='Shell',\n        arguments='{\"command\": \"sleep 3\", \"timeout\": 10}'\n    ),\n    extras=None\n)\nStatusUpdate(\n    context_usage=0.03202056884765625,\n    context_tokens=8394,\n    max_context_tokens=262144,\n    token_usage=TokenUsage(\n        input_other=202,\n        output=45,\n        input_cache_read=8192,\n        input_cache_creation=0\n    ),\n    message_id='chatcmpl-fixture-0018',\n    plan_mode=False\n)\nToolResult(\n    tool_call_id='tool_palQ1dKuOPHKgj4z3QBJYv4q',\n    return_value=ToolReturnValue(\n        is_error=False,\n        output='',\n        message='Command executed successfully.',\n        display=[],\n        extras=None\n    )\n)\nStepBegin(n=4)\nThinkPart(type='think', think='等待了 3 秒，现在停止任务。', encrypted=None)\nToolCall(\n    type='function',\n    id='tool_S9lk4xoGb3Aewu7ewUeEWsiI',\n    function=FunctionBody(\n        name='TaskStop',\n        arguments='{\"task_id\": \"bp6amsrcu\", \"reason\": \"用户请求停止测试\"}'\n    ),\n    extras=None\n)\nToolResult(\n    tool_call_id='tool_S9lk4xoGb3Aewu7ewUeEWsiI',\n    return_value=ToolReturnValue(\n        is_error=False,\n        output='task_id: bp6amsrcu\\nkind: bash\\nstatus: running\\ndescription: \n测试停止功能\\ncommand: for i in 1 2 3 4 5; do echo \"line $i\"; sleep 5; done',\n        message='Task stop requested.',\n        display=[\n            BackgroundTaskDisplayBlock(\n                type='background_task',\n                task_id='bp6amsrcu',\n                kind='bash',\n                status='running',\n                description='测试停止功能'\n            )\n        ],\n        extras=None\n    )\n)\nStatusUpdate(\n    context_usage=0.032291412353515625,\n    context_tokens=8465,\n    max_context_tokens=262144,\n    token_usage=TokenUsage(\n        input_other=273,\n        output=43,\n        input_cache_read=8192,\n        input_cache_creation=0\n    ),\n    message_id='chatcmpl-fixture-0019',\n    plan_mode=False\n)\nStepBegin(n=5)\nNotification(\n    id='n6afa14f0',\n    category='task',\n    type='task.killed',\n    source_kind='background_task',\n    source_id='bp6amsrcu',\n    title='Background task stopped: 测试停止功能',\n    body='Task ID: bp6amsrcu\\nStatus: killed\\nDescription: 测试停止功能\\nExit \ncode: -15\\nFailure reason: 用户请求停止测试',\n    severity='warning',\n    created_at=1773723566.1025841,\n    payload={\n        'task_id': 'bp6amsrcu',\n        'task_kind': 'bash',\n        'status': 'killed',\n        'description': '测试停止功能',\n        'exit_code': -15,\n        'interrupted': True,\n        'timed_out': False,\n        'terminal_reason': 'killed',\n        'failure_reason': '用户请求停止测试'\n    }\n)\nThinkPart(\n    type='think',\n    think='任务已成功停止，我收到了通知。现在获取任务的最终状态和输出。',\n    encrypted=None\n)\nToolCall(\n    type='function',\n    id='tool_e26EO7zGZcrLe8DedQfX11Z9',\n    function=FunctionBody(\n        name='TaskOutput',\n        arguments='{\"task_id\": \"bp6amsrcu\", \"block\": false}'\n    ),\n    extras=None\n)\nToolResult(\n    tool_call_id='tool_e26EO7zGZcrLe8DedQfX11Z9',\n    return_value=ToolReturnValue(\n        is_error=False,\n        output='retrieval_status: success\\ntask_id: bp6amsrcu\\nkind: \nbash\\nstatus: killed\\ndescription: 测试停止功能\\ncommand: for i in 1 2 3 4 5; do\necho \"line $i\"; sleep 5; done\\ninterrupted: true\\ntimed_out: \nfalse\\nterminal_reason: killed\\nexit_code: -15\\nreason: 用户请求停止测试\\n\\nline\n1\\nline 2',\n        message='Task output retrieved.',\n        display=[\n            BackgroundTaskDisplayBlock(\n                type='background_task',\n                task_id='bp6amsrcu',\n                kind='bash',\n                status='killed',\n                description='测试停止功能'\n            )\n        ],\n        extras=None\n    )\n)\nStatusUpdate(\n    context_usage=0.03333282470703125,\n    context_tokens=8738,\n    max_context_tokens=262144,\n    token_usage=TokenUsage(\n        input_other=290,\n        output=43,\n        input_cache_read=8448,\n        input_cache_creation=0\n    ),\n    message_id='chatcmpl-fixture-0020',\n    plan_mode=False\n)\nStepBegin(n=6)\nThinkPart(\n    type='think',\n    think='测试完成。让我总结一下测试结果。',\n    encrypted=None\n)\nTextPart(\n    type='text',\n    text='## 边界条件测试报告\\n\\n### 任务信息\\n| 属性 | 值 |\\n|------|-----|\\n| \n**task_id** | `bp6amsrcu` |\\n| **任务类型** | bash |\\n| **描述** | 测试停止功能 \n|\\n\\n### 状态变化\\n| 时间点 | 状态 | 说明 |\\n|--------|------|------|\\n| 启动时 \n| `starting` | 任务刚启动 |\\n| TaskList 查询时 | `running` | 确认任务运行中 |\\n|\nTaskStop 请求时 | `running` | 正在运行 |\\n| 停止后 | `killed` | 被终止 |\\n\\n### \n输出内容\\n```\\nline 1\\nline 2\\n```\\n- 任务在输出第 2 行后被停止\\n- 原计划输出 5 \n行（5 次循环），实际完成 2 次循环\\n\\n### 终止详情\\n| 属性 | 值 \n|\\n|------|-----|\\n| exit_code | `-15` (SIGTERM) |\\n| terminal_reason | `killed`\n|\\n| reason | 用户请求停止测试 |\\n| interrupted | `true` |\\n| timed_out | \n`false` |\\n\\n### 通知验证 ✅\\n- **自动通知已触发**：收到了 `task.killed` \n类型的通知\\n- 通知包含：Task ID、状态、killed、exit \ncode、停止原因、输出尾部\\n\\n### 测试结论\\n所有边界条件测试通过：\\n1. ✅ \n后台任务正常启动\\n2. ✅ TaskList 正确显示运行中的任务\\n3. ✅ TaskStop \n成功停止任务（发送 SIGTERM）\\n4. ✅ TaskOutput 正确获取最终状态和输出\\n5. ✅ \n自动通知机制正常工作'\n)\nStatusUpdate(\n    context_usage=0.03395843505859375,\n    context_tokens=8902,\n    max_context_tokens=262144,\n    token_usage=TokenUsage(\n        input_other=198,\n        output=370,\n        input_cache_read=8704,\n        input_cache_creation=0\n    ),\n    message_id='chatcmpl-fixture-0021',\n    plan_mode=False\n)\nTurnEnd()\nexit_code=0\n", "message": "Command executed successfully.", "display": [], "extras": null}}}}
+{"timestamp": 1773723578.762163, "message": {"type": "StepBegin", "payload": {"n": 9}}}
+{"timestamp": 1773723582.081287, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "第二轮也成功！测试了停止功能，验证了：\n1. ✅ TaskStop 成功停止任务\n2. ✅ 通知正确发送 (task.killed)\n3. ✅ exit_code 正确 (-15 = SIGTERM)\n4. ✅ 输出正确捕获\n\n现在进行第三轮测试：测试超时处理。", "encrypted": null}}}
+{"timestamp": 1773723582.782677, "message": {"type": "ContentPart", "payload": {"type": "text", "text": "第二轮成功！停止功能完全正常。现在测试超时场景："}}}
+{"timestamp": 1773723586.549674, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_TS5JUSZELJoTVcos6rp90ZUT", "function": {"name": "SetTodoList", "arguments": "{\"todos\": [{\"title\": \"准备测试环境（创建隔离 work-dir）\", \"status\": \"done\"}, {\"title\": \"探索轮：验证工具可用性和接口\", \"status\": \"done\"}, {\"title\": \"执行轮1：正常路径 - 后台任务生命周期\", \"status\": \"done\"}, {\"title\": \"执行轮2：边界条件 - 超时和停止\", \"status\": \"done\"}, {\"title\": \"执行轮3：超时场景测试\", \"status\": \"in_progress\"}, {\"title\": \"观察轮：检查 session 产物\", \"status\": \"pending\"}, {\"title\": \"汇报结论\", \"status\": \"pending\"}]}"}, "extras": null}}}
+{"timestamp": 1773723586.553171, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_J3cQ5m3qyTep0zNLWhZR3OGg", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\n\\n# "}, "extras": null}}}
+{"timestamp": 1773723586.55373, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_TS5JUSZELJoTVcos6rp90ZUT", "return_value": {"is_error": false, "output": "", "message": "Todo list updated", "display": [{"type": "todo", "items": [{"title": "准备测试环境（创建隔离 work-dir）", "status": "done"}, {"title": "探索轮：验证工具可用性和接口", "status": "done"}, {"title": "执行轮1：正常路径 - 后台任务生命周期", "status": "done"}, {"title": "执行轮2：边界条件 - 超时和停止", "status": "done"}, {"title": "执行轮3：超时场景测试", "status": "in_progress"}, {"title": "观察轮：检查 session 产物", "status": "pending"}, {"title": "汇报结论", "status": "pending"}]}], "extras": null}}}}
+{"timestamp": 1773723590.976526, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "执行轮3：测试超时处理\\nuv run python -m example_pkg.cli \\\\\\n  --print \\\\\\n  --prompt \\\"请测试后台任务超时功能：\\n\\n1. 启动一个会超时的后台任务：\\n   - 命令: sleep 300\\n   - run_in_background: true\\n   - description: '测试超时处理'\\n   - timeout: 3  （设置为3秒，确保会超时）\\n\\n2. 使用 TaskOutput 阻塞等待任务结束（block=true, timeout=15）\\n\\n3. 检查任务最终状态是否为 timeout\\n\\n请报告：task_id、最终状态、exit_code、是否有 timeout 通知。\\\" \\\\\\n  --work-dir \\\"$SMOKE_DIR\\\" 2>&1\\necho \\\"exit_code=$?\\\"\", \"timeout\": 180}"}}}
+{"timestamp": 1773723590.977342, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.1998748779296875, "context_tokens": 52396, "max_context_tokens": 262144, "token_usage": {"input_other": 3756, "output": 438, "input_cache_read": 48640, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0022", "plan_mode": false}}}
+{"timestamp": 1773723614.7084181, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_J3cQ5m3qyTep0zNLWhZR3OGg", "return_value": {"is_error": false, "output": "请测试后台任务超时功能：\n\n1. 启动一个会超时的后台任务：\n   - 命令: sleep 300\n   - run_in_background: true\n   - description: '测试超时处理'\n   - timeout: 3  （设置为3秒，确保会超时）\n\n2. 使用 TaskOutput 阻塞等待任务结束（block=true, timeout=15）\n\n3. 检查任务最终状态是否为 timeout\n\n请报告：task_id、最终状态、exit_code、是否有 timeout 通知。\nTurnBegin(\n    user_input=\"请测试后台任务超时功能：\\n\\n1. 启动一个会超时的后台任务：\\n   - \n命令: sleep 300\\n   - run_in_background: true\\n   - description: \n'测试超时处理'\\n   - timeout: 3  （设置为3秒，确保会超时）\\n\\n2. 使用 TaskOutput\n阻塞等待任务结束（block=true, timeout=15）\\n\\n3. 检查任务最终状态是否为 \ntimeout\\n\\n请报告：task_id、最终状态、exit_code、是否有 timeout 通知。\"\n)\nStepBegin(n=1)\nThinkPart(\n    type='think',\n    think='用户想要测试后台任务的超时功能。让我按照步骤执行：\\n\\n1. \n启动一个会超时的后台任务（sleep 300，timeout=3秒）\\n2. 使用 TaskOutput \n阻塞等待任务结束\\n3. 检查任务最终状态\\n\\n让我开始执行这些步骤。',\n    encrypted=None\n)\nTextPart(\n    type='text',\n    text='我将按照您的步骤测试后台任务超时功能。\\n\\n**步骤 1: \n启动会超时的后台任务**'\n)\nToolCall(\n    type='function',\n    id='tool_jdgL3fRhcSJAUsxZ9tqP0GBb',\n    function=FunctionBody(\n        name='Shell',\n        arguments='{\"command\": \"sleep 300\", \"run_in_background\": true, \n\"description\": \"测试超时处理\", \"timeout\": 3}'\n    ),\n    extras=None\n)\nToolResult(\n    tool_call_id='tool_jdgL3fRhcSJAUsxZ9tqP0GBb',\n    return_value=ToolReturnValue(\n        is_error=False,\n        output='task_id: b4c3d8fta\\nkind: bash\\nstatus: starting\\ndescription: \n测试超时处理\\ncommand: sleep 300\\nautomatic_notification: true\\nnext_step: You \nwill be automatically notified when it completes.\\nnext_step: Use TaskOutput \nwith this task_id if you need progress or want to wait.\\nnext_step: Use TaskStop\nonly if the task must be cancelled.',\n        message='Background task started.',\n        display=[\n            BriefDisplayBlock(type='brief', text='Started b4c3d8fta'),\n            BackgroundTaskDisplayBlock(\n                type='background_task',\n                task_id='b4c3d8fta',\n                kind='bash',\n                status='starting',\n                description='测试超时处理'\n            )\n        ],\n        extras=None\n    )\n)\nStatusUpdate(\n    context_usage=0.030384063720703125,\n    context_tokens=7965,\n    max_context_tokens=262144,\n    token_usage=TokenUsage(\n        input_other=1309,\n        output=124,\n        input_cache_read=6656,\n        input_cache_creation=0\n    ),\n    message_id='chatcmpl-fixture-0023',\n    plan_mode=False\n)\nStepBegin(n=2)\nThinkPart(\n    type='think',\n    think='好的，任务已经启动，task_id 是 b4c3d8fta。现在执行步骤 2，使用 \nTaskOutput 阻塞等待任务结束，设置 timeout=15 秒，这足够让任务在 3 秒后超时。',\n    encrypted=None\n)\nTextPart(type='text', text='**步骤 2: 阻塞等待任务结束（timeout=15秒）**')\nToolCall(\n    type='function',\n    id='tool_sGZinjDXMxzsQfrzY72ok0hc',\n    function=FunctionBody(\n        name='TaskOutput',\n        arguments='{\"task_id\": \"b4c3d8fta\", \"block\": true, \"timeout\": 15}'\n    ),\n    extras=None\n)\nToolResult(\n    tool_call_id='tool_sGZinjDXMxzsQfrzY72ok0hc',\n    return_value=ToolReturnValue(\n        is_error=False,\n        output='retrieval_status: success\\ntask_id: b4c3d8fta\\nkind: \nbash\\nstatus: failed\\ndescription: 测试超时处理\\ncommand: sleep \n300\\ninterrupted: true\\ntimed_out: true\\nterminal_reason: timed_out\\nexit_code: \n-15\\nreason: Command timed out after 3s\\n\\n[no output available]',\n        message='Task output retrieved.',\n        display=[\n            BackgroundTaskDisplayBlock(\n                type='background_task',\n                task_id='b4c3d8fta',\n                kind='bash',\n                status='failed',\n                description='测试超时处理'\n            )\n        ],\n        extras=None\n    )\n)\nStatusUpdate(\n    context_usage=0.031269073486328125,\n    context_tokens=8197,\n    max_context_tokens=262144,\n    token_usage=TokenUsage(\n        input_other=261,\n        output=106,\n        input_cache_read=7936,\n        input_cache_creation=0\n    ),\n    message_id='chatcmpl-fixture-0024',\n    plan_mode=False\n)\nStepBegin(n=3)\nNotification(\n    id='n08e25c76',\n    category='task',\n    type='task.timed_out',\n    source_kind='background_task',\n    source_id='b4c3d8fta',\n    title='Background task timed out: 测试超时处理',\n    body='Task ID: b4c3d8fta\\nStatus: failed\\nDescription: \n测试超时处理\\nTerminal reason: timed_out\\nExit code: -15\\nFailure reason: \nCommand timed out after 3s',\n    severity='error',\n    created_at=1773723600.5713642,\n    payload={\n        'task_id': 'b4c3d8fta',\n        'task_kind': 'bash',\n        'status': 'failed',\n        'description': '测试超时处理',\n        'exit_code': -15,\n        'interrupted': True,\n        'timed_out': True,\n        'terminal_reason': 'timed_out',\n        'failure_reason': 'Command timed out after 3s'\n    }\n)\nThinkPart(\n    type='think',\n    think='测试完成了。现在我来总结测试结果：\\n\\n1. task_id: b4c3d8fta\\n2. \n最终状态: failed\\n3. exit_code: -15\\n4. 是否有 timeout 通知: 是（收到了 \nnotification）\\n\\n超时功能正常工作！',\n    encrypted=None\n)\nTextPart(\n    type='text',\n    text='## 测试结果报告\\n\\n| 项目 | 值 |\\n|------|-----|\\n| **task_id** | \n`b4c3d8fta` |\\n| **最终状态** | `failed` ✅ |\\n| **exit_code** | `-15` ✅ |\\n| \n**timeout 通知** | ✅ **有**（收到了 `<notification type=\"task.timed_out\">`） \n|\\n\\n### 详细说明：\\n\\n1. **任务启动成功** - task_id 为 `b4c3d8fta`\\n2. \n**超时机制正常** - 任务在 3 秒后准时被终止（`timed_out: true`）\\n3. **状态正确**\n- 最终状态为 `failed`，中断原因为 `timed_out`\\n4. **Exit Code** - `-15` \n表示进程被 SIGTERM 信号终止（这是正常的超时处理行为）\\n5. **自动通知** - \n系统发送了 `task.timed_out` 类型的通知\\n\\n✅ **后台任务超时功能测试通过！** \n超时机制工作正常，任务在设定的 3 秒后被正确终止。'\n)\nStatusUpdate(\n    context_usage=0.032680511474609375,\n    context_tokens=8567,\n    max_context_tokens=262144,\n    token_usage=TokenUsage(\n        input_other=375,\n        output=289,\n        input_cache_read=8192,\n        input_cache_creation=0\n    ),\n    message_id='chatcmpl-fixture-0025',\n    plan_mode=False\n)\nTurnEnd()\nexit_code=0\n", "message": "Command executed successfully.", "display": [], "extras": null}}}}
+{"timestamp": 1773723614.711324, "message": {"type": "StepBegin", "payload": {"n": 10}}}
+{"timestamp": 1773723618.1559749, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "第三轮也成功！测试了超时处理：\n1. ✅ 任务正确超时\n2. ✅ 状态为 failed，timed_out=true\n3. ✅ 通知正确发送 (task.timed_out)\n4. ✅ exit_code 正确 (-15)\n\n现在进入观察轮，检查 session 产物，验证 notification 是否正确写入 context 等。", "encrypted": null}}}
+{"timestamp": 1773723618.655921, "message": {"type": "ContentPart", "payload": {"type": "text", "text": "第三轮成功！超时处理完全正常。现在进入观察轮，检查 session 产物："}}}
+{"timestamp": 1773723622.686785, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_n7Bz3OSHPlOZnL3ghEe8Rciw", "function": {"name": "SetTodoList", "arguments": "{\"todos\": [{\"title\": \"准备测试环境（创建隔离 work-dir）\", \"status\": \"done\"}, {\"title\": \"探索轮：验证工具可用性和接口\", \"status\": \"done\"}, {\"title\": \"执行轮1：正常路径 - 后台任务生命周期\", \"status\": \"done\"}, {\"title\": \"执行轮2：边界条件 - 超时和停止\", \"status\": \"done\"}, {\"title\": \"执行轮3：超时场景测试\", \"status\": \"done\"}, {\"title\": \"观察轮：检查 session 产物\", \"status\": \"in_progress\"}, {\"title\": \"汇报结论\", \"status\": \"pending\"}]}"}, "extras": null}}}
+{"timestamp": 1773723622.70358, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_3s3qLBo5c7kA1pqbpX36YbVo", "function": {"name": "Shell", "arguments": "{\"command\": \"SM"}, "extras": null}}}
+{"timestamp": 1773723622.7041652, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_n7Bz3OSHPlOZnL3ghEe8Rciw", "return_value": {"is_error": false, "output": "", "message": "Todo list updated", "display": [{"type": "todo", "items": [{"title": "准备测试环境（创建隔离 work-dir）", "status": "done"}, {"title": "探索轮：验证工具可用性和接口", "status": "done"}, {"title": "执行轮1：正常路径 - 后台任务生命周期", "status": "done"}, {"title": "执行轮2：边界条件 - 超时和停止", "status": "done"}, {"title": "执行轮3：超时场景测试", "status": "done"}, {"title": "观察轮：检查 session 产物", "status": "in_progress"}, {"title": "汇报结论", "status": "pending"}]}], "extras": null}}}}
+{"timestamp": 1773723626.6639738, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "OKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\n\\n# 查找 session 目录\\necho \\\"=== Session 定位 ===\\\"\\nSESSION_ID=$(echo -n \\\"$SMOKE_DIR\\\" | md5)\\necho \\\"Work dir: $SMOKE_DIR\\\"\\necho \\\"Session ID (md5): $SESSION_ID\\\"\\nSESSION_DIR=\\\"$HOME/.kimi/sessions/$SESSION_ID\\\"\\necho \\\"Session dir: $SESSION_DIR\\\"\\n\\n# 检查 session 目录是否存在\\nif [ -d \\\"$SESSION_DIR\\\" ]; then\\n    echo \\\"Session exists: YES\\\"\\n    ls -la \\\"$SESSION_DIR\\\"\\nelse\\n    echo \\\"Session exists: NO\\\"\\n    # 尝试找到最新的 session\\n    echo \\\"Finding latest session...\\\"\\n    ls -lt \\\"$HOME/.kimi/sessions/\\\" 2>/dev/null | head -10\\nfi\"}"}}}
+{"timestamp": 1773723626.6649349, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.20894622802734375, "context_tokens": 54774, "max_context_tokens": 262144, "token_usage": {"input_other": 2550, "output": 446, "input_cache_read": 52224, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0026", "plan_mode": false}}}
+{"timestamp": 1773723626.684848, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_3s3qLBo5c7kA1pqbpX36YbVo", "return_value": {"is_error": false, "output": "=== Session 定位 ===\nWork dir: /tmp/kimi-smoke-a2i1xj\nSession ID (md5): d1c3750c0cc0757aeac04ad5a7d6b8cf\nSession dir: /Users/example/proj/.kimi/sessions/d1c3750c0cc0757aeac04ad5a7d6b8cf\nSession exists: YES\ntotal 0\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:59 .\ndrwxr-xr-x@ 1722 user      staff  55104  3月 17 12:58 ..\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:58 0e1d3b94-dae2-4dfb-b36d-717397f4d2f6\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:59 228b54e2-5b5d-4675-94f2-ec56e42cdbae\ndrwxr-xr-x@    6 user      staff    192  3月 17 13:00 be8228d5-1c57-43dc-9f23-9e7dba209a1a\ndrwxr-xr-x@    4 user      staff    128  3月 17 12:58 ea3920e8-2a4b-4e38-be51-c500aab582ab\n", "message": "Command executed successfully.", "display": [], "extras": null}}}}
+{"timestamp": 1773723626.68736, "message": {"type": "StepBegin", "payload": {"n": 11}}}
+{"timestamp": 1773723629.4917262, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "找到了 session 目录，下面有多个子目录（每次运行 CLI 会创建一个新的子 session）。让我使用 inspect_session.py 来检查最新的 session。", "encrypted": null}}}
+{"timestamp": 1773723630.804826, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_4Zcuo5i4xl2NEz1Y1EZ1IvSn", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\n\\n# 使用 inspect_session.py 检查最新的 session\\necho \\\"=== 使用 inspect_session.py 检查 ===\\\"\\nuv run python .agents/skills/example-task/scripts/inspect_session.py --share-dir ~/.kimi 2>&1\"}"}, "extras": null}}}
+{"timestamp": 1773723630.805852, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.21220779418945312, "context_tokens": 55629, "max_context_tokens": 262144, "token_usage": {"input_other": 1101, "output": 119, "input_cache_read": 54528, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0027", "plan_mode": false}}}
+{"timestamp": 1773723631.2581189, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_4Zcuo5i4xl2NEz1Y1EZ1IvSn", "return_value": {"is_error": false, "output": "=== 使用 inspect_session.py 检查 ===\nSession dir: /Users/example/proj/.kimi/sessions/6a7967e2a97cd71a62b8375c5ae461ba/ef00f9f9-a470-4e50-b279-59429da67d27\n\n== Files ==\ncontext.jsonl (209039 bytes)\nstate.json (188 bytes)\nwire.jsonl (197310 bytes)\n\n== Context ==\n/Users/example/proj/.kimi/sessions/6a7967e2a97cd71a62b8375c5ae461ba/ef00f9f9-a470-4e50-b279-59429da67d27/context.jsonl\nrecords: 85\nroles: _checkpoint=16, _system_prompt=1, _usage=27, assistant=13, tool=26, user=2\n[74] role=assistant | tools=SetTodoList,Shell | text=第二轮也成功！测试了停止功能，验证了： 1. ✅ TaskStop 成功停止任务 2. ✅ 通知正确发送 (task.killed) 3. ✅ exit_code 正确 (-15 = SIGTERM) 4. ✅ 输出正确捕获 现在进行第三轮测试：测试超时处理。 第二轮成功！停止功能完全正常。现在测试超时场景：\n[75] role=_usage token_count=52834\n[76] role=tool | tool_call_id=tool_TS5JUSZELJoTVcos6rp90ZUT | text=<system>Todo list updated</system>\n[77] role=tool | tool_call_id=tool_J3cQ5m3qyTep0zNLWhZR3OGg | text=<system>Command executed successfully.</system> 请测试后台任务超时功能： 1. 启动一个会超时的后台任务： - 命令: sleep 300 - run_in_background: true - description: '测试超时处理' - timeout: 3 （设置为3秒，确保会超时） 2. 使用 TaskOutput 阻塞等待任务结束（block=true, timeout=...\n[78] role=_checkpoint id=14\n[79] role=_usage token_count=54774\n[80] role=assistant | tools=SetTodoList,Shell | text=第三轮也成功！测试了超时处理： 1. ✅ 任务正确超时 2. ✅ 状态为 failed，timed_out=true 3. ✅ 通知正确发送 (task.timed_out) 4. ✅ exit_code 正确 (-15) 现在进入观察轮，检查 session 产物，验证 notification 是否正确写入 context 等。 第三轮成功！超时处理完全正常。现在进入观察轮，检查 session 产物：\n[81] role=_usage token_count=55220\n[82] role=tool | tool_call_id=tool_n7Bz3OSHPlOZnL3ghEe8Rciw | text=<system>Todo list updated</system>\n[83] role=tool | tool_call_id=tool_3s3qLBo5c7kA1pqbpX36YbVo | text=<system>Command executed successfully.</system> === Session 定位 === Work dir: /tmp/kimi-smoke-a2i1xj Session ID (md5): d1c3750c0cc0757aeac04ad5a7d6b8cf Session dir: /Users/example/proj/.kimi/sessions/d1c3750c0cc0757aeac04a...\n[84] role=_checkpoint id=15\n[85] role=_usage token_count=55629\n\n== Wire ==\n/Users/example/proj/.kimi/sessions/6a7967e2a97cd71a62b8375c5ae461ba/ef00f9f9-a470-4e50-b279-59429da67d27/wire.jsonl\nrecords: 123\ntypes: <raw>=1, ApprovalRequest=1, ApprovalResponse=1, ContentPart=22, StatusUpdate=14, StepBegin=14, ToolCall=27, ToolCallPart=14, ToolResult=26, TurnBegin=2, TurnEnd=1\n[112] type=ContentPart | part=think | text=第三轮也成功！测试了超时处理： 1. ✅ 任务正确超时 2. ✅ 状态为 failed，timed_out=true 3. ✅ 通知正确发送 (task.timed_out) 4. ✅ exit_code 正确 (-15) 现在进入观察轮，检查 session 产物，验证 notification 是否正确写入 context 等。\n[113] type=ContentPart | part=text | text=第三轮成功！超时处理完全正常。现在进入观察轮，检查 session 产物：\n[114] type=ToolCall | tool=SetTodoList\n[115] type=ToolCall | tool=Shell\n[116] type=ToolResult\n[117] type=ToolCallPart\n[118] type=StatusUpdate | context_tokens=54774\n[119] type=ToolResult\n[120] type=StepBegin | n=11\n[121] type=ContentPart | part=think | text=找到了 session 目录，下面有多个子目录（每次运行 CLI 会创建一个新的子 session）。让我使用 inspect_session.py 来检查最新的 session。\n[122] type=ToolCall | tool=Shell\n[123] type=StatusUpdate | context_tokens=55629\n", "message": "Command executed successfully.", "display": [], "extras": null}}}}
+{"timestamp": 1773723631.259616, "message": {"type": "StepBegin", "payload": {"n": 12}}}
+{"timestamp": 1773723634.7667892, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "这个 session 不是我刚才测试的那个。让我直接检查正确的 session 目录（d1c3750c0cc0757aeac04ad5a7d6b8cf），里面有多个子目录，对应三次测试运行。", "encrypted": null}}}
+{"timestamp": 1773723639.134093, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_DmwmxRwjKGDXt1PTAyVbYAdM", "function": {"name": "Shell", "arguments": "{\"command\": \"SMOKE_DIR=\\\"/tmp/kimi-smoke-a2i1xj\\\"\\nSESSION_ID=$(echo -n \\\"$SMOKE_DIR\\\" | md5)\\nSESSION_DIR=\\\"$HOME/.kimi/sessions/$SESSION_ID\\\"\\n\\necho \\\"=== 检查正确的 session 目录 ===\\\"\\necho \\\"Session dir: $SESSION_DIR\\\"\\necho \\\"\\\"\\necho \\\"=== 子目录列表 ===\\\"\\nls -la \\\"$SESSION_DIR\\\"\\n\\n# 检查每个子目录的 wire.jsonl 中的 Notification 事件\\necho \\\"\\\"\\necho \\\"=== 检查 Notification 事件 ===\\\"\\nfor subdir in \\\"$SESSION_DIR\\\"/*; do\\n    if [ -d \\\"$subdir\\\" ] && [ -f \\\"$subdir/wire.jsonl\\\" ]; then\\n        subname=$(basename \\\"$subdir\\\")\\n        echo \\\"\\\"\\n        echo \\\"--- Sub-session: $subname ---\\\"\\n        # 查找 Notification 事件\\n        grep -c '\\\"type\\\":\\\"Notification\\\"' \\\"$subdir/wire.jsonl\\\" 2>/dev/null || echo \\\"0\\\"\\n    fi\\ndone\"}"}, "extras": null}}}
+{"timestamp": 1773723639.135063, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.21719741821289062, "context_tokens": 56937, "max_context_tokens": 262144, "token_usage": {"input_other": 1385, "output": 298, "input_cache_read": 55552, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-0028", "plan_mode": false}}}
+{"timestamp": 1773723639.176179, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tool_DmwmxRwjKGDXt1PTAyVbYAdM", "return_value": {"is_error": false, "output": "=== 检查正确的 session 目录 ===\nSession dir: /Users/example/proj/.kimi/sessions/d1c3750c0cc0757aeac04ad5a7d6b8cf\n\n=== 子目录列表 ===\ntotal 0\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:59 .\ndrwxr-xr-x@ 1722 user      staff  55104  3月 17 12:58 ..\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:58 0e1d3b94-dae2-4dfb-b36d-717397f4d2f6\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:59 228b54e2-5b5d-4675-94f2-ec56e42cdbae\ndrwxr-xr-x@    6 user      staff    192  3月 17 13:00 be8228d5-1c57-43dc-9f23-9e7dba209a1a\ndrwxr-xr-x@    4 user      staff    128  3月 17 12:58 ea3920e8-2a4b-4e38-be51-c500aab582ab\n\n=== 检查 Notification 事件 ===\n\n--- Sub-session: 0e1d3b94-dae2-4dfb-b36d-717397f4d2f6 ---\n0\n0\n\n--- Sub-session: 228b54e2-5b5d-4675-94f2-ec56e42cdbae ---\n0\n0\n\n--- Sub-session: be8228d5-1c57-43dc-9f23-9e7dba209a1a ---\n0\n0\n\n--- Sub-session: ea3920e8-2a4b-4e38-be51-c500aab582ab ---\n0\n0\n", "message": "Command executed successfully.", "display": [], "extras": null}}}}
+{"timestamp": 1773723639.178098, "message": {"type": "StepBegin", "payload": {"n": 13}}}
diff --git a/packages/migration-legacy/test/fixtures/legacy-protocol-1.3/context.jsonl b/packages/migration-legacy/test/fixtures/legacy-protocol-1.3/context.jsonl
new file mode 100644
index 000000000..4549c3c02
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/legacy-protocol-1.3/context.jsonl
@@ -0,0 +1,10 @@
+{"role": "_checkpoint", "id": 0}
+{"role": "user", "content": "帮我写一个示例函数，处理字符串清理和分块"}
+{"role": "_checkpoint", "id": 1}
+{"role":"user","content":"<system-reminder>\n<!-- plan-mode-reminder -->\nPlan mode is active. You are in a research and planning phase.\n\nIn plan mode, you should:\n1. Thoroughly explore the codebase using Glob, Grep, and ReadFile tools.\n2. Understand existing patterns and architecture.\n3. Design an implementation approach.\n4. Write your plan to the plan file using WriteFile.\n5. Use AskUserQuestion if you need to clarify approaches.\n6. When your plan is complete, call ExitPlanMode.\n\nRemember: DO NOT write or edit code files... [truncated]"}
+{"role": "_usage", "token_count": 9665}
+{"role": "assistant", "content": [{"type": "think", "think": "用户想要写一个示例函数，处理字符串清理和分块。我先看看当前 diff 中有哪些相关代码可以参考。\n\n让我先检查一下当前的 git diff。", "encrypted": null}], "tool_calls": [{"type": "function", "id": "Shell:0", "function": {"name": "Shell", "arguments": "{\"command\": \"git diff --no-color\"}"}}]}
+{"role": "_usage", "token_count": 9722}
+{"role": "tool", "content": [{"type": "text", "text": "<system>Command executed successfully.</system>"}, {"type": "text", "text": "diff --git a/example.py b/example.py\nindex 0000aaaa..1111bbbb 100644\n--- a/example.py\n+++ b/example.py\n@@ -1,12 +1,16 @@\n class Greeter:\n     def __init__(self, name: str) -> None:\n         self.name = name\n+        self.greetings: list[str] = []\n \n     def greet(self) -> str:\n-        return f\"Hello, {self.name}!\"\n+        msg = f\"Hello, {self.name}!\"\n+        self.greetings.append(msg)\n+        return msg\n \n-    def farewell(self) -> str:\n-        return f\"Goodbye, {self.name}!\"\n+    def farewell(self, formal: bool = False) -> str:\n+        prefix = \"Farewell\" if formal else \"Goodbye\"\n+        return f\"{prefix}, {self.name}!\"\n \ndiff --git a/example/utils.py b/example/utils.py\nindex 22223333..44445555 100644\n--- a/example/utils.py\n+++ b/example/utils.py\n@@ -10,16 +10,20 @@ def slugify(text: str) -> str:\n     result = text.lower()\n     result = result.replace(\" \", \"-\")\n-    # Remove punctuation\n-    result = \"\".join(c for c in result if c.isalnum() or c == \"-\")\n+    # Remove punctuation and collapse repeated dashes\n+    cleaned = \"\".join(c for c in result if c.isalnum() or c == \"-\")\n+    parts = [p for p in cleaned.split(\"-\") if p]\n+    result = \"-\".join(parts)\n     return result\n \n \n def chunk(items: list[str], size: int) -> list[list[str]]:\n-    if size <= 0:\n-        raise ValueError(\"size must be positive\")\n-    return [items[i:i + size] for i in range(0, len(items), size)]\n+    if size <= 0:\n+        raise ValueError(\"chunk size must be a positive integer\")\n+    if not items:\n+        return []\n+    return [items[i : i + size] for i in range(0, len(items), size)]\n \n \n def truncate(text: str, limit: int = 80) -> str:\n@@ -32,8 +36,12 @@ def truncate(text: str, limit: int = 80) -> str:\n         return text\n     return text[: limit - 1] + \"…\"\n \n+\n+def normalize_whitespace(text: str) -> str:\n+    return \" \".join(text.split())\n+\n diff --git a/example/cli.py b/example/cli.py\nindex 66667777..88889999 100644\n--- a/example/cli.py\n+++ b/example/cli.py\n@@ -5,12 +5,18 @@ from .utils import slugify, truncate\n \n def build_parser() -> argparse.ArgumentParser:\n     parser = argparse.ArgumentParser(prog=\"example\")\n-    parser.add_argument(\"--name\", default=\"world\")\n+    parser.add_argument(\"--name\", default=\"world\", help=\"who to greet\")\n+    parser.add_argument(\n+        \"--formal\",\n+        action=\"store_true\",\n+        help=\"use a formal farewell tone\",\n+    )\n     return parser\n \n \n def main(argv: list[str] | None = None) -> int:\n     parser = build_parser()\n     args = parser.parse_args(argv)\n-    print(f\"Hello, {args.name}!\")\n+    greeter = Greeter(args.name)\n+    print(greeter.greet())\n+    print(greeter.farewell(formal=args.formal))\n     return 0\ndiff --git a/example/config.py b/example/config.py\nindex ccccdddd..eeeeffff 100644\n--- a/example/config.py\n+++ b/example/config.py\n@@ -1,15 +1,22 @@\n from dataclasses import dataclass, field\n+from pathlib import Path\n \n \n @dataclass\n class AppConfig:\n     name: str = \"example\"\n     verbose: bool = False\n-    timeout: int = 30\n+    timeout_seconds: int = 30\n+    cache_dir: Path | None = None\n     features: list[str] = field(default_factory=list)\n \n     def is_feature_enabled(self, feature: str) -> bool:\n         return feature in self.features\n+\n+    def with_feature(self, feature: str) -> \"AppConfig\":\n+        if feature in self.features:\n+            return self\n+        return AppConfig(**{**self.__dict__, \"features\": [*self.features, feature]})\n diff --git a/tests/test_example.py b/tests/test_example.py\nindex aabbccdd..eeff0011 100644\n--- a/tests/test_example.py\n+++ b/tests/test_example.py\n@@ -1,10 +1,22 @@\n from example import Greeter\n+from example.utils import slugify, chunk, normalize_whitespace\n+from example.config import AppConfig\n \n \n def test_greeter_greet() -> None:\n     g = Greeter(\"Ada\")\n     assert g.greet() == \"Hello, Ada!\"\n+    assert g.greetings == [\"Hello, Ada!\"]\n \n \n def test_greeter_farewell() -> None:\n     g = Greeter(\"Ada\")\n     assert g.farewell() == \"Goodbye, Ada!\"\n+    assert g.farewell(formal=True) == \"Farewell, Ada!\"\n+\n+\n+def test_slugify_collapses_dashes() -> None:\n+    assert slugify(\"hello   world!!!\") == \"hello-world\"\n+    assert slugify(\"--abc--def--\") == \"abc-def\"\n+\n+\n+def test_config_with_feature_is_idempotent() -> None:\n+    cfg = AppConfig().with_feature(\"beta\").with_feature(\"beta\")\n+    assert cfg.features == [\"beta ... [truncated]"}], "tool_call_id": "Shell:0"}
+{"role": "_checkpoint", "id": 2}
+{"role": "_usage", "token_count": 11286}
diff --git a/packages/migration-legacy/test/fixtures/legacy-protocol-1.3/state.json b/packages/migration-legacy/test/fixtures/legacy-protocol-1.3/state.json
new file mode 100644
index 000000000..818625632
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/legacy-protocol-1.3/state.json
@@ -0,0 +1,20 @@
+{
+  "version": 1,
+  "approval": {
+    "yolo": false,
+    "auto_approve_actions": [
+      "run command"
+    ]
+  },
+  "additional_dirs": [],
+  "custom_title": "帮我创建一个 plan，来优化我当前 diff 中的代码",
+  "title_generated": false,
+  "title_generate_attempts": 0,
+  "plan_mode": false,
+  "plan_session_id": null,
+  "plan_slug": null,
+  "wire_mtime": 1773128903.353285,
+  "archived": true,
+  "archived_at": 1774779476.84407,
+  "auto_archive_exempt": false
+}
\ No newline at end of file
diff --git a/packages/migration-legacy/test/fixtures/legacy-protocol-1.3/wire.jsonl b/packages/migration-legacy/test/fixtures/legacy-protocol-1.3/wire.jsonl
new file mode 100644
index 000000000..03bb686c6
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/legacy-protocol-1.3/wire.jsonl
@@ -0,0 +1,10 @@
+{"type": "metadata", "protocol_version": "1.3"}
+{"timestamp": 1773128640.5874681, "message": {"type": "TurnBegin", "payload": {"user_input": [{"type": "text", "text": "帮我写一个示例函数，处理字符串清理和分块"}]}}}
+{"timestamp": 1773128640.589089, "message": {"type": "StepBegin", "payload": {"n": 1}}}
+{"timestamp": 1773128644.0387058, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "用户想要写一个示例函数，处理字符串清理和分块。我先看看当前 diff 中有哪些相关代码可以参考。\n\n让我先检查一下当前的 git diff。", "encrypted": null}}}
+{"timestamp": 1773128644.1119459, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "Shell:0", "function": {"name": "Shell", "arguments": "{\"command\": \"git diff --no-color\"}"}, "extras": null}}}
+{"timestamp": 1773128644.112614, "message": {"type": "ApprovalRequest", "payload": {"id": "245bc43b-84ab-4db1-9e40-3f5508b0404f", "tool_call_id": "Shell:0", "sender": "Shell", "action": "run command", "description": "Run command `git diff --no-color`", "display": [{"type": "shell", "language": "bash", "command": "git diff --no-color"}]}}}
+{"timestamp": 1773128644.112929, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.03866, "context_tokens": 9665, "max_context_tokens": 250000, "token_usage": {"input_other": 4033, "output": 57, "input_cache_read": 5632, "input_cache_creation": 0}, "message_id": "chatcmpl-fixture-legacy-0001"}}}
+{"timestamp": 1773128714.045961, "message": {"type": "ApprovalResponse", "payload": {"request_id": "245bc43b-84ab-4db1-9e40-3f5508b0404f", "response": "approve_for_session"}}}
+{"timestamp": 1773128714.070226, "message": {"type": "ToolResult", "payload": {"tool_call_id": "Shell:0", "return_value": {"is_error": false, "output": "diff --git a/example.py b/example.py\nindex 0000aaaa..1111bbbb 100644\n--- a/example.py\n+++ b/example.py\n@@ -1,12 +1,16 @@\n class Greeter:\n     def __init__(self, name: str) -> None:\n         self.name = name\n+        self.greetings: list[str] = []\n \n     def greet(self) -> str:\n-        return f\"Hello, {self.name}!\"\n+        msg = f\"Hello, {self.name}!\"\n+        self.greetings.append(msg)\n+        return msg\n \n-    def farewell(self) -> str:\n-        return f\"Goodbye, {self.name}!\"\n+    def farewell(self, formal: bool = False) -> str:\n+        prefix = \"Farewell\" if formal else \"Goodbye\"\n+        return f\"{prefix}, {self.name}!\"\n \ndiff --git a/example/utils.py b/example/utils.py\nindex 22223333..44445555 100644\n--- a/example/utils.py\n+++ b/example/utils.py\n@@ -10,16 +10,20 @@ def slugify(text: str) -> str:\n     result = text.lower()\n     result = result.replace(\" \", \"-\")\n-    # Remove punctuation\n-    result = \"\".join(c for c in result if c.isalnum() or c == \"-\")\n+    # Remove punctuation and collapse repeated dashes\n+    cleaned = \"\".join(c for c in result if c.isalnum() or c == \"-\")\n+    parts = [p for p in cleaned.split(\"-\") if p]\n+    result = \"-\".join(parts)\n     return result\n \n \n def chunk(items: list[str], size: int) -> list[list[str]]:\n-    if size <= 0:\n-        raise ValueError(\"size must be positive\")\n-    return [items[i:i + size] for i in range(0, len(items), size)]\n+    if size <= 0:\n+        raise ValueError(\"chunk size must be a positive integer\")\n+    if not items:\n+        return []\n+    return [items[i : i + size] for i in range(0, len(items), size)]\n \n \n def truncate(text: str, limit: int = 80) -> str:\n@@ -32,8 +36,12 @@ def truncate(text: str, limit: int = 80) -> str:\n         return text\n     return text[: limit - 1] + \"…\"\n \n+\n+def normalize_whitespace(text: str) -> str:\n+    return \" \".join(text.split())\n+\n diff --git a/example/cli.py b/example/cli.py\nindex 66667777..88889999 100644\n--- a/example/cli.py\n+++ b/example/cli.py\n@@ -5,12 +5,18 @@ from .utils import slugify, truncate\n \n def build_parser() -> argparse.ArgumentParser:\n     parser = argparse.ArgumentParser(prog=\"example\")\n-    parser.add_argument(\"--name\", default=\"world\")\n+    parser.add_argument(\"--name\", default=\"world\", help=\"who to greet\")\n+    parser.add_argument(\n+        \"--formal\",\n+        action=\"store_true\",\n+        help=\"use a formal farewell tone\",\n+    )\n     return parser\n \n \n def main(argv: list[str] | None = None) -> int:\n     parser = build_parser()\n     args = parser.parse_args(argv)\n-    print(f\"Hello, {args.name}!\")\n+    greeter = Greeter(args.name)\n+    print(greeter.greet())\n+    print(greeter.farewell(formal=args.formal))\n     return 0\ndiff --git a/example/config.py b/example/config.py\nindex ccccdddd..eeeeffff 100644\n--- a/example/config.py\n+++ b/example/config.py\n@@ -1,15 +1,22 @@\n from dataclasses import dataclass, field\n+from pathlib import Path\n \n \n @dataclass\n class AppConfig:\n     name: str = \"example\"\n     verbose: bool = False\n-    timeout: int = 30\n+    timeout_seconds: int = 30\n+    cache_dir: Path | None = None\n     features: list[str] = field(default_factory=list)\n \n     def is_feature_enabled(self, feature: str) -> bool:\n         return feature in self.features\n+\n+    def with_feature(self, feature: str) -> \"AppConfig\":\n+        if feature in self.features:\n+            return self\n+        return AppConfig(**{**self.__dict__, \"features\": [*self.features, feature]})\n diff --git a/tests/test_example.py b/tests/test_example.py\nindex aabbccdd..eeff0011 100644\n--- a/tests/test_example.py\n+++ b/tests/test_example.py\n@@ -1,10 +1,22 @@\n from example import Greeter\n+from example.utils import slugify, chunk, normalize_whitespace\n+from example.config import AppConfig\n \n \n def test_greeter_greet() -> None:\n     g = Greeter(\"Ada\")\n     assert g.greet() == \"Hello, Ada!\"\n+    assert g.greetings == [\"Hello, Ada!\"]\n \n \n def test_greeter_farewell() -> None:\n     g = Greeter(\"Ada\")\n     assert g.farewell() == \"Goodbye, Ada!\"\n+    assert g.farewell(formal=True) == \"Farewell, Ada!\"\n+\n+\n+def test_slugify_collapses_dashes() -> None:\n+    assert slugify(\"hello   world!!!\") == \"hello-world\"\n+    assert slugify(\"--abc--def--\") == \"abc-def\"\n+\n+\n+def test_config_with_feature_is_idempotent() -> None:\n+    cfg = AppConfig().with_feature(\"beta\").with_feature(\"beta\")\n+    assert cfg.features == [\"beta\"]\n", "message": "Command executed successfully.", "display": [], "extras": null}}}}
+{"timestamp": 1773128714.072314, "message": {"type": "StepBegin", "payload": {"n": 2}}}
diff --git a/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/kimi.json b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/kimi.json
new file mode 100644
index 000000000..fc0636ee3
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/kimi.json
@@ -0,0 +1,7 @@
+{
+  "work_dirs": [
+    { "path": "/proj-a", "kaos": "local", "last_session_id": null },
+    { "path": "/proj-b", "kaos": "local", "last_session_id": null },
+    { "path": "/proj-c", "kaos": "kaos-foo", "last_session_id": null }
+  ]
+}
diff --git a/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/73d3cf4d1cf337adf57d6732b8be2205/uuid-a1/context.jsonl b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/73d3cf4d1cf337adf57d6732b8be2205/uuid-a1/context.jsonl
new file mode 100644
index 000000000..2cdab36fb
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/73d3cf4d1cf337adf57d6732b8be2205/uuid-a1/context.jsonl
@@ -0,0 +1,3 @@
+{"role":"_system_prompt","content":"You are a helper."}
+{"role":"user","content":"hello from a1"}
+{"role":"assistant","content":[{"type":"text","text":"hi a1"}]}
diff --git a/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/73d3cf4d1cf337adf57d6732b8be2205/uuid-a1/state.json b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/73d3cf4d1cf337adf57d6732b8be2205/uuid-a1/state.json
new file mode 100644
index 000000000..a96808529
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/73d3cf4d1cf337adf57d6732b8be2205/uuid-a1/state.json
@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "approval": { "yolo": false, "auto_approve_actions": [] },
+  "additional_dirs": [],
+  "custom_title": "a1",
+  "title_generated": false,
+  "wire_mtime": 1700000000.0,
+  "archived": false,
+  "auto_archive_exempt": false
+}
diff --git a/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/73d3cf4d1cf337adf57d6732b8be2205/uuid-a2/context.jsonl b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/73d3cf4d1cf337adf57d6732b8be2205/uuid-a2/context.jsonl
new file mode 100644
index 000000000..394fd0d0a
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/73d3cf4d1cf337adf57d6732b8be2205/uuid-a2/context.jsonl
@@ -0,0 +1,3 @@
+{"role":"_system_prompt","content":"You are a helper."}
+{"role":"user","content":"hello from a2"}
+{"role":"assistant","content":[{"type":"text","text":"hi a2"}]}
diff --git a/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/73d3cf4d1cf337adf57d6732b8be2205/uuid-a2/state.json b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/73d3cf4d1cf337adf57d6732b8be2205/uuid-a2/state.json
new file mode 100644
index 000000000..478fd4662
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/73d3cf4d1cf337adf57d6732b8be2205/uuid-a2/state.json
@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "approval": { "yolo": false, "auto_approve_actions": [] },
+  "additional_dirs": [],
+  "custom_title": "a2",
+  "title_generated": false,
+  "wire_mtime": 1800000000.0,
+  "archived": false,
+  "auto_archive_exempt": false
+}
diff --git a/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/dbf62706c1b976e79a5e7cfcc3491a1f/uuid-b1/test b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/dbf62706c1b976e79a5e7cfcc3491a1f/uuid-b1/test
new file mode 100644
index 000000000..e69de29bb
diff --git a/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/kaos-foo_caaf674614e26c6365945408f85c9c9a/uuid-c1/context.jsonl b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/kaos-foo_caaf674614e26c6365945408f85c9c9a/uuid-c1/context.jsonl
new file mode 100644
index 000000000..825a092c7
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/kaos-foo_caaf674614e26c6365945408f85c9c9a/uuid-c1/context.jsonl
@@ -0,0 +1,3 @@
+{"role":"_system_prompt","content":"You are a remote helper."}
+{"role":"user","content":"hello from c1"}
+{"role":"assistant","content":[{"type":"text","text":"hi c1"}]}
diff --git a/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/kaos-foo_caaf674614e26c6365945408f85c9c9a/uuid-c1/state.json b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/kaos-foo_caaf674614e26c6365945408f85c9c9a/uuid-c1/state.json
new file mode 100644
index 000000000..f17177884
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/multi-workdir/.kimi/sessions/kaos-foo_caaf674614e26c6365945408f85c9c9a/uuid-c1/state.json
@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "approval": { "yolo": false, "auto_approve_actions": [] },
+  "additional_dirs": [],
+  "custom_title": "c1",
+  "title_generated": false,
+  "wire_mtime": 1900000000.0,
+  "archived": false,
+  "auto_archive_exempt": false
+}
diff --git a/packages/migration-legacy/test/fixtures/recent-protocol-1.10/context.jsonl b/packages/migration-legacy/test/fixtures/recent-protocol-1.10/context.jsonl
new file mode 100644
index 000000000..0e96b405e
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/recent-protocol-1.10/context.jsonl
@@ -0,0 +1,10 @@
+{"role":"_system_prompt","content":"You are an AI agent. (system prompt elided in fixture)"}
+{"role": "_checkpoint", "id": 0}
+{"role":"user","content":"hi"}
+{"role": "_checkpoint", "id": 1}
+{"role":"assistant","content":[{"type":"think","think":"The user said \"hi\". This is a simple greeting. I should respond in a friendly, helpful manner. Since there's no specific task or question, I'll just greet them back and ask how I can help.","encrypted":null},{"type":"text","text":"Hello! How can I help you today?"}]}
+{"role": "_checkpoint", "id": 2}
+{"role":"user","content":"探索这个项目"}
+{"role": "_checkpoint", "id": 3}
+{"role":"assistant","content":[{"type":"think","think":"用户要求探索这个项目。让我先了解一下项目的整体结构，然后提供一些关键信息。\n\n从目录结构来看，这是一个示例 Python 项目。让我先查看一些关键文件来更好地理解项目。","encrypted":null}],"tool_calls":[{"type":"function","id":"Shell:0","function":{"name":"Shell","arguments":"{\"command\": \"find . -maxdepth 2 -type f -name \\\"*.md\\\" | grep -E \\\"(README|CHANGELOG|CONTRIBUTING|AGENTS)\\\" | sort\"}"}},{"type":"function","id":"Shell:1","function":{"name":"Shell","arguments":"{\"command\": \"ls -la pyproject.toml Makefile 2>/dev/null || echo \\\"No pyproject.toml or Makefile found\\\"\"}"}},{"type":"function","id":"Shell:2","function":{"name":"Shell","arguments":"{\"command\": \"git log --oneline -10 2>/dev/null || echo \\\"Not a git repo or no commits\\\"\"}"}}]}
+{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"./.pytest_cache/README.md\n./AGENTS.md\n./CHANGELOG.md\n./CONTRIBUTING.md\n./docs/AGENTS.md\n./README.md\n./tests_e2e/AGENTS.md\n"}],"tool_call_id":"Shell:0"}
diff --git a/packages/migration-legacy/test/fixtures/recent-protocol-1.10/state.json b/packages/migration-legacy/test/fixtures/recent-protocol-1.10/state.json
new file mode 100644
index 000000000..f3d4ff8a3
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/recent-protocol-1.10/state.json
@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "approval": {
+    "yolo": false,
+    "afk": false,
+    "auto_approve_actions": [
+      "run command"
+    ]
+  },
+  "additional_dirs": [],
+  "custom_title": "hi",
+  "title_generated": false,
+  "title_generate_attempts": 0,
+  "plan_mode": false,
+  "plan_session_id": null,
+  "plan_slug": null,
+  "wire_mtime": null,
+  "archived": false,
+  "archived_at": null,
+  "auto_archive_exempt": false,
+  "todos": []
+}
\ No newline at end of file
diff --git a/packages/migration-legacy/test/fixtures/recent-protocol-1.10/wire.jsonl b/packages/migration-legacy/test/fixtures/recent-protocol-1.10/wire.jsonl
new file mode 100644
index 000000000..b8fa65824
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/recent-protocol-1.10/wire.jsonl
@@ -0,0 +1,10 @@
+{"type": "metadata", "protocol_version": "1.10"}
+{"timestamp": 1778563950.7300851, "message": {"type": "TurnBegin", "payload": {"user_input": [{"type": "text", "text": "hi"}]}}}
+{"timestamp": 1778563950.733035, "message": {"type": "StepBegin", "payload": {"n": 1}}}
+{"timestamp": 1778563951.794603, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "The user said \"hi\". This is a simple greeting. I should respond in a friendly, helpful manner. Since there's no specific task or question, I'll just greet them back and ask how I can help.", "encrypted": null}}}
+{"timestamp": 1778563951.826904, "message": {"type": "ContentPart", "payload": {"type": "text", "text": "Hello! How can I help you today?"}}}
+{"timestamp": 1778563951.827712, "message": {"type": "StatusUpdate", "payload": {"context_usage": null, "context_tokens": null, "max_context_tokens": null, "token_usage": null, "message_id": "chatcmpl-fixture-recent-0001", "plan_mode": false, "mcp_status": null}}}
+{"timestamp": 1778563951.8288698, "message": {"type": "TurnEnd", "payload": {}}}
+{"timestamp": 1778563970.0091572, "message": {"type": "TurnBegin", "payload": {"user_input": [{"type": "text", "text": "探索这个项目"}]}}}
+{"timestamp": 1778563970.010856, "message": {"type": "StepBegin", "payload": {"n": 1}}}
+{"timestamp": 1778563970.716398, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "用户要求探索这个项目。让我先了解一下项目的整体结构，然后提供一些关键信息。\n\n从目录结构来看，这是一个示例 Python 项目。让我先查看一些关键文件来更好地理解项目。", "encrypted": null}}}
diff --git a/packages/migration-legacy/test/fixtures/tiny-hello-world/context.jsonl b/packages/migration-legacy/test/fixtures/tiny-hello-world/context.jsonl
new file mode 100644
index 000000000..68089f19c
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/tiny-hello-world/context.jsonl
@@ -0,0 +1,5 @@
+{"role":"_system_prompt","content":"You are ..."}
+{"role":"_checkpoint","id":0}
+{"role":"user","content":"hi"}
+{"role":"_usage","token_count":9133}
+{"role":"assistant","content":[{"type":"text","text":"Hello! How can I help?"}]}
diff --git a/packages/migration-legacy/test/fixtures/tiny-hello-world/state.json b/packages/migration-legacy/test/fixtures/tiny-hello-world/state.json
new file mode 100644
index 000000000..4be7b7e7b
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/tiny-hello-world/state.json
@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "approval": { "yolo": false, "auto_approve_actions": [] },
+  "additional_dirs": [],
+  "custom_title": "hi",
+  "title_generated": false,
+  "wire_mtime": 1772616338.93,
+  "archived": false,
+  "auto_archive_exempt": false
+}
diff --git a/packages/migration-legacy/test/fixtures/tiny-hello-world/wire.jsonl b/packages/migration-legacy/test/fixtures/tiny-hello-world/wire.jsonl
new file mode 100644
index 000000000..200e71f95
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/tiny-hello-world/wire.jsonl
@@ -0,0 +1 @@
+{"type": "metadata", "protocol_version": "1.10"}
diff --git a/packages/migration-legacy/test/fixtures/with-image/context.jsonl b/packages/migration-legacy/test/fixtures/with-image/context.jsonl
new file mode 100644
index 000000000..f3856c22d
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/with-image/context.jsonl
@@ -0,0 +1,10 @@
+{"role":"_system_prompt","content":"You are an AI agent. (system prompt elided in fixture)"}
+{"role": "_checkpoint", "id": 0}
+{"role":"user","content":[{"type":"text","text":"Describe this image."},{"type":"image","url":"data:image/png;base64,AAAA","id":"img-1"}]}
+{"role": "_checkpoint", "id": 1}
+{"role":"user","content":"<system-reminder>\nYou are running in non-interactive mode. The user cannot answer questions or provide feedback during execution.\n- Do NOT call AskUserQuestion. If you need to make a decision, make your best judgment and proceed.\n- For EnterPlanMode / ExitPlanMode, they will be auto-approved. You can use them normally but expect no user feedback.\n</system-reminder>"}
+{"role": "_usage", "token_count": 11}
+{"role":"assistant","content":[{"type":"think","think":"analyzing the image","encrypted":null},{"type":"text","text":"The image shows a simple scene."}]}
+{"role": "_usage", "token_count": 16}
+{"role": "_checkpoint", "id": 2}
+{"role":"user","content":[{"type":"text","text":"Describe this audio clip."},{"type":"audio","url":"data:audio/wav;base64,AAAA","id":"aud-1"}]}
diff --git a/packages/migration-legacy/test/fixtures/with-image/wire.jsonl b/packages/migration-legacy/test/fixtures/with-image/wire.jsonl
new file mode 100644
index 000000000..b0fde690b
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/with-image/wire.jsonl
@@ -0,0 +1,10 @@
+{"type": "metadata", "protocol_version": "1.7"}
+{"timestamp": 1774872443.608067, "message": {"type": "TurnBegin", "payload": {"user_input": [{"type": "text", "text": "Describe this image."}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,AAAA", "id": null}}]}}}
+{"timestamp": 1774872443.609118, "message": {"type": "StepBegin", "payload": {"n": 1}}}
+{"timestamp": 1774872443.610024, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "analyzing the image", "encrypted": null}}}
+{"timestamp": 1774872443.6104598, "message": {"type": "ContentPart", "payload": {"type": "text", "text": "The image shows a simple scene."}}}
+{"timestamp": 1774872443.610832, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.00011, "context_tokens": 11, "max_context_tokens": 100000, "token_usage": {"input_other": 11, "output": 5, "input_cache_read": 0, "input_cache_creation": 0}, "message_id": "scripted-1", "plan_mode": false, "mcp_status": null}}}
+{"timestamp": 1774872443.6114979, "message": {"type": "TurnEnd", "payload": {}}}
+{"timestamp": 1774872443.612142, "message": {"type": "TurnBegin", "payload": {"user_input": [{"type": "text", "text": "Describe this video."}, {"type": "video_url", "video_url": {"url": "data:video/mp4;base64,AAAA", "id": null}}]}}}
+{"timestamp": 1774872443.61272, "message": {"type": "StepBegin", "payload": {"n": 1}}}
+{"timestamp": 1774872443.613224, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "analyzing the video", "encrypted": null}}}
diff --git a/packages/migration-legacy/test/fixtures/with-subagent-collapsed/context.jsonl b/packages/migration-legacy/test/fixtures/with-subagent-collapsed/context.jsonl
new file mode 100644
index 000000000..d86a7278c
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/with-subagent-collapsed/context.jsonl
@@ -0,0 +1,10 @@
+{"role":"_system_prompt","content":"You are an AI agent. (system prompt elided in fixture)"}
+{"role": "_checkpoint", "id": 0}
+{"role":"user","content":"你启动三个 sub agent，每个 sub，都要运行一些需要被批准的简单指令，运行两个以上"}
+{"role": "_checkpoint", "id": 1}
+{"role": "_usage", "token_count": 12095}
+{"role":"assistant","content":[{"type":"think","think":"用户要求我启动三个 sub agent，每个 sub agent 都需要运行一些需要被批准的简单指令，并且要求运行两个以上。\n\n我需要使用 Agent 工具来创建三个 sub agent。每个 sub agent 都应该执行一些需要批准的操作，比如文件写入或 shell 命令。\n\n让我创建三个 sub agent，每个都执行不同的需要批准的任务：\n1. 第一个 sub agent：创建一个测试文件\n2. 第二个 sub agent：执行一个简单的 shell 命令\n3. 第三个 sub agent：创建另一个测试文件\n\n我需要并行启动这三个 sub agent。","encrypted":null},{"type":"text","text":"我来启动三个 sub agent，每个都会执行需要批准的简单指令。"}],"tool_calls":[{"type":"function","id":"tool_Ct3NdbCjJ2Xbl7YzithE2Dy8","function":{"name":"Agent","arguments":"{\"description\": \"Sub agent 1: 创建文件\", \"prompt\": \"你是一个测试用的 sub agent。请执行以下需要批准的操作：\\n\\n1. 使用 WriteFile 工具在当前目录创建一个名为 `subagent1_test.txt` 的文件，内容为 \\\"Hello from Sub Agent 1!\\\"\\n\\n这个操作需要用户批准，请等待批准并完成操作。\\n\\n完成后，报告操作结果。\"}"}},{"type":"function","id":"tool_OtoGSYsrDQpEaav0hLYbXDhd","function":{"name":"Agent","arguments":"{\"description\": \"Sub agent 2: Shell 命令\", \"prompt\": \"你是一个测试用的 sub agent。请执行以下需要批准的操作：\\n\\n1. 使用 Shell 工具执行命令 `echo \\\"Hello from Sub Agent 2!\\\" > subagent2_test.txt`\\n\\n这个操作需要用户批准，请等待批准并完成操作。\\n\\n完成后，报告操作结果。\"}"}},{"type":"function","id":"tool_zi4b3Pfbiia2kxPMUvjL4cVN","function":{"name":"Agent","arguments":"{\"description\": \"Sub agent 3: 创建文件\", \"prompt\": \"你是一个测试用的 sub agent。请执行以下需要批准的操作：\\n\\n1. 使用 WriteFile 工具在当前目录创建一个名为 `subagent3_test.txt` 的文件，内容为 \\\"Hello from Sub Agent 3!\\\"\\n\\n这个操作需要用户批准，请等待批准并完成操作。\\n\\n完成后，报告操作结果。\"}"}}]}
+{"role": "_usage", "token_count": 12507}
+{"role":"tool","content":"agent_id: ac1f74988\nresumed: false\nactual_subagent_type: coder\nstatus: completed\n\n[summary]\n## 详细操作报告\n\n### 任务背景\n作为测试用的 sub agent，我被要求执行一个需要用户批准的文件写入操作。这是一个测试场景，旨在验证带批准流程的工具调用机制。\n\n### 执行过程\n\n#### 第一次尝试（被拒绝）\n- **操作**: 使用 `WriteFile` 工具创建文件 `subagent1_test.txt`\n- **预期内容**: `\"Hello from Sub Agent 1!\"`\n- **结果**: 用户拒绝了此操作\n- **用户反馈**: 要求将文件名改为 `kk`\n\n#### 第二次尝试（成功）\n- **操作**: 使用 `WriteFile` 工具创建文件 `kk`\n- **内容**: `\"Hello from Sub Agent 1!\"`\n- **结果**: ✅ 成功创建/覆盖文件\n- **文件大小**: 23 字节\n\n### 技术细节\n\n1. **工具使用**: `W... [truncated]","tool_call_id":"tool_Ct3NdbCjJ2Xbl7YzithE2Dy8"}
+{"role": "tool", "content": "agent_id: aa373b195\nresumed: false\nactual_subagent_type: coder\nstatus: completed\n\n[summary]\n## 详细操作结果报告\n\n### 1. 任务概述\n\n作为测试用 sub agent，我成功执行了需要用户批准的 Shell 命令操作，创建了测试文件并验证了其内容完整性。\n\n### 2. 执行详情\n\n#### 2.1 命令信息\n- **命令类型**: Shell 命令执行\n- **具体命令**: `echo \"Hello from Sub Agent 2!\" > subagent2_test.txt`\n- **工作目录**: `/Users/example/proj/example-project`\n- **执行时间**: 2026-03-23T21:42:43+08:00（系统参考时间）\n\n#### 2.2 技术实现\n该命令使用了以下 Shell 特性：\n- `echo` 命令：输出字符串到标准输出\n- 重定向操作符 `>`：将标准输出重定向到文件\n- 如果文件不存在则... [truncated]", "tool_call_id": "tool_OtoGSYsrDQpEaav0hLYbXDhd"}
+{"role": "tool", "content": "agent_id: aadd98577\nresumed: false\nactual_subagent_type: coder\nstatus: completed\n\n[summary]\n**详细操作报告 - Sub Agent 3**\n\n---\n\n## 1. 任务概述\n\n本次任务要求以测试用的 sub agent 身份执行一个需要用户批准的操作：在指定目录创建一个包含特定内容的文本文件。\n\n---\n\n## 2. 操作执行详情\n\n### 2.1 第一次尝试\n\n| 属性 | 详情 |\n|------|------|\n| **目标文件路径** | `subagent3_test.txt` |\n| **请求内容** | `Hello from Sub Agent 3!` |\n| **操作类型** | WriteFile（覆盖模式，默认）|\n| **执行状态** | 被拒绝 |\n| **用户反馈** | \"用另一个文件名再试一次\" |\n\n**技术分析**：系统在第一次请求时触发了用户审批流程。用户拒绝了原始文件名 `subagent3_test.txt`，并明确要求使用另一个文件名再试。这表... [truncated]", "tool_call_id": "tool_zi4b3Pfbiia2kxPMUvjL4cVN"}
diff --git a/packages/migration-legacy/test/fixtures/with-subagent-collapsed/state.json b/packages/migration-legacy/test/fixtures/with-subagent-collapsed/state.json
new file mode 100644
index 000000000..93c632372
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/with-subagent-collapsed/state.json
@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "approval": {
+    "yolo": false,
+    "auto_approve_actions": []
+  },
+  "additional_dirs": [],
+  "custom_title": "你启动三个 sub agent，每个 sub，都要运行一些需要被批准的简单指令，运行两个以上",
+  "title_generated": false,
+  "title_generate_attempts": 1,
+  "plan_mode": false,
+  "plan_session_id": null,
+  "plan_slug": null,
+  "wire_mtime": 1774273468.238773,
+  "archived": false,
+  "archived_at": null,
+  "auto_archive_exempt": false
+}
\ No newline at end of file
diff --git a/packages/migration-legacy/test/fixtures/with-subagent-collapsed/wire.jsonl b/packages/migration-legacy/test/fixtures/with-subagent-collapsed/wire.jsonl
new file mode 100644
index 000000000..94330cbcc
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/with-subagent-collapsed/wire.jsonl
@@ -0,0 +1,10 @@
+{"type": "metadata", "protocol_version": "1.6"}
+{"timestamp": 1774273363.887481, "message": {"type": "TurnBegin", "payload": {"user_input": [{"type": "text", "text": "你启动三个 sub agent，每个 sub，都要运行一些需要被批准的简单指令，运行两个以上"}]}}}
+{"timestamp": 1774273363.888598, "message": {"type": "StepBegin", "payload": {"n": 1}}}
+{"timestamp": 1774273371.364724, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "用户要求我启动三个 sub agent，每个 sub agent 都需要运行一些需要被批准的简单指令，并且要求运行两个以上。\n\n我需要使用 Agent 工具来创建三个 sub agent。每个 sub agent 都应该执行一些需要批准的操作，比如文件写入或 shell 命令。\n\n让我创建三个 sub agent，每个都执行不同的需要批准的任务：\n1. 第一个 sub agent：创建一个测试文件\n2. 第二个 sub agent：执行一个简单的 shell 命令\n3. 第三个 sub agent：创建另一个测试文件\n\n我需要并行启动这三个 sub agent。", "encrypted": null}}}
+{"timestamp": 1774273371.87823, "message": {"type": "ContentPart", "payload": {"type": "text", "text": "我来启动三个 sub agent，每个都会执行需要批准的简单指令。"}}}
+{"timestamp": 1774273375.4379919, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_Ct3NdbCjJ2Xbl7YzithE2Dy8", "function": {"name": "Agent", "arguments": "{\"description\": \"Sub agent 1: 创建文件\", \"prompt\": \"你是一个测试用的 sub agent。请执行以下需要批准的操作：\\n\\n1. 使用 WriteFile 工具在当前目录创建一个名为 `subagent1_test.txt` 的文件，内容为 \\\"Hello from Sub Agent 1!\\\"\\n\\n这个操作需要用户批准，请等待批准并完成操作。\\n\\n完成后，报告操作结果。\"}"}, "extras": null}}}
+{"timestamp": 1774273375.475582, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tool_OtoGSYsrDQpEaav0hLYbXDhd", "function": {"name": "Agent", "arguments": "{\"description\": \""}, "extras": null}}}
+{"timestamp": 1774273375.476424, "message": {"type": "SubagentEvent", "payload": {"parent_tool_call_id": "tool_Ct3NdbCjJ2Xbl7YzithE2Dy8", "agent_id": "ac1f74988", "subagent_type": "coder", "event": {"type": "TurnBegin", "payload": {"user_input": "你是一个测试用的 sub agent。请执行以下需要批准的操作：\n\n1. 使用 WriteFile 工具在当前目录创建一个名为 `subagent1_test.txt` 的文件，内容为 \"Hello from Sub Agent 1!\"\n\n这个操作需要用户批准，请等待批准并完成操作。\n\n完成后，报告操作结果。"}}}}}
+{"timestamp": 1774273375.4771452, "message": {"type": "SubagentEvent", "payload": {"parent_tool_call_id": "tool_Ct3NdbCjJ2Xbl7YzithE2Dy8", "agent_id": "ac1f74988", "subagent_type": "coder", "event": {"type": "StepBegin", "payload": {"n": 1}}}}}
+{"timestamp": 1774273378.226876, "message": {"type": "ToolCallPart", "payload": {"arguments_part": "Sub agent 2: Shell 命令\", \"prompt\": \"你是一个测试用的 sub agent。请执行以下需要批准的操作：\\n\\n1. 使用 Shell 工具执行命令 `echo \\\"Hello from Sub Agent 2!\\\" > subagent2_test.txt`\\n\\n这个操作需要用户批准，请等待批准并完成操作。\\n\\n完成后，"}}}
diff --git a/packages/migration-legacy/test/fixtures/with-thinking/context.jsonl b/packages/migration-legacy/test/fixtures/with-thinking/context.jsonl
new file mode 100644
index 000000000..2ae6ce2ed
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/with-thinking/context.jsonl
@@ -0,0 +1,10 @@
+{"role":"_system_prompt","content":"You are an AI agent. (system prompt elided in fixture)"}
+{"role": "_checkpoint", "id": 0}
+{"role":"user","content":"Describe this image."}
+{"role": "_checkpoint", "id": 1}
+{"role":"user","content":"<system-reminder>\nYou are running in non-interactive mode. The user cannot answer questions or provide feedback during execution.\n- Do NOT call AskUserQuestion. If you need to make a decision, make your best judgment and proceed.\n- For EnterPlanMode / ExitPlanMode, they will be auto-approved. You can use them normally but expect no user feedback.\n</system-reminder>"}
+{"role": "_usage", "token_count": 11}
+{"role":"assistant","content":[{"type":"think","think":"analyzing the image","encrypted":null},{"type":"text","text":"The image shows a simple scene."}]}
+{"role": "_usage", "token_count": 16}
+{"role": "_checkpoint", "id": 2}
+{"role":"user","content":"Describe this video."}
diff --git a/packages/migration-legacy/test/fixtures/with-thinking/state.json b/packages/migration-legacy/test/fixtures/with-thinking/state.json
new file mode 100644
index 000000000..67a8244a9
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/with-thinking/state.json
@@ -0,0 +1,19 @@
+{
+  "version": 1,
+  "approval": {
+    "yolo": false,
+    "auto_approve_actions": []
+  },
+  "additional_dirs": [],
+  "custom_title": "Describe this image.",
+  "title_generated": false,
+  "title_generate_attempts": 0,
+  "plan_mode": false,
+  "plan_session_id": null,
+  "plan_slug": null,
+  "wire_mtime": null,
+  "archived": false,
+  "archived_at": null,
+  "auto_archive_exempt": false,
+  "todos": []
+}
\ No newline at end of file
diff --git a/packages/migration-legacy/test/fixtures/with-thinking/wire.jsonl b/packages/migration-legacy/test/fixtures/with-thinking/wire.jsonl
new file mode 100644
index 000000000..bf9b36646
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/with-thinking/wire.jsonl
@@ -0,0 +1,10 @@
+{"type": "metadata", "protocol_version": "1.9"}
+{"timestamp": 1776961639.307648, "message": {"type": "TurnBegin", "payload": {"user_input": "Describe this image."}}}
+{"timestamp": 1776961639.3084009, "message": {"type": "StepBegin", "payload": {"n": 1}}}
+{"timestamp": 1776961639.309221, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "analyzing the image", "encrypted": null}}}
+{"timestamp": 1776961639.309566, "message": {"type": "ContentPart", "payload": {"type": "text", "text": "The image shows a simple scene."}}}
+{"timestamp": 1776961639.3098629, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.00011, "context_tokens": 11, "max_context_tokens": 100000, "token_usage": {"input_other": 11, "output": 5, "input_cache_read": 0, "input_cache_creation": 0}, "message_id": "scripted-1", "plan_mode": false, "mcp_status": null}}}
+{"timestamp": 1776961639.3107672, "message": {"type": "TurnEnd", "payload": {}}}
+{"timestamp": 1776961639.311408, "message": {"type": "TurnBegin", "payload": {"user_input": "Describe this video."}}}
+{"timestamp": 1776961639.311872, "message": {"type": "StepBegin", "payload": {"n": 1}}}
+{"timestamp": 1776961639.31232, "message": {"type": "ContentPart", "payload": {"type": "think", "think": "analyzing the video", "encrypted": null}}}
diff --git a/packages/migration-legacy/test/fixtures/with-tool-calls/context.jsonl b/packages/migration-legacy/test/fixtures/with-tool-calls/context.jsonl
new file mode 100644
index 000000000..c0a265afa
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/with-tool-calls/context.jsonl
@@ -0,0 +1,10 @@
+{"role":"_system_prompt","content":"You are an AI agent. (system prompt elided in fixture)"}
+{"role": "_checkpoint", "id": 0}
+{"role":"user","content":"run echo hi"}
+{"role": "_checkpoint", "id": 1}
+{"role":"user","content":"<system-reminder>\nYou are running in non-interactive mode. The user cannot answer questions or provide feedback during execution.\n- Do NOT call AskUserQuestion. If you need to make a decision, make your best judgment and proceed.\n- For EnterPlanMode / ExitPlanMode, they will be auto-approved. You can use them normally but expect no user feedback.\n</system-reminder>"}
+{"role": "_usage", "token_count": 10}
+{"role":"assistant","content":[],"tool_calls":[{"type":"function","id":"tc1","function":{"name":"Shell","arguments":"{\"command\": \"echo hi\"}"}}]}
+{"role": "_usage", "token_count": 12}
+{"role":"tool","content":"<system>ERROR: Shell blocked by hook</system>","tool_call_id":"tc1"}
+{"role": "_checkpoint", "id": 2}
diff --git a/packages/migration-legacy/test/fixtures/with-tool-calls/state.json b/packages/migration-legacy/test/fixtures/with-tool-calls/state.json
new file mode 100644
index 000000000..da31ab25f
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/with-tool-calls/state.json
@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "approval": {
+    "yolo": false,
+    "auto_approve_actions": []
+  },
+  "additional_dirs": [],
+  "custom_title": "run echo hi",
+  "title_generated": false,
+  "title_generate_attempts": 0,
+  "plan_mode": false,
+  "plan_session_id": null,
+  "plan_slug": null
+}
\ No newline at end of file
diff --git a/packages/migration-legacy/test/fixtures/with-tool-calls/wire.jsonl b/packages/migration-legacy/test/fixtures/with-tool-calls/wire.jsonl
new file mode 100644
index 000000000..9680822d5
--- /dev/null
+++ b/packages/migration-legacy/test/fixtures/with-tool-calls/wire.jsonl
@@ -0,0 +1,10 @@
+{"type": "metadata", "protocol_version": "1.8"}
+{"timestamp": 1774949785.23238, "message": {"type": "TurnBegin", "payload": {"user_input": "run echo hi"}}}
+{"timestamp": 1774949785.233404, "message": {"type": "StepBegin", "payload": {"n": 1}}}
+{"timestamp": 1774949785.2350621, "message": {"type": "ToolCall", "payload": {"type": "function", "id": "tc1", "function": {"name": "Shell", "arguments": "{\"command\": \"echo hi\"}"}, "extras": null}}}
+{"timestamp": 1774949785.240099, "message": {"type": "HookTriggered", "payload": {"event": "PreToolUse", "target": "Shell", "hook_count": 1}}}
+{"timestamp": 1774949785.2407029, "message": {"type": "StatusUpdate", "payload": {"context_usage": 0.0001, "context_tokens": 10, "max_context_tokens": 100000, "token_usage": {"input_other": 10, "output": 2, "input_cache_read": 0, "input_cache_creation": 0}, "message_id": "scripted-1", "plan_mode": false, "mcp_status": null}}}
+{"timestamp": 1774949785.876885, "message": {"type": "HookResolved", "payload": {"event": "PreToolUse", "target": "Shell", "action": "block", "reason": "Shell blocked by hook", "duration_ms": 641}}}
+{"timestamp": 1774949785.877887, "message": {"type": "ToolResult", "payload": {"tool_call_id": "tc1", "return_value": {"is_error": true, "output": "", "message": "Shell blocked by hook", "display": [{"type": "brief", "text": "Hook blocked"}], "extras": null}}}}
+{"timestamp": 1774949785.878922, "message": {"type": "StepBegin", "payload": {"n": 2}}}
+{"timestamp": 1774949785.8802822, "message": {"type": "ContentPart", "payload": {"type": "text", "text": "OK, shell was blocked."}}}
diff --git a/packages/migration-legacy/test/integration.test.ts b/packages/migration-legacy/test/integration.test.ts
new file mode 100644
index 000000000..8e1f80af4
--- /dev/null
+++ b/packages/migration-legacy/test/integration.test.ts
@@ -0,0 +1,122 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdir, mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectMigration, runMigration } from '../src/index.js';
+
+const FIXTURES = fileURLToPath(new URL('./fixtures', import.meta.url));
+const SOURCE_HOME = join(FIXTURES, 'multi-workdir', '.kimi');
+const MARKER_PATH = join(SOURCE_HOME, '.migrated-to-kimi-code');
+const FIXTURE_CONFIG = join(SOURCE_HOME, 'config.toml');
+
+let tgt: string;
+beforeEach(async () => {
+  tgt = await mkdtemp(join(tmpdir(), 'integration-'));
+  // Clean any leftover artifacts that previous failed runs might have left in
+  // the committed fixture directory.
+  await rm(MARKER_PATH, { recursive: true, force: true });
+  await rm(FIXTURE_CONFIG, { force: true });
+});
+afterEach(async () => {
+  await rm(tgt, { recursive: true, force: true });
+  await rm(MARKER_PATH, { recursive: true, force: true });
+  await rm(FIXTURE_CONFIG, { force: true });
+});
+
+describe('runMigration (end-to-end on multi-workdir fixture)', () => {
+  it('migrates everything when scope is full and limit is null', async () => {
+    const plan = await detectMigration({ sourcePath: SOURCE_HOME });
+    const report = await runMigration({
+      plan,
+      scope: {
+        config: true,
+        mcp: true,
+        userHistory: true,
+        sessions: true,
+      },
+      source: SOURCE_HOME,
+      target: tgt,
+    });
+    expect(report.summary.sessions.sessionsMigrated).toBeGreaterThan(0);
+
+    const indexText = await readFile(join(tgt, 'session_index.jsonl'), 'utf-8');
+    const indexLines = indexText.split('\n').filter((l) => l.length > 0);
+    expect(indexLines.length).toBeGreaterThan(0);
+
+    const markerText = await readFile(MARKER_PATH, 'utf-8');
+    const marker: unknown = JSON.parse(markerText);
+    expect((marker as { version: number }).version).toBe(1);
+  });
+
+  it('completes the migration even when the source marker cannot be written', async () => {
+    // Block the marker path with a directory so writeMarker()'s writeFile fails.
+    await mkdir(MARKER_PATH, { recursive: true });
+    const plan = await detectMigration({ sourcePath: SOURCE_HOME });
+    const report = await runMigration({
+      plan,
+      scope: { config: true, mcp: true, userHistory: true, sessions: true },
+      source: SOURCE_HOME,
+      target: tgt,
+    });
+    // All data migrated — a completed run must return a report, not reject.
+    expect(report.summary.sessions.sessionsMigrated).toBeGreaterThan(0);
+  });
+
+  it('config-only scope writes config but skips sessions', async () => {
+    // Materialize a config.toml in the fixture; afterEach cleans it up.
+    await writeFile(FIXTURE_CONFIG, 'default_thinking = true\n');
+
+    const plan = await detectMigration({ sourcePath: SOURCE_HOME });
+    const report = await runMigration({
+      plan,
+      scope: {
+        config: true,
+        mcp: true,
+        userHistory: true,
+        sessions: false,
+      },
+      source: SOURCE_HOME,
+      target: tgt,
+    });
+    expect(report.summary.sessions.scope).toBe('config-only');
+    expect(report.summary.sessions.sessionsMigrated).toBe(0);
+  });
+
+  it('does not copy OAuth credentials into the target', async () => {
+    // OAuth refresh tokens rotate server-side: they are single-use and
+    // single-owner. Copying a credential to a second install breaks login
+    // for whichever side refreshes second. The migration must NOT copy
+    // credentials — it leaves the legacy login alone and asks the user to
+    // run /login in kimi-code instead.
+    const src = await mkdtemp(join(tmpdir(), 'oauth-src-'));
+    try {
+      await mkdir(join(src, 'credentials'), { recursive: true });
+      await writeFile(
+        join(src, 'credentials', 'kimi-code.json'),
+        JSON.stringify({
+          access_token: 'a',
+          refresh_token: 'r',
+          expires_at: 1,
+          scope: 's',
+          token_type: 'Bearer',
+        }),
+      );
+      const plan = await detectMigration({ sourcePath: src });
+      const report = await runMigration({
+        plan,
+        scope: { config: true, mcp: true, userHistory: true, sessions: false },
+        source: src,
+        target: tgt,
+      });
+      // The credential must not be copied into the target.
+      await expect(
+        readFile(join(tgt, 'credentials', 'kimi-code.json'), 'utf-8'),
+      ).rejects.toThrow();
+      // The report tells the user to sign in again in kimi-code.
+      expect(report.notices.oauthLoginsRequiringRelogin).toContain('kimi-code.json');
+    } finally {
+      await rm(src, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/migration-legacy/test/kimi-cli-schema.test.ts b/packages/migration-legacy/test/kimi-cli-schema.test.ts
new file mode 100644
index 000000000..958355ed6
--- /dev/null
+++ b/packages/migration-legacy/test/kimi-cli-schema.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { OldKimiJsonSchema, OldSessionStateSchema } from '../src/kimi-cli-schema.js';
+
+describe('OldKimiJsonSchema', () => {
+  it('parses a real-shape kimi.json', () => {
+    const input = {
+      work_dirs: [
+        { path: '/Users/x/proj', kaos: 'local', last_session_id: 'abc' },
+        { path: '/Users/x/other', kaos: 'local', last_session_id: null },
+      ],
+    };
+    const parsed = OldKimiJsonSchema.parse(input);
+    expect(parsed.work_dirs).toHaveLength(2);
+    expect(parsed.work_dirs[0]!.kaos).toBe('local');
+  });
+
+  it('accepts missing last_session_id', () => {
+    const input = { work_dirs: [{ path: '/x', kaos: 'local' }] };
+    expect(() => OldKimiJsonSchema.parse(input)).not.toThrow();
+  });
+});
+
+describe('OldSessionStateSchema', () => {
+  it('parses a realistic state.json', () => {
+    const input = {
+      version: 1,
+      approval: { yolo: false, afk: false, auto_approve_actions: [] },
+      additional_dirs: [],
+      custom_title: 'hi',
+      title_generated: false,
+      title_generate_attempts: 0,
+      plan_mode: false,
+      plan_session_id: null,
+      plan_slug: null,
+      wire_mtime: 1772616338.93,
+      archived: true,
+      archived_at: 1774273349.5,
+      auto_archive_exempt: false,
+    };
+    const parsed = OldSessionStateSchema.parse(input);
+    expect(parsed.custom_title).toBe('hi');
+    expect(parsed.archived).toBe(true);
+  });
+
+  it('tolerates missing optional fields', () => {
+    expect(() => OldSessionStateSchema.parse({ version: 1 })).not.toThrow();
+  });
+});
diff --git a/packages/migration-legacy/test/marker.test.ts b/packages/migration-legacy/test/marker.test.ts
new file mode 100644
index 000000000..bcacd9b1f
--- /dev/null
+++ b/packages/migration-legacy/test/marker.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  readMarker,
+  writeMarker,
+  appendMarkerRun,
+  type MarkerData,
+} from '../src/marker.js';
+
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'migration-marker-'));
+});
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('marker', () => {
+  it('readMarker returns undefined when file does not exist', async () => {
+    expect(await readMarker(dir)).toBeUndefined();
+  });
+
+  it('writeMarker creates a new marker file with first_migrated_at = last_migrated_at', async () => {
+    const summaryStub = { sessionsAttempted: 5 } as MarkerData['runs'][number]['summary'];
+    await writeMarker(dir, {
+      migratorVersion: '0.1.1',
+      targetPath: '/foo',
+      startedAt: '2026-05-16T10:00:00Z',
+      completedAt: '2026-05-16T10:00:42Z',
+      summary: summaryStub,
+    });
+    const data = await readMarker(dir);
+    expect(data?.first_migrated_at).toBe('2026-05-16T10:00:00Z');
+    expect(data?.last_migrated_at).toBe('2026-05-16T10:00:42Z');
+    expect(data?.runs).toHaveLength(1);
+  });
+
+  it('appendMarkerRun appends to existing marker without losing history', async () => {
+    await writeMarker(dir, {
+      migratorVersion: '0.1.1',
+      targetPath: '/foo',
+      startedAt: '2026-05-16T10:00:00Z',
+      completedAt: '2026-05-16T10:00:42Z',
+      summary: {} as any,
+    });
+    await appendMarkerRun(dir, {
+      migratorVersion: '0.2.0',
+      startedAt: '2026-05-17T10:00:00Z',
+      completedAt: '2026-05-17T10:00:30Z',
+      summary: {} as any,
+      targetPath: '/bar',
+    });
+    const data = await readMarker(dir);
+    expect(data?.first_migrated_at).toBe('2026-05-16T10:00:00Z');
+    expect(data?.last_migrated_at).toBe('2026-05-17T10:00:30Z');
+    expect(data?.runs).toHaveLength(2);
+    // A rerun to a different target updates target_path so the marker
+    // reflects the home it most recently migrated to.
+    expect(data?.target_path).toBe('/bar');
+  });
+
+  it('readMarker returns undefined when file is corrupt', async () => {
+    await writeFile(join(dir, '.migrated-to-kimi-code'), 'not-json', 'utf-8');
+    expect(await readMarker(dir)).toBeUndefined();
+  });
+
+  it('readMarker returns undefined when version is kept but runs is missing', async () => {
+    // A partially-written/hand-edited marker: treating it as absent avoids
+    // appendMarkerRun throwing on `[...existing.runs, run]`.
+    await writeFile(
+      join(dir, '.migrated-to-kimi-code'),
+      JSON.stringify({ version: 1, target_path: '/foo' }),
+      'utf-8',
+    );
+    expect(await readMarker(dir)).toBeUndefined();
+  });
+});
diff --git a/packages/migration-legacy/test/migration-errors-log.test.ts b/packages/migration-legacy/test/migration-errors-log.test.ts
new file mode 100644
index 000000000..aa22ba775
--- /dev/null
+++ b/packages/migration-legacy/test/migration-errors-log.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, writeFile, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { writeMigrationErrorsLog } from '../src/migration-errors-log.js';
+import { migrationErrorsLogFile } from '../src/paths.js';
+
+let tgt: string;
+let src: string;
+beforeEach(async () => {
+  tgt = await mkdtemp(join(tmpdir(), 'errlog-tgt-'));
+  src = await mkdtemp(join(tmpdir(), 'errlog-src-'));
+});
+afterEach(async () => {
+  await rm(tgt, { recursive: true, force: true });
+  await rm(src, { recursive: true, force: true });
+});
+
+describe('writeMigrationErrorsLog', () => {
+  it('appends a "no failures" marker block on a successful run', async () => {
+    await writeMigrationErrorsLog(tgt, {
+      startedAt: '2026-05-19T00:00:00Z',
+      failures: [],
+    });
+    const log = await readFile(migrationErrorsLogFile(tgt), 'utf-8');
+    expect(log).toContain('===== migration run @ 2026-05-19T00:00:00Z =====');
+    expect(log).toContain('no failures.');
+  });
+
+  it('writes a diagnostic block per failure with a context.jsonl role histogram', async () => {
+    const sessionDir = join(src, 'ses-1');
+    await mkdir(sessionDir, { recursive: true });
+    await writeFile(
+      join(sessionDir, 'context.jsonl'),
+      '{"role":"_system_prompt","content":"x"}\n{"role":"user","content":"hi"}\n',
+    );
+
+    await writeMigrationErrorsLog(tgt, {
+      startedAt: '2026-05-19T00:00:00Z',
+      failures: [{ sourcePath: sessionDir, reason: 'write failed: ENOSPC' }],
+    });
+
+    const log = await readFile(migrationErrorsLogFile(tgt), 'utf-8');
+    expect(log).toContain('===== migration run @ 2026-05-19T00:00:00Z =====');
+    expect(log).toContain('1 session(s) failed to migrate.');
+    expect(log).toContain(sessionDir);
+    expect(log).toContain('write failed: ENOSPC');
+    expect(log).toContain('context.jsonl: 2 lines');
+    expect(log).toContain('_system_prompt=1');
+    expect(log).toContain('user=1');
+  });
+
+  it('notes an unreadable context.jsonl rather than throwing', async () => {
+    const sessionDir = join(src, 'gone');
+    await writeMigrationErrorsLog(tgt, {
+      startedAt: '2026-05-19T00:00:00Z',
+      failures: [{ sourcePath: sessionDir, reason: 'cannot read context.jsonl' }],
+    });
+    const log = await readFile(migrationErrorsLogFile(tgt), 'utf-8');
+    expect(log).toContain('context.jsonl: unreadable');
+  });
+
+  it('appends a second block when a later run also has failures', async () => {
+    // Cross-run history: a user who retries the migration and hits failures
+    // each time must end up with one log that shows every attempt — the team
+    // can analyze the full retry sequence from a single file.
+    const ses1 = join(src, 'ses-1');
+    const ses2 = join(src, 'ses-2');
+    await mkdir(ses1, { recursive: true });
+    await mkdir(ses2, { recursive: true });
+    await writeFile(join(ses1, 'context.jsonl'), '{"role":"user","content":"a"}\n');
+    await writeFile(join(ses2, 'context.jsonl'), '{"role":"user","content":"b"}\n');
+
+    await writeMigrationErrorsLog(tgt, {
+      startedAt: '2026-05-19T00:00:00Z',
+      failures: [{ sourcePath: ses1, reason: 'first-run reason' }],
+    });
+    await writeMigrationErrorsLog(tgt, {
+      startedAt: '2026-05-20T00:00:00Z',
+      failures: [{ sourcePath: ses2, reason: 'second-run reason' }],
+    });
+
+    const log = await readFile(migrationErrorsLogFile(tgt), 'utf-8');
+    // Both run headers survive (append-only, no overwrite).
+    const headerMatches = log.match(/===== migration run @ /g) ?? [];
+    expect(headerMatches).toHaveLength(2);
+    expect(log).toContain('2026-05-19T00:00:00Z');
+    expect(log).toContain('2026-05-20T00:00:00Z');
+    // Both runs' failure data survive.
+    expect(log).toContain('first-run reason');
+    expect(log).toContain('second-run reason');
+    expect(log).toContain(ses1);
+    expect(log).toContain(ses2);
+  });
+
+  it('appends after an earlier failed run when the later run has no failures', async () => {
+    // The earlier failure record must NOT be deleted by a successful retry —
+    // we want the timeline visible even after the user recovers.
+    const ses1 = join(src, 'ses-1');
+    await mkdir(ses1, { recursive: true });
+    await writeFile(join(ses1, 'context.jsonl'), '{"role":"user","content":"a"}\n');
+
+    await writeMigrationErrorsLog(tgt, {
+      startedAt: '2026-05-19T00:00:00Z',
+      failures: [{ sourcePath: ses1, reason: 'first-run reason' }],
+    });
+    await writeMigrationErrorsLog(tgt, {
+      startedAt: '2026-05-20T00:00:00Z',
+      failures: [],
+    });
+
+    const log = await readFile(migrationErrorsLogFile(tgt), 'utf-8');
+    expect(log).toContain('===== migration run @ 2026-05-19T00:00:00Z =====');
+    expect(log).toContain('first-run reason');
+    expect(log).toContain('===== migration run @ 2026-05-20T00:00:00Z =====');
+    expect(log).toContain('no failures.');
+  });
+});
diff --git a/packages/migration-legacy/test/paths.test.ts b/packages/migration-legacy/test/paths.test.ts
new file mode 100644
index 000000000..4712ce8f7
--- /dev/null
+++ b/packages/migration-legacy/test/paths.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { join } from 'node:path';
+import * as paths from '../src/paths.js';
+
+describe('paths', () => {
+  it('sourceCredentialsDir joins ~/.kimi/credentials', () => {
+    expect(paths.sourceCredentialsDir('/x/.kimi')).toBe(join('/x/.kimi', 'credentials'));
+  });
+
+  it('targetConfigFile and targetTuiFile', () => {
+    expect(paths.targetConfigFile('/y')).toBe(join('/y', 'config.toml'));
+    expect(paths.targetTuiFile('/y')).toBe(join('/y', 'tui.toml'));
+  });
+
+  it('targetSessionIndex', () => {
+    expect(paths.targetSessionIndex('/y')).toBe(join('/y', 'session_index.jsonl'));
+  });
+
+  it('migratedMarker is under source', () => {
+    expect(paths.migratedMarker('/x/.kimi')).toBe(join('/x/.kimi', '.migrated-to-kimi-code'));
+  });
+
+  it('skipMarker is under target', () => {
+    expect(paths.skipMarker('/y/.kimi-code')).toBe(join('/y/.kimi-code', '.skip-migration-from-kimi-cli'));
+  });
+
+  it('migrationReportFile is under target', () => {
+    expect(paths.migrationReportFile('/y')).toBe(join('/y', 'migration-report.json'));
+  });
+
+  it('sourceSessionsDir / sourceUserHistoryDir / sourceKimiJson', () => {
+    expect(paths.sourceSessionsDir('/x')).toBe(join('/x', 'sessions'));
+    expect(paths.sourceUserHistoryDir('/x')).toBe(join('/x', 'user-history'));
+    expect(paths.sourceKimiJson('/x')).toBe(join('/x', 'kimi.json'));
+  });
+});
diff --git a/packages/migration-legacy/test/prompt-modules.d.ts b/packages/migration-legacy/test/prompt-modules.d.ts
new file mode 100644
index 000000000..56eea9ef6
--- /dev/null
+++ b/packages/migration-legacy/test/prompt-modules.d.ts
@@ -0,0 +1,14 @@
+// `resume.integration.test.ts` imports real kimi-core, which transitively
+// imports `.md` / `.yaml` prompt sources as raw strings (resolved by the
+// shared `raw-text-plugin`). This ambient declaration lets `tsc` type-check
+// the migration package without pulling in kimi-core's own `.d.ts`.
+
+declare module '*.md' {
+  const content: string;
+  export default content;
+}
+
+declare module '*.yaml' {
+  const content: string;
+  export default content;
+}
diff --git a/packages/migration-legacy/test/prompt.test.ts b/packages/migration-legacy/test/prompt.test.ts
new file mode 100644
index 000000000..827ff26b1
--- /dev/null
+++ b/packages/migration-legacy/test/prompt.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveMigrationScope } from '../src/prompt.js';
+
+describe('resolveMigrationScope', () => {
+  it('returns scope.sessions=false when user picks "config-only" at Prompt 2', () => {
+    const result = resolveMigrationScope(['now', 'config-only']);
+    expect(result.decision).toBe('now');
+    expect(result.scope).toEqual({
+      config: true,
+      mcp: true,
+      userHistory: true,
+      sessions: false,
+    });
+  });
+
+  it('returns scope.sessions=true when user picks "all-sessions" at Prompt 2', () => {
+    const result = resolveMigrationScope(['now', 'all-sessions']);
+    expect(result.decision).toBe('now');
+    expect(result.scope).toEqual({
+      config: true,
+      mcp: true,
+      userHistory: true,
+      sessions: true,
+    });
+  });
+
+  it('"later" short-circuits with no scope', () => {
+    const result = resolveMigrationScope(['later']);
+    expect(result.decision).toBe('later');
+    expect(result.scope).toBeUndefined();
+  });
+
+  it('"never" returns decision=never (caller writes skip marker)', () => {
+    const result = resolveMigrationScope(['never']);
+    expect(result.decision).toBe('never');
+    expect(result.scope).toBeUndefined();
+  });
+});
diff --git a/packages/migration-legacy/test/report.test.ts b/packages/migration-legacy/test/report.test.ts
new file mode 100644
index 000000000..bc8b2f198
--- /dev/null
+++ b/packages/migration-legacy/test/report.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { writeReport } from '../src/report.js';
+import type { MigrationReport } from '../src/types.js';
+
+let tgt: string;
+beforeEach(async () => {
+  tgt = await mkdtemp(join(tmpdir(), 'rpt-'));
+});
+afterEach(async () => {
+  await rm(tgt, { recursive: true, force: true });
+});
+
+describe('writeReport', () => {
+  it('serializes the report at <target>/migration-report.json', async () => {
+    const report: MigrationReport = {
+      startedAt: 's',
+      completedAt: 'e',
+      migratorVersion: '0.1.1',
+      source: '/x',
+      target: tgt,
+      summary: {
+        config: {
+          migrated: false,
+          tuiExtracted: false,
+          droppedProviders: [],
+          droppedModels: [],
+          droppedKeys: [],
+          configConflicts: [],
+          wroteSiblingDueToConflict: false,
+          wroteTuiSibling: false,
+          migratedHooks: 0,
+          droppedHooks: 0,
+          siblingContents: { providers: [], models: [], hooks: 0 },
+        },
+        mcp: { mergedServers: [], keptNewForConflicts: [], droppedServers: [], wroteSiblingDueToConflict: false },
+        userHistory: { copied: 0, skippedExisting: 0 },
+        sessions: {
+          scope: 'all',
+          bucketsScanned: 0,
+          bucketsSkippedNonlocalKaos: 0,
+          bucketsSkippedNoWorkdirFound: 0,
+          sessionsAttempted: 0,
+          sessionsMigrated: 0,
+          sessionsAlreadyMigrated: 0,
+          sessionsSkippedPlaceholder: 0,
+          sessionsSkippedEmpty: 0,
+          sessionsSkippedMalformed: 0,
+          sessionsFailed: [],
+          sessionsConflicts: [],
+        },
+      },
+      notices: {
+        mcpOauthServersRequiringReauth: [],
+        oauthLoginsRequiringRelogin: [],
+        detectedPlugins: [],
+        configConflictNotice: null,
+        tuiConflictNotice: null,
+      },
+    };
+    await writeReport(tgt, report);
+    const text = await readFile(join(tgt, 'migration-report.json'), 'utf-8');
+    const parsed: unknown = JSON.parse(text);
+    expect((parsed as { migratorVersion: string }).migratorVersion).toBe('0.1.1');
+  });
+});
diff --git a/packages/migration-legacy/test/resume.integration.test.ts b/packages/migration-legacy/test/resume.integration.test.ts
new file mode 100644
index 000000000..fbdd8375f
--- /dev/null
+++ b/packages/migration-legacy/test/resume.integration.test.ts
@@ -0,0 +1,168 @@
+/**
+ * End-to-end check that a migrated session is actually visible to — and
+ * resumable by — real kimi-core. The migrator writes session buckets named by
+ * `computeWorkdirBucket`; kimi-core's session picker (`SessionStore.list`)
+ * locates sessions purely by `readdir(encodeWorkDirKey(workDir))`. If the two
+ * bucket algorithms diverge (see review item C1), migrated sessions become
+ * silently invisible — this test fails fast in that case.
+ *
+ * The resume test additionally drives a real `Session.resume()`: it reads the
+ * migrated `state.json`, instantiates the `main` agent from
+ * `agents.main.homedir`, and replays that agent's `wire.jsonl`. If
+ * `agents.main.homedir` does not point at `<sessionDir>/agents/main` (where the
+ * migrator writes the translated history), the resumed agent's context is
+ * empty and the migrated history is lost.
+ *
+ * agent-core API used:
+ *   - `SessionStore` (constructor: `new SessionStore(homeDir)`)
+ *   - `SessionStore.list({ workDir })`
+ *   - `encodeWorkDirKey` / `normalizeWorkDir`
+ *     all from `@moonshot-ai/agent-core/session/store`.
+ *   - `Session` (constructor + `resume()` + `agents` map), from
+ *     `@moonshot-ai/agent-core`; `localKaos` from `@moonshot-ai/kaos`. After
+ *     `resume()`, `session.agents.get('main').context.messages` exposes the
+ *     replayed message history.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  SessionStore,
+  encodeWorkDirKey,
+  normalizeWorkDir,
+} from '@moonshot-ai/agent-core/session/store';
+import { Session, type SDKSessionRPC } from '@moonshot-ai/agent-core';
+import { localKaos } from '@moonshot-ai/kaos';
+
+import { migrateOneSession, type MigrateOneResult } from '../src/sessions/migrate-one.js';
+import { computeWorkdirBucket } from '../src/sessions/workdir-bucket.js';
+
+const TEST_OS_ENV = {
+  osKind: 'Linux',
+  osArch: 'arm64',
+  osVersion: 'test',
+  shellPath: '/bin/bash',
+  shellName: 'bash',
+} as const;
+
+function createSessionRpc(): SDKSessionRPC {
+  return {
+    emitEvent: vi.fn(async () => {}),
+    requestApproval: vi.fn(async () => ({ decision: 'cancelled' })),
+    requestQuestion: vi.fn(async () => null),
+    toolCall: vi.fn(async () => ({ output: 'unused', isError: true })),
+  } as unknown as SDKSessionRPC;
+}
+
+const FIXTURES = fileURLToPath(new URL('./fixtures', import.meta.url));
+const WORK_DIR = '/Users/example/proj';
+
+let targetHome: string;
+beforeEach(async () => {
+  targetHome = await mkdtemp(join(tmpdir(), 'resume-integ-'));
+});
+afterEach(async () => {
+  await rm(targetHome, { recursive: true, force: true });
+});
+
+describe('migrated session loads in real kimi-core', () => {
+  it('computeWorkdirBucket matches kimi-core encodeWorkDirKey', () => {
+    expect(computeWorkdirBucket(WORK_DIR)).toBe(
+      encodeWorkDirKey(normalizeWorkDir(WORK_DIR)),
+    );
+  });
+
+  it('SessionStore.list() finds a migrated session under the same workDir', async () => {
+    const result = await migrateOneSession({
+      sourceSessionDir: join(FIXTURES, 'with-tool-calls'),
+      oldSessionUuid: 'integ-uuid',
+      workdirPath: WORK_DIR,
+      targetHome,
+    });
+    expect(result.outcome).toBe('migrated');
+
+    // `SessionStore(homeDir)` resolves sessions under `homeDir/sessions`,
+    // which is exactly where the migrator wrote.
+    const store = new SessionStore(targetHome);
+    const sessions = await store.list({ workDir: WORK_DIR });
+
+    // This exercises kimi-core's bucket lookup end-to-end: list() does
+    // `readdir(encodeWorkDirKey(workDir))` and never consults the index.
+    expect(sessions.map((s) => s.id)).toContain('ses_integ-uuid');
+
+    const migrated = sessions.find((s) => s.id === 'ses_integ-uuid');
+    expect(migrated?.metadata?.['imported_from_kimi_cli']).toBe(true);
+  });
+
+  it('migrated wire history is non-empty and resumable', async () => {
+    const result = await migrateOneSession({
+      sourceSessionDir: join(FIXTURES, 'tiny-hello-world'),
+      oldSessionUuid: 'tiny-resume',
+      workdirPath: WORK_DIR,
+      targetHome,
+    });
+    expect(result.outcome).toBe('migrated');
+    const targetDir = (result as Extract<MigrateOneResult, { outcome: 'migrated' }>)
+      .targetDir;
+
+    const wire = await readFile(join(targetDir, 'agents', 'main', 'wire.jsonl'), 'utf-8');
+    const events = wire
+      .split('\n')
+      .filter((l) => l.length > 0)
+      .map((l) => JSON.parse(l) as { type: string });
+    expect(events[0]?.type).toBe('metadata');
+    expect(events.filter((e) => e.type === 'context.append_message').length).toBeGreaterThan(0);
+  });
+
+  it('real kimi-core Session.resume() loads the migrated message history', async () => {
+    const result = await migrateOneSession({
+      sourceSessionDir: join(FIXTURES, 'tiny-hello-world'),
+      oldSessionUuid: 'tiny-resume',
+      workdirPath: WORK_DIR,
+      targetHome,
+    });
+    expect(result.outcome).toBe('migrated');
+    const targetDir = (result as Extract<MigrateOneResult, { outcome: 'migrated' }>)
+      .targetDir;
+
+    // Drive a real kimi-core resume: `Session.resume()` reads `state.json`
+    // from `homedir`, then instantiates the `main` agent from
+    // `agents.main.homedir` and replays *that directory's* `wire.jsonl`.
+    // If `agents.main.homedir` were the project workdir (the bug), the agent
+    // would replay an absent file and the history would be empty.
+    const session = new Session({
+      runtime: { kaos: localKaos, osEnv: TEST_OS_ENV },
+      id: 'ses_tiny-resume',
+      homedir: targetDir,
+      cwd: WORK_DIR,
+      rpc: createSessionRpc(),
+      initializeMainAgent: false,
+    });
+    try {
+      await session.resume();
+      const mainAgent = session.agents.get('main');
+      expect(mainAgent).toBeDefined();
+
+      // The migrated wire carries no `config.update` bootstrap events, so a
+      // naive replay leaves the agent with an empty system prompt and no
+      // tools. `Session.resume()` re-applies the default profile when it
+      // detects this — assert it took effect so the resumed session is usable.
+      expect((mainAgent?.config.systemPrompt ?? '').length).toBeGreaterThan(0);
+
+      const messages = mainAgent?.context.messages ?? [];
+      // The fixture has a user + assistant message — both must be replayed.
+      expect(messages.length).toBeGreaterThan(0);
+      const transcript = messages
+        .flatMap((m) => m.content)
+        .map((part) => (part.type === 'text' ? part.text : ''))
+        .join('\n');
+      expect(transcript).toContain('hi');
+      expect(transcript).toContain('Hello! How can I help?');
+    } finally {
+      await session.close();
+    }
+  });
+});
diff --git a/packages/migration-legacy/test/session-index.test.ts b/packages/migration-legacy/test/session-index.test.ts
new file mode 100644
index 000000000..aa74a34c3
--- /dev/null
+++ b/packages/migration-legacy/test/session-index.test.ts
@@ -0,0 +1,95 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { appendSessionIndexEntry, ensureSessionIndexEntry } from '../src/session-index.js';
+
+let target: string;
+beforeEach(async () => {
+  target = await mkdtemp(join(tmpdir(), 'sess-idx-'));
+});
+afterEach(async () => {
+  await rm(target, { recursive: true, force: true });
+});
+
+describe('appendSessionIndexEntry', () => {
+  it('creates the file and appends one line per call', async () => {
+    await appendSessionIndexEntry(target, {
+      sessionId: 'ses_a',
+      sessionDir: '/abs/a',
+      workDir: '/abs/wd',
+    });
+    await appendSessionIndexEntry(target, {
+      sessionId: 'ses_b',
+      sessionDir: '/abs/b',
+      workDir: '/abs/wd',
+    });
+    const text = await readFile(join(target, 'session_index.jsonl'), 'utf-8');
+    const lines = text.split('\n').filter((l) => l.length > 0);
+    expect(lines).toHaveLength(2);
+    const first = lines[0];
+    const second = lines[1];
+    if (first === undefined || second === undefined) {
+      throw new Error('expected two non-empty lines');
+    }
+    expect(JSON.parse(first).sessionId).toBe('ses_a');
+    expect(JSON.parse(second).sessionId).toBe('ses_b');
+  });
+});
+
+describe('ensureSessionIndexEntry', () => {
+  it('appends the entry when the index is missing it', async () => {
+    await ensureSessionIndexEntry(target, {
+      sessionId: 'ses_x',
+      sessionDir: '/abs/x',
+      workDir: '/abs/wd',
+    });
+    const text = await readFile(join(target, 'session_index.jsonl'), 'utf-8');
+    const lines = text.split('\n').filter((l) => l.length > 0);
+    expect(lines).toHaveLength(1);
+    const only = lines[0];
+    if (only === undefined) throw new Error('expected one line');
+    expect(JSON.parse(only).sessionId).toBe('ses_x');
+  });
+
+  it('is a no-op when an entry with the same sessionId already exists', async () => {
+    await appendSessionIndexEntry(target, {
+      sessionId: 'ses_x',
+      sessionDir: '/abs/x',
+      workDir: '/abs/wd',
+    });
+    // Same id, different dir — must not add a duplicate line.
+    await ensureSessionIndexEntry(target, {
+      sessionId: 'ses_x',
+      sessionDir: '/abs/x-rerun',
+      workDir: '/abs/wd',
+    });
+    const text = await readFile(join(target, 'session_index.jsonl'), 'utf-8');
+    const lines = text.split('\n').filter((l) => l.length > 0);
+    expect(lines).toHaveLength(1);
+  });
+
+  it('appends only the missing entry when others are already present', async () => {
+    await appendSessionIndexEntry(target, {
+      sessionId: 'ses_a',
+      sessionDir: '/abs/a',
+      workDir: '/abs/wd',
+    });
+    await ensureSessionIndexEntry(target, {
+      sessionId: 'ses_a',
+      sessionDir: '/abs/a',
+      workDir: '/abs/wd',
+    });
+    await ensureSessionIndexEntry(target, {
+      sessionId: 'ses_b',
+      sessionDir: '/abs/b',
+      workDir: '/abs/wd',
+    });
+    const text = await readFile(join(target, 'session_index.jsonl'), 'utf-8');
+    const ids = text
+      .split('\n')
+      .filter((l) => l.length > 0)
+      .map((l) => JSON.parse(l).sessionId);
+    expect(ids).toEqual(['ses_a', 'ses_b']);
+  });
+});
diff --git a/packages/migration-legacy/test/sessions/__snapshots__/fixtures.snapshot.test.ts.snap b/packages/migration-legacy/test/sessions/__snapshots__/fixtures.snapshot.test.ts.snap
new file mode 100644
index 000000000..e037c8abc
--- /dev/null
+++ b/packages/migration-legacy/test/sessions/__snapshots__/fixtures.snapshot.test.ts.snap
@@ -0,0 +1,355 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`migration snapshot: archived > migration succeeds and matches snapshot 1`] = `
+{
+  "state": "{
+  "createdAt": "<REDACTED>",
+  "updatedAt": "<REDACTED>",
+  "title": "You are a code translation assistant. Task: [...]",
+  "isCustomTitle": true,
+  "lastPrompt": "<system-reminder>\\nYou are running in non-interactive mode. The user cannot answer questions or provide feedback during execution.\\n- Do NOT call AskUserQuestion. If you need to make a decision, make yo",
+  "agents": {
+    "main": {
+      "homedir": "<TARGET>/sessions/wd_proj_33c5ea5aa7eb/ses_archived/agents/main",
+      "type": "main",
+      "parentAgentId": null
+    }
+  },
+  "custom": {
+    "imported_from_kimi_cli": true,
+    "kimi_cli_source_path": "<REDACTED>",
+    "kimi_cli_session_id": "archived",
+    "kimi_cli_wire_protocol": "1.8",
+    "imported_at": "<REDACTED>",
+    "archived": true
+  }
+}",
+  "wire": "{"type":"metadata","protocol_version":"1.0","created_at":<REDACTED>}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"You are a code translation assistant.\\n\\nTask:\\n- Read the file \`sample.js\` in the current working directory.\\n- Translate it into idiomatic Python 3.\\n- Write the translated code to \`translated.py\` in the current working directory.\\n\\nRules:\\n- You must read the file from disk; do not guess its contents.\\n- Preserve behavior and output.\\n- Write only Python code in translated.py (no Markdown).\\n- Overwrite translated.py if it already exists.\\n- After writing, reply with a single short ASCII confirmation se... [truncated]"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"<system-reminder>\\nYou are running in non-interactive mode. The user cannot answer questions or provide feedback during execution.\\n- Do NOT call AskUserQuestion. If you need to make a decision, make your best judgment and proceed.\\n- For EnterPlanMode / ExitPlanMode, they will be auto-approved. You can use them normally but expect no user feedback.\\n</system-reminder>"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"assistant","content":[],"toolCalls":[{"type":"function","id":"ReadFile:0","function":{"name":"ReadFile","arguments":"{\\"path\\": \\"sample.js\\"}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>10 lines read from file starting from line 1. End of file reached.</system>"},{"type":"text","text":"     1\\tfunction add(a, b) {\\n     2\\t  return a + b;\\n     3\\t}\\n     4\\t\\n     5\\tfunction main() {\\n     6\\t  const result = add(2, 3);\\n     7\\t  console.log(\`2 + 3 = \${result}\`);\\n     8\\t}\\n     9\\t\\n    10\\tmain();\\n"}],"toolCalls":[],"toolCallId":"ReadFile:0"}}
+",
+}
+`;
+
+exports[`migration snapshot: large-100msgs > migration succeeds and matches snapshot 1`] = `
+{
+  "state": "{
+  "createdAt": "<REDACTED>",
+  "updatedAt": "<REDACTED>",
+  "title": "source /Users/example/proj/example-project/.venv/b",
+  "isCustomTitle": false,
+  "lastPrompt": "source /Users/example/proj/example-project/.venv/bin/activate",
+  "agents": {
+    "main": {
+      "homedir": "<TARGET>/sessions/wd_proj_33c5ea5aa7eb/ses_large-100msgs/agents/main",
+      "type": "main",
+      "parentAgentId": null
+    }
+  },
+  "custom": {
+    "imported_from_kimi_cli": true,
+    "kimi_cli_source_path": "<REDACTED>",
+    "kimi_cli_session_id": "large-100msgs",
+    "kimi_cli_wire_protocol": "1.4",
+    "imported_at": "<REDACTED>",
+    "archived": false
+  }
+}",
+  "wire": "{"type":"metadata","protocol_version":"1.0","created_at":<REDACTED>}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"请帮我探索一下当前这个仓库的整体结构，了解它的主要模块和功能。看完之后请写一份简短的小报告，列出你认为最重要的几个模块、它们的职责，以及彼此之间的依赖关系。报告控制在一页之内，便于团队成员快速了解项目。"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"用户想要我读取 example-task skill 的 SKILL.md 文件，但他们已经在 prompt 中提供了完整的 skill 内容。不过我需要了解这个 skill 的更多细节，特别是 references/prompt-patterns.md 文件。\\n\\n用户似乎在向我介绍这个 skill，让我熟悉它的用法。我应该先检查一下这个 skill 目录的结构，看看是否有其他有用的资源文件。\\n\\n让我先了解一下这个 skill 的完整结构，以便以后需要时可以使用它。"},{"type":"text","text":"我来熟悉一下 \`example-task\` skill 的完整结构和资源。"}],"toolCalls":[{"type":"function","id":"tool_3mtoDjRlqenM0GDSjv9xRzLS","function":{"name":"Glob","arguments":"{\\"pattern\\": \\".agents/skills/example-task/**/*\\"}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Found 5 matches for pattern \`.agents/skills/example-task/**/*\`.</system>"},{"type":"text","text":".agents/skills/example-task/SKILL.md\\n.agents/skills/example-task/references\\n.agents/skills/example-task/references/prompt-patterns.md\\n.agents/skills/example-task/scripts\\n.agents/skills/example-task/scripts/inspect_session.py"}],"toolCalls":[],"toolCallId":"tool_3mtoDjRlqenM0GDSjv9xRzLS"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"让我读取 references/prompt-patterns.md 和 scripts/inspect_session.py 来了解完整的 skill 资源。"}],"toolCalls":[{"type":"function","id":"tool_nqkbedqxXK1aX9zAWWNEhzmM","function":{"name":"ReadFile","arguments":"{\\"path\\": \\".agents/skills/example-task/references/prompt-patterns.md\\"}"}},{"type":"function","id":"tool_300OLXjS5RZxFz9LvWJP6QyJ","function":{"name":"ReadFile","arguments":"{\\"path\\": \\".agents/skills/example-task/scripts/inspect_session.py\\"}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>85 lines read from file starting from line 1. End of file reached.</system>"},{"type":"text","text":"     1\\t# Prompt 模板\\n     2\\t\\n     3\\t以下模板作为脚手架使用。运行前替换占位符。\\n     4\\t\\n     5\\t## 单轮还是多轮\\n     6\\t\\n     7\\t满足以下任一条件时使用多轮：\\n     8\\t\\n     9\\t- 功能有状态\\n    10\\t- 功能依赖时序或并发\\n    11\\t- 功能需要审批、清理或恢复\\n    12\\t- session 产物本身是证据的一部分\\n    13\\t- 工具接口可能近期发生过变化\\n    14\\t\\n    15\\t仅对无状态的窄范围检查使用单轮。\\n    16\\t\\n    17\\t## 变量\\n    18\\t\\n    19\\t起草 prompt 前填写以下字段：\\n    20\\t\\n    21\\t- \`<feature>\` — 被测功能名称\\n    22\\t- \`<goal>\` — 当前场景的目标\\n    23\\t- \`<source_paths>\` — 需要阅读的源码路径\\n    24\\t- \`<constraints>\` — 执行约束\\n    25\\t- \`<success_signals>\` — 成功信号\\n    26\\t- \`<fai... [truncated]"}],"toolCalls":[],"toolCallId":"tool_nqkbedqxXK1aX9zAWWNEhzmM"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>321 lines read from file starting from line 1. End of file reached.</system>"},{"type":"text","text":"     1\\t#!/usr/bin/env python3\\n     2\\t\\"\\"\\"Locate and summarize a Kimi CLI session for smoke-test review.\\"\\"\\"\\n     3\\t\\n     4\\tfrom __future__ import annotations\\n     5\\t\\n     6\\timport argparse\\n     7\\timport json\\n     8\\timport sys\\n     9\\tfrom collections import Counter\\n    10\\tfrom pathlib import Path\\n    11\\tfrom typing import Any\\n    12\\t\\n    13\\t\\n    14\\tdef parse_args() -> argparse.Namespace:\\n    15\\t    parser = argparse.ArgumentParser(\\n    16\\t        description=\\"Locate and summarize a Kimi CLI session... [truncated]"}],"toolCalls":[],"toolCallId":"tool_300OLXjS5RZxFz9LvWJP6QyJ"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"好的，我现在已经完整了解了 \`example-task\` skill 的内容。这个 skill 提供了：\\n\\n1. **SKILL.md** - 主文档，描述了如何针对 the example CLI 的新增或变更功能进行端到端冒烟测试的完整流程\\n2. **references/prompt-patterns.md** - 可复用的 prompt 模板\\n3. **scripts/inspect_session.py** - 用于检查和分析 session 产物的脚本\\n\\n用户似乎是在测试我是否能正确读取和使用这个 skill。既然用户已经在 prompt 中提供了完整的 skill 内容，我应该：\\n1. 确认我已经理解了 skill 的内容\\n2. 询问用户是否有具体的功能需要我使用这个 skill 来进行冒烟测试\\n\\n或者，用户可能是想了解这个 skill 的用法。让我给出一个总结并询问用户的具体需求。"},{"type":"text","text":"我已完整阅读 \`example-task\` skill。这是一个用于对 the example CLI 进行端到端冒烟测试的系统化流程。\\n\\n## Skill 要点总结\\n\\n**核心流程：**\\n1. **确定测试范围** - 从 \`git diff\` 推断功能边界\\n2. **读取事实来源** - 文档、代码、agent prompt、测试\\n3. **制定最小测试计划** - 正常路径、边界条件、中断/清理\\n4. **多轮执行** - 探索→执行→观察→清理\\n5. **非交互模式运行** - 使用 \`--print --work-dir /tmp/...\`\\n6. **检查产物** - \`context.jsonl\`, \`wire.jsonl\`, 后台任务等\\n7. **问题探查** - 并行多路追踪根因\\n\\n**可用资源：**\\n- \`references/prompt-patterns.md\` - 探索/执行/观察/复盘 prompt 模板\\n- \`scripts/inspect_session.py\` - Session 产物分析工具\\n\\n---\\n\\n**你想让我使用这个 skill 来测试... [truncated]"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"请基于 README 和主要源代码目录，给出一份简短的探索清单"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"用户想让我直接使用 \`git diff main --name-only\` 来查看当前分支相对于 main 分支的变更，然后基于这些变更进行冒烟测试。\\n\\n让我先执行这个命令看看有哪些文件变更。"}],"toolCalls":[{"type":"function","id":"tool_jOGB6wicU1PmefwL15U57RUT","function":{"name":"Shell","arguments":"{\\"command\\": \\"git diff main --name-only && echo \\\\\\"---\\\\\\" && git diff main --stat\\"}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":".agents/skills/example-task/SKILL.md\\n.agents/skills/example-task/references/prompt-patterns.md\\n.agents/skills/example-task/scripts/inspect_session.py\\nCHANGELOG.md\\nfeature-overview.md\\ndocs/en/configuration/data-locations.md\\ndocs/en/customization/wire-mode.md\\ndocs/en/guides/interaction.md\\ndocs/en/guides/sessions.md\\ndocs/en/reference/keyboard.md\\ndocs/en/reference/kimi-command.md\\ndocs/en/reference/kimi-info.md\\ndocs/en/reference/kimi-vis.md\\ndocs/en/release-notes/changelog.md\\ndoc... [truncated]"}],"toolCalls":[],"toolCallId":"tool_jOGB6wicU1PmefwL15U57RUT"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"从 git diff 的输出来看，这是一个非常大的变更集，主要涉及以下几个核心功能：\\n\\n1. **后台任务系统 (background/)** - 全新模块\\n   - \`src/example_pkg/background/\` - 后台任务管理核心\\n   - \`src/example_pkg/tools/background/\` - 后台任务工具\\n\\n2. **通知系统 (notifications/)** - 全新模块\\n   - \`src/example_pkg/notifications/\` - 通知管理\\n\\n3. **Shell UI 重构** - 大规模重构\\n   - \`src/example_pkg/ui/shell/\` - Shell UI 组件重构\\n   - 移除了大量旧代码（placeholders, echo 等）\\n\\n4. **Wire 协议更新**\\n   - \`src/example_pkg/wire/types.py\` 和 \`protocol.py\`\\n\\n5. **动态注入 (dynamic_injection.py)**\\n   - 更新\\n\\n6. **测试覆盖**\\n   - 大量新增测试\\n\\n这是一个... [truncated]"},{"type":"text","text":"根据 git diff 输出，这是一个大规模功能变更，主要涉及：\\n\\n1. **后台任务系统** (\`src/example_pkg/background/\`) - 全新模块\\n2. **通知系统** (\`src/example_pkg/notifications/\`) - 全新模块  \\n3. **后台任务工具** (\`src/example_pkg/tools/background/\`) - 新工具\\n4. **Shell UI 重构** (\`src/example_pkg/ui/shell/\`) - 大量重构\\n5. **Wire 协议更新** (\`src/example_pkg/wire/types.py\`)\\n6. **动态注入更新** (\`src/example_pkg/soul/dynamic_injection.py\`)\\n\\n让我开始冒烟测试流程，首先读取事实来源："}],"toolCalls":[{"type":"function","id":"tool_TB9CacXCzJ8B11tzzOneV7MK","function":{"name":"ReadFile","arguments":"{\\"path\\": \\"feature-overview.md\\"}"}},{"type":"function","id":"tool_7tKhkdZsBAFotRMTFs0BmgM6","function":{"name":"ReadFile","arguments":"{\\"path\\": \\"src/example_pkg/background/manager.py\\"}"}},{"type":"function","id":"tool_DR5VfRHgGe7WZ1dXKSA5Yowh","function":{"name":"ReadFile","arguments":"{\\"path\\": \\"src/example_pkg/background/models.py\\"}"}},{"type":"function","id":"tool_XZXYciY6FY2Tl4SHwuh7Elhl","function":{"name":"ReadFile","arguments":"{\\"path\\": \\"src/example_pkg/tools/background/__init__.py\\"}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>353 lines read from file starting from line 1. End of file reached.</system>"},{"type":"text","text":"     1\\t# 后台任务实现说明\\n     2\\t\\n     3\\t这份文档是给后续开发者快速理解当前 background task / notification 实现用的内部说明，不是用户文档。\\n     4\\t\\n     5\\t## 一句话结论\\n     6\\t\\n     7\\t当前实现已经不再把 background task completion 建模成 \`dynamic injection\` 的一个特例。\\n     8\\t\\n     9\\t现在的结构是：\\n    10\\t\\n    11\\t- \`Shell(run_in_background=true)\` 负责启动后台任务\\n    12\\t- \`TaskList\` / \`TaskOutput\` / \`TaskStop\` 负责最小控制面\\n    13\\t- \`BackgroundTaskManager\` 负责 task 生命周期\\n    14\\t- \`NotificationManager\` 负责通用 notification 基建\\n    15\\t- \`task notification\` 只是 notification 基建里的一个 type\\n  ... [truncated]"}],"toolCalls":[],"toolCallId":"tool_TB9CacXCzJ8B11tzzOneV7MK"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>358 lines read from file starting from line 1. End of file reached.</system>"},{"type":"text","text":"     1\\tfrom __future__ import annotations\\n     2\\t\\n     3\\timport asyncio\\n     4\\timport os\\n     5\\timport signal\\n     6\\timport subprocess\\n     7\\timport sys\\n     8\\timport time\\n     9\\tfrom pathlib import Path\\n    10\\t\\n    11\\tfrom kaos.local import local_kaos\\n    12\\t\\n    13\\tfrom example_pkg.config import BackgroundConfig\\n    14\\tfrom example_pkg.notifications import NotificationEvent, NotificationManager\\n    15\\tfrom example_pkg.session import Session\\n    16\\tfrom example_pkg.utils.logging import logger\\n    17\\t\\n    1... [truncated]"}],"toolCalls":[],"toolCallId":"tool_7tKhkdZsBAFotRMTFs0BmgM6"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>89 lines read from file starting from line 1. End of file reached.</system>"},{"type":"text","text":"     1\\tfrom __future__ import annotations\\n     2\\t\\n     3\\timport time\\n     4\\tfrom typing import Literal\\n     5\\t\\n     6\\tfrom pydantic import BaseModel, ConfigDict, Field\\n     7\\t\\n     8\\ttype TaskKind = Literal[\\"bash\\", \\"agent\\"]\\n     9\\ttype TaskStatus = Literal[\\"created\\", \\"starting\\", \\"running\\", \\"completed\\", \\"failed\\", \\"killed\\", \\"lost\\"]\\n    10\\ttype TaskOwnerRole = Literal[\\"root\\", \\"fixed_subagent\\", \\"dynamic_subagent\\"]\\n    11\\t\\n    12\\tTERMINAL_TASK_STATUSES: tuple[TaskStatus, ...] = (\\"completed\\", \\"failed\\"... [truncated]"}],"toolCalls":[],"toolCallId":"tool_DR5VfRHgGe7WZ1dXKSA5Yowh"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>235 lines read from file starting from line 1. End of file reached.</system>"},{"type":"text","text":"     1\\timport time\\n     2\\tfrom pathlib import Path\\n     3\\tfrom typing import override\\n     4\\t\\n     5\\tfrom kosong.tooling import CallableTool2, ToolError, ToolReturnValue\\n     6\\tfrom pydantic import BaseModel, Field\\n     7\\t\\n     8\\tfrom example_pkg.background import format_task, format_task_list, list_task_views\\n     9\\tfrom example_pkg.soul.agent import Runtime\\n    10\\tfrom example_pkg.soul.approval import Approval\\n    11\\tfrom example_pkg.tools.display import BackgroundTaskDisplayBlock\\n    12\\tfrom example_pkg.too... [truncated]"}],"toolCalls":[],"toolCallId":"tool_XZXYciY6FY2Tl4SHwuh7Elhl"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"好的，我已经读取了关键的事实来源。现在让我继续读取其他重要文件来理解完整的功能边界：\\n\\n1. Shell 工具的后台模式支持\\n2. Notification 系统\\n3. Wire 协议更新\\n4. KimiSoul 中的 notification 集成\\n\\n让我继续读取这些文件。"}],"toolCalls":[{"type":"function","id":"tool_4vAGVbvQFNnyAFHtAkgnKwUu","function":{"name":"ReadFile","arguments":"{\\"path\\": \\"src/example_pkg/tools/shell/__init__.py\\"}"}},{"type":"function","id":"tool_YRsRNEO743zdY5vBEYPYv5QJ","function":{"name":"ReadFile","arguments":"{\\"path\\": \\"src/example_pkg/notifications/manager.py\\"}"}},{"type":"function","id":"tool_Zi0gi1gBQijIF8lEEx1RiSPz","function":{"name":"ReadFile","arguments":"{\\"path\\": \\"src/example_pkg/wire/types.py\\"}"}},{"type":"function","id":"tool_SorRMdJIzuUdPESVPYIbDqQU","function":{"name":"ReadFile","arguments":"{\\"path\\": \\"src/example_pkg/soul/kimisoul.py\\", \\"n_lines\\": 150}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>216 lines read from file starting from line 1. End of file reached.</system>"},{"type":"text","text":"     1\\timport asyncio\\n     2\\tfrom collections.abc import Callable\\n     3\\tfrom pathlib import Path\\n     4\\tfrom typing import Self, override\\n     5\\t\\n     6\\timport kaos\\n     7\\tfrom kaos import AsyncReadable\\n     8\\tfrom kosong.tooling import CallableTool2, ToolReturnValue\\n     9\\tfrom pydantic import BaseModel, Field, model_validator\\n    10\\t\\n    11\\tfrom example_pkg.background import TaskView, format_task\\n    12\\tfrom example_pkg.soul.agent import Runtime\\n    13\\tfrom example_pkg.soul.approval import Approval\\n  ... [truncated]"}],"toolCalls":[],"toolCallId":"tool_4vAGVbvQFNnyAFHtAkgnKwUu"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>105 lines read from file starting from line 1. End of file reached.</system>"},{"type":"text","text":"     1\\tfrom __future__ import annotations\\n     2\\t\\n     3\\timport time\\n     4\\timport uuid\\n     5\\tfrom pathlib import Path\\n     6\\t\\n     7\\tfrom example_pkg.config import NotificationConfig\\n     8\\t\\n     9\\tfrom .models import (\\n    10\\t    NotificationDelivery,\\n    11\\t    NotificationEvent,\\n    12\\t    NotificationSink,\\n    13\\t    NotificationSinkState,\\n    14\\t    NotificationView,\\n    15\\t)\\n    16\\tfrom .store import NotificationStore\\n    17\\t\\n    18\\t\\n    19\\tclass NotificationManager:\\n    20\\t    def __init__... [truncated]"}],"toolCalls":[],"toolCallId":"tool_YRsRNEO743zdY5vBEYPYv5QJ"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>515 lines read from file starting from line 1. End of file reached.</system>"},{"type":"text","text":"     1\\tfrom __future__ import annotations\\n     2\\t\\n     3\\timport asyncio\\n     4\\tfrom typing import Any, Literal, TypeGuard, cast\\n     5\\t\\n     6\\tfrom kosong.chat_provider import TokenUsage\\n     7\\tfrom kosong.message import (\\n     8\\t    AudioURLPart,\\n     9\\t    ContentPart,\\n    10\\t    ImageURLPart,\\n    11\\t    TextPart,\\n    12\\t    ThinkPart,\\n    13\\t    ToolCall,\\n    14\\t    ToolCallPart,\\n    15\\t    VideoURLPart,\\n    16\\t)\\n    17\\tfrom kosong.tooling import (\\n    18\\t    BriefDisplayBlock,\\n    19\\t    Dis... [truncated]"}],"toolCalls":[],"toolCallId":"tool_Zi0gi1gBQijIF8lEEx1RiSPz"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>150 lines read from file starting from line 1.</system>"},{"type":"text","text":"     1\\tfrom __future__ import annotations\\n     2\\t\\n     3\\timport asyncio\\n     4\\tfrom collections.abc import Awaitable, Callable, Sequence\\n     5\\tfrom contextlib import suppress\\n     6\\tfrom dataclasses import dataclass\\n     7\\tfrom functools import partial\\n     8\\tfrom pathlib import Path\\n     9\\tfrom typing import TYPE_CHECKING, Any, Literal\\n    10\\t\\n    11\\timport kosong\\n    12\\timport tenacity\\n    13\\tfrom kosong import StepResult\\n    14\\tfrom kosong.chat_provider import (\\n    15\\t    APIConnectionError... [truncated]"}],"toolCalls":[],"toolCallId":"tool_SorRMdJIzuUdPESVPYIbDqQU"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"我已经获取了足够的背景信息。让我继续读取 KimiSoul 中 notification 相关的代码，以及相关的测试来理解完整的功能边界。"}],"toolCalls":[{"type":"function","id":"tool_okFY9oLifSxqJb8egNPac0MS","function":{"name":"ReadFile","arguments":"{\\"path\\": \\"src/example_pkg/soul/kimisoul.py\\", \\"line_offset\\": 200, \\"n_lines\\": 200}"}},{"type":"function","id":"tool_CcxVl6nzWr4TfMaivaLiZxsz","function":{"name":"Grep","arguments":"{\\"pattern\\": \\"def _step|notification|claim|publish\\", \\"path\\": \\"src/example_pkg/soul/kimisoul.py\\", \\"output_mode\\": \\"content\\", \\"-n\\": true}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>200 lines read from file starting from line 200.</system>"},{"type":"text","text":"   200\\t\\n   201\\t        def path_getter() -> Path | None:\\n   202\\t            return self.get_plan_file_path()\\n   203\\t\\n   204\\t        # WriteFile gets both checker and path_getter (for plan file auto-approve)\\n   205\\t        from example_pkg.tools.file.write import WriteFile\\n   206\\t\\n   207\\t        write_tool = self._agent.toolset.find(\\"WriteFile\\")\\n   208\\t        if isinstance(write_tool, WriteFile):\\n   209\\t            write_tool.bind_plan_mode(checker, path_getter)\\n   210\\t\\n   211\\t        # ExitPlanMod... [truncated]"}],"toolCalls":[],"toolCallId":"tool_okFY9oLifSxqJb8egNPac0MS"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"26:from example_pkg.notifications import build_notification_message, extract_notification_ids\\n147:            self._runtime.notifications.ack_ids(\\"llm\\", extract_notification_ids(context.history))\\n626:    async def _step(self) -> StepOutcome | None:\\n634:            notifications = self._runtime.notifications.claim_for_sink(\\"llm\\", limit=4)\\n635:            if notifications:\\n637:                    build_notification_message(view, self._runtime) for view in notifications\\n640:                self._runti... [truncated]"}],"toolCalls":[],"toolCallId":"tool_CcxVl6nzWr4TfMaivaLiZxsz"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"现在我对功能有了完整的理解。让我总结一下测试范围：\\n\\n**功能边界：**\\n1. **后台任务系统** - 创建、监控、停止、输出获取\\n2. **通知系统** - 发布、消费、去重、确认\\n3. **集成点** - Shell 后台模式、TaskList/TaskOutput/TaskStop 工具、Wire 通知事件、LLM 通知消息\\n\\n**用户可感知的行为变化：**\\n1. Shell 工具新增 \`run_in_background\` 和 \`description\` 参数\\n2. 新增 TaskList/TaskOutput/TaskStop 工具\\n3. 后台任务完成后自动发送通知到 LLM context 和 Wire\\n4. 通知通过独立的 \`<notification>\` 消息进入 context\\n5. Wire 协议新增 \`Notification\` 事件类型\\n\\n**测试计划：**\\n1. **正常路径** - 启动后台任务，等待完成，验证通知\\n2. **边界条件** - 超时处理、重复停止、无效 task_id\\n3. **中断/清理** - 主动停止任务、任务丢失恢复\\n\\n让我开始制定... [truncated]"},{"type":"text","text":"现在我对功能有了完整理解。让我制定测试计划：\\n\\n## 功能边界总结\\n\\n**主要变更：**\\n1. **后台任务系统** (\`background/\`) - 全新模块，支持后台 bash 任务\\n2. **通知系统** (\`notifications/\`) - 独立基建，支持多 sink (llm/wire/shell)\\n3. **新工具** - \`TaskList\` / \`TaskOutput\` / \`TaskStop\`\\n4. **Shell 工具更新** - 新增 \`run_in_background\` + \`description\` 参数\\n5. **Wire 协议** - 新增 \`Notification\` 事件类型\\n6. **KimiSoul 集成** - 自动 claim/ack notification，compaction 后恢复活跃任务快照\\n\\n**测试范围：**\\n- 后台任务生命周期（创建→运行→完成→通知）\\n- 任务控制工具（List/Output/Stop）\\n- 通知系统（去重、claim/ack、多 sink）\\n- 集成点（Shell 后台模式、Wire 事件、LLM ... [truncated]"}],"toolCalls":[{"type":"function","id":"tool_y3SXWWQIUysddnYoklaWhUeE","function":{"name":"SetTodoList","arguments":"{\\"todos\\": [{\\"title\\": \\"准备测试环境（创建隔离 work-dir）\\", \\"status\\": \\"in_progress\\"}, {\\"title\\": \\"探索轮：验证工具可用性和接口\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"执行轮1：正常路径 - 后台任务生命周期\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"执行轮2：边界条件 - 超时和停止\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"执行轮3：中断场景 - TaskStop 和恢复\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"观察轮：检查 session 产物\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"汇报结论\\", \\"status\\": \\"pending\\"}]}"}},{"type":"function","id":"tool_BH2zd6kVzHhV4pIjKLSmrUeB","function":{"name":"Shell","arguments":"{\\"command\\": \\"SMOKE_DIR=\\\\\\"$(mktemp -d /tmp/kimi-smoke-XXXXXX)\\\\\\"\\\\necho \\\\\\"SMOKE_DIR=$SMOKE_DIR\\\\\\"\\\\n# 验证 CLI 可运行\\\\nuv run python -m example_pkg.cli --help 2>&1 | head -20\\"}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Todo list updated</system>"}],"toolCalls":[],"toolCallId":"tool_y3SXWWQIUysddnYoklaWhUeE"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"SMOKE_DIR=/tmp/kimi-smoke-a2i1xj\\n                                                                                \\n Usage: python -m example_pkg.cli [OPTIONS] COMMAND [ARGS]...                      \\n                                                                                \\n The Starting Point for Next-Gen Agents                                                     \\n                                                                                \\n╭─ Options ───────────────────────────────────────────────────... [truncated]"}],"toolCalls":[],"toolCallId":"tool_BH2zd6kVzHhV4pIjKLSmrUeB"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"环境准备好了，现在让我开始第一轮探索测试，验证工具可用性。"}],"toolCalls":[{"type":"function","id":"tool_mj72EeaBIxBi3NOVwE3tjxBc","function":{"name":"SetTodoList","arguments":"{\\"todos\\": [{\\"title\\": \\"准备测试环境（创建隔离 work-dir）\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"探索轮：验证工具可用性和接口\\", \\"status\\": \\"in_progress\\"}, {\\"title\\": \\"执行轮1：正常路径 - 后台任务生命周期\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"执行轮2：边界条件 - 超时和停止\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"执行轮3：中断场景 - TaskStop 和恢复\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"观察轮：检查 session 产物\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"汇报结论\\", \\"status\\": \\"pending\\"}]}"}},{"type":"function","id":"tool_ocohNUErNzzNQnYsibl670ms","function":{"name":"Shell","arguments":"{\\"command\\": \\"SMOKE_DIR=\\\\\\"/tmp/kimi-smoke-a2i1xj\\\\\\"\\\\n\\\\n# 探索轮：验证后台任务相关工具是否可用\\\\nuv run python -m example_pkg.cli \\\\\\\\\\\\n  --print \\\\\\\\\\\\n  --prompt \\\\\\"请列出你当前所有可用的工具，特别关注：\\\\n1. 是否有 TaskList、TaskOutput、TaskStop 这三个工具？\\\\n2. Shell 工具是否支持 run_in_background 参数？\\\\n3. 简单描述这些工具的功能。\\\\\\" \\\\\\\\\\\\n  --work-dir \\\\\\"$SMOKE_DIR\\\\\\" 2>&1\\\\necho \\\\\\"exit_code=$?\\\\\\"\\", \\"timeout\\": 120}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Todo list updated</system>"}],"toolCalls":[],"toolCallId":"tool_mj72EeaBIxBi3NOVwE3tjxBc"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"请列出你当前所有可用的工具，特别关注：\\n1. 是否有 TaskList、TaskOutput、TaskStop 这三个工具？\\n2. Shell 工具是否支持 run_in_background 参数？\\n3. 简单描述这些工具的功能。\\nTurnBegin(\\n    user_input='请列出你当前所有可用的工具，特别关注：\\\\n1. 是否有 \\nTaskList、TaskOutput、TaskStop 这三个工具？\\\\n2. Shell 工具是否支持 \\nrun_in_background 参数？\\\\n3. 简单描述这些工具的功能。'\\n)\\nStepBegin(n=1)\\nThinkPart(\\n    type='think',\\n    think='用户询问我当前可用的工具列表，特别关注三个问题：\\\\n1. 是否有 \\nTaskList、TaskOutput、TaskStop 这三个工具？\\\\n2. Shell 工具是否支持 \\nrun_in_background 参数？\\\\n3. \\n简单描述这些工具的功能。\\\\n\\\\n我需要查看我的工具列表。从 system \\n提示中，我可以看到我有以下工具：\\\\n- Tas... [truncated]"}],"toolCalls":[],"toolCallId":"tool_ocohNUErNzzNQnYsibl670ms"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"探索轮成功，工具都已正确加载。现在进入执行轮1：测试正常路径 - 启动后台任务，等待完成，验证通知。"},{"type":"text","text":"探索轮成功！工具都已正确加载。现在执行第一轮测试："}],"toolCalls":[{"type":"function","id":"tool_bpOwCgVz6wYah52SnaJB39ZW","function":{"name":"SetTodoList","arguments":"{\\"todos\\": [{\\"title\\": \\"准备测试环境（创建隔离 work-dir）\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"探索轮：验证工具可用性和接口\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"执行轮1：正常路径 - 后台任务生命周期\\", \\"status\\": \\"in_progress\\"}, {\\"title\\": \\"执行轮2：边界条件 - 超时和停止\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"执行轮3：中断场景 - TaskStop 和恢复\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"观察轮：检查 session 产物\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"汇报结论\\", \\"status\\": \\"pending\\"}]}"}},{"type":"function","id":"tool_HejoTo6Izmlets9y9hN9u1pZ","function":{"name":"Shell","arguments":"{\\"command\\": \\"SMOKE_DIR=\\\\\\"/tmp/kimi-smoke-a2i1xj\\\\\\"\\\\n\\\\n# 执行轮1：正常路径 - 启动一个短生命周期的后台任务，验证生命周期完整\\\\nuv run python -m example_pkg.cli \\\\\\\\\\\\n  --print \\\\\\\\\\\\n  --prompt \\\\\\"请执行以下测试：\\\\n\\\\n1. 使用 Shell 工具启动一个后台任务：\\\\n   - 命令: echo 'hello from background' && sleep 2 && echo 'task done'\\\\n   - run_in_background: true\\\\n   - description: '测试后台任务生命周期'\\\\n   - timeout: 30\\\\n\\\\n2. 记录返回的 task_id\\\\n\\\\n3. 使用 TaskList 查看当前活跃任务\\\\n\\\\n4. 使用 TaskOutput 获取任务输出（block=true, timeout=10）\\\\n\\\\n请报告：task_id、任务状态、输出内容。\\\\\\" \\\\\\\\\\\\n  --work-dir \\\\\\"$SMOKE_DIR\\\\\\" 2>&... [truncated]"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Todo list updated</system>"}],"toolCalls":[],"toolCallId":"tool_bpOwCgVz6wYah52SnaJB39ZW"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"请执行以下测试：\\n\\n1. 使用 Shell 工具启动一个后台任务：\\n   - 命令: echo 'hello from background' && sleep 2 && echo 'task done'\\n   - run_in_background: true\\n   - description: '测试后台任务生命周期'\\n   - timeout: 30\\n\\n2. 记录返回的 task_id\\n\\n3. 使用 TaskList 查看当前活跃任务\\n\\n4. 使用 TaskOutput 获取任务输出（block=true, timeout=10）\\n\\n请报告：task_id、任务状态、输出内容。\\nTurnBegin(\\n    user_input=\\"请执行以下测试：\\\\n\\\\n1. 使用 Shell 工具启动一个后台任务：\\\\n   - \\n命令: echo 'hello from background' && sleep 2 && echo 'task done'\\\\n   - \\nrun_in_background: true\\\\n   - description: '测试后台任务生命周期'\\\\n   - t... [truncated]"}],"toolCalls":[],"toolCallId":"tool_HejoTo6Izmlets9y9hN9u1pZ"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"第一轮测试成功！关键验证点：\\n1. ✅ Shell 后台任务启动成功，返回 task_id\\n2. ✅ TaskList 正确工作\\n3. ✅ TaskOutput 正确工作，block=true 等待完成\\n4. ✅ Notification 事件正确发送（Wire 中可见 Notification 事件）\\n\\n现在进行第二轮：边界条件 - 测试超时和停止功能。"},{"type":"text","text":"第一轮成功！所有核心功能正常工作。现在测试边界条件："}],"toolCalls":[{"type":"function","id":"tool_3tueNNJt54oG2X47QK4PLnTj","function":{"name":"SetTodoList","arguments":"{\\"todos\\": [{\\"title\\": \\"准备测试环境（创建隔离 work-dir）\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"探索轮：验证工具可用性和接口\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"执行轮1：正常路径 - 后台任务生命周期\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"执行轮2：边界条件 - 超时和停止\\", \\"status\\": \\"in_progress\\"}, {\\"title\\": \\"执行轮3：中断场景 - TaskStop 和恢复\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"观察轮：检查 session 产物\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"汇报结论\\", \\"status\\": \\"pending\\"}]}"}},{"type":"function","id":"tool_NT90qPui3vOOBqIjmTgvYe9Q","function":{"name":"Shell","arguments":"{\\"command\\": \\"SMOKE_DIR=\\\\\\"/tmp/kimi-smoke-a2i1xj\\\\\\"\\\\n\\\\n# 执行轮2：边界条件 - 超时处理和停止\\\\nuv run python -m example_pkg.cli \\\\\\\\\\\\n  --print \\\\\\\\\\\\n  --prompt \\\\\\"请执行以下边界条件测试：\\\\n\\\\n1. 启动一个长时间运行的后台任务（会被停止）：\\\\n   - 命令: for i in 1 2 3 4 5; do echo \\\\\\\\\\\\\\"line \\\\\\\\$i\\\\\\\\\\\\\\"; sleep 5; done\\\\n   - run_in_background: true\\\\n   - description: '测试停止功能'\\\\n   - timeout: 60\\\\n\\\\n2. 使用 TaskList 确认任务在运行中\\\\n\\\\n3. 等待 3 秒后，使用 TaskStop 停止该任务\\\\n\\\\n4. 使用 TaskOutput 获取任务最终状态和输出\\\\n\\\\n请报告：task_id、停止前后的状态、输出内容、是否有正确通知。\\\\\\" \\\\\\\\\\\\n  --work-dir \\\\\\"$SMOKE_DIR\\\\\\" 2>&1\\\\necho \\\\\\"... [truncated]"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Todo list updated</system>"}],"toolCalls":[],"toolCallId":"tool_3tueNNJt54oG2X47QK4PLnTj"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"请执行以下边界条件测试：\\n\\n1. 启动一个长时间运行的后台任务（会被停止）：\\n   - 命令: for i in 1 2 3 4 5; do echo \\"line $i\\"; sleep 5; done\\n   - run_in_background: true\\n   - description: '测试停止功能'\\n   - timeout: 60\\n\\n2. 使用 TaskList 确认任务在运行中\\n\\n3. 等待 3 秒后，使用 TaskStop 停止该任务\\n\\n4. 使用 TaskOutput 获取任务最终状态和输出\\n\\n请报告：task_id、停止前后的状态、输出内容、是否有正确通知。\\nTurnBegin(\\n    user_input='请执行以下边界条件测试：\\\\n\\\\n1. \\n启动一个长时间运行的后台任务（会被停止）：\\\\n   - 命令: for i in 1 2 3 4 5; do \\necho \\"line $i\\"; sleep 5; done\\\\n   - run_in_background: true\\\\n   - description: \\n\\\\'测试停止功能\\\\'\\\\n   - timeou... [truncated]"}],"toolCalls":[],"toolCallId":"tool_NT90qPui3vOOBqIjmTgvYe9Q"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"第二轮也成功！测试了停止功能，验证了：\\n1. ✅ TaskStop 成功停止任务\\n2. ✅ 通知正确发送 (task.killed)\\n3. ✅ exit_code 正确 (-15 = SIGTERM)\\n4. ✅ 输出正确捕获\\n\\n现在进行第三轮测试：测试超时处理。"},{"type":"text","text":"第二轮成功！停止功能完全正常。现在测试超时场景："}],"toolCalls":[{"type":"function","id":"tool_TS5JUSZELJoTVcos6rp90ZUT","function":{"name":"SetTodoList","arguments":"{\\"todos\\": [{\\"title\\": \\"准备测试环境（创建隔离 work-dir）\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"探索轮：验证工具可用性和接口\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"执行轮1：正常路径 - 后台任务生命周期\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"执行轮2：边界条件 - 超时和停止\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"执行轮3：超时场景测试\\", \\"status\\": \\"in_progress\\"}, {\\"title\\": \\"观察轮：检查 session 产物\\", \\"status\\": \\"pending\\"}, {\\"title\\": \\"汇报结论\\", \\"status\\": \\"pending\\"}]}"}},{"type":"function","id":"tool_J3cQ5m3qyTep0zNLWhZR3OGg","function":{"name":"Shell","arguments":"{\\"command\\": \\"SMOKE_DIR=\\\\\\"/tmp/kimi-smoke-a2i1xj\\\\\\"\\\\n\\\\n# 执行轮3：测试超时处理\\\\nuv run python -m example_pkg.cli \\\\\\\\\\\\n  --print \\\\\\\\\\\\n  --prompt \\\\\\"请测试后台任务超时功能：\\\\n\\\\n1. 启动一个会超时的后台任务：\\\\n   - 命令: sleep 300\\\\n   - run_in_background: true\\\\n   - description: '测试超时处理'\\\\n   - timeout: 3  （设置为3秒，确保会超时）\\\\n\\\\n2. 使用 TaskOutput 阻塞等待任务结束（block=true, timeout=15）\\\\n\\\\n3. 检查任务最终状态是否为 timeout\\\\n\\\\n请报告：task_id、最终状态、exit_code、是否有 timeout 通知。\\\\\\" \\\\\\\\\\\\n  --work-dir \\\\\\"$SMOKE_DIR\\\\\\" 2>&1\\\\necho \\\\\\"exit_code=$?\\\\\\"\\", \\"timeout\\": 180}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Todo list updated</system>"}],"toolCalls":[],"toolCallId":"tool_TS5JUSZELJoTVcos6rp90ZUT"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"请测试后台任务超时功能：\\n\\n1. 启动一个会超时的后台任务：\\n   - 命令: sleep 300\\n   - run_in_background: true\\n   - description: '测试超时处理'\\n   - timeout: 3  （设置为3秒，确保会超时）\\n\\n2. 使用 TaskOutput 阻塞等待任务结束（block=true, timeout=15）\\n\\n3. 检查任务最终状态是否为 timeout\\n\\n请报告：task_id、最终状态、exit_code、是否有 timeout 通知。\\nTurnBegin(\\n    user_input=\\"请测试后台任务超时功能：\\\\n\\\\n1. 启动一个会超时的后台任务：\\\\n   - \\n命令: sleep 300\\\\n   - run_in_background: true\\\\n   - description: \\n'测试超时处理'\\\\n   - timeout: 3  （设置为3秒，确保会超时）\\\\n\\\\n2. 使用 TaskOutput\\n阻塞等待任务结束（block=true, timeout=15）\\\\n\\\\n3. 检查任务最终状态是否为 \\n... [truncated]"}],"toolCalls":[],"toolCallId":"tool_J3cQ5m3qyTep0zNLWhZR3OGg"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"第三轮也成功！测试了超时处理：\\n1. ✅ 任务正确超时\\n2. ✅ 状态为 failed，timed_out=true\\n3. ✅ 通知正确发送 (task.timed_out)\\n4. ✅ exit_code 正确 (-15)\\n\\n现在进入观察轮，检查 session 产物，验证 notification 是否正确写入 context 等。"},{"type":"text","text":"第三轮成功！超时处理完全正常。现在进入观察轮，检查 session 产物："}],"toolCalls":[{"type":"function","id":"tool_n7Bz3OSHPlOZnL3ghEe8Rciw","function":{"name":"SetTodoList","arguments":"{\\"todos\\": [{\\"title\\": \\"准备测试环境（创建隔离 work-dir）\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"探索轮：验证工具可用性和接口\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"执行轮1：正常路径 - 后台任务生命周期\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"执行轮2：边界条件 - 超时和停止\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"执行轮3：超时场景测试\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"观察轮：检查 session 产物\\", \\"status\\": \\"in_progress\\"}, {\\"title\\": \\"汇报结论\\", \\"status\\": \\"pending\\"}]}"}},{"type":"function","id":"tool_3s3qLBo5c7kA1pqbpX36YbVo","function":{"name":"Shell","arguments":"{\\"command\\": \\"SMOKE_DIR=\\\\\\"/tmp/kimi-smoke-a2i1xj\\\\\\"\\\\n\\\\n# 查找 session 目录\\\\necho \\\\\\"=== Session 定位 ===\\\\\\"\\\\nSESSION_ID=$(echo -n \\\\\\"$SMOKE_DIR\\\\\\" | md5)\\\\necho \\\\\\"Work dir: $SMOKE_DIR\\\\\\"\\\\necho \\\\\\"Session ID (md5): $SESSION_ID\\\\\\"\\\\nSESSION_DIR=\\\\\\"$HOME/.kimi/sessions/$SESSION_ID\\\\\\"\\\\necho \\\\\\"Session dir: $SESSION_DIR\\\\\\"\\\\n\\\\n# 检查 session 目录是否存在\\\\nif [ -d \\\\\\"$SESSION_DIR\\\\\\" ]; then\\\\n    echo \\\\\\"Session exists: YES\\\\\\"\\\\n    ls -la \\\\\\"$SESSION_DIR\\\\\\"\\\\nelse\\\\n    echo \\\\\\"Session exists: NO\\\\\\"\\\\n    # 尝试找到最新的 session\\\\n    echo \\\\\\"Finding... [truncated]"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Todo list updated</system>"}],"toolCalls":[],"toolCallId":"tool_n7Bz3OSHPlOZnL3ghEe8Rciw"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"=== Session 定位 ===\\nWork dir: /tmp/kimi-smoke-a2i1xj\\nSession ID (md5): d1c3750c0cc0757aeac04ad5a7d6b8cf\\nSession dir: /Users/example/proj/.kimi/sessions/d1c3750c0cc0757aeac04ad5a7d6b8cf\\nSession exists: YES\\ntotal 0\\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:59 .\\ndrwxr-xr-x@ 1722 user      staff  55104  3月 17 12:58 ..\\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:58 0e1d3b94-dae2-4dfb-b36d-717397f4d2f6\\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:59 228b54e2-5b5d-4675-94f2-ec56e42cdbae\\nd... [truncated]"}],"toolCalls":[],"toolCallId":"tool_3s3qLBo5c7kA1pqbpX36YbVo"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"找到了 session 目录，下面有多个子目录（每次运行 CLI 会创建一个新的子 session）。让我使用 inspect_session.py 来检查最新的 session。"}],"toolCalls":[{"type":"function","id":"tool_4Zcuo5i4xl2NEz1Y1EZ1IvSn","function":{"name":"Shell","arguments":"{\\"command\\": \\"SMOKE_DIR=\\\\\\"/tmp/kimi-smoke-a2i1xj\\\\\\"\\\\n\\\\n# 使用 inspect_session.py 检查最新的 session\\\\necho \\\\\\"=== 使用 inspect_session.py 检查 ===\\\\\\"\\\\nuv run python .agents/skills/example-task/scripts/inspect_session.py --share-dir ~/.kimi 2>&1\\"}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"=== 使用 inspect_session.py 检查 ===\\nSession dir: /Users/example/proj/.kimi/sessions/6a7967e2a97cd71a62b8375c5ae461ba/ef00f9f9-a470-4e50-b279-59429da67d27\\n\\n== Files ==\\ncontext.jsonl (209039 bytes)\\nstate.json (188 bytes)\\nwire.jsonl (197310 bytes)\\n\\n== Context ==\\n/Users/example/proj/.kimi/sessions/6a7967e2a97cd71a62b8375c5ae461ba/ef00f9f9-a470-4e50-b279-59429da67d27/context.jsonl\\nrecords: 85\\nroles: _checkpoint=16, _system_prompt=1, _usage=27, assistant=13, tool=26, user=2\\n[74] role=assistant | tools=SetTodoLis... [truncated]"}],"toolCalls":[],"toolCallId":"tool_4Zcuo5i4xl2NEz1Y1EZ1IvSn"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"这个 session 不是我刚才测试的那个。让我直接检查正确的 session 目录（d1c3750c0cc0757aeac04ad5a7d6b8cf），里面有多个子目录，对应三次测试运行。"}],"toolCalls":[{"type":"function","id":"tool_DmwmxRwjKGDXt1PTAyVbYAdM","function":{"name":"Shell","arguments":"{\\"command\\": \\"SMOKE_DIR=\\\\\\"/tmp/kimi-smoke-a2i1xj\\\\\\"\\\\nSESSION_ID=$(echo -n \\\\\\"$SMOKE_DIR\\\\\\" | md5)\\\\nSESSION_DIR=\\\\\\"$HOME/.kimi/sessions/$SESSION_ID\\\\\\"\\\\n\\\\necho \\\\\\"=== 检查正确的 session 目录 ===\\\\\\"\\\\necho \\\\\\"Session dir: $SESSION_DIR\\\\\\"\\\\necho \\\\\\"\\\\\\"\\\\necho \\\\\\"=== 子目录列表 ===\\\\\\"\\\\nls -la \\\\\\"$SESSION_DIR\\\\\\"\\\\n\\\\n# 检查每个子目录的 wire.jsonl 中的 Notification 事件\\\\necho \\\\\\"\\\\\\"\\\\necho \\\\\\"=== 检查 Notification 事件 ===\\\\\\"\\\\nfor subdir in \\\\\\"$SESSION_DIR\\\\\\"/*; do\\\\n    if [ -d \\\\\\"$subdir\\\\\\" ] && [ -f \\\\\\"$subdir/wire.jsonl\\\\\\" ]; then\\\\n        subname=$(basename... [truncated]"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"=== 检查正确的 session 目录 ===\\nSession dir: /Users/example/proj/.kimi/sessions/d1c3750c0cc0757aeac04ad5a7d6b8cf\\n\\n=== 子目录列表 ===\\ntotal 0\\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:59 .\\ndrwxr-xr-x@ 1722 user      staff  55104  3月 17 12:58 ..\\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:58 0e1d3b94-dae2-4dfb-b36d-717397f4d2f6\\ndrwxr-xr-x@    6 user      staff    192  3月 17 12:59 228b54e2-5b5d-4675-94f2-ec56e42cdbae\\ndrwxr-xr-x@    6 user      staff    192  3月 17 13:00 be8228d5-1c57-43dc-9f23-9e7dba2... [truncated]"}],"toolCalls":[],"toolCallId":"tool_DmwmxRwjKGDXt1PTAyVbYAdM"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"奇怪，没有找到 Notification 事件。可能 Notification 事件格式不一样，让我直接查看 wire.jsonl 文件内容，搜索 notification。"}],"toolCalls":[{"type":"function","id":"tool_97R6Gz8LI01cAOsQDuv9nbwm","function":{"name":"Shell","arguments":"{\\"command\\": \\"SMOKE_DIR=\\\\\\"/tmp/kimi-smoke-a2i1xj\\\\\\"\\\\nSESSION_ID=$(echo -n \\\\\\"$SMOKE_DIR\\\\\\" | md5)\\\\nSESSION_DIR=\\\\\\"$HOME/.kimi/sessions/$SESSION_ID\\\\\\"\\\\n\\\\n# 直接查看每个子目录的 wire.jsonl 内容\\\\necho \\\\\\"=== 查看 wire.jsonl 中的通知相关内容 ===\\\\\\"\\\\nfor subdir in \\\\\\"$SESSION_DIR\\\\\\"/*; do\\\\n    if [ -d \\\\\\"$subdir\\\\\\" ] && [ -f \\\\\\"$subdir/wire.jsonl\\\\\\" ]; then\\\\n        subname=$(basename \\\\\\"$subdir\\\\\\")\\\\n        echo \\\\\\"\\\\\\"\\\\n        echo \\\\\\"--- Sub-session: $subname ---\\\\\\"\\\\n        # 查找包含 notification 的行\\\\n        grep -i \\\\\\"notification\\\\\\\\|task\\\\\\\\.... [truncated]"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"=== 查看 wire.jsonl 中的通知相关内容 ===\\n\\n--- Sub-session: 0e1d3b94-dae2-4dfb-b36d-717397f4d2f6 ---\\n{\\"timestamp\\": 1773723525.133148, \\"message\\": {\\"type\\": \\"ToolResult\\", \\"payload\\": {\\"tool_call_id\\": \\"tool_KviOIHcT5WgvrVhhHtEzsDNR\\", \\"return_value\\": {\\"is_error\\": false, \\"output\\": \\"task_id: b83rhswvs\\\\nkind: bash\\\\nstatus: starting\\\\ndescription: 测试后台任务生命周期\\\\ncommand: echo 'hello from background' && sleep 2 && echo 'task done'\\\\nautomatic_notification: true\\\\nnext_step: You will be automatically notified when it comple... [truncated]"}],"toolCalls":[],"toolCallId":"tool_97R6Gz8LI01cAOsQDuv9nbwm"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"我找到了所有的 Notification 事件：\\n1. \`0e1d3b94-dae2-4dfb-b36d-717397f4d2f6\` - task.completed (b83rhswvs)\\n2. \`228b54e2-5b5d-4675-94f2-ec56e42cdbae\` - task.killed (bp6amsrcu)\\n3. \`be8228d5-1c57-43dc-9f23-9e7dba209a1a\` - task.timed_out (b4c3d8fta)\\n\\n现在让我检查 context.jsonl 中是否有 notification 消息，以及 task 目录结构。"},{"type":"text","text":"找到了所有 Notification 事件！现在检查 context.jsonl 和 task 目录："}],"toolCalls":[{"type":"function","id":"tool_74k2gxGVF3RSOhTaEhnnvPzk","function":{"name":"Shell","arguments":"{\\"command\\": \\"SMOKE_DIR=\\\\\\"/tmp/kimi-smoke-a2i1xj\\\\\\"\\\\nSESSION_ID=$(echo -n \\\\\\"$SMOKE_DIR\\\\\\" | md5)\\\\nSESSION_DIR=\\\\\\"$HOME/.kimi/sessions/$SESSION_ID\\\\\\"\\\\n\\\\n# 检查 context.jsonl 中的 notification 消息\\\\necho \\\\\\"=== 检查 context.jsonl 中的 notification 消息 ===\\\\\\"\\\\nfor subdir in \\\\\\"$SESSION_DIR\\\\\\"/*; do\\\\n    if [ -d \\\\\\"$subdir\\\\\\" ] && [ -f \\\\\\"$subdir/context.jsonl\\\\\\" ]; then\\\\n        subname=$(basename \\\\\\"$subdir\\\\\\")\\\\n        count=$(grep -c '\\\\\\"role\\\\\\":\\\\\\"notification\\\\\\"' \\\\\\"$subdir/context.jsonl\\\\\\" 2>/dev/null || echo \\\\\\"0\\\\\\")\\\\n      ... [truncated]"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"=== 检查 context.jsonl 中的 notification 消息 ===\\nSub-session 0e1d3b94-dae2-4dfb-b36d-717397f4d2f6: notification messages = 0\\n0\\n/bin/bash: line 11: [: 0\\n0: integer expression expected\\nSub-session 228b54e2-5b5d-4675-94f2-ec56e42cdbae: notification messages = 0\\n0\\n/bin/bash: line 11: [: 0\\n0: integer expression expected\\nSub-session be8228d5-1c57-43dc-9f23-9e7dba209a1a: notification messages = 0\\n0\\n/bin/bash: line 11: [: 0\\n0: integer expression expected\\nSub-session ea3920e8-2a4b-4e38-be51-c500aab582ab: noti... [truncated]"}],"toolCalls":[],"toolCallId":"tool_74k2gxGVF3RSOhTaEhnnvPzk"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"找到了 task 目录。现在让我检查 task 目录的内容，以及 notification 持久化目录。"}],"toolCalls":[{"type":"function","id":"tool_doClKbqjLQAuMtimAxF3mufI","function":{"name":"Shell","arguments":"{\\"command\\": \\"SMOKE_DIR=\\\\\\"/tmp/kimi-smoke-a2i1xj\\\\\\"\\\\nSESSION_ID=$(echo -n \\\\\\"$SMOKE_DIR\\\\\\" | md5)\\\\nSESSION_DIR=\\\\\\"$HOME/.kimi/sessions/$SESSION_ID\\\\\\"\\\\n\\\\n# 检查 task 目录内容\\\\necho \\\\\\"=== 检查第一个 task 的目录结构 ===\\\\\\"\\\\nTASK_DIR=\\\\\\"$SESSION_DIR/0e1d3b94-dae2-4dfb-b36d-717397f4d2f6/tasks/b83rhswvs\\\\\\"\\\\nls -la \\\\\\"$TASK_DIR\\\\\\"\\\\n\\\\necho \\\\\\"\\\\\\"\\\\necho \\\\\\"=== spec.json ===\\\\\\"\\\\ncat \\\\\\"$TASK_DIR/spec.json\\\\\\"\\\\n\\\\necho \\\\\\"\\\\\\"\\\\necho \\\\\\"=== runtime.json ===\\\\\\"\\\\ncat \\\\\\"$TASK_DIR/runtime.json\\\\\\"\\\\n\\\\necho \\\\\\"\\\\\\"\\\\necho \\\\\\"=== output.log ===\\\\\\"\\\\ncat \\\\\\"$TASK_... [truncated]"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"=== 检查第一个 task 的目录结构 ===\\ntotal 40\\ndrwxr-xr-x@ 7 user      staff  224  3月 17 12:58 .\\ndrwxr-xr-x@ 3 user      staff   96  3月 17 12:58 ..\\n-rw-------@ 1 user      staff   72  3月 17 12:58 consumer.json\\n-rw-------@ 1 user      staff   72  3月 17 12:58 control.json\\n-rw-r--r--@ 1 user      staff   32  3月 17 12:58 output.log\\n-rw-------@ 1 user      staff  331  3月 17 12:58 runtime.json\\n-rw-------@ 1 user      staff  481  3月 17 12:58 spec.json\\n\\n=== spec.json ===\\n{\\n  \\"version\\": 1,\\n  \\"id\\": \\"b83rhswvs\\",\\n  \\"kin... [truncated]"}],"toolCalls":[],"toolCallId":"tool_doClKbqjLQAuMtimAxF3mufI"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"所有验证都通过了：\\n1. task 目录结构正确\\n2. spec.json 包含正确的 task 信息\\n3. runtime.json 包含正确的状态信息\\n4. output.log 包含正确的输出\\n5. notification 持久化正确\\n\\n现在让我检查 notification 目录的内容。"}],"toolCalls":[{"type":"function","id":"tool_7SICneqn0eGcgCADXOFuo2yj","function":{"name":"Shell","arguments":"{\\"command\\": \\"SMOKE_DIR=\\\\\\"/tmp/kimi-smoke-a2i1xj\\\\\\"\\\\nSESSION_ID=$(echo -n \\\\\\"$SMOKE_DIR\\\\\\" | md5)\\\\nSESSION_DIR=\\\\\\"$HOME/.kimi/sessions/$SESSION_ID\\\\\\"\\\\n\\\\n# 检查 notification 目录内容\\\\necho \\\\\\"=== 检查 notification 持久化内容 ===\\\\\\"\\\\nNOTIF_DIR=\\\\\\"$SESSION_DIR/0e1d3b94-dae2-4dfb-b36d-717397f4d2f6/notifications/n495ae5fb\\\\\\"\\\\necho \\\\\\"Notification: n495ae5fb (task.completed)\\\\\\"\\\\nls -la \\\\\\"$NOTIF_DIR\\\\\\"\\\\n\\\\necho \\\\\\"\\\\\\"\\\\necho \\\\\\"=== event.json ===\\\\\\"\\\\ncat \\\\\\"$NOTIF_DIR/event.json\\\\\\" | head -30\\\\n\\\\necho \\\\\\"\\\\\\"\\\\necho \\\\\\"=== delivery.json ===\\\\... [truncated]"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"=== 检查 notification 持久化内容 ===\\nNotification: n495ae5fb (task.completed)\\ntotal 16\\ndrwxr-xr-x@ 4 user      staff  128  3月 17 12:58 .\\ndrwxr-xr-x@ 3 user      staff   96  3月 17 12:58 ..\\n-rw-------@ 1 user      staff  332  3月 17 12:58 delivery.json\\n-rw-------@ 1 user      staff  790  3月 17 12:58 event.json\\n\\n=== event.json ===\\n{\\n  \\"version\\": 1,\\n  \\"id\\": \\"n495ae5fb\\",\\n  \\"category\\": \\"task\\",\\n  \\"type\\": \\"task.completed\\",\\n  \\"source_kind\\": \\"background_task\\",\\n  \\"source_id\\": \\"b83rhswvs\\",\\n  \\"title\\": \\"Background ta... [truncated]"}],"toolCalls":[],"toolCallId":"tool_7SICneqn0eGcgCADXOFuo2yj"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"所有验证都通过了！现在让我总结冒烟测试的结果。"},{"type":"text","text":"所有验证完成！现在更新 todo 并汇报结论："}],"toolCalls":[{"type":"function","id":"tool_CcJKFj7faabalZQ9X1gPrTbr","function":{"name":"SetTodoList","arguments":"{\\"todos\\": [{\\"title\\": \\"准备测试环境（创建隔离 work-dir）\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"探索轮：验证工具可用性和接口\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"执行轮1：正常路径 - 后台任务生命周期\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"执行轮2：边界条件 - 超时和停止\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"执行轮3：超时场景测试\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"观察轮：检查 session 产物\\", \\"status\\": \\"done\\"}, {\\"title\\": \\"汇报结论\\", \\"status\\": \\"done\\"}]}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Todo list updated</system>"}],"toolCalls":[],"toolCallId":"tool_CcJKFj7faabalZQ9X1gPrTbr"}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"所有测试完成。现在整理完整的测试报告。"},{"type":"text","text":"---\\n\\n## 冒烟测试报告\\n\\n### 测试范围\\n**后台任务系统 + 通知系统** - 本次变更新增的核心功能\\n\\n### 已确认的行为 ✅\\n\\n| 功能 | 验证结果 |\\n|------|----------|\\n| **Shell 后台模式** | \`run_in_background=true\` + \`description\` 参数正常工作 |\\n| **TaskList** | 正确列出活跃/全部任务，显示 task_id/kind/status/description |\\n| **TaskOutput** | \`block=true/false\` 模式工作正常，返回完整任务状态和输出 |\\n| **TaskStop** | 成功发送 SIGTERM 停止任务，支持自定义 reason |\\n| **任务超时** | timeout 参数正确终止超时任务，exit_code=-15 |\\n| **Wire Notification** | \`Notification\` 事件正确发送，包含完整 payload |\\n| **Notification 持久化** | event.json + d... [truncated]"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"source /Users/example/proj/example-project/.venv/bin/activate"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"用户只是在执行激活虚拟环境的命令，这是一个 shell 命令。我应该执行它并确认环境已激活。"}],"toolCalls":[{"type":"function","id":"tool_oKHd9KBRZQ3pT7x7XgOWhcMJ","function":{"name":"Shell","arguments":"{\\"command\\": \\"source /Users/example/proj/example-project/.venv/bin/activate && echo \\\\\\"Virtual environment activated\\\\\\" && which python && python --version\\"}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"Virtual environment activated\\n/Users/example/proj/example-project/.venv/bin/python\\nPython 3.14.2\\n"}],"toolCalls":[],"toolCallId":"tool_oKHd9KBRZQ3pT7x7XgOWhcMJ"}}
+",
+}
+`;
+
+exports[`migration snapshot: legacy-protocol-1.3 > migration succeeds and matches snapshot 1`] = `
+{
+  "state": "{
+  "createdAt": "<REDACTED>",
+  "updatedAt": "<REDACTED>",
+  "title": "帮我创建一个 plan，来优化我当前 diff 中的代码",
+  "isCustomTitle": true,
+  "lastPrompt": "<system-reminder>\\n<!-- plan-mode-reminder -->\\nPlan mode is active. You are in a research and planning phase.\\n\\nIn plan mode, you should:\\n1. Thoroughly explore the codebase using Glob, Grep, and ReadFil",
+  "agents": {
+    "main": {
+      "homedir": "<TARGET>/sessions/wd_proj_33c5ea5aa7eb/ses_legacy-protocol-1.3/agents/main",
+      "type": "main",
+      "parentAgentId": null
+    }
+  },
+  "custom": {
+    "imported_from_kimi_cli": true,
+    "kimi_cli_source_path": "<REDACTED>",
+    "kimi_cli_session_id": "legacy-protocol-1.3",
+    "kimi_cli_wire_protocol": "1.3",
+    "imported_at": "<REDACTED>",
+    "archived": true
+  }
+}",
+  "wire": "{"type":"metadata","protocol_version":"1.0","created_at":<REDACTED>}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"帮我写一个示例函数，处理字符串清理和分块"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"<system-reminder>\\n<!-- plan-mode-reminder -->\\nPlan mode is active. You are in a research and planning phase.\\n\\nIn plan mode, you should:\\n1. Thoroughly explore the codebase using Glob, Grep, and ReadFile tools.\\n2. Understand existing patterns and architecture.\\n3. Design an implementation approach.\\n4. Write your plan to the plan file using WriteFile.\\n5. Use AskUserQuestion if you need to clarify approaches.\\n6. When your plan is complete, call ExitPlanMode.\\n\\nRemember: DO NOT write or edit code files... [truncated]"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"用户想要写一个示例函数，处理字符串清理和分块。我先看看当前 diff 中有哪些相关代码可以参考。\\n\\n让我先检查一下当前的 git diff。"}],"toolCalls":[{"type":"function","id":"Shell:0","function":{"name":"Shell","arguments":"{\\"command\\": \\"git diff --no-color\\"}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"diff --git a/example.py b/example.py\\nindex 0000aaaa..1111bbbb 100644\\n--- a/example.py\\n+++ b/example.py\\n@@ -1,12 +1,16 @@\\n class Greeter:\\n     def __init__(self, name: str) -> None:\\n         self.name = name\\n+        self.greetings: list[str] = []\\n \\n     def greet(self) -> str:\\n-        return f\\"Hello, {self.name}!\\"\\n+        msg = f\\"Hello, {self.name}!\\"\\n+        self.greetings.append(msg)\\n+        return msg\\n \\n-    def farewell(self) -> str:\\n-        return f\\"Goodbye, {self.name}!\\"\\n+    def farewell(self, formal: bool = False) -> str:\\n+        prefix = \\"Farewell\\" if formal else \\"Goodbye\\"\\n+        return f\\"{prefix}, {self.name}!\\"\\n \\ndiff --git a/example/utils.py b/example/utils.py\\nindex 22223333..44445555 100644\\n--- a/example/utils.py\\n+++ b/example/utils.py\\n@@ -10,16 +10,20 @@ def slugify(text: str) -> str:\\n     result = text.lower()\\n     result = result.replace(\\" \\", \\"-\\")\\n-    # Remove punctuation\\n-    result = \\"\\".join(c for c in result if c.isalnum() or c == \\"-\\")\\n+    # Remove punctuation and collapse repeated dashes\\n+    cleaned = \\"\\".join(c for c in result if c.isalnum() or c == \\"-\\")\\n+    parts = [p for p in cleaned.split(\\"-\\") if p]\\n+    result = \\"-\\".join(parts)\\n     return result\\n \\n \\n def chunk(items: list[str], size: int) -> list[list[str]]:\\n-    if size <= 0:\\n-        raise ValueError(\\"size must be positive\\")\\n-    return [items[i:i + size] for i in range(0, len(items), size)]\\n+    if size <= 0:\\n+        raise ValueError(\\"chunk size must be a positive integer\\")\\n+    if not items:\\n+        return []\\n+    return [items[i : i + size] for i in range(0, len(items), size)]\\n \\n \\n def truncate(text: str, limit: int = 80) -> str:\\n@@ -32,8 +36,12 @@ def truncate(text: str, limit: int = 80) -> str:\\n         return text\\n     return text[: limit - 1] + \\"…\\"\\n \\n+\\n+def normalize_whitespace(text: str) -> str:\\n+    return \\" \\".join(text.split())\\n+\\n diff --git a/example/cli.py b/example/cli.py\\nindex 66667777..88889999 100644\\n--- a/example/cli.py\\n+++ b/example/cli.py\\n@@ -5,12 +5,18 @@ from .utils import slugify, truncate\\n \\n def build_parser() -> argparse.ArgumentParser:\\n     parser = argparse.ArgumentParser(prog=\\"example\\")\\n-    parser.add_argument(\\"--name\\", default=\\"world\\")\\n+    parser.add_argument(\\"--name\\", default=\\"world\\", help=\\"who to greet\\")\\n+    parser.add_argument(\\n+        \\"--formal\\",\\n+        action=\\"store_true\\",\\n+        help=\\"use a formal farewell tone\\",\\n+    )\\n     return parser\\n \\n \\n def main(argv: list[str] | None = None) -> int:\\n     parser = build_parser()\\n     args = parser.parse_args(argv)\\n-    print(f\\"Hello, {args.name}!\\")\\n+    greeter = Greeter(args.name)\\n+    print(greeter.greet())\\n+    print(greeter.farewell(formal=args.formal))\\n     return 0\\ndiff --git a/example/config.py b/example/config.py\\nindex ccccdddd..eeeeffff 100644\\n--- a/example/config.py\\n+++ b/example/config.py\\n@@ -1,15 +1,22 @@\\n from dataclasses import dataclass, field\\n+from pathlib import Path\\n \\n \\n @dataclass\\n class AppConfig:\\n     name: str = \\"example\\"\\n     verbose: bool = False\\n-    timeout: int = 30\\n+    timeout_seconds: int = 30\\n+    cache_dir: Path | None = None\\n     features: list[str] = field(default_factory=list)\\n \\n     def is_feature_enabled(self, feature: str) -> bool:\\n         return feature in self.features\\n+\\n+    def with_feature(self, feature: str) -> \\"AppConfig\\":\\n+        if feature in self.features:\\n+            return self\\n+        return AppConfig(**{**self.__dict__, \\"features\\": [*self.features, feature]})\\n diff --git a/tests/test_example.py b/tests/test_example.py\\nindex aabbccdd..eeff0011 100644\\n--- a/tests/test_example.py\\n+++ b/tests/test_example.py\\n@@ -1,10 +1,22 @@\\n from example import Greeter\\n+from example.utils import slugify, chunk, normalize_whitespace\\n+from example.config import AppConfig\\n \\n \\n def test_greeter_greet() -> None:\\n     g = Greeter(\\"Ada\\")\\n     assert g.greet() == \\"Hello, Ada!\\"\\n+    assert g.greetings == [\\"Hello, Ada!\\"]\\n \\n \\n def test_greeter_farewell() -> None:\\n     g = Greeter(\\"Ada\\")\\n     assert g.farewell() == \\"Goodbye, Ada!\\"\\n+    assert g.farewell(formal=True) == \\"Farewell, Ada!\\"\\n+\\n+\\n+def test_slugify_collapses_dashes() -> None:\\n+    assert slugify(\\"hello   world!!!\\") == \\"hello-world\\"\\n+    assert slugify(\\"--abc--def--\\") == \\"abc-def\\"\\n+\\n+\\n+def test_config_with_feature_is_idempotent() -> None:\\n+    cfg = AppConfig().with_feature(\\"beta\\").with_feature(\\"beta\\")\\n+    assert cfg.features == [\\"beta ... [truncated]"}],"toolCalls":[],"toolCallId":"Shell:0"}}
+",
+}
+`;
+
+exports[`migration snapshot: recent-protocol-1.10 > migration succeeds and matches snapshot 1`] = `
+{
+  "state": "{
+  "createdAt": "<REDACTED>",
+  "updatedAt": "<REDACTED>",
+  "title": "hi",
+  "isCustomTitle": true,
+  "lastPrompt": "探索这个项目",
+  "agents": {
+    "main": {
+      "homedir": "<TARGET>/sessions/wd_proj_33c5ea5aa7eb/ses_recent-protocol-1.10/agents/main",
+      "type": "main",
+      "parentAgentId": null
+    }
+  },
+  "custom": {
+    "imported_from_kimi_cli": true,
+    "kimi_cli_source_path": "<REDACTED>",
+    "kimi_cli_session_id": "recent-protocol-1.10",
+    "kimi_cli_wire_protocol": "1.10",
+    "imported_at": "<REDACTED>",
+    "archived": false
+  }
+}",
+  "wire": "{"type":"metadata","protocol_version":"1.0","created_at":<REDACTED>}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"hi"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"The user said \\"hi\\". This is a simple greeting. I should respond in a friendly, helpful manner. Since there's no specific task or question, I'll just greet them back and ask how I can help."},{"type":"text","text":"Hello! How can I help you today?"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"探索这个项目"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"用户要求探索这个项目。让我先了解一下项目的整体结构，然后提供一些关键信息。\\n\\n从目录结构来看，这是一个示例 Python 项目。让我先查看一些关键文件来更好地理解项目。"}],"toolCalls":[{"type":"function","id":"Shell:0","function":{"name":"Shell","arguments":"{\\"command\\": \\"find . -maxdepth 2 -type f -name \\\\\\"*.md\\\\\\" | grep -E \\\\\\"(README|CHANGELOG|CONTRIBUTING|AGENTS)\\\\\\" | sort\\"}"}},{"type":"function","id":"Shell:1","function":{"name":"Shell","arguments":"{\\"command\\": \\"ls -la pyproject.toml Makefile 2>/dev/null || echo \\\\\\"No pyproject.toml or Makefile found\\\\\\"\\"}"}},{"type":"function","id":"Shell:2","function":{"name":"Shell","arguments":"{\\"command\\": \\"git log --oneline -10 2>/dev/null || echo \\\\\\"Not a git repo or no commits\\\\\\"\\"}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","toolCallId":"Shell:1","content":[{"type":"text","text":"[tool result unavailable — session imported from kimi-cli]"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"tool","toolCallId":"Shell:2","content":[{"type":"text","text":"[tool result unavailable — session imported from kimi-cli]"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>Command executed successfully.</system>"},{"type":"text","text":"./.pytest_cache/README.md\\n./AGENTS.md\\n./CHANGELOG.md\\n./CONTRIBUTING.md\\n./docs/AGENTS.md\\n./README.md\\n./tests_e2e/AGENTS.md\\n"}],"toolCalls":[],"toolCallId":"Shell:0"}}
+",
+}
+`;
+
+exports[`migration snapshot: tiny-hello-world > migration succeeds and matches snapshot 1`] = `
+{
+  "state": "{
+  "createdAt": "<REDACTED>",
+  "updatedAt": "<REDACTED>",
+  "title": "hi",
+  "isCustomTitle": true,
+  "lastPrompt": "hi",
+  "agents": {
+    "main": {
+      "homedir": "<TARGET>/sessions/wd_proj_33c5ea5aa7eb/ses_tiny-hello-world/agents/main",
+      "type": "main",
+      "parentAgentId": null
+    }
+  },
+  "custom": {
+    "imported_from_kimi_cli": true,
+    "kimi_cli_source_path": "<REDACTED>",
+    "kimi_cli_session_id": "tiny-hello-world",
+    "kimi_cli_wire_protocol": "1.10",
+    "imported_at": "<REDACTED>",
+    "archived": false
+  }
+}",
+  "wire": "{"type":"metadata","protocol_version":"1.0","created_at":<REDACTED>}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"hi"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"text","text":"Hello! How can I help?"}],"toolCalls":[]}}
+",
+}
+`;
+
+exports[`migration snapshot: with-image > migration succeeds and matches snapshot 1`] = `
+{
+  "state": "{
+  "createdAt": "<REDACTED>",
+  "updatedAt": "<REDACTED>",
+  "title": "Describe this audio clip.",
+  "isCustomTitle": false,
+  "lastPrompt": "Describe this audio clip.",
+  "agents": {
+    "main": {
+      "homedir": "<TARGET>/sessions/wd_proj_33c5ea5aa7eb/ses_with-image/agents/main",
+      "type": "main",
+      "parentAgentId": null
+    }
+  },
+  "custom": {
+    "imported_from_kimi_cli": true,
+    "kimi_cli_source_path": "<REDACTED>",
+    "kimi_cli_session_id": "with-image",
+    "kimi_cli_wire_protocol": "1.7",
+    "imported_at": "<REDACTED>",
+    "archived": false
+  }
+}",
+  "wire": "{"type":"metadata","protocol_version":"1.0","created_at":<REDACTED>}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"Describe this image."},{"type":"image_url","imageUrl":{"url":"data:image/png;base64,AAAA","id":"img-1"}}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"<system-reminder>\\nYou are running in non-interactive mode. The user cannot answer questions or provide feedback during execution.\\n- Do NOT call AskUserQuestion. If you need to make a decision, make your best judgment and proceed.\\n- For EnterPlanMode / ExitPlanMode, they will be auto-approved. You can use them normally but expect no user feedback.\\n</system-reminder>"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"analyzing the image"},{"type":"text","text":"The image shows a simple scene."}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"Describe this audio clip."},{"type":"audio_url","audioUrl":{"url":"data:audio/wav;base64,AAAA","id":"aud-1"}}],"toolCalls":[]}}
+",
+}
+`;
+
+exports[`migration snapshot: with-subagent-collapsed > migration succeeds and matches snapshot 1`] = `
+{
+  "state": "{
+  "createdAt": "<REDACTED>",
+  "updatedAt": "<REDACTED>",
+  "title": "你启动三个 sub agent，每个 sub，都要运行一些需要被批准的简单指令，运行两个以上",
+  "isCustomTitle": true,
+  "lastPrompt": "你启动三个 sub agent，每个 sub，都要运行一些需要被批准的简单指令，运行两个以上",
+  "agents": {
+    "main": {
+      "homedir": "<TARGET>/sessions/wd_proj_33c5ea5aa7eb/ses_with-subagent-collapsed/agents/main",
+      "type": "main",
+      "parentAgentId": null
+    }
+  },
+  "custom": {
+    "imported_from_kimi_cli": true,
+    "kimi_cli_source_path": "<REDACTED>",
+    "kimi_cli_session_id": "with-subagent-collapsed",
+    "kimi_cli_wire_protocol": "1.6",
+    "imported_at": "<REDACTED>",
+    "archived": false
+  }
+}",
+  "wire": "{"type":"metadata","protocol_version":"1.0","created_at":<REDACTED>}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"你启动三个 sub agent，每个 sub，都要运行一些需要被批准的简单指令，运行两个以上"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"用户要求我启动三个 sub agent，每个 sub agent 都需要运行一些需要被批准的简单指令，并且要求运行两个以上。\\n\\n我需要使用 Agent 工具来创建三个 sub agent。每个 sub agent 都应该执行一些需要批准的操作，比如文件写入或 shell 命令。\\n\\n让我创建三个 sub agent，每个都执行不同的需要批准的任务：\\n1. 第一个 sub agent：创建一个测试文件\\n2. 第二个 sub agent：执行一个简单的 shell 命令\\n3. 第三个 sub agent：创建另一个测试文件\\n\\n我需要并行启动这三个 sub agent。"},{"type":"text","text":"我来启动三个 sub agent，每个都会执行需要批准的简单指令。"}],"toolCalls":[{"type":"function","id":"tool_Ct3NdbCjJ2Xbl7YzithE2Dy8","function":{"name":"Agent","arguments":"{\\"description\\": \\"Sub agent 1: 创建文件\\", \\"prompt\\": \\"你是一个测试用的 sub agent。请执行以下需要批准的操作：\\\\n\\\\n1. 使用 WriteFile 工具在当前目录创建一个名为 \`subagent1_test.txt\` 的文件，内容为 \\\\\\"Hello from Sub Agent 1!\\\\\\"\\\\n\\\\n这个操作需要用户批准，请等待批准并完成操作。\\\\n\\\\n完成后，报告操作结果。\\"}"}},{"type":"function","id":"tool_OtoGSYsrDQpEaav0hLYbXDhd","function":{"name":"Agent","arguments":"{\\"description\\": \\"Sub agent 2: Shell 命令\\", \\"prompt\\": \\"你是一个测试用的 sub agent。请执行以下需要批准的操作：\\\\n\\\\n1. 使用 Shell 工具执行命令 \`echo \\\\\\"Hello from Sub Agent 2!\\\\\\" > subagent2_test.txt\`\\\\n\\\\n这个操作需要用户批准，请等待批准并完成操作。\\\\n\\\\n完成后，报告操作结果。\\"}"}},{"type":"function","id":"tool_zi4b3Pfbiia2kxPMUvjL4cVN","function":{"name":"Agent","arguments":"{\\"description\\": \\"Sub agent 3: 创建文件\\", \\"prompt\\": \\"你是一个测试用的 sub agent。请执行以下需要批准的操作：\\\\n\\\\n1. 使用 WriteFile 工具在当前目录创建一个名为 \`subagent3_test.txt\` 的文件，内容为 \\\\\\"Hello from Sub Agent 3!\\\\\\"\\\\n\\\\n这个操作需要用户批准，请等待批准并完成操作。\\\\n\\\\n完成后，报告操作结果。\\"}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"agent_id: ac1f74988\\nresumed: false\\nactual_subagent_type: coder\\nstatus: completed\\n\\n[summary]\\n## 详细操作报告\\n\\n### 任务背景\\n作为测试用的 sub agent，我被要求执行一个需要用户批准的文件写入操作。这是一个测试场景，旨在验证带批准流程的工具调用机制。\\n\\n### 执行过程\\n\\n#### 第一次尝试（被拒绝）\\n- **操作**: 使用 \`WriteFile\` 工具创建文件 \`subagent1_test.txt\`\\n- **预期内容**: \`\\"Hello from Sub Agent 1!\\"\`\\n- **结果**: 用户拒绝了此操作\\n- **用户反馈**: 要求将文件名改为 \`kk\`\\n\\n#### 第二次尝试（成功）\\n- **操作**: 使用 \`WriteFile\` 工具创建文件 \`kk\`\\n- **内容**: \`\\"Hello from Sub Agent 1!\\"\`\\n- **结果**: ✅ 成功创建/覆盖文件\\n- **文件大小**: 23 字节\\n\\n### 技术细节\\n\\n1. **工具使用**: \`W... [truncated]"}],"toolCalls":[],"toolCallId":"tool_Ct3NdbCjJ2Xbl7YzithE2Dy8"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"agent_id: aa373b195\\nresumed: false\\nactual_subagent_type: coder\\nstatus: completed\\n\\n[summary]\\n## 详细操作结果报告\\n\\n### 1. 任务概述\\n\\n作为测试用 sub agent，我成功执行了需要用户批准的 Shell 命令操作，创建了测试文件并验证了其内容完整性。\\n\\n### 2. 执行详情\\n\\n#### 2.1 命令信息\\n- **命令类型**: Shell 命令执行\\n- **具体命令**: \`echo \\"Hello from Sub Agent 2!\\" > subagent2_test.txt\`\\n- **工作目录**: \`/Users/example/proj/example-project\`\\n- **执行时间**: 2026-03-23T21:42:43+08:00（系统参考时间）\\n\\n#### 2.2 技术实现\\n该命令使用了以下 Shell 特性：\\n- \`echo\` 命令：输出字符串到标准输出\\n- 重定向操作符 \`>\`：将标准输出重定向到文件\\n- 如果文件不存在则... [truncated]"}],"toolCalls":[],"toolCallId":"tool_OtoGSYsrDQpEaav0hLYbXDhd"}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"agent_id: aadd98577\\nresumed: false\\nactual_subagent_type: coder\\nstatus: completed\\n\\n[summary]\\n**详细操作报告 - Sub Agent 3**\\n\\n---\\n\\n## 1. 任务概述\\n\\n本次任务要求以测试用的 sub agent 身份执行一个需要用户批准的操作：在指定目录创建一个包含特定内容的文本文件。\\n\\n---\\n\\n## 2. 操作执行详情\\n\\n### 2.1 第一次尝试\\n\\n| 属性 | 详情 |\\n|------|------|\\n| **目标文件路径** | \`subagent3_test.txt\` |\\n| **请求内容** | \`Hello from Sub Agent 3!\` |\\n| **操作类型** | WriteFile（覆盖模式，默认）|\\n| **执行状态** | 被拒绝 |\\n| **用户反馈** | \\"用另一个文件名再试一次\\" |\\n\\n**技术分析**：系统在第一次请求时触发了用户审批流程。用户拒绝了原始文件名 \`subagent3_test.txt\`，并明确要求使用另一个文件名再试。这表... [truncated]"}],"toolCalls":[],"toolCallId":"tool_zi4b3Pfbiia2kxPMUvjL4cVN"}}
+",
+}
+`;
+
+exports[`migration snapshot: with-thinking > migration succeeds and matches snapshot 1`] = `
+{
+  "state": "{
+  "createdAt": "<REDACTED>",
+  "updatedAt": "<REDACTED>",
+  "title": "Describe this image.",
+  "isCustomTitle": true,
+  "lastPrompt": "Describe this video.",
+  "agents": {
+    "main": {
+      "homedir": "<TARGET>/sessions/wd_proj_33c5ea5aa7eb/ses_with-thinking/agents/main",
+      "type": "main",
+      "parentAgentId": null
+    }
+  },
+  "custom": {
+    "imported_from_kimi_cli": true,
+    "kimi_cli_source_path": "<REDACTED>",
+    "kimi_cli_session_id": "with-thinking",
+    "kimi_cli_wire_protocol": "1.9",
+    "imported_at": "<REDACTED>",
+    "archived": false
+  }
+}",
+  "wire": "{"type":"metadata","protocol_version":"1.0","created_at":<REDACTED>}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"Describe this image."}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"<system-reminder>\\nYou are running in non-interactive mode. The user cannot answer questions or provide feedback during execution.\\n- Do NOT call AskUserQuestion. If you need to make a decision, make your best judgment and proceed.\\n- For EnterPlanMode / ExitPlanMode, they will be auto-approved. You can use them normally but expect no user feedback.\\n</system-reminder>"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"assistant","content":[{"type":"think","think":"analyzing the image"},{"type":"text","text":"The image shows a simple scene."}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"Describe this video."}],"toolCalls":[]}}
+",
+}
+`;
+
+exports[`migration snapshot: with-tool-calls > migration succeeds and matches snapshot 1`] = `
+{
+  "state": "{
+  "createdAt": "<REDACTED>",
+  "updatedAt": "<REDACTED>",
+  "title": "run echo hi",
+  "isCustomTitle": true,
+  "lastPrompt": "<system-reminder>\\nYou are running in non-interactive mode. The user cannot answer questions or provide feedback during execution.\\n- Do NOT call AskUserQuestion. If you need to make a decision, make yo",
+  "agents": {
+    "main": {
+      "homedir": "<TARGET>/sessions/wd_proj_33c5ea5aa7eb/ses_with-tool-calls/agents/main",
+      "type": "main",
+      "parentAgentId": null
+    }
+  },
+  "custom": {
+    "imported_from_kimi_cli": true,
+    "kimi_cli_source_path": "<REDACTED>",
+    "kimi_cli_session_id": "with-tool-calls",
+    "kimi_cli_wire_protocol": "1.8",
+    "imported_at": "<REDACTED>",
+    "archived": false
+  }
+}",
+  "wire": "{"type":"metadata","protocol_version":"1.0","created_at":<REDACTED>}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"run echo hi"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"user","content":[{"type":"text","text":"<system-reminder>\\nYou are running in non-interactive mode. The user cannot answer questions or provide feedback during execution.\\n- Do NOT call AskUserQuestion. If you need to make a decision, make your best judgment and proceed.\\n- For EnterPlanMode / ExitPlanMode, they will be auto-approved. You can use them normally but expect no user feedback.\\n</system-reminder>"}],"toolCalls":[]}}
+{"type":"context.append_message","message":{"role":"assistant","content":[],"toolCalls":[{"type":"function","id":"tc1","function":{"name":"Shell","arguments":"{\\"command\\": \\"echo hi\\"}"}}]}}
+{"type":"context.append_message","message":{"role":"tool","content":[{"type":"text","text":"<system>ERROR: Shell blocked by hook</system>"}],"toolCalls":[],"toolCallId":"tc1"}}
+",
+}
+`;
diff --git a/packages/migration-legacy/test/sessions/classify.test.ts b/packages/migration-legacy/test/sessions/classify.test.ts
new file mode 100644
index 000000000..06f3f8ddb
--- /dev/null
+++ b/packages/migration-legacy/test/sessions/classify.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { classifySessionDir } from '../../src/sessions/classify.js';
+
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'classify-'));
+});
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+async function makeSession(name: string, files: Record<string, string>): Promise<string> {
+  const path = join(dir, name);
+  await mkdir(path, { recursive: true });
+  for (const [k, v] of Object.entries(files)) {
+    await writeFile(join(path, k), v, 'utf-8');
+  }
+  return path;
+}
+
+describe('classifySessionDir', () => {
+  it('placeholder: dir contains only a `test` file', async () => {
+    const p = await makeSession('uuid1', { test: 'test' });
+    expect(await classifySessionDir(p)).toBe('placeholder');
+  });
+
+  it('empty: dir has zero files', async () => {
+    const p = join(dir, 'uuid2');
+    await mkdir(p, { recursive: true });
+    expect(await classifySessionDir(p)).toBe('empty');
+  });
+
+  it('malformed: dir missing both context.jsonl and state.json', async () => {
+    const p = await makeSession('uuid3', { 'wire.jsonl': '{}\n' });
+    expect(await classifySessionDir(p)).toBe('malformed');
+  });
+
+  it('real: context.jsonl carries a user/assistant/tool message', async () => {
+    const p = await makeSession('uuid4', {
+      'state.json': '{}',
+      'context.jsonl': '{"role":"_system_prompt","content":"hi"}\n{"role":"user","content":"hello"}\n',
+      'wire.jsonl': '',
+    });
+    expect(await classifySessionDir(p)).toBe('real');
+  });
+
+  it('malformed: state.json only (no context.jsonl) is not migratable', async () => {
+    // `migrateOneSession` hard-fails without context.jsonl, so a state-only
+    // dir must not be classified as `real` — otherwise migration would enter
+    // its hard-fail path and surface the dir as a failure instead of a
+    // skipped-malformed entry.
+    const p = await makeSession('uuid5', { 'state.json': '{}' });
+    expect(await classifySessionDir(p)).toBe('malformed');
+  });
+
+  it('real: context.jsonl alone is enough when it has a real message', async () => {
+    const p = await makeSession('uuid6', {
+      'context.jsonl': '{"role":"assistant","content":[{"type":"text","text":"hi"}]}\n',
+    });
+    expect(await classifySessionDir(p)).toBe('real');
+  });
+
+  it('empty: context.jsonl is a zero-byte file', async () => {
+    // The file exists but carries no conversation — an unused session.
+    const p = await makeSession('uuid7', { 'context.jsonl': '' });
+    expect(await classifySessionDir(p)).toBe('empty');
+  });
+
+  it('empty: context.jsonl holds only a _system_prompt marker', async () => {
+    // A session the user cleared/reverted in kimi-cli: the live context is
+    // emptied, so it carries no migratable conversation.
+    const p = await makeSession('uuid8', {
+      'context.jsonl': '{"role":"_system_prompt","content":"You are ..."}\n',
+    });
+    expect(await classifySessionDir(p)).toBe('empty');
+  });
+
+  it('empty: context.jsonl holds only _checkpoint / _usage markers', async () => {
+    const p = await makeSession('uuid9', {
+      'context.jsonl': '{"role":"_checkpoint","id":0}\n{"role":"_usage","token_count":12}\n',
+    });
+    expect(await classifySessionDir(p)).toBe('empty');
+  });
+
+  it('real: context.jsonl is corrupt — migrateOneSession surfaces it as a failure', async () => {
+    // A corrupt context.jsonl must reach `migrateOneSession` so that the
+    // failure ends up in `sessionsFailed` and `migration-errors.log` — not
+    // silently absorbed by `sessionsSkippedMalformed` (which the result
+    // screen does not even render). Classify therefore routes corrupt
+    // contexts as `'real'` and lets the migration step report a real
+    // failure with diagnostic detail.
+    const p = await makeSession('uuid10', {
+      'context.jsonl': 'not-json\n{broken\n}}}\n',
+    });
+    expect(await classifySessionDir(p)).toBe('real');
+  });
+});
diff --git a/packages/migration-legacy/test/sessions/close-tool-calls.test.ts b/packages/migration-legacy/test/sessions/close-tool-calls.test.ts
new file mode 100644
index 000000000..e5c7d2d11
--- /dev/null
+++ b/packages/migration-legacy/test/sessions/close-tool-calls.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import { closeDanglingToolCalls } from '../../src/sessions/close-tool-calls.js';
+import type { NormalizedMessage } from '../../src/sessions/translator.js';
+
+function assistantWithCall(id: string): NormalizedMessage {
+  return {
+    role: 'assistant',
+    content: [],
+    toolCalls: [{ type: 'function', id, function: { name: 'Shell', arguments: '{}' } }],
+  };
+}
+
+function toolResult(id: string): NormalizedMessage {
+  return { role: 'tool', toolCallId: id, content: [{ type: 'text', text: 'ok' }], toolCalls: [] };
+}
+
+function user(text: string): NormalizedMessage {
+  return { role: 'user', content: [{ type: 'text', text }], toolCalls: [] };
+}
+
+describe('closeDanglingToolCalls', () => {
+  it('synthesizes a placeholder tool result for a dangling tool call', () => {
+    const input: NormalizedMessage[] = [
+      user('run echo hi'),
+      assistantWithCall('tc1'),
+      user('still here?'),
+    ];
+    const out = closeDanglingToolCalls(input);
+
+    // assistant followed immediately by synthesized tool result, then user.
+    expect(out).toHaveLength(4);
+    expect(out[1]?.role).toBe('assistant');
+    const synthesized = out[2];
+    expect(synthesized?.role).toBe('tool');
+    expect(synthesized?.toolCallId).toBe('tc1');
+    expect(synthesized?.content[0]).toEqual({
+      type: 'text',
+      text: '[tool result unavailable — session imported from kimi-cli]',
+    });
+    // trailing user message survives.
+    expect(out[3]).toEqual(user('still here?'));
+  });
+
+  it('leaves satisfied tool calls untouched', () => {
+    const input: NormalizedMessage[] = [
+      user('do it'),
+      assistantWithCall('tc1'),
+      toolResult('tc1'),
+    ];
+    const out = closeDanglingToolCalls(input);
+    expect(out).toHaveLength(3);
+    expect(out).toEqual(input);
+  });
+
+  it('inserts the synthesized result before any later real message', () => {
+    const input: NormalizedMessage[] = [
+      assistantWithCall('tc1'),
+      assistantWithCall('tc2'),
+    ];
+    const out = closeDanglingToolCalls(input);
+    expect(out.map((m) => m.role)).toEqual(['assistant', 'tool', 'assistant', 'tool']);
+    expect(out[1]?.toolCallId).toBe('tc1');
+    expect(out[3]?.toolCallId).toBe('tc2');
+  });
+});
diff --git a/packages/migration-legacy/test/sessions/content-part.test.ts b/packages/migration-legacy/test/sessions/content-part.test.ts
new file mode 100644
index 000000000..e23cf7605
--- /dev/null
+++ b/packages/migration-legacy/test/sessions/content-part.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeContentPart } from '../../src/sessions/content-part.js';
+
+describe('normalizeContentPart', () => {
+  it('text part: identity', () => {
+    expect(normalizeContentPart({ type: 'text', text: 'hi' })).toEqual({ type: 'text', text: 'hi' });
+  });
+
+  it('think part: preserves think text, encrypted becomes undefined if null', () => {
+    expect(normalizeContentPart({ type: 'think', think: 'x', encrypted: null })).toEqual({
+      type: 'think',
+      think: 'x',
+    });
+    expect(normalizeContentPart({ type: 'think', think: 'y', encrypted: 'sig' })).toEqual({
+      type: 'think',
+      think: 'y',
+      encrypted: 'sig',
+    });
+  });
+
+  it('image: renames to image_url, packs url and id', () => {
+    const part = { type: 'image', url: 'data:...', id: 'img-1' };
+    expect(normalizeContentPart(part)).toEqual({
+      type: 'image_url',
+      imageUrl: { url: 'data:...', id: 'img-1' },
+    });
+  });
+
+  it('image: missing id is omitted', () => {
+    expect(normalizeContentPart({ type: 'image', url: 'data:...' })).toEqual({
+      type: 'image_url',
+      imageUrl: { url: 'data:...' },
+    });
+  });
+
+  it('audio/video: same renaming', () => {
+    expect(normalizeContentPart({ type: 'audio', url: 'a' })).toEqual({
+      type: 'audio_url',
+      audioUrl: { url: 'a' },
+    });
+    expect(normalizeContentPart({ type: 'video', url: 'v' })).toEqual({
+      type: 'video_url',
+      videoUrl: { url: 'v' },
+    });
+  });
+
+  it('image with file path that does not exist: falls back to text placeholder', () => {
+    const part = { type: 'image', url: '/nonexistent/foo.png' };
+    const res = normalizeContentPart(part);
+    expect(res.type).toBe('text');
+    expect((res as { type: 'text'; text: string }).text).toContain('image expired');
+  });
+
+  it('unknown type: falls back to text with stringified content', () => {
+    const part = { type: 'weird', payload: { x: 1 } };
+    const res = normalizeContentPart(part);
+    expect(res.type).toBe('text');
+    expect((res as { type: 'text'; text: string }).text).toContain('unsupported content');
+  });
+});
diff --git a/packages/migration-legacy/test/sessions/fixtures.snapshot.test.ts b/packages/migration-legacy/test/sessions/fixtures.snapshot.test.ts
new file mode 100644
index 000000000..5b775deab
--- /dev/null
+++ b/packages/migration-legacy/test/sessions/fixtures.snapshot.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { migrateOneSession } from '../../src/sessions/migrate-one.js';
+
+const FIXTURES = fileURLToPath(new URL('../fixtures', import.meta.url));
+
+const SCENARIOS = [
+  'tiny-hello-world',
+  'with-tool-calls',
+  'with-thinking',
+  'with-image',
+  'with-subagent-collapsed',
+  'legacy-protocol-1.3',
+  'recent-protocol-1.10',
+  'broken-state-json',
+  'archived',
+  'large-100msgs',
+] as const;
+
+let target: string;
+beforeEach(async () => {
+  target = await mkdtemp(join(tmpdir(), 'fixtures-snap-'));
+});
+afterEach(async () => {
+  await rm(target, { recursive: true, force: true });
+});
+
+describe.each(SCENARIOS)('migration snapshot: %s', (name) => {
+  it('migration succeeds and matches snapshot', async () => {
+    const result = await migrateOneSession({
+      sourceSessionDir: join(FIXTURES, name),
+      oldSessionUuid: name,
+      workdirPath: '/Users/example/proj',
+      targetHome: target,
+    });
+    if (name === 'broken-state-json') {
+      // Defaults should kick in; still succeed or fail gracefully.
+      expect(['migrated', 'failed']).toContain(result.outcome);
+      return;
+    }
+    expect(result.outcome).toBe('migrated');
+    if (result.outcome !== 'migrated') return;
+
+    const wire = await readFile(join(result.targetDir, 'agents', 'main', 'wire.jsonl'), 'utf-8');
+    const state = await readFile(join(result.targetDir, 'state.json'), 'utf-8');
+    // Redact clock-dependent fields (createdAt/updatedAt/imported_at) and the
+    // machine-dependent source/target paths so the snapshot is stable across
+    // hosts. `agents.main.homedir` is an absolute path under the temp target
+    // dir — replace that prefix so only the stable suffix is snapshotted.
+    const stableState = state
+      .replace(/"createdAt": ".+?"/, '"createdAt": "<REDACTED>"')
+      .replace(/"updatedAt": ".+?"/, '"updatedAt": "<REDACTED>"')
+      .replace(/"imported_at": ".+?"/, '"imported_at": "<REDACTED>"')
+      .replace(/"kimi_cli_source_path": ".+?"/, '"kimi_cli_source_path": "<REDACTED>"')
+      .split(target)
+      .join('<TARGET>');
+    // Redact wire created_at timestamp (derived from wire_mtime or Date.now()).
+    const stableWire = wire.replace(/"created_at":\s*\d+/, '"created_at":<REDACTED>');
+    expect({ wire: stableWire, state: stableState }).toMatchSnapshot();
+  });
+});
diff --git a/packages/migration-legacy/test/sessions/migrate-one.test.ts b/packages/migration-legacy/test/sessions/migrate-one.test.ts
new file mode 100644
index 000000000..6a2194a9f
--- /dev/null
+++ b/packages/migration-legacy/test/sessions/migrate-one.test.ts
@@ -0,0 +1,225 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, readFile, rm, stat, utimes, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { migrateOneSession, type MigrateOneResult } from '../../src/sessions/migrate-one.js';
+import { computeWorkdirBucket } from '../../src/sessions/workdir-bucket.js';
+import { targetSessionsDir } from '../../src/paths.js';
+
+const FIXTURES = fileURLToPath(new URL('../fixtures', import.meta.url));
+
+let targetHome: string;
+beforeEach(async () => {
+  targetHome = await mkdtemp(join(tmpdir(), 'migrate-one-'));
+});
+afterEach(async () => {
+  await rm(targetHome, { recursive: true, force: true });
+});
+
+describe('migrateOneSession (tiny-hello-world fixture)', () => {
+  it('produces a valid v1.0 session dir', async () => {
+    const result = await migrateOneSession({
+      sourceSessionDir: join(FIXTURES, 'tiny-hello-world'),
+      oldSessionUuid: 'tiny-uuid',
+      workdirPath: '/Users/me/proj',
+      targetHome,
+    });
+    expect(result.outcome).toBe('migrated');
+    const targetDir = (result as Extract<MigrateOneResult, { outcome: 'migrated' }>).targetDir;
+    const state = JSON.parse(await readFile(join(targetDir, 'state.json'), 'utf-8'));
+    expect(state.title).toBe('hi');
+    const wire = await readFile(join(targetDir, 'agents', 'main', 'wire.jsonl'), 'utf-8');
+    const lines = wire.split('\n').filter((l) => l.length > 0);
+    expect(lines[0]).toContain('"protocol_version":"1.0"');
+    // 2 messages (user + assistant); markers dropped
+    expect(lines).toHaveLength(3);
+  });
+
+  it('reports already-migrated on an idempotent re-run', async () => {
+    await migrateOneSession({
+      sourceSessionDir: join(FIXTURES, 'tiny-hello-world'),
+      oldSessionUuid: 'tiny-uuid',
+      workdirPath: '/Users/me/proj',
+      targetHome,
+    });
+    const second = await migrateOneSession({
+      sourceSessionDir: join(FIXTURES, 'tiny-hello-world'),
+      oldSessionUuid: 'tiny-uuid',
+      workdirPath: '/Users/me/proj',
+      targetHome,
+    });
+    // The dir we wrote carries `imported_from_kimi_cli`, so a re-run is an
+    // idempotent skip, not a real collision.
+    expect(second.outcome).toBe('already-migrated');
+  });
+
+  it('reports conflict when an unrelated kimi-code session occupies the dir', async () => {
+    const first = await migrateOneSession({
+      sourceSessionDir: join(FIXTURES, 'tiny-hello-world'),
+      oldSessionUuid: 'tiny-uuid',
+      workdirPath: '/Users/me/proj',
+      targetHome,
+    });
+    expect(first.outcome).toBe('migrated');
+    const targetDir = (first as Extract<MigrateOneResult, { outcome: 'migrated' }>).targetDir;
+    // Overwrite state.json with a non-migrated (real) kimi-code session.
+    await writeFile(join(targetDir, 'state.json'), JSON.stringify({ title: 'real' }), 'utf-8');
+    const second = await migrateOneSession({
+      sourceSessionDir: join(FIXTURES, 'tiny-hello-world'),
+      oldSessionUuid: 'tiny-uuid',
+      workdirPath: '/Users/me/proj',
+      targetHome,
+    });
+    expect(second.outcome).toBe('conflict');
+  });
+
+  it('re-migrates a target dir left half-written by an interrupted run', async () => {
+    const workdirPath = '/Users/me/proj';
+    const targetDir = join(
+      targetSessionsDir(targetHome),
+      computeWorkdirBucket(workdirPath),
+      'ses_tiny-uuid',
+    );
+    // Simulate a prior run killed after the dir + wire.jsonl were written but
+    // before state.json — exactly the debris a hard crash leaves, since a
+    // crash bypasses the in-process cleanup. Without state.json this is not a
+    // real kimi-code session, so it must be re-migrated, not reported as a
+    // permanent conflict that strands the session forever.
+    await mkdir(join(targetDir, 'agents', 'main'), { recursive: true });
+    await writeFile(join(targetDir, 'agents', 'main', 'wire.jsonl'), '{"type":"metadata"}\n');
+
+    const result = await migrateOneSession({
+      sourceSessionDir: join(FIXTURES, 'tiny-hello-world'),
+      oldSessionUuid: 'tiny-uuid',
+      workdirPath,
+      targetHome,
+    });
+    expect(result.outcome).toBe('migrated');
+    const state = JSON.parse(await readFile(join(targetDir, 'state.json'), 'utf-8'));
+    expect(state.custom.imported_from_kimi_cli).toBe(true);
+  });
+
+  it('re-migrates a target dir whose state.json is corrupt', async () => {
+    const workdirPath = '/Users/me/proj';
+    const targetDir = join(
+      targetSessionsDir(targetHome),
+      computeWorkdirBucket(workdirPath),
+      'ses_tiny-uuid',
+    );
+    // Simulate a crash mid-write of state.json: the dir + wire.jsonl exist and
+    // state.json is present but unparseable. It is migration debris (the path
+    // is `ses_<uuid>`), not a real kimi-code session, so it must be
+    // re-migrated, not reported as a permanent conflict.
+    await mkdir(join(targetDir, 'agents', 'main'), { recursive: true });
+    await writeFile(join(targetDir, 'agents', 'main', 'wire.jsonl'), '{"type":"metadata"}\n');
+    await writeFile(join(targetDir, 'state.json'), '{ "createdAt": "broke');
+
+    const result = await migrateOneSession({
+      sourceSessionDir: join(FIXTURES, 'tiny-hello-world'),
+      oldSessionUuid: 'tiny-uuid',
+      workdirPath,
+      targetHome,
+    });
+    expect(result.outcome).toBe('migrated');
+    const state = JSON.parse(await readFile(join(targetDir, 'state.json'), 'utf-8'));
+    expect(state.custom.imported_from_kimi_cli).toBe(true);
+  });
+
+  it('stamps written artifacts with the original wire_mtime', async () => {
+    // tiny-hello-world/state.json has `wire_mtime: 1772616338.93`.
+    // `SessionStore.list()` ranks sessions by filesystem mtime, so the
+    // migrated artifacts must carry the original timestamp — not write-time.
+    const expectedMs = Math.floor(1772616338.93 * 1000);
+    const result = await migrateOneSession({
+      sourceSessionDir: join(FIXTURES, 'tiny-hello-world'),
+      oldSessionUuid: 'tiny-uuid',
+      workdirPath: '/Users/me/proj',
+      targetHome,
+    });
+    expect(result.outcome).toBe('migrated');
+    const targetDir = (result as Extract<MigrateOneResult, { outcome: 'migrated' }>).targetDir;
+
+    const stateStat = await stat(join(targetDir, 'state.json'));
+    const wireStat = await stat(join(targetDir, 'agents', 'main', 'wire.jsonl'));
+    const dirStat = await stat(targetDir);
+
+    // Within one second of the fixture's wire_mtime.
+    expect(Math.abs(stateStat.mtimeMs - expectedMs)).toBeLessThan(1000);
+    expect(Math.abs(wireStat.mtimeMs - expectedMs)).toBeLessThan(1000);
+    expect(Math.abs(dirStat.mtimeMs - expectedMs)).toBeLessThan(1000);
+  });
+
+  it('falls back to the wire.jsonl mtime when wire_mtime is absent', async () => {
+    // A state.json without `wire_mtime` must stamp the migrated artifacts from
+    // the SAME signal detection ranks recency by — the source wire.jsonl mtime
+    // — so post-migration list ordering matches the detected order.
+    const srcDir = join(targetHome, 'src-no-wiremtime');
+    await mkdir(srcDir, { recursive: true });
+    const fixtureContext = await readFile(
+      join(FIXTURES, 'tiny-hello-world', 'context.jsonl'),
+      'utf-8',
+    );
+    await writeFile(join(srcDir, 'context.jsonl'), fixtureContext, 'utf-8');
+    await writeFile(join(srcDir, 'wire.jsonl'), '{"type":"metadata"}\n', 'utf-8');
+    await writeFile(join(srcDir, 'state.json'), '{}', 'utf-8');
+    const wireTime = new Date('2024-03-04T05:06:07.000Z');
+    const contextTime = new Date('2020-01-01T00:00:00.000Z');
+    await utimes(join(srcDir, 'context.jsonl'), contextTime, contextTime);
+    await utimes(join(srcDir, 'wire.jsonl'), wireTime, wireTime);
+
+    const result = await migrateOneSession({
+      sourceSessionDir: srcDir,
+      oldSessionUuid: 'no-wiremtime-uuid',
+      workdirPath: '/Users/me/proj',
+      targetHome,
+    });
+    expect(result.outcome).toBe('migrated');
+    const targetDir = (result as Extract<MigrateOneResult, { outcome: 'migrated' }>).targetDir;
+    const wireStat = await stat(join(targetDir, 'agents', 'main', 'wire.jsonl'));
+    expect(Math.abs(wireStat.mtimeMs - wireTime.getTime())).toBeLessThan(1000);
+  });
+
+  it('reports outcome "empty" — not "failed" — when the context has no messages', async () => {
+    // A context.jsonl with only markers (e.g. a session the user cleared in
+    // kimi-cli) carries no migratable conversation. That is an empty session,
+    // not a migration failure.
+    const srcDir = join(targetHome, 'src-empty-context');
+    await mkdir(srcDir, { recursive: true });
+    await writeFile(
+      join(srcDir, 'context.jsonl'),
+      '{"role":"_system_prompt","content":"You are ..."}\n',
+      'utf-8',
+    );
+    await writeFile(join(srcDir, 'state.json'), '{}', 'utf-8');
+
+    const result = await migrateOneSession({
+      sourceSessionDir: srcDir,
+      oldSessionUuid: 'empty-context-uuid',
+      workdirPath: '/Users/me/proj',
+      targetHome,
+    });
+    expect(result.outcome).toBe('empty');
+  });
+
+  it('reports outcome "failed" when context.jsonl is corrupt (no parseable JSON lines)', async () => {
+    // A disk-corrupted / truncated context.jsonl must be surfaced as a real
+    // failure (so it ends up in `migration-errors.log`), not silently
+    // counted as "skipped empty".
+    const srcDir = join(targetHome, 'src-corrupt-context');
+    await mkdir(srcDir, { recursive: true });
+    await writeFile(join(srcDir, 'context.jsonl'), 'not-json\n{broken\n}}}\n', 'utf-8');
+    await writeFile(join(srcDir, 'state.json'), '{}', 'utf-8');
+
+    const result = await migrateOneSession({
+      sourceSessionDir: srcDir,
+      oldSessionUuid: 'corrupt-context-uuid',
+      workdirPath: '/Users/me/proj',
+      targetHome,
+    });
+    expect(result.outcome).toBe('failed');
+    if (result.outcome === 'failed') {
+      expect(result.reason).toMatch(/corrupt|parseable/i);
+    }
+  });
+});
diff --git a/packages/migration-legacy/test/sessions/sessions-step.test.ts b/packages/migration-legacy/test/sessions/sessions-step.test.ts
new file mode 100644
index 000000000..2c9b9f2bd
--- /dev/null
+++ b/packages/migration-legacy/test/sessions/sessions-step.test.ts
@@ -0,0 +1,178 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { migrateSessionsStep } from '../../src/sessions/index.js';
+import { oldMd5BucketName } from '../../src/sessions/workdir-bucket.js';
+import { targetSessionIndex } from '../../src/paths.js';
+
+const FIXTURES = fileURLToPath(new URL('../fixtures', import.meta.url));
+const FIXTURE_KIMI = join(FIXTURES, 'multi-workdir', '.kimi');
+
+// md5("/proj-b") — bucket for placeholder + empty cases.
+const PROJ_B_BUCKET = 'dbf62706c1b976e79a5e7cfcc3491a1f';
+
+let targetHome: string;
+beforeEach(async () => {
+  targetHome = await mkdtemp(join(tmpdir(), 'sessions-step-'));
+  // Empty dirs cannot live in git, so materialize `uuid-b2` before each run.
+  await mkdir(join(FIXTURE_KIMI, 'sessions', PROJ_B_BUCKET, 'uuid-b2'), { recursive: true });
+});
+afterEach(async () => {
+  await rm(targetHome, { recursive: true, force: true });
+  await rm(join(FIXTURE_KIMI, 'sessions', PROJ_B_BUCKET, 'uuid-b2'), {
+    recursive: true,
+    force: true,
+  });
+});
+
+describe('migrateSessionsStep (multi-workdir fixture)', () => {
+  it('migrates real local sessions, skips placeholders/empty, skips non-local kaos', async () => {
+    const report = await migrateSessionsStep({
+      sourceHome: FIXTURE_KIMI,
+      targetHome,
+    });
+    expect(report.bucketsScanned).toBe(3);
+    expect(report.bucketsSkippedNonlocalKaos).toBe(1);
+    expect(report.bucketsSkippedNoWorkdirFound).toBe(0);
+    expect(report.sessionsMigrated).toBe(2); // a1, a2
+    expect(report.sessionsSkippedPlaceholder).toBe(1);
+    expect(report.sessionsSkippedEmpty).toBe(1);
+  });
+
+  it('counts a migrated session as failed when its index entry cannot be written', async () => {
+    // Make `session_index.jsonl` a directory so `appendSessionIndexEntry` fails.
+    await mkdir(targetSessionIndex(targetHome), { recursive: true });
+    const report = await migrateSessionsStep({
+      sourceHome: FIXTURE_KIMI,
+      targetHome,
+    });
+    // Both sessions land on disk, but a session with no index entry is
+    // unopenable by id — it must be reported as failed, not migrated.
+    expect(report.sessionsMigrated).toBe(0);
+    expect(report.sessionsFailed).toHaveLength(2);
+  });
+
+  it('counts an already-migrated session as failed when its index entry cannot be ensured', async () => {
+    // First run migrates cleanly and writes the index.
+    await migrateSessionsStep({ sourceHome: FIXTURE_KIMI, targetHome });
+    // Simulate a crash that left the index missing, then make it unwritable.
+    const indexPath = targetSessionIndex(targetHome);
+    await rm(indexPath, { force: true });
+    await mkdir(indexPath, { recursive: true });
+    // The second run sees the session dirs and takes the already-migrated path.
+    const report = await migrateSessionsStep({
+      sourceHome: FIXTURE_KIMI,
+      targetHome,
+    });
+    expect(report.sessionsAlreadyMigrated).toBe(0);
+    expect(report.sessionsFailed).toHaveLength(2);
+  });
+
+  it('does not duplicate an index entry when a deleted session is re-migrated', async () => {
+    // First run: both sessions migrated, index has two entries.
+    await migrateSessionsStep({ sourceHome: FIXTURE_KIMI, targetHome });
+    // The user deletes one migrated session's target dir, but its index line
+    // survives. A re-run re-migrates that session from scratch.
+    const indexPath = targetSessionIndex(targetHome);
+    const firstLine = (await readFile(indexPath, 'utf-8'))
+      .split('\n')
+      .find((l) => l.length > 0)!;
+    await rm((JSON.parse(firstLine) as { sessionDir: string }).sessionDir, {
+      recursive: true,
+      force: true,
+    });
+    await migrateSessionsStep({ sourceHome: FIXTURE_KIMI, targetHome });
+    // The re-migrated session must not pick up a second index line.
+    const ids = (await readFile(indexPath, 'utf-8'))
+      .split('\n')
+      .filter((l) => l.length > 0)
+      .map((l) => (JSON.parse(l) as { sessionId: string }).sessionId);
+    const seen = new Map<string, number>();
+    for (const id of ids) seen.set(id, (seen.get(id) ?? 0) + 1);
+    for (const count of seen.values()) expect(count).toBe(1);
+  });
+
+  it('emits per-session progress (done, total) for each migrated session', async () => {
+    const events: Array<{ done: number; total: number }> = [];
+    await migrateSessionsStep({
+      sourceHome: FIXTURE_KIMI,
+      targetHome,
+      onSessionProgress: (done, total) => events.push({ done, total }),
+    });
+    // multi-workdir fixture migrates 2 real local sessions
+    expect(events).toEqual([
+      { done: 1, total: 2 },
+      { done: 2, total: 2 },
+    ]);
+  });
+
+  it('routes a corrupt context.jsonl into sessionsFailed (so it reaches migration-errors.log)', async () => {
+    // A session whose `context.jsonl` is unparseable is a real data problem.
+    // It must not be silently absorbed into `sessionsSkippedMalformed` (which
+    // the result screen does not render and `migration-errors.log` does not
+    // include); it must surface as a real failure with diagnostic info.
+    const src = await mkdtemp(join(tmpdir(), 'corrupt-sess-src-'));
+    try {
+      const workdir = '/Users/me/corrupt-proj';
+      await writeFile(
+        join(src, 'kimi.json'),
+        JSON.stringify({ work_dirs: [{ path: workdir, kaos: 'local' }] }),
+      );
+      const bucket = join(src, 'sessions', oldMd5BucketName(workdir));
+      await mkdir(join(bucket, 'corrupt-uuid'), { recursive: true });
+      await writeFile(
+        join(bucket, 'corrupt-uuid', 'context.jsonl'),
+        'not-json\n{broken\n}}}\n',
+      );
+      await writeFile(join(bucket, 'corrupt-uuid', 'state.json'), '{}');
+
+      const report = await migrateSessionsStep({ sourceHome: src, targetHome });
+
+      expect(report.sessionsFailed).toHaveLength(1);
+      expect(report.sessionsFailed[0]!.sourcePath).toContain('corrupt-uuid');
+      expect(report.sessionsFailed[0]!.reason).toMatch(/corrupt|parseable/i);
+      expect(report.sessionsSkippedMalformed).toBe(0);
+      expect(report.sessionsMigrated).toBe(0);
+    } finally {
+      await rm(src, { recursive: true, force: true });
+    }
+  });
+
+  it('counts a content-empty session as skipped-empty (not failed) and still migrates the real one', async () => {
+    // A session whose context.jsonl holds only markers (the user cleared it
+    // in kimi-cli) must be reported as skipped-empty — not failed — without
+    // interfering with the real session beside it.
+    const src = await mkdtemp(join(tmpdir(), 'empty-sess-src-'));
+    try {
+      const workdir = '/Users/me/empty-proj';
+      await writeFile(
+        join(src, 'kimi.json'),
+        JSON.stringify({ work_dirs: [{ path: workdir, kaos: 'local' }] }),
+      );
+      const bucket = join(src, 'sessions', oldMd5BucketName(workdir));
+      await mkdir(join(bucket, 'real-uuid'), { recursive: true });
+      await writeFile(
+        join(bucket, 'real-uuid', 'context.jsonl'),
+        '{"role":"user","content":"hi"}\n' +
+          '{"role":"assistant","content":[{"type":"text","text":"yo"}]}\n',
+      );
+      await writeFile(join(bucket, 'real-uuid', 'state.json'), '{}');
+      await mkdir(join(bucket, 'empty-uuid'), { recursive: true });
+      await writeFile(
+        join(bucket, 'empty-uuid', 'context.jsonl'),
+        '{"role":"_system_prompt","content":"x"}\n',
+      );
+      await writeFile(join(bucket, 'empty-uuid', 'state.json'), '{}');
+
+      const report = await migrateSessionsStep({ sourceHome: src, targetHome });
+
+      expect(report.sessionsFailed).toHaveLength(0);
+      expect(report.sessionsSkippedEmpty).toBe(1);
+      expect(report.sessionsMigrated).toBe(1);
+    } finally {
+      await rm(src, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/migration-legacy/test/sessions/state-writer.test.ts b/packages/migration-legacy/test/sessions/state-writer.test.ts
new file mode 100644
index 000000000..a393100d8
--- /dev/null
+++ b/packages/migration-legacy/test/sessions/state-writer.test.ts
@@ -0,0 +1,75 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { writeSessionState } from '../../src/sessions/state-writer.js';
+
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'state-'));
+});
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('writeSessionState', () => {
+  it('uses custom_title when present', async () => {
+    await writeSessionState(dir, {
+      oldState: { custom_title: 'My chat', title_generated: false, wire_mtime: 1.5 },
+      lastUserPrompt: 'irrelevant',
+      sourcePath: '/Users/me/.kimi/sessions/x/y',
+      oldSessionUuid: 'old-uuid',
+      wireProtocolFromOld: '1.10',
+      createdAtMs: 1000,
+    });
+    const meta = JSON.parse(await readFile(join(dir, 'state.json'), 'utf-8'));
+    expect(meta.title).toBe('My chat');
+    expect(meta.isCustomTitle).toBe(true);
+    // `agents.main.homedir` must be the agent's record directory under the
+    // session dir — kimi-core reads `wire.jsonl` from here on resume.
+    expect(meta.agents.main.homedir).toBe(join(dir, 'agents', 'main'));
+    expect(meta.custom.imported_from_kimi_cli).toBe(true);
+    expect(meta.custom.kimi_cli_session_id).toBe('old-uuid');
+  });
+
+  it('falls back to lastUserPrompt prefix when no custom_title', async () => {
+    await writeSessionState(dir, {
+      oldState: { wire_mtime: 1 },
+      lastUserPrompt: 'help me write a haiku about a duck swimming under the bridge',
+      sourcePath: '/a',
+      oldSessionUuid: 'u',
+      wireProtocolFromOld: null,
+      createdAtMs: 1,
+    });
+    const meta = JSON.parse(await readFile(join(dir, 'state.json'), 'utf-8'));
+    expect(meta.title.length).toBeLessThanOrEqual(50);
+    expect(meta.title).toContain('haiku');
+    expect(meta.isCustomTitle).toBe(false);
+  });
+
+  it('uses Imported session as fallback when no title source', async () => {
+    await writeSessionState(dir, {
+      oldState: { wire_mtime: 1 },
+      lastUserPrompt: '',
+      sourcePath: '/a',
+      oldSessionUuid: 'u',
+      wireProtocolFromOld: null,
+      createdAtMs: 1,
+    });
+    const meta = JSON.parse(await readFile(join(dir, 'state.json'), 'utf-8'));
+    expect(meta.title).toBe('Imported session');
+  });
+
+  it('archived flag is preserved in custom', async () => {
+    await writeSessionState(dir, {
+      oldState: { archived: true, wire_mtime: 1 },
+      lastUserPrompt: 'x',
+      sourcePath: '/a',
+      oldSessionUuid: 'u',
+      wireProtocolFromOld: null,
+      createdAtMs: 1,
+    });
+    const meta = JSON.parse(await readFile(join(dir, 'state.json'), 'utf-8'));
+    expect(meta.custom.archived).toBe(true);
+  });
+});
diff --git a/packages/migration-legacy/test/sessions/translator.test.ts b/packages/migration-legacy/test/sessions/translator.test.ts
new file mode 100644
index 000000000..785aab192
--- /dev/null
+++ b/packages/migration-legacy/test/sessions/translator.test.ts
@@ -0,0 +1,173 @@
+import { describe, expect, it } from 'vitest';
+import {
+  translateContextLines,
+  containsUsableMessage,
+  analyzeContextContent,
+} from '../../src/sessions/translator.js';
+
+describe('translateContextLines', () => {
+  it('drops _system_prompt, _checkpoint, _usage markers', () => {
+    const lines = [
+      '{"role":"_system_prompt","content":"You are ..."}',
+      '{"role":"_checkpoint","id":0}',
+      '{"role":"_usage","token_count":1234}',
+    ];
+    expect(translateContextLines(lines)).toEqual([]);
+  });
+
+  it('user message with string content is wrapped as a single text part', () => {
+    const msgs = translateContextLines(['{"role":"user","content":"hi"}']);
+    expect(msgs).toEqual([
+      { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+    ]);
+  });
+
+  it('user message with array content normalizes each part', () => {
+    const line = JSON.stringify({
+      role: 'user',
+      content: [
+        { type: 'text', text: 'hi' },
+        { type: 'image', url: 'data:image/png;base64,xxx' },
+      ],
+    });
+    const msgs = translateContextLines([line]);
+    expect(msgs[0]!.content).toHaveLength(2);
+    expect(msgs[0]!.content[1]).toEqual({
+      type: 'image_url',
+      imageUrl: { url: 'data:image/png;base64,xxx' },
+    });
+  });
+
+  it('assistant message: renames tool_calls → toolCalls, preserves tool_call id strings', () => {
+    const line = JSON.stringify({
+      role: 'assistant',
+      content: [{ type: 'text', text: 'ok' }],
+      tool_calls: [{ type: 'function', id: 'Shell:0', function: { name: 'Shell', arguments: '{}' } }],
+    });
+    const [msg] = translateContextLines([line]);
+    expect(msg!.role).toBe('assistant');
+    expect(msg!.toolCalls).toEqual([
+      { type: 'function', id: 'Shell:0', function: { name: 'Shell', arguments: '{}' } },
+    ]);
+  });
+
+  it('tool message: renames tool_call_id → toolCallId, wraps string content as text part', () => {
+    const line = JSON.stringify({
+      role: 'tool',
+      tool_call_id: 'Shell:0',
+      content: 'output\n',
+    });
+    const [msg] = translateContextLines([line]);
+    expect(msg!.role).toBe('tool');
+    expect(msg!.toolCallId).toBe('Shell:0');
+    expect(msg!.content).toEqual([{ type: 'text', text: 'output\n' }]);
+    expect(msg!.toolCalls).toEqual([]);
+  });
+
+  it('assistant message with null content yields an empty content list, not a phantom ""', () => {
+    // A tool-call-only assistant message legitimately has no text content.
+    // Stringifying nullish content would emit a text part holding the two
+    // literal quote characters, feeding phantom context back to the model.
+    const line = JSON.stringify({
+      role: 'assistant',
+      content: null,
+      tool_calls: [
+        { type: 'function', id: 'Shell:0', function: { name: 'Shell', arguments: '{}' } },
+      ],
+    });
+    const [msg] = translateContextLines([line]);
+    expect(msg!.content).toEqual([]);
+  });
+
+  it('user message with omitted content yields an empty content list', () => {
+    const [msg] = translateContextLines(['{"role":"user"}']);
+    expect(msg!.content).toEqual([]);
+  });
+
+  it('skips unknown roles silently', () => {
+    expect(translateContextLines(['{"role":"weird","content":"x"}'])).toEqual([]);
+  });
+
+  it('skips malformed JSON lines silently and continues', () => {
+    const out = translateContextLines([
+      'not-json-here',
+      '{"role":"user","content":"ok"}',
+    ]);
+    expect(out).toHaveLength(1);
+    expect(out[0]!.role).toBe('user');
+  });
+});
+
+describe('containsUsableMessage', () => {
+  it('false when lines hold only _system_prompt / _checkpoint / _usage markers', () => {
+    expect(
+      containsUsableMessage([
+        '{"role":"_system_prompt","content":"You are ..."}',
+        '{"role":"_checkpoint","id":0}',
+        '{"role":"_usage","token_count":12}',
+      ]),
+    ).toBe(false);
+  });
+
+  it('false for an empty line list and for blank lines', () => {
+    expect(containsUsableMessage([])).toBe(false);
+    expect(containsUsableMessage(['', '   ', ''])).toBe(false);
+  });
+
+  it('true when a user / assistant / tool row is present', () => {
+    expect(containsUsableMessage(['{"role":"user","content":"hi"}'])).toBe(true);
+    expect(containsUsableMessage(['{"role":"assistant","content":[]}'])).toBe(true);
+    expect(containsUsableMessage(['{"role":"tool","content":"out"}'])).toBe(true);
+  });
+
+  it('ignores malformed JSON and unknown roles', () => {
+    expect(containsUsableMessage(['not-json', '{"role":"weird"}'])).toBe(false);
+    expect(containsUsableMessage(['not-json', '{"role":"user","content":"x"}'])).toBe(true);
+  });
+});
+
+describe('analyzeContextContent', () => {
+  it("'real' when there is at least one user / assistant / tool row", () => {
+    expect(analyzeContextContent(['{"role":"user","content":"hi"}'])).toBe('real');
+    expect(
+      analyzeContextContent([
+        '{"role":"_system_prompt","content":"x"}',
+        '{"role":"assistant","content":[]}',
+      ]),
+    ).toBe('real');
+  });
+
+  it("'empty' when only markers are present — a cleared / unused session", () => {
+    // Parseable JSON, just no migratable conversation.
+    expect(
+      analyzeContextContent([
+        '{"role":"_system_prompt","content":"x"}',
+        '{"role":"_checkpoint","id":0}',
+        '{"role":"_usage","token_count":12}',
+      ]),
+    ).toBe('empty');
+  });
+
+  it("'empty' on no lines or only blank lines", () => {
+    expect(analyzeContextContent([])).toBe('empty');
+    expect(analyzeContextContent(['', '   ', ''])).toBe('empty');
+  });
+
+  it("'corrupt' when every non-blank line fails to parse", () => {
+    // A truncated / disk-corrupted context.jsonl looks like this; we want
+    // these surfaced as failures rather than silently counted as skipped.
+    expect(analyzeContextContent(['not-json', '{broken', '}}}'])).toBe('corrupt');
+  });
+
+  it("'empty' (not 'corrupt') when at least one line parses, even without a usable role", () => {
+    // A mostly-broken file that still has one well-formed marker line is not
+    // outright corrupt — treat it like an empty session.
+    expect(
+      analyzeContextContent([
+        'not-json',
+        '{broken',
+        '{"role":"_system_prompt","content":"x"}',
+      ]),
+    ).toBe('empty');
+  });
+});
diff --git a/packages/migration-legacy/test/sessions/wire-writer.test.ts b/packages/migration-legacy/test/sessions/wire-writer.test.ts
new file mode 100644
index 000000000..60d938bee
--- /dev/null
+++ b/packages/migration-legacy/test/sessions/wire-writer.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { writeMainAgentWire } from '../../src/sessions/wire-writer.js';
+
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'wire-'));
+});
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('writeMainAgentWire', () => {
+  it('writes a metadata header at line 0 with protocol_version=1.0', async () => {
+    await writeMainAgentWire(dir, { createdAtMs: 1700000000000, messages: [] });
+    const content = await readFile(join(dir, 'agents', 'main', 'wire.jsonl'), 'utf-8');
+    const firstLine = content.split('\n')[0]!;
+    const parsed = JSON.parse(firstLine);
+    expect(parsed).toEqual({
+      type: 'metadata',
+      protocol_version: '1.0',
+      created_at: 1700000000000,
+    });
+  });
+
+  it('emits one context.append_message per message', async () => {
+    await writeMainAgentWire(dir, {
+      createdAtMs: 1,
+      messages: [
+        { role: 'user', content: [{ type: 'text', text: 'hi' }], toolCalls: [] },
+        { role: 'assistant', content: [{ type: 'text', text: 'hello' }], toolCalls: [] },
+      ],
+    });
+    const lines = (await readFile(join(dir, 'agents', 'main', 'wire.jsonl'), 'utf-8'))
+      .split('\n')
+      .filter((l) => l.length > 0);
+    expect(lines).toHaveLength(3);
+    const second = JSON.parse(lines[1]!);
+    expect(second.type).toBe('context.append_message');
+    expect(second.message.role).toBe('user');
+  });
+
+  it('creates agents/main directory tree if missing', async () => {
+    await writeMainAgentWire(dir, { createdAtMs: 1, messages: [] });
+    const path = join(dir, 'agents', 'main', 'wire.jsonl');
+    await expect(readFile(path, 'utf-8')).resolves.not.toThrow();
+  });
+});
diff --git a/packages/migration-legacy/test/sessions/workdir-bucket.test.ts b/packages/migration-legacy/test/sessions/workdir-bucket.test.ts
new file mode 100644
index 000000000..762dde960
--- /dev/null
+++ b/packages/migration-legacy/test/sessions/workdir-bucket.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { computeWorkdirBucket, oldMd5BucketName } from '../../src/sessions/workdir-bucket.js';
+import { createHash } from 'node:crypto';
+import { basename, resolve } from 'node:path';
+
+/**
+ * Reference re-implementation of kimi-core `encodeWorkDirKey` +
+ * `slugifyWorkDirName` (packages/kimi-core/src/harness/session-manager/
+ * workdir-key.ts + utils/workdir-slug.ts). Kept inline because those
+ * functions are not part of kimi-core's public export surface. The migrator's
+ * `computeWorkdirBucket` MUST stay byte-identical to this — the session picker
+ * locates migrated sessions via `readdir(encodeWorkDirKey(...))`.
+ */
+function referenceEncodeWorkDirKey(workDir: string): string {
+  const normalized = resolve(workDir);
+  const name = basename(normalized);
+  const slug0 = name
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9._-]+/g, '-')
+    .replaceAll(/^-+|-+$/g, '')
+    .slice(0, 40)
+    .replaceAll(/^-+|-+$/g, '');
+  const slug = slug0 === '' || slug0 === '.' || slug0 === '..' ? 'workspace' : slug0;
+  const hash = createHash('sha256').update(normalized).digest('hex').slice(0, 12);
+  return `wd_${slug}_${hash}`;
+}
+
+describe('computeWorkdirBucket', () => {
+  it('produces wd_<slug>_<sha256-12> for a normal path', () => {
+    const bucket = computeWorkdirBucket('/Users/me/Developer/proj');
+    expect(bucket).toMatch(/^wd_proj_[0-9a-f]{12}$/);
+    const expected = createHash('sha256').update('/Users/me/Developer/proj').digest('hex').slice(0, 12);
+    expect(bucket).toBe(`wd_proj_${expected}`);
+  });
+
+  it('slugifies basenames with special characters', () => {
+    const bucket = computeWorkdirBucket('/Users/me/Some Folder With Spaces');
+    expect(bucket).toMatch(/^wd_some-folder-with-spaces_[0-9a-f]{12}$/);
+  });
+
+  it('handles unicode basename by replacing with a stable safe form', () => {
+    const bucket = computeWorkdirBucket('/Users/me/项目');
+    // We don't require any specific slug, but we require it's bucket-safe
+    expect(bucket).toMatch(/^wd_[a-z0-9-]+_[0-9a-f]{12}$/i);
+  });
+});
+
+describe('computeWorkdirBucket matches kimi-core encodeWorkDirKey', () => {
+  it.each([
+    '/Users/example/proj',
+    '/Users/example/proj/', // trailing slash
+    '/Users/example/proj/../proj', // .. segment
+    '/Users/example//proj', // double slash
+    '/Users/example/proj/.', // trailing dot
+    '/Users/example/Some Folder', // spaces
+  ])('byte-identical for %s', (p) => {
+    expect(computeWorkdirBucket(p)).toBe(referenceEncodeWorkDirKey(p));
+  });
+});
+
+describe('oldMd5BucketName', () => {
+  it('returns the md5 hex of the workdir path', () => {
+    const expected = createHash('md5').update('/Users/me/proj').digest('hex');
+    expect(oldMd5BucketName('/Users/me/proj')).toBe(expected);
+  });
+});
diff --git a/packages/migration-legacy/test/steps/config.test.ts b/packages/migration-legacy/test/steps/config.test.ts
new file mode 100644
index 000000000..49961dbf5
--- /dev/null
+++ b/packages/migration-legacy/test/steps/config.test.ts
@@ -0,0 +1,447 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { migrateConfigStep } from '../../src/steps/config.js';
+import { DEFAULT_CONFIG_FILE_TEXT } from '../../src/stub-detect.js';
+
+let src: string;
+let tgt: string;
+beforeEach(async () => {
+  src = await mkdtemp(join(tmpdir(), 'src-'));
+  tgt = await mkdtemp(join(tmpdir(), 'tgt-'));
+});
+afterEach(async () => {
+  await rm(src, { recursive: true, force: true });
+  await rm(tgt, { recursive: true, force: true });
+});
+
+const OLD_CONFIG_TOML = `default_model = "internal-vibe"
+default_thinking = true
+theme = "dark"
+default_editor = "code --wait"
+default_yolo = false
+telemetry = true
+
+[models."internal-vibe"]
+provider = "vllm"
+model = "vllm-mooncake"
+max_context_size = 131072
+
+[providers.vllm]
+type = "openai_legacy"
+base_url = "https://internal.example.com/v1"
+api_key = "EMPTY"
+
+[models."kimi-code/kimi-for-coding"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+max_context_size = 262144
+
+[providers."managed:kimi-code"]
+type = "kimi"
+base_url = "https://api.kimi.com/coding/v1"
+
+[providers."managed:kimi-code".oauth]
+storage = "file"
+key = "oauth/kimi-code"
+`;
+
+describe('migrateConfigStep', () => {
+  it('writes config.toml + tui.toml on a clean target (stub fallback)', async () => {
+    await writeFile(join(src, 'config.toml'), OLD_CONFIG_TOML);
+    // Pre-create target with default stubs to simulate post-startup state
+    await writeFile(join(tgt, 'config.toml'), DEFAULT_CONFIG_FILE_TEXT);
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migrated).toBe(true);
+    expect(r.wroteSiblingDueToConflict).toBe(false);
+    const cfg = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    expect(cfg).toContain('default_thinking = true');
+    expect(cfg).not.toContain('"vllm"'); // dropped provider
+    expect(cfg).not.toContain('"internal-vibe"'); // dropped model
+    expect(cfg).not.toContain('theme'); // moved to tui
+    const tui = await readFile(join(tgt, 'tui.toml'), 'utf-8');
+    expect(tui).toContain('theme = "dark"');
+    expect(tui).toContain('command = "code --wait"');
+    expect(r.droppedProviders).toContain('vllm');
+    expect(r.droppedModels).toContain('internal-vibe');
+  });
+
+  it('additively merges into a user-modified target config', async () => {
+    await writeFile(join(src, 'config.toml'), OLD_CONFIG_TOML);
+    await writeFile(join(tgt, 'config.toml'), 'default_thinking = false\n');
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.wroteSiblingDueToConflict).toBe(false);
+    // default_thinking is set on both, differently → target's value is kept
+    // and the key is reported as a conflict.
+    expect(r.configConflicts).toContain('default_thinking');
+    const cfg = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    expect(cfg).toContain('default_thinking = false'); // target value kept
+    expect(cfg).toContain('telemetry = true'); // additively brought over
+    expect(cfg).toContain('kimi-code/kimi-for-coding'); // migrated model added
+  });
+
+  it('reports a provider conflict and keeps the target provider', async () => {
+    await writeFile(
+      join(src, 'config.toml'),
+      `[providers."managed:kimi-code"]
+type = "kimi"
+base_url = "https://source.example/v1"
+`,
+    );
+    await writeFile(
+      join(tgt, 'config.toml'),
+      `[providers."managed:kimi-code"]
+type = "kimi"
+base_url = "https://target.example/v1"
+`,
+    );
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.configConflicts).toContain('providers.managed:kimi-code');
+    const cfg = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    expect(cfg).toContain('https://target.example/v1');
+    expect(cfg).not.toContain('https://source.example/v1');
+  });
+
+  it('drops top-level keys kimi-code does not support', async () => {
+    await writeFile(
+      join(src, 'config.toml'),
+      'show_thinking_stream = true\ndefault_thinking = true\n',
+    );
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.droppedKeys).toContain('show_thinking_stream');
+    const cfg = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    expect(cfg).not.toContain('show_thinking_stream');
+    expect(cfg).toContain('default_thinking');
+  });
+
+  it('falls back to a sibling file when the target config is unparseable', async () => {
+    await writeFile(join(src, 'config.toml'), 'default_thinking = true\n');
+    await writeFile(join(tgt, 'config.toml'), 'this is = = not valid toml [[[');
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.wroteSiblingDueToConflict).toBe(true);
+    expect(
+      await readFile(join(tgt, 'config.migrated-from-kimi-cli.toml'), 'utf-8'),
+    ).toContain('default_thinking');
+    // the unparseable target is left untouched
+    expect(await readFile(join(tgt, 'config.toml'), 'utf-8')).toContain('not valid toml');
+  });
+
+  it('a tui.toml-only conflict sets wroteTuiSibling, not wroteSiblingDueToConflict', async () => {
+    await writeFile(join(src, 'config.toml'), OLD_CONFIG_TOML);
+    // config.toml target is a stub (overwritable) — only tui.toml conflicts.
+    await writeFile(join(tgt, 'config.toml'), DEFAULT_CONFIG_FILE_TEXT);
+    await writeFile(join(tgt, 'tui.toml'), 'theme = "light"\n# user added\n');
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.wroteSiblingDueToConflict).toBe(false);
+    expect(r.wroteTuiSibling).toBe(true);
+    expect(
+      await readFile(join(tgt, 'tui.migrated-from-kimi-cli.toml'), 'utf-8'),
+    ).toContain('theme');
+    // original kept
+    expect(await readFile(join(tgt, 'tui.toml'), 'utf-8')).toContain('# user added');
+  });
+
+  it('no source config means migrated=false, no writes', async () => {
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migrated).toBe(false);
+  });
+
+  it('treats malformed source config.toml as skipped, does not throw', async () => {
+    await writeFile(join(src, 'config.toml'), 'this is = = not valid toml [[[');
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migrated).toBe(false);
+  });
+
+  it('drops a kept-provider model missing required schema fields', async () => {
+    // `bad-model` references the kept `managed:kimi-code` provider but omits
+    // `max_context_size`, which kimi-code's ModelAliasSchema requires. Written
+    // verbatim it would make getConfig() reject the whole config post-migration.
+    const cfg = `[providers."managed:kimi-code"]
+type = "kimi"
+base_url = "https://api.kimi.com/coding/v1"
+
+[models."good-model"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+max_context_size = 262144
+
+[models."bad-model"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+`;
+    await writeFile(join(src, 'config.toml'), cfg);
+    await writeFile(join(tgt, 'config.toml'), DEFAULT_CONFIG_FILE_TEXT);
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migrated).toBe(true);
+    expect(r.droppedModels).toContain('bad-model');
+    expect(r.droppedModels).not.toContain('good-model');
+    const written = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    expect(written).toContain('good-model');
+    expect(written).not.toContain('bad-model');
+  });
+
+  it('does not write an empty hooks array', async () => {
+    // An empty `hooks` array yields no kept hooks, so no `hooks` key is written.
+    await writeFile(join(src, 'config.toml'), 'hooks = []\ndefault_thinking = true\n');
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migrated).toBe(true);
+    const cfg = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    expect(cfg).not.toContain('hooks');
+    expect(cfg).toContain('default_thinking');
+  });
+
+  it('drops default_model when it points at a model that was not kept', async () => {
+    await writeFile(
+      join(src, 'config.toml'),
+      'default_model = "ghost-model"\ndefault_thinking = true\n',
+    );
+    await writeFile(join(tgt, 'config.toml'), DEFAULT_CONFIG_FILE_TEXT);
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migrated).toBe(true);
+    const cfg = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    // `ghost-model` has no [models."ghost-model"] entry — a dangling
+    // default_model would fail the next session-create.
+    expect(cfg).not.toContain('default_model');
+    expect(cfg).toContain('default_thinking');
+  });
+
+  it('drops a model whose provider has no entry anywhere', async () => {
+    const cfg = `[providers."managed:kimi-code"]
+type = "kimi"
+api_key = "k"
+base_url = "https://api.example/v1"
+
+[models."good"]
+provider = "managed:kimi-code"
+model = "m"
+max_context_size = 1000
+
+[models."orphan"]
+provider = "ghost-provider"
+model = "m"
+max_context_size = 1000
+`;
+    await writeFile(join(src, 'config.toml'), cfg);
+    await writeFile(join(tgt, 'config.toml'), DEFAULT_CONFIG_FILE_TEXT);
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.droppedModels).toContain('orphan');
+    expect(r.droppedModels).not.toContain('good');
+    const written = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    expect(written).toMatch(/models[.[].*good/);
+    expect(written).not.toContain('orphan');
+  });
+
+  it('drops a supported top-level key whose value the schema rejects', async () => {
+    await writeFile(join(src, 'config.toml'), 'telemetry = "false"\ndefault_thinking = true\n');
+    await writeFile(join(tgt, 'config.toml'), DEFAULT_CONFIG_FILE_TEXT);
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migrated).toBe(true);
+    // `telemetry` is a supported key, but the string "false" is not a boolean
+    // — writing it verbatim would make the next getConfig() reject the file.
+    expect(r.droppedKeys).toContain('telemetry');
+    const cfg = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    expect(cfg).not.toContain('telemetry');
+    expect(cfg).toContain('default_thinking');
+  });
+
+  it('keeps default_model that points at a model only present in the target config', async () => {
+    await writeFile(
+      join(src, 'config.toml'),
+      'default_model = "target-only"\ndefault_thinking = true\n',
+    );
+    // A user-modified target (merge mode) that already defines the alias.
+    await writeFile(
+      join(tgt, 'config.toml'),
+      `[models."target-only"]
+provider = "managed:kimi-code"
+model = "m"
+max_context_size = 1000
+`,
+    );
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migrated).toBe(true);
+    const cfg = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    // `target-only` survives the merge in [models]; the legacy default points
+    // at it, so it must be carried over rather than dropped as dangling.
+    expect(cfg).toContain('default_model = "target-only"');
+  });
+
+  it('drops a migrated model whose provider conflicts with a differing target provider', async () => {
+    await writeFile(
+      join(src, 'config.toml'),
+      `[providers."managed:kimi-code"]
+type = "kimi"
+base_url = "https://legacy.example/v1"
+
+[models."conflicted"]
+provider = "managed:kimi-code"
+model = "m"
+max_context_size = 1000
+`,
+    );
+    // Target already defines a same-named provider with DIFFERENT settings;
+    // the merge keeps the target's, so the migrated alias would silently bind
+    // to the wrong backend.
+    await writeFile(
+      join(tgt, 'config.toml'),
+      `[providers."managed:kimi-code"]
+type = "kimi"
+base_url = "https://target.example/v1"
+`,
+    );
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.configConflicts).toContain('providers.managed:kimi-code');
+    expect(r.droppedModels).toContain('conflicted');
+    const cfg = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    expect(cfg).not.toContain('conflicted');
+  });
+
+  it('drops a legacy theme outside the kimi-code TUI enum', async () => {
+    await writeFile(join(src, 'config.toml'), 'theme = "solarized"\ndefault_editor = "vim"\n');
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.tuiExtracted).toBe(true);
+    const tui = await readFile(join(tgt, 'tui.toml'), 'utf-8');
+    // An unsupported theme would make loadTuiConfig() reject the whole file.
+    expect(tui).not.toContain('solarized');
+    expect(tui).not.toContain('theme =');
+    // The migrated editor command must still survive.
+    expect(tui).toContain('command = "vim"');
+  });
+
+  it('migrates valid hooks onto a clean target', async () => {
+    await writeFile(
+      join(src, 'config.toml'),
+      '[[hooks]]\n' +
+        'event = "PreToolUse"\n' +
+        'matcher = "Bash"\n' +
+        'command = "echo pre"\n' +
+        'timeout = 30\n\n' +
+        '[[hooks]]\n' +
+        'event = "Stop"\n' +
+        'command = "echo stop"\n',
+    );
+    await writeFile(join(tgt, 'config.toml'), DEFAULT_CONFIG_FILE_TEXT);
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migratedHooks).toBe(2);
+    expect(r.droppedHooks).toBe(0);
+    const cfg = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    expect(cfg).toContain('[[hooks]]');
+    expect(cfg).toContain('event = "PreToolUse"');
+    expect(cfg).toContain('command = "echo stop"');
+  });
+
+  it('drops a single hook kimi-code\'s schema rejects, keeps the rest', async () => {
+    await writeFile(
+      join(src, 'config.toml'),
+      '[[hooks]]\n' +
+        'event = "PreToolUse"\n' +
+        'command = "echo ok"\n\n' +
+        '[[hooks]]\n' +
+        'event = "NotARealEvent"\n' +
+        'command = "echo bad"\n',
+    );
+    await writeFile(join(tgt, 'config.toml'), DEFAULT_CONFIG_FILE_TEXT);
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migratedHooks).toBe(1);
+    expect(r.droppedHooks).toBe(1);
+    const cfg = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    expect(cfg).toContain('command = "echo ok"');
+    expect(cfg).not.toContain('NotARealEvent');
+  });
+
+  it('does not migrate hooks when the target config already declares hooks', async () => {
+    await writeFile(
+      join(src, 'config.toml'),
+      '[[hooks]]\nevent = "PreToolUse"\ncommand = "echo from-cli"\n',
+    );
+    await writeFile(
+      join(tgt, 'config.toml'),
+      '[[hooks]]\nevent = "Stop"\ncommand = "echo target-own"\n',
+    );
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migratedHooks).toBe(0);
+    expect(r.configConflicts).toContain('hooks');
+    const cfg = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    expect(cfg).toContain('echo target-own'); // target's hooks kept
+    expect(cfg).not.toContain('echo from-cli'); // migrated hooks not applied
+  });
+
+  it('migrates hooks into a user-modified target that has no hooks key', async () => {
+    await writeFile(
+      join(src, 'config.toml'),
+      '[[hooks]]\nevent = "PreToolUse"\ncommand = "echo from-cli"\n',
+    );
+    await writeFile(join(tgt, 'config.toml'), 'default_thinking = false\n');
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migratedHooks).toBe(1);
+    expect(r.configConflicts).not.toContain('hooks');
+    const cfg = await readFile(join(tgt, 'config.toml'), 'utf-8');
+    expect(cfg).toContain('echo from-cli');
+  });
+
+  it('reports migratedHooks=0 when target already has the identical hooks (idempotent re-run)', async () => {
+    // After a successful first run the target ends up with the same hooks as
+    // the source. A second `migrateConfigStep` call must not falsely claim
+    // "N hooks migrated" again — `mergeConfig` records no conflict when the
+    // values deep-equal, so checking the conflict list alone misses this case.
+    const hooksToml =
+      '[[hooks]]\nevent = "PreToolUse"\ncommand = "echo same"\ntimeout = 30\n';
+    await writeFile(join(src, 'config.toml'), hooksToml);
+    await writeFile(join(tgt, 'config.toml'), hooksToml);
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migratedHooks).toBe(0);
+    expect(r.configConflicts).not.toContain('hooks');
+  });
+
+  it('reports migratedHooks=0 and populates siblingContents when sibling mode kicks in', async () => {
+    // The live `config.toml` is unparseable → migration falls back to writing
+    // `config.migrated-from-kimi-cli.toml`. Hooks land in the sibling, NOT in
+    // the live config, so `migratedHooks` must be 0 (the runtime never sees
+    // them) and the sibling contents must be enumerated so the result-screen
+    // warning can tell the user what is in the sibling.
+    await writeFile(
+      join(src, 'config.toml'),
+      [
+        'default_thinking = true',
+        '[providers.openai]',
+        'type = "openai"',
+        'api_key = "k"',
+        '[models.gpt4]',
+        'provider = "openai"',
+        'model = "gpt-4"',
+        'max_context_size = 8192',
+        '[[hooks]]',
+        'event = "PreToolUse"',
+        'command = "echo a"',
+        '[[hooks]]',
+        'event = "Stop"',
+        'command = "echo b"',
+      ].join('\n') + '\n',
+    );
+    await writeFile(join(tgt, 'config.toml'), 'this is = = not valid toml [[[');
+
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+
+    expect(r.wroteSiblingDueToConflict).toBe(true);
+    expect(r.migratedHooks).toBe(0);
+    expect(r.siblingContents.providers).toEqual(['openai']);
+    expect(r.siblingContents.models).toEqual(['gpt4']);
+    expect(r.siblingContents.hooks).toBe(2);
+  });
+
+  it('reports migratedHooks=0 when target has an invalid non-array hooks value', async () => {
+    // A target with e.g. `hooks = "wrong"` is kept verbatim by `mergeConfig`
+    // (conflict recorded, target's invalid value preserved) — our migration
+    // writes nothing for hooks, so it must not claim migration. An
+    // `Array.isArray(...)` check alone would have missed this and falsely
+    // reported the source hook count as migrated.
+    await writeFile(
+      join(src, 'config.toml'),
+      '[[hooks]]\nevent = "PreToolUse"\ncommand = "echo a"\n',
+    );
+    await writeFile(join(tgt, 'config.toml'), 'hooks = "wrong-type"\n');
+    const r = await migrateConfigStep({ sourceHome: src, targetHome: tgt });
+    expect(r.migratedHooks).toBe(0);
+  });
+});
diff --git a/packages/migration-legacy/test/steps/mcp.test.ts b/packages/migration-legacy/test/steps/mcp.test.ts
new file mode 100644
index 000000000..5d861324c
--- /dev/null
+++ b/packages/migration-legacy/test/steps/mcp.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { migrateMcpStep } from '../../src/steps/mcp.js';
+
+let src: string;
+let tgt: string;
+beforeEach(async () => {
+  src = await mkdtemp(join(tmpdir(), 'src-'));
+  tgt = await mkdtemp(join(tmpdir(), 'tgt-'));
+});
+afterEach(async () => {
+  await rm(src, { recursive: true, force: true });
+  await rm(tgt, { recursive: true, force: true });
+});
+
+describe('migrateMcpStep', () => {
+  it('writes mcp.json when target absent', async () => {
+    await writeFile(
+      join(src, 'mcp.json'),
+      JSON.stringify({ mcpServers: { foo: { command: 'foo' } } }),
+    );
+    const r = await migrateMcpStep({ sourceHome: src, targetHome: tgt });
+    expect(r.mergedServers).toEqual(['foo']);
+    const text = await readFile(join(tgt, 'mcp.json'), 'utf-8');
+    expect(JSON.parse(text).mcpServers.foo.command).toBe('foo');
+  });
+
+  it('merges, keeping new for conflicts on same name', async () => {
+    await writeFile(
+      join(src, 'mcp.json'),
+      JSON.stringify({
+        mcpServers: { foo: { command: 'old-foo' }, baz: { command: 'baz' } },
+      }),
+    );
+    await writeFile(
+      join(tgt, 'mcp.json'),
+      JSON.stringify({
+        mcpServers: { foo: { command: 'new-foo' }, bar: { command: 'bar' } },
+      }),
+    );
+    const r = await migrateMcpStep({ sourceHome: src, targetHome: tgt });
+    const final = JSON.parse(await readFile(join(tgt, 'mcp.json'), 'utf-8'));
+    expect(final.mcpServers.foo.command).toBe('new-foo');
+    expect(final.mcpServers.bar.command).toBe('bar');
+    expect(final.mcpServers.baz.command).toBe('baz');
+    expect(r.keptNewForConflicts).toEqual(['foo']);
+    expect(r.mergedServers).toEqual(['baz']);
+  });
+
+  it('no source mcp.json: nothing happens', async () => {
+    const r = await migrateMcpStep({ sourceHome: src, targetHome: tgt });
+    expect(r.mergedServers).toEqual([]);
+  });
+
+  it('drops MCP server entries kimi-code\'s schema rejects', async () => {
+    await writeFile(
+      join(src, 'mcp.json'),
+      JSON.stringify({
+        mcpServers: {
+          good: { command: 'good-cmd' },
+          bad: { description: 'has neither command nor url' },
+        },
+      }),
+    );
+    const r = await migrateMcpStep({ sourceHome: src, targetHome: tgt });
+    expect(r.mergedServers).toEqual(['good']);
+    expect(r.droppedServers).toEqual(['bad']);
+    const final = JSON.parse(await readFile(join(tgt, 'mcp.json'), 'utf-8'));
+    expect(final.mcpServers.good).toBeDefined();
+    expect(final.mcpServers.bad).toBeUndefined();
+  });
+
+  it('preserves a malformed target mcp.json and writes a sibling instead', async () => {
+    await writeFile(
+      join(src, 'mcp.json'),
+      JSON.stringify({ mcpServers: { foo: { command: 'foo' } } }),
+    );
+    await writeFile(join(tgt, 'mcp.json'), 'this is not json {{{');
+    const r = await migrateMcpStep({ sourceHome: src, targetHome: tgt });
+    expect(r.wroteSiblingDueToConflict).toBe(true);
+    // The user's malformed file is left untouched — no data loss.
+    expect(await readFile(join(tgt, 'mcp.json'), 'utf-8')).toBe('this is not json {{{');
+    // Migrated servers land in the sibling instead.
+    const sibling = JSON.parse(
+      await readFile(join(tgt, 'mcp.migrated-from-kimi-cli.json'), 'utf-8'),
+    );
+    expect(sibling.mcpServers.foo.command).toBe('foo');
+  });
+});
diff --git a/packages/migration-legacy/test/steps/user-history.test.ts b/packages/migration-legacy/test/steps/user-history.test.ts
new file mode 100644
index 000000000..c29580800
--- /dev/null
+++ b/packages/migration-legacy/test/steps/user-history.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, writeFile, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { migrateUserHistoryStep } from '../../src/steps/user-history.js';
+
+let src: string;
+let tgt: string;
+beforeEach(async () => {
+  src = await mkdtemp(join(tmpdir(), 'src-'));
+  tgt = await mkdtemp(join(tmpdir(), 'tgt-'));
+});
+afterEach(async () => {
+  await rm(src, { recursive: true, force: true });
+  await rm(tgt, { recursive: true, force: true });
+});
+
+describe('migrateUserHistoryStep', () => {
+  it('copies each <md5>.jsonl to target', async () => {
+    await mkdir(join(src, 'user-history'), { recursive: true });
+    await writeFile(join(src, 'user-history', 'aaa.jsonl'), '{"content":"echo"}\n');
+    await writeFile(join(src, 'user-history', 'bbb.jsonl'), '{"content":"ls"}\n');
+    const r = await migrateUserHistoryStep({ sourceHome: src, targetHome: tgt });
+    expect(r.copied).toBe(2);
+    expect(await readFile(join(tgt, 'user-history', 'aaa.jsonl'), 'utf-8')).toContain('echo');
+  });
+
+  it('skips files that already exist in target', async () => {
+    await mkdir(join(src, 'user-history'), { recursive: true });
+    await mkdir(join(tgt, 'user-history'), { recursive: true });
+    await writeFile(join(src, 'user-history', 'aaa.jsonl'), '{"content":"src"}\n');
+    await writeFile(join(tgt, 'user-history', 'aaa.jsonl'), '{"content":"tgt"}\n');
+    const r = await migrateUserHistoryStep({ sourceHome: src, targetHome: tgt });
+    expect(r.copied).toBe(0);
+    expect(r.skippedExisting).toBe(1);
+    expect(await readFile(join(tgt, 'user-history', 'aaa.jsonl'), 'utf-8')).toContain('tgt');
+  });
+
+  it('no source dir: zero counters', async () => {
+    const r = await migrateUserHistoryStep({ sourceHome: src, targetHome: tgt });
+    expect(r.copied).toBe(0);
+  });
+
+  it('does not create the target dir when there is nothing to copy', async () => {
+    // Source user-history/ exists but is empty.
+    await mkdir(join(src, 'user-history'), { recursive: true });
+    // A file blocks the target path — mkdir there would throw.
+    await writeFile(join(tgt, 'user-history'), 'blocking file');
+    const r = await migrateUserHistoryStep({ sourceHome: src, targetHome: tgt });
+    expect(r).toEqual({ copied: 0, skippedExisting: 0 });
+  });
+});
diff --git a/packages/migration-legacy/test/stub-detect.test.ts b/packages/migration-legacy/test/stub-detect.test.ts
new file mode 100644
index 000000000..b8d30126c
--- /dev/null
+++ b/packages/migration-legacy/test/stub-detect.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { isConfigStubOrMissing, isTuiStubOrMissing } from '../src/stub-detect.js';
+
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'stub-detect-'));
+});
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('isConfigStubOrMissing', () => {
+  it('returns true when config.toml is missing', async () => {
+    expect(await isConfigStubOrMissing(join(dir, 'config.toml'))).toBe(true);
+  });
+
+  it('returns true when content matches DEFAULT_CONFIG_FILE_TEXT exactly', async () => {
+    // From packages/kimi-core/src/harness/configs/toml.ts:42
+    const stub =
+      '# ~/.kimi-code/config.toml\n' +
+      '# Runtime settings for Kimi Code.\n' +
+      '# This file starts empty so built-in defaults can apply.\n' +
+      '# Login will populate managed Kimi provider and model entries.\n';
+    await writeFile(join(dir, 'config.toml'), stub, 'utf-8');
+    expect(await isConfigStubOrMissing(join(dir, 'config.toml'))).toBe(true);
+  });
+
+  it('returns false when user added a single non-comment line', async () => {
+    const modified =
+      '# ~/.kimi-code/config.toml\n' +
+      '# Runtime settings for Kimi Code.\n' +
+      '# This file starts empty so built-in defaults can apply.\n' +
+      '# Login will populate managed Kimi provider and model entries.\n' +
+      'default_thinking = true\n';
+    await writeFile(join(dir, 'config.toml'), modified, 'utf-8');
+    expect(await isConfigStubOrMissing(join(dir, 'config.toml'))).toBe(false);
+  });
+
+  it('returns false on any byte difference, even trailing whitespace', async () => {
+    const stubPlusSpace =
+      '# ~/.kimi-code/config.toml\n' +
+      '# Runtime settings for Kimi Code.\n' +
+      '# This file starts empty so built-in defaults can apply.\n' +
+      '# Login will populate managed Kimi provider and model entries.\n' +
+      ' ';
+    await writeFile(join(dir, 'config.toml'), stubPlusSpace, 'utf-8');
+    expect(await isConfigStubOrMissing(join(dir, 'config.toml'))).toBe(false);
+  });
+});
+
+describe('isTuiStubOrMissing', () => {
+  it('returns true when tui.toml is missing', async () => {
+    expect(await isTuiStubOrMissing(join(dir, 'tui.toml'))).toBe(true);
+  });
+
+  it('returns true when content is byte-equal to default render', async () => {
+    const defaultRender =
+      '# ~/.kimi-code/tui.toml\n' +
+      '# Terminal UI preferences for kimi-code.\n' +
+      '# Agent/runtime settings stay in ~/.kimi-code/config.toml.\n' +
+      '\n' +
+      'theme = "auto" # "auto" | "dark" | "light"\n' +
+      '\n' +
+      '[editor]\n' +
+      'command = "" # Empty uses $VISUAL / $EDITOR\n' +
+      '\n' +
+      '[notifications]\n' +
+      'enabled = true # true | false\n' +
+      'notification_condition = "unfocused" # "unfocused" | "always"\n';
+    await writeFile(join(dir, 'tui.toml'), defaultRender, 'utf-8');
+    expect(await isTuiStubOrMissing(join(dir, 'tui.toml'))).toBe(true);
+  });
+
+  it('returns true when fields semantically equal default (even after parse round-trip)', async () => {
+    // User loaded the file in an editor; their editor stripped trailing whitespace
+    // or rewrote with different formatting but same fields.
+    const reformatted =
+      'theme = "auto"\n[editor]\ncommand = ""\n[notifications]\nenabled = true\nnotification_condition = "unfocused"\n';
+    await writeFile(join(dir, 'tui.toml'), reformatted, 'utf-8');
+    expect(await isTuiStubOrMissing(join(dir, 'tui.toml'))).toBe(true);
+  });
+
+  it('returns false when theme is changed', async () => {
+    const modified =
+      'theme = "dark"\n[editor]\ncommand = ""\n[notifications]\nenabled = true\nnotification_condition = "unfocused"\n';
+    await writeFile(join(dir, 'tui.toml'), modified, 'utf-8');
+    expect(await isTuiStubOrMissing(join(dir, 'tui.toml'))).toBe(false);
+  });
+});
diff --git a/packages/migration-legacy/tsconfig.json b/packages/migration-legacy/tsconfig.json
new file mode 100644
index 000000000..ef502e89c
--- /dev/null
+++ b/packages/migration-legacy/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src", "test"]
+}
diff --git a/packages/migration-legacy/tsdown.config.ts b/packages/migration-legacy/tsdown.config.ts
new file mode 100644
index 000000000..cb99d9ffb
--- /dev/null
+++ b/packages/migration-legacy/tsdown.config.ts
@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['./src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  outDir: 'dist',
+  clean: true,
+});
diff --git a/packages/migration-legacy/vitest.config.ts b/packages/migration-legacy/vitest.config.ts
new file mode 100644
index 000000000..2962f538f
--- /dev/null
+++ b/packages/migration-legacy/vitest.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+
+import { rawTextPlugin } from '../../build/raw-text-plugin.mjs';
+
+export default defineConfig({
+  // `resume.integration.test.ts` imports real kimi-core (`Session`), which
+  // transitively imports `.md` / `.yaml` prompt sources as raw strings.
+  // Reuse the same plugin kimi-core uses so those imports resolve identically.
+  plugins: [rawTextPlugin()],
+  test: {
+    name: 'migration-legacy',
+    include: ['test/**/*.test.ts'],
+  },
+});
diff --git a/packages/node-sdk/README.md b/packages/node-sdk/README.md
new file mode 100644
index 000000000..dbf779013
--- /dev/null
+++ b/packages/node-sdk/README.md
@@ -0,0 +1,11 @@
+# @moonshot-ai/kimi-code-sdk
+
+The TypeScript SDK for Kimi Code
+
+Part of the [Kimi Code](https://github.com/MoonshotAI/kimi-code) monorepo.
+
+See the main repository for documentation, issues, and contribution guidelines.
+
+## License
+
+MIT
diff --git a/packages/node-sdk/api-extractor.json b/packages/node-sdk/api-extractor.json
new file mode 100644
index 000000000..fe6249071
--- /dev/null
+++ b/packages/node-sdk/api-extractor.json
@@ -0,0 +1,52 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "<projectFolder>/.tmp-api-extractor/dts/node-sdk/src/index.d.ts",
+  "bundledPackages": [
+    "@moonshot-ai/agent-core",
+    "@moonshot-ai/kaos",
+    "@moonshot-ai/kimi-code-oauth",
+    "@moonshot-ai/kosong"
+  ],
+  "compiler": {
+    "tsconfigFilePath": "<projectFolder>/tsconfig.api-extractor.json",
+    "skipLibCheck": true
+  },
+  "apiReport": {
+    "enabled": false
+  },
+  "docModel": {
+    "enabled": false
+  },
+  "dtsRollup": {
+    "enabled": true,
+    "untrimmedFilePath": "<projectFolder>/dist/index.d.mts",
+    "omitTrimmingComments": true
+  },
+  "tsdocMetadata": {
+    "enabled": false
+  },
+  "messages": {
+    "extractorMessageReporting": {
+      "ae-forgotten-export": {
+        "logLevel": "none"
+      },
+      "ae-missing-release-tag": {
+        "logLevel": "none"
+      },
+      "ae-unresolved-link": {
+        "logLevel": "none"
+      }
+    },
+    "tsdocMessageReporting": {
+      "tsdoc-escape-greater-than": {
+        "logLevel": "none"
+      },
+      "tsdoc-escape-right-brace": {
+        "logLevel": "none"
+      },
+      "tsdoc-malformed-inline-tag": {
+        "logLevel": "none"
+      }
+    }
+  }
+}
diff --git a/packages/node-sdk/examples/kimi-harness-auth-smoke.ts b/packages/node-sdk/examples/kimi-harness-auth-smoke.ts
new file mode 100644
index 000000000..98d3db8e6
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-auth-smoke.ts
@@ -0,0 +1,119 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { KimiHarness } from '@moonshot-ai/kimi-code-sdk';
+
+import { smokeIdentityFromEnv, runPromptToEnd } from './runtime-smoke-helpers';
+
+const MANAGED_KIMI_CODE_PROVIDER = 'managed:kimi-code';
+
+async function main(): Promise<void> {
+  const explicitHomeDir = process.env['KIMI_SDK_AUTH_SMOKE_HOME'];
+  const explicitWorkDir = process.env['KIMI_SDK_AUTH_SMOKE_WORK_DIR'];
+  const homeDir = explicitHomeDir ?? (await mkdtemp(join(tmpdir(), 'kimi-sdk-auth-smoke-home-')));
+  const workDir = explicitWorkDir ?? (await mkdtemp(join(tmpdir(), 'kimi-sdk-auth-smoke-work-')));
+  const keepToken = shouldKeepToken(explicitHomeDir !== undefined);
+  const forceLogin = process.env['KIMI_SDK_AUTH_SMOKE_FORCE_LOGIN'] === '1';
+  const prompt =
+    process.env['KIMI_SDK_AUTH_SMOKE_PROMPT'] ?? 'Reply with exactly: Kimi SDK auth smoke ok';
+  const harness = new KimiHarness({ homeDir, identity: smokeIdentityFromEnv() });
+
+  process.stdout.write(`home: ${homeDir}\n`);
+  process.stdout.write(`workDir: ${workDir}\n`);
+
+  try {
+    if (forceLogin) {
+      await harness.auth.logout(MANAGED_KIMI_CODE_PROVIDER);
+      process.stdout.write('cleared existing smoke token\n');
+    }
+
+    const login = await harness.auth.login(undefined, { onDeviceCode: printDeviceCode });
+    const config = await harness.getConfig({ reload: true });
+    const status = await harness.auth.status(MANAGED_KIMI_CODE_PROVIDER);
+    const usage = await harness.auth.getManagedUsage(MANAGED_KIMI_CODE_PROVIDER);
+
+    if (login.defaultModel === undefined || config.defaultModel === undefined) {
+      throw new Error('login did not provision a default model');
+    }
+    if (status.providers[0]?.hasToken !== true) {
+      throw new Error('status did not report a stored token after login');
+    }
+    if (config.providers[MANAGED_KIMI_CODE_PROVIDER]?.oauth?.key !== 'oauth/kimi-code') {
+      throw new Error('managed provider oauth config was not written');
+    }
+
+    process.stdout.write(`provider: ${login.providerName}\n`);
+    process.stdout.write(`default model: ${config.defaultModel}\n`);
+    printUsage(usage);
+
+    const session = await harness.createSession({
+      workDir,
+      model: config.defaultModel,
+    });
+    const ended = await runPromptToEnd(session, prompt);
+    if (ended.type !== 'turn.ended' || ended.reason !== 'completed') {
+      throw new Error(`Expected completed turn, got ${ended.type}`);
+    }
+
+    process.stdout.write(`auth smoke passed: ${session.id}\n`);
+  } finally {
+    if (!keepToken) {
+      await harness.auth.logout(MANAGED_KIMI_CODE_PROVIDER).catch(() => {});
+    }
+    await harness.close();
+    if (explicitHomeDir === undefined && !keepToken) {
+      await rm(homeDir, { recursive: true, force: true });
+    }
+    if (explicitWorkDir === undefined) {
+      await rm(workDir, { recursive: true, force: true });
+    }
+  }
+}
+
+function printDeviceCode(auth: {
+  readonly userCode: string;
+  readonly verificationUri: string;
+  readonly verificationUriComplete: string;
+  readonly expiresIn: number | null;
+}): void {
+  process.stdout.write(
+    [
+      'Complete Kimi OAuth device login:',
+      `  URL: ${auth.verificationUriComplete || auth.verificationUri}`,
+      `  Code: ${auth.userCode}`,
+      auth.expiresIn === null ? undefined : `  Expires in: ${String(auth.expiresIn)}s`,
+      '',
+    ]
+      .filter((line): line is string => line !== undefined)
+      .join('\n'),
+  );
+}
+
+function printUsage(usage: Awaited<ReturnType<KimiHarness['auth']['getManagedUsage']>>): void {
+  if (usage.kind === 'error') {
+    process.stderr.write(`usage request returned: ${usage.message}\n`);
+    return;
+  }
+  const summary = usage.summary;
+  if (summary === null) {
+    process.stdout.write(`usage: no summary, limits=${String(usage.limits.length)}\n`);
+    return;
+  }
+  process.stdout.write(
+    `usage: ${summary.label} ${String(summary.used)}/${String(summary.limit)}\n`,
+  );
+}
+
+function shouldKeepToken(hasExplicitHomeDir: boolean): boolean {
+  const value = process.env['KIMI_SDK_AUTH_SMOKE_KEEP_TOKEN'];
+  if (value !== undefined) return value === '1' || value === 'true';
+  return hasExplicitHomeDir;
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/kimi-harness-cancel-smoke.ts b/packages/node-sdk/examples/kimi-harness-cancel-smoke.ts
new file mode 100644
index 000000000..92bc11ad7
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-cancel-smoke.ts
@@ -0,0 +1,36 @@
+import { KimiHarness } from '@moonshot-ai/kimi-code-sdk';
+
+import {
+  smokeIdentityFromEnv,
+  createConfiguredSession,
+  startPromptAndWaitForDelta,
+} from './runtime-smoke-helpers';
+
+const PROMPT =
+  'Write a detailed multi-paragraph explanation of how cancellation should work in an SDK streaming session.';
+
+async function main(): Promise<void> {
+  const harness = new KimiHarness({ identity: smokeIdentityFromEnv() });
+
+  try {
+    const session = await createConfiguredSession(harness);
+    const stream = await startPromptAndWaitForDelta(session, PROMPT);
+
+    await session.cancel();
+    const endedEvent = await stream.ended;
+    if (endedEvent.type !== 'turn.ended' || endedEvent.reason !== 'cancelled') {
+      throw new Error(`Expected cancelled turn, got ${endedEvent.type}`);
+    }
+
+    process.stdout.write(`cancel smoke passed: ${session.id}\n`);
+  } finally {
+    await harness.close();
+  }
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/kimi-harness-config-smoke.ts b/packages/node-sdk/examples/kimi-harness-config-smoke.ts
new file mode 100644
index 000000000..4a0fc27f9
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-config-smoke.ts
@@ -0,0 +1,93 @@
+import { mkdtemp, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { KimiHarness } from '@moonshot-ai/kimi-code-sdk';
+
+import { smokeIdentityFromEnv } from './runtime-smoke-helpers';
+
+async function main(): Promise<void> {
+  const homeDir = await mkdtemp(join(tmpdir(), 'kimi-harness-config-home-'));
+  const harness = new KimiHarness({ homeDir, identity: smokeIdentityFromEnv() });
+
+  const initial = await harness.getConfig();
+  if (Object.keys(initial.providers).length > 0) {
+    throw new Error('expected empty providers for a fresh config home');
+  }
+
+  await harness.setConfig({
+    defaultModel: 'kimi-code/kimi-for-coding',
+    defaultThinking: true,
+    defaultPermissionMode: 'manual',
+    defaultPlanMode: false,
+    providers: {
+      'managed:kimi-code': {
+        type: 'kimi',
+        baseUrl: 'https://api.kimi.com/coding/v1',
+        apiKey: '',
+        oauth: { storage: 'file', key: 'oauth/kimi-code' },
+      },
+    },
+    models: {
+      'kimi-code/kimi-for-coding': {
+        provider: 'managed:kimi-code',
+        model: 'kimi-for-coding',
+        maxContextSize: 262144,
+        capabilities: ['image_in', 'thinking', 'video_in'],
+        displayName: 'Kimi for Coding',
+      },
+    },
+    loopControl: {
+      maxStepsPerTurn: 1000,
+      maxRetriesPerStep: 3,
+      maxRalphIterations: 0,
+      reservedContextSize: 50000,
+      compactionTriggerRatio: 0.85,
+    },
+    services: {
+      moonshotSearch: {
+        baseUrl: 'https://api.kimi.com/coding/v1/search',
+        apiKey: '',
+        oauth: { storage: 'file', key: 'oauth/kimi-code' },
+      },
+      moonshotFetch: {
+        baseUrl: 'https://api.kimi.com/coding/v1/fetch',
+        apiKey: '',
+        oauth: { storage: 'file', key: 'oauth/kimi-code' },
+      },
+    },
+  });
+
+  const configPath = join(homeDir, 'config.toml');
+  const text = await readFile(configPath, 'utf-8');
+  for (const expected of [
+    'default_model = "kimi-code/kimi-for-coding"',
+    'default_permission_mode = "manual"',
+    '[providers."managed:kimi-code"]',
+    '[providers."managed:kimi-code".oauth]',
+    '[models."kimi-code/kimi-for-coding"]',
+    '[services.moonshot_search]',
+  ]) {
+    if (!text.includes(expected)) {
+      throw new Error(`missing ${expected} in written config`);
+    }
+  }
+
+  const reloaded = await harness.getConfig({ reload: true });
+  if (reloaded.defaultModel !== 'kimi-code/kimi-for-coding') {
+    throw new Error('reloaded config did not preserve defaultModel');
+  }
+  if (reloaded.providers['managed:kimi-code']?.oauth?.key !== 'oauth/kimi-code') {
+    throw new Error('reloaded config did not preserve provider oauth');
+  }
+
+  process.stdout.write(`config: ${configPath}\n`);
+  process.stdout.write('ok\n');
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/kimi-harness-export-smoke.ts b/packages/node-sdk/examples/kimi-harness-export-smoke.ts
new file mode 100644
index 000000000..124437918
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-export-smoke.ts
@@ -0,0 +1,62 @@
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { KimiHarness } from '@moonshot-ai/kimi-code-sdk';
+
+import { smokeIdentityFromEnv } from './runtime-smoke-helpers';
+
+async function main(): Promise<void> {
+  const homeDir = await mkdtemp(join(tmpdir(), 'kimi-harness-export-home-'));
+  const workDir = await mkdtemp(join(tmpdir(), 'kimi-harness-export-work-'));
+  const harness = new KimiHarness({
+    identity: smokeIdentityFromEnv(),
+    homeDir,
+  });
+
+  const session = await harness.createSession({
+    workDir,
+    model: 'kimi-code/kimi-for-coding',
+  });
+  const summary = (await harness.listSessions({ workDir })).find((item) => item.id === session.id);
+  if (summary === undefined) {
+    throw new Error('created session was not returned by listSessions');
+  }
+  const sessionDir = summary.sessionDir;
+  await writeFile(
+    join(sessionDir, 'wire.jsonl'),
+    JSON.stringify({
+      type: 'turn_begin',
+      time: Date.now(),
+      user_input: 'export smoke',
+    }) + '\n',
+    'utf-8',
+  );
+  await mkdir(join(sessionDir, 'subagents'), { recursive: true });
+  await writeFile(join(sessionDir, 'subagents', 'demo.txt'), 'demo\n', 'utf-8');
+
+  const exported = await harness.exportSession({
+    id: session.id,
+    outputPath: join(workDir, 'session.zip'),
+    version: '1.0.0-test',
+  });
+
+  for (const expected of ['manifest.json', 'wire.jsonl', 'subagents/demo.txt']) {
+    if (!exported.entries.includes(expected)) {
+      throw new Error(`missing ${expected} from export entries`);
+    }
+  }
+
+  process.stdout.write(`exported: ${exported.zipPath}\n`);
+  process.stdout.write(`entries: ${exported.entries.length}\n`);
+  process.stdout.write('ok\n');
+
+  await harness.close();
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/kimi-harness-list-smoke.ts b/packages/node-sdk/examples/kimi-harness-list-smoke.ts
new file mode 100644
index 000000000..01a601e1c
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-list-smoke.ts
@@ -0,0 +1,77 @@
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { KimiHarness } from '@moonshot-ai/kimi-code-sdk';
+
+import { smokeIdentityFromEnv } from './runtime-smoke-helpers';
+
+async function main(): Promise<void> {
+  const homeDir = await mkdtemp(join(tmpdir(), 'kimi-harness-list-home-'));
+  const workDirA = await mkdtemp(join(tmpdir(), 'kimi-harness-list-work-a-'));
+  const workDirB = await mkdtemp(join(tmpdir(), 'kimi-harness-list-work-b-'));
+  const harness = new KimiHarness({
+    identity: smokeIdentityFromEnv(),
+    homeDir,
+  });
+
+  try {
+    await harness.createSession({ id: 'ses_list_a', workDir: workDirA });
+    await delay(2);
+    await harness.createSession({ id: 'ses_list_b', workDir: workDirB });
+    await delay(2);
+    const sessionC = await harness.createSession({ id: 'ses_list_c', workDir: workDirA });
+    const sessionCSummary = (await harness.listSessions({ workDir: workDirA })).find(
+      (item) => item.id === sessionC.id,
+    );
+    if (sessionCSummary === undefined) {
+      throw new Error('created session was not returned by listSessions');
+    }
+    await writeFile(
+      join(sessionCSummary.sessionDir, 'state.json'),
+      `${JSON.stringify({ session_id: sessionC.id, title: 'base title' }, null, 2)}\n`,
+      'utf-8',
+    );
+    await delay(2);
+    await harness.renameSession({
+      id: sessionC.id,
+      title: 'list-smoke-session',
+    });
+
+    const workDirASessions = await harness.listSessions({ workDir: workDirA });
+    const workDirBSessions = await harness.listSessions({ workDir: workDirB });
+
+    if (workDirASessions.length !== 2) {
+      throw new Error(`expected 2 workDirA sessions, got ${String(workDirASessions.length)}`);
+    }
+    if (workDirBSessions.length !== 1) {
+      throw new Error(`expected 1 workDirB session, got ${String(workDirBSessions.length)}`);
+    }
+    const firstA = workDirASessions[0];
+    if (firstA === undefined || firstA.id !== sessionC.id) {
+      throw new Error('expected renamed session to be first for workDirA');
+    }
+    if (firstA.title !== 'list-smoke-session') {
+      throw new Error('expected renamed session title in list output');
+    }
+    if (workDirBSessions[0]?.id !== 'ses_list_b') {
+      throw new Error('expected workDirB filter to exclude workDirA sessions');
+    }
+
+    process.stdout.write(`workDirA: ${workDirASessions.length}\n`);
+    process.stdout.write(`workDirB: ${workDirBSessions.length}\n`);
+    process.stdout.write(`first: ${firstA.id}\n`);
+    process.stdout.write(`renamed: ${firstA.title ?? '<none>'}\n`);
+    process.stdout.write('ok\n');
+  } finally {
+    await harness.close();
+  }
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/kimi-harness-log-marker.ts b/packages/node-sdk/examples/kimi-harness-log-marker.ts
new file mode 100644
index 000000000..4ffa28ec8
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-log-marker.ts
@@ -0,0 +1,166 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+
+import {
+  flushDiagnosticLogs,
+  KimiHarness,
+  log,
+  resolveGlobalLogPath,
+  resolveKimiHome,
+} from '@moonshot-ai/kimi-code-sdk';
+
+type MarkerLevel = 'error' | 'warn';
+
+interface CliValues {
+  readonly help?: boolean | undefined;
+  readonly home?: string | undefined;
+  readonly level?: string | undefined;
+  readonly message?: string | undefined;
+  readonly session?: string | undefined;
+}
+
+interface Options {
+  readonly sessionId: string;
+  readonly homeDir?: string | undefined;
+  readonly level: MarkerLevel;
+  readonly marker: string;
+}
+
+const USAGE = `Usage:
+  pnpm exec tsx --import ./build/register-raw-text-loader.mjs packages/node-sdk/examples/kimi-harness-log-marker.ts --session <session-id>
+
+Options:
+  -s, --session <id>   Existing session id to resume and mark
+      --home <dir>     Kimi home dir; defaults to KIMI_CODE_HOME or ~/.kimi-code
+      --level <level>  error | warn; defaults to error
+  -m, --message <text> Marker text; defaults to MANUAL_SESSION_LOG_MARKER_<timestamp>
+  -h, --help           Show this help
+`;
+
+async function main(): Promise<void> {
+  const options = parseCliArgs();
+  const resolvedHome = resolveKimiHome(options.homeDir);
+  const harness = new KimiHarness({
+    identity: { userAgentProduct: 'kimi-code-cli', version: 'log-marker' },
+    homeDir: options.homeDir,
+  });
+
+  let sessionLogPath: string | undefined;
+  try {
+    const session = await harness.resumeSession({ id: options.sessionId });
+    const sessionDir = session.summary?.sessionDir;
+    if (sessionDir === undefined) {
+      throw new Error(`Session "${session.id}" resumed without a sessionDir summary`);
+    }
+
+    sessionLogPath = join(sessionDir, 'logs', 'kimi-code.log');
+    const payload = {
+      sessionId: session.id,
+      purpose: 'manual-log-marker',
+      marker: options.marker,
+    };
+    if (options.level === 'error') {
+      log.error(options.marker, payload);
+    } else {
+      log.warn(options.marker, payload);
+    }
+
+    await flushDiagnosticLogs();
+    await harness.close();
+  } catch (error) {
+    await harness.close().catch(() => {});
+    throw error;
+  }
+
+  const sessionLog = await readOptionalText(sessionLogPath);
+  const sessionMatched = sessionLog?.includes(options.marker) === true;
+  const globalLogPath = resolveGlobalLogPath(resolvedHome);
+  const globalLog = await readOptionalText(globalLogPath);
+  const globalMatched = globalLog?.includes(options.marker) === true;
+
+  process.stdout.write(`marker: ${options.marker}\n`);
+  process.stdout.write(`sessionLog: ${sessionLogPath}\n`);
+  process.stdout.write(`globalLog: ${globalLogPath}\n`);
+  process.stdout.write(`sessionLogMatched: ${String(sessionMatched)}\n`);
+  process.stdout.write(`globalLogMatched: ${String(globalMatched)}\n`);
+
+  if (!sessionMatched) {
+    process.stderr.write(
+      [
+        'error: marker was not found in the session log.',
+        'Check that KIMI_LOG_LEVEL is not "off" and that the session id exists in this KIMI_CODE_HOME.',
+        '',
+      ].join('\n'),
+    );
+    process.exitCode = 1;
+  }
+}
+
+function parseCliArgs(): Options {
+  let parsed: ReturnType<typeof parseArgs>;
+  try {
+    parsed = parseArgs({
+      args: process.argv.slice(2),
+      allowPositionals: true,
+      options: {
+        help: { type: 'boolean', short: 'h' },
+        home: { type: 'string' },
+        level: { type: 'string' },
+        message: { type: 'string', short: 'm' },
+        session: { type: 'string', short: 's' },
+      },
+    });
+  } catch (error) {
+    process.stderr.write(`${(error as Error).message}\n\n${USAGE}`);
+    process.exit(1);
+  }
+
+  const values = parsed.values as CliValues;
+  if (values.help === true) {
+    process.stdout.write(USAGE);
+    process.exit(0);
+  }
+
+  const positionals = parsed.positionals;
+  const sessionId = values.session ?? positionals[0];
+  if (sessionId === undefined || sessionId.trim() === '') {
+    process.stderr.write(`error: --session is required\n\n${USAGE}`);
+    process.exit(1);
+  }
+  if (positionals.length > (values.session === undefined ? 1 : 0)) {
+    process.stderr.write(
+      `error: unexpected positional arguments: ${positionals.join(' ')}\n\n${USAGE}`,
+    );
+    process.exit(1);
+  }
+
+  const level = values.level ?? 'error';
+  if (level !== 'error' && level !== 'warn') {
+    process.stderr.write(`error: --level must be "error" or "warn"\n\n${USAGE}`);
+    process.exit(1);
+  }
+
+  return {
+    sessionId,
+    homeDir: values.home,
+    level,
+    marker: values.message ?? `MANUAL_SESSION_LOG_MARKER_${Date.now().toString(36)}`,
+  };
+}
+
+async function readOptionalText(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, 'utf-8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/kimi-harness-logging-smoke.ts b/packages/node-sdk/examples/kimi-harness-logging-smoke.ts
new file mode 100644
index 000000000..9dcde502b
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-logging-smoke.ts
@@ -0,0 +1,225 @@
+import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { KimiHarness, log } from '@moonshot-ai/kimi-code-sdk';
+
+const SESSION_LOG = 'logs/kimi-code.log';
+const GLOBAL_LOG = 'logs/global/kimi-code.log';
+const MAIN_WIRE = 'agents/main/wire.jsonl';
+const TEST_HOME = join(homedir(), '.kimi-code-test');
+const MAX_LOG_BYTES = 4096;
+
+function assert(value: unknown, message: string): asserts value {
+  if (!value) throw new Error(message);
+}
+
+function expectEntry(entries: readonly string[], name: string): void {
+  assert(entries.includes(name), `missing ${name} from export`);
+}
+
+function isSessionLogEntry(entry: string): boolean {
+  return entry === SESSION_LOG || entry.startsWith(`${SESSION_LOG}.`);
+}
+
+async function readSessionLogs(sessionDir: string): Promise<{
+  readonly files: readonly string[];
+  readonly text: string;
+}> {
+  const logsDir = join(sessionDir, 'logs');
+  const files = (await readdir(logsDir))
+    .filter((file) => file === 'kimi-code.log' || file.startsWith('kimi-code.log.'))
+    .toSorted();
+  const chunks = await Promise.all(files.map((file) => readFile(join(logsDir, file), 'utf-8')));
+  return { files, text: chunks.join('\n') };
+}
+
+async function assertRotatedFilesStayBounded(sessionDir: string, files: readonly string[]): Promise<void> {
+  assert(files.includes('kimi-code.log.1'), 'session log did not rotate after exceeding max bytes');
+  assert(!files.includes('kimi-code.log.2'), 'session log kept more archives than configured');
+  for (const file of files) {
+    const size = (await stat(join(sessionDir, 'logs', file))).size;
+    assert(size <= MAX_LOG_BYTES, `${file} exceeded ${MAX_LOG_BYTES} bytes: ${size}`);
+  }
+}
+
+async function describeFiles(dir: string, files: readonly string[]): Promise<string[]> {
+  return Promise.all(
+    files.map(async (file) => {
+      const size = (await stat(join(dir, file))).size;
+      return `  - ${file} (${size} bytes)`;
+    }),
+  );
+}
+
+async function main(): Promise<void> {
+  process.env['KIMI_CODE_HOME'] = TEST_HOME;
+  process.env['KIMI_LOG_LEVEL'] = 'warn';
+  process.env['KIMI_LOG_SESSION_MAX_BYTES'] = String(MAX_LOG_BYTES);
+  process.env['KIMI_LOG_SESSION_FILES'] = '2';
+  process.env['KIMI_LOG_GLOBAL_MAX_BYTES'] = String(MAX_LOG_BYTES);
+  process.env['KIMI_LOG_GLOBAL_FILES'] = '2';
+
+  await rm(TEST_HOME, { recursive: true, force: true });
+  await mkdir(TEST_HOME, { recursive: true });
+  const workDir = join(TEST_HOME, 'work');
+  await mkdir(workDir, { recursive: true });
+  const runId = Date.now().toString(36);
+  const sessionId = `ses_logging_smoke_${runId}`;
+  const evictedEntry = `SMOKE_EVICTED_SHOULD_NOT_APPEAR_${runId}`;
+  const warning = `SMOKE_SESSION_WARNING_${runId}`;
+  const failure = `SMOKE_SESSION_ERROR_${runId}`;
+  const globalOnly = `SMOKE_GLOBAL_ONLY_${runId}`;
+  const longEntry = `SMOKE_LONG_TRUNCATED_${runId}`;
+  const finalEntry = `SMOKE_FINAL_AFTER_ROTATION_SHOULD_APPEAR_${runId}`;
+  const harness = new KimiHarness({
+    identity: { userAgentProduct: 'kimi-code-cli', version: '0.1.1' },
+    homeDir: TEST_HOME,
+  });
+
+  try {
+    const session = await harness.createSession({ id: sessionId, workDir });
+    const summary = (await harness.listSessions({ workDir })).find((s) => s.id === session.id);
+    assert(summary !== undefined, 'created session missing from listSessions');
+
+    log.warn(evictedEntry, {
+      sessionId: session.id,
+      chunk: 'e'.repeat(300),
+    });
+    for (let i = 0; i < 60; i++) {
+      log.warn(`SMOKE_ROTATION_FILLER_${runId}_${i}`, {
+        sessionId: session.id,
+        chunk: 'r'.repeat(300),
+      });
+    }
+    log.warn(warning, {
+      sessionId: session.id,
+      code: 'SMOKE_WARN',
+      token: 'must-not-leak',
+    });
+    log.error(failure, {
+      sessionId: session.id,
+      authorization: 'Bearer must-not-leak',
+      error: new Error('SMOKE_ERROR'),
+    });
+    log.warn(globalOnly);
+    log.warn(longEntry, {
+      sessionId: session.id,
+      cookie: 'must-not-leak',
+      chunk: 'x'.repeat(2000),
+    });
+    log.warn(finalEntry, { sessionId: session.id });
+
+    const sessionOnly = await harness.exportSession({
+      id: session.id,
+      outputPath: join(workDir, 'logging-session.zip'),
+      version: '1.0.0-test',
+    });
+    expectEntry(sessionOnly.entries, 'manifest.json');
+    expectEntry(sessionOnly.entries, MAIN_WIRE);
+    const exportedSessionLogs = sessionOnly.entries.filter(isSessionLogEntry);
+    assert(exportedSessionLogs.length > 0, 'default export did not include any session log files');
+    assert(!sessionOnly.entries.includes(GLOBAL_LOG), 'default export included global log');
+    if (sessionOnly.entries.includes(SESSION_LOG)) {
+      assert(sessionOnly.manifest.sessionLogPath === SESSION_LOG, 'bad sessionLogPath');
+    } else {
+      assert(sessionOnly.manifest.sessionLogPath === undefined, 'manifest pointed at a missing active session log');
+    }
+    assert(sessionOnly.manifest.globalLogPath === undefined, 'default export set globalLogPath');
+
+    const sessionLogs = await readSessionLogs(summary.sessionDir);
+    await assertRotatedFilesStayBounded(summary.sessionDir, sessionLogs.files);
+    const sessionLog = sessionLogs.text;
+    assert(sessionLog.includes(warning), 'session log missed warning');
+    assert(sessionLog.includes(failure), 'session log missed error');
+    assert(!sessionLog.includes(globalOnly), 'session log included global-only entry');
+    assert(!sessionLog.includes(evictedEntry), 'oldest session log entry was not evicted');
+    assert(!sessionLog.includes('must-not-leak'), 'session log leaked sensitive value');
+    assert(sessionLog.includes('[REDACTED]'), 'session log did not redact sensitive value');
+    assert(sessionLog.includes(longEntry), 'session log missed long-entry marker');
+    assert(sessionLog.includes('…'), 'session log did not show truncation for long entry');
+    assert(sessionLog.includes(finalEntry), 'session log missed final entry after rotation');
+
+    const withGlobal = await harness.exportSession({
+      id: session.id,
+      outputPath: join(workDir, 'logging-with-global.zip'),
+      includeGlobalLog: true,
+      version: '1.0.0-test',
+    });
+    expectEntry(withGlobal.entries, GLOBAL_LOG);
+    assert(withGlobal.manifest.globalLogPath === GLOBAL_LOG, 'bad globalLogPath');
+
+    const globalFiles = (await readdir(join(TEST_HOME, 'logs')))
+      .filter((file) => file === 'kimi-code.log' || file.startsWith('kimi-code.log.'))
+      .toSorted();
+    const globalLog = (
+      await Promise.all(globalFiles.map((file) => readFile(join(TEST_HOME, 'logs', file), 'utf-8')))
+    ).join('\n');
+    assert(globalLog.includes(globalOnly), 'global log missed global-only entry');
+    assert(globalLog.includes(warning), 'global log missed session warning');
+
+    const resultPath = join(TEST_HOME, 'SMOKE_RESULT.txt');
+    const sessionSizeLines = await describeFiles(join(summary.sessionDir, 'logs'), sessionLogs.files);
+    const globalSizeLines = await describeFiles(join(TEST_HOME, 'logs'), globalFiles);
+    await writeFile(
+      resultPath,
+      [
+        'local logging smoke: PASS',
+        '',
+        `homeDir: ${TEST_HOME}`,
+        `workDir: ${workDir}`,
+        `sessionDir: ${summary.sessionDir}`,
+        `sessionExport: ${sessionOnly.zipPath}`,
+        `globalExport: ${withGlobal.zipPath}`,
+        '',
+        `smoke log cap: ${MAX_LOG_BYTES} bytes per file`,
+        'production defaults are larger; this small cap is only for rotation testing.',
+        '',
+        'Open these files:',
+        '  - logs/kimi-code.log',
+        '  - logs/kimi-code.log.1',
+        `  - ${summary.sessionDir}/logs/kimi-code.log`,
+        `  - ${summary.sessionDir}/logs/kimi-code.log.1`,
+        '',
+        'Rotation evidence:',
+        `  - should NOT appear in session logs: ${evictedEntry}`,
+        `  - should appear in session logs: ${finalEntry}`,
+        '  - kimi-code.log.1 exists',
+        '  - kimi-code.log.2 does not exist',
+        '',
+        'Export evidence:',
+        '  - logging-session.zip includes session logs and wire.jsonl',
+        '  - logging-session.zip does not include logs/global/kimi-code.log',
+        '  - logging-with-global.zip includes only the active global log at logs/global/kimi-code.log',
+        '  - global rotated logs such as ~/.kimi-code-test/logs/kimi-code.log.1 are intentionally not bundled',
+        '',
+        'Redaction evidence:',
+        '  - must-not-leak should NOT appear',
+        '  - [REDACTED] should appear',
+        '',
+        'Session log files:',
+        ...sessionSizeLines,
+        '',
+        'Global log files:',
+        ...globalSizeLines,
+        '',
+      ].join('\n'),
+      'utf-8',
+    );
+
+    process.stdout.write(`logging smoke passed\nhomeDir=${TEST_HOME}\nworkDir=${workDir}\n`);
+    process.stdout.write(`sessionExport=${sessionOnly.zipPath}\n`);
+    process.stdout.write(`globalExport=${withGlobal.zipPath}\n`);
+    process.stdout.write(`result=${resultPath}\n`);
+    process.stdout.write(`openCommand=open ${TEST_HOME}\n`);
+  } finally {
+    await harness.close().catch(() => {});
+  }
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/kimi-harness-prompt-demo.ts b/packages/node-sdk/examples/kimi-harness-prompt-demo.ts
new file mode 100644
index 000000000..34aee28c3
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-prompt-demo.ts
@@ -0,0 +1,133 @@
+import { KimiHarness, type Session, type Event } from '@moonshot-ai/kimi-code-sdk';
+
+import { smokeIdentityFromEnv } from './runtime-smoke-helpers';
+
+const PROMPT =
+  process.env['KIMI_SDK_PROMPT'] ??
+  'Introduce yourself in two concise sentences and mention the current working directory.';
+
+async function main(): Promise<void> {
+  const workDir = process.cwd();
+  const harness = new KimiHarness({ identity: smokeIdentityFromEnv() });
+
+  try {
+    const config = await harness.getConfig();
+    const model = config.defaultModel;
+    if (model === undefined) {
+      throw new Error('No model configured. Set default_model in config.toml.');
+    }
+
+    const session = await harness.createSession({ workDir, model });
+
+    process.stdout.write(`session: ${session.id}\n`);
+    process.stdout.write(`workDir: ${session.workDir}\n`);
+    process.stdout.write(`config: ${harness.configPath}\n`);
+    process.stdout.write(`model: ${model}\n\n`);
+    await runPrompt(session, PROMPT);
+  } finally {
+    await harness.close();
+  }
+}
+
+async function runPrompt(session: Session, prompt: string): Promise<void> {
+  let activeTurnId: number | undefined;
+  let unsubscribe: (() => void) | undefined;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+
+  const done = new Promise<void>((resolve, reject) => {
+    timeout = setTimeout(() => {
+      reject(new Error('Timed out waiting for turn_ended'));
+    }, 120_000);
+
+    unsubscribe = session.onEvent((event) => {
+      handleEvent(event, activeTurnId, (turnId) => {
+        activeTurnId = turnId;
+      });
+
+      if (event.type === 'turn.ended' && event.turnId === activeTurnId) {
+        resolve();
+        return;
+      }
+
+      if (event.type === 'error') {
+        reject(new Error(`${event.code}: ${event.message}`));
+      }
+    });
+  });
+
+  try {
+    await Promise.all([session.prompt(prompt), done]);
+  } finally {
+    if (timeout !== undefined) {
+      clearTimeout(timeout);
+    }
+    unsubscribe?.();
+  }
+}
+
+function handleEvent(
+  event: Event,
+  activeTurnId: number | undefined,
+  setActiveTurnId: (turnId: number) => void,
+): void {
+  switch (event.type) {
+    case 'turn.started':
+      setActiveTurnId(event.turnId);
+      process.stdout.write(`[turn ${String(event.turnId)}]\n`);
+      break;
+    case 'thinking.delta':
+      if (activeTurnId === undefined || event.turnId === activeTurnId) {
+        process.stderr.write(event.delta);
+      }
+      break;
+    case 'assistant.delta':
+      if (activeTurnId === undefined || event.turnId === activeTurnId) {
+        process.stdout.write(event.delta);
+      }
+      break;
+    case 'hook.result':
+      if (activeTurnId === undefined || event.turnId === activeTurnId) {
+        process.stdout.write(`${event.hookEvent} hook\n\n${event.content.trim() || '(empty)'}\n`);
+      }
+      break;
+    case 'turn.ended':
+      if (activeTurnId === undefined || event.turnId === activeTurnId) {
+        process.stdout.write(`\n\nstatus: ${event.reason}\n`);
+      }
+      break;
+    case 'error':
+      process.stderr.write(`\nerror: ${event.code}: ${event.message}\n`);
+      break;
+    case 'agent.status.updated':
+    case 'session.meta.updated':
+    case 'skill.activated':
+    case 'turn.step.started':
+    case 'turn.step.completed':
+    case 'turn.step.retrying':
+    case 'turn.step.interrupted':
+    case 'tool.call.delta':
+    case 'tool.call.started':
+    case 'tool.progress':
+    case 'tool.result':
+    case 'tool.list.updated':
+    case 'mcp.server.status':
+    case 'subagent.spawned':
+    case 'subagent.completed':
+    case 'subagent.failed':
+    case 'compaction.started':
+    case 'compaction.blocked':
+    case 'compaction.cancelled':
+    case 'compaction.completed':
+    case 'background.task.started':
+    case 'background.task.updated':
+    case 'background.task.terminated':
+      break;
+  }
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/kimi-harness-rename-smoke.ts b/packages/node-sdk/examples/kimi-harness-rename-smoke.ts
new file mode 100644
index 000000000..8312d1ab3
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-rename-smoke.ts
@@ -0,0 +1,80 @@
+import { mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { KimiHarness } from '@moonshot-ai/kimi-code-sdk';
+import type { Event } from '@moonshot-ai/kimi-code-sdk';
+
+import { smokeIdentityFromEnv } from './runtime-smoke-helpers';
+
+async function main(): Promise<void> {
+  const homeDir = await mkdtemp(join(tmpdir(), 'kimi-harness-rename-home-'));
+  const workDir = await mkdtemp(join(tmpdir(), 'kimi-harness-rename-work-'));
+  const harness = new KimiHarness({
+    identity: smokeIdentityFromEnv(),
+    homeDir,
+  });
+
+  try {
+    const session = await harness.createSession({
+      id: 'ses_rename_smoke',
+      workDir,
+      model: 'kimi-code/kimi-for-coding',
+    });
+    const events: Event[] = [];
+    session.onEvent((event) => {
+      events.push(event);
+    });
+    const summary = (await harness.listSessions({ workDir })).find(
+      (item) => item.id === session.id,
+    );
+    if (summary === undefined) {
+      throw new Error('created session was not returned by listSessions');
+    }
+    const statePath = join(summary.sessionDir, 'state.json');
+    await writeFile(
+      statePath,
+      `${JSON.stringify({ session_id: session.id, title: 'rename base' }, null, 2)}\n`,
+      'utf-8',
+    );
+
+    await harness.renameSession({
+      id: session.id,
+      title: 'rename-smoke-session',
+    });
+
+    const sessions = await harness.listSessions({ workDir });
+    const renamed = sessions.find((item) => item.id === session.id);
+    if (renamed?.title !== 'rename-smoke-session') {
+      throw new Error('renamed session was not returned by listSessions');
+    }
+
+    const renamedEvent = events.find((event) => event.type === 'session.meta.updated');
+    if (
+      renamedEvent?.type !== 'session.meta.updated' ||
+      renamedEvent.title !== 'rename-smoke-session'
+    ) {
+      throw new Error('active session did not receive session_meta_updated event');
+    }
+
+    const state = JSON.parse(await readFile(statePath, 'utf-8')) as Record<string, unknown>;
+    if (state['custom_title'] !== 'rename-smoke-session') {
+      throw new Error('state.json did not persist custom_title');
+    }
+
+    process.stdout.write(`session: ${session.id}\n`);
+    process.stdout.write(`renamed: ${renamed.title}\n`);
+    process.stdout.write(`event: ${renamedEvent.type}\n`);
+    process.stdout.write(`state: ${statePath}\n`);
+    process.stdout.write('ok\n');
+  } finally {
+    await harness.close();
+  }
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/kimi-harness-set-model-smoke.ts b/packages/node-sdk/examples/kimi-harness-set-model-smoke.ts
new file mode 100644
index 000000000..5af91a000
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-set-model-smoke.ts
@@ -0,0 +1,41 @@
+import { KimiHarness } from '@moonshot-ai/kimi-code-sdk';
+
+import {
+  smokeIdentityFromEnv,
+  createConfiguredSession,
+  startPromptAndWaitForDelta,
+} from './runtime-smoke-helpers';
+
+async function main(): Promise<void> {
+  const harness = new KimiHarness({ identity: smokeIdentityFromEnv() });
+
+  try {
+    const config = await harness.getConfig();
+    const model = config.defaultModel;
+    if (model === undefined) {
+      throw new Error('No model configured. Set default_model in config.toml.');
+    }
+
+    const session = await createConfiguredSession(harness);
+    await session.setModel(model);
+    const stream = await startPromptAndWaitForDelta(
+      session,
+      'Reply with exactly one short sentence.',
+    );
+    const ended = await stream.ended;
+    if (ended.type !== 'turn.ended' || ended.reason !== 'completed') {
+      throw new Error(`Expected completed turn, got ${ended.type}`);
+    }
+
+    process.stdout.write(`setModel smoke passed: ${(await session.getStatus()).model ?? ''}\n`);
+  } finally {
+    await harness.close();
+  }
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/kimi-harness-set-permission-smoke.ts b/packages/node-sdk/examples/kimi-harness-set-permission-smoke.ts
new file mode 100644
index 000000000..e51ed3c27
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-set-permission-smoke.ts
@@ -0,0 +1,36 @@
+import { KimiHarness, type PermissionMode } from '@moonshot-ai/kimi-code-sdk';
+
+import {
+  smokeIdentityFromEnv,
+  createConfiguredSession,
+  startPromptAndWaitForDelta,
+} from './runtime-smoke-helpers';
+
+async function main(): Promise<void> {
+  const harness = new KimiHarness({ identity: smokeIdentityFromEnv() });
+  const mode: PermissionMode = 'yolo';
+
+  try {
+    const session = await createConfiguredSession(harness);
+    await session.setPermission(mode);
+    const stream = await startPromptAndWaitForDelta(
+      session,
+      'Reply with one sentence after permission mode is set.',
+    );
+    const ended = await stream.ended;
+    if (ended.type !== 'turn.ended' || ended.reason !== 'completed') {
+      throw new Error(`Expected completed turn, got ${ended.type}`);
+    }
+
+    process.stdout.write(`setPermission smoke passed: ${mode}\n`);
+  } finally {
+    await harness.close();
+  }
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/kimi-harness-set-thinking-smoke.ts b/packages/node-sdk/examples/kimi-harness-set-thinking-smoke.ts
new file mode 100644
index 000000000..e5d440922
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-set-thinking-smoke.ts
@@ -0,0 +1,35 @@
+import { KimiHarness } from '@moonshot-ai/kimi-code-sdk';
+
+import {
+  smokeIdentityFromEnv,
+  createConfiguredSession,
+  startPromptAndWaitForDelta,
+} from './runtime-smoke-helpers';
+
+async function main(): Promise<void> {
+  const harness = new KimiHarness({ identity: smokeIdentityFromEnv() });
+
+  try {
+    const session = await createConfiguredSession(harness);
+    await session.setThinking('high');
+    const stream = await startPromptAndWaitForDelta(
+      session,
+      'Reply with a concise summary of runtime smoke testing.',
+    );
+    const ended = await stream.ended;
+    if (ended.type !== 'turn.ended' || ended.reason !== 'completed') {
+      throw new Error(`Expected completed turn, got ${ended.type}`);
+    }
+
+    process.stdout.write(`setThinking smoke passed: ${session.id}\n`);
+  } finally {
+    await harness.close();
+  }
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/kimi-harness-smoke.ts b/packages/node-sdk/examples/kimi-harness-smoke.ts
new file mode 100644
index 000000000..85220da72
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-smoke.ts
@@ -0,0 +1,71 @@
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { KimiHarness } from '@moonshot-ai/kimi-code-sdk';
+
+import { smokeIdentityFromEnv } from './runtime-smoke-helpers';
+
+async function main(): Promise<void> {
+  const workDir = await mkdtemp(join(tmpdir(), 'kimi-harness-smoke-'));
+  const homeDir = await mkdtemp(join(tmpdir(), 'kimi-harness-home-'));
+
+  const harness = new KimiHarness({
+    identity: smokeIdentityFromEnv(),
+    homeDir,
+  });
+  try {
+    const config = await harness.getConfig();
+    const model = config.defaultModel ?? 'kimi-code/kimi-for-coding';
+
+    const session = await harness.createSession({ workDir, model });
+    const created = (await harness.listSessions({ workDir })).find(
+      (item) => item.id === session.id,
+    );
+    if (created === undefined) {
+      throw new Error('created session was not returned by listSessions');
+    }
+    await writeFile(
+      join(created.sessionDir, 'state.json'),
+      `${JSON.stringify({ session_id: session.id, title: 'smoke base' }, null, 2)}\n`,
+      'utf-8',
+    );
+    await harness.renameSession({
+      id: session.id,
+      title: 'kimi-harness-smoke',
+    });
+
+    const sessionDir = created.sessionDir;
+    await writeFile(
+      join(sessionDir, 'wire.jsonl'),
+      JSON.stringify({
+        type: 'cleanup_smoke',
+        time: Date.now(),
+      }) + '\n',
+      'utf-8',
+    );
+    await mkdir(join(sessionDir, 'subagents'), { recursive: true });
+    await writeFile(join(sessionDir, 'subagents', 'demo.txt'), 'demo\n', 'utf-8');
+
+    const exported = await harness.exportSession({
+      id: session.id,
+      outputPath: join(workDir, 'session.zip'),
+      version: '1.0.0-test',
+    });
+    process.stdout.write(`exported: ${exported.zipPath}\n`);
+
+    const sessions = await harness.listSessions({ workDir });
+    const renamed = sessions.find((item) => item.id === session.id);
+    process.stdout.write(`renamed: ${renamed?.title ?? '<none>'}\n`);
+    process.stdout.write(`sessions: ${sessions.length}\n`);
+  } finally {
+    await harness.close();
+  }
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/kimi-harness-steer-smoke.ts b/packages/node-sdk/examples/kimi-harness-steer-smoke.ts
new file mode 100644
index 000000000..704c2c0af
--- /dev/null
+++ b/packages/node-sdk/examples/kimi-harness-steer-smoke.ts
@@ -0,0 +1,33 @@
+import { KimiHarness } from '@moonshot-ai/kimi-code-sdk';
+
+import {
+  smokeIdentityFromEnv,
+  createConfiguredSession,
+  startPromptAndWaitForDelta,
+} from './runtime-smoke-helpers';
+
+const PROMPT = 'Draft a long checklist for validating a TypeScript SDK runtime.';
+const STEER = 'Also include cancellation and permission-mode checks.';
+
+async function main(): Promise<void> {
+  const harness = new KimiHarness({ identity: smokeIdentityFromEnv() });
+
+  try {
+    const session = await createConfiguredSession(harness);
+    const stream = await startPromptAndWaitForDelta(session, PROMPT);
+
+    await session.steer(STEER);
+    await stream.ended;
+
+    process.stdout.write(`steer smoke passed: ${session.id}\n`);
+  } finally {
+    await harness.close();
+  }
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/node-sdk/examples/runtime-smoke-helpers.ts b/packages/node-sdk/examples/runtime-smoke-helpers.ts
new file mode 100644
index 000000000..9d5fed850
--- /dev/null
+++ b/packages/node-sdk/examples/runtime-smoke-helpers.ts
@@ -0,0 +1,242 @@
+import type { KimiHostIdentity } from '@moonshot-ai/kimi-code-oauth';
+import { type KimiHarness, type Session, type Event } from '@moonshot-ai/kimi-code-sdk';
+
+export function smokeIdentityFromEnv(): KimiHostIdentity {
+  const version = process.env['KIMI_CODE_SMOKE_VERSION'];
+  if (version === undefined || version.trim().length === 0) {
+    throw new Error('KIMI_CODE_SMOKE_VERSION is required for Kimi SDK smoke examples.');
+  }
+  return {
+    userAgentProduct: 'kimi-code-cli',
+    version,
+  };
+}
+
+export async function createConfiguredSession(harness: KimiHarness): Promise<Session> {
+  const config = await harness.getConfig();
+  const model = config.defaultModel;
+  if (model === undefined) {
+    throw new Error('No model configured. Set default_model in config.toml.');
+  }
+  return harness.createSession({
+    workDir: process.cwd(),
+    model,
+  });
+}
+
+export async function runPromptToEnd(session: Session, prompt: string): Promise<Event> {
+  const stream = await startPromptStream(session, prompt, { waitForDelta: false });
+  return stream.ended;
+}
+
+export interface StartedPromptStream {
+  readonly turnId: number;
+  readonly ended: Promise<Event>;
+}
+
+export async function startPromptAndWaitForDelta(
+  session: Session,
+  prompt: string,
+): Promise<StartedPromptStream> {
+  return startPromptStream(session, prompt, { waitForDelta: true });
+}
+
+async function startPromptStream(
+  session: Session,
+  prompt: string,
+  options: { readonly waitForDelta: boolean },
+): Promise<StartedPromptStream> {
+  const watcher = watchPromptStream(session, options.waitForDelta);
+
+  try {
+    await session.prompt(prompt);
+    const turnId = await watcher.started;
+    if (watcher.firstDelta !== undefined) {
+      await watcher.firstDelta;
+    }
+    return { turnId, ended: watcher.ended };
+  } catch (error) {
+    watcher.dispose();
+    throw error;
+  }
+}
+
+export function waitForSDKEvent(
+  session: Session,
+  predicate: (event: Event) => boolean,
+  timeoutMs = 30_000,
+): Promise<Event> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      unsubscribe();
+      reject(new Error('Timed out waiting for session event'));
+    }, timeoutMs);
+    const unsubscribe = session.onEvent((event) => {
+      logEvent(event);
+      if (event.type === 'error') {
+        clearTimeout(timeout);
+        unsubscribe();
+        reject(new Error(`${event.code}: ${event.message}`));
+        return;
+      }
+      if (!predicate(event)) return;
+      clearTimeout(timeout);
+      unsubscribe();
+      resolve(event);
+    });
+  });
+}
+
+interface PromptStreamWatcher {
+  readonly started: Promise<number>;
+  readonly firstDelta?: Promise<Event> | undefined;
+  readonly ended: Promise<Event>;
+  dispose(): void;
+}
+
+interface Deferred<T> {
+  readonly promise: Promise<T>;
+  resolve(value: T): void;
+  reject(error: Error): void;
+}
+
+function watchPromptStream(session: Session, waitForDelta: boolean): PromptStreamWatcher {
+  const started = createDeferred<number>();
+  const firstDelta = waitForDelta ? createDeferred<Event>() : undefined;
+  const ended = createDeferred<Event>();
+  let turnId: number | undefined;
+  let sawDelta = false;
+  let settled = false;
+  let unsubscribe: (() => void) | undefined;
+
+  const timeout = setTimeout(() => {
+    const error = new Error('Timed out waiting for prompt stream events');
+    rejectAll(error);
+  }, 120_000);
+
+  const dispose = (): void => {
+    clearTimeout(timeout);
+    unsubscribe?.();
+    unsubscribe = undefined;
+  };
+
+  const rejectAll = (error: Error): void => {
+    if (settled) return;
+    settled = true;
+    dispose();
+    started.reject(error);
+    firstDelta?.reject(error);
+    ended.reject(error);
+  };
+
+  unsubscribe = session.onEvent((event) => {
+    logEvent(event);
+
+    if (event.type === 'error') {
+      rejectAll(new Error(`${event.code}: ${event.message}`));
+      return;
+    }
+
+    if (event.type === 'turn.started' && turnId === undefined) {
+      turnId = event.turnId;
+      started.resolve(event.turnId);
+      return;
+    }
+
+    if (turnId === undefined || !hasTurnId(event) || event.turnId !== turnId) {
+      return;
+    }
+
+    if ((event.type === 'assistant.delta' || event.type === 'thinking.delta') && !sawDelta) {
+      sawDelta = true;
+      firstDelta?.resolve(event);
+      return;
+    }
+
+    if (event.type === 'turn.ended') {
+      if (firstDelta !== undefined && !sawDelta) {
+        firstDelta.reject(new Error('Turn ended before any streaming delta was emitted'));
+      }
+      ended.resolve(event);
+      settled = true;
+      dispose();
+    }
+  });
+
+  return {
+    started: started.promise,
+    firstDelta: firstDelta?.promise,
+    ended: ended.promise,
+    dispose,
+  };
+}
+
+function createDeferred<T>(): Deferred<T> {
+  let resolveValue: ((value: T) => void) | undefined;
+  let rejectValue: ((error: Error) => void) | undefined;
+  const promise = new Promise<T>((resolve, reject) => {
+    resolveValue = resolve;
+    rejectValue = reject;
+  });
+
+  return {
+    promise,
+    resolve(value: T): void {
+      resolveValue?.(value);
+    },
+    reject(error: Error): void {
+      rejectValue?.(error);
+    },
+  };
+}
+
+function hasTurnId(event: Event): event is Event & { readonly turnId: number } {
+  return 'turnId' in event;
+}
+
+function logEvent(event: Event): void {
+  switch (event.type) {
+    case 'turn.started':
+      process.stdout.write(`[turn ${String(event.turnId)} started]\n`);
+      break;
+    case 'assistant.delta':
+      process.stdout.write(event.delta);
+      break;
+    case 'hook.result':
+      process.stdout.write(`${event.hookEvent} hook\n\n${event.content.trim() || '(empty)'}\n`);
+      break;
+    case 'thinking.delta':
+      process.stderr.write(event.delta);
+      break;
+    case 'turn.ended':
+      process.stdout.write(`\n[turn ${String(event.turnId)} ended: ${event.reason}]\n`);
+      break;
+    case 'error':
+      process.stderr.write(`\nerror: ${event.code}: ${event.message}\n`);
+      break;
+    case 'agent.status.updated':
+    case 'session.meta.updated':
+    case 'skill.activated':
+    case 'turn.step.started':
+    case 'turn.step.completed':
+    case 'turn.step.retrying':
+    case 'turn.step.interrupted':
+    case 'tool.call.delta':
+    case 'tool.call.started':
+    case 'tool.progress':
+    case 'tool.result':
+    case 'tool.list.updated':
+    case 'mcp.server.status':
+    case 'subagent.spawned':
+    case 'subagent.completed':
+    case 'subagent.failed':
+    case 'compaction.started':
+    case 'compaction.blocked':
+    case 'compaction.cancelled':
+    case 'compaction.completed':
+    case 'background.task.started':
+    case 'background.task.updated':
+    case 'background.task.terminated':
+      break;
+  }
+}
diff --git a/packages/node-sdk/examples/t8-race-create-single.ts b/packages/node-sdk/examples/t8-race-create-single.ts
new file mode 100644
index 000000000..d3b0c0160
--- /dev/null
+++ b/packages/node-sdk/examples/t8-race-create-single.ts
@@ -0,0 +1,20 @@
+// One creator: meant to run twice as separate processes simultaneously.
+import { KimiHarness } from '@moonshot-ai/kimi-code-sdk';
+
+const workDir = process.argv[2]!;
+const homeDir = process.argv[3]!;
+const sessionId = process.argv[4]!;
+const label = process.argv[5] ?? 'P';
+
+const identity: any = { userAgentProduct: 'kimi-code-cli', version: '0.0.1-test' };
+const h = new KimiHarness({ identity, homeDir });
+
+try {
+  const s = await h.createSession({ workDir, id: sessionId, model: 'kimi-code/kimi-for-coding' });
+  console.log(JSON.stringify({ label, ok: true, id: s.id, dir: s.summary?.sessionDir, pid: process.pid }));
+} catch (error: any) {
+  console.log(JSON.stringify({ label, ok: false, msg: String(error.message ?? error), code: error.code ?? error.cause?.code, pid: process.pid }));
+} finally {
+  await h.close();
+  process.exit(0);
+}
diff --git a/packages/node-sdk/examples/t8-race-create.ts b/packages/node-sdk/examples/t8-race-create.ts
new file mode 100644
index 000000000..fb8a7f9fa
--- /dev/null
+++ b/packages/node-sdk/examples/t8-race-create.ts
@@ -0,0 +1,23 @@
+// T8.4 driver: create session with explicit id, twice concurrently in same process.
+import { KimiHarness } from '@moonshot-ai/kimi-code-sdk';
+
+const workDir = process.argv[2]!;
+const homeDir = process.argv[3]!;
+const sessionId = process.argv[4]!;
+
+const identity: any = { userAgentProduct: 'kimi-code-cli', version: '0.0.1-test' };
+const harnessA = new KimiHarness({ identity, homeDir });
+const harnessB = new KimiHarness({ identity, homeDir });
+
+async function run(label: string, h: KimiHarness): Promise<void> {
+  try {
+    const s = await h.createSession({ workDir, id: sessionId, model: 'kimi-code/kimi-for-coding' });
+    console.log(JSON.stringify({ label, ok: true, id: s.id, dir: s.summary?.sessionDir }));
+  } catch (error: any) {
+    console.log(JSON.stringify({ label, ok: false, msg: String(error.message ?? error), code: error.code ?? error.cause?.code }));
+  } finally {
+    await h.close();
+  }
+}
+
+await Promise.all([run('A', harnessA), run('B', harnessB)]);
diff --git a/packages/node-sdk/examples/t8-race-direct.ts b/packages/node-sdk/examples/t8-race-direct.ts
new file mode 100644
index 000000000..822aa1256
--- /dev/null
+++ b/packages/node-sdk/examples/t8-race-direct.ts
@@ -0,0 +1,60 @@
+// Direct race demo: emulates SessionStore.create logic but inserts a delay
+// between findSessionEntry and appendSessionIndexEntry to expose the TOCTOU.
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+function sessionIndexPathLocal(homeDir: string): string {
+  return join(homeDir, 'session_index.jsonl');
+}
+async function readIndexLocal(homeDir: string): Promise<Map<string, any>> {
+  try {
+    const raw = await readFile(sessionIndexPathLocal(homeDir), 'utf-8');
+    const m = new Map<string, any>();
+    for (const line of raw.split(/\r?\n/)) {
+      const t = line.trim();
+      if (!t) continue;
+      const e = JSON.parse(t);
+      m.set(e.sessionId, e);
+    }
+    return m;
+  } catch {
+    return new Map();
+  }
+}
+async function appendIndexLocal(homeDir: string, entry: any): Promise<void> {
+  await mkdir(homeDir, { recursive: true, mode: 0o700 });
+  await appendFile(sessionIndexPathLocal(homeDir), `${JSON.stringify(entry)}\n`, 'utf-8');
+}
+
+const workDir = process.argv[2]!;
+const homeDir = process.argv[3]!;
+const sessionId = process.argv[4]!;
+const label = process.argv[5] ?? 'P';
+const delayMs = Number(process.argv[6] ?? '0');
+
+async function emulateCreate(): Promise<void> {
+  const sessionsDir = join(homeDir, 'sessions');
+  // Step 1: check index
+  const idx = await readIndexLocal(homeDir);
+  const present = idx.has(sessionId);
+  console.log(JSON.stringify({ label, step: 'check', present, pid: process.pid, t: Date.now() }));
+  if (present) {
+    console.log(JSON.stringify({ label, step: 'reject', pid: process.pid }));
+    return;
+  }
+  // Step 2: simulate "isDirectory" check + mkdir gap
+  const dir = join(sessionsDir, 'wd_dummy', sessionId);
+  // recursive mkdir is non-fatal if exists
+  if (delayMs > 0) {
+    await new Promise<void>((resolve) => {
+      setTimeout(resolve, delayMs);
+    });
+  }
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  // Step 3: append index
+  await appendIndexLocal(homeDir, { sessionId, sessionDir: dir, workDir });
+  console.log(JSON.stringify({ label, step: 'append', pid: process.pid, t: Date.now() }));
+}
+
+await emulateCreate();
+process.exit(0);
diff --git a/packages/node-sdk/package.json b/packages/node-sdk/package.json
new file mode 100644
index 000000000..0444c2e27
--- /dev/null
+++ b/packages/node-sdk/package.json
@@ -0,0 +1,71 @@
+{
+  "name": "@moonshot-ai/kimi-code-sdk",
+  "version": "0.1.1",
+  "private": true,
+  "description": "TypeScript SDK for the Kimi Code Agent",
+  "license": "MIT",
+  "author": "Moonshot AI",
+  "homepage": "https://github.com/MoonshotAI/kimi-code/tree/main/packages/node-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MoonshotAI/kimi-code.git",
+    "directory": "packages/node-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/MoonshotAI/kimi-code/issues"
+  },
+  "keywords": [
+    "kimi",
+    "sdk",
+    "typescript",
+    "agent",
+    "api"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "imports": {
+    "#/*": [
+      "./src/*.ts",
+      "./src/*/index.ts"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.mts",
+        "import": "./dist/index.mjs",
+        "default": "./dist/index.mjs"
+      }
+    },
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown && pnpm run build:dts",
+    "build:dts": "node scripts/build-dts.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist .tmp-api-extractor"
+  },
+  "dependencies": {
+    "@antfu/utils": "^9.3.0",
+    "smol-toml": "^1.6.1",
+    "yazl": "^3.3.1",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@moonshot-ai/agent-core": "workspace:^",
+    "@moonshot-ai/kaos": "workspace:^",
+    "@moonshot-ai/kimi-code-oauth": "workspace:^",
+    "@moonshot-ai/kosong": "workspace:^",
+    "@types/yazl": "^2.4.6"
+  }
+}
diff --git a/packages/node-sdk/scripts/build-dts.mjs b/packages/node-sdk/scripts/build-dts.mjs
new file mode 100644
index 000000000..2c90f4461
--- /dev/null
+++ b/packages/node-sdk/scripts/build-dts.mjs
@@ -0,0 +1,211 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const packageRoot = path.resolve(import.meta.dirname, '..');
+const tempDir = path.join(packageRoot, '.tmp-api-extractor');
+const dtsRoot = path.join(tempDir, 'dts');
+const providerClientShimPath = path.join(dtsRoot, 'provider-clients.d.ts');
+
+const packageDirs = new Set(['agent-core', 'kaos', 'kosong', 'node-sdk', 'oauth']);
+const workspacePackages = new Map([
+  ['@moonshot-ai/agent-core', 'agent-core'],
+  ['@moonshot-ai/kaos', 'kaos'],
+  ['@moonshot-ai/kimi-code-oauth', 'oauth'],
+  ['@moonshot-ai/kosong', 'kosong'],
+]);
+
+try {
+  await rm(tempDir, { recursive: true, force: true });
+  await run('tsc', ['-p', 'tsconfig.dts.json']);
+  await writeProviderClientShim();
+  await rewriteWorkspaceSpecifiers();
+  await run('api-extractor', ['run', '--local']);
+} finally {
+  await rm(tempDir, { recursive: true, force: true });
+}
+
+function run(command, args) {
+  const executable = process.platform === 'win32' ? `${command}.cmd` : command;
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, args, {
+      cwd: packageRoot,
+      stdio: 'inherit',
+    });
+
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      const detail = signal === null ? `exit code ${String(code)}` : `signal ${signal}`;
+      reject(new Error(`${command} failed with ${detail}`));
+    });
+  });
+}
+
+async function writeProviderClientShim() {
+  await mkdir(dtsRoot, { recursive: true });
+  await writeFile(
+    providerClientShimPath,
+    [
+      'export interface Anthropic {}',
+      'export interface GoogleGenAI {}',
+      'export interface OpenAI {}',
+      'export namespace OpenAI {',
+      '  export namespace Chat {',
+      '    export type ChatCompletion = unknown;',
+      '    export type ChatCompletionChunk = unknown;',
+      '    export type ChatCompletionCreateParamsNonStreaming = unknown;',
+      '  }',
+      '}',
+      '',
+    ].join('\n'),
+  );
+}
+
+async function rewriteWorkspaceSpecifiers() {
+  const files = await findDtsFiles(dtsRoot);
+  const emittedFiles = new Set(files.map((file) => path.resolve(file)));
+
+  await Promise.all(
+    files.map(async (file) => {
+      const packageDir = packageDirForFile(file);
+      if (packageDir === undefined) {
+        return;
+      }
+
+      const text = await readFile(file, 'utf8');
+      const providerClientSpecifier = relativeSpecifier(file, providerClientShimPath);
+      const providerClientText = text
+        .replaceAll(
+          "import Anthropic from '@anthropic-ai/sdk';",
+          `import { Anthropic } from '${providerClientSpecifier}';`,
+        )
+        .replaceAll(
+          "import OpenAI from 'openai';",
+          `import { OpenAI } from '${providerClientSpecifier}';`,
+        )
+        .replaceAll(
+          "import type OpenAI from 'openai';",
+          `import type { OpenAI } from '${providerClientSpecifier}';`,
+        )
+        .replaceAll(
+          "import { GoogleGenAI as GenAIClient } from '@google/genai';",
+          `import { GoogleGenAI as GenAIClient } from '${providerClientSpecifier}';`,
+        );
+      const updated = providerClientText.replaceAll(
+        /(["'])(#\/[^"']+|@moonshot-ai\/(?:agent-core|kaos|kimi-code-oauth|kosong)(?:\/[^"']+)?)\1/g,
+        (_match, quote, specifier) => {
+          const resolved = resolveSpecifier({
+            currentFile: file,
+            emittedFiles,
+            packageDir,
+            specifier,
+          });
+
+          return `${quote}${relativeSpecifier(file, resolved)}${quote}`;
+        },
+      );
+
+      if (updated !== text) {
+        await writeFile(file, updated);
+      }
+    }),
+  );
+}
+
+async function findDtsFiles(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const entryPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        return findDtsFiles(entryPath);
+      }
+      return entry.name.endsWith('.d.ts') ? [entryPath] : [];
+    }),
+  );
+
+  return files.flat();
+}
+
+function packageDirForFile(file) {
+  const parts = path.relative(dtsRoot, file).split(path.sep);
+  const [packageDir, firstDir] = parts;
+
+  if (packageDir === undefined || firstDir !== 'src' || !packageDirs.has(packageDir)) {
+    return undefined;
+  }
+
+  return packageDir;
+}
+
+function resolveSpecifier({ currentFile, emittedFiles, packageDir, specifier }) {
+  if (specifier.startsWith('#/')) {
+    return resolvePackageSubpath({
+      emittedFiles,
+      packageDir,
+      subpath: specifier.slice(2),
+      originalSpecifier: specifier,
+    });
+  }
+
+  const workspacePackage = workspacePackageForSpecifier(specifier);
+  if (workspacePackage === undefined) {
+    throw new Error(`Unexpected workspace specifier in ${currentFile}: ${specifier}`);
+  }
+
+  return resolvePackageSubpath({
+    emittedFiles,
+    packageDir: workspacePackage.packageDir,
+    subpath: workspacePackage.subpath,
+    originalSpecifier: specifier,
+  });
+}
+
+function workspacePackageForSpecifier(specifier) {
+  for (const [packageName, packageDir] of workspacePackages) {
+    if (specifier === packageName) {
+      return { packageDir, subpath: 'index' };
+    }
+
+    const prefix = `${packageName}/`;
+    if (specifier.startsWith(prefix)) {
+      return { packageDir, subpath: specifier.slice(prefix.length) };
+    }
+  }
+
+  return undefined;
+}
+
+function resolvePackageSubpath({ emittedFiles, packageDir, subpath, originalSpecifier }) {
+  const srcRoot = path.join(dtsRoot, packageDir, 'src');
+  const directFile = path.resolve(srcRoot, `${subpath}.d.ts`);
+  if (emittedFiles.has(directFile) || existsSync(directFile)) {
+    return directFile;
+  }
+
+  const indexFile = path.resolve(srcRoot, subpath, 'index.d.ts');
+  if (emittedFiles.has(indexFile) || existsSync(indexFile)) {
+    return indexFile;
+  }
+
+  throw new Error(`Unable to resolve ${originalSpecifier} in emitted declarations`);
+}
+
+function relativeSpecifier(fromFile, toFile) {
+  const fromDir = path.dirname(fromFile);
+  const withoutExtension = toFile.slice(0, -'.d.ts'.length);
+  let relative = path.relative(fromDir, withoutExtension).replaceAll(path.sep, '/');
+
+  if (!relative.startsWith('.')) {
+    relative = `./${relative}`;
+  }
+
+  return relative;
+}
diff --git a/packages/node-sdk/src/auth.ts b/packages/node-sdk/src/auth.ts
new file mode 100644
index 000000000..15a01eff8
--- /dev/null
+++ b/packages/node-sdk/src/auth.ts
@@ -0,0 +1,133 @@
+import { readConfigFile, writeConfigFile, type KimiConfig, type OAuthRef } from '@moonshot-ai/agent-core';
+import {
+  applyManagedKimiCodeConfig,
+  applyManagedKimiCodeLogoutConfig,
+  KIMI_CODE_PROVIDER_NAME,
+  KimiOAuthToolkit,
+  type AuthManagedUsageResult,
+  type AuthStatus,
+  type BearerTokenProvider,
+  type FetchSubmitFeedbackResult,
+  type KimiHostIdentity,
+  type KimiOAuthLoginOptions,
+  type ManagedKimiConfigShape,
+  type OAuthRefreshOutcome,
+} from '@moonshot-ai/kimi-code-oauth';
+
+export interface KimiAuthSubmitFeedbackInput {
+  readonly content: string;
+  readonly sessionId: string;
+  readonly version: string;
+  readonly os: string;
+  readonly model: string | null;
+}
+
+export type KimiAuthLoginOptions = Omit<KimiOAuthLoginOptions, 'provisionConfig'>;
+
+export interface KimiAuthLoginResult {
+  readonly providerName: string;
+  readonly ok: true;
+  readonly defaultModel: string;
+  readonly defaultThinking: boolean;
+  readonly configPath?: string | undefined;
+}
+
+export interface KimiAuthLogoutResult {
+  readonly providerName: string;
+  readonly ok: true;
+}
+
+export interface KimiAuthFacadeOptions {
+  readonly homeDir: string;
+  readonly configPath: string;
+  readonly identity?: KimiHostIdentity | undefined;
+  readonly onConfigUpdated?: ((config: KimiConfig) => void) | undefined;
+  readonly onRefresh?: ((outcome: OAuthRefreshOutcome) => void) | undefined;
+}
+
+type SDKManagedConfig = KimiConfig & ManagedKimiConfigShape;
+
+export class KimiAuthFacade {
+  private readonly toolkit: KimiOAuthToolkit<SDKManagedConfig>;
+
+  constructor(private readonly options: KimiAuthFacadeOptions) {
+    this.toolkit = new KimiOAuthToolkit<SDKManagedConfig>({
+      homeDir: options.homeDir,
+      identity: options.identity,
+      onRefresh: options.onRefresh,
+      configAdapter: {
+        configPath: options.configPath,
+        read: () => readConfigFile(options.configPath) as SDKManagedConfig,
+        write: async (config) => {
+          await writeConfigFile(options.configPath, config);
+        },
+        apply: applyManagedKimiCodeConfig,
+        remove: applyManagedKimiCodeLogoutConfig,
+      },
+    });
+  }
+
+  async status(providerName?: string | undefined): Promise<AuthStatus> {
+    return this.toolkit.status(providerName);
+  }
+
+  async login(
+    providerName: string | undefined = KIMI_CODE_PROVIDER_NAME,
+    options: KimiAuthLoginOptions = {},
+  ): Promise<KimiAuthLoginResult> {
+    const result = await this.toolkit.login(providerName, { ...options, provisionConfig: true });
+    if (result.provision === undefined) {
+      throw new Error('Kimi auth login did not provision model config.');
+    }
+    const updated = readConfigFile(this.options.configPath);
+    this.options.onConfigUpdated?.(updated);
+    return {
+      providerName: result.providerName,
+      ok: true,
+      defaultModel: result.provision.defaultModel,
+      defaultThinking: result.provision.defaultThinking,
+      configPath: result.provision.configPath,
+    };
+  }
+
+  async logout(providerName?: string | undefined): Promise<KimiAuthLogoutResult> {
+    const result = await this.toolkit.logout(providerName);
+    const updated = readConfigFile(this.options.configPath);
+    this.options.onConfigUpdated?.(updated);
+    return {
+      providerName: result.providerName,
+      ok: result.ok,
+    };
+  }
+
+  async getManagedUsage(providerName?: string | undefined): Promise<AuthManagedUsageResult> {
+    return this.toolkit.getManagedUsage(providerName);
+  }
+
+  async submitFeedback(
+    input: KimiAuthSubmitFeedbackInput,
+    providerName?: string | undefined,
+  ): Promise<FetchSubmitFeedbackResult> {
+    return this.toolkit.submitFeedback(
+      {
+        session_id: input.sessionId,
+        content: input.content,
+        version: input.version,
+        os: input.os,
+        model: input.model,
+      },
+      providerName,
+    );
+  }
+
+  async getCachedAccessToken(providerName?: string): Promise<string | undefined> {
+    return this.toolkit.getCachedAccessToken(providerName);
+  }
+
+  readonly resolveOAuthTokenProvider = (
+    providerName: string,
+    oauthRef?: OAuthRef | undefined,
+  ): BearerTokenProvider => {
+    return this.toolkit.tokenProvider(providerName, oauthRef);
+  };
+}
diff --git a/packages/node-sdk/src/events.ts b/packages/node-sdk/src/events.ts
new file mode 100644
index 000000000..014d81bb3
--- /dev/null
+++ b/packages/node-sdk/src/events.ts
@@ -0,0 +1,108 @@
+import type {
+  ApprovalRequest,
+  ApprovalResponse,
+  QuestionRequest,
+  QuestionResult,
+} from '@moonshot-ai/agent-core';
+
+// Event union plus shared fields/payloads used across event families.
+export type { KimiErrorPayload, Event } from '@moonshot-ai/agent-core';
+
+export { MCP_OAUTH_AUTHORIZATION_URL_TOOL_UPDATE } from '@moonshot-ai/agent-core';
+
+// Session lifecycle/status events and their status payload.
+export type {
+  AgentStatusUpdatedEvent,
+  SessionMetaUpdatedEvent,
+  SkillActivatedEvent,
+  ErrorEvent,
+  UsageStatus,
+} from '@moonshot-ai/agent-core';
+
+// Turn and step lifecycle events plus the turn-ending reason enum.
+export type {
+  TurnStartedEvent,
+  TurnEndedEvent,
+  TurnStepStartedEvent,
+  TurnStepCompletedEvent,
+  TurnStepRetryingEvent,
+  TurnStepInterruptedEvent,
+  TurnEndReason,
+} from '@moonshot-ai/agent-core';
+
+// Streaming content and hook-result events.
+export type {
+  AssistantDeltaEvent,
+  HookResultEvent,
+  ThinkingDeltaEvent,
+} from '@moonshot-ai/agent-core';
+
+// Tool-call events and incremental progress payloads.
+export type {
+  ToolCallStartedEvent,
+  ToolCallDeltaEvent,
+  ToolProgressEvent,
+  ToolResultEvent,
+  ToolCallRequest,
+  ToolCallResponse,
+  ToolUpdate,
+  McpOAuthAuthorizationUrlUpdateData,
+} from '@moonshot-ai/agent-core';
+
+// MCP tool-list and server status events.
+export type {
+  ToolListUpdatedEvent,
+  ToolListUpdatedReason,
+  McpServerStatusEvent,
+  McpServerStatusPayload,
+} from '@moonshot-ai/agent-core';
+
+// Approval reverse-RPC request and response/display payloads.
+export type {
+  ApprovalRequest,
+  ApprovalDecision,
+  ApprovalScope,
+  ApprovalResponse,
+  ToolInputDisplay,
+} from '@moonshot-ai/agent-core';
+
+// Question reverse-RPC request and answer payloads.
+export type {
+  QuestionRequest,
+  QuestionItem,
+  QuestionOption,
+  QuestionAnswerMethod,
+  QuestionAnswers,
+  QuestionResponse,
+  QuestionResult,
+} from '@moonshot-ai/agent-core';
+
+// Subagent lifecycle events.
+export type {
+  SubagentSpawnedEvent,
+  SubagentCompletedEvent,
+  SubagentFailedEvent,
+} from '@moonshot-ai/agent-core';
+
+// Compaction lifecycle events and compaction result payload.
+export type {
+  CompactionStartedEvent,
+  CompactionBlockedEvent,
+  CompactionCancelledEvent,
+  CompactionCompletedEvent,
+  CompactionResult,
+} from '@moonshot-ai/agent-core';
+
+// Background task lifecycle events emitted by the BPM. Covers both
+// bash (`bash-*`) and agent (`agent-*`) tasks under one wire format.
+export type {
+  BackgroundTaskStartedEvent,
+  BackgroundTaskUpdatedEvent,
+  BackgroundTaskTerminatedEvent,
+} from '@moonshot-ai/agent-core';
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type ApprovalHandler = (request: ApprovalRequest) => MaybePromise<ApprovalResponse>;
+
+export type QuestionHandler = (request: QuestionRequest) => MaybePromise<QuestionResult>;
diff --git a/packages/node-sdk/src/index.ts b/packages/node-sdk/src/index.ts
new file mode 100644
index 000000000..f1801ef11
--- /dev/null
+++ b/packages/node-sdk/src/index.ts
@@ -0,0 +1,36 @@
+export { KimiHarness } from '#/kimi-harness';
+export { Session } from '#/session';
+export { KimiAuthFacade } from '#/auth';
+
+export {
+  ErrorCodes,
+  KimiError,
+  type KimiErrorCode,
+  type KimiErrorInfo,
+  type KimiErrorOptions,
+  type KimiErrorPayload,
+  KIMI_ERROR_INFO,
+  fromKimiErrorPayload,
+  isKimiError,
+  toKimiErrorPayload,
+} from '@moonshot-ai/agent-core';
+
+// Diagnostic logging — public surface only.
+// RootLogger / getRootLogger / LoggingConfig stay inside agent-core.
+export {
+  flushDiagnosticLogs,
+  log,
+  redact,
+  resolveGlobalLogPath,
+  resolveKimiHome,
+} from '@moonshot-ai/agent-core';
+export type { LogContext, LogLevel, LogPayload, Logger } from '@moonshot-ai/agent-core';
+
+export type {
+  KimiAuthLoginResult,
+  KimiAuthLogoutResult,
+  KimiAuthSubmitFeedbackInput,
+} from '#/auth';
+
+export * from '#/events';
+export type * from '#/types';
diff --git a/packages/node-sdk/src/kimi-harness.ts b/packages/node-sdk/src/kimi-harness.ts
new file mode 100644
index 000000000..82185eb89
--- /dev/null
+++ b/packages/node-sdk/src/kimi-harness.ts
@@ -0,0 +1,240 @@
+import {
+  ensureConfigFile,
+  ErrorCodes,
+  KimiError,
+  getRootLogger,
+  noopTelemetryClient,
+  resolveConfigPath,
+  resolveKimiHome,
+  resolveLoggingConfig,
+  withTelemetryContext,
+  type TelemetryClient,
+  type TelemetryContextPatch,
+  type TelemetryProperties,
+} from '@moonshot-ai/agent-core';
+import { assertKimiHostIdentity } from '@moonshot-ai/kimi-code-oauth';
+
+import { KimiAuthFacade } from '#/auth';
+import { SDKRpcClient } from '#/rpc';
+import { Session } from '#/session';
+import type {
+  CreateSessionOptions,
+  ExportSessionInput,
+  ExportSessionResult,
+  ForkSessionInput,
+  GetConfigOptions,
+  KimiConfig,
+  KimiConfigPatch,
+  KimiHarnessOptions,
+  KimiHostIdentity,
+  ListSessionsOptions,
+  RenameSessionInput,
+  ResumeSessionInput,
+  SessionSummary,
+} from '#/types';
+
+export class KimiHarness {
+  readonly homeDir: string;
+  readonly configPath: string;
+  readonly auth: KimiAuthFacade;
+
+  private readonly identity: KimiHostIdentity | undefined;
+  private readonly uiMode: string;
+  private readonly telemetry: TelemetryClient;
+  private readonly activeSessions = new Map<string, Session>();
+  private readonly rpc: SDKRpcClient;
+
+  constructor(options: KimiHarnessOptions) {
+    this.identity =
+      options.identity === undefined ? undefined : assertKimiHostIdentity(options.identity);
+    this.uiMode = options.uiMode ?? DEFAULT_SESSION_STARTED_UI_MODE;
+    this.homeDir = resolveKimiHome(options.homeDir);
+    this.configPath = resolveConfigPath({
+      homeDir: this.homeDir,
+      configPath: options.configPath,
+    });
+    this.configureLogging();
+    this.telemetry = options.telemetry ?? noopTelemetryClient;
+    this.auth = new KimiAuthFacade({
+      homeDir: this.homeDir,
+      configPath: this.configPath,
+      identity: this.identity,
+      onRefresh: options.onOAuthRefresh,
+    });
+    this.rpc = new SDKRpcClient({
+      homeDir: options.homeDir,
+      configPath: this.configPath,
+      identity: this.identity,
+      resolveOAuthTokenProvider: this.auth.resolveOAuthTokenProvider,
+      skillDirs: options.skillDirs,
+      telemetry: this.telemetry,
+    });
+  }
+
+  private configureLogging(): void {
+    // Fresh configure completes synchronously on the first-time path; pre-init
+    // noop covers any caller that races before this returns.
+    void getRootLogger().configure(resolveLoggingConfig({ homeDir: this.homeDir }));
+  }
+
+  get sessions(): ReadonlyMap<string, Session> {
+    return this.activeSessions;
+  }
+
+  get interactiveAgentId(): string {
+    return this.rpc.interactiveAgentId;
+  }
+
+  set interactiveAgentId(agentId: string) {
+    this.rpc.interactiveAgentId = agentId;
+  }
+
+  track(event: string, properties?: TelemetryProperties): void {
+    this.telemetry.track(event, properties);
+  }
+
+  setTelemetryContext(patch: TelemetryContextPatch): void {
+    this.telemetry.setContext?.(patch);
+  }
+
+  async createSession(options: CreateSessionOptions): Promise<Session> {
+    const { planMode, ...coreOptions } = options;
+    const summary = await this.rpc.createSession(coreOptions);
+    const session = new Session({
+      id: summary.id,
+      workDir: summary.workDir,
+      summary,
+      rpc: this.rpc,
+      onClose: () => {
+        this.activeSessions.delete(summary.id);
+      },
+    });
+    this.activeSessions.set(session.id, session);
+    if (planMode === true) {
+      await session.setPlanMode(true);
+    }
+    this.trackSessionStarted(summary.id, false);
+    this.trackSessionEvent(session.id, 'session_new');
+    return session;
+  }
+
+  async resumeSession(input: ResumeSessionInput): Promise<Session> {
+    const id = normalizeSessionId(input.id);
+    const active = this.activeSessions.get(id);
+    if (active !== undefined) return active;
+
+    const summary = await this.rpc.resumeSession({ id });
+    const session = new Session({
+      id: summary.id,
+      workDir: summary.workDir,
+      summary,
+      rpc: this.rpc,
+      onClose: () => {
+        this.activeSessions.delete(summary.id);
+      },
+    });
+    this.activeSessions.set(session.id, session);
+    this.trackSessionStarted(summary.id, true);
+    this.trackSessionEvent(session.id, 'session_resume');
+    return session;
+  }
+
+  async forkSession(input: ForkSessionInput): Promise<Session> {
+    const summary = await this.rpc.forkSession({
+      id: normalizeSessionId(input.id),
+      forkId: input.forkId,
+      title: input.title,
+      metadata: input.metadata,
+    });
+    const session = new Session({
+      id: summary.id,
+      workDir: summary.workDir,
+      summary,
+      rpc: this.rpc,
+      onClose: () => {
+        this.activeSessions.delete(summary.id);
+      },
+    });
+    this.activeSessions.set(session.id, session);
+    this.trackSessionStarted(summary.id, true);
+    this.trackSessionEvent(session.id, 'session_fork');
+    return session;
+  }
+
+  getSession(id: string): Session | undefined {
+    return this.activeSessions.get(id);
+  }
+
+  async closeSession(id: string): Promise<void> {
+    await this.activeSessions.get(id)?.close();
+  }
+
+  async renameSession(input: RenameSessionInput): Promise<void> {
+    await this.rpc.renameSession(input);
+    this.activeSessions.get(input.id)?.emitMetaUpdated({ title: input.title });
+  }
+
+  async exportSession(input: ExportSessionInput): Promise<ExportSessionResult> {
+    const result = await this.rpc.exportSession({
+      ...input,
+      version: input.version ?? this.identity?.version,
+    });
+    this.trackSessionEvent(input.id, 'export');
+    return result;
+  }
+
+  async listSessions(options: ListSessionsOptions): Promise<readonly SessionSummary[]> {
+    return this.rpc.listSessions(options);
+  }
+
+  async getConfig(options: GetConfigOptions = {}): Promise<KimiConfig> {
+    return this.rpc.getConfig(options);
+  }
+
+  async ensureConfigFile(): Promise<void> {
+    await ensureConfigFile(this.configPath);
+  }
+
+  async setConfig(patch: KimiConfigPatch): Promise<KimiConfig> {
+    return this.rpc.setConfig(patch);
+  }
+
+  async removeProvider(providerId: string): Promise<KimiConfig> {
+    return this.rpc.removeProvider(providerId);
+  }
+
+  async close(): Promise<void> {
+    await Promise.all(Array.from(this.activeSessions.values(), (session) => session.close()));
+    try {
+      await getRootLogger().flush();
+    } catch {
+      // never let logger flush block process exit
+    }
+  }
+
+  private trackSessionEvent(eventSessionId: string, event: string): void {
+    withTelemetryContext(this.telemetry, { sessionId: eventSessionId }).track(event);
+  }
+
+  private trackSessionStarted(eventSessionId: string, resumed: boolean): void {
+    withTelemetryContext(this.telemetry, { sessionId: eventSessionId }).track('session_started', {
+      client_name: this.identity?.userAgentProduct ?? null,
+      client_version: this.identity?.version ?? null,
+      ui_mode: this.uiMode,
+      resumed,
+    });
+  }
+}
+
+const DEFAULT_SESSION_STARTED_UI_MODE = 'shell';
+
+function normalizeSessionId(value: string): string {
+  if (typeof value !== 'string') {
+    throw new KimiError(ErrorCodes.SESSION_ID_REQUIRED, 'Session id is required.');
+  }
+  const normalized = value.trim();
+  if (normalized.length === 0) {
+    throw new KimiError(ErrorCodes.SESSION_ID_EMPTY, 'Session id cannot be empty.');
+  }
+  return normalized;
+}
diff --git a/packages/node-sdk/src/rpc.ts b/packages/node-sdk/src/rpc.ts
new file mode 100644
index 000000000..0446dafd6
--- /dev/null
+++ b/packages/node-sdk/src/rpc.ts
@@ -0,0 +1,556 @@
+import {
+  createRPC,
+  ErrorCodes,
+  KimiCore,
+  makeErrorPayload,
+  resolveKimiHome,
+  type ApprovalRequest,
+  type ApprovalResponse,
+  type CoreAPI,
+  type Event,
+  type OAuthTokenProviderResolver,
+  type QuestionRequest,
+  type QuestionResult,
+  type SDKAPI,
+  type SDKRPCClient,
+  type TelemetryClient,
+  type ToolCallRequest,
+  type ToolCallResponse,
+} from '@moonshot-ai/agent-core';
+import { createKimiDefaultHeaders } from '@moonshot-ai/kimi-code-oauth';
+
+import type { ApprovalHandler, QuestionHandler } from '#/events';
+import type {
+  BackgroundTaskInfo,
+  CreateSessionOptions,
+  ExportSessionInput,
+  ExportSessionResult,
+  ForkSessionInput,
+  GetConfigOptions,
+  KimiConfig,
+  KimiConfigPatch,
+  ListSessionsOptions,
+  McpServerInfo,
+  McpStartupMetrics,
+  PermissionMode,
+  CompactOptions,
+  SessionPlan,
+  SessionStatus,
+  SessionUsage,
+  PromptInput,
+  RenameSessionInput,
+  ResumeSessionInput,
+  ResumedSessionSummary,
+  SessionSummary,
+  SkillSummary,
+  Unsubscribe,
+  KimiHostIdentity,
+} from '#/types';
+
+const MAIN_AGENT_ID = 'main';
+
+export interface SDKRpcClientOptions {
+  readonly homeDir?: string | undefined;
+  readonly configPath?: string | undefined;
+  readonly identity?: KimiHostIdentity | undefined;
+  readonly resolveOAuthTokenProvider?: OAuthTokenProviderResolver | undefined;
+  readonly skillDirs?: readonly string[];
+  readonly telemetry?: TelemetryClient | undefined;
+}
+
+export interface SessionPromptRpcInput {
+  readonly sessionId: string;
+  readonly input: PromptInput;
+}
+
+export interface SessionIdRpcInput {
+  readonly sessionId: string;
+}
+
+export interface SetSessionModelRpcInput extends SessionIdRpcInput {
+  readonly model: string;
+}
+
+export interface SetSessionModelRpcResult {
+  readonly model: string;
+  readonly providerName?: string | undefined;
+}
+
+export interface SetSessionThinkingRpcInput extends SessionIdRpcInput {
+  readonly level: string;
+}
+
+export interface SetSessionPermissionRpcInput extends SessionIdRpcInput {
+  readonly mode: PermissionMode;
+}
+
+export interface SetSessionPlanModeRpcInput extends SessionIdRpcInput {
+  readonly enabled: boolean;
+}
+
+export interface ActivateSkillRpcInput extends SessionIdRpcInput {
+  readonly name: string;
+  readonly args?: string | undefined;
+}
+
+export interface ReconnectMcpServerRpcInput extends SessionIdRpcInput {
+  readonly name: string;
+}
+
+type ResolvedCoreAPI = Awaited<ReturnType<SDKRPCClient>>;
+
+export class SDKRpcClient {
+  readonly core: KimiCore;
+  interactiveAgentId = MAIN_AGENT_ID;
+  private readonly ready: Promise<void>;
+  private rpc: ResolvedCoreAPI | undefined;
+  private readonly eventListeners = new Set<(event: Event) => void>();
+  private readonly approvalHandlers = new Map<string, ApprovalHandler>();
+  private readonly questionHandlers = new Map<string, QuestionHandler>();
+
+  constructor(options: SDKRpcClientOptions = {}) {
+    const [coreRpc, sdkRpc] = createRPC<CoreAPI, SDKAPI>();
+    const homeDir = resolveKimiHome(options.homeDir);
+    const kimiRequestHeaders =
+      options.identity === undefined
+        ? undefined
+        : createKimiDefaultHeaders({ homeDir, ...options.identity });
+    this.core = new KimiCore(coreRpc, {
+      homeDir: options.homeDir,
+      configPath: options.configPath,
+      kimiRequestHeaders,
+      resolveOAuthTokenProvider: options.resolveOAuthTokenProvider,
+      skillDirs: options.skillDirs,
+      telemetry: options.telemetry,
+    });
+    this.ready = sdkRpc(new ClientAPI(this)).then((rpc) => {
+      this.rpc = rpc;
+    });
+  }
+
+  get homeDir(): string {
+    return this.core.homeDir;
+  }
+
+  get configPath(): string {
+    return this.core.configPath;
+  }
+
+  async createSession(input: CreateSessionOptions): Promise<SessionSummary> {
+    const rpc = await this.getRpc();
+    const { planMode, ...coreInput } = input;
+    void planMode;
+    return rpc.createSession(coreInput);
+  }
+
+  async resumeSession(input: ResumeSessionInput): Promise<ResumedSessionSummary> {
+    const rpc = await this.getRpc();
+    return rpc.resumeSession({ sessionId: input.id });
+  }
+
+  async forkSession(input: ForkSessionInput): Promise<SessionSummary> {
+    const rpc = await this.getRpc();
+    return rpc.forkSession({
+      sessionId: input.id,
+      id: input.forkId,
+      title: input.title,
+      metadata: input.metadata,
+    });
+  }
+
+  async closeSession(input: SessionIdRpcInput): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.closeSession({ sessionId: input.sessionId });
+  }
+
+  async listSessions(input: ListSessionsOptions): Promise<readonly SessionSummary[]> {
+    const rpc = await this.getRpc();
+    return rpc.listSessions(input);
+  }
+
+  async renameSession(input: RenameSessionInput): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.renameSession({
+      sessionId: input.id,
+      title: input.title,
+    });
+  }
+
+  async exportSession(input: ExportSessionInput): Promise<ExportSessionResult> {
+    const rpc = await this.getRpc();
+    return rpc.exportSession({
+      sessionId: input.id,
+      outputPath: input.outputPath,
+      includeGlobalLog: input.includeGlobalLog,
+      version: input.version,
+    });
+  }
+
+  async getConfig(input?: GetConfigOptions): Promise<KimiConfig> {
+    const rpc = await this.getRpc();
+    return rpc.getKimiConfig(input ?? {});
+  }
+
+  async setConfig(input: KimiConfigPatch): Promise<KimiConfig> {
+    const rpc = await this.getRpc();
+    return rpc.setKimiConfig(input);
+  }
+
+  async removeProvider(providerId: string): Promise<KimiConfig> {
+    const rpc = await this.getRpc();
+    return rpc.removeKimiProvider({ providerId });
+  }
+
+  async prompt(input: SessionPromptRpcInput): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.prompt({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+      input: input.input,
+    });
+  }
+
+  async steer(input: SessionPromptRpcInput): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.steer({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+      input: input.input,
+    });
+  }
+
+  async generateAgentsMd(input: SessionIdRpcInput): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.generateAgentsMd({ sessionId: input.sessionId });
+  }
+
+  async cancel(input: SessionIdRpcInput): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.cancel({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+    });
+  }
+
+  async setModel(input: SetSessionModelRpcInput): Promise<SetSessionModelRpcResult> {
+    const rpc = await this.getRpc();
+    return rpc.setModel({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+      model: input.model,
+    });
+  }
+
+  async setThinking(input: SetSessionThinkingRpcInput): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.setThinking({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+      level: input.level,
+    });
+  }
+
+  async setPermission(input: SetSessionPermissionRpcInput): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.setPermission({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+      mode: input.mode,
+    });
+  }
+
+  async setPlanMode(input: SetSessionPlanModeRpcInput): Promise<void> {
+    const rpc = await this.getRpc();
+    if (!input.enabled) {
+      return rpc.cancelPlan({
+        sessionId: input.sessionId,
+        agentId: this.interactiveAgentId,
+      });
+    }
+    return rpc.enterPlan({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+    });
+  }
+
+  async getPlan(input: SessionIdRpcInput): Promise<SessionPlan> {
+    const rpc = await this.getRpc();
+    return rpc.getPlan({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+    });
+  }
+
+  async clearPlan(input: SessionIdRpcInput): Promise<void> {
+    const rpc = await this.getRpc();
+    await rpc.clearPlan({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+    });
+  }
+
+  async compact(input: SessionIdRpcInput & CompactOptions): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.beginCompaction({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+      ...(input.instruction !== undefined ? { instruction: input.instruction } : {}),
+    });
+  }
+
+  async cancelCompaction(input: SessionIdRpcInput): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.cancelCompaction({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+    });
+  }
+
+  async getUsage(input: SessionIdRpcInput): Promise<SessionUsage> {
+    const rpc = await this.getRpc();
+    return rpc.getUsage({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+    });
+  }
+
+  async getStatus(input: SessionIdRpcInput): Promise<SessionStatus> {
+    const rpc = await this.getRpc();
+    const agentId = this.interactiveAgentId;
+    const config = await rpc.getConfig({
+      sessionId: input.sessionId,
+      agentId,
+    });
+    const context = await rpc.getContext({
+      sessionId: input.sessionId,
+      agentId,
+    });
+    const permission = await rpc.getPermission({
+      sessionId: input.sessionId,
+      agentId,
+    });
+    const plan = await rpc.getPlan({
+      sessionId: input.sessionId,
+      agentId,
+    });
+    const usage = await rpc.getUsage({
+      sessionId: input.sessionId,
+      agentId,
+    });
+    const maxContextTokens = config.modelCapabilities?.max_context_tokens ?? 0;
+    const contextTokens = context.tokenCount;
+    const contextUsage = maxContextTokens > 0 ? contextTokens / maxContextTokens : 0;
+    const hasUsage =
+      usage.byModel !== undefined || usage.total !== undefined || usage.currentTurn !== undefined;
+    return {
+      model: config.modelAlias ?? config.provider?.model,
+      thinkingLevel: config.thinkingLevel,
+      permission: permission.mode,
+      planMode: plan !== null,
+      contextTokens,
+      maxContextTokens,
+      contextUsage,
+      usage: hasUsage ? usage : undefined,
+    };
+  }
+
+  async listSkills(input: SessionIdRpcInput): Promise<readonly SkillSummary[]> {
+    const rpc = await this.getRpc();
+    return rpc.listSkills({ sessionId: input.sessionId });
+  }
+
+  async listBackgroundTasks(
+    input: SessionIdRpcInput & { activeOnly?: boolean; limit?: number },
+  ): Promise<readonly BackgroundTaskInfo[]> {
+    const rpc = await this.getRpc();
+    return rpc.getBackground({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+      activeOnly: input.activeOnly,
+      limit: input.limit,
+    });
+  }
+
+  async getBackgroundTaskOutput(
+    input: SessionIdRpcInput & { taskId: string; tail?: number },
+  ): Promise<string> {
+    const rpc = await this.getRpc();
+    return rpc.getBackgroundOutput({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+      taskId: input.taskId,
+      tail: input.tail,
+    });
+  }
+
+  async getBackgroundTaskOutputPath(
+    input: SessionIdRpcInput & { taskId: string },
+  ): Promise<string | undefined> {
+    const rpc = await this.getRpc();
+    return rpc.getBackgroundOutputPath({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+      taskId: input.taskId,
+    });
+  }
+
+  async stopBackgroundTask(
+    input: SessionIdRpcInput & { taskId: string; reason?: string },
+  ): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.stopBackground({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+      taskId: input.taskId,
+      reason: input.reason,
+    });
+  }
+
+  async listMcpServers(input: SessionIdRpcInput): Promise<readonly McpServerInfo[]> {
+    const rpc = await this.getRpc();
+    return rpc.listMcpServers({ sessionId: input.sessionId });
+  }
+
+  async getMcpStartupMetrics(input: SessionIdRpcInput): Promise<McpStartupMetrics> {
+    const rpc = await this.getRpc();
+    return rpc.getMcpStartupMetrics({ sessionId: input.sessionId });
+  }
+
+  async reconnectMcpServer(input: ReconnectMcpServerRpcInput): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.reconnectMcpServer({ sessionId: input.sessionId, name: input.name });
+  }
+
+  async activateSkill(input: ActivateSkillRpcInput): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.activateSkill({
+      sessionId: input.sessionId,
+      agentId: this.interactiveAgentId,
+      name: input.name,
+      args: input.args,
+    });
+  }
+
+  onEvent(listener: (event: Event) => void): Unsubscribe {
+    this.eventListeners.add(listener);
+    return () => {
+      this.eventListeners.delete(listener);
+    };
+  }
+
+  receiveEvent(event: Event): void {
+    for (const listener of this.eventListeners) {
+      listener(event);
+    }
+  }
+
+  setApprovalHandler(sessionId: string, handler: ApprovalHandler | undefined): void {
+    if (handler === undefined) {
+      this.approvalHandlers.delete(sessionId);
+      return;
+    }
+    this.approvalHandlers.set(sessionId, handler);
+  }
+
+  setQuestionHandler(sessionId: string, handler: QuestionHandler | undefined): void {
+    if (handler === undefined) {
+      this.questionHandlers.delete(sessionId);
+      return;
+    }
+    this.questionHandlers.set(sessionId, handler);
+  }
+
+  clearSessionHandlers(sessionId: string): void {
+    this.approvalHandlers.delete(sessionId);
+    this.questionHandlers.delete(sessionId);
+  }
+
+  async requestApproval(
+    request: ApprovalRequest & { sessionId: string; agentId: string },
+  ): Promise<ApprovalResponse> {
+    const handler = this.approvalHandlers.get(request.sessionId);
+    if (handler === undefined) {
+      return {
+        decision: 'cancelled',
+        feedback: 'No approval handler registered.',
+      };
+    }
+
+    try {
+      return await handler(request);
+    } catch (error) {
+      this.receiveEvent({
+        type: 'error',
+        sessionId: request.sessionId,
+        agentId: request.agentId,
+        ...makeErrorPayload(ErrorCodes.SESSION_APPROVAL_HANDLER_ERROR, errorMessage(error)),
+      });
+      return {
+        decision: 'cancelled',
+        feedback: 'Approval handler failed.',
+      };
+    }
+  }
+
+  async requestQuestion(
+    request: QuestionRequest & { sessionId: string; agentId: string },
+  ): Promise<QuestionResult> {
+    const handler = this.questionHandlers.get(request.sessionId);
+    if (handler === undefined) return null;
+
+    try {
+      return await handler(request);
+    } catch (error) {
+      this.receiveEvent({
+        type: 'error',
+        sessionId: request.sessionId,
+        agentId: request.agentId,
+        ...makeErrorPayload(ErrorCodes.SESSION_QUESTION_HANDLER_ERROR, errorMessage(error)),
+      });
+      return null;
+    }
+  }
+
+  async toolCall(request: ToolCallRequest): Promise<ToolCallResponse> {
+    return {
+      output: `SDK custom tool calls are not supported: ${request.toolCallId}`,
+      isError: true,
+    };
+  }
+
+  private async getRpc(): Promise<ResolvedCoreAPI> {
+    await this.ready;
+    if (this.rpc === undefined) {
+      throw new Error('SDK RPC client was not initialized.');
+    }
+    return this.rpc;
+  }
+}
+
+export class ClientAPI implements SDKAPI {
+  constructor(readonly client: SDKRpcClient) {}
+
+  emitEvent(event: Event): void {
+    this.client.receiveEvent(event);
+  }
+
+  requestApproval(
+    request: ApprovalRequest & { sessionId: string; agentId: string },
+  ): Promise<ApprovalResponse> {
+    return this.client.requestApproval(request);
+  }
+
+  requestQuestion(
+    request: QuestionRequest & { sessionId: string; agentId: string },
+  ): Promise<QuestionResult> {
+    return this.client.requestQuestion(request);
+  }
+
+  toolCall(request: ToolCallRequest): Promise<ToolCallResponse> {
+    return this.client.toolCall(request);
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
diff --git a/packages/node-sdk/src/session.ts b/packages/node-sdk/src/session.ts
new file mode 100644
index 000000000..766cae584
--- /dev/null
+++ b/packages/node-sdk/src/session.ts
@@ -0,0 +1,411 @@
+import { ErrorCodes, KimiError, type KimiErrorCode } from '@moonshot-ai/agent-core';
+import { type ApprovalHandler, type Event, type QuestionHandler } from '#/events';
+import type { SDKRpcClient } from '#/rpc';
+import type {
+  BackgroundTaskInfo,
+  CompactOptions,
+  McpServerInfo,
+  McpStartupMetrics,
+  PermissionMode,
+  PromptInput,
+  ResumedSessionState,
+  SessionPlan,
+  SessionStatus,
+  SessionSummary,
+  SessionUsage,
+  SkillSummary,
+  Unsubscribe,
+} from '#/types';
+
+const MAIN_AGENT_ID = 'main';
+
+export interface SessionOptions {
+  readonly id: string;
+  readonly workDir: string;
+  readonly summary?: SessionSummary | undefined;
+  readonly resumeState?: ResumedSessionState | undefined;
+  readonly rpc: SDKRpcClient;
+  readonly onClose?: (() => void | Promise<void>) | undefined;
+}
+
+export class Session {
+  readonly id: string;
+  readonly workDir: string;
+  readonly summary?: SessionSummary | undefined;
+  private readonly resumeState: ResumedSessionState | undefined;
+
+  private readonly rpc: SDKRpcClient;
+  private readonly onClose?: (() => void | Promise<void>) | undefined;
+  private closed = false;
+
+  constructor(options: SessionOptions) {
+    this.id = options.id;
+    this.workDir = options.workDir;
+    this.summary = options.summary;
+    this.resumeState = options.resumeState ?? resumeStateFromSummary(options.summary);
+    this.rpc = options.rpc;
+    this.onClose = options.onClose;
+  }
+
+  getResumeState(): ResumedSessionState | undefined {
+    this.ensureOpen();
+    return this.resumeState;
+  }
+
+  onEvent(listener: (event: Event) => void): Unsubscribe {
+    this.ensureOpen();
+    return this.rpc.onEvent((event) => {
+      if (event.sessionId === this.id) {
+        listener(event);
+      }
+    });
+  }
+
+  setApprovalHandler(handler: ApprovalHandler | undefined): void {
+    this.ensureOpen();
+    this.rpc.setApprovalHandler(this.id, handler);
+  }
+
+  setQuestionHandler(handler: QuestionHandler | undefined): void {
+    this.ensureOpen();
+    this.rpc.setQuestionHandler(this.id, handler);
+  }
+
+  async prompt(input: string | PromptInput): Promise<void> {
+    this.ensureOpen();
+    await this.rpc.prompt({
+      sessionId: this.id,
+      input: normalizePromptInput(input),
+    });
+  }
+
+  async steer(input: string | PromptInput): Promise<void> {
+    this.ensureOpen();
+    await this.rpc.steer({
+      sessionId: this.id,
+      input: normalizePromptInput(input),
+    });
+  }
+
+  async init(): Promise<void> {
+    this.ensureOpen();
+    await this.rpc.generateAgentsMd({ sessionId: this.id });
+  }
+
+  async cancel(): Promise<void> {
+    this.ensureOpen();
+    await this.rpc.cancel({ sessionId: this.id });
+  }
+
+  async setModel(model: string): Promise<void> {
+    this.ensureOpen();
+    const normalized = normalizeRequiredString(
+      model,
+      'Session model cannot be empty',
+      ErrorCodes.SESSION_MODEL_EMPTY,
+    );
+    await this.rpc.setModel({ sessionId: this.id, model: normalized });
+  }
+
+  async setThinking(level: string): Promise<void> {
+    this.ensureOpen();
+    const normalized = normalizeRequiredString(
+      level,
+      'Session thinking level cannot be empty',
+      ErrorCodes.SESSION_THINKING_EMPTY,
+    );
+    await this.rpc.setThinking({ sessionId: this.id, level: normalized });
+  }
+
+  async setPermission(mode: PermissionMode): Promise<void> {
+    this.ensureOpen();
+    if (!isPermissionMode(mode)) {
+      throw new KimiError(
+        ErrorCodes.SESSION_PERMISSION_MODE_INVALID,
+        'Session permission mode must be yolo, manual, or auto',
+      );
+    }
+    await this.rpc.setPermission({ sessionId: this.id, mode });
+  }
+
+  async setPlanMode(enabled: boolean): Promise<void> {
+    this.ensureOpen();
+    if (typeof enabled !== 'boolean') {
+      throw new KimiError(
+        ErrorCodes.SESSION_PLAN_MODE_INVALID,
+        'Session plan mode must be a boolean',
+      );
+    }
+    await this.rpc.setPlanMode({ sessionId: this.id, enabled });
+  }
+
+  async getPlan(): Promise<SessionPlan> {
+    this.ensureOpen();
+    return this.rpc.getPlan({ sessionId: this.id });
+  }
+
+  async clearPlan(): Promise<void> {
+    this.ensureOpen();
+    await this.rpc.clearPlan({ sessionId: this.id });
+  }
+
+  async compact(options: CompactOptions = {}): Promise<void> {
+    this.ensureOpen();
+    const instruction = normalizeOptionalString(options.instruction);
+    await this.rpc.compact({
+      sessionId: this.id,
+      ...(instruction !== undefined ? { instruction } : {}),
+    });
+  }
+
+  async cancelCompaction(): Promise<void> {
+    this.ensureOpen();
+    await this.rpc.cancelCompaction({ sessionId: this.id });
+  }
+
+  async getUsage(): Promise<SessionUsage> {
+    this.ensureOpen();
+    return this.rpc.getUsage({ sessionId: this.id });
+  }
+
+  async getStatus(): Promise<SessionStatus> {
+    this.ensureOpen();
+    return this.rpc.getStatus({ sessionId: this.id });
+  }
+
+  async listSkills(): Promise<readonly SkillSummary[]> {
+    this.ensureOpen();
+    return this.rpc.listSkills({ sessionId: this.id });
+  }
+
+  /**
+   * List background tasks for this session's interactive agent.
+   *
+   * Defaults to all tasks (including terminal/lost). Pass
+   * `{ activeOnly: true }` to filter to non-terminal entries.
+   */
+  async listBackgroundTasks(
+    options: { activeOnly?: boolean; limit?: number } = {},
+  ): Promise<readonly BackgroundTaskInfo[]> {
+    this.ensureOpen();
+    return this.rpc.listBackgroundTasks({
+      sessionId: this.id,
+      activeOnly: options.activeOnly,
+      limit: options.limit,
+    });
+  }
+
+  /**
+   * Read a background task's captured output. Returns the in-memory
+   * ring buffer if available, otherwise falls back to the persisted
+   * `<sessionDir>/tasks/<taskId>/output.log`. `tail` caps the returned
+   * string to that many trailing characters.
+   */
+  async getBackgroundTaskOutput(
+    taskId: string,
+    options: { tail?: number } = {},
+  ): Promise<string> {
+    this.ensureOpen();
+    const trimmedTaskId = normalizeRequiredString(
+      taskId,
+      'Task id cannot be empty',
+      ErrorCodes.BACKGROUND_TASK_ID_EMPTY,
+    );
+    return this.rpc.getBackgroundTaskOutput({
+      sessionId: this.id,
+      taskId: trimmedTaskId,
+      tail: options.tail,
+    });
+  }
+
+  /**
+   * Request a running background task to stop. Sends SIGTERM with a
+   * grace period (handled by the core BPM); subscribers receive a
+   * `background.task.terminated` event when the kill settles. Calls
+   * for unknown or already-terminal task ids are no-ops at the core
+   * level — this method does not throw in those cases.
+   */
+  async stopBackgroundTask(
+    taskId: string,
+    options: { reason?: string } = {},
+  ): Promise<void> {
+    this.ensureOpen();
+    const trimmedTaskId = normalizeRequiredString(
+      taskId,
+      'Task id cannot be empty',
+      ErrorCodes.BACKGROUND_TASK_ID_EMPTY,
+    );
+    await this.rpc.stopBackgroundTask({
+      sessionId: this.id,
+      taskId: trimmedTaskId,
+      reason: options.reason,
+    });
+  }
+
+  /**
+   * Return the absolute path to the task's `output.log` on disk, or
+   * `undefined` when the task is unknown or has no persisted output.
+   * Callers can hand the path to an external pager.
+   */
+  async getBackgroundTaskOutputPath(taskId: string): Promise<string | undefined> {
+    this.ensureOpen();
+    const trimmedTaskId = normalizeRequiredString(
+      taskId,
+      'Task id cannot be empty',
+      ErrorCodes.BACKGROUND_TASK_ID_EMPTY,
+    );
+    return this.rpc.getBackgroundTaskOutputPath({
+      sessionId: this.id,
+      taskId: trimmedTaskId,
+    });
+  }
+
+  async listMcpServers(): Promise<readonly McpServerInfo[]> {
+    this.ensureOpen();
+    return this.rpc.listMcpServers({ sessionId: this.id });
+  }
+
+  async getMcpStartupMetrics(): Promise<McpStartupMetrics> {
+    this.ensureOpen();
+    return this.rpc.getMcpStartupMetrics({ sessionId: this.id });
+  }
+
+  async reconnectMcpServer(name: string): Promise<void> {
+    this.ensureOpen();
+    await this.rpc.reconnectMcpServer({ sessionId: this.id, name });
+  }
+
+  async activateSkill(name: string, args?: string | undefined): Promise<void> {
+    this.ensureOpen();
+    const skillName = normalizeRequiredString(
+      name,
+      'Skill name cannot be empty',
+      ErrorCodes.SKILL_NAME_EMPTY,
+    );
+    const skillArgs = normalizeOptionalString(args);
+    await this.rpc.activateSkill({
+      sessionId: this.id,
+      name: skillName,
+      ...(skillArgs !== undefined ? { args: skillArgs } : {}),
+    });
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    try {
+      await this.rpc.closeSession({ sessionId: this.id });
+    } finally {
+      this.rpc.clearSessionHandlers(this.id);
+      await this.onClose?.();
+    }
+  }
+
+  /** @internal */
+  emitMetaUpdated(patch: { readonly title?: string | undefined }): void {
+    this.emit({
+      type: 'session.meta.updated',
+      sessionId: this.id,
+      agentId: MAIN_AGENT_ID,
+      title: patch.title,
+      patch,
+    });
+  }
+
+  private emit(event: Event): void {
+    this.rpc.receiveEvent(event);
+  }
+
+  private ensureOpen(): void {
+    if (this.closed) {
+      throw new KimiError(ErrorCodes.SESSION_CLOSED, 'Session is closed');
+    }
+  }
+}
+
+function normalizePromptInput(input: string | PromptInput): PromptInput {
+  if (typeof input === 'string') {
+    if (input.trim().length === 0) {
+      throw new KimiError(ErrorCodes.REQUEST_PROMPT_INPUT_EMPTY, 'Prompt input cannot be empty');
+    }
+    return [{ type: 'text', text: input }];
+  }
+
+  if (input.length === 0) {
+    throw new KimiError(ErrorCodes.REQUEST_PROMPT_INPUT_EMPTY, 'Prompt input cannot be empty');
+  }
+
+  for (const part of input) {
+    switch (part.type) {
+      case 'text':
+        if (part.text.trim().length === 0) {
+          throw new KimiError(
+            ErrorCodes.REQUEST_PROMPT_INPUT_EMPTY,
+            'Prompt input cannot contain empty text parts',
+          );
+        }
+        break;
+      case 'image_url':
+        if (part.imageUrl.url.trim().length === 0) {
+          throw new KimiError(
+            ErrorCodes.REQUEST_PROMPT_INPUT_EMPTY,
+            'Prompt input cannot contain empty image URLs',
+          );
+        }
+        break;
+      case 'video_url':
+        if (part.videoUrl.url.trim().length === 0) {
+          throw new KimiError(
+            ErrorCodes.REQUEST_PROMPT_INPUT_EMPTY,
+            'Prompt input cannot contain empty video URLs',
+          );
+        }
+        break;
+    }
+  }
+  return input;
+}
+
+function normalizeRequiredString(
+  value: string,
+  message: string,
+  code: KimiErrorCode,
+): string {
+  const normalized = value.trim();
+  if (normalized.length === 0) {
+    throw new KimiError(code, message);
+  }
+  return normalized;
+}
+
+function normalizeOptionalString(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+function isPermissionMode(value: unknown): value is PermissionMode {
+  return value === 'yolo' || value === 'manual' || value === 'auto';
+}
+
+function resumeStateFromSummary(
+  summary: SessionSummary | undefined,
+): ResumedSessionState | undefined {
+  if (!hasResumeState(summary)) return undefined;
+  return {
+    sessionMetadata: summary.sessionMetadata,
+    agents: summary.agents,
+  };
+}
+
+function hasResumeState(
+  summary: SessionSummary | undefined,
+): summary is SessionSummary & ResumedSessionState {
+  return (
+    summary !== undefined &&
+    typeof (summary as { readonly sessionMetadata?: unknown }).sessionMetadata === 'object' &&
+    (summary as { readonly sessionMetadata?: unknown }).sessionMetadata !== null &&
+    typeof (summary as { readonly agents?: unknown }).agents === 'object' &&
+    (summary as { readonly agents?: unknown }).agents !== null
+  );
+}
diff --git a/packages/node-sdk/src/types.ts b/packages/node-sdk/src/types.ts
new file mode 100644
index 000000000..c6571786e
--- /dev/null
+++ b/packages/node-sdk/src/types.ts
@@ -0,0 +1,164 @@
+import type {
+  ExportSessionManifest,
+  ResumeSessionResult,
+  TelemetryClient,
+  TelemetryContextPatch,
+  TelemetryProperties,
+} from '@moonshot-ai/agent-core';
+import type { KimiHostIdentity, OAuthRefreshOutcome } from '@moonshot-ai/kimi-code-oauth';
+import type { ContentPart } from '@moonshot-ai/kosong';
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { readonly [key: string]: JsonValue };
+export type JsonObject = { readonly [key: string]: JsonValue };
+
+export type Unsubscribe = () => void;
+
+export type {
+  AgentReplayRecord,
+  BackgroundConfig,
+  BackgroundTaskInfo,
+  BackgroundTaskKind,
+  BackgroundTaskStatus,
+  ContextMessage,
+  ExportSessionManifest,
+  KimiConfig,
+  KimiConfigPatch,
+  LoopControl,
+  McpServerInfo,
+  McpStartupMetrics,
+  ModelAlias,
+  MoonshotServiceConfig,
+  OAuthRef,
+  PromptOrigin,
+  ProviderConfig,
+  ProviderType,
+  ResumedAgentState,
+  ServicesConfig,
+  SkillSummary,
+  ThinkingConfig,
+  ToolInfo,
+} from '@moonshot-ai/agent-core';
+
+export type { KimiHostIdentity, OAuthRefreshOutcome };
+export type { TelemetryClient, TelemetryContextPatch, TelemetryProperties };
+export type { ContentPart, Role, ToolCall } from '@moonshot-ai/kosong';
+
+export type PermissionMode = 'yolo' | 'manual' | 'auto';
+
+export type TextPromptPart = Extract<ContentPart, { type: 'text' }>;
+export type PromptPart = Extract<ContentPart, { type: 'text' | 'image_url' | 'video_url' }>;
+
+export type PromptInput = readonly PromptPart[];
+
+export interface KimiHarnessOptions {
+  readonly identity?: KimiHostIdentity | undefined;
+  readonly homeDir?: string | undefined;
+  readonly configPath?: string | undefined;
+  readonly autoLoadConfig?: boolean | undefined;
+  readonly uiMode?: string;
+  readonly skillDirs?: readonly string[];
+  readonly telemetry?: TelemetryClient | undefined;
+  readonly onOAuthRefresh?: ((outcome: OAuthRefreshOutcome) => void) | undefined;
+}
+
+export interface CreateSessionOptions {
+  readonly id?: string | undefined;
+  readonly workDir: string;
+  readonly model?: string | undefined;
+  readonly thinking?: string | undefined;
+  readonly permission?: PermissionMode | undefined;
+  readonly planMode?: boolean;
+  readonly metadata?: JsonObject | undefined;
+}
+
+export interface RenameSessionInput {
+  readonly id: string;
+  readonly title: string;
+}
+
+export interface ResumeSessionInput {
+  readonly id: string;
+}
+
+export interface ForkSessionInput {
+  readonly id: string;
+  readonly forkId?: string;
+  readonly title?: string;
+  readonly metadata?: JsonObject;
+}
+
+export interface ExportSessionInput {
+  readonly id: string;
+  readonly outputPath?: string | undefined;
+  readonly includeGlobalLog?: boolean | undefined;
+  /** Host version to record in the export manifest. */
+  readonly version: string;
+}
+
+export interface ExportSessionResult {
+  readonly zipPath: string;
+  readonly entries: readonly string[];
+  readonly sessionDir: string;
+  readonly manifest: ExportSessionManifest;
+}
+
+export interface ListSessionsOptions {
+  readonly workDir: string;
+}
+
+export interface GetConfigOptions {
+  readonly reload?: boolean | undefined;
+}
+
+export interface CompactOptions {
+  readonly instruction?: string | undefined;
+}
+
+export interface PlanInfo {
+  readonly id: string;
+  readonly content: string;
+  readonly path: string;
+}
+
+export type SessionPlan = PlanInfo | null;
+
+export interface TokenUsage {
+  readonly inputOther: number;
+  readonly output: number;
+  readonly inputCacheRead: number;
+  readonly inputCacheCreation: number;
+}
+
+export interface SessionUsage {
+  readonly byModel?: Record<string, TokenUsage> | undefined;
+  readonly currentTurn?: TokenUsage | undefined;
+  readonly total?: TokenUsage | undefined;
+}
+
+export interface SessionStatus {
+  readonly model?: string;
+  readonly thinkingLevel: string;
+  readonly permission: PermissionMode;
+  readonly planMode: boolean;
+  readonly contextTokens: number;
+  readonly maxContextTokens: number;
+  readonly contextUsage: number;
+  readonly usage?: SessionUsage;
+}
+
+export interface SessionSummary {
+  readonly id: string;
+  readonly title?: string | undefined;
+  readonly lastPrompt?: string;
+  readonly workDir: string;
+  readonly sessionDir: string;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+  readonly archived?: boolean | undefined;
+  readonly metadata?: JsonObject | undefined;
+}
+
+export type ResumedSessionState = Pick<ResumeSessionResult, 'sessionMetadata' | 'agents'>;
+
+export interface ResumedSessionSummary extends SessionSummary, ResumedSessionState {}
diff --git a/packages/node-sdk/test/auth-facade.test.ts b/packages/node-sdk/test/auth-facade.test.ts
new file mode 100644
index 000000000..0e15dfefd
--- /dev/null
+++ b/packages/node-sdk/test/auth-facade.test.ts
@@ -0,0 +1,309 @@
+import { mkdirSync, rmSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { FileTokenStorage, KIMI_CODE_PROVIDER_NAME, type TokenInfo } from '@moonshot-ai/kimi-code-oauth';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { KimiHarness } from '#/index';
+
+import { resolveRuntimeProviderWithOAuth } from '../../agent-core/src/providers/runtime-provider';
+import { TEST_IDENTITY } from './test-identity';
+
+let homeDir: string;
+
+type FetchMock = (
+  input: Parameters<typeof fetch>[0],
+  init?: Parameters<typeof fetch>[1],
+) => Promise<Response>;
+
+function freshToken(): TokenInfo {
+  return {
+    accessToken: 'oauth-access-token',
+    refreshToken: 'oauth-refresh-token',
+    expiresAt: Math.floor(Date.now() / 1000) + 3600,
+    scope: '',
+    tokenType: 'Bearer',
+    expiresIn: 3600,
+  };
+}
+
+beforeEach(() => {
+  homeDir = join(tmpdir(), `kimi-sdk-auth-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(homeDir, { recursive: true });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  rmSync(homeDir, { recursive: true, force: true });
+});
+
+describe('KimiHarness.auth', () => {
+  it('can construct auth facade without host identity', () => {
+    expect(() => new KimiHarness({ homeDir })).not.toThrow();
+  });
+
+  it('exposes a cached access token without refreshing auth state', async () => {
+    await new FileTokenStorage(join(homeDir, 'credentials')).save('kimi-code', freshToken());
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    await expect(harness.auth.getCachedAccessToken()).resolves.toBe('oauth-access-token');
+  });
+
+  it('provisions SDK config using an existing Kimi OAuth token', async () => {
+    await new FileTokenStorage(join(homeDir, 'credentials')).save('kimi-code', freshToken());
+    const fetchMock = vi.fn<FetchMock>(
+      async (_input, _init) =>
+        new Response(
+          JSON.stringify({
+            data: [
+              {
+                id: 'kimi-for-coding',
+                context_length: 262144,
+                supports_reasoning: true,
+                supports_image_in: true,
+                supports_video_in: true,
+                display_name: 'Kimi for Coding',
+              },
+            ],
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        ),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+    const result = await harness.auth.login();
+    const config = await harness.getConfig({ reload: true });
+
+    expect(result).toMatchObject({
+      providerName: KIMI_CODE_PROVIDER_NAME,
+      ok: true,
+      defaultModel: 'kimi-code/kimi-for-coding',
+      defaultThinking: true,
+    });
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://api.kimi.com/coding/v1/models',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer oauth-access-token',
+        }),
+      }),
+    );
+    expect(config.defaultModel).toBe('kimi-code/kimi-for-coding');
+    expect(config.models?.['kimi-code/kimi-for-coding']).toMatchObject({
+      capabilities: ['thinking', 'image_in', 'video_in', 'tool_use'],
+      displayName: 'Kimi for Coding',
+    });
+    await expect(
+      resolveRuntimeProviderWithOAuth({
+        config,
+        resolveOAuthTokenProvider: () => ({
+          getAccessToken: vi.fn().mockResolvedValue('fresh-oauth-token'),
+        }),
+      }),
+    ).resolves.toMatchObject({
+      modelCapabilities: {
+        tool_use: true,
+      },
+    });
+    expect(config.providers[KIMI_CODE_PROVIDER_NAME]).toMatchObject({
+      type: 'kimi',
+      apiKey: '',
+      oauth: { storage: 'file', key: 'oauth/kimi-code' },
+    });
+    expect(config.services?.moonshotSearch?.oauth).toEqual({
+      storage: 'file',
+      key: 'oauth/kimi-code',
+    });
+  });
+
+  it('fails clearly when a configured model alias does not have max_context_size', async () => {
+    await new FileTokenStorage(join(homeDir, 'credentials')).save('kimi-code', freshToken());
+    await writeFile(
+      join(homeDir, 'config.toml'),
+      `
+default_model = "kimi-code/kimi-for-coding"
+
+[providers."managed:kimi-code"]
+type = "kimi"
+api_key = ""
+
+[models."kimi-code/kimi-for-coding"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+`,
+    );
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(
+        async () =>
+          new Response(
+            JSON.stringify({
+              data: [
+                {
+                  id: 'kimi-for-coding',
+                  context_length: 262144,
+                  supports_reasoning: true,
+                  supports_image_in: true,
+                  supports_video_in: true,
+                },
+              ],
+            }),
+            { status: 200, headers: { 'Content-Type': 'application/json' } },
+          ),
+      ),
+    );
+
+    expect(() => new KimiHarness({ homeDir, identity: TEST_IDENTITY })).toThrow(
+      /Model "kimi-code\/kimi-for-coding" must define a positive max_context_size/,
+    );
+  });
+
+  it('removes managed Kimi config on logout', async () => {
+    await new FileTokenStorage(join(homeDir, 'credentials')).save('kimi-code', freshToken());
+    await writeFile(
+      join(homeDir, 'config.toml'),
+      `
+default_model = "kimi-code/kimi-for-coding"
+
+[providers."managed:kimi-code"]
+type = "kimi"
+api_key = ""
+oauth = { storage = "file", key = "oauth/kimi-code" }
+
+[providers.custom]
+type = "kimi"
+api_key = "sk-existing"
+
+[models."kimi-code/kimi-for-coding"]
+provider = "managed:kimi-code"
+model = "kimi-for-coding"
+max_context_size = 262144
+
+[models.custom-default]
+provider = "custom"
+model = "custom-model"
+max_context_size = 1000
+
+[services.moonshot_search]
+base_url = "https://api.kimi.com/coding/v1/search"
+api_key = ""
+oauth = { storage = "file", key = "oauth/kimi-code" }
+
+[services.moonshot_fetch]
+base_url = "https://api.kimi.com/coding/v1/fetch"
+api_key = ""
+oauth = { storage = "file", key = "oauth/kimi-code" }
+`,
+    );
+
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    await expect(harness.auth.logout()).resolves.toMatchObject({
+      providerName: KIMI_CODE_PROVIDER_NAME,
+      ok: true,
+    });
+
+    const config = await harness.getConfig({ reload: true });
+    expect(config.defaultModel).toBeUndefined();
+    expect(config.providers[KIMI_CODE_PROVIDER_NAME]).toBeUndefined();
+    expect(config.providers['custom']).toMatchObject({ apiKey: 'sk-existing' });
+    expect(config.models?.['kimi-code/kimi-for-coding']).toBeUndefined();
+    expect(config.models?.['custom-default']).toMatchObject({ provider: 'custom' });
+    expect(config.services?.moonshotSearch).toBeUndefined();
+    expect(config.services?.moonshotFetch).toBeUndefined();
+    await expect(
+      new FileTokenStorage(join(homeDir, 'credentials')).load('kimi-code'),
+    ).resolves.toBeUndefined();
+
+    const text = await readFile(join(homeDir, 'config.toml'), 'utf-8');
+    expect(text).not.toContain('managed:kimi-code');
+    expect(text).not.toContain('kimi-code/kimi-for-coding');
+    expect(text).not.toContain('moonshot_search');
+  });
+
+  it('gets managed usage without host identity and sends only auth headers', async () => {
+    await new FileTokenStorage(join(homeDir, 'credentials')).save('kimi-code', freshToken());
+    const fetchMock = vi.fn<FetchMock>(
+      async (_input, _init) =>
+        new Response(
+          JSON.stringify({
+            usage: { used: 1, limit: 10, name: 'Weekly limit' },
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        ),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const harness = new KimiHarness({ homeDir });
+    const result = await harness.auth.getManagedUsage();
+
+    expect(result).toMatchObject({
+      kind: 'ok',
+      summary: { label: 'Weekly limit', used: 1, limit: 10 },
+    });
+    const init = fetchMock.mock.calls[0]?.[1] as RequestInit;
+    const headers = new Headers((init.headers ?? {}) as Record<string, string>);
+    expect(headers.get('authorization')).toBe('Bearer oauth-access-token');
+    expect(headers.get('accept')).toBe('application/json');
+    expect(headers.get('user-agent')).toBeNull();
+    expect(headers.get('x-msh-platform')).toBeNull();
+  });
+
+  it('submitFeedback maps camelCase input to snake_case body and posts with bearer auth', async () => {
+    await new FileTokenStorage(join(homeDir, 'credentials')).save('kimi-code', freshToken());
+    const fetchMock = vi.fn<FetchMock>(async () => new Response('', { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const harness = new KimiHarness({ homeDir });
+    const result = await harness.auth.submitFeedback({
+      content: 'great tool',
+      sessionId: 'sess-42',
+      version: 'kimi-code-0.1.1',
+      os: 'Darwin 25.3.0',
+      model: 'kimi-code/kimi-for-coding',
+    });
+
+    expect(result).toEqual({ kind: 'ok' });
+
+    const calls = fetchMock.mock.calls as unknown as [string, RequestInit?][];
+    const [url, init] = calls[0]!;
+    expect(url).toBe('https://api.kimi.com/coding/v1/feedback');
+    expect(init?.method).toBe('POST');
+
+    const headers = new Headers((init?.headers ?? {}) as Record<string, string>);
+    expect(headers.get('authorization')).toBe('Bearer oauth-access-token');
+    expect(headers.get('content-type')).toBe('application/json');
+
+    expect(JSON.parse(init?.body as string)).toEqual({
+      session_id: 'sess-42',
+      content: 'great tool',
+      version: 'kimi-code-0.1.1',
+      os: 'Darwin 25.3.0',
+      model: 'kimi-code/kimi-for-coding',
+    });
+  });
+
+  it('submitFeedback surfaces HTTP errors without throwing', async () => {
+    await new FileTokenStorage(join(homeDir, 'credentials')).save('kimi-code', freshToken());
+    vi.stubGlobal(
+      'fetch',
+      vi.fn<FetchMock>(async () => new Response('nope', { status: 401 })),
+    );
+
+    const harness = new KimiHarness({ homeDir });
+    const result = await harness.auth.submitFeedback({
+      content: 'x',
+      sessionId: 's',
+      version: 'kimi-code-0.0.0',
+      os: 'Darwin 25.3.0',
+      model: null,
+    });
+
+    expect(result.kind).toBe('error');
+    if (result.kind !== 'error') return;
+    expect(result.status).toBe(401);
+  });
+});
diff --git a/packages/node-sdk/test/config.test.ts b/packages/node-sdk/test/config.test.ts
new file mode 100644
index 000000000..bc4956fc5
--- /dev/null
+++ b/packages/node-sdk/test/config.test.ts
@@ -0,0 +1,307 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { KimiError, KimiHarness } from '#/index';
+
+import {
+  parseConfigString,
+  readConfigFile,
+  writeConfigFile,
+} from '../../agent-core/src/config';
+import { TEST_IDENTITY } from './test-identity';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'kimi-sdk-config-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+const COMPLETE_TOML = `
+default_model = "kimi-for-coding"
+default_thinking = false
+default_permission_mode = "auto"
+skip_afk_prompt_injection = false
+default_plan_mode = false
+default_editor = ""
+theme = "dark"
+show_thinking_stream = true
+merge_all_available_skills = true
+extra_skill_dirs = ["~/team-skills", ".agents/team-skills"]
+
+[providers.kimi-for-coding]
+type = "kimi"
+base_url = "https://api.kimi.com/coding/v1"
+api_key = "sk-xxx"
+custom_headers = { "X-Custom-Header" = "value" }
+
+[providers.kimi-for-coding.env]
+GOOGLE_CLOUD_PROJECT = "project-1"
+
+[models.kimi-for-coding]
+provider = "kimi-for-coding"
+model = "kimi-for-coding"
+max_context_size = 262144
+capabilities = ["image_in", "thinking", "video_in"]
+display_name = "Kimi for Coding"
+
+[loop_control]
+max_steps_per_turn = 1000
+max_retries_per_step = 3
+max_ralph_iterations = 0
+reserved_context_size = 50000
+compaction_trigger_ratio = 0.85
+
+[background]
+max_running_tasks = 4
+keep_alive_on_exit = false
+kill_grace_period_ms = 2000
+agent_task_timeout_s = 900
+print_wait_ceiling_s = 3600
+
+[services.moonshot_search]
+base_url = "https://api.kimi.com/coding/v1/search"
+api_key = "sk-search"
+custom_headers = { "X-Search" = "1" }
+
+[services.moonshot_fetch]
+base_url = "https://api.kimi.com/coding/v1/fetch"
+api_key = "sk-fetch"
+
+[notifications]
+claim_stale_after_ms = 15000
+`;
+
+describe('SDK config TOML', () => {
+  it('parses the documented config shape and keeps TUI-only fields in raw', () => {
+    const config = parseConfigString(COMPLETE_TOML, 'complete.toml');
+
+    expect(config.defaultModel).toBe('kimi-for-coding');
+    expect(config.defaultThinking).toBe(false);
+    expect(config.defaultPermissionMode).toBe('auto');
+    expect(config.defaultPlanMode).toBe(false);
+    expect(config.mergeAllAvailableSkills).toBe(true);
+    expect(config.extraSkillDirs).toEqual(['~/team-skills', '.agents/team-skills']);
+
+    const provider = config.providers['kimi-for-coding'];
+    expect(provider).toMatchObject({
+      type: 'kimi',
+      baseUrl: 'https://api.kimi.com/coding/v1',
+      apiKey: 'sk-xxx',
+      customHeaders: { 'X-Custom-Header': 'value' },
+      env: { GOOGLE_CLOUD_PROJECT: 'project-1' },
+    });
+
+    expect(config.models?.['kimi-for-coding']).toMatchObject({
+      provider: 'kimi-for-coding',
+      model: 'kimi-for-coding',
+      maxContextSize: 262144,
+      capabilities: ['image_in', 'thinking', 'video_in'],
+      displayName: 'Kimi for Coding',
+    });
+
+    expect(config.loopControl).toEqual({
+      maxStepsPerTurn: 1000,
+      maxRetriesPerStep: 3,
+      maxRalphIterations: 0,
+      reservedContextSize: 50000,
+      compactionTriggerRatio: 0.85,
+    });
+    expect(config.background).toEqual({
+      maxRunningTasks: 4,
+      keepAliveOnExit: false,
+      killGracePeriodMs: 2000,
+      agentTaskTimeoutS: 900,
+      printWaitCeilingS: 3600,
+    });
+    expect(config.services?.moonshotSearch?.customHeaders).toEqual({ 'X-Search': '1' });
+    expect(config.services?.moonshotFetch?.apiKey).toBe('sk-fetch');
+
+    expect('theme' in config).toBe(false);
+    expect(config.raw?.['theme']).toBe('dark');
+    expect(config.raw?.['skip_afk_prompt_injection']).toBe(false);
+    expect(config.raw?.['show_thinking_stream']).toBe(true);
+    expect(config.raw?.['notifications']).toEqual({ claim_stale_after_ms: 15000 });
+  });
+
+  it('writes typed fields in snake_case and preserves unknown raw sections', async () => {
+    const dir = await makeTempDir();
+    const configPath = join(dir, 'config.toml');
+    const config = parseConfigString(COMPLETE_TOML, configPath);
+
+    await writeConfigFile(configPath, {
+      ...config,
+      defaultModel: 'kimi-for-coding',
+      loopControl: {
+        ...config.loopControl,
+        maxStepsPerTurn: 42,
+      },
+    });
+
+    const text = await readFile(configPath, 'utf-8');
+    expect(text).toContain('default_model = "kimi-for-coding"');
+    expect(text).toContain('default_permission_mode = "auto"');
+    expect(text).toContain('extra_skill_dirs = [ "~/team-skills", ".agents/team-skills" ]');
+    expect(text).not.toContain('default_yolo');
+    expect(text).toContain('max_steps_per_turn = 42');
+    expect(text).toContain('display_name = "Kimi for Coding"');
+    expect(text).toContain('GOOGLE_CLOUD_PROJECT = "project-1"');
+    expect(text).toContain('claim_stale_after_ms = 15000');
+    expect(text).toContain('theme = "dark"');
+
+    const reloaded = readConfigFile(configPath);
+    expect(reloaded.loopControl?.maxStepsPerTurn).toBe(42);
+    expect(reloaded.raw?.['theme']).toBe('dark');
+  });
+
+  it('accepts camelCase aliases without keeping unknown fields in typed config', () => {
+    const config = parseConfigString(`
+defaultModel = "camel-model"
+
+[providers.local]
+type = "openai"
+baseUrl = "https://example.test/v1"
+apiKey = "sk-test"
+unsupported_provider_field = "raw-only"
+
+[models.camel-model]
+provider = "local"
+model = "gpt-test"
+maxContextSize = 128000
+displayName = "Camel Model"
+custom_model_field = "raw-only"
+
+[services.moonshotSearch]
+baseUrl = "https://example.test/search"
+apiKey = "sk-search"
+
+[loopControl]
+maxStepsPerRun = 7
+
+[background]
+maxRunningTasks = 2
+`);
+
+    expect(config.defaultModel).toBe('camel-model');
+    expect(config.providers['local']).toMatchObject({
+      type: 'openai',
+      baseUrl: 'https://example.test/v1',
+      apiKey: 'sk-test',
+    });
+    expect(config.models?.['camel-model']).toMatchObject({
+      maxContextSize: 128000,
+      displayName: 'Camel Model',
+    });
+    expect(config.services?.moonshotSearch).toMatchObject({
+      baseUrl: 'https://example.test/search',
+      apiKey: 'sk-search',
+    });
+    expect(config.loopControl?.maxStepsPerTurn).toBe(7);
+    expect(config.background?.maxRunningTasks).toBe(2);
+
+    expect('unsupportedProviderField' in config.providers['local']!).toBe(false);
+    expect('customModelField' in config.models!['camel-model']!).toBe(false);
+
+    const rawProviders = config.raw?.['providers'] as Record<string, Record<string, unknown>>;
+    const rawModels = config.raw?.['models'] as Record<string, Record<string, unknown>>;
+    expect(rawProviders['local']?.['unsupported_provider_field']).toBe('raw-only');
+    expect(rawModels['camel-model']?.['custom_model_field']).toBe('raw-only');
+  });
+});
+
+describe('KimiHarness config API', () => {
+  it('loads default config when missing and deep-merges setConfig patches from disk', async () => {
+    const homeDir = await makeTempDir();
+    const configPath = join(homeDir, 'config.toml');
+    await writeFile(configPath, COMPLETE_TOML, 'utf-8');
+
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    await harness.setConfig({
+      providers: {
+        'kimi-for-coding': {
+          apiKey: 'sk-updated',
+        },
+      },
+      services: {
+        moonshotSearch: {
+          apiKey: 'sk-search-updated',
+        },
+      },
+    });
+
+    const config = await harness.getConfig({ reload: true });
+    expect(config.providers['kimi-for-coding']).toMatchObject({
+      type: 'kimi',
+      baseUrl: 'https://api.kimi.com/coding/v1',
+      apiKey: 'sk-updated',
+      env: { GOOGLE_CLOUD_PROJECT: 'project-1' },
+    });
+    expect(config.services?.moonshotSearch?.apiKey).toBe('sk-search-updated');
+    expect(config.raw?.['theme']).toBe('dark');
+
+    const text = await readFile(configPath, 'utf-8');
+    expect(text).toContain('theme = "dark"');
+    expect(text).toContain('GOOGLE_CLOUD_PROJECT = "project-1"');
+    expect(text).toContain('claim_stale_after_ms = 15000');
+  });
+
+  it('does not write invalid config patches', async () => {
+    const homeDir = await makeTempDir();
+    const configPath = join(homeDir, 'config.toml');
+    await writeFile(configPath, COMPLETE_TOML, 'utf-8');
+    const before = await readFile(configPath, 'utf-8');
+
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    const setInvalidConfig = harness.setConfig({
+      providers: {
+        bad: {
+          type: 'not-a-provider',
+        },
+      },
+    } as never);
+
+    await expect(setInvalidConfig).rejects.toBeInstanceOf(KimiError);
+    await expect(setInvalidConfig).rejects.toMatchObject({
+      code: 'config.invalid',
+    } satisfies Partial<KimiError>);
+
+    await expect(readFile(configPath, 'utf-8')).resolves.toBe(before);
+  });
+
+  it('uses default config when the config file is absent', async () => {
+    const homeDir = await makeTempDir();
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    await expect(harness.getConfig()).resolves.toEqual({ providers: {} });
+  });
+
+  it('can create the default config scaffold without selecting a model', async () => {
+    const homeDir = await makeTempDir();
+    const configPath = join(homeDir, 'config.toml');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    await harness.ensureConfigFile();
+
+    const text = await readFile(configPath, 'utf-8');
+    expect(text).toContain('Runtime settings for Kimi Code.');
+    expect(text).not.toMatch(/^default_thinking =/m);
+    expect(text).not.toMatch(/^default_model =/m);
+
+    const config = await harness.getConfig({ reload: true });
+    expect(config.providers).toEqual({});
+    expect(config.defaultModel).toBeUndefined();
+    expect(config.defaultThinking).toBeUndefined();
+  });
+});
diff --git a/packages/node-sdk/test/create-session-transport.test.ts b/packages/node-sdk/test/create-session-transport.test.ts
new file mode 100644
index 000000000..aa60174ea
--- /dev/null
+++ b/packages/node-sdk/test/create-session-transport.test.ts
@@ -0,0 +1,510 @@
+import { existsSync } from 'node:fs';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { KimiHarness } from '#/index';
+import type { KimiError } from '#/index';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { waitForAgentWireEvent } from './session-runtime-helpers';
+import { recordingTelemetry, type TelemetryRecord } from './telemetry';
+import { TEST_IDENTITY } from './test-identity';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'kimi-sdk-create-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+async function writeTestModelConfig(homeDir: string, modelName = 'kimi-test-model'): Promise<void> {
+  await writeFile(
+    join(homeDir, 'config.toml'),
+    `
+[providers.local]
+type = "kimi"
+base_url = "https://example.test/v1"
+api_key = "sk-test"
+
+[models."${modelName}"]
+provider = "local"
+model = "${modelName}"
+max_context_size = 1000
+`,
+    'utf-8',
+  );
+}
+
+describe('KimiHarness.createSession transport link', () => {
+  it('emits session_started with client attribution when a session is opened', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const records: TelemetryRecord[] = [];
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+      telemetry: recordingTelemetry(records),
+    });
+
+    try {
+      const session = await harness.createSession({
+        id: 'ses_session_started',
+        workDir,
+      });
+      await harness.resumeSession({ id: session.id });
+
+      expect(records).toContainEqual({
+        event: 'session_started',
+        sessionId: session.id,
+        properties: {
+          client_name: 'kimi-code-cli',
+          client_version: '0.0.0-test',
+          ui_mode: 'shell',
+          resumed: false,
+        },
+      });
+      expect(records.filter((record) => record.event === 'session_started')).toHaveLength(1);
+      expect(records).toContainEqual({
+        event: 'session_new',
+        sessionId: session.id,
+        properties: undefined,
+      });
+
+      await session.close();
+      await harness.resumeSession({ id: session.id });
+
+      expect(records.filter((record) => record.event === 'session_started')).toHaveLength(2);
+      expect(records).toContainEqual({
+        event: 'session_started',
+        sessionId: session.id,
+        properties: {
+          client_name: 'kimi-code-cli',
+          client_version: '0.0.0-test',
+          ui_mode: 'shell',
+          resumed: true,
+        },
+      });
+      expect(records).toContainEqual({
+        event: 'session_resume',
+        sessionId: session.id,
+        properties: undefined,
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('uses the configured UI mode for session_started attribution', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const records: TelemetryRecord[] = [];
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+      telemetry: recordingTelemetry(records),
+      uiMode: 'print',
+    });
+
+    try {
+      const session = await harness.createSession({
+        id: 'ses_session_started_print',
+        workDir,
+      });
+
+      expect(records).toContainEqual({
+        event: 'session_started',
+        sessionId: session.id,
+        properties: {
+          client_name: 'kimi-code-cli',
+          client_version: '0.0.0-test',
+          ui_mode: 'print',
+          resumed: false,
+        },
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('emits session_fork with the forked session context', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const records: TelemetryRecord[] = [];
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+      telemetry: recordingTelemetry(records),
+    });
+
+    try {
+      const source = await harness.createSession({
+        id: 'ses_fork_source',
+        workDir,
+      });
+      const forked = await harness.forkSession({
+        id: source.id,
+        forkId: 'ses_fork_child',
+        title: 'Forked child',
+      });
+
+      expect(forked.id).toBe('ses_fork_child');
+      expect(records).toContainEqual({
+        event: 'session_started',
+        sessionId: forked.id,
+        properties: {
+          client_name: 'kimi-code-cli',
+          client_version: '0.0.0-test',
+          ui_mode: 'shell',
+          resumed: true,
+        },
+      });
+      expect(records).toContainEqual({
+        event: 'session_fork',
+        sessionId: forked.id,
+        properties: undefined,
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('does not invent client attribution without host identity', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const records: TelemetryRecord[] = [];
+    const harness = new KimiHarness({
+      homeDir,
+      telemetry: recordingTelemetry(records),
+    });
+
+    try {
+      const session = await harness.createSession({
+        id: 'ses_session_started_shell',
+        workDir,
+      });
+
+      expect(records).toContainEqual({
+        event: 'session_started',
+        sessionId: session.id,
+        properties: {
+          client_name: null,
+          client_version: null,
+          ui_mode: 'shell',
+          resumed: false,
+        },
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('creates metadata and keeps the session active in the harness', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    await writeTestModelConfig(homeDir);
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      const session = await harness.createSession({
+        id: 'ses_transport_link',
+        workDir,
+        model: 'kimi-test-model',
+      });
+
+      expect(session.id).toBe('ses_transport_link');
+      expect(session.workDir).toBe(workDir);
+      await expect(session.getStatus()).resolves.toMatchObject({ model: 'kimi-test-model' });
+      expect(harness.sessions.get(session.id)).toBe(session);
+      const configEvent = await waitForAgentWireEvent(
+        homeDir,
+        session.id,
+        'config.update',
+        (event) => event['modelAlias'] === 'kimi-test-model',
+      );
+      expect(configEvent).toMatchObject({
+        type: 'config.update',
+        modelAlias: 'kimi-test-model',
+      });
+      expect(configEvent).not.toHaveProperty('provider');
+
+      const summaries = await harness.listSessions({ workDir });
+      const summary = summaries.find((item) => item.id === session.id);
+      expect(summary?.sessionDir).not.toBe(join(homeDir, 'sessions', session.id));
+      expect(summary?.sessionDir).toContain(join(homeDir, 'sessions'));
+      expect(existsSync(join(summary!.sessionDir, 'state.json'))).toBe(true);
+      expect(await readFile(join(homeDir, 'session_index.jsonl'), 'utf-8')).toContain(session.id);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('accepts configured model aliases while creating the core session', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    await writeFile(
+      join(homeDir, 'config.toml'),
+      `
+default_model = "alias-model"
+
+[providers.local]
+type = "openai"
+base_url = "https://example.test/v1"
+api_key = "sk-test"
+
+[models.alias-model]
+provider = "local"
+model = "real-model"
+max_context_size = 1000
+
+[thinking]
+effort = "medium"
+`,
+      'utf-8',
+    );
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_alias_model', workDir });
+      expect(session.id).toBe('ses_alias_model');
+      await expect(session.getStatus()).resolves.toMatchObject({ model: 'alias-model' });
+      expect(harness.sessions.get(session.id)).toBe(session);
+      const configEvent = await waitForAgentWireEvent(
+        homeDir,
+        session.id,
+        'config.update',
+        (event) => event['modelAlias'] === 'alias-model',
+      );
+      expect(configEvent).toMatchObject({
+        type: 'config.update',
+        modelAlias: 'alias-model',
+      });
+      expect(configEvent).not.toHaveProperty('provider');
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('does not require provider config or API keys before prompt is implemented', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_empty_config', workDir });
+      expect(session.id).toBe('ses_empty_config');
+      expect((await session.getStatus()).model).toBeUndefined();
+      expect(harness.sessions.get(session.id)).toBe(session);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('requires a non-empty workDir on createSession', async () => {
+    const homeDir = await makeTempDir();
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      await expect(
+        harness.createSession({ id: 'ses_missing_workdir' } as never),
+      ).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'request.work_dir_required',
+      } satisfies Partial<KimiError>);
+      await expect(
+        harness.createSession({ id: 'ses_blank_workdir', workDir: '   ' }),
+      ).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'request.work_dir_required',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('does not persist a session record when MCP config validation fails', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    // Project-local mcp.json is intentionally ignored, so plant the malformed
+    // file under the user home dir where the loader actually reads from.
+    await writeFile(join(homeDir, 'mcp.json'), '{not json}', 'utf-8');
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      await expect(
+        harness.createSession({ id: 'ses_bad_mcp_config', workDir }),
+      ).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'config.invalid',
+      });
+      expect(await harness.listSessions({ workDir })).toEqual([]);
+      expect(existsSync(join(homeDir, 'session_index.jsonl'))).toBe(false);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('closes active runtime handles through closeSession, session.close, and close', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    await writeTestModelConfig(homeDir);
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    const first = await harness.createSession({
+      id: 'ses_close_one',
+      workDir,
+      model: 'kimi-test-model',
+    });
+    const second = await harness.createSession({
+      id: 'ses_close_two',
+      workDir,
+      model: 'kimi-test-model',
+    });
+    expect(coreSessionIds(harness)).toEqual([first.id, second.id]);
+
+    await harness.closeSession(first.id);
+    expect(harness.getSession(first.id)).toBeUndefined();
+    expect(coreSessionIds(harness)).toEqual([second.id]);
+
+    await second.close();
+    expect(harness.getSession(second.id)).toBeUndefined();
+    expect(coreSessionIds(harness)).toEqual([]);
+
+    await harness.close();
+    expect(harness.sessions.size).toBe(0);
+    expect(coreSessionIds(harness)).toEqual([]);
+  });
+
+  it('rejects explicitly empty model names', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      await expect(
+        harness.createSession({ id: 'ses_empty_model', workDir, model: '   ' }),
+      ).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'model.config_invalid',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('applies initial thinking and permission runtime options', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      const session = await harness.createSession({
+        id: 'ses_initial_runtime_options',
+        workDir,
+        thinking: 'low',
+        permission: 'auto',
+      });
+
+      await expect(
+        waitForAgentWireEvent(
+          homeDir,
+          session.id,
+          'config.update',
+          (event) => event['thinkingLevel'] === 'low',
+        ),
+      ).resolves.toMatchObject({
+        type: 'config.update',
+        thinkingLevel: 'low',
+      });
+      await expect(
+        waitForAgentWireEvent(
+          homeDir,
+          session.id,
+          'permission.set_mode',
+          (event) => event['mode'] === 'auto',
+        ),
+      ).resolves.toMatchObject({
+        type: 'permission.set_mode',
+        mode: 'auto',
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('applies configured default permission mode to new sessions', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    await writeFile(join(homeDir, 'config.toml'), 'default_permission_mode = "auto"\n', 'utf-8');
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      const session = await harness.createSession({
+        id: 'ses_default_permission_mode',
+        workDir,
+      });
+
+      await expect(session.getStatus()).resolves.toMatchObject({ permission: 'auto' });
+      await expect(
+        waitForAgentWireEvent(
+          homeDir,
+          session.id,
+          'permission.set_mode',
+          (event) => event['mode'] === 'auto',
+        ),
+      ).resolves.toMatchObject({
+        type: 'permission.set_mode',
+        mode: 'auto',
+      });
+
+      const explicit = await harness.createSession({
+        id: 'ses_default_permission_explicit_override',
+        workDir,
+        permission: 'manual',
+      });
+      await expect(explicit.getStatus()).resolves.toMatchObject({ permission: 'manual' });
+    } finally {
+      await harness.close();
+    }
+  });
+});
+
+function coreSessionIds(harness: KimiHarness): readonly string[] {
+  const core = (
+    harness as unknown as {
+      readonly rpc: { readonly core: { readonly sessions: ReadonlyMap<string, unknown> } };
+    }
+  ).rpc.core;
+  return Array.from(core.sessions.keys()).toSorted();
+}
diff --git a/packages/node-sdk/test/export-session.test.ts b/packages/node-sdk/test/export-session.test.ts
new file mode 100644
index 000000000..be3e0007c
--- /dev/null
+++ b/packages/node-sdk/test/export-session.test.ts
@@ -0,0 +1,310 @@
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import * as zlib from 'node:zlib';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  KimiError,
+  KimiHarness,
+  type SessionSummary,
+} from '#/index';
+import { resolveGlobalLogPath } from '../../agent-core/src/logging/logger';
+import { exportSessionDirectory } from '../../agent-core/src/session/export';
+import { recordingTelemetry, type TelemetryRecord } from './telemetry';
+import { TEST_IDENTITY } from './test-identity';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'kimi-sdk-export-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function readZipEntries(buf: Buffer): Map<string, Buffer> {
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 65557); i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) {
+      eocd = i;
+      break;
+    }
+  }
+  if (eocd === -1) throw new Error('zip eocd not found');
+
+  const entryCount = buf.readUInt16LE(eocd + 10);
+  const cdOffset = buf.readUInt32LE(eocd + 16);
+  const entries = new Map<string, Buffer>();
+  let pos = cdOffset;
+
+  for (let i = 0; i < entryCount; i++) {
+    if (buf.readUInt32LE(pos) !== 0x02014b50) {
+      throw new Error(`bad central-directory entry at ${String(pos)}`);
+    }
+    const method = buf.readUInt16LE(pos + 10);
+    const compressedSize = buf.readUInt32LE(pos + 20);
+    const fnameLen = buf.readUInt16LE(pos + 28);
+    const extraLen = buf.readUInt16LE(pos + 30);
+    const commentLen = buf.readUInt16LE(pos + 32);
+    const lfhOffset = buf.readUInt32LE(pos + 42);
+    const filename = buf.toString('utf8', pos + 46, pos + 46 + fnameLen);
+
+    if (buf.readUInt32LE(lfhOffset) !== 0x04034b50) {
+      throw new Error(`bad local-file-header at ${String(lfhOffset)}`);
+    }
+    const lfhFnameLen = buf.readUInt16LE(lfhOffset + 26);
+    const lfhExtraLen = buf.readUInt16LE(lfhOffset + 28);
+    const dataStart = lfhOffset + 30 + lfhFnameLen + lfhExtraLen;
+    const compressed = buf.subarray(dataStart, dataStart + compressedSize);
+    const data = method === 0 ? compressed : method === 8 ? zlib.inflateRawSync(compressed) : null;
+    if (data === null) throw new Error(`unsupported compression method: ${String(method)}`);
+    entries.set(filename, data);
+    pos += 46 + fnameLen + extraLen + commentLen;
+  }
+
+  return entries;
+}
+
+function makeSummary(input: {
+  readonly id: string;
+  readonly sessionDir: string;
+  readonly workDir: string;
+  readonly title?: string | undefined;
+}): SessionSummary {
+  return {
+    id: input.id,
+    sessionDir: input.sessionDir,
+    workDir: input.workDir,
+    createdAt: 1,
+    updatedAt: 2,
+    title: input.title,
+  };
+}
+
+describe('exportSessionDirectory', () => {
+  it('writes a zip with manifest and every session file', async () => {
+    const tmp = await makeTempDir();
+    const sid = 'ses_export_test';
+    const workDir = join(tmp, 'work');
+    const sessionDir = join(tmp, 'sessions', sid);
+    await mkdir(join(sessionDir, 'subagents'), { recursive: true });
+    await writeFile(
+      join(sessionDir, 'wire.jsonl'),
+      [
+        JSON.stringify({
+          type: 'turn_begin',
+          time: Date.parse('2026-04-18T10:00:00Z'),
+          user_input: 'hello',
+        }),
+        JSON.stringify({
+          type: 'turn_end',
+          time: Date.parse('2026-04-18T10:00:03Z'),
+        }),
+        '',
+      ].join('\n'),
+      'utf-8',
+    );
+    await writeFile(join(sessionDir, 'state.json'), JSON.stringify({ session_id: sid }), 'utf-8');
+    await writeFile(join(sessionDir, 'subagents', 'a.txt'), 'child', 'utf-8');
+
+    const outputPath = join(tmp, 'out.zip');
+    const result = await exportSessionDirectory({
+      request: { sessionId: sid, outputPath, version: '1.0.0-test' },
+      summary: makeSummary({
+        id: sid,
+        sessionDir,
+        workDir,
+        title: 'Export Test',
+      }),
+    });
+
+    expect(result.zipPath).toBe(outputPath);
+    expect(result.sessionDir).toBe(sessionDir);
+    expect(result.entries).toEqual([
+      'manifest.json',
+      'state.json',
+      'subagents/a.txt',
+      'wire.jsonl',
+    ]);
+    expect(result.manifest).toMatchObject({
+      sessionId: sid,
+      wireProtocolVersion: '1.0',
+      sessionFirstActivity: '2026-04-18T10:00:00.000Z',
+      sessionLastActivity: '2026-04-18T10:00:03.000Z',
+      title: 'Export Test',
+      workspaceDir: workDir,
+      kimiCodeVersion: '1.0.0-test',
+    });
+    expect(result.manifest.exportedAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+
+    const entries = readZipEntries(await readFile(outputPath));
+    expect(entries.has('manifest.json')).toBe(true);
+    expect(entries.get('state.json')?.toString('utf-8')).toContain(sid);
+    expect(entries.get('subagents/a.txt')?.toString('utf-8')).toBe('child');
+    expect([...entries.keys()].some((name) => name.includes(tmp))).toBe(false);
+
+    const manifest = JSON.parse(entries.get('manifest.json')!.toString('utf-8')) as {
+      sessionId: string;
+      title: string;
+      workspaceDir: string;
+    };
+    expect(manifest.sessionId).toBe(sid);
+    expect(manifest.title).toBe('Export Test');
+    expect(manifest.workspaceDir).toBe(workDir);
+  });
+
+  it('uses the default output path when outputPath is omitted', async () => {
+    const tmp = await makeTempDir();
+    const sid = 'session_default_output';
+    const sessionDir = join(tmp, 'sessions', sid);
+    await mkdir(sessionDir, { recursive: true });
+    await writeFile(join(sessionDir, 'state.json'), '{}', 'utf-8');
+
+    const result = await exportSessionDirectory({
+      request: { sessionId: sid, version: '1.0.0-test' },
+      summary: makeSummary({ id: sid, sessionDir, workDir: tmp }),
+    });
+
+    const expectedPath = resolve(`${sid}.zip`);
+    expect(result.zipPath).toBe(expectedPath);
+    expect(existsSync(result.zipPath)).toBe(true);
+    await rm(expectedPath, { force: true });
+  });
+
+  it('omits global log manifest path when the global log cannot be bundled', async () => {
+    const tmp = await makeTempDir();
+    const homeDir = join(tmp, 'home');
+    const sid = 'ses_unreadable_global_log';
+    const sessionDir = join(tmp, 'sessions', sid);
+    await mkdir(sessionDir, { recursive: true });
+    await writeFile(join(sessionDir, 'state.json'), '{}', 'utf-8');
+    await mkdir(resolveGlobalLogPath(homeDir), { recursive: true });
+
+    const outputPath = join(tmp, 'unreadable-global.zip');
+    const result = await exportSessionDirectory({
+      request: { sessionId: sid, outputPath, includeGlobalLog: true, version: '1.0.0-test' },
+      summary: makeSummary({ id: sid, sessionDir, workDir: tmp }),
+      homeDir,
+    });
+
+    expect(result.manifest.globalLogPath).toBeUndefined();
+    expect(result.entries).not.toContain('logs/global/kimi-code.log');
+    const entries = readZipEntries(await readFile(outputPath));
+    expect(entries.has('logs/global/kimi-code.log')).toBe(false);
+    const manifest = JSON.parse(entries.get('manifest.json')!.toString('utf-8')) as Record<
+      string,
+      unknown
+    >;
+    expect(manifest['globalLogPath']).toBeUndefined();
+  });
+
+  it('supports relative outputPath and creates parent directories', async () => {
+    const tmp = await makeTempDir();
+    const sid = 'ses_relative_output';
+    const sessionDir = join(tmp, 'sessions', sid);
+    await mkdir(sessionDir, { recursive: true });
+    await writeFile(join(sessionDir, 'state.json'), '{}', 'utf-8');
+
+    const outputPath = join(tmp, 'exports/out.zip');
+    const result = await exportSessionDirectory({
+      request: { sessionId: sid, outputPath, version: '1.0.0-test' },
+      summary: makeSummary({ id: sid, sessionDir, workDir: tmp }),
+    });
+
+    expect(result.zipPath).toBe(outputPath);
+    expect(existsSync(result.zipPath)).toBe(true);
+  });
+
+  it('exports sessions without wire.jsonl and omits activity fields', async () => {
+    const tmp = await makeTempDir();
+    const sid = 'ses_no_wire';
+    const sessionDir = join(tmp, 'sessions', sid);
+    await mkdir(sessionDir, { recursive: true });
+    await writeFile(join(sessionDir, 'state.json'), '{}', 'utf-8');
+
+    const result = await exportSessionDirectory({
+      request: { sessionId: sid, version: '1.0.0-test' },
+      summary: makeSummary({ id: sid, sessionDir, workDir: tmp }),
+    });
+
+    expect(result.manifest.sessionFirstActivity).toBeUndefined();
+    expect(result.manifest.sessionLastActivity).toBeUndefined();
+    await rm(resolve(`${sid}.zip`), { force: true });
+  });
+
+  it('rejects empty or missing session directories', async () => {
+    const tmp = await makeTempDir();
+    const sid = 'ses_empty';
+    const sessionDir = join(tmp, 'sessions', sid);
+    await mkdir(sessionDir, { recursive: true });
+
+    await expect(
+      exportSessionDirectory({
+        request: { sessionId: sid, version: '1.0.0-test' },
+        summary: makeSummary({ id: sid, sessionDir, workDir: tmp }),
+      }),
+    ).rejects.toMatchObject({
+      name: 'KimiError',
+      code: 'session.export_not_found',
+    } satisfies Partial<KimiError>);
+  });
+});
+
+describe('KimiHarness.exportSession', () => {
+  it('exports a created session through the public Harness API', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const records: TelemetryRecord[] = [];
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+      telemetry: recordingTelemetry(records),
+    });
+
+    const session = await harness.createSession({
+      id: 'ses_harness_export',
+      workDir,
+    });
+    const sessionDir = (await harness.listSessions({ workDir })).find(
+      (item) => item.id === session.id,
+    )!.sessionDir;
+    await writeFile(join(sessionDir, 'wire.jsonl'), '{}\n', 'utf-8');
+    await mkdir(join(sessionDir, 'subagents'), { recursive: true });
+    await writeFile(join(sessionDir, 'subagents', 'demo.txt'), 'demo', 'utf-8');
+
+    const outputPath = join(workDir, 'export.zip');
+    const result = await harness.exportSession({ id: session.id, outputPath, version: '1.0.0-test' });
+
+    expect(result.zipPath).toBe(outputPath);
+    expect(result.entries).toContain('manifest.json');
+    expect(result.entries).toContain('state.json');
+    expect(result.entries).toContain('wire.jsonl');
+    expect(result.entries).toContain('subagents/demo.txt');
+    expect(result.manifest.sessionId).toBe(session.id);
+    expect(records).toContainEqual({
+      event: 'export',
+      sessionId: session.id,
+      properties: undefined,
+    });
+  });
+
+  it('rejects missing session ids', async () => {
+    const homeDir = await makeTempDir();
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    const missingExport = harness.exportSession({ id: 'ses_missing', version: '1.0.0-test' });
+    await expect(missingExport).rejects.toBeInstanceOf(KimiError);
+    await expect(missingExport).rejects.toMatchObject({
+      code: 'session.not_found',
+      details: { sessionId: 'ses_missing' },
+    } satisfies Partial<KimiError>);
+  });
+});
diff --git a/packages/node-sdk/test/list-sessions.test.ts b/packages/node-sdk/test/list-sessions.test.ts
new file mode 100644
index 000000000..63de606d7
--- /dev/null
+++ b/packages/node-sdk/test/list-sessions.test.ts
@@ -0,0 +1,295 @@
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm, utimes, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { KimiHarness } from '#/index';
+import type { KimiError } from '#/index';
+
+import {
+  SessionStore,
+  encodeWorkDirKey,
+  sessionIndexPath,
+} from '../../agent-core/src/session/store';
+import { TEST_IDENTITY } from './test-identity';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'kimi-sdk-list-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+async function writeSessionState(
+  sessionDir: string,
+  state: Record<string, unknown>,
+): Promise<string> {
+  const statePath = join(sessionDir, 'state.json');
+  await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf-8');
+  return statePath;
+}
+
+describe('SessionStore.list', () => {
+  it('returns an empty array when the workDir bucket does not exist', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const store = new SessionStore(homeDir);
+
+    await expect(store.list({ workDir })).resolves.toEqual([]);
+  });
+
+  it('creates workDir-scoped session directories and a root session index', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const store = new SessionStore(homeDir);
+
+    const summary = await store.create({ id: 'ses_list_full', workDir });
+
+    expect(summary).toMatchObject({
+      id: 'ses_list_full',
+      workDir,
+      title: undefined,
+    });
+    expect(summary.sessionDir).not.toBe(join(homeDir, 'sessions', 'ses_list_full'));
+    expect(basename(summary.sessionDir)).toBe('ses_list_full');
+    const workdirKey = basename(dirname(summary.sessionDir));
+    expect(workdirKey).toBe(encodeWorkDirKey(workDir));
+    expect(workdirKey.length).toBeLessThan(70);
+    expect(existsSync(join(summary.sessionDir, 'state.json'))).toBe(false);
+
+    const indexRaw = await readFile(sessionIndexPath(homeDir), 'utf-8');
+    expect(indexRaw).toContain('"sessionId":"ses_list_full"');
+    expect(indexRaw).toContain(summary.sessionDir);
+    expect(indexRaw).toContain(`"workDir":"${workDir}"`);
+  });
+
+  it('forks a session directory and rewrites fork metadata', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const store = new SessionStore(homeDir);
+
+    const source = await store.create({ id: 'ses_fork_source', workDir });
+    const sourceAgentDir = join(source.sessionDir, 'agents', 'main');
+    await mkdir(sourceAgentDir, { recursive: true });
+    await writeFile(join(sourceAgentDir, 'wire.jsonl'), '{"type":"context.clear"}\n', 'utf-8');
+    await writeSessionState(source.sessionDir, {
+      createdAt: '2030-01-01T00:00:00.000Z',
+      updatedAt: '2030-01-01T00:00:00.000Z',
+      title: 'Source title',
+      isCustomTitle: true,
+      agents: {
+        main: {
+          homedir: sourceAgentDir,
+          type: 'main',
+        },
+      },
+      custom: {
+        source: true,
+      },
+    });
+
+    const fork = await store.fork({
+      sourceId: source.id,
+      targetId: 'ses_fork_child',
+      title: 'Fork title',
+      metadata: { child: true },
+    });
+
+    const forkState = JSON.parse(await readFile(join(fork.sessionDir, 'state.json'), 'utf-8')) as {
+      title?: string;
+      isCustomTitle?: boolean;
+      forkedFrom?: string;
+      agents?: { main?: { homedir?: string } };
+      custom?: Record<string, unknown>;
+    };
+    expect(forkState.title).toBe('Fork title');
+    expect(forkState.isCustomTitle).toBe(true);
+    expect(forkState.forkedFrom).toBe(source.id);
+    expect(forkState.agents?.main?.homedir).toBe(join(fork.sessionDir, 'agents', 'main'));
+    expect(forkState.custom).toMatchObject({ source: true, child: true });
+    await expect(readFile(join(fork.sessionDir, 'agents', 'main', 'wire.jsonl'), 'utf-8')).resolves.toBe(
+      '{"type":"context.clear"}\n',
+    );
+
+    const sourceState = JSON.parse(
+      await readFile(join(source.sessionDir, 'state.json'), 'utf-8'),
+    ) as { forkedFrom?: string };
+    expect(sourceState.forkedFrom).toBeUndefined();
+    const sessions = await store.list({ workDir });
+    expect(sessions.map((session) => session.id).toSorted()).toEqual([
+      source.id,
+      fork.id,
+    ].toSorted());
+  });
+
+  it('returns only sessions from the requested workDir bucket', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const otherWorkDir = await makeTempDir();
+    const store = new SessionStore(homeDir);
+
+    await store.create({ id: 'ses_list_a', workDir });
+    await store.create({ id: 'ses_other_workdir', workDir: otherWorkDir });
+
+    const sessions = await store.list({ workDir });
+    expect(sessions.map((session) => session.id)).toEqual(['ses_list_a']);
+  });
+
+  it('reads title from customTitle before title', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const store = new SessionStore(homeDir);
+
+    const custom = await store.create({ id: 'ses_custom_title', workDir });
+    await writeSessionState(custom.sessionDir, {
+      title: 'Base Title',
+      customTitle: 'Custom Title',
+    });
+    const fallback = await store.create({ id: 'ses_fallback_title', workDir });
+    await writeSessionState(fallback.sessionDir, {
+      title: 'Fallback Title',
+    });
+
+    const sessions = await store.list({ workDir });
+    expect(sessions.find((session) => session.id === custom.id)?.title).toBe('Custom Title');
+    expect(sessions.find((session) => session.id === fallback.id)?.title).toBe('Fallback Title');
+  });
+
+  it('keeps sessions visible when state.json is missing or malformed', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const store = new SessionStore(homeDir);
+
+    await store.create({ id: 'ses_no_state', workDir });
+    const malformed = await store.create({ id: 'ses_bad_state', workDir });
+    await writeFile(join(malformed.sessionDir, 'state.json'), '{bad json', 'utf-8');
+
+    const sessions = await store.list({ workDir });
+    expect(sessions.map((session) => session.id).toSorted()).toEqual([
+      'ses_bad_state',
+      'ses_no_state',
+    ]);
+    expect(sessions.every((session) => session.title === undefined)).toBe(true);
+  });
+
+  it('sorts by filesystem activity descending', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const store = new SessionStore(homeDir);
+
+    const oldSession = await store.create({ id: 'ses_old', workDir });
+    const newSession = await store.create({ id: 'ses_new', workDir });
+    const oldTime = new Date('2030-04-18T12:00:00Z');
+    const newTime = new Date('2030-04-18T12:00:10Z');
+    await writeFile(join(oldSession.sessionDir, 'wire.jsonl'), '{}\n', 'utf-8');
+    await writeFile(join(newSession.sessionDir, 'wire.jsonl'), '{}\n', 'utf-8');
+    await utimes(join(oldSession.sessionDir, 'wire.jsonl'), oldTime, oldTime);
+    await utimes(join(newSession.sessionDir, 'wire.jsonl'), newTime, newTime);
+
+    const sessions = await store.list({ workDir });
+    expect(sessions.map((session) => session.id)).toEqual(['ses_new', 'ses_old']);
+  });
+
+  it('does not scan legacy flat session directories', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    await mkdir(join(homeDir, 'sessions', 'ses_legacy_flat'), { recursive: true });
+    await writeSessionState(join(homeDir, 'sessions', 'ses_legacy_flat'), {
+      session_id: 'ses_legacy_flat',
+      workspace_dir: workDir,
+      custom_title: 'Legacy Flat',
+    });
+
+    const store = new SessionStore(homeDir);
+    await expect(store.list({ workDir })).resolves.toEqual([]);
+    await expect(store.get('ses_legacy_flat')).rejects.toMatchObject({
+      name: 'KimiError',
+      code: 'session.not_found',
+    });
+  });
+});
+
+describe('KimiHarness.listSessions', () => {
+  it('rejects whitespace-only workDir with request.work_dir_required', async () => {
+    const homeDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      await expect(harness.listSessions({ workDir: '   ' })).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'request.work_dir_required',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects undefined payload as KimiError(internal)', async () => {
+    const homeDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      await expect(harness.listSessions(undefined as never)).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'internal',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('resolves relative workDir inputs before filtering', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+    const originalCwd = process.cwd();
+
+    try {
+      process.chdir(workDir);
+      const session = await harness.createSession({ id: 'ses_relative_workdir', workDir: '.' });
+
+      const sessions = await harness.listSessions({ workDir: '.' });
+      expect(sessions.map((item) => item.id)).toEqual([session.id]);
+    } finally {
+      process.chdir(originalCwd);
+      await harness.close();
+    }
+  });
+
+  it('lists persisted sessions after the active Session has been closed', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_closed_but_listed', workDir });
+      await harness.closeSession(session.id);
+
+      const sessions = await harness.listSessions({ workDir });
+      expect(sessions.map((item) => item.id)).toEqual([session.id]);
+    } finally {
+      await harness.close();
+    }
+  });
+});
diff --git a/packages/node-sdk/test/local-logging.test.ts b/packages/node-sdk/test/local-logging.test.ts
new file mode 100644
index 000000000..1a4fb3cec
--- /dev/null
+++ b/packages/node-sdk/test/local-logging.test.ts
@@ -0,0 +1,387 @@
+import { readFile, mkdtemp, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as zlib from 'node:zlib';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { KimiHarness, log } from '#/index';
+import { __resetRootLoggerForTest, getRootLogger } from '../../agent-core/src/logging/logger';
+import { TEST_IDENTITY } from './test-identity';
+
+const tempDirs: string[] = [];
+
+const LOG_ENV_KEYS = [
+  'KIMI_LOG_LEVEL',
+  'KIMI_LOG_GLOBAL_MAX_BYTES',
+  'KIMI_LOG_GLOBAL_FILES',
+  'KIMI_LOG_SESSION_MAX_BYTES',
+  'KIMI_LOG_SESSION_FILES',
+] as const;
+
+beforeEach(async () => {
+  await __resetRootLoggerForTest();
+});
+
+afterEach(async () => {
+  await __resetRootLoggerForTest();
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+async function makeTempDir(prefix: string): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+}
+
+async function readOptionalFile(path: string): Promise<string> {
+  try {
+    return await readFile(path, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function snapshotLogEnv(): Record<(typeof LOG_ENV_KEYS)[number], string | undefined> {
+  return Object.fromEntries(LOG_ENV_KEYS.map((key) => [key, process.env[key]])) as Record<
+    (typeof LOG_ENV_KEYS)[number],
+    string | undefined
+  >;
+}
+
+function restoreLogEnv(snapshot: Record<(typeof LOG_ENV_KEYS)[number], string | undefined>): void {
+  for (const key of LOG_ENV_KEYS) {
+    const value = snapshot[key];
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+}
+
+function readZipEntries(buf: Buffer): Map<string, Buffer> {
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 65557); i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) {
+      eocd = i;
+      break;
+    }
+  }
+  if (eocd === -1) throw new Error('zip eocd not found');
+  const entryCount = buf.readUInt16LE(eocd + 10);
+  const cdOffset = buf.readUInt32LE(eocd + 16);
+  const entries = new Map<string, Buffer>();
+  let pos = cdOffset;
+  for (let i = 0; i < entryCount; i++) {
+    if (buf.readUInt32LE(pos) !== 0x02014b50) throw new Error('bad cd entry');
+    const method = buf.readUInt16LE(pos + 10);
+    const compressedSize = buf.readUInt32LE(pos + 20);
+    const fnameLen = buf.readUInt16LE(pos + 28);
+    const extraLen = buf.readUInt16LE(pos + 30);
+    const commentLen = buf.readUInt16LE(pos + 32);
+    const lfhOffset = buf.readUInt32LE(pos + 42);
+    const filename = buf.toString('utf8', pos + 46, pos + 46 + fnameLen);
+    if (buf.readUInt32LE(lfhOffset) !== 0x04034b50) throw new Error('bad lfh');
+    const lfhFnameLen = buf.readUInt16LE(lfhOffset + 26);
+    const lfhExtraLen = buf.readUInt16LE(lfhOffset + 28);
+    const dataStart = lfhOffset + 30 + lfhFnameLen + lfhExtraLen;
+    const compressed = buf.subarray(dataStart, dataStart + compressedSize);
+    const data = method === 0 ? compressed : method === 8 ? zlib.inflateRawSync(compressed) : null;
+    if (data === null) throw new Error('unsupported compression');
+    entries.set(filename, data);
+    pos += 46 + fnameLen + extraLen + commentLen;
+  }
+  return entries;
+}
+
+describe('Local logging — harness integration', () => {
+  it('writes session-tagged entries to both global and session log files', async () => {
+    const homeDir = await makeTempDir('kimi-log-home-');
+    const workDir = await makeTempDir('kimi-log-work-');
+
+    const harness = new KimiHarness({ identity: TEST_IDENTITY, homeDir });
+    const session = await harness.createSession({
+      id: 'ses_logging_int',
+      workDir,
+    });
+
+    log.warn('session diagnostic', { sessionId: session.id });
+    log.warn('untagged event');
+
+    // Drain the in-process logger via export's flush path is overkill; just
+    // rely on the configured root logger's flush.
+    const summary = (await harness.listSessions({ workDir })).find(
+      (s) => s.id === session.id,
+    )!;
+
+    const globalPath = join(homeDir, 'logs', 'kimi-code.log');
+    const sessionLogPath = join(summary.sessionDir, 'logs', 'kimi-code.log');
+
+    // Trigger an export — this flushes both global and session via KimiCore
+    const exportOut = join(workDir, 'out.zip');
+    await harness.exportSession({
+      id: session.id,
+      outputPath: exportOut,
+      includeGlobalLog: true,
+      version: '1.0.0-test',
+    });
+
+    const global = await readFile(globalPath, 'utf-8');
+    const sessionLog = await readFile(sessionLogPath, 'utf-8');
+    expect(global).toContain('session diagnostic');
+    expect(sessionLog).toContain('session diagnostic');
+    expect(global).toContain('untagged event');
+    expect(sessionLog).not.toContain('untagged event');
+  });
+
+  it('default export bundles session log only; no globalLogPath in manifest', async () => {
+    const homeDir = await makeTempDir('kimi-log-home-');
+    const workDir = await makeTempDir('kimi-log-work-');
+    const harness = new KimiHarness({ identity: TEST_IDENTITY, homeDir });
+    const session = await harness.createSession({ id: 'ses_default_export', workDir });
+    log.warn('session export marker', { sessionId: session.id });
+
+    const outputPath = join(workDir, 'default.zip');
+    const result = await harness.exportSession({ id: session.id, outputPath, version: '1.0.0-test' });
+
+    const zipBuf = await readFile(result.zipPath);
+    const entries = readZipEntries(zipBuf);
+    expect(entries.has('agents/main/wire.jsonl')).toBe(true);
+    expect(entries.has('logs/kimi-code.log')).toBe(true);
+    expect(entries.has('logs/global/kimi-code.log')).toBe(false);
+    expect(entries.get('logs/kimi-code.log')!.toString('utf-8')).toContain(
+      'session export marker',
+    );
+    expect(result.manifest.sessionLogPath).toBe('logs/kimi-code.log');
+    expect(result.manifest.globalLogPath).toBeUndefined();
+    const manifest = JSON.parse(entries.get('manifest.json')!.toString('utf-8')) as Record<
+      string,
+      unknown
+    >;
+    expect(manifest['sessionLogPath']).toBe('logs/kimi-code.log');
+    expect(manifest['globalLogPath']).toBeUndefined();
+  });
+
+  it('default export works when no session log file exists', async () => {
+    const homeDir = await makeTempDir('kimi-log-home-');
+    const workDir = await makeTempDir('kimi-log-work-');
+    const harness = new KimiHarness({ identity: TEST_IDENTITY, homeDir });
+    const session = await harness.createSession({ id: 'ses_no_session_log', workDir });
+
+    const outputPath = join(workDir, 'no-log.zip');
+    const result = await harness.exportSession({ id: session.id, outputPath, version: '1.0.0-test' });
+
+    const entries = readZipEntries(await readFile(result.zipPath));
+    expect(entries.has('agents/main/wire.jsonl')).toBe(true);
+    expect(entries.has('logs/kimi-code.log')).toBe(false);
+    expect(result.manifest.sessionLogPath).toBeUndefined();
+    const manifest = JSON.parse(entries.get('manifest.json')!.toString('utf-8')) as Record<
+      string,
+      unknown
+    >;
+    expect(manifest['sessionLogPath']).toBeUndefined();
+  });
+
+  it('default export includes rotated session log files without requiring active kimi-code.log', async () => {
+    const env = snapshotLogEnv();
+    process.env['KIMI_LOG_LEVEL'] = 'warn';
+    process.env['KIMI_LOG_SESSION_MAX_BYTES'] = '1024';
+    process.env['KIMI_LOG_SESSION_FILES'] = '2';
+    try {
+      const homeDir = await makeTempDir('kimi-log-home-');
+      const workDir = await makeTempDir('kimi-log-work-');
+      const harness = new KimiHarness({ identity: TEST_IDENTITY, homeDir });
+      const session = await harness.createSession({ id: 'ses_rotated_export', workDir });
+      for (let i = 0; i < 16; i++) {
+        log.warn(`rotated session marker ${i}`, {
+          sessionId: session.id,
+          chunk: 'x'.repeat(220),
+        });
+      }
+
+      const result = await harness.exportSession({
+        id: session.id,
+        outputPath: join(workDir, 'rotated.zip'),
+        version: '1.0.0-test',
+      });
+
+      const entries = readZipEntries(await readFile(result.zipPath));
+      const sessionLogEntries = [...entries.keys()].filter(
+        (entry) => entry === 'logs/kimi-code.log' || entry.startsWith('logs/kimi-code.log.'),
+      );
+      expect(sessionLogEntries.length).toBeGreaterThan(0);
+      expect(sessionLogEntries).toContain('logs/kimi-code.log.1');
+      expect(entries.has('logs/global/kimi-code.log')).toBe(false);
+      if (entries.has('logs/kimi-code.log')) {
+        expect(result.manifest.sessionLogPath).toBe('logs/kimi-code.log');
+      } else {
+        expect(result.manifest.sessionLogPath).toBeUndefined();
+      }
+    } finally {
+      restoreLogEnv(env);
+    }
+  });
+
+  it('--include-global-log bundles global active and sets manifest field', async () => {
+    const homeDir = await makeTempDir('kimi-log-home-');
+    const workDir = await makeTempDir('kimi-log-work-');
+    const harness = new KimiHarness({ identity: TEST_IDENTITY, homeDir });
+    const session = await harness.createSession({ id: 'ses_global_export', workDir });
+    log.warn('untagged probe');
+
+    const outputPath = join(workDir, 'with-global.zip');
+    const result = await harness.exportSession({
+      id: session.id,
+      outputPath,
+      includeGlobalLog: true,
+      version: '1.0.0-test',
+    });
+    const zipBuf = await readFile(result.zipPath);
+    const entries = readZipEntries(zipBuf);
+    expect(entries.has('agents/main/wire.jsonl')).toBe(true);
+    expect(entries.has('logs/global/kimi-code.log')).toBe(true);
+    expect(result.manifest.globalLogPath).toBe('logs/global/kimi-code.log');
+    // Global log carries entries that don't have a sessionId routed to a sink.
+    expect(entries.get('logs/global/kimi-code.log')!.toString('utf-8')).toContain(
+      'untagged probe',
+    );
+  });
+
+  it('--include-global-log bundles the active root global log path', async () => {
+    const firstHome = await makeTempDir('kimi-log-home-a-');
+    const secondHome = await makeTempDir('kimi-log-home-b-');
+    const workDir = await makeTempDir('kimi-log-work-');
+    const first = new KimiHarness({ identity: TEST_IDENTITY, homeDir: firstHome });
+    const firstSession = await first.createSession({ id: 'ses_first_global_export', workDir });
+    const second = new KimiHarness({ identity: TEST_IDENTITY, homeDir: secondHome });
+
+    log.warn('active-global-export-marker');
+    await getRootLogger().flushGlobal();
+
+    const result = await first.exportSession({
+      id: firstSession.id,
+      outputPath: join(workDir, 'active-global.zip'),
+      includeGlobalLog: true,
+      version: '1.0.0-test',
+    });
+
+    const entries = readZipEntries(await readFile(result.zipPath));
+    const globalLog = entries.get('logs/global/kimi-code.log')!.toString('utf-8');
+    const firstLog = await readOptionalFile(join(firstHome, 'logs', 'kimi-code.log'));
+    expect(globalLog).toContain('active-global-export-marker');
+    expect(firstLog).not.toContain('active-global-export-marker');
+
+    await first.close();
+    await second.close();
+  });
+
+  it('logs export flush failures without failing the export', async () => {
+    const homeDir = await makeTempDir('kimi-log-home-');
+    const workDir = await makeTempDir('kimi-log-work-');
+    const harness = new KimiHarness({ identity: TEST_IDENTITY, homeDir });
+    const session = await harness.createSession({ id: 'ses_flush_warning', workDir });
+    log.warn('flush warning setup', { sessionId: session.id });
+
+    const root = getRootLogger();
+    const flushSessionSpy = vi
+      .spyOn(root, 'flushSession')
+      .mockRejectedValueOnce(new Error('session flush boom'));
+    const flushGlobalSpy = vi
+      .spyOn(root, 'flushGlobal')
+      .mockRejectedValueOnce(new Error('global flush boom'));
+    try {
+      const result = await harness.exportSession({
+        id: session.id,
+        outputPath: join(workDir, 'flush-warning.zip'),
+        includeGlobalLog: true,
+        version: '1.0.0-test',
+      });
+
+      const entries = readZipEntries(await readFile(result.zipPath));
+      const sessionLog = entries.get('logs/kimi-code.log')!.toString('utf-8');
+      const globalLog = entries.get('logs/global/kimi-code.log')!.toString('utf-8');
+      expect(sessionLog).toContain('export session log flush failed');
+      expect(sessionLog).toContain('export global log flush failed');
+      expect(globalLog).toContain('export global log flush failed');
+    } finally {
+      flushSessionSpy.mockRestore();
+      flushGlobalSpy.mockRestore();
+    }
+  });
+
+  it('multiple KimiHarness constructions in the same process do not throw', async () => {
+    const homeDir = await makeTempDir('kimi-log-home-');
+    expect(() => new KimiHarness({ identity: TEST_IDENTITY, homeDir })).not.toThrow();
+    expect(() => new KimiHarness({ identity: TEST_IDENTITY, homeDir })).not.toThrow();
+    expect(() => new KimiHarness({ identity: TEST_IDENTITY, homeDir })).not.toThrow();
+  });
+
+  it('uses the latest harness homeDir for global diagnostic logging', async () => {
+    const firstHome = await makeTempDir('kimi-log-home-a-');
+    const secondHome = await makeTempDir('kimi-log-home-b-');
+    const first = new KimiHarness({ identity: TEST_IDENTITY, homeDir: firstHome });
+    const second = new KimiHarness({ identity: TEST_IDENTITY, homeDir: secondHome });
+
+    log.warn('second-home-marker');
+    await getRootLogger().flushGlobal();
+
+    const firstLog = await readOptionalFile(join(firstHome, 'logs', 'kimi-code.log'));
+    const secondLog = await readFile(join(secondHome, 'logs', 'kimi-code.log'), 'utf-8');
+    expect(firstLog).not.toContain('second-home-marker');
+    expect(secondLog).toContain('second-home-marker');
+
+    await first.close();
+    await second.close();
+  });
+
+  it('SDK does not expose RootLogger / getRootLogger / LoggingConfig', async () => {
+    // Type-level check — if these names show up on the SDK index they must
+    // be re-exports we forgot to filter. Use string keys so the assertion is
+    // structural and survives renames.
+    const sdk = await import('#/index');
+    const exposed = Object.keys(sdk);
+    expect(exposed).toContain('log');
+    expect(exposed).toContain('redact');
+    expect(exposed).toContain('flushDiagnosticLogs');
+    expect(exposed).not.toContain('getLogger');
+    expect(exposed).not.toContain('getRootLogger');
+    expect(exposed).not.toContain('resolveLoggingConfig');
+    expect(exposed).not.toContain('installProcessCrashHandlers');
+  });
+
+  it('checks that an empty session log directory does not get a log file', async () => {
+    // Sanity: if level is off, no log files should be created
+    const env = snapshotLogEnv();
+    process.env['KIMI_LOG_LEVEL'] = 'off';
+    try {
+      const homeDir = await makeTempDir('kimi-log-home-');
+      const workDir = await makeTempDir('kimi-log-work-');
+      const harness = new KimiHarness({ identity: TEST_IDENTITY, homeDir });
+      await harness.createSession({ id: 'ses_off', workDir });
+      log.error('this should not write');
+      let logsDir: string[] = [];
+      try {
+        logsDir = await readdir(join(homeDir, 'logs'));
+      } catch {
+        // intentional — directory may not exist when level=off
+      }
+      expect(logsDir).not.toContain('kimi-code.log');
+    } finally {
+      restoreLogEnv(env);
+    }
+  });
+
+  it('KimiHarness.close() flushes the global log', async () => {
+    const homeDir = await makeTempDir('kimi-log-home-');
+    const harness = new KimiHarness({ identity: TEST_IDENTITY, homeDir });
+    log.warn('untagged before close');
+    // No `await flush()` here on purpose — close() must do it.
+    await harness.close();
+    const globalPath = join(homeDir, 'logs', 'kimi-code.log');
+    const text = await readFile(globalPath, 'utf-8');
+    expect(text).toContain('untagged before close');
+  });
+});
diff --git a/packages/node-sdk/test/rename-session.test.ts b/packages/node-sdk/test/rename-session.test.ts
new file mode 100644
index 000000000..693b1050f
--- /dev/null
+++ b/packages/node-sdk/test/rename-session.test.ts
@@ -0,0 +1,228 @@
+import { existsSync } from 'node:fs';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { KimiError, KimiHarness, type Event } from '#/index';
+
+import { SessionStore } from '../../agent-core/src/session/store';
+import { TEST_IDENTITY } from './test-identity';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'kimi-sdk-rename-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+async function writeSessionState(
+  sessionDir: string,
+  state: Record<string, unknown>,
+): Promise<void> {
+  await writeFile(join(sessionDir, 'state.json'), `${JSON.stringify(state, null, 2)}\n`, 'utf-8');
+}
+
+async function readSessionState(sessionDir: string): Promise<Record<string, unknown>> {
+  const raw = await readFile(join(sessionDir, 'state.json'), 'utf-8');
+  return JSON.parse(raw) as Record<string, unknown>;
+}
+
+function findRenamedEvent(
+  events: readonly Event[],
+): Extract<Event, { readonly type: 'session.meta.updated' }> {
+  const event = events.find((item) => item.type === 'session.meta.updated');
+  if (event === undefined || event.type !== 'session.meta.updated') {
+    throw new Error('session_meta_updated event not found');
+  }
+  return event;
+}
+
+describe('SessionStore.rename', () => {
+  it('persists custom title state and preserves existing state fields', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const store = new SessionStore(homeDir);
+
+    const summary = await store.create({
+      id: 'ses_store_rename',
+      workDir,
+    });
+    await writeSessionState(summary.sessionDir, {
+      session_id: 'ses_store_rename',
+      title: 'Original Title',
+      updated_at: 1_000,
+      model: 'kimi-for-coding',
+      nested: { enabled: true },
+    });
+
+    await store.rename('ses_store_rename', 'New Store Title');
+
+    const state = await readSessionState(summary.sessionDir);
+    expect(state).toMatchObject({
+      session_id: 'ses_store_rename',
+      title: 'New Store Title',
+      updated_at: 1_000,
+      model: 'kimi-for-coding',
+      isCustomTitle: true,
+      nested: { enabled: true },
+    });
+
+    const renamed = await store.get('ses_store_rename');
+    expect(renamed.title).toBe('New Store Title');
+    expect(renamed.metadata).toBeUndefined();
+  });
+
+  it('rejects indexed sessions with missing state without creating state.json', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const store = new SessionStore(homeDir);
+    const summary = await store.create({ id: 'ses_no_state_rename', workDir });
+
+    await expect(store.rename(summary.id, 'Missing State')).rejects.toMatchObject({
+      name: 'KimiError',
+      code: 'session.state_not_found',
+    } satisfies Partial<KimiError>);
+    expect(existsSync(join(summary.sessionDir, 'state.json'))).toBe(false);
+  });
+
+  it('rejects invalid state.json without overwriting it', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const store = new SessionStore(homeDir);
+    const summary = await store.create({ id: 'ses_bad_state_rename', workDir });
+    await writeFile(join(summary.sessionDir, 'state.json'), '[]', 'utf-8');
+
+    await expect(store.rename(summary.id, 'Bad State')).rejects.toMatchObject({
+      name: 'KimiError',
+      code: 'session.state_invalid',
+    } satisfies Partial<KimiError>);
+    expect(await readFile(join(summary.sessionDir, 'state.json'), 'utf-8')).toBe('[]');
+  });
+
+  it('rejects missing session ids without creating state', async () => {
+    const homeDir = await makeTempDir();
+    const store = new SessionStore(homeDir);
+
+    await expect(store.rename('ses_missing', 'Missing Title')).rejects.toMatchObject({
+      name: 'KimiError',
+      code: 'session.not_found',
+      details: { sessionId: 'ses_missing' },
+    } satisfies Partial<KimiError>);
+    expect(existsSync(join(homeDir, 'sessions', 'ses_missing', 'state.json'))).toBe(false);
+  });
+});
+
+describe('KimiHarness.renameSession', () => {
+  it('persists titles through the public Harness API and emits an active session event', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      const session = await harness.createSession({
+        id: 'ses_harness_rename',
+        workDir,
+      });
+      const summary = (await harness.listSessions({ workDir })).find(
+        (item) => item.id === session.id,
+      )!;
+      await writeSessionState(summary.sessionDir, {
+        session_id: session.id,
+        title: 'Base Title',
+      });
+      const events: Event[] = [];
+      const unsubscribe = session.onEvent((event) => {
+        events.push(event);
+      });
+
+      await harness.renameSession({ id: session.id, title: 'Harness Title' });
+      unsubscribe();
+
+      const sessions = await harness.listSessions({ workDir });
+      expect(sessions.find((item) => item.id === session.id)?.title).toBe('Harness Title');
+
+      const state = await readSessionState(summary.sessionDir);
+      expect(state['title']).toBe('Harness Title');
+      expect(state['isCustomTitle']).toBe(true);
+
+      const event = findRenamedEvent(events);
+      expect(event).toMatchObject({
+        type: 'session.meta.updated',
+        sessionId: session.id,
+        agentId: 'main',
+        title: 'Harness Title',
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('renames persisted sessions even when they are not active in memory', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_inactive_rename', workDir });
+      const summary = (await harness.listSessions({ workDir })).find(
+        (item) => item.id === session.id,
+      )!;
+      await writeSessionState(summary.sessionDir, {
+        session_id: session.id,
+        title: 'Inactive Base',
+      });
+      const events: Event[] = [];
+      session.onEvent((event) => {
+        events.push(event);
+      });
+
+      await harness.closeSession(session.id);
+      events.length = 0;
+
+      await harness.renameSession({ id: session.id, title: 'Inactive Title' });
+
+      const sessions = await harness.listSessions({ workDir });
+      expect(sessions.find((item) => item.id === session.id)?.title).toBe('Inactive Title');
+      expect(events.some((event) => event.type === 'session.meta.updated')).toBe(false);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects missing session ids', async () => {
+    const homeDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      const missingRename = harness.renameSession({
+        id: 'ses_missing',
+        title: 'Missing Title',
+      });
+      await expect(missingRename).rejects.toBeInstanceOf(KimiError);
+      await expect(missingRename).rejects.toMatchObject({
+        code: 'session.not_found',
+        details: { sessionId: 'ses_missing' },
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+});
diff --git a/packages/node-sdk/test/runtime-provider-identity.test.ts b/packages/node-sdk/test/runtime-provider-identity.test.ts
new file mode 100644
index 000000000..684d0e8d6
--- /dev/null
+++ b/packages/node-sdk/test/runtime-provider-identity.test.ts
@@ -0,0 +1,138 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import type { KimiConfig } from '@moonshot-ai/agent-core';
+import { createKimiDefaultHeaders } from '@moonshot-ai/kimi-code-oauth';
+
+import { resolveRuntimeProvider } from '../../agent-core/src/providers/runtime-provider';
+import { TEST_IDENTITY } from './test-identity';
+
+const tempDirs: string[] = [];
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'kimi-sdk-provider-identity-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+describe('runtime provider identity headers', () => {
+  it('adds kimi-code-cli User-Agent and complete X-Msh headers to the default Kimi provider', async () => {
+    const homeDir = await makeTempDir();
+    const kimiRequestHeaders = createKimiDefaultHeaders({ homeDir, ...TEST_IDENTITY });
+    const resolved = resolveRuntimeProvider({
+      config: {
+        defaultModel: 'kimi-model',
+        providers: {
+          kimi: {
+            type: 'kimi',
+            apiKey: 'test-key',
+          },
+        },
+        models: {
+          'kimi-model': {
+            provider: 'kimi',
+            model: 'kimi-model',
+            maxContextSize: 1000,
+          },
+        },
+      },
+      kimiRequestHeaders,
+    });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'kimi',
+      defaultHeaders: expect.objectContaining({
+        'User-Agent': 'kimi-code-cli/0.0.0-test',
+        'X-Msh-Platform': 'kimi-code-cli',
+        'X-Msh-Version': '0.0.0-test',
+        'X-Msh-Device-Name': expect.any(String),
+        'X-Msh-Device-Model': expect.any(String),
+        'X-Msh-Os-Version': expect.any(String),
+        'X-Msh-Device-Id': expect.stringMatching(/^[0-9a-f-]+$/),
+      }),
+    });
+  });
+
+  it('lets Kimi provider customHeaders override default identity headers', async () => {
+    const homeDir = await makeTempDir();
+    const kimiRequestHeaders = createKimiDefaultHeaders({ homeDir, ...TEST_IDENTITY });
+    const config: KimiConfig = {
+      providers: {
+        kimi: {
+          type: 'kimi',
+          apiKey: 'test-key',
+          customHeaders: {
+            'User-Agent': 'Custom/1',
+            'X-Msh-Version': 'override-version',
+          },
+        },
+      },
+      defaultProvider: 'kimi',
+      defaultModel: 'kimi-model',
+      models: {
+        'kimi-model': {
+          provider: 'kimi',
+          model: 'kimi-model',
+          maxContextSize: 1000,
+        },
+      },
+    };
+
+    const resolved = resolveRuntimeProvider({
+      config,
+      kimiRequestHeaders,
+    });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'kimi',
+      defaultHeaders: expect.objectContaining({
+        'User-Agent': 'Custom/1',
+        'X-Msh-Version': 'override-version',
+        'X-Msh-Platform': 'kimi-code-cli',
+      }),
+    });
+  });
+
+  it('does not add Kimi identity headers to non-Kimi providers', async () => {
+    const homeDir = await makeTempDir();
+    const kimiRequestHeaders = createKimiDefaultHeaders({ homeDir, ...TEST_IDENTITY });
+    const config: KimiConfig = {
+      providers: {
+        openai: {
+          type: 'openai',
+          baseUrl: 'https://example.test/v1',
+          apiKey: 'sk-test',
+        },
+      },
+      defaultProvider: 'openai',
+      defaultModel: 'gpt-test',
+      models: {
+        'gpt-test': {
+          provider: 'openai',
+          model: 'gpt-test',
+          maxContextSize: 1000,
+        },
+      },
+    };
+
+    const resolved = resolveRuntimeProvider({
+      config,
+      kimiRequestHeaders,
+    });
+
+    expect(resolved.provider).toMatchObject({
+      type: 'openai',
+      model: 'gpt-test',
+    });
+    expect(resolved.provider).not.toHaveProperty('defaultHeaders');
+  });
+});
diff --git a/packages/node-sdk/test/runtime-provider-oauth.test.ts b/packages/node-sdk/test/runtime-provider-oauth.test.ts
new file mode 100644
index 000000000..c750741e4
--- /dev/null
+++ b/packages/node-sdk/test/runtime-provider-oauth.test.ts
@@ -0,0 +1,148 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { ErrorCodes, KimiError, type KimiConfig, type Logger } from '#/index';
+
+import { resolveRuntimeProviderWithOAuth } from '../../agent-core/src/providers/runtime-provider';
+
+function managedConfig(): KimiConfig {
+  return {
+    providers: {
+      'managed:kimi-code': {
+        type: 'kimi',
+        baseUrl: 'https://api.kimi.com/coding/v1',
+        apiKey: '',
+        oauth: { storage: 'file', key: 'oauth/kimi-code' },
+      },
+    },
+    models: {
+      'kimi-code/kimi-for-coding': {
+        provider: 'managed:kimi-code',
+        model: 'kimi-for-coding',
+        maxContextSize: 262144,
+      },
+    },
+    defaultModel: 'kimi-code/kimi-for-coding',
+  };
+}
+
+describe('resolveRuntimeProviderWithOAuth', () => {
+  it('returns request-scoped OAuth auth without storing the initial access token in provider config', async () => {
+    const tokens = ['initial-oauth-token', 'rotated-oauth-token', 'force-refreshed-oauth-token'];
+    const getAccessToken = vi.fn().mockImplementation(async () => {
+      const token = tokens.shift();
+      if (token === undefined) throw new Error('unexpected token request');
+      return token;
+    });
+
+    const resolved = await resolveRuntimeProviderWithOAuth({
+      config: managedConfig(),
+      resolveOAuthTokenProvider: (_providerName, oauthRef) => {
+        expect(oauthRef).toEqual({ storage: 'file', key: 'oauth/kimi-code' });
+        return { getAccessToken };
+      },
+    });
+
+    expect(resolved.providerName).toBe('managed:kimi-code');
+    expect(resolved.provider).toMatchObject({
+      type: 'kimi',
+      model: 'kimi-for-coding',
+      baseUrl: 'https://api.kimi.com/coding/v1',
+    });
+    expect(resolved.provider.apiKey).toBeUndefined();
+    await expect(resolved.resolveAuth?.()).resolves.toEqual({ apiKey: 'rotated-oauth-token' });
+    await expect(resolved.resolveAuth?.({ forceRefresh: true })).resolves.toEqual({
+      apiKey: 'force-refreshed-oauth-token',
+    });
+    expect(getAccessToken.mock.calls).toEqual([[undefined], [undefined], [{ force: true }]]);
+  });
+
+  it('throws a clear login-required error when no token provider exists', async () => {
+    await expect(
+      resolveRuntimeProviderWithOAuth({
+        config: managedConfig(),
+      }),
+    ).rejects.toThrow(/requires login/);
+  });
+
+  it('rejects providers that set both apiKey and oauth on the same config', async () => {
+    const conflicting: KimiConfig = {
+      ...managedConfig(),
+      providers: {
+        'managed:kimi-code': {
+          type: 'kimi',
+          baseUrl: 'https://api.kimi.com/coding/v1',
+          apiKey: 'static-key',
+          oauth: { storage: 'file', key: 'oauth/kimi-code' },
+        },
+      },
+    };
+
+    await expect(
+      resolveRuntimeProviderWithOAuth({
+        config: conflicting,
+        resolveOAuthTokenProvider: () => ({
+          getAccessToken: vi.fn().mockResolvedValue('unused'),
+        }),
+      }),
+    ).rejects.toThrow(/mutually exclusive/);
+  });
+
+  it('wraps token provider failures as login-required errors', async () => {
+    await expect(
+      resolveRuntimeProviderWithOAuth({
+        config: managedConfig(),
+        resolveOAuthTokenProvider: () => ({
+          getAccessToken: vi.fn().mockRejectedValue(new Error('missing token')),
+        }),
+      }),
+    ).rejects.toMatchObject({
+      name: 'KimiError',
+      code: 'auth.login_required',
+    });
+  });
+
+  it('logs token provider failures except plain login-required errors', async () => {
+    const log = testLogger();
+    await expect(
+      resolveRuntimeProviderWithOAuth({
+        config: managedConfig(),
+        log,
+        resolveOAuthTokenProvider: () => ({
+          getAccessToken: vi.fn().mockRejectedValue(new Error('token endpoint down')),
+        }),
+      }),
+    ).rejects.toMatchObject({ code: 'auth.login_required' });
+    expect(log.warn).toHaveBeenCalledWith(
+      'oauth token fetch failed',
+      expect.objectContaining({
+        providerName: 'managed:kimi-code',
+        error: expect.any(Error),
+      }),
+    );
+
+    vi.clearAllMocks();
+    await expect(
+      resolveRuntimeProviderWithOAuth({
+        config: managedConfig(),
+        log,
+        resolveOAuthTokenProvider: () => ({
+          getAccessToken: vi.fn().mockRejectedValue(
+            new KimiError(ErrorCodes.AUTH_LOGIN_REQUIRED, 'not logged in'),
+          ),
+        }),
+      }),
+    ).rejects.toMatchObject({ code: 'auth.login_required' });
+    expect(log.warn).not.toHaveBeenCalled();
+  });
+});
+
+function testLogger(): Logger {
+  const logger: Logger = {
+    error: vi.fn(),
+    warn: vi.fn(),
+    info: vi.fn(),
+    debug: vi.fn(),
+    createChild: () => logger,
+  };
+  return logger;
+}
diff --git a/packages/node-sdk/test/session-approval-handler.test.ts b/packages/node-sdk/test/session-approval-handler.test.ts
new file mode 100644
index 000000000..72fd0f34d
--- /dev/null
+++ b/packages/node-sdk/test/session-approval-handler.test.ts
@@ -0,0 +1,223 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { ApprovalHandler, ApprovalRequest, ApprovalResponse } from '#/index';
+import { Session } from '#/index';
+import type { SDKRpcClient } from '#/rpc';
+
+describe('Session approval handler', () => {
+  it('registers an approval handler and returns approved responses', async () => {
+    const rpc = new FakeSDKRpcClient();
+    const session = new Session({
+      id: 'ses_approval_handler',
+      workDir: '/tmp',
+      rpc: rpc.asRpc(),
+    });
+    const handler = vi.fn(async (request: ApprovalRequest) => {
+      expect(request).toMatchObject({
+        toolCallId: 'tool_1',
+        toolName: 'Bash',
+        action: 'Run command',
+      });
+      return { decision: 'approved' as const, selectedLabel: 'Approve once' };
+    });
+    session.setApprovalHandler(handler);
+
+    await expect(
+      rpc.requestApproval(
+        session.id,
+        'main',
+        approvalRequest({
+          toolCallId: 'tool_1',
+          toolName: 'Bash',
+          action: 'Run command',
+        }),
+      ),
+    ).resolves.toEqual({ decision: 'approved', selectedLabel: 'Approve once' });
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('sends rejected responses with feedback', async () => {
+    const rpc = new FakeSDKRpcClient();
+    const session = new Session({
+      id: 'ses_approval_rejected',
+      workDir: '/tmp',
+      rpc: rpc.asRpc(),
+    });
+    session.setApprovalHandler(() => ({ decision: 'rejected', feedback: 'No writes.' }));
+
+    await expect(
+      rpc.requestApproval(
+        session.id,
+        'main',
+        approvalRequest({
+          toolCallId: 'tool_2',
+          toolName: 'Write',
+          action: 'Write file',
+        }),
+      ),
+    ).resolves.toEqual({ decision: 'rejected', feedback: 'No writes.' });
+  });
+
+  it('sends session-scoped approved responses when requested', async () => {
+    const rpc = new FakeSDKRpcClient();
+    const session = new Session({
+      id: 'ses_approval_scope',
+      workDir: '/tmp',
+      rpc: rpc.asRpc(),
+    });
+    session.setApprovalHandler(() => ({ decision: 'approved', scope: 'session' }));
+
+    await expect(
+      rpc.requestApproval(
+        session.id,
+        'main',
+        approvalRequest({
+          toolCallId: 'tool_scope',
+          toolName: 'Bash',
+          action: 'Run command',
+        }),
+      ),
+    ).resolves.toEqual({ decision: 'approved', scope: 'session' });
+  });
+
+  it('cancels approval requests when no handler is registered', async () => {
+    const rpc = new FakeSDKRpcClient();
+    const session = new Session({
+      id: 'ses_approval_default',
+      workDir: '/tmp',
+      rpc: rpc.asRpc(),
+    });
+
+    await expect(
+      rpc.requestApproval(
+        session.id,
+        'main',
+        approvalRequest({
+          toolCallId: 'tool_3',
+          toolName: 'Bash',
+          action: 'Run command',
+        }),
+      ),
+    ).resolves.toEqual({
+      decision: 'cancelled',
+      feedback: 'No approval handler registered.',
+    });
+    await session.close();
+    expect(rpc.closeSession).toHaveBeenCalledWith({ sessionId: session.id });
+  });
+
+  it('cancels approval requests when the handler throws', async () => {
+    const rpc = new FakeSDKRpcClient();
+    const session = new Session({
+      id: 'ses_approval_throw',
+      workDir: '/tmp',
+      rpc: rpc.asRpc(),
+    });
+    session.setApprovalHandler(() => {
+      throw new Error('boom');
+    });
+
+    await expect(
+      rpc.requestApproval(
+        session.id,
+        'main',
+        approvalRequest({
+          toolCallId: 'tool_4',
+          toolName: 'Bash',
+          action: 'Run command',
+        }),
+      ),
+    ).resolves.toEqual({
+      decision: 'cancelled',
+      feedback: 'Approval handler failed.',
+    });
+  });
+
+  it('responds to the original subagent id', async () => {
+    const rpc = new FakeSDKRpcClient();
+    const session = new Session({
+      id: 'ses_approval_subagent',
+      workDir: '/tmp',
+      rpc: rpc.asRpc(),
+    });
+    const handler = vi.fn(() => ({ decision: 'approved' as const }));
+    session.setApprovalHandler(handler);
+
+    await expect(
+      rpc.requestApproval(
+        session.id,
+        'agent-1',
+        approvalRequest({
+          toolCallId: 'tool_5',
+          toolName: 'Read',
+          action: 'Read file',
+        }),
+      ),
+    ).resolves.toEqual({ decision: 'approved' });
+
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionId: session.id,
+        agentId: 'agent-1',
+      }),
+    );
+  });
+});
+
+interface ApprovalRequestInput {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly action: string;
+}
+
+function approvalRequest(input: ApprovalRequestInput): ApprovalRequest {
+  return {
+    toolCallId: input.toolCallId,
+    toolName: input.toolName,
+    action: input.action,
+    display: { kind: 'generic', summary: input.action },
+  };
+}
+
+class FakeSDKRpcClient {
+  private readonly approvalHandlers = new Map<string, ApprovalHandler>();
+  readonly closeSession = vi.fn(async (_input: { readonly sessionId: string }) => {});
+
+  asRpc(): SDKRpcClient {
+    return this as unknown as SDKRpcClient;
+  }
+
+  setApprovalHandler(sessionId: string, handler: ApprovalHandler | undefined): void {
+    if (handler === undefined) {
+      this.approvalHandlers.delete(sessionId);
+      return;
+    }
+    this.approvalHandlers.set(sessionId, handler);
+  }
+
+  async requestApproval(
+    sessionId: string,
+    agentId: string,
+    request: ApprovalRequest,
+  ): Promise<ApprovalResponse> {
+    const handler = this.approvalHandlers.get(sessionId);
+    if (handler === undefined) {
+      return {
+        decision: 'cancelled',
+        feedback: 'No approval handler registered.',
+      };
+    }
+    try {
+      return await handler({ ...request, sessionId, agentId } as ApprovalRequest);
+    } catch {
+      return {
+        decision: 'cancelled',
+        feedback: 'Approval handler failed.',
+      };
+    }
+  }
+
+  clearSessionHandlers(sessionId: string): void {
+    this.approvalHandlers.delete(sessionId);
+  }
+}
diff --git a/packages/node-sdk/test/session-background-tasks.test.ts b/packages/node-sdk/test/session-background-tasks.test.ts
new file mode 100644
index 000000000..735df1a6b
--- /dev/null
+++ b/packages/node-sdk/test/session-background-tasks.test.ts
@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { KimiHarness, type KimiError } from '#/index';
+
+import { makeTempDir, removeTempDirs } from './session-runtime-helpers';
+import { TEST_IDENTITY } from './test-identity';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await removeTempDirs(tempDirs);
+});
+
+describe('Session.listBackgroundTasks / getBackgroundTaskOutput / getBackgroundTaskOutputPath', () => {
+  it('lists an empty task set for a fresh session', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-bgtask-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-bgtask-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_bg_list_empty', workDir });
+      const tasks = await session.listBackgroundTasks();
+      expect(tasks).toEqual([]);
+
+      const filtered = await session.listBackgroundTasks({ activeOnly: true });
+      expect(filtered).toEqual([]);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('returns empty output and undefined path for an unknown task id', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-bgtask-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-bgtask-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_bg_unknown', workDir });
+      // Unknown task ids must not throw — UI fetches output speculatively.
+      await expect(session.getBackgroundTaskOutput('bash-deadbeef')).resolves.toBe('');
+      await expect(session.getBackgroundTaskOutputPath('bash-deadbeef')).resolves.toBeUndefined();
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects empty task ids with a stable error code', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-bgtask-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-bgtask-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_bg_empty_id', workDir });
+      await expect(session.getBackgroundTaskOutput('')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'background.task_id_empty',
+      } satisfies Partial<KimiError>);
+      await expect(session.getBackgroundTaskOutputPath('   ')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'background.task_id_empty',
+      } satisfies Partial<KimiError>);
+      await expect(session.stopBackgroundTask('')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'background.task_id_empty',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects after the session is closed', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-bgtask-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-bgtask-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_bg_closed', workDir });
+      await session.close();
+
+      await expect(session.listBackgroundTasks()).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.closed',
+      } satisfies Partial<KimiError>);
+      await expect(session.getBackgroundTaskOutput('bash-aaaaaaaa')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.closed',
+      } satisfies Partial<KimiError>);
+      await expect(session.getBackgroundTaskOutputPath('bash-aaaaaaaa')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.closed',
+      } satisfies Partial<KimiError>);
+      await expect(session.stopBackgroundTask('bash-aaaaaaaa')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.closed',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('stopBackgroundTask is a no-op for an unknown task id', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-bgtask-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-bgtask-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_bg_stop_unknown', workDir });
+      // Unknown task ids must not throw — the core BPM silently no-ops.
+      await expect(
+        session.stopBackgroundTask('bash-deadbeef', { reason: 'test' }),
+      ).resolves.toBeUndefined();
+    } finally {
+      await harness.close();
+    }
+  });
+});
diff --git a/packages/node-sdk/test/session-cancel.test.ts b/packages/node-sdk/test/session-cancel.test.ts
new file mode 100644
index 000000000..b3155eb72
--- /dev/null
+++ b/packages/node-sdk/test/session-cancel.test.ts
@@ -0,0 +1,171 @@
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import type * as KosongModule from '@moonshot-ai/kosong';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { KimiError, Event } from '#/index';
+
+import { makeTempDir, removeTempDirs, waitForSDKEvent } from './session-runtime-helpers';
+import { TEST_IDENTITY } from './test-identity';
+
+vi.mock('@moonshot-ai/kosong', async (importOriginal) => {
+  const actual = await importOriginal<typeof KosongModule>();
+  return {
+    ...actual,
+    createProvider: () => ({
+      name: 'fake',
+      modelName: 'fake-model',
+      thinkingEffort: null,
+      async generate(
+        _systemPrompt: string,
+        _tools: unknown,
+        _history: unknown,
+        options?: { readonly signal?: AbortSignal },
+      ) {
+        await waitForAbort(options?.signal);
+        throwAbortError();
+      },
+      withThinking() {
+        return this;
+      },
+    }),
+  };
+});
+
+const { KimiHarness } = await import('#/index');
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await removeTempDirs(tempDirs);
+});
+
+describe('Session.cancel', () => {
+  it('cancels an active streaming turn and emits turn_ended(cancelled)', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-cancel-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-cancel-work-');
+    await writeFakeModelConfig(homeDir);
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_cancel_active_turn', workDir });
+      const events: Event[] = [];
+      const unsubscribe = session.onEvent((event) => {
+        events.push(event);
+      });
+      const started = waitForSDKEvent(session, (event) => event.type === 'turn.started');
+      const ended = waitForSDKEvent(session, (event) => event.type === 'turn.ended');
+
+      await session.prompt('start a turn that will be cancelled');
+      const startedEvent = await started;
+      await session.cancel();
+      const endedEvent = await ended;
+      unsubscribe();
+
+      expect(startedEvent).toMatchObject({
+        type: 'turn.started',
+        sessionId: session.id,
+      });
+      expect(endedEvent).toMatchObject({
+        type: 'turn.ended',
+        sessionId: session.id,
+        turnId: startedEvent.type === 'turn.started' ? startedEvent.turnId : undefined,
+        reason: 'cancelled',
+      });
+      expect(events).toContainEqual(expect.objectContaining({ type: 'turn.started' }));
+      expect(events).toContainEqual(expect.objectContaining({ type: 'turn.ended' }));
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('cancels an active manual compaction and emits compaction.cancelled', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-cancel-compact-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-cancel-compact-work-');
+    await writeFakeModelConfig(homeDir);
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_cancel_compaction', workDir });
+      const started = waitForSDKEvent(session, (event) => event.type === 'compaction.started');
+      const cancelled = waitForSDKEvent(session, (event) => event.type === 'compaction.cancelled');
+
+      await session.compact({ instruction: 'Keep the compact test pending.' });
+      await expect(started).resolves.toMatchObject({
+        type: 'compaction.started',
+        sessionId: session.id,
+        trigger: 'manual',
+      });
+      await session.cancelCompaction();
+
+      await expect(cancelled).resolves.toMatchObject({
+        type: 'compaction.cancelled',
+        sessionId: session.id,
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects after the session is closed', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-cancel-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-cancel-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_cancel_closed', workDir });
+      await session.close();
+
+      await expect(session.cancel()).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.closed',
+      } satisfies Partial<KimiError>);
+      await expect(session.cancelCompaction()).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.closed',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+});
+
+async function writeFakeModelConfig(homeDir: string): Promise<void> {
+  await writeFile(
+    join(homeDir, 'config.toml'),
+    `
+default_model = "fake-model"
+
+[providers.local]
+type = "kimi"
+base_url = "https://example.test/v1"
+api_key = "sk-test"
+
+[models.fake-model]
+provider = "local"
+model = "fake-model"
+max_context_size = 1000
+`,
+    'utf-8',
+  );
+}
+
+function waitForAbort(signal: AbortSignal | undefined): Promise<void> {
+  if (signal?.aborted === true) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    signal?.addEventListener(
+      'abort',
+      () => {
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}
+
+function throwAbortError(): never {
+  throw new DOMException('The operation was aborted.', 'AbortError');
+}
diff --git a/packages/node-sdk/test/session-event-types.test.ts b/packages/node-sdk/test/session-event-types.test.ts
new file mode 100644
index 000000000..24265cb7b
--- /dev/null
+++ b/packages/node-sdk/test/session-event-types.test.ts
@@ -0,0 +1,83 @@
+import { describe, expectTypeOf, it } from 'vitest';
+
+import type { ApprovalRequest, ApprovalResponse, Event, QuestionRequest } from '#/index';
+
+type EventByType<T extends Event['type']> = Extract<Event, { readonly type: T }>;
+
+describe('Event public types', () => {
+  it('narrows assistant deltas by type', () => {
+    expectTypeOf<EventByType<'assistant.delta'>['delta']>().toEqualTypeOf<string>();
+  });
+
+  it('narrows hook results by type', () => {
+    expectTypeOf<EventByType<'hook.result'>['hookEvent']>().toEqualTypeOf<string>();
+    expectTypeOf<EventByType<'hook.result'>['content']>().toEqualTypeOf<string>();
+    expectTypeOf<EventByType<'hook.result'>['blocked']>().toEqualTypeOf<boolean | undefined>();
+  });
+
+  it('narrows tool calls by type', () => {
+    expectTypeOf<EventByType<'tool.call.started'>['toolCallId']>().toEqualTypeOf<string>();
+    expectTypeOf<EventByType<'tool.call.started'>['name']>().toEqualTypeOf<string>();
+    expectTypeOf<EventByType<'tool.call.started'>['args']>().toEqualTypeOf<unknown>();
+  });
+
+  it('narrows subagent lifecycle events by type', () => {
+    expectTypeOf<EventByType<'subagent.spawned'>['subagentId']>().toEqualTypeOf<string>();
+    expectTypeOf<EventByType<'subagent.spawned'>['runInBackground']>().toEqualTypeOf<boolean>();
+  });
+
+  it('exposes approval and question reverse-RPC requests', () => {
+    expectTypeOf<ApprovalRequest['turnId']>().toEqualTypeOf<number | undefined>();
+    expectTypeOf<ApprovalRequest['toolName']>().toEqualTypeOf<string>();
+    expectTypeOf<QuestionRequest['questions'][number]['question']>().toEqualTypeOf<string>();
+  });
+
+  it('exposes optional session scope on approval responses', () => {
+    expectTypeOf<ApprovalResponse['scope']>().toEqualTypeOf<'session' | undefined>();
+  });
+
+  it('covers every event in exhaustive switches', () => {
+    function handle(event: Event): void {
+      switch (event.type) {
+        case 'agent.status.updated':
+        case 'session.meta.updated':
+        case 'skill.activated':
+        case 'error':
+        case 'turn.started':
+        case 'turn.ended':
+        case 'turn.step.started':
+        case 'turn.step.completed':
+        case 'turn.step.retrying':
+        case 'turn.step.interrupted':
+        case 'assistant.delta':
+        case 'hook.result':
+        case 'thinking.delta':
+        case 'tool.call.delta':
+        case 'tool.call.started':
+        case 'tool.progress':
+        case 'tool.result':
+        case 'tool.list.updated':
+        case 'mcp.server.status':
+        case 'subagent.spawned':
+        case 'subagent.completed':
+        case 'subagent.failed':
+        case 'compaction.started':
+        case 'compaction.blocked':
+        case 'compaction.cancelled':
+        case 'compaction.completed':
+        case 'background.task.started':
+        case 'background.task.updated':
+        case 'background.task.terminated':
+          return;
+        default:
+          assertNever(event);
+      }
+    }
+
+    expectTypeOf(handle).toEqualTypeOf<(event: Event) => void>();
+  });
+});
+
+function assertNever(value: never): never {
+  throw new Error(String(value));
+}
diff --git a/packages/node-sdk/test/session-plan-compact-usage-resume.test.ts b/packages/node-sdk/test/session-plan-compact-usage-resume.test.ts
new file mode 100644
index 000000000..74c3ec3db
--- /dev/null
+++ b/packages/node-sdk/test/session-plan-compact-usage-resume.test.ts
@@ -0,0 +1,340 @@
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { KimiHarness, type Event, type KimiError } from '#/index';
+
+import { makeTempDir, removeTempDirs } from './session-runtime-helpers';
+import { TEST_IDENTITY } from './test-identity';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await removeTempDirs(tempDirs);
+});
+
+describe('Session plan, compact, usage, and resume APIs', () => {
+  it('sets plan mode through manualEnterPlan and clears the active plan file', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-plan-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-plan-work-');
+    await writeTestConfig(homeDir);
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_plan_runtime', workDir });
+
+      const planOn = waitForSessionEvent(
+        session,
+        (event) => event.type === 'agent.status.updated' && event.planMode === true,
+      );
+      await session.setPlanMode(true);
+      await expect(planOn).resolves.toMatchObject({
+        type: 'agent.status.updated',
+        planMode: true,
+      });
+
+      await expect(session.clearPlan()).resolves.toBeUndefined();
+      await expect(session.getPlan()).resolves.toMatchObject({
+        content: '',
+      });
+      await session.cancel();
+
+      const planOff = waitForSessionEvent(
+        session,
+        (event) => event.type === 'agent.status.updated' && event.planMode === false,
+      );
+      await session.setPlanMode(false);
+      await expect(planOff).resolves.toMatchObject({
+        type: 'agent.status.updated',
+        planMode: false,
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('prepares the plans directory without creating plan files on repeated toggles', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-plan-toggle-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-plan-toggle-work-');
+    await writeTestConfig(homeDir);
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_plan_toggle_runtime', workDir });
+
+      await session.setPlanMode(true);
+      const firstPlan = await session.getPlan();
+      if (firstPlan === null) throw new Error('expected first plan');
+      const plansDir = dirname(firstPlan.path);
+      await expect(markdownFiles(plansDir)).resolves.toEqual([]);
+
+      await session.setPlanMode(false);
+      await session.setPlanMode(true);
+      const secondPlan = await session.getPlan();
+      if (secondPlan === null) throw new Error('expected second plan');
+
+      expect(secondPlan.path).not.toBe(firstPlan.path);
+      expect(dirname(secondPlan.path)).toBe(plansDir);
+      await expect(markdownFiles(plansDir)).resolves.toEqual([]);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('starts manual compaction with an optional instruction', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-compact-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-compact-work-');
+    await writeTestConfig(homeDir);
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_compact_runtime', workDir });
+
+      const started = waitForSessionEvent(session, (event) => event.type === 'compaction.started');
+      await session.compact({ instruction: 'Keep important facts.' });
+
+      await expect(started).resolves.toMatchObject({
+        type: 'compaction.started',
+        trigger: 'manual',
+        instruction: 'Keep important facts.',
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('returns current session usage totals', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-usage-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-usage-work-');
+    await writeTestConfig(homeDir);
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_usage_runtime', workDir });
+
+      await expect(session.getUsage()).resolves.toEqual({});
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('resumes a persisted session and restores runtime plan mode from wire history', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-resume-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-resume-work-');
+    await writeTestConfig(homeDir);
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const created = await harness.createSession({
+        id: 'ses_resume_runtime',
+        workDir,
+        model: 'test-model',
+      });
+      await created.setPlanMode(true);
+      await expect(created.getPlan()).resolves.toMatchObject({
+        content: '',
+      });
+      await created.close();
+      expect(harness.getSession(created.id)).toBeUndefined();
+
+      const resumed = await harness.resumeSession({ id: created.id });
+
+      expect(resumed.id).toBe(created.id);
+      expect(resumed.workDir).toBe(workDir);
+      await expect(resumed.getStatus()).resolves.toMatchObject({
+        model: 'test-model',
+        planMode: true,
+      });
+      await expect(resumed.getPlan()).resolves.toMatchObject({
+        content: '',
+        path: expect.stringContaining('/plans/'),
+      });
+      expect(harness.getSession(created.id)).toBe(resumed);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it.todo('marks resumed plan mode active when the restored plan has no plan data', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-resume-legacy-plan-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-resume-legacy-plan-work-');
+    await writeTestConfig(homeDir);
+    const createdHarness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+    let sessionId = '';
+    let sessionDir = '';
+
+    try {
+      const created = await createdHarness.createSession({
+        id: 'ses_resume_legacy_plan_runtime',
+        workDir,
+        model: 'test-model',
+      });
+      await created.setPlanMode(true);
+      const summary = created.summary;
+      expect(summary).toBeDefined();
+      sessionId = created.id;
+      sessionDir = summary!.sessionDir;
+    } finally {
+      await createdHarness.close();
+    }
+
+    await removeManualPlanIds(sessionDir);
+
+    const resumedHarness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+    try {
+      const resumed = await resumedHarness.resumeSession({ id: sessionId });
+
+      await expect(resumed.getStatus()).resolves.toMatchObject({
+        planMode: true,
+      });
+      await expect(resumed.getPlan()).resolves.toBeNull();
+    } finally {
+      await resumedHarness.close();
+    }
+  });
+
+  it('forks a session and returns an active fork session', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-fork-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-fork-work-');
+    await writeTestConfig(homeDir);
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const source = await harness.createSession({
+        id: 'ses_fork_runtime_source',
+        workDir,
+        model: 'test-model',
+        metadata: { source: true },
+      });
+      await source.setPlanMode(true);
+      const sourcePlan = await source.getPlan();
+      if (sourcePlan === null) throw new Error('expected source plan');
+      await mkdir(dirname(sourcePlan.path), { recursive: true });
+      await writeFile(sourcePlan.path, 'source plan', 'utf-8');
+
+      const fork = await harness.forkSession({
+        id: source.id,
+        forkId: 'ses_fork_runtime_child',
+        title: 'Forked runtime',
+        metadata: { child: true },
+      });
+
+      expect(fork.id).toBe('ses_fork_runtime_child');
+      expect(fork.workDir).toBe(workDir);
+      await expect(fork.getStatus()).resolves.toMatchObject({ model: 'test-model' });
+      expect(harness.getSession(fork.id)).toBe(fork);
+      await expect(fork.getUsage()).resolves.toEqual({});
+
+      const forkSummary = fork.summary;
+      expect(forkSummary).toBeDefined();
+      const forkPlan = await fork.getPlan();
+      expect(forkPlan).toEqual({
+        id: sourcePlan.id,
+        content: 'source plan',
+        path: join(forkSummary!.sessionDir, 'agents', 'main', 'plans', `${sourcePlan.id}.md`),
+      });
+      expect(forkPlan?.path).not.toBe(sourcePlan.path);
+      const forkWire = await readFile(
+        join(forkSummary!.sessionDir, 'agents', 'main', 'wire.jsonl'),
+        'utf-8',
+      );
+      const enterRecord = forkWire
+        .trim()
+        .split('\n')
+        .map((line) => JSON.parse(line) as Record<string, unknown>)
+        .find((record) => record['type'] === 'plan_mode.enter');
+      expect(enterRecord).toEqual({
+        type: 'plan_mode.enter',
+        id: sourcePlan.id,
+        time: expect.any(Number),
+      });
+      const forkState = JSON.parse(
+        await readFile(join(forkSummary!.sessionDir, 'state.json'), 'utf-8'),
+      ) as {
+        title?: string;
+        forkedFrom?: string;
+        agents?: { main?: { homedir?: string } };
+        custom?: Record<string, unknown>;
+      };
+      expect(forkState.title).toBe('Forked runtime');
+      expect(forkState.forkedFrom).toBe(source.id);
+      expect(forkState.agents?.main?.homedir).toBe(join(forkSummary!.sessionDir, 'agents', 'main'));
+      expect(forkState.custom).toMatchObject({ source: true, child: true });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects an empty resume id', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-resume-empty-home-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      await expect(harness.resumeSession({ id: '   ' })).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.id_empty',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+});
+
+async function removeManualPlanIds(sessionDir: string): Promise<void> {
+  const wirePath = join(sessionDir, 'agents', 'main', 'wire.jsonl');
+  const raw = await readFile(wirePath, 'utf-8');
+  const lines = raw
+    .split('\n')
+    .filter((line) => line.length > 0)
+    .flatMap((line) => {
+      const record = JSON.parse(line) as Record<string, unknown>;
+      if (record['type'] === 'plan.enter') return [];
+      if (record['type'] === 'plan.manual_enter') delete record['id'];
+      return [JSON.stringify(record)];
+    });
+  await writeFile(wirePath, `${lines.join('\n')}\n`, 'utf-8');
+}
+
+function waitForSessionEvent(
+  session: { onEvent(listener: (event: Event) => void): () => void },
+  predicate: (event: Event) => boolean,
+): Promise<Event> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      unsubscribe();
+      reject(new Error('Timed out waiting for session event'));
+    }, 1_000);
+    const unsubscribe = session.onEvent((event) => {
+      if (!predicate(event)) return;
+      clearTimeout(timeout);
+      unsubscribe();
+      resolve(event);
+    });
+  });
+}
+
+async function writeTestConfig(homeDir: string): Promise<void> {
+  await writeFile(
+    join(homeDir, 'config.toml'),
+    `
+default_model = "test-model"
+
+[providers.local]
+type = "openai"
+base_url = "https://example.test/v1"
+api_key = "sk-test"
+
+[models.test-model]
+provider = "local"
+model = "test-model"
+max_context_size = 200000
+`,
+    'utf-8',
+  );
+}
+
+async function markdownFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir);
+  return entries.filter((entry) => entry.endsWith('.md')).toSorted();
+}
diff --git a/packages/node-sdk/test/session-prompt-events.test.ts b/packages/node-sdk/test/session-prompt-events.test.ts
new file mode 100644
index 000000000..50a4537f0
--- /dev/null
+++ b/packages/node-sdk/test/session-prompt-events.test.ts
@@ -0,0 +1,370 @@
+import { existsSync } from 'node:fs';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import type * as KosongModule from '@moonshot-ai/kosong';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { Event } from '#/index';
+
+import { TEST_IDENTITY } from './test-identity';
+
+const fakeProviderState = vi.hoisted(() => ({
+  calls: [] as Array<{
+    readonly systemPrompt: string;
+    readonly history: unknown;
+  }>,
+  providerConfigs: [] as unknown[],
+  responseText: 'hello from fake provider',
+}));
+
+vi.mock('@moonshot-ai/kosong', async (importOriginal) => {
+  const actual = await importOriginal<typeof KosongModule>();
+  return {
+    ...actual,
+    createProvider: (config: unknown) => {
+      fakeProviderState.providerConfigs.push(config);
+      return {
+        name: 'fake',
+        modelName: 'fake-model',
+        thinkingEffort: null,
+        async generate(systemPrompt: string, _tools: unknown, history: unknown) {
+          fakeProviderState.calls.push({ systemPrompt, history });
+          return {
+            id: 'fake-response',
+            usage: {
+              inputOther: 0,
+              output: 1,
+              inputCacheRead: 0,
+              inputCacheCreation: 0,
+            },
+            finishReason: 'completed',
+            rawFinishReason: 'stop',
+            async *[Symbol.asyncIterator]() {
+              yield { type: 'text', text: fakeProviderState.responseText };
+            },
+          };
+        },
+        withThinking() {
+          return this;
+        },
+      };
+    },
+  };
+});
+
+const { KimiHarness } = await import('#/index');
+
+const tempDirs: string[] = [];
+
+beforeEach(() => {
+  fakeProviderState.calls.length = 0;
+  fakeProviderState.providerConfigs.length = 0;
+  fakeProviderState.responseText = 'hello from fake provider';
+});
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await removeTempDir(dir);
+  }
+});
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'kimi-sdk-prompt-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+async function removeTempDir(dir: string): Promise<void> {
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    try {
+      await rm(dir, { recursive: true, force: true });
+      return;
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== 'ENOTEMPTY' && code !== 'EBUSY' && code !== 'EPERM') {
+        throw error;
+      }
+      await delay(10);
+    }
+  }
+
+  await rm(dir, { recursive: true, force: true });
+}
+
+describe('Session.prompt events', () => {
+  it('persists sanitized prompt metadata without marking the title custom', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      await configureFakeProvider(harness);
+      const session = await harness.createSession({ id: 'ses_prompt_meta', workDir });
+      const events: Event[] = [];
+      const unsubscribe = session.onEvent((event) => {
+        events.push(event);
+      });
+
+      let done = waitForEvent(session, (event) => event.type === 'turn.ended');
+      await session.prompt('use api_key=secret-value for the request');
+      await done;
+
+      const statePath = join(session.summary!.sessionDir, 'state.json');
+      const firstState = JSON.parse(await readFile(statePath, 'utf-8')) as Record<string, unknown>;
+      expect(firstState['title']).toBe('use api_key=[redacted] for the request');
+      expect(firstState['isCustomTitle']).toBe(false);
+      expect(firstState['lastPrompt']).toBe('use api_key=[redacted] for the request');
+      expect(events).toContainEqual(
+        expect.objectContaining({
+          type: 'session.meta.updated',
+          title: 'use api_key=[redacted] for the request',
+          patch: expect.objectContaining({
+            isCustomTitle: false,
+            lastPrompt: 'use api_key=[redacted] for the request',
+          }),
+        }),
+      );
+
+      events.length = 0;
+      done = waitForEvent(session, (event) => event.type === 'turn.ended');
+      await session.prompt('second prompt');
+      await done;
+
+      const secondState = JSON.parse(await readFile(statePath, 'utf-8')) as Record<string, unknown>;
+      expect(secondState['title']).toBe('use api_key=[redacted] for the request');
+      expect(secondState['isCustomTitle']).toBe(false);
+      expect(secondState['lastPrompt']).toBe('second prompt');
+      expect(events).toContainEqual(
+        expect.objectContaining({
+          type: 'session.meta.updated',
+          patch: expect.objectContaining({
+            lastPrompt: 'second prompt',
+          }),
+        }),
+      );
+
+      events.length = 0;
+      done = waitForEvent(session, (event) => event.type === 'turn.ended');
+      await session.prompt([{ type: 'image_url', imageUrl: { url: 'https://example.com/a.png' } }]);
+      await done;
+      unsubscribe();
+
+      const mediaState = JSON.parse(await readFile(statePath, 'utf-8')) as Record<string, unknown>;
+      expect(mediaState['title']).toBe('use api_key=[redacted] for the request');
+      expect(mediaState['lastPrompt']).toBe('[image]');
+      expect(events).toContainEqual(
+        expect.objectContaining({
+          type: 'session.meta.updated',
+          patch: expect.objectContaining({
+            lastPrompt: '[image]',
+          }),
+        }),
+      );
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('emits mapped turn events through Session.onEvent', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      await configureFakeProvider(harness);
+      const session = await harness.createSession({ id: 'ses_prompt_events', workDir });
+      const events: Event[] = [];
+      const done = waitForEvent(session, (event) => event.type === 'turn.ended');
+      const unsubscribe = session.onEvent((event) => {
+        events.push(event);
+      });
+
+      await session.prompt('hello');
+      await done;
+      unsubscribe();
+
+      expect(events.some((event) => event.type === 'turn.started')).toBe(true);
+      expect(events).toContainEqual(
+        expect.objectContaining({
+          type: 'assistant.delta',
+          sessionId: session.id,
+          turnId: 0,
+          delta: 'hello from fake provider',
+        }),
+      );
+      expect(events).toContainEqual(
+        expect.objectContaining({
+          type: 'turn.ended',
+          sessionId: session.id,
+          turnId: 0,
+          reason: 'completed',
+        }),
+      );
+      expect(fakeProviderState.calls[0]?.systemPrompt).toContain('You are Kimi Code CLI');
+      expect(fakeProviderState.calls[0]?.systemPrompt).toContain('Available skills');
+      expect(fakeProviderState.providerConfigs[0]).toMatchObject({
+        type: 'kimi',
+        defaultHeaders: expect.objectContaining({
+          'X-Msh-Platform': 'kimi-code-cli',
+          'User-Agent': 'kimi-code-cli/0.0.0-test',
+        }),
+      });
+      expect(existsSync(join(homeDir, 'device_id'))).toBe(true);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('supports onEvent unsubscribe without touching runtime wire directly', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      await configureFakeProvider(harness);
+      const session = await harness.createSession({ id: 'ses_prompt_unsubscribe', workDir });
+      const unsubscribedEvents: Event[] = [];
+      const unsubscribe = session.onEvent((event) => {
+        unsubscribedEvents.push(event);
+      });
+      unsubscribe();
+      const done = waitForEvent(session, (event) => event.type === 'turn.ended');
+
+      await session.prompt([{ type: 'text', text: 'hello' }]);
+      await done;
+
+      expect(unsubscribedEvents).toEqual([]);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('runs init through generateAgentsMd RPC as a system trigger without prompt metadata updates', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      await configureFakeProvider(harness);
+      const session = await harness.createSession({ id: 'ses_init_rpc', workDir });
+      const events: Event[] = [];
+      const unsubscribe = session.onEvent((event) => {
+        events.push(event);
+      });
+
+      await session.init();
+      unsubscribe();
+
+      const spawned = events.find((event) => event.type === 'subagent.spawned');
+      expect(spawned).toMatchObject({
+        type: 'subagent.spawned',
+        sessionId: session.id,
+        agentId: 'main',
+        subagentName: 'coder',
+        parentToolCallId: 'generate-agents-md',
+      });
+      expect(events).toContainEqual(
+        expect.objectContaining({
+          type: 'turn.started',
+          sessionId: session.id,
+          agentId: spawned?.type === 'subagent.spawned' ? spawned.subagentId : undefined,
+          origin: { kind: 'system_trigger', name: 'init' },
+        }),
+      );
+      expect(events).not.toContainEqual(
+        expect.objectContaining({
+          type: 'session.meta.updated',
+        }),
+      );
+      expect(fakeProviderState.calls[0]?.history).toMatchObject([
+        {
+          role: 'user',
+          content: [
+            expect.objectContaining({
+              text: expect.stringContaining('Task requirements:'),
+            }),
+          ],
+        },
+      ]);
+
+      const statePath = join(session.summary!.sessionDir, 'state.json');
+      const state = JSON.parse(await readFile(statePath, 'utf-8')) as Record<string, unknown>;
+      expect(state['lastPrompt']).toBeUndefined();
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects empty prompt input', async () => {
+    const homeDir = await makeTempDir();
+    const workDir = await makeTempDir();
+    const harness = new KimiHarness({
+      identity: TEST_IDENTITY,
+      homeDir,
+    });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_empty_prompt', workDir });
+      await expect(session.prompt('   ')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'request.prompt_input_empty',
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+});
+
+async function configureFakeProvider(harness: InstanceType<typeof KimiHarness>): Promise<void> {
+  await harness.setConfig({
+    providers: {
+      local: {
+        type: 'kimi',
+        apiKey: 'sk-test',
+      },
+    },
+    models: {
+      'fake-model': {
+        provider: 'local',
+        model: 'fake-model',
+        maxContextSize: 262144,
+      },
+    },
+    defaultModel: 'fake-model',
+  });
+}
+
+function waitForEvent(
+  session: {
+    onEvent(listener: (event: Event) => void): () => void;
+  },
+  predicate: (event: Event) => boolean,
+): Promise<Event> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      unsubscribe();
+      reject(new Error('Timed out waiting for session event'));
+    }, 1_000);
+    const unsubscribe = session.onEvent((event) => {
+      if (!predicate(event)) return;
+      clearTimeout(timeout);
+      unsubscribe();
+      resolve(event);
+    });
+  });
+}
diff --git a/packages/node-sdk/test/session-prompt-input.test.ts b/packages/node-sdk/test/session-prompt-input.test.ts
new file mode 100644
index 000000000..df32e2b4b
--- /dev/null
+++ b/packages/node-sdk/test/session-prompt-input.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { SDKRpcClient } from '../src/rpc';
+import { Session } from '../src/session';
+
+describe('Session.prompt input normalization', () => {
+  it('passes multimodal prompt parts through to the core RPC client', async () => {
+    const prompt = vi.fn(async () => {});
+    const session = new Session({
+      id: 'ses_multimodal_prompt',
+      workDir: '/tmp/work',
+      rpc: { prompt } as unknown as SDKRpcClient,
+    });
+    const input = [
+      { type: 'text', text: 'describe these' },
+      { type: 'image_url', imageUrl: { url: 'data:image/png;base64,AAAA' } },
+      { type: 'video_url', videoUrl: { url: 'ms://file-123', id: 'file-123' } },
+    ] as const;
+
+    await session.prompt(input);
+
+    expect(prompt).toHaveBeenCalledWith({
+      sessionId: 'ses_multimodal_prompt',
+      input,
+    });
+  });
+});
diff --git a/packages/node-sdk/test/session-question-handler.test.ts b/packages/node-sdk/test/session-question-handler.test.ts
new file mode 100644
index 000000000..807202b32
--- /dev/null
+++ b/packages/node-sdk/test/session-question-handler.test.ts
@@ -0,0 +1,148 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { Session, type QuestionHandler, type QuestionRequest, type QuestionResult } from '#/index';
+import type { SDKRpcClient } from '#/rpc';
+
+describe('Session question handler', () => {
+  it('registers a question handler and returns handler results', async () => {
+    const rpc = new FakeSDKRpcClient();
+    const session = new Session({
+      id: 'ses_question_handler',
+      workDir: '/tmp',
+      rpc: rpc.asRpc(),
+    });
+    const handler = vi.fn(async (request: QuestionRequest) => {
+      expect(request).toMatchObject({
+        questions: [
+          {
+            question: 'Pick one?',
+            options: [{ label: 'A' }],
+          },
+        ],
+      });
+      return { 'Pick one?': 'A' };
+    });
+    session.setQuestionHandler(handler);
+
+    await expect(
+      rpc.requestQuestion(session.id, 'main', questionRequest('Pick one?')),
+    ).resolves.toEqual({ 'Pick one?': 'A' });
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('sends null question results when no handler is registered', async () => {
+    const rpc = new FakeSDKRpcClient();
+    const session = new Session({
+      id: 'ses_question_default',
+      workDir: '/tmp',
+      rpc: rpc.asRpc(),
+    });
+
+    await expect(
+      rpc.requestQuestion(session.id, 'main', questionRequest('Continue?')),
+    ).resolves.toBeNull();
+    await session.close();
+    expect(rpc.closeSession).toHaveBeenCalledWith({ sessionId: session.id });
+  });
+
+  it('sends null question results when the handler throws', async () => {
+    const rpc = new FakeSDKRpcClient();
+    const session = new Session({
+      id: 'ses_question_throw',
+      workDir: '/tmp',
+      rpc: rpc.asRpc(),
+    });
+    session.setQuestionHandler(() => {
+      throw new Error('boom');
+    });
+
+    await expect(
+      rpc.requestQuestion(session.id, 'main', questionRequest('Continue?')),
+    ).resolves.toBeNull();
+  });
+
+  it('responds to concurrent question requests', async () => {
+    const rpc = new FakeSDKRpcClient();
+    const session = new Session({
+      id: 'ses_question_concurrent',
+      workDir: '/tmp',
+      rpc: rpc.asRpc(),
+    });
+    session.setQuestionHandler((request) => ({ [request.questions[0]!.question]: true }));
+
+    await expect(rpc.requestQuestion(session.id, 'main', questionRequest('A?'))).resolves.toEqual({
+      'A?': true,
+    });
+    await expect(rpc.requestQuestion(session.id, 'main', questionRequest('B?'))).resolves.toEqual({
+      'B?': true,
+    });
+  });
+
+  it('responds to the original subagent id', async () => {
+    const rpc = new FakeSDKRpcClient();
+    const session = new Session({
+      id: 'ses_question_subagent',
+      workDir: '/tmp',
+      rpc: rpc.asRpc(),
+    });
+    const handler = vi.fn(() => ({ 'Continue?': 'yes' }));
+    session.setQuestionHandler(handler);
+
+    await expect(
+      rpc.requestQuestion(session.id, 'agent-1', questionRequest('Continue?')),
+    ).resolves.toEqual({ 'Continue?': 'yes' });
+
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionId: session.id,
+        agentId: 'agent-1',
+      }),
+    );
+  });
+});
+
+function questionRequest(question: string): QuestionRequest {
+  return {
+    questions: [
+      {
+        question,
+        options: [{ label: 'A' }],
+      },
+    ],
+  };
+}
+
+class FakeSDKRpcClient {
+  private readonly questionHandlers = new Map<string, QuestionHandler>();
+  readonly closeSession = vi.fn(async (_input: { readonly sessionId: string }) => {});
+
+  asRpc(): SDKRpcClient {
+    return this as unknown as SDKRpcClient;
+  }
+
+  setQuestionHandler(sessionId: string, handler: QuestionHandler | undefined): void {
+    if (handler === undefined) {
+      this.questionHandlers.delete(sessionId);
+      return;
+    }
+    this.questionHandlers.set(sessionId, handler);
+  }
+
+  async requestQuestion(
+    sessionId: string,
+    agentId: string,
+    request: QuestionRequest,
+  ): Promise<QuestionResult> {
+    const handler = this.questionHandlers.get(sessionId);
+    if (handler === undefined) return null;
+    try {
+      return await handler({ ...request, sessionId, agentId } as QuestionRequest);
+    } catch {
+      return null;
+    }
+  }
+
+  clearSessionHandlers(sessionId: string): void {
+    this.questionHandlers.delete(sessionId);
+  }
+}
diff --git a/packages/node-sdk/test/session-runtime-helpers.ts b/packages/node-sdk/test/session-runtime-helpers.ts
new file mode 100644
index 000000000..94035f0f9
--- /dev/null
+++ b/packages/node-sdk/test/session-runtime-helpers.ts
@@ -0,0 +1,159 @@
+import { readFile, rm, mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import type { Event } from '#/index';
+
+export interface AgentWirePayload {
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+export interface AgentSessionWireRecord {
+  readonly type: 'agent';
+  readonly agentId: string;
+  readonly event: AgentWirePayload;
+}
+
+export async function makeTempDir(tempDirs: string[], prefix: string): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+}
+
+export async function removeTempDirs(tempDirs: string[]): Promise<void> {
+  for (const dir of tempDirs.splice(0)) {
+    await removeTempDir(dir);
+  }
+}
+
+export async function waitForAgentWireEvent(
+  homeDir: string,
+  sessionId: string,
+  eventType: string,
+  predicate: (event: AgentWirePayload) => boolean = () => true,
+): Promise<AgentWirePayload> {
+  const deadline = Date.now() + 1_000;
+  while (Date.now() < deadline) {
+    const events = await readWireEvents(homeDir, sessionId);
+    for (const event of events) {
+      const agentEvent = toMainAgentWirePayload(event);
+      if (agentEvent === undefined) continue;
+      if (agentEvent.type !== eventType) continue;
+      if (predicate(agentEvent)) {
+        return agentEvent;
+      }
+    }
+    await delay(10);
+  }
+
+  throw new Error(`Timed out waiting for ${eventType} in ${sessionId}`);
+}
+
+export function waitForSDKEvent(
+  session: {
+    onEvent(listener: (event: Event) => void): () => void;
+  },
+  predicate: (event: Event) => boolean,
+  timeoutMs = 1_000,
+): Promise<Event> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      unsubscribe();
+      reject(new Error('Timed out waiting for session event'));
+    }, timeoutMs);
+    const unsubscribe = session.onEvent((event) => {
+      if (!predicate(event)) return;
+      clearTimeout(timeout);
+      unsubscribe();
+      resolve(event);
+    });
+  });
+}
+
+async function readWireEvents(homeDir: string, sessionId: string): Promise<readonly unknown[]> {
+  const sessionDir = await readIndexedSessionDir(homeDir, sessionId);
+  if (sessionDir === undefined) return [];
+
+  try {
+    const raw = await readFile(join(sessionDir, 'agents', 'main', 'wire.jsonl'), 'utf-8');
+    return raw
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => JSON.parse(line) as unknown);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+function toMainAgentWirePayload(value: unknown): AgentWirePayload | undefined {
+  if (isAgentWirePayload(value)) return value;
+  if (!isAgentSessionWireRecord(value)) return undefined;
+  if (value.agentId !== 'main') return undefined;
+  return value.event;
+}
+
+async function readIndexedSessionDir(
+  homeDir: string,
+  sessionId: string,
+): Promise<string | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(join(homeDir, 'session_index.jsonl'), 'utf-8');
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return undefined;
+    throw error;
+  }
+
+  let sessionDir: string | undefined;
+  for (const line of raw.split(/\r?\n/)) {
+    if (line.trim().length === 0) continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line) as unknown;
+    } catch {
+      continue;
+    }
+    if (!isRecord(parsed)) continue;
+    if (parsed['sessionId'] !== sessionId) continue;
+    if (typeof parsed['sessionDir'] !== 'string') continue;
+    sessionDir = parsed['sessionDir'];
+  }
+  return sessionDir;
+}
+
+function isAgentSessionWireRecord(value: unknown): value is AgentSessionWireRecord {
+  if (!isRecord(value)) return false;
+  if (value['type'] !== 'agent') return false;
+  if (typeof value['agentId'] !== 'string') return false;
+  return isAgentWirePayload(value['event']);
+}
+
+function isAgentWirePayload(value: unknown): value is AgentWirePayload {
+  return isRecord(value) && typeof value['type'] === 'string';
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+async function removeTempDir(dir: string): Promise<void> {
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    try {
+      await rm(dir, { recursive: true, force: true });
+      return;
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== 'ENOTEMPTY' && code !== 'EBUSY' && code !== 'EPERM') {
+        throw error;
+      }
+      await delay(10);
+    }
+  }
+
+  await rm(dir, { recursive: true, force: true });
+}
diff --git a/packages/node-sdk/test/session-set-model.test.ts b/packages/node-sdk/test/session-set-model.test.ts
new file mode 100644
index 000000000..b3bcdcf83
--- /dev/null
+++ b/packages/node-sdk/test/session-set-model.test.ts
@@ -0,0 +1,177 @@
+import { join } from 'node:path';
+
+import { FileTokenStorage, type TokenInfo } from '@moonshot-ai/kimi-code-oauth';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { KimiHarness, type KimiError } from '#/index';
+import { makeTempDir, removeTempDirs, waitForAgentWireEvent } from './session-runtime-helpers';
+import { TEST_IDENTITY } from './test-identity';
+
+const tempDirs: string[] = [];
+
+function freshToken(): TokenInfo {
+  return {
+    accessToken: 'oauth-access-token',
+    refreshToken: 'oauth-refresh-token',
+    expiresAt: Math.floor(Date.now() / 1000) + 3600,
+    scope: '',
+    tokenType: 'Bearer',
+    expiresIn: 3600,
+  };
+}
+
+afterEach(async () => {
+  await removeTempDirs(tempDirs);
+});
+
+describe('Session.setModel', () => {
+  it('updates the runtime model and sends config.update with the resolved model', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-model-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-model-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      await configureLocalProvider(harness);
+      const session = await harness.createSession({
+        id: 'ses_model_wire',
+        workDir,
+        model: 'initial-model',
+      });
+
+      await session.setModel('next-model');
+
+      await expect(session.getStatus()).resolves.toMatchObject({ model: 'next-model' });
+      const configEvent = await waitForAgentWireEvent(
+        homeDir,
+        session.id,
+        'config.update',
+        (event) => event['modelAlias'] === 'next-model',
+      );
+      expect(configEvent).toMatchObject({
+        type: 'config.update',
+        modelAlias: 'next-model',
+      });
+      expect(configEvent).not.toHaveProperty('provider');
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('resolves managed OAuth aliases before updating the runtime provider', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-model-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-model-work-');
+    await new FileTokenStorage(join(homeDir, 'credentials')).save('kimi-code', freshToken());
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      await harness.setConfig({
+        providers: {
+          'managed:kimi-code': {
+            type: 'kimi',
+            baseUrl: 'https://api.kimi.com/coding/v1',
+            apiKey: '',
+            oauth: { storage: 'file', key: 'oauth/kimi-code' },
+          },
+        },
+        models: {
+          'kimi-code/initial': {
+            provider: 'managed:kimi-code',
+            model: 'kimi-initial',
+            maxContextSize: 262144,
+          },
+          'kimi-code/kimi-for-coding': {
+            provider: 'managed:kimi-code',
+            model: 'kimi-for-coding',
+            maxContextSize: 262144,
+          },
+        },
+        defaultModel: 'kimi-code/initial',
+      });
+      const session = await harness.createSession({
+        id: 'ses_model_oauth_wire',
+        workDir,
+        model: 'kimi-code/initial',
+      });
+
+      await session.setModel('kimi-code/kimi-for-coding');
+
+      await expect(session.getStatus()).resolves.toMatchObject({
+        model: 'kimi-code/kimi-for-coding',
+      });
+      const configEvent = await waitForAgentWireEvent(
+        homeDir,
+        session.id,
+        'config.update',
+        (event) => event['modelAlias'] === 'kimi-code/kimi-for-coding',
+      );
+      expect(configEvent).toMatchObject({
+        type: 'config.update',
+        modelAlias: 'kimi-code/kimi-for-coding',
+      });
+      expect(configEvent).not.toHaveProperty('provider');
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects empty model names', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-model-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-model-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      await configureLocalProvider(harness);
+      const session = await harness.createSession({ id: 'ses_model_empty', workDir });
+
+      await expect(session.setModel('   ')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.model_empty',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects after the session is closed', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-model-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-model-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      await configureLocalProvider(harness);
+      const session = await harness.createSession({ id: 'ses_model_closed', workDir });
+      await session.close();
+
+      await expect(session.setModel('next-model')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.closed',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+});
+
+async function configureLocalProvider(harness: KimiHarness): Promise<void> {
+  await harness.setConfig({
+    providers: {
+      local: {
+        type: 'kimi',
+        apiKey: 'sk-test',
+      },
+    },
+    models: {
+      'initial-model': {
+        provider: 'local',
+        model: 'initial-model',
+        maxContextSize: 262144,
+      },
+      'next-model': {
+        provider: 'local',
+        model: 'next-model',
+        maxContextSize: 262144,
+      },
+    },
+    defaultProvider: 'local',
+  });
+}
diff --git a/packages/node-sdk/test/session-set-permission.test.ts b/packages/node-sdk/test/session-set-permission.test.ts
new file mode 100644
index 000000000..bf597364c
--- /dev/null
+++ b/packages/node-sdk/test/session-set-permission.test.ts
@@ -0,0 +1,80 @@
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { KimiHarness, type KimiError, type PermissionMode } from '#/index';
+import { makeTempDir, removeTempDirs, waitForAgentWireEvent } from './session-runtime-helpers';
+import { TEST_IDENTITY } from './test-identity';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await removeTempDirs(tempDirs);
+});
+
+describe('Session.setPermission', () => {
+  it.each(['yolo', 'manual', 'auto'] as const)(
+    'sends permission.set_mode with mode %s',
+    async (mode: PermissionMode) => {
+      const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-permission-home-');
+      const workDir = await makeTempDir(tempDirs, 'kimi-sdk-permission-work-');
+      const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+      try {
+        const session = await harness.createSession({
+          id: `ses_permission_${mode}`,
+          workDir,
+        });
+
+        await session.setPermission(mode);
+
+        await expect(
+          waitForAgentWireEvent(
+            homeDir,
+            session.id,
+            'permission.set_mode',
+            (event) => event['mode'] === mode,
+          ),
+        ).resolves.toMatchObject({
+          type: 'permission.set_mode',
+          mode,
+        });
+      } finally {
+        await harness.close();
+      }
+    },
+  );
+
+  it('rejects invalid permission modes', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-permission-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-permission-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_permission_invalid', workDir });
+
+      await expect(session.setPermission('invalid' as never)).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.permission_mode_invalid',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects after the session is closed', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-permission-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-permission-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_permission_closed', workDir });
+      await session.close();
+
+      await expect(session.setPermission('yolo')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.closed',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+});
diff --git a/packages/node-sdk/test/session-set-thinking.test.ts b/packages/node-sdk/test/session-set-thinking.test.ts
new file mode 100644
index 000000000..70e957a66
--- /dev/null
+++ b/packages/node-sdk/test/session-set-thinking.test.ts
@@ -0,0 +1,75 @@
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { KimiHarness, type KimiError } from '#/index';
+
+import { makeTempDir, removeTempDirs, waitForAgentWireEvent } from './session-runtime-helpers';
+import { TEST_IDENTITY } from './test-identity';
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await removeTempDirs(tempDirs);
+});
+
+describe('Session.setThinking', () => {
+  it('sends config.update with the new thinking level', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-thinking-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-thinking-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_thinking_wire', workDir });
+
+      await session.setThinking('low');
+
+      await expect(
+        waitForAgentWireEvent(
+          homeDir,
+          session.id,
+          'config.update',
+          (event) => event['thinkingLevel'] === 'low',
+        ),
+      ).resolves.toMatchObject({
+        type: 'config.update',
+        thinkingLevel: 'low',
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects empty thinking levels', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-thinking-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-thinking-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_thinking_empty', workDir });
+
+      await expect(session.setThinking('   ')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.thinking_empty',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects after the session is closed', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-thinking-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-thinking-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_thinking_closed', workDir });
+      await session.close();
+
+      await expect(session.setThinking('high')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.closed',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+});
diff --git a/packages/node-sdk/test/session-skills.test.ts b/packages/node-sdk/test/session-skills.test.ts
new file mode 100644
index 000000000..5be7bb2ec
--- /dev/null
+++ b/packages/node-sdk/test/session-skills.test.ts
@@ -0,0 +1,300 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import type * as KosongModule from '@moonshot-ai/kosong';
+import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi } from 'vitest';
+
+import type { Event, KimiError, SkillActivatedEvent, SkillSummary } from '#/index';
+import type { SDKRpcClient } from '#/rpc';
+
+import {
+  makeTempDir,
+  removeTempDirs,
+  waitForAgentWireEvent,
+  waitForSDKEvent,
+} from './session-runtime-helpers';
+import { TEST_IDENTITY } from './test-identity';
+
+const fakeProviderState = vi.hoisted(() => ({
+  histories: [] as unknown[],
+  responseText: 'skill response',
+}));
+
+vi.mock('@moonshot-ai/kosong', async (importOriginal) => {
+  const actual = await importOriginal<typeof KosongModule>();
+  return {
+    ...actual,
+    createProvider: () => ({
+      name: 'fake',
+      modelName: 'fake-model',
+      thinkingEffort: null,
+      async generate(_systemPrompt: string, _tools: unknown, history: unknown) {
+        fakeProviderState.histories.push(history);
+        return {
+          id: 'fake-response',
+          usage: {
+            inputOther: 0,
+            output: 1,
+            inputCacheRead: 0,
+            inputCacheCreation: 0,
+          },
+          finishReason: 'completed',
+          rawFinishReason: 'stop',
+          async *[Symbol.asyncIterator]() {
+            yield { type: 'text', text: fakeProviderState.responseText };
+          },
+        };
+      },
+      withThinking() {
+        return this;
+      },
+    }),
+  };
+});
+
+const { KimiHarness, Session } = await import('#/index');
+
+const tempDirs: string[] = [];
+
+beforeEach(() => {
+  fakeProviderState.histories.length = 0;
+  fakeProviderState.responseText = 'skill response';
+});
+
+afterEach(async () => {
+  await removeTempDirs(tempDirs);
+  vi.unstubAllEnvs();
+});
+
+describe('Session skills', () => {
+  it('lists session skills without exposing content', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-skills-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-skills-work-');
+    await writeSkill(workDir, 'review', [
+      '---',
+      'name: review',
+      'description: Review code',
+      'disable_model_invocation: true',
+      '---',
+      '',
+      'Review the requested file.',
+    ]);
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_sdk_skill_list', workDir });
+
+      const skills = await session.listSkills();
+      const listed = skills.find((skill) => skill.name === 'review');
+
+      expect(listed).toMatchObject({
+        name: 'review',
+        description: 'Review code',
+        source: 'project',
+        disableModelInvocation: true,
+      });
+      expect(listed?.path.endsWith('/.kimi-code/skills/review/SKILL.md')).toBe(true);
+      expect(JSON.stringify(skills)).not.toContain('Review the requested file.');
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('activates a skill through core and emits the public skill event', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-skills-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-skills-work-');
+    await writeSkill(workDir, 'review', [
+      '---',
+      'name: review',
+      'description: Review code',
+      '---',
+      '',
+      'Review the requested file.',
+    ]);
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_sdk_skill_activate', workDir });
+      const events: Event[] = [];
+      const unsubscribe = session.onEvent((event) => {
+        events.push(event);
+      });
+      const activated = waitForSDKEvent(session, (event) => event.type === 'skill.activated');
+      const metaUpdated = waitForSDKEvent(
+        session,
+        (event) => event.type === 'session.meta.updated',
+      );
+      const ended = waitForSDKEvent(session, (event) => event.type === 'turn.ended');
+
+      await session.activateSkill(' review ', ' src/app.ts ');
+      const activatedEvent = await activated;
+      const metaEvent = await metaUpdated;
+      await ended;
+      unsubscribe();
+
+      expect(activatedEvent).toMatchObject({
+        type: 'skill.activated',
+        sessionId: session.id,
+        agentId: 'main',
+        skillName: 'review',
+        skillArgs: 'src/app.ts',
+        trigger: 'user-slash',
+        skillSource: 'project',
+      });
+      expect(JSON.stringify(activatedEvent)).not.toContain('Review the requested file.');
+      expect(events.findIndex((event) => event.type === 'skill.activated')).toBeGreaterThanOrEqual(
+        0,
+      );
+      expect(events.findIndex((event) => event.type === 'turn.started')).toBeGreaterThan(
+        events.findIndex((event) => event.type === 'skill.activated'),
+      );
+      expect(metaEvent).toMatchObject({
+        type: 'session.meta.updated',
+        sessionId: session.id,
+        agentId: 'main',
+        title: '/review src/app.ts',
+        patch: {
+          title: '/review src/app.ts',
+          isCustomTitle: false,
+          lastPrompt: '/review src/app.ts',
+        },
+      });
+
+      const statePath = join(session.summary!.sessionDir, 'state.json');
+      const state = JSON.parse(await readFile(statePath, 'utf-8')) as Record<string, unknown>;
+      expect(state['title']).toBe('/review src/app.ts');
+      expect(state['isCustomTitle']).toBe(false);
+      expect(state['lastPrompt']).toBe('/review src/app.ts');
+
+      await expect(
+        waitForAgentWireEvent(
+          homeDir,
+          session.id,
+          'turn.prompt',
+          (event) => event['origin'] !== undefined,
+        ),
+      ).resolves.toMatchObject({
+        type: 'turn.prompt',
+        input: [
+          {
+            type: 'text',
+            text: 'Review the requested file.\n\nARGUMENTS: src/app.ts',
+          },
+        ],
+        origin: {
+          kind: 'skill_activation',
+          skillName: 'review',
+          skillArgs: 'src/app.ts',
+        },
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('uses KIMI_CODE_HOME as the user skill home through the SDK harness', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-skills-home-');
+    const processHome = await makeTempDir(tempDirs, 'kimi-sdk-skills-process-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-skills-work-');
+    vi.stubEnv('HOME', processHome);
+    vi.stubEnv('KIMI_CODE_HOME', homeDir);
+    await writeUserSkill(processHome, 'sdk-real-home-only', 'SDK real home skill');
+    await writeUserSkill(homeDir, 'sdk-sandbox-only', 'SDK sandbox skill');
+    const harness = new KimiHarness({ identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_sdk_skill_env_home', workDir });
+      const names = new Set((await session.listSkills()).map((skill) => skill.name));
+
+      expect(names.has('sdk-sandbox-only')).toBe(true);
+      expect(names.has('sdk-real-home-only')).toBe(false);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects empty names before calling RPC and rejects after close', async () => {
+    const activateSkill = vi.fn(async () => {});
+    const closeSession = vi.fn(async (_input: { readonly sessionId: string }) => {});
+    const clearSessionHandlers = vi.fn();
+    const listSkills = vi.fn(async () => []);
+    const session = new Session({
+      id: 'ses_skill_validation',
+      workDir: '/tmp/work',
+      rpc: {
+        activateSkill,
+        closeSession,
+        clearSessionHandlers,
+        listSkills,
+      } as unknown as SDKRpcClient,
+    });
+
+    await expect(session.activateSkill('   ')).rejects.toMatchObject({
+      name: 'KimiError',
+      code: 'skill.name_empty',
+    } satisfies Partial<KimiError>);
+    expect(activateSkill).not.toHaveBeenCalled();
+
+    await session.close();
+    expect(closeSession).toHaveBeenCalledWith({ sessionId: session.id });
+    expect(clearSessionHandlers).toHaveBeenCalledWith(session.id);
+    await expect(session.listSkills()).rejects.toMatchObject({
+      name: 'KimiError',
+      code: 'session.closed',
+    } satisfies Partial<KimiError>);
+    await expect(session.activateSkill('review')).rejects.toMatchObject({
+      name: 'KimiError',
+      code: 'session.closed',
+    } satisfies Partial<KimiError>);
+  });
+
+  it('finalizes local close state when the core close RPC fails', async () => {
+    const closeSession = vi.fn(async (_input: { readonly sessionId: string }) => {
+      throw new Error('flush failed');
+    });
+    const clearSessionHandlers = vi.fn();
+    const listSkills = vi.fn(async () => []);
+    const activateSkill = vi.fn(async () => {});
+    const session = new Session({
+      id: 'ses_close_failed',
+      workDir: '/tmp/work',
+      rpc: {
+        activateSkill,
+        closeSession,
+        clearSessionHandlers,
+        listSkills,
+      } as unknown as SDKRpcClient,
+    });
+
+    await expect(session.close()).rejects.toThrow('flush failed');
+    await expect(session.close()).resolves.toBeUndefined();
+    expect(closeSession).toHaveBeenCalledTimes(1);
+    expect(clearSessionHandlers).toHaveBeenCalledWith(session.id);
+    await expect(session.listSkills()).rejects.toMatchObject({
+      name: 'KimiError',
+      code: 'session.closed',
+    } satisfies Partial<KimiError>);
+  });
+
+  it('exposes public skill event and summary types', () => {
+    expectTypeOf<SkillSummary['name']>().toEqualTypeOf<string>();
+    expectTypeOf<SkillActivatedEvent['skillName']>().toEqualTypeOf<string>();
+  });
+});
+
+async function writeSkill(workDir: string, name: string, lines: readonly string[]): Promise<void> {
+  const dir = join(workDir, '.kimi-code', 'skills', name);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, 'SKILL.md'), lines.join('\n'));
+}
+
+async function writeUserSkill(userHomeDir: string, name: string, description: string): Promise<void> {
+  const dir = join(userHomeDir, '.kimi-code', 'skills', name);
+  await mkdir(dir, { recursive: true });
+  await writeFile(
+    join(dir, 'SKILL.md'),
+    ['---', `name: ${name}`, `description: ${description}`, '---', '', `${description}.`].join(
+      '\n',
+    ),
+  );
+}
diff --git a/packages/node-sdk/test/session-steer.test.ts b/packages/node-sdk/test/session-steer.test.ts
new file mode 100644
index 000000000..727dbf18e
--- /dev/null
+++ b/packages/node-sdk/test/session-steer.test.ts
@@ -0,0 +1,114 @@
+import type * as KosongModule from '@moonshot-ai/kosong';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { KimiError } from '#/index';
+
+import { makeTempDir, removeTempDirs, waitForAgentWireEvent } from './session-runtime-helpers';
+import { TEST_IDENTITY } from './test-identity';
+
+const fakeProviderState = vi.hoisted(() => ({
+  responseText: 'steer response',
+}));
+
+vi.mock('@moonshot-ai/kosong', async (importOriginal) => {
+  const actual = await importOriginal<typeof KosongModule>();
+  return {
+    ...actual,
+    createProvider: () => ({
+      name: 'fake',
+      modelName: 'fake-model',
+      thinkingEffort: null,
+      async generate() {
+        return {
+          id: 'fake-response',
+          usage: {
+            inputOther: 0,
+            output: 1,
+            inputCacheRead: 0,
+            inputCacheCreation: 0,
+          },
+          finishReason: 'completed',
+          rawFinishReason: 'stop',
+          async *[Symbol.asyncIterator]() {
+            yield { type: 'text', text: fakeProviderState.responseText };
+          },
+        };
+      },
+      withThinking() {
+        return this;
+      },
+    }),
+  };
+});
+
+const { KimiHarness } = await import('#/index');
+
+const tempDirs: string[] = [];
+
+beforeEach(() => {
+  fakeProviderState.responseText = 'steer response';
+});
+
+afterEach(async () => {
+  await removeTempDirs(tempDirs);
+});
+
+describe('Session.steer', () => {
+  it('sends turn.steer to the core session runtime', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-steer-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-steer-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_steer_wire', workDir });
+
+      await session.steer('also do this');
+
+      await expect(
+        waitForAgentWireEvent(homeDir, session.id, 'turn.steer', (event) =>
+          Array.isArray(event['input']),
+        ),
+      ).resolves.toMatchObject({
+        type: 'turn.steer',
+        input: [{ type: 'text', text: 'also do this' }],
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects empty steer input', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-steer-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-steer-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_steer_empty', workDir });
+
+      await expect(session.steer('   ')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'request.prompt_input_empty',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it('rejects after the session is closed', async () => {
+    const homeDir = await makeTempDir(tempDirs, 'kimi-sdk-steer-home-');
+    const workDir = await makeTempDir(tempDirs, 'kimi-sdk-steer-work-');
+    const harness = new KimiHarness({ homeDir, identity: TEST_IDENTITY });
+
+    try {
+      const session = await harness.createSession({ id: 'ses_steer_closed', workDir });
+      await session.close();
+
+      await expect(session.steer('hello')).rejects.toMatchObject({
+        name: 'KimiError',
+        code: 'session.closed',
+      } satisfies Partial<KimiError>);
+    } finally {
+      await harness.close();
+    }
+  });
+});
diff --git a/packages/node-sdk/test/telemetry.ts b/packages/node-sdk/test/telemetry.ts
new file mode 100644
index 000000000..fe9c9995a
--- /dev/null
+++ b/packages/node-sdk/test/telemetry.ts
@@ -0,0 +1,20 @@
+import type { TelemetryClient, TelemetryProperties } from '#/index';
+
+export interface TelemetryRecord {
+  readonly event: string;
+  readonly sessionId: string | null;
+  readonly properties?: TelemetryProperties;
+}
+
+export function recordingTelemetry(records: TelemetryRecord[]): TelemetryClient {
+  return {
+    track: (event, properties) => {
+      records.push({ event, sessionId: null, properties });
+    },
+    withContext: (patch) => ({
+      track: (event, properties) => {
+        records.push({ event, sessionId: patch.sessionId ?? null, properties });
+      },
+    }),
+  };
+}
diff --git a/packages/node-sdk/test/test-identity.ts b/packages/node-sdk/test/test-identity.ts
new file mode 100644
index 000000000..c06848660
--- /dev/null
+++ b/packages/node-sdk/test/test-identity.ts
@@ -0,0 +1,6 @@
+import type { KimiHostIdentity } from '#/index';
+
+export const TEST_IDENTITY: KimiHostIdentity = {
+  userAgentProduct: 'kimi-code-cli',
+  version: '0.0.0-test',
+};
diff --git a/packages/node-sdk/tsconfig.api-extractor.json b/packages/node-sdk/tsconfig.api-extractor.json
new file mode 100644
index 000000000..eeccd7a89
--- /dev/null
+++ b/packages/node-sdk/tsconfig.api-extractor.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": [".tmp-api-extractor/dts/**/*.d.ts"]
+}
diff --git a/packages/node-sdk/tsconfig.dts.json b/packages/node-sdk/tsconfig.dts.json
new file mode 100644
index 000000000..c1210f3de
--- /dev/null
+++ b/packages/node-sdk/tsconfig.dts.json
@@ -0,0 +1,21 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "declarationMap": false,
+    "sourceMap": false,
+    "outDir": ".tmp-api-extractor/dts",
+    "rootDir": ".."
+  },
+  "include": [
+    "src/**/*.ts",
+    "../agent-core/src/**/*.ts",
+    "../agent-core/src/prompt-modules.d.ts",
+    "../kaos/src/**/*.ts",
+    "../kosong/src/**/*.ts",
+    "../oauth/src/**/*.ts"
+  ],
+  "exclude": ["dist", ".tmp-api-extractor", "examples", "test", "../*/dist", "../*/test"]
+}
diff --git a/packages/node-sdk/tsconfig.json b/packages/node-sdk/tsconfig.json
new file mode 100644
index 000000000..93dc31e55
--- /dev/null
+++ b/packages/node-sdk/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ESNext"]
+  },
+  "include": ["src", "test", "examples", "../agent-core/src/prompt-modules.d.ts"]
+}
diff --git a/packages/node-sdk/tsdown.config.ts b/packages/node-sdk/tsdown.config.ts
new file mode 100644
index 000000000..34169d55d
--- /dev/null
+++ b/packages/node-sdk/tsdown.config.ts
@@ -0,0 +1,32 @@
+import { fileURLToPath } from 'node:url';
+
+import { defineConfig } from 'tsdown';
+
+import { rawTextPlugin } from '../../build/raw-text-plugin.mjs';
+
+export default defineConfig({
+  entry: ['./src/index.ts'],
+  format: ['esm'],
+  dts: false,
+  outDir: 'dist',
+  clean: true,
+  plugins: [rawTextPlugin()],
+  banner: {
+    js: [
+      "import { fileURLToPath as __cjsShimFileURLToPath } from 'node:url';",
+      "import { dirname as __cjsShimDirname } from 'node:path';",
+      'const __filename = __cjsShimFileURLToPath(import.meta.url);',
+      'const __dirname = __cjsShimDirname(__filename);',
+    ].join('\n'),
+  },
+  alias: {
+    '@moonshot-ai/agent-core': fileURLToPath(new URL('../agent-core/src/index.ts', import.meta.url)),
+    '@moonshot-ai/kaos': fileURLToPath(new URL('../kaos/src/index.ts', import.meta.url)),
+    '@moonshot-ai/kimi-code-oauth': fileURLToPath(new URL('../oauth/src/index.ts', import.meta.url)),
+    '@moonshot-ai/kosong': fileURLToPath(new URL('../kosong/src/index.ts', import.meta.url)),
+  },
+  deps: {
+    alwaysBundle: [/^@moonshot-ai\//],
+    neverBundle: [],
+  },
+});
diff --git a/packages/node-sdk/vitest.config.ts b/packages/node-sdk/vitest.config.ts
new file mode 100644
index 000000000..53a01f20e
--- /dev/null
+++ b/packages/node-sdk/vitest.config.ts
@@ -0,0 +1,21 @@
+import { fileURLToPath } from 'node:url';
+
+import { defineConfig } from 'vitest/config';
+
+import { rawTextPlugin } from '../../build/raw-text-plugin.mjs';
+
+export default defineConfig({
+  plugins: [rawTextPlugin()],
+  resolve: {
+    alias: {
+      '@moonshot-ai/agent-core': fileURLToPath(new URL('../agent-core/src/index.ts', import.meta.url)),
+      '@moonshot-ai/kimi-code-oauth': fileURLToPath(
+        new URL('../oauth/src/index.ts', import.meta.url),
+      ),
+    },
+  },
+  test: {
+    name: 'kimi-sdk',
+    include: ['test/**/*.test.ts'],
+  },
+});
diff --git a/packages/oauth/README.md b/packages/oauth/README.md
new file mode 100644
index 000000000..6cc8d6ec7
--- /dev/null
+++ b/packages/oauth/README.md
@@ -0,0 +1,11 @@
+# @moonshot-ai/kimi-code-oauth
+
+OAuth toolkit for Kimi Code managed authentication.
+
+Part of the [Kimi Code](https://github.com/MoonshotAI/kimi-code) monorepo.
+
+See the main repository for documentation, issues, and contribution guidelines.
+
+## License
+
+MIT
diff --git a/packages/oauth/examples/kimi-oauth-smoke.ts b/packages/oauth/examples/kimi-oauth-smoke.ts
new file mode 100644
index 000000000..cd23a43e5
--- /dev/null
+++ b/packages/oauth/examples/kimi-oauth-smoke.ts
@@ -0,0 +1,128 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  applyManagedKimiCodeConfig,
+  KIMI_CODE_PROVIDER_NAME,
+  KimiOAuthToolkit,
+  type DeviceAuthorization,
+  type KimiHostIdentity,
+  type ManagedKimiConfigShape,
+} from '@moonshot-ai/kimi-code-oauth';
+
+async function main(): Promise<void> {
+  const explicitHomeDir = process.env['KIMI_OAUTH_SMOKE_HOME'];
+  const homeDir = explicitHomeDir ?? (await mkdtemp(join(tmpdir(), 'kimi-oauth-smoke-')));
+  const keepToken = shouldKeepToken(explicitHomeDir !== undefined);
+  const forceLogin = process.env['KIMI_OAUTH_SMOKE_FORCE_LOGIN'] === '1';
+  const config: ManagedKimiConfigShape = { providers: {} };
+
+  const toolkit = new KimiOAuthToolkit<ManagedKimiConfigShape>({
+    homeDir,
+    identity: smokeIdentityFromEnv(),
+    configAdapter: {
+      read: () => config,
+      write: () => {},
+      apply: applyManagedKimiCodeConfig,
+      configPath: '<memory>',
+    },
+  });
+
+  process.stdout.write(`home: ${homeDir}\n`);
+
+  try {
+    if (forceLogin) {
+      await toolkit.logout(KIMI_CODE_PROVIDER_NAME);
+      process.stdout.write('cleared existing smoke token\n');
+    }
+
+    const login = await toolkit.login(KIMI_CODE_PROVIDER_NAME, {
+      onDeviceCode: printDeviceCode,
+    });
+    const status = await toolkit.status(KIMI_CODE_PROVIDER_NAME);
+    const accessToken = await toolkit.tokenProvider(KIMI_CODE_PROVIDER_NAME).getAccessToken();
+    const usage = await toolkit.getManagedUsage(KIMI_CODE_PROVIDER_NAME);
+
+    if (login.provision?.defaultModel === undefined) {
+      throw new Error('login did not provision a default model');
+    }
+    if (status.providers[0]?.hasToken !== true) {
+      throw new Error('status did not report a stored token after login');
+    }
+    if (accessToken.length === 0) {
+      throw new Error('token provider returned an empty access token');
+    }
+    if (config.providers[KIMI_CODE_PROVIDER_NAME] === undefined) {
+      throw new Error('managed provider was not written to config');
+    }
+
+    process.stdout.write(`provider: ${login.providerName}\n`);
+    process.stdout.write(`default model: ${login.provision.defaultModel}\n`);
+    process.stdout.write(`models: ${String(login.provision.models.length)}\n`);
+    printUsage(usage);
+    process.stdout.write('oauth smoke passed\n');
+  } finally {
+    if (!keepToken) {
+      await toolkit.logout(KIMI_CODE_PROVIDER_NAME).catch(() => {});
+    }
+    if (explicitHomeDir === undefined && !keepToken) {
+      await rm(homeDir, { recursive: true, force: true });
+    }
+  }
+}
+
+function smokeIdentityFromEnv(): KimiHostIdentity {
+  const version = process.env['KIMI_CODE_SMOKE_VERSION'];
+  if (version === undefined || version.trim().length === 0) {
+    throw new Error('KIMI_CODE_SMOKE_VERSION is required for Kimi OAuth smoke.');
+  }
+  return {
+    userAgentProduct: "kimi-code-cli",
+    version,
+  };
+}
+
+function printDeviceCode(auth: DeviceAuthorization): void {
+  process.stdout.write(
+    [
+      'Complete Kimi OAuth device login:',
+      `  URL: ${auth.verificationUriComplete || auth.verificationUri}`,
+      `  Code: ${auth.userCode}`,
+      auth.expiresIn === null ? undefined : `  Expires in: ${String(auth.expiresIn)}s`,
+      '',
+    ]
+      .filter((line): line is string => line !== undefined)
+      .join('\n'),
+  );
+}
+
+function printUsage(
+  usage: Awaited<ReturnType<KimiOAuthToolkit<ManagedKimiConfigShape>['getManagedUsage']>>,
+): void {
+  if (usage.kind === 'error') {
+    process.stderr.write(`usage request returned: ${usage.message}\n`);
+    return;
+  }
+  const summary = usage.summary;
+  if (summary === null) {
+    process.stdout.write(`usage: no summary, limits=${String(usage.limits.length)}\n`);
+    return;
+  }
+  process.stdout.write(
+    `usage: ${summary.label} ${String(summary.used)}/${String(summary.limit)}\n`,
+  );
+}
+
+function shouldKeepToken(hasExplicitHomeDir: boolean): boolean {
+  const value = process.env['KIMI_OAUTH_SMOKE_KEEP_TOKEN'];
+  if (value !== undefined) return value === '1' || value === 'true';
+  return hasExplicitHomeDir;
+}
+
+try {
+  await main();
+} catch (error: unknown) {
+  console.error(error);
+  process.exitCode = 1;
+}
diff --git a/packages/oauth/package.json b/packages/oauth/package.json
new file mode 100644
index 000000000..5453da53c
--- /dev/null
+++ b/packages/oauth/package.json
@@ -0,0 +1,51 @@
+{
+  "name": "@moonshot-ai/kimi-code-oauth",
+  "version": "0.1.1",
+  "private": true,
+  "description": "Kimi OAuth toolkit for managed Kimi Code authentication",
+  "license": "MIT",
+  "author": "Moonshot AI",
+  "homepage": "https://github.com/MoonshotAI/kimi-code/tree/main/packages/oauth#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MoonshotAI/kimi-code.git",
+    "directory": "packages/oauth"
+  },
+  "bugs": {
+    "url": "https://github.com/MoonshotAI/kimi-code/issues"
+  },
+  "keywords": [
+    "kimi",
+    "oauth",
+    "authentication",
+    "auth",
+    "cli"
+  ],
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "imports": {
+    "#/*": [
+      "./src/*.ts",
+      "./src/*/index.ts"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "proper-lockfile": "^4.1.2"
+  },
+  "devDependencies": {
+    "@types/proper-lockfile": "^4.1.4"
+  }
+}
diff --git a/packages/oauth/src/constants.ts b/packages/oauth/src/constants.ts
new file mode 100644
index 000000000..3c338fb6e
--- /dev/null
+++ b/packages/oauth/src/constants.ts
@@ -0,0 +1,10 @@
+import type { OAuthFlowConfig } from './types';
+
+export const KIMI_CODE_FLOW_CONFIG: OAuthFlowConfig = {
+  name: 'kimi-code',
+  oauthHost:
+    process.env['KIMI_CODE_OAUTH_HOST'] ??
+    process.env['KIMI_OAUTH_HOST'] ??
+    'https://auth.kimi.com',
+  clientId: '17e5f671-d194-4dfb-9706-5516cb48c098',
+};
diff --git a/packages/oauth/src/errors.ts b/packages/oauth/src/errors.ts
new file mode 100644
index 000000000..8dd525070
--- /dev/null
+++ b/packages/oauth/src/errors.ts
@@ -0,0 +1,49 @@
+/**
+ * OAuth error classes.
+ *
+ * All errors derive from {@link OAuthError}. Distinguishing subclasses let
+ * callers react appropriately:
+ *  - `OAuthUnauthorizedError`: 401/403 from token endpoint → refresh_token
+ *    or credentials are bad; drive user through `/login` again.
+ *  - `DeviceCodeExpiredError`: device_code TTL ran out before user approved;
+ *    restart the device flow.
+ *  - `DeviceCodeTimeoutError`: local 15 min wall-clock budget exhausted
+ *    before the user completed approval.
+ *  - `RetryableRefreshError`: 429 / 5xx from token endpoint; the refresh
+ *    helper retries with exponential backoff before surfacing this.
+ */
+
+export class OAuthError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'OAuthError';
+  }
+}
+
+export class OAuthUnauthorizedError extends OAuthError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'OAuthUnauthorizedError';
+  }
+}
+
+export class DeviceCodeExpiredError extends OAuthError {
+  constructor(message = 'Device code expired.') {
+    super(message);
+    this.name = 'DeviceCodeExpiredError';
+  }
+}
+
+export class DeviceCodeTimeoutError extends OAuthError {
+  constructor(message = 'Device authorization timed out locally.') {
+    super(message);
+    this.name = 'DeviceCodeTimeoutError';
+  }
+}
+
+export class RetryableRefreshError extends OAuthError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RetryableRefreshError';
+  }
+}
diff --git a/packages/oauth/src/identity.ts b/packages/oauth/src/identity.ts
new file mode 100644
index 000000000..82a22dad9
--- /dev/null
+++ b/packages/oauth/src/identity.ts
@@ -0,0 +1,130 @@
+/**
+ * Kimi host and device identity header factories.
+ *
+ * The caller owns the host identity (product name + host app version)
+ * and the `homeDir` where the stable device id is stored. This module
+ * intentionally keeps no global CLI version or environment-derived
+ * production state.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { arch, hostname, release, type } from 'node:os';
+import { join } from 'node:path';
+
+import type { DeviceHeaders } from './types';
+
+export interface KimiHostIdentity {
+  readonly userAgentProduct: string;
+  readonly version: string;
+  readonly userAgentSuffix?: string | undefined;
+}
+
+export interface KimiIdentityOptions extends KimiHostIdentity {
+  readonly homeDir: string;
+}
+
+export interface CreateKimiDeviceIdOptions {
+  /** Invoked synchronously the first time a device id is minted on this machine. */
+  readonly onFirstLaunch?: ((id: string) => void) | undefined;
+}
+
+export function createKimiDeviceId(
+  homeDir: string,
+  options: CreateKimiDeviceIdOptions = {},
+): string {
+  const deviceIdPath = join(homeDir, 'device_id');
+  if (existsSync(deviceIdPath)) {
+    try {
+      const text = readFileSync(deviceIdPath, 'utf-8').trim();
+      if (text.length > 0) return text;
+    } catch {
+      // Fall through to regenerate.
+    }
+  }
+
+  const id = randomUUID();
+  try {
+    mkdirSync(homeDir, { recursive: true, mode: 0o700 });
+    writeFileSync(deviceIdPath, id, { encoding: 'utf-8', mode: 0o600 });
+  } catch {
+    // Best-effort: requests can still use the in-memory id.
+  }
+  if (options.onFirstLaunch !== undefined) {
+    try {
+      options.onFirstLaunch(id);
+    } catch {
+      // Telemetry callback must not affect device id creation.
+    }
+  }
+  return id;
+}
+
+export function createKimiDeviceHeaders(options: {
+  readonly homeDir: string;
+  readonly version: string;
+}): DeviceHeaders {
+  return {
+    'X-Msh-Platform': 'kimi-code-cli',
+    'X-Msh-Version': requiredAsciiHeader(options.version, 'Kimi identity version'),
+    'X-Msh-Device-Name': asciiHeader(hostname()),
+    'X-Msh-Device-Model': asciiHeader(deviceModel()),
+    'X-Msh-Os-Version': asciiHeader(release()),
+    'X-Msh-Device-Id': createKimiDeviceId(options.homeDir),
+  };
+}
+
+export function createKimiUserAgent(options: {
+  readonly userAgentProduct: string;
+  readonly version: string;
+  readonly userAgentSuffix?: string | undefined;
+}): string {
+  const product = requiredAsciiHeader(options.userAgentProduct, 'Kimi identity product');
+  const version = requiredAsciiHeader(options.version, 'Kimi identity version');
+  const suffix =
+    options.userAgentSuffix === undefined ? undefined : asciiHeader(options.userAgentSuffix, '');
+  return suffix === undefined || suffix.length === 0
+    ? `${product}/${version}`
+    : `${product}/${version} (${suffix})`;
+}
+
+export function createKimiDefaultHeaders(options: KimiIdentityOptions): Record<string, string> {
+  return {
+    'User-Agent': createKimiUserAgent(options),
+    ...createKimiDeviceHeaders({
+      homeDir: options.homeDir,
+      version: options.version,
+    }),
+  };
+}
+
+export function assertKimiHostIdentity(identity: KimiHostIdentity | undefined): KimiHostIdentity {
+  if (identity === undefined) {
+    throw new Error('Kimi host identity is required. Pass the host product name and version.');
+  }
+  requiredAsciiHeader(identity.userAgentProduct, 'Kimi identity product');
+  requiredAsciiHeader(identity.version, 'Kimi identity version');
+  return identity;
+}
+
+function deviceModel(): string {
+  const os = type();
+  const version = release();
+  const osArch = arch();
+  if (os === 'Darwin') return `macOS ${version} ${osArch}`;
+  if (os === 'Windows_NT') return `Windows ${version} ${osArch}`;
+  return `${os} ${version} ${osArch}`.trim();
+}
+
+function asciiHeader(value: string, fallback = 'unknown'): string {
+  const cleaned = value.replaceAll(/[^\u0020-\u007E]/g, '').trim();
+  return cleaned.length > 0 ? cleaned : fallback;
+}
+
+function requiredAsciiHeader(value: string, fieldName: string): string {
+  const cleaned = asciiHeader(value, '');
+  if (cleaned.length === 0) {
+    throw new Error(`${fieldName} must be a non-empty ASCII string.`);
+  }
+  return cleaned;
+}
diff --git a/packages/oauth/src/index.ts b/packages/oauth/src/index.ts
new file mode 100644
index 000000000..9c8b97d6a
--- /dev/null
+++ b/packages/oauth/src/index.ts
@@ -0,0 +1,111 @@
+export {
+  DeviceCodeExpiredError,
+  DeviceCodeTimeoutError,
+  OAuthError,
+  OAuthUnauthorizedError,
+  RetryableRefreshError,
+} from './errors';
+
+export type {
+  DeviceAuthorization,
+  DeviceHeaders,
+  OAuthFlowConfig,
+  OAuthStorageBackend,
+  TokenInfo,
+  TokenInfoWire,
+} from './types';
+export { tokenFromWire, tokenToWire } from './types';
+
+export type { TokenStorage } from './storage';
+export { FileTokenStorage } from './storage';
+
+export type { DevicePollResult, RefreshOptions } from './oauth';
+export { pollDeviceToken, refreshAccessToken, requestDeviceAuthorization } from './oauth';
+
+export type { LoginOptions, OAuthManagerOptions, OAuthRefreshOutcome } from './oauth-manager';
+export { OAuthManager, defaultRefreshThreshold, newInstanceId } from './oauth-manager';
+
+export {
+  assertKimiHostIdentity,
+  createKimiDefaultHeaders,
+  createKimiDeviceHeaders,
+  createKimiDeviceId,
+  createKimiUserAgent,
+} from './identity';
+export type { KimiHostIdentity, KimiIdentityOptions } from './identity';
+
+export { KIMI_CODE_FLOW_CONFIG } from './constants';
+
+export {
+  applyManagedKimiCodeLogoutConfig,
+  applyManagedKimiCodeConfig,
+  clearManagedKimiCodeConfig,
+  fetchManagedKimiCodeModels,
+  KIMI_CODE_OAUTH_KEY,
+  KIMI_CODE_PLATFORM_ID,
+  KIMI_CODE_PROVIDER_NAME,
+  provisionManagedKimiCodeConfig,
+} from './managed-kimi-code';
+export type {
+  FetchManagedKimiCodeModelsOptions,
+  ManagedKimiCodeApplyResult,
+  ManagedKimiCodeCleanupResult,
+  ManagedKimiCodeModelInfo,
+  ManagedKimiCodeProvisionResult,
+  ManagedKimiConfigAdapter,
+  ManagedKimiConfigShape,
+  ProvisionManagedKimiCodeConfigOptions,
+} from './managed-kimi-code';
+
+export {
+  fetchManagedUsage,
+  formatDuration,
+  formatResetTime,
+  isManagedKimiCode,
+  kimiCodeBaseUrl,
+  kimiCodeUsageUrl,
+  parseManagedUsagePayload,
+} from './managed-usage';
+export type {
+  FetchManagedUsageError,
+  FetchManagedUsageResult,
+  ParsedManagedUsage,
+  UsageRow,
+} from './managed-usage';
+
+export { fetchSubmitFeedback, kimiCodeFeedbackUrl } from './managed-feedback';
+export type {
+  FetchSubmitFeedbackError,
+  FetchSubmitFeedbackOk,
+  FetchSubmitFeedbackResult,
+  SubmitFeedbackBody,
+} from './managed-feedback';
+
+export {
+  applyOpenPlatformConfig,
+  capabilitiesForModel,
+  fetchOpenPlatformModels,
+  filterModelsByPrefix,
+  getOpenPlatformById,
+  isOpenPlatformId,
+  OPEN_PLATFORMS,
+  OpenPlatformApiError,
+  removeOpenPlatformConfig,
+} from './open-platform';
+export type {
+  ApplyOpenPlatformResult,
+  OpenPlatformDefinition,
+} from './open-platform';
+
+export { KimiOAuthToolkit, resolveKimiTokenStorageName } from './toolkit';
+export type {
+  AuthManagedUsageResult,
+  AuthProviderStatus,
+  AuthStatus,
+  BearerTokenProvider,
+  KimiOAuthLoginOptions,
+  KimiOAuthLoginResult,
+  KimiOAuthLogoutResult,
+  KimiOAuthTokenRef,
+  KimiOAuthToolkitOptions,
+} from './toolkit';
diff --git a/packages/oauth/src/managed-feedback.ts b/packages/oauth/src/managed-feedback.ts
new file mode 100644
index 000000000..91ff5d8ff
--- /dev/null
+++ b/packages/oauth/src/managed-feedback.ts
@@ -0,0 +1,73 @@
+/**
+ * Submit user feedback to the managed Kimi Code platform.
+ *
+ * POSTs a JSON body to `{kimiCodeBaseUrl}/feedback` with a Bearer access
+ * token. The client tags `version` with a `kimi-code-` prefix so the
+ * backend can identify this client.
+ */
+
+import { kimiCodeBaseUrl } from './managed-usage';
+
+export interface SubmitFeedbackBody {
+  readonly session_id: string;
+  readonly content: string;
+  readonly version: string;
+  readonly os: string;
+  readonly model: string | null;
+}
+
+export interface FetchSubmitFeedbackOk {
+  readonly kind: 'ok';
+}
+
+export interface FetchSubmitFeedbackError {
+  readonly kind: 'error';
+  readonly status?: number;
+  readonly message: string;
+}
+
+export type FetchSubmitFeedbackResult = FetchSubmitFeedbackOk | FetchSubmitFeedbackError;
+
+export function kimiCodeFeedbackUrl(): string {
+  return `${kimiCodeBaseUrl().replace(/\/+$/, '')}/feedback`;
+}
+
+export async function fetchSubmitFeedback(
+  url: string,
+  accessToken: string,
+  body: SubmitFeedbackBody,
+  opts: { timeoutMs?: number } = {},
+): Promise<FetchSubmitFeedbackResult> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => {
+    controller.abort();
+  }, opts.timeoutMs ?? 8000);
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return {
+        kind: 'error',
+        status: res.status,
+        message: `Failed to submit feedback: HTTP ${String(res.status)}`,
+      };
+    }
+    return { kind: 'ok' };
+  } catch (error) {
+    if (error instanceof Error && error.name === 'AbortError') {
+      return { kind: 'error', message: 'Failed to submit feedback: request timed out.' };
+    }
+    const msg = error instanceof Error ? error.message : String(error);
+    return { kind: 'error', message: `Failed to submit feedback: ${msg}` };
+  } finally {
+    clearTimeout(timer);
+  }
+}
diff --git a/packages/oauth/src/managed-kimi-code.ts b/packages/oauth/src/managed-kimi-code.ts
new file mode 100644
index 000000000..6f6ee1e46
--- /dev/null
+++ b/packages/oauth/src/managed-kimi-code.ts
@@ -0,0 +1,395 @@
+import { kimiCodeBaseUrl } from './managed-usage';
+import { isRecord } from './utils';
+
+export const KIMI_CODE_PLATFORM_ID = 'kimi-code';
+export const KIMI_CODE_PROVIDER_NAME = 'managed:kimi-code';
+export const KIMI_CODE_OAUTH_KEY = 'oauth/kimi-code';
+
+export interface ManagedKimiCodeModelInfo {
+  readonly id: string;
+  readonly contextLength: number;
+  readonly supportsReasoning: boolean;
+  readonly supportsImageIn: boolean;
+  readonly supportsVideoIn: boolean;
+  readonly supportsToolUse?: boolean;
+  readonly displayName?: string | undefined;
+}
+
+export interface ManagedKimiCodeProvisionResult {
+  readonly providerName: typeof KIMI_CODE_PROVIDER_NAME;
+  readonly defaultModel: string;
+  readonly defaultThinking: boolean;
+  readonly models: readonly ManagedKimiCodeModelInfo[];
+  readonly configPath?: string | undefined;
+}
+
+export interface FetchManagedKimiCodeModelsOptions {
+  readonly accessToken: string;
+  readonly baseUrl?: string | undefined;
+  readonly fetchImpl?: typeof fetch | undefined;
+}
+
+export interface ManagedKimiCodeApplyResult {
+  readonly defaultModel: string;
+  readonly defaultThinking: boolean;
+}
+
+export interface ManagedKimiCodeCleanupResult {
+  readonly providerName: typeof KIMI_CODE_PROVIDER_NAME;
+  readonly removedProvider: boolean;
+  readonly removedModels: readonly string[];
+  readonly defaultModelCleared: boolean;
+  readonly removedServices: readonly string[];
+}
+
+export interface ManagedKimiOAuthRef {
+  readonly storage: 'file';
+  readonly key: typeof KIMI_CODE_OAUTH_KEY;
+}
+
+export interface ManagedKimiProviderConfig {
+  type: 'kimi';
+  baseUrl?: string | undefined;
+  apiKey?: string | undefined;
+  oauth?: ManagedKimiOAuthRef | undefined;
+  readonly [key: string]: unknown;
+}
+
+export interface ManagedKimiModelAlias {
+  provider: string;
+  model: string;
+  maxContextSize: number;
+  capabilities?: string[] | undefined;
+  displayName?: string | undefined;
+  readonly [key: string]: unknown;
+}
+
+export interface ManagedKimiServiceConfig {
+  baseUrl?: string | undefined;
+  apiKey?: string | undefined;
+  oauth?: ManagedKimiOAuthRef | undefined;
+}
+
+export interface ManagedKimiServicesConfig {
+  moonshotSearch?: ManagedKimiServiceConfig | undefined;
+  moonshotFetch?: ManagedKimiServiceConfig | undefined;
+  readonly [key: string]: unknown;
+}
+
+export interface ManagedKimiConfigShape {
+  providers: Record<string, ManagedKimiProviderConfig | Record<string, unknown>>;
+  models?: Record<string, ManagedKimiModelAlias | Record<string, unknown>> | undefined;
+  defaultModel?: string | undefined;
+  defaultThinking?: boolean | undefined;
+  services?: ManagedKimiServicesConfig | undefined;
+  [key: string]: unknown;
+}
+
+export interface ManagedKimiConfigAdapter<TConfig> {
+  read(): Promise<TConfig> | TConfig;
+  write(config: TConfig): Promise<void> | void;
+  apply(
+    config: TConfig,
+    input: {
+      readonly models: readonly ManagedKimiCodeModelInfo[];
+      readonly baseUrl?: string | undefined;
+      readonly preserveDefaultModel?: boolean | undefined;
+    },
+  ): ManagedKimiCodeApplyResult;
+  remove?(config: TConfig): void;
+  readonly configPath?: string | undefined;
+}
+
+export interface ProvisionManagedKimiCodeConfigOptions<TConfig> {
+  readonly adapter: ManagedKimiConfigAdapter<TConfig>;
+  readonly accessToken: string;
+  readonly baseUrl?: string | undefined;
+  readonly preserveDefaultModel?: boolean | undefined;
+  readonly fetchImpl?: typeof fetch | undefined;
+}
+
+function managedModelKey(modelId: string): string {
+  return `${KIMI_CODE_PLATFORM_ID}/${modelId}`;
+}
+
+interface SelectedDefaultModel {
+  readonly modelKey: string;
+  readonly thinking: boolean;
+}
+
+function capabilitiesForModel(model: ManagedKimiCodeModelInfo): string[] | undefined {
+  const caps = new Set<string>();
+  if (model.supportsReasoning) caps.add('thinking');
+  if (model.supportsImageIn) caps.add('image_in');
+  if (model.supportsVideoIn) caps.add('video_in');
+  if (model.supportsToolUse ?? true) caps.add('tool_use');
+  return caps.size > 0 ? [...caps] : undefined;
+}
+
+function defaultBaseUrl(baseUrl: string | undefined): string {
+  return (baseUrl ?? kimiCodeBaseUrl()).replace(/\/+$/, '');
+}
+
+function toModelInfo(item: unknown): ManagedKimiCodeModelInfo | undefined {
+  if (!isRecord(item) || typeof item['id'] !== 'string' || item['id'].length === 0) {
+    return undefined;
+  }
+  const contextLength = Number(item['context_length']);
+  if (!Number.isInteger(contextLength) || contextLength <= 0) {
+    throw new Error(`Kimi Code model "${item['id']}" must include a positive context_length.`);
+  }
+  const displayName = item['display_name'];
+  const normalizedDisplayName =
+    typeof displayName === 'string' && displayName.length > 0 ? displayName : undefined;
+  const supportsToolUse = Object.hasOwn(item, 'supports_tool_use')
+    ? Boolean(item['supports_tool_use'])
+    : true;
+  return {
+    id: item['id'],
+    contextLength,
+    supportsReasoning: Boolean(item['supports_reasoning']),
+    supportsImageIn: Boolean(item['supports_image_in']),
+    supportsVideoIn: Boolean(item['supports_video_in']),
+    supportsToolUse,
+    displayName: normalizedDisplayName,
+  };
+}
+
+export async function fetchManagedKimiCodeModels(
+  options: FetchManagedKimiCodeModelsOptions,
+): Promise<ManagedKimiCodeModelInfo[]> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const baseUrl = defaultBaseUrl(options.baseUrl);
+  const response = await fetchImpl(`${baseUrl}/models`, {
+    headers: {
+      Authorization: `Bearer ${options.accessToken}`,
+      Accept: 'application/json',
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to list Kimi Code models (HTTP ${response.status}).`);
+  }
+  const payload: unknown = await response.json();
+  if (!isRecord(payload) || !Array.isArray(payload['data'])) {
+    throw new Error(`Unexpected models response for ${baseUrl}.`);
+  }
+  return payload['data']
+    .map((item) => toModelInfo(item))
+    .filter((item): item is ManagedKimiCodeModelInfo => item !== undefined);
+}
+
+export function applyManagedKimiCodeConfig(
+  config: ManagedKimiConfigShape,
+  options: {
+    readonly models: readonly ManagedKimiCodeModelInfo[];
+    readonly baseUrl?: string | undefined;
+    readonly preserveDefaultModel?: boolean | undefined;
+  },
+): ManagedKimiCodeApplyResult {
+  if (options.models.length === 0) {
+    throw new Error('No models available for Kimi Code.');
+  }
+  for (const model of options.models) {
+    assertPositiveContextLength(model);
+  }
+
+  const baseUrl = defaultBaseUrl(options.baseUrl);
+  const existingModels = config.models ?? {};
+  const selectedDefault = selectDefaultModel(config, options.models, {
+    preserveExisting: options.preserveDefaultModel === true,
+  });
+
+  config.providers[KIMI_CODE_PROVIDER_NAME] = {
+    type: 'kimi',
+    baseUrl,
+    apiKey: '',
+    oauth: { storage: 'file', key: KIMI_CODE_OAUTH_KEY },
+  };
+
+  for (const [key, model] of Object.entries(existingModels)) {
+    if (isRecord(model) && model['provider'] === KIMI_CODE_PROVIDER_NAME) {
+      delete existingModels[key];
+    }
+  }
+  for (const model of options.models) {
+    const capabilities = capabilitiesForModel(model);
+    existingModels[managedModelKey(model.id)] = {
+      provider: KIMI_CODE_PROVIDER_NAME,
+      model: model.id,
+      maxContextSize: model.contextLength,
+      capabilities,
+      displayName: model.displayName,
+    };
+  }
+
+  config.models = existingModels;
+  config.defaultModel = selectedDefault.modelKey;
+  config.defaultThinking = selectedDefault.thinking;
+  config.services = {
+    moonshotSearch: {
+      baseUrl: `${baseUrl}/search`,
+      apiKey: '',
+      oauth: { storage: 'file', key: KIMI_CODE_OAUTH_KEY },
+    },
+    moonshotFetch: {
+      baseUrl: `${baseUrl}/fetch`,
+      apiKey: '',
+      oauth: { storage: 'file', key: KIMI_CODE_OAUTH_KEY },
+    },
+  };
+
+  return {
+    defaultModel: selectedDefault.modelKey,
+    defaultThinking: selectedDefault.thinking,
+  };
+}
+
+export function applyManagedKimiCodeLogoutConfig(config: ManagedKimiConfigShape): void {
+  delete config.providers[KIMI_CODE_PROVIDER_NAME];
+
+  let removedDefaultModel = false;
+  const existingModels = config.models ?? {};
+  for (const [key, model] of Object.entries(existingModels)) {
+    if (!isRecord(model) || model['provider'] !== KIMI_CODE_PROVIDER_NAME) continue;
+    delete existingModels[key];
+    if (config.defaultModel === key) removedDefaultModel = true;
+  }
+  config.models = existingModels;
+
+  if (removedDefaultModel) {
+    config.defaultModel = undefined;
+  }
+
+  if (config['defaultProvider'] === KIMI_CODE_PROVIDER_NAME) {
+    config['defaultProvider'] = undefined;
+  }
+
+  if (config.services !== undefined) {
+    delete config.services.moonshotSearch;
+    delete config.services.moonshotFetch;
+    if (Object.keys(config.services).length === 0) {
+      config.services = undefined;
+    }
+  }
+}
+
+function selectDefaultModel(
+  config: ManagedKimiConfigShape,
+  models: readonly ManagedKimiCodeModelInfo[],
+  options: { readonly preserveExisting: boolean },
+): SelectedDefaultModel {
+  const firstModel = models[0];
+  if (firstModel === undefined) {
+    throw new Error('No models available for Kimi Code.');
+  }
+
+  const managedModels = new Map(models.map((model) => [managedModelKey(model.id), model]));
+  const existingModels = config.models ?? {};
+  const currentDefault =
+    typeof config.defaultModel === 'string' && config.defaultModel.length > 0
+      ? config.defaultModel
+      : undefined;
+
+  if (
+    options.preserveExisting &&
+    currentDefault !== undefined &&
+    canPreserveDefaultModel(existingModels, currentDefault, managedModels)
+  ) {
+    const preservedModel = managedModels.get(currentDefault);
+    return {
+      modelKey: currentDefault,
+      thinking: config.defaultThinking ?? preservedModel?.supportsReasoning ?? false,
+    };
+  }
+
+  return {
+    modelKey: managedModelKey(firstModel.id),
+    thinking: config.defaultThinking ?? firstModel.supportsReasoning,
+  };
+}
+
+function canPreserveDefaultModel(
+  existingModels: Record<string, ManagedKimiModelAlias | Record<string, unknown>>,
+  defaultModel: string,
+  managedModels: ReadonlyMap<string, ManagedKimiCodeModelInfo>,
+): boolean {
+  if (managedModels.has(defaultModel)) return true;
+  const existing = existingModels[defaultModel];
+  return isRecord(existing) && existing['provider'] !== KIMI_CODE_PROVIDER_NAME;
+}
+
+export function clearManagedKimiCodeConfig(
+  config: ManagedKimiConfigShape,
+): ManagedKimiCodeCleanupResult {
+  const removedProvider = Object.hasOwn(config.providers, KIMI_CODE_PROVIDER_NAME);
+  delete config.providers[KIMI_CODE_PROVIDER_NAME];
+
+  const removedModels: string[] = [];
+  const models = config.models;
+  if (models !== undefined) {
+    for (const [key, model] of Object.entries(models)) {
+      if (!isRecord(model) || model['provider'] !== KIMI_CODE_PROVIDER_NAME) continue;
+      delete models[key];
+      removedModels.push(key);
+    }
+  }
+
+  let defaultModelCleared = false;
+  if (typeof config.defaultModel === 'string' && removedModels.includes(config.defaultModel)) {
+    config.defaultModel = undefined;
+    defaultModelCleared = true;
+  }
+
+  const removedServices: string[] = [];
+  if (config.services?.moonshotSearch !== undefined) {
+    delete config.services.moonshotSearch;
+    removedServices.push('moonshotSearch');
+  }
+  if (config.services?.moonshotFetch !== undefined) {
+    delete config.services.moonshotFetch;
+    removedServices.push('moonshotFetch');
+  }
+  if (config.services !== undefined && Object.keys(config.services).length === 0) {
+    config.services = undefined;
+  }
+
+  return {
+    providerName: KIMI_CODE_PROVIDER_NAME,
+    removedProvider,
+    removedModels,
+    defaultModelCleared,
+    removedServices,
+  };
+}
+
+function assertPositiveContextLength(model: ManagedKimiCodeModelInfo): void {
+  if (!Number.isInteger(model.contextLength) || model.contextLength <= 0) {
+    throw new Error(`Kimi Code model "${model.id}" must include a positive context_length.`);
+  }
+}
+
+export async function provisionManagedKimiCodeConfigAfterLogin(
+  options: ProvisionManagedKimiCodeConfigOptions<ManagedKimiConfigShape>,
+): Promise<ManagedKimiCodeProvisionResult> {
+  return provisionManagedKimiCodeConfig(options);
+}
+
+export async function provisionManagedKimiCodeConfig<TConfig>(
+  options: ProvisionManagedKimiCodeConfigOptions<TConfig>,
+): Promise<ManagedKimiCodeProvisionResult> {
+  const models = await fetchManagedKimiCodeModels(options);
+  const config = await options.adapter.read();
+  const applied = options.adapter.apply(config, {
+    models,
+    baseUrl: options.baseUrl,
+    preserveDefaultModel: options.preserveDefaultModel,
+  });
+  await options.adapter.write(config);
+  return {
+    providerName: KIMI_CODE_PROVIDER_NAME,
+    defaultModel: applied.defaultModel,
+    defaultThinking: applied.defaultThinking,
+    models,
+    configPath: options.adapter.configPath,
+  };
+}
diff --git a/packages/oauth/src/managed-usage.ts b/packages/oauth/src/managed-usage.ts
new file mode 100644
index 000000000..a6dc3f030
--- /dev/null
+++ b/packages/oauth/src/managed-usage.ts
@@ -0,0 +1,235 @@
+/**
+ * Managed-platform usage fetch / parse.
+ *
+ * Only `managed:kimi-code` is supported today. The platform exposes a
+ * `/usages` endpoint that returns a payload of the shape:
+ *
+ *   {
+ *     "usage":  { "name": "Weekly limit", "used": 40, "limit": 1000, "resetAt": "..." },
+ *     "limits": [
+ *       { "detail": {"used":1, "limit":100, "name":"5h limit"}, "window": {...} },
+ *       ...
+ *     ]
+ *   }
+ *
+ * The parser is intentionally loose because field spelling / casing
+ * drifted across versions (`used` vs `remaining`, `resetAt` vs
+ * `reset_at`, `duration+timeUnit` window labels, etc.).
+ */
+
+import { isRecord } from './utils';
+
+const MANAGED_PREFIX = 'managed:';
+const KIMI_CODE_PLATFORM_ID = 'kimi-code';
+
+export function isManagedKimiCode(providerKey?: string | null): boolean {
+  if (!providerKey) return false;
+  if (!providerKey.startsWith(MANAGED_PREFIX)) return false;
+  return providerKey.slice(MANAGED_PREFIX.length) === KIMI_CODE_PLATFORM_ID;
+}
+
+export function kimiCodeBaseUrl(): string {
+  return process.env['KIMI_CODE_BASE_URL'] ?? 'https://api.kimi.com/coding/v1';
+}
+
+export function kimiCodeUsageUrl(): string {
+  return `${kimiCodeBaseUrl().replace(/\/+$/, '')}/usages`;
+}
+
+export interface UsageRow {
+  readonly label: string;
+  readonly used: number;
+  readonly limit: number;
+  readonly resetHint?: string | undefined;
+}
+
+export interface ParsedManagedUsage {
+  readonly summary: UsageRow | null;
+  readonly limits: UsageRow[];
+}
+
+export function parseManagedUsagePayload(payload: unknown): ParsedManagedUsage {
+  if (typeof payload !== 'object' || payload === null) {
+    return { summary: null, limits: [] };
+  }
+  const rec = payload as Record<string, unknown>;
+  const summary = toUsageRow(rec['usage'], 'Weekly limit');
+  const limits: UsageRow[] = [];
+  const rawLimits = rec['limits'];
+  if (Array.isArray(rawLimits)) {
+    for (let idx = 0; idx < rawLimits.length; idx++) {
+      const item = rawLimits[idx] as Record<string, unknown> | undefined;
+      if (!item || typeof item !== 'object') continue;
+      const detailRaw = item['detail'];
+      const detail = isRecord(detailRaw) ? detailRaw : item;
+      const windowRaw = item['window'];
+      const window = isRecord(windowRaw) ? windowRaw : {};
+      const label = limitLabel(item, detail, window, idx);
+      const row = toUsageRow(detail, label);
+      if (row !== null) limits.push(row);
+    }
+  }
+  return { summary, limits };
+}
+
+function toUsageRow(raw: unknown, defaultLabel: string): UsageRow | null {
+  if (!isRecord(raw)) return null;
+  const limit = toInt(raw['limit']);
+  let used = toInt(raw['used']);
+  if (used === null) {
+    const remaining = toInt(raw['remaining']);
+    if (remaining !== null && limit !== null) {
+      used = limit - remaining;
+    }
+  }
+  if (used === null && limit === null) return null;
+  const name =
+    typeof raw['name'] === 'string'
+      ? raw['name']
+      : typeof raw['title'] === 'string'
+        ? raw['title']
+        : defaultLabel;
+  const resetHint = resetHintFrom(raw);
+  return {
+    label: name,
+    used: used ?? 0,
+    limit: limit ?? 0,
+    resetHint,
+  };
+}
+
+function limitLabel(
+  item: Record<string, unknown>,
+  detail: Record<string, unknown>,
+  window: Record<string, unknown>,
+  idx: number,
+): string {
+  for (const key of ['name', 'title', 'scope']) {
+    const v = item[key] ?? detail[key];
+    if (typeof v === 'string' && v.length > 0) return v;
+  }
+  const duration = toInt(window['duration'] ?? item['duration'] ?? detail['duration']);
+  const rawUnit = window['timeUnit'] ?? item['timeUnit'] ?? detail['timeUnit'];
+  const timeUnit = typeof rawUnit === 'string' ? rawUnit : '';
+  if (duration !== null) {
+    if (timeUnit.includes('MINUTE')) {
+      if (duration >= 60 && duration % 60 === 0) return `${String(duration / 60)}h limit`;
+      return `${String(duration)}m limit`;
+    }
+    if (timeUnit.includes('HOUR')) return `${String(duration)}h limit`;
+    if (timeUnit.includes('DAY')) return `${String(duration)}d limit`;
+    return `${String(duration)}s limit`;
+  }
+  return `Limit #${String(idx + 1)}`;
+}
+
+function resetHintFrom(raw: Record<string, unknown>): string | undefined {
+  for (const key of ['reset_at', 'resetAt', 'reset_time', 'resetTime']) {
+    const v = raw[key];
+    if (typeof v === 'string' && v.length > 0) {
+      return formatResetTime(v);
+    }
+  }
+  for (const key of ['reset_in', 'resetIn', 'ttl', 'window']) {
+    const seconds = toInt(raw[key]);
+    if (seconds !== null && seconds > 0) {
+      return `resets in ${formatDuration(seconds)}`;
+    }
+  }
+  return undefined;
+}
+
+export function formatResetTime(val: string): string {
+  let normalised = val;
+  // ISO with nano precision → trim to ms for JS Date.
+  if (normalised.includes('.') && normalised.endsWith('Z')) {
+    const [base, frac] = normalised.slice(0, -1).split('.');
+    if (base !== undefined && frac !== undefined) {
+      normalised = `${base}.${frac.slice(0, 3)}Z`;
+    }
+  }
+  const parsed = Date.parse(normalised);
+  if (!Number.isFinite(parsed)) return `resets at ${val}`;
+  const diffSec = Math.floor((parsed - Date.now()) / 1000);
+  if (diffSec <= 0) return 'reset';
+  return `resets in ${formatDuration(diffSec)}`;
+}
+
+export function formatDuration(totalSeconds: number): string {
+  if (!Number.isFinite(totalSeconds) || totalSeconds <= 0) return '0s';
+  const seconds = Math.floor(totalSeconds);
+  const days = Math.floor(seconds / 86_400);
+  const hours = Math.floor((seconds % 86_400) / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  const secs = seconds % 60;
+  const parts: string[] = [];
+  if (days) parts.push(`${String(days)}d`);
+  if (hours) parts.push(`${String(hours)}h`);
+  if (minutes) parts.push(`${String(minutes)}m`);
+  if (secs && parts.length === 0) parts.push(`${String(secs)}s`);
+  return parts.length > 0 ? parts.join(' ') : '0s';
+}
+
+function toInt(value: unknown): number | null {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? Math.trunc(value) : null;
+  }
+  if (typeof value === 'string') {
+    const n = Number(value);
+    return Number.isFinite(n) ? Math.trunc(n) : null;
+  }
+  return null;
+}
+
+// ── HTTP fetch ────────────────────────────────────────────────────────
+
+export interface FetchManagedUsageResult {
+  readonly kind: 'ok';
+  readonly parsed: ParsedManagedUsage;
+}
+
+export interface FetchManagedUsageError {
+  readonly kind: 'error';
+  readonly status?: number;
+  readonly message: string;
+}
+
+export async function fetchManagedUsage(
+  url: string,
+  accessToken: string,
+  opts: { timeoutMs?: number } = {},
+): Promise<FetchManagedUsageResult | FetchManagedUsageError> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => {
+    controller.abort();
+  }, opts.timeoutMs ?? 8000);
+  try {
+    const res = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/json',
+      },
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      const status = res.status;
+      const hint =
+        status === 401
+          ? 'Authorization failed. Please check your API key (try /login).'
+          : status === 404
+            ? 'Usage endpoint not available. Try Kimi For Coding.'
+            : `Failed to fetch usage: HTTP ${String(status)}`;
+      return { kind: 'error', status, message: hint };
+    }
+    const json: unknown = await res.json();
+    return { kind: 'ok', parsed: parseManagedUsagePayload(json) };
+  } catch (error) {
+    if (error instanceof Error && error.name === 'AbortError') {
+      return { kind: 'error', message: 'Failed to fetch usage: request timed out.' };
+    }
+    const msg = error instanceof Error ? error.message : String(error);
+    return { kind: 'error', message: `Failed to fetch usage: ${msg}` };
+  } finally {
+    clearTimeout(timer);
+  }
+}
diff --git a/packages/oauth/src/oauth-manager.ts b/packages/oauth/src/oauth-manager.ts
new file mode 100644
index 000000000..5192f7859
--- /dev/null
+++ b/packages/oauth/src/oauth-manager.ts
@@ -0,0 +1,478 @@
+/**
+ * OAuthManager — per-provider token lifecycle (load / refresh / login / logout).
+ *
+ *  - Lazy refresh on `ensureFresh()` — no background loop
+ *  - Single-process concurrency: in-memory mutex serialises refreshes
+ *  - Multi-process coordination: before + after storage re-read, so a
+ *    concurrent refresh from another CLI process is detected (best-effort)
+ *  - `login()`: device code flow with a 15 min local timeout
+ *  - `logout()`: delete stored token
+ *
+ * All network / clock / storage operations are injectable for tests.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import lockfile from 'proper-lockfile';
+
+import { DeviceCodeTimeoutError, OAuthError, OAuthUnauthorizedError } from './errors';
+import { pollDeviceToken, refreshAccessToken, requestDeviceAuthorization } from './oauth';
+import type { DevicePollResult, RefreshOptions } from './oauth';
+import type { TokenStorage } from './storage';
+import { classifyToken, revokedTombstone, type TokenState } from './token-state';
+import type { DeviceAuthorization, DeviceHeaders, OAuthFlowConfig, TokenInfo } from './types';
+
+const MIN_REFRESH_THRESHOLD_SECONDS = 300;
+const REFRESH_THRESHOLD_RATIO = 0.5;
+const DEFAULT_DEVICE_CODE_TIMEOUT_MS = 15 * 60 * 1000;
+
+export function defaultRefreshThreshold(expiresIn: number): number {
+  if (expiresIn > 0) {
+    return Math.max(MIN_REFRESH_THRESHOLD_SECONDS, expiresIn * REFRESH_THRESHOLD_RATIO);
+  }
+  return MIN_REFRESH_THRESHOLD_SECONDS;
+}
+
+type Sleep = (ms: number) => Promise<void>;
+const defaultSleep: Sleep = (ms) =>
+  new Promise<void>((resolve) => {
+    setTimeout(resolve, ms);
+  });
+type ManagerRefreshOptions = Omit<RefreshOptions, 'deviceHeaders'>;
+
+export type OAuthRefreshOutcome =
+  | { readonly success: true }
+  | { readonly success: false; readonly reason: 'unauthorized' | 'network_or_other' };
+
+export interface OAuthManagerOptions {
+  readonly config: OAuthFlowConfig;
+  readonly storage: TokenStorage;
+  readonly refreshThreshold?: ((expiresIn: number) => number) | undefined;
+  readonly deviceCodeTimeoutMs?: number | undefined;
+  readonly now?: (() => number) | undefined;
+  readonly sleep?: Sleep | undefined;
+  /** Observer invoked synchronously when a refresh attempt resolves. */
+  readonly onRefresh?: ((outcome: OAuthRefreshOutcome) => void) | undefined;
+  readonly refreshTokenImpl?:
+    | ((
+        config: OAuthFlowConfig,
+        refreshToken: string,
+        options?: ManagerRefreshOptions,
+      ) => Promise<TokenInfo>)
+    | undefined;
+  readonly requestDeviceImpl?:
+    | ((config: OAuthFlowConfig) => Promise<DeviceAuthorization>)
+    | undefined;
+  readonly pollDeviceImpl?:
+    | ((config: OAuthFlowConfig, deviceCode: string) => Promise<DevicePollResult>)
+    | undefined;
+  readonly deviceHeaders?: (() => DeviceHeaders | undefined) | undefined;
+  /**
+   * Root directory for per-provider lock files; resolves to
+   * `{configDir}/oauth/{providerName}.lock`.
+   *
+   * **Production callers MUST pass this explicitly** (KimiCoreClient /
+   * session-manager wire it through from the resolved config root). A
+   * missing `configDir` disables the cross-process lock entirely, so
+   * silently falling back to an env var in production would mask a
+   * genuine mis-wiring.
+   *
+   * When omitted AND `process.env.NODE_ENV === 'test'`, the manager
+   * falls back to `process.env.KIMI_CODE_HOME` so multi-process test
+   * harnesses don't need to thread the dir through every fixture. In
+   * production the fallback is inert. Windows platforms and
+   * `process.env.KIMI_DISABLE_OAUTH_LOCK === '1'` always skip; the
+   * "re-read storage" fail-safe remains as a best-effort coordinator.
+   */
+  readonly configDir?: string | undefined;
+}
+
+export interface LoginOptions {
+  readonly onDeviceCode?: ((auth: DeviceAuthorization) => Promise<void> | void) | undefined;
+  readonly signal?: AbortSignal | undefined;
+}
+
+export class OAuthManager {
+  private readonly config: OAuthFlowConfig;
+  private readonly storage: TokenStorage;
+  private readonly refreshThresholdFn: (expiresIn: number) => number;
+  private readonly deviceCodeTimeoutMs: number;
+  private readonly now: () => number;
+  private readonly sleep: Sleep;
+  private readonly refreshImpl: NonNullable<OAuthManagerOptions['refreshTokenImpl']>;
+  private readonly requestImpl: NonNullable<OAuthManagerOptions['requestDeviceImpl']>;
+  private readonly pollImpl: NonNullable<OAuthManagerOptions['pollDeviceImpl']>;
+  private readonly deviceHeaders: (() => DeviceHeaders | undefined) | undefined;
+  private readonly configDir: string | undefined;
+  private readonly onRefresh: ((outcome: OAuthRefreshOutcome) => void) | undefined;
+
+  /**
+   * In-flight refresh coalescer: one refresh per ensureFresh race.
+   *
+   * Tracks the `force` flag of the in-flight call so a later `force=true`
+   * caller cannot piggyback a non-force result that may short-circuit on
+   * a still-cached token. A non-force caller is happy with any settled
+   * outcome and may piggyback either kind.
+   */
+  private inFlightRefresh: { promise: Promise<string>; force: boolean } | undefined;
+
+  constructor(options: OAuthManagerOptions) {
+    this.config = options.config;
+    this.storage = options.storage;
+    this.refreshThresholdFn = options.refreshThreshold ?? defaultRefreshThreshold;
+    this.deviceCodeTimeoutMs = options.deviceCodeTimeoutMs ?? DEFAULT_DEVICE_CODE_TIMEOUT_MS;
+    this.now = options.now ?? (() => Math.floor(Date.now() / 1000));
+    this.sleep = options.sleep ?? defaultSleep;
+    this.deviceHeaders = options.deviceHeaders;
+    this.onRefresh = options.onRefresh;
+    this.refreshImpl =
+      options.refreshTokenImpl ??
+      ((config, refreshToken, refreshOptions) =>
+        refreshAccessToken(config, refreshToken, {
+          ...refreshOptions,
+          deviceHeaders: this.resolveDeviceHeaders(),
+        }));
+    this.requestImpl =
+      options.requestDeviceImpl ??
+      ((config) =>
+        requestDeviceAuthorization(config, {
+          deviceHeaders: this.resolveDeviceHeaders(),
+        }));
+    this.pollImpl =
+      options.pollDeviceImpl ??
+      ((config, deviceCode) =>
+        pollDeviceToken(config, deviceCode, {
+          deviceHeaders: this.resolveDeviceHeaders(),
+        }));
+    // The `KIMI_CODE_HOME` fallback MUST stay test-only so production
+    // entry points can't silently run without a lock just because the
+    // env happens to be unset. vitest sets `NODE_ENV='test'` by default,
+    // so multi-process test workers still pick up the test home path.
+    const envConfigDir =
+      process.env['NODE_ENV'] === 'test' ? process.env['KIMI_CODE_HOME'] : undefined;
+    this.configDir = options.configDir ?? envConfigDir;
+  }
+
+  private resolveDeviceHeaders(): DeviceHeaders | undefined {
+    return this.deviceHeaders?.();
+  }
+
+  private async loadState(): Promise<TokenState> {
+    return classifyToken(await this.storage.load(this.config.name));
+  }
+
+  private notifyRefresh(outcome: OAuthRefreshOutcome): void {
+    if (this.onRefresh === undefined) return;
+    try {
+      this.onRefresh(outcome);
+    } catch {
+      // Observer must not affect OAuth flow.
+    }
+  }
+
+  /**
+   * Resolve the sentinel target file `proper-lockfile` locks against.
+   * `proper-lockfile.lock(target)` creates `${target}.lock` as the
+   * actual lock directory, so the real lockfile on disk ends up at
+   * `{configDir}/oauth/{providerName}.lock`. Returns `undefined` when
+   * locking is opted out (no configDir, Windows, env kill switch).
+   */
+  private resolveLockTarget(): string | undefined {
+    if (process.platform === 'win32') return undefined;
+    if (process.env['KIMI_DISABLE_OAUTH_LOCK'] === '1') return undefined;
+    if (this.configDir === undefined) return undefined;
+    return `${this.configDir}/oauth/${this.config.name}`;
+  }
+
+  /**
+   * Acquire the cross-process lock around the refresh critical section.
+   * Returns a `release` closure; when locking is disabled returns a no-op.
+   * If locking is configured but cannot be acquired, fail closed rather than
+   * refreshing with no lock and racing refresh_token rotation.
+   */
+  private async acquireRefreshLock(): Promise<() => Promise<void>> {
+    const target = this.resolveLockTarget();
+    if (target === undefined) return async () => {};
+
+    // proper-lockfile requires the target path to exist. We create
+    // an empty sentinel file; the real lock indicator is the sibling
+    // `{target}.lock` directory proper-lockfile creates and cleans
+    // up on release (→ test oracle `{configDir}/oauth/{name}.lock`
+    // must be absent after a graceful exit).
+    try {
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, '', { flag: 'a' });
+    } catch (error) {
+      throw new OAuthError(
+        `Unable to prepare OAuth refresh lock for "${this.config.name}": ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+
+    try {
+      const release = await lockfile.lock(target, {
+        retries: { retries: 120, factor: 1, minTimeout: 500, maxTimeout: 1_000 },
+        stale: 5_000,
+        realpath: false,
+      });
+      return async () => {
+        try {
+          await release();
+        } catch {
+          /* ignore release-after-stale */
+        }
+      };
+    } catch (error) {
+      throw new OAuthError(
+        `Unable to acquire OAuth refresh lock for "${this.config.name}": ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  async hasToken(): Promise<boolean> {
+    return (await this.loadState()).kind === 'valid';
+  }
+
+  async getCachedAccessToken(): Promise<string | undefined> {
+    const state = await this.loadState();
+    return state.kind === 'valid' ? state.token.accessToken : undefined;
+  }
+
+  async logout(): Promise<void> {
+    await this.storage.remove(this.config.name);
+  }
+
+  /**
+   * Return a valid access_token, refreshing if within the dynamic threshold.
+   * Throws if no token is persisted (caller should invoke `/login`).
+   */
+  async ensureFresh(options: { force?: boolean } = {}): Promise<string> {
+    const force = options.force === true;
+    const current = this.inFlightRefresh;
+    if (current !== undefined) {
+      // A non-force caller is happy with whatever the in-flight call
+      // settles to. A force caller can also piggyback another force
+      // call. Only force-on-top-of-non-force needs its own refresh,
+      // because the non-force call may return a still-cached token
+      // that doesn't satisfy the caller-requested forced rotation.
+      if (!force || current.force) {
+        return current.promise;
+      }
+      // Wait for the non-force call to settle (success or failure),
+      // then start our own forced refresh. Swallowing rejection here
+      // is safe: the non-force caller already owns surfacing that error.
+      return current.promise.catch(() => undefined).then(() => this.ensureFresh(options));
+    }
+
+    const promise = this.doEnsureFresh(force).finally(() => {
+      // Only clear our own slot. A later, replacement in-flight (e.g. a
+      // queued force after this non-force resolves) must not be evicted
+      // by our cleanup.
+      if (this.inFlightRefresh?.promise === promise) {
+        this.inFlightRefresh = undefined;
+      }
+    });
+    this.inFlightRefresh = { promise, force };
+    return promise;
+  }
+
+  private async doEnsureFresh(force: boolean): Promise<string> {
+    const initial = await this.loadState();
+    switch (initial.kind) {
+      case 'missing':
+        throw new OAuthError(`No token for "${this.config.name}". Run /login to authenticate.`);
+      case 'revoked':
+        // A prior 401 (possibly from another process) tombstoned this token.
+        // Surface as unauthorized so callers route into the re-login flow
+        // instead of treating it as a transient error.
+        throw new OAuthUnauthorizedError(
+          `Stored token for "${this.config.name}" was rejected; re-login required.`,
+        );
+      case 'valid':
+        break;
+    }
+    const token = initial.token;
+
+    const needRefresh = this.shouldRefreshToken(token, force);
+    if (!needRefresh) {
+      return token.accessToken;
+    }
+
+    // Acquire the cross-process lock before entering the refresh critical
+    // section. Concurrent CLI processes serialise on
+    // `{configDir}/oauth/{providerName}.lock` via `proper-lockfile`.
+    // Post-acquire we re-read storage: if a peer already rotated the
+    // token, short-circuit and return theirs instead of burning an
+    // extra refresh.
+    const release = await this.acquireRefreshLock();
+    try {
+      // Post-lock re-read. The semantics:
+      //
+      //   • force=false: the normal threshold short-circuit still
+      //     applies.
+      //   • force=true: still refresh unless storage changed while we
+      //     waited for the lock. That preserves caller-requested forced
+      //     refreshes for unchanged tokens while coalescing real peer
+      //     refreshes across processes.
+      const afterLock = await this.loadState();
+      let activeToken: TokenInfo;
+      switch (afterLock.kind) {
+        case 'revoked':
+          // Peer process tombstoned the file while we waited for the lock.
+          throw new OAuthUnauthorizedError(
+            `Stored token for "${this.config.name}" was rejected; re-login required.`,
+          );
+        case 'missing':
+          // File disappeared (e.g. logout from another process) while we
+          // waited for the lock; fall back to the snapshot we read pre-lock.
+          activeToken = token;
+          break;
+        case 'valid': {
+          const after = afterLock.token;
+          if (!this.shouldRefreshToken(after, force)) {
+            return after.accessToken;
+          }
+          if (force) {
+            const changedWhileWaiting =
+              after.refreshToken !== token.refreshToken ||
+              after.accessToken !== token.accessToken ||
+              after.expiresAt !== token.expiresAt ||
+              after.expiresIn !== token.expiresIn;
+            if (changedWhileWaiting) {
+              return after.accessToken;
+            }
+          }
+          activeToken = after;
+          break;
+        }
+      }
+
+      if (activeToken.refreshToken.length === 0) {
+        throw new OAuthError(
+          `Token for "${this.config.name}" has no refresh_token; re-login required.`,
+        );
+      }
+
+      try {
+        const refreshed = await this.refreshImpl(this.config, activeToken.refreshToken);
+        await this.storage.save(this.config.name, refreshed);
+        this.notifyRefresh({ success: true });
+        return refreshed.accessToken;
+      } catch (error) {
+        if (error instanceof OAuthUnauthorizedError) {
+          // 401/403 might mean (a) refresh_token genuinely revoked or
+          // (b) another process rotated the refresh_token while we were
+          // mid-flight. Check (b) first: re-read storage, and if a peer
+          // wrote a different valid refresh_token, treat the 401 as a
+          // stale-token race and use the rotated value.
+          await this.sleep(100);
+          const recovery = await this.loadState();
+          if (
+            recovery.kind === 'valid' &&
+            recovery.token.refreshToken !== activeToken.refreshToken
+          ) {
+            this.notifyRefresh({ success: true });
+            return recovery.token.accessToken;
+          }
+          // No peer rotated — record the rejection on disk as a tombstone so
+          // a fresh process (with no in-memory state) won't re-attempt the
+          // same dead refresh_token. The file stays present so peers see
+          // "previously logged in, now rejected" instead of "never logged in".
+          await this.storage.save(this.config.name, revokedTombstone(activeToken));
+          this.notifyRefresh({ success: false, reason: 'unauthorized' });
+        } else {
+          this.notifyRefresh({ success: false, reason: 'network_or_other' });
+        }
+        throw error;
+      }
+    } finally {
+      await release();
+    }
+  }
+
+  /**
+   * Drive the device code flow end-to-end. `onDeviceCode` is called once
+   * the user code is available so the caller can display it.
+   *
+   * Local 15-min wall-clock budget guards against forever-pending flows.
+   */
+  async login(options: LoginOptions = {}): Promise<TokenInfo> {
+    const startedAt = this.now();
+    const deadlineAt = startedAt + Math.ceil(this.deviceCodeTimeoutMs / 1000);
+
+    while (true) {
+      const auth = await this.requestImpl(this.config);
+      await options.onDeviceCode?.(auth);
+
+      // RFC 8628 §3.5: clients must add at least 5s on `slow_down` and
+      // continue polling at the increased interval thereafter.
+      let currentInterval = Math.max(auth.interval, 1);
+      // Poll until success, denial, local timeout, or expired_token (retry outer).
+      let deviceExpired = false;
+      while (true) {
+        this.throwIfAborted(options.signal);
+        if (this.now() >= deadlineAt) {
+          throw new DeviceCodeTimeoutError(
+            `Device authorization timed out after ${Math.ceil(this.deviceCodeTimeoutMs / 1000)}s`,
+          );
+        }
+
+        const result = await this.pollImpl(this.config, auth.deviceCode);
+        if (result.kind === 'success') {
+          await this.storage.save(this.config.name, result.token);
+          return result.token;
+        }
+        if (result.kind === 'denied') {
+          throw new OAuthError(
+            `Authorization denied${result.description ? `: ${result.description}` : ''}`,
+          );
+        }
+        if (result.kind === 'expired') {
+          deviceExpired = true;
+          break;
+        }
+        // pending: bump interval permanently when server requests slow_down.
+        if (result.errorCode === 'slow_down') {
+          currentInterval += 5;
+        }
+        await this.sleep(currentInterval * 1000);
+      }
+      if (!deviceExpired) break;
+      // Otherwise loop outer to request a new device code.
+      // Guard: if we're already past the deadline, bail.
+      if (this.now() >= deadlineAt) {
+        throw new DeviceCodeTimeoutError('Device authorization timed out');
+      }
+    }
+
+    // Unreachable — inner loop always returns or throws.
+    throw new OAuthError('Device flow ended unexpectedly');
+  }
+
+  private shouldRefreshToken(token: TokenInfo, force: boolean): boolean {
+    if (force) return true;
+    if (token.expiresAt === 0) return false;
+    const remaining = token.expiresAt - this.now();
+    return remaining < this.refreshThresholdFn(token.expiresIn);
+  }
+
+  private throwIfAborted(signal: AbortSignal | undefined): void {
+    if (signal?.aborted === true) {
+      throw new OAuthError('Login aborted by caller');
+    }
+  }
+}
+
+/**
+ * Generate a synthetic OAuth client instance id. Used by `/login` to
+ * correlate device flows with the CLI instance without depending on
+ * runtime state. Not required by the protocol — purely for diagnostics.
+ */
+export function newInstanceId(): string {
+  return randomUUID();
+}
diff --git a/packages/oauth/src/oauth.ts b/packages/oauth/src/oauth.ts
new file mode 100644
index 000000000..3a1024877
--- /dev/null
+++ b/packages/oauth/src/oauth.ts
@@ -0,0 +1,276 @@
+/**
+ * Device Code OAuth flow — pure HTTP wrappers.
+ *
+ * Three endpoints, all POST form-encoded to the OAuth host:
+ *  - `/api/oauth/device_authorization` → DeviceAuthorization
+ *  - `/api/oauth/token` (grant_type=device_code) → polling result
+ *  - `/api/oauth/token` (grant_type=refresh_token) → refreshed TokenInfo
+ *
+ * No state is kept here — `OAuthManager` drives the flow and decides
+ * when to poll / refresh / store.
+ */
+
+import { OAuthError, OAuthUnauthorizedError, RetryableRefreshError } from './errors';
+import type { DeviceAuthorization, DeviceHeaders, OAuthFlowConfig, TokenInfo } from './types';
+import { isRecord } from './utils';
+
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+
+function pickErrorDetail(data: Record<string, unknown>): string {
+  if (typeof data['error_description'] === 'string') return data['error_description'];
+  if (typeof data['error'] === 'string') return data['error'];
+  return 'unknown';
+}
+
+function tokenFromResponse(payload: Record<string, unknown>): TokenInfo {
+  // Required-field validation. Reject responses that are missing
+  // any of the three load-bearing fields rather than persisting empty
+  // strings that will fail mysteriously later.
+  const accessToken = payload['access_token'];
+  if (typeof accessToken !== 'string' || accessToken.length === 0) {
+    throw new OAuthError('OAuth response missing access_token');
+  }
+  const refreshToken = payload['refresh_token'];
+  if (typeof refreshToken !== 'string' || refreshToken.length === 0) {
+    throw new OAuthError('OAuth response missing refresh_token');
+  }
+  const expiresInRaw = payload['expires_in'];
+  const expiresIn = Number(expiresInRaw);
+  if (!Number.isFinite(expiresIn) || expiresIn <= 0) {
+    throw new OAuthError('OAuth response missing or invalid expires_in');
+  }
+  return {
+    accessToken,
+    refreshToken,
+    expiresAt: Math.floor(Date.now() / 1000) + expiresIn,
+    scope: typeof payload['scope'] === 'string' ? payload['scope'] : '',
+    tokenType: typeof payload['token_type'] === 'string' ? payload['token_type'] : 'Bearer',
+    expiresIn,
+  };
+}
+
+/** HTTP client default timeout for OAuth requests. */
+const DEFAULT_HTTP_TIMEOUT_MS = 30_000;
+
+async function postForm(
+  url: string,
+  params: Record<string, string>,
+  deviceHeaders?: DeviceHeaders | undefined,
+  options?: { timeoutMs?: number; signal?: AbortSignal },
+): Promise<{ status: number; data: Record<string, unknown> }> {
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
+  const body = new URLSearchParams(params).toString();
+  // Compose a timeout signal with the optional caller signal.
+  const signals: AbortSignal[] = [AbortSignal.timeout(timeoutMs)];
+  if (options?.signal !== undefined) signals.push(options.signal);
+  const signal = AbortSignal.any(signals);
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        ...deviceHeaders,
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+      },
+      body,
+      signal,
+    });
+  } catch (error) {
+    throw new OAuthError(
+      `OAuth request to ${url} failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  const status = response.status;
+  let data: Record<string, unknown> = {};
+  try {
+    const text = await response.text();
+    if (text.length > 0) {
+      const parsed: unknown = JSON.parse(text);
+      if (isRecord(parsed)) data = parsed;
+    }
+  } catch {
+    // Non-JSON response — leave data empty; caller interprets by status.
+  }
+  return { status, data };
+}
+
+// ── requestDeviceAuthorization ────────────────────────────────────────
+
+export async function requestDeviceAuthorization(
+  config: OAuthFlowConfig,
+  options: { readonly deviceHeaders?: DeviceHeaders | undefined },
+): Promise<DeviceAuthorization> {
+  const url = `${config.oauthHost.replace(/\/$/, '')}/api/oauth/device_authorization`;
+  const { status, data } = await postForm(
+    url,
+    { client_id: config.clientId },
+    options.deviceHeaders,
+  );
+
+  if (status !== 200) {
+    throw new OAuthError(`Device authorization failed (HTTP ${status}): ${pickErrorDetail(data)}`);
+  }
+
+  // Required-field validation for the device authorization response.
+  const userCode = data['user_code'];
+  const deviceCode = data['device_code'];
+  const verificationUriComplete = data['verification_uri_complete'];
+  if (typeof userCode !== 'string' || userCode.length === 0) {
+    throw new OAuthError('Device authorization response missing user_code');
+  }
+  if (typeof deviceCode !== 'string' || deviceCode.length === 0) {
+    throw new OAuthError('Device authorization response missing device_code');
+  }
+  if (typeof verificationUriComplete !== 'string' || verificationUriComplete.length === 0) {
+    throw new OAuthError('Device authorization response missing verification_uri_complete');
+  }
+
+  return {
+    userCode,
+    deviceCode,
+    verificationUri: typeof data['verification_uri'] === 'string' ? data['verification_uri'] : '',
+    verificationUriComplete,
+    expiresIn: data['expires_in'] !== undefined ? Number(data['expires_in']) : null,
+    interval: Number(data['interval'] ?? 5),
+  };
+}
+
+// ── pollDeviceToken ───────────────────────────────────────────────────
+
+export type DevicePollResult =
+  | { readonly kind: 'success'; readonly token: TokenInfo }
+  | { readonly kind: 'pending'; readonly errorCode: string; readonly description: string }
+  | { readonly kind: 'expired' }
+  | { readonly kind: 'denied'; readonly description: string };
+
+export async function pollDeviceToken(
+  config: OAuthFlowConfig,
+  deviceCode: string,
+  options: { readonly deviceHeaders?: DeviceHeaders | undefined },
+): Promise<DevicePollResult> {
+  const url = `${config.oauthHost.replace(/\/$/, '')}/api/oauth/token`;
+  const { status, data } = await postForm(
+    url,
+    {
+      client_id: config.clientId,
+      device_code: deviceCode,
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+    },
+    options.deviceHeaders,
+  );
+
+  if (status === 200 && typeof data['access_token'] === 'string') {
+    return { kind: 'success', token: tokenFromResponse(data) };
+  }
+
+  if (status >= 500) {
+    throw new OAuthError(
+      `Device token polling server error (HTTP ${status}): ${pickErrorDetail(data)}`,
+    );
+  }
+
+  const errorCode = typeof data['error'] === 'string' ? data['error'] : 'unknown_error';
+  const description =
+    typeof data['error_description'] === 'string' ? data['error_description'] : '';
+  switch (errorCode) {
+    case 'authorization_pending':
+    case 'slow_down':
+      return { kind: 'pending', errorCode, description };
+    case 'expired_token':
+      return { kind: 'expired' };
+    case 'access_denied':
+      return { kind: 'denied', description };
+    default:
+      throw new OAuthError(
+        `Device token polling failed (HTTP ${status}): ${errorCode} ${description}`,
+      );
+  }
+}
+
+// ── refreshAccessToken ────────────────────────────────────────────────
+
+export interface RefreshOptions {
+  readonly deviceHeaders?: DeviceHeaders | undefined;
+  readonly maxRetries?: number | undefined;
+  /**
+   * Backoff between retries in ms. Defaults to `2 ** attempt * 1000` (1s, 2s).
+   * Accepts an attempt-indexed callable for testability (set to `() => 0`).
+   */
+  readonly backoffMs?: ((attempt: number) => number) | undefined;
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+
+export async function refreshAccessToken(
+  config: OAuthFlowConfig,
+  refreshToken: string,
+  options: RefreshOptions,
+): Promise<TokenInfo> {
+  const maxRetries = options.maxRetries ?? 3;
+  const backoff = options.backoffMs ?? ((attempt) => 2 ** attempt * 1000);
+  const sleep =
+    options.sleep ??
+    ((ms: number) =>
+      new Promise<void>((resolve) => {
+        setTimeout(resolve, ms);
+      }));
+  const url = `${config.oauthHost.replace(/\/$/, '')}/api/oauth/token`;
+
+  let lastError: Error | undefined;
+  for (let attempt = 0; attempt < maxRetries; attempt += 1) {
+    let status: number;
+    let data: Record<string, unknown>;
+    try {
+      ({ status, data } = await postForm(
+        url,
+        {
+          client_id: config.clientId,
+          grant_type: 'refresh_token',
+          refresh_token: refreshToken,
+        },
+        options.deviceHeaders,
+      ));
+    } catch (error) {
+      // Transport-level failure (DNS, connection refused, timeout). Treat
+      // as retryable to match Python's `aiohttp.ClientError` handling.
+      lastError = error instanceof Error ? error : new OAuthError(String(error));
+      if (attempt < maxRetries - 1) {
+        await sleep(backoff(attempt));
+        continue;
+      }
+      throw lastError instanceof Error ? lastError : new OAuthError(String(lastError));
+    }
+
+    if (status === 200 && typeof data['access_token'] === 'string') {
+      return tokenFromResponse(data);
+    }
+
+    const errorCode = typeof data['error'] === 'string' ? data['error'] : '';
+    if (status === 401 || status === 403 || errorCode === 'invalid_grant') {
+      throw new OAuthUnauthorizedError(
+        typeof data['error_description'] === 'string'
+          ? data['error_description']
+          : 'Token refresh unauthorized.',
+      );
+    }
+
+    const desc =
+      typeof data['error_description'] === 'string'
+        ? data['error_description']
+        : `Token refresh failed (HTTP ${status}).`;
+    if (RETRYABLE_STATUSES.has(status)) {
+      lastError = new RetryableRefreshError(desc);
+      if (attempt < maxRetries - 1) {
+        await sleep(backoff(attempt));
+        continue;
+      }
+      // fall through: out of retries, surface the retryable error
+    } else {
+      throw new OAuthError(desc);
+    }
+  }
+
+  throw lastError ?? new OAuthError('Token refresh failed after retries.');
+}
+
+export type { DeviceHeaders };
diff --git a/packages/oauth/src/open-platform.ts b/packages/oauth/src/open-platform.ts
new file mode 100644
index 000000000..328a9b2c5
--- /dev/null
+++ b/packages/oauth/src/open-platform.ts
@@ -0,0 +1,189 @@
+import { isRecord } from './utils';
+import type {
+  ManagedKimiCodeModelInfo,
+  ManagedKimiConfigShape,
+} from './managed-kimi-code';
+
+export type { ManagedKimiConfigShape };
+
+export interface OpenPlatformDefinition {
+  readonly id: string;
+  readonly name: string;
+  readonly baseUrl: string;
+  readonly allowedPrefixes?: readonly string[] | undefined;
+}
+
+export const OPEN_PLATFORMS: readonly OpenPlatformDefinition[] = [
+  {
+    id: 'moonshot-cn',
+    name: 'Moonshot AI Open Platform (moonshot.cn)',
+    baseUrl: 'https://api.moonshot.cn/v1',
+    allowedPrefixes: ['kimi-k'],
+  },
+  {
+    id: 'moonshot-ai',
+    name: 'Moonshot AI Open Platform (moonshot.ai)',
+    baseUrl: 'https://api.moonshot.ai/v1',
+    allowedPrefixes: ['kimi-k'],
+  },
+];
+
+export function getOpenPlatformById(id: string): OpenPlatformDefinition | undefined {
+  return OPEN_PLATFORMS.find((p) => p.id === id);
+}
+
+export function isOpenPlatformId(id: string): boolean {
+  return OPEN_PLATFORMS.some((p) => p.id === id);
+}
+
+function toModelInfo(item: unknown): ManagedKimiCodeModelInfo | undefined {
+  if (!isRecord(item) || typeof item['id'] !== 'string' || item['id'].length === 0) {
+    return undefined;
+  }
+  const contextLength = Number(item['context_length']);
+  if (!Number.isInteger(contextLength) || contextLength <= 0) {
+    throw new Error(`Model "${item['id']}" must include a positive context_length.`);
+  }
+  const displayName = item['display_name'];
+  const normalizedDisplayName =
+    typeof displayName === 'string' && displayName.length > 0 ? displayName : undefined;
+  const supportsToolUse = Object.hasOwn(item, 'supports_tool_use')
+    ? Boolean(item['supports_tool_use'])
+    : true;
+  return {
+    id: item['id'],
+    contextLength,
+    supportsReasoning: Boolean(item['supports_reasoning']),
+    supportsImageIn: Boolean(item['supports_image_in']),
+    supportsVideoIn: Boolean(item['supports_video_in']),
+    supportsToolUse,
+    displayName: normalizedDisplayName,
+  };
+}
+
+export function capabilitiesForModel(model: ManagedKimiCodeModelInfo): string[] | undefined {
+  const caps = new Set<string>();
+  if (model.supportsReasoning) caps.add('thinking');
+  if (model.supportsImageIn) caps.add('image_in');
+  if (model.supportsVideoIn) caps.add('video_in');
+  if (model.supportsToolUse ?? true) caps.add('tool_use');
+  return caps.size > 0 ? [...caps] : undefined;
+}
+
+export class OpenPlatformApiError extends Error {
+  readonly status: number;
+
+  constructor(message: string, status: number) {
+    super(message);
+    this.status = status;
+  }
+}
+
+export async function fetchOpenPlatformModels(
+  platform: OpenPlatformDefinition,
+  apiKey: string,
+  fetchImpl: typeof fetch = fetch,
+  signal?: AbortSignal,
+): Promise<ManagedKimiCodeModelInfo[]> {
+  const res = await fetchImpl(`${platform.baseUrl.replace(/\/+$/, '')}/models`, {
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      Accept: 'application/json',
+    },
+    signal,
+  });
+  if (!res.ok) {
+    throw new OpenPlatformApiError(`Failed to list models (HTTP ${res.status}).`, res.status);
+  }
+  const payload: unknown = await res.json();
+  if (!isRecord(payload) || !Array.isArray(payload['data'])) {
+    throw new Error(`Unexpected models response for ${platform.baseUrl}.`);
+  }
+  return payload['data']
+    .map((item) => toModelInfo(item))
+    .filter((item): item is ManagedKimiCodeModelInfo => item !== undefined);
+}
+
+export function filterModelsByPrefix(
+  models: ManagedKimiCodeModelInfo[],
+  platform: OpenPlatformDefinition,
+): ManagedKimiCodeModelInfo[] {
+  if (!platform.allowedPrefixes || platform.allowedPrefixes.length === 0) {
+    return models;
+  }
+  const prefixes = platform.allowedPrefixes;
+  return models.filter((m) => prefixes.some((p) => m.id.startsWith(p)));
+}
+
+export interface ApplyOpenPlatformResult {
+  readonly defaultModel: string;
+  readonly defaultThinking: boolean;
+}
+
+export function applyOpenPlatformConfig(
+  config: ManagedKimiConfigShape,
+  options: {
+    readonly platform: OpenPlatformDefinition;
+    readonly models: readonly ManagedKimiCodeModelInfo[];
+    readonly selectedModel: ManagedKimiCodeModelInfo;
+    readonly thinking: boolean;
+    readonly apiKey: string;
+  },
+): ApplyOpenPlatformResult {
+  const providerKey = options.platform.id;
+  const modelKey = `${providerKey}/${options.selectedModel.id}`;
+
+  config.providers[providerKey] = {
+    type: 'kimi',
+    baseUrl: options.platform.baseUrl,
+    apiKey: options.apiKey,
+  };
+
+  const existingModels = config.models ?? {};
+  for (const [key, model] of Object.entries(existingModels)) {
+    if (isRecord(model) && model['provider'] === providerKey) {
+      delete existingModels[key];
+    }
+  }
+
+  for (const model of options.models) {
+    const aliasKey = `${providerKey}/${model.id}`;
+    existingModels[aliasKey] = {
+      provider: providerKey,
+      model: model.id,
+      maxContextSize: model.contextLength,
+      capabilities: capabilitiesForModel(model),
+      displayName: model.displayName,
+    };
+  }
+
+  config.models = existingModels;
+  config.defaultModel = modelKey;
+  config.defaultThinking = options.thinking;
+
+  return { defaultModel: modelKey, defaultThinking: options.thinking };
+}
+
+export function removeOpenPlatformConfig(
+  config: ManagedKimiConfigShape,
+  platformId: string,
+): void {
+  delete config.providers[platformId];
+
+  let removedDefault = false;
+  const existingModels = config.models ?? {};
+  for (const [key, model] of Object.entries(existingModels)) {
+    if (!isRecord(model) || model['provider'] !== platformId) continue;
+    delete existingModels[key];
+    if (config.defaultModel === key) removedDefault = true;
+  }
+  config.models = existingModels;
+
+  if (removedDefault) {
+    config.defaultModel = undefined;
+  }
+
+  if (config['defaultProvider'] === platformId) {
+    config['defaultProvider'] = undefined;
+  }
+}
diff --git a/packages/oauth/src/storage.ts b/packages/oauth/src/storage.ts
new file mode 100644
index 000000000..f7d4e1abb
--- /dev/null
+++ b/packages/oauth/src/storage.ts
@@ -0,0 +1,138 @@
+/**
+ * File-based OAuth token storage.
+ *
+ * Tokens are persisted under a directory (default
+ * `~/.kimi-code/credentials/`) as `<name>.json` with mode 0600 (parent
+ * dir 0700). Wire format uses snake_case to match the server contract.
+ *
+ * Write semantics: write to `<name>.tmp.<pid>.<rand>` → fsync → rename.
+ * Atomic on POSIX; Windows best-effort.
+ *
+ * Load semantics: missing file → undefined. Corrupt JSON / wrong shape →
+ * undefined (never throws). Callers treat undefined as "no token stored".
+ */
+
+import { randomBytes } from 'node:crypto';
+import {
+  chmodSync,
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeSync,
+} from 'node:fs';
+import { basename, join } from 'node:path';
+
+import type { TokenInfo, TokenInfoWire } from './types';
+import { tokenFromWire, tokenToWire } from './types';
+import { isRecord } from './utils';
+
+export interface TokenStorage {
+  load(name: string): Promise<TokenInfo | undefined>;
+  save(name: string, token: TokenInfo): Promise<void>;
+  remove(name: string): Promise<void>;
+  list(): Promise<string[]>;
+}
+
+export class FileTokenStorage implements TokenStorage {
+  private readonly dir: string;
+
+  constructor(dir: string) {
+    this.dir = dir;
+  }
+
+  private ensureDir(): void {
+    mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    // recursive=true with mode only applies on initial create; tighten after
+    // the fact in case an existing dir had looser permissions.
+    try {
+      chmodSync(this.dir, 0o700);
+    } catch {
+      // best-effort; Windows / read-only FS may refuse
+    }
+  }
+
+  private pathFor(name: string): string {
+    // Guard against path traversal: caller-provided names (from config.toml
+    // or slash commands) must not escape the credentials dir. `basename`
+    // strips any `..` or `/` segments; if the sanitized value differs from
+    // the input we refuse the request entirely rather than silently
+    // writing to a different file than the caller asked for.
+    const safe = basename(name);
+    if (safe.length === 0 || safe !== name || safe.startsWith('.')) {
+      throw new Error(`Invalid token name: "${name}"`);
+    }
+    return join(this.dir, `${safe}.json`);
+  }
+
+  async load(name: string): Promise<TokenInfo | undefined> {
+    const file = this.pathFor(name);
+    let raw: string;
+    try {
+      raw = readFileSync(file, 'utf-8');
+    } catch {
+      return undefined;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return undefined;
+    }
+    if (!isRecord(parsed)) return undefined;
+    return tokenFromWire(parsed as Partial<TokenInfoWire>);
+  }
+
+  async save(name: string, token: TokenInfo): Promise<void> {
+    this.ensureDir();
+    const target = this.pathFor(name);
+    const tmp = `${target}.tmp.${process.pid}.${randomBytes(4).toString('hex')}`;
+    const data = Buffer.from(`${JSON.stringify(tokenToWire(token), null, 2)}\n`, 'utf-8');
+    const fd = openSync(tmp, 'w', 0o600);
+    try {
+      let written = 0;
+      while (written < data.length) {
+        written += writeSync(fd, data, written, data.length - written);
+      }
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    try {
+      // chmod again in case umask stripped bits during open
+      chmodSync(tmp, 0o600);
+      renameSync(tmp, target);
+    } catch (error) {
+      try {
+        unlinkSync(tmp);
+      } catch {
+        /* ignore */
+      }
+      throw error;
+    }
+  }
+
+  async remove(name: string): Promise<void> {
+    try {
+      unlinkSync(this.pathFor(name));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw error;
+      }
+    }
+  }
+
+  async list(): Promise<string[]> {
+    let entries: string[];
+    try {
+      entries = readdirSync(this.dir);
+    } catch {
+      return [];
+    }
+    return entries.filter((e) => e.endsWith('.json')).map((e) => e.slice(0, -'.json'.length));
+  }
+}
diff --git a/packages/oauth/src/token-state.ts b/packages/oauth/src/token-state.ts
new file mode 100644
index 000000000..5785d4e40
--- /dev/null
+++ b/packages/oauth/src/token-state.ts
@@ -0,0 +1,45 @@
+/**
+ * Internal three-state view of what storage holds for a provider.
+ *
+ *   • valid    — a usable token. Refresh decisions are made elsewhere
+ *                from `token.expiresAt`.
+ *   • revoked  — a "tombstone": the on-disk file exists but the prior
+ *                refresh_token was rejected (401/403). A fresh process
+ *                with no in-memory state needs to see "previously logged
+ *                in, now needs re-login" instead of "never logged in".
+ *   • missing  — no file on disk.
+ *
+ * Wire format and `TokenInfo` are unchanged: a revoked record is still
+ * persisted as `{ access_token: "", refresh_token: "", expires_at: 0,
+ * scope, token_type, expires_in: 0 }`. This module exists so the
+ * manager doesn't have to repeat that field-emptiness convention on
+ * every branch.
+ *
+ * Package-private. NOT re-exported from `index.ts`.
+ */
+
+import type { TokenInfo } from './types';
+
+export type TokenState =
+  | { readonly kind: 'valid'; readonly token: TokenInfo }
+  | { readonly kind: 'revoked'; readonly scope: string; readonly tokenType: string }
+  | { readonly kind: 'missing' };
+
+export function classifyToken(token: TokenInfo | undefined): TokenState {
+  if (token === undefined) return { kind: 'missing' };
+  if (token.accessToken.length === 0) {
+    return { kind: 'revoked', scope: token.scope, tokenType: token.tokenType };
+  }
+  return { kind: 'valid', token };
+}
+
+export function revokedTombstone(prior: TokenInfo): TokenInfo {
+  return {
+    accessToken: '',
+    refreshToken: '',
+    expiresAt: 0,
+    scope: prior.scope,
+    tokenType: prior.tokenType,
+    expiresIn: 0,
+  };
+}
diff --git a/packages/oauth/src/toolkit.ts b/packages/oauth/src/toolkit.ts
new file mode 100644
index 000000000..c09d3b59f
--- /dev/null
+++ b/packages/oauth/src/toolkit.ts
@@ -0,0 +1,300 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { KIMI_CODE_FLOW_CONFIG } from './constants';
+import { OAuthUnauthorizedError } from './errors';
+import { assertKimiHostIdentity, createKimiDeviceHeaders, type KimiHostIdentity } from './identity';
+import {
+  fetchSubmitFeedback,
+  kimiCodeFeedbackUrl,
+  type FetchSubmitFeedbackResult,
+  type SubmitFeedbackBody,
+} from './managed-feedback';
+import {
+  KIMI_CODE_OAUTH_KEY,
+  KIMI_CODE_PROVIDER_NAME,
+  provisionManagedKimiCodeConfig,
+  type ManagedKimiCodeProvisionResult,
+  type ManagedKimiConfigAdapter,
+} from './managed-kimi-code';
+import {
+  fetchManagedUsage,
+  kimiCodeUsageUrl,
+  type FetchManagedUsageError,
+  type ParsedManagedUsage,
+} from './managed-usage';
+import { OAuthManager, type LoginOptions, type OAuthManagerOptions } from './oauth-manager';
+import { FileTokenStorage, type TokenStorage } from './storage';
+import type { OAuthFlowConfig } from './types';
+
+export interface BearerTokenProvider {
+  getAccessToken(options?: { readonly force?: boolean | undefined }): Promise<string>;
+}
+
+export interface AuthProviderStatus {
+  readonly providerName: string;
+  readonly hasToken: boolean;
+}
+
+export interface AuthStatus {
+  readonly providers: readonly AuthProviderStatus[];
+}
+
+export interface KimiOAuthToolkitOptions<TConfig = unknown> {
+  readonly identity?: KimiHostIdentity | undefined;
+  readonly homeDir?: string | undefined;
+  readonly credentialsDir?: string | undefined;
+  readonly storage?: TokenStorage | undefined;
+  readonly flowConfig?: OAuthFlowConfig | undefined;
+  readonly configAdapter?: ManagedKimiConfigAdapter<TConfig> | undefined;
+  readonly fetchImpl?: typeof fetch | undefined;
+  readonly now?: OAuthManagerOptions['now'];
+  readonly sleep?: OAuthManagerOptions['sleep'];
+  readonly deviceCodeTimeoutMs?: number | undefined;
+  readonly refreshThreshold?: OAuthManagerOptions['refreshThreshold'];
+  readonly onRefresh?: OAuthManagerOptions['onRefresh'];
+}
+
+export interface KimiOAuthLoginOptions extends LoginOptions {
+  readonly provisionConfig?: boolean | undefined;
+  readonly baseUrl?: string | undefined;
+}
+
+export interface KimiOAuthTokenRef {
+  readonly key?: string | undefined;
+}
+
+export interface KimiOAuthLoginResult {
+  readonly providerName: string;
+  readonly ok: true;
+  readonly provision?: ManagedKimiCodeProvisionResult | undefined;
+}
+
+export interface KimiOAuthLogoutResult {
+  readonly providerName: string;
+  readonly ok: true;
+}
+
+export type AuthManagedUsageResult =
+  | {
+      readonly kind: 'ok';
+      readonly summary: ParsedManagedUsage['summary'];
+      readonly limits: ParsedManagedUsage['limits'];
+    }
+  | FetchManagedUsageError;
+
+export class KimiOAuthToolkit<TConfig = unknown> {
+  private readonly homeDir: string;
+  private readonly identity: KimiHostIdentity | undefined;
+  private readonly storage: TokenStorage;
+  private readonly flowConfig: OAuthFlowConfig;
+  private readonly configAdapter: ManagedKimiConfigAdapter<TConfig> | undefined;
+  private readonly fetchImpl: typeof fetch | undefined;
+  private readonly managerOptions: Pick<
+    OAuthManagerOptions,
+    'now' | 'sleep' | 'deviceCodeTimeoutMs' | 'refreshThreshold' | 'onRefresh'
+  >;
+  private readonly managers = new Map<string, OAuthManager>();
+
+  constructor(options: KimiOAuthToolkitOptions<TConfig>) {
+    this.identity =
+      options.identity === undefined ? undefined : assertKimiHostIdentity(options.identity);
+    this.homeDir = options.homeDir ?? defaultKimiHome();
+    const credentialsDir = options.credentialsDir ?? join(this.homeDir, 'credentials');
+    this.storage = options.storage ?? new FileTokenStorage(credentialsDir);
+    this.flowConfig = options.flowConfig ?? KIMI_CODE_FLOW_CONFIG;
+    this.configAdapter = options.configAdapter;
+    this.fetchImpl = options.fetchImpl;
+    this.managerOptions = {
+      now: options.now,
+      sleep: options.sleep,
+      deviceCodeTimeoutMs: options.deviceCodeTimeoutMs,
+      refreshThreshold: options.refreshThreshold,
+      onRefresh: options.onRefresh,
+    };
+  }
+
+  async status(providerName?: string | undefined): Promise<AuthStatus> {
+    const name = providerName ?? KIMI_CODE_PROVIDER_NAME;
+    return {
+      providers: [
+        {
+          providerName: name,
+          hasToken: await this.managerFor(name).hasToken(),
+        },
+      ],
+    };
+  }
+
+  async login(
+    providerName?: string | undefined,
+    options: KimiOAuthLoginOptions = {},
+  ): Promise<KimiOAuthLoginResult> {
+    const name = providerName ?? KIMI_CODE_PROVIDER_NAME;
+    const manager = this.managerFor(name);
+    const hadToken = await manager.hasToken();
+    let accessToken: string;
+    if (hadToken) {
+      try {
+        accessToken = await manager.ensureFresh();
+      } catch (error) {
+        if (!(error instanceof OAuthUnauthorizedError)) throw error;
+        accessToken = (
+          await manager.login({
+            signal: options.signal,
+            onDeviceCode: options.onDeviceCode,
+          })
+        ).accessToken;
+      }
+    } else {
+      accessToken = (
+        await manager.login({
+          signal: options.signal,
+          onDeviceCode: options.onDeviceCode,
+        })
+      ).accessToken;
+    }
+
+    const shouldProvision = options.provisionConfig ?? this.configAdapter !== undefined;
+    const provision =
+      shouldProvision && this.configAdapter !== undefined
+        ? await provisionManagedKimiCodeConfig({
+            accessToken,
+            adapter: this.configAdapter,
+            baseUrl: options.baseUrl,
+            preserveDefaultModel: hadToken,
+            fetchImpl: this.fetchImpl,
+          })
+        : undefined;
+
+    return { providerName: name, ok: true, provision };
+  }
+
+  async logout(providerName?: string | undefined): Promise<KimiOAuthLogoutResult> {
+    const name = providerName ?? KIMI_CODE_PROVIDER_NAME;
+    await this.managerFor(name).logout();
+    if (this.configAdapter?.remove !== undefined && name === KIMI_CODE_PROVIDER_NAME) {
+      const config = await this.configAdapter.read();
+      this.configAdapter.remove(config);
+      await this.configAdapter.write(config);
+    }
+    return { providerName: name, ok: true };
+  }
+
+  async ensureFresh(
+    providerName?: string | undefined,
+    options: { readonly force?: boolean | undefined } = {},
+  ): Promise<string> {
+    const name = providerName ?? KIMI_CODE_PROVIDER_NAME;
+    return this.managerFor(name).ensureFresh(options);
+  }
+
+  async getCachedAccessToken(
+    providerName?: string,
+    oauthRef?: KimiOAuthTokenRef,
+  ): Promise<string | undefined> {
+    const name = providerName ?? KIMI_CODE_PROVIDER_NAME;
+    const oauthKey = oauthRef?.key ?? KIMI_CODE_OAUTH_KEY;
+    return this.managerFor(name, oauthKey).getCachedAccessToken();
+  }
+
+  tokenProvider(
+    providerName?: string | undefined,
+    oauthRef?: KimiOAuthTokenRef | undefined,
+  ): BearerTokenProvider {
+    const name = providerName ?? KIMI_CODE_PROVIDER_NAME;
+    const oauthKey = oauthRef?.key ?? KIMI_CODE_OAUTH_KEY;
+    return {
+      getAccessToken: (options) => this.managerFor(name, oauthKey).ensureFresh(options),
+    };
+  }
+
+  async getManagedUsage(providerName?: string | undefined): Promise<AuthManagedUsageResult> {
+    const name = providerName ?? KIMI_CODE_PROVIDER_NAME;
+    try {
+      const accessToken = await this.ensureFresh(name);
+      const result = await fetchManagedUsage(kimiCodeUsageUrl(), accessToken);
+      if (result.kind === 'error') return result;
+      return {
+        kind: 'ok',
+        summary: result.parsed.summary,
+        limits: result.parsed.limits,
+      };
+    } catch (error) {
+      return {
+        kind: 'error',
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  async submitFeedback(
+    body: SubmitFeedbackBody,
+    providerName?: string | undefined,
+  ): Promise<FetchSubmitFeedbackResult> {
+    const name = providerName ?? KIMI_CODE_PROVIDER_NAME;
+    try {
+      const accessToken = await this.ensureFresh(name);
+      return await fetchSubmitFeedback(kimiCodeFeedbackUrl(), accessToken, body);
+    } catch (error) {
+      return {
+        kind: 'error',
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  managerFor(providerName: string, oauthKey = KIMI_CODE_OAUTH_KEY): OAuthManager {
+    const storageName = resolveKimiTokenStorageName({ providerName, oauthKey });
+    let manager = this.managers.get(storageName);
+    if (manager !== undefined) return manager;
+
+    const identity = this.identity;
+    manager = new OAuthManager({
+      config: {
+        ...this.flowConfig,
+        name: storageName,
+      },
+      storage: this.storage,
+      configDir: this.homeDir,
+      deviceHeaders:
+        identity === undefined
+          ? undefined
+          : () =>
+              createKimiDeviceHeaders({
+                homeDir: this.homeDir,
+                version: identity.version,
+              }),
+      ...this.managerOptions,
+    });
+    this.managers.set(storageName, manager);
+    return manager;
+  }
+}
+
+export function resolveKimiTokenStorageName(input: {
+  readonly providerName?: string | undefined;
+  readonly oauthKey?: string | undefined;
+}): string {
+  const providerName = input.providerName ?? KIMI_CODE_PROVIDER_NAME;
+  if (providerName !== KIMI_CODE_PROVIDER_NAME) {
+    throw new Error(`No OAuth manager configured for provider "${providerName}".`);
+  }
+
+  const key = input.oauthKey ?? KIMI_CODE_OAUTH_KEY;
+  if (key === 'kimi-code' || key === KIMI_CODE_OAUTH_KEY) return 'kimi-code';
+
+  const prefix = 'oauth/';
+  if (key.startsWith(prefix) && key.slice(prefix.length).length > 0) {
+    return key.slice(prefix.length);
+  }
+
+  if (!key.includes('/') && !key.startsWith('.')) return key;
+  throw new Error(`Invalid Kimi OAuth token key: "${key}".`);
+}
+
+function defaultKimiHome(): string {
+  const override = process.env['KIMI_CODE_HOME'];
+  if (override !== undefined && override.length > 0) return override;
+  return join(homedir(), '.kimi-code');
+}
diff --git a/packages/oauth/src/types.ts b/packages/oauth/src/types.ts
new file mode 100644
index 000000000..9073f8614
--- /dev/null
+++ b/packages/oauth/src/types.ts
@@ -0,0 +1,87 @@
+/**
+ * OAuth type definitions for managed providers.
+ *
+ * Only Device Code Flow (RFC 8628) is supported, against
+ * `https://auth.kimi.com`.
+ *
+ * Wire format (on disk / server) uses snake_case to match the server
+ * contract; in-process types use camelCase per TS convention.
+ */
+
+export type OAuthStorageBackend = 'file';
+
+/** A persisted OAuth token bundle. */
+export interface TokenInfo {
+  readonly accessToken: string;
+  readonly refreshToken: string;
+  /** Unix seconds when access_token expires. */
+  readonly expiresAt: number;
+  readonly scope: string;
+  readonly tokenType: string;
+  /** Original expires_in from server response (seconds). */
+  readonly expiresIn: number;
+}
+
+/** RFC 8628 §3.2 device authorization response. */
+export interface DeviceAuthorization {
+  readonly userCode: string;
+  readonly deviceCode: string;
+  readonly verificationUri: string;
+  readonly verificationUriComplete: string;
+  /** Seconds until device_code expires (server-reported). May be null. */
+  readonly expiresIn: number | null;
+  /** Polling interval in seconds. */
+  readonly interval: number;
+}
+
+/** OAuth flow endpoint + client configuration. */
+export interface OAuthFlowConfig {
+  /** Logical provider name for storage (e.g. "kimi-code"). */
+  readonly name: string;
+  /** Base URL of the OAuth server, no trailing slash. */
+  readonly oauthHost: string;
+  /** Client ID registered with the OAuth provider. */
+  readonly clientId: string;
+}
+
+/** Device identification for `X-Msh-*` headers. */
+export interface DeviceHeaders {
+  readonly 'X-Msh-Platform': string;
+  readonly 'X-Msh-Version': string;
+  readonly 'X-Msh-Device-Name': string;
+  readonly 'X-Msh-Device-Model': string;
+  readonly 'X-Msh-Os-Version': string;
+  readonly 'X-Msh-Device-Id': string;
+}
+
+/** JSON wire format for token persistence (snake_case, Python-compatible). */
+export interface TokenInfoWire {
+  readonly access_token: string;
+  readonly refresh_token: string;
+  readonly expires_at: number;
+  readonly scope: string;
+  readonly token_type: string;
+  readonly expires_in: number;
+}
+
+export function tokenToWire(token: TokenInfo): TokenInfoWire {
+  return {
+    access_token: token.accessToken,
+    refresh_token: token.refreshToken,
+    expires_at: token.expiresAt,
+    scope: token.scope,
+    token_type: token.tokenType,
+    expires_in: token.expiresIn,
+  };
+}
+
+export function tokenFromWire(wire: Partial<TokenInfoWire>): TokenInfo {
+  return {
+    accessToken: wire.access_token ?? '',
+    refreshToken: wire.refresh_token ?? '',
+    expiresAt: typeof wire.expires_at === 'number' ? wire.expires_at : 0,
+    scope: wire.scope ?? '',
+    tokenType: wire.token_type ?? '',
+    expiresIn: typeof wire.expires_in === 'number' ? wire.expires_in : 0,
+  };
+}
diff --git a/packages/oauth/src/utils.ts b/packages/oauth/src/utils.ts
new file mode 100644
index 000000000..8bd11aada
--- /dev/null
+++ b/packages/oauth/src/utils.ts
@@ -0,0 +1,3 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
diff --git a/packages/oauth/test/helpers.ts b/packages/oauth/test/helpers.ts
new file mode 100644
index 000000000..f877bb642
--- /dev/null
+++ b/packages/oauth/test/helpers.ts
@@ -0,0 +1,129 @@
+import { spawn, type ChildProcessByStdio } from 'node:child_process';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import type { Readable } from 'node:stream';
+import { fileURLToPath } from 'node:url';
+
+const tsxCli = join(
+  dirname(fileURLToPath(import.meta.resolve('tsx/package.json'))),
+  'dist',
+  'cli.mjs',
+);
+
+export interface TempDirHandle {
+  readonly path: string;
+  cleanup(): Promise<void>;
+}
+
+export async function createTempWorkDir(): Promise<TempDirHandle> {
+  const path = await mkdtemp(join(tmpdir(), 'kimi-oauth-test-work-'));
+  let disposed = false;
+  return {
+    path,
+    cleanup: async () => {
+      if (disposed) return;
+      disposed = true;
+      await rm(path, { recursive: true, force: true });
+    },
+  };
+}
+
+export interface SpawnedWorker {
+  readonly id: number;
+  readonly pid: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+  readonly signal: NodeJS.Signals | null;
+}
+
+export interface SpawnInlineWorkersOptions {
+  readonly count: number;
+  readonly inlineScript: string;
+  readonly tmpDir: string;
+  readonly shareDir: string;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly timeoutMs?: number | undefined;
+}
+
+interface RunningWorker {
+  readonly id: number;
+  readonly child: ChildProcessByStdio<null, Readable, Readable>;
+  stdout: string;
+  stderr: string;
+  readonly exit: Promise<{ code: number | null; signal: NodeJS.Signals | null }>;
+}
+
+export async function spawnInlineWorkers(
+  opts: SpawnInlineWorkersOptions,
+): Promise<readonly SpawnedWorker[]> {
+  await mkdir(opts.tmpDir, { recursive: true });
+  const scriptPath = join(opts.tmpDir, 'worker.mjs');
+  await writeFile(scriptPath, opts.inlineScript, 'utf8');
+  const running: RunningWorker[] = [];
+  for (let id = 0; id < opts.count; id += 1) {
+    const child = spawn(tsxCli, [scriptPath, String(id)], {
+      env: {
+        ...process.env,
+        KIMI_CODE_HOME: opts.shareDir,
+        KIMI_WORKER_ID: String(id),
+        ...opts.env,
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const worker: RunningWorker = {
+      id,
+      child,
+      stdout: '',
+      stderr: '',
+      exit: new Promise((resolve) => {
+        child.on('exit', (code, signal) => {
+          resolve({ code, signal });
+        });
+        child.on('error', () => {
+          resolve({ code: -1, signal: null });
+        });
+      }),
+    };
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk: string) => {
+      worker.stdout += chunk;
+    });
+    child.stderr.on('data', (chunk: string) => {
+      worker.stderr += chunk;
+    });
+    running.push(worker);
+  }
+
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    for (const worker of running) {
+      if (worker.child.exitCode === null) worker.child.kill('SIGKILL');
+    }
+  }, opts.timeoutMs ?? 60_000);
+
+  try {
+    const results = await Promise.all(
+      running.map(async (worker): Promise<SpawnedWorker> => {
+        const exit = await worker.exit;
+        return {
+          id: worker.id,
+          pid: worker.child.pid ?? -1,
+          stdout: worker.stdout,
+          stderr: worker.stderr,
+          exitCode: exit.code ?? -1,
+          signal: exit.signal,
+        };
+      }),
+    );
+    if (timedOut) {
+      throw new Error(`spawnInlineWorkers timed out after ${String(opts.timeoutMs ?? 60_000)}ms`);
+    }
+    return results;
+  } finally {
+    clearTimeout(timer);
+  }
+}
diff --git a/packages/oauth/test/identity.test.ts b/packages/oauth/test/identity.test.ts
new file mode 100644
index 000000000..f33a9b97a
--- /dev/null
+++ b/packages/oauth/test/identity.test.ts
@@ -0,0 +1,150 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createKimiDefaultHeaders,
+  createKimiDeviceHeaders,
+  createKimiDeviceId,
+  createKimiUserAgent,
+} from '../src/identity';
+
+const tmpRoots: string[] = [];
+
+function tempHome(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'kimi-oauth-identity-'));
+  tmpRoots.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tmpRoots.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe('Kimi identity factories', () => {
+  it('creates and reuses a device id in the explicit homeDir', () => {
+    const homeDir = tempHome();
+    const first = createKimiDeviceId(homeDir);
+    const second = createKimiDeviceId(homeDir);
+
+    expect(first).toMatch(/^[0-9a-f-]+$/);
+    expect(second).toBe(first);
+  });
+
+  it('creates different device ids for different homeDir values', () => {
+    const first = createKimiDeviceId(tempHome());
+    const second = createKimiDeviceId(tempHome());
+
+    expect(second).not.toBe(first);
+  });
+
+  it('creates complete X-Msh device headers from host version', () => {
+    const headers = createKimiDeviceHeaders({
+      homeDir: tempHome(),
+      version: '1.2.3-test',
+    });
+
+    expect(headers['X-Msh-Platform']).toBe('kimi-code-cli');
+    expect(headers['X-Msh-Version']).toBe('1.2.3-test');
+    expect(headers['X-Msh-Device-Name']).toBeTruthy();
+    expect(headers['X-Msh-Device-Model']).toBeTruthy();
+    expect(headers['X-Msh-Os-Version']).toBeTruthy();
+    expect(headers['X-Msh-Device-Id']).toMatch(/^[0-9a-f-]+$/);
+  });
+
+  it('creates kimi-code-cli User-Agent and appends suffix only to UA', () => {
+    expect(
+      createKimiUserAgent({
+        userAgentProduct: 'kimi-code-cli',
+        version: '1.2.3',
+      }),
+    ).toBe('kimi-code-cli/1.2.3');
+    expect(
+      createKimiUserAgent({
+        userAgentProduct: 'kimi-code-cli',
+        version: '1.2.3',
+        userAgentSuffix: 'wire 4.5.6',
+      }),
+    ).toBe('kimi-code-cli/1.2.3 (wire 4.5.6)');
+  });
+
+  it('merges User-Agent and device headers into default headers', () => {
+    const headers = createKimiDefaultHeaders({
+      homeDir: tempHome(),
+      userAgentProduct: 'kimi-code-cli',
+      version: '1.2.3',
+    });
+
+    expect(headers['User-Agent']).toBe('kimi-code-cli/1.2.3');
+    expect(headers['X-Msh-Version']).toBe('1.2.3');
+    expect(headers['X-Msh-Device-Id']).toMatch(/^[0-9a-f-]+$/);
+  });
+});
+
+// HTTP header values must be plain ASCII without leading/trailing whitespace.
+// The public factories surface the sanitizer used for User-Agent and X-Msh-*.
+describe('ascii header value sanitization', () => {
+  it('strips a trailing newline from a header value', () => {
+    const ua = createKimiUserAgent({ userAgentProduct: 'kimi-code-cli', version: '6.8.0-101\n' });
+    expect(ua).toBe('kimi-code-cli/6.8.0-101');
+  });
+
+  it('drops non-ASCII codepoints while keeping the ASCII remainder', () => {
+    const ua = createKimiUserAgent({ userAgentProduct: 'kimi-code-cli', version: 'héllo' });
+    expect(ua).toBe('kimi-code-cli/hllo');
+  });
+
+  it('uses the unknown fallback when every hostname codepoint is non-ASCII', async () => {
+    vi.resetModules();
+    vi.doMock('node:os', async () => {
+      const actual = await vi.importActual<typeof import('node:os')>('node:os');
+      return {
+        ...actual,
+        hostname: () => '你好',
+        release: () => '1.0.0',
+        type: () => 'Linux',
+        arch: () => 'x64',
+      };
+    });
+
+    try {
+      const { createKimiDeviceHeaders: createHeaders } = await import('../src/identity');
+      const headers = createHeaders({ homeDir: tempHome(), version: '1.0.0' });
+      expect(headers['X-Msh-Device-Name']).toBe('unknown');
+    } finally {
+      vi.doUnmock('node:os');
+      vi.resetModules();
+    }
+  });
+
+  it('keeps every device-header value free of leading or trailing whitespace', async () => {
+    vi.resetModules();
+    vi.doMock('node:os', async () => {
+      const actual = await vi.importActual<typeof import('node:os')>('node:os');
+      return {
+        ...actual,
+        hostname: () => '  myhost  ',
+        release: () => '#101-Ubuntu SMP\n',
+        type: () => 'Linux',
+        arch: () => 'x64',
+      };
+    });
+
+    try {
+      const { createKimiDeviceHeaders: createHeaders } = await import('../src/identity');
+      const headers = createHeaders({ homeDir: tempHome(), version: '1.0.0' });
+      for (const [key, value] of Object.entries(headers)) {
+        expect(value, `header ${key} has untrimmed whitespace: ${JSON.stringify(value)}`).toBe(
+          value.trim(),
+        );
+      }
+    } finally {
+      vi.doUnmock('node:os');
+      vi.resetModules();
+    }
+  });
+});
diff --git a/packages/oauth/test/managed-feedback.test.ts b/packages/oauth/test/managed-feedback.test.ts
new file mode 100644
index 000000000..2ce23b18d
--- /dev/null
+++ b/packages/oauth/test/managed-feedback.test.ts
@@ -0,0 +1,152 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  fetchSubmitFeedback,
+  kimiCodeFeedbackUrl,
+  type SubmitFeedbackBody,
+} from '../src/managed-feedback';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+});
+
+const SAMPLE_BODY: SubmitFeedbackBody = {
+  session_id: 'sess-123',
+  content: 'great tool',
+  version: 'kimi-code-0.1.1',
+  os: 'Darwin 25.3.0',
+  model: 'kimi-code/kimi-for-coding',
+};
+
+describe('kimiCodeFeedbackUrl', () => {
+  it('appends /feedback to the default base URL', () => {
+    expect(kimiCodeFeedbackUrl()).toBe('https://api.kimi.com/coding/v1/feedback');
+  });
+
+  it('honours KIMI_CODE_BASE_URL and trims trailing slashes', () => {
+    vi.stubEnv('KIMI_CODE_BASE_URL', 'https://example.test/v9///');
+    expect(kimiCodeFeedbackUrl()).toBe('https://example.test/v9/feedback');
+  });
+});
+
+describe('fetchSubmitFeedback', () => {
+  it('POSTs JSON body with bearer auth and returns ok on 200', async () => {
+    const fetchMock = vi.fn(async () => new Response('', { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await fetchSubmitFeedback(
+      'https://api.example/feedback',
+      'access-token',
+      SAMPLE_BODY,
+    );
+
+    expect(result).toEqual({ kind: 'ok' });
+
+    const calls = fetchMock.mock.calls as unknown as [string, RequestInit?][];
+    const [calledUrl, init] = calls[0]!;
+    expect(calledUrl).toBe('https://api.example/feedback');
+    expect(init?.method).toBe('POST');
+
+    const headers = new Headers((init?.headers ?? {}) as Record<string, string>);
+    expect(headers.get('authorization')).toBe('Bearer access-token');
+    expect(headers.get('content-type')).toBe('application/json');
+    expect(headers.get('accept')).toBe('application/json');
+
+    expect(JSON.parse(init?.body as string)).toEqual(SAMPLE_BODY);
+  });
+
+  it('preserves the kimi-code- version prefix in the request body', async () => {
+    const fetchMock = vi.fn(async () => new Response('', { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    await fetchSubmitFeedback('https://api.example/feedback', 'tok', SAMPLE_BODY);
+
+    const calls = fetchMock.mock.calls as unknown as [string, RequestInit?][];
+    const sent = JSON.parse(calls[0]?.[1]?.body as string) as Record<string, unknown>;
+    expect(sent['version']).toBe('kimi-code-0.1.1');
+  });
+
+  it('returns an error with status when the server responds 401', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response('nope', { status: 401 })),
+    );
+
+    const result = await fetchSubmitFeedback(
+      'https://api.example/feedback',
+      'access-token',
+      SAMPLE_BODY,
+    );
+
+    expect(result.kind).toBe('error');
+    if (result.kind !== 'error') return;
+    expect(result.status).toBe(401);
+    expect(result.message).toMatch(/401/);
+  });
+
+  it('returns an error with status when the server responds 500', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response('boom', { status: 500 })),
+    );
+
+    const result = await fetchSubmitFeedback(
+      'https://api.example/feedback',
+      'access-token',
+      SAMPLE_BODY,
+    );
+
+    expect(result.kind).toBe('error');
+    if (result.kind !== 'error') return;
+    expect(result.status).toBe(500);
+  });
+
+  it('returns a timeout error when the request aborts', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(
+        (_url: string, init?: RequestInit) =>
+          new Promise<Response>((_, reject) => {
+            init?.signal?.addEventListener('abort', () => {
+              const err = new Error('aborted');
+              err.name = 'AbortError';
+              reject(err);
+            });
+          }),
+      ),
+    );
+
+    const result = await fetchSubmitFeedback(
+      'https://api.example/feedback',
+      'access-token',
+      SAMPLE_BODY,
+      { timeoutMs: 5 },
+    );
+
+    expect(result.kind).toBe('error');
+    if (result.kind !== 'error') return;
+    expect(result.status).toBeUndefined();
+    expect(result.message).toMatch(/timed out/);
+  });
+
+  it('returns a generic error message on network failure', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => {
+        throw new TypeError('network down');
+      }),
+    );
+
+    const result = await fetchSubmitFeedback(
+      'https://api.example/feedback',
+      'access-token',
+      SAMPLE_BODY,
+    );
+
+    expect(result.kind).toBe('error');
+    if (result.kind !== 'error') return;
+    expect(result.status).toBeUndefined();
+    expect(result.message).toMatch(/network down/);
+  });
+});
diff --git a/packages/oauth/test/managed-kimi-code.test.ts b/packages/oauth/test/managed-kimi-code.test.ts
new file mode 100644
index 000000000..fb0291923
--- /dev/null
+++ b/packages/oauth/test/managed-kimi-code.test.ts
@@ -0,0 +1,531 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  applyManagedKimiCodeLogoutConfig,
+  applyManagedKimiCodeConfig,
+  clearManagedKimiCodeConfig,
+  fetchManagedKimiCodeModels,
+  KIMI_CODE_PROVIDER_NAME,
+  provisionManagedKimiCodeConfig,
+  type ManagedKimiConfigShape,
+} from '../src/managed-kimi-code';
+
+function makeModelsResponse(): Response {
+  return new Response(
+    JSON.stringify({
+      data: [
+        {
+          id: 'kimi-for-coding',
+          context_length: 262144,
+          supports_reasoning: true,
+          supports_image_in: true,
+          supports_video_in: true,
+          display_name: 'Kimi for Coding',
+        },
+        {
+          id: 'kimi-k2.5',
+          context_length: 250000,
+          supports_reasoning: false,
+          supports_image_in: false,
+          supports_video_in: false,
+          supports_tool_use: false,
+        },
+      ],
+    }),
+    { status: 200, headers: { 'Content-Type': 'application/json' } },
+  );
+}
+
+describe('provisionManagedKimiCodeConfig', () => {
+  it('writes the managed provider, models, services, and default model through an adapter', async () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {
+        custom: {
+          type: 'kimi',
+          apiKey: 'sk-existing',
+          baseUrl: 'https://example.test/v1',
+        },
+      },
+      models: {
+        'kimi-code/stale': {
+          provider: KIMI_CODE_PROVIDER_NAME,
+          model: 'stale',
+        },
+        'custom-default': {
+          provider: 'custom',
+          model: 'custom-model',
+        },
+      },
+    };
+    const write = vi.fn();
+    const fetchMock = vi.fn(async () => makeModelsResponse());
+
+    const result = await provisionManagedKimiCodeConfig({
+      accessToken: 'oauth-access-token',
+      fetchImpl: fetchMock as unknown as typeof fetch,
+      adapter: {
+        configPath: '/tmp/config.toml',
+        read: () => config,
+        write,
+        apply: applyManagedKimiCodeConfig,
+      },
+    });
+
+    expect(result).toMatchObject({
+      providerName: KIMI_CODE_PROVIDER_NAME,
+      defaultModel: 'kimi-code/kimi-for-coding',
+      defaultThinking: true,
+      configPath: '/tmp/config.toml',
+    });
+    expect(result.models[0]?.supportsToolUse).toBe(true);
+    expect(result.models[1]?.supportsToolUse).toBe(false);
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://api.kimi.com/coding/v1/models',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer oauth-access-token',
+          Accept: 'application/json',
+        }),
+      }),
+    );
+    const calls = fetchMock.mock.calls as unknown as [string, RequestInit?][];
+    const init = calls[0]?.[1] ?? {};
+    const headers = new Headers((init.headers ?? {}) as Record<string, string>);
+    expect(headers.get('user-agent')).toBeNull();
+    expect(headers.get('x-msh-platform')).toBeNull();
+    expect(write).toHaveBeenCalledWith(config);
+
+    expect(config.providers['custom']).toMatchObject({
+      apiKey: 'sk-existing',
+    });
+    expect(config.models?.['custom-default']?.provider).toBe('custom');
+    expect(config.models?.['kimi-code/stale']).toBeUndefined();
+    expect(config.providers[KIMI_CODE_PROVIDER_NAME]).toMatchObject({
+      type: 'kimi',
+      baseUrl: 'https://api.kimi.com/coding/v1',
+      apiKey: '',
+      oauth: { storage: 'file', key: 'oauth/kimi-code' },
+    });
+    expect(config.models?.['kimi-code/kimi-for-coding']).toMatchObject({
+      provider: KIMI_CODE_PROVIDER_NAME,
+      model: 'kimi-for-coding',
+      maxContextSize: 262144,
+      capabilities: ['thinking', 'image_in', 'video_in', 'tool_use'],
+      displayName: 'Kimi for Coding',
+    });
+    expect(config.models?.['kimi-code/kimi-k2.5']?.capabilities).toBeUndefined();
+    expect(config.services?.moonshotSearch).toMatchObject({
+      baseUrl: 'https://api.kimi.com/coding/v1/search',
+      apiKey: '',
+      oauth: { storage: 'file', key: 'oauth/kimi-code' },
+    });
+    expect(Object.keys(config.services ?? {})).toEqual(['moonshotSearch', 'moonshotFetch']);
+  });
+
+  it('preserves an existing valid default model during refresh', async () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {
+        custom: {
+          type: 'kimi',
+          apiKey: 'sk-existing',
+          baseUrl: 'https://example.test/v1',
+        },
+        [KIMI_CODE_PROVIDER_NAME]: {
+          type: 'kimi',
+          apiKey: '',
+        },
+      },
+      defaultModel: 'custom-default',
+      defaultThinking: false,
+      models: {
+        'custom-default': {
+          provider: 'custom',
+          model: 'custom-model',
+          maxContextSize: 1000,
+        },
+        'kimi-code/stale': {
+          provider: KIMI_CODE_PROVIDER_NAME,
+          model: 'stale',
+          maxContextSize: 1000,
+        },
+      },
+    };
+
+    const result = await provisionManagedKimiCodeConfig({
+      accessToken: 'oauth-access-token',
+      fetchImpl: vi.fn(async () => makeModelsResponse()) as unknown as typeof fetch,
+      preserveDefaultModel: true,
+      adapter: {
+        read: () => config,
+        write: vi.fn(),
+        apply: applyManagedKimiCodeConfig,
+      },
+    });
+
+    expect(result.defaultModel).toBe('custom-default');
+    expect(result.defaultThinking).toBe(false);
+    expect(config.defaultModel).toBe('custom-default');
+    expect(config.defaultThinking).toBe(false);
+    expect(config.models?.['kimi-code/stale']).toBeUndefined();
+    expect(config.models?.['kimi-code/kimi-for-coding']?.displayName).toBe('Kimi for Coding');
+  });
+
+  it('infers default_thinking from fresh managed model capabilities', async () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {
+        [KIMI_CODE_PROVIDER_NAME]: {
+          type: 'kimi',
+          apiKey: '',
+        },
+      },
+      defaultModel: 'kimi-code/kimi-for-coding',
+      models: {
+        'kimi-code/kimi-for-coding': {
+          provider: KIMI_CODE_PROVIDER_NAME,
+          model: 'kimi-for-coding',
+          maxContextSize: 1000,
+          capabilities: [],
+        },
+      },
+    };
+
+    const result = await provisionManagedKimiCodeConfig({
+      accessToken: 'oauth-access-token',
+      fetchImpl: vi.fn(async () => makeModelsResponse()) as unknown as typeof fetch,
+      preserveDefaultModel: true,
+      adapter: {
+        read: () => config,
+        write: vi.fn(),
+        apply: applyManagedKimiCodeConfig,
+      },
+    });
+
+    expect(result.defaultModel).toBe('kimi-code/kimi-for-coding');
+    expect(result.defaultThinking).toBe(true);
+    expect(config.defaultThinking).toBe(true);
+  });
+
+  it('preserves explicit default_thinking when preserving a custom default without capabilities', async () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {
+        custom: {
+          type: 'kimi',
+          apiKey: 'sk-existing',
+        },
+      },
+      defaultModel: 'custom-default',
+      defaultThinking: true,
+      models: {
+        'custom-default': {
+          provider: 'custom',
+          model: 'custom-model',
+          maxContextSize: 1000,
+        },
+      },
+    };
+
+    const result = await provisionManagedKimiCodeConfig({
+      accessToken: 'oauth-access-token',
+      fetchImpl: vi.fn(async () => makeModelsResponse()) as unknown as typeof fetch,
+      preserveDefaultModel: true,
+      adapter: {
+        read: () => config,
+        write: vi.fn(),
+        apply: applyManagedKimiCodeConfig,
+      },
+    });
+
+    expect(result.defaultModel).toBe('custom-default');
+    expect(result.defaultThinking).toBe(true);
+    expect(config.defaultThinking).toBe(true);
+  });
+
+  it('defaults default_thinking to false when a preserved custom default has no signal', async () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {
+        custom: {
+          type: 'kimi',
+          apiKey: 'sk-existing',
+        },
+      },
+      defaultModel: 'custom-default',
+      models: {
+        'custom-default': {
+          provider: 'custom',
+          model: 'custom-model',
+          maxContextSize: 1000,
+        },
+      },
+    };
+
+    const result = await provisionManagedKimiCodeConfig({
+      accessToken: 'oauth-access-token',
+      fetchImpl: vi.fn(async () => makeModelsResponse()) as unknown as typeof fetch,
+      preserveDefaultModel: true,
+      adapter: {
+        read: () => config,
+        write: vi.fn(),
+        apply: applyManagedKimiCodeConfig,
+      },
+    });
+
+    expect(result.defaultModel).toBe('custom-default');
+    expect(result.defaultThinking).toBe(false);
+    expect(config.defaultThinking).toBe(false);
+  });
+
+  it('does not infer default_thinking from preserved custom default capabilities', async () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {
+        custom: {
+          type: 'kimi',
+          apiKey: 'sk-existing',
+        },
+      },
+      defaultModel: 'custom-default',
+      models: {
+        'custom-default': {
+          provider: 'custom',
+          model: 'custom-model',
+          maxContextSize: 1000,
+          capabilities: [],
+        },
+      },
+    };
+
+    const result = await provisionManagedKimiCodeConfig({
+      accessToken: 'oauth-access-token',
+      fetchImpl: vi.fn(async () => makeModelsResponse()) as unknown as typeof fetch,
+      preserveDefaultModel: true,
+      adapter: {
+        read: () => config,
+        write: vi.fn(),
+        apply: applyManagedKimiCodeConfig,
+      },
+    });
+
+    expect(result.defaultModel).toBe('custom-default');
+    expect(result.defaultThinking).toBe(false);
+    expect(config.defaultThinking).toBe(false);
+  });
+
+  it('keeps default_thinking off even when preserved custom default has thinking capability', async () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {
+        custom: {
+          type: 'kimi',
+          apiKey: 'sk-existing',
+        },
+      },
+      defaultModel: 'custom-default',
+      models: {
+        'custom-default': {
+          provider: 'custom',
+          model: 'custom-model',
+          maxContextSize: 1000,
+          capabilities: ['thinking'],
+        },
+      },
+    };
+
+    const result = await provisionManagedKimiCodeConfig({
+      accessToken: 'oauth-access-token',
+      fetchImpl: vi.fn(async () => makeModelsResponse()) as unknown as typeof fetch,
+      preserveDefaultModel: true,
+      adapter: {
+        read: () => config,
+        write: vi.fn(),
+        apply: applyManagedKimiCodeConfig,
+      },
+    });
+
+    expect(result.defaultModel).toBe('custom-default');
+    expect(result.defaultThinking).toBe(false);
+    expect(config.defaultThinking).toBe(false);
+  });
+
+  it('falls back to the first fetched model when the preserved default was removed', async () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {
+        [KIMI_CODE_PROVIDER_NAME]: {
+          type: 'kimi',
+          apiKey: '',
+        },
+      },
+      defaultModel: 'kimi-code/stale',
+      defaultThinking: false,
+      models: {
+        'kimi-code/stale': {
+          provider: KIMI_CODE_PROVIDER_NAME,
+          model: 'stale',
+          maxContextSize: 1000,
+        },
+      },
+    };
+
+    const result = await provisionManagedKimiCodeConfig({
+      accessToken: 'oauth-access-token',
+      fetchImpl: vi.fn(async () => makeModelsResponse()) as unknown as typeof fetch,
+      preserveDefaultModel: true,
+      adapter: {
+        read: () => config,
+        write: vi.fn(),
+        apply: applyManagedKimiCodeConfig,
+      },
+    });
+
+    expect(result.defaultModel).toBe('kimi-code/kimi-for-coding');
+    expect(result.defaultThinking).toBe(false);
+    expect(config.defaultModel).toBe('kimi-code/kimi-for-coding');
+    expect(config.defaultThinking).toBe(false);
+  });
+
+  it('removes managed provider, models, services, and default model on logout', () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {
+        [KIMI_CODE_PROVIDER_NAME]: {
+          type: 'kimi',
+          apiKey: '',
+        },
+        custom: {
+          type: 'kimi',
+          apiKey: 'sk-existing',
+        },
+      },
+      defaultModel: 'kimi-code/kimi-for-coding',
+      defaultThinking: true,
+      models: {
+        'kimi-code/kimi-for-coding': {
+          provider: KIMI_CODE_PROVIDER_NAME,
+          model: 'kimi-for-coding',
+          maxContextSize: 262144,
+        },
+        'custom-default': {
+          provider: 'custom',
+          model: 'custom-model',
+          maxContextSize: 1000,
+        },
+      },
+      services: {
+        moonshotSearch: { baseUrl: 'https://api.kimi.com/coding/v1/search' },
+        moonshotFetch: { baseUrl: 'https://api.kimi.com/coding/v1/fetch' },
+        customService: { baseUrl: 'https://service.example.test' },
+      },
+      raw: {
+        default_model: 'kimi-code/kimi-for-coding',
+        providers: {
+          [KIMI_CODE_PROVIDER_NAME]: { type: 'kimi' },
+          custom: { type: 'kimi' },
+        },
+        models: {
+          'kimi-code/kimi-for-coding': {
+            provider: KIMI_CODE_PROVIDER_NAME,
+            model: 'kimi-for-coding',
+          },
+          'custom-default': {
+            provider: 'custom',
+            model: 'custom-model',
+          },
+        },
+        services: {
+          moonshot_search: { base_url: 'https://api.kimi.com/coding/v1/search' },
+          moonshot_fetch: { base_url: 'https://api.kimi.com/coding/v1/fetch' },
+        },
+      },
+    };
+
+    applyManagedKimiCodeLogoutConfig(config);
+
+    expect(config.defaultModel).toBeUndefined();
+    expect(config.providers[KIMI_CODE_PROVIDER_NAME]).toBeUndefined();
+    expect(config.providers['custom']).toBeDefined();
+    expect(config.models?.['kimi-code/kimi-for-coding']).toBeUndefined();
+    expect(config.models?.['custom-default']).toBeDefined();
+    expect(config.services?.moonshotSearch).toBeUndefined();
+    expect(config.services?.moonshotFetch).toBeUndefined();
+    expect(config.services?.['customService']).toEqual({
+      baseUrl: 'https://service.example.test',
+    });
+  });
+
+  it('rejects managed models that do not include a positive context_length', async () => {
+    const fetchImpl = vi.fn(
+      async () =>
+        new Response(
+          JSON.stringify({
+            data: [{ id: 'kimi-for-coding', supports_reasoning: true }],
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        ),
+    ) as unknown as typeof fetch;
+
+    await expect(
+      fetchManagedKimiCodeModels({
+        accessToken: 'oauth-access-token',
+        fetchImpl,
+      }),
+    ).rejects.toThrow(/positive context_length/);
+  });
+
+  it('clears managed provider, models, default model, and services on logout', () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {
+        [KIMI_CODE_PROVIDER_NAME]: {
+          type: 'kimi',
+          apiKey: '',
+          oauth: { storage: 'file', key: 'oauth/kimi-code' },
+        },
+        custom: {
+          type: 'kimi',
+          apiKey: 'sk-existing',
+        },
+      },
+      defaultModel: 'kimi-code/kimi-for-coding',
+      models: {
+        'kimi-code/kimi-for-coding': {
+          provider: KIMI_CODE_PROVIDER_NAME,
+          model: 'kimi-for-coding',
+          maxContextSize: 262144,
+        },
+        'custom-default': {
+          provider: 'custom',
+          model: 'custom-model',
+          maxContextSize: 128000,
+        },
+      },
+      services: {
+        moonshotSearch: {
+          baseUrl: 'https://api.kimi.com/coding/v1/search',
+          apiKey: '',
+          oauth: { storage: 'file', key: 'oauth/kimi-code' },
+        },
+        moonshotFetch: {
+          baseUrl: 'https://api.kimi.com/coding/v1/fetch',
+          apiKey: '',
+          oauth: { storage: 'file', key: 'oauth/kimi-code' },
+        },
+        otherService: { baseUrl: 'https://service.example.test' },
+      },
+    };
+
+    const result = clearManagedKimiCodeConfig(config);
+
+    expect(result).toMatchObject({
+      providerName: KIMI_CODE_PROVIDER_NAME,
+      removedProvider: true,
+      removedModels: ['kimi-code/kimi-for-coding'],
+      defaultModelCleared: true,
+      removedServices: ['moonshotSearch', 'moonshotFetch'],
+    });
+    expect(config.providers[KIMI_CODE_PROVIDER_NAME]).toBeUndefined();
+    expect(config.providers['custom']).toMatchObject({ apiKey: 'sk-existing' });
+    expect(config.defaultModel).toBeUndefined();
+    expect(config.models?.['kimi-code/kimi-for-coding']).toBeUndefined();
+    expect(config.models?.['custom-default']).toMatchObject({ provider: 'custom' });
+    expect(config.services?.moonshotSearch).toBeUndefined();
+    expect(config.services?.moonshotFetch).toBeUndefined();
+    expect(config.services?.['otherService']).toMatchObject({
+      baseUrl: 'https://service.example.test',
+    });
+  });
+});
diff --git a/packages/oauth/test/managed-usage.test.ts b/packages/oauth/test/managed-usage.test.ts
new file mode 100644
index 000000000..28dfa610b
--- /dev/null
+++ b/packages/oauth/test/managed-usage.test.ts
@@ -0,0 +1,133 @@
+import { afterEach, describe, it, expect, vi } from 'vitest';
+
+import {
+  fetchManagedUsage,
+  formatDuration,
+  formatResetTime,
+  isManagedKimiCode,
+  parseManagedUsagePayload,
+} from '../src/managed-usage';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('isManagedKimiCode', () => {
+  it('matches only the kimi-code managed provider', () => {
+    expect(isManagedKimiCode('managed:kimi-code')).toBe(true);
+    expect(isManagedKimiCode('managed:moonshot-ai')).toBe(false);
+    expect(isManagedKimiCode('openai')).toBe(false);
+    expect(isManagedKimiCode('')).toBe(false);
+    expect(isManagedKimiCode(null)).toBe(false);
+    expect(isManagedKimiCode()).toBe(false);
+  });
+});
+
+describe('parseManagedUsagePayload', () => {
+  it('returns empty when payload is not an object', () => {
+    expect(parseManagedUsagePayload(null)).toEqual({ summary: null, limits: [] });
+    expect(parseManagedUsagePayload('nope')).toEqual({ summary: null, limits: [] });
+  });
+
+  it('extracts a summary from the `usage` object', () => {
+    const parsed = parseManagedUsagePayload({
+      usage: { used: 40, limit: 1000, name: 'Weekly limit' },
+    });
+    expect(parsed.summary).toEqual({
+      label: 'Weekly limit',
+      used: 40,
+      limit: 1000,
+    });
+    expect(parsed.limits).toEqual([]);
+  });
+
+  it('falls back to remaining=limit-used when used is absent', () => {
+    const parsed = parseManagedUsagePayload({ usage: { remaining: 200, limit: 1000 } });
+    expect(parsed.summary).toEqual({ label: 'Weekly limit', used: 800, limit: 1000 });
+  });
+
+  it('labels limits from window duration when no name is given', () => {
+    const parsed = parseManagedUsagePayload({
+      limits: [
+        { detail: { used: 1, limit: 100 }, window: { duration: 300, timeUnit: 'MINUTE' } },
+        { detail: { used: 2, limit: 50 }, window: { duration: 24, timeUnit: 'HOUR' } },
+      ],
+    });
+    expect(parsed.limits.map((l) => l.label)).toEqual(['5h limit', '24h limit']);
+  });
+
+  it('prefers explicit item.name over window duration label', () => {
+    const parsed = parseManagedUsagePayload({
+      limits: [
+        {
+          name: 'Daily cap',
+          detail: { used: 5, limit: 100 },
+          window: { duration: 1440, timeUnit: 'MINUTE' },
+        },
+      ],
+    });
+    expect(parsed.limits[0]!.label).toBe('Daily cap');
+  });
+
+  it('surfaces reset hints from resetAt timestamps', () => {
+    const future = new Date(Date.now() + 3600_000).toISOString();
+    const parsed = parseManagedUsagePayload({ usage: { used: 1, limit: 10, resetAt: future } });
+    expect(parsed.summary?.resetHint).toMatch(/resets in/);
+  });
+});
+
+describe('fetchManagedUsage', () => {
+  it('sends only Authorization and Accept headers', async () => {
+    const fetchMock = vi.fn(
+      async () =>
+        new Response(JSON.stringify({ usage: { used: 1, limit: 10 } }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(fetchManagedUsage('https://api.example/usages', 'access-token')).resolves.toEqual({
+      kind: 'ok',
+      parsed: {
+        summary: { label: 'Weekly limit', used: 1, limit: 10 },
+        limits: [],
+      },
+    });
+
+    const calls = fetchMock.mock.calls as unknown as [string, RequestInit?][];
+    const init = calls[0]?.[1] ?? {};
+    const headers = new Headers((init.headers ?? {}) as Record<string, string>);
+    expect(headers.get('authorization')).toBe('Bearer access-token');
+    expect(headers.get('accept')).toBe('application/json');
+    expect(headers.get('user-agent')).toBeNull();
+    expect(headers.get('x-msh-platform')).toBeNull();
+  });
+});
+
+describe('formatDuration', () => {
+  it('formats days/hours/minutes', () => {
+    expect(formatDuration(0)).toBe('0s');
+    expect(formatDuration(45)).toBe('45s');
+    expect(formatDuration(90)).toBe('1m');
+    expect(formatDuration(3600)).toBe('1h');
+    expect(formatDuration(3661)).toBe('1h 1m');
+    expect(formatDuration(86_400 + 7200 + 600)).toBe('1d 2h 10m');
+  });
+});
+
+describe('formatResetTime', () => {
+  it('returns "reset" for past timestamps', () => {
+    const past = new Date(Date.now() - 5000).toISOString();
+    expect(formatResetTime(past)).toBe('reset');
+  });
+
+  it('returns "resets in X" for future timestamps', () => {
+    const future = new Date(Date.now() + 3600_000).toISOString();
+    expect(formatResetTime(future)).toMatch(/^resets in /);
+  });
+
+  it('falls back when parsing fails', () => {
+    expect(formatResetTime('not-a-date')).toBe('resets at not-a-date');
+  });
+});
diff --git a/packages/oauth/test/oauth-manager-lock-failure.test.ts b/packages/oauth/test/oauth-manager-lock-failure.test.ts
new file mode 100644
index 000000000..cc5cd2a21
--- /dev/null
+++ b/packages/oauth/test/oauth-manager-lock-failure.test.ts
@@ -0,0 +1,95 @@
+import { mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { OAuthError } from '../src/errors';
+import { OAuthManager } from '../src/oauth-manager';
+import type { TokenStorage } from '../src/storage';
+import type { OAuthFlowConfig, TokenInfo } from '../src/types';
+
+const lockMock = vi.hoisted(() => ({
+  lock: vi.fn(),
+}));
+
+vi.mock('proper-lockfile', () => ({
+  default: {
+    lock: lockMock.lock,
+  },
+}));
+
+class InMemoryStorage implements TokenStorage {
+  public token: TokenInfo | undefined;
+
+  async load(): Promise<TokenInfo | undefined> {
+    return this.token;
+  }
+
+  async save(_name: string, token: TokenInfo): Promise<void> {
+    this.token = token;
+  }
+
+  async remove(): Promise<void> {
+    this.token = undefined;
+  }
+
+  async list(): Promise<string[]> {
+    return this.token === undefined ? [] : ['kimi-code'];
+  }
+}
+
+const config: OAuthFlowConfig = {
+  name: 'kimi-code',
+  oauthHost: 'https://unused.test',
+  clientId: 'test-client-id',
+};
+
+function makeToken(overrides: Partial<TokenInfo> = {}): TokenInfo {
+  return {
+    accessToken: 'at-old',
+    refreshToken: 'rt-old',
+    expiresAt: 1_000_000_100,
+    scope: '',
+    tokenType: 'Bearer',
+    expiresIn: 3600,
+    ...overrides,
+  };
+}
+
+describe('OAuthManager refresh lock failure', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = join(
+      tmpdir(),
+      `kimi-oauth-lock-failure-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    mkdirSync(dir, { recursive: true });
+    lockMock.lock.mockReset();
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it('fails closed instead of refreshing without a configured cross-process lock', async () => {
+    const storage = new InMemoryStorage();
+    storage.token = makeToken();
+    lockMock.lock.mockRejectedValue(new Error('lock busy'));
+    const refreshImpl = vi.fn().mockResolvedValue(makeToken({ accessToken: 'at-new' }));
+
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      configDir: dir,
+      now: () => 1_000_000_000,
+      refreshTokenImpl: refreshImpl,
+    });
+
+    await expect(mgr.ensureFresh()).rejects.toBeInstanceOf(OAuthError);
+    await expect(mgr.ensureFresh()).rejects.toThrow(/refresh lock/i);
+    expect(refreshImpl).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/oauth/test/oauth-manager-multi-process.test.ts b/packages/oauth/test/oauth-manager-multi-process.test.ts
new file mode 100644
index 000000000..4e8bbf7ca
--- /dev/null
+++ b/packages/oauth/test/oauth-manager-multi-process.test.ts
@@ -0,0 +1,268 @@
+/**
+ * OAuthManager cross-process refresh lock.
+ *
+ * Spawns N Node worker processes that each call `ensureFresh(force=true)`
+ * on the same OAuth provider. With the `proper-lockfile`-backed
+ * cross-process mutex around `doEnsureFresh`, only one worker actually
+ * hits the refresh endpoint (`refreshImpl`); the others re-read storage
+ * and see the rotated token produced by the winner.
+ *
+ * Workers run as inline `.mjs` scripts via `spawnInlineWorkers`. Each
+ * worker:
+ *   1. Dynamically imports `OAuthManager` from the current package source.
+ *   2. Constructs it with a file-backed TokenStorage pointing at
+ *      `{shareDir}/token.json` and a `refreshTokenImpl` that increments
+ *      `{shareDir}/refresh-count.txt` atomically before returning a
+ *      rotated token (refreshToken changes every refresh).
+ *   3. Calls `ensureFresh({force:true})` and exits.
+ *
+ * Oracle: after all workers exit, `refresh-count.txt` contains exactly
+ * `1` (when the lock is in place); `N` (when it is not).
+ *
+ * **Platform**: macOS / Linux only. Windows path quirks for
+ * `proper-lockfile` are bypassed via the `KIMI_DISABLE_OAUTH_LOCK=1`
+ * env-var escape hatch; this test skips on `process.platform === 'win32'`.
+ */
+
+import { mkdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createTempWorkDir, spawnInlineWorkers, type TempDirHandle } from './helpers';
+
+const skipOnWindows = process.platform === 'win32';
+const OAUTH_ENTRY_URL = new URL('../src/index.ts', import.meta.url).href;
+
+// ─────────────────────────────────────────────────────────────────────
+// Worker body — dedicated inline .mjs script.
+// ─────────────────────────────────────────────────────────────────────
+//
+// One worker = one ensureFresh(force=true) invocation. All workers race
+// against the same on-disk lock file and the same refresh-count.txt.
+//
+// `refresh-count.txt` starts empty (or missing). Workers atomically
+// append a single byte per observed refresh using O_APPEND semantics;
+// the final byte count equals the number of refreshes that took place.
+
+const WORKER_SCRIPT = `
+  import { readFile, writeFile, appendFile, mkdir, stat } from 'node:fs/promises';
+  import { join } from 'node:path';
+  const { OAuthManager } = await import(process.env.KIMI_OAUTH_ENTRY);
+
+  const shareDir = process.env.KIMI_CODE_HOME;
+  const tokenPath = join(shareDir, 'token.json');
+  const counterPath = join(shareDir, 'refresh-count.txt');
+  const readyPath = join(shareDir, 'first-load-ready.txt');
+  const lockDir = join(shareDir, 'oauth');
+  await mkdir(lockDir, { recursive: true });
+
+  async function waitForFirstLoadBarrier() {
+    if (process.env.KIMI_SYNC_FIRST_LOAD !== '1') return;
+    await appendFile(readyPath, '.');
+    const expected = Number(process.env.KIMI_WORKER_COUNT || '1');
+    const deadline = Date.now() + 10_000;
+    while (true) {
+      let ready = 0;
+      try {
+        ready = (await stat(readyPath)).size;
+      } catch {}
+      if (ready >= expected) return;
+      if (Date.now() >= deadline) {
+        throw new Error('first-load barrier timed out');
+      }
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  }
+
+  const config = {
+    name: 'test-provider',
+    oauthHost: 'https://unused.test',
+    clientId: 'test',
+  };
+
+  /** File-backed TokenStorage keyed on the single provider 'test-provider'. */
+  let firstLoad = true;
+  const storage = {
+    async load(name) {
+      try {
+        const raw = await readFile(tokenPath, 'utf8');
+        if (firstLoad) {
+          firstLoad = false;
+          await waitForFirstLoadBarrier();
+        }
+        const parsed = JSON.parse(raw);
+        return parsed[name];
+      } catch {
+        return undefined;
+      }
+    },
+    async save(name, token) {
+      // Read-modify-write. Good enough for the test oracle; the real
+      // cross-process correctness comes from the lock, not the storage.
+      let bag = {};
+      try {
+        bag = JSON.parse(await readFile(tokenPath, 'utf8'));
+      } catch {
+        bag = {};
+      }
+      bag[name] = token;
+      await writeFile(tokenPath, JSON.stringify(bag), 'utf8');
+    },
+    async remove(name) {},
+    async list() { return ['test-provider']; },
+  };
+
+  /** refreshImpl increments the oracle file and hands back a rotated token. */
+  const refreshImpl = async () => {
+    // One byte per observed refresh; O_APPEND is atomic on POSIX.
+    await appendFile(counterPath, '.');
+    const nowSec = Math.floor(Date.now() / 1000);
+    return {
+      accessToken: 'at-refreshed-' + String(nowSec),
+      refreshToken: 'rt-rotated-' + String(nowSec),
+      expiresAt: nowSec + 3600,
+      scope: '',
+      tokenType: 'Bearer',
+      expiresIn: 3600,
+    };
+  };
+
+  const manager = new OAuthManager({
+    config,
+    storage,
+    refreshTokenImpl: refreshImpl,
+    // minimal stubs — unused on ensureFresh
+    requestDeviceImpl: async () => { throw new Error('unused'); },
+    pollDeviceImpl: async () => { throw new Error('unused'); },
+    now: () => Math.floor(Date.now() / 1000),
+  });
+
+  // Every worker attempts a forced refresh. With a cross-process lock
+  // in place, only one worker's refreshImpl runs; the others read the
+  // rotated storage and return its accessToken without calling
+  // refreshImpl.
+  try {
+    const token = await manager.ensureFresh({ force: true });
+    process.stdout.write('ok:' + token + '\\n');
+  } catch (err) {
+    process.stdout.write('err:' + (err && err.message ? err.message : String(err)) + '\\n');
+  }
+  // Debug trace so the test oracle can diagnose mis-locking.
+  if (process.env.DEBUG_OAUTH_WORKER === '1') {
+    process.stderr.write('[worker ' + process.env.KIMI_WORKER_ID + '] done\\n');
+  }
+`;
+
+async function seedInitialToken(shareDir: string): Promise<void> {
+  const tokenPath = join(shareDir, 'token.json');
+  const nowSec = Math.floor(Date.now() / 1000);
+  const token = {
+    'test-provider': {
+      accessToken: 'at-initial',
+      refreshToken: 'rt-initial',
+      expiresAt: nowSec + 60, // inside refresh threshold → force refresh hits
+      scope: '',
+      tokenType: 'Bearer',
+      expiresIn: 3600,
+    },
+  };
+  const { writeFile } = await import('node:fs/promises');
+  await writeFile(tokenPath, JSON.stringify(token), 'utf8');
+}
+
+async function readRefreshCount(shareDir: string): Promise<number> {
+  const counterPath = join(shareDir, 'refresh-count.txt');
+  try {
+    const s = await stat(counterPath);
+    return s.size;
+  } catch {
+    return 0;
+  }
+}
+
+const tmpHandles: TempDirHandle[] = [];
+
+afterEach(async () => {
+  while (tmpHandles.length > 0) {
+    await tmpHandles.pop()!.cleanup();
+  }
+});
+
+describe.skipIf(skipOnWindows)('OAuthManager cross-process refresh lock', () => {
+  it('2 workers concurrently force-refresh → exactly one refreshImpl fires', async () => {
+    const dir = await createTempWorkDir();
+    tmpHandles.push(dir);
+    await seedInitialToken(dir.path);
+
+    const workers = await spawnInlineWorkers({
+      count: 2,
+      inlineScript: WORKER_SCRIPT,
+      tmpDir: dir.path,
+      shareDir: dir.path,
+      timeoutMs: 30_000,
+      env: {
+        KIMI_OAUTH_ENTRY: OAUTH_ENTRY_URL,
+        KIMI_SYNC_FIRST_LOAD: '1',
+        KIMI_WORKER_COUNT: '2',
+      },
+    });
+
+    // All workers exit cleanly.
+    for (const w of workers) {
+      expect(w.exitCode, `worker ${String(w.id)} stderr: ${w.stderr}`).toBe(0);
+      expect(w.stdout.startsWith('ok:')).toBe(true);
+    }
+
+    // Refresh count = 1 → exactly one refresh happened across the 5
+    // processes. Without the lock the count equals N (or any value > 1).
+    const count = await readRefreshCount(dir.path);
+    expect(count).toBe(1);
+  }, 45_000);
+
+  it('stale lock (held by a killed worker) is reclaimed after stale timeout', async () => {
+    // Scenario: worker A takes the lock and crashes without releasing
+    // (SIGKILL). Worker B arrives 6+ seconds later and must reclaim
+    // the stale lock via `proper-lockfile`'s `stale: 5_000ms` policy.
+    //
+    // BLK-2 fix: proper-lockfile represents the lock as a DIRECTORY
+    // at `{target}.lock/`. The staleness probe is `stat().mtimeMs`
+    // on that directory, so we must `mkdir` + `utimes` (not
+    // `writeFile`, which would put a regular file where a dir is
+    // expected — `proper-lockfile` would then blow up or
+    // mis-interpret it).
+    const dir = await createTempWorkDir();
+    tmpHandles.push(dir);
+    await seedInitialToken(dir.path);
+    await mkdir(join(dir.path, 'oauth'), { recursive: true });
+
+    const { utimes } = await import('node:fs/promises');
+    const lockDir = join(dir.path, 'oauth', 'test-provider.lock');
+    await mkdir(lockDir, { recursive: true });
+    // 10 seconds ago — past the 5 s stale threshold.
+    const tenSecondsAgo = (Date.now() - 10_000) / 1000;
+    await utimes(lockDir, tenSecondsAgo, tenSecondsAgo);
+
+    const workers = await spawnInlineWorkers({
+      count: 1,
+      inlineScript: WORKER_SCRIPT,
+      tmpDir: dir.path,
+      shareDir: dir.path,
+      timeoutMs: 20_000,
+      env: {
+        KIMI_OAUTH_ENTRY: OAUTH_ENTRY_URL,
+      },
+    });
+
+    expect(workers[0]?.exitCode).toBe(0);
+    expect(workers[0]?.stdout.startsWith('ok:')).toBe(true);
+  }, 30_000);
+});
+
+// Prevent "no tests in file" when running on Windows.
+describe.skipIf(!skipOnWindows)('OAuthManager cross-process refresh lock (Windows skip)', () => {
+  it('skipped on Windows — covered by KIMI_DISABLE_OAUTH_LOCK=1 env escape hatch', () => {
+    expect(skipOnWindows).toBe(true);
+  });
+});
+
diff --git a/packages/oauth/test/oauth-manager.test.ts b/packages/oauth/test/oauth-manager.test.ts
new file mode 100644
index 000000000..bbac594d0
--- /dev/null
+++ b/packages/oauth/test/oauth-manager.test.ts
@@ -0,0 +1,902 @@
+/**
+ * OAuthManager tests — exercise ensureFresh / login / logout against a fake
+ * storage and injected transport mocks. No network, no file locks.
+ *
+ * We inject `refreshTokenImpl`, `pollDeviceImpl`, `requestDeviceImpl`, `now`,
+ * and `sleep` for determinism. The storage is an in-memory implementation.
+ */
+
+import { mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { DeviceCodeTimeoutError, OAuthUnauthorizedError } from '../src/errors';
+import type { DevicePollResult } from '../src/oauth';
+import { OAuthManager } from '../src/oauth-manager';
+import { FileTokenStorage } from '../src/storage';
+import type { TokenStorage } from '../src/storage';
+import type { DeviceAuthorization, OAuthFlowConfig, TokenInfo } from '../src/types';
+
+class InMemoryStorage implements TokenStorage {
+  public store = new Map<string, TokenInfo>();
+
+  async load(name: string): Promise<TokenInfo | undefined> {
+    return this.store.get(name);
+  }
+
+  async save(name: string, token: TokenInfo): Promise<void> {
+    this.store.set(name, token);
+  }
+
+  async remove(name: string): Promise<void> {
+    this.store.delete(name);
+  }
+
+  async list(): Promise<string[]> {
+    return [...this.store.keys()];
+  }
+}
+
+const config: OAuthFlowConfig = {
+  name: 'kimi-code',
+  oauthHost: 'https://test',
+  clientId: 'test',
+};
+
+function makeToken(overrides: Partial<TokenInfo> = {}): TokenInfo {
+  return {
+    accessToken: 'at-1',
+    refreshToken: 'rt-1',
+    expiresAt: 2_000_000_000, // far future
+    scope: '',
+    tokenType: 'Bearer',
+    expiresIn: 3600,
+    ...overrides,
+  };
+}
+
+let currentNow = 1_000_000_000;
+function now(): number {
+  return currentNow;
+}
+
+beforeEach(() => {
+  currentNow = 1_000_000_000;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ── ensureFresh ───────────────────────────────────────────────────────
+
+describe('OAuthManager.ensureFresh', () => {
+  it('returns stored access_token when not close to expiry', async () => {
+    const storage = new InMemoryStorage();
+    await storage.save('kimi-code', makeToken({ expiresAt: currentNow + 7200 }));
+    const refreshImpl = vi.fn();
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      refreshTokenImpl: refreshImpl,
+    });
+    const access = await mgr.ensureFresh();
+    expect(access).toBe('at-1');
+    expect(refreshImpl).not.toHaveBeenCalled();
+  });
+
+  it('refreshes when within dynamic threshold', async () => {
+    const storage = new InMemoryStorage();
+    // expires in 200s, threshold = max(300, 3600*0.5) = 1800. 200 < 1800 → refresh
+    await storage.save('kimi-code', makeToken({ expiresAt: currentNow + 200 }));
+    const refreshed = makeToken({
+      accessToken: 'at-new',
+      refreshToken: 'rt-new',
+      expiresAt: currentNow + 3600,
+    });
+    const refreshImpl = vi.fn().mockResolvedValue(refreshed);
+    const mgr = new OAuthManager({ config, storage, now, refreshTokenImpl: refreshImpl });
+    const access = await mgr.ensureFresh();
+    expect(refreshImpl).toHaveBeenCalledWith(config, 'rt-1');
+    expect(access).toBe('at-new');
+    expect((await storage.load('kimi-code'))?.accessToken).toBe('at-new');
+  });
+
+  it('force=true always refreshes', async () => {
+    const storage = new InMemoryStorage();
+    await storage.save('kimi-code', makeToken({ expiresAt: currentNow + 7200 }));
+    const refreshImpl = vi.fn().mockResolvedValue(makeToken({ accessToken: 'forced' }));
+    const mgr = new OAuthManager({ config, storage, now, refreshTokenImpl: refreshImpl });
+    const access = await mgr.ensureFresh({ force: true });
+    expect(refreshImpl).toHaveBeenCalled();
+    expect(access).toBe('forced');
+  });
+
+  it('force=true refreshes an unchanged freshly-issued token', async () => {
+    const storage = new InMemoryStorage();
+    await storage.save(
+      'kimi-code',
+      makeToken({
+        accessToken: 'at-fresh',
+        refreshToken: 'rt-fresh',
+        expiresAt: currentNow + 3600,
+        expiresIn: 3600,
+      }),
+    );
+    const refreshImpl = vi.fn().mockResolvedValue(
+      makeToken({
+        accessToken: 'forced-fresh',
+        refreshToken: 'rt-forced',
+        expiresAt: currentNow + 7200,
+      }),
+    );
+    const mgr = new OAuthManager({ config, storage, now, refreshTokenImpl: refreshImpl });
+    const access = await mgr.ensureFresh({ force: true });
+    expect(refreshImpl).toHaveBeenCalledTimes(1);
+    expect(access).toBe('forced-fresh');
+  });
+
+  it('force=true reuses a token changed by another process while waiting for the lock', async () => {
+    const storage = new InMemoryStorage();
+    await storage.save(
+      'kimi-code',
+      makeToken({
+        accessToken: 'at-old',
+        refreshToken: 'rt-old',
+        expiresAt: currentNow + 100,
+      }),
+    );
+    const refreshImpl = vi.fn();
+    const mgr = new OAuthManager({ config, storage, now, refreshTokenImpl: refreshImpl });
+
+    const originalLoad = storage.load.bind(storage);
+    let callCount = 0;
+    storage.load = async (name: string) => {
+      callCount += 1;
+      if (callCount === 2) {
+        await storage.save(
+          'kimi-code',
+          makeToken({
+            accessToken: 'at-peer',
+            refreshToken: 'rt-peer',
+            expiresAt: currentNow + 3600,
+          }),
+        );
+      }
+      return originalLoad(name);
+    };
+
+    const access = await mgr.ensureFresh({ force: true });
+    expect(access).toBe('at-peer');
+    expect(refreshImpl).not.toHaveBeenCalled();
+  });
+
+  it('concurrent ensureFresh calls share a single refresh', async () => {
+    const storage = new InMemoryStorage();
+    await storage.save('kimi-code', makeToken({ expiresAt: currentNow + 200 }));
+    let refreshCount = 0;
+    const refreshImpl = vi.fn().mockImplementation(async () => {
+      refreshCount += 1;
+      return makeToken({ accessToken: `at-${refreshCount}` });
+    });
+    const mgr = new OAuthManager({ config, storage, now, refreshTokenImpl: refreshImpl });
+    const [a, b, c] = await Promise.all([mgr.ensureFresh(), mgr.ensureFresh(), mgr.ensureFresh()]);
+    expect(refreshCount).toBe(1);
+    expect(a).toBe(b);
+    expect(b).toBe(c);
+  });
+
+  it('does not let a force=true caller piggyback a non-force in-flight refresh', async () => {
+    // The non-force caller arrives first while the stored token is still
+    // fresh enough to short-circuit (no refresh would fire). A later
+    // force=true caller must NOT receive that cached short-circuit —
+    // forced rotation has its own semantics (e.g. recovery after a 401
+    // upstream) that the non-force coalesce path cannot satisfy.
+    const storage = new InMemoryStorage();
+    await storage.save('kimi-code', makeToken({ expiresAt: currentNow + 7200 }));
+    let refreshCount = 0;
+    const refreshImpl = vi.fn().mockImplementation(async () => {
+      refreshCount += 1;
+      return makeToken({ accessToken: `forced-${refreshCount}`, refreshToken: 'rt-new' });
+    });
+    const mgr = new OAuthManager({ config, storage, now, refreshTokenImpl: refreshImpl });
+
+    const nonForce = mgr.ensureFresh();
+    const forced = mgr.ensureFresh({ force: true });
+    const [nonForceResult, forcedResult] = await Promise.all([nonForce, forced]);
+
+    expect(refreshCount).toBe(1);
+    // Non-force saw the still-fresh cached token; force=true got the
+    // refresh it actually asked for.
+    expect(nonForceResult).toBe('at-1');
+    expect(forcedResult).toBe('forced-1');
+  });
+
+  it('lets a non-force caller piggyback a force=true in-flight refresh', async () => {
+    // The reverse direction is always safe: a non-force caller is happy
+    // with anything the in-flight call returns, so we MUST coalesce
+    // rather than spawn a second refresh round-trip.
+    const storage = new InMemoryStorage();
+    await storage.save('kimi-code', makeToken({ expiresAt: currentNow + 7200 }));
+    let refreshCount = 0;
+    const refreshImpl = vi.fn().mockImplementation(async () => {
+      refreshCount += 1;
+      return makeToken({ accessToken: `forced-${refreshCount}` });
+    });
+    const mgr = new OAuthManager({ config, storage, now, refreshTokenImpl: refreshImpl });
+
+    const forced = mgr.ensureFresh({ force: true });
+    const nonForce = mgr.ensureFresh();
+    const [forcedResult, nonForceResult] = await Promise.all([forced, nonForce]);
+
+    expect(refreshCount).toBe(1);
+    expect(forcedResult).toBe('forced-1');
+    expect(nonForceResult).toBe(forcedResult);
+  });
+
+  it('coalesces concurrent force=true callers onto a single refresh', async () => {
+    const storage = new InMemoryStorage();
+    await storage.save('kimi-code', makeToken({ expiresAt: currentNow + 7200 }));
+    let refreshCount = 0;
+    const refreshImpl = vi.fn().mockImplementation(async () => {
+      refreshCount += 1;
+      return makeToken({ accessToken: `forced-${refreshCount}` });
+    });
+    const mgr = new OAuthManager({ config, storage, now, refreshTokenImpl: refreshImpl });
+
+    const [a, b, c] = await Promise.all([
+      mgr.ensureFresh({ force: true }),
+      mgr.ensureFresh({ force: true }),
+      mgr.ensureFresh({ force: true }),
+    ]);
+
+    expect(refreshCount).toBe(1);
+    expect(a).toBe(b);
+    expect(b).toBe(c);
+  });
+
+  it('coalesces multiple queued force callers behind a single non-force in-flight refresh', async () => {
+    // While a non-force call is in flight, several force=true callers
+    // may arrive. They cannot piggyback the non-force result, but they
+    // SHOULD share a single forced refresh among themselves once the
+    // non-force call settles — otherwise N concurrent 401 recoveries
+    // would each burn a separate OAuth round-trip.
+    const storage = new InMemoryStorage();
+    await storage.save('kimi-code', makeToken({ expiresAt: currentNow + 7200 }));
+    let refreshCount = 0;
+    const refreshImpl = vi.fn().mockImplementation(async () => {
+      refreshCount += 1;
+      return makeToken({ accessToken: `forced-${refreshCount}` });
+    });
+    const mgr = new OAuthManager({ config, storage, now, refreshTokenImpl: refreshImpl });
+
+    const nonForce = mgr.ensureFresh();
+    const force1 = mgr.ensureFresh({ force: true });
+    const force2 = mgr.ensureFresh({ force: true });
+    const [nonForceResult, force1Result, force2Result] = await Promise.all([
+      nonForce,
+      force1,
+      force2,
+    ]);
+
+    expect(refreshCount).toBe(1);
+    expect(nonForceResult).toBe('at-1');
+    expect(force1Result).toBe('forced-1');
+    expect(force2Result).toBe(force1Result);
+  });
+
+  it('starts a fresh forced refresh after the non-force in-flight call fails', async () => {
+    // Edge case: the non-force in-flight call rejects (e.g. transient
+    // network error). A queued force caller must still get its forced
+    // refresh — the failure of the unrelated non-force call must not
+    // bleed into the force caller's outcome.
+    const storage = new InMemoryStorage();
+    await storage.save('kimi-code', makeToken({ expiresAt: currentNow + 200 }));
+    const refreshImpl = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('network unreachable'))
+      .mockResolvedValueOnce(makeToken({ accessToken: 'forced-recovery' }));
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      refreshTokenImpl: refreshImpl,
+      sleep: async () => {},
+    });
+
+    const nonForcePromise = mgr.ensureFresh().catch((error: unknown) => error);
+    const forcedPromise = mgr.ensureFresh({ force: true });
+    const [nonForceOutcome, forcedResult] = await Promise.all([nonForcePromise, forcedPromise]);
+
+    expect((nonForceOutcome as Error).message).toMatch(/network unreachable/);
+    expect(forcedResult).toBe('forced-recovery');
+    expect(refreshImpl).toHaveBeenCalledTimes(2);
+  });
+
+  it('throws when no stored token (caller should drive /login)', async () => {
+    const storage = new InMemoryStorage();
+    const mgr = new OAuthManager({ config, storage, now });
+    await expect(mgr.ensureFresh()).rejects.toThrow(/no token/i);
+  });
+
+  it('tombstones the stored token on OAuthUnauthorizedError (refresh_token rejected)', async () => {
+    // Keep the file (so a peer can observe "previously logged in, now
+    // rejected") but blank out access_token and refresh_token so neither
+    // this process nor a fresh one will try to reuse the rejected token.
+    const storage = new InMemoryStorage();
+    await storage.save(
+      'kimi-code',
+      makeToken({
+        accessToken: 'at-retained',
+        refreshToken: 'rt-retained',
+        expiresAt: currentNow + 100,
+      }),
+    );
+    const refreshImpl = vi.fn().mockRejectedValue(new OAuthUnauthorizedError('invalid_grant'));
+    const mgr = new OAuthManager({ config, storage, now, refreshTokenImpl: refreshImpl });
+    await expect(mgr.ensureFresh()).rejects.toBeInstanceOf(OAuthUnauthorizedError);
+    const retained = await storage.load('kimi-code');
+    expect(retained).toBeDefined();
+    expect(retained?.accessToken).toBe('');
+    expect(retained?.refreshToken).toBe('');
+  });
+
+  it('does NOT delete file if 401 happens after another process rotated (M5)', async () => {
+    const storage = new InMemoryStorage();
+    await storage.save(
+      'kimi-code',
+      makeToken({
+        accessToken: 'at-old',
+        refreshToken: 'rt-old',
+        expiresAt: currentNow + 100,
+      }),
+    );
+    // Simulate: our refresh attempt fails 401 because rt-old was rotated by
+    // another process; the new token is already in storage.
+    let refreshAttempts = 0;
+    const refreshImpl = vi.fn().mockImplementation(async (_cfg, rt: string) => {
+      refreshAttempts += 1;
+      if (rt === 'rt-old') {
+        // Race: while we were calling refresh, another process rotated.
+        await storage.save(
+          'kimi-code',
+          makeToken({
+            accessToken: 'at-rotated',
+            refreshToken: 'rt-rotated',
+            expiresAt: currentNow + 7200,
+          }),
+        );
+        throw new OAuthUnauthorizedError('rt-old already rotated');
+      }
+      return makeToken({ accessToken: 'should-not-reach' });
+    });
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      refreshTokenImpl: refreshImpl,
+      sleep: async () => {},
+    });
+    // Should NOT throw — should re-read the rotated token and return it
+    const access = await mgr.ensureFresh();
+    expect(access).toBe('at-rotated');
+    // File should still have the rotated token
+    expect((await storage.load('kimi-code'))?.accessToken).toBe('at-rotated');
+    expect(refreshAttempts).toBe(1);
+  });
+
+  // ── force=true propagates errors (no silent swallow) ──────────────────
+
+  it('force=true surfaces OAuthUnauthorizedError to the caller', async () => {
+    // `force=true` must not paper over a genuinely revoked refresh_token.
+    // Caller drives /login to recover; ensureFresh throws so the error
+    // is observable.
+    const storage = new InMemoryStorage();
+    await storage.save(
+      'kimi-code',
+      makeToken({ expiresAt: currentNow + 7200, refreshToken: 'rt-revoked' }),
+    );
+    const refreshImpl = vi
+      .fn()
+      .mockRejectedValue(new OAuthUnauthorizedError('refresh_token revoked'));
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      refreshTokenImpl: refreshImpl,
+      sleep: () => Promise.resolve(),
+    });
+
+    await expect(mgr.ensureFresh({ force: true })).rejects.toBeInstanceOf(OAuthUnauthorizedError);
+    // Tombstone on disk so a fresh process won't retry the dead refresh_token.
+    const retained = await storage.load('kimi-code');
+    expect(retained).toBeDefined();
+    expect(retained?.accessToken).toBe('');
+    expect(retained?.refreshToken).toBe('');
+  });
+
+  it('force=true surfaces network errors without swallowing', async () => {
+    // A transport error inside force=true must reach the caller —
+    // the caller owns the try/catch policy, not ensureFresh.
+    const storage = new InMemoryStorage();
+    await storage.save('kimi-code', makeToken({ expiresAt: currentNow + 7200 }));
+    const refreshImpl = vi.fn().mockRejectedValue(new Error('ECONNRESET: network unreachable'));
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      refreshTokenImpl: refreshImpl,
+      sleep: () => Promise.resolve(),
+    });
+
+    await expect(mgr.ensureFresh({ force: true })).rejects.toThrow(/ECONNRESET/);
+    // Network error is NOT a revocation signal — storage must stay intact.
+    expect(await storage.load('kimi-code')).toBeDefined();
+  });
+
+  it('uses fresh stored token when another process already rotated', async () => {
+    const storage = new InMemoryStorage();
+    await storage.save(
+      'kimi-code',
+      makeToken({
+        accessToken: 'at-old',
+        refreshToken: 'rt-old',
+        expiresAt: currentNow + 100,
+      }),
+    );
+    const refreshImpl = vi.fn(); // should NOT be called — latest is fresh
+    const mgr = new OAuthManager({ config, storage, now, refreshTokenImpl: refreshImpl });
+
+    // Second load call returns an externally-rotated token that's fresh.
+    const originalLoad = storage.load.bind(storage);
+    let callCount = 0;
+    storage.load = async (name: string) => {
+      callCount += 1;
+      if (callCount === 2) {
+        await storage.save(
+          'kimi-code',
+          makeToken({
+            accessToken: 'at-rotated',
+            refreshToken: 'rt-rotated',
+            expiresAt: currentNow + 3600,
+          }),
+        );
+      }
+      return originalLoad(name);
+    };
+
+    const access = await mgr.ensureFresh();
+    expect(access).toBe('at-rotated');
+    expect(refreshImpl).not.toHaveBeenCalled();
+  });
+});
+
+describe('OAuthManager.ensureFresh — rejected refresh token retention', () => {
+  it('suppresses a rejected refresh_token until the on-disk token rotates', async () => {
+    const storage = new InMemoryStorage();
+    await storage.save(
+      'kimi-code',
+      makeToken({
+        accessToken: 'at-stale',
+        refreshToken: 'rt-rejected-until-rotate',
+        expiresAt: currentNow + 100,
+      }),
+    );
+    const refreshImpl = vi.fn().mockRejectedValue(new OAuthUnauthorizedError('invalid_grant'));
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      refreshTokenImpl: refreshImpl,
+      sleep: async () => {},
+    });
+
+    await expect(mgr.ensureFresh({ force: true })).rejects.toBeInstanceOf(OAuthUnauthorizedError);
+    // Tombstoned on disk — fresh processes load this and see "rejected".
+    const persistedAfter401 = await storage.load('kimi-code');
+    expect(persistedAfter401).toBeDefined();
+    expect(persistedAfter401?.accessToken).toBe('');
+    expect(persistedAfter401?.refreshToken).toBe('');
+    expect(await mgr.hasToken()).toBe(false);
+    expect(await mgr.getCachedAccessToken()).toBeUndefined();
+
+    currentNow += 10_000;
+    await expect(mgr.ensureFresh()).rejects.toBeInstanceOf(OAuthUnauthorizedError);
+    // The tombstone short-circuits before refreshImpl can be called again.
+    expect(refreshImpl).toHaveBeenCalledTimes(1);
+
+    await storage.save(
+      'kimi-code',
+      makeToken({
+        accessToken: 'at-rotated',
+        refreshToken: 'rt-rotated',
+        expiresAt: currentNow + 7200,
+      }),
+    );
+
+    await expect(mgr.hasToken()).resolves.toBe(true);
+    await expect(mgr.getCachedAccessToken()).resolves.toBe('at-rotated');
+    await expect(mgr.ensureFresh()).resolves.toBe('at-rotated');
+    expect(refreshImpl).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns the stored access_token when expires_at is 0 (unknown expiry)', async () => {
+    const storage = new InMemoryStorage();
+    await storage.save(
+      'kimi-code',
+      makeToken({
+        accessToken: 'at-zero-expiry',
+        refreshToken: 'rt-zero-expiry',
+        expiresAt: 0,
+      }),
+    );
+    const refreshImpl = vi
+      .fn()
+      .mockResolvedValue(makeToken({ accessToken: 'at-should-not-refresh' }));
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      refreshTokenImpl: refreshImpl,
+      sleep: async () => {},
+    });
+
+    await expect(mgr.ensureFresh()).resolves.toBe('at-zero-expiry');
+    expect(refreshImpl).not.toHaveBeenCalled();
+  });
+
+  it('tombstones the on-disk token after 401 so a fresh process sees logged-out', async () => {
+    // After a refresh_token rejection we keep the file (so concurrent peers
+    // can observe the state and so we don't lose diagnostic info), but the
+    // persisted token MUST itself indicate "not usable" — otherwise a fresh
+    // process with an empty in-memory suppression cache would happily try
+    // to refresh the dead token again and burn an OAuth server round-trip
+    // every time. Tombstone = empty access_token + empty refresh_token.
+    const storage = new InMemoryStorage();
+    await storage.save(
+      'kimi-code',
+      makeToken({
+        accessToken: 'at-stale',
+        refreshToken: 'rt-rejected',
+        expiresAt: currentNow + 100,
+      }),
+    );
+    const refreshImpl = vi.fn().mockRejectedValue(new OAuthUnauthorizedError('invalid_grant'));
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      refreshTokenImpl: refreshImpl,
+      sleep: async () => {},
+    });
+
+    await expect(mgr.ensureFresh({ force: true })).rejects.toBeInstanceOf(OAuthUnauthorizedError);
+
+    const persistedAfter401 = await storage.load('kimi-code');
+    expect(persistedAfter401).toBeDefined();
+    expect(persistedAfter401?.accessToken).toBe('');
+    expect(persistedAfter401?.refreshToken).toBe('');
+  });
+});
+
+// ── login ─────────────────────────────────────────────────────────────
+
+describe('OAuthManager.login', () => {
+  function okAuth(): DeviceAuthorization {
+    return {
+      userCode: 'WDJB-MJHT',
+      deviceCode: 'dev123',
+      verificationUri: 'https://auth/verify',
+      verificationUriComplete: 'https://auth/verify?user_code=WDJB-MJHT',
+      expiresIn: 600,
+      interval: 5,
+    };
+  }
+
+  it('drives device flow to success and persists token', async () => {
+    const storage = new InMemoryStorage();
+    const requestImpl = vi.fn().mockResolvedValue(okAuth());
+    const pollResponses: DevicePollResult[] = [
+      { kind: 'pending', errorCode: 'authorization_pending', description: '' },
+      { kind: 'pending', errorCode: 'authorization_pending', description: '' },
+      { kind: 'success', token: makeToken({ accessToken: 'at-login' }) },
+    ];
+    const pollImpl = vi.fn().mockImplementation(async () => pollResponses.shift()!);
+
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      requestDeviceImpl: requestImpl,
+      pollDeviceImpl: pollImpl,
+      sleep: async () => {},
+    });
+
+    const onDeviceCode = vi.fn();
+    const result = await mgr.login({ onDeviceCode });
+    expect(result.accessToken).toBe('at-login');
+    expect(await storage.load('kimi-code')).toBeDefined();
+    expect(onDeviceCode).toHaveBeenCalledTimes(1);
+  });
+
+  it('awaits async onDeviceCode before polling', async () => {
+    const storage = new InMemoryStorage();
+    let deviceCodeDelivered = false;
+    const pollImpl = vi.fn().mockImplementation(async (): Promise<DevicePollResult> => {
+      expect(deviceCodeDelivered).toBe(true);
+      return { kind: 'success', token: makeToken({ accessToken: 'at-login' }) };
+    });
+
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      requestDeviceImpl: vi.fn().mockResolvedValue(okAuth()),
+      pollDeviceImpl: pollImpl,
+      sleep: async () => {},
+    });
+
+    await mgr.login({
+      onDeviceCode: async () => {
+        await Promise.resolve();
+        deviceCodeDelivered = true;
+      },
+    });
+
+    expect(pollImpl).toHaveBeenCalledTimes(1);
+  });
+
+  it('throws DeviceCodeTimeoutError when local 15-min budget exceeds', async () => {
+    const storage = new InMemoryStorage();
+    const requestImpl = vi.fn().mockResolvedValue(okAuth());
+    const pollImpl = vi.fn().mockResolvedValue({
+      kind: 'pending' as const,
+      errorCode: 'authorization_pending',
+      description: '',
+    });
+    // sleep mock also advances `currentNow` to simulate wall clock
+    const sleep = vi.fn().mockImplementation(async (ms: number) => {
+      currentNow += Math.ceil(ms / 1000);
+    });
+
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      requestDeviceImpl: requestImpl,
+      pollDeviceImpl: pollImpl,
+      sleep,
+      deviceCodeTimeoutMs: 10_000, // 10s for test
+    });
+
+    await expect(mgr.login()).rejects.toBeInstanceOf(DeviceCodeTimeoutError);
+    expect(await storage.load('kimi-code')).toBeUndefined();
+  });
+
+  it('throws on denied', async () => {
+    const storage = new InMemoryStorage();
+    const pollImpl = vi.fn().mockResolvedValue({
+      kind: 'denied' as const,
+      description: 'user rejected',
+    });
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      requestDeviceImpl: vi.fn().mockResolvedValue(okAuth()),
+      pollDeviceImpl: pollImpl,
+      sleep: async () => {},
+    });
+    await expect(mgr.login()).rejects.toThrow(/denied|reject/i);
+  });
+
+  it('restarts device flow when server reports expired_token', async () => {
+    const storage = new InMemoryStorage();
+    const requestImpl = vi.fn().mockResolvedValue(okAuth());
+    const pollResponses: DevicePollResult[] = [
+      { kind: 'expired' },
+      { kind: 'success', token: makeToken() },
+    ];
+    const pollImpl = vi.fn().mockImplementation(async () => pollResponses.shift()!);
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      requestDeviceImpl: requestImpl,
+      pollDeviceImpl: pollImpl,
+      sleep: async () => {},
+    });
+    const token = await mgr.login();
+    expect(token.accessToken).toBe('at-1');
+    expect(requestImpl).toHaveBeenCalledTimes(2);
+  });
+
+  it('respects AbortSignal during polling', async () => {
+    const storage = new InMemoryStorage();
+    const pollImpl = vi.fn().mockResolvedValue({
+      kind: 'pending' as const,
+      errorCode: 'authorization_pending',
+      description: '',
+    });
+    const ac = new AbortController();
+    const sleep = vi.fn().mockImplementation(async () => {
+      ac.abort();
+    });
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      requestDeviceImpl: vi.fn().mockResolvedValue({
+        userCode: 'U',
+        deviceCode: 'D',
+        verificationUri: '',
+        verificationUriComplete: 'https://x',
+        expiresIn: 600,
+        interval: 1,
+      }),
+      pollDeviceImpl: pollImpl,
+      sleep,
+    });
+    await expect(mgr.login({ signal: ac.signal })).rejects.toThrow(/abort/i);
+  });
+});
+
+// ── logout & hasToken ─────────────────────────────────────────────────
+
+describe('OAuthManager.logout and hasToken', () => {
+  it('logout removes stored token', async () => {
+    const storage = new InMemoryStorage();
+    await storage.save('kimi-code', makeToken());
+    const mgr = new OAuthManager({ config, storage, now });
+    await mgr.logout();
+    expect(await storage.load('kimi-code')).toBeUndefined();
+  });
+
+  it('hasToken returns true when stored, false otherwise', async () => {
+    const storage = new InMemoryStorage();
+    const mgr = new OAuthManager({ config, storage, now });
+    expect(await mgr.hasToken()).toBe(false);
+    await storage.save('kimi-code', makeToken());
+    expect(await mgr.hasToken()).toBe(true);
+  });
+
+  it('treats an empty stored access_token as missing', async () => {
+    const storage = new InMemoryStorage();
+    await storage.save(
+      'kimi-code',
+      makeToken({ accessToken: '', refreshToken: 'rt-empty-access-token' }),
+    );
+    const mgr = new OAuthManager({ config, storage, now });
+    expect(await mgr.getCachedAccessToken()).toBeUndefined();
+    expect(await mgr.hasToken()).toBe(false);
+  });
+});
+
+// ── slow_down RFC 8628 §3.5 ────────────────────────────────────────────
+
+describe('OAuthManager.login — slow_down handling', () => {
+  it('increases polling interval by 5s on slow_down (RFC 8628 §3.5)', async () => {
+    const storage = new InMemoryStorage();
+    const sleepCalls: number[] = [];
+    const sleep = async (ms: number): Promise<void> => {
+      sleepCalls.push(ms);
+    };
+    let n = 0;
+    const pollImpl = async (): Promise<DevicePollResult> => {
+      n += 1;
+      if (n === 1) return { kind: 'pending', errorCode: 'authorization_pending', description: '' };
+      if (n === 2) return { kind: 'pending', errorCode: 'slow_down', description: '' };
+      if (n === 3) return { kind: 'pending', errorCode: 'slow_down', description: '' };
+      return { kind: 'success', token: makeToken() };
+    };
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      requestDeviceImpl: async () => ({
+        userCode: 'U',
+        deviceCode: 'D',
+        verificationUri: '',
+        verificationUriComplete: 'https://x',
+        expiresIn: 600,
+        interval: 5, // baseline
+      }),
+      pollDeviceImpl: pollImpl,
+      sleep,
+    });
+    await mgr.login();
+    // After 1st pending → sleep 5s. After slow_down #2 → +5 = 10s.
+    // After slow_down #3 → +5 = 15s. Then success (no sleep).
+    expect(sleepCalls).toEqual([5000, 10_000, 15_000]);
+  });
+});
+
+// ── FileTokenStorage integration ───────────────────────────────────────
+
+describe('OAuthManager + FileTokenStorage integration', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = join(tmpdir(), `kimi-oauth-mgr-int-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(dir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('login persists token to disk; ensureFresh reads it back', async () => {
+    const storage = new FileTokenStorage(dir);
+    const refreshImpl = vi.fn().mockResolvedValue(makeToken({ accessToken: 'refreshed' }));
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      requestDeviceImpl: async () => ({
+        userCode: 'U',
+        deviceCode: 'D',
+        verificationUri: '',
+        verificationUriComplete: 'https://x',
+        expiresIn: 600,
+        interval: 5,
+      }),
+      pollDeviceImpl: async (): Promise<DevicePollResult> => ({
+        kind: 'success',
+        token: makeToken({ accessToken: 'fresh-from-login', expiresAt: currentNow + 7200 }),
+      }),
+      sleep: async () => {},
+      refreshTokenImpl: refreshImpl,
+    });
+    const token = await mgr.login();
+    expect(token.accessToken).toBe('fresh-from-login');
+
+    // New manager instance reads from same storage (simulates restart)
+    const mgr2 = new OAuthManager({
+      config,
+      storage,
+      now,
+      refreshTokenImpl: refreshImpl,
+    });
+    const access = await mgr2.ensureFresh();
+    expect(access).toBe('fresh-from-login');
+    expect(refreshImpl).not.toHaveBeenCalled();
+  });
+
+  it('logout removes token file', async () => {
+    const storage = new FileTokenStorage(dir);
+    await storage.save('kimi-code', makeToken());
+    const mgr = new OAuthManager({ config, storage, now });
+    expect(await mgr.hasToken()).toBe(true);
+    await mgr.logout();
+    expect(await mgr.hasToken()).toBe(false);
+    expect(await storage.load('kimi-code')).toBeUndefined();
+  });
+
+  it('ensureFresh refreshes and persists to disk', async () => {
+    const storage = new FileTokenStorage(dir);
+    await storage.save(
+      'kimi-code',
+      makeToken({ refreshToken: 'rt-original', expiresAt: currentNow + 100 }),
+    );
+    const refreshImpl = vi.fn().mockResolvedValue(
+      makeToken({
+        accessToken: 'rotated-access',
+        refreshToken: 'rotated-refresh',
+        expiresAt: currentNow + 7200,
+      }),
+    );
+    const mgr = new OAuthManager({
+      config,
+      storage,
+      now,
+      refreshTokenImpl: refreshImpl,
+    });
+    await mgr.ensureFresh();
+    const persisted = await storage.load('kimi-code');
+    expect(persisted?.accessToken).toBe('rotated-access');
+    expect(persisted?.refreshToken).toBe('rotated-refresh');
+  });
+});
diff --git a/packages/oauth/test/oauth.test.ts b/packages/oauth/test/oauth.test.ts
new file mode 100644
index 000000000..82a5c7f0b
--- /dev/null
+++ b/packages/oauth/test/oauth.test.ts
@@ -0,0 +1,636 @@
+/**
+ * OAuth device code flow tests — pure HTTP wrappers against a fake server.
+ *
+ * Covers the three endpoint calls: requestDeviceAuthorization, pollDeviceToken,
+ * refreshAccessToken. Uses a local HTTP server on a dynamic port to exercise
+ * the real fetch code path.
+ */
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { RetryableRefreshError, OAuthError, OAuthUnauthorizedError } from '../src/errors';
+import {
+  pollDeviceToken,
+  refreshAccessToken,
+  requestDeviceAuthorization,
+  type RefreshOptions,
+} from '../src/oauth';
+import type { DeviceHeaders, OAuthFlowConfig } from '../src/types';
+
+interface FakeResponse {
+  status: number;
+  body: string | Record<string, unknown>;
+  /**
+   * When true, destroy the socket before writing any status / body.
+   * Used by the "network error retry" test to surface a transport-level
+   * failure (fetch throws) on the first N attempts.
+   */
+  drop?: boolean;
+}
+
+interface Recorded {
+  path: string;
+  method: string;
+  headers: Record<string, string>;
+  body: string;
+}
+
+class FakeOAuthServer {
+  private server: Server | undefined;
+  private responses: Map<string, FakeResponse[]> = new Map();
+  readonly recorded: Recorded[] = [];
+  host = '';
+
+  async start(): Promise<void> {
+    this.server = createServer((req, res) => {
+      this.handle(req, res);
+    });
+    await new Promise<void>((resolve) => {
+      this.server!.listen(0, '127.0.0.1', () => {
+        resolve();
+      });
+    });
+    const addr = this.server.address();
+    if (addr === null || typeof addr === 'string') {
+      throw new Error('no server address');
+    }
+    this.host = `http://127.0.0.1:${addr.port}`;
+  }
+
+  async stop(): Promise<void> {
+    await new Promise<void>((resolve) => {
+      this.server!.close(() => {
+        resolve();
+      });
+    });
+  }
+
+  /** Queue a response for the given POST path (FIFO). */
+  enqueue(path: string, response: FakeResponse): void {
+    const key = `POST ${path}`;
+    const list = this.responses.get(key) ?? [];
+    list.push(response);
+    this.responses.set(key, list);
+  }
+
+  private handle(req: IncomingMessage, res: ServerResponse): void {
+    const chunks: Buffer[] = [];
+    req.on('data', (chunk: Buffer) => chunks.push(chunk));
+    req.on('end', () => {
+      const body = Buffer.concat(chunks).toString('utf-8');
+      const path = req.url ?? '';
+      this.recorded.push({
+        path,
+        method: req.method ?? '',
+        headers: req.headers as Record<string, string>,
+        body,
+      });
+      const key = `${req.method} ${path}`;
+      const queue = this.responses.get(key);
+      const next = queue?.shift();
+      if (!next) {
+        res.statusCode = 404;
+        res.end(JSON.stringify({ error: 'no fake response queued', key }));
+        return;
+      }
+      if (next.drop === true) {
+        // Destroy the socket so `fetch` rejects with a transport error.
+        req.socket.destroy();
+        return;
+      }
+      res.statusCode = next.status;
+      res.setHeader('content-type', 'application/json');
+      res.end(typeof next.body === 'string' ? next.body : JSON.stringify(next.body));
+    });
+  }
+}
+
+// ── Fixtures ──────────────────────────────────────────────────────────
+
+let server: FakeOAuthServer;
+
+const TEST_DEVICE_HEADERS: DeviceHeaders = {
+  'X-Msh-Platform': 'kimi-code-cli',
+  'X-Msh-Version': '0.0.0-test',
+  'X-Msh-Device-Name': 'test-device',
+  'X-Msh-Device-Model': 'test-model',
+  'X-Msh-Os-Version': 'test-os',
+  'X-Msh-Device-Id': 'test-device-id',
+};
+
+function expectNoDeviceHeaders(headers: Record<string, string>): void {
+  expect(headers['x-msh-platform']).toBeUndefined();
+  expect(headers['x-msh-device-id']).toBeUndefined();
+  expect(headers['x-msh-version']).toBeUndefined();
+}
+
+function flowConfig(): OAuthFlowConfig {
+  return {
+    name: 'kimi-code',
+    oauthHost: server.host,
+    clientId: 'test-client-id',
+  };
+}
+
+function requestAuth(
+  config: OAuthFlowConfig = flowConfig(),
+): ReturnType<typeof requestDeviceAuthorization> {
+  return requestDeviceAuthorization(config, { deviceHeaders: TEST_DEVICE_HEADERS });
+}
+
+function pollToken(
+  config: OAuthFlowConfig,
+  deviceCode: string,
+): ReturnType<typeof pollDeviceToken> {
+  return pollDeviceToken(config, deviceCode, { deviceHeaders: TEST_DEVICE_HEADERS });
+}
+
+function refreshToken(
+  config: OAuthFlowConfig,
+  refreshTokenValue: string,
+  options: Omit<RefreshOptions, 'deviceHeaders'> = {},
+): ReturnType<typeof refreshAccessToken> {
+  return refreshAccessToken(config, refreshTokenValue, {
+    ...options,
+    deviceHeaders: TEST_DEVICE_HEADERS,
+  });
+}
+
+beforeEach(async () => {
+  server = new FakeOAuthServer();
+  await server.start();
+});
+
+afterEach(async () => {
+  await server.stop();
+});
+
+// ── requestDeviceAuthorization ────────────────────────────────────────
+
+describe('requestDeviceAuthorization', () => {
+  it('parses a successful response', async () => {
+    server.enqueue('/api/oauth/device_authorization', {
+      status: 200,
+      body: {
+        user_code: 'WDJB-MJHT',
+        device_code: 'devcode123',
+        verification_uri: 'https://auth.kimi.com/verify',
+        verification_uri_complete: 'https://auth.kimi.com/verify?user_code=WDJB-MJHT',
+        expires_in: 600,
+        interval: 5,
+      },
+    });
+
+    const auth = await requestAuth();
+    expect(auth.userCode).toBe('WDJB-MJHT');
+    expect(auth.deviceCode).toBe('devcode123');
+    expect(auth.verificationUri).toBe('https://auth.kimi.com/verify');
+    expect(auth.verificationUriComplete).toBe('https://auth.kimi.com/verify?user_code=WDJB-MJHT');
+    expect(auth.expiresIn).toBe(600);
+    expect(auth.interval).toBe(5);
+  });
+
+  it('posts client_id as form-encoded body', async () => {
+    server.enqueue('/api/oauth/device_authorization', {
+      status: 200,
+      body: {
+        user_code: 'U',
+        device_code: 'D',
+        verification_uri_complete: 'https://x/y',
+        expires_in: 60,
+        interval: 5,
+      },
+    });
+    await requestAuth();
+    const recorded = server.recorded[0]!;
+    expect(recorded.headers['content-type']).toContain('application/x-www-form-urlencoded');
+    expect(recorded.body).toContain('client_id=test-client-id');
+  });
+
+  it('sends X-Msh-* device headers', async () => {
+    server.enqueue('/api/oauth/device_authorization', {
+      status: 200,
+      body: {
+        user_code: 'U',
+        device_code: 'D',
+        verification_uri_complete: 'https://x/y',
+        expires_in: 60,
+        interval: 5,
+      },
+    });
+    await requestAuth();
+    const recorded = server.recorded[0]!;
+    expect(recorded.headers['x-msh-platform']).toBe('kimi-code-cli');
+    expect(recorded.headers['x-msh-device-id']).toBe('test-device-id');
+    expect(recorded.headers['x-msh-version']).toBe('0.0.0-test');
+    expect(recorded.headers['user-agent'] ?? '').not.toContain('kimi-code-cli');
+  });
+
+  it('omits X-Msh-* device headers when deviceHeaders are absent', async () => {
+    server.enqueue('/api/oauth/device_authorization', {
+      status: 200,
+      body: {
+        user_code: 'U',
+        device_code: 'D',
+        verification_uri_complete: 'https://x/y',
+        expires_in: 60,
+        interval: 5,
+      },
+    });
+    await requestDeviceAuthorization(flowConfig(), {});
+    const recorded = server.recorded[0]!;
+    expectNoDeviceHeaders(recorded.headers);
+  });
+
+  it('defaults interval to 5 when omitted', async () => {
+    server.enqueue('/api/oauth/device_authorization', {
+      status: 200,
+      body: {
+        user_code: 'U',
+        device_code: 'D',
+        verification_uri_complete: 'https://x/y',
+        expires_in: 60,
+      },
+    });
+    const auth = await requestAuth();
+    expect(auth.interval).toBe(5);
+  });
+
+  it('throws OAuthError on non-200 response', async () => {
+    server.enqueue('/api/oauth/device_authorization', {
+      status: 500,
+      body: { error: 'server_error' },
+    });
+    await expect(requestAuth()).rejects.toBeInstanceOf(OAuthError);
+  });
+
+  it('throws when device_code is missing (required-field validation)', async () => {
+    server.enqueue('/api/oauth/device_authorization', {
+      status: 200,
+      body: {
+        user_code: 'X',
+        verification_uri_complete: 'https://x',
+        expires_in: 60,
+        interval: 5,
+        // device_code missing
+      },
+    });
+    await expect(requestAuth()).rejects.toBeInstanceOf(OAuthError);
+  });
+
+  it('throws when verification_uri_complete is missing (required-field validation)', async () => {
+    server.enqueue('/api/oauth/device_authorization', {
+      status: 200,
+      body: {
+        user_code: 'X',
+        device_code: 'D',
+        expires_in: 60,
+        interval: 5,
+        // verification_uri_complete missing
+      },
+    });
+    await expect(requestAuth()).rejects.toBeInstanceOf(OAuthError);
+  });
+});
+
+// ── pollDeviceToken ───────────────────────────────────────────────────
+
+describe('pollDeviceToken', () => {
+  it('returns TokenInfo on success (200)', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 200,
+      body: {
+        access_token: 'at-1',
+        refresh_token: 'rt-1',
+        expires_in: 3600,
+        scope: 'read',
+        token_type: 'Bearer',
+      },
+    });
+
+    const res = await pollToken(flowConfig(), 'devcode123');
+    expect(res.kind).toBe('success');
+    if (res.kind !== 'success') throw new Error('expected success');
+    expect(res.token.accessToken).toBe('at-1');
+    expect(res.token.refreshToken).toBe('rt-1');
+    expect(res.token.expiresIn).toBe(3600);
+    expect(res.token.expiresAt).toBeGreaterThan(Date.now() / 1000);
+  });
+
+  it('omits X-Msh-* device headers when deviceHeaders are absent', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 200,
+      body: {
+        access_token: 'at-1',
+        refresh_token: 'rt-1',
+        expires_in: 3600,
+        scope: '',
+        token_type: 'Bearer',
+      },
+    });
+    await pollDeviceToken(flowConfig(), 'devcode123', {});
+    const recorded = server.recorded[0]!;
+    expectNoDeviceHeaders(recorded.headers);
+  });
+
+  it('returns pending on authorization_pending', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 400,
+      body: { error: 'authorization_pending' },
+    });
+
+    const res = await pollToken(flowConfig(), 'devcode123');
+    expect(res.kind).toBe('pending');
+    if (res.kind !== 'pending') throw new Error('expected pending');
+    expect(res.errorCode).toBe('authorization_pending');
+  });
+
+  it('returns pending on slow_down', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 400,
+      body: { error: 'slow_down' },
+    });
+    const res = await pollToken(flowConfig(), 'devcode123');
+    expect(res.kind).toBe('pending');
+  });
+
+  it('returns expired on expired_token', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 400,
+      body: { error: 'expired_token' },
+    });
+    const res = await pollToken(flowConfig(), 'devcode123');
+    expect(res.kind).toBe('expired');
+  });
+
+  it('returns denied on access_denied', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 400,
+      body: { error: 'access_denied' },
+    });
+    const res = await pollToken(flowConfig(), 'devcode123');
+    expect(res.kind).toBe('denied');
+  });
+
+  it('throws on 500 server error', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 500,
+      body: { error: 'server_error' },
+    });
+    await expect(pollToken(flowConfig(), 'd')).rejects.toBeInstanceOf(OAuthError);
+  });
+
+  it('throws when success response is missing refresh_token (required-field validation)', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 200,
+      body: {
+        access_token: 'at-1',
+        // refresh_token missing
+        expires_in: 60,
+        scope: '',
+        token_type: 'Bearer',
+      },
+    });
+    await expect(pollToken(flowConfig(), 'd')).rejects.toBeInstanceOf(OAuthError);
+  });
+
+  it('throws when success response has zero/missing expires_in (required-field validation)', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 200,
+      body: {
+        access_token: 'at-1',
+        refresh_token: 'rt-1',
+        scope: '',
+        token_type: 'Bearer',
+        // expires_in missing
+      },
+    });
+    await expect(pollToken(flowConfig(), 'd')).rejects.toBeInstanceOf(OAuthError);
+  });
+
+  it('sends device_code + grant_type=urn:ietf:params:oauth:grant-type:device_code', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 200,
+      body: {
+        access_token: 'a',
+        refresh_token: 'r',
+        expires_in: 60,
+        scope: '',
+        token_type: 'Bearer',
+      },
+    });
+    await pollToken(flowConfig(), 'devcode123');
+    const recorded = server.recorded[0]!;
+    expect(recorded.body).toContain('device_code=devcode123');
+    expect(recorded.body).toContain(
+      'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code',
+    );
+  });
+});
+
+// ── refreshAccessToken ────────────────────────────────────────────────
+
+describe('refreshAccessToken', () => {
+  it('returns new TokenInfo on success', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 200,
+      body: {
+        access_token: 'new-at',
+        refresh_token: 'new-rt',
+        expires_in: 3600,
+        scope: '',
+        token_type: 'Bearer',
+      },
+    });
+    const token = await refreshToken(flowConfig(), 'old-rt');
+    expect(token.accessToken).toBe('new-at');
+    expect(token.refreshToken).toBe('new-rt');
+  });
+
+  it('does not retry after a 401 refresh response', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 401,
+      body: { error: 'invalid_grant', error_description: 'refresh_token expired' },
+    });
+    server.enqueue('/api/oauth/token', {
+      status: 200,
+      body: {
+        access_token: 'should-not-reach',
+        refresh_token: 'r',
+        expires_in: 60,
+        scope: '',
+        token_type: 'Bearer',
+      },
+    });
+    await expect(
+      refreshToken(flowConfig(), 'old-rt', { maxRetries: 3, backoffMs: () => 0 }),
+    ).rejects.toBeInstanceOf(OAuthUnauthorizedError);
+    expect(server.recorded.length).toBe(1);
+  });
+
+  it('throws OAuthUnauthorizedError on 403', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 403,
+      body: {},
+    });
+    await expect(refreshToken(flowConfig(), 'old-rt')).rejects.toBeInstanceOf(
+      OAuthUnauthorizedError,
+    );
+  });
+
+  it('throws OAuthUnauthorizedError on invalid_grant refresh responses', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 400,
+      body: {
+        error: 'invalid_grant',
+        error_description: 'The provided authorization grant is invalid',
+      },
+    });
+    await expect(refreshToken(flowConfig(), 'old-rt')).rejects.toBeInstanceOf(
+      OAuthUnauthorizedError,
+    );
+  });
+
+  it.each([429, 500, 502, 503, 504])(
+    'retries transient HTTP %i refresh responses until success',
+    async (status) => {
+      server.enqueue('/api/oauth/token', {
+        status,
+        body: { error_description: 'overloaded' },
+      });
+      server.enqueue('/api/oauth/token', {
+        status: 200,
+        body: {
+          access_token: 'a',
+          refresh_token: 'r',
+          expires_in: 60,
+          scope: '',
+          token_type: 'Bearer',
+        },
+      });
+      const token = await refreshToken(flowConfig(), 'old-rt', {
+        maxRetries: 2,
+        backoffMs: () => 0,
+      });
+      expect(token.accessToken).toBe('a');
+      expect(server.recorded.length).toBe(2);
+    },
+  );
+
+  it('eventually raises RetryableRefreshError after max retries', async () => {
+    server.enqueue('/api/oauth/token', { status: 503, body: {} });
+    server.enqueue('/api/oauth/token', { status: 503, body: {} });
+    await expect(
+      refreshToken(flowConfig(), 'old-rt', { maxRetries: 2, backoffMs: () => 0 }),
+    ).rejects.toBeInstanceOf(RetryableRefreshError);
+  });
+
+  it('retries on transport-level fetch failure (network retry gap fix)', async () => {
+    // First attempt: server unreachable. Second: success.
+    const badConfig: OAuthFlowConfig = {
+      ...flowConfig(),
+      // Stop the real server, point at it (will refuse connection), then
+      // restart for the retry. This is awkward; instead inject via a
+      // separate flowConfig with closed port for the first call.
+      oauthHost: 'http://127.0.0.1:1', // reserved port, ECONNREFUSED
+    };
+    // Single attempt against unreachable host should throw (not RetryableRefreshError)
+    await expect(
+      refreshToken(badConfig, 'rt', { maxRetries: 1, backoffMs: () => 0 }),
+    ).rejects.toThrow(/OAuth request|fetch failed|Token refresh request|ECONNREFUSED|connect/i);
+  });
+
+  it('sends grant_type=refresh_token + refresh_token', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 200,
+      body: {
+        access_token: 'a',
+        refresh_token: 'r',
+        expires_in: 60,
+        scope: '',
+        token_type: 'Bearer',
+      },
+    });
+    await refreshToken(flowConfig(), 'old-rt-xyz');
+    const recorded = server.recorded[0]!;
+    expect(recorded.body).toContain('grant_type=refresh_token');
+    expect(recorded.body).toContain('refresh_token=old-rt-xyz');
+  });
+
+  it('omits X-Msh-* device headers when deviceHeaders are absent', async () => {
+    server.enqueue('/api/oauth/token', {
+      status: 200,
+      body: {
+        access_token: 'a',
+        refresh_token: 'r',
+        expires_in: 60,
+        scope: '',
+        token_type: 'Bearer',
+      },
+    });
+    await refreshAccessToken(flowConfig(), 'old-rt-xyz', { maxRetries: 1 });
+    const recorded = server.recorded[0]!;
+    expectNoDeviceHeaders(recorded.headers);
+  });
+
+  // ── network error retry / 400 fail-fast ───────────────────────────────
+
+  it('retries transport-level failures N times, then succeeds', async () => {
+    // The first two attempts fail with a transport error, the third
+    // succeeds. We prime the fake server with two force-drop responses
+    // that destroy the socket before writing headers, which surfaces
+    // as `fetch` throwing.
+    server.enqueue('/api/oauth/token', { status: 0, body: '', drop: true });
+    server.enqueue('/api/oauth/token', { status: 0, body: '', drop: true });
+    server.enqueue('/api/oauth/token', {
+      status: 200,
+      body: {
+        access_token: 'recovered-at',
+        refresh_token: 'recovered-rt',
+        expires_in: 3600,
+        scope: '',
+        token_type: 'Bearer',
+      },
+    });
+    const token = await refreshToken(flowConfig(), 'old-rt', {
+      maxRetries: 3,
+      backoffMs: () => 0,
+    });
+    expect(token.accessToken).toBe('recovered-at');
+    // All three attempts hit the server (two destroyed + one success)
+    expect(server.recorded.length).toBe(3);
+  });
+
+  it('400 Bad Request fails fast (not retried, non-retryable)', async () => {
+    // 400 is a client-side fault and must surface immediately as a
+    // bare OAuthError (never RetryableRefreshError, never retried).
+    server.enqueue('/api/oauth/token', {
+      status: 400,
+      body: { error: 'invalid_request', error_description: 'bad client id' },
+    });
+    // Second enqueue exists to prove a retry would hit it — if the
+    // implementation incorrectly retried, the second call would succeed
+    // and the test would miss the regression.
+    server.enqueue('/api/oauth/token', {
+      status: 200,
+      body: {
+        access_token: 'should-not-reach',
+        refresh_token: 'r',
+        expires_in: 60,
+        scope: '',
+        token_type: 'Bearer',
+      },
+    });
+    const err = await refreshToken(flowConfig(), 'rt', {
+      maxRetries: 5,
+      backoffMs: () => 0,
+    }).catch((error: unknown) => error);
+    expect(err).toBeInstanceOf(OAuthError);
+    expect(err).not.toBeInstanceOf(RetryableRefreshError);
+    expect(err).not.toBeInstanceOf(OAuthUnauthorizedError);
+    // Only one request — no retry.
+    expect(server.recorded.length).toBe(1);
+  });
+});
diff --git a/packages/oauth/test/open-platform.test.ts b/packages/oauth/test/open-platform.test.ts
new file mode 100644
index 000000000..79aa60618
--- /dev/null
+++ b/packages/oauth/test/open-platform.test.ts
@@ -0,0 +1,279 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  applyOpenPlatformConfig,
+  capabilitiesForModel,
+  fetchOpenPlatformModels,
+  filterModelsByPrefix,
+  getOpenPlatformById,
+  isOpenPlatformId,
+  OPEN_PLATFORMS,
+  removeOpenPlatformConfig,
+  type ManagedKimiConfigShape,
+} from '../src/open-platform';
+
+function makeModelsResponse(): Response {
+  return new Response(
+    JSON.stringify({
+      data: [
+        {
+          id: 'kimi-k2-0712-preview',
+          context_length: 256000,
+          supports_reasoning: true,
+          supports_image_in: true,
+          supports_video_in: true,
+          display_name: 'Kimi K2 0712 Preview',
+        },
+        {
+          id: 'kimi-k2-lite',
+          context_length: 128000,
+          supports_reasoning: false,
+          supports_image_in: false,
+          supports_video_in: false,
+          supports_tool_use: false,
+        },
+        {
+          id: 'non-kimi-model',
+          context_length: 1000,
+          supports_reasoning: false,
+        },
+      ],
+    }),
+    { status: 200, headers: { 'Content-Type': 'application/json' } },
+  );
+}
+
+describe('OPEN_PLATFORMS', () => {
+  it('contains moonshot.cn and moonshot.ai', () => {
+    expect(getOpenPlatformById('moonshot-cn')).toMatchObject({
+      name: 'Moonshot AI Open Platform (moonshot.cn)',
+      baseUrl: 'https://api.moonshot.cn/v1',
+      allowedPrefixes: ['kimi-k'],
+    });
+    expect(getOpenPlatformById('moonshot-ai')).toMatchObject({
+      name: 'Moonshot AI Open Platform (moonshot.ai)',
+      baseUrl: 'https://api.moonshot.ai/v1',
+      allowedPrefixes: ['kimi-k'],
+    });
+    expect(getOpenPlatformById('unknown')).toBeUndefined();
+  });
+
+  it('isOpenPlatformId works', () => {
+    expect(isOpenPlatformId('moonshot-cn')).toBe(true);
+    expect(isOpenPlatformId('moonshot-ai')).toBe(true);
+    expect(isOpenPlatformId('kimi-code')).toBe(false);
+  });
+});
+
+describe('fetchOpenPlatformModels', () => {
+  it('lists and parses models from the platform endpoint', async () => {
+    const fetchMock = vi.fn(async () => makeModelsResponse());
+    const platform = getOpenPlatformById('moonshot-cn')!;
+
+    const models = await fetchOpenPlatformModels(platform, 'sk-test', fetchMock as unknown as typeof fetch);
+
+    expect(models).toHaveLength(3);
+    expect(models[0]).toMatchObject({
+      id: 'kimi-k2-0712-preview',
+      contextLength: 256000,
+      supportsReasoning: true,
+      supportsImageIn: true,
+      supportsVideoIn: true,
+      displayName: 'Kimi K2 0712 Preview',
+    });
+    expect(models[1]?.supportsToolUse).toBe(false);
+    expect(models[2]?.id).toBe('non-kimi-model');
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://api.moonshot.cn/v1/models',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: 'Bearer sk-test',
+          Accept: 'application/json',
+        }),
+      }),
+    );
+  });
+
+  it('throws on HTTP error', async () => {
+    const fetchMock = vi.fn(async () => new Response('Unauthorized', { status: 401 }));
+    const platform = getOpenPlatformById('moonshot-cn')!;
+
+    await expect(
+      fetchOpenPlatformModels(platform, 'sk-bad', fetchMock as unknown as typeof fetch),
+    ).rejects.toThrow('Failed to list models (HTTP 401).');
+  });
+
+  it('throws on unexpected response shape', async () => {
+    const fetchMock = vi.fn(async () => new Response(JSON.stringify({}), { status: 200 }));
+    const platform = getOpenPlatformById('moonshot-cn')!;
+
+    await expect(
+      fetchOpenPlatformModels(platform, 'sk-test', fetchMock as unknown as typeof fetch),
+    ).rejects.toThrow(/Unexpected models response/);
+  });
+});
+
+describe('filterModelsByPrefix', () => {
+  it('filters by allowedPrefixes when present', () => {
+    const platform = getOpenPlatformById('moonshot-cn')!;
+    const models = [
+      { id: 'kimi-k2-0712-preview', contextLength: 256000, supportsReasoning: true, supportsImageIn: true, supportsVideoIn: true },
+      { id: 'gpt-4', contextLength: 1000, supportsReasoning: false, supportsImageIn: false, supportsVideoIn: false },
+    ];
+
+    const filtered = filterModelsByPrefix(models as unknown as import('../src/managed-kimi-code').ManagedKimiCodeModelInfo[], platform);
+    expect(filtered).toHaveLength(1);
+    expect(filtered[0]?.id).toBe('kimi-k2-0712-preview');
+  });
+
+  it('returns all models when allowedPrefixes is absent', () => {
+    const platform: import('../src/open-platform').OpenPlatformDefinition = {
+      id: 'custom',
+      name: 'Custom',
+      baseUrl: 'https://example.com/v1',
+    };
+    const models = [
+      { id: 'model-a', contextLength: 1000, supportsReasoning: false, supportsImageIn: false, supportsVideoIn: false },
+      { id: 'model-b', contextLength: 2000, supportsReasoning: false, supportsImageIn: false, supportsVideoIn: false },
+    ];
+
+    const filtered = filterModelsByPrefix(models as unknown as import('../src/managed-kimi-code').ManagedKimiCodeModelInfo[], platform);
+    expect(filtered).toHaveLength(2);
+  });
+});
+
+describe('capabilitiesForModel', () => {
+  it('returns undefined for a model with no capabilities', () => {
+    const model = {
+      id: 'plain',
+      contextLength: 1000,
+      supportsReasoning: false,
+      supportsImageIn: false,
+      supportsVideoIn: false,
+      supportsToolUse: false,
+    };
+    expect(capabilitiesForModel(model)).toBeUndefined();
+  });
+
+  it('returns all caps for a full-featured model', () => {
+    const model = {
+      id: 'full',
+      contextLength: 1000,
+      supportsReasoning: true,
+      supportsImageIn: true,
+      supportsVideoIn: true,
+      supportsToolUse: true,
+    };
+    expect(capabilitiesForModel(model)).toEqual(['thinking', 'image_in', 'video_in', 'tool_use']);
+  });
+});
+
+describe('applyOpenPlatformConfig', () => {
+  it('writes provider, models, and defaults', () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {},
+    };
+    const platform = getOpenPlatformById('moonshot-cn')!;
+    const models = [
+      { id: 'kimi-k2-0712-preview', contextLength: 256000, supportsReasoning: true, supportsImageIn: true, supportsVideoIn: true, displayName: 'Kimi K2' },
+      { id: 'kimi-k2-lite', contextLength: 128000, supportsReasoning: false, supportsImageIn: false, supportsVideoIn: false },
+    ];
+
+    const result = applyOpenPlatformConfig(config, {
+      platform,
+      models,
+      selectedModel: models[0]!,
+      thinking: true,
+      apiKey: 'sk-test',
+    });
+
+    expect(result).toEqual({
+      defaultModel: 'moonshot-cn/kimi-k2-0712-preview',
+      defaultThinking: true,
+    });
+
+    expect(config.providers['moonshot-cn']).toMatchObject({
+      type: 'kimi',
+      baseUrl: 'https://api.moonshot.cn/v1',
+      apiKey: 'sk-test',
+    });
+    expect(config.models?.['moonshot-cn/kimi-k2-0712-preview']).toMatchObject({
+      provider: 'moonshot-cn',
+      model: 'kimi-k2-0712-preview',
+      maxContextSize: 256000,
+      capabilities: ['thinking', 'image_in', 'video_in', 'tool_use'],
+      displayName: 'Kimi K2',
+    });
+    expect(config.defaultModel).toBe('moonshot-cn/kimi-k2-0712-preview');
+    expect(config.defaultThinking).toBe(true);
+    expect(config.services).toBeUndefined();
+  });
+
+  it('clears stale models for the same provider', () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {
+        'moonshot-cn': { type: 'kimi', baseUrl: 'https://api.moonshot.cn/v1', apiKey: 'sk-old' },
+      },
+      models: {
+        'moonshot-cn/stale': { provider: 'moonshot-cn', model: 'stale', maxContextSize: 1000 },
+        'other/model': { provider: 'other', model: 'other-model', maxContextSize: 1000 },
+      },
+    };
+    const platform = getOpenPlatformById('moonshot-cn')!;
+    const models = [
+      { id: 'kimi-k2-0712-preview', contextLength: 256000, supportsReasoning: true, supportsImageIn: true, supportsVideoIn: true },
+    ];
+
+    applyOpenPlatformConfig(config, {
+      platform,
+      models,
+      selectedModel: models[0]!,
+      thinking: false,
+      apiKey: 'sk-new',
+    });
+
+    expect(config.models?.['moonshot-cn/stale']).toBeUndefined();
+    expect(config.models?.['other/model']).toBeDefined();
+  });
+});
+
+describe('removeOpenPlatformConfig', () => {
+  it('removes provider, its models, and defaultModel when matched', () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {
+        'moonshot-cn': { type: 'kimi', baseUrl: 'https://api.moonshot.cn/v1', apiKey: 'sk-test' },
+        'other': { type: 'kimi', baseUrl: 'https://other.test/v1', apiKey: 'sk-other' },
+      },
+      models: {
+        'moonshot-cn/kimi-k2': { provider: 'moonshot-cn', model: 'kimi-k2', maxContextSize: 256000 },
+        'other/model': { provider: 'other', model: 'other-model', maxContextSize: 1000 },
+      },
+      defaultModel: 'moonshot-cn/kimi-k2',
+    };
+
+    removeOpenPlatformConfig(config, 'moonshot-cn');
+
+    expect(config.providers['moonshot-cn']).toBeUndefined();
+    expect(config.providers['other']).toBeDefined();
+    expect(config.models?.['moonshot-cn/kimi-k2']).toBeUndefined();
+    expect(config.models?.['other/model']).toBeDefined();
+    expect(config.defaultModel).toBeUndefined();
+  });
+
+  it('leaves defaultModel intact when it belongs to another provider', () => {
+    const config: ManagedKimiConfigShape = {
+      providers: {
+        'moonshot-cn': { type: 'kimi', baseUrl: 'https://api.moonshot.cn/v1', apiKey: 'sk-test' },
+      },
+      models: {
+        'moonshot-cn/kimi-k2': { provider: 'moonshot-cn', model: 'kimi-k2', maxContextSize: 256000 },
+      },
+      defaultModel: 'other/model',
+    };
+
+    removeOpenPlatformConfig(config, 'moonshot-cn');
+
+    expect(config.defaultModel).toBe('other/model');
+  });
+});
diff --git a/packages/oauth/test/refresh-threshold.test.ts b/packages/oauth/test/refresh-threshold.test.ts
new file mode 100644
index 000000000..7f2bbb9fc
--- /dev/null
+++ b/packages/oauth/test/refresh-threshold.test.ts
@@ -0,0 +1,30 @@
+/**
+ * defaultRefreshThreshold — three boundary cases.
+ *
+ * Formula (oauth-manager.ts:39-44):
+ *   threshold = max(MIN_REFRESH_THRESHOLD_SECONDS, expiresIn * 0.5)
+ * where MIN_REFRESH_THRESHOLD_SECONDS = 300 and 0 / negative expiresIn
+ * fall back to MIN (the implementation short-circuits on `> 0`).
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { defaultRefreshThreshold } from '../src/oauth-manager';
+
+describe('defaultRefreshThreshold — boundary cases', () => {
+  it('returns expiresIn * 0.5 when ratio exceeds the 300s minimum (expiresIn=1800 → 900)', () => {
+    // 1800 * 0.5 = 900 > 300.
+    expect(defaultRefreshThreshold(1800)).toBe(900);
+  });
+
+  it('clamps to the 300s minimum when expiresIn * 0.5 falls below (expiresIn=500 → 300)', () => {
+    // 500 * 0.5 = 250 < 300, so the floor wins.
+    expect(defaultRefreshThreshold(500)).toBe(300);
+  });
+
+  it('falls back to the 300s minimum when expiresIn is 0 (expiresIn=0 → 300)', () => {
+    // A pathological token with no lifetime still refreshes on a fixed
+    // cadence; never produces a zero threshold.
+    expect(defaultRefreshThreshold(0)).toBe(300);
+  });
+});
diff --git a/packages/oauth/test/storage.test.ts b/packages/oauth/test/storage.test.ts
new file mode 100644
index 000000000..7cdba1599
--- /dev/null
+++ b/packages/oauth/test/storage.test.ts
@@ -0,0 +1,214 @@
+/**
+ * FileTokenStorage tests — round-trip persistence + permission checks.
+ *
+ * Scope guards: tokens never leak to process.env or other files; permission
+ * 0600 is enforced; corrupted files return undefined rather than throwing.
+ */
+
+import { chmodSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { FileTokenStorage } from '../src/storage';
+import type { TokenInfo } from '../src/types';
+
+function makeTmpDir(): string {
+  const dir = join(
+    tmpdir(),
+    `kimi-storage-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function sampleToken(overrides: Partial<TokenInfo> = {}): TokenInfo {
+  return {
+    accessToken: 'at-abc',
+    refreshToken: 'rt-xyz',
+    expiresAt: 1_700_000_000,
+    scope: 'read write',
+    tokenType: 'Bearer',
+    expiresIn: 3600,
+    ...overrides,
+  };
+}
+
+describe('FileTokenStorage', () => {
+  let dir: string;
+  let storage: FileTokenStorage;
+
+  beforeEach(() => {
+    dir = makeTmpDir();
+    storage = new FileTokenStorage(dir);
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('returns undefined when no token exists', async () => {
+    expect(await storage.load('kimi-code')).toBeUndefined();
+  });
+
+  it('round-trips a token via save/load', async () => {
+    const token = sampleToken();
+    await storage.save('kimi-code', token);
+    const loaded = await storage.load('kimi-code');
+    expect(loaded).toEqual(token);
+  });
+
+  it('persists tokens in snake_case JSON (Python-compatible)', async () => {
+    const token = sampleToken();
+    await storage.save('kimi-code', token);
+    const raw = readFileSync(join(dir, 'kimi-code.json'), 'utf-8');
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    expect(parsed['access_token']).toBe('at-abc');
+    expect(parsed['refresh_token']).toBe('rt-xyz');
+    expect(parsed['expires_at']).toBe(1_700_000_000);
+    expect(parsed['token_type']).toBe('Bearer');
+    expect(parsed['expires_in']).toBe(3600);
+    expect(parsed['accessToken']).toBeUndefined();
+  });
+
+  it('writes the credentials file with mode 0600', async () => {
+    await storage.save('kimi-code', sampleToken());
+    const stat = statSync(join(dir, 'kimi-code.json'));
+    // eslint-disable-next-line no-bitwise
+    expect(stat.mode & 0o777).toBe(0o600);
+  });
+
+  it('remove() deletes the file; load() then returns undefined', async () => {
+    await storage.save('kimi-code', sampleToken());
+    await storage.remove('kimi-code');
+    expect(await storage.load('kimi-code')).toBeUndefined();
+  });
+
+  it('remove() is idempotent when file is absent', async () => {
+    await expect(storage.remove('never-existed')).resolves.toBeUndefined();
+  });
+
+  it('save() overwrites an existing token atomically', async () => {
+    await storage.save('kimi-code', sampleToken({ accessToken: 'first' }));
+    await storage.save('kimi-code', sampleToken({ accessToken: 'second' }));
+    const loaded = await storage.load('kimi-code');
+    expect(loaded?.accessToken).toBe('second');
+  });
+
+  it('load() returns undefined on corrupt JSON (does not throw)', async () => {
+    const file = join(dir, 'kimi-code.json');
+    writeFileSync(file, '{ not json', 'utf-8');
+    chmodSync(file, 0o600);
+    expect(await storage.load('kimi-code')).toBeUndefined();
+  });
+
+  it('load() returns undefined on malformed payload (not a dict)', async () => {
+    const file = join(dir, 'kimi-code.json');
+    writeFileSync(file, '["array", "instead"]', 'utf-8');
+    chmodSync(file, 0o600);
+    expect(await storage.load('kimi-code')).toBeUndefined();
+  });
+
+  it('load() tolerates missing numeric fields by defaulting to 0', async () => {
+    const file = join(dir, 'kimi-code.json');
+    writeFileSync(file, JSON.stringify({ access_token: 'a', refresh_token: 'r' }), 'utf-8');
+    chmodSync(file, 0o600);
+    const token = await storage.load('kimi-code');
+    expect(token?.expiresAt).toBe(0);
+    expect(token?.expiresIn).toBe(0);
+  });
+
+  it('list() returns all stored token names', async () => {
+    await storage.save('kimi-code', sampleToken());
+    await storage.save('other-provider', sampleToken());
+    const names = await storage.list();
+    expect(names.toSorted()).toEqual(['kimi-code', 'other-provider']);
+  });
+
+  it('list() ignores non-JSON files in the credentials dir', async () => {
+    await storage.save('kimi-code', sampleToken());
+    writeFileSync(join(dir, 'kimi-code.lock'), 'lock', 'utf-8');
+    writeFileSync(join(dir, 'readme.txt'), 'readme', 'utf-8');
+    const names = await storage.list();
+    expect(names).toEqual(['kimi-code']);
+  });
+
+  it('creates the credentials dir with mode 0700 if missing', async () => {
+    const freshDir = join(dir, 'nested', 'sub');
+    const s = new FileTokenStorage(freshDir);
+    await s.save('kimi-code', sampleToken());
+    const stat = statSync(freshDir);
+    // eslint-disable-next-line no-bitwise
+    expect(stat.mode & 0o777).toBe(0o700);
+  });
+
+  it('refuses path-traversal names on save (B1)', async () => {
+    await expect(storage.save('../../etc/passwd', sampleToken())).rejects.toThrow(
+      /Invalid token name/,
+    );
+  });
+
+  it('refuses path-traversal names on load', async () => {
+    await expect(storage.load('../etc/passwd')).rejects.toThrow(/Invalid token name/);
+  });
+
+  it('refuses path-traversal names on remove', async () => {
+    await expect(storage.remove('../etc/passwd')).rejects.toThrow(/Invalid token name/);
+  });
+
+  it('refuses leading-dot names (hidden file abuse)', async () => {
+    await expect(storage.save('.hidden', sampleToken())).rejects.toThrow(/Invalid token name/);
+  });
+
+  it('refuses empty name', async () => {
+    await expect(storage.save('', sampleToken())).rejects.toThrow(/Invalid token name/);
+  });
+
+  // ── atomic save leaves no .tmp sibling ────────────────────────────────
+
+  it('save() leaves no *.tmp.* sibling once the rename completes', async () => {
+    // Atomic save must clean up its temp artefact after rename. Uses
+    // `target.tmp.<pid>.<rand>` then renameSync; this test asserts the
+    // resulting directory contains only the canonical file.
+    await storage.save('kimi-code', sampleToken());
+    const { readdirSync } = await import('node:fs');
+    const entries = readdirSync(dir);
+    const tmps = entries.filter((name) => name.startsWith('kimi-code.json.tmp.'));
+    expect(tmps).toEqual([]);
+    expect(entries).toContain('kimi-code.json');
+  });
+
+  it('save() + load() preserves expires_in and expires_at roundtrip', async () => {
+    // The wire format records both `expires_at` and `expires_in`; the
+    // load path must restore both fields without loss.
+    const token = sampleToken({ expiresAt: 1_800_000_000, expiresIn: 7200 });
+    await storage.save('kimi-code', token);
+    const loaded = await storage.load('kimi-code');
+    expect(loaded?.expiresAt).toBe(1_800_000_000);
+    expect(loaded?.expiresIn).toBe(7200);
+  });
+
+  it('load() of a wire payload missing scope/token_type uses safe defaults', async () => {
+    // A legacy file written without the optional `scope` / `token_type`
+    // fields must still load; the defaults come from `tokenFromWire`.
+    const file = join(dir, 'kimi-code.json');
+    writeFileSync(
+      file,
+      JSON.stringify({
+        access_token: 'a',
+        refresh_token: 'r',
+        expires_at: 1,
+        expires_in: 60,
+      }),
+      'utf-8',
+    );
+    chmodSync(file, 0o600);
+    const loaded = await storage.load('kimi-code');
+    expect(loaded?.accessToken).toBe('a');
+    expect(loaded?.refreshToken).toBe('r');
+    // Defaults should be strings (empty / 'Bearer'), never undefined.
+    expect(typeof loaded?.scope).toBe('string');
+    expect(typeof loaded?.tokenType).toBe('string');
+  });
+});
diff --git a/packages/oauth/test/toolkit.test.ts b/packages/oauth/test/toolkit.test.ts
new file mode 100644
index 000000000..9a3ff1ca2
--- /dev/null
+++ b/packages/oauth/test/toolkit.test.ts
@@ -0,0 +1,307 @@
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  KIMI_CODE_PROVIDER_NAME,
+  KimiOAuthToolkit,
+  resolveKimiTokenStorageName,
+  type TokenInfo,
+  type TokenStorage,
+} from '../src';
+
+class MemoryTokenStorage implements TokenStorage {
+  readonly tokens = new Map<string, TokenInfo>();
+
+  async load(name: string): Promise<TokenInfo | undefined> {
+    return this.tokens.get(name);
+  }
+
+  async save(name: string, token: TokenInfo): Promise<void> {
+    this.tokens.set(name, token);
+  }
+
+  async remove(name: string): Promise<void> {
+    this.tokens.delete(name);
+  }
+
+  async list(): Promise<string[]> {
+    return [...this.tokens.keys()];
+  }
+}
+
+function token(accessToken: string): TokenInfo {
+  return {
+    accessToken,
+    refreshToken: `refresh-${accessToken}`,
+    expiresAt: 10_000,
+    scope: '',
+    tokenType: 'Bearer',
+    expiresIn: 3600,
+  };
+}
+
+const TEST_IDENTITY = {
+  userAgentProduct: 'kimi-code-cli',
+  version: '0.0.0-test',
+} as const;
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('resolveKimiTokenStorageName', () => {
+  it('maps config oauth keys to the file storage token name', () => {
+    expect(
+      resolveKimiTokenStorageName({
+        providerName: KIMI_CODE_PROVIDER_NAME,
+        oauthKey: 'oauth/kimi-code',
+      }),
+    ).toBe('kimi-code');
+    expect(resolveKimiTokenStorageName({ oauthKey: 'kimi-code' })).toBe('kimi-code');
+  });
+
+  it('rejects unsupported providers and unsafe token keys', () => {
+    expect(() =>
+      resolveKimiTokenStorageName({
+        providerName: 'custom',
+        oauthKey: 'kimi-code',
+      }),
+    ).toThrow(/No OAuth manager/);
+    expect(() => resolveKimiTokenStorageName({ oauthKey: '../kimi-code' })).toThrow(/Invalid/);
+  });
+});
+
+describe('KimiOAuthToolkit', () => {
+  it('can be constructed without host identity', async () => {
+    const storage = new MemoryTokenStorage();
+    storage.tokens.set('kimi-code', token('access-1'));
+    const toolkit = new KimiOAuthToolkit({
+      homeDir: join('/tmp', 'kimi-oauth-toolkit-test'),
+      storage,
+      now: () => 100,
+    });
+
+    await expect(toolkit.tokenProvider().getAccessToken()).resolves.toBe('access-1');
+  });
+
+  it('reports status and exposes a bearer token provider', async () => {
+    const storage = new MemoryTokenStorage();
+    storage.tokens.set('kimi-code', token('access-1'));
+    const toolkit = new KimiOAuthToolkit({
+      homeDir: join('/tmp', 'kimi-oauth-toolkit-test'),
+      identity: TEST_IDENTITY,
+      storage,
+      now: () => 100,
+    });
+
+    await expect(toolkit.status()).resolves.toEqual({
+      providers: [{ providerName: KIMI_CODE_PROVIDER_NAME, hasToken: true }],
+    });
+    await expect(toolkit.tokenProvider().getAccessToken()).resolves.toBe('access-1');
+  });
+
+  it('resolves bearer token providers using the configured oauth key', async () => {
+    const storage = new MemoryTokenStorage();
+    storage.tokens.set('custom-kimi-code', token('custom-access'));
+    const toolkit = new KimiOAuthToolkit({
+      homeDir: join('/tmp', 'kimi-oauth-toolkit-test'),
+      identity: TEST_IDENTITY,
+      storage,
+      now: () => 100,
+    });
+
+    await expect(
+      toolkit
+        .tokenProvider(KIMI_CODE_PROVIDER_NAME, { key: 'oauth/custom-kimi-code' })
+        .getAccessToken(),
+    ).resolves.toBe('custom-access');
+  });
+
+  it('returns the cached access token without refreshing it', async () => {
+    const storage = new MemoryTokenStorage();
+    storage.tokens.set('kimi-code', {
+      ...token('cached-access'),
+      expiresAt: 1,
+    });
+    const toolkit = new KimiOAuthToolkit({
+      homeDir: join('/tmp', 'kimi-oauth-toolkit-test'),
+      identity: TEST_IDENTITY,
+      storage,
+      now: () => 10_000,
+    });
+
+    await expect(toolkit.getCachedAccessToken()).resolves.toBe('cached-access');
+  });
+
+  it('resolves cached access tokens using the configured oauth key', async () => {
+    const storage = new MemoryTokenStorage();
+    storage.tokens.set('custom-kimi-code', token('custom-cached-access'));
+    const toolkit = new KimiOAuthToolkit({
+      homeDir: join('/tmp', 'kimi-oauth-toolkit-test'),
+      identity: TEST_IDENTITY,
+      storage,
+      now: () => 100,
+    });
+
+    await expect(
+      toolkit.getCachedAccessToken(KIMI_CODE_PROVIDER_NAME, { key: 'oauth/custom-kimi-code' }),
+    ).resolves.toBe('custom-cached-access');
+  });
+
+  it('returns undefined when no cached access token exists', async () => {
+    const toolkit = new KimiOAuthToolkit({
+      homeDir: join('/tmp', 'kimi-oauth-toolkit-test'),
+      identity: TEST_IDENTITY,
+      storage: new MemoryTokenStorage(),
+      now: () => 100,
+    });
+
+    await expect(toolkit.getCachedAccessToken()).resolves.toBeUndefined();
+  });
+
+  it('provisions managed config after login when an adapter is configured', async () => {
+    const storage = new MemoryTokenStorage();
+    const write = vi.fn();
+    const fetchImpl = vi.fn(
+      async () =>
+        new Response(
+          JSON.stringify({
+            data: [
+              {
+                id: 'kimi-for-coding',
+                context_length: 262144,
+                supports_reasoning: true,
+              },
+            ],
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        ),
+    ) as unknown as typeof fetch;
+    const config = { providers: {} };
+    const toolkit = new KimiOAuthToolkit({
+      homeDir: join('/tmp', 'kimi-oauth-toolkit-test'),
+      identity: TEST_IDENTITY,
+      storage,
+      now: () => 100,
+      fetchImpl,
+      configAdapter: {
+        read: () => config,
+        write,
+        apply: (target, input) => {
+          target.providers[KIMI_CODE_PROVIDER_NAME] = {
+            type: 'kimi',
+            apiKey: '',
+          };
+          return {
+            defaultModel: `kimi-code/${input.models[0]?.id ?? 'unknown'}`,
+            defaultThinking: true,
+          };
+        },
+      },
+    });
+
+    storage.tokens.set('kimi-code', token('access-1'));
+    await expect(toolkit.login()).resolves.toMatchObject({
+      providerName: KIMI_CODE_PROVIDER_NAME,
+      ok: true,
+      provision: {
+        defaultModel: 'kimi-code/kimi-for-coding',
+      },
+    });
+    expect(write).toHaveBeenCalledWith(config);
+  });
+
+  it('starts a new device flow when the stored refresh token is invalid', async () => {
+    const storage = new MemoryTokenStorage();
+    storage.tokens.set('kimi-code', {
+      ...token('stale-access'),
+      refreshToken: 'revoked-refresh',
+      expiresAt: 101,
+    });
+    const onDeviceCode = vi.fn();
+    const fetchImpl = vi.fn(async (_input: unknown, init?: RequestInit) => {
+      if (typeof init?.body !== 'string') throw new TypeError('expected form body');
+      const body = new URLSearchParams(init.body);
+      if (body.get('grant_type') === 'refresh_token') {
+        return new Response(
+          JSON.stringify({
+            error: 'invalid_grant',
+            error_description: 'The provided authorization grant is invalid',
+          }),
+          { status: 400, headers: { 'Content-Type': 'application/json' } },
+        );
+      }
+      if (body.get('grant_type') === 'urn:ietf:params:oauth:grant-type:device_code') {
+        return new Response(
+          JSON.stringify({
+            access_token: 'fresh-access',
+            refresh_token: 'fresh-refresh',
+            expires_in: 3600,
+            scope: '',
+            token_type: 'Bearer',
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        );
+      }
+      return new Response(
+        JSON.stringify({
+          user_code: 'WDJB-MJHT',
+          device_code: 'device-code',
+          verification_uri: 'https://auth.test/verify',
+          verification_uri_complete: 'https://auth.test/verify?user_code=WDJB-MJHT',
+          expires_in: 600,
+          interval: 1,
+        }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      );
+    }) as unknown as typeof fetch;
+    vi.stubGlobal('fetch', fetchImpl);
+    const toolkit = new KimiOAuthToolkit({
+      homeDir: join('/tmp', 'kimi-oauth-toolkit-test'),
+      identity: TEST_IDENTITY,
+      storage,
+      now: () => 100,
+      flowConfig: {
+        name: 'kimi-code',
+        oauthHost: 'https://auth.test',
+        clientId: 'test-client-id',
+      },
+    });
+
+    await expect(toolkit.login(undefined, { onDeviceCode })).resolves.toMatchObject({
+      providerName: KIMI_CODE_PROVIDER_NAME,
+      ok: true,
+    });
+    expect(onDeviceCode).toHaveBeenCalledTimes(1);
+    expect((await storage.load('kimi-code'))?.accessToken).toBe('fresh-access');
+  });
+
+  it('removes managed config on logout when an adapter supports cleanup', async () => {
+    const storage = new MemoryTokenStorage();
+    storage.tokens.set('kimi-code', token('access-1'));
+    const config = { providers: { [KIMI_CODE_PROVIDER_NAME]: { type: 'kimi' } } };
+    const write = vi.fn();
+    const remove = vi.fn();
+    const toolkit = new KimiOAuthToolkit({
+      homeDir: join('/tmp', 'kimi-oauth-toolkit-test'),
+      identity: TEST_IDENTITY,
+      storage,
+      now: () => 100,
+      configAdapter: {
+        read: () => config,
+        write,
+        apply: () => ({ defaultModel: 'kimi-code/kimi-for-coding', defaultThinking: true }),
+        remove,
+      },
+    });
+
+    await expect(toolkit.logout()).resolves.toMatchObject({
+      providerName: KIMI_CODE_PROVIDER_NAME,
+      ok: true,
+    });
+    expect(remove).toHaveBeenCalledWith(config);
+    expect(write).toHaveBeenCalledWith(config);
+    await expect(storage.load('kimi-code')).resolves.toBeUndefined();
+  });
+});
diff --git a/packages/oauth/tsconfig.json b/packages/oauth/tsconfig.json
new file mode 100644
index 000000000..b999c0575
--- /dev/null
+++ b/packages/oauth/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src", "test", "examples"]
+}
diff --git a/packages/oauth/tsdown.config.ts b/packages/oauth/tsdown.config.ts
new file mode 100644
index 000000000..cb99d9ffb
--- /dev/null
+++ b/packages/oauth/tsdown.config.ts
@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['./src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  outDir: 'dist',
+  clean: true,
+});
diff --git a/packages/oauth/vitest.config.ts b/packages/oauth/vitest.config.ts
new file mode 100644
index 000000000..4f5ef4273
--- /dev/null
+++ b/packages/oauth/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    name: 'kimi-oauth',
+    include: ['test/**/*.test.ts'],
+  },
+});
diff --git a/packages/telemetry/README.md b/packages/telemetry/README.md
new file mode 100644
index 000000000..414dfda9a
--- /dev/null
+++ b/packages/telemetry/README.md
@@ -0,0 +1,11 @@
+# @moonshot-ai/kimi-telemetry
+
+Shared telemetry infrastructure for Kimi Code.
+
+Part of the [Kimi Code](https://github.com/MoonshotAI/kimi-code) monorepo.
+
+See the main repository for documentation, issues, and contribution guidelines.
+
+## License
+
+MIT
diff --git a/packages/telemetry/package.json b/packages/telemetry/package.json
new file mode 100644
index 000000000..26fbc1a98
--- /dev/null
+++ b/packages/telemetry/package.json
@@ -0,0 +1,46 @@
+{
+  "name": "@moonshot-ai/kimi-telemetry",
+  "version": "0.1.1",
+  "private": true,
+  "description": "Shared telemetry infrastructure for Kimi Code",
+  "license": "MIT",
+  "author": "Moonshot AI",
+  "homepage": "https://github.com/MoonshotAI/kimi-code/tree/main/packages/telemetry#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MoonshotAI/kimi-code.git",
+    "directory": "packages/telemetry"
+  },
+  "bugs": {
+    "url": "https://github.com/MoonshotAI/kimi-code/issues"
+  },
+  "keywords": [
+    "kimi",
+    "telemetry",
+    "analytics",
+    "events",
+    "client"
+  ],
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "imports": {
+    "#/*": [
+      "./src/*.ts",
+      "./src/*/index.ts"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  }
+}
diff --git a/packages/telemetry/src/bootstrap.ts b/packages/telemetry/src/bootstrap.ts
new file mode 100644
index 000000000..041e650d4
--- /dev/null
+++ b/packages/telemetry/src/bootstrap.ts
@@ -0,0 +1,69 @@
+import { getDefaultTelemetryClient } from './client';
+import { EventSink } from './sink';
+import { AsyncTransport } from './transport';
+
+export const TELEMETRY_DISABLE_ENV = 'KIMI_DISABLE_TELEMETRY';
+
+const TRUE_ENV_VALUES = new Set(['1', 'true', 't', 'yes', 'y']);
+
+export interface TelemetryBootstrapOptions {
+  readonly enabled?: boolean;
+  readonly homeDir: string;
+  readonly deviceId: string;
+  readonly sessionId?: string;
+  readonly appName: string;
+  readonly version: string;
+  readonly uiMode?: string;
+  readonly model?: string;
+  readonly buildSha?: string;
+  readonly terminal?: string;
+  readonly locale?: string;
+  readonly getAccessToken?: () => string | null | Promise<string | null>;
+}
+
+export function isTelemetryDisabledByEnv(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = env[TELEMETRY_DISABLE_ENV];
+  return value !== undefined && TRUE_ENV_VALUES.has(value.trim().toLowerCase());
+}
+
+export function shouldEnableTelemetry(
+  input: { readonly enabled?: boolean; readonly env?: NodeJS.ProcessEnv } = {},
+): boolean {
+  return input.enabled !== false && !isTelemetryDisabledByEnv(input.env ?? process.env);
+}
+
+export function initializeTelemetry(options: TelemetryBootstrapOptions): void {
+  const client = getDefaultTelemetryClient();
+  if (!shouldEnableTelemetry({ enabled: options.enabled })) {
+    client.disable();
+    return;
+  }
+
+  client.enable();
+  client.setContext({
+    deviceId: options.deviceId,
+    sessionId: options.sessionId,
+  });
+
+  const transport = new AsyncTransport({
+    homeDir: options.homeDir,
+    deviceId: options.deviceId,
+    getAccessToken: options.getAccessToken,
+  });
+  const sink = new EventSink({
+    transport,
+    context: {
+      appName: options.appName,
+      version: options.version,
+      uiMode: options.uiMode,
+      model: options.model,
+      buildSha: options.buildSha,
+      terminal: options.terminal,
+      locale: options.locale,
+    },
+  });
+
+  client.attachSink(sink);
+  sink.startPeriodicFlush();
+  void sink.retryDiskEvents().catch(() => {});
+}
diff --git a/packages/telemetry/src/client.ts b/packages/telemetry/src/client.ts
new file mode 100644
index 000000000..d4904e8f2
--- /dev/null
+++ b/packages/telemetry/src/client.ts
@@ -0,0 +1,275 @@
+import { randomUUID } from 'node:crypto';
+
+import type { EventSink } from './sink';
+import type { TelemetryEvent, TelemetryProperties } from './types';
+import { isTelemetryPrimitive } from './types';
+
+export interface TelemetryContextIds {
+  readonly deviceId?: string | null;
+  readonly sessionId?: string | null;
+}
+
+export interface TelemetryShutdownOptions {
+  readonly timeoutMs?: number;
+}
+
+const MAX_QUEUE_SIZE = 1000;
+
+interface PendingTelemetryEvent extends TelemetryEvent {
+  readonly contextOverrides?: {
+    readonly deviceId?: boolean;
+    readonly sessionId?: boolean;
+  };
+}
+
+export class TelemetryClient {
+  private queue: PendingTelemetryEvent[] = [];
+  private sink: EventSink | null = null;
+  private deviceId: string | null = null;
+  private sessionId: string | null = null;
+  private disabled = false;
+
+  setContext(input: TelemetryContextIds): void {
+    if (input.deviceId !== undefined) this.deviceId = input.deviceId;
+    if (input.sessionId !== undefined) this.sessionId = input.sessionId;
+  }
+
+  withContext(input: TelemetryContextIds): TelemetryClient {
+    return new ScopedTelemetryClient(this, input);
+  }
+
+  attachSink(sink: EventSink): void {
+    if (this.sink !== null && this.sink !== sink) {
+      this.sink.stopPeriodicFlush();
+      this.sink.flushSync();
+    }
+    this.sink = sink;
+    for (const event of this.queue) {
+      const record = toTelemetryEvent(event);
+      if (record.device_id === null && event.contextOverrides?.deviceId !== true) {
+        record.device_id = this.deviceId;
+      }
+      if (record.session_id === null && event.contextOverrides?.sessionId !== true) {
+        record.session_id = this.sessionId;
+      }
+      sink.accept(record);
+    }
+    this.queue = [];
+  }
+
+  disable(): void {
+    this.disabled = true;
+    this.queue = [];
+    if (this.sink !== null) {
+      this.sink.stopPeriodicFlush();
+      this.sink.clearBuffer();
+      this.sink = null;
+    }
+  }
+
+  enable(): void {
+    this.disabled = false;
+  }
+
+  track(event: string, properties: TelemetryProperties = {}): void {
+    this.trackWithContext(event, properties, {});
+  }
+
+  trackWithContext(
+    event: string,
+    properties: TelemetryProperties = {},
+    context: TelemetryContextIds,
+  ): void {
+    if (this.disabled) return;
+    const record: PendingTelemetryEvent = {
+      event_id: randomUUID().replaceAll('-', ''),
+      device_id: context.deviceId === undefined ? this.deviceId : context.deviceId,
+      session_id: context.sessionId === undefined ? this.sessionId : context.sessionId,
+      event,
+      timestamp: Date.now() / 1000,
+      properties: sanitizeProperties(properties),
+      contextOverrides: {
+        deviceId: context.deviceId !== undefined,
+        sessionId: context.sessionId !== undefined,
+      },
+    };
+    if (this.sink !== null) {
+      this.sink.accept(toTelemetryEvent(record));
+      return;
+    }
+    this.queue.push(record);
+    if (this.queue.length > MAX_QUEUE_SIZE) {
+      this.queue = this.queue.slice(this.queue.length - MAX_QUEUE_SIZE);
+    }
+  }
+
+  getSink(): EventSink | null {
+    return this.sink;
+  }
+
+  async flush(signal?: AbortSignal): Promise<void> {
+    await this.sink?.flush(signal);
+  }
+
+  flushSync(): void {
+    this.sink?.flushSync();
+  }
+
+  async shutdown(options: TelemetryShutdownOptions = {}): Promise<void> {
+    const sink = this.sink;
+    if (sink === null) return;
+    sink.stopPeriodicFlush();
+    if (options.timeoutMs === undefined) {
+      await sink.flush();
+      return;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+      controller.abort();
+    }, options.timeoutMs);
+    timer.unref?.();
+    try {
+      await sink.flush(controller.signal);
+    } catch {
+      sink.flushSync();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  resetForTests(): void {
+    this.sink?.stopPeriodicFlush();
+    this.queue = [];
+    this.sink = null;
+    this.deviceId = null;
+    this.sessionId = null;
+    this.disabled = false;
+  }
+}
+
+class ScopedTelemetryClient extends TelemetryClient {
+  constructor(
+    private readonly parent: TelemetryClient,
+    private readonly context: TelemetryContextIds,
+  ) {
+    super();
+  }
+
+  override setContext(input: TelemetryContextIds): void {
+    this.parent.setContext(input);
+  }
+
+  override withContext(input: TelemetryContextIds): TelemetryClient {
+    return new ScopedTelemetryClient(this.parent, mergeContext(this.context, input));
+  }
+
+  override attachSink(sink: EventSink): void {
+    this.parent.attachSink(sink);
+  }
+
+  override disable(): void {
+    this.parent.disable();
+  }
+
+  override enable(): void {
+    this.parent.enable();
+  }
+
+  override track(event: string, properties: TelemetryProperties = {}): void {
+    this.parent.trackWithContext(event, properties, this.context);
+  }
+
+  override getSink(): EventSink | null {
+    return this.parent.getSink();
+  }
+
+  override async flush(signal?: AbortSignal): Promise<void> {
+    await this.parent.flush(signal);
+  }
+
+  override flushSync(): void {
+    this.parent.flushSync();
+  }
+
+  override async shutdown(options: TelemetryShutdownOptions = {}): Promise<void> {
+    await this.parent.shutdown(options);
+  }
+
+  override resetForTests(): void {
+    this.parent.resetForTests();
+  }
+}
+
+const defaultClient = new TelemetryClient();
+
+export function setContext(input: TelemetryContextIds): void {
+  defaultClient.setContext(input);
+}
+
+export function attachSink(sink: EventSink): void {
+  defaultClient.attachSink(sink);
+}
+
+export function disable(): void {
+  defaultClient.disable();
+}
+
+export function enable(): void {
+  defaultClient.enable();
+}
+
+export function track(event: string, properties: TelemetryProperties = {}): void {
+  defaultClient.track(event, properties);
+}
+
+export function withContext(input: TelemetryContextIds): TelemetryClient {
+  return defaultClient.withContext(input);
+}
+
+export function getSink(): EventSink | null {
+  return defaultClient.getSink();
+}
+
+export function flushSync(): void {
+  defaultClient.flushSync();
+}
+
+export async function shutdown(options: TelemetryShutdownOptions = {}): Promise<void> {
+  await defaultClient.shutdown(options);
+}
+
+export function getDefaultTelemetryClient(): TelemetryClient {
+  return defaultClient;
+}
+
+export function resetDefaultTelemetryClientForTests(): void {
+  defaultClient.resetForTests();
+}
+
+function mergeContext(base: TelemetryContextIds, patch: TelemetryContextIds): TelemetryContextIds {
+  return {
+    deviceId: patch.deviceId === undefined ? base.deviceId : patch.deviceId,
+    sessionId: patch.sessionId === undefined ? base.sessionId : patch.sessionId,
+  };
+}
+
+function toTelemetryEvent(event: PendingTelemetryEvent): TelemetryEvent {
+  return {
+    event_id: event.event_id,
+    device_id: event.device_id,
+    session_id: event.session_id,
+    event: event.event,
+    timestamp: event.timestamp,
+    properties: event.properties,
+  };
+}
+
+function sanitizeProperties(input: TelemetryProperties): TelemetryProperties {
+  const out: TelemetryProperties = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (isTelemetryPrimitive(value)) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
diff --git a/packages/telemetry/src/crash.ts b/packages/telemetry/src/crash.ts
new file mode 100644
index 000000000..4c501de2d
--- /dev/null
+++ b/packages/telemetry/src/crash.ts
@@ -0,0 +1,64 @@
+import { getDefaultTelemetryClient, type TelemetryClient } from './client';
+
+export type CrashPhase = 'startup' | 'runtime' | 'shutdown';
+
+let phase: CrashPhase = 'startup';
+let installed = false;
+let installedUncaughtHandler:
+  | ((error: Error, origin: NodeJS.UncaughtExceptionOrigin) => void)
+  | null = null;
+
+export function setCrashPhase(nextPhase: CrashPhase): void {
+  phase = nextPhase;
+}
+
+export function installCrashHandlers(): () => void {
+  return installCrashHandlersForClient(getDefaultTelemetryClient());
+}
+
+export function installCrashHandlersForClient(client: TelemetryClient): () => void {
+  if (installed && installedUncaughtHandler !== null) {
+    return () => {
+      uninstallCrashHandlers();
+    };
+  }
+  const trackCrash = (errorType: string, source: string) => {
+    try {
+      client.track('crash', {
+        error_type: errorType,
+        where: phase,
+        source,
+      });
+      client.flushSync();
+    } catch {
+      // Crash telemetry must never mask the original exception.
+    }
+  };
+  installedUncaughtHandler = (error, origin) => {
+    if (isAbortError(error)) return;
+    trackCrash(error.name || error.constructor.name, origin);
+  };
+  process.on('uncaughtExceptionMonitor', installedUncaughtHandler);
+  installed = true;
+  return () => {
+    uninstallCrashHandlers();
+  };
+}
+
+export function uninstallCrashHandlers(): void {
+  if (!installed) return;
+  if (installedUncaughtHandler !== null) {
+    process.off('uncaughtExceptionMonitor', installedUncaughtHandler);
+  }
+  installedUncaughtHandler = null;
+  installed = false;
+}
+
+function isAbortError(reason: unknown): boolean {
+  return (
+    typeof reason === 'object' &&
+    reason !== null &&
+    'name' in reason &&
+    reason.name === 'AbortError'
+  );
+}
diff --git a/packages/telemetry/src/index.ts b/packages/telemetry/src/index.ts
new file mode 100644
index 000000000..1f03b1a65
--- /dev/null
+++ b/packages/telemetry/src/index.ts
@@ -0,0 +1,42 @@
+import {
+  flushSync,
+  setContext,
+  shutdown,
+  track as trackEvent,
+  withContext,
+} from './client';
+import type { TelemetryProperties as TelemetryPropertiesType } from './types';
+import type { TelemetryContextIds, TelemetryClient } from './client';
+
+export function track(event: string, properties: TelemetryPropertiesType = {}): void {
+  trackEvent(event, properties);
+}
+
+export function setTelemetryContext(patch: TelemetryContextIds): void {
+  setContext(patch);
+}
+
+export function withTelemetryContext(patch: TelemetryContextIds): TelemetryClient {
+  return withContext(patch);
+}
+
+export function flushTelemetrySync(): void {
+  flushSync();
+}
+
+export async function shutdownTelemetry(
+  options: { readonly timeoutMs?: number } = {},
+): Promise<void> {
+  await shutdown(options);
+}
+
+export { initializeTelemetry } from './bootstrap';
+export type { TelemetryBootstrapOptions } from './bootstrap';
+
+export { installCrashHandlers, setCrashPhase } from './crash';
+export type { CrashPhase } from './crash';
+
+export { normalizeRemote } from './remote';
+
+export type { TelemetryPrimitive, TelemetryProperties } from './types';
+export type { TelemetryClient, TelemetryContextIds } from './client';
diff --git a/packages/telemetry/src/remote.ts b/packages/telemetry/src/remote.ts
new file mode 100644
index 000000000..024efaf33
--- /dev/null
+++ b/packages/telemetry/src/remote.ts
@@ -0,0 +1,42 @@
+export function normalizeRemote(url: string): string {
+  const trimmed = url.trim();
+  if (trimmed.length === 0) return '';
+
+  if (!trimmed.includes('://')) {
+    const scpLike = /^(?:[^@\s]+@)?([^:\s]+):(.+)$/.exec(trimmed);
+    if (scpLike !== null) {
+      return joinRemoteParts(scpLike[1], undefined, scpLike[2]);
+    }
+    return stripGitSuffix(trimmed);
+  }
+
+  try {
+    const parsed = new URL(trimmed);
+    if (parsed.hostname.length === 0) return stripGitSuffix(trimmed);
+    return joinRemoteParts(parsed.hostname, parsed.port, parsed.pathname);
+  } catch {
+    return stripGitSuffix(trimmed);
+  }
+}
+
+function joinRemoteParts(
+  host: string | undefined,
+  port: string | undefined,
+  path: string | undefined,
+): string {
+  const normalizedHost = host?.trim() ?? '';
+  const normalizedPort = port?.trim() ?? '';
+  const normalizedPath = stripGitSuffix(path ?? '');
+  const parts = [normalizedHost];
+  if (normalizedPort.length > 0) parts.push(normalizedPort);
+  if (normalizedPath.length > 0) parts.push(normalizedPath);
+  return parts.join('/');
+}
+
+function stripGitSuffix(value: string): string {
+  let normalized = value.trim().replace(/^\/+/, '').replace(/\/+$/, '');
+  if (normalized.endsWith('.git')) {
+    normalized = normalized.slice(0, -4);
+  }
+  return normalized;
+}
diff --git a/packages/telemetry/src/sink.ts b/packages/telemetry/src/sink.ts
new file mode 100644
index 000000000..ae51be6c1
--- /dev/null
+++ b/packages/telemetry/src/sink.ts
@@ -0,0 +1,127 @@
+import { arch, platform, release } from 'node:os';
+
+import type {
+  EnrichedTelemetryEvent,
+  TelemetryContext,
+  TelemetryEvent,
+  TelemetryPrimitive,
+  TelemetryTransport,
+} from './types';
+
+export interface EventSinkContextOptions {
+  readonly appName: string;
+  readonly version: string;
+  readonly uiMode?: string;
+  readonly model?: string;
+  readonly buildSha?: string;
+  readonly terminal?: string;
+  readonly locale?: string;
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+export interface EventSinkOptions {
+  readonly transport: TelemetryTransport;
+  readonly context: EventSinkContextOptions;
+  readonly flushIntervalMs?: number;
+  readonly flushThreshold?: number;
+}
+
+const DEFAULT_FLUSH_INTERVAL_MS = 30_000;
+const DEFAULT_FLUSH_THRESHOLD = 50;
+
+export class EventSink {
+  private readonly transport: TelemetryTransport;
+  private readonly context: TelemetryContext;
+  private readonly flushIntervalMs: number;
+  private readonly flushThreshold: number;
+  private buffer: EnrichedTelemetryEvent[] = [];
+  private flushTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(options: EventSinkOptions) {
+    this.transport = options.transport;
+    this.context = buildContext(options.context);
+    this.flushIntervalMs = options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+    this.flushThreshold = options.flushThreshold ?? DEFAULT_FLUSH_THRESHOLD;
+  }
+
+  accept(event: TelemetryEvent): void {
+    const enriched: EnrichedTelemetryEvent = {
+      ...event,
+      context: { ...this.context },
+    };
+    this.buffer.push(enriched);
+    if (this.buffer.length >= this.flushThreshold) {
+      void this.flush().catch(() => {});
+    }
+  }
+
+  startPeriodicFlush(): void {
+    if (this.flushTimer !== null) return;
+    this.flushTimer = setInterval(() => {
+      void this.flush().catch(() => {});
+    }, this.flushIntervalMs);
+    this.flushTimer.unref?.();
+  }
+
+  stopPeriodicFlush(): void {
+    if (this.flushTimer === null) return;
+    clearInterval(this.flushTimer);
+    this.flushTimer = null;
+  }
+
+  async retryDiskEvents(): Promise<void> {
+    await this.transport.retryDiskEvents();
+  }
+
+  clearBuffer(): void {
+    this.buffer = [];
+  }
+
+  async flush(signal?: AbortSignal): Promise<void> {
+    if (this.buffer.length === 0) return;
+    const events = this.buffer;
+    this.buffer = [];
+    await this.transport.send(events, signal);
+  }
+
+  flushSync(): void {
+    if (this.buffer.length === 0) return;
+    const events = this.buffer;
+    this.buffer = [];
+    try {
+      this.transport.saveToDisk(events);
+    } catch {
+      // Telemetry must never make shutdown fail.
+    }
+  }
+}
+
+function buildContext(options: EventSinkContextOptions): TelemetryContext {
+  const env = options.env ?? process.env;
+  const context: TelemetryContext = {
+    app_name: options.appName,
+    version: options.version,
+    runtime: 'node',
+    platform: platform(),
+    arch: arch(),
+    node_version: process.versions.node,
+    os_version: release(),
+    ci: env['CI'] !== undefined,
+    locale: options.locale ?? env['LANG'] ?? '',
+    terminal: options.terminal ?? env['TERM_PROGRAM'] ?? '',
+    ui_mode: options.uiMode ?? 'shell',
+  };
+  setPrimitive(context, 'model', options.model);
+  setPrimitive(context, 'build_sha', options.buildSha);
+  return context;
+}
+
+function setPrimitive(
+  target: TelemetryContext,
+  key: string,
+  value: TelemetryPrimitive | undefined,
+): void {
+  if (value === undefined) return;
+  if (typeof value === 'string' && value.length === 0) return;
+  target[key] = value;
+}
diff --git a/packages/telemetry/src/transport.ts b/packages/telemetry/src/transport.ts
new file mode 100644
index 000000000..73d6f1f8b
--- /dev/null
+++ b/packages/telemetry/src/transport.ts
@@ -0,0 +1,350 @@
+import { randomBytes } from 'node:crypto';
+import {
+  chmodSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+import type { EnrichedTelemetryEvent, TelemetryPrimitive } from './types';
+import { isTelemetryPrimitive } from './types';
+
+export const TELEMETRY_ENDPOINT = 'https://telemetry-logs.kimi.com/v1/event';
+export const SERVER_EVENT_PREFIX = 'kfc_';
+export const USER_ID_PREFIX = 'kfc_device_id_';
+export const DISK_EVENT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+export const RETRY_BACKOFFS_MS = [1_000, 4_000, 16_000] as const;
+
+export interface AsyncTransportOptions {
+  readonly homeDir: string;
+  readonly deviceId: string;
+  readonly endpoint?: string;
+  readonly getAccessToken?: () => string | null | Promise<string | null>;
+  readonly fetchImpl?: typeof fetch;
+  readonly retryBackoffsMs?: readonly number[];
+  readonly requestTimeoutMs?: number;
+  readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+  readonly now?: () => number;
+}
+
+export interface TelemetryPayload {
+  readonly user_id: string;
+  readonly events: readonly Record<string, TelemetryPrimitive>[];
+}
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+
+export class AsyncTransport {
+  private readonly homeDir: string;
+  private readonly deviceId: string;
+  private readonly endpoint: string;
+  private readonly getAccessToken: (() => string | null | Promise<string | null>) | null;
+  private readonly fetchImpl: typeof fetch;
+  private readonly retryBackoffsMs: readonly number[];
+  private readonly requestTimeoutMs: number;
+  private readonly sleepImpl: (ms: number, signal?: AbortSignal) => Promise<void>;
+  private readonly now: () => number;
+
+  constructor(options: AsyncTransportOptions) {
+    this.homeDir = options.homeDir;
+    this.deviceId = options.deviceId;
+    this.endpoint = options.endpoint ?? TELEMETRY_ENDPOINT;
+    this.getAccessToken = options.getAccessToken ?? null;
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.retryBackoffsMs = options.retryBackoffsMs ?? RETRY_BACKOFFS_MS;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    this.sleepImpl = options.sleep ?? abortableSleep;
+    this.now = options.now ?? Date.now;
+  }
+
+  async send(events: readonly EnrichedTelemetryEvent[], signal?: AbortSignal): Promise<void> {
+    if (events.length === 0) return;
+    let savedToDisk = false;
+    const saveEventsToDisk = (): void => {
+      if (savedToDisk) return;
+      this.saveToDisk(events);
+      savedToDisk = true;
+    };
+    if (signal?.aborted === true) {
+      saveEventsToDisk();
+      throw abortError();
+    }
+
+    let payload: TelemetryPayload;
+    try {
+      payload = buildPayload(events, this.deviceId);
+    } catch {
+      return;
+    }
+
+    try {
+      for (let attempt = 0; attempt <= this.retryBackoffsMs.length; attempt++) {
+        try {
+          await this.sendHttp(payload, signal);
+          return;
+        } catch (error) {
+          if (isSignalAborted(signal) || isAbortError(error)) {
+            saveEventsToDisk();
+            throw error;
+          }
+          if (!(error instanceof TransientTelemetryError)) {
+            break;
+          }
+          const backoff = this.retryBackoffsMs[attempt];
+          if (backoff === undefined) break;
+          await this.sleepImpl(backoff, signal);
+        }
+      }
+    } catch (error) {
+      if (isSignalAborted(signal) || isAbortError(error)) {
+        saveEventsToDisk();
+        throw error;
+      }
+    }
+
+    saveEventsToDisk();
+  }
+
+  saveToDisk(events: readonly EnrichedTelemetryEvent[]): void {
+    if (events.length === 0) return;
+    const path = join(this.telemetryDir(), `failed_${randomBytes(6).toString('hex')}.jsonl`);
+    const text = events.map((event) => JSON.stringify(event)).join('\n') + '\n';
+    writeFileSync(path, text, { encoding: 'utf-8', mode: 0o600, flag: 'wx' });
+    try {
+      chmodSync(path, 0o600);
+    } catch {
+      // best effort on platforms that do not support chmod.
+    }
+  }
+
+  async retryDiskEvents(): Promise<void> {
+    let entries: string[];
+    try {
+      entries = readdirSync(this.telemetryDir());
+    } catch {
+      return;
+    }
+
+    const now = this.now();
+    for (const entry of entries) {
+      if (!entry.startsWith('failed_') || !entry.endsWith('.jsonl')) continue;
+      const path = join(this.telemetryDir(), entry);
+      try {
+        const stat = statSync(path);
+        if (now - stat.mtimeMs > DISK_EVENT_MAX_AGE_MS) {
+          unlinkSync(path);
+          continue;
+        }
+      } catch {
+        continue;
+      }
+
+      let events: EnrichedTelemetryEvent[];
+      let payload: TelemetryPayload;
+      try {
+        events = readJsonl(path);
+        payload = buildPayload(events, this.deviceId);
+      } catch (error) {
+        if (error instanceof SyntaxError || error instanceof TypeError) {
+          try {
+            unlinkSync(path);
+          } catch {
+            // best effort cleanup.
+          }
+        }
+        continue;
+      }
+
+      try {
+        await this.sendHttp(payload);
+        unlinkSync(path);
+      } catch (error) {
+        if (error instanceof TransientTelemetryError) continue;
+      }
+    }
+  }
+
+  private async sendHttp(payload: TelemetryPayload, signal?: AbortSignal): Promise<void> {
+    const token = this.getAccessToken === null ? null : await this.getAccessToken();
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+    if (token !== null && token.length > 0) {
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+
+    const response = await this.post(payload, headers, signal);
+    if (response.status === 401 && headers['Authorization'] !== undefined) {
+      delete headers['Authorization'];
+      const retry = await this.post(payload, headers, signal);
+      handleStatus(retry.status);
+      return;
+    }
+    handleStatus(response.status);
+  }
+
+  private async post(
+    payload: TelemetryPayload,
+    headers: Record<string, string>,
+    signal?: AbortSignal,
+  ): Promise<Response> {
+    try {
+      return await fetchWithTimeout(
+        this.fetchImpl,
+        this.endpoint,
+        {
+          method: 'POST',
+          headers: { ...headers },
+          body: JSON.stringify(payload),
+        },
+        this.requestTimeoutMs,
+        signal,
+      );
+    } catch (error) {
+      if (signal?.aborted === true || isAbortError(error)) throw error;
+      throw new TransientTelemetryError(String(error));
+    }
+  }
+
+  private telemetryDir(): string {
+    const path = join(this.homeDir, 'telemetry');
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    try {
+      chmodSync(path, 0o700);
+    } catch {
+      // best effort on platforms that do not support chmod.
+    }
+    return path;
+  }
+}
+
+export class TransientTelemetryError extends Error {
+  override readonly name = 'TransientTelemetryError';
+}
+
+export function buildUserId(deviceId: string): string {
+  return USER_ID_PREFIX + deviceId;
+}
+
+export function buildPayload(
+  events: readonly EnrichedTelemetryEvent[],
+  deviceId: string,
+): TelemetryPayload {
+  return {
+    user_id: buildUserId(deviceId),
+    events: events.map((event) => flattenEvent(applyServerPrefix(event))),
+  };
+}
+
+export function applyServerPrefix(event: EnrichedTelemetryEvent): EnrichedTelemetryEvent {
+  const name: unknown = event.event;
+  if (typeof name !== 'string' || name.length === 0 || name.startsWith(SERVER_EVENT_PREFIX)) {
+    return event;
+  }
+  return { ...event, event: SERVER_EVENT_PREFIX + name };
+}
+
+export function flattenEvent(event: EnrichedTelemetryEvent): Record<string, TelemetryPrimitive> {
+  const out: Record<string, TelemetryPrimitive> = {};
+  for (const [key, value] of Object.entries(event)) {
+    if (key === 'properties') {
+      flattenNested(out, 'property', value);
+    } else if (key === 'context') {
+      flattenNested(out, 'context', value);
+    } else {
+      assertPrimitive(key, value);
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function flattenNested(target: Record<string, TelemetryPrimitive>, prefix: string, value: unknown) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return;
+  for (const [key, nestedValue] of Object.entries(value)) {
+    assertPrimitive(`${prefix}.${key}`, nestedValue);
+    target[`${prefix}_${key}`] = nestedValue;
+  }
+}
+
+function assertPrimitive(key: string, value: unknown): asserts value is TelemetryPrimitive {
+  if (isTelemetryPrimitive(value)) return;
+  throw new TypeError(`telemetry ${key} must be primitive`);
+}
+
+function handleStatus(status: number): void {
+  if (status >= 500 || status === 429) {
+    throw new TransientTelemetryError(`HTTP ${String(status)}`);
+  }
+  if (status >= 400) {
+    return;
+  }
+}
+
+function readJsonl(path: string): EnrichedTelemetryEvent[] {
+  const text = readFileSync(path, 'utf-8');
+  const events: EnrichedTelemetryEvent[] = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    events.push(JSON.parse(trimmed) as EnrichedTelemetryEvent);
+  }
+  return events;
+}
+
+async function fetchWithTimeout(
+  fetchImpl: typeof fetch,
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+  externalSignal?: AbortSignal,
+): Promise<Response> {
+  const controller = new AbortController();
+  const abortFromExternal = (): void => {
+    controller.abort(externalSignal?.reason);
+  };
+  const timeout = setTimeout(() => {
+    controller.abort(new Error('telemetry request timed out'));
+  }, timeoutMs);
+  timeout.unref?.();
+  if (externalSignal?.aborted === true) abortFromExternal();
+  externalSignal?.addEventListener('abort', abortFromExternal, { once: true });
+  try {
+    return await fetchImpl(url, {
+      ...init,
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timeout);
+    externalSignal?.removeEventListener('abort', abortFromExternal);
+  }
+}
+
+function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted === true) return Promise.reject(abortError());
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(abortError());
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === 'AbortError';
+}
+
+function isSignalAborted(signal?: AbortSignal): boolean {
+  return signal?.aborted === true;
+}
+
+function abortError(): DOMException {
+  return new DOMException('The operation was aborted.', 'AbortError');
+}
diff --git a/packages/telemetry/src/types.ts b/packages/telemetry/src/types.ts
new file mode 100644
index 000000000..4a992e965
--- /dev/null
+++ b/packages/telemetry/src/types.ts
@@ -0,0 +1,31 @@
+export type TelemetryPrimitive = boolean | number | string | null;
+export type TelemetryProperties = Record<string, TelemetryPrimitive>;
+export type TelemetryContext = Record<string, TelemetryPrimitive>;
+
+export interface TelemetryEvent {
+  readonly event_id: string;
+  device_id: string | null;
+  session_id: string | null;
+  readonly event: string;
+  readonly timestamp: number;
+  readonly properties: TelemetryProperties;
+}
+
+export interface EnrichedTelemetryEvent extends TelemetryEvent {
+  readonly context: TelemetryContext;
+}
+
+export interface TelemetryTransport {
+  send(events: readonly EnrichedTelemetryEvent[], signal?: AbortSignal): Promise<void>;
+  saveToDisk(events: readonly EnrichedTelemetryEvent[]): void;
+  retryDiskEvents(): Promise<void>;
+}
+
+export function isTelemetryPrimitive(value: unknown): value is TelemetryPrimitive {
+  return (
+    value === null ||
+    typeof value === 'boolean' ||
+    typeof value === 'string' ||
+    (typeof value === 'number' && Number.isFinite(value))
+  );
+}
diff --git a/packages/telemetry/test/normalize-remote.test.ts b/packages/telemetry/test/normalize-remote.test.ts
new file mode 100644
index 000000000..3c21a33c0
--- /dev/null
+++ b/packages/telemetry/test/normalize-remote.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+
+import { normalizeRemote } from '../src/remote';
+
+describe('normalizeRemote', () => {
+  it.each([
+    ['git@github.com:user/repo.git', 'github.com/user/repo'],
+    ['https://github.com/user/repo.git', 'github.com/user/repo'],
+    ['https://github.com/user/repo', 'github.com/user/repo'],
+    ['http://github.com/user/repo.git', 'github.com/user/repo'],
+    ['https://user:token@github.com/org/repo.git', 'github.com/org/repo'],
+    ['http://user@github.com/org/repo.git', 'github.com/org/repo'],
+    ['https://user:pass:word@github.com/repo.git', 'github.com/repo'],
+    ['git@host.com:path/to/repo.git', 'host.com/path/to/repo'],
+    ['git@host.com:path/to/repo', 'host.com/path/to/repo'],
+    ['https://github.com/org/team/repo.git', 'github.com/org/team/repo'],
+    ['github.com/user/repo', 'github.com/user/repo'],
+    ['github.com/user/repo.git', 'github.com/user/repo'],
+    ['user@host.com:path/repo.git', 'host.com/path/repo'],
+    ['', ''],
+    ['   ', ''],
+    ['https://host.com:8443/path/repo.git', 'host.com/8443/path/repo'],
+  ])('canonicalizes %s to %s', (url, expected) => {
+    expect(normalizeRemote(url)).toBe(expected);
+  });
+});
diff --git a/packages/telemetry/test/telemetry.test.ts b/packages/telemetry/test/telemetry.test.ts
new file mode 100644
index 000000000..e143ad9b8
--- /dev/null
+++ b/packages/telemetry/test/telemetry.test.ts
@@ -0,0 +1,889 @@
+import { spawn } from 'node:child_process';
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { flushTelemetrySync, initializeTelemetry, shutdownTelemetry, track } from '../src';
+import { isTelemetryDisabledByEnv } from '../src/bootstrap';
+import { TelemetryClient, resetDefaultTelemetryClientForTests } from '../src/client';
+import { installCrashHandlersForClient, setCrashPhase, uninstallCrashHandlers } from '../src/crash';
+import { EventSink } from '../src/sink';
+import {
+  AsyncTransport,
+  DISK_EVENT_MAX_AGE_MS,
+  RETRY_BACKOFFS_MS,
+  SERVER_EVENT_PREFIX,
+  TransientTelemetryError,
+  USER_ID_PREFIX,
+  applyServerPrefix,
+  buildPayload,
+} from '../src/transport';
+import type { EnrichedTelemetryEvent, TelemetryEvent, TelemetryTransport } from '../src/types';
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  uninstallCrashHandlers();
+  setCrashPhase('startup');
+  resetDefaultTelemetryClientForTests();
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  vi.restoreAllMocks();
+});
+
+async function tempHome(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'kimi-telemetry-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+class RecordingTransport implements TelemetryTransport {
+  readonly sent: EnrichedTelemetryEvent[][] = [];
+  readonly saved: EnrichedTelemetryEvent[][] = [];
+  retryCount = 0;
+
+  async send(events: readonly EnrichedTelemetryEvent[]): Promise<void> {
+    this.sent.push([...events]);
+  }
+
+  saveToDisk(events: readonly EnrichedTelemetryEvent[]): void {
+    this.saved.push([...events]);
+  }
+
+  async retryDiskEvents(): Promise<void> {
+    this.retryCount += 1;
+  }
+}
+
+function makeSink(transport: TelemetryTransport, flushThreshold = 10): EventSink {
+  return new EventSink({
+    transport,
+    context: {
+      appName: 'kimi-code-cli',
+      version: '1.2.3',
+      uiMode: 'shell',
+      model: 'kimi-k2',
+      env: {},
+      terminal: 'test-terminal',
+      locale: 'en_US',
+    },
+    flushThreshold,
+  });
+}
+
+function sampleEvent(name = 'started'): EnrichedTelemetryEvent {
+  return {
+    event_id: 'event-1',
+    device_id: 'device-1',
+    session_id: 'session-1',
+    event: name,
+    timestamp: 123,
+    properties: {
+      resumed: false,
+      count: 2,
+    },
+    context: {
+      version: '1.2.3',
+      runtime: 'node',
+    },
+  };
+}
+
+describe('TelemetryClient', () => {
+  it('queues events before sink attach, then drains with backfilled context ids', async () => {
+    const client = new TelemetryClient();
+    client.track('early');
+    client.setContext({ deviceId: 'dev', sessionId: 'ses' });
+    const transport = new RecordingTransport();
+
+    client.attachSink(makeSink(transport));
+    await client.flush();
+
+    expect(transport.sent).toHaveLength(1);
+    expect(transport.sent[0]?.[0]).toMatchObject({
+      event: 'early',
+      device_id: 'dev',
+      session_id: 'ses',
+    });
+  });
+
+  it('records scoped session ids without mutating the parent context', async () => {
+    const client = new TelemetryClient();
+    const transport = new RecordingTransport();
+    client.setContext({ deviceId: 'dev', sessionId: 'active' });
+    client.attachSink(makeSink(transport));
+
+    client.withContext({ sessionId: 'session-a' }).track('scoped');
+    client.track('root');
+    await client.flush();
+
+    expect(transport.sent[0]).toMatchObject([
+      { event: 'scoped', device_id: 'dev', session_id: 'session-a' },
+      { event: 'root', device_id: 'dev', session_id: 'active' },
+    ]);
+  });
+
+  it('can clear the active session context', async () => {
+    const client = new TelemetryClient();
+    const transport = new RecordingTransport();
+    client.setContext({ deviceId: 'dev', sessionId: 'active' });
+    client.attachSink(makeSink(transport));
+
+    client.setContext({ sessionId: null });
+    client.track('no_session');
+    await client.flush();
+
+    expect(transport.sent[0]?.[0]).toMatchObject({
+      event: 'no_session',
+      device_id: 'dev',
+      session_id: null,
+    });
+  });
+
+  it('forwards directly to the attached sink and can be disabled', async () => {
+    const client = new TelemetryClient();
+    const transport = new RecordingTransport();
+    client.attachSink(makeSink(transport));
+
+    client.track('before_disable');
+    client.disable();
+    client.track('after_disable');
+    await client.flush();
+
+    expect(transport.sent).toHaveLength(0);
+  });
+
+  it('flushes the previous sink synchronously when replacing sinks', () => {
+    const client = new TelemetryClient();
+    const first = new RecordingTransport();
+    const second = new RecordingTransport();
+    client.attachSink(makeSink(first));
+    client.track('old_sink');
+
+    client.attachSink(makeSink(second));
+
+    expect(first.saved[0]?.[0]?.event).toBe('old_sink');
+    expect(second.saved).toHaveLength(0);
+  });
+
+  it('caps the pre-sink queue at 1000 events and keeps the newest entries', async () => {
+    const client = new TelemetryClient();
+    const transport = new RecordingTransport();
+
+    for (let i = 0; i < 1005; i++) {
+      client.track(`queued_${String(i)}`);
+    }
+
+    client.attachSink(makeSink(transport, 2000));
+    await client.flush();
+
+    expect(transport.sent[0]).toHaveLength(1000);
+    expect(transport.sent[0]?.[0]?.event).toBe('queued_5');
+    expect(transport.sent[0]?.at(-1)?.event).toBe('queued_1004');
+  });
+
+  it('emits generated ids and second-resolution timestamps on tracked events', async () => {
+    const client = new TelemetryClient();
+    const transport = new RecordingTransport();
+    client.attachSink(makeSink(transport));
+    const before = Date.now() / 1000;
+
+    client.track('timed');
+    await client.flush();
+
+    const event = transport.sent[0]?.[0];
+    expect(event?.event_id).toMatch(/^[0-9a-f]{32}$/);
+    expect(event?.timestamp).toBeGreaterThanOrEqual(before);
+    expect(event?.timestamp).toBeLessThanOrEqual(Date.now() / 1000);
+    expect(event?.properties).toEqual({});
+  });
+});
+
+describe('EventSink', () => {
+  it('enriches context without mutating the original event', () => {
+    const transport = new RecordingTransport();
+    const sink = makeSink(transport);
+    const event: TelemetryEvent = {
+      event_id: 'e1',
+      device_id: 'dev',
+      session_id: 'ses',
+      event: 'test',
+      timestamp: 1,
+      properties: {},
+    };
+
+    sink.accept(event);
+    sink.flushSync();
+
+    expect('context' in event).toBe(false);
+    expect(transport.saved[0]?.[0]?.context).toMatchObject({
+      app_name: 'kimi-code-cli',
+      version: '1.2.3',
+      runtime: 'node',
+      ui_mode: 'shell',
+      model: 'kimi-k2',
+      terminal: 'test-terminal',
+    });
+  });
+
+  it('delegates retry of disk events to its transport', async () => {
+    const transport = new RecordingTransport();
+    const sink = makeSink(transport);
+
+    await sink.retryDiskEvents();
+
+    expect(transport.retryCount).toBe(1);
+  });
+});
+
+describe('payload assembly', () => {
+  it('adds server event prefix, payload user id, and flattened fields', () => {
+    const payload = buildPayload([sampleEvent('started')], 'device-1');
+
+    expect(payload.user_id).toBe('kfc_device_id_device-1');
+    expect(payload.events[0]).toMatchObject({
+      event_id: 'event-1',
+      device_id: 'device-1',
+      session_id: 'session-1',
+      event: `${SERVER_EVENT_PREFIX}started`,
+      property_resumed: false,
+      property_count: 2,
+      context_version: '1.2.3',
+      context_runtime: 'node',
+    });
+    expect(payload.events[0]).not.toHaveProperty('properties');
+    expect(payload.events[0]).not.toHaveProperty('context');
+  });
+
+  it('does not double-prefix already-prefixed events', () => {
+    const payload = buildPayload([sampleEvent('kfc_started')], 'device-1');
+
+    expect(payload.events[0]?.['event']).toBe('kfc_started');
+  });
+
+  it('rejects nested property values before outbound send', () => {
+    const event = {
+      ...sampleEvent('bad'),
+      properties: {
+        nested: { nope: true },
+      },
+    } as unknown as EnrichedTelemetryEvent;
+
+    expect(() => buildPayload([event], 'device-1')).toThrow(/property.nested/);
+  });
+
+  it('rejects nested context and array property values before outbound send', () => {
+    const nestedContext = {
+      ...sampleEvent('bad_context'),
+      context: {
+        nested: { nope: true },
+      },
+    } as unknown as EnrichedTelemetryEvent;
+    const arrayProperty = {
+      ...sampleEvent('bad_array'),
+      properties: {
+        list: ['nope'],
+      },
+    } as unknown as EnrichedTelemetryEvent;
+
+    expect(() => buildPayload([nestedContext], 'device-1')).toThrow(/context.nested/);
+    expect(() => buildPayload([arrayProperty], 'device-1')).toThrow(/property.list/);
+  });
+
+  it('passes null primitive values through and leaves the input event untouched', () => {
+    const event = {
+      ...sampleEvent('nullable'),
+      properties: {
+        empty: null,
+      },
+    };
+    const originalProperties = event.properties;
+    const originalContext = event.context;
+
+    const payload = buildPayload([event], 'device-1');
+
+    expect(payload.events[0]).toMatchObject({
+      event: 'kfc_nullable',
+      property_empty: null,
+    });
+    expect(event.properties).toBe(originalProperties);
+    expect(event.context).toBe(originalContext);
+    expect(event.event).toBe('nullable');
+  });
+});
+
+describe('server prefix application', () => {
+  it('locks the outbound telemetry prefixes', () => {
+    expect(SERVER_EVENT_PREFIX).toBe('kfc_');
+    expect(USER_ID_PREFIX).toBe('kfc_device_id_');
+  });
+
+  it('returns a new object only when adding the server prefix', () => {
+    const event = sampleEvent('started');
+
+    const prefixed = applyServerPrefix(event);
+
+    expect(prefixed).not.toBe(event);
+    expect(prefixed.event).toBe('kfc_started');
+    expect(event.event).toBe('started');
+  });
+
+  it('passes already-prefixed and invalid event names through unchanged', () => {
+    const prefixed = sampleEvent('kfc_started');
+    const emptyName = sampleEvent('');
+    const missingName = { ...sampleEvent('missing') } as unknown as Record<string, unknown>;
+    delete missingName['event'];
+    const numberName = {
+      ...sampleEvent('number'),
+      event: 123,
+    } as unknown as EnrichedTelemetryEvent;
+
+    expect(applyServerPrefix(prefixed)).toBe(prefixed);
+    expect(applyServerPrefix(emptyName as unknown as EnrichedTelemetryEvent)).toBe(emptyName);
+    expect(applyServerPrefix(missingName as unknown as EnrichedTelemetryEvent)).toBe(missingName);
+    expect(applyServerPrefix(numberName)).toBe(numberName);
+  });
+});
+
+describe('AsyncTransport', () => {
+  it('locks the retry backoff schedule', () => {
+    expect(RETRY_BACKOFFS_MS).toEqual([1_000, 4_000, 16_000]);
+  });
+
+  it('sends the outbound payload with bearer token when available', async () => {
+    const fetchImpl = vi.fn(async () => new Response('', { status: 200 }));
+    const transport = new AsyncTransport({
+      homeDir: await tempHome(),
+      deviceId: 'dev',
+      endpoint: 'https://mock.test/events',
+      getAccessToken: () => 'token-1',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+      retryBackoffsMs: [],
+    });
+
+    await transport.send([sampleEvent()]);
+
+    const init = requestInitFrom(fetchImpl);
+    expect(init.headers).toMatchObject({ Authorization: 'Bearer token-1' });
+    expect(JSON.parse(init.body as string)).toMatchObject({
+      user_id: 'kfc_device_id_dev',
+    });
+  });
+
+  it('retries anonymously on 401 with a token', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(new Response('', { status: 401 }))
+      .mockResolvedValueOnce(new Response('', { status: 200 }));
+    const transport = new AsyncTransport({
+      homeDir: await tempHome(),
+      deviceId: 'dev',
+      endpoint: 'https://mock.test/events',
+      getAccessToken: () => 'token-1',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+      retryBackoffsMs: [],
+    });
+
+    await transport.send([sampleEvent()]);
+
+    const first = requestInitFrom(fetchImpl);
+    const second = requestInitFrom(fetchImpl, 1);
+    expect(first.headers).toMatchObject({ Authorization: 'Bearer token-1' });
+    expect(second.headers).not.toHaveProperty('Authorization');
+  });
+
+  it('spools to disk when the anonymous 401 retry gets a transient response', async () => {
+    const homeDir = await tempHome();
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(new Response('', { status: 401 }))
+      .mockResolvedValueOnce(new Response('', { status: 500 }));
+    const transport = new AsyncTransport({
+      homeDir,
+      deviceId: 'dev',
+      endpoint: 'https://mock.test/events',
+      getAccessToken: () => 'token-1',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+      retryBackoffsMs: [],
+    });
+
+    await transport.send([sampleEvent('anonymous_retry_server_error')]);
+
+    const first = requestInitFrom(fetchImpl);
+    const second = requestInitFrom(fetchImpl, 1);
+    expect(first.headers).toMatchObject({ Authorization: 'Bearer token-1' });
+    expect(second.headers).not.toHaveProperty('Authorization');
+    const telemetryDir = join(homeDir, 'telemetry');
+    const file = readFileSync(join(telemetryDir, readdirOne(telemetryDir)), 'utf-8');
+    expect(file).toContain('"event":"anonymous_retry_server_error"');
+  });
+
+  it('drops events when the anonymous 401 retry gets a non-retryable 4xx', async () => {
+    const homeDir = await tempHome();
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(new Response('', { status: 401 }))
+      .mockResolvedValueOnce(new Response('', { status: 403 }));
+    const transport = new AsyncTransport({
+      homeDir,
+      deviceId: 'dev',
+      endpoint: 'https://mock.test/events',
+      getAccessToken: () => 'token-1',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+      retryBackoffsMs: [],
+    });
+
+    await transport.send([sampleEvent('anonymous_retry_forbidden')]);
+
+    const first = requestInitFrom(fetchImpl);
+    const second = requestInitFrom(fetchImpl, 1);
+    expect(first.headers).toMatchObject({ Authorization: 'Bearer token-1' });
+    expect(second.headers).not.toHaveProperty('Authorization');
+    expect(() => statSync(join(homeDir, 'telemetry'))).toThrow();
+  });
+
+  it('spools transient failures to disk after retries exhaust', async () => {
+    const homeDir = await tempHome();
+    const fetchImpl = vi.fn(async () => new Response('', { status: 429 }));
+    const transport = new AsyncTransport({
+      homeDir,
+      deviceId: 'dev',
+      endpoint: 'https://mock.test/events',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+      retryBackoffsMs: [],
+    });
+
+    await transport.send([sampleEvent('rate_limited')]);
+
+    const telemetryDir = join(homeDir, 'telemetry');
+    const file = readFileSync(join(telemetryDir, readdirOne(telemetryDir)), 'utf-8');
+    expect(file).toContain('"event":"rate_limited"');
+  });
+
+  it('drops non-retryable 4xx responses without disk fallback', async () => {
+    const homeDir = await tempHome();
+    const fetchImpl = vi.fn(async () => new Response('', { status: 422 }));
+    const transport = new AsyncTransport({
+      homeDir,
+      deviceId: 'dev',
+      endpoint: 'https://mock.test/events',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+      retryBackoffsMs: [],
+    });
+
+    await transport.send([sampleEvent('bad_schema')]);
+
+    expect(() => statSync(join(homeDir, 'telemetry'))).toThrow();
+  });
+
+  it('retries disk events through the outbound pipeline and deletes the file on success', async () => {
+    const homeDir = await tempHome();
+    const telemetryDir = join(homeDir, 'telemetry');
+    mkdirSync(telemetryDir, { recursive: true });
+    const file = join(telemetryDir, 'failed_retry.jsonl');
+    writeFileSync(file, `${JSON.stringify(sampleEvent('from_disk'))}\n`);
+    const fetchImpl = vi.fn(async () => new Response('', { status: 200 }));
+    const transport = new AsyncTransport({
+      homeDir,
+      deviceId: 'dev',
+      endpoint: 'https://mock.test/events',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    await transport.retryDiskEvents();
+
+    const init = requestInitFrom(fetchImpl);
+    const payload = JSON.parse(init.body as string) as { events: Array<{ event: string }> };
+    expect(payload.events[0]?.['event']).toBe('kfc_from_disk');
+    expect(() => statSync(file)).toThrow();
+  });
+
+  it('removes expired and corrupted disk files', async () => {
+    const homeDir = await tempHome();
+    const telemetryDir = join(homeDir, 'telemetry');
+    mkdirSync(telemetryDir, { recursive: true });
+    const expired = join(telemetryDir, 'failed_expired.jsonl');
+    const corrupt = join(telemetryDir, 'failed_corrupt.jsonl');
+    writeFileSync(expired, `${JSON.stringify(sampleEvent('old'))}\n`);
+    writeFileSync(corrupt, 'not json\n');
+    const now = Date.now();
+    const transport = new AsyncTransport({
+      homeDir,
+      deviceId: 'dev',
+      endpoint: 'https://mock.test/events',
+      fetchImpl: vi.fn(async () => new Response('', { status: 200 })) as unknown as typeof fetch,
+      now: () => now + DISK_EVENT_MAX_AGE_MS + 1,
+    });
+
+    await transport.retryDiskEvents();
+
+    expect(() => statSync(expired)).toThrow();
+    expect(() => statSync(corrupt)).toThrow();
+  });
+
+  it('saves events before propagating shutdown aborts', async () => {
+    const homeDir = await tempHome();
+    const transport = new AsyncTransport({
+      homeDir,
+      deviceId: 'dev',
+      endpoint: 'https://mock.test/events',
+      fetchImpl: vi.fn(async () => {
+        throw new TransientTelemetryError('nope');
+      }) as unknown as typeof fetch,
+      retryBackoffsMs: [10_000],
+    });
+    const controller = new AbortController();
+    const send = transport.send([sampleEvent('aborted')], controller.signal);
+
+    controller.abort();
+    await expect(send).rejects.toThrow();
+
+    const telemetryDir = join(homeDir, 'telemetry');
+    const file = readFileSync(join(telemetryDir, readdirOne(telemetryDir)), 'utf-8');
+    expect(file).toContain('"event":"aborted"');
+  });
+
+  it('saves events when shutdown aborts during retry backoff', async () => {
+    const homeDir = await tempHome();
+    const controller = new AbortController();
+    const transport = new AsyncTransport({
+      homeDir,
+      deviceId: 'dev',
+      endpoint: 'https://mock.test/events',
+      fetchImpl: vi.fn(async () => new Response('', { status: 429 })) as unknown as typeof fetch,
+      retryBackoffsMs: [10_000],
+      sleep: async () => {
+        controller.abort();
+        throw new DOMException('The operation was aborted.', 'AbortError');
+      },
+    });
+
+    await expect(
+      transport.send([sampleEvent('aborted_backoff')], controller.signal),
+    ).rejects.toThrow();
+
+    const telemetryDir = join(homeDir, 'telemetry');
+    const file = readFileSync(join(telemetryDir, readdirOne(telemetryDir)), 'utf-8');
+    expect(file).toContain('"event":"aborted_backoff"');
+  });
+
+  it('writes one JSONL line per event and keeps raw event names on disk fallback', async () => {
+    const homeDir = await tempHome();
+    const transport = new AsyncTransport({
+      homeDir,
+      deviceId: 'dev',
+      endpoint: 'https://mock.test/events',
+      fetchImpl: vi.fn(async () => new Response('', { status: 500 })) as unknown as typeof fetch,
+      retryBackoffsMs: [],
+    });
+
+    await transport.send([sampleEvent('first'), sampleEvent('second')]);
+
+    const telemetryDir = join(homeDir, 'telemetry');
+    const file = readFileSync(join(telemetryDir, readdirOne(telemetryDir)), 'utf-8');
+    const lines = file.trim().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0]!) as Record<string, unknown>).toMatchObject({
+      event: 'first',
+      properties: { resumed: false, count: 2 },
+    });
+    expect(file).not.toContain('user_id');
+    expect(file).not.toContain('kfc_first');
+  });
+
+  it('does not create a disk file for an empty batch or a schema violation', async () => {
+    const homeDir = await tempHome();
+    const fetchImpl = vi.fn(async () => new Response('', { status: 200 }));
+    const transport = new AsyncTransport({
+      homeDir,
+      deviceId: 'dev',
+      endpoint: 'https://mock.test/events',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    transport.saveToDisk([]);
+    await transport.send([
+      {
+        ...sampleEvent('bad_schema'),
+        properties: { nested: { nope: true } },
+      } as unknown as EnrichedTelemetryEvent,
+    ]);
+
+    expect(fetchImpl).not.toHaveBeenCalled();
+    expect(() => statSync(join(homeDir, 'telemetry'))).toThrow();
+  });
+});
+
+describe('telemetry bootstrap', () => {
+  it('matches the KIMI_DISABLE_TELEMETRY true-value semantics', () => {
+    expect(isTelemetryDisabledByEnv({ KIMI_DISABLE_TELEMETRY: '1' })).toBe(true);
+    expect(isTelemetryDisabledByEnv({ KIMI_DISABLE_TELEMETRY: 'yes' })).toBe(true);
+    expect(isTelemetryDisabledByEnv({ KIMI_DISABLE_TELEMETRY: '0' })).toBe(false);
+    expect(isTelemetryDisabledByEnv({ KIMI_DISABLE_TELEMETRY: 'false' })).toBe(false);
+  });
+
+  it('disables the singleton without attaching a sink when opted out', async () => {
+    const fetchImpl = vi.fn(async () => new Response('', { status: 200 }));
+    vi.stubGlobal('fetch', fetchImpl);
+    const saved = process.env['KIMI_DISABLE_TELEMETRY'];
+    try {
+      process.env['KIMI_DISABLE_TELEMETRY'] = 'true';
+      initializeTelemetry({
+        homeDir: await tempHome(),
+        deviceId: 'dev',
+        appName: 'kimi-code-cli',
+        version: '1.2.3',
+      });
+      track('dropped');
+      await shutdownTelemetry();
+    } finally {
+      if (saved === undefined) delete process.env['KIMI_DISABLE_TELEMETRY'];
+      else process.env['KIMI_DISABLE_TELEMETRY'] = saved;
+    }
+
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it('queues singleton track calls before initialization, then flushes after bootstrap', async () => {
+    const fetchImpl = vi.fn(async () => new Response('', { status: 200 }));
+    vi.stubGlobal('fetch', fetchImpl);
+
+    track('before_init');
+    initializeTelemetry({
+      homeDir: await tempHome(),
+      deviceId: 'dev',
+      sessionId: 'ses',
+      appName: 'kimi-code-cli',
+      version: '1.2.3',
+    });
+
+    await shutdownTelemetry();
+
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    const init = requestInitFrom(fetchImpl);
+    const payload = JSON.parse(init.body as string) as {
+      events: Array<{ event: string; session_id: string }>;
+    };
+    expect(payload.events[0]).toMatchObject({
+      event: 'kfc_before_init',
+      session_id: 'ses',
+    });
+  });
+
+  it('flushes the singleton synchronously to disk fallback', async () => {
+    const homeDir = await tempHome();
+    initializeTelemetry({
+      homeDir,
+      deviceId: 'dev',
+      sessionId: 'ses',
+      appName: 'kimi-code-cli',
+      version: '1.2.3',
+    });
+    track('sync_flush');
+
+    flushTelemetrySync();
+
+    const telemetryDir = join(homeDir, 'telemetry');
+    const file = readFileSync(join(telemetryDir, readdirOne(telemetryDir)), 'utf-8');
+    expect(file).toContain('"event":"sync_flush"');
+  });
+});
+
+describe('crash handler', () => {
+  it('records uncaught exception monitor crashes and flushes synchronously', () => {
+    const client = new TelemetryClient();
+    const transport = new RecordingTransport();
+    client.attachSink(makeSink(transport));
+    setCrashPhase('runtime');
+    installCrashHandlersForClient(client);
+
+    (process.emit as (event: string, ...args: unknown[]) => boolean)(
+      'uncaughtExceptionMonitor',
+      new Error('boom'),
+      'uncaughtException',
+    );
+
+    expect(transport.saved[0]?.[0]).toMatchObject({
+      event: 'crash',
+      properties: {
+        error_type: 'Error',
+        where: 'runtime',
+        source: 'uncaughtException',
+      },
+    });
+  });
+
+  it('records unhandled rejection crashes and flushes synchronously', () => {
+    const client = new TelemetryClient();
+    const transport = new RecordingTransport();
+    client.attachSink(makeSink(transport));
+    setCrashPhase('runtime');
+    installCrashHandlersForClient(client);
+
+    emitCrash(new TypeError('promise failed'), 'unhandledRejection');
+
+    expect(transport.saved[0]?.[0]).toMatchObject({
+      event: 'crash',
+      properties: {
+        error_type: 'TypeError',
+        where: 'runtime',
+        source: 'unhandledRejection',
+      },
+    });
+  });
+
+  it('keeps Node default non-zero exit semantics for unhandled rejections', async () => {
+    const status = await runTelemetryCrashScript(`
+      installCrashHandlersForClient(new TelemetryClient());
+      Promise.reject(new TypeError('promise failed'));
+      setTimeout(() => process.exit(0), 50);
+    `);
+
+    expect(status).not.toBe(0);
+  });
+
+  it('records Node-wrapped non-error unhandled rejection crashes', () => {
+    const client = new TelemetryClient();
+    const transport = new RecordingTransport();
+    client.attachSink(makeSink(transport));
+    installCrashHandlersForClient(client);
+
+    const error = Object.assign(new Error('promise failed'), {
+      name: 'UnhandledPromiseRejection',
+    });
+    emitCrash(error, 'unhandledRejection');
+
+    expect(transport.saved[0]?.[0]).toMatchObject({
+      event: 'crash',
+      properties: {
+        error_type: 'UnhandledPromiseRejection',
+        where: 'startup',
+        source: 'unhandledRejection',
+      },
+    });
+  });
+
+  it('reflects startup, runtime, and shutdown phases in crash telemetry', () => {
+    const client = new TelemetryClient();
+    const transport = new RecordingTransport();
+    client.attachSink(makeSink(transport));
+    installCrashHandlersForClient(client);
+
+    for (const phase of ['startup', 'runtime', 'shutdown'] as const) {
+      setCrashPhase(phase);
+      emitCrash(new Error(phase));
+    }
+
+    expect(transport.saved.map((batch) => batch[0]?.properties['where'])).toEqual([
+      'startup',
+      'runtime',
+      'shutdown',
+    ]);
+  });
+
+  it('does not register duplicate monitor listeners when installed twice', () => {
+    const client = new TelemetryClient();
+    const beforeUncaught = process.listenerCount('uncaughtExceptionMonitor');
+    const beforeRejection = process.listenerCount('unhandledRejection');
+
+    const uninstallFirst = installCrashHandlersForClient(client);
+    const uninstallSecond = installCrashHandlersForClient(client);
+
+    expect(process.listenerCount('uncaughtExceptionMonitor')).toBe(beforeUncaught + 1);
+    expect(process.listenerCount('unhandledRejection')).toBe(beforeRejection);
+    uninstallSecond();
+    uninstallFirst();
+    expect(process.listenerCount('uncaughtExceptionMonitor')).toBe(beforeUncaught);
+    expect(process.listenerCount('unhandledRejection')).toBe(beforeRejection);
+  });
+
+  it('ignores aborted-operation errors', () => {
+    const client = new TelemetryClient();
+    const transport = new RecordingTransport();
+    client.attachSink(makeSink(transport));
+    installCrashHandlersForClient(client);
+
+    emitCrash(new DOMException('The operation was aborted.', 'AbortError'));
+    emitCrash(Object.assign(new Error('aborted'), { name: 'AbortError' }));
+    emitCrash(new DOMException('The operation was aborted.', 'AbortError'), 'unhandledRejection');
+    emitCrash(
+      Object.assign(new Error('aborted'), { name: 'AbortError' }),
+      'unhandledRejection',
+    );
+
+    expect(transport.saved).toHaveLength(0);
+  });
+});
+
+function readdirOne(dir: string): string {
+  const entry = readdirSync(dir)[0];
+  if (entry === undefined) throw new Error(`No files in ${dir}`);
+  return entry;
+}
+
+function requestInitFrom(
+  fetchImpl: { readonly mock: { readonly calls: readonly unknown[][] } },
+  index = 0,
+): RequestInit {
+  const call = fetchImpl.mock.calls[index] as readonly [unknown, RequestInit?] | undefined;
+  const init = call?.[1];
+  if (init === undefined) throw new Error(`No request init for fetch call ${String(index)}`);
+  return init;
+}
+
+function emitCrash(
+  error: Error,
+  origin: NodeJS.UncaughtExceptionOrigin = 'uncaughtException',
+): void {
+  (process.emit as (event: string, ...args: unknown[]) => boolean)(
+    'uncaughtExceptionMonitor',
+    error,
+    origin,
+  );
+}
+
+async function runTelemetryCrashScript(body: string): Promise<number> {
+  const dir = await tempHome();
+  const scriptPath = join(dir, 'crash-worker.ts');
+  const testDir = import.meta.dirname;
+  const tsxCli = join(
+    dirname(fileURLToPath(import.meta.resolve('tsx/package.json'))),
+    'dist/cli.mjs',
+  );
+  const crashModuleUrl = pathToFileURL(join(testDir, '../src/crash.ts')).href;
+  const clientModuleUrl = pathToFileURL(join(testDir, '../src/client.ts')).href;
+  writeFileSync(
+    scriptPath,
+    `
+      import { TelemetryClient } from ${JSON.stringify(clientModuleUrl)};
+      import { installCrashHandlersForClient } from ${JSON.stringify(crashModuleUrl)};
+
+      ${body}
+    `,
+  );
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(tsxCli, [scriptPath], {
+      cwd: join(testDir, '../../..'),
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    let stderr = '';
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk: string) => {
+      stderr += chunk;
+    });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === null) {
+        reject(new Error(`Crash script exited without a code: ${stderr}`));
+        return;
+      }
+      resolve(code);
+    });
+  });
+}
diff --git a/packages/telemetry/tsconfig.json b/packages/telemetry/tsconfig.json
new file mode 100644
index 000000000..46f71c10f
--- /dev/null
+++ b/packages/telemetry/tsconfig.json
@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {},
+  "include": ["src", "test"]
+}
diff --git a/packages/telemetry/tsdown.config.ts b/packages/telemetry/tsdown.config.ts
new file mode 100644
index 000000000..cb99d9ffb
--- /dev/null
+++ b/packages/telemetry/tsdown.config.ts
@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['./src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  outDir: 'dist',
+  clean: true,
+});
diff --git a/packages/telemetry/vitest.config.ts b/packages/telemetry/vitest.config.ts
new file mode 100644
index 000000000..c1924a1b0
--- /dev/null
+++ b/packages/telemetry/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    name: 'kimi-telemetry',
+    include: ['test/**/*.test.ts'],
+  },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
new file mode 100644
index 000000000..c23aa42f9
--- /dev/null
+++ b/pnpm-lock.yaml
@@ -0,0 +1,7992 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+catalogs:
+  default:
+    zod:
+      specifier: ^4.3.6
+      version: 4.3.6
+
+overrides:
+  ssh2@1.17.0>cpu-features: '-'
+  ssh2@1.17.0>nan: '-'
+
+importers:
+
+  .:
+    devDependencies:
+      '@arethetypeswrong/cli':
+        specifier: 0.18.2
+        version: 0.18.2
+      '@changesets/changelog-github':
+        specifier: 0.7.0
+        version: 0.7.0
+      '@changesets/cli':
+        specifier: 2.30.0
+        version: 2.30.0(@types/node@22.19.17)
+      '@microsoft/api-extractor':
+        specifier: 7.58.7
+        version: 7.58.7(@types/node@22.19.17)
+      '@types/node':
+        specifier: ^22.15.3
+        version: 22.19.17
+      '@vitest/coverage-v8':
+        specifier: 4.1.4
+        version: 4.1.4(vitest@4.1.4)
+      lint-staged:
+        specifier: 16.4.0
+        version: 16.4.0
+      oxlint:
+        specifier: 1.59.0
+        version: 1.59.0(oxlint-tsgolint@0.20.0)
+      oxlint-tsgolint:
+        specifier: 0.20.0
+        version: 0.20.0
+      publint:
+        specifier: 0.3.18
+        version: 0.3.18
+      sherif:
+        specifier: 1.11.1
+        version: 1.11.1
+      simple-git-hooks:
+        specifier: 2.13.1
+        version: 2.13.1
+      tsdown:
+        specifier: 0.22.0
+        version: 0.22.0(@arethetypeswrong/core@0.18.2)(publint@0.3.18)(tsx@4.21.0)(typescript@6.0.2)(unrun@0.2.34(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0))
+      tsx:
+        specifier: ^4.21.0
+        version: 4.21.0
+      typescript:
+        specifier: 6.0.2
+        version: 6.0.2
+      vitest:
+        specifier: 4.1.4
+        version: 4.1.4(@types/node@22.19.17)(@vitest/coverage-v8@4.1.4)(vite@8.0.8(@types/node@22.19.17)(esbuild@0.27.7)(jiti@2.6.1)(tsx@4.21.0)(yaml@2.8.3))
+
+  apps/kimi-code:
+    dependencies:
+      '@earendil-works/pi-tui':
+        specifier: ^0.74.0
+        version: 0.74.0
+      '@mariozechner/clipboard':
+        specifier: ^0.3.2
+        version: 0.3.2
+      chalk:
+        specifier: ^5.4.1
+        version: 5.6.2
+      cli-highlight:
+        specifier: ^2.1.11
+        version: 2.1.11
+      commander:
+        specifier: ^13.1.0
+        version: 13.1.0
+      semver:
+        specifier: ^7.7.4
+        version: 7.7.4
+      smol-toml:
+        specifier: ^1.6.1
+        version: 1.6.1
+      zod:
+        specifier: ^4.3.6
+        version: 4.3.6
+    devDependencies:
+      '@moonshot-ai/kimi-code-oauth':
+        specifier: workspace:^
+        version: link:../../packages/oauth
+      '@moonshot-ai/kimi-code-sdk':
+        specifier: workspace:^
+        version: link:../../packages/node-sdk
+      '@moonshot-ai/kimi-telemetry':
+        specifier: workspace:^
+        version: link:../../packages/telemetry
+      '@moonshot-ai/migration-legacy':
+        specifier: workspace:^
+        version: link:../../packages/migration-legacy
+      '@types/semver':
+        specifier: ^7.7.0
+        version: 7.7.1
+      '@types/yazl':
+        specifier: ^2.4.6
+        version: 2.4.6
+      postject:
+        specifier: 1.0.0-alpha.6
+        version: 1.0.0-alpha.6
+      tsx:
+        specifier: ^4.21.0
+        version: 4.21.0
+      yazl:
+        specifier: ^3.3.1
+        version: 3.3.1
+
+  apps/vis:
+    devDependencies:
+      concurrently:
+        specifier: ^9.1.2
+        version: 9.2.1
+
+  apps/vis/server:
+    dependencies:
+      '@hono/node-server':
+        specifier: ^1.13.7
+        version: 1.19.14(hono@4.12.14)
+      '@moonshot-ai/agent-core':
+        specifier: workspace:^
+        version: link:../../../packages/agent-core
+      hono:
+        specifier: ^4.7.7
+        version: 4.12.14
+    devDependencies:
+      tsx:
+        specifier: ^4.21.0
+        version: 4.21.0
+      vitest:
+        specifier: 4.1.4
+        version: 4.1.4(@types/node@22.19.17)(@vitest/coverage-v8@4.1.4)(vite@8.0.8(@types/node@22.19.17)(esbuild@0.27.7)(jiti@2.6.1)(tsx@4.21.0)(yaml@2.8.3))
+
+  apps/vis/web:
+    dependencies:
+      '@tanstack/react-query':
+        specifier: ^5.74.4
+        version: 5.99.2(react@19.2.5)
+      '@tanstack/react-virtual':
+        specifier: ^3.13.5
+        version: 3.13.24(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
+      react:
+        specifier: ^19.1.0
+        version: 19.2.5
+      react-dom:
+        specifier: ^19.1.0
+        version: 19.2.5(react@19.2.5)
+      react-router-dom:
+        specifier: ^7.5.2
+        version: 7.14.1(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
+    devDependencies:
+      '@tailwindcss/vite':
+        specifier: ^4.1.4
+        version: 4.2.2(vite@6.4.2(@types/node@22.19.17)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.8.3))
+      '@types/react':
+        specifier: ^19.1.2
+        version: 19.2.14
+      '@types/react-dom':
+        specifier: ^19.1.2
+        version: 19.2.3(@types/react@19.2.14)
+      '@vitejs/plugin-react':
+        specifier: ^4.4.1
+        version: 4.7.0(vite@6.4.2(@types/node@22.19.17)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.8.3))
+      tailwindcss:
+        specifier: ^4.1.4
+        version: 4.2.2
+      typescript:
+        specifier: 6.0.2
+        version: 6.0.2
+      vite:
+        specifier: ^6.3.3
+        version: 6.4.2(@types/node@22.19.17)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.8.3)
+
+  packages/agent-core:
+    dependencies:
+      '@antfu/utils':
+        specifier: ^9.3.0
+        version: 9.3.0
+      '@modelcontextprotocol/sdk':
+        specifier: ^1.29.0
+        version: 1.29.0(zod@4.3.6)
+      '@moonshot-ai/kaos':
+        specifier: workspace:^
+        version: link:../kaos
+      '@moonshot-ai/kosong':
+        specifier: workspace:^
+        version: link:../kosong
+      '@mozilla/readability':
+        specifier: ^0.6.0
+        version: 0.6.0
+      ajv:
+        specifier: ^8.18.0
+        version: 8.18.0
+      ajv-formats:
+        specifier: ^3.0.1
+        version: 3.0.1(ajv@8.18.0)
+      js-yaml:
+        specifier: ^4.1.1
+        version: 4.1.1
+      linkedom:
+        specifier: ^0.18.12
+        version: 0.18.12
+      nunjucks:
+        specifier: ^3.2.4
+        version: 3.2.4
+      open:
+        specifier: ^10.2.0
+        version: 10.2.0
+      picomatch:
+        specifier: ^4.0.4
+        version: 4.0.4
+      proper-lockfile:
+        specifier: ^4.1.2
+        version: 4.1.2
+      regexp.escape:
+        specifier: ^2.0.1
+        version: 2.0.1
+      retry:
+        specifier: 0.13.1
+        version: 0.13.1
+      smol-toml:
+        specifier: ^1.6.1
+        version: 1.6.1
+      tar:
+        specifier: ^7.5.13
+        version: 7.5.13
+      yauzl:
+        specifier: ^3.3.0
+        version: 3.3.0
+      zod:
+        specifier: 'catalog:'
+        version: 4.3.6
+    devDependencies:
+      '@types/js-yaml':
+        specifier: ^4.0.9
+        version: 4.0.9
+      '@types/nunjucks':
+        specifier: ^3.2.6
+        version: 3.2.6
+      '@types/picomatch':
+        specifier: ^4.0.3
+        version: 4.0.3
+      '@types/proper-lockfile':
+        specifier: ^4.1.4
+        version: 4.1.4
+      '@types/regexp.escape':
+        specifier: ^2.0.0
+        version: 2.0.0
+      '@types/retry':
+        specifier: 0.12.0
+        version: 0.12.0
+      '@types/tar':
+        specifier: ^7.0.87
+        version: 7.0.87
+      '@types/yauzl':
+        specifier: ^2.10.3
+        version: 2.10.3
+      '@types/yazl':
+        specifier: ^2.4.6
+        version: 2.4.6
+      yazl:
+        specifier: ^3.3.1
+        version: 3.3.1
+
+  packages/kaos:
+    dependencies:
+      ssh2:
+        specifier: ^1.17.0
+        version: 1.17.0
+    devDependencies:
+      '@types/ssh2':
+        specifier: ^1.15.5
+        version: 1.15.5
+
+  packages/kosong:
+    dependencies:
+      '@anthropic-ai/sdk':
+        specifier: ^0.95.2
+        version: 0.95.2(zod@4.3.6)
+      '@google/genai':
+        specifier: ^1.49.0
+        version: 1.49.0(@modelcontextprotocol/sdk@1.29.0(zod@4.3.6))
+      openai:
+        specifier: ^6.34.0
+        version: 6.34.0(ws@8.20.0)(zod@4.3.6)
+      zod:
+        specifier: 'catalog:'
+        version: 4.3.6
+      zod-to-json-schema:
+        specifier: ^3.25.2
+        version: 3.25.2(zod@4.3.6)
+    devDependencies:
+      ajv:
+        specifier: ^8.18.0
+        version: 8.18.0
+      ajv-formats:
+        specifier: ^3.0.1
+        version: 3.0.1(ajv@8.18.0)
+
+  packages/migration-legacy:
+    dependencies:
+      '@moonshot-ai/agent-core':
+        specifier: workspace:^
+        version: link:../agent-core
+      smol-toml:
+        specifier: ^1.6.1
+        version: 1.6.1
+      zod:
+        specifier: 'catalog:'
+        version: 4.3.6
+    devDependencies:
+      '@moonshot-ai/kaos':
+        specifier: workspace:^
+        version: link:../kaos
+
+  packages/node-sdk:
+    dependencies:
+      '@antfu/utils':
+        specifier: ^9.3.0
+        version: 9.3.0
+      smol-toml:
+        specifier: ^1.6.1
+        version: 1.6.1
+      yazl:
+        specifier: ^3.3.1
+        version: 3.3.1
+      zod:
+        specifier: 'catalog:'
+        version: 4.3.6
+    devDependencies:
+      '@moonshot-ai/agent-core':
+        specifier: workspace:^
+        version: link:../agent-core
+      '@moonshot-ai/kaos':
+        specifier: workspace:^
+        version: link:../kaos
+      '@moonshot-ai/kimi-code-oauth':
+        specifier: workspace:^
+        version: link:../oauth
+      '@moonshot-ai/kosong':
+        specifier: workspace:^
+        version: link:../kosong
+      '@types/yazl':
+        specifier: ^2.4.6
+        version: 2.4.6
+
+  packages/oauth:
+    dependencies:
+      proper-lockfile:
+        specifier: ^4.1.2
+        version: 4.1.2
+    devDependencies:
+      '@types/proper-lockfile':
+        specifier: ^4.1.4
+        version: 4.1.4
+
+  packages/telemetry: {}
+
+packages:
+
+  '@andrewbranch/untar.js@1.0.3':
+    resolution: {integrity: sha512-Jh15/qVmrLGhkKJBdXlK1+9tY4lZruYjsgkDFj08ZmDiWVBLJcqkok7Z0/R0In+i1rScBpJlSvrTS2Lm41Pbnw==}
+
+  '@antfu/utils@9.3.0':
+    resolution: {integrity: sha512-9hFT4RauhcUzqOE4f1+frMKLZrgNog5b06I7VmZQV1BkvwvqrbC8EBZf3L1eEL2AKb6rNKjER0sEvJiSP1FXEA==}
+
+  '@anthropic-ai/sdk@0.95.2':
+    resolution: {integrity: sha512-Egddwo3sheo1PzUrMkZnH6VkQYwS0h/b/i8vSK8Ta9M45UQipAMeDFH57dYuDAfXMEUUGeKw6CMlremgMZgrSQ==}
+    hasBin: true
+    peerDependencies:
+      zod: ^3.25.0 || ^4.0.0
+    peerDependenciesMeta:
+      zod:
+        optional: true
+
+  '@arethetypeswrong/cli@0.18.2':
+    resolution: {integrity: sha512-PcFM20JNlevEDKBg4Re29Rtv2xvjvQZzg7ENnrWFSS0PHgdP2njibVFw+dRUhNkPgNfac9iUqO0ohAXqQL4hbw==}
+    engines: {node: '>=20'}
+    hasBin: true
+
+  '@arethetypeswrong/core@0.18.2':
+    resolution: {integrity: sha512-GiwTmBFOU1/+UVNqqCGzFJYfBXEytUkiI+iRZ6Qx7KmUVtLm00sYySkfe203C9QtPG11yOz1ZaMek8dT/xnlgg==}
+    engines: {node: '>=20'}
+
+  '@babel/code-frame@7.29.0':
+    resolution: {integrity: sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/compat-data@7.29.0':
+    resolution: {integrity: sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/core@7.29.0':
+    resolution: {integrity: sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/generator@7.29.1':
+    resolution: {integrity: sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/generator@8.0.0-rc.5':
+    resolution: {integrity: sha512-nFZPWz3FHIS7y6rMIVoa/WBwjdutfIaRJIBQjzn+t3RnecZoRNlGmGcyR2wb0T/IgSd50Kz/6dG8/LvMCRunjg==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/helper-compilation-targets@7.28.6':
+    resolution: {integrity: sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-globals@7.28.0':
+    resolution: {integrity: sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-imports@7.28.6':
+    resolution: {integrity: sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-transforms@7.28.6':
+    resolution: {integrity: sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-plugin-utils@7.28.6':
+    resolution: {integrity: sha512-S9gzZ/bz83GRysI7gAD4wPT/AI3uCnY+9xn+Mx/KPs2JwHJIz1W8PZkg2cqyt3RNOBM8ejcXhV6y8Og7ly/Dug==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-string-parser@7.27.1':
+    resolution: {integrity: sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-string-parser@8.0.0-rc.5':
+    resolution: {integrity: sha512-sN7R8rBvDurfaziNfDEIjIntlazmlkCDGO4SNl2RJ3wRCn+QxspLV7hzYAE8WWVd2joVuT8sUxeePdLp2idI1A==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/helper-validator-identifier@7.28.5':
+    resolution: {integrity: sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-identifier@8.0.0-rc.5':
+    resolution: {integrity: sha512-ehJDxHvtbZ85RtX/L2fi0h9AGsBNqB5Euv1EB8RMAvGYvD+2X+QbpzzOpbklnNXO+WSZJNOaetw2BBj27xsWVg==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/helper-validator-option@7.27.1':
+    resolution: {integrity: sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helpers@7.29.2':
+    resolution: {integrity: sha512-HoGuUs4sCZNezVEKdVcwqmZN8GoHirLUcLaYVNBK2J0DadGtdcqgr3BCbvH8+XUo4NGjNl3VOtSjEKNzqfFgKw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/parser@7.29.2':
+    resolution: {integrity: sha512-4GgRzy/+fsBa72/RZVJmGKPmZu9Byn8o4MoLpmNe1m8ZfYnz5emHLQz3U4gLud6Zwl0RZIcgiLD7Uq7ySFuDLA==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  '@babel/parser@8.0.0-rc.4':
+    resolution: {integrity: sha512-0S/1yefMa15N4i2v3t8Fw9pgMHhf2gF6Lc1UEXI96Ls6FNAjqvHHZouZ2ZS/deqLhbMFtmfVeFac6iTsvFbLwA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+
+  '@babel/parser@8.0.0-rc.5':
+    resolution: {integrity: sha512-/Mfg83rK3+jsRbl4Vbd0jqxc6M1A1/WNFtgrowRM1unEsD3XcNnrBdMM0JWakd0/RN9lseQKwPduW1TiEwKOlQ==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+    hasBin: true
+
+  '@babel/plugin-transform-react-jsx-self@7.27.1':
+    resolution: {integrity: sha512-6UzkCs+ejGdZ5mFFC/OCUrv028ab2fp1znZmCZjAOBKiBK2jXD1O+BPSfX8X2qjJ75fZBMSnQn3Rq2mrBJK2mw==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-react-jsx-source@7.27.1':
+    resolution: {integrity: sha512-zbwoTsBruTeKB9hSq73ha66iFeJHuaFkUbwvqElnygoNbj/jHRsSeokowZFN3CZ64IvEqcmmkVe89OPXc7ldAw==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/runtime@7.29.2':
+    resolution: {integrity: sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/template@7.28.6':
+    resolution: {integrity: sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/traverse@7.29.0':
+    resolution: {integrity: sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/types@7.29.0':
+    resolution: {integrity: sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/types@8.0.0-rc.5':
+    resolution: {integrity: sha512-JeSVu/m8x/zpp4CLjYHVNXuhEyOkhPXuxM8YOXjh6L4LlvQNKuUNOTo5KdBuKAcTDHw8DquToTaEkhsBqPXOaA==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@bcoe/v8-coverage@1.0.2':
+    resolution: {integrity: sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==}
+    engines: {node: '>=18'}
+
+  '@braidai/lang@1.1.2':
+    resolution: {integrity: sha512-qBcknbBufNHlui137Hft8xauQMTZDKdophmLFv05r2eNmdIv/MlPuP4TdUknHG68UdWLgVZwgxVe735HzJNIwA==}
+
+  '@changesets/apply-release-plan@7.1.0':
+    resolution: {integrity: sha512-yq8ML3YS7koKQ/9bk1PqO0HMzApIFNwjlwCnwFEXMzNe8NpzeeYYKCmnhWJGkN8g7E51MnWaSbqRcTcdIxUgnQ==}
+
+  '@changesets/assemble-release-plan@6.0.9':
+    resolution: {integrity: sha512-tPgeeqCHIwNo8sypKlS3gOPmsS3wP0zHt67JDuL20P4QcXiw/O4Hl7oXiuLnP9yg+rXLQ2sScdV1Kkzde61iSQ==}
+
+  '@changesets/changelog-git@0.2.1':
+    resolution: {integrity: sha512-x/xEleCFLH28c3bQeQIyeZf8lFXyDFVn1SgcBiR2Tw/r4IAWlk1fzxCEZ6NxQAjF2Nwtczoen3OA2qR+UawQ8Q==}
+
+  '@changesets/changelog-github@0.7.0':
+    resolution: {integrity: sha512-rBsbRvc4TVn+FvFnOVM3LxlFJfTXXCp8gfVJ+0BubxWNSVnLuAzowi5j+IEraLLP52w8AAs9QfKbPS3MMiXQJA==}
+
+  '@changesets/cli@2.30.0':
+    resolution: {integrity: sha512-5D3Nk2JPqMI1wK25pEymeWRSlSMdo5QOGlyfrKg0AOufrUcjEE3RQgaCpHoBiM31CSNrtSgdJ0U6zL1rLDDfBA==}
+    hasBin: true
+
+  '@changesets/config@3.1.3':
+    resolution: {integrity: sha512-vnXjcey8YgBn2L1OPWd3ORs0bGC4LoYcK/ubpgvzNVr53JXV5GiTVj7fWdMRsoKUH7hhhMAQnsJUqLr21EncNw==}
+
+  '@changesets/errors@0.2.0':
+    resolution: {integrity: sha512-6BLOQUscTpZeGljvyQXlWOItQyU71kCdGz7Pi8H8zdw6BI0g3m43iL4xKUVPWtG+qrrL9DTjpdn8eYuCQSRpow==}
+
+  '@changesets/get-dependents-graph@2.1.3':
+    resolution: {integrity: sha512-gphr+v0mv2I3Oxt19VdWRRUxq3sseyUpX9DaHpTUmLj92Y10AGy+XOtV+kbM6L/fDcpx7/ISDFK6T8A/P3lOdQ==}
+
+  '@changesets/get-github-info@0.8.0':
+    resolution: {integrity: sha512-cRnC+xdF0JIik7coko3iUP9qbnfi1iJQ3sAa6dE+Tx3+ET8bjFEm63PA4WEohgjYcmsOikPHWzPsMWWiZmntOQ==}
+
+  '@changesets/get-release-plan@4.0.15':
+    resolution: {integrity: sha512-Q04ZaRPuEVZtA+auOYgFaVQQSA98dXiVe/yFaZfY7hoSmQICHGvP0TF4u3EDNHWmmCS4ekA/XSpKlSM2PyTS2g==}
+
+  '@changesets/get-version-range-type@0.4.0':
+    resolution: {integrity: sha512-hwawtob9DryoGTpixy1D3ZXbGgJu1Rhr+ySH2PvTLHvkZuQ7sRT4oQwMh0hbqZH1weAooedEjRsbrWcGLCeyVQ==}
+
+  '@changesets/git@3.0.4':
+    resolution: {integrity: sha512-BXANzRFkX+XcC1q/d27NKvlJ1yf7PSAgi8JG6dt8EfbHFHi4neau7mufcSca5zRhwOL8j9s6EqsxmT+s+/E6Sw==}
+
+  '@changesets/logger@0.1.1':
+    resolution: {integrity: sha512-OQtR36ZlnuTxKqoW4Sv6x5YIhOmClRd5pWsjZsddYxpWs517R0HkyiefQPIytCVh4ZcC5x9XaG8KTdd5iRQUfg==}
+
+  '@changesets/parse@0.4.3':
+    resolution: {integrity: sha512-ZDmNc53+dXdWEv7fqIUSgRQOLYoUom5Z40gmLgmATmYR9NbL6FJJHwakcCpzaeCy+1D0m0n7mT4jj2B/MQPl7A==}
+
+  '@changesets/pre@2.0.2':
+    resolution: {integrity: sha512-HaL/gEyFVvkf9KFg6484wR9s0qjAXlZ8qWPDkTyKF6+zqjBe/I2mygg3MbpZ++hdi0ToqNUF8cjj7fBy0dg8Ug==}
+
+  '@changesets/read@0.6.7':
+    resolution: {integrity: sha512-D1G4AUYGrBEk8vj8MGwf75k9GpN6XL3wg8i42P2jZZwFLXnlr2Pn7r9yuQNbaMCarP7ZQWNJbV6XLeysAIMhTA==}
+
+  '@changesets/should-skip-package@0.1.2':
+    resolution: {integrity: sha512-qAK/WrqWLNCP22UDdBTMPH5f41elVDlsNyat180A33dWxuUDyNpg6fPi/FyTZwRriVjg0L8gnjJn2F9XAoF0qw==}
+
+  '@changesets/types@4.1.0':
+    resolution: {integrity: sha512-LDQvVDv5Kb50ny2s25Fhm3d9QSZimsoUGBsUioj6MC3qbMUCuC8GPIvk/M6IvXx3lYhAs0lwWUQLb+VIEUCECw==}
+
+  '@changesets/types@6.1.0':
+    resolution: {integrity: sha512-rKQcJ+o1nKNgeoYRHKOS07tAMNd3YSN0uHaJOZYjBAgxfV7TUE7JE+z4BzZdQwb5hKaYbayKN5KrYV7ODb2rAA==}
+
+  '@changesets/write@0.4.0':
+    resolution: {integrity: sha512-CdTLvIOPiCNuH71pyDu3rA+Q0n65cmAbXnwWH84rKGiFumFzkmHNT8KHTMEchcxN+Kl8I54xGUhJ7l3E7X396Q==}
+
+  '@colors/colors@1.5.0':
+    resolution: {integrity: sha512-ooWCrlZP11i8GImSjTHYHLkvFDP48nS4+204nGb1RiX/WXYHmJA2III9/e2DWVabCESdW7hBAEzHRqUn9OUVvQ==}
+    engines: {node: '>=0.1.90'}
+
+  '@earendil-works/pi-tui@0.74.0':
+    resolution: {integrity: sha512-1aIfXZp7D/z+1VlZX8BZcs6pgO8rjmil7kwyhctNDsWvce3Yfl8GVgu4eq+I0Mjhr8Cj+ipBiv9CLIzdoyCOIQ==}
+    engines: {node: '>=20.0.0'}
+
+  '@emnapi/core@1.10.0':
+    resolution: {integrity: sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==}
+
+  '@emnapi/core@1.9.2':
+    resolution: {integrity: sha512-UC+ZhH3XtczQYfOlu3lNEkdW/p4dsJ1r/bP7H8+rhao3TTTMO1ATq/4DdIi23XuGoFY+Cz0JmCbdVl0hz9jZcA==}
+
+  '@emnapi/runtime@1.10.0':
+    resolution: {integrity: sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==}
+
+  '@emnapi/runtime@1.9.2':
+    resolution: {integrity: sha512-3U4+MIWHImeyu1wnmVygh5WlgfYDtyf0k8AbLhMFxOipihf6nrWC4syIm/SwEeec0mNSafiiNnMJwbza/Is6Lw==}
+
+  '@emnapi/wasi-threads@1.2.1':
+    resolution: {integrity: sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==}
+
+  '@esbuild/aix-ppc64@0.25.12':
+    resolution: {integrity: sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/aix-ppc64@0.27.7':
+    resolution: {integrity: sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.25.12':
+    resolution: {integrity: sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm64@0.27.7':
+    resolution: {integrity: sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.25.12':
+    resolution: {integrity: sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-arm@0.27.7':
+    resolution: {integrity: sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.25.12':
+    resolution: {integrity: sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/android-x64@0.27.7':
+    resolution: {integrity: sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.25.12':
+    resolution: {integrity: sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-arm64@0.27.7':
+    resolution: {integrity: sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.25.12':
+    resolution: {integrity: sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.27.7':
+    resolution: {integrity: sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.25.12':
+    resolution: {integrity: sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-arm64@0.27.7':
+    resolution: {integrity: sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.25.12':
+    resolution: {integrity: sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.27.7':
+    resolution: {integrity: sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.25.12':
+    resolution: {integrity: sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm64@0.27.7':
+    resolution: {integrity: sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.25.12':
+    resolution: {integrity: sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.27.7':
+    resolution: {integrity: sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.25.12':
+    resolution: {integrity: sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.27.7':
+    resolution: {integrity: sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.25.12':
+    resolution: {integrity: sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.27.7':
+    resolution: {integrity: sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.25.12':
+    resolution: {integrity: sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.27.7':
+    resolution: {integrity: sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.25.12':
+    resolution: {integrity: sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.27.7':
+    resolution: {integrity: sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.25.12':
+    resolution: {integrity: sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.27.7':
+    resolution: {integrity: sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.25.12':
+    resolution: {integrity: sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.27.7':
+    resolution: {integrity: sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.25.12':
+    resolution: {integrity: sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.27.7':
+    resolution: {integrity: sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.25.12':
+    resolution: {integrity: sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-arm64@0.27.7':
+    resolution: {integrity: sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.25.12':
+    resolution: {integrity: sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.27.7':
+    resolution: {integrity: sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.25.12':
+    resolution: {integrity: sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-arm64@0.27.7':
+    resolution: {integrity: sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.25.12':
+    resolution: {integrity: sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.27.7':
+    resolution: {integrity: sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.25.12':
+    resolution: {integrity: sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/openharmony-arm64@0.27.7':
+    resolution: {integrity: sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.25.12':
+    resolution: {integrity: sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/sunos-x64@0.27.7':
+    resolution: {integrity: sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.25.12':
+    resolution: {integrity: sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-arm64@0.27.7':
+    resolution: {integrity: sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.25.12':
+    resolution: {integrity: sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.27.7':
+    resolution: {integrity: sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.25.12':
+    resolution: {integrity: sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.27.7':
+    resolution: {integrity: sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@google/genai@1.49.0':
+    resolution: {integrity: sha512-hO69Zl0H3x+L0KL4stl1pLYgnqnwHoLqtKy6MRlNnW8TAxjqMdOUVafomKd4z1BePkzoxJWbYILny9a2Zk43VQ==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      '@modelcontextprotocol/sdk': ^1.25.2
+    peerDependenciesMeta:
+      '@modelcontextprotocol/sdk':
+        optional: true
+
+  '@hono/node-server@1.19.14':
+    resolution: {integrity: sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==}
+    engines: {node: '>=18.14.1'}
+    peerDependencies:
+      hono: ^4
+
+  '@inquirer/external-editor@1.0.3':
+    resolution: {integrity: sha512-RWbSrDiYmO4LbejWY7ttpxczuwQyZLBUyygsA9Nsv95hpzUWwnNTVQmAq3xuh7vNwCp07UTmE5i11XAEExx4RA==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@isaacs/fs-minipass@4.0.1':
+    resolution: {integrity: sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w==}
+    engines: {node: '>=18.0.0'}
+
+  '@jridgewell/gen-mapping@0.3.13':
+    resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
+
+  '@jridgewell/remapping@2.3.5':
+    resolution: {integrity: sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==}
+
+  '@jridgewell/resolve-uri@3.1.2':
+    resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==}
+    engines: {node: '>=6.0.0'}
+
+  '@jridgewell/sourcemap-codec@1.5.5':
+    resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
+
+  '@loaderkit/resolve@1.0.4':
+    resolution: {integrity: sha512-rJzYKVcV4dxJv+vW6jlvagF8zvGxHJ2+HTr1e2qOejfmGhAApgJHl8Aog4mMszxceTRiKTTbnpgmTO1bEZHV/A==}
+
+  '@manypkg/find-root@1.1.0':
+    resolution: {integrity: sha512-mki5uBvhHzO8kYYix/WRy2WX8S3B5wdVSc9D6KcU5lQNglP2yt58/VfLuAK49glRXChosY8ap2oJ1qgma3GUVA==}
+
+  '@manypkg/get-packages@1.1.3':
+    resolution: {integrity: sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A==}
+
+  '@mariozechner/clipboard-darwin-arm64@0.3.2':
+    resolution: {integrity: sha512-uBf6K7Je1ihsgvmWxA8UCGCeI+nbRVRXoarZdLjl6slz94Zs1tNKFZqx7aCI5O1i3e0B6ja82zZ06BWrl0MCVw==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@mariozechner/clipboard-darwin-universal@0.3.2':
+    resolution: {integrity: sha512-mxSheKTW2U9LsBdXy0SdmdCAE5HqNS9QUmpNHLnfJ+SsbFKALjEZc5oRrVMXxGQSirDvYf5bjmRyT0QYYonnlg==}
+    engines: {node: '>= 10'}
+    os: [darwin]
+
+  '@mariozechner/clipboard-darwin-x64@0.3.2':
+    resolution: {integrity: sha512-U1BcVEoidvwIp95+HJswSW+xr28EQiHR7rZjH6pn8Sja5yO4Yoe3yCN0Zm8Lo72BbSOK/fTSq0je7CJpaPCspg==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@mariozechner/clipboard-linux-arm64-gnu@0.3.2':
+    resolution: {integrity: sha512-BsinwG3yWTIjdgNCxsFlip7LkfwPk+ruw/aFCXHUg/fb5XC/Ksp+YMQ7u0LUtiKzIv/7LMXgZInJQH6gxbAaqQ==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@mariozechner/clipboard-linux-arm64-musl@0.3.2':
+    resolution: {integrity: sha512-0/Gi5Xq2V6goXBop19ePoHvXsmJD9SzFlO3S+d6+T2b+BlPcpOu3Oa0wTjl+cZrLAAEzA86aPNBI+VVAFDFPKw==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@mariozechner/clipboard-linux-riscv64-gnu@0.3.2':
+    resolution: {integrity: sha512-2AFFiXB24qf0zOZsxI1GJGb9wQGlOJyN6UwoXqmKS3dpQi/l6ix30IzDDA4c4ZcCcx4D+9HLYXhC1w7Sov8pXA==}
+    engines: {node: '>= 10'}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@mariozechner/clipboard-linux-x64-gnu@0.3.2':
+    resolution: {integrity: sha512-v6fVnsn7WMGg73Dab8QMwyFce7tzGfgEixKgzLP8f1GJqkJZi5zO4k4FOHzSgUufgLil63gnxvMpjWkgfeQN7A==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@mariozechner/clipboard-linux-x64-musl@0.3.2':
+    resolution: {integrity: sha512-xVUtnoMQ8v2JVyfJLKKXACA6avdnchdbBkTsZs8BgJQo29qwCp5NIHAUO8gbJ40iaEGToW5RlmVk2M9V0HsHEw==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@mariozechner/clipboard-win32-arm64-msvc@0.3.2':
+    resolution: {integrity: sha512-AEgg95TNi8TGgak2wSXZkXKCvAUTjWoU1Pqb0ON7JHrX78p616XUFNTJohtIon3e0w6k0pYPZeCuqRCza/Tqeg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@mariozechner/clipboard-win32-x64-msvc@0.3.2':
+    resolution: {integrity: sha512-tGRuYpZwDOD7HBrCpyRuhGnHHSCknELvqwKKUG4JSfSB7JIU7LKRh6zx6fMUOQd8uISK35TjFg5UcNih+vJhFA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
+  '@mariozechner/clipboard@0.3.2':
+    resolution: {integrity: sha512-IHQpksNjo7EAtGuHFU+tbWDp5LarH3HU/8WiB9O70ZEoBPHOg0/6afwSLK0QyNMMmx4Bpi/zl6+DcBXe95nWYA==}
+    engines: {node: '>= 10'}
+
+  '@microsoft/api-extractor-model@7.33.8':
+    resolution: {integrity: sha512-aIcoQggPyer3B6Ze3usz0YWC/oBwUHfRH5ETUsr+oT2BRA6SfTJl7IKPcPZkX4UR+PohowzW4uMxsvjrn8vm+w==}
+
+  '@microsoft/api-extractor@7.58.7':
+    resolution: {integrity: sha512-yK6OycD46gIzLRpj6ueVUWPk1ACSpkN1LBo05gY1qPTylbWyUCanXfH7+VgkI5LJrJoRSQR5F04XuCffCXLOBw==}
+    hasBin: true
+
+  '@microsoft/tsdoc-config@0.18.1':
+    resolution: {integrity: sha512-9brPoVdfN9k9g0dcWkFeA7IH9bbcttzDJlXvkf8b2OBzd5MueR1V2wkKBL0abn0otvmkHJC6aapBOTJDDeMCZg==}
+
+  '@microsoft/tsdoc@0.16.0':
+    resolution: {integrity: sha512-xgAyonlVVS+q7Vc7qLW0UrJU7rSFcETRWsqdXZtjzRU8dF+6CkozTK4V4y1LwOX7j8r/vHphjDeMeGI4tNGeGA==}
+
+  '@modelcontextprotocol/sdk@1.29.0':
+    resolution: {integrity: sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@cfworker/json-schema': ^4.1.1
+      zod: ^3.25 || ^4.0
+    peerDependenciesMeta:
+      '@cfworker/json-schema':
+        optional: true
+
+  '@mozilla/readability@0.6.0':
+    resolution: {integrity: sha512-juG5VWh4qAivzTAeMzvY9xs9HY5rAcr2E4I7tiSSCokRFi7XIZCAu92ZkSTsIj1OPceCifL3cpfteP3pDT9/QQ==}
+    engines: {node: '>=14.0.0'}
+
+  '@napi-rs/wasm-runtime@1.1.4':
+    resolution: {integrity: sha512-3NQNNgA1YSlJb/kMH1ildASP9HW7/7kYnRI2szWJaofaS1hWmbGI4H+d3+22aGzXXN9IJ+n+GiFVcGipJP18ow==}
+    peerDependencies:
+      '@emnapi/core': ^1.7.1
+      '@emnapi/runtime': ^1.7.1
+
+  '@nodelib/fs.scandir@2.1.5':
+    resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.stat@2.0.5':
+    resolution: {integrity: sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.walk@1.2.8':
+    resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==}
+    engines: {node: '>= 8'}
+
+  '@oxc-project/types@0.122.0':
+    resolution: {integrity: sha512-oLAl5kBpV4w69UtFZ9xqcmTi+GENWOcPF7FCrczTiBbmC0ibXxCwyvZGbO39rCVEuLGAZM84DH0pUIyyv/YJzA==}
+
+  '@oxc-project/types@0.124.0':
+    resolution: {integrity: sha512-VBFWMTBvHxS11Z5Lvlr3IWgrwhMTXV+Md+EQF0Xf60+wAdsGFTBx7X7K/hP4pi8N7dcm1RvcHwDxZ16Qx8keUg==}
+
+  '@oxc-project/types@0.130.0':
+    resolution: {integrity: sha512-ibD2usx9JRu7f5pu2tMKMI4cpA4NgXJQoYRP4pQ7Pxmn1l6k/53qWtQWZayhYy3X4QZkt90Ot+mJEaeXouio6Q==}
+
+  '@oxlint-tsgolint/darwin-arm64@0.20.0':
+    resolution: {integrity: sha512-KKQcIHZHMxqpHUA1VXIbOG6chNCFkUWbQy6M+AFVtPKkA/3xAeJkJ3njoV66bfzwPHRcWQO+kcj5XqtbkjakoA==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@oxlint-tsgolint/darwin-x64@0.20.0':
+    resolution: {integrity: sha512-7HeVMuclGfG+NLZi2ybY0T4fMI7/XxO/208rJk+zEIloKkVnlh11Wd241JMGwgNFXn+MLJbOqOfojDb2Dt4L1g==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@oxlint-tsgolint/linux-arm64@0.20.0':
+    resolution: {integrity: sha512-zxhUwz+WSxE6oWlZLK2z2ps9yC6ebmgoYmjAl0Oa48+GqkZ56NVgo+wb8DURNv6xrggzHStQxqQxe3mK51HZag==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@oxlint-tsgolint/linux-x64@0.20.0':
+    resolution: {integrity: sha512-/1l6FnahC9im8PK+Ekkx/V3yetO/PzZnJegE2FXcv/iXEhbeVxP/ouiTYcUQu9shT1FWJCSNti1VJHH+21Y1dg==}
+    cpu: [x64]
+    os: [linux]
+
+  '@oxlint-tsgolint/win32-arm64@0.20.0':
+    resolution: {integrity: sha512-oPZ5Yz8sVdo7P/5q+i3IKeix31eFZ55JAPa1+RGPoe9PoaYVsdMvR6Jvib6YtrqoJnFPlg3fjEjlEPL8VBKYJA==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@oxlint-tsgolint/win32-x64@0.20.0':
+    resolution: {integrity: sha512-4stx8RHj3SP9vQyRF/yZbz5igtPvYMEUR8CUoha4BVNZihi39DpCR8qkU7lpjB5Ga1DRMo2pHaA4bdTOMaY4mw==}
+    cpu: [x64]
+    os: [win32]
+
+  '@oxlint/binding-android-arm-eabi@1.59.0':
+    resolution: {integrity: sha512-etYDw/UaEv936AQUd/CRMBVd+e+XuuU6wC+VzOv1STvsTyZenLChepLWqLtnyTTp4YMlM22ypzogDDwqYxv5cg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [android]
+
+  '@oxlint/binding-android-arm64@1.59.0':
+    resolution: {integrity: sha512-TgLc7XVLKH2a4h8j3vn1MDjfK33i9MY60f/bKhRGWyVzbk5LCZ4X01VZG7iHrMmi5vYbAp8//Ponigx03CLsdw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@oxlint/binding-darwin-arm64@1.59.0':
+    resolution: {integrity: sha512-DXyFPf5ZKldMLloRHx/B9fsxsiTQomaw7cmEW3YIJko2HgCh+GUhp9gGYwHrqlLJPsEe3dYj9JebjX92D3j3AA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@oxlint/binding-darwin-x64@1.59.0':
+    resolution: {integrity: sha512-LgvrsdgVLX1qWqIEmNsSmMXJhpAWdtUQ0M+oR0CySwi+9IHWyOGuIL8w8+u/kbZNMyZr4WUyYB5i0+D+AKgkLg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@oxlint/binding-freebsd-x64@1.59.0':
+    resolution: {integrity: sha512-bOJhqX/ny4hrFuTPlyk8foSRx/vLRpxJh0jOOKN2NWW6FScXHPAA5rQbrwdQPcgGB5V8Ua51RS03fke8ssBcug==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@oxlint/binding-linux-arm-gnueabihf@1.59.0':
+    resolution: {integrity: sha512-vVUXxYMF9trXCsz4m9H6U0IjehosVHxBzVgJUxly1uz4W1PdDyicaBnpC0KRXsHYretLVe+uS9pJy8iM57Kujw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@oxlint/binding-linux-arm-musleabihf@1.59.0':
+    resolution: {integrity: sha512-TULQW8YBPGRWg5yZpFPL54HLOnJ3/HiX6VenDPi6YfxB/jlItwSMFh3/hCeSNbh+DAMaE1Py0j5MOaivHkI/9Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@oxlint/binding-linux-arm64-gnu@1.59.0':
+    resolution: {integrity: sha512-Gt54Y4eqSgYJ90xipm24xeyaPV854706o/kiT8oZvUt3VDY7qqxdqyGqchMaujd87ib+/MXvnl9WkK8Cc1BExg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxlint/binding-linux-arm64-musl@1.59.0':
+    resolution: {integrity: sha512-3CtsKp7NFB3OfqQzbuAecrY7GIZeiv7AD+xutU4tefVQzlfmTI7/ygWLrvkzsDEjTlMq41rYHxgsn6Yh8tybmA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@oxlint/binding-linux-ppc64-gnu@1.59.0':
+    resolution: {integrity: sha512-K0diOpT3ncDmOfl9I1HuvpEsAuTxkts0VYwIv/w6Xiy9CdwyPBVX88Ga9l8VlGgMrwBMnSY4xIvVlVY/fkQk7Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxlint/binding-linux-riscv64-gnu@1.59.0':
+    resolution: {integrity: sha512-xAU7+QDU6kTJJ7mJLOGgo7oOjtAtkKyFZ0Yjdb5cEo3DiCCPFLvyr08rWiQh6evZ7RiUTf+o65NY/bqttzJiQQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxlint/binding-linux-riscv64-musl@1.59.0':
+    resolution: {integrity: sha512-KUmZmKlTTyauOnvUNVxK7G40sSSx0+w5l1UhaGsC6KPpOYHenx2oqJTnabmpLJicok7IC+3Y6fXAUOMyexaeJQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [musl]
+
+  '@oxlint/binding-linux-s390x-gnu@1.59.0':
+    resolution: {integrity: sha512-4usRxC8gS0PGdkHnRmwJt/4zrQNZyk6vL0trCxwZSsAKM+OxhB8nKiR+mhjdBbl8lbMh2gc3bZpNN/ik8c4c2A==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxlint/binding-linux-x64-gnu@1.59.0':
+    resolution: {integrity: sha512-s/rNE2gDmbwAOOP493xk2X7M8LZfI1LJFSSW1+yanz3vuQCFPiHkx4GY+O1HuLUDtkzGlhtMrIcxxzyYLv308w==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxlint/binding-linux-x64-musl@1.59.0':
+    resolution: {integrity: sha512-+yYj1udJa2UvvIUmEm0IcKgc0UlPMgz0nsSTvkPL2y6n0uU5LgIHSwVu4AHhrve6j9BpVSoRksnz8c9QcvITJA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@oxlint/binding-openharmony-arm64@1.59.0':
+    resolution: {integrity: sha512-bUplUb48LYsB3hHlQXP2ZMOenpieWoOyppLAnnAhuPag3MGPnt+7caxE3w/Vl9wpQsTA3gzLntQi9rxWrs7Xqg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@oxlint/binding-win32-arm64-msvc@1.59.0':
+    resolution: {integrity: sha512-/HLsLuz42rWl7h7ePdmMTpHm2HIDmPtcEMYgm5BBEHiEiuNOrzMaUpd2z7UnNni5LGN9obJy2YoAYBLXQwazrA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@oxlint/binding-win32-ia32-msvc@1.59.0':
+    resolution: {integrity: sha512-rUPy+JnanpPwV/aJCPnxAD1fW50+XPI0VkWr7f0vEbqcdsS8NpB24Rw6RsS7SdpFv8Dw+8ugCwao5nCFbqOUSg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ia32]
+    os: [win32]
+
+  '@oxlint/binding-win32-x64-msvc@1.59.0':
+    resolution: {integrity: sha512-xkE7puteDS/vUyRngLXW0t8WgdWoS/tfxXjhP/P7SMqPDx+hs44SpssO3h3qmTqECYEuXBUPzcAw5257Ka+ofA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@protobufjs/aspromise@1.1.2':
+    resolution: {integrity: sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==}
+
+  '@protobufjs/base64@1.1.2':
+    resolution: {integrity: sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==}
+
+  '@protobufjs/codegen@2.0.4':
+    resolution: {integrity: sha512-YyFaikqM5sH0ziFZCN3xDC7zeGaB/d0IUb9CATugHWbd1FRFwWwt4ld4OYMPWu5a3Xe01mGAULCdqhMlPl29Jg==}
+
+  '@protobufjs/eventemitter@1.1.0':
+    resolution: {integrity: sha512-j9ednRT81vYJ9OfVuXG6ERSTdEL1xVsNgqpkxMsbIabzSo3goCjDIveeGv5d03om39ML71RdmrGNjG5SReBP/Q==}
+
+  '@protobufjs/fetch@1.1.0':
+    resolution: {integrity: sha512-lljVXpqXebpsijW71PZaCYeIcE5on1w5DlQy5WH6GLbFryLUrBD4932W/E2BSpfRJWseIL4v/KPgBFxDOIdKpQ==}
+
+  '@protobufjs/float@1.0.2':
+    resolution: {integrity: sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==}
+
+  '@protobufjs/inquire@1.1.0':
+    resolution: {integrity: sha512-kdSefcPdruJiFMVSbn801t4vFK7KB/5gd2fYvrxhuJYg8ILrmn9SKSX2tZdV6V+ksulWqS7aXjBcRXl3wHoD9Q==}
+
+  '@protobufjs/path@1.1.2':
+    resolution: {integrity: sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==}
+
+  '@protobufjs/pool@1.1.0':
+    resolution: {integrity: sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==}
+
+  '@protobufjs/utf8@1.1.0':
+    resolution: {integrity: sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw==}
+
+  '@publint/pack@0.1.4':
+    resolution: {integrity: sha512-HDVTWq3H0uTXiU0eeSQntcVUTPP3GamzeXI41+x7uU9J65JgWQh3qWZHblR1i0npXfFtF+mxBiU2nJH8znxWnQ==}
+    engines: {node: '>=18'}
+
+  '@quansync/fs@1.0.0':
+    resolution: {integrity: sha512-4TJ3DFtlf1L5LDMaM6CanJ/0lckGNtJcMjQ1NAV6zDmA0tEHKZtxNKin8EgPaVX1YzljbxckyT2tJrpQKAtngQ==}
+
+  '@rolldown/binding-android-arm64@1.0.0-rc.12':
+    resolution: {integrity: sha512-pv1y2Fv0JybcykuiiD3qBOBdz6RteYojRFY1d+b95WVuzx211CRh+ytI/+9iVyWQ6koTh5dawe4S/yRfOFjgaA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@rolldown/binding-android-arm64@1.0.0-rc.15':
+    resolution: {integrity: sha512-YYe6aWruPZDtHNpwu7+qAHEMbQ/yRl6atqb/AhznLTnD3UY99Q1jE7ihLSahNWkF4EqRPVC4SiR4O0UkLK02tA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@rolldown/binding-android-arm64@1.0.1':
+    resolution: {integrity: sha512-fJI3I0r3C3Oj/zdBCpaCmBRZYf07xpaq4yCfDDoSFm+beWNzbIl26puW8RraUdugoJw/95zerNOn6jasAhzSmg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@rolldown/binding-darwin-arm64@1.0.0-rc.12':
+    resolution: {integrity: sha512-cFYr6zTG/3PXXF3pUO+umXxt1wkRK/0AYT8lDwuqvRC+LuKYWSAQAQZjCWDQpAH172ZV6ieYrNnFzVVcnSflAg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rolldown/binding-darwin-arm64@1.0.0-rc.15':
+    resolution: {integrity: sha512-oArR/ig8wNTPYsXL+Mzhs0oxhxfuHRfG7Ikw7jXsw8mYOtk71W0OkF2VEVh699pdmzjPQsTjlD1JIOoHkLP1Fg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rolldown/binding-darwin-arm64@1.0.1':
+    resolution: {integrity: sha512-cKnAhWEsV7TPcA/5EAteDp6KcJZBQ2G+BqE7zayMMi7kMvwRsbv7WT9aOnn0WNl4SKEIf43vjS31iUPu80nzXg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rolldown/binding-darwin-x64@1.0.0-rc.12':
+    resolution: {integrity: sha512-ZCsYknnHzeXYps0lGBz8JrF37GpE9bFVefrlmDrAQhOEi4IOIlcoU1+FwHEtyXGx2VkYAvhu7dyBf75EJQffBw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rolldown/binding-darwin-x64@1.0.0-rc.15':
+    resolution: {integrity: sha512-YzeVqOqjPYvUbJSWJ4EDL8ahbmsIXQpgL3JVipmN+MX0XnXMeWomLN3Fb+nwCmP/jfyqte5I3XRSm7OfQrbyxw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rolldown/binding-darwin-x64@1.0.1':
+    resolution: {integrity: sha512-YKrVwQjIRBPo+5G/u03wGjbdy4q7pyzCe93DK9VJ7zkVmeg8LJ7GbgsiHWdR4xSoe4CAXRD7Bcjgbtr64bkXNg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rolldown/binding-freebsd-x64@1.0.0-rc.12':
+    resolution: {integrity: sha512-dMLeprcVsyJsKolRXyoTH3NL6qtsT0Y2xeuEA8WQJquWFXkEC4bcu1rLZZSnZRMtAqwtrF/Ib9Ddtpa/Gkge9Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rolldown/binding-freebsd-x64@1.0.0-rc.15':
+    resolution: {integrity: sha512-9Erhx956jeQ0nNTyif1+QWAXDRD38ZNjr//bSHrt6wDwB+QkAfl2q6Mn1k6OBPerznjRmbM10lgRb1Pli4xZPw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rolldown/binding-freebsd-x64@1.0.1':
+    resolution: {integrity: sha512-z/oBsREo46SsFqBwYtFe0kpJeBijAT48O/WXLI4suiCLBkr03RTtTJMCzSdDd2znlh8VJizL09XVkQgk8IZonw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.0.0-rc.12':
+    resolution: {integrity: sha512-YqWjAgGC/9M1lz3GR1r1rP79nMgo3mQiiA+Hfo+pvKFK1fAJ1bCi0ZQVh8noOqNacuY1qIcfyVfP6HoyBRZ85Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.0.0-rc.15':
+    resolution: {integrity: sha512-cVwk0w8QbZJGTnP/AHQBs5yNwmpgGYStL88t4UIaqcvYJWBfS0s3oqVLZPwsPU6M0zlW4GqjP0Zq5MnAGwFeGA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.0.1':
+    resolution: {integrity: sha512-ik8q7GM11zxvYxFc2PeDcT6TBvhCQMaUxfph/M5l9sKuTs/Sjg3L+Byw0F7w0ZVLBZmx30P+gG0ECzzN+MFcmQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm64-gnu@1.0.0-rc.12':
+    resolution: {integrity: sha512-/I5AS4cIroLpslsmzXfwbe5OmWvSsrFuEw3mwvbQ1kDxJ822hFHIx+vsN/TAzNVyepI/j/GSzrtCIwQPeKCLIg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-arm64-gnu@1.0.0-rc.15':
+    resolution: {integrity: sha512-eBZ/u8iAK9SoHGanqe/jrPnY0JvBN6iXbVOsbO38mbz+ZJsaobExAm1Iu+rxa4S1l2FjG0qEZn4Rc6X8n+9M+w==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-arm64-gnu@1.0.1':
+    resolution: {integrity: sha512-QoSx2EkyrrdZ6kcyE8stqZ62t0Yra8Fs5ia9lOxJrh6TMQJK7gQKmscdTHf7pOXKREKrVwOtJcQG3qVSfc866A==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-arm64-musl@1.0.0-rc.12':
+    resolution: {integrity: sha512-V6/wZztnBqlx5hJQqNWwFdxIKN0m38p8Jas+VoSfgH54HSj9tKTt1dZvG6JRHcjh6D7TvrJPWFGaY9UBVOaWPw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-linux-arm64-musl@1.0.0-rc.15':
+    resolution: {integrity: sha512-ZvRYMGrAklV9PEkgt4LQM6MjQX2P58HPAuecwYObY2DhS2t35R0I810bKi0wmaYORt6m/2Sm+Z+nFgb0WhXNcQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-linux-arm64-musl@1.0.1':
+    resolution: {integrity: sha512-uwNwFpwKeNiZawfAWBgg0VIztPTV3ihhh1vV334h9ivnNLorxnQMU6Fz8wG1Zb4Qh9LC1/MkcyT3YlDXG3Rsgg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-linux-ppc64-gnu@1.0.0-rc.12':
+    resolution: {integrity: sha512-AP3E9BpcUYliZCxa3w5Kwj9OtEVDYK6sVoUzy4vTOJsjPOgdaJZKFmN4oOlX0Wp0RPV2ETfmIra9x1xuayFB7g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-ppc64-gnu@1.0.0-rc.15':
+    resolution: {integrity: sha512-VDpgGBzgfg5hLg+uBpCLoFG5kVvEyafmfxGUV0UHLcL5irxAK7PKNeC2MwClgk6ZAiNhmo9FLhRYgvMmedLtnQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-ppc64-gnu@1.0.1':
+    resolution: {integrity: sha512-zY1bul7OWr7DFBiJ++wofXvnr8B45ce3QsQUhKrIhXsygAh7bTkwyeM1bi1a2g5C/yC/N8TZyGDEoMfm/l9mpg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-s390x-gnu@1.0.0-rc.12':
+    resolution: {integrity: sha512-nWwpvUSPkoFmZo0kQazZYOrT7J5DGOJ/+QHHzjvNlooDZED8oH82Yg67HvehPPLAg5fUff7TfWFHQS8IV1n3og==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-s390x-gnu@1.0.0-rc.15':
+    resolution: {integrity: sha512-y1uXY3qQWCzcPgRJATPSOUP4tCemh4uBdY7e3EZbVwCJTY3gLJWnQABgeUetvED+bt1FQ01OeZwvhLS2bpNrAQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-s390x-gnu@1.0.1':
+    resolution: {integrity: sha512-0frlsT/f4Ft6I7SMESTKnF3cZsdicQn1dCMkF/jT9wDLE+gGoiQfv1nmT9e+s7s/fekvvy6tZM2jHvI2tkbJDQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-gnu@1.0.0-rc.12':
+    resolution: {integrity: sha512-RNrafz5bcwRy+O9e6P8Z/OCAJW/A+qtBczIqVYwTs14pf4iV1/+eKEjdOUta93q2TsT/FI0XYDP3TCky38LMAg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-gnu@1.0.0-rc.15':
+    resolution: {integrity: sha512-023bTPBod7J3Y/4fzAN6QtpkSABR0rigtrwaP+qSEabUh5zf6ELr9Nc7GujaROuPY3uwdSIXWrvhn1KxOvurWA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-gnu@1.0.1':
+    resolution: {integrity: sha512-XABVmGp9Tg0WspTVvwduTc4fpqy6JnAUrSQe6OuyqD/03nI7r0O9OWUkMIwFrjKAIqolvqoA4ZrJppgwE0Gxmw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-musl@1.0.0-rc.12':
+    resolution: {integrity: sha512-Jpw/0iwoKWx3LJ2rc1yjFrj+T7iHZn2JDg1Yny1ma0luviFS4mhAIcd1LFNxK3EYu3DHWCps0ydXQ5i/rrJ2ig==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-linux-x64-musl@1.0.0-rc.15':
+    resolution: {integrity: sha512-witB2O0/hU4CgfOOKUoeFgQ4GktPi1eEbAhaLAIpgD6+ZnhcPkUtPsoKKHRzmOoWPZue46IThdSgdo4XneOLYw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-linux-x64-musl@1.0.1':
+    resolution: {integrity: sha512-bV4fzswuzVcKD90o/VM6QqKxnxlDq0g2BISDLNVmxrnhpv1DDbyPhCIjYfvzYLV+MvkKKnQt2Q6AO86SEBULUQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-openharmony-arm64@1.0.0-rc.12':
+    resolution: {integrity: sha512-vRugONE4yMfVn0+7lUKdKvN4D5YusEiPilaoO2sgUWpCvrncvWgPMzK00ZFFJuiPgLwgFNP5eSiUlv2tfc+lpA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rolldown/binding-openharmony-arm64@1.0.0-rc.15':
+    resolution: {integrity: sha512-UCL68NJ0Ud5zRipXZE9dF5PmirzJE4E4BCIOOssEnM7wLDsxjc6Qb0sGDxTNRTP53I6MZpygyCpY8Aa8sPfKPg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rolldown/binding-openharmony-arm64@1.0.1':
+    resolution: {integrity: sha512-/Mh0Zhq3OP7fVs0kcQHZP6lZEthMGTaSf8UBQYSFEZDWGXXlEC+nJ6EqenaK2t4LBXMe3A+K/G2BVXXdtOr4PQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rolldown/binding-wasm32-wasi@1.0.0-rc.12':
+    resolution: {integrity: sha512-ykGiLr/6kkiHc0XnBfmFJuCjr5ZYKKofkx+chJWDjitX+KsJuAmrzWhwyOMSHzPhzOHOy7u9HlFoa5MoAOJ/Zg==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+
+  '@rolldown/binding-wasm32-wasi@1.0.0-rc.15':
+    resolution: {integrity: sha512-ApLruZq/ig+nhaE7OJm4lDjayUnOHVUa77zGeqnqZ9pn0ovdVbbNPerVibLXDmWeUZXjIYIT8V3xkT58Rm9u5Q==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+
+  '@rolldown/binding-wasm32-wasi@1.0.1':
+    resolution: {integrity: sha512-+1xc9X45l8ufsBAm6Gjvx2qDRIY9lTVt0cgWNcJ+1gdhXvkbxePA60yRTwSTuXL09CMhyJmjpV7E3NoyxbqFQQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [wasm32]
+
+  '@rolldown/binding-win32-arm64-msvc@1.0.0-rc.12':
+    resolution: {integrity: sha512-5eOND4duWkwx1AzCxadcOrNeighiLwMInEADT0YM7xeEOOFcovWZCq8dadXgcRHSf3Ulh1kFo/qvzoFiCLOL1Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rolldown/binding-win32-arm64-msvc@1.0.0-rc.15':
+    resolution: {integrity: sha512-KmoUoU7HnN+Si5YWJigfTws1jz1bKBYDQKdbLspz0UaqjjFkddHsqorgiW1mxcAj88lYUE6NC/zJNwT+SloqtA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rolldown/binding-win32-arm64-msvc@1.0.1':
+    resolution: {integrity: sha512-1D+UqZdfnuR+Jy1GgMJwi85bD40H21uNmOPRWQhw4oRSuolZ/B5rixZ45DK2KXOTCvmVCecauWgEhbw8bI7tOw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rolldown/binding-win32-x64-msvc@1.0.0-rc.12':
+    resolution: {integrity: sha512-PyqoipaswDLAZtot351MLhrlrh6lcZPo2LSYE+VDxbVk24LVKAGOuE4hb8xZQmrPAuEtTZW8E6D2zc5EUZX4Lw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@rolldown/binding-win32-x64-msvc@1.0.0-rc.15':
+    resolution: {integrity: sha512-3P2A8L+x75qavWLe/Dll3EYBJLQmtkJN8rfh+U/eR3MqMgL/h98PhYI+JFfXuDPgPeCB7iZAKiqii5vqOvnA0g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@rolldown/binding-win32-x64-msvc@1.0.1':
+    resolution: {integrity: sha512-INAycaWuhlOK3wk4mRHGsdgwYWmd9cChdPdE9bwWmy6rn9VqVNYNFGhOdXrofXUxwHIncSiPNb8tNm8knDVIeQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@rolldown/pluginutils@1.0.0-beta.27':
+    resolution: {integrity: sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA==}
+
+  '@rolldown/pluginutils@1.0.0-rc.12':
+    resolution: {integrity: sha512-HHMwmarRKvoFsJorqYlFeFRzXZqCt2ETQlEDOb9aqssrnVBB1/+xgTGtuTrIk5vzLNX1MjMtTf7W9z3tsSbrxw==}
+
+  '@rolldown/pluginutils@1.0.0-rc.15':
+    resolution: {integrity: sha512-UromN0peaE53IaBRe9W7CjrZgXl90fqGpK+mIZbA3qSTeYqg3pqpROBdIPvOG3F5ereDHNwoHBI2e50n1BDr1g==}
+
+  '@rolldown/pluginutils@1.0.1':
+    resolution: {integrity: sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==}
+
+  '@rollup/rollup-android-arm-eabi@4.60.2':
+    resolution: {integrity: sha512-dnlp69efPPg6Uaw2dVqzWRfAWRnYVb1XJ8CyyhIbZeaq4CA5/mLeZ1IEt9QqQxmbdvagjLIm2ZL8BxXv5lH4Yw==}
+    cpu: [arm]
+    os: [android]
+
+  '@rollup/rollup-android-arm64@4.60.2':
+    resolution: {integrity: sha512-OqZTwDRDchGRHHm/hwLOL7uVPB9aUvI0am/eQuWMNyFHf5PSEQmyEeYYheA0EPPKUO/l0uigCp+iaTjoLjVoHg==}
+    cpu: [arm64]
+    os: [android]
+
+  '@rollup/rollup-darwin-arm64@4.60.2':
+    resolution: {integrity: sha512-UwRE7CGpvSVEQS8gUMBe1uADWjNnVgP3Iusyda1nSRwNDCsRjnGc7w6El6WLQsXmZTbLZx9cecegumcitNfpmA==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rollup/rollup-darwin-x64@4.60.2':
+    resolution: {integrity: sha512-gjEtURKLCC5VXm1I+2i1u9OhxFsKAQJKTVB8WvDAHF+oZlq0GTVFOlTlO1q3AlCTE/DF32c16ESvfgqR7343/g==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rollup/rollup-freebsd-arm64@4.60.2':
+    resolution: {integrity: sha512-Bcl6CYDeAgE70cqZaMojOi/eK63h5Me97ZqAQoh77VPjMysA/4ORQBRGo3rRy45x4MzVlU9uZxs8Uwy7ZaKnBw==}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@rollup/rollup-freebsd-x64@4.60.2':
+    resolution: {integrity: sha512-LU+TPda3mAE2QB0/Hp5VyeKJivpC6+tlOXd1VMoXV/YFMvk/MNk5iXeBfB4MQGRWyOYVJ01625vjkr0Az98OJQ==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rollup/rollup-linux-arm-gnueabihf@4.60.2':
+    resolution: {integrity: sha512-2QxQrM+KQ7DAW4o22j+XZ6RKdxjLD7BOWTP0Bv0tmjdyhXSsr2Ul1oJDQqh9Zf5qOwTuTc7Ek83mOFaKnodPjg==}
+    cpu: [arm]
+    os: [linux]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-arm-musleabihf@4.60.2':
+    resolution: {integrity: sha512-TbziEu2DVsTEOPif2mKWkMeDMLoYjx95oESa9fkQQK7r/Orta0gnkcDpzwufEcAO2BLBsD7mZkXGFqEdMRRwfw==}
+    cpu: [arm]
+    os: [linux]
+    libc: [musl]
+
+  '@rollup/rollup-linux-arm64-gnu@4.60.2':
+    resolution: {integrity: sha512-bO/rVDiDUuM2YfuCUwZ1t1cP+/yqjqz+Xf2VtkdppefuOFS2OSeAfgafaHNkFn0t02hEyXngZkxtGqXcXwO8Rg==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-arm64-musl@4.60.2':
+    resolution: {integrity: sha512-hr26p7e93Rl0Za+JwW7EAnwAvKkehh12BU1Llm9Ykiibg4uIr2rbpxG9WCf56GuvidlTG9KiiQT/TXT1yAWxTA==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@rollup/rollup-linux-loong64-gnu@4.60.2':
+    resolution: {integrity: sha512-pOjB/uSIyDt+ow3k/RcLvUAOGpysT2phDn7TTUB3n75SlIgZzM6NKAqlErPhoFU+npgY3/n+2HYIQVbF70P9/A==}
+    cpu: [loong64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-loong64-musl@4.60.2':
+    resolution: {integrity: sha512-2/w+q8jszv9Ww1c+6uJT3OwqhdmGP2/4T17cu8WuwyUuuaCDDJ2ojdyYwZzCxx0GcsZBhzi3HmH+J5pZNXnd+Q==}
+    cpu: [loong64]
+    os: [linux]
+    libc: [musl]
+
+  '@rollup/rollup-linux-ppc64-gnu@4.60.2':
+    resolution: {integrity: sha512-11+aL5vKheYgczxtPVVRhdptAM2H7fcDR5Gw4/bTcteuZBlH4oP9f5s9zYO9aGZvoGeBpqXI/9TZZihZ609wKw==}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-ppc64-musl@4.60.2':
+    resolution: {integrity: sha512-i16fokAGK46IVZuV8LIIwMdtqhin9hfYkCh8pf8iC3QU3LpwL+1FSFGej+O7l3E/AoknL6Dclh2oTdnRMpTzFQ==}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [musl]
+
+  '@rollup/rollup-linux-riscv64-gnu@4.60.2':
+    resolution: {integrity: sha512-49FkKS6RGQoriDSK/6E2GkAsAuU5kETFCh7pG4yD/ylj9rKhTmO3elsnmBvRD4PgJPds5W2PkhC82aVwmUcJ7A==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-riscv64-musl@4.60.2':
+    resolution: {integrity: sha512-mjYNkHPfGpUR00DuM1ZZIgs64Hpf4bWcz9Z41+4Q+pgDx73UwWdAYyf6EG/lRFldmdHHzgrYyge5akFUW0D3mQ==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [musl]
+
+  '@rollup/rollup-linux-s390x-gnu@4.60.2':
+    resolution: {integrity: sha512-ALyvJz965BQk8E9Al/JDKKDLH2kfKFLTGMlgkAbbYtZuJt9LU8DW3ZoDMCtQpXAltZxwBHevXz5u+gf0yA0YoA==}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-x64-gnu@4.60.2':
+    resolution: {integrity: sha512-UQjrkIdWrKI626Du8lCQ6MJp/6V1LAo2bOK9OTu4mSn8GGXIkPXk/Vsp4bLHCd9Z9Iz2OTEaokUE90VweJgIYQ==}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rollup/rollup-linux-x64-musl@4.60.2':
+    resolution: {integrity: sha512-bTsRGj6VlSdn/XD4CGyzMnzaBs9bsRxy79eTqTCBsA8TMIEky7qg48aPkvJvFe1HyzQ5oMZdg7AnVlWQSKLTnw==}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@rollup/rollup-openbsd-x64@4.60.2':
+    resolution: {integrity: sha512-6d4Z3534xitaA1FcMWP7mQPq5zGwBmGbhphh2DwaA1aNIXUu3KTOfwrWpbwI4/Gr0uANo7NTtaykFyO2hPuFLg==}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@rollup/rollup-openharmony-arm64@4.60.2':
+    resolution: {integrity: sha512-NetAg5iO2uN7eB8zE5qrZ3CSil+7IJt4WDFLcC75Ymywq1VZVD6qJ6EvNLjZ3rEm6gB7XW5JdT60c6MN35Z85Q==}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rollup/rollup-win32-arm64-msvc@4.60.2':
+    resolution: {integrity: sha512-NCYhOotpgWZ5kdxCZsv6Iudx0wX8980Q/oW4pNFNihpBKsDbEA1zpkfxJGC0yugsUuyDZ7gL37dbzwhR0VI7pQ==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rollup/rollup-win32-ia32-msvc@4.60.2':
+    resolution: {integrity: sha512-RXsaOqXxfoUBQoOgvmmijVxJnW2IGB0eoMO7F8FAjaj0UTywUO/luSqimWBJn04WNgUkeNhh7fs7pESXajWmkg==}
+    cpu: [ia32]
+    os: [win32]
+
+  '@rollup/rollup-win32-x64-gnu@4.60.2':
+    resolution: {integrity: sha512-qdAzEULD+/hzObedtmV6iBpdL5TIbKVztGiK7O3/KYSf+HIzU257+MX1EXJcyIiDbMAqmbwaufcYPvyRryeZtA==}
+    cpu: [x64]
+    os: [win32]
+
+  '@rollup/rollup-win32-x64-msvc@4.60.2':
+    resolution: {integrity: sha512-Nd/SgG27WoA9e+/TdK74KnHz852TLa94ovOYySo/yMPuTmpckK/jIF2jSwS3g7ELSKXK13/cVdmg1Z/DaCWKxA==}
+    cpu: [x64]
+    os: [win32]
+
+  '@rushstack/node-core-library@5.23.1':
+    resolution: {integrity: sha512-wlKmIKIYCKuCASbITvOxLZXepPbwXvrv7S6ig6XNWFchSyhL/E2txmVXspHY49Wu2dzf7nI27a2k/yV5BA3EiA==}
+    peerDependencies:
+      '@types/node': '*'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@rushstack/problem-matcher@0.2.1':
+    resolution: {integrity: sha512-gulfhBs6n+I5b7DvjKRfhMGyUejtSgOHTclF/eONr8hcgF1APEDjhxIsfdUYYMzC3rvLwGluqLjbwCFZ8nxrog==}
+    peerDependencies:
+      '@types/node': '*'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@rushstack/rig-package@0.7.3':
+    resolution: {integrity: sha512-aAA518n6wxxjCfnTAOjQnm7ngNE0FVHxHAw2pxKlIhxrMn0XQjGcXKF0oKWpjBgJOmsaJpVob/v+zr3zxgPWuA==}
+
+  '@rushstack/terminal@0.24.0':
+    resolution: {integrity: sha512-8ZQS4MMaGsv27EXCBiH7WMPkRZrffeDoIevs6z9TM5dzqiY6+Hn4evfK/G+gvgBTjfvfkHIZPQQmalmI2sM4TQ==}
+    peerDependencies:
+      '@types/node': '*'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@rushstack/ts-command-line@5.3.9':
+    resolution: {integrity: sha512-GIHqU+sRGQ3LGWAZu1O+9Yh++qwtyNIIGuNbcWHJjBTm2qRez0cwINUHZ+pQLR8UuzZDcMajrDaNbUYoaL/XtQ==}
+
+  '@sindresorhus/is@4.6.0':
+    resolution: {integrity: sha512-t09vSN3MdfsyCHoFcTRCH/iUtG7OJ0CsjzB8cjAmKc/va/kIgeDI/TxsigdncE/4be734m0cvIYwNaV4i2XqAw==}
+    engines: {node: '>=10'}
+
+  '@stablelib/base64@1.0.1':
+    resolution: {integrity: sha512-1bnPQqSxSuc3Ii6MhBysoWCg58j97aUjuCSZrGSmDxNqtytIi0k8utUenAwTZN4V5mXXYGsVUI9zeBqy+jBOSQ==}
+
+  '@standard-schema/spec@1.1.0':
+    resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
+
+  '@tailwindcss/node@4.2.2':
+    resolution: {integrity: sha512-pXS+wJ2gZpVXqFaUEjojq7jzMpTGf8rU6ipJz5ovJV6PUGmlJ+jvIwGrzdHdQ80Sg+wmQxUFuoW1UAAwHNEdFA==}
+
+  '@tailwindcss/oxide-android-arm64@4.2.2':
+    resolution: {integrity: sha512-dXGR1n+P3B6748jZO/SvHZq7qBOqqzQ+yFrXpoOWWALWndF9MoSKAT3Q0fYgAzYzGhxNYOoysRvYlpixRBBoDg==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [android]
+
+  '@tailwindcss/oxide-darwin-arm64@4.2.2':
+    resolution: {integrity: sha512-iq9Qjr6knfMpZHj55/37ouZeykwbDqF21gPFtfnhCCKGDcPI/21FKC9XdMO/XyBM7qKORx6UIhGgg6jLl7BZlg==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-darwin-x64@4.2.2':
+    resolution: {integrity: sha512-BlR+2c3nzc8f2G639LpL89YY4bdcIdUmiOOkv2GQv4/4M0vJlpXEa0JXNHhCHU7VWOKWT/CjqHdTP8aUuDJkuw==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-freebsd-x64@4.2.2':
+    resolution: {integrity: sha512-YUqUgrGMSu2CDO82hzlQ5qSb5xmx3RUrke/QgnoEx7KvmRJHQuZHZmZTLSuuHwFf0DJPybFMXMYf+WJdxHy/nQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.2.2':
+    resolution: {integrity: sha512-FPdhvsW6g06T9BWT0qTwiVZYE2WIFo2dY5aCSpjG/S/u1tby+wXoslXS0kl3/KXnULlLr1E3NPRRw0g7t2kgaQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.2.2':
+    resolution: {integrity: sha512-4og1V+ftEPXGttOO7eCmW7VICmzzJWgMx+QXAJRAhjrSjumCwWqMfkDrNu1LXEQzNAwz28NCUpucgQPrR4S2yw==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.2.2':
+    resolution: {integrity: sha512-oCfG/mS+/+XRlwNjnsNLVwnMWYH7tn/kYPsNPh+JSOMlnt93mYNCKHYzylRhI51X+TbR+ufNhhKKzm6QkqX8ag==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.2.2':
+    resolution: {integrity: sha512-rTAGAkDgqbXHNp/xW0iugLVmX62wOp2PoE39BTCGKjv3Iocf6AFbRP/wZT/kuCxC9QBh9Pu8XPkv/zCZB2mcMg==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@tailwindcss/oxide-linux-x64-musl@4.2.2':
+    resolution: {integrity: sha512-XW3t3qwbIwiSyRCggeO2zxe3KWaEbM0/kW9e8+0XpBgyKU4ATYzcVSMKteZJ1iukJ3HgHBjbg9P5YPRCVUxlnQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@tailwindcss/oxide-wasm32-wasi@4.2.2':
+    resolution: {integrity: sha512-eKSztKsmEsn1O5lJ4ZAfyn41NfG7vzCg496YiGtMDV86jz1q/irhms5O0VrY6ZwTUkFy/EKG3RfWgxSI3VbZ8Q==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+    bundledDependencies:
+      - '@napi-rs/wasm-runtime'
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+      - '@tybys/wasm-util'
+      - '@emnapi/wasi-threads'
+      - tslib
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.2.2':
+    resolution: {integrity: sha512-qPmaQM4iKu5mxpsrWZMOZRgZv1tOZpUm+zdhhQP0VhJfyGGO3aUKdbh3gDZc/dPLQwW4eSqWGrrcWNBZWUWaXQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.2.2':
+    resolution: {integrity: sha512-1T/37VvI7WyH66b+vqHj/cLwnCxt7Qt3WFu5Q8hk65aOvlwAhs7rAp1VkulBJw/N4tMirXjVnylTR72uI0HGcA==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [win32]
+
+  '@tailwindcss/oxide@4.2.2':
+    resolution: {integrity: sha512-qEUA07+E5kehxYp9BVMpq9E8vnJuBHfJEC0vPC5e7iL/hw7HR61aDKoVoKzrG+QKp56vhNZe4qwkRmMC0zDLvg==}
+    engines: {node: '>= 20'}
+
+  '@tailwindcss/vite@4.2.2':
+    resolution: {integrity: sha512-mEiF5HO1QqCLXoNEfXVA1Tzo+cYsrqV7w9Juj2wdUFyW07JRenqMG225MvPwr3ZD9N1bFQj46X7r33iHxLUW0w==}
+    peerDependencies:
+      vite: ^5.2.0 || ^6 || ^7 || ^8
+
+  '@tanstack/query-core@5.99.2':
+    resolution: {integrity: sha512-1HunU0bXVsR1ZJMZbcOPE6VtaBJxsW809RE9xPe4Gz7MlB0GWwQvuTPhMoEmQ/hIzFKJ/DWAuttIe7BOaWx0tA==}
+
+  '@tanstack/react-query@5.99.2':
+    resolution: {integrity: sha512-vM91UEe45QUS9ED6OklsVL15i8qKcRqNwpWzPTVWvRPRSEgDudDgHpvyTjcdlwHcrKNa80T+xXYcchT2noPnZA==}
+    peerDependencies:
+      react: ^18 || ^19
+
+  '@tanstack/react-virtual@3.13.24':
+    resolution: {integrity: sha512-aIJvz5OSkhNIhZIpYivrxrPTKYsjW9Uzy+sP/mx0S3sev2HyvPb7xmjbYvokzEpfgYHy/HjzJ2zFAETuUfgCpg==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  '@tanstack/virtual-core@3.14.0':
+    resolution: {integrity: sha512-JLANqGy/D6k4Ujmh8Tr25lGimuOXNiaVyXaCAZS0W+1390sADdGnyUdSWNIfd49gebtIxGMij4IktRVzrdr12Q==}
+
+  '@tybys/wasm-util@0.10.1':
+    resolution: {integrity: sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==}
+
+  '@types/argparse@1.0.38':
+    resolution: {integrity: sha512-ebDJ9b0e702Yr7pWgB0jzm+CX4Srzz8RcXtLJDJB+BSccqMa36uyH/zUsSYao5+BD1ytv3k3rPYCq4mAE1hsXA==}
+
+  '@types/babel__core@7.20.5':
+    resolution: {integrity: sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==}
+
+  '@types/babel__generator@7.27.0':
+    resolution: {integrity: sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg==}
+
+  '@types/babel__template@7.4.4':
+    resolution: {integrity: sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A==}
+
+  '@types/babel__traverse@7.28.0':
+    resolution: {integrity: sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==}
+
+  '@types/chai@5.2.3':
+    resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
+
+  '@types/deep-eql@4.0.2':
+    resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
+
+  '@types/estree@1.0.8':
+    resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
+
+  '@types/js-yaml@4.0.9':
+    resolution: {integrity: sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==}
+
+  '@types/jsesc@2.5.1':
+    resolution: {integrity: sha512-9VN+6yxLOPLOav+7PwjZbxiID2bVaeq0ED4qSQmdQTdjnXJSaCVKTR58t15oqH1H5t8Ng2ZX1SabJVoN9Q34bw==}
+
+  '@types/mime-types@2.1.4':
+    resolution: {integrity: sha512-lfU4b34HOri+kAY5UheuFMWPDOI+OPceBSHZKp69gEyTL/mmJ4cnU6Y/rlme3UL3GyOn6Y42hyIEw0/q8sWx5w==}
+
+  '@types/node@12.20.55':
+    resolution: {integrity: sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==}
+
+  '@types/node@18.19.130':
+    resolution: {integrity: sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==}
+
+  '@types/node@22.19.17':
+    resolution: {integrity: sha512-wGdMcf+vPYM6jikpS/qhg6WiqSV/OhG+jeeHT/KlVqxYfD40iYJf9/AE1uQxVWFvU7MipKRkRv8NSHiCGgPr8Q==}
+
+  '@types/nunjucks@3.2.6':
+    resolution: {integrity: sha512-pHiGtf83na1nCzliuAdq8GowYiXvH5l931xZ0YEHaLMNFgynpEqx+IPStlu7UaDkehfvl01e4x/9Tpwhy7Ue3w==}
+
+  '@types/picomatch@4.0.3':
+    resolution: {integrity: sha512-iG0T6+nYJ9FAPmx9SsUlnwcq1ZVRuCXcVEvWnntoPlrOpwtSTKNDC9uVAxTsC3PUvJ+99n4RpAcNgBbHX3JSnQ==}
+
+  '@types/proper-lockfile@4.1.4':
+    resolution: {integrity: sha512-uo2ABllncSqg9F1D4nugVl9v93RmjxF6LJzQLMLDdPaXCUIDPeOJ21Gbqi43xNKzBi/WQ0Q0dICqufzQbMjipQ==}
+
+  '@types/react-dom@19.2.3':
+    resolution: {integrity: sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==}
+    peerDependencies:
+      '@types/react': ^19.2.0
+
+  '@types/react@19.2.14':
+    resolution: {integrity: sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==}
+
+  '@types/regexp.escape@2.0.0':
+    resolution: {integrity: sha512-L0+4KOC47zH0AE/27YhzECRlE4HxHycQy0ng8P4SMmsYIdUqJFzKlk4LameozRQ2mRozPRwRAzpXsDsUgb6ezA==}
+
+  '@types/retry@0.12.0':
+    resolution: {integrity: sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==}
+
+  '@types/semver@7.7.1':
+    resolution: {integrity: sha512-FmgJfu+MOcQ370SD0ev7EI8TlCAfKYU+B4m5T3yXc1CiRN94g/SZPtsCkk506aUDtlMnFZvasDwHHUcZUEaYuA==}
+
+  '@types/ssh2@1.15.5':
+    resolution: {integrity: sha512-N1ASjp/nXH3ovBHddRJpli4ozpk6UdDYIX4RJWFa9L1YKnzdhTlVmiGHm4DZnj/jLbqZpes4aeR30EFGQtvhQQ==}
+
+  '@types/tar@7.0.87':
+    resolution: {integrity: sha512-3IxNBV8LeY5oi2ZFpvAhOtW1+mHswkzM7BuisVrwJgPv67GBO2rkLPQlEKtzfHuLdhDDczhkCZeT+RuizMay4A==}
+    deprecated: This is a stub types definition. tar provides its own type definitions, so you do not need this installed.
+
+  '@types/yauzl@2.10.3':
+    resolution: {integrity: sha512-oJoftv0LSuaDZE3Le4DbKX+KS9G36NzOeSap90UIK0yMA/NhKJhqlSGtNDORNRaIbQfzjXDrQa0ytJ6mNRGz/Q==}
+
+  '@types/yazl@2.4.6':
+    resolution: {integrity: sha512-/ifFjQtcKaoZOjl5NNCQRR0fAKafB3Foxd7J/WvFPTMea46zekapcR30uzkwIkKAAuq5T6d0dkwz754RFH27hg==}
+
+  '@vitejs/plugin-react@4.7.0':
+    resolution: {integrity: sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA==}
+    engines: {node: ^14.18.0 || >=16.0.0}
+    peerDependencies:
+      vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
+
+  '@vitest/coverage-v8@4.1.4':
+    resolution: {integrity: sha512-x7FptB5oDruxNPDNY2+S8tCh0pcq7ymCe1gTHcsp733jYjrJl8V1gMUlVysuCD9Kz46Xz9t1akkv08dPcYDs1w==}
+    peerDependencies:
+      '@vitest/browser': 4.1.4
+      vitest: 4.1.4
+    peerDependenciesMeta:
+      '@vitest/browser':
+        optional: true
+
+  '@vitest/expect@4.1.4':
+    resolution: {integrity: sha512-iPBpra+VDuXmBFI3FMKHSFXp3Gx5HfmSCE8X67Dn+bwephCnQCaB7qWK2ldHa+8ncN8hJU8VTMcxjPpyMkUjww==}
+
+  '@vitest/mocker@4.1.4':
+    resolution: {integrity: sha512-R9HTZBhW6yCSGbGQnDnH3QHfJxokKN4KB+Yvk9Q1le7eQNYwiCyKxmLmurSpFy6BzJanSLuEUDrD+j97Q+ZLPg==}
+    peerDependencies:
+      msw: ^2.4.9
+      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      msw:
+        optional: true
+      vite:
+        optional: true
+
+  '@vitest/pretty-format@4.1.4':
+    resolution: {integrity: sha512-ddmDHU0gjEUyEVLxtZa7xamrpIefdEETu3nZjWtHeZX4QxqJ7tRxSteHVXJOcr8jhiLoGAhkK4WJ3WqBpjx42A==}
+
+  '@vitest/runner@4.1.4':
+    resolution: {integrity: sha512-xTp7VZ5aXP5ZJrn15UtJUWlx6qXLnGtF6jNxHepdPHpMfz/aVPx+htHtgcAL2mDXJgKhpoo2e9/hVJsIeFbytQ==}
+
+  '@vitest/snapshot@4.1.4':
+    resolution: {integrity: sha512-MCjCFgaS8aZz+m5nTcEcgk/xhWv0rEH4Yl53PPlMXOZ1/Ka2VcZU6CJ+MgYCZbcJvzGhQRjVrGQNZqkGPttIKw==}
+
+  '@vitest/spy@4.1.4':
+    resolution: {integrity: sha512-XxNdAsKW7C+FLydqFJLb5KhJtl3PGCMmYwFRfhvIgxJvLSXhhVI1zM8f1qD3Zg7RCjTSzDVyct6sghs9UEgBEQ==}
+
+  '@vitest/utils@4.1.4':
+    resolution: {integrity: sha512-13QMT+eysM5uVGa1rG4kegGYNp6cnQcsTc67ELFbhNLQO+vgsygtYJx2khvdt4gVQqSSpC/KT5FZZxUpP3Oatw==}
+
+  a-sync-waterfall@1.0.1:
+    resolution: {integrity: sha512-RYTOHHdWipFUliRFMCS4X2Yn2X8M87V/OpSqWzKKOGhzqyUxzyVmhHDH9sAvG+ZuQf/TAOFsLCpMw09I1ufUnA==}
+
+  accepts@2.0.0:
+    resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
+    engines: {node: '>= 0.6'}
+
+  agent-base@7.1.4:
+    resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
+    engines: {node: '>= 14'}
+
+  ajv-draft-04@1.0.0:
+    resolution: {integrity: sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==}
+    peerDependencies:
+      ajv: ^8.5.0
+    peerDependenciesMeta:
+      ajv:
+        optional: true
+
+  ajv-formats@3.0.1:
+    resolution: {integrity: sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==}
+    peerDependencies:
+      ajv: ^8.0.0
+    peerDependenciesMeta:
+      ajv:
+        optional: true
+
+  ajv@8.18.0:
+    resolution: {integrity: sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==}
+
+  ansi-colors@4.1.3:
+    resolution: {integrity: sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw==}
+    engines: {node: '>=6'}
+
+  ansi-escapes@7.3.0:
+    resolution: {integrity: sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg==}
+    engines: {node: '>=18'}
+
+  ansi-regex@5.0.1:
+    resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
+    engines: {node: '>=8'}
+
+  ansi-regex@6.2.2:
+    resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
+    engines: {node: '>=12'}
+
+  ansi-styles@4.3.0:
+    resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
+    engines: {node: '>=8'}
+
+  ansi-styles@6.2.3:
+    resolution: {integrity: sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==}
+    engines: {node: '>=12'}
+
+  ansis@4.2.0:
+    resolution: {integrity: sha512-HqZ5rWlFjGiV0tDm3UxxgNRqsOTniqoKZu0pIAfh7TZQMGuZK+hH0drySty0si0QXj1ieop4+SkSfPZBPPkHig==}
+    engines: {node: '>=14'}
+
+  any-promise@1.3.0:
+    resolution: {integrity: sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==}
+
+  argparse@1.0.10:
+    resolution: {integrity: sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==}
+
+  argparse@2.0.1:
+    resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
+
+  array-buffer-byte-length@1.0.2:
+    resolution: {integrity: sha512-LHE+8BuR7RYGDKvnrmcuSq3tDcKv9OFEXQt/HpbZhY7V6h0zlUXutnAD82GiFx9rdieCMjkvtcsPqBwgUl1Iiw==}
+    engines: {node: '>= 0.4'}
+
+  array-union@2.1.0:
+    resolution: {integrity: sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==}
+    engines: {node: '>=8'}
+
+  arraybuffer.prototype.slice@1.0.4:
+    resolution: {integrity: sha512-BNoCY6SXXPQ7gF2opIP4GBE+Xw7U+pHMYKuzjgCN3GwiaIR09UUeKfheyIry77QtrCBlC0KK0q5/TER/tYh3PQ==}
+    engines: {node: '>= 0.4'}
+
+  asap@2.0.6:
+    resolution: {integrity: sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA==}
+
+  asn1@0.2.6:
+    resolution: {integrity: sha512-ix/FxPn0MDjeyJ7i/yoHGFt/EX6LyNbxSEhPPXODPL+KB0VPk86UYfL0lMdy+KCnv+fmvIzySwaK5COwqVbWTQ==}
+
+  assertion-error@2.0.1:
+    resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
+    engines: {node: '>=12'}
+
+  ast-kit@3.0.0-beta.1:
+    resolution: {integrity: sha512-trmleAnZ2PxN/loHWVhhx1qeOHSRXq4TDsBBxq3GqeJitfk3+jTQ+v/C1km/KYq9M7wKqCewMh+/NAvVH7m+bw==}
+    engines: {node: '>=20.19.0'}
+
+  ast-v8-to-istanbul@1.0.0:
+    resolution: {integrity: sha512-1fSfIwuDICFA4LKkCzRPO7F0hzFf0B7+Xqrl27ynQaa+Rh0e1Es0v6kWHPott3lU10AyAr7oKHa65OppjLn3Rg==}
+
+  async-function@1.0.0:
+    resolution: {integrity: sha512-hsU18Ae8CDTR6Kgu9DYf0EbCr/a5iGL0rytQDobUcdpYOKokk8LEjVphnXkDkgpi0wYVsqrXuP0bZxJaTqdgoA==}
+    engines: {node: '>= 0.4'}
+
+  available-typed-arrays@1.0.7:
+    resolution: {integrity: sha512-wvUjBtSGN7+7SjNpq/9M2Tg350UZD3q62IFZLbRAR1bSMlCo1ZaeW+BJ+D090e4hIIZLBcTDWe4Mh4jvUDajzQ==}
+    engines: {node: '>= 0.4'}
+
+  balanced-match@4.0.4:
+    resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
+    engines: {node: 18 || 20 || >=22}
+
+  base64-js@1.5.1:
+    resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==}
+
+  baseline-browser-mapping@2.10.20:
+    resolution: {integrity: sha512-1AaXxEPfXT+GvTBJFuy4yXVHWJBXa4OdbIebGN/wX5DlsIkU0+wzGnd2lOzokSk51d5LUmqjgBLRLlypLUqInQ==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  bcrypt-pbkdf@1.0.2:
+    resolution: {integrity: sha512-qeFIXtP4MSoi6NLqO12WfqARWWuCKi2Rn/9hJLEmtB5yTNr9DqFWkJRCf2qShWzPeAMRnOgCrq0sg/KLv5ES9w==}
+
+  better-path-resolve@1.0.0:
+    resolution: {integrity: sha512-pbnl5XzGBdrFU/wT4jqmJVPn2B6UHPBOhzMQkY/SPUPB6QtUXtmBHBIwCbXJol93mOpGMnQyP/+BB19q04xj7g==}
+    engines: {node: '>=4'}
+
+  bignumber.js@9.3.1:
+    resolution: {integrity: sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==}
+
+  birpc@4.0.0:
+    resolution: {integrity: sha512-LShSxJP0KTmd101b6DRyGBj57LZxSDYWKitQNW/mi8GRMvZb078Uf9+pveax1DrVL89vm7mWe+TovdI/UDOuPw==}
+
+  body-parser@2.2.2:
+    resolution: {integrity: sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA==}
+    engines: {node: '>=18'}
+
+  boolbase@1.0.0:
+    resolution: {integrity: sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==}
+
+  brace-expansion@5.0.6:
+    resolution: {integrity: sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==}
+    engines: {node: 18 || 20 || >=22}
+
+  braces@3.0.3:
+    resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==}
+    engines: {node: '>=8'}
+
+  browserslist@4.28.2:
+    resolution: {integrity: sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg==}
+    engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
+    hasBin: true
+
+  buffer-crc32@0.2.13:
+    resolution: {integrity: sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ==}
+
+  buffer-crc32@1.0.0:
+    resolution: {integrity: sha512-Db1SbgBS/fg/392AblrMJk97KggmvYhr4pB5ZIMTWtaivCPMWLkmb7m21cJvpvgK+J3nsU2CmmixNBZx4vFj/w==}
+    engines: {node: '>=8.0.0'}
+
+  buffer-equal-constant-time@1.0.1:
+    resolution: {integrity: sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==}
+
+  bundle-name@4.1.0:
+    resolution: {integrity: sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q==}
+    engines: {node: '>=18'}
+
+  bytes@3.1.2:
+    resolution: {integrity: sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==}
+    engines: {node: '>= 0.8'}
+
+  cac@7.0.0:
+    resolution: {integrity: sha512-tixWYgm5ZoOD+3g6UTea91eow5z6AAHaho3g0V9CNSNb45gM8SmflpAc+GRd1InC4AqN/07Unrgp56Y94N9hJQ==}
+    engines: {node: '>=20.19.0'}
+
+  call-bind-apply-helpers@1.0.2:
+    resolution: {integrity: sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==}
+    engines: {node: '>= 0.4'}
+
+  call-bind@1.0.9:
+    resolution: {integrity: sha512-a/hy+pNsFUTR+Iz8TCJvXudKVLAnz/DyeSUo10I5yvFDQJBFU2s9uqQpoSrJlroHUKoKqzg+epxyP9lqFdzfBQ==}
+    engines: {node: '>= 0.4'}
+
+  call-bound@1.0.4:
+    resolution: {integrity: sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==}
+    engines: {node: '>= 0.4'}
+
+  caniuse-lite@1.0.30001788:
+    resolution: {integrity: sha512-6q8HFp+lOQtcf7wBK+uEenxymVWkGKkjFpCvw5W25cmMwEDU45p1xQFBQv8JDlMMry7eNxyBaR+qxgmTUZkIRQ==}
+
+  chai@6.2.2:
+    resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
+    engines: {node: '>=18'}
+
+  chalk@4.1.2:
+    resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
+    engines: {node: '>=10'}
+
+  chalk@5.6.2:
+    resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
+    engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
+
+  char-regex@1.0.2:
+    resolution: {integrity: sha512-kWWXztvZ5SBQV+eRgKFeh8q5sLuZY2+8WUIzlxWVTg+oGwY14qylx1KbKzHd8P6ZYkAg0xyIDU9JMHhyJMZ1jw==}
+    engines: {node: '>=10'}
+
+  chardet@2.1.1:
+    resolution: {integrity: sha512-PsezH1rqdV9VvyNhxxOW32/d75r01NY7TQCmOqomRo15ZSOKbpTFVsfjghxo6JloQUCGnH4k1LGu0R4yCLlWQQ==}
+
+  chownr@3.0.0:
+    resolution: {integrity: sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==}
+    engines: {node: '>=18'}
+
+  cjs-module-lexer@1.4.3:
+    resolution: {integrity: sha512-9z8TZaGM1pfswYeXrUpzPrkx8UnWYdhJclsiYMm6x/w5+nN+8Tf/LnAgfLGQCm59qAOxU8WwHEq2vNwF6i4j+Q==}
+
+  cli-cursor@5.0.0:
+    resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
+    engines: {node: '>=18'}
+
+  cli-highlight@2.1.11:
+    resolution: {integrity: sha512-9KDcoEVwyUXrjcJNvHD0NFc/hiwe/WPVYIleQh2O1N2Zro5gWJZ/K+3DGn8w8P/F6FxOgzyC5bxDyHIgCSPhGg==}
+    engines: {node: '>=8.0.0', npm: '>=5.0.0'}
+    hasBin: true
+
+  cli-table3@0.6.5:
+    resolution: {integrity: sha512-+W/5efTR7y5HRD7gACw9yQjqMVvEMLBHmboM/kPWam+H+Hmyrgjh6YncVKK122YZkXrLudzTuAukUw9FnMf7IQ==}
+    engines: {node: 10.* || >= 12.*}
+
+  cli-truncate@5.2.0:
+    resolution: {integrity: sha512-xRwvIOMGrfOAnM1JYtqQImuaNtDEv9v6oIYAs4LIHwTiKee8uwvIi363igssOC0O5U04i4AlENs79LQLu9tEMw==}
+    engines: {node: '>=20'}
+
+  cliui@7.0.4:
+    resolution: {integrity: sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==}
+
+  cliui@8.0.1:
+    resolution: {integrity: sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==}
+    engines: {node: '>=12'}
+
+  color-convert@2.0.1:
+    resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
+    engines: {node: '>=7.0.0'}
+
+  color-name@1.1.4:
+    resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
+
+  colorette@2.0.20:
+    resolution: {integrity: sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==}
+
+  commander@10.0.1:
+    resolution: {integrity: sha512-y4Mg2tXshplEbSGzx7amzPwKKOCGuoSRP/CjEdwwk0FOGlUbq6lKuoyDZTNZkmxHdJtp54hdfY/JUrdL7Xfdug==}
+    engines: {node: '>=14'}
+
+  commander@13.1.0:
+    resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
+    engines: {node: '>=18'}
+
+  commander@14.0.3:
+    resolution: {integrity: sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==}
+    engines: {node: '>=20'}
+
+  commander@5.1.0:
+    resolution: {integrity: sha512-P0CysNDQ7rtVw4QIQtm+MRxV66vKFSvlsQvGYXZWR3qFU0jlMKHZZZgw8e+8DSah4UDKMqnknRDQz+xuQXQ/Zg==}
+    engines: {node: '>= 6'}
+
+  commander@9.5.0:
+    resolution: {integrity: sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==}
+    engines: {node: ^12.20.0 || >=14}
+
+  concurrently@9.2.1:
+    resolution: {integrity: sha512-fsfrO0MxV64Znoy8/l1vVIjjHa29SZyyqPgQBwhiDcaW8wJc2W3XWVOGx4M3oJBnv/zdUZIIp1gDeS98GzP8Ng==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  content-disposition@1.1.0:
+    resolution: {integrity: sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==}
+    engines: {node: '>=18'}
+
+  content-type@1.0.5:
+    resolution: {integrity: sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==}
+    engines: {node: '>= 0.6'}
+
+  convert-source-map@2.0.0:
+    resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
+
+  cookie-signature@1.2.2:
+    resolution: {integrity: sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==}
+    engines: {node: '>=6.6.0'}
+
+  cookie@0.7.2:
+    resolution: {integrity: sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==}
+    engines: {node: '>= 0.6'}
+
+  cookie@1.1.1:
+    resolution: {integrity: sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==}
+    engines: {node: '>=18'}
+
+  cors@2.8.6:
+    resolution: {integrity: sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==}
+    engines: {node: '>= 0.10'}
+
+  cross-spawn@7.0.6:
+    resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
+    engines: {node: '>= 8'}
+
+  css-select@5.2.2:
+    resolution: {integrity: sha512-TizTzUddG/xYLA3NXodFM0fSbNizXjOKhqiQQwvhlspadZokn1KDy0NZFS0wuEubIYAV5/c1/lAr0TaaFXEXzw==}
+
+  css-what@6.2.2:
+    resolution: {integrity: sha512-u/O3vwbptzhMs3L1fQE82ZSLHQQfto5gyZzwteVIEyeaY5Fc7R4dapF/BvRoSYFeqfBk4m0V1Vafq5Pjv25wvA==}
+    engines: {node: '>= 6'}
+
+  cssom@0.5.0:
+    resolution: {integrity: sha512-iKuQcq+NdHqlAcwUY0o/HL69XQrUaQdMjmStJ8JFmUaiiQErlhrmuigkg/CU4E2J0IyUKUrMAgl36TvN67MqTw==}
+
+  csstype@3.2.3:
+    resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
+
+  data-uri-to-buffer@4.0.1:
+    resolution: {integrity: sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==}
+    engines: {node: '>= 12'}
+
+  data-view-buffer@1.0.2:
+    resolution: {integrity: sha512-EmKO5V3OLXh1rtK2wgXRansaK1/mtVdTUEiEI0W8RkvgT05kfxaH29PliLnpLP73yYO6142Q72QNa8Wx/A5CqQ==}
+    engines: {node: '>= 0.4'}
+
+  data-view-byte-length@1.0.2:
+    resolution: {integrity: sha512-tuhGbE6CfTM9+5ANGf+oQb72Ky/0+s3xKUpHvShfiz2RxMFgFPjsXuRLBVMtvMs15awe45SRb83D6wH4ew6wlQ==}
+    engines: {node: '>= 0.4'}
+
+  data-view-byte-offset@1.0.1:
+    resolution: {integrity: sha512-BS8PfmtDGnrgYdOonGZQdLZslWIeCGFP9tpan0hi1Co2Zr2NKADsvGYA8XxuG/4UWgJ6Cjtv+YJnB6MM69QGlQ==}
+    engines: {node: '>= 0.4'}
+
+  dataloader@1.4.0:
+    resolution: {integrity: sha512-68s5jYdlvasItOJnCuI2Q9s4q98g0pCyL3HrcKJu8KNugUl8ahgmZYg38ysLTgQjjXX3H8CJLkAvWrclWfcalw==}
+
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  default-browser-id@5.0.1:
+    resolution: {integrity: sha512-x1VCxdX4t+8wVfd1so/9w+vQ4vx7lKd2Qp5tDRutErwmR85OgmfX7RlLRMWafRMY7hbEiXIbudNrjOAPa/hL8Q==}
+    engines: {node: '>=18'}
+
+  default-browser@5.5.0:
+    resolution: {integrity: sha512-H9LMLr5zwIbSxrmvikGuI/5KGhZ8E2zH3stkMgM5LpOWDutGM2JZaj460Udnf1a+946zc7YBgrqEWwbk7zHvGw==}
+    engines: {node: '>=18'}
+
+  define-data-property@1.1.4:
+    resolution: {integrity: sha512-rBMvIzlpA8v6E+SJZoo++HAYqsLrkg7MSfIinMPFhmkorw7X+dOXVJQs+QT69zGkzMyfDnIMN2Wid1+NbL3T+A==}
+    engines: {node: '>= 0.4'}
+
+  define-lazy-prop@3.0.0:
+    resolution: {integrity: sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg==}
+    engines: {node: '>=12'}
+
+  define-properties@1.2.1:
+    resolution: {integrity: sha512-8QmQKqEASLd5nx0U1B1okLElbUuuttJ/AnYmRXbbbGDWh6uS208EjD4Xqq/I9wK7u0v6O08XhTWnt5XtEbR6Dg==}
+    engines: {node: '>= 0.4'}
+
+  defu@6.1.7:
+    resolution: {integrity: sha512-7z22QmUWiQ/2d0KkdYmANbRUVABpZ9SNYyH5vx6PZ+nE5bcC0l7uFvEfHlyld/HcGBFTL536ClDt3DEcSlEJAQ==}
+
+  depd@2.0.0:
+    resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==}
+    engines: {node: '>= 0.8'}
+
+  detect-indent@6.1.0:
+    resolution: {integrity: sha512-reYkTUJAZb9gUuZ2RvVCNhVHdg62RHnJ7WJl8ftMi4diZ6NWlciOzQN88pUhSELEwflJht4oQDv0F0BMlwaYtA==}
+    engines: {node: '>=8'}
+
+  detect-libc@2.1.2:
+    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+    engines: {node: '>=8'}
+
+  diff@8.0.4:
+    resolution: {integrity: sha512-DPi0FmjiSU5EvQV0++GFDOJ9ASQUVFh5kD+OzOnYdi7n3Wpm9hWWGfB/O2blfHcMVTL5WkQXSnRiK9makhrcnw==}
+    engines: {node: '>=0.3.1'}
+
+  dir-glob@3.0.1:
+    resolution: {integrity: sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==}
+    engines: {node: '>=8'}
+
+  dom-serializer@2.0.0:
+    resolution: {integrity: sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg==}
+
+  domelementtype@2.3.0:
+    resolution: {integrity: sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==}
+
+  domhandler@5.0.3:
+    resolution: {integrity: sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==}
+    engines: {node: '>= 4'}
+
+  domutils@3.2.2:
+    resolution: {integrity: sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw==}
+
+  dotenv@8.6.0:
+    resolution: {integrity: sha512-IrPdXQsk2BbzvCBGBOTmmSH5SodmqZNt4ERAZDmW4CT+tL8VtvinqywuANaFu4bOMWki16nqf0e4oC0QIaDr/g==}
+    engines: {node: '>=10'}
+
+  dts-resolver@3.0.0:
+    resolution: {integrity: sha512-1T1f+z+4tl9XD+m+0HBgWoL/nm0bOIffyWaUuUSBlFg/86IWvfx+wjNaO/ybU0AJzG9/Mi5hBUgGV6zCmWEN7Q==}
+    engines: {node: ^22.18.0 || >=24.0.0}
+    peerDependencies:
+      oxc-resolver: '>=11.0.0'
+    peerDependenciesMeta:
+      oxc-resolver:
+        optional: true
+
+  dunder-proto@1.0.1:
+    resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
+    engines: {node: '>= 0.4'}
+
+  ecdsa-sig-formatter@1.0.11:
+    resolution: {integrity: sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==}
+
+  ee-first@1.1.1:
+    resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
+
+  electron-to-chromium@1.5.340:
+    resolution: {integrity: sha512-908qahOGocRMinT2nM3ajCEM99H4iPdv84eagPP3FfZy/1ZGeOy2CZYzjhms81ckOPCXPlW7LkY4XpxD8r1DrA==}
+
+  emoji-regex@10.6.0:
+    resolution: {integrity: sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==}
+
+  emoji-regex@8.0.0:
+    resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}
+
+  emojilib@2.4.0:
+    resolution: {integrity: sha512-5U0rVMU5Y2n2+ykNLQqMoqklN9ICBT/KsvC1Gz6vqHbz2AXXGkG+Pm5rMWk/8Vjrr/mY9985Hi8DYzn1F09Nyw==}
+
+  empathic@2.0.0:
+    resolution: {integrity: sha512-i6UzDscO/XfAcNYD75CfICkmfLedpyPDdozrLMmQc5ORaQcdMoc21OnlEylMIqI7U8eniKrPMxxtj8k0vhmJhA==}
+    engines: {node: '>=14'}
+
+  encodeurl@2.0.0:
+    resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==}
+    engines: {node: '>= 0.8'}
+
+  enhanced-resolve@5.20.1:
+    resolution: {integrity: sha512-Qohcme7V1inbAfvjItgw0EaxVX5q2rdVEZHRBrEQdRZTssLDGsL8Lwrznl8oQ/6kuTJONLaDcGjkNP247XEhcA==}
+    engines: {node: '>=10.13.0'}
+
+  enquirer@2.4.1:
+    resolution: {integrity: sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ==}
+    engines: {node: '>=8.6'}
+
+  entities@4.5.0:
+    resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==}
+    engines: {node: '>=0.12'}
+
+  entities@7.0.1:
+    resolution: {integrity: sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==}
+    engines: {node: '>=0.12'}
+
+  environment@1.1.0:
+    resolution: {integrity: sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==}
+    engines: {node: '>=18'}
+
+  es-abstract@1.24.2:
+    resolution: {integrity: sha512-2FpH9Q5i2RRwyEP1AylXe6nYLR5OhaJTZwmlcP0dL/+JCbgg7yyEo/sEK6HeGZRf3dFpWwThaRHVApXSkW3xeg==}
+    engines: {node: '>= 0.4'}
+
+  es-define-property@1.0.1:
+    resolution: {integrity: sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==}
+    engines: {node: '>= 0.4'}
+
+  es-errors@1.3.0:
+    resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==}
+    engines: {node: '>= 0.4'}
+
+  es-module-lexer@2.0.0:
+    resolution: {integrity: sha512-5POEcUuZybH7IdmGsD8wlf0AI55wMecM9rVBTI/qEAy2c1kTOm3DjFYjrBdI2K3BaJjJYfYFeRtM0t9ssnRuxw==}
+
+  es-object-atoms@1.1.1:
+    resolution: {integrity: sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==}
+    engines: {node: '>= 0.4'}
+
+  es-set-tostringtag@2.1.0:
+    resolution: {integrity: sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==}
+    engines: {node: '>= 0.4'}
+
+  es-to-primitive@1.3.0:
+    resolution: {integrity: sha512-w+5mJ3GuFL+NjVtJlvydShqE1eN3h3PbI7/5LAsYJP/2qtuMXjfL2LpHSRqo4b4eSF5K/DH1JXKUAHSB2UW50g==}
+    engines: {node: '>= 0.4'}
+
+  esbuild@0.25.12:
+    resolution: {integrity: sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  esbuild@0.27.7:
+    resolution: {integrity: sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  escalade@3.2.0:
+    resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
+    engines: {node: '>=6'}
+
+  escape-html@1.0.3:
+    resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==}
+
+  esprima@4.0.1:
+    resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==}
+    engines: {node: '>=4'}
+    hasBin: true
+
+  estree-walker@3.0.3:
+    resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
+
+  etag@1.8.1:
+    resolution: {integrity: sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==}
+    engines: {node: '>= 0.6'}
+
+  eventemitter3@5.0.4:
+    resolution: {integrity: sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==}
+
+  eventsource-parser@3.0.6:
+    resolution: {integrity: sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg==}
+    engines: {node: '>=18.0.0'}
+
+  eventsource@3.0.7:
+    resolution: {integrity: sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==}
+    engines: {node: '>=18.0.0'}
+
+  expect-type@1.3.0:
+    resolution: {integrity: sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==}
+    engines: {node: '>=12.0.0'}
+
+  express-rate-limit@8.3.2:
+    resolution: {integrity: sha512-77VmFeJkO0/rvimEDuUC5H30oqUC4EyOhyGccfqoLebB0oiEYfM7nwPrsDsBL1gsTpwfzX8SFy2MT3TDyRq+bg==}
+    engines: {node: '>= 16'}
+    peerDependencies:
+      express: '>= 4.11'
+
+  express@5.2.1:
+    resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==}
+    engines: {node: '>= 18'}
+
+  extend@3.0.2:
+    resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==}
+
+  extendable-error@0.1.7:
+    resolution: {integrity: sha512-UOiS2in6/Q0FK0R0q6UY9vYpQ21mr/Qn1KOnte7vsACuNJf514WvCCUHSRCPcgjPT2bAhNIJdlE6bVap1GKmeg==}
+
+  fast-deep-equal@3.1.3:
+    resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
+
+  fast-glob@3.3.3:
+    resolution: {integrity: sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==}
+    engines: {node: '>=8.6.0'}
+
+  fast-sha256@1.3.0:
+    resolution: {integrity: sha512-n11RGP/lrWEFI/bWdygLxhI+pVeo1ZYIVwvvPkW7azl/rOy+F3HYRZ2K5zeE9mmkhQppyv9sQFx0JM9UabnpPQ==}
+
+  fast-uri@3.1.0:
+    resolution: {integrity: sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==}
+
+  fastq@1.20.1:
+    resolution: {integrity: sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw==}
+
+  fdir@6.5.0:
+    resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
+    engines: {node: '>=12.0.0'}
+    peerDependencies:
+      picomatch: ^3 || ^4
+    peerDependenciesMeta:
+      picomatch:
+        optional: true
+
+  fetch-blob@3.2.0:
+    resolution: {integrity: sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==}
+    engines: {node: ^12.20 || >= 14.13}
+
+  fflate@0.8.2:
+    resolution: {integrity: sha512-cPJU47OaAoCbg0pBvzsgpTPhmhqI5eJjh/JIu8tPj5q+T7iLvW/JAYUqmE7KOB4R1ZyEhzBaIQpQpardBF5z8A==}
+
+  fill-range@7.1.1:
+    resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==}
+    engines: {node: '>=8'}
+
+  finalhandler@2.1.1:
+    resolution: {integrity: sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==}
+    engines: {node: '>= 18.0.0'}
+
+  find-up@4.1.0:
+    resolution: {integrity: sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==}
+    engines: {node: '>=8'}
+
+  for-each@0.3.5:
+    resolution: {integrity: sha512-dKx12eRCVIzqCxFGplyFKJMPvLEWgmNtUrpTiJIR5u97zEhRG8ySrtboPHZXx7daLxQVrl643cTzbab2tkQjxg==}
+    engines: {node: '>= 0.4'}
+
+  formdata-polyfill@4.0.10:
+    resolution: {integrity: sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==}
+    engines: {node: '>=12.20.0'}
+
+  forwarded@0.2.0:
+    resolution: {integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==}
+    engines: {node: '>= 0.6'}
+
+  fresh@2.0.0:
+    resolution: {integrity: sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==}
+    engines: {node: '>= 0.8'}
+
+  fs-extra@11.3.5:
+    resolution: {integrity: sha512-eKpRKAovdpZtR1WopLHxlBWvAgPny3c4gX1G5Jhwmmw4XJj0ifSD5qB5TOo8hmA0wlRKDAOAhEE1yVPgs6Fgcg==}
+    engines: {node: '>=14.14'}
+
+  fs-extra@7.0.1:
+    resolution: {integrity: sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==}
+    engines: {node: '>=6 <7 || >=8'}
+
+  fs-extra@8.1.0:
+    resolution: {integrity: sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==}
+    engines: {node: '>=6 <7 || >=8'}
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  function-bind@1.1.2:
+    resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
+
+  function.prototype.name@1.1.8:
+    resolution: {integrity: sha512-e5iwyodOHhbMr/yNrc7fDYG4qlbIvI5gajyzPnb5TCwyhjApznQh1BMFou9b30SevY43gCJKXycoCBjMbsuW0Q==}
+    engines: {node: '>= 0.4'}
+
+  functions-have-names@1.2.3:
+    resolution: {integrity: sha512-xckBUXyTIqT97tq2x2AMb+g163b5JFysYk0x4qxNFwbfQkmNZoiRHb6sPzI9/QV33WeuvVYBUIiD4NzNIyqaRQ==}
+
+  gaxios@7.1.4:
+    resolution: {integrity: sha512-bTIgTsM2bWn3XklZISBTQX7ZSddGW+IO3bMdGaemHZ3tbqExMENHLx6kKZ/KlejgrMtj8q7wBItt51yegqalrA==}
+    engines: {node: '>=18'}
+
+  gcp-metadata@8.1.2:
+    resolution: {integrity: sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==}
+    engines: {node: '>=18'}
+
+  generator-function@2.0.1:
+    resolution: {integrity: sha512-SFdFmIJi+ybC0vjlHN0ZGVGHc3lgE0DxPAT0djjVg+kjOnSqclqmj0KQ7ykTOLP6YxoqOvuAODGdcHJn+43q3g==}
+    engines: {node: '>= 0.4'}
+
+  gensync@1.0.0-beta.2:
+    resolution: {integrity: sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==}
+    engines: {node: '>=6.9.0'}
+
+  get-caller-file@2.0.5:
+    resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==}
+    engines: {node: 6.* || 8.* || >= 10.*}
+
+  get-east-asian-width@1.5.0:
+    resolution: {integrity: sha512-CQ+bEO+Tva/qlmw24dCejulK5pMzVnUOFOijVogd3KQs07HnRIgp8TGipvCCRT06xeYEbpbgwaCxglFyiuIcmA==}
+    engines: {node: '>=18'}
+
+  get-intrinsic@1.3.0:
+    resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==}
+    engines: {node: '>= 0.4'}
+
+  get-proto@1.0.1:
+    resolution: {integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==}
+    engines: {node: '>= 0.4'}
+
+  get-symbol-description@1.1.0:
+    resolution: {integrity: sha512-w9UMqWwJxHNOvoNzSJ2oPF5wvYcvP7jUvYzhp67yEhTi17ZDBBC1z9pTdGuzjD+EFIqLSYRweZjqfiPzQ06Ebg==}
+    engines: {node: '>= 0.4'}
+
+  get-tsconfig@4.13.7:
+    resolution: {integrity: sha512-7tN6rFgBlMgpBML5j8typ92BKFi2sFQvIdpAqLA2beia5avZDrMs0FLZiM5etShWq5irVyGcGMEA1jcDaK7A/Q==}
+
+  get-tsconfig@5.0.0-beta.5:
+    resolution: {integrity: sha512-/6gFNr0N04nob252sTQxyFLi3eKFRqIg1I87YcqAMT1i6SQrSF6KujUEQrtrjMV0H/eejTCltLdDSTEMzHbnsQ==}
+    engines: {node: '>=20.20.0'}
+
+  glob-parent@5.1.2:
+    resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==}
+    engines: {node: '>= 6'}
+
+  globalthis@1.0.4:
+    resolution: {integrity: sha512-DpLKbNU4WylpxJykQujfCcwYWiV/Jhm50Goo0wrVILAv5jOr9d+H+UR3PhSCD2rCCEIg0uc+G+muBTwD54JhDQ==}
+    engines: {node: '>= 0.4'}
+
+  globby@11.1.0:
+    resolution: {integrity: sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==}
+    engines: {node: '>=10'}
+
+  google-auth-library@10.6.2:
+    resolution: {integrity: sha512-e27Z6EThmVNNvtYASwQxose/G57rkRuaRbQyxM2bvYLLX/GqWZ5chWq2EBoUchJbCc57eC9ArzO5wMsEmWftCw==}
+    engines: {node: '>=18'}
+
+  google-logging-utils@1.1.3:
+    resolution: {integrity: sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA==}
+    engines: {node: '>=14'}
+
+  gopd@1.2.0:
+    resolution: {integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==}
+    engines: {node: '>= 0.4'}
+
+  graceful-fs@4.2.11:
+    resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
+
+  has-bigints@1.1.0:
+    resolution: {integrity: sha512-R3pbpkcIqv2Pm3dUwgjclDRVmWpTJW2DcMzcIhEXEx1oh/CEMObMm3KLmRJOdvhM7o4uQBnwr8pzRK2sJWIqfg==}
+    engines: {node: '>= 0.4'}
+
+  has-flag@4.0.0:
+    resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
+    engines: {node: '>=8'}
+
+  has-property-descriptors@1.0.2:
+    resolution: {integrity: sha512-55JNKuIW+vq4Ke1BjOTjM2YctQIvCT7GFzHwmfZPGo5wnrgkid0YQtnAleFSqumZm4az3n2BS+erby5ipJdgrg==}
+
+  has-proto@1.2.0:
+    resolution: {integrity: sha512-KIL7eQPfHQRC8+XluaIw7BHUwwqL19bQn4hzNgdr+1wXoU0KKj6rufu47lhY7KbJR2C6T6+PfyN0Ea7wkSS+qQ==}
+    engines: {node: '>= 0.4'}
+
+  has-symbols@1.1.0:
+    resolution: {integrity: sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==}
+    engines: {node: '>= 0.4'}
+
+  has-tostringtag@1.0.2:
+    resolution: {integrity: sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==}
+    engines: {node: '>= 0.4'}
+
+  hasown@2.0.3:
+    resolution: {integrity: sha512-ej4AhfhfL2Q2zpMmLo7U1Uv9+PyhIZpgQLGT1F9miIGmiCJIoCgSmczFdrc97mWT4kVY72KA+WnnhJ5pghSvSg==}
+    engines: {node: '>= 0.4'}
+
+  highlight.js@10.7.3:
+    resolution: {integrity: sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A==}
+
+  hono@4.12.14:
+    resolution: {integrity: sha512-am5zfg3yu6sqn5yjKBNqhnTX7Cv+m00ox+7jbaKkrLMRJ4rAdldd1xPd/JzbBWspqaQv6RSTrgFN95EsfhC+7w==}
+    engines: {node: '>=16.9.0'}
+
+  hookable@6.1.1:
+    resolution: {integrity: sha512-U9LYDy1CwhMCnprUfeAZWZGByVbhd54hwepegYTK7Pi5NvqEj63ifz5z+xukznehT7i6NIZRu89Ay1AZmRsLEQ==}
+
+  html-escaper@2.0.2:
+    resolution: {integrity: sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==}
+
+  html-escaper@3.0.3:
+    resolution: {integrity: sha512-RuMffC89BOWQoY0WKGpIhn5gX3iI54O6nRA0yC124NYVtzjmFWBIiFd8M0x+ZdX0P9R4lADg1mgP8C7PxGOWuQ==}
+
+  htmlparser2@10.1.0:
+    resolution: {integrity: sha512-VTZkM9GWRAtEpveh7MSF6SjjrpNVNNVJfFup7xTY3UpFtm67foy9HDVXneLtFVt4pMz5kZtgNcvCniNFb1hlEQ==}
+
+  http-errors@2.0.1:
+    resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
+    engines: {node: '>= 0.8'}
+
+  https-proxy-agent@7.0.6:
+    resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==}
+    engines: {node: '>= 14'}
+
+  human-id@4.1.3:
+    resolution: {integrity: sha512-tsYlhAYpjCKa//8rXZ9DqKEawhPoSytweBC2eNvcaDK+57RZLHGqNs3PZTQO6yekLFSuvA6AlnAfrw1uBvtb+Q==}
+    hasBin: true
+
+  iconv-lite@0.7.2:
+    resolution: {integrity: sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==}
+    engines: {node: '>=0.10.0'}
+
+  ignore@5.3.2:
+    resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
+    engines: {node: '>= 4'}
+
+  import-lazy@4.0.0:
+    resolution: {integrity: sha512-rKtvo6a868b5Hu3heneU+L4yEQ4jYKLtjpnPeUdK7h0yzXGmyBTypknlkCvHFBqfX9YlorEiMM6Dnq/5atfHkw==}
+    engines: {node: '>=8'}
+
+  import-without-cache@0.4.0:
+    resolution: {integrity: sha512-NkJQA7oZ4YHQhd2+H3BoRFKF3d/XNsiKpHZCQEMH9pDX27hQQLsTyOocyRgaIVtf8gHX3Nt3LPkR4e5EdtPAGQ==}
+    engines: {node: ^22.18.0 || >=24.0.0}
+
+  inherits@2.0.4:
+    resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
+
+  internal-slot@1.1.0:
+    resolution: {integrity: sha512-4gd7VpWNQNB4UKKCFFVcp1AVv+FMOgs9NKzjHKusc8jTMhd5eL1NqQqOpE0KzMds804/yHlglp3uxgluOqAPLw==}
+    engines: {node: '>= 0.4'}
+
+  ip-address@10.1.0:
+    resolution: {integrity: sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==}
+    engines: {node: '>= 12'}
+
+  ipaddr.js@1.9.1:
+    resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==}
+    engines: {node: '>= 0.10'}
+
+  is-array-buffer@3.0.5:
+    resolution: {integrity: sha512-DDfANUiiG2wC1qawP66qlTugJeL5HyzMpfr8lLK+jMQirGzNod0B12cFB/9q838Ru27sBwfw78/rdoU7RERz6A==}
+    engines: {node: '>= 0.4'}
+
+  is-async-function@2.1.1:
+    resolution: {integrity: sha512-9dgM/cZBnNvjzaMYHVoxxfPj2QXt22Ev7SuuPrs+xav0ukGB0S6d4ydZdEiM48kLx5kDV+QBPrpVnFyefL8kkQ==}
+    engines: {node: '>= 0.4'}
+
+  is-bigint@1.1.0:
+    resolution: {integrity: sha512-n4ZT37wG78iz03xPRKJrHTdZbe3IicyucEtdRsV5yglwc3GyUfbAfpSeD0FJ41NbUNSt5wbhqfp1fS+BgnvDFQ==}
+    engines: {node: '>= 0.4'}
+
+  is-boolean-object@1.2.2:
+    resolution: {integrity: sha512-wa56o2/ElJMYqjCjGkXri7it5FbebW5usLw/nPmCMs5DeZ7eziSYZhSmPRn0txqeW4LnAmQQU7FgqLpsEFKM4A==}
+    engines: {node: '>= 0.4'}
+
+  is-callable@1.2.7:
+    resolution: {integrity: sha512-1BC0BVFhS/p0qtw6enp8e+8OD0UrK0oFLztSjNzhcKA3WDuJxxAPXzPuPtKkjEY9UUoEWlX/8fgKeu2S8i9JTA==}
+    engines: {node: '>= 0.4'}
+
+  is-core-module@2.16.2:
+    resolution: {integrity: sha512-evOr8xfXKxE6qSR0hSXL2r3sd7ALj8+7jQEUvPYcm5sgZFdJ+AYzT6yNmJenvIYQBgIGwfwz08sL8zoL7yq2BA==}
+    engines: {node: '>= 0.4'}
+
+  is-data-view@1.0.2:
+    resolution: {integrity: sha512-RKtWF8pGmS87i2D6gqQu/l7EYRlVdfzemCJN/P3UOs//x1QE7mfhvzHIApBTRf7axvT6DMGwSwBXYCT0nfB9xw==}
+    engines: {node: '>= 0.4'}
+
+  is-date-object@1.1.0:
+    resolution: {integrity: sha512-PwwhEakHVKTdRNVOw+/Gyh0+MzlCl4R6qKvkhuvLtPMggI1WAHt9sOwZxQLSGpUaDnrdyDsomoRgNnCfKNSXXg==}
+    engines: {node: '>= 0.4'}
+
+  is-docker@3.0.0:
+    resolution: {integrity: sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+    hasBin: true
+
+  is-extglob@2.1.1:
+    resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==}
+    engines: {node: '>=0.10.0'}
+
+  is-finalizationregistry@1.1.1:
+    resolution: {integrity: sha512-1pC6N8qWJbWoPtEjgcL2xyhQOP491EQjeUo3qTKcmV8YSDDJrOepfG8pcC7h/QgnQHYSv0mJ3Z/ZWxmatVrysg==}
+    engines: {node: '>= 0.4'}
+
+  is-fullwidth-code-point@3.0.0:
+    resolution: {integrity: sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==}
+    engines: {node: '>=8'}
+
+  is-fullwidth-code-point@5.1.0:
+    resolution: {integrity: sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ==}
+    engines: {node: '>=18'}
+
+  is-generator-function@1.1.2:
+    resolution: {integrity: sha512-upqt1SkGkODW9tsGNG5mtXTXtECizwtS2kA161M+gJPc1xdb/Ax629af6YrTwcOeQHbewrPNlE5Dx7kzvXTizA==}
+    engines: {node: '>= 0.4'}
+
+  is-glob@4.0.3:
+    resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
+    engines: {node: '>=0.10.0'}
+
+  is-inside-container@1.0.0:
+    resolution: {integrity: sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==}
+    engines: {node: '>=14.16'}
+    hasBin: true
+
+  is-map@2.0.3:
+    resolution: {integrity: sha512-1Qed0/Hr2m+YqxnM09CjA2d/i6YZNfF6R2oRAOj36eUdS6qIV/huPJNSEpKbupewFs+ZsJlxsjjPbc0/afW6Lw==}
+    engines: {node: '>= 0.4'}
+
+  is-negative-zero@2.0.3:
+    resolution: {integrity: sha512-5KoIu2Ngpyek75jXodFvnafB6DJgr3u8uuK0LEZJjrU19DrMD3EVERaR8sjz8CCGgpZvxPl9SuE1GMVPFHx1mw==}
+    engines: {node: '>= 0.4'}
+
+  is-number-object@1.1.1:
+    resolution: {integrity: sha512-lZhclumE1G6VYD8VHe35wFaIif+CTy5SJIi5+3y4psDgWu4wPDoBhF8NxUOinEc7pHgiTsT6MaBb92rKhhD+Xw==}
+    engines: {node: '>= 0.4'}
+
+  is-number@7.0.0:
+    resolution: {integrity: sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==}
+    engines: {node: '>=0.12.0'}
+
+  is-promise@4.0.0:
+    resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==}
+
+  is-regex@1.2.1:
+    resolution: {integrity: sha512-MjYsKHO5O7mCsmRGxWcLWheFqN9DJ/2TmngvjKXihe6efViPqc274+Fx/4fYj/r03+ESvBdTXK0V6tA3rgez1g==}
+    engines: {node: '>= 0.4'}
+
+  is-set@2.0.3:
+    resolution: {integrity: sha512-iPAjerrse27/ygGLxw+EBR9agv9Y6uLeYVJMu+QNCoouJ1/1ri0mGrcWpfCqFZuzzx3WjtwxG098X+n4OuRkPg==}
+    engines: {node: '>= 0.4'}
+
+  is-shared-array-buffer@1.0.4:
+    resolution: {integrity: sha512-ISWac8drv4ZGfwKl5slpHG9OwPNty4jOWPRIhBpxOoD+hqITiwuipOQ2bNthAzwA3B4fIjO4Nln74N0S9byq8A==}
+    engines: {node: '>= 0.4'}
+
+  is-string@1.1.1:
+    resolution: {integrity: sha512-BtEeSsoaQjlSPBemMQIrY1MY0uM6vnS1g5fmufYOtnxLGUZM2178PKbhsk7Ffv58IX+ZtcvoGwccYsh0PglkAA==}
+    engines: {node: '>= 0.4'}
+
+  is-subdir@1.2.0:
+    resolution: {integrity: sha512-2AT6j+gXe/1ueqbW6fLZJiIw3F8iXGJtt0yDrZaBhAZEG1raiTxKWU+IPqMCzQAXOUCKdA4UDMgacKH25XG2Cw==}
+    engines: {node: '>=4'}
+
+  is-symbol@1.1.1:
+    resolution: {integrity: sha512-9gGx6GTtCQM73BgmHQXfDmLtfjjTUDSyoxTCbp5WtoixAhfgsDirWIcVQ/IHpvI5Vgd5i/J5F7B9cN/WlVbC/w==}
+    engines: {node: '>= 0.4'}
+
+  is-typed-array@1.1.15:
+    resolution: {integrity: sha512-p3EcsicXjit7SaskXHs1hA91QxgTw46Fv6EFKKGS5DRFLD8yKnohjF3hxoju94b/OcMZoQukzpPpBE9uLVKzgQ==}
+    engines: {node: '>= 0.4'}
+
+  is-weakmap@2.0.2:
+    resolution: {integrity: sha512-K5pXYOm9wqY1RgjpL3YTkF39tni1XajUIkawTLUo9EZEVUFga5gSQJF8nNS7ZwJQ02y+1YCNYcMh+HIf1ZqE+w==}
+    engines: {node: '>= 0.4'}
+
+  is-weakref@1.1.1:
+    resolution: {integrity: sha512-6i9mGWSlqzNMEqpCp93KwRS1uUOodk2OJ6b+sq7ZPDSy2WuI5NFIxp/254TytR8ftefexkWn5xNiHUNpPOfSew==}
+    engines: {node: '>= 0.4'}
+
+  is-weakset@2.0.4:
+    resolution: {integrity: sha512-mfcwb6IzQyOKTs84CQMrOwW4gQcaTOAWJ0zzJCl2WSPDrWk/OzDaImWFH3djXhb24g4eudZfLRozAvPGw4d9hQ==}
+    engines: {node: '>= 0.4'}
+
+  is-windows@1.0.2:
+    resolution: {integrity: sha512-eXK1UInq2bPmjyX6e3VHIzMLobc4J94i4AWn+Hpq3OU5KkrRC96OAcR3PRJ/pGu6m8TRnBHP9dkXQVsT/COVIA==}
+    engines: {node: '>=0.10.0'}
+
+  is-wsl@3.1.1:
+    resolution: {integrity: sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==}
+    engines: {node: '>=16'}
+
+  isarray@2.0.5:
+    resolution: {integrity: sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw==}
+
+  isexe@2.0.0:
+    resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
+
+  istanbul-lib-coverage@3.2.2:
+    resolution: {integrity: sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==}
+    engines: {node: '>=8'}
+
+  istanbul-lib-report@3.0.1:
+    resolution: {integrity: sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw==}
+    engines: {node: '>=10'}
+
+  istanbul-reports@3.2.0:
+    resolution: {integrity: sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==}
+    engines: {node: '>=8'}
+
+  jiti@2.6.1:
+    resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
+    hasBin: true
+
+  jju@1.4.0:
+    resolution: {integrity: sha512-8wb9Yw966OSxApiCt0K3yNJL8pnNeIv+OEq2YMidz4FKP6nonSRoOXc80iXY4JaN2FC11B9qsNmDsm+ZOfMROA==}
+
+  jose@6.2.2:
+    resolution: {integrity: sha512-d7kPDd34KO/YnzaDOlikGpOurfF0ByC2sEV4cANCtdqLlTfBlw2p14O/5d/zv40gJPbIQxfES3nSx1/oYNyuZQ==}
+
+  js-tokens@10.0.0:
+    resolution: {integrity: sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==}
+
+  js-tokens@4.0.0:
+    resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
+
+  js-yaml@3.14.2:
+    resolution: {integrity: sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==}
+    hasBin: true
+
+  js-yaml@4.1.1:
+    resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==}
+    hasBin: true
+
+  jsesc@3.1.0:
+    resolution: {integrity: sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  json-bigint@1.0.0:
+    resolution: {integrity: sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==}
+
+  json-schema-to-ts@3.1.1:
+    resolution: {integrity: sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g==}
+    engines: {node: '>=16'}
+
+  json-schema-traverse@1.0.0:
+    resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==}
+
+  json-schema-typed@8.0.2:
+    resolution: {integrity: sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==}
+
+  json5@2.2.3:
+    resolution: {integrity: sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  jsonfile@4.0.0:
+    resolution: {integrity: sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==}
+
+  jsonfile@6.2.1:
+    resolution: {integrity: sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==}
+
+  jwa@2.0.1:
+    resolution: {integrity: sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg==}
+
+  jws@4.0.1:
+    resolution: {integrity: sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA==}
+
+  koffi@2.16.0:
+    resolution: {integrity: sha512-h/2NJueOKWd0YYycEOWDspomizgNfuOKf/V7ZE2fytvuRtHoY9Tb+y4x6GJ6pFqaVndWn9dLK+sCI14eWtu5rA==}
+
+  lightningcss-android-arm64@1.32.0:
+    resolution: {integrity: sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.32.0:
+    resolution: {integrity: sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.32.0:
+    resolution: {integrity: sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-freebsd-x64@1.32.0:
+    resolution: {integrity: sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    resolution: {integrity: sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    resolution: {integrity: sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  lightningcss-linux-x64-musl@1.32.0:
+    resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    resolution: {integrity: sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  lightningcss@1.32.0:
+    resolution: {integrity: sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==}
+    engines: {node: '>= 12.0.0'}
+
+  linkedom@0.18.12:
+    resolution: {integrity: sha512-jalJsOwIKuQJSeTvsgzPe9iJzyfVaEJiEXl+25EkKevsULHvMJzpNqwvj1jOESWdmgKDiXObyjOYwlUqG7wo1Q==}
+    engines: {node: '>=16'}
+    peerDependencies:
+      canvas: '>= 2'
+    peerDependenciesMeta:
+      canvas:
+        optional: true
+
+  lint-staged@16.4.0:
+    resolution: {integrity: sha512-lBWt8hujh/Cjysw5GYVmZpFHXDCgZzhrOm8vbcUdobADZNOK/bRshr2kM3DfgrrtR1DQhfupW9gnIXOfiFi+bw==}
+    engines: {node: '>=20.17'}
+    hasBin: true
+
+  listr2@9.0.5:
+    resolution: {integrity: sha512-ME4Fb83LgEgwNw96RKNvKV4VTLuXfoKudAmm2lP8Kk87KaMK0/Xrx/aAkMWmT8mDb+3MlFDspfbCs7adjRxA2g==}
+    engines: {node: '>=20.0.0'}
+
+  locate-path@5.0.0:
+    resolution: {integrity: sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==}
+    engines: {node: '>=8'}
+
+  lodash.startcase@4.4.0:
+    resolution: {integrity: sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg==}
+
+  log-update@6.1.0:
+    resolution: {integrity: sha512-9ie8ItPR6tjY5uYJh8K/Zrv/RMZ5VOlOWvtZdEHYSTFKZfIBPQa9tOAEeAWhd+AnIneLJ22w5fjOYtoutpWq5w==}
+    engines: {node: '>=18'}
+
+  long@5.3.2:
+    resolution: {integrity: sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==}
+
+  lru-cache@11.3.3:
+    resolution: {integrity: sha512-JvNw9Y81y33E+BEYPr0U7omo+U9AySnsMsEiXgwT6yqd31VQWTLNQqmT4ou5eqPFUrTfIDFta2wKhB1hyohtAQ==}
+    engines: {node: 20 || >=22}
+
+  lru-cache@5.1.1:
+    resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
+
+  magic-string@0.30.21:
+    resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
+
+  magicast@0.5.2:
+    resolution: {integrity: sha512-E3ZJh4J3S9KfwdjZhe2afj6R9lGIN5Pher1pF39UGrXRqq/VDaGVIGN13BjHd2u8B61hArAGOnso7nBOouW3TQ==}
+
+  make-dir@4.0.0:
+    resolution: {integrity: sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==}
+    engines: {node: '>=10'}
+
+  marked-terminal@7.3.0:
+    resolution: {integrity: sha512-t4rBvPsHc57uE/2nJOLmMbZCQ4tgAccAED3ngXQqW6g+TxA488JzJ+FK3lQkzBQOI1mRV/r/Kq+1ZlJ4D0owQw==}
+    engines: {node: '>=16.0.0'}
+    peerDependencies:
+      marked: '>=1 <16'
+
+  marked@15.0.12:
+    resolution: {integrity: sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA==}
+    engines: {node: '>= 18'}
+    hasBin: true
+
+  marked@9.1.6:
+    resolution: {integrity: sha512-jcByLnIFkd5gSXZmjNvS1TlmRhCXZjIzHYlaGkPlLIekG55JDR2Z4va9tZwCiP+/RDERiNhMOFu01xd6O5ct1Q==}
+    engines: {node: '>= 16'}
+    hasBin: true
+
+  math-intrinsics@1.1.0:
+    resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
+    engines: {node: '>= 0.4'}
+
+  media-typer@1.1.0:
+    resolution: {integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==}
+    engines: {node: '>= 0.8'}
+
+  merge-descriptors@2.0.0:
+    resolution: {integrity: sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==}
+    engines: {node: '>=18'}
+
+  merge2@1.4.1:
+    resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
+    engines: {node: '>= 8'}
+
+  micromatch@4.0.8:
+    resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
+    engines: {node: '>=8.6'}
+
+  mime-db@1.54.0:
+    resolution: {integrity: sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==}
+    engines: {node: '>= 0.6'}
+
+  mime-types@3.0.2:
+    resolution: {integrity: sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==}
+    engines: {node: '>=18'}
+
+  mimic-function@5.0.1:
+    resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
+    engines: {node: '>=18'}
+
+  minimatch@10.2.3:
+    resolution: {integrity: sha512-Rwi3pnapEqirPSbWbrZaa6N3nmqq4Xer/2XooiOKyV3q12ML06f7MOuc5DVH8ONZIFhwIYQ3yzPH4nt7iWHaTg==}
+    engines: {node: 18 || 20 || >=22}
+
+  minipass@7.1.3:
+    resolution: {integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==}
+    engines: {node: '>=16 || 14 >=14.17'}
+
+  minizlib@3.1.0:
+    resolution: {integrity: sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==}
+    engines: {node: '>= 18'}
+
+  mri@1.2.0:
+    resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==}
+    engines: {node: '>=4'}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
+  mz@2.7.0:
+    resolution: {integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==}
+
+  nanoid@3.3.11:
+    resolution: {integrity: sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
+  negotiator@1.0.0:
+    resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
+    engines: {node: '>= 0.6'}
+
+  node-domexception@1.0.0:
+    resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==}
+    engines: {node: '>=10.5.0'}
+    deprecated: Use your platform's native DOMException instead
+
+  node-emoji@2.2.0:
+    resolution: {integrity: sha512-Z3lTE9pLaJF47NyMhd4ww1yFTAP8YhYI8SleJiHzM46Fgpm5cnNzSl9XfzFNqbaz+VlJrIj3fXQ4DeN1Rjm6cw==}
+    engines: {node: '>=18'}
+
+  node-fetch@2.7.0:
+    resolution: {integrity: sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==}
+    engines: {node: 4.x || >=6.0.0}
+    peerDependencies:
+      encoding: ^0.1.0
+    peerDependenciesMeta:
+      encoding:
+        optional: true
+
+  node-fetch@3.3.2:
+    resolution: {integrity: sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
+  node-releases@2.0.37:
+    resolution: {integrity: sha512-1h5gKZCF+pO/o3Iqt5Jp7wc9rH3eJJ0+nh/CIoiRwjRxde/hAHyLPXYN4V3CqKAbiZPSeJFSWHmJsbkicta0Eg==}
+
+  nth-check@2.1.1:
+    resolution: {integrity: sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==}
+
+  nunjucks@3.2.4:
+    resolution: {integrity: sha512-26XRV6BhkgK0VOxfbU5cQI+ICFUtMLixv1noZn1tGU38kQH5A5nmmbk/O45xdyBhD1esk47nKrY0mvQpZIhRjQ==}
+    engines: {node: '>= 6.9.0'}
+    hasBin: true
+    peerDependencies:
+      chokidar: ^3.3.0
+    peerDependenciesMeta:
+      chokidar:
+        optional: true
+
+  object-assign@4.1.1:
+    resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
+    engines: {node: '>=0.10.0'}
+
+  object-inspect@1.13.4:
+    resolution: {integrity: sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==}
+    engines: {node: '>= 0.4'}
+
+  object-keys@1.1.1:
+    resolution: {integrity: sha512-NuAESUOUMrlIXOfHKzD6bpPu3tYt3xvjNdRIQ+FeT0lNb4K8WR70CaDxhuNguS2XG+GjkyMwOzsN5ZktImfhLA==}
+    engines: {node: '>= 0.4'}
+
+  object.assign@4.1.7:
+    resolution: {integrity: sha512-nK28WOo+QIjBkDduTINE4JkF/UJJKyf2EJxvJKfblDpyg0Q+pkOHNTL0Qwy6NP6FhE/EnzV73BxxqcJaXY9anw==}
+    engines: {node: '>= 0.4'}
+
+  obug@2.1.1:
+    resolution: {integrity: sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==}
+
+  on-finished@2.4.1:
+    resolution: {integrity: sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==}
+    engines: {node: '>= 0.8'}
+
+  once@1.4.0:
+    resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==}
+
+  onetime@7.0.0:
+    resolution: {integrity: sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==}
+    engines: {node: '>=18'}
+
+  open@10.2.0:
+    resolution: {integrity: sha512-YgBpdJHPyQ2UE5x+hlSXcnejzAvD0b22U2OuAP+8OnlJT+PjWPxtgmGqKKc+RgTM63U9gN0YzrYc71R2WT/hTA==}
+    engines: {node: '>=18'}
+
+  openai@6.34.0:
+    resolution: {integrity: sha512-yEr2jdGf4tVFYG6ohmr3pF6VJuveP0EA/sS8TBx+4Eq5NT10alu5zg2dmxMXMgqpihRDQlFGpRt2XwsGj+Fyxw==}
+    hasBin: true
+    peerDependencies:
+      ws: ^8.18.0
+      zod: ^3.25 || ^4.0
+    peerDependenciesMeta:
+      ws:
+        optional: true
+      zod:
+        optional: true
+
+  outdent@0.5.0:
+    resolution: {integrity: sha512-/jHxFIzoMXdqPzTaCpFzAAWhpkSjZPF4Vsn6jAfNpmbH/ymsmd7Qc6VE9BGn0L6YMj6uwpQLxCECpus4ukKS9Q==}
+
+  own-keys@1.0.1:
+    resolution: {integrity: sha512-qFOyK5PjiWZd+QQIh+1jhdb9LpxTF0qs7Pm8o5QHYZ0M3vKqSqzsZaEB6oWlxZ+q2sJBMI/Ktgd2N5ZwQoRHfg==}
+    engines: {node: '>= 0.4'}
+
+  oxlint-tsgolint@0.20.0:
+    resolution: {integrity: sha512-/Uc9TQyN1l8w9QNvXtVHYtz+SzDJHKpb5X0UnHodl0BVzijUPk0LPlDOHAvogd1UI+iy9ZSF6gQxEqfzUxCULQ==}
+    hasBin: true
+
+  oxlint@1.59.0:
+    resolution: {integrity: sha512-0xBLeGGjP4vD9pygRo8iuOkOzEU1MqOnfiOl7KYezL/QvWL8NUg6n03zXc7ZVqltiOpUxBk2zgHI3PnRIEdAvw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      oxlint-tsgolint: '>=0.18.0'
+    peerDependenciesMeta:
+      oxlint-tsgolint:
+        optional: true
+
+  p-filter@2.1.0:
+    resolution: {integrity: sha512-ZBxxZ5sL2HghephhpGAQdoskxplTwr7ICaehZwLIlfL6acuVgZPm8yBNuRAFBGEqtD/hmUeq9eqLg2ys9Xr/yw==}
+    engines: {node: '>=8'}
+
+  p-limit@2.3.0:
+    resolution: {integrity: sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==}
+    engines: {node: '>=6'}
+
+  p-locate@4.1.0:
+    resolution: {integrity: sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==}
+    engines: {node: '>=8'}
+
+  p-map@2.1.0:
+    resolution: {integrity: sha512-y3b8Kpd8OAN444hxfBbFfj1FY/RjtTd8tzYwhUqNYXx0fXx2iX4maP4Qr6qhIKbQXI02wTLAda4fYUbDagTUFw==}
+    engines: {node: '>=6'}
+
+  p-retry@4.6.2:
+    resolution: {integrity: sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ==}
+    engines: {node: '>=8'}
+
+  p-try@2.2.0:
+    resolution: {integrity: sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==}
+    engines: {node: '>=6'}
+
+  package-manager-detector@0.2.11:
+    resolution: {integrity: sha512-BEnLolu+yuz22S56CU1SUKq3XC3PkwD5wv4ikR4MfGvnRVcmzXR9DwSlW2fEamyTPyXHomBJRzgapeuBvRNzJQ==}
+
+  package-manager-detector@1.6.0:
+    resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
+
+  parse5-htmlparser2-tree-adapter@6.0.1:
+    resolution: {integrity: sha512-qPuWvbLgvDGilKc5BoicRovlT4MtYT6JfJyBOMDsKoiT+GiuP5qyrPCnR9HcPECIJJmZh5jRndyNThnhhb/vlA==}
+
+  parse5@5.1.1:
+    resolution: {integrity: sha512-ugq4DFI0Ptb+WWjAdOK16+u/nHfiIrcE+sh8kZMaM0WllQKLI9rOUq6c2b7cwPkXdzfQESqvoqK6ug7U/Yyzug==}
+
+  parse5@6.0.1:
+    resolution: {integrity: sha512-Ofn/CTFzRGTTxwpNEs9PP93gXShHcTq255nzRYSKe8AkVpZY7e1fpmTfOyoIvjP5HG7Z2ZM7VS9PPhQGW2pOpw==}
+
+  parseurl@1.3.3:
+    resolution: {integrity: sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==}
+    engines: {node: '>= 0.8'}
+
+  path-exists@4.0.0:
+    resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==}
+    engines: {node: '>=8'}
+
+  path-key@3.1.1:
+    resolution: {integrity: sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==}
+    engines: {node: '>=8'}
+
+  path-parse@1.0.7:
+    resolution: {integrity: sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==}
+
+  path-to-regexp@8.4.2:
+    resolution: {integrity: sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==}
+
+  path-type@4.0.0:
+    resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==}
+    engines: {node: '>=8'}
+
+  pathe@2.0.3:
+    resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
+
+  pend@1.2.0:
+    resolution: {integrity: sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg==}
+
+  picocolors@1.1.1:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
+
+  picomatch@2.3.2:
+    resolution: {integrity: sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==}
+    engines: {node: '>=8.6'}
+
+  picomatch@4.0.4:
+    resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
+    engines: {node: '>=12'}
+
+  pify@4.0.1:
+    resolution: {integrity: sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g==}
+    engines: {node: '>=6'}
+
+  pkce-challenge@5.0.1:
+    resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
+    engines: {node: '>=16.20.0'}
+
+  possible-typed-array-names@1.1.0:
+    resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
+    engines: {node: '>= 0.4'}
+
+  postcss@8.5.9:
+    resolution: {integrity: sha512-7a70Nsot+EMX9fFU3064K/kdHWZqGVY+BADLyXc8Dfv+mTLLVl6JzJpPaCZ2kQL9gIJvKXSLMHhqdRRjwQeFtw==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  postject@1.0.0-alpha.6:
+    resolution: {integrity: sha512-b9Eb8h2eVqNE8edvKdwqkrY6O7kAwmI8kcnBv1NScolYJbo59XUF0noFq+lxbC1yN20bmC0WBEbDC5H/7ASb0A==}
+    engines: {node: '>=14.0.0'}
+    hasBin: true
+
+  prettier@2.8.8:
+    resolution: {integrity: sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==}
+    engines: {node: '>=10.13.0'}
+    hasBin: true
+
+  proper-lockfile@4.1.2:
+    resolution: {integrity: sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==}
+
+  protobufjs@7.5.4:
+    resolution: {integrity: sha512-CvexbZtbov6jW2eXAvLukXjXUW1TzFaivC46BpWc/3BpcCysb5Vffu+B3XHMm8lVEuy2Mm4XGex8hBSg1yapPg==}
+    engines: {node: '>=12.0.0'}
+
+  proxy-addr@2.0.7:
+    resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==}
+    engines: {node: '>= 0.10'}
+
+  publint@0.3.18:
+    resolution: {integrity: sha512-JRJFeBTrfx4qLwEuGFPk+haJOJN97KnPuK01yj+4k/Wj5BgoOK5uNsivporiqBjk2JDaslg7qJOhGRnpltGeog==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  qs@6.15.1:
+    resolution: {integrity: sha512-6YHEFRL9mfgcAvql/XhwTvf5jKcOiiupt2FiJxHkiX1z4j7WL8J/jRHYLluORvc1XxB5rV20KoeK00gVJamspg==}
+    engines: {node: '>=0.6'}
+
+  quansync@0.2.11:
+    resolution: {integrity: sha512-AifT7QEbW9Nri4tAwR5M/uzpBuqfZf+zwaEM/QkzEjj7NBuFD2rBuy0K3dE+8wltbezDV7JMA0WfnCPYRSYbXA==}
+
+  quansync@1.0.0:
+    resolution: {integrity: sha512-5xZacEEufv3HSTPQuchrvV6soaiACMFnq1H8wkVioctoH3TRha9Sz66lOxRwPK/qZj7HPiSveih9yAyh98gvqA==}
+
+  queue-microtask@1.2.3:
+    resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==}
+
+  range-parser@1.2.1:
+    resolution: {integrity: sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==}
+    engines: {node: '>= 0.6'}
+
+  raw-body@3.0.2:
+    resolution: {integrity: sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==}
+    engines: {node: '>= 0.10'}
+
+  react-dom@19.2.5:
+    resolution: {integrity: sha512-J5bAZz+DXMMwW/wV3xzKke59Af6CHY7G4uYLN1OvBcKEsWOs4pQExj86BBKamxl/Ik5bx9whOrvBlSDfWzgSag==}
+    peerDependencies:
+      react: ^19.2.5
+
+  react-refresh@0.17.0:
+    resolution: {integrity: sha512-z6F7K9bV85EfseRCp2bzrpyQ0Gkw1uLoCel9XBVWPg/TjRj94SkJzUTGfOa4bs7iJvBWtQG0Wq7wnI0syw3EBQ==}
+    engines: {node: '>=0.10.0'}
+
+  react-router-dom@7.14.1:
+    resolution: {integrity: sha512-ZkrQuwwhGibjQLqH1eCdyiZyLWglPxzxdl5tgwgKEyCSGC76vmAjleGocRe3J/MLfzMUIKwaFJWpFVJhK3d2xA==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+
+  react-router@7.14.1:
+    resolution: {integrity: sha512-5BCvFskyAAVumqhEKh/iPhLOIkfxcEUz8WqFIARCkMg8hZZzDYX9CtwxXA0e+qT8zAxmMC0x3Ckb9iMONwc5jg==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+    peerDependenciesMeta:
+      react-dom:
+        optional: true
+
+  react@19.2.5:
+    resolution: {integrity: sha512-llUJLzz1zTUBrskt2pwZgLq59AemifIftw4aB7JxOqf1HY2FDaGDxgwpAPVzHU1kdWabH7FauP4i1oEeer2WCA==}
+    engines: {node: '>=0.10.0'}
+
+  read-yaml-file@1.1.0:
+    resolution: {integrity: sha512-VIMnQi/Z4HT2Fxuwg5KrY174U1VdUIASQVWXXyqtNRtxSr9IYkn1rsI6Tb6HsrHCmB7gVpNwX6JxPTHcH6IoTA==}
+    engines: {node: '>=6'}
+
+  reflect.getprototypeof@1.0.10:
+    resolution: {integrity: sha512-00o4I+DVrefhv+nX0ulyi3biSHCPDe+yLv5o/p6d/UVlirijB8E16FtfwSAi4g3tcqrQ4lRAqQSoFEZJehYEcw==}
+    engines: {node: '>= 0.4'}
+
+  regexp.escape@2.0.1:
+    resolution: {integrity: sha512-JItRb4rmyTzmERBkAf6J87LjDPy/RscIwmaJQ3gsFlAzrmZbZU8LwBw5IydFZXW9hqpgbPlGbMhtpqtuAhMgtg==}
+    engines: {node: '>= 0.4'}
+
+  regexp.prototype.flags@1.5.4:
+    resolution: {integrity: sha512-dYqgNSZbDwkaJ2ceRd9ojCGjBq+mOm9LmtXnAnEGyHhN/5R7iDW2TRw3h+o/jCFxus3P2LfWIIiwowAjANm7IA==}
+    engines: {node: '>= 0.4'}
+
+  require-directory@2.1.1:
+    resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
+    engines: {node: '>=0.10.0'}
+
+  require-from-string@2.0.2:
+    resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
+    engines: {node: '>=0.10.0'}
+
+  resolve-from@5.0.0:
+    resolution: {integrity: sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==}
+    engines: {node: '>=8'}
+
+  resolve-pkg-maps@1.0.0:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
+  resolve@1.22.12:
+    resolution: {integrity: sha512-TyeJ1zif53BPfHootBGwPRYT1RUt6oGWsaQr8UyZW/eAm9bKoijtvruSDEmZHm92CwS9nj7/fWttqPCgzep8CA==}
+    engines: {node: '>= 0.4'}
+    hasBin: true
+
+  restore-cursor@5.1.0:
+    resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
+    engines: {node: '>=18'}
+
+  retry@0.12.0:
+    resolution: {integrity: sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow==}
+    engines: {node: '>= 4'}
+
+  retry@0.13.1:
+    resolution: {integrity: sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg==}
+    engines: {node: '>= 4'}
+
+  reusify@1.1.0:
+    resolution: {integrity: sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==}
+    engines: {iojs: '>=1.0.0', node: '>=0.10.0'}
+
+  rfdc@1.4.1:
+    resolution: {integrity: sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==}
+
+  rolldown-plugin-dts@0.25.1:
+    resolution: {integrity: sha512-zK82aC/8z1iVW+g0bCnlQZq04Y5bNeL/RcRwTYBwsnU6wH0N+6vpIFkN7JC0kYRS5qKA+pxQyfIPvXJ6Q5xSpQ==}
+    engines: {node: ^22.18.0 || >=24.0.0}
+    peerDependencies:
+      '@ts-macro/tsc': ^0.3.6
+      '@typescript/native-preview': '>=7.0.0-dev.20260325.1'
+      rolldown: ^1.0.0
+      typescript: ^5.0.0 || ^6.0.0
+      vue-tsc: ~3.2.0
+    peerDependenciesMeta:
+      '@ts-macro/tsc':
+        optional: true
+      '@typescript/native-preview':
+        optional: true
+      typescript:
+        optional: true
+      vue-tsc:
+        optional: true
+
+  rolldown@1.0.0-rc.12:
+    resolution: {integrity: sha512-yP4USLIMYrwpPHEFB5JGH1uxhcslv6/hL0OyvTuY+3qlOSJvZ7ntYnoWpehBxufkgN0cvXxppuTu5hHa/zPh+A==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+
+  rolldown@1.0.0-rc.15:
+    resolution: {integrity: sha512-Ff31guA5zT6WjnGp0SXw76X6hzGRk/OQq2hE+1lcDe+lJdHSgnSX6nK3erbONHyCbpSj9a9E+uX/OvytZoWp2g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+
+  rolldown@1.0.1:
+    resolution: {integrity: sha512-X0KQHljNnEkWNqqiz9zJrGunh1B0HgOxLXvnFpCOcadzcy5qohZ3tqMEUg00vncoRovXuK3ZqCT9KnnKzoInFQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+
+  rollup@4.60.2:
+    resolution: {integrity: sha512-J9qZyW++QK/09NyN/zeO0dG/1GdGfyp9lV8ajHnRVLfo/uFsbji5mHnDgn/qYdUHyCkM2N+8VyspgZclfAh0eQ==}
+    engines: {node: '>=18.0.0', npm: '>=8.0.0'}
+    hasBin: true
+
+  router@2.2.0:
+    resolution: {integrity: sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==}
+    engines: {node: '>= 18'}
+
+  run-applescript@7.1.0:
+    resolution: {integrity: sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q==}
+    engines: {node: '>=18'}
+
+  run-parallel@1.2.0:
+    resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
+
+  rxjs@7.8.2:
+    resolution: {integrity: sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA==}
+
+  sade@1.8.1:
+    resolution: {integrity: sha512-xal3CZX1Xlo/k4ApwCFrHVACi9fBqJ7V+mwhBsuf/1IOKbBy098Fex+Wa/5QMubw09pSZ/u8EY8PWgevJsXp1A==}
+    engines: {node: '>=6'}
+
+  safe-array-concat@1.1.4:
+    resolution: {integrity: sha512-wtZlHyOje6OZTGqAoaDKxFkgRtkF9CnHAVnCHKfuj200wAgL+bSJhdsCD2l0Qx/2ekEXjPWcyKkfGb5CPboslg==}
+    engines: {node: '>=0.4'}
+
+  safe-buffer@5.2.1:
+    resolution: {integrity: sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==}
+
+  safe-push-apply@1.0.0:
+    resolution: {integrity: sha512-iKE9w/Z7xCzUMIZqdBsp6pEQvwuEebH4vdpjcDWnyzaI6yl6O9FHvVpmGelvEHNsoY6wGblkxR6Zty/h00WiSA==}
+    engines: {node: '>= 0.4'}
+
+  safe-regex-test@1.1.0:
+    resolution: {integrity: sha512-x/+Cz4YrimQxQccJf5mKEbIa1NzeCRNI5Ecl/ekmlYaampdNLPalVyIcCZNNH3MvmqBugV5TMYZXv0ljslUlaw==}
+    engines: {node: '>= 0.4'}
+
+  safer-buffer@2.1.2:
+    resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
+
+  scheduler@0.27.0:
+    resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
+
+  semver@6.3.1:
+    resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
+    hasBin: true
+
+  semver@7.7.4:
+    resolution: {integrity: sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==}
+    engines: {node: '>=10'}
+    hasBin: true
+
+  send@1.2.1:
+    resolution: {integrity: sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==}
+    engines: {node: '>= 18'}
+
+  serve-static@2.2.1:
+    resolution: {integrity: sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==}
+    engines: {node: '>= 18'}
+
+  set-cookie-parser@2.7.2:
+    resolution: {integrity: sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==}
+
+  set-function-length@1.2.2:
+    resolution: {integrity: sha512-pgRc4hJ4/sNjWCSS9AmnS40x3bNMDTknHgL5UaMBTMyJnU90EgWh1Rz+MC9eFu4BuN/UwZjKQuY/1v3rM7HMfg==}
+    engines: {node: '>= 0.4'}
+
+  set-function-name@2.0.2:
+    resolution: {integrity: sha512-7PGFlmtwsEADb0WYyvCMa1t+yke6daIG4Wirafur5kcf+MhUnPms1UeR0CKQdTZD81yESwMHbtn+TR+dMviakQ==}
+    engines: {node: '>= 0.4'}
+
+  set-proto@1.0.0:
+    resolution: {integrity: sha512-RJRdvCo6IAnPdsvP/7m6bsQqNnn1FCBX5ZNtFL98MmFF/4xAIJTIg1YbHW5DC2W5SKZanrC6i4HsJqlajw/dZw==}
+    engines: {node: '>= 0.4'}
+
+  setprototypeof@1.2.0:
+    resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==}
+
+  shebang-command@2.0.0:
+    resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==}
+    engines: {node: '>=8'}
+
+  shebang-regex@3.0.0:
+    resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
+    engines: {node: '>=8'}
+
+  shell-quote@1.8.3:
+    resolution: {integrity: sha512-ObmnIF4hXNg1BqhnHmgbDETF8dLPCggZWBjkQfhZpbszZnYur5DUljTcCHii5LC3J5E0yeO/1LIMyH+UvHQgyw==}
+    engines: {node: '>= 0.4'}
+
+  sherif-darwin-arm64@1.11.1:
+    resolution: {integrity: sha512-VoMrUv5QY6hQ2rByNa3AAhr/KGQsCb6pvAUNKa1iCh1jvnY836hQr6zNBw9hYCDkVv6t9sITFGJljwdTCQD4xw==}
+    cpu: [arm64]
+    os: [darwin]
+
+  sherif-darwin-x64@1.11.1:
+    resolution: {integrity: sha512-7j3yOCBkvVbltVT3lXoiazGfG2nb36FteYT5VZPEBSf8sTn1pPTScukAQ1Fdl+MphadGyici7XlRbDrtZ/wnvA==}
+    cpu: [x64]
+    os: [darwin]
+
+  sherif-linux-arm64-musl@1.11.1:
+    resolution: {integrity: sha512-DCf87RFqBh8ZrYgu3y+fv0x4kFn/np84m2jAEgygznwozH/VCfrXbHFVdhxW7762JCYkXbHO9dUj/ff5fkvkvw==}
+    cpu: [arm64]
+    os: [linux]
+
+  sherif-linux-arm64@1.11.1:
+    resolution: {integrity: sha512-vCZFS7RxhZ/8g9bdj3UPNVPTcZiKiWigW+FIlVQEUKEKfG0MfSOMBJqEWPVVUniyJa3rdIxtmZKSdWkG0e1x3w==}
+    cpu: [arm64]
+    os: [linux]
+
+  sherif-linux-x64-musl@1.11.1:
+    resolution: {integrity: sha512-f8xitqXdHObUFPZo4QVbz3o30Y4+gHA3B5ZobsOWocnSfJBaUGutBzJsUsjG6w2tccSRn6+mugiMUGKIbIPZmQ==}
+    cpu: [x64]
+    os: [linux]
+
+  sherif-linux-x64@1.11.1:
+    resolution: {integrity: sha512-9t+p1X3SyhU75BrJNHBbj9i/aQxHC/sF+Mdkf17V5AlokCznFgYKQUXq5EVmcmRDDhDl69RMzCTLD95EBqUSYA==}
+    cpu: [x64]
+    os: [linux]
+
+  sherif-windows-arm64@1.11.1:
+    resolution: {integrity: sha512-Dnffgcyz9zLq/8UTY2REchJzRJWcWAuMWo5Vl5O17IZGkhl71dwa7/Vi2wC3EQd8WAVK/O82yArOYggWA0dj5w==}
+    cpu: [arm64]
+    os: [win32]
+
+  sherif-windows-x64@1.11.1:
+    resolution: {integrity: sha512-xjfYUL/IQ65DwHkRsWIxiZWtglKtL5/E3UHpnLwOui3jqW1V2K88SMct415dnlBQiL3U9VEIVUo1i+KmToOBgQ==}
+    cpu: [x64]
+    os: [win32]
+
+  sherif@1.11.1:
+    resolution: {integrity: sha512-HBFce8NGaPuWPg5NXb6+aI7hJQFjTilhtbrgo+Y/BvtGlkuJAzLnkmC8nyD+p3v7oIAq4KQeA8qySKGga28xZg==}
+    hasBin: true
+
+  side-channel-list@1.0.1:
+    resolution: {integrity: sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==}
+    engines: {node: '>= 0.4'}
+
+  side-channel-map@1.0.1:
+    resolution: {integrity: sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==}
+    engines: {node: '>= 0.4'}
+
+  side-channel-weakmap@1.0.2:
+    resolution: {integrity: sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==}
+    engines: {node: '>= 0.4'}
+
+  side-channel@1.1.0:
+    resolution: {integrity: sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==}
+    engines: {node: '>= 0.4'}
+
+  siginfo@2.0.0:
+    resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==}
+
+  signal-exit@3.0.7:
+    resolution: {integrity: sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==}
+
+  signal-exit@4.1.0:
+    resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
+    engines: {node: '>=14'}
+
+  simple-git-hooks@2.13.1:
+    resolution: {integrity: sha512-WszCLXwT4h2k1ufIXAgsbiTOazqqevFCIncOuUBZJ91DdvWcC5+OFkluWRQPrcuSYd8fjq+o2y1QfWqYMoAToQ==}
+    hasBin: true
+
+  skin-tone@2.0.0:
+    resolution: {integrity: sha512-kUMbT1oBJCpgrnKoSr0o6wPtvRWT9W9UKvGLwfJYO2WuahZRHOpEyL1ckyMGgMWh0UdpmaoFqKKD29WTomNEGA==}
+    engines: {node: '>=8'}
+
+  slash@3.0.0:
+    resolution: {integrity: sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==}
+    engines: {node: '>=8'}
+
+  slice-ansi@7.1.2:
+    resolution: {integrity: sha512-iOBWFgUX7caIZiuutICxVgX1SdxwAVFFKwt1EvMYYec/NWO5meOJ6K5uQxhrYBdQJne4KxiqZc+KptFOWFSI9w==}
+    engines: {node: '>=18'}
+
+  slice-ansi@8.0.0:
+    resolution: {integrity: sha512-stxByr12oeeOyY2BlviTNQlYV5xOj47GirPr4yA1hE9JCtxfQN0+tVbkxwCtYDQWhEKWFHsEK48ORg5jrouCAg==}
+    engines: {node: '>=20'}
+
+  smol-toml@1.6.1:
+    resolution: {integrity: sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg==}
+    engines: {node: '>= 18'}
+
+  source-map-js@1.2.1:
+    resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
+    engines: {node: '>=0.10.0'}
+
+  source-map@0.6.1:
+    resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==}
+    engines: {node: '>=0.10.0'}
+
+  spawndamnit@3.0.1:
+    resolution: {integrity: sha512-MmnduQUuHCoFckZoWnXsTg7JaiLBJrKFj9UI2MbRPGaJeVpsLcVBu6P/IGZovziM/YBsellCmsprgNA+w0CzVg==}
+
+  sprintf-js@1.0.3:
+    resolution: {integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==}
+
+  ssh2@1.17.0:
+    resolution: {integrity: sha512-wPldCk3asibAjQ/kziWQQt1Wh3PgDFpC0XpwclzKcdT1vql6KeYxf5LIt4nlFkUeR8WuphYMKqUA56X4rjbfgQ==}
+    engines: {node: '>=10.16.0'}
+
+  stackback@0.0.2:
+    resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
+
+  standardwebhooks@1.0.0:
+    resolution: {integrity: sha512-BbHGOQK9olHPMvQNHWul6MYlrRTAOKn03rOe4A8O3CLWhNf4YHBqq2HJKKC+sfqpxiBY52pNeesD6jIiLDz8jg==}
+
+  statuses@2.0.2:
+    resolution: {integrity: sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==}
+    engines: {node: '>= 0.8'}
+
+  std-env@4.0.0:
+    resolution: {integrity: sha512-zUMPtQ/HBY3/50VbpkupYHbRroTRZJPRLvreamgErJVys0ceuzMkD44J/QjqhHjOzK42GQ3QZIeFG1OYfOtKqQ==}
+
+  stop-iteration-iterator@1.1.0:
+    resolution: {integrity: sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ==}
+    engines: {node: '>= 0.4'}
+
+  string-argv@0.3.2:
+    resolution: {integrity: sha512-aqD2Q0144Z+/RqG52NeHEkZauTAUWJO8c6yTftGJKO3Tja5tUgIfmIl6kExvhtxSDP7fXB6DvzkfMpCd/F3G+Q==}
+    engines: {node: '>=0.6.19'}
+
+  string-width@4.2.3:
+    resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
+    engines: {node: '>=8'}
+
+  string-width@7.2.0:
+    resolution: {integrity: sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==}
+    engines: {node: '>=18'}
+
+  string-width@8.2.0:
+    resolution: {integrity: sha512-6hJPQ8N0V0P3SNmP6h2J99RLuzrWz2gvT7VnK5tKvrNqJoyS9W4/Fb8mo31UiPvy00z7DQXkP2hnKBVav76thw==}
+    engines: {node: '>=20'}
+
+  string.prototype.trim@1.2.10:
+    resolution: {integrity: sha512-Rs66F0P/1kedk5lyYyH9uBzuiI/kNRmwJAR9quK6VOtIpZ2G+hMZd+HQbbv25MgCA6gEffoMZYxlTod4WcdrKA==}
+    engines: {node: '>= 0.4'}
+
+  string.prototype.trimend@1.0.9:
+    resolution: {integrity: sha512-G7Ok5C6E/j4SGfyLCloXTrngQIQU3PWtXGst3yM7Bea9FRURf1S42ZHlZZtsNque2FN2PoUhfZXYLNWwEr4dLQ==}
+    engines: {node: '>= 0.4'}
+
+  string.prototype.trimstart@1.0.8:
+    resolution: {integrity: sha512-UXSH262CSZY1tfu3G3Secr6uGLCFVPMhIqHjlgCUtCCcgihYc/xKs9djMTMUOb2j1mVSeU8EU6NWc/iQKU6Gfg==}
+    engines: {node: '>= 0.4'}
+
+  strip-ansi@6.0.1:
+    resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==}
+    engines: {node: '>=8'}
+
+  strip-ansi@7.2.0:
+    resolution: {integrity: sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==}
+    engines: {node: '>=12'}
+
+  strip-bom@3.0.0:
+    resolution: {integrity: sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==}
+    engines: {node: '>=4'}
+
+  supports-color@7.2.0:
+    resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
+    engines: {node: '>=8'}
+
+  supports-color@8.1.1:
+    resolution: {integrity: sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==}
+    engines: {node: '>=10'}
+
+  supports-hyperlinks@3.2.0:
+    resolution: {integrity: sha512-zFObLMyZeEwzAoKCyu1B91U79K2t7ApXuQfo8OuxwXLDgcKxuwM+YvcbIhm6QWqz7mHUH1TVytR1PwVVjEuMig==}
+    engines: {node: '>=14.18'}
+
+  supports-preserve-symlinks-flag@1.0.0:
+    resolution: {integrity: sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==}
+    engines: {node: '>= 0.4'}
+
+  tailwindcss@4.2.2:
+    resolution: {integrity: sha512-KWBIxs1Xb6NoLdMVqhbhgwZf2PGBpPEiwOqgI4pFIYbNTfBXiKYyWoTsXgBQ9WFg/OlhnvHaY+AEpW7wSmFo2Q==}
+
+  tapable@2.3.2:
+    resolution: {integrity: sha512-1MOpMXuhGzGL5TTCZFItxCc0AARf1EZFQkGqMm7ERKj8+Hgr5oLvJOVFcC+lRmR8hCe2S3jC4T5D7Vg/d7/fhA==}
+    engines: {node: '>=6'}
+
+  tar@7.5.13:
+    resolution: {integrity: sha512-tOG/7GyXpFevhXVh8jOPJrmtRpOTsYqUIkVdVooZYJS/z8WhfQUX8RJILmeuJNinGAMSu1veBr4asSHFt5/hng==}
+    engines: {node: '>=18'}
+
+  term-size@2.2.1:
+    resolution: {integrity: sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg==}
+    engines: {node: '>=8'}
+
+  thenify-all@1.6.0:
+    resolution: {integrity: sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==}
+    engines: {node: '>=0.8'}
+
+  thenify@3.3.1:
+    resolution: {integrity: sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw==}
+
+  tinybench@2.9.0:
+    resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
+
+  tinyexec@1.1.1:
+    resolution: {integrity: sha512-VKS/ZaQhhkKFMANmAOhhXVoIfBXblQxGX1myCQ2faQrfmobMftXeJPcZGp0gS07ocvGJWDLZGyOZDadDBqYIJg==}
+    engines: {node: '>=18'}
+
+  tinyexec@1.1.2:
+    resolution: {integrity: sha512-dAqSqE/RabpBKI8+h26GfLq6Vb3JVXs30XYQjdMjaj/c2tS8IYYMbIzP599KtRj7c57/wYApb3QjgRgXmrCukA==}
+    engines: {node: '>=18'}
+
+  tinyglobby@0.2.16:
+    resolution: {integrity: sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==}
+    engines: {node: '>=12.0.0'}
+
+  tinyrainbow@3.1.0:
+    resolution: {integrity: sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==}
+    engines: {node: '>=14.0.0'}
+
+  to-regex-range@5.0.1:
+    resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==}
+    engines: {node: '>=8.0'}
+
+  toidentifier@1.0.1:
+    resolution: {integrity: sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==}
+    engines: {node: '>=0.6'}
+
+  tr46@0.0.3:
+    resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==}
+
+  tree-kill@1.2.2:
+    resolution: {integrity: sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==}
+    hasBin: true
+
+  ts-algebra@2.0.0:
+    resolution: {integrity: sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==}
+
+  tsdown@0.22.0:
+    resolution: {integrity: sha512-FgW0hHb27nGQA/+F3d5+U9wKXkfilk9DVkc5+7x/ZqF03g+Hoz/eeApT32jqxATt9eRoR+1jxk7MUMON+O4CXw==}
+    engines: {node: ^22.18.0 || >=24.0.0}
+    hasBin: true
+    peerDependencies:
+      '@arethetypeswrong/core': ^0.18.1
+      '@tsdown/css': 0.22.0
+      '@tsdown/exe': 0.22.0
+      '@vitejs/devtools': '*'
+      publint: ^0.3.8
+      tsx: '*'
+      typescript: ^5.0.0 || ^6.0.0
+      unplugin-unused: ^0.5.0
+      unrun: '*'
+    peerDependenciesMeta:
+      '@arethetypeswrong/core':
+        optional: true
+      '@tsdown/css':
+        optional: true
+      '@tsdown/exe':
+        optional: true
+      '@vitejs/devtools':
+        optional: true
+      publint:
+        optional: true
+      tsx:
+        optional: true
+      typescript:
+        optional: true
+      unplugin-unused:
+        optional: true
+      unrun:
+        optional: true
+
+  tslib@2.8.1:
+    resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
+
+  tsx@4.21.0:
+    resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  tweetnacl@0.14.5:
+    resolution: {integrity: sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA==}
+
+  type-is@2.0.1:
+    resolution: {integrity: sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw==}
+    engines: {node: '>= 0.6'}
+
+  typed-array-buffer@1.0.3:
+    resolution: {integrity: sha512-nAYYwfY3qnzX30IkA6AQZjVbtK6duGontcQm1WSG1MD94YLqK0515GNApXkoxKOWMusVssAHWLh9SeaoefYFGw==}
+    engines: {node: '>= 0.4'}
+
+  typed-array-byte-length@1.0.3:
+    resolution: {integrity: sha512-BaXgOuIxz8n8pIq3e7Atg/7s+DpiYrxn4vdot3w9KbnBhcRQq6o3xemQdIfynqSeXeDrF32x+WvfzmOjPiY9lg==}
+    engines: {node: '>= 0.4'}
+
+  typed-array-byte-offset@1.0.4:
+    resolution: {integrity: sha512-bTlAFB/FBYMcuX81gbL4OcpH5PmlFHqlCCpAl8AlEzMz5k53oNDvN8p1PNOWLEmI2x4orp3raOFB51tv9X+MFQ==}
+    engines: {node: '>= 0.4'}
+
+  typed-array-length@1.0.7:
+    resolution: {integrity: sha512-3KS2b+kL7fsuk/eJZ7EQdnEmQoaho/r6KUef7hxvltNA5DR8NAUM+8wJMbJyZ4G9/7i3v5zPBIMN5aybAh2/Jg==}
+    engines: {node: '>= 0.4'}
+
+  typescript@5.6.1-rc:
+    resolution: {integrity: sha512-E3b2+1zEFu84jB0YQi9BORDjz9+jGbwwy1Zi3G0LUNw7a7cePUrHMRNy8aPh53nXpkFGVHSxIZo5vKTfYaFiBQ==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  typescript@6.0.2:
+    resolution: {integrity: sha512-bGdAIrZ0wiGDo5l8c++HWtbaNCWTS4UTv7RaTH/ThVIgjkveJt83m74bBHMJkuCbslY8ixgLBVZJIOiQlQTjfQ==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  uhyphen@0.2.0:
+    resolution: {integrity: sha512-qz3o9CHXmJJPGBdqzab7qAYuW8kQGKNEuoHFYrBwV6hWIMcpAmxDLXojcHfFr9US1Pe6zUswEIJIbLI610fuqA==}
+
+  unbox-primitive@1.1.0:
+    resolution: {integrity: sha512-nWJ91DjeOkej/TA8pXQ3myruKpKEYgqvpw9lz4OPHj/NWFNluYrjbz9j01CJ8yKQd2g4jFoOkINCTW2I5LEEyw==}
+    engines: {node: '>= 0.4'}
+
+  unconfig-core@7.5.0:
+    resolution: {integrity: sha512-Su3FauozOGP44ZmKdHy2oE6LPjk51M/TRRjHv2HNCWiDvfvCoxC2lno6jevMA91MYAdCdwP05QnWdWpSbncX/w==}
+
+  undici-types@5.26.5:
+    resolution: {integrity: sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==}
+
+  undici-types@6.21.0:
+    resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+
+  unicode-emoji-modifier-base@1.0.0:
+    resolution: {integrity: sha512-yLSH4py7oFH3oG/9K+XWrz1pSi3dfUrWEnInbxMfArOfc1+33BlGPQtLsOYwvdMy11AwUBetYuaRxSPqgkq+8g==}
+    engines: {node: '>=4'}
+
+  universalify@0.1.2:
+    resolution: {integrity: sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==}
+    engines: {node: '>= 4.0.0'}
+
+  universalify@2.0.1:
+    resolution: {integrity: sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==}
+    engines: {node: '>= 10.0.0'}
+
+  unpipe@1.0.0:
+    resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==}
+    engines: {node: '>= 0.8'}
+
+  unrun@0.2.34:
+    resolution: {integrity: sha512-LyaghRBR++r7svhDK6tnDz2XaYHWdneBOA0jbS8wnRsHerI9MFljX4fIiTgbbNbEVzZ0C9P1OjWLLe1OqoaaEw==}
+    engines: {node: '>=20.19.0'}
+    hasBin: true
+    peerDependencies:
+      synckit: ^0.11.11
+    peerDependenciesMeta:
+      synckit:
+        optional: true
+
+  update-browserslist-db@1.2.3:
+    resolution: {integrity: sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==}
+    hasBin: true
+    peerDependencies:
+      browserslist: '>= 4.21.0'
+
+  validate-npm-package-name@5.0.1:
+    resolution: {integrity: sha512-OljLrQ9SQdOUqTaQxqL5dEfZWrXExyyWsozYlAWFawPVNuD83igl7uJD2RTkNMbniIYgt8l81eCJGIdQF7avLQ==}
+    engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0}
+
+  vary@1.1.2:
+    resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
+    engines: {node: '>= 0.8'}
+
+  vite@6.4.2:
+    resolution: {integrity: sha512-2N/55r4JDJ4gdrCvGgINMy+HH3iRpNIz8K6SFwVsA+JbQScLiC+clmAxBgwiSPgcG9U15QmvqCGWzMbqda5zGQ==}
+    engines: {node: ^18.0.0 || ^20.0.0 || >=22.0.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^18.0.0 || ^20.0.0 || >=22.0.0
+      jiti: '>=1.21.0'
+      less: '*'
+      lightningcss: ^1.21.0
+      sass: '*'
+      sass-embedded: '*'
+      stylus: '*'
+      sugarss: '*'
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      lightningcss:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
+  vite@8.0.8:
+    resolution: {integrity: sha512-dbU7/iLVa8KZALJyLOBOQ88nOXtNG8vxKuOT4I2mD+Ya70KPceF4IAmDsmU0h1Qsn5bPrvsY9HJstCRh3hG6Uw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^20.19.0 || >=22.12.0
+      '@vitejs/devtools': ^0.1.0
+      esbuild: ^0.27.0 || ^0.28.0
+      jiti: '>=1.21.0'
+      less: ^4.0.0
+      sass: ^1.70.0
+      sass-embedded: ^1.70.0
+      stylus: '>=0.54.8'
+      sugarss: ^5.0.0
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      '@vitejs/devtools':
+        optional: true
+      esbuild:
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
+  vitest@4.1.4:
+    resolution: {integrity: sha512-tFuJqTxKb8AvfyqMfnavXdzfy3h3sWZRWwfluGbkeR7n0HUev+FmNgZ8SDrRBTVrVCjgH5cA21qGbCffMNtWvg==}
+    engines: {node: ^20.0.0 || ^22.0.0 || >=24.0.0}
+    hasBin: true
+    peerDependencies:
+      '@edge-runtime/vm': '*'
+      '@opentelemetry/api': ^1.9.0
+      '@types/node': ^20.0.0 || ^22.0.0 || >=24.0.0
+      '@vitest/browser-playwright': 4.1.4
+      '@vitest/browser-preview': 4.1.4
+      '@vitest/browser-webdriverio': 4.1.4
+      '@vitest/coverage-istanbul': 4.1.4
+      '@vitest/coverage-v8': 4.1.4
+      '@vitest/ui': 4.1.4
+      happy-dom: '*'
+      jsdom: '*'
+      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      '@edge-runtime/vm':
+        optional: true
+      '@opentelemetry/api':
+        optional: true
+      '@types/node':
+        optional: true
+      '@vitest/browser-playwright':
+        optional: true
+      '@vitest/browser-preview':
+        optional: true
+      '@vitest/browser-webdriverio':
+        optional: true
+      '@vitest/coverage-istanbul':
+        optional: true
+      '@vitest/coverage-v8':
+        optional: true
+      '@vitest/ui':
+        optional: true
+      happy-dom:
+        optional: true
+      jsdom:
+        optional: true
+
+  web-streams-polyfill@3.3.3:
+    resolution: {integrity: sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==}
+    engines: {node: '>= 8'}
+
+  webidl-conversions@3.0.1:
+    resolution: {integrity: sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==}
+
+  whatwg-url@5.0.0:
+    resolution: {integrity: sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==}
+
+  which-boxed-primitive@1.1.1:
+    resolution: {integrity: sha512-TbX3mj8n0odCBFVlY8AxkqcHASw3L60jIuF8jFP78az3C2YhmGvqbHBpAjTRH2/xqYunrJ9g1jSyjCjpoWzIAA==}
+    engines: {node: '>= 0.4'}
+
+  which-builtin-type@1.2.1:
+    resolution: {integrity: sha512-6iBczoX+kDQ7a3+YJBnh3T+KZRxM/iYNPXicqk66/Qfm1b93iu+yOImkg0zHbj5LNOcNv1TEADiZ0xa34B4q6Q==}
+    engines: {node: '>= 0.4'}
+
+  which-collection@1.0.2:
+    resolution: {integrity: sha512-K4jVyjnBdgvc86Y6BkaLZEN933SwYOuBFkdmBu9ZfkcAbdVbpITnDmjvZ/aQjRXQrv5EPkTnD1s39GiiqbngCw==}
+    engines: {node: '>= 0.4'}
+
+  which-typed-array@1.1.20:
+    resolution: {integrity: sha512-LYfpUkmqwl0h9A2HL09Mms427Q1RZWuOHsukfVcKRq9q95iQxdw0ix1JQrqbcDR9PH1QDwf5Qo8OZb5lksZ8Xg==}
+    engines: {node: '>= 0.4'}
+
+  which@2.0.2:
+    resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
+    engines: {node: '>= 8'}
+    hasBin: true
+
+  why-is-node-running@2.3.0:
+    resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==}
+    engines: {node: '>=8'}
+    hasBin: true
+
+  wrap-ansi@7.0.0:
+    resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
+    engines: {node: '>=10'}
+
+  wrap-ansi@9.0.2:
+    resolution: {integrity: sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==}
+    engines: {node: '>=18'}
+
+  wrappy@1.0.2:
+    resolution: {integrity: sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==}
+
+  ws@8.20.0:
+    resolution: {integrity: sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==}
+    engines: {node: '>=10.0.0'}
+    peerDependencies:
+      bufferutil: ^4.0.1
+      utf-8-validate: '>=5.0.2'
+    peerDependenciesMeta:
+      bufferutil:
+        optional: true
+      utf-8-validate:
+        optional: true
+
+  wsl-utils@0.1.0:
+    resolution: {integrity: sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw==}
+    engines: {node: '>=18'}
+
+  y18n@5.0.8:
+    resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
+    engines: {node: '>=10'}
+
+  yallist@3.1.1:
+    resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
+
+  yallist@5.0.0:
+    resolution: {integrity: sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==}
+    engines: {node: '>=18'}
+
+  yaml@2.8.3:
+    resolution: {integrity: sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
+  yargs-parser@20.2.9:
+    resolution: {integrity: sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==}
+    engines: {node: '>=10'}
+
+  yargs-parser@21.1.1:
+    resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
+    engines: {node: '>=12'}
+
+  yargs@16.2.0:
+    resolution: {integrity: sha512-D1mvvtDG0L5ft/jGWkLpG1+m0eQxOfaBvTNELraWj22wSVUMWxZUvYgJYcKh6jGGIkJFhH4IZPQhR4TKpc8mBw==}
+    engines: {node: '>=10'}
+
+  yargs@17.7.2:
+    resolution: {integrity: sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==}
+    engines: {node: '>=12'}
+
+  yauzl@3.3.0:
+    resolution: {integrity: sha512-PtGEvEP30p7sbIBJKUBjUnqgTVOyMURc4dLo9iNyAJnNIEz9pm88cCXF21w94Kg3k6RXkeZh5DHOGS0qEONvNQ==}
+    engines: {node: '>=12'}
+
+  yazl@3.3.1:
+    resolution: {integrity: sha512-BbETDVWG+VcMUle37k5Fqp//7SDOK2/1+T7X8TD96M3D9G8jK5VLUdQVdVjGi8im7FGkazX7kk5hkU8X4L5Bng==}
+
+  zod-to-json-schema@3.25.2:
+    resolution: {integrity: sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==}
+    peerDependencies:
+      zod: ^3.25.28 || ^4
+
+  zod@4.3.6:
+    resolution: {integrity: sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==}
+
+snapshots:
+
+  '@andrewbranch/untar.js@1.0.3': {}
+
+  '@antfu/utils@9.3.0': {}
+
+  '@anthropic-ai/sdk@0.95.2(zod@4.3.6)':
+    dependencies:
+      json-schema-to-ts: 3.1.1
+      standardwebhooks: 1.0.0
+    optionalDependencies:
+      zod: 4.3.6
+
+  '@arethetypeswrong/cli@0.18.2':
+    dependencies:
+      '@arethetypeswrong/core': 0.18.2
+      chalk: 4.1.2
+      cli-table3: 0.6.5
+      commander: 10.0.1
+      marked: 9.1.6
+      marked-terminal: 7.3.0(marked@9.1.6)
+      semver: 7.7.4
+
+  '@arethetypeswrong/core@0.18.2':
+    dependencies:
+      '@andrewbranch/untar.js': 1.0.3
+      '@loaderkit/resolve': 1.0.4
+      cjs-module-lexer: 1.4.3
+      fflate: 0.8.2
+      lru-cache: 11.3.3
+      semver: 7.7.4
+      typescript: 5.6.1-rc
+      validate-npm-package-name: 5.0.1
+
+  '@babel/code-frame@7.29.0':
+    dependencies:
+      '@babel/helper-validator-identifier': 7.28.5
+      js-tokens: 4.0.0
+      picocolors: 1.1.1
+
+  '@babel/compat-data@7.29.0': {}
+
+  '@babel/core@7.29.0':
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      '@babel/generator': 7.29.1
+      '@babel/helper-compilation-targets': 7.28.6
+      '@babel/helper-module-transforms': 7.28.6(@babel/core@7.29.0)
+      '@babel/helpers': 7.29.2
+      '@babel/parser': 7.29.2
+      '@babel/template': 7.28.6
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
+      '@jridgewell/remapping': 2.3.5
+      convert-source-map: 2.0.0
+      debug: 4.4.3
+      gensync: 1.0.0-beta.2
+      json5: 2.2.3
+      semver: 6.3.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/generator@7.29.1':
+    dependencies:
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+      jsesc: 3.1.0
+
+  '@babel/generator@8.0.0-rc.5':
+    dependencies:
+      '@babel/parser': 8.0.0-rc.5
+      '@babel/types': 8.0.0-rc.5
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+      '@types/jsesc': 2.5.1
+      jsesc: 3.1.0
+
+  '@babel/helper-compilation-targets@7.28.6':
+    dependencies:
+      '@babel/compat-data': 7.29.0
+      '@babel/helper-validator-option': 7.27.1
+      browserslist: 4.28.2
+      lru-cache: 5.1.1
+      semver: 6.3.1
+
+  '@babel/helper-globals@7.28.0': {}
+
+  '@babel/helper-module-imports@7.28.6':
+    dependencies:
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-module-transforms@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-module-imports': 7.28.6
+      '@babel/helper-validator-identifier': 7.28.5
+      '@babel/traverse': 7.29.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-plugin-utils@7.28.6': {}
+
+  '@babel/helper-string-parser@7.27.1': {}
+
+  '@babel/helper-string-parser@8.0.0-rc.5': {}
+
+  '@babel/helper-validator-identifier@7.28.5': {}
+
+  '@babel/helper-validator-identifier@8.0.0-rc.5': {}
+
+  '@babel/helper-validator-option@7.27.1': {}
+
+  '@babel/helpers@7.29.2':
+    dependencies:
+      '@babel/template': 7.28.6
+      '@babel/types': 7.29.0
+
+  '@babel/parser@7.29.2':
+    dependencies:
+      '@babel/types': 7.29.0
+
+  '@babel/parser@8.0.0-rc.4':
+    dependencies:
+      '@babel/types': 8.0.0-rc.5
+
+  '@babel/parser@8.0.0-rc.5':
+    dependencies:
+      '@babel/types': 8.0.0-rc.5
+
+  '@babel/plugin-transform-react-jsx-self@7.27.1(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-plugin-utils': 7.28.6
+
+  '@babel/plugin-transform-react-jsx-source@7.27.1(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-plugin-utils': 7.28.6
+
+  '@babel/runtime@7.29.2': {}
+
+  '@babel/template@7.28.6':
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
+
+  '@babel/traverse@7.29.0':
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      '@babel/generator': 7.29.1
+      '@babel/helper-globals': 7.28.0
+      '@babel/parser': 7.29.2
+      '@babel/template': 7.28.6
+      '@babel/types': 7.29.0
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/types@7.29.0':
+    dependencies:
+      '@babel/helper-string-parser': 7.27.1
+      '@babel/helper-validator-identifier': 7.28.5
+
+  '@babel/types@8.0.0-rc.5':
+    dependencies:
+      '@babel/helper-string-parser': 8.0.0-rc.5
+      '@babel/helper-validator-identifier': 8.0.0-rc.5
+
+  '@bcoe/v8-coverage@1.0.2': {}
+
+  '@braidai/lang@1.1.2': {}
+
+  '@changesets/apply-release-plan@7.1.0':
+    dependencies:
+      '@changesets/config': 3.1.3
+      '@changesets/get-version-range-type': 0.4.0
+      '@changesets/git': 3.0.4
+      '@changesets/should-skip-package': 0.1.2
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+      detect-indent: 6.1.0
+      fs-extra: 7.0.1
+      lodash.startcase: 4.4.0
+      outdent: 0.5.0
+      prettier: 2.8.8
+      resolve-from: 5.0.0
+      semver: 7.7.4
+
+  '@changesets/assemble-release-plan@6.0.9':
+    dependencies:
+      '@changesets/errors': 0.2.0
+      '@changesets/get-dependents-graph': 2.1.3
+      '@changesets/should-skip-package': 0.1.2
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+      semver: 7.7.4
+
+  '@changesets/changelog-git@0.2.1':
+    dependencies:
+      '@changesets/types': 6.1.0
+
+  '@changesets/changelog-github@0.7.0':
+    dependencies:
+      '@changesets/get-github-info': 0.8.0
+      '@changesets/types': 6.1.0
+      dotenv: 8.6.0
+    transitivePeerDependencies:
+      - encoding
+
+  '@changesets/cli@2.30.0(@types/node@22.19.17)':
+    dependencies:
+      '@changesets/apply-release-plan': 7.1.0
+      '@changesets/assemble-release-plan': 6.0.9
+      '@changesets/changelog-git': 0.2.1
+      '@changesets/config': 3.1.3
+      '@changesets/errors': 0.2.0
+      '@changesets/get-dependents-graph': 2.1.3
+      '@changesets/get-release-plan': 4.0.15
+      '@changesets/git': 3.0.4
+      '@changesets/logger': 0.1.1
+      '@changesets/pre': 2.0.2
+      '@changesets/read': 0.6.7
+      '@changesets/should-skip-package': 0.1.2
+      '@changesets/types': 6.1.0
+      '@changesets/write': 0.4.0
+      '@inquirer/external-editor': 1.0.3(@types/node@22.19.17)
+      '@manypkg/get-packages': 1.1.3
+      ansi-colors: 4.1.3
+      enquirer: 2.4.1
+      fs-extra: 7.0.1
+      mri: 1.2.0
+      package-manager-detector: 0.2.11
+      picocolors: 1.1.1
+      resolve-from: 5.0.0
+      semver: 7.7.4
+      spawndamnit: 3.0.1
+      term-size: 2.2.1
+    transitivePeerDependencies:
+      - '@types/node'
+
+  '@changesets/config@3.1.3':
+    dependencies:
+      '@changesets/errors': 0.2.0
+      '@changesets/get-dependents-graph': 2.1.3
+      '@changesets/logger': 0.1.1
+      '@changesets/should-skip-package': 0.1.2
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+      fs-extra: 7.0.1
+      micromatch: 4.0.8
+
+  '@changesets/errors@0.2.0':
+    dependencies:
+      extendable-error: 0.1.7
+
+  '@changesets/get-dependents-graph@2.1.3':
+    dependencies:
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+      picocolors: 1.1.1
+      semver: 7.7.4
+
+  '@changesets/get-github-info@0.8.0':
+    dependencies:
+      dataloader: 1.4.0
+      node-fetch: 2.7.0
+    transitivePeerDependencies:
+      - encoding
+
+  '@changesets/get-release-plan@4.0.15':
+    dependencies:
+      '@changesets/assemble-release-plan': 6.0.9
+      '@changesets/config': 3.1.3
+      '@changesets/pre': 2.0.2
+      '@changesets/read': 0.6.7
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+
+  '@changesets/get-version-range-type@0.4.0': {}
+
+  '@changesets/git@3.0.4':
+    dependencies:
+      '@changesets/errors': 0.2.0
+      '@manypkg/get-packages': 1.1.3
+      is-subdir: 1.2.0
+      micromatch: 4.0.8
+      spawndamnit: 3.0.1
+
+  '@changesets/logger@0.1.1':
+    dependencies:
+      picocolors: 1.1.1
+
+  '@changesets/parse@0.4.3':
+    dependencies:
+      '@changesets/types': 6.1.0
+      js-yaml: 4.1.1
+
+  '@changesets/pre@2.0.2':
+    dependencies:
+      '@changesets/errors': 0.2.0
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+      fs-extra: 7.0.1
+
+  '@changesets/read@0.6.7':
+    dependencies:
+      '@changesets/git': 3.0.4
+      '@changesets/logger': 0.1.1
+      '@changesets/parse': 0.4.3
+      '@changesets/types': 6.1.0
+      fs-extra: 7.0.1
+      p-filter: 2.1.0
+      picocolors: 1.1.1
+
+  '@changesets/should-skip-package@0.1.2':
+    dependencies:
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+
+  '@changesets/types@4.1.0': {}
+
+  '@changesets/types@6.1.0': {}
+
+  '@changesets/write@0.4.0':
+    dependencies:
+      '@changesets/types': 6.1.0
+      fs-extra: 7.0.1
+      human-id: 4.1.3
+      prettier: 2.8.8
+
+  '@colors/colors@1.5.0':
+    optional: true
+
+  '@earendil-works/pi-tui@0.74.0':
+    dependencies:
+      '@types/mime-types': 2.1.4
+      chalk: 5.6.2
+      get-east-asian-width: 1.5.0
+      marked: 15.0.12
+      mime-types: 3.0.2
+    optionalDependencies:
+      koffi: 2.16.0
+
+  '@emnapi/core@1.10.0':
+    dependencies:
+      '@emnapi/wasi-threads': 1.2.1
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/core@1.9.2':
+    dependencies:
+      '@emnapi/wasi-threads': 1.2.1
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/runtime@1.10.0':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/runtime@1.9.2':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/wasi-threads@1.2.1':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@esbuild/aix-ppc64@0.25.12':
+    optional: true
+
+  '@esbuild/aix-ppc64@0.27.7':
+    optional: true
+
+  '@esbuild/android-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/android-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/android-arm@0.25.12':
+    optional: true
+
+  '@esbuild/android-arm@0.27.7':
+    optional: true
+
+  '@esbuild/android-x64@0.25.12':
+    optional: true
+
+  '@esbuild/android-x64@0.27.7':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/darwin-x64@0.25.12':
+    optional: true
+
+  '@esbuild/darwin-x64@0.27.7':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.25.12':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/linux-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-arm@0.25.12':
+    optional: true
+
+  '@esbuild/linux-arm@0.27.7':
+    optional: true
+
+  '@esbuild/linux-ia32@0.25.12':
+    optional: true
+
+  '@esbuild/linux-ia32@0.27.7':
+    optional: true
+
+  '@esbuild/linux-loong64@0.25.12':
+    optional: true
+
+  '@esbuild/linux-loong64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.25.12':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.27.7':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.25.12':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.25.12':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-s390x@0.25.12':
+    optional: true
+
+  '@esbuild/linux-s390x@0.27.7':
+    optional: true
+
+  '@esbuild/linux-x64@0.25.12':
+    optional: true
+
+  '@esbuild/linux-x64@0.27.7':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.25.12':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.27.7':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.25.12':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.27.7':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/sunos-x64@0.25.12':
+    optional: true
+
+  '@esbuild/sunos-x64@0.27.7':
+    optional: true
+
+  '@esbuild/win32-arm64@0.25.12':
+    optional: true
+
+  '@esbuild/win32-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/win32-ia32@0.25.12':
+    optional: true
+
+  '@esbuild/win32-ia32@0.27.7':
+    optional: true
+
+  '@esbuild/win32-x64@0.25.12':
+    optional: true
+
+  '@esbuild/win32-x64@0.27.7':
+    optional: true
+
+  '@google/genai@1.49.0(@modelcontextprotocol/sdk@1.29.0(zod@4.3.6))':
+    dependencies:
+      google-auth-library: 10.6.2
+      p-retry: 4.6.2
+      protobufjs: 7.5.4
+      ws: 8.20.0
+    optionalDependencies:
+      '@modelcontextprotocol/sdk': 1.29.0(zod@4.3.6)
+    transitivePeerDependencies:
+      - bufferutil
+      - supports-color
+      - utf-8-validate
+
+  '@hono/node-server@1.19.14(hono@4.12.14)':
+    dependencies:
+      hono: 4.12.14
+
+  '@inquirer/external-editor@1.0.3(@types/node@22.19.17)':
+    dependencies:
+      chardet: 2.1.1
+      iconv-lite: 0.7.2
+    optionalDependencies:
+      '@types/node': 22.19.17
+
+  '@isaacs/fs-minipass@4.0.1':
+    dependencies:
+      minipass: 7.1.3
+
+  '@jridgewell/gen-mapping@0.3.13':
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/remapping@2.3.5':
+    dependencies:
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/resolve-uri@3.1.2': {}
+
+  '@jridgewell/sourcemap-codec@1.5.5': {}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    dependencies:
+      '@jridgewell/resolve-uri': 3.1.2
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  '@loaderkit/resolve@1.0.4':
+    dependencies:
+      '@braidai/lang': 1.1.2
+
+  '@manypkg/find-root@1.1.0':
+    dependencies:
+      '@babel/runtime': 7.29.2
+      '@types/node': 12.20.55
+      find-up: 4.1.0
+      fs-extra: 8.1.0
+
+  '@manypkg/get-packages@1.1.3':
+    dependencies:
+      '@babel/runtime': 7.29.2
+      '@changesets/types': 4.1.0
+      '@manypkg/find-root': 1.1.0
+      fs-extra: 8.1.0
+      globby: 11.1.0
+      read-yaml-file: 1.1.0
+
+  '@mariozechner/clipboard-darwin-arm64@0.3.2':
+    optional: true
+
+  '@mariozechner/clipboard-darwin-universal@0.3.2':
+    optional: true
+
+  '@mariozechner/clipboard-darwin-x64@0.3.2':
+    optional: true
+
+  '@mariozechner/clipboard-linux-arm64-gnu@0.3.2':
+    optional: true
+
+  '@mariozechner/clipboard-linux-arm64-musl@0.3.2':
+    optional: true
+
+  '@mariozechner/clipboard-linux-riscv64-gnu@0.3.2':
+    optional: true
+
+  '@mariozechner/clipboard-linux-x64-gnu@0.3.2':
+    optional: true
+
+  '@mariozechner/clipboard-linux-x64-musl@0.3.2':
+    optional: true
+
+  '@mariozechner/clipboard-win32-arm64-msvc@0.3.2':
+    optional: true
+
+  '@mariozechner/clipboard-win32-x64-msvc@0.3.2':
+    optional: true
+
+  '@mariozechner/clipboard@0.3.2':
+    optionalDependencies:
+      '@mariozechner/clipboard-darwin-arm64': 0.3.2
+      '@mariozechner/clipboard-darwin-universal': 0.3.2
+      '@mariozechner/clipboard-darwin-x64': 0.3.2
+      '@mariozechner/clipboard-linux-arm64-gnu': 0.3.2
+      '@mariozechner/clipboard-linux-arm64-musl': 0.3.2
+      '@mariozechner/clipboard-linux-riscv64-gnu': 0.3.2
+      '@mariozechner/clipboard-linux-x64-gnu': 0.3.2
+      '@mariozechner/clipboard-linux-x64-musl': 0.3.2
+      '@mariozechner/clipboard-win32-arm64-msvc': 0.3.2
+      '@mariozechner/clipboard-win32-x64-msvc': 0.3.2
+
+  '@microsoft/api-extractor-model@7.33.8(@types/node@22.19.17)':
+    dependencies:
+      '@microsoft/tsdoc': 0.16.0
+      '@microsoft/tsdoc-config': 0.18.1
+      '@rushstack/node-core-library': 5.23.1(@types/node@22.19.17)
+    transitivePeerDependencies:
+      - '@types/node'
+
+  '@microsoft/api-extractor@7.58.7(@types/node@22.19.17)':
+    dependencies:
+      '@microsoft/api-extractor-model': 7.33.8(@types/node@22.19.17)
+      '@microsoft/tsdoc': 0.16.0
+      '@microsoft/tsdoc-config': 0.18.1
+      '@rushstack/node-core-library': 5.23.1(@types/node@22.19.17)
+      '@rushstack/rig-package': 0.7.3
+      '@rushstack/terminal': 0.24.0(@types/node@22.19.17)
+      '@rushstack/ts-command-line': 5.3.9(@types/node@22.19.17)
+      diff: 8.0.4
+      minimatch: 10.2.3
+      resolve: 1.22.12
+      semver: 7.7.4
+      source-map: 0.6.1
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - '@types/node'
+
+  '@microsoft/tsdoc-config@0.18.1':
+    dependencies:
+      '@microsoft/tsdoc': 0.16.0
+      ajv: 8.18.0
+      jju: 1.4.0
+      resolve: 1.22.12
+
+  '@microsoft/tsdoc@0.16.0': {}
+
+  '@modelcontextprotocol/sdk@1.29.0(zod@4.3.6)':
+    dependencies:
+      '@hono/node-server': 1.19.14(hono@4.12.14)
+      ajv: 8.18.0
+      ajv-formats: 3.0.1(ajv@8.18.0)
+      content-type: 1.0.5
+      cors: 2.8.6
+      cross-spawn: 7.0.6
+      eventsource: 3.0.7
+      eventsource-parser: 3.0.6
+      express: 5.2.1
+      express-rate-limit: 8.3.2(express@5.2.1)
+      hono: 4.12.14
+      jose: 6.2.2
+      json-schema-typed: 8.0.2
+      pkce-challenge: 5.0.1
+      raw-body: 3.0.2
+      zod: 4.3.6
+      zod-to-json-schema: 3.25.2(zod@4.3.6)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@mozilla/readability@0.6.0': {}
+
+  '@napi-rs/wasm-runtime@1.1.4(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)':
+    dependencies:
+      '@emnapi/core': 1.10.0
+      '@emnapi/runtime': 1.10.0
+      '@tybys/wasm-util': 0.10.1
+    optional: true
+
+  '@napi-rs/wasm-runtime@1.1.4(@emnapi/core@1.9.2)(@emnapi/runtime@1.9.2)':
+    dependencies:
+      '@emnapi/core': 1.9.2
+      '@emnapi/runtime': 1.9.2
+      '@tybys/wasm-util': 0.10.1
+    optional: true
+
+  '@nodelib/fs.scandir@2.1.5':
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      run-parallel: 1.2.0
+
+  '@nodelib/fs.stat@2.0.5': {}
+
+  '@nodelib/fs.walk@1.2.8':
+    dependencies:
+      '@nodelib/fs.scandir': 2.1.5
+      fastq: 1.20.1
+
+  '@oxc-project/types@0.122.0':
+    optional: true
+
+  '@oxc-project/types@0.124.0': {}
+
+  '@oxc-project/types@0.130.0': {}
+
+  '@oxlint-tsgolint/darwin-arm64@0.20.0':
+    optional: true
+
+  '@oxlint-tsgolint/darwin-x64@0.20.0':
+    optional: true
+
+  '@oxlint-tsgolint/linux-arm64@0.20.0':
+    optional: true
+
+  '@oxlint-tsgolint/linux-x64@0.20.0':
+    optional: true
+
+  '@oxlint-tsgolint/win32-arm64@0.20.0':
+    optional: true
+
+  '@oxlint-tsgolint/win32-x64@0.20.0':
+    optional: true
+
+  '@oxlint/binding-android-arm-eabi@1.59.0':
+    optional: true
+
+  '@oxlint/binding-android-arm64@1.59.0':
+    optional: true
+
+  '@oxlint/binding-darwin-arm64@1.59.0':
+    optional: true
+
+  '@oxlint/binding-darwin-x64@1.59.0':
+    optional: true
+
+  '@oxlint/binding-freebsd-x64@1.59.0':
+    optional: true
+
+  '@oxlint/binding-linux-arm-gnueabihf@1.59.0':
+    optional: true
+
+  '@oxlint/binding-linux-arm-musleabihf@1.59.0':
+    optional: true
+
+  '@oxlint/binding-linux-arm64-gnu@1.59.0':
+    optional: true
+
+  '@oxlint/binding-linux-arm64-musl@1.59.0':
+    optional: true
+
+  '@oxlint/binding-linux-ppc64-gnu@1.59.0':
+    optional: true
+
+  '@oxlint/binding-linux-riscv64-gnu@1.59.0':
+    optional: true
+
+  '@oxlint/binding-linux-riscv64-musl@1.59.0':
+    optional: true
+
+  '@oxlint/binding-linux-s390x-gnu@1.59.0':
+    optional: true
+
+  '@oxlint/binding-linux-x64-gnu@1.59.0':
+    optional: true
+
+  '@oxlint/binding-linux-x64-musl@1.59.0':
+    optional: true
+
+  '@oxlint/binding-openharmony-arm64@1.59.0':
+    optional: true
+
+  '@oxlint/binding-win32-arm64-msvc@1.59.0':
+    optional: true
+
+  '@oxlint/binding-win32-ia32-msvc@1.59.0':
+    optional: true
+
+  '@oxlint/binding-win32-x64-msvc@1.59.0':
+    optional: true
+
+  '@protobufjs/aspromise@1.1.2': {}
+
+  '@protobufjs/base64@1.1.2': {}
+
+  '@protobufjs/codegen@2.0.4': {}
+
+  '@protobufjs/eventemitter@1.1.0': {}
+
+  '@protobufjs/fetch@1.1.0':
+    dependencies:
+      '@protobufjs/aspromise': 1.1.2
+      '@protobufjs/inquire': 1.1.0
+
+  '@protobufjs/float@1.0.2': {}
+
+  '@protobufjs/inquire@1.1.0': {}
+
+  '@protobufjs/path@1.1.2': {}
+
+  '@protobufjs/pool@1.1.0': {}
+
+  '@protobufjs/utf8@1.1.0': {}
+
+  '@publint/pack@0.1.4': {}
+
+  '@quansync/fs@1.0.0':
+    dependencies:
+      quansync: 1.0.0
+
+  '@rolldown/binding-android-arm64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-android-arm64@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-android-arm64@1.0.1':
+    optional: true
+
+  '@rolldown/binding-darwin-arm64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-darwin-arm64@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-darwin-arm64@1.0.1':
+    optional: true
+
+  '@rolldown/binding-darwin-x64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-darwin-x64@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-darwin-x64@1.0.1':
+    optional: true
+
+  '@rolldown/binding-freebsd-x64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-freebsd-x64@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-freebsd-x64@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-gnu@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-gnu@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-gnu@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-musl@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-musl@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-musl@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-ppc64-gnu@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-ppc64-gnu@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-linux-ppc64-gnu@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-s390x-gnu@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-s390x-gnu@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-linux-s390x-gnu@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-x64-gnu@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-x64-gnu@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-linux-x64-gnu@1.0.1':
+    optional: true
+
+  '@rolldown/binding-linux-x64-musl@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-x64-musl@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-linux-x64-musl@1.0.1':
+    optional: true
+
+  '@rolldown/binding-openharmony-arm64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-openharmony-arm64@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-openharmony-arm64@1.0.1':
+    optional: true
+
+  '@rolldown/binding-wasm32-wasi@1.0.0-rc.12(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)':
+    dependencies:
+      '@napi-rs/wasm-runtime': 1.1.4(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+    optional: true
+
+  '@rolldown/binding-wasm32-wasi@1.0.0-rc.15':
+    dependencies:
+      '@emnapi/core': 1.9.2
+      '@emnapi/runtime': 1.9.2
+      '@napi-rs/wasm-runtime': 1.1.4(@emnapi/core@1.9.2)(@emnapi/runtime@1.9.2)
+    optional: true
+
+  '@rolldown/binding-wasm32-wasi@1.0.1':
+    dependencies:
+      '@emnapi/core': 1.10.0
+      '@emnapi/runtime': 1.10.0
+      '@napi-rs/wasm-runtime': 1.1.4(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)
+    optional: true
+
+  '@rolldown/binding-win32-arm64-msvc@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-win32-arm64-msvc@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-win32-arm64-msvc@1.0.1':
+    optional: true
+
+  '@rolldown/binding-win32-x64-msvc@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-win32-x64-msvc@1.0.0-rc.15':
+    optional: true
+
+  '@rolldown/binding-win32-x64-msvc@1.0.1':
+    optional: true
+
+  '@rolldown/pluginutils@1.0.0-beta.27': {}
+
+  '@rolldown/pluginutils@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/pluginutils@1.0.0-rc.15': {}
+
+  '@rolldown/pluginutils@1.0.1': {}
+
+  '@rollup/rollup-android-arm-eabi@4.60.2':
+    optional: true
+
+  '@rollup/rollup-android-arm64@4.60.2':
+    optional: true
+
+  '@rollup/rollup-darwin-arm64@4.60.2':
+    optional: true
+
+  '@rollup/rollup-darwin-x64@4.60.2':
+    optional: true
+
+  '@rollup/rollup-freebsd-arm64@4.60.2':
+    optional: true
+
+  '@rollup/rollup-freebsd-x64@4.60.2':
+    optional: true
+
+  '@rollup/rollup-linux-arm-gnueabihf@4.60.2':
+    optional: true
+
+  '@rollup/rollup-linux-arm-musleabihf@4.60.2':
+    optional: true
+
+  '@rollup/rollup-linux-arm64-gnu@4.60.2':
+    optional: true
+
+  '@rollup/rollup-linux-arm64-musl@4.60.2':
+    optional: true
+
+  '@rollup/rollup-linux-loong64-gnu@4.60.2':
+    optional: true
+
+  '@rollup/rollup-linux-loong64-musl@4.60.2':
+    optional: true
+
+  '@rollup/rollup-linux-ppc64-gnu@4.60.2':
+    optional: true
+
+  '@rollup/rollup-linux-ppc64-musl@4.60.2':
+    optional: true
+
+  '@rollup/rollup-linux-riscv64-gnu@4.60.2':
+    optional: true
+
+  '@rollup/rollup-linux-riscv64-musl@4.60.2':
+    optional: true
+
+  '@rollup/rollup-linux-s390x-gnu@4.60.2':
+    optional: true
+
+  '@rollup/rollup-linux-x64-gnu@4.60.2':
+    optional: true
+
+  '@rollup/rollup-linux-x64-musl@4.60.2':
+    optional: true
+
+  '@rollup/rollup-openbsd-x64@4.60.2':
+    optional: true
+
+  '@rollup/rollup-openharmony-arm64@4.60.2':
+    optional: true
+
+  '@rollup/rollup-win32-arm64-msvc@4.60.2':
+    optional: true
+
+  '@rollup/rollup-win32-ia32-msvc@4.60.2':
+    optional: true
+
+  '@rollup/rollup-win32-x64-gnu@4.60.2':
+    optional: true
+
+  '@rollup/rollup-win32-x64-msvc@4.60.2':
+    optional: true
+
+  '@rushstack/node-core-library@5.23.1(@types/node@22.19.17)':
+    dependencies:
+      ajv: 8.18.0
+      ajv-draft-04: 1.0.0(ajv@8.18.0)
+      ajv-formats: 3.0.1(ajv@8.18.0)
+      fs-extra: 11.3.5
+      import-lazy: 4.0.0
+      jju: 1.4.0
+      resolve: 1.22.12
+      semver: 7.7.4
+    optionalDependencies:
+      '@types/node': 22.19.17
+
+  '@rushstack/problem-matcher@0.2.1(@types/node@22.19.17)':
+    optionalDependencies:
+      '@types/node': 22.19.17
+
+  '@rushstack/rig-package@0.7.3':
+    dependencies:
+      jju: 1.4.0
+      resolve: 1.22.12
+
+  '@rushstack/terminal@0.24.0(@types/node@22.19.17)':
+    dependencies:
+      '@rushstack/node-core-library': 5.23.1(@types/node@22.19.17)
+      '@rushstack/problem-matcher': 0.2.1(@types/node@22.19.17)
+      supports-color: 8.1.1
+    optionalDependencies:
+      '@types/node': 22.19.17
+
+  '@rushstack/ts-command-line@5.3.9(@types/node@22.19.17)':
+    dependencies:
+      '@rushstack/terminal': 0.24.0(@types/node@22.19.17)
+      '@types/argparse': 1.0.38
+      argparse: 1.0.10
+      string-argv: 0.3.2
+    transitivePeerDependencies:
+      - '@types/node'
+
+  '@sindresorhus/is@4.6.0': {}
+
+  '@stablelib/base64@1.0.1': {}
+
+  '@standard-schema/spec@1.1.0': {}
+
+  '@tailwindcss/node@4.2.2':
+    dependencies:
+      '@jridgewell/remapping': 2.3.5
+      enhanced-resolve: 5.20.1
+      jiti: 2.6.1
+      lightningcss: 1.32.0
+      magic-string: 0.30.21
+      source-map-js: 1.2.1
+      tailwindcss: 4.2.2
+
+  '@tailwindcss/oxide-android-arm64@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-arm64@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-x64@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-freebsd-x64@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-musl@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-wasm32-wasi@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide@4.2.2':
+    optionalDependencies:
+      '@tailwindcss/oxide-android-arm64': 4.2.2
+      '@tailwindcss/oxide-darwin-arm64': 4.2.2
+      '@tailwindcss/oxide-darwin-x64': 4.2.2
+      '@tailwindcss/oxide-freebsd-x64': 4.2.2
+      '@tailwindcss/oxide-linux-arm-gnueabihf': 4.2.2
+      '@tailwindcss/oxide-linux-arm64-gnu': 4.2.2
+      '@tailwindcss/oxide-linux-arm64-musl': 4.2.2
+      '@tailwindcss/oxide-linux-x64-gnu': 4.2.2
+      '@tailwindcss/oxide-linux-x64-musl': 4.2.2
+      '@tailwindcss/oxide-wasm32-wasi': 4.2.2
+      '@tailwindcss/oxide-win32-arm64-msvc': 4.2.2
+      '@tailwindcss/oxide-win32-x64-msvc': 4.2.2
+
+  '@tailwindcss/vite@4.2.2(vite@6.4.2(@types/node@22.19.17)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.8.3))':
+    dependencies:
+      '@tailwindcss/node': 4.2.2
+      '@tailwindcss/oxide': 4.2.2
+      tailwindcss: 4.2.2
+      vite: 6.4.2(@types/node@22.19.17)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.8.3)
+
+  '@tanstack/query-core@5.99.2': {}
+
+  '@tanstack/react-query@5.99.2(react@19.2.5)':
+    dependencies:
+      '@tanstack/query-core': 5.99.2
+      react: 19.2.5
+
+  '@tanstack/react-virtual@3.13.24(react-dom@19.2.5(react@19.2.5))(react@19.2.5)':
+    dependencies:
+      '@tanstack/virtual-core': 3.14.0
+      react: 19.2.5
+      react-dom: 19.2.5(react@19.2.5)
+
+  '@tanstack/virtual-core@3.14.0': {}
+
+  '@tybys/wasm-util@0.10.1':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@types/argparse@1.0.38': {}
+
+  '@types/babel__core@7.20.5':
+    dependencies:
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
+      '@types/babel__generator': 7.27.0
+      '@types/babel__template': 7.4.4
+      '@types/babel__traverse': 7.28.0
+
+  '@types/babel__generator@7.27.0':
+    dependencies:
+      '@babel/types': 7.29.0
+
+  '@types/babel__template@7.4.4':
+    dependencies:
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
+
+  '@types/babel__traverse@7.28.0':
+    dependencies:
+      '@babel/types': 7.29.0
+
+  '@types/chai@5.2.3':
+    dependencies:
+      '@types/deep-eql': 4.0.2
+      assertion-error: 2.0.1
+
+  '@types/deep-eql@4.0.2': {}
+
+  '@types/estree@1.0.8': {}
+
+  '@types/js-yaml@4.0.9': {}
+
+  '@types/jsesc@2.5.1': {}
+
+  '@types/mime-types@2.1.4': {}
+
+  '@types/node@12.20.55': {}
+
+  '@types/node@18.19.130':
+    dependencies:
+      undici-types: 5.26.5
+
+  '@types/node@22.19.17':
+    dependencies:
+      undici-types: 6.21.0
+
+  '@types/nunjucks@3.2.6': {}
+
+  '@types/picomatch@4.0.3': {}
+
+  '@types/proper-lockfile@4.1.4':
+    dependencies:
+      '@types/retry': 0.12.0
+
+  '@types/react-dom@19.2.3(@types/react@19.2.14)':
+    dependencies:
+      '@types/react': 19.2.14
+
+  '@types/react@19.2.14':
+    dependencies:
+      csstype: 3.2.3
+
+  '@types/regexp.escape@2.0.0': {}
+
+  '@types/retry@0.12.0': {}
+
+  '@types/semver@7.7.1': {}
+
+  '@types/ssh2@1.15.5':
+    dependencies:
+      '@types/node': 18.19.130
+
+  '@types/tar@7.0.87':
+    dependencies:
+      tar: 7.5.13
+
+  '@types/yauzl@2.10.3':
+    dependencies:
+      '@types/node': 22.19.17
+
+  '@types/yazl@2.4.6':
+    dependencies:
+      '@types/node': 22.19.17
+
+  '@vitejs/plugin-react@4.7.0(vite@6.4.2(@types/node@22.19.17)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.8.3))':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.29.0)
+      '@babel/plugin-transform-react-jsx-source': 7.27.1(@babel/core@7.29.0)
+      '@rolldown/pluginutils': 1.0.0-beta.27
+      '@types/babel__core': 7.20.5
+      react-refresh: 0.17.0
+      vite: 6.4.2(@types/node@22.19.17)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.8.3)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@vitest/coverage-v8@4.1.4(vitest@4.1.4)':
+    dependencies:
+      '@bcoe/v8-coverage': 1.0.2
+      '@vitest/utils': 4.1.4
+      ast-v8-to-istanbul: 1.0.0
+      istanbul-lib-coverage: 3.2.2
+      istanbul-lib-report: 3.0.1
+      istanbul-reports: 3.2.0
+      magicast: 0.5.2
+      obug: 2.1.1
+      std-env: 4.0.0
+      tinyrainbow: 3.1.0
+      vitest: 4.1.4(@types/node@22.19.17)(@vitest/coverage-v8@4.1.4)(vite@8.0.8(@types/node@22.19.17)(esbuild@0.27.7)(jiti@2.6.1)(tsx@4.21.0)(yaml@2.8.3))
+
+  '@vitest/expect@4.1.4':
+    dependencies:
+      '@standard-schema/spec': 1.1.0
+      '@types/chai': 5.2.3
+      '@vitest/spy': 4.1.4
+      '@vitest/utils': 4.1.4
+      chai: 6.2.2
+      tinyrainbow: 3.1.0
+
+  '@vitest/mocker@4.1.4(vite@8.0.8(@types/node@22.19.17)(esbuild@0.27.7)(jiti@2.6.1)(tsx@4.21.0)(yaml@2.8.3))':
+    dependencies:
+      '@vitest/spy': 4.1.4
+      estree-walker: 3.0.3
+      magic-string: 0.30.21
+    optionalDependencies:
+      vite: 8.0.8(@types/node@22.19.17)(esbuild@0.27.7)(jiti@2.6.1)(tsx@4.21.0)(yaml@2.8.3)
+
+  '@vitest/pretty-format@4.1.4':
+    dependencies:
+      tinyrainbow: 3.1.0
+
+  '@vitest/runner@4.1.4':
+    dependencies:
+      '@vitest/utils': 4.1.4
+      pathe: 2.0.3
+
+  '@vitest/snapshot@4.1.4':
+    dependencies:
+      '@vitest/pretty-format': 4.1.4
+      '@vitest/utils': 4.1.4
+      magic-string: 0.30.21
+      pathe: 2.0.3
+
+  '@vitest/spy@4.1.4': {}
+
+  '@vitest/utils@4.1.4':
+    dependencies:
+      '@vitest/pretty-format': 4.1.4
+      convert-source-map: 2.0.0
+      tinyrainbow: 3.1.0
+
+  a-sync-waterfall@1.0.1: {}
+
+  accepts@2.0.0:
+    dependencies:
+      mime-types: 3.0.2
+      negotiator: 1.0.0
+
+  agent-base@7.1.4: {}
+
+  ajv-draft-04@1.0.0(ajv@8.18.0):
+    optionalDependencies:
+      ajv: 8.18.0
+
+  ajv-formats@3.0.1(ajv@8.18.0):
+    optionalDependencies:
+      ajv: 8.18.0
+
+  ajv@8.18.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-uri: 3.1.0
+      json-schema-traverse: 1.0.0
+      require-from-string: 2.0.2
+
+  ansi-colors@4.1.3: {}
+
+  ansi-escapes@7.3.0:
+    dependencies:
+      environment: 1.1.0
+
+  ansi-regex@5.0.1: {}
+
+  ansi-regex@6.2.2: {}
+
+  ansi-styles@4.3.0:
+    dependencies:
+      color-convert: 2.0.1
+
+  ansi-styles@6.2.3: {}
+
+  ansis@4.2.0: {}
+
+  any-promise@1.3.0: {}
+
+  argparse@1.0.10:
+    dependencies:
+      sprintf-js: 1.0.3
+
+  argparse@2.0.1: {}
+
+  array-buffer-byte-length@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      is-array-buffer: 3.0.5
+
+  array-union@2.1.0: {}
+
+  arraybuffer.prototype.slice@1.0.4:
+    dependencies:
+      array-buffer-byte-length: 1.0.2
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      is-array-buffer: 3.0.5
+
+  asap@2.0.6: {}
+
+  asn1@0.2.6:
+    dependencies:
+      safer-buffer: 2.1.2
+
+  assertion-error@2.0.1: {}
+
+  ast-kit@3.0.0-beta.1:
+    dependencies:
+      '@babel/parser': 8.0.0-rc.4
+      estree-walker: 3.0.3
+      pathe: 2.0.3
+
+  ast-v8-to-istanbul@1.0.0:
+    dependencies:
+      '@jridgewell/trace-mapping': 0.3.31
+      estree-walker: 3.0.3
+      js-tokens: 10.0.0
+
+  async-function@1.0.0: {}
+
+  available-typed-arrays@1.0.7:
+    dependencies:
+      possible-typed-array-names: 1.1.0
+
+  balanced-match@4.0.4: {}
+
+  base64-js@1.5.1: {}
+
+  baseline-browser-mapping@2.10.20: {}
+
+  bcrypt-pbkdf@1.0.2:
+    dependencies:
+      tweetnacl: 0.14.5
+
+  better-path-resolve@1.0.0:
+    dependencies:
+      is-windows: 1.0.2
+
+  bignumber.js@9.3.1: {}
+
+  birpc@4.0.0: {}
+
+  body-parser@2.2.2:
+    dependencies:
+      bytes: 3.1.2
+      content-type: 1.0.5
+      debug: 4.4.3
+      http-errors: 2.0.1
+      iconv-lite: 0.7.2
+      on-finished: 2.4.1
+      qs: 6.15.1
+      raw-body: 3.0.2
+      type-is: 2.0.1
+    transitivePeerDependencies:
+      - supports-color
+
+  boolbase@1.0.0: {}
+
+  brace-expansion@5.0.6:
+    dependencies:
+      balanced-match: 4.0.4
+
+  braces@3.0.3:
+    dependencies:
+      fill-range: 7.1.1
+
+  browserslist@4.28.2:
+    dependencies:
+      baseline-browser-mapping: 2.10.20
+      caniuse-lite: 1.0.30001788
+      electron-to-chromium: 1.5.340
+      node-releases: 2.0.37
+      update-browserslist-db: 1.2.3(browserslist@4.28.2)
+
+  buffer-crc32@0.2.13: {}
+
+  buffer-crc32@1.0.0: {}
+
+  buffer-equal-constant-time@1.0.1: {}
+
+  bundle-name@4.1.0:
+    dependencies:
+      run-applescript: 7.1.0
+
+  bytes@3.1.2: {}
+
+  cac@7.0.0: {}
+
+  call-bind-apply-helpers@1.0.2:
+    dependencies:
+      es-errors: 1.3.0
+      function-bind: 1.1.2
+
+  call-bind@1.0.9:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-define-property: 1.0.1
+      get-intrinsic: 1.3.0
+      set-function-length: 1.2.2
+
+  call-bound@1.0.4:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      get-intrinsic: 1.3.0
+
+  caniuse-lite@1.0.30001788: {}
+
+  chai@6.2.2: {}
+
+  chalk@4.1.2:
+    dependencies:
+      ansi-styles: 4.3.0
+      supports-color: 7.2.0
+
+  chalk@5.6.2: {}
+
+  char-regex@1.0.2: {}
+
+  chardet@2.1.1: {}
+
+  chownr@3.0.0: {}
+
+  cjs-module-lexer@1.4.3: {}
+
+  cli-cursor@5.0.0:
+    dependencies:
+      restore-cursor: 5.1.0
+
+  cli-highlight@2.1.11:
+    dependencies:
+      chalk: 4.1.2
+      highlight.js: 10.7.3
+      mz: 2.7.0
+      parse5: 5.1.1
+      parse5-htmlparser2-tree-adapter: 6.0.1
+      yargs: 16.2.0
+
+  cli-table3@0.6.5:
+    dependencies:
+      string-width: 4.2.3
+    optionalDependencies:
+      '@colors/colors': 1.5.0
+
+  cli-truncate@5.2.0:
+    dependencies:
+      slice-ansi: 8.0.0
+      string-width: 8.2.0
+
+  cliui@7.0.4:
+    dependencies:
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+      wrap-ansi: 7.0.0
+
+  cliui@8.0.1:
+    dependencies:
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+      wrap-ansi: 7.0.0
+
+  color-convert@2.0.1:
+    dependencies:
+      color-name: 1.1.4
+
+  color-name@1.1.4: {}
+
+  colorette@2.0.20: {}
+
+  commander@10.0.1: {}
+
+  commander@13.1.0: {}
+
+  commander@14.0.3: {}
+
+  commander@5.1.0: {}
+
+  commander@9.5.0: {}
+
+  concurrently@9.2.1:
+    dependencies:
+      chalk: 4.1.2
+      rxjs: 7.8.2
+      shell-quote: 1.8.3
+      supports-color: 8.1.1
+      tree-kill: 1.2.2
+      yargs: 17.7.2
+
+  content-disposition@1.1.0: {}
+
+  content-type@1.0.5: {}
+
+  convert-source-map@2.0.0: {}
+
+  cookie-signature@1.2.2: {}
+
+  cookie@0.7.2: {}
+
+  cookie@1.1.1: {}
+
+  cors@2.8.6:
+    dependencies:
+      object-assign: 4.1.1
+      vary: 1.1.2
+
+  cross-spawn@7.0.6:
+    dependencies:
+      path-key: 3.1.1
+      shebang-command: 2.0.0
+      which: 2.0.2
+
+  css-select@5.2.2:
+    dependencies:
+      boolbase: 1.0.0
+      css-what: 6.2.2
+      domhandler: 5.0.3
+      domutils: 3.2.2
+      nth-check: 2.1.1
+
+  css-what@6.2.2: {}
+
+  cssom@0.5.0: {}
+
+  csstype@3.2.3: {}
+
+  data-uri-to-buffer@4.0.1: {}
+
+  data-view-buffer@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      is-data-view: 1.0.2
+
+  data-view-byte-length@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      is-data-view: 1.0.2
+
+  data-view-byte-offset@1.0.1:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      is-data-view: 1.0.2
+
+  dataloader@1.4.0: {}
+
+  debug@4.4.3:
+    dependencies:
+      ms: 2.1.3
+
+  default-browser-id@5.0.1: {}
+
+  default-browser@5.5.0:
+    dependencies:
+      bundle-name: 4.1.0
+      default-browser-id: 5.0.1
+
+  define-data-property@1.1.4:
+    dependencies:
+      es-define-property: 1.0.1
+      es-errors: 1.3.0
+      gopd: 1.2.0
+
+  define-lazy-prop@3.0.0: {}
+
+  define-properties@1.2.1:
+    dependencies:
+      define-data-property: 1.1.4
+      has-property-descriptors: 1.0.2
+      object-keys: 1.1.1
+
+  defu@6.1.7: {}
+
+  depd@2.0.0: {}
+
+  detect-indent@6.1.0: {}
+
+  detect-libc@2.1.2: {}
+
+  diff@8.0.4: {}
+
+  dir-glob@3.0.1:
+    dependencies:
+      path-type: 4.0.0
+
+  dom-serializer@2.0.0:
+    dependencies:
+      domelementtype: 2.3.0
+      domhandler: 5.0.3
+      entities: 4.5.0
+
+  domelementtype@2.3.0: {}
+
+  domhandler@5.0.3:
+    dependencies:
+      domelementtype: 2.3.0
+
+  domutils@3.2.2:
+    dependencies:
+      dom-serializer: 2.0.0
+      domelementtype: 2.3.0
+      domhandler: 5.0.3
+
+  dotenv@8.6.0: {}
+
+  dts-resolver@3.0.0: {}
+
+  dunder-proto@1.0.1:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-errors: 1.3.0
+      gopd: 1.2.0
+
+  ecdsa-sig-formatter@1.0.11:
+    dependencies:
+      safe-buffer: 5.2.1
+
+  ee-first@1.1.1: {}
+
+  electron-to-chromium@1.5.340: {}
+
+  emoji-regex@10.6.0: {}
+
+  emoji-regex@8.0.0: {}
+
+  emojilib@2.4.0: {}
+
+  empathic@2.0.0: {}
+
+  encodeurl@2.0.0: {}
+
+  enhanced-resolve@5.20.1:
+    dependencies:
+      graceful-fs: 4.2.11
+      tapable: 2.3.2
+
+  enquirer@2.4.1:
+    dependencies:
+      ansi-colors: 4.1.3
+      strip-ansi: 6.0.1
+
+  entities@4.5.0: {}
+
+  entities@7.0.1: {}
+
+  environment@1.1.0: {}
+
+  es-abstract@1.24.2:
+    dependencies:
+      array-buffer-byte-length: 1.0.2
+      arraybuffer.prototype.slice: 1.0.4
+      available-typed-arrays: 1.0.7
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      data-view-buffer: 1.0.2
+      data-view-byte-length: 1.0.2
+      data-view-byte-offset: 1.0.1
+      es-define-property: 1.0.1
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.1
+      es-set-tostringtag: 2.1.0
+      es-to-primitive: 1.3.0
+      function.prototype.name: 1.1.8
+      get-intrinsic: 1.3.0
+      get-proto: 1.0.1
+      get-symbol-description: 1.1.0
+      globalthis: 1.0.4
+      gopd: 1.2.0
+      has-property-descriptors: 1.0.2
+      has-proto: 1.2.0
+      has-symbols: 1.1.0
+      hasown: 2.0.3
+      internal-slot: 1.1.0
+      is-array-buffer: 3.0.5
+      is-callable: 1.2.7
+      is-data-view: 1.0.2
+      is-negative-zero: 2.0.3
+      is-regex: 1.2.1
+      is-set: 2.0.3
+      is-shared-array-buffer: 1.0.4
+      is-string: 1.1.1
+      is-typed-array: 1.1.15
+      is-weakref: 1.1.1
+      math-intrinsics: 1.1.0
+      object-inspect: 1.13.4
+      object-keys: 1.1.1
+      object.assign: 4.1.7
+      own-keys: 1.0.1
+      regexp.prototype.flags: 1.5.4
+      safe-array-concat: 1.1.4
+      safe-push-apply: 1.0.0
+      safe-regex-test: 1.1.0
+      set-proto: 1.0.0
+      stop-iteration-iterator: 1.1.0
+      string.prototype.trim: 1.2.10
+      string.prototype.trimend: 1.0.9
+      string.prototype.trimstart: 1.0.8
+      typed-array-buffer: 1.0.3
+      typed-array-byte-length: 1.0.3
+      typed-array-byte-offset: 1.0.4
+      typed-array-length: 1.0.7
+      unbox-primitive: 1.1.0
+      which-typed-array: 1.1.20
+
+  es-define-property@1.0.1: {}
+
+  es-errors@1.3.0: {}
+
+  es-module-lexer@2.0.0: {}
+
+  es-object-atoms@1.1.1:
+    dependencies:
+      es-errors: 1.3.0
+
+  es-set-tostringtag@2.1.0:
+    dependencies:
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      has-tostringtag: 1.0.2
+      hasown: 2.0.3
+
+  es-to-primitive@1.3.0:
+    dependencies:
+      is-callable: 1.2.7
+      is-date-object: 1.1.0
+      is-symbol: 1.1.1
+
+  esbuild@0.25.12:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.25.12
+      '@esbuild/android-arm': 0.25.12
+      '@esbuild/android-arm64': 0.25.12
+      '@esbuild/android-x64': 0.25.12
+      '@esbuild/darwin-arm64': 0.25.12
+      '@esbuild/darwin-x64': 0.25.12
+      '@esbuild/freebsd-arm64': 0.25.12
+      '@esbuild/freebsd-x64': 0.25.12
+      '@esbuild/linux-arm': 0.25.12
+      '@esbuild/linux-arm64': 0.25.12
+      '@esbuild/linux-ia32': 0.25.12
+      '@esbuild/linux-loong64': 0.25.12
+      '@esbuild/linux-mips64el': 0.25.12
+      '@esbuild/linux-ppc64': 0.25.12
+      '@esbuild/linux-riscv64': 0.25.12
+      '@esbuild/linux-s390x': 0.25.12
+      '@esbuild/linux-x64': 0.25.12
+      '@esbuild/netbsd-arm64': 0.25.12
+      '@esbuild/netbsd-x64': 0.25.12
+      '@esbuild/openbsd-arm64': 0.25.12
+      '@esbuild/openbsd-x64': 0.25.12
+      '@esbuild/openharmony-arm64': 0.25.12
+      '@esbuild/sunos-x64': 0.25.12
+      '@esbuild/win32-arm64': 0.25.12
+      '@esbuild/win32-ia32': 0.25.12
+      '@esbuild/win32-x64': 0.25.12
+
+  esbuild@0.27.7:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.7
+      '@esbuild/android-arm': 0.27.7
+      '@esbuild/android-arm64': 0.27.7
+      '@esbuild/android-x64': 0.27.7
+      '@esbuild/darwin-arm64': 0.27.7
+      '@esbuild/darwin-x64': 0.27.7
+      '@esbuild/freebsd-arm64': 0.27.7
+      '@esbuild/freebsd-x64': 0.27.7
+      '@esbuild/linux-arm': 0.27.7
+      '@esbuild/linux-arm64': 0.27.7
+      '@esbuild/linux-ia32': 0.27.7
+      '@esbuild/linux-loong64': 0.27.7
+      '@esbuild/linux-mips64el': 0.27.7
+      '@esbuild/linux-ppc64': 0.27.7
+      '@esbuild/linux-riscv64': 0.27.7
+      '@esbuild/linux-s390x': 0.27.7
+      '@esbuild/linux-x64': 0.27.7
+      '@esbuild/netbsd-arm64': 0.27.7
+      '@esbuild/netbsd-x64': 0.27.7
+      '@esbuild/openbsd-arm64': 0.27.7
+      '@esbuild/openbsd-x64': 0.27.7
+      '@esbuild/openharmony-arm64': 0.27.7
+      '@esbuild/sunos-x64': 0.27.7
+      '@esbuild/win32-arm64': 0.27.7
+      '@esbuild/win32-ia32': 0.27.7
+      '@esbuild/win32-x64': 0.27.7
+
+  escalade@3.2.0: {}
+
+  escape-html@1.0.3: {}
+
+  esprima@4.0.1: {}
+
+  estree-walker@3.0.3:
+    dependencies:
+      '@types/estree': 1.0.8
+
+  etag@1.8.1: {}
+
+  eventemitter3@5.0.4: {}
+
+  eventsource-parser@3.0.6: {}
+
+  eventsource@3.0.7:
+    dependencies:
+      eventsource-parser: 3.0.6
+
+  expect-type@1.3.0: {}
+
+  express-rate-limit@8.3.2(express@5.2.1):
+    dependencies:
+      express: 5.2.1
+      ip-address: 10.1.0
+
+  express@5.2.1:
+    dependencies:
+      accepts: 2.0.0
+      body-parser: 2.2.2
+      content-disposition: 1.1.0
+      content-type: 1.0.5
+      cookie: 0.7.2
+      cookie-signature: 1.2.2
+      debug: 4.4.3
+      depd: 2.0.0
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      finalhandler: 2.1.1
+      fresh: 2.0.0
+      http-errors: 2.0.1
+      merge-descriptors: 2.0.0
+      mime-types: 3.0.2
+      on-finished: 2.4.1
+      once: 1.4.0
+      parseurl: 1.3.3
+      proxy-addr: 2.0.7
+      qs: 6.15.1
+      range-parser: 1.2.1
+      router: 2.2.0
+      send: 1.2.1
+      serve-static: 2.2.1
+      statuses: 2.0.2
+      type-is: 2.0.1
+      vary: 1.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  extend@3.0.2: {}
+
+  extendable-error@0.1.7: {}
+
+  fast-deep-equal@3.1.3: {}
+
+  fast-glob@3.3.3:
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      '@nodelib/fs.walk': 1.2.8
+      glob-parent: 5.1.2
+      merge2: 1.4.1
+      micromatch: 4.0.8
+
+  fast-sha256@1.3.0: {}
+
+  fast-uri@3.1.0: {}
+
+  fastq@1.20.1:
+    dependencies:
+      reusify: 1.1.0
+
+  fdir@6.5.0(picomatch@4.0.4):
+    optionalDependencies:
+      picomatch: 4.0.4
+
+  fetch-blob@3.2.0:
+    dependencies:
+      node-domexception: 1.0.0
+      web-streams-polyfill: 3.3.3
+
+  fflate@0.8.2: {}
+
+  fill-range@7.1.1:
+    dependencies:
+      to-regex-range: 5.0.1
+
+  finalhandler@2.1.1:
+    dependencies:
+      debug: 4.4.3
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      on-finished: 2.4.1
+      parseurl: 1.3.3
+      statuses: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
+  find-up@4.1.0:
+    dependencies:
+      locate-path: 5.0.0
+      path-exists: 4.0.0
+
+  for-each@0.3.5:
+    dependencies:
+      is-callable: 1.2.7
+
+  formdata-polyfill@4.0.10:
+    dependencies:
+      fetch-blob: 3.2.0
+
+  forwarded@0.2.0: {}
+
+  fresh@2.0.0: {}
+
+  fs-extra@11.3.5:
+    dependencies:
+      graceful-fs: 4.2.11
+      jsonfile: 6.2.1
+      universalify: 2.0.1
+
+  fs-extra@7.0.1:
+    dependencies:
+      graceful-fs: 4.2.11
+      jsonfile: 4.0.0
+      universalify: 0.1.2
+
+  fs-extra@8.1.0:
+    dependencies:
+      graceful-fs: 4.2.11
+      jsonfile: 4.0.0
+      universalify: 0.1.2
+
+  fsevents@2.3.3:
+    optional: true
+
+  function-bind@1.1.2: {}
+
+  function.prototype.name@1.1.8:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-properties: 1.2.1
+      functions-have-names: 1.2.3
+      hasown: 2.0.3
+      is-callable: 1.2.7
+
+  functions-have-names@1.2.3: {}
+
+  gaxios@7.1.4:
+    dependencies:
+      extend: 3.0.2
+      https-proxy-agent: 7.0.6
+      node-fetch: 3.3.2
+    transitivePeerDependencies:
+      - supports-color
+
+  gcp-metadata@8.1.2:
+    dependencies:
+      gaxios: 7.1.4
+      google-logging-utils: 1.1.3
+      json-bigint: 1.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  generator-function@2.0.1: {}
+
+  gensync@1.0.0-beta.2: {}
+
+  get-caller-file@2.0.5: {}
+
+  get-east-asian-width@1.5.0: {}
+
+  get-intrinsic@1.3.0:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-define-property: 1.0.1
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.1
+      function-bind: 1.1.2
+      get-proto: 1.0.1
+      gopd: 1.2.0
+      has-symbols: 1.1.0
+      hasown: 2.0.3
+      math-intrinsics: 1.1.0
+
+  get-proto@1.0.1:
+    dependencies:
+      dunder-proto: 1.0.1
+      es-object-atoms: 1.1.1
+
+  get-symbol-description@1.1.0:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+
+  get-tsconfig@4.13.7:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
+  get-tsconfig@5.0.0-beta.5:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
+  glob-parent@5.1.2:
+    dependencies:
+      is-glob: 4.0.3
+
+  globalthis@1.0.4:
+    dependencies:
+      define-properties: 1.2.1
+      gopd: 1.2.0
+
+  globby@11.1.0:
+    dependencies:
+      array-union: 2.1.0
+      dir-glob: 3.0.1
+      fast-glob: 3.3.3
+      ignore: 5.3.2
+      merge2: 1.4.1
+      slash: 3.0.0
+
+  google-auth-library@10.6.2:
+    dependencies:
+      base64-js: 1.5.1
+      ecdsa-sig-formatter: 1.0.11
+      gaxios: 7.1.4
+      gcp-metadata: 8.1.2
+      google-logging-utils: 1.1.3
+      jws: 4.0.1
+    transitivePeerDependencies:
+      - supports-color
+
+  google-logging-utils@1.1.3: {}
+
+  gopd@1.2.0: {}
+
+  graceful-fs@4.2.11: {}
+
+  has-bigints@1.1.0: {}
+
+  has-flag@4.0.0: {}
+
+  has-property-descriptors@1.0.2:
+    dependencies:
+      es-define-property: 1.0.1
+
+  has-proto@1.2.0:
+    dependencies:
+      dunder-proto: 1.0.1
+
+  has-symbols@1.1.0: {}
+
+  has-tostringtag@1.0.2:
+    dependencies:
+      has-symbols: 1.1.0
+
+  hasown@2.0.3:
+    dependencies:
+      function-bind: 1.1.2
+
+  highlight.js@10.7.3: {}
+
+  hono@4.12.14: {}
+
+  hookable@6.1.1: {}
+
+  html-escaper@2.0.2: {}
+
+  html-escaper@3.0.3: {}
+
+  htmlparser2@10.1.0:
+    dependencies:
+      domelementtype: 2.3.0
+      domhandler: 5.0.3
+      domutils: 3.2.2
+      entities: 7.0.1
+
+  http-errors@2.0.1:
+    dependencies:
+      depd: 2.0.0
+      inherits: 2.0.4
+      setprototypeof: 1.2.0
+      statuses: 2.0.2
+      toidentifier: 1.0.1
+
+  https-proxy-agent@7.0.6:
+    dependencies:
+      agent-base: 7.1.4
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  human-id@4.1.3: {}
+
+  iconv-lite@0.7.2:
+    dependencies:
+      safer-buffer: 2.1.2
+
+  ignore@5.3.2: {}
+
+  import-lazy@4.0.0: {}
+
+  import-without-cache@0.4.0: {}
+
+  inherits@2.0.4: {}
+
+  internal-slot@1.1.0:
+    dependencies:
+      es-errors: 1.3.0
+      hasown: 2.0.3
+      side-channel: 1.1.0
+
+  ip-address@10.1.0: {}
+
+  ipaddr.js@1.9.1: {}
+
+  is-array-buffer@3.0.5:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      get-intrinsic: 1.3.0
+
+  is-async-function@2.1.1:
+    dependencies:
+      async-function: 1.0.0
+      call-bound: 1.0.4
+      get-proto: 1.0.1
+      has-tostringtag: 1.0.2
+      safe-regex-test: 1.1.0
+
+  is-bigint@1.1.0:
+    dependencies:
+      has-bigints: 1.1.0
+
+  is-boolean-object@1.2.2:
+    dependencies:
+      call-bound: 1.0.4
+      has-tostringtag: 1.0.2
+
+  is-callable@1.2.7: {}
+
+  is-core-module@2.16.2:
+    dependencies:
+      hasown: 2.0.3
+
+  is-data-view@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      get-intrinsic: 1.3.0
+      is-typed-array: 1.1.15
+
+  is-date-object@1.1.0:
+    dependencies:
+      call-bound: 1.0.4
+      has-tostringtag: 1.0.2
+
+  is-docker@3.0.0: {}
+
+  is-extglob@2.1.1: {}
+
+  is-finalizationregistry@1.1.1:
+    dependencies:
+      call-bound: 1.0.4
+
+  is-fullwidth-code-point@3.0.0: {}
+
+  is-fullwidth-code-point@5.1.0:
+    dependencies:
+      get-east-asian-width: 1.5.0
+
+  is-generator-function@1.1.2:
+    dependencies:
+      call-bound: 1.0.4
+      generator-function: 2.0.1
+      get-proto: 1.0.1
+      has-tostringtag: 1.0.2
+      safe-regex-test: 1.1.0
+
+  is-glob@4.0.3:
+    dependencies:
+      is-extglob: 2.1.1
+
+  is-inside-container@1.0.0:
+    dependencies:
+      is-docker: 3.0.0
+
+  is-map@2.0.3: {}
+
+  is-negative-zero@2.0.3: {}
+
+  is-number-object@1.1.1:
+    dependencies:
+      call-bound: 1.0.4
+      has-tostringtag: 1.0.2
+
+  is-number@7.0.0: {}
+
+  is-promise@4.0.0: {}
+
+  is-regex@1.2.1:
+    dependencies:
+      call-bound: 1.0.4
+      gopd: 1.2.0
+      has-tostringtag: 1.0.2
+      hasown: 2.0.3
+
+  is-set@2.0.3: {}
+
+  is-shared-array-buffer@1.0.4:
+    dependencies:
+      call-bound: 1.0.4
+
+  is-string@1.1.1:
+    dependencies:
+      call-bound: 1.0.4
+      has-tostringtag: 1.0.2
+
+  is-subdir@1.2.0:
+    dependencies:
+      better-path-resolve: 1.0.0
+
+  is-symbol@1.1.1:
+    dependencies:
+      call-bound: 1.0.4
+      has-symbols: 1.1.0
+      safe-regex-test: 1.1.0
+
+  is-typed-array@1.1.15:
+    dependencies:
+      which-typed-array: 1.1.20
+
+  is-weakmap@2.0.2: {}
+
+  is-weakref@1.1.1:
+    dependencies:
+      call-bound: 1.0.4
+
+  is-weakset@2.0.4:
+    dependencies:
+      call-bound: 1.0.4
+      get-intrinsic: 1.3.0
+
+  is-windows@1.0.2: {}
+
+  is-wsl@3.1.1:
+    dependencies:
+      is-inside-container: 1.0.0
+
+  isarray@2.0.5: {}
+
+  isexe@2.0.0: {}
+
+  istanbul-lib-coverage@3.2.2: {}
+
+  istanbul-lib-report@3.0.1:
+    dependencies:
+      istanbul-lib-coverage: 3.2.2
+      make-dir: 4.0.0
+      supports-color: 7.2.0
+
+  istanbul-reports@3.2.0:
+    dependencies:
+      html-escaper: 2.0.2
+      istanbul-lib-report: 3.0.1
+
+  jiti@2.6.1: {}
+
+  jju@1.4.0: {}
+
+  jose@6.2.2: {}
+
+  js-tokens@10.0.0: {}
+
+  js-tokens@4.0.0: {}
+
+  js-yaml@3.14.2:
+    dependencies:
+      argparse: 1.0.10
+      esprima: 4.0.1
+
+  js-yaml@4.1.1:
+    dependencies:
+      argparse: 2.0.1
+
+  jsesc@3.1.0: {}
+
+  json-bigint@1.0.0:
+    dependencies:
+      bignumber.js: 9.3.1
+
+  json-schema-to-ts@3.1.1:
+    dependencies:
+      '@babel/runtime': 7.29.2
+      ts-algebra: 2.0.0
+
+  json-schema-traverse@1.0.0: {}
+
+  json-schema-typed@8.0.2: {}
+
+  json5@2.2.3: {}
+
+  jsonfile@4.0.0:
+    optionalDependencies:
+      graceful-fs: 4.2.11
+
+  jsonfile@6.2.1:
+    dependencies:
+      universalify: 2.0.1
+    optionalDependencies:
+      graceful-fs: 4.2.11
+
+  jwa@2.0.1:
+    dependencies:
+      buffer-equal-constant-time: 1.0.1
+      ecdsa-sig-formatter: 1.0.11
+      safe-buffer: 5.2.1
+
+  jws@4.0.1:
+    dependencies:
+      jwa: 2.0.1
+      safe-buffer: 5.2.1
+
+  koffi@2.16.0:
+    optional: true
+
+  lightningcss-android-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-x64@1.32.0:
+    optional: true
+
+  lightningcss-freebsd-x64@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-musl@1.32.0:
+    optional: true
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    optional: true
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    optional: true
+
+  lightningcss@1.32.0:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.32.0
+      lightningcss-darwin-arm64: 1.32.0
+      lightningcss-darwin-x64: 1.32.0
+      lightningcss-freebsd-x64: 1.32.0
+      lightningcss-linux-arm-gnueabihf: 1.32.0
+      lightningcss-linux-arm64-gnu: 1.32.0
+      lightningcss-linux-arm64-musl: 1.32.0
+      lightningcss-linux-x64-gnu: 1.32.0
+      lightningcss-linux-x64-musl: 1.32.0
+      lightningcss-win32-arm64-msvc: 1.32.0
+      lightningcss-win32-x64-msvc: 1.32.0
+
+  linkedom@0.18.12:
+    dependencies:
+      css-select: 5.2.2
+      cssom: 0.5.0
+      html-escaper: 3.0.3
+      htmlparser2: 10.1.0
+      uhyphen: 0.2.0
+
+  lint-staged@16.4.0:
+    dependencies:
+      commander: 14.0.3
+      listr2: 9.0.5
+      picomatch: 4.0.4
+      string-argv: 0.3.2
+      tinyexec: 1.1.1
+      yaml: 2.8.3
+
+  listr2@9.0.5:
+    dependencies:
+      cli-truncate: 5.2.0
+      colorette: 2.0.20
+      eventemitter3: 5.0.4
+      log-update: 6.1.0
+      rfdc: 1.4.1
+      wrap-ansi: 9.0.2
+
+  locate-path@5.0.0:
+    dependencies:
+      p-locate: 4.1.0
+
+  lodash.startcase@4.4.0: {}
+
+  log-update@6.1.0:
+    dependencies:
+      ansi-escapes: 7.3.0
+      cli-cursor: 5.0.0
+      slice-ansi: 7.1.2
+      strip-ansi: 7.2.0
+      wrap-ansi: 9.0.2
+
+  long@5.3.2: {}
+
+  lru-cache@11.3.3: {}
+
+  lru-cache@5.1.1:
+    dependencies:
+      yallist: 3.1.1
+
+  magic-string@0.30.21:
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  magicast@0.5.2:
+    dependencies:
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
+      source-map-js: 1.2.1
+
+  make-dir@4.0.0:
+    dependencies:
+      semver: 7.7.4
+
+  marked-terminal@7.3.0(marked@9.1.6):
+    dependencies:
+      ansi-escapes: 7.3.0
+      ansi-regex: 6.2.2
+      chalk: 5.6.2
+      cli-highlight: 2.1.11
+      cli-table3: 0.6.5
+      marked: 9.1.6
+      node-emoji: 2.2.0
+      supports-hyperlinks: 3.2.0
+
+  marked@15.0.12: {}
+
+  marked@9.1.6: {}
+
+  math-intrinsics@1.1.0: {}
+
+  media-typer@1.1.0: {}
+
+  merge-descriptors@2.0.0: {}
+
+  merge2@1.4.1: {}
+
+  micromatch@4.0.8:
+    dependencies:
+      braces: 3.0.3
+      picomatch: 2.3.2
+
+  mime-db@1.54.0: {}
+
+  mime-types@3.0.2:
+    dependencies:
+      mime-db: 1.54.0
+
+  mimic-function@5.0.1: {}
+
+  minimatch@10.2.3:
+    dependencies:
+      brace-expansion: 5.0.6
+
+  minipass@7.1.3: {}
+
+  minizlib@3.1.0:
+    dependencies:
+      minipass: 7.1.3
+
+  mri@1.2.0: {}
+
+  ms@2.1.3: {}
+
+  mz@2.7.0:
+    dependencies:
+      any-promise: 1.3.0
+      object-assign: 4.1.1
+      thenify-all: 1.6.0
+
+  nanoid@3.3.11: {}
+
+  negotiator@1.0.0: {}
+
+  node-domexception@1.0.0: {}
+
+  node-emoji@2.2.0:
+    dependencies:
+      '@sindresorhus/is': 4.6.0
+      char-regex: 1.0.2
+      emojilib: 2.4.0
+      skin-tone: 2.0.0
+
+  node-fetch@2.7.0:
+    dependencies:
+      whatwg-url: 5.0.0
+
+  node-fetch@3.3.2:
+    dependencies:
+      data-uri-to-buffer: 4.0.1
+      fetch-blob: 3.2.0
+      formdata-polyfill: 4.0.10
+
+  node-releases@2.0.37: {}
+
+  nth-check@2.1.1:
+    dependencies:
+      boolbase: 1.0.0
+
+  nunjucks@3.2.4:
+    dependencies:
+      a-sync-waterfall: 1.0.1
+      asap: 2.0.6
+      commander: 5.1.0
+
+  object-assign@4.1.1: {}
+
+  object-inspect@1.13.4: {}
+
+  object-keys@1.1.1: {}
+
+  object.assign@4.1.7:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-properties: 1.2.1
+      es-object-atoms: 1.1.1
+      has-symbols: 1.1.0
+      object-keys: 1.1.1
+
+  obug@2.1.1: {}
+
+  on-finished@2.4.1:
+    dependencies:
+      ee-first: 1.1.1
+
+  once@1.4.0:
+    dependencies:
+      wrappy: 1.0.2
+
+  onetime@7.0.0:
+    dependencies:
+      mimic-function: 5.0.1
+
+  open@10.2.0:
+    dependencies:
+      default-browser: 5.5.0
+      define-lazy-prop: 3.0.0
+      is-inside-container: 1.0.0
+      wsl-utils: 0.1.0
+
+  openai@6.34.0(ws@8.20.0)(zod@4.3.6):
+    optionalDependencies:
+      ws: 8.20.0
+      zod: 4.3.6
+
+  outdent@0.5.0: {}
+
+  own-keys@1.0.1:
+    dependencies:
+      get-intrinsic: 1.3.0
+      object-keys: 1.1.1
+      safe-push-apply: 1.0.0
+
+  oxlint-tsgolint@0.20.0:
+    optionalDependencies:
+      '@oxlint-tsgolint/darwin-arm64': 0.20.0
+      '@oxlint-tsgolint/darwin-x64': 0.20.0
+      '@oxlint-tsgolint/linux-arm64': 0.20.0
+      '@oxlint-tsgolint/linux-x64': 0.20.0
+      '@oxlint-tsgolint/win32-arm64': 0.20.0
+      '@oxlint-tsgolint/win32-x64': 0.20.0
+
+  oxlint@1.59.0(oxlint-tsgolint@0.20.0):
+    optionalDependencies:
+      '@oxlint/binding-android-arm-eabi': 1.59.0
+      '@oxlint/binding-android-arm64': 1.59.0
+      '@oxlint/binding-darwin-arm64': 1.59.0
+      '@oxlint/binding-darwin-x64': 1.59.0
+      '@oxlint/binding-freebsd-x64': 1.59.0
+      '@oxlint/binding-linux-arm-gnueabihf': 1.59.0
+      '@oxlint/binding-linux-arm-musleabihf': 1.59.0
+      '@oxlint/binding-linux-arm64-gnu': 1.59.0
+      '@oxlint/binding-linux-arm64-musl': 1.59.0
+      '@oxlint/binding-linux-ppc64-gnu': 1.59.0
+      '@oxlint/binding-linux-riscv64-gnu': 1.59.0
+      '@oxlint/binding-linux-riscv64-musl': 1.59.0
+      '@oxlint/binding-linux-s390x-gnu': 1.59.0
+      '@oxlint/binding-linux-x64-gnu': 1.59.0
+      '@oxlint/binding-linux-x64-musl': 1.59.0
+      '@oxlint/binding-openharmony-arm64': 1.59.0
+      '@oxlint/binding-win32-arm64-msvc': 1.59.0
+      '@oxlint/binding-win32-ia32-msvc': 1.59.0
+      '@oxlint/binding-win32-x64-msvc': 1.59.0
+      oxlint-tsgolint: 0.20.0
+
+  p-filter@2.1.0:
+    dependencies:
+      p-map: 2.1.0
+
+  p-limit@2.3.0:
+    dependencies:
+      p-try: 2.2.0
+
+  p-locate@4.1.0:
+    dependencies:
+      p-limit: 2.3.0
+
+  p-map@2.1.0: {}
+
+  p-retry@4.6.2:
+    dependencies:
+      '@types/retry': 0.12.0
+      retry: 0.13.1
+
+  p-try@2.2.0: {}
+
+  package-manager-detector@0.2.11:
+    dependencies:
+      quansync: 0.2.11
+
+  package-manager-detector@1.6.0: {}
+
+  parse5-htmlparser2-tree-adapter@6.0.1:
+    dependencies:
+      parse5: 6.0.1
+
+  parse5@5.1.1: {}
+
+  parse5@6.0.1: {}
+
+  parseurl@1.3.3: {}
+
+  path-exists@4.0.0: {}
+
+  path-key@3.1.1: {}
+
+  path-parse@1.0.7: {}
+
+  path-to-regexp@8.4.2: {}
+
+  path-type@4.0.0: {}
+
+  pathe@2.0.3: {}
+
+  pend@1.2.0: {}
+
+  picocolors@1.1.1: {}
+
+  picomatch@2.3.2: {}
+
+  picomatch@4.0.4: {}
+
+  pify@4.0.1: {}
+
+  pkce-challenge@5.0.1: {}
+
+  possible-typed-array-names@1.1.0: {}
+
+  postcss@8.5.9:
+    dependencies:
+      nanoid: 3.3.11
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
+  postject@1.0.0-alpha.6:
+    dependencies:
+      commander: 9.5.0
+
+  prettier@2.8.8: {}
+
+  proper-lockfile@4.1.2:
+    dependencies:
+      graceful-fs: 4.2.11
+      retry: 0.12.0
+      signal-exit: 3.0.7
+
+  protobufjs@7.5.4:
+    dependencies:
+      '@protobufjs/aspromise': 1.1.2
+      '@protobufjs/base64': 1.1.2
+      '@protobufjs/codegen': 2.0.4
+      '@protobufjs/eventemitter': 1.1.0
+      '@protobufjs/fetch': 1.1.0
+      '@protobufjs/float': 1.0.2
+      '@protobufjs/inquire': 1.1.0
+      '@protobufjs/path': 1.1.2
+      '@protobufjs/pool': 1.1.0
+      '@protobufjs/utf8': 1.1.0
+      '@types/node': 22.19.17
+      long: 5.3.2
+
+  proxy-addr@2.0.7:
+    dependencies:
+      forwarded: 0.2.0
+      ipaddr.js: 1.9.1
+
+  publint@0.3.18:
+    dependencies:
+      '@publint/pack': 0.1.4
+      package-manager-detector: 1.6.0
+      picocolors: 1.1.1
+      sade: 1.8.1
+
+  qs@6.15.1:
+    dependencies:
+      side-channel: 1.1.0
+
+  quansync@0.2.11: {}
+
+  quansync@1.0.0: {}
+
+  queue-microtask@1.2.3: {}
+
+  range-parser@1.2.1: {}
+
+  raw-body@3.0.2:
+    dependencies:
+      bytes: 3.1.2
+      http-errors: 2.0.1
+      iconv-lite: 0.7.2
+      unpipe: 1.0.0
+
+  react-dom@19.2.5(react@19.2.5):
+    dependencies:
+      react: 19.2.5
+      scheduler: 0.27.0
+
+  react-refresh@0.17.0: {}
+
+  react-router-dom@7.14.1(react-dom@19.2.5(react@19.2.5))(react@19.2.5):
+    dependencies:
+      react: 19.2.5
+      react-dom: 19.2.5(react@19.2.5)
+      react-router: 7.14.1(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
+
+  react-router@7.14.1(react-dom@19.2.5(react@19.2.5))(react@19.2.5):
+    dependencies:
+      cookie: 1.1.1
+      react: 19.2.5
+      set-cookie-parser: 2.7.2
+    optionalDependencies:
+      react-dom: 19.2.5(react@19.2.5)
+
+  react@19.2.5: {}
+
+  read-yaml-file@1.1.0:
+    dependencies:
+      graceful-fs: 4.2.11
+      js-yaml: 3.14.2
+      pify: 4.0.1
+      strip-bom: 3.0.0
+
+  reflect.getprototypeof@1.0.10:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.1
+      get-intrinsic: 1.3.0
+      get-proto: 1.0.1
+      which-builtin-type: 1.2.1
+
+  regexp.escape@2.0.1:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-errors: 1.3.0
+      for-each: 0.3.5
+      safe-regex-test: 1.1.0
+
+  regexp.prototype.flags@1.5.4:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-errors: 1.3.0
+      get-proto: 1.0.1
+      gopd: 1.2.0
+      set-function-name: 2.0.2
+
+  require-directory@2.1.1: {}
+
+  require-from-string@2.0.2: {}
+
+  resolve-from@5.0.0: {}
+
+  resolve-pkg-maps@1.0.0: {}
+
+  resolve@1.22.12:
+    dependencies:
+      es-errors: 1.3.0
+      is-core-module: 2.16.2
+      path-parse: 1.0.7
+      supports-preserve-symlinks-flag: 1.0.0
+
+  restore-cursor@5.1.0:
+    dependencies:
+      onetime: 7.0.0
+      signal-exit: 4.1.0
+
+  retry@0.12.0: {}
+
+  retry@0.13.1: {}
+
+  reusify@1.1.0: {}
+
+  rfdc@1.4.1: {}
+
+  rolldown-plugin-dts@0.25.1(rolldown@1.0.1)(typescript@6.0.2):
+    dependencies:
+      '@babel/generator': 8.0.0-rc.5
+      '@babel/helper-validator-identifier': 8.0.0-rc.5
+      '@babel/parser': 8.0.0-rc.4
+      ast-kit: 3.0.0-beta.1
+      birpc: 4.0.0
+      dts-resolver: 3.0.0
+      get-tsconfig: 5.0.0-beta.5
+      obug: 2.1.1
+      rolldown: 1.0.1
+    optionalDependencies:
+      typescript: 6.0.2
+    transitivePeerDependencies:
+      - oxc-resolver
+
+  rolldown@1.0.0-rc.12(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0):
+    dependencies:
+      '@oxc-project/types': 0.122.0
+      '@rolldown/pluginutils': 1.0.0-rc.12
+    optionalDependencies:
+      '@rolldown/binding-android-arm64': 1.0.0-rc.12
+      '@rolldown/binding-darwin-arm64': 1.0.0-rc.12
+      '@rolldown/binding-darwin-x64': 1.0.0-rc.12
+      '@rolldown/binding-freebsd-x64': 1.0.0-rc.12
+      '@rolldown/binding-linux-arm-gnueabihf': 1.0.0-rc.12
+      '@rolldown/binding-linux-arm64-gnu': 1.0.0-rc.12
+      '@rolldown/binding-linux-arm64-musl': 1.0.0-rc.12
+      '@rolldown/binding-linux-ppc64-gnu': 1.0.0-rc.12
+      '@rolldown/binding-linux-s390x-gnu': 1.0.0-rc.12
+      '@rolldown/binding-linux-x64-gnu': 1.0.0-rc.12
+      '@rolldown/binding-linux-x64-musl': 1.0.0-rc.12
+      '@rolldown/binding-openharmony-arm64': 1.0.0-rc.12
+      '@rolldown/binding-wasm32-wasi': 1.0.0-rc.12(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)
+      '@rolldown/binding-win32-arm64-msvc': 1.0.0-rc.12
+      '@rolldown/binding-win32-x64-msvc': 1.0.0-rc.12
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+    optional: true
+
+  rolldown@1.0.0-rc.15:
+    dependencies:
+      '@oxc-project/types': 0.124.0
+      '@rolldown/pluginutils': 1.0.0-rc.15
+    optionalDependencies:
+      '@rolldown/binding-android-arm64': 1.0.0-rc.15
+      '@rolldown/binding-darwin-arm64': 1.0.0-rc.15
+      '@rolldown/binding-darwin-x64': 1.0.0-rc.15
+      '@rolldown/binding-freebsd-x64': 1.0.0-rc.15
+      '@rolldown/binding-linux-arm-gnueabihf': 1.0.0-rc.15
+      '@rolldown/binding-linux-arm64-gnu': 1.0.0-rc.15
+      '@rolldown/binding-linux-arm64-musl': 1.0.0-rc.15
+      '@rolldown/binding-linux-ppc64-gnu': 1.0.0-rc.15
+      '@rolldown/binding-linux-s390x-gnu': 1.0.0-rc.15
+      '@rolldown/binding-linux-x64-gnu': 1.0.0-rc.15
+      '@rolldown/binding-linux-x64-musl': 1.0.0-rc.15
+      '@rolldown/binding-openharmony-arm64': 1.0.0-rc.15
+      '@rolldown/binding-wasm32-wasi': 1.0.0-rc.15
+      '@rolldown/binding-win32-arm64-msvc': 1.0.0-rc.15
+      '@rolldown/binding-win32-x64-msvc': 1.0.0-rc.15
+
+  rolldown@1.0.1:
+    dependencies:
+      '@oxc-project/types': 0.130.0
+      '@rolldown/pluginutils': 1.0.1
+    optionalDependencies:
+      '@rolldown/binding-android-arm64': 1.0.1
+      '@rolldown/binding-darwin-arm64': 1.0.1
+      '@rolldown/binding-darwin-x64': 1.0.1
+      '@rolldown/binding-freebsd-x64': 1.0.1
+      '@rolldown/binding-linux-arm-gnueabihf': 1.0.1
+      '@rolldown/binding-linux-arm64-gnu': 1.0.1
+      '@rolldown/binding-linux-arm64-musl': 1.0.1
+      '@rolldown/binding-linux-ppc64-gnu': 1.0.1
+      '@rolldown/binding-linux-s390x-gnu': 1.0.1
+      '@rolldown/binding-linux-x64-gnu': 1.0.1
+      '@rolldown/binding-linux-x64-musl': 1.0.1
+      '@rolldown/binding-openharmony-arm64': 1.0.1
+      '@rolldown/binding-wasm32-wasi': 1.0.1
+      '@rolldown/binding-win32-arm64-msvc': 1.0.1
+      '@rolldown/binding-win32-x64-msvc': 1.0.1
+
+  rollup@4.60.2:
+    dependencies:
+      '@types/estree': 1.0.8
+    optionalDependencies:
+      '@rollup/rollup-android-arm-eabi': 4.60.2
+      '@rollup/rollup-android-arm64': 4.60.2
+      '@rollup/rollup-darwin-arm64': 4.60.2
+      '@rollup/rollup-darwin-x64': 4.60.2
+      '@rollup/rollup-freebsd-arm64': 4.60.2
+      '@rollup/rollup-freebsd-x64': 4.60.2
+      '@rollup/rollup-linux-arm-gnueabihf': 4.60.2
+      '@rollup/rollup-linux-arm-musleabihf': 4.60.2
+      '@rollup/rollup-linux-arm64-gnu': 4.60.2
+      '@rollup/rollup-linux-arm64-musl': 4.60.2
+      '@rollup/rollup-linux-loong64-gnu': 4.60.2
+      '@rollup/rollup-linux-loong64-musl': 4.60.2
+      '@rollup/rollup-linux-ppc64-gnu': 4.60.2
+      '@rollup/rollup-linux-ppc64-musl': 4.60.2
+      '@rollup/rollup-linux-riscv64-gnu': 4.60.2
+      '@rollup/rollup-linux-riscv64-musl': 4.60.2
+      '@rollup/rollup-linux-s390x-gnu': 4.60.2
+      '@rollup/rollup-linux-x64-gnu': 4.60.2
+      '@rollup/rollup-linux-x64-musl': 4.60.2
+      '@rollup/rollup-openbsd-x64': 4.60.2
+      '@rollup/rollup-openharmony-arm64': 4.60.2
+      '@rollup/rollup-win32-arm64-msvc': 4.60.2
+      '@rollup/rollup-win32-ia32-msvc': 4.60.2
+      '@rollup/rollup-win32-x64-gnu': 4.60.2
+      '@rollup/rollup-win32-x64-msvc': 4.60.2
+      fsevents: 2.3.3
+
+  router@2.2.0:
+    dependencies:
+      debug: 4.4.3
+      depd: 2.0.0
+      is-promise: 4.0.0
+      parseurl: 1.3.3
+      path-to-regexp: 8.4.2
+    transitivePeerDependencies:
+      - supports-color
+
+  run-applescript@7.1.0: {}
+
+  run-parallel@1.2.0:
+    dependencies:
+      queue-microtask: 1.2.3
+
+  rxjs@7.8.2:
+    dependencies:
+      tslib: 2.8.1
+
+  sade@1.8.1:
+    dependencies:
+      mri: 1.2.0
+
+  safe-array-concat@1.1.4:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      get-intrinsic: 1.3.0
+      has-symbols: 1.1.0
+      isarray: 2.0.5
+
+  safe-buffer@5.2.1: {}
+
+  safe-push-apply@1.0.0:
+    dependencies:
+      es-errors: 1.3.0
+      isarray: 2.0.5
+
+  safe-regex-test@1.1.0:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      is-regex: 1.2.1
+
+  safer-buffer@2.1.2: {}
+
+  scheduler@0.27.0: {}
+
+  semver@6.3.1: {}
+
+  semver@7.7.4: {}
+
+  send@1.2.1:
+    dependencies:
+      debug: 4.4.3
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      fresh: 2.0.0
+      http-errors: 2.0.1
+      mime-types: 3.0.2
+      ms: 2.1.3
+      on-finished: 2.4.1
+      range-parser: 1.2.1
+      statuses: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
+  serve-static@2.2.1:
+    dependencies:
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      parseurl: 1.3.3
+      send: 1.2.1
+    transitivePeerDependencies:
+      - supports-color
+
+  set-cookie-parser@2.7.2: {}
+
+  set-function-length@1.2.2:
+    dependencies:
+      define-data-property: 1.1.4
+      es-errors: 1.3.0
+      function-bind: 1.1.2
+      get-intrinsic: 1.3.0
+      gopd: 1.2.0
+      has-property-descriptors: 1.0.2
+
+  set-function-name@2.0.2:
+    dependencies:
+      define-data-property: 1.1.4
+      es-errors: 1.3.0
+      functions-have-names: 1.2.3
+      has-property-descriptors: 1.0.2
+
+  set-proto@1.0.0:
+    dependencies:
+      dunder-proto: 1.0.1
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.1
+
+  setprototypeof@1.2.0: {}
+
+  shebang-command@2.0.0:
+    dependencies:
+      shebang-regex: 3.0.0
+
+  shebang-regex@3.0.0: {}
+
+  shell-quote@1.8.3: {}
+
+  sherif-darwin-arm64@1.11.1:
+    optional: true
+
+  sherif-darwin-x64@1.11.1:
+    optional: true
+
+  sherif-linux-arm64-musl@1.11.1:
+    optional: true
+
+  sherif-linux-arm64@1.11.1:
+    optional: true
+
+  sherif-linux-x64-musl@1.11.1:
+    optional: true
+
+  sherif-linux-x64@1.11.1:
+    optional: true
+
+  sherif-windows-arm64@1.11.1:
+    optional: true
+
+  sherif-windows-x64@1.11.1:
+    optional: true
+
+  sherif@1.11.1:
+    optionalDependencies:
+      sherif-darwin-arm64: 1.11.1
+      sherif-darwin-x64: 1.11.1
+      sherif-linux-arm64: 1.11.1
+      sherif-linux-arm64-musl: 1.11.1
+      sherif-linux-x64: 1.11.1
+      sherif-linux-x64-musl: 1.11.1
+      sherif-windows-arm64: 1.11.1
+      sherif-windows-x64: 1.11.1
+
+  side-channel-list@1.0.1:
+    dependencies:
+      es-errors: 1.3.0
+      object-inspect: 1.13.4
+
+  side-channel-map@1.0.1:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      object-inspect: 1.13.4
+
+  side-channel-weakmap@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      object-inspect: 1.13.4
+      side-channel-map: 1.0.1
+
+  side-channel@1.1.0:
+    dependencies:
+      es-errors: 1.3.0
+      object-inspect: 1.13.4
+      side-channel-list: 1.0.1
+      side-channel-map: 1.0.1
+      side-channel-weakmap: 1.0.2
+
+  siginfo@2.0.0: {}
+
+  signal-exit@3.0.7: {}
+
+  signal-exit@4.1.0: {}
+
+  simple-git-hooks@2.13.1: {}
+
+  skin-tone@2.0.0:
+    dependencies:
+      unicode-emoji-modifier-base: 1.0.0
+
+  slash@3.0.0: {}
+
+  slice-ansi@7.1.2:
+    dependencies:
+      ansi-styles: 6.2.3
+      is-fullwidth-code-point: 5.1.0
+
+  slice-ansi@8.0.0:
+    dependencies:
+      ansi-styles: 6.2.3
+      is-fullwidth-code-point: 5.1.0
+
+  smol-toml@1.6.1: {}
+
+  source-map-js@1.2.1: {}
+
+  source-map@0.6.1: {}
+
+  spawndamnit@3.0.1:
+    dependencies:
+      cross-spawn: 7.0.6
+      signal-exit: 4.1.0
+
+  sprintf-js@1.0.3: {}
+
+  ssh2@1.17.0:
+    dependencies:
+      asn1: 0.2.6
+      bcrypt-pbkdf: 1.0.2
+
+  stackback@0.0.2: {}
+
+  standardwebhooks@1.0.0:
+    dependencies:
+      '@stablelib/base64': 1.0.1
+      fast-sha256: 1.3.0
+
+  statuses@2.0.2: {}
+
+  std-env@4.0.0: {}
+
+  stop-iteration-iterator@1.1.0:
+    dependencies:
+      es-errors: 1.3.0
+      internal-slot: 1.1.0
+
+  string-argv@0.3.2: {}
+
+  string-width@4.2.3:
+    dependencies:
+      emoji-regex: 8.0.0
+      is-fullwidth-code-point: 3.0.0
+      strip-ansi: 6.0.1
+
+  string-width@7.2.0:
+    dependencies:
+      emoji-regex: 10.6.0
+      get-east-asian-width: 1.5.0
+      strip-ansi: 7.2.0
+
+  string-width@8.2.0:
+    dependencies:
+      get-east-asian-width: 1.5.0
+      strip-ansi: 7.2.0
+
+  string.prototype.trim@1.2.10:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-data-property: 1.1.4
+      define-properties: 1.2.1
+      es-abstract: 1.24.2
+      es-object-atoms: 1.1.1
+      has-property-descriptors: 1.0.2
+
+  string.prototype.trimend@1.0.9:
+    dependencies:
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      define-properties: 1.2.1
+      es-object-atoms: 1.1.1
+
+  string.prototype.trimstart@1.0.8:
+    dependencies:
+      call-bind: 1.0.9
+      define-properties: 1.2.1
+      es-object-atoms: 1.1.1
+
+  strip-ansi@6.0.1:
+    dependencies:
+      ansi-regex: 5.0.1
+
+  strip-ansi@7.2.0:
+    dependencies:
+      ansi-regex: 6.2.2
+
+  strip-bom@3.0.0: {}
+
+  supports-color@7.2.0:
+    dependencies:
+      has-flag: 4.0.0
+
+  supports-color@8.1.1:
+    dependencies:
+      has-flag: 4.0.0
+
+  supports-hyperlinks@3.2.0:
+    dependencies:
+      has-flag: 4.0.0
+      supports-color: 7.2.0
+
+  supports-preserve-symlinks-flag@1.0.0: {}
+
+  tailwindcss@4.2.2: {}
+
+  tapable@2.3.2: {}
+
+  tar@7.5.13:
+    dependencies:
+      '@isaacs/fs-minipass': 4.0.1
+      chownr: 3.0.0
+      minipass: 7.1.3
+      minizlib: 3.1.0
+      yallist: 5.0.0
+
+  term-size@2.2.1: {}
+
+  thenify-all@1.6.0:
+    dependencies:
+      thenify: 3.3.1
+
+  thenify@3.3.1:
+    dependencies:
+      any-promise: 1.3.0
+
+  tinybench@2.9.0: {}
+
+  tinyexec@1.1.1: {}
+
+  tinyexec@1.1.2: {}
+
+  tinyglobby@0.2.16:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+
+  tinyrainbow@3.1.0: {}
+
+  to-regex-range@5.0.1:
+    dependencies:
+      is-number: 7.0.0
+
+  toidentifier@1.0.1: {}
+
+  tr46@0.0.3: {}
+
+  tree-kill@1.2.2: {}
+
+  ts-algebra@2.0.0: {}
+
+  tsdown@0.22.0(@arethetypeswrong/core@0.18.2)(publint@0.3.18)(tsx@4.21.0)(typescript@6.0.2)(unrun@0.2.34(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)):
+    dependencies:
+      ansis: 4.2.0
+      cac: 7.0.0
+      defu: 6.1.7
+      empathic: 2.0.0
+      hookable: 6.1.1
+      import-without-cache: 0.4.0
+      obug: 2.1.1
+      picomatch: 4.0.4
+      rolldown: 1.0.1
+      rolldown-plugin-dts: 0.25.1(rolldown@1.0.1)(typescript@6.0.2)
+      semver: 7.7.4
+      tinyexec: 1.1.2
+      tinyglobby: 0.2.16
+      tree-kill: 1.2.2
+      unconfig-core: 7.5.0
+    optionalDependencies:
+      '@arethetypeswrong/core': 0.18.2
+      publint: 0.3.18
+      tsx: 4.21.0
+      typescript: 6.0.2
+      unrun: 0.2.34(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)
+    transitivePeerDependencies:
+      - '@ts-macro/tsc'
+      - '@typescript/native-preview'
+      - oxc-resolver
+      - vue-tsc
+
+  tslib@2.8.1: {}
+
+  tsx@4.21.0:
+    dependencies:
+      esbuild: 0.27.7
+      get-tsconfig: 4.13.7
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  tweetnacl@0.14.5: {}
+
+  type-is@2.0.1:
+    dependencies:
+      content-type: 1.0.5
+      media-typer: 1.1.0
+      mime-types: 3.0.2
+
+  typed-array-buffer@1.0.3:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      is-typed-array: 1.1.15
+
+  typed-array-byte-length@1.0.3:
+    dependencies:
+      call-bind: 1.0.9
+      for-each: 0.3.5
+      gopd: 1.2.0
+      has-proto: 1.2.0
+      is-typed-array: 1.1.15
+
+  typed-array-byte-offset@1.0.4:
+    dependencies:
+      available-typed-arrays: 1.0.7
+      call-bind: 1.0.9
+      for-each: 0.3.5
+      gopd: 1.2.0
+      has-proto: 1.2.0
+      is-typed-array: 1.1.15
+      reflect.getprototypeof: 1.0.10
+
+  typed-array-length@1.0.7:
+    dependencies:
+      call-bind: 1.0.9
+      for-each: 0.3.5
+      gopd: 1.2.0
+      is-typed-array: 1.1.15
+      possible-typed-array-names: 1.1.0
+      reflect.getprototypeof: 1.0.10
+
+  typescript@5.6.1-rc: {}
+
+  typescript@5.9.3: {}
+
+  typescript@6.0.2: {}
+
+  uhyphen@0.2.0: {}
+
+  unbox-primitive@1.1.0:
+    dependencies:
+      call-bound: 1.0.4
+      has-bigints: 1.1.0
+      has-symbols: 1.1.0
+      which-boxed-primitive: 1.1.1
+
+  unconfig-core@7.5.0:
+    dependencies:
+      '@quansync/fs': 1.0.0
+      quansync: 1.0.0
+
+  undici-types@5.26.5: {}
+
+  undici-types@6.21.0: {}
+
+  unicode-emoji-modifier-base@1.0.0: {}
+
+  universalify@0.1.2: {}
+
+  universalify@2.0.1: {}
+
+  unpipe@1.0.0: {}
+
+  unrun@0.2.34(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0):
+    dependencies:
+      rolldown: 1.0.0-rc.12(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+    optional: true
+
+  update-browserslist-db@1.2.3(browserslist@4.28.2):
+    dependencies:
+      browserslist: 4.28.2
+      escalade: 3.2.0
+      picocolors: 1.1.1
+
+  validate-npm-package-name@5.0.1: {}
+
+  vary@1.1.2: {}
+
+  vite@6.4.2(@types/node@22.19.17)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)(yaml@2.8.3):
+    dependencies:
+      esbuild: 0.25.12
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+      postcss: 8.5.9
+      rollup: 4.60.2
+      tinyglobby: 0.2.16
+    optionalDependencies:
+      '@types/node': 22.19.17
+      fsevents: 2.3.3
+      jiti: 2.6.1
+      lightningcss: 1.32.0
+      tsx: 4.21.0
+      yaml: 2.8.3
+
+  vite@8.0.8(@types/node@22.19.17)(esbuild@0.27.7)(jiti@2.6.1)(tsx@4.21.0)(yaml@2.8.3):
+    dependencies:
+      lightningcss: 1.32.0
+      picomatch: 4.0.4
+      postcss: 8.5.9
+      rolldown: 1.0.0-rc.15
+      tinyglobby: 0.2.16
+    optionalDependencies:
+      '@types/node': 22.19.17
+      esbuild: 0.27.7
+      fsevents: 2.3.3
+      jiti: 2.6.1
+      tsx: 4.21.0
+      yaml: 2.8.3
+
+  vitest@4.1.4(@types/node@22.19.17)(@vitest/coverage-v8@4.1.4)(vite@8.0.8(@types/node@22.19.17)(esbuild@0.27.7)(jiti@2.6.1)(tsx@4.21.0)(yaml@2.8.3)):
+    dependencies:
+      '@vitest/expect': 4.1.4
+      '@vitest/mocker': 4.1.4(vite@8.0.8(@types/node@22.19.17)(esbuild@0.27.7)(jiti@2.6.1)(tsx@4.21.0)(yaml@2.8.3))
+      '@vitest/pretty-format': 4.1.4
+      '@vitest/runner': 4.1.4
+      '@vitest/snapshot': 4.1.4
+      '@vitest/spy': 4.1.4
+      '@vitest/utils': 4.1.4
+      es-module-lexer: 2.0.0
+      expect-type: 1.3.0
+      magic-string: 0.30.21
+      obug: 2.1.1
+      pathe: 2.0.3
+      picomatch: 4.0.4
+      std-env: 4.0.0
+      tinybench: 2.9.0
+      tinyexec: 1.1.1
+      tinyglobby: 0.2.16
+      tinyrainbow: 3.1.0
+      vite: 8.0.8(@types/node@22.19.17)(esbuild@0.27.7)(jiti@2.6.1)(tsx@4.21.0)(yaml@2.8.3)
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@types/node': 22.19.17
+      '@vitest/coverage-v8': 4.1.4(vitest@4.1.4)
+    transitivePeerDependencies:
+      - msw
+
+  web-streams-polyfill@3.3.3: {}
+
+  webidl-conversions@3.0.1: {}
+
+  whatwg-url@5.0.0:
+    dependencies:
+      tr46: 0.0.3
+      webidl-conversions: 3.0.1
+
+  which-boxed-primitive@1.1.1:
+    dependencies:
+      is-bigint: 1.1.0
+      is-boolean-object: 1.2.2
+      is-number-object: 1.1.1
+      is-string: 1.1.1
+      is-symbol: 1.1.1
+
+  which-builtin-type@1.2.1:
+    dependencies:
+      call-bound: 1.0.4
+      function.prototype.name: 1.1.8
+      has-tostringtag: 1.0.2
+      is-async-function: 2.1.1
+      is-date-object: 1.1.0
+      is-finalizationregistry: 1.1.1
+      is-generator-function: 1.1.2
+      is-regex: 1.2.1
+      is-weakref: 1.1.1
+      isarray: 2.0.5
+      which-boxed-primitive: 1.1.1
+      which-collection: 1.0.2
+      which-typed-array: 1.1.20
+
+  which-collection@1.0.2:
+    dependencies:
+      is-map: 2.0.3
+      is-set: 2.0.3
+      is-weakmap: 2.0.2
+      is-weakset: 2.0.4
+
+  which-typed-array@1.1.20:
+    dependencies:
+      available-typed-arrays: 1.0.7
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      for-each: 0.3.5
+      get-proto: 1.0.1
+      gopd: 1.2.0
+      has-tostringtag: 1.0.2
+
+  which@2.0.2:
+    dependencies:
+      isexe: 2.0.0
+
+  why-is-node-running@2.3.0:
+    dependencies:
+      siginfo: 2.0.0
+      stackback: 0.0.2
+
+  wrap-ansi@7.0.0:
+    dependencies:
+      ansi-styles: 4.3.0
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+
+  wrap-ansi@9.0.2:
+    dependencies:
+      ansi-styles: 6.2.3
+      string-width: 7.2.0
+      strip-ansi: 7.2.0
+
+  wrappy@1.0.2: {}
+
+  ws@8.20.0: {}
+
+  wsl-utils@0.1.0:
+    dependencies:
+      is-wsl: 3.1.1
+
+  y18n@5.0.8: {}
+
+  yallist@3.1.1: {}
+
+  yallist@5.0.0: {}
+
+  yaml@2.8.3: {}
+
+  yargs-parser@20.2.9: {}
+
+  yargs-parser@21.1.1: {}
+
+  yargs@16.2.0:
+    dependencies:
+      cliui: 7.0.4
+      escalade: 3.2.0
+      get-caller-file: 2.0.5
+      require-directory: 2.1.1
+      string-width: 4.2.3
+      y18n: 5.0.8
+      yargs-parser: 20.2.9
+
+  yargs@17.7.2:
+    dependencies:
+      cliui: 8.0.1
+      escalade: 3.2.0
+      get-caller-file: 2.0.5
+      require-directory: 2.1.1
+      string-width: 4.2.3
+      y18n: 5.0.8
+      yargs-parser: 21.1.1
+
+  yauzl@3.3.0:
+    dependencies:
+      buffer-crc32: 0.2.13
+      pend: 1.2.0
+
+  yazl@3.3.1:
+    dependencies:
+      buffer-crc32: 1.0.0
+
+  zod-to-json-schema@3.25.2(zod@4.3.6):
+    dependencies:
+      zod: 4.3.6
+
+  zod@4.3.6: {}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
new file mode 100644
index 000000000..3e1c67ae0
--- /dev/null
+++ b/pnpm-workspace.yaml
@@ -0,0 +1,12 @@
+packages:
+  - packages/*
+  - apps/*
+  - apps/vis/server
+  - apps/vis/web
+
+catalog:
+  zod: ^4.3.6
+
+overrides:
+  "ssh2@1.17.0>cpu-features": "-"
+  "ssh2@1.17.0>nan": "-"
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 000000000..71b93da26
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,44 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "preserve",
+    "moduleResolution": "bundler",
+    "lib": ["ES2023"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "react",
+
+    "strict": true,
+    "isolatedModules": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true,
+
+    "declaration": true,
+    "sourceMap": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+
+    "types": ["node"]
+  },
+  "include": [
+    "packages/*/src/**/*.ts",
+    "packages/*/src/**/*.tsx",
+    "packages/*/test/**/*.ts",
+    "packages/*/test/**/*.tsx",
+    "apps/*/src/**/*.ts",
+    "apps/*/src/**/*.tsx",
+    "apps/*/test/**/*.ts",
+    "apps/*/test/**/*.tsx"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "coverage",
+    "packages/kosong/test/type-safety-negative.ts",
+    "**/*.disabled/**",
+    "**/*.disabled"
+  ]
+}
diff --git a/vitest.config.ts b/vitest.config.ts
new file mode 100644
index 000000000..08f1e765f
--- /dev/null
+++ b/vitest.config.ts
@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    projects: ['packages/*', 'apps/kimi-code'],
+    coverage: {
+      provider: 'v8',
+      include: ['packages/*/src/**/*.ts', 'apps/*/src/**/*.ts'],
+      exclude: ['**/*.test.ts', '**/*.spec.ts', '**/dist/**'],
+      reporter: ['text', 'html'],
+    },
+  },
+});